lemon-model 1.2.3 → 1.4.0

package/dist/socket/decorators.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTranslatedNetwork = exports.createReconnectingNetwork = void 0;
+const websocket_1 = require("./websocket");
+/**
+ * default watchdog cadence for readyState-based death detection.
+ * needed because an in-memory `Network.close()` notifies no one (see `socket/socket.ts`); only a
+ * real `OwnedWebSocketNetwork`/`BrowserWebSocketNetwork` close notifies via `onError` (see below),
+ * so the watchdog is a fallback and can stay slow — 1s keeps idle browser cost negligible.
+ */
+const DEFAULT_WATCHDOG_MS = 1000;
+/** create the L1 reconnect decorator: swaps the internal network on death, keeping instance identity for L3 */
+const createReconnectingNetwork = (factory, options) => new ReconnectingNetwork(factory, options);
+exports.createReconnectingNetwork = createReconnectingNetwork;
+/** `NetworkSupportable` decorator that transparently swaps its internal network on death */
+class ReconnectingNetwork {
+    constructor(factory, options) {
+        var _a, _b, _c, _d;
+        this.factory = factory;
+        this._generation = 0;
+        /** connected: 정상 감시 | connecting: 후보 open 대기 | backoff: 재시도 대기 | closed: 영구 종료 */
+        this.phase = 'connected';
+        this.retryCount = 0;
+        this.lastMessageAt = Date.now();
+        this.messageHandlers = new Set();
+        this.errorHandlers = new Set();
+        this.reconnectHandlers = new Set();
+        this.baseMs = (_a = options === null || options === void 0 ? void 0 : options.baseMs) !== null && _a !== void 0 ? _a : 1000;
+        this.factor = (_b = options === null || options === void 0 ? void 0 : options.factor) !== null && _b !== void 0 ? _b : 2;
+        this.maxMs = (_c = options === null || options === void 0 ? void 0 : options.maxMs) !== null && _c !== void 0 ? _c : 30000;
+        this.maxRetries = options === null || options === void 0 ? void 0 : options.maxRetries;
+        this.idleTimeoutMs = options === null || options === void 0 ? void 0 : options.idleTimeoutMs;
+        this.delayMs = this.baseMs;
+        this.current = factory();
+        this.attach(this.current);
+        this.watchdogTimer = setInterval(() => this.watch(), (_d = options === null || options === void 0 ? void 0 : options.watchdogMs) !== null && _d !== void 0 ? _d : DEFAULT_WATCHDOG_MS);
+    }
+    /** internal network generation (0 initially, +1 per reconnect) */
+    get generation() {
+        return this._generation;
+    }
+    get readyState() {
+        return this.phase === 'closed' ? 'closed' : this.current.readyState;
+    }
+    ready() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.current).ready) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : Promise.resolve();
+    }
+    onOpen(handler) {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.current).onOpen) === null || _b === void 0 ? void 0 : _b.call(_a, handler)) !== null && _c !== void 0 ? _c : (() => undefined);
+    }
+    /** while disconnected (mid-reconnect or permanently closed) this throws synchronously; no send queuing */
+    send(data) {
+        if (this.phase === 'closed')
+            throw new Error(`@network is closed - reconnectingNetwork.send`);
+        if (this.current.readyState !== 'open') {
+            throw new Error(`@network is not connected - reconnectingNetwork.send`);
+        }
+        this.current.send(data);
+    }
+    onMessage(handler) {
+        this.messageHandlers.add(handler);
+        return () => this.messageHandlers.delete(handler);
+    }
+    onError(handler) {
+        this.errorHandlers.add(handler);
+        return () => this.errorHandlers.delete(handler);
+    }
+    onReconnect(handler) {
+        this.reconnectHandlers.add(handler);
+        return () => this.reconnectHandlers.delete(handler);
+    }
+    /** options are remembered and re-applied to every reconnected generation */
+    configure(options) {
+        var _a, _b;
+        this.configured = Object.assign(Object.assign({}, this.configured), options);
+        (_b = (_a = this.current).configure) === null || _b === void 0 ? void 0 : _b.call(_a, this.configured);
+    }
+    /** stop reconnecting and close the internal network for good */
+    close(code, reason) {
+        if (this.phase === 'closed')
+            return;
+        this.phase = 'closed';
+        clearInterval(this.watchdogTimer);
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.detach();
+        this.current.close(code, reason);
+        this.messageHandlers.clear();
+        this.errorHandlers.clear();
+        this.reconnectHandlers.clear();
+    }
+    attach(network) {
+        this.unsubscribeMessage = network.onMessage(raw => {
+            this.lastMessageAt = Date.now();
+            for (const handler of [...this.messageHandlers])
+                handler(raw);
+        });
+        this.unsubscribeError = network.onError((error, context) => {
+            for (const handler of [...this.errorHandlers])
+                handler(error, Object.assign(Object.assign({}, context), { network: this }));
+            //! `OwnedWebSocketNetwork`/`BrowserWebSocketNetwork` notify a close via onError with this scope
+            //! (see `WEBSOCKET_NETWORK_SCOPE` in `socket/websocket.ts`). other onError calls (e.g. delivery
+            //! errors) are forwarded above but do not by themselves mean the network died.
+            if (context.scope === websocket_1.WEBSOCKET_NETWORK_SCOPE.ownedClose ||
+                context.scope === websocket_1.WEBSOCKET_NETWORK_SCOPE.browserClose) {
+                this.onInnerDeath();
+            }
+        });
+    }
+    detach() {
+        var _a, _b, _c;
+        (_a = this.unsubscribeMessage) === null || _a === void 0 ? void 0 : _a.call(this);
+        (_b = this.unsubscribeError) === null || _b === void 0 ? void 0 : _b.call(this);
+        (_c = this.unsubscribeCandidateOpen) === null || _c === void 0 ? void 0 : _c.call(this);
+    }
+    onInnerDeath() {
+        if (this.phase === 'connected')
+            this.beginBackoff();
+        else if (this.phase === 'connecting')
+            this.failAttempt(new Error(`@candidate network died before open - reconnectingNetwork`), 'reconnectingNetwork.connect');
+    }
+    /** watchdog fallback for networks that close without notifying (e.g. in-memory `Network.close()`) */
+    watch() {
+        const state = this.current.readyState;
+        if (this.phase === 'connected') {
+            if (state === 'closing' || state === 'closed')
+                return this.beginBackoff();
+            if (this.idleTimeoutMs && Date.now() - this.lastMessageAt > this.idleTimeoutMs)
+                this.beginBackoff();
+            return;
+        }
+        if (this.phase === 'connecting') {
+            if (state === 'open')
+                return this.settleReconnected(); // onOpen 없는 network용 fallback
+            if (state === 'closing' || state === 'closed')
+                this.onInnerDeath();
+        }
+    }
+    beginBackoff() {
+        this.detach();
+        this.phase = 'backoff';
+        this.reconnectTimer = setTimeout(() => this.attemptReconnect(), this.delayMs);
+    }
+    attemptReconnect() {
+        var _a, _b;
+        if (this.phase === 'closed')
+            return;
+        if (this.maxRetries != null && this.retryCount >= this.maxRetries) {
+            this.phase = 'closed';
+            clearInterval(this.watchdogTimer);
+            const error = new Error(`@network exceeded maxRetries[${this.maxRetries}] - reconnectingNetwork`);
+            for (const handler of [...this.errorHandlers])
+                handler(error, { scope: 'reconnectingNetwork.maxRetries', network: this });
+            this.messageHandlers.clear();
+            this.errorHandlers.clear();
+            this.reconnectHandlers.clear();
+            return;
+        }
+        let next;
+        try {
+            next = this.factory();
+        }
+        catch (e) {
+            this.failAttempt(e, 'reconnectingNetwork.factory');
+            return;
+        }
+        this.current = next;
+        this.attach(next);
+        if (this.configured)
+            (_a = next.configure) === null || _a === void 0 ? void 0 : _a.call(next, this.configured);
+        this.phase = 'connecting';
+        //! success is declared only once the candidate actually OPENS. a factory return alone is not a
+        //! connection (a real WebSocket constructs fine while the server is down), so resetting backoff
+        //! here would degrade to a constant-rate reconnect storm with an onReconnect/tick per attempt.
+        const state = next.readyState;
+        if (state === 'open')
+            return this.settleReconnected();
+        if (state === 'closing' || state === 'closed')
+            return this.onInnerDeath();
+        this.unsubscribeCandidateOpen = (_b = next.onOpen) === null || _b === void 0 ? void 0 : _b.call(next, () => {
+            if (this.phase === 'connecting' && this.current === next)
+                this.settleReconnected();
+        });
+        //! a candidate stuck in 'connecting' is bounded by the inner network's own connect timeout
+        //! (e.g. `OwnedWebSocketNetwork.connectTimeoutMs`), which actual-closes and lands in onInnerDeath.
+    }
+    /** a reconnect attempt failed (factory throw, or candidate died before open): keep growing the backoff */
+    failAttempt(error, scope) {
+        this.detach();
+        this.retryCount++;
+        this.delayMs = Math.min(this.delayMs * this.factor, this.maxMs);
+        for (const handler of [...this.errorHandlers])
+            handler(error, { scope, network: this });
+        this.phase = 'backoff';
+        this.reconnectTimer = setTimeout(() => this.attemptReconnect(), this.delayMs);
+    }
+    /** the candidate opened: only now reset the backoff/retry budget and notify onReconnect */
+    settleReconnected() {
+        var _a;
+        (_a = this.unsubscribeCandidateOpen) === null || _a === void 0 ? void 0 : _a.call(this);
+        this.unsubscribeCandidateOpen = undefined;
+        this.phase = 'connected';
+        this._generation++;
+        this.retryCount = 0;
+        this.delayMs = this.baseMs;
+        this.lastMessageAt = Date.now();
+        for (const handler of [...this.reconnectHandlers])
+            handler();
+    }
+}
+/** create the L1 wire translator decorator over a raw string, same slot as `createFilteredNetwork` */
+const createTranslatedNetwork = (source, translator) => new TranslatedNetwork(source, translator);
+exports.createTranslatedNetwork = createTranslatedNetwork;
+/** `NetworkSupportable` decorator that translates raw strings at the wire boundary */
+class TranslatedNetwork {
+    constructor(source, translator) {
+        this.source = source;
+        this.translator = translator;
+        this.errorHandlers = new Set();
+        this.unsubscribeSourceError = source.onError((error, context) => this.emitError(error, context));
+    }
+    get readyState() {
+        return this.source.readyState;
+    }
+    ready() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.source).ready) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : Promise.resolve();
+    }
+    onOpen(handler) {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.source).onOpen) === null || _b === void 0 ? void 0 : _b.call(_a, handler)) !== null && _c !== void 0 ? _c : (() => undefined);
+    }
+    send(data) {
+        this.source.send(this.translator.outbound ? this.translator.outbound(data) : data);
+    }
+    onMessage(handler) {
+        return this.source.onMessage(raw => {
+            let translated;
+            try {
+                translated = this.translator.inbound ? this.translator.inbound(raw) : raw;
+            }
+            catch (e) {
+                this.emitError(e, { scope: 'translatedNetwork.inbound' });
+                return;
+            }
+            if (translated === undefined)
+                return; // dropped by translator
+            handler(translated);
+        });
+    }
+    configure(options) {
+        var _a, _b;
+        (_b = (_a = this.source).configure) === null || _b === void 0 ? void 0 : _b.call(_a, options);
+    }
+    onError(handler) {
+        this.errorHandlers.add(handler);
+        return () => this.errorHandlers.delete(handler);
+    }
+    close(code, reason) {
+        this.unsubscribeSourceError();
+        this.errorHandlers.clear();
+        this.source.close(code, reason);
+    }
+    emitError(error, context) {
+        for (const handler of [...this.errorHandlers])
+            handler(error, Object.assign(Object.assign({}, context), { network: this }));
+    }
+}
+//# sourceMappingURL=decorators.js.map

