@hcikn/colibri 1.2.0 → 2.0.0

package/dist/index.d.cts

@@ -1,6 +1,51 @@
 import * as rxjs from 'rxjs';
 import { Subject, Observable } from 'rxjs';
+import { CustomError } from 'ts-custom-error';
 
+/** Base class of colibri-web's errors, such as an invalid address or port. */
+declare class ColibriError extends CustomError {
+}
+/**
+ * Reported when this client and the server do not speak the same wire protocol. The fix is to run
+ * matching `colibri-web` and `colibri-server` versions.
+ *
+ * Check `fatal` first. Both kinds are reported on `Colibri.protocolMismatch`:
+ *
+ * - `fatal: true`: the server refused this client and disconnected it. Terminal. There is no
+ *   negotiation, so reconnecting cannot succeed, and `Colibri` stops Socket.IO from retrying.
+ * - `fatal: false`: the server is suspected to predate colibri-server 2.0.0, because it never
+ *   announced its protocol version. The connection stays up. Upgrade the server when you can.
+ */
+declare class ProtocolMismatchError extends ColibriError {
+    /**
+     * Wire protocol version the server speaks, like `'2'`, not a release version. The server
+     * reports it on refusal, and it is `'unknown'` if the refusal did not say. When not `fatal`
+     * it is inferred: a server that never announced itself is taken to speak `'1'`.
+     */
+    readonly serverVersion: string;
+    /** Wire protocol version this client announced in its handshake. */
+    readonly clientVersion: string;
+    /** Whether the connection is gone. False when the server is only suspected to be old. */
+    readonly fatal: boolean;
+    constructor(message: string, 
+    /**
+     * Wire protocol version the server speaks, like `'2'`, not a release version. The server
+     * reports it on refusal, and it is `'unknown'` if the refusal did not say. When not `fatal`
+     * it is inferred: a server that never announced itself is taken to speak `'1'`.
+     */
+    serverVersion: string, 
+    /** Wire protocol version this client announced in its handshake. */
+    clientVersion: string, 
+    /** Whether the connection is gone. False when the server is only suspected to be old. */
+    fatal?: boolean);
+}
+
+/**
+ * The wire protocol version this client speaks, sent in the handshake query. Must match the
+ * server's `PROTOCOL_VERSION` (`src/server/modules/networking/protocol.ts`); a server refuses a
+ * client that announces another version.
+ */
+declare const PROTOCOL_VERSION = "2";
 interface Message {
     channel: string;
     command: string;
@@ -9,16 +54,54 @@ interface Message {
 declare class Colibri {
     readonly app: string;
     readonly server: string;
-    readonly port: number;
     private static instance;
     private readonly socket;
     private readonly messageSubject;
     readonly messages: rxjs.Observable<Message>;
+    private readonly protocolMismatchSubject;
+    /**
+     * Reports that this client and the server do not speak the same wire protocol. Two kinds,
+     * told apart by {@link ProtocolMismatchError.fatal `fatal`}, each emitted at most once per
+     * instance:
+     *
+     * - `fatal: true`: the server refused this client. The connection is closed and not retried.
+     * - `fatal: false`: the server did not announce itself within 5s of connecting, so it is
+     *   suspected to predate colibri-server 2.0.0. The connection stays up.
+     *
+     * A suspicion can be followed by a refusal, never the other way round. Nothing is replayed to
+     * a late subscriber, so subscribe right after construction. Both kinds are also logged.
+     */
+    readonly protocolMismatch: rxjs.Observable<ProtocolMismatchError>;
     readonly uri: string;
     readonly uriRestApi: string;
+    /** The port connected to: the one in the server address, else the one passed, else 9211. */
+    readonly port: number;
+    private oldServerTimer;
+    private hasReportedOldServer;
+    private hasReportedRefusal;
+    private hasConnected;
+    private hasReportedOutage;
+    /**
+     * Connects to a Colibri server. Only one instance may exist.
+     * @param app the application name; clients only see each other's messages within one app
+     * @param server the host, optionally after `ws://`, `wss://`, `http://` or `https://` (the
+     *   secure ones mean `wss` for the socket and `https` for REST) and optionally with a port,
+     *   as in `'http://example.com:9211'`; no path. Defaults to the host that served the page,
+     *   and is required outside a browser.
+     * @param port the server port, if the address has none; 9211 if neither does. When both have
+     *   one, they must agree.
+     * @throws ColibriError for an address or port this client cannot connect to, or when an
+     *   instance already exists
+     */
     constructor(app: string, server?: string, port?: number);
     private onSocketConnect;
+    private onSocketDisconnect;
+    private onSocketConnectError;
+    private waitForServerHello;
+    private stopWaitingForServerHello;
+    private onServerHelloMissing;
     private onSocketAny;
+    private onProtocolRejected;
     /**
      * Returns the existing Colibri instance or null if there's none yet
      * @param warnIfNotInitialized true => print Log message if Colibri has not been initialized yet
@@ -51,24 +134,43 @@ declare class Colibri {
      */
     registerOnce(channel: string, handler: (payload: Message) => void): void;
     /**
-     * Returns the REST API Endpoint for a given `key` or null of the key is empty.
+     * Returns the REST API Endpoint for a given `key`, or null if the key is empty, `.` or `..`.
+     * Any other key is stored under exactly that name (`#`, `?`, `/`, `%` and spaces included)
+     * after surrounding whitespace and leading slashes are stripped.
      * @param key REST API storage key
      * @returns
      */
     getRestUri(key: string): string | null;
     /**
      * Queries an object from the REST API identified by `key`.
+     *
+     * Rejects when the server cannot be reached (wrong address, server down, no network) or an
+     * answer with a success status is not JSON.
      * @param key REST API storage key
-     * @returns JSON object with data or null if object does not exist or any other error occurrs
+     * @returns the stored value; or null if `key` is empty or the server answered with an error
+     *   status, such as 404 for a key that was never stored. A stored `null` looks the same.
      */
-    getRestObject(key: string): Promise<any | null>;
+    getRestObject(key: string): Promise<any>;
     /**
-     * Sets or updatees an object in the REST API identified by `key`.
+     * Sets or updates an object in the REST API identified by `key`.
+     *
+     * Rejects when the server cannot be reached (wrong address, server down, no network) or
+     * `data` cannot be serialized to JSON (circular structure, BigInt).
      * @param key REST API storage key
      * @param data JSON data to write
-     * @returns true if data was written to REST API
+     * @returns true if the server stored the data; false if `key` is empty or the server answered
+     *   with any other status
      */
     setRestObject(key: string, data: unknown): Promise<boolean>;
+    /**
+     * Deletes the object identified by `key` from the REST API.
+     *
+     * Rejects when the server cannot be reached (wrong address, server down, no network).
+     * @param key REST API storage key
+     * @returns true if the server deleted the value; false if `key` is empty or the server answered
+     *   with any other status, such as 404 for a key that holds no value
+     */
+    deleteRestObject(key: string): Promise<boolean>;
 }
 /**
  * @see {@link Colibri.sendMessage `Colibri.sendMessage()`}
@@ -77,19 +179,23 @@ declare class Colibri {
 declare const SendMessage: (channel: string, command: string, payload?: unknown) => void | undefined;
 /**
  * @see {@link Colibri.registerChannel `Colibri.registerChannel()`}
- * @returns undefined if {@link Colibri `Colibri`} has not been initialized yet
+ *
+ * Works before `new Colibri()` too: the handler is attached once the instance is constructed.
  */
-declare const RegisterChannel: (channel: string, handler: (payload: Message) => void) => void | undefined;
+declare const RegisterChannel: (channel: string, handler: (payload: Message) => void) => void;
 /**
  * @see {@link Colibri.unregisterChannel `Colibri.unregisterChannel()`}
- * @returns undefined if {@link Colibri `Colibri`} has not been initialized yet
+ *
+ * Before `new Colibri()`, takes back a handler that {@link RegisterChannel} or
+ * {@link RegisterOnce} queued.
  */
-declare const UnregisterChannel: (channel: string, handler: (payload: Message) => void) => void | undefined;
+declare const UnregisterChannel: (channel: string, handler: (payload: Message) => void) => void;
 /**
  * @see {@link Colibri.registerOnce `Colibri.registerOnce()`}
- * @returns undefined if {@link Colibri `Colibri`} has not been initialized yet
+ *
+ * Works before `new Colibri()` too, like {@link RegisterChannel}.
  */
-declare const RegisterOnce: (channel: string, handler: (payload: Message) => void) => void | undefined;
+declare const RegisterOnce: (channel: string, handler: (payload: Message) => void) => void;
 /**
  * @see {@link Colibri.getRestObject `Colibri.getRestObject()`}
  * @returns undefined if {@link Colibri `Colibri`} has not been initialized yet
@@ -100,8 +206,24 @@ declare const GetRestApi: (key: string) => Promise<any> | undefined;
  * @returns undefined if {@link Colibri `Colibri`} has not been initialized yet
  */
 declare const PutRestApi: (key: string, data: unknown) => Promise<boolean> | undefined;
+/**
+ * @see {@link Colibri.deleteRestObject `Colibri.deleteRestObject()`}
+ * @returns undefined if {@link Colibri `Colibri`} has not been initialized yet
+ */
+declare const DeleteRestApi: (key: string) => Promise<boolean> | undefined;
 
+/**
+ * A colour on the wire: `[r, g, b, a]` with components 0-1 from colibri-web, `"#RRGGBBAA"` from
+ * colibri-unity. Received colours can be either; normalize with {@link toHexColor} or
+ * {@link toRgbaColor}.
+ */
+type ColorValue = string | [number, number, number, number];
 type genericCallback = (val: any) => void;
+/** Converts a colour to `"#RRGGBBAA"`. An unparseable colour warns and gives opaque black. */
+declare const toHexColor: (val: ColorValue) => string;
+/** Converts a colour to `[r, g, b, a]` with components 0-1. An unparseable colour warns and gives opaque black. */
+declare const toRgbaColor: (val: ColorValue) => [number, number, number, number];
+/** Sends typed values on a channel and registers callbacks for the values received on it. */
 declare const Sync: {
     sendBool: (channel: string, val: boolean) => void;
     sendBoolArray: (channel: string, val: boolean[]) => void;
@@ -109,26 +231,14 @@ declare const Sync: {
     sendNumberArray: (channel: string, val: number[]) => void;
     sendString: (channel: string, val: string) => void;
     sendStringArray: (channel: string, val: string[]) => void;
+    sendVector2: (channel: string, val: [number, number]) => void;
+    sendVector2Array: (channel: string, val: [number, number][]) => void;
     sendVector3: (channel: string, val: [number, number, number]) => void;
-    sendVector3Array: (channel: string, val: [
-        number,
-        number,
-        number
-    ][]) => void;
+    sendVector3Array: (channel: string, val: [number, number, number][]) => void;
     sendQuaternion: (channel: string, val: [number, number, number, number]) => void;
-    sendQuaternionArray: (channel: string, val: [
-        number,
-        number,
-        number,
-        number
-    ][]) => void;
-    sendColor: (channel: string, val: [number, number, number, number]) => void;
-    sendColorArray: (channel: string, val: [
-        number,
-        number,
-        number,
-        number
-    ][]) => void;
+    sendQuaternionArray: (channel: string, val: [number, number, number, number][]) => void;
+    sendColor: (channel: string, val: ColorValue) => void;
+    sendColorArray: (channel: string, val: ColorValue[]) => void;
     sendJson: (channel: string, val: {
         [key: string]: unknown;
     }) => void;
@@ -138,21 +248,14 @@ declare const Sync: {
     receiveNumberArray: (channel: string, callback: (val: number[]) => void) => void;
     receiveString: (channel: string, callback: (val: string) => void) => void;
     receiveStringArray: (channel: string, callback: (val: string[]) => void) => void;
+    receiveVector2: (channel: string, callback: (val: [number, number]) => void) => void;
+    receiveVector2Array: (channel: string, callback: (val: [number, number][]) => void) => void;
     receiveVector3: (channel: string, callback: (val: [number, number, number]) => void) => void;
-    receiveVector3Array: (channel: string, callback: (val: [
-        number,
-        number,
-        number
-    ][]) => void) => void;
+    receiveVector3Array: (channel: string, callback: (val: [number, number, number][]) => void) => void;
     receiveQuaternion: (channel: string, callback: (val: [number, number, number, number]) => void) => void;
-    receiveQuaternionArray: (channel: string, callback: (val: [
-        number,
-        number,
-        number,
-        number
-    ][]) => void) => void;
-    receiveColor: (channel: string, callback: (val: string) => void) => void;
-    receiveColorArray: (channel: string, callback: (val: string[]) => void) => void;
+    receiveQuaternionArray: (channel: string, callback: (val: [number, number, number, number][]) => void) => void;
+    receiveColor: (channel: string, callback: (val: ColorValue) => void) => void;
+    receiveColorArray: (channel: string, callback: (val: ColorValue[]) => void) => void;
     receiveJson: (channel: string, callback: (val: {
         [key: string]: unknown;
     }) => void) => void;
@@ -165,37 +268,67 @@ declare const Sync: {
 
 declare class RemoteLogger {
     private enabled;
+    private static patched;
+    private readonly forwarder;
+    private hasWarnedOfAnotherInstance;
     private readonly consoleDebug;
     private readonly consoleLog;
     private readonly consoleInfo;
     private readonly consoleWarn;
     private readonly consoleError;
+    private forwarding;
+    private readonly earlyLines;
+    private droppedEarlyLines;
+    private waitingForColibri;
     /**
      * @deprecated use new class constructor directly
      */
     static init(enabled?: boolean): RemoteLogger;
+    /**
+     * Forwards everything logged through `console` to the server's log. Create one, at startup.
+     * A further instance warns once and does not patch again; its `enabled` argument, `enable()` and
+     * `disable()` act on the first one.
+     * @param enabled whether to forward from the start
+     */
     constructor(enabled?: boolean);
     private sendMessage;
+    private keepUntilColibriExists;
+    private sendEarlyLines;
+    /** Starts forwarding console output to the server's log. */
     enable(): void;
+    /** Stops forwarding to the server's log; the console still prints. */
     disable(): void;
 }
 
 declare abstract class SyncModel<T> {
+    #private;
+    private __syncedProperties?;
     readonly id: string;
-    private syncedProperties;
-    ignoreNextChange: boolean;
+    applyingRemoteUpdate: boolean;
     readonly modelChanges: Subject<string>;
     readonly modelChanges$: rxjs.Observable<string[]>;
+    readonly deletions: Subject<void>;
     constructor(id: string);
     private uniq;
     protected onModelChanges(prop: string): void;
+    /**
+     * Deletes the model for every client of the app (Unity destroys its GameObject) and removes it
+     * from this client's list. The model stops syncing.
+     */
     delete(): void;
+    /**
+     * Stops syncing the model on this client only; every other client keeps it. RegisterModelSync
+     * calls it on a remote delete and when registerModel replaces a listed copy.
+     */
+    detach(): void;
     registerSyncedProperty(name: string, prop: string | symbol): void;
+    private getSyncedProperties;
     update(updates: Partial<T>): void;
     toJson(attributes?: string[]): Partial<T>;
 }
 
 interface ModelSyncRegistration<T> {
+    /** The channel to sync on. Recommended: the default, the lowercased class name, changes when minified. */
     name?: string;
     type: {
         new (id: string): T;
@@ -205,10 +338,67 @@ type ModelSync<T> = [Observable<T[]>, (model: T) => void];
 declare const RegisterModelSync: <T extends SyncModel<T>>(registration: ModelSyncRegistration<T>) => ModelSync<T>;
 
 /**
- *  This decorator can be attached to any property or accessor of a SyncModel.
+ *  This decorator can be attached to any `accessor` member of a SyncModel.
  *  It will cause the property to be synchronized with the server.
- *  Refer to https://www.typescriptlang.org/docs/handbook/decorators.html
+ *  Refer to https://github.com/tc39/proposal-decorators
+ */
+declare function Synced<This extends SyncModel<unknown>, V>(syncedName?: string): (value: ClassAccessorDecoratorTarget<This, V>, context: ClassAccessorDecoratorContext<This, V>) => ClassAccessorDecoratorResult<This, V>;
+/**
+ *  Declares synchronized properties without a decorator, for plain JavaScript. Call it in the
+ *  constructor of a SyncModel subclass, after `super(id)`, with each property and its start value:
+ *
+ *  ```js
+ *  class Cube extends SyncModel {
+ *      constructor(id) {
+ *          super(id);
+ *          synced(this, { x: 0, y: 0, color: 'red' });
+ *      }
+ *  }
+ *  ```
+ *
+ *  Each property syncs as with `@Synced()`, under its lowercased name or under `names[property]`.
+ *  Throws for a property the model already has as a member, and for a start value of `undefined`.
+ */
+declare function synced<M extends SyncModel<unknown>, P extends Record<string, unknown>>(model: M, values: P, names?: Partial<Record<keyof P & string, string>>): asserts model is M & P;
+
+/** `[x, y, z]`, as colibri-unity sends a Vector3. */
+type Vector3 = [number, number, number];
+/** `[x, y, z, w]`, as colibri-unity sends a Quaternion. */
+type Quaternion = [number, number, number, number];
+/**
+ * The web side of colibri-unity's `SyncTransform`: active state, position, rotation and scale in
+ * Unity's coordinates. Register it with {@link RegisterSyncTransforms}.
+ *
+ * Members mirror colibri-unity's `[Sync]` members. A Unity object with a member's Sync box unticked
+ * never sends it, so it keeps its default here, which equals Unity's placeholder.
+ *
+ * Assign a new array to change a vector: `transform.position = [1, 2, 3]` is sent,
+ * `transform.position[0] = 1` is not.
+ */
+declare class SyncTransform extends SyncModel<SyncTransform> {
+    /** Unity's `activeSelf`. `false` hides the object on the Unity clients. */
+    accessor active: boolean;
+    /** World position, or local position with *Use Local Transform* ticked. */
+    accessor position: Vector3;
+    /** World rotation, or local rotation with *Use Local Transform* ticked. */
+    accessor rotation: Quaternion;
+    /** Local scale. */
+    accessor scale: Vector3;
+    /**
+     * Id of the Unity client that simulates the object's physics (`PhysicsAuthority`). Declared so a
+     * remote update carrying it is not warned about as an unknown property. Setting it takes the
+     * authority away from that client.
+     */
+    accessor physicsId: string;
+}
+/**
+ * {@link RegisterModelSync} for `SyncTransform`: returns an Observable of all of them, which emits
+ * when one is added, changed or deleted, and a function that registers a new one.
+ *
+ * Unity objects with a `ModelId` sync on a channel of their own, so pass the same `modelId`. Call
+ * this once per channel and share the result: two registrations on one channel in one page do not
+ * receive each other's updates.
  */
-declare const Synced: <T>(syncedName?: string) => PropertyDecorator;
+declare const RegisterSyncTransforms: (modelId?: string) => [Observable<SyncTransform[]>, (transform: SyncTransform) => void];
 
-export { Colibri, GetRestApi, Message, PutRestApi, RegisterChannel, RegisterModelSync, RegisterOnce, RemoteLogger, SendMessage, Sync, SyncModel, Synced, UnregisterChannel };
+export { Colibri, ColibriError, type ColorValue, DeleteRestApi, GetRestApi, type Message, PROTOCOL_VERSION, ProtocolMismatchError, PutRestApi, type Quaternion, RegisterChannel, RegisterModelSync, RegisterOnce, RegisterSyncTransforms, RemoteLogger, SendMessage, Sync, SyncModel, SyncTransform, Synced, UnregisterChannel, type Vector3, synced, toHexColor, toRgbaColor };