Skip to content

Commit

Permalink
Split REST functionality into a tree-shakable module
Browse files Browse the repository at this point in the history 
This moves the following functionality from BaseClient into a new module
named Rest:

- methods that wrap REST endpoints (e.g. `stats`)
- the `request` method
- all functionality accessed via `BaseRest.channels` and `BaseRest.push`

This allows us to now construct a BaseRealtime instance that doesn’t
have REST functionality.

Note that the BaseRest class always includes the Rest module. This comes
after discussions in which we decided that it would be quite useless
without it.

Resolves #1374.

Co-authored-by: Owen Pearson <owen.pearson@ably.com>
  • Loading branch information
@lawrence-forooghian @owenpearson
lawrence-forooghian and owenpearson committed Nov 1, 2023
1 parent cebf17b commit 32e3f8f
Show file tree
Hide file tree
Showing 9 changed files with 381 additions and 258 deletions.
4 changes: 2 additions & 2 deletions scripts/moduleReport.js
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
const esbuild = require('esbuild');

// List of all modules accepted in ModulesMap
const moduleNames = [];
const moduleNames = ['Rest'];

function formatBytes(bytes) {
const kibibytes = bytes / 1024;
Expand Down Expand Up @@ -40,7 +40,7 @@ const errors = [];
const size = getImportSize([baseClient, moduleName]);
console.log(`${baseClient} + ${moduleName}: ${formatBytes(size)}`);

if (!(baseClientSize < size)) {
if (!(baseClientSize < size) && !(baseClient === 'BaseRest' && moduleName === 'Rest')) {
// Emit an error if adding the module does not increase the bundle size
// (this means that the module is not being tree-shaken correctly).
errors.push(new Error(`Adding ${moduleName} to ${baseClient} does not increase the bundle size.`));
Expand Down
277 changes: 31 additions & 246 deletions src/common/lib/client/baseclient.ts
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,19 @@
import * as Utils from '../util/utils';
import Logger, { LoggerOptions } from '../util/logger';
import Defaults from '../util/defaults';
import Auth from './auth';
import Push from './push';
import PaginatedResource, { HttpPaginatedResponse, PaginatedResult } from './paginatedresource';
import Channel from './channel';
import { HttpPaginatedResponse, PaginatedResult } from './paginatedresource';
import ErrorInfo from '../types/errorinfo';
import Stats from '../types/stats';
import HttpMethods from '../../constants/HttpMethods';
import { ChannelOptions } from '../../types/channel';
import { PaginatedResultCallback, StandardCallback } from '../../types/utils';
import { ErrnoException, IHttp, RequestParams } from '../../types/http';
import { StandardCallback } from '../../types/utils';
import { IHttp, RequestParams } from '../../types/http';
import ClientOptions, { NormalisedClientOptions } from '../../types/ClientOptions';
import * as API from '../../../../ably';

import Platform from '../../platform';
import Message from '../types/message';
import PresenceMessage from '../types/presencemessage';
import Resource from './resource';
import { ModulesMap } from './modulesmap';
import { Rest } from './rest';

type BatchResult<T> = API.Types.BatchResult<T>;
type BatchPublishSpec = API.Types.BatchPublishSpec;
Expand All @@ -29,8 +24,6 @@ type BatchPresenceSuccessResult = API.Types.BatchPresenceSuccessResult;
type BatchPresenceFailureResult = API.Types.BatchPresenceFailureResult;
type BatchPresenceResult = BatchResult<BatchPresenceSuccessResult | BatchPresenceFailureResult>;

const noop = function () {};

/**
`BaseClient` acts as the base class for all of the client classes exported by the SDK. It is an implementation detail and this class is not advertised publicly.
*/
Expand All @@ -43,14 +36,10 @@ class BaseClient {
serverTimeOffset: number | null;
http: IHttp;
auth: Auth;
channels: Channels;
push: Push;

constructor(
options: ClientOptions | string,
// eslint-disable-next-line no-unused-vars, @typescript-eslint/no-unused-vars
modules: ModulesMap
) {
private readonly _rest: Rest | null;

constructor(options: ClientOptions | string, modules: ModulesMap) {
if (!options) {
const msg = 'no options provided';
Logger.logAction(Logger.LOG_ERROR, 'BaseClient()', msg);
Expand Down Expand Up @@ -97,8 +86,23 @@ class BaseClient {
this.serverTimeOffset = null;
this.http = new Platform.Http(normalOptions);
this.auth = new Auth(this, normalOptions);
this.channels = new Channels(this);
this.push = new Push(this);

this._rest = modules.Rest ? new modules.Rest(this) : null;
}

private get rest(): Rest {
if (!this._rest) {
throw new ErrorInfo('Rest module not provided', 400, 40000);
}
return this._rest;
}

get channels() {
return this.rest.channels;
}

get push() {
return this.rest.push;
}

baseUri(host: string) {
Expand All @@ -109,78 +113,11 @@ class BaseClient {
params: RequestParams,
callback: StandardCallback<PaginatedResult<Stats>>
): Promise<PaginatedResult<Stats>> | void {
/* params and callback are optional; see if params contains the callback */
if (callback === undefined) {
if (typeof params == 'function') {
callback = params;
params = null;
} else {
return Utils.promisify(this, 'stats', [params]) as Promise<PaginatedResult<Stats>>;
}
}
const headers = Defaults.defaultGetHeaders(this.options),
format = this.options.useBinaryProtocol ? Utils.Format.msgpack : Utils.Format.json,
envelope = this.http.supportsLinkHeaders ? undefined : format;

Utils.mixin(headers, this.options.headers);

new PaginatedResource(this, '/stats', headers, envelope, function (
body: unknown,
headers: Record<string, string>,
unpacked?: boolean
) {
const statsValues = unpacked ? body : JSON.parse(body as string);
for (let i = 0; i < statsValues.length; i++) statsValues[i] = Stats.fromValues(statsValues[i]);
return statsValues;
}).get(params as Record<string, string>, callback);
return this.rest.stats(params, callback);
}

time(params?: RequestParams | StandardCallback<number>, callback?: StandardCallback<number>): Promise<number> | void {
/* params and callback are optional; see if params contains the callback */
if (callback === undefined) {
if (typeof params == 'function') {
callback = params;
params = null;
} else {
return Utils.promisify(this, 'time', [params]) as Promise<number>;
}
}

const _callback = callback || noop;

const headers = Defaults.defaultGetHeaders(this.options);
if (this.options.headers) Utils.mixin(headers, this.options.headers);
const timeUri = (host: string) => {
return this.baseUri(host) + '/time';
};
this.http.do(
HttpMethods.Get,
this,
timeUri,
headers,
null,
params as RequestParams,
(
err?: ErrorInfo | ErrnoException | null,
res?: unknown,
headers?: Record<string, string>,
unpacked?: boolean
) => {
if (err) {
_callback(err);
return;
}
if (!unpacked) res = JSON.parse(res as string);
const time = (res as number[])[0];
if (!time) {
_callback(new ErrorInfo('Internal error (unexpected result type from GET /time)', 50000, 500));
return;
}
/* calculate time offset only once for this device by adding to the prototype */
this.serverTimeOffset = time - Utils.now();
_callback(null, time);
}
);
return this.rest.time(params, callback);
}

request(
Expand All @@ -192,141 +129,17 @@ class BaseClient {
customHeaders: Record<string, string>,
callback: StandardCallback<HttpPaginatedResponse<unknown>>
): Promise<HttpPaginatedResponse<unknown>> | void {
const useBinary = this.options.useBinaryProtocol,
encoder = useBinary ? Platform.Config.msgpack.encode : JSON.stringify,
decoder = useBinary ? Platform.Config.msgpack.decode : JSON.parse,
format = useBinary ? Utils.Format.msgpack : Utils.Format.json,
envelope = this.http.supportsLinkHeaders ? undefined : format;
params = params || {};
const _method = method.toLowerCase() as HttpMethods;
const headers =
_method == 'get'
? Defaults.defaultGetHeaders(this.options, { format, protocolVersion: version })
: Defaults.defaultPostHeaders(this.options, { format, protocolVersion: version });

if (callback === undefined) {
return Utils.promisify(this, 'request', [method, path, version, params, body, customHeaders]) as Promise<
HttpPaginatedResponse<unknown>
>;
}

if (typeof body !== 'string') {
body = encoder(body);
}
Utils.mixin(headers, this.options.headers);
if (customHeaders) {
Utils.mixin(headers, customHeaders);
}
const paginatedResource = new PaginatedResource(
this,
path,
headers,
envelope,
async function (resbody: unknown, headers: Record<string, string>, unpacked?: boolean) {
return Utils.ensureArray(unpacked ? resbody : decoder(resbody as string & Buffer));
},
/* useHttpPaginatedResponse: */ true
);

if (!Utils.arrIn(Platform.Http.methods, _method)) {
throw new ErrorInfo('Unsupported method ' + _method, 40500, 405);
}

if (Utils.arrIn(Platform.Http.methodsWithBody, _method)) {
paginatedResource[_method as HttpMethods.Post](params, body, callback as PaginatedResultCallback<unknown>);
} else {
paginatedResource[_method as HttpMethods.Get | HttpMethods.Delete](
params,
callback as PaginatedResultCallback<unknown>
);
}
return this.rest.request(method, path, version, params, body, customHeaders, callback);
}

batchPublish<T extends BatchPublishSpec | BatchPublishSpec[]>(
specOrSpecs: T
): Promise<T extends BatchPublishSpec ? BatchPublishResult : BatchPublishResult[]>;
batchPublish<T extends BatchPublishSpec | BatchPublishSpec[]>(
specOrSpecs: T,
callback?: StandardCallback<T extends BatchPublishSpec ? BatchPublishResult : BatchPublishResult[]>
): void | Promise<T extends BatchPublishSpec ? BatchPublishResult : BatchPublishResult[]> {
if (callback === undefined) {
return Utils.promisify(this, 'batchPublish', [specOrSpecs]);
}

let requestBodyDTO: BatchPublishSpec[];
let singleSpecMode: boolean;
if (Utils.isArray(specOrSpecs)) {
requestBodyDTO = specOrSpecs;
singleSpecMode = false;
} else {
requestBodyDTO = [specOrSpecs];
singleSpecMode = true;
}

const format = this.options.useBinaryProtocol ? Utils.Format.msgpack : Utils.Format.json,
headers = Defaults.defaultPostHeaders(this.options, { format });

if (this.options.headers) Utils.mixin(headers, this.options.headers);

const requestBody = Utils.encodeBody(requestBodyDTO, format);
Resource.post(
this,
'/messages',
requestBody,
headers,
{ newBatchResponse: 'true' },
null,
(err, body, headers, unpacked) => {
if (err) {
callback(err);
return;
}

const batchResults = (unpacked ? body : Utils.decodeBody(body, format)) as BatchPublishResult[];

// I don't love the below type assertions for `callback` but not sure how to avoid them
if (singleSpecMode) {
(callback as StandardCallback<BatchPublishResult>)(null, batchResults[0]);
} else {
(callback as StandardCallback<BatchPublishResult[]>)(null, batchResults);
}
}
);
): Promise<T extends BatchPublishSpec ? BatchPublishResult : BatchPublishResult[]> {
return this.rest.batchPublish(specOrSpecs);
}

batchPresence(channels: string[]): Promise<BatchPresenceResult>;
batchPresence(
channels: string[],
callback?: StandardCallback<BatchPresenceResult>
): void | Promise<BatchPresenceResult> {
if (callback === undefined) {
return Utils.promisify(this, 'batchPresence', [channels]);
}

const format = this.options.useBinaryProtocol ? Utils.Format.msgpack : Utils.Format.json,
headers = Defaults.defaultPostHeaders(this.options, { format });

if (this.options.headers) Utils.mixin(headers, this.options.headers);

const channelsParam = channels.join(',');

Resource.get(
this,
'/presence',
headers,
{ newBatchResponse: 'true', channels: channelsParam },
null,
(err, body, headers, unpacked) => {
if (err) {
callback(err);
return;
}

const batchResult = (unpacked ? body : Utils.decodeBody(body, format)) as BatchPresenceResult;

callback(null, batchResult);
}
);
batchPresence(channels: string[]): Promise<BatchPresenceResult> {
return this.rest.batchPresence(channels);
}

setLog(logOptions: LoggerOptions): void {
Expand All @@ -339,32 +152,4 @@ class BaseClient {
static PresenceMessage = PresenceMessage;
}

class Channels {
client: BaseClient;
all: Record<string, Channel>;

constructor(client: BaseClient) {
this.client = client;
this.all = Object.create(null);
}

get(name: string, channelOptions?: ChannelOptions) {
name = String(name);
let channel = this.all[name];
if (!channel) {
this.all[name] = channel = new Channel(this.client, name, channelOptions);
} else if (channelOptions) {
channel.setOptions(channelOptions);
}

return channel;
}

/* Included to support certain niche use-cases; most users should ignore this.
* Please do not use this unless you know what you're doing */
release(name: string) {
delete this.all[String(name)];
}
}

export default BaseClient;
8 changes: 6 additions & 2 deletions src/common/lib/client/baserealtime.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,17 +18,21 @@ import { ModulesMap } from './modulesmap';
`BaseRealtime` is an export of the tree-shakable version of the SDK, and acts as the base class for the `DefaultRealtime` class exported by the non tree-shakable version.
*/
class BaseRealtime extends BaseClient {
channels: any;
_channels: any;
connection: Connection;

constructor(options: ClientOptions, modules: ModulesMap) {
super(options, modules);
Logger.logAction(Logger.LOG_MINOR, 'Realtime()', '');
this.connection = new Connection(this, this.options);
this.channels = new Channels(this);
this._channels = new Channels(this);
if (options.autoConnect !== false) this.connect();
}

get channels() {
return this._channels;
}

connect(): void {
Logger.logAction(Logger.LOG_MINOR, 'Realtime.connect()', '');
this.connection.connect();
Expand Down
Loading

0 comments on commit 32e3f8f

Please sign in to comment.