Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

21.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    NetChannel.ts
 * @brief   A typed message + request/response layer over a raw socket. The raw
 *          GameSocket / WeChatSocket only move string|ArrayBuffer frames; this
 *          is the single channel that gives them typed events (`on`/`send`) and
 *          RPC (`handle`/`request`) with a small JSON envelope. Transport-
 *          agnostic — anything that can `send` and surface `message` events works.
 */
import { decodeUtf8, encodeUtf8 } from '../util/utf8';
import type { IdempotencyStore } from './IdempotencyStore';
import { CONTROL_CHANNEL, decodeEnvelope, encodeEnvelope, type Envelope, type PayloadCodec, type WireFormat } from './wire';

export type { PayloadCodec, WireFormat } from './wire';

/** The codecs of one request: how its payload and its answer travel. */
export interface RequestCodec<Req = unknown, Res = unknown> {
    req: PayloadCodec<Req>;
    res: PayloadCodec<Res>;
}

/** The minimal socket surface NetChannel drives (GameSocket / WeChatSocket fit). */
export interface NetTransport {
    send(data: string | ArrayBuffer): void;
    /** Subscribe to incoming frames. Returns an unsubscribe function. */
    on(event: 'message', handler: (data: string | ArrayBuffer) => void): () => void;
}

/**
 * A transport that delivers every frame, once, in send order. {@link NetChannel}
 * needs no such promise; replication does — its client applies the inbox in
 * ARRIVAL order because that IS the authority's order. Declaring the marker is
 * a claim about the link, not a feature to switch on.
 */
export interface ReliableOrderedTransport extends NetTransport {
    readonly delivery: 'reliable-ordered';
}

export type MessageHandler<T = unknown> = (payload: T) => void;
export type RequestHandler<Req = unknown, Res = unknown> = (payload: Req) => Res | Promise<Res>;
export type BinaryHandler = (payload: Uint8Array) => void;

/** What the peer answers when it refuses a message for coming too fast. */
export const NET_RATE_LIMITED = 'rate limited';
/** What the peer answers a retry whose first attempt threw: the key is free, send it again. */
export const NET_ATTEMPT_FAILED = 'the first attempt failed, retry';

/**
 * Why a request did not return a value.
 *
 * - `timeout`: no answer in time; the peer may or may not have run it.
 * - `closed`: the channel went away with the request in flight; same doubt.
 * - `rate-limited` / `retry`: the peer ran nothing and says to send it again.
 * - `remote`: the peer's handler threw, or has none; its message is in `message`.
 */
export type NetRequestErrorCode = 'timeout' | 'closed' | 'rate-limited' | 'retry' | 'remote';

export class NetRequestError extends Error {
    constructor(message: string, readonly code: NetRequestErrorCode) {
        super(message);
        this.name = 'NetRequestError';
    }

    /** True when sending the same request again, with the same key, is safe. */
    get retryable(): boolean {
        return this.code !== 'remote';
    }
}

/** Why a channel dropped or refused something the peer sent. */
export type NetViolation = 'frame-size' | 'rate' | 'wire';

export interface NetHeartbeatOptions {
    /** How often to ping the peer. */
    intervalMs: number;
    /** Silence longer than this (no frame of any kind) means the peer is gone. */
    timeoutMs: number;
    /** Called once, when the peer has been silent for `timeoutMs`. */
    onDead: () => void;
}

export interface NetLimitOptions {
    /** Larger frames are dropped before they are parsed. Binary frames count too. */
    maxFrameBytes?: number;
    /** Sustained control messages (events and requests) per second. Binary frames are not limited. */
    messagesPerSecond?: number;
    /** Messages allowed at once before the sustained rate applies. Default: one second's worth. */
    burst?: number;
    /** Called for every dropped frame or refused message. */
    onViolation?: (kind: NetViolation) => void;
}

export interface NetChannelOptions {
    /** Default RPC timeout in ms (0 disables). Default 10000. */
    requestTimeoutMs?: number;
    /**
     * Answer a retried request from memory. Only requests that carry a key
     * (`idempotencyKey` on the sender) are looked up; the rest run as before.
     */
    idempotency?: IdempotencyStore;
    /** Prefixes every key so two players cannot collide on one. Usually the player id. */
    idempotencyScope?: string;
    /** Ping the peer and report when it goes silent. */
    heartbeat?: NetHeartbeatOptions;
    limits?: NetLimitOptions;
}