package/dist/socket/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../src/socket/decorators.ts"],"names":[],"mappings":"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"}

package/dist/socket/index.d.ts

@@ -7,3 +7,5 @@
 export * from './types';
 export * from './transport';
 export * from './websocket';
+export * from './decorators';
+export * from './multi';

package/dist/socket/index.js

@@ -23,6 +23,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./transport"), exports);
 __exportStar(require("./websocket"), exports);
+__exportStar(require("./decorators"), exports);
+__exportStar(require("./multi"), exports);
 //! NOTE: the in-memory peer simulator (`./socket`) is intentionally NOT re-exported here.
 //! It is a test/dev utility — import it via the isolated `lemon-model/socket/testing` entry
 //! so production (esp. frontend) bundles do not pull in the simulator runtime.

package/dist/socket/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/socket/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;GAKG;AACH,0CAAwB;AACxB,8CAA4B;AAC5B,8CAA4B;AAE5B,0FAA0F;AAC1F,4FAA4F;AAC5F,+EAA+E"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/socket/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;GAKG;AACH,0CAAwB;AACxB,8CAA4B;AAC5B,8CAA4B;AAC5B,+CAA6B;AAC7B,0CAAwB;AAExB,0FAA0F;AAC1F,4FAA4F;AAC5F,+EAA+E"}

package/dist/socket/multi.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `socket/multi.ts`
+ * - `NetworkSupportable` composite that pairs N (>=2) networks — a main plus one or more backups.
+ * - `send`/`onMessage`/etc follow the main (index 0); `sendAll` is the only multi-transport extension call.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { NetworkSupportable, SocketErrorContext } from './types';
+/** `scope` values `MultiSocketNetwork` puts on `SocketErrorContext` */
+export declare const MULTI_NETWORK_SCOPE: {
+    readonly send: "network.multi.send";
+};
+/** `SocketErrorContext` extended with the origin socket index (0 = main); `types.ts` stays untouched */
+export interface MultiSocketErrorContext extends SocketErrorContext {
+    /** which socket the error originated from; 0 is the main socket */
+    index: number;
+}
+/** `NetworkSupportable` plus the multi-transport extension call */
+export interface MultiNetworkSupportable extends NetworkSupportable {
+    /** send the same raw string to every socket; never throws, failures surface via onError */
+    sendAll(data: string): void;
+}
+/** per-index network factory for the `{ count, networkFactory }` convenience overload */
+export interface MultiSocketNetworkFactory {
+    (index: number): NetworkSupportable;
+}
+/** create a `NetworkSupportable` composite over an array of networks (>=2) */
+export declare function createMultiSocketNetwork(networks: NetworkSupportable[]): MultiNetworkSupportable;
+/** create a `NetworkSupportable` composite by calling `networkFactory` `count` times (>=2) */
+export declare function createMultiSocketNetwork(options: {
+    count: number;
+    networkFactory: MultiSocketNetworkFactory;
+}): MultiNetworkSupportable;

package/dist/socket/multi.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMultiSocketNetwork = exports.MULTI_NETWORK_SCOPE = void 0;
+/** `scope` values `MultiSocketNetwork` puts on `SocketErrorContext` */
+exports.MULTI_NETWORK_SCOPE = {
+    send: 'network.multi.send',
+};
+/**
+ * `NetworkSupportable` composite over N (>=2) sockets.
+ *
+ * `send`/`readyState`/`ready`/`onOpen` delegate to the main socket (index 0) only (01 no-breakage).
+ * `sendAll` is the only member that touches every socket; failures never throw and are only
+ * observable via `onError`.
+ */
+class MultiSocketNetwork {
+    constructor(networks) {
+        this.networks = networks;
+        /** array (not Set) so a handler subscribed twice fires twice, matching the underlying delegation path */
+        this.errorHandlers = [];
+    }
+    get readyState() {
+        return this.networks[0].readyState;
+    }
+    ready() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.networks[0]).ready) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : Promise.resolve();
+    }
+    onOpen(handler) {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.networks[0]).onOpen) === null || _b === void 0 ? void 0 : _b.call(_a, handler)) !== null && _c !== void 0 ? _c : (() => undefined);
+    }
+    send(data) {
+        this.networks[0].send(data);
+    }
+    /** send to every socket independently; each failure is caught and re-emitted with index, never thrown */
+    sendAll(data) {
+        this.networks.forEach((network, index) => this.trySend(network, data, index));
+    }
+    onMessage(handler) {
+        const unsubscribes = this.networks.map(network => network.onMessage(handler));
+        return () => unsubscribes.forEach(unsubscribe => unsubscribe());
+    }
+    onError(handler) {
+        const unsubscribes = this.networks.map((network, index) => network.onError((error, context) => {
+            const tagged = Object.assign(Object.assign({}, context), { network: this, index });
+            handler(error, tagged);
+        }));
+        this.errorHandlers.push(handler);
+        return () => {
+            unsubscribes.forEach(unsubscribe => unsubscribe());
+            const index = this.errorHandlers.indexOf(handler);
+            if (index >= 0)
+                this.errorHandlers.splice(index, 1);
+        };
+    }
+    configure(options) {
+        this.networks.forEach(network => { var _a; return (_a = network.configure) === null || _a === void 0 ? void 0 : _a.call(network, options); });
+    }
+    /** close every socket independently (idempotent); onError subscriptions stay alive so post-close sendAll failures are still observable */
+    close(code, reason) {
+        this.networks.forEach(network => {
+            try {
+                network.close(code, reason);
+            }
+            catch (_a) {
+                // ignore; the other sockets must still be closed
+            }
+        });
+    }
+    trySend(network, data, index) {
+        try {
+            network.send(data);
+        }
+        catch (e) {
+            const context = { scope: exports.MULTI_NETWORK_SCOPE.send, network: this, index };
+            for (const handler of [...this.errorHandlers]) {
+                try {
+                    handler(e, context);
+                }
+                catch (_a) {
+                    // sendAll() must never throw; a throwing consumer handler cannot break the other sockets' send
+                }
+            }
+        }
+    }
+}
+function createMultiSocketNetwork(input) {
+    const count = Array.isArray(input) ? input.length : input.count;
+    if (count < 2) {
+        throw new Error(`@networks (2+) is required - createMultiSocketNetwork(${count})`);
+    }
+    const networks = Array.isArray(input)
+        ? input
+        : Array.from({ length: count }, (_, index) => input.networkFactory(index));
+    return new MultiSocketNetwork(networks);
+}
+exports.createMultiSocketNetwork = createMultiSocketNetwork;
+//# sourceMappingURL=multi.js.map

package/dist/socket/multi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi.js","sourceRoot":"","sources":["../../src/socket/multi.ts"],"names":[],"mappings":"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"}

package/dist/socket/socket.d.ts

@@ -5,7 +5,7 @@
  * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
  */
 import { NetworkMessageHandler, NetworkSupportable, PeerMessageHandler, PeerSupportable, PeerTargetOptions, SocketErrorHandler, SocketLogger, SocketNetworkOptions, SocketMessage, SocketReadyState, SocketUnsubscribe } from './types';
-import { JSONTransportOptions } from './transport';
+import { JSONTransportOptions, ReliableOptions } from './transport';
 /** options for simulated peers */
 export interface PeerOptions extends SocketNetworkOptions {
     /** peer id */
@@ -16,8 +16,21 @@ export interface PeerOptions extends SocketNetworkOptions {
     networkFactory?: PeerNetworkFactory;
     /** structured logger for peer lifecycle and delivery events */
     logger?: SocketLogger;
-    /** enable JSON transport chunking for peer message envelopes sent by this peer */
+    /**
+     * enable JSON transport chunking for peer message envelopes sent by this peer.
+     * for `jsonTransport.reliable`, both the sending and receiving peer must opt in — an
+     * asymmetric setup surfaces as `json.reliable.mismatch` on the non-reliable side.
+     * onError pattern: `error instanceof JSONTransportReliableError` gives access to `error.tid`.
+     */
     jsonTransport?: boolean | JSONTransportOptions;
+    /**
+     * shortcut for `jsonTransport: { reliable: true }` — the recommended entry point for reliable
+     * delivery, equivalent to setting `reliable` on `jsonTransport` directly. truthy activates JSON
+     * transport chunking even when `jsonTransport` is otherwise unset. an explicit `jsonTransport.reliable`
+     * takes precedence over this shortcut when both are set. both the sending and receiving peer must
+     * opt in — an asymmetric setup surfaces as `json.reliable.mismatch` on the non-reliable side.
+     */
+    reliable?: boolean | ReliableOptions;
 }
 /** network creation context independent from peer instances. */
 export interface PeerNetworkFactoryContext {
@@ -148,11 +161,16 @@ export declare class Peer<SendData = any, MessageData = any> implements PeerSupp
     /** close this peer */
     close(): void;
     private accept;
-    private attachClientReceiverTransport;
+    private attachClientTransport;
     private detachClient;
     private closeLink;
     private static reconnectPair;
-    private static attachReceiver;
+    /**
+     * reliable-on locals merge write+read networks into one instance (Peer 통합 절):
+     * writeNetwork carries send()+ack/nack/error, receiveNetwork(=readNetwork) carries the onMessage subscription.
+     * off (remoteTransportOptions only, or neither) keeps the existing receiver-only/raw paths untouched.
+     */
+    private static attachTransport;
     private createPeerNetwork;
     private static createNetworkPair;
     private publish;