felix-gateway-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Loewen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# felix-gateway-client
+
+The browser client for [felix-gateway](https://github.com/GetFelix/felix-gateway). It opens a WebSocket, joins one
+scope (a room or a match) with an ID token, and then publishes, subscribes,
+reads and watches caches and adds to counters, each named by its alias in the
+gateway's scope file.
+[docs/protocol.md](https://github.com/GetFelix/felix-gateway/blob/main/docs/protocol.md)
+describes the protocol.
+
+```ts
+import { GatewayClient } from "felix-gateway-client";
+
+const client = await GatewayClient.connect("wss://example.com/ws", { room: "lobby", token });
+client.onEvent = (event) => console.log(event.stream, event.offset, event.payload);
+client.subscribe("ops", "live");
+await client.publish("ops", new TextEncoder().encode("hello"));
+```
+
+`felix-gateway-client/fake` has `FakeScope` and `FakeGateway`, an in-memory
+stand-in with the same shape as `GatewayClient`, for tests that should not need
+a gateway or a broker. It can drop live records and lose acks to exercise
+recovery paths.
+
+## License
+
+MIT

package/dist/fake.d.ts

@@ -0,0 +1,58 @@
+import { type CacheEntry, type Gateway } from "./index.js";
+/**
+ * The streams, caches and counters of one scope, shared by every
+ * {@link FakeGateway} connected to it.
+ */
+export declare class FakeScope {
+    /** Each stream's records, indexed by log offset. */
+    readonly streams: Map<string, Uint8Array<ArrayBufferLike>[]>;
+    /** Each cache's entries by key. */
+    readonly caches: Map<string, Map<string, Uint8Array<ArrayBufferLike>>>;
+    /** Each counter's sums by key. */
+    readonly counters: Map<string, Map<string, number>>;
+    /** The first offset each stream still holds; a subscribe from earlier is `trimmed`. */
+    readonly retainedFrom: Map<string, number>;
+    readonly connections: Set<FakeGateway>;
+    /** The records of `stream`, which a test may read or fill directly. */
+    log(stream: string): Uint8Array[];
+    /** Append a record to `stream`, deliver it to subscribers and return its offset. */
+    append(stream: string, payload: Uint8Array): number;
+    /** Answer a `cacheGet`. Override it to compute a value when it is read. */
+    readCache(cache: string, key: string): Uint8Array | null;
+    /** Write `key` of `cache`, or delete it with `null`, and tell its watchers. */
+    writeCache(cache: string, key: string, payload: Uint8Array | null): void;
+    /** Add `delta` to `key` of `counter` and return the new sum. */
+    addCounter(counter: string, key: string, delta: number): number;
+}
+/** One connection to a {@link FakeScope}, shaped like a `GatewayClient`. */
+export declare class FakeGateway implements Gateway {
+    #private;
+    readonly scope: FakeScope;
+    onHello: Gateway["onHello"];
+    onEvent: Gateway["onEvent"];
+    onSubscribed: Gateway["onSubscribed"];
+    onError: Gateway["onError"];
+    onClose: Gateway["onClose"];
+    onCacheEntries: Gateway["onCacheEntries"];
+    onCacheChange: Gateway["onCacheChange"];
+    /** While set, live records are lost on the way, as Felix drops them for a slow reader. */
+    dropping: boolean;
+    /** While set, a publish lands in the log but its answer is lost, as when the owner fails. */
+    losingAcks: boolean;
+    /** The last rate passed to {@link throttle}. */
+    bitsPerSecond: number | null;
+    constructor(scope: FakeScope);
+    subscribe(stream: string, from: number | "live"): void;
+    /** Deliver the record at `offset` of `stream` if this connection subscribes to it. */
+    deliver(stream: string, offset: number, live?: boolean): void;
+    publish(stream: string, payload: Uint8Array, ack?: boolean): Promise<number | null>;
+    counterAdd(counter: string, key: string, delta: number): Promise<number>;
+    cacheGet(cache: string, key: string): Promise<Uint8Array | null>;
+    cachePut(cache: string, key: string, payload: Uint8Array): void;
+    cacheDelete(cache: string, key: string): void;
+    cacheWatch(cache: string): void;
+    /** Report a change to `cache` if this connection watches it. */
+    changed(cache: string, entry: CacheEntry): void;
+    throttle(bitsPerSecond: number | null): void;
+    close(): void;
+}

package/dist/fake.js

@@ -0,0 +1,145 @@
+// An in-memory stand-in for the gateway, for testing code written against
+// GatewayClient without a gateway or a broker. Everything is answered on a
+// later task, as a socket would.
+import { GatewayError } from "./index.js";
+/**
+ * The streams, caches and counters of one scope, shared by every
+ * {@link FakeGateway} connected to it.
+ */
+export class FakeScope {
+    /** Each stream's records, indexed by log offset. */
+    streams = new Map();
+    /** Each cache's entries by key. */
+    caches = new Map();
+    /** Each counter's sums by key. */
+    counters = new Map();
+    /** The first offset each stream still holds; a subscribe from earlier is `trimmed`. */
+    retainedFrom = new Map();
+    connections = new Set();
+    /** The records of `stream`, which a test may read or fill directly. */
+    log(stream) {
+        let log = this.streams.get(stream);
+        if (!log)
+            this.streams.set(stream, (log = []));
+        return log;
+    }
+    /** Append a record to `stream`, deliver it to subscribers and return its offset. */
+    append(stream, payload) {
+        const offset = this.log(stream).push(payload) - 1;
+        for (const connection of this.connections)
+            connection.deliver(stream, offset);
+        return offset;
+    }
+    /** Answer a `cacheGet`. Override it to compute a value when it is read. */
+    readCache(cache, key) {
+        return this.caches.get(cache)?.get(key) ?? null;
+    }
+    /** Write `key` of `cache`, or delete it with `null`, and tell its watchers. */
+    writeCache(cache, key, payload) {
+        let entries = this.caches.get(cache);
+        if (!entries)
+            this.caches.set(cache, (entries = new Map()));
+        if (payload === null)
+            entries.delete(key);
+        else
+            entries.set(key, payload);
+        for (const connection of this.connections) {
+            connection.changed(cache, { key, payload, expiresInMs: null });
+        }
+    }
+    /** Add `delta` to `key` of `counter` and return the new sum. */
+    addCounter(counter, key, delta) {
+        let sums = this.counters.get(counter);
+        if (!sums)
+            this.counters.set(counter, (sums = new Map()));
+        const value = (sums.get(key) ?? 0) + delta;
+        sums.set(key, value);
+        return value;
+    }
+}
+/** One connection to a {@link FakeScope}, shaped like a `GatewayClient`. */
+export class FakeGateway {
+    scope;
+    onHello = () => { };
+    onEvent = () => { };
+    onSubscribed = () => { };
+    onError = () => { };
+    onClose = () => { };
+    onCacheEntries = () => { };
+    onCacheChange = () => { };
+    /** While set, live records are lost on the way, as Felix drops them for a slow reader. */
+    dropping = false;
+    /** While set, a publish lands in the log but its answer is lost, as when the owner fails. */
+    losingAcks = false;
+    /** The last rate passed to {@link throttle}. */
+    bitsPerSecond = null;
+    #from = new Map();
+    #watching = new Set();
+    constructor(scope) {
+        this.scope = scope;
+        scope.connections.add(this);
+    }
+    subscribe(stream, from) {
+        setTimeout(() => {
+            const oldest = this.scope.retainedFrom.get(stream) ?? 0;
+            if (typeof from === "number" && from < oldest) {
+                this.onError(new GatewayError("trimmed", `oldest is ${oldest}`), stream);
+                return;
+            }
+            const tail = this.scope.log(stream).length;
+            const start = from === "live" ? tail : from;
+            this.#from.set(stream, start);
+            this.onSubscribed(stream, start, tail);
+            for (let offset = start; offset < tail; offset++)
+                this.deliver(stream, offset, false);
+        });
+    }
+    /** Deliver the record at `offset` of `stream` if this connection subscribes to it. */
+    deliver(stream, offset, live = true) {
+        const from = this.#from.get(stream);
+        if (from === undefined || offset < from || (live && this.dropping))
+            return;
+        const payload = this.scope.log(stream)[offset];
+        this.onEvent({ stream, offset, skippedBefore: 0, payload });
+    }
+    async publish(stream, payload, ack = true) {
+        const offset = this.scope.append(stream, payload);
+        if (this.losingAcks)
+            throw new GatewayError("publish_failed", "connection lost");
+        return ack ? offset : null;
+    }
+    async counterAdd(counter, key, delta) {
+        return this.scope.addCounter(counter, key, delta);
+    }
+    async cacheGet(cache, key) {
+        await new Promise((resolve) => setTimeout(resolve));
+        return this.scope.readCache(cache, key);
+    }
+    cachePut(cache, key, payload) {
+        this.scope.writeCache(cache, key, payload);
+    }
+    cacheDelete(cache, key) {
+        this.scope.writeCache(cache, key, null);
+    }
+    cacheWatch(cache) {
+        setTimeout(() => {
+            this.#watching.add(cache);
+            const entries = [...(this.scope.caches.get(cache) ?? [])].map(([key, payload]) => ({ key, payload, expiresInMs: null }));
+            this.onCacheEntries(cache, entries);
+        });
+    }
+    /** Report a change to `cache` if this connection watches it. */
+    changed(cache, entry) {
+        if (this.#watching.has(cache))
+            this.onCacheChange(cache, entry);
+    }
+    throttle(bitsPerSecond) {
+        this.bitsPerSecond = bitsPerSecond;
+    }
+    close() {
+        this.#from.clear();
+        this.#watching.clear();
+        this.scope.connections.delete(this);
+        this.onClose();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,159 @@
+/** The protocol version this client speaks. */
+export declare const PROTOCOL = 1;
+/** Messages the gateway sends. */
+export type ServerMessage = {
+    type: "hello";
+    protocol: number;
+    features: string[];
+    namespace: string;
+    cache_ttl_ms: Record<string, number>;
+    missing?: string[];
+} | {
+    type: "subscribed";
+    stream: string;
+    start_offset: number | null;
+    live_offset: number | null;
+} | {
+    type: "event";
+    stream: string;
+    offset: number | null;
+    skipped_before?: number;
+    payload: string;
+} | {
+    type: "ack";
+    id: number;
+    offset: number | null;
+} | {
+    type: "counter";
+    id: number;
+    value: number;
+} | {
+    type: "cache_value";
+    id: number;
+    payload: string | null;
+} | {
+    type: "cache_entries";
+    cache: string;
+    entries: WireEntry[];
+} | ({
+    type: "cache_change";
+    cache: string;
+} & WireEntry) | {
+    type: "error";
+    id?: number;
+    stream?: string;
+    cache?: string;
+    code: "bad_request" | "unsupported" | "publish_failed" | "subscribe_failed" | "subscription_ended" | "counter_failed" | "cache_failed" | "trimmed" | "watch_failed" | "signed_out" | "forbidden" | "unavailable";
+    oldest?: number;
+    message: string;
+};
+/**
+ * The sign-in, and the scope to open under the key the gateway's scope file
+ * names, such as `{ room: "lobby", token }`.
+ */
+export interface Join {
+    token: string;
+    [scopeField: string]: string;
+}
+/** What the gateway answered a join with. */
+export interface Hello {
+    namespace: string;
+    /** The features asked for that the gateway accepted. */
+    features: string[];
+    /** How long an entry lasts without a write, for each cache with a TTL. */
+    cacheTtlMs: Record<string, number>;
+    /** Optional resources the sign-in does not reach. */
+    missing: string[];
+}
+interface WireEntry {
+    key: string;
+    payload: string | null;
+    expires_in_ms: number | null;
+}
+/** One cache entry as the gateway reports it. */
+export interface CacheEntry {
+    key: string;
+    /** The entry's value, or `null` when it was deleted. */
+    payload: Uint8Array | null;
+    /** Milliseconds until the entry expires, or `null` if it never does. */
+    expiresInMs: number | null;
+}
+/** One record delivered on a stream. */
+export interface GatewayEvent {
+    stream: string;
+    /** Log offset; `null` on a stream with no log. */
+    offset: number | null;
+    /** Offsets just before this one that hold no event. */
+    skippedBefore: number;
+    payload: Uint8Array;
+}
+/** Raised when the gateway reports that a request failed. */
+export declare class GatewayError extends Error {
+    readonly code: string;
+    name: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Everything a {@link GatewayClient} offers, without its private state, so
+ * code can accept a stand-in such as `FakeGateway` from `felix-gateway-client/fake`.
+ */
+export type Gateway = Pick<GatewayClient, keyof GatewayClient>;
+/**
+ * A connection to the gateway. Events and subscription changes are reported
+ * through the callbacks; publishes resolve with the record's log offset.
+ */
+export declare class GatewayClient {
+    #private;
+    /** Called once, first, when the gateway has opened the session. */
+    onHello: (hello: Hello) => void;
+    /** Called with every entry of a cache when a watch of it starts. */
+    onCacheEntries: (cache: string, entries: CacheEntry[]) => void;
+    /** Called for each entry written or deleted after that. */
+    onCacheChange: (cache: string, entry: CacheEntry) => void;
+    /** Called for every event, in the order the broker delivered them. */
+    onEvent: (event: GatewayEvent) => void;
+    /** Called once a subscription is registered with the broker. */
+    onSubscribed: (stream: string, start: number | null, live: number | null) => void;
+    /**
+     * Called for errors not tied to a request, such as a subscription ending,
+     * with the stream or cache they are about.
+     */
+    onError: (error: GatewayError, stream?: string, cache?: string) => void;
+    /** Called when the connection closes. */
+    onClose: () => void;
+    private constructor();
+    /**
+     * Open a connection to the gateway at `url`, a `ws:` or `wss:` URL, and
+     * join the scope in `join`, asking for `features`. The gateway answers with
+     * `hello`, or refuses with an error and closes.
+     */
+    static connect(url: string, join: Join, features?: string[]): Promise<GatewayClient>;
+    /**
+     * Relay `stream` from `from`: a log offset (the last one handled, plus one)
+     * or `"live"`. Replaces an earlier subscription to the same stream.
+     */
+    subscribe(stream: string, from: number | "live"): void;
+    /**
+     * Publish one record. With `ack`, resolves once the broker has it, with its
+     * log offset when the broker acknowledged after writing. Without, resolves
+     * as soon as the request is sent.
+     */
+    publish(stream: string, payload: Uint8Array, ack?: boolean): Promise<number | null>;
+    /** Add `delta` to `key` of `counter` and resolve with the new sum. */
+    counterAdd(counter: string, key: string, delta: number): Promise<number>;
+    /** Read `key` of `cache`: its value, or `null` when there is none. */
+    cacheGet(cache: string, key: string): Promise<Uint8Array | null>;
+    /** Write `key` of `cache`. It expires after the cache's TTL unless written again. */
+    cachePut(cache: string, key: string, payload: Uint8Array): void;
+    /** Delete `key` of `cache`. */
+    cacheDelete(cache: string, key: string): void;
+    /** Watch the entries of `cache`. Replaces an earlier watch of it. */
+    cacheWatch(cache: string): void;
+    /**
+     * Have the gateway read this connection's subscriptions no faster than a
+     * link of `bitsPerSecond` would carry them, or at full speed with `null`.
+     */
+    throttle(bitsPerSecond: number | null): void;
+    close(): void;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,201 @@
+// The browser half of the gateway protocol. docs/protocol.md is the reference.
+// Streams, caches and counters are named by their alias in the gateway's
+// scope file.
+/** The protocol version this client speaks. */
+export const PROTOCOL = 1;
+/** Raised when the gateway reports that a request failed. */
+export class GatewayError extends Error {
+    code;
+    name = "GatewayError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * A connection to the gateway. Events and subscription changes are reported
+ * through the callbacks; publishes resolve with the record's log offset.
+ */
+export class GatewayClient {
+    /** Called once, first, when the gateway has opened the session. */
+    onHello = () => { };
+    /** Called with every entry of a cache when a watch of it starts. */
+    onCacheEntries = () => { };
+    /** Called for each entry written or deleted after that. */
+    onCacheChange = () => { };
+    /** Called for every event, in the order the broker delivered them. */
+    onEvent = () => { };
+    /** Called once a subscription is registered with the broker. */
+    onSubscribed = () => { };
+    /**
+     * Called for errors not tied to a request, such as a subscription ending,
+     * with the stream or cache they are about.
+     */
+    onError = () => { };
+    /** Called when the connection closes. */
+    onClose = () => { };
+    #socket;
+    #pending = new Map();
+    #nextId = 0;
+    constructor(socket) {
+        this.#socket = socket;
+        socket.addEventListener("message", (message) => this.#receive(String(message.data)));
+        socket.addEventListener("close", () => {
+            for (const pending of this.#pending.values()) {
+                pending.reject(new GatewayError("closed", "the gateway connection closed"));
+            }
+            this.#pending.clear();
+            this.onClose();
+        });
+    }
+    /**
+     * Open a connection to the gateway at `url`, a `ws:` or `wss:` URL, and
+     * join the scope in `join`, asking for `features`. The gateway answers with
+     * `hello`, or refuses with an error and closes.
+     */
+    static connect(url, join, features = []) {
+        return new Promise((resolve, reject) => {
+            const socket = new WebSocket(url);
+            socket.addEventListener("open", () => {
+                const client = new GatewayClient(socket);
+                client.#send({ ...join, type: "join", protocol: PROTOCOL, features });
+                resolve(client);
+            }, { once: true });
+            socket.addEventListener("error", () => reject(new Error(`cannot reach ${url}`)), {
+                once: true,
+            });
+        });
+    }
+    /**
+     * Relay `stream` from `from`: a log offset (the last one handled, plus one)
+     * or `"live"`. Replaces an earlier subscription to the same stream.
+     */
+    subscribe(stream, from) {
+        this.#send({ type: "subscribe", stream, from });
+    }
+    /**
+     * Publish one record. With `ack`, resolves once the broker has it, with its
+     * log offset when the broker acknowledged after writing. Without, resolves
+     * as soon as the request is sent.
+     */
+    publish(stream, payload, ack = true) {
+        const message = { type: "publish", stream, payload: toBase64(payload), ack };
+        if (!ack) {
+            this.#send({ ...message, id: this.#nextId++ });
+            return Promise.resolve(null);
+        }
+        return this.#request(message);
+    }
+    /** Add `delta` to `key` of `counter` and resolve with the new sum. */
+    counterAdd(counter, key, delta) {
+        return this.#request({ type: "counter_add", counter, key, delta });
+    }
+    /** Read `key` of `cache`: its value, or `null` when there is none. */
+    async cacheGet(cache, key) {
+        const payload = (await this.#request({ type: "cache_get", cache, key }));
+        return payload === null ? null : fromBase64(payload);
+    }
+    /** Write `key` of `cache`. It expires after the cache's TTL unless written again. */
+    cachePut(cache, key, payload) {
+        this.#send({ type: "cache_put", cache, key, payload: toBase64(payload) });
+    }
+    /** Delete `key` of `cache`. */
+    cacheDelete(cache, key) {
+        this.#send({ type: "cache_delete", cache, key });
+    }
+    /** Watch the entries of `cache`. Replaces an earlier watch of it. */
+    cacheWatch(cache) {
+        this.#send({ type: "cache_watch", cache });
+    }
+    /**
+     * Have the gateway read this connection's subscriptions no faster than a
+     * link of `bitsPerSecond` would carry them, or at full speed with `null`.
+     */
+    throttle(bitsPerSecond) {
+        this.#send({ type: "throttle", bits_per_second: bitsPerSecond });
+    }
+    close() {
+        this.#socket.close();
+    }
+    #request(message) {
+        const id = this.#nextId++;
+        this.#send({ ...message, id });
+        return new Promise((resolve, reject) => this.#pending.set(id, { resolve, reject }));
+    }
+    #send(message) {
+        this.#socket.send(JSON.stringify(message));
+    }
+    #receive(text) {
+        const message = JSON.parse(text);
+        switch (message.type) {
+            case "event":
+                this.onEvent({
+                    stream: message.stream,
+                    offset: message.offset,
+                    skippedBefore: message.skipped_before ?? 0,
+                    payload: fromBase64(message.payload),
+                });
+                break;
+            case "hello":
+                this.onHello({
+                    namespace: message.namespace,
+                    features: message.features,
+                    cacheTtlMs: message.cache_ttl_ms,
+                    missing: message.missing ?? [],
+                });
+                break;
+            case "subscribed":
+                this.onSubscribed(message.stream, message.start_offset, message.live_offset);
+                break;
+            case "cache_entries":
+                this.onCacheEntries(message.cache, message.entries.map(cacheEntry));
+                break;
+            case "cache_change":
+                this.onCacheChange(message.cache, cacheEntry(message));
+                break;
+            case "counter":
+                this.#take(message.id)?.resolve(message.value);
+                break;
+            case "ack":
+                this.#take(message.id)?.resolve(message.offset);
+                break;
+            case "cache_value":
+                this.#take(message.id)?.resolve(message.payload);
+                break;
+            case "error": {
+                const error = new GatewayError(message.code, message.message);
+                const pending = this.#take(message.id);
+                if (pending) {
+                    pending.reject(error);
+                }
+                else {
+                    this.onError(error, message.stream, message.cache);
+                }
+                break;
+            }
+        }
+    }
+    #take(id) {
+        if (id === undefined)
+            return undefined;
+        const pending = this.#pending.get(id);
+        this.#pending.delete(id);
+        return pending;
+    }
+}
+function cacheEntry(entry) {
+    return {
+        key: entry.key,
+        payload: entry.payload === null ? null : fromBase64(entry.payload),
+        expiresInMs: entry.expires_in_ms,
+    };
+}
+function toBase64(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function fromBase64(text) {
+    return Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "felix-gateway-client",
+  "version": "0.1.0",
+  "description": "The browser client for felix-gateway, and an in-memory fake of it for tests",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GetFelix/felix-gateway.git",
+    "directory": "packages/gateway-client"
+  },
+  "homepage": "https://github.com/GetFelix/felix-gateway#readme",
+  "bugs": "https://github.com/GetFelix/felix-gateway/issues",
+  "keywords": [
+    "felix",
+    "websocket",
+    "gateway",
+    "pubsub"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./fake": {
+      "types": "./dist/fake.d.ts",
+      "default": "./dist/fake.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "vitest": "^5.0.2"
+  }
+}