export interface RequestOptions {
    /** RPC timeout in ms (0 disables). */
    timeoutMs?: number;
    /**
     * Names this intent. A retry with the same key gets the first attempt's
     * answer instead of running the handler again. One key per intent (one
     * click), not per attempt.
     */
    idempotencyKey?: string;
    /** How the payload and the answer travel on the protobuf wire; the JSON wire carries their JSON form. */
    codec?: RequestCodec<any, any>;
}

interface WireEvent { k: 'event'; t: string; d: unknown; }
interface WireReq { k: 'req'; t: string; id: number; d: unknown; ik?: string; }
interface WireRes { k: 'res'; id: number; d?: unknown; e?: string; }
interface WirePing { k: 'ping'; n: number; }
interface WirePong { k: 'pong'; n: number; }
type Wire = WireEvent | WireReq | WireRes | WirePing | WirePong;

interface Pending {
    resolve: (value: unknown) => void;
    reject: (err: Error) => void;
    timer: ReturnType<typeof setTimeout> | null;
    codec: PayloadCodec | undefined;
}

/** A control message as it arrived, whichever wire it came on; `payload` reads the value with the codec the handler knows. */
interface Incoming {
    k: Wire['k'];
    t?: string;
    id?: number;
    ik?: string;
    e?: string;
    n?: number;
    hasPayload: boolean;
    payload(codec: PayloadCodec | undefined): unknown;
}

/**
 * Typed messaging over a {@link NetTransport}. Subscribes to the transport's
 * `message` events (it is the message router). Events are fire-and-forget;
 * requests await a matching response by id (or reject on timeout / remote
 * error).
 *
 * Two planes share the one transport: string frames carry the JSON control
 * envelope; binary frames carry a 1-byte channel id + payload for high-rate
 * data (replication snapshots claim channel 1). A binary frame with no
 * registered channel handler is dropped.
 */
export class NetChannel {
    private readonly transport: NetTransport;
    private readonly handlers = new Map<string, Set<MessageHandler>>();
    private readonly requestHandlers = new Map<string, { handler: RequestHandler; codec: RequestCodec<any, any> | undefined }>();
    private readonly eventCodecs = new Map<string, PayloadCodec>();
    private wire_: WireFormat = 'json';
    private jsonAllowed_ = true;
    private readonly binaryHandlers = new Map<number, BinaryHandler>();
    private readonly pending = new Map<number, Pending>();
    private readonly defaultTimeout: number;
    private readonly offMessage_: () => void;
    private readonly idempotency_: IdempotencyStore | undefined;
    private scope_: string;
    private readonly limits_: NetLimitOptions;
    private readonly bucketCapacity_: number;
    private heartbeatTimer_: ReturnType<typeof setInterval> | null = null;
    private bucket_: number;
    private bucketAt_ = Date.now();
    private lastHeard_ = Date.now();
    private nextId = 1;
    private nextPing_ = 1;

    constructor(transport: NetTransport, opts: NetChannelOptions = {}) {
        this.transport = transport;
        this.defaultTimeout = opts.requestTimeoutMs ?? 10000;
        this.idempotency_ = opts.idempotency;
        this.scope_ = opts.idempotencyScope ?? '';
        this.limits_ = opts.limits ?? {};
        const rate = this.limits_.messagesPerSecond ?? 0;
        this.bucketCapacity_ = rate > 0 ? Math.max(1, this.limits_.burst ?? rate) : 0;
        this.bucket_ = this.bucketCapacity_;
        this.offMessage_ = transport.on('message', (data) => this.handleIncoming_(data));
        if (opts.heartbeat) this.startHeartbeat_(opts.heartbeat);
    }

    /** Subscribe to a typed event. Returns an unsubscribe function. */
    on<T = unknown>(type: string, handler: MessageHandler<T>, codec?: PayloadCodec<T>): () => void {
        if (codec) this.eventCodecs.set(type, codec as PayloadCodec);
        let set = this.handlers.get(type);
        if (!set) { set = new Set(); this.handlers.set(type, set); }
        set.add(handler as MessageHandler);
        return () => {
            const s = this.handlers.get(type);
            if (s) { s.delete(handler as MessageHandler); if (s.size === 0) this.handlers.delete(type); }
        };
    }

