chore: change CI target for next

.github/workflows/ci-plugin.yml

@@ -4,12 +4,10 @@ on:
  push:
  branches:
  - master
+ - next
  pull_request:
  workflow_dispatch:
 
 jobs:
  test:
- uses: hapijs/.github/.github/workflows/ci-plugin.yml@master
- with:
- min-node-version: 14
- min-hapi-version: 20
+ uses: hapijs/.github/.github/workflows/ci-plugin.yml@min-node-18-hapi-21

lib/client.d.ts

@@ -0,0 +1,372 @@
+// Same as exported type in @hapi/hapi v20
+type HTTP_METHODS = 'ACL' | 'BIND' | 'CHECKOUT' | 'CONNECT' | 'COPY' | 'DELETE' | 'GET' | 'HEAD' | 'LINK' | 'LOCK' |
+ 'M-SEARCH' | 'MERGE' | 'MKACTIVITY' | 'MKCALENDAR' | 'MKCOL' | 'MOVE' | 'NOTIFY' | 'OPTIONS' | 'PATCH' | 'POST' |
+ 'PROPFIND' | 'PROPPATCH' | 'PURGE' | 'PUT' | 'REBIND' | 'REPORT' | 'SEARCH' | 'SOURCE' | 'SUBSCRIBE' | 'TRACE' |
+ 'UNBIND' | 'UNLINK' | 'UNLOCK' | 'UNSUBSCRIBE';
+
+type ErrorType = (
+ 'timeout' |
+ 'disconnect' |
+ 'server' |
+ 'protocol' |
+ 'ws' |
+ 'user'
+);
+
+type ErrorCodes = {
+ 1000: 'Normal closure',
+ 1001: 'Going away',
+ 1002: 'Protocol error',
+ 1003: 'Unsupported data',
+ 1004: 'Reserved',
+ 1005: 'No status received',
+ 1006: 'Abnormal closure',
+ 1007: 'Invalid frame payload data',
+ 1008: 'Policy violation',
+ 1009: 'Message too big',
+ 1010: 'Mandatory extension',
+ 1011: 'Internal server error',
+ 1015: 'TLS handshake'
+};
+
+type NesLog = {
+
+ readonly code: keyof ErrorCodes;
+ readonly explanation: ErrorCodes[keyof ErrorCodes] | 'Unknown';
+ readonly reason: string;
+ readonly wasClean: boolean;
+ readonly willReconnect: boolean;
+ readonly wasRequested: boolean;
+}
+
+export interface NesError extends Error {
+
+ type: ErrorType;
+ isNes: true;
+ statusCode?: number;
+ data?: any;
+ headers?: Record<string, string>;
+ path?: string;
+}
+
+export interface ClientConnectOptions {
+
+ /**
+ * sets the credentials used to authenticate.
+ * when the server is configured for
+ *
+ * - `'token'` type authentication, the value
+ * is the token response received from the
+ * authentication endpoint (called manually by
+ * the application). When the server is
+ * configured for `'direct'` type
+ * authentication, the value is the credentials
+ * expected by the server for the specified
+ * authentication strategy used which typically
+ * means an object with headers
+ * (e.g. `{ headers: { authorization: 'Basic am9objpzZWNyZXQ=' } }`).
+ */
+ auth?: string | {
+ headers?: Record<string, string>;
+ payload?: Record<string, string>;
+ };
+
+ /**
+ * A boolean that indicates whether the client
+ * should try to reconnect. Defaults to `true`.
+ */
+ reconnect?: boolean;
+
+ /**
+ * Time in milliseconds to wait between each
+ * reconnection attempt. The delay time is
+ * cumulative, meaning that if the value is set
+ * to `1000` (1 second), the first wait will be
+ * 1 seconds, then 2 seconds, 3 seconds, until
+ * the `maxDelay` value is reached and then
+ * `maxDelay` is used.
+ */
+ delay?: number;
+
+ /**
+ * The maximum delay time in milliseconds
+ * between reconnections.
+ */
+ maxDelay?: number;
+
+ /**
+ * number of reconnection attempts. Defaults to
+ * `Infinity` (unlimited).
+ */
+ retries?: number;
+
+ /**
+ * socket connection timeout in milliseconds.
+ * Defaults to the WebSocket implementation
+ * timeout default.
+ */
+ timeout?: number;
+}
+
+type NesReqRes<R> = {
+ payload: R;
+ statusCode: number;
+ headers: Record<string, string>;
+}
+
+export interface ClientRequestOptions {
+
+ /**
+ * The requested endpoint path or route id.
+ */
+ path: string;
+
+ /**
+ * The requested HTTP method (can also be any
+ * method string supported by the server).
+ * Defaults to `'GET'`.
+ */
+ method?: Omit<HTTP_METHODS | Lowercase<HTTP_METHODS>, 'HEAD' | 'head'>;
+ /**
+ * An object where each key is a request header
+ * and the value the header content. Cannot
+ * include an Authorization header. Defaults to
+ * no headers.
+ */
+ headers?: Record<string, string>;
+
+ /**
+ * The request payload sent to the server.
+ */
+ payload?: any;
+}
+
+export interface NesSubHandler {
+
+ (
+ message: unknown,
+ flags: {
+
+ /**
+ * Set to `true` when the message is the
+ * last update from the server due to a
+ * subscription revocation.
+ */
+ revoked?: boolean;
+
+ }
+ ): void;
+}
+
+/**
+ * Creates a new client object
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#client-5
+ */
+export class Client {
+
+ /**
+ * https://github.com/hapijs/nes/blob/master/API.md#new-clienturl-options
+ * @param url
+ * @param options
+ */
+ constructor(
+ url: `ws://${string}` | `wss://${string}`,
+ options?: {
+ ws?: string | string[];
+ timeout?: number | boolean;
+ });
+
+ /**
+ * The unique socket identifier assigned by the
+ * server. The value is set after the
+ * connection is established.
+ */
+ readonly id: string | null;
+
+ /**
+ * A property set by the developer to handle
+ * errors. Invoked whenever an error happens
+ * that cannot be associated with a pending
+ * request.
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#clientonerror
+ */
+ onError(err: NesError): void;
+
+ /**
+ * A property set by the developer used to set
+ * a handler for connection events (initial
+ * connection and subsequent reconnections)
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#clientonconnect
+ */
+ onConnect(): void;
+
+ /**
+ * A property set by the developer used to set
+ * a handler for disconnection events
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#clientondisconnect
+ *
+ * @param willReconnect A boolean indicating if
+ * the client will automatically attempt to
+ * reconnect
+ * @param log A log object containing
+ * information about the disconnection
+ */
+ onDisconnect(willReconnect: boolean, log: NesLog): void;
+
+ /**
+ * A property set by the developer used to set
+ * a handler for heartbeat timeout events
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#clientonheartbeattimeout
+ *
+ * @param willReconnect A boolean indicating if
+ * the client will automatically attempt to
+ * reconnect
+ */
+ onHeartbeatTimeout(willReconnect: boolean): void;
+
+ /**
+ * A property set by the developer used to set
+ * a custom message handler. Invoked whenever
+ * the server calls `server.broadcast()` or
+ * `socket.send()`.
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#clientonupdate
+ *
+ * @param message
+ */
+
+ onUpdate(message: unknown): void;
+
+
+ /**
+ * Connects the client to the server
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#await-clientconnectoptions
+ */
+ connect(options?: ClientConnectOptions): Promise<void>;
+
+ /**
+ * Disconnects the client from the server and
+ * stops future reconnects.
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#await-clientdisconnect
+ */
+ disconnect(): Promise<void>;
+
+ /**
+ * Sends an endpoint request to the server.
+ * This overload will perform a `GET` request by
+ * default.
+ *
+ * Rejects with `Error` if the request failed.
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#await-clientrequestoptions
+ *
+ * @param path The endpoint path
+ */
+ request <R = any>(path: string): Promise<NesReqRes<R>>;
+
+ /**
+ * Sends an endpoint request to the server.
+ *
+ * Rejects with `Error` if the request failed.
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#await-clientrequestoptions
+ *
+ * @param options The request options
+ */
+ request <R = any>(options: ClientRequestOptions): Promise<NesReqRes<R>>;
+
+
+ /**
+ * Sends a custom message to the server which
+ * is received by the server `onMessage` handler
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#await-clientmessagemessage
+ *
+ * @param message The message sent to the
+ * server. Can be any type which can be safely
+ * converted to string using `JSON.stringify()`.
+ */
+ message <R = any>(message: unknown): Promise<R>;
+
+ /**
+ * Subscribes to a server subscription
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#await-clientsubscribepath-handler
+ *
+ * @param path The requested subscription path.
+ * Paths are just like HTTP request paths (e.g.
+ * `'/item/5'` or `'/updates'` based on the
+ * paths supported by the server).
+ *
+ * @param handler The function used to receive subscription updates
+ */
+ subscribe(path: string, handler: NesSubHandler): Promise<void>;
+
+ /**
+ * Cancels a subscription
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#await-clientunsubscribepath-handler
+ *
+ * @param path the subscription path used to subscribe
+ * @param handler remove a specific handler from a
+ * subscription or `null` to remove all handlers for
+ * the given path
+ */
+ unsubscribe(path: string, handler?: NesSubHandler): Promise<void>;
+
+ /**
+ * Returns an array of the current subscription paths.
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#clientsubscriptions
+ *
+ */
+ subscriptions(): string[];
+
+ /**
+ * Sets or overrides the authentication credentials used
+ * to reconnect the client on disconnect when the client
+ * is configured to automatically reconnect
+ *
+ * Returns `true` if reconnection is enabled, otherwise
+ * `false` (in which case the method was ignored).
+ *
+ * Note: this will not update the credentials on the
+ * server - use `client.reauthenticate()`
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#clientoverridereconnectionauthauth
+ *
+ * @param auth same as the `auth` option passed to
+ * `client.connect()`
+ */
+ overrideReconnectionAuth(auth: ClientConnectOptions['auth']): boolean;
+
+ /**
+ * Will issue the `reauth` message to the server with
+ * updated `auth` details and also override the
+ * reconnection information, if reconnection is enabled.
+ * The server will respond with an error and drop the
+ * connection in case the new `auth` credentials are
+ * invalid.
+ *
+ * Rejects with `Error` if the request failed.
+ *
+ * Resolves with `true` if the request succeeds.
+ *
+ * Note: when authentication has a limited lifetime,
+ * `reauthenticate()` should be called early enough to
+ * avoid the server dropping the connection.
+ *
+ * https://github.com/hapijs/nes/blob/master/API.md#await-clientreauthenticateauth
+ *
+ * @param auth same as the `auth` option passed to
+ * `client.connect()`
+ */
+ reauthenticate(auth: ClientConnectOptions['auth']): Promise<unknown>;
+}