    /** Fire-and-forget a typed event to the peer. */
    send<T = unknown>(type: string, payload: T, codec?: PayloadCodec<T>): void {
        this.send_({ k: 'event', t: type, d: payload }, codec as PayloadCodec | undefined);
    }

    /** The encoding this channel writes. It reads both. */
    get wire(): WireFormat {
        return this.wire_;
    }

    /**
     * Choose what this channel writes from now on. `acceptJson: false` makes it refuse JSON frames
     * from the peer (counted as a `wire` violation), for a server that has agreed on protobuf.
     */
    setWire(format: WireFormat, options: { acceptJson?: boolean } = {}): void {
        this.wire_ = format;
        this.jsonAllowed_ = options.acceptJson ?? true;
    }

    /** Register the single handler that answers `request(type, …)` from the peer.
     *  Returns an unregister function. */
    handle<Req = unknown, Res = unknown>(type: string, handler: RequestHandler<Req, Res>, codec?: RequestCodec<Req, Res>): () => void {
        const entry = { handler: handler as RequestHandler, codec: codec as RequestCodec<any, any> | undefined };
        this.requestHandlers.set(type, entry);
        return () => {
            if (this.requestHandlers.get(type) === entry) {
                this.requestHandlers.delete(type);
            }
        };
    }

    /**
     * Send a request and await the peer's response (rejects on timeout / remote
     * error). A number is the timeout in ms; an options object adds an
     * idempotency key.
     */
    request<Res = unknown, Req = unknown>(type: string, payload: Req, options?: number | RequestOptions): Promise<Res> {
        const id = this.nextId++;
        const opts: RequestOptions = typeof options === 'number' ? { timeoutMs: options } : options ?? {};
        const limit = opts.timeoutMs ?? this.defaultTimeout;
        return new Promise<Res>((resolve, reject) => {
            const timer = limit > 0
                ? setTimeout(() => {
                    this.pending.delete(id);
                    reject(new NetRequestError(`net request "${type}" timed out after ${limit}ms`, 'timeout'));
                }, limit)
                : null;
            this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer, codec: opts.codec?.res });
            const wire: WireReq = { k: 'req', t: type, id, d: payload };
            if (opts.idempotencyKey !== undefined) wire.ik = opts.idempotencyKey;
            this.send_(wire, opts.codec?.req);
        });
    }

    /** Register the single handler for a binary channel id (0-254; 255 carries control messages on the protobuf wire). Returns an
     *  unregister function. */
    onBinary(channel: number, handler: BinaryHandler): () => void {
        if (channel === CONTROL_CHANNEL) throw new RangeError(`[net] binary channel ${CONTROL_CHANNEL} is reserved for control messages`);
        this.binaryHandlers.set(channel, handler);
        return () => {
            if (this.binaryHandlers.get(channel) === handler) {
                this.binaryHandlers.delete(channel);
            }
        };
    }

    /** Fire-and-forget a binary payload on a channel id (0-254; 255 carries control messages on the protobuf wire). */
    sendBinary(channel: number, payload: Uint8Array): void {
        if (channel === CONTROL_CHANNEL) throw new RangeError(`[net] binary channel ${CONTROL_CHANNEL} is reserved for control messages`);
        const frame = new Uint8Array(1 + payload.byteLength);
        frame[0] = channel;
        frame.set(payload, 1);
        this.transport.send(frame.buffer);
    }

    /**
     * Scope later idempotency keys to this owner. A server knows the player only
     * after the hello, so the scope is set once the connection has authenticated.
     */
    setIdempotencyScope(scope: string): void {
        this.scope_ = scope;
    }

    /** Reject all in-flight requests and drop handlers (call on disconnect). */
    dispose(reason = 'net channel closed'): void {
        this.offMessage_();
        if (this.heartbeatTimer_) { clearInterval(this.heartbeatTimer_); this.heartbeatTimer_ = null; }
        for (const [, p] of this.pending) {
            if (p.timer) clearTimeout(p.timer);
            p.reject(new NetRequestError(reason, 'closed'));
        }
        this.pending.clear();
        this.handlers.clear();
        this.requestHandlers.clear();
        this.binaryHandlers.clear();
    }

    // -- internals ------------------------------------------------------------

    /** Write one control message in this channel's wire; `codec` is how its payload travels. */
    private send_(wire: Wire, codec?: PayloadCodec): void {
        const value = 'd' in wire ? wire.d : undefined;
        if (this.wire_ === 'json') {
            if (codec && value !== undefined) (wire as { d?: unknown }).d = codec.toJSON(value);
            this.transport.send(JSON.stringify(wire));
            return;
        }
        const e: Envelope = { kind: wire.k };
        if ('t' in wire) e.type = wire.t;
        if (wire.k === 'req' || wire.k === 'res') e.id = wire.id;
        if (wire.k === 'ping' || wire.k === 'pong') e.id = wire.n;
        if (wire.k === 'req' && wire.ik !== undefined) e.key = wire.ik;
        if (wire.k === 'res' && wire.e !== undefined) e.error = wire.e;
        if (value !== undefined) e.payload = codec ? codec.encode(value) : encodeUtf8(JSON.stringify(value));
        this.transport.send(encodeEnvelope(e));
    }

    private startHeartbeat_(beat: NetHeartbeatOptions): void {
        const timer = setInterval(() => {
            if (Date.now() - this.lastHeard_ > beat.timeoutMs) {
                clearInterval(timer);
                this.heartbeatTimer_ = null;
                beat.onDead();
                return;
            }
            this.send_({ k: 'ping', n: this.nextPing_++ });
        }, beat.intervalMs);
        // A heartbeat must not keep a server process alive by itself.
        (timer as { unref?: () => void }).unref?.();
        this.heartbeatTimer_ = timer;
    }

    /** Spend one message from the bucket; false when the peer is over its rate. */
    private admit_(): boolean {
        if (this.bucketCapacity_ === 0) return true;
        const now = Date.now();
        const refill = ((now - this.bucketAt_) / 1000) * (this.limits_.messagesPerSecond ?? 0);
        this.bucketAt_ = now;
        this.bucket_ = Math.min(this.bucketCapacity_, this.bucket_ + refill);
        if (this.bucket_ < 1) return false;
        this.bucket_ -= 1;
        return true;
    }

    private handleIncoming_(data: string | ArrayBuffer): void {
        this.lastHeard_ = Date.now();
        const max = this.limits_.maxFrameBytes;
        if (max !== undefined) {
            // A string's length counts UTF-16 units, not bytes; the bound only has
            // to keep a hostile frame from being parsed, not measure it exactly.
            const size = typeof data === 'string' ? data.length : data.byteLength;
            if (size > max) { this.limits_.onViolation?.('frame-size'); return; }
        }
        let msg: Incoming | null;
        if (typeof data !== 'string') {
            const view = new Uint8Array(data);
            if (view.byteLength === 0) return;
            if (view[0] !== CONTROL_CHANNEL) {
                this.binaryHandlers.get(view[0]!)?.(view.subarray(1));
                return;
            }
            msg = incomingFromEnvelope(decodeEnvelope(view.subarray(1)));
        } else {
            if (!this.jsonAllowed_) { this.limits_.onViolation?.('wire'); return; }
            msg = incomingFromJson(data);
        }
        if (!msg) return;
        switch (msg.k) {
            case 'ping': this.send_({ k: 'pong', n: msg.n ?? 0 }); break;
            case 'pong': break;
            case 'event':
                if (!this.admit_()) { this.limits_.onViolation?.('rate'); break; }
                this.dispatchEvent_(msg);
                break;
            case 'req':
                if (!this.admit_()) {
                    this.limits_.onViolation?.('rate');
                    this.send_({ k: 'res', id: msg.id ?? 0, e: NET_RATE_LIMITED });
                    break;
                }
                this.handleRequest_(msg);
                break;
            case 'res': this.resolvePending_(msg); break;
        }
    }

    private dispatchEvent_(msg: Incoming): void {
        const type = msg.t ?? '';
        const set = this.handlers.get(type);
        if (!set) return;
        let payload: unknown;
        try { payload = msg.payload(this.eventCodecs.get(type)); } catch { return; }
        for (const h of [...set]) h(payload);
    }

    private handleRequest_(msg: Incoming): void {
        const type = msg.t ?? '';
        const id = msg.id ?? 0;
        const entry = this.requestHandlers.get(type);
        if (!entry) {
            this.send_({ k: 'res', id, e: `no request handler for "${type}"` });
            return;
        }
        let payload: unknown;
        try { payload = msg.payload(entry.codec?.req); } catch (err) {
            this.send_({ k: 'res', id, e: `invalid ${type} request: ${errorText(err)}` });
            return;
        }
        const store = this.idempotency_;
        if (store && typeof msg.ik === 'string') {
            void this.handleIdempotent_(store, `${this.scope_}\u0000${type}\u0000${msg.ik}`, entry, id, payload);
            return;
        }
        Promise.resolve()
            .then(() => entry.handler(payload))
            .then(
                (result) => this.send_({ k: 'res', id, d: result }, entry.codec?.res),
                (err) => this.send_({ k: 'res', id, e: errorText(err) }),
            );
    }

    /**
     * Run a keyed request at most once to completion. A handler that returns has
     * its answer kept, so a retry replays it; one that throws frees the key and
     * the retry runs again — a business refusal belongs in the return value.
     * The answer is kept in its JSON form, which any store can hold and either wire can rebuild.
     */
    private async handleIdempotent_(
        store: IdempotencyStore, key: string, entry: { handler: RequestHandler; codec: RequestCodec<any, any> | undefined }, id: number, payload: unknown,
    ): Promise<void> {
        const res = entry.codec?.res;
        const replay = (stored: unknown): void => {
            let value: unknown = stored;
            if (res && stored !== undefined) {
                try { value = res.fromJSON(stored); } catch (err) { this.send_({ k: 'res', id, e: errorText(err) }); return; }
            }
            this.send_({ k: 'res', id, d: value }, res);
        };
        try {
            const begin = await store.begin(key);
            if (begin.state === 'done') {
                replay(begin.outcome.d);
                return;
            }
            if (begin.state === 'busy') {
                const outcome = await begin.outcome;
                if (outcome) replay(outcome.d);
                else this.send_({ k: 'res', id, e: NET_ATTEMPT_FAILED });
                return;
            }
            let result: unknown;
            try {
                result = await entry.handler(payload);
            } catch (err) {
                await store.abandon(key);
                this.send_({ k: 'res', id, e: errorText(err) });
                return;
            }
            await store.finish(key, { d: res && result !== undefined ? res.toJSON(result) : result });
            this.send_({ k: 'res', id, d: result }, res);
        } catch (err) {
            this.send_({ k: 'res', id, e: errorText(err) });
        }
    }

    private resolvePending_(msg: Incoming): void {
        const p = this.pending.get(msg.id ?? 0);
        if (!p) return;
        this.pending.delete(msg.id ?? 0);
        if (p.timer) clearTimeout(p.timer);
        if (msg.e !== undefined) { p.reject(new NetRequestError(msg.e, remoteCode(msg.e))); return; }
        try { p.resolve(msg.payload(p.codec)); } catch (err) { p.reject(new NetRequestError(`the reply could not be read: ${errorText(err)}`, 'remote')); }
    }
}

function incomingFromJson(data: string): Incoming | null {
    let msg: Wire;
    try { msg = JSON.parse(data) as Wire; } catch { return null; }
    if (!msg || typeof (msg as { k?: unknown }).k !== 'string') return null;
    const any = msg as unknown as Record<string, unknown>;
    return {
        k: msg.k,
        t: typeof any.t === 'string' ? any.t : undefined,
        id: typeof any.id === 'number' ? any.id : undefined,
        ik: typeof any.ik === 'string' ? any.ik : undefined,
        e: typeof any.e === 'string' ? any.e : undefined,
        n: typeof any.n === 'number' ? any.n : undefined,
        hasPayload: 'd' in any,
        payload: (codec) => (codec && any.d !== undefined ? codec.fromJSON(any.d) : any.d),
    };
}

function incomingFromEnvelope(e: Envelope | null): Incoming | null {
    if (!e) return null;
    const bytes = e.payload;
    return {
        k: e.kind, t: e.type, id: e.id, ik: e.key, e: e.error, n: e.id,
        hasPayload: bytes !== undefined,
        payload: (codec) => {
            if (bytes === undefined) return undefined;
            return codec ? codec.decode(bytes) : JSON.parse(decodeUtf8(bytes));
        },
    };
}

function remoteCode(message: string): NetRequestErrorCode {
    if (message === NET_RATE_LIMITED) return 'rate-limited';
    if (message === NET_ATTEMPT_FAILED) return 'retry';
    return 'remote';
}

function errorText(err: unknown): string {
    return err instanceof Error ? err.message : String(err);
}