@lemoncloud/chatic-sockets-lib 0.2.0 → 0.3.0

package/dist/client-socket-v2/plans/profile-sync-plan.d.ts

@@ -0,0 +1,33 @@
+import type { ProfileView } from '@lemoncloud/chatic-socials-api';
+import type { SocketMessage } from '../../lib/types';
+import type { DomainSyncContext, DomainSyncPlan, SyncBackoffOptions, SyncFailureInfo, SyncTargetDescriptor } from '../types';
+export interface ProfileSyncTarget extends SyncTargetDescriptor {
+    type: 'profile';
+}
+export interface ProfileSyncSnapshot {
+    id?: string;
+    updatedAt?: number;
+    view?: ProfileView;
+}
+export interface ProfileSyncPlanOptions {
+    intervalMs?: number;
+    idleBackoff?: SyncBackoffOptions;
+    resetSnapshotOnConnected?: boolean;
+    onUpdate?: (target: ProfileSyncTarget, view: ProfileView, previous?: ProfileSyncSnapshot) => void;
+    onRemove?: (target: ProfileSyncTarget, previous?: ProfileSyncSnapshot) => void;
+}
+/** Single-profile sync: polls `profile.get`, applies on `updatedAt` change, re-pulls on a `profile.sync` nudge. */
+export declare class ProfileSyncPlan implements DomainSyncPlan<ProfileSyncTarget> {
+    private readonly options;
+    readonly domain = "profile";
+    readonly idleBackoff: SyncBackoffOptions;
+    constructor(options?: ProfileSyncPlanOptions);
+    supports: (target: SyncTargetDescriptor) => target is ProfileSyncTarget;
+    getKey: (target: ProfileSyncTarget) => string;
+    getIntervalMs: (target: ProfileSyncTarget) => number;
+    onConnected: (target: ProfileSyncTarget, ctx: DomainSyncContext) => void;
+    run: (target: ProfileSyncTarget, ctx: DomainSyncContext) => Promise<void>;
+    onTrigger: (target: ProfileSyncTarget, message: SocketMessage<any>, ctx: DomainSyncContext) => Promise<void>;
+    onStopped: (target: ProfileSyncTarget, _info: SyncFailureInfo, ctx: DomainSyncContext) => void;
+    updateLocalState: (target: ProfileSyncTarget, snapshot: unknown, ctx: DomainSyncContext) => void;
+}

package/dist/client-socket-v2/plans/profile-sync-plan.js

@@ -0,0 +1,67 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProfileSyncPlan = void 0;
+/** Single-profile sync: polls `profile.get`, applies on `updatedAt` change, re-pulls on a `profile.sync` nudge. */
+class ProfileSyncPlan {
+    constructor(options = {}) {
+        var _a;
+        this.options = options;
+        this.domain = 'profile';
+        this.supports = (target) => (target === null || target === void 0 ? void 0 : target.type) === 'profile';
+        this.getKey = (target) => { var _a; return `profile:${(_a = target === null || target === void 0 ? void 0 : target.id) !== null && _a !== void 0 ? _a : ''}`; };
+        this.getIntervalMs = (target) => { var _a, _b; return (_b = (_a = target.intervalMs) !== null && _a !== void 0 ? _a : this.options.intervalMs) !== null && _b !== void 0 ? _b : 2000; };
+        this.onConnected = (target, ctx) => {
+            if (this.options.resetSnapshotOnConnected === false)
+                return;
+            ctx.writeSnapshot(target, undefined);
+        };
+        this.run = (target, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _b, _c, _d, _e;
+            if (!target.id)
+                return;
+            const prev = ctx.readSnapshot(target);
+            const input = { id: target.id };
+            // profile.get 응답은 socials 소유(registry response=unknown) → ProfileView 로 단언
+            const view = (yield ctx.client.request('profile.get', input));
+            const nextUpdatedAt = typeof (view === null || view === void 0 ? void 0 : view.updatedAt) === 'number' ? view.updatedAt : undefined;
+            const prevUpdatedAt = typeof (prev === null || prev === void 0 ? void 0 : prev.updatedAt) === 'number' ? prev.updatedAt : undefined;
+            if (prevUpdatedAt === nextUpdatedAt && (prev === null || prev === void 0 ? void 0 : prev.view))
+                return;
+            const next = {
+                id: `${(_c = (_b = view === null || view === void 0 ? void 0 : view.id) !== null && _b !== void 0 ? _b : target.id) !== null && _c !== void 0 ? _c : ''}` || undefined,
+                updatedAt: nextUpdatedAt,
+                view,
+            };
+            ctx.writeSnapshot(target, next);
+            (_e = (_d = this.options).onUpdate) === null || _e === void 0 ? void 0 : _e.call(_d, target, view, prev);
+        });
+        this.onTrigger = (target, message, ctx) => __awaiter(this, void 0, void 0, function* () {
+            const data = ((message === null || message === void 0 ? void 0 : message.data) || {});
+            if (target.id && (data === null || data === void 0 ? void 0 : data.id) && target.id !== data.id)
+                return;
+            yield this.run(target, ctx);
+        });
+        this.onStopped = (target, _info, ctx) => {
+            var _a, _b;
+            const prev = ctx.readSnapshot(target);
+            (_b = (_a = this.options).onRemove) === null || _b === void 0 ? void 0 : _b.call(_a, target, prev);
+        };
+        this.updateLocalState = (target, snapshot, ctx) => {
+            var _a, _b;
+            const prev = ctx.readSnapshot(target);
+            const patch = (snapshot || {});
+            ctx.writeSnapshot(target, Object.assign(Object.assign(Object.assign({}, prev), patch), { view: (_a = patch.view) !== null && _a !== void 0 ? _a : prev === null || prev === void 0 ? void 0 : prev.view, updatedAt: (_b = patch.updatedAt) !== null && _b !== void 0 ? _b : prev === null || prev === void 0 ? void 0 : prev.updatedAt }));
+        };
+        this.idleBackoff = (_a = options.idleBackoff) !== null && _a !== void 0 ? _a : { factor: 2, maxMs: 60000 };
+    }
+}
+exports.ProfileSyncPlan = ProfileSyncPlan;

package/dist/client-socket-v2/socket-runtime.d.ts

@@ -1,7 +1,8 @@
 import { AutoReconnectController } from './reconnect-controller';
 import { ConnectionRotationController } from './connection-rotation-controller';
 import { KeepAliveLoop } from './keep-alive-loop';
-import type { ClientSocketRuntime, ClientSocketV2, DomainSyncPlan, KeepAliveLoopControl, ReconnectController, SharedTimerScheduler, SyncScheduler, SyncTargetDescriptor } from './types';
+import { type SyncBackoffOptions } from './sync-scheduler';
+import type { ClientSocketRuntime, ClientSocketV2, DomainSyncPlan, KeepAliveLoopControl, ReconnectController, SharedTimerScheduler, SyncFailurePolicy, SyncScheduler, SyncTargetDescriptor } from './types';
 export interface ClientSocketRuntimeOptions {
     client: ClientSocketV2;
     scheduler?: SyncScheduler;
@@ -10,6 +11,9 @@ export interface ClientSocketRuntimeOptions {
     rotation?: ConnectionRotationController;
     timerScheduler?: SharedTimerScheduler;
     syncPlans?: DomainSyncPlan<any>[];
+    syncBackoff?: SyncBackoffOptions;
+    syncIdleBackoff?: SyncBackoffOptions;
+    failurePolicy?: SyncFailurePolicy;
     keepAliveOptions?: Omit<ConstructorParameters<typeof KeepAliveLoop>[0], 'client' | 'timerScheduler'>;
     reconnectOptions?: Omit<ConstructorParameters<typeof AutoReconnectController>[0], 'client'>;
     rotationOptions?: Omit<ConstructorParameters<typeof ConnectionRotationController>[0], 'client' | 'reconnect'>;

package/dist/client-socket-v2/socket-runtime.js

@@ -34,12 +34,16 @@ class SocketRuntime {
         this.stopAllSync = () => this.scheduler.stopAll();
         this.listSyncTargets = () => this.scheduler.list();
         this.updateLocalSnapshot = (target, snapshot) => this.scheduler.updateLocalSnapshot(target, snapshot);
-        this.timerScheduler = (_b = (_a = options.timerScheduler) !== null && _a !== void 0 ? _a : options.client.timerScheduler) !== null && _b !== void 0 ? _b : new shared_timer_scheduler_1.InMemorySharedTimerScheduler();
+        this.timerScheduler =
+            (_b = (_a = options.timerScheduler) !== null && _a !== void 0 ? _a : options.client.timerScheduler) !== null && _b !== void 0 ? _b : new shared_timer_scheduler_1.InMemorySharedTimerScheduler();
         this.scheduler =
             (_c = options.scheduler) !== null && _c !== void 0 ? _c : new sync_scheduler_1.DomainSyncScheduler({
                 client: options.client,
                 plans: (_d = options.syncPlans) !== null && _d !== void 0 ? _d : [],
                 timerScheduler: this.timerScheduler,
+                backoff: options.syncBackoff,
+                idleBackoff: options.syncIdleBackoff,
+                failurePolicy: options.failurePolicy,
             });
         this.keepAlive =
             (_e = options.keepAlive) !== null && _e !== void 0 ? _e : (options.keepAliveOptions

package/dist/client-socket-v2/socket-transport.d.ts

@@ -3,13 +3,21 @@ export interface WebSocketTransportOptions {
     /** connect() open 이벤트 대기 timeout. 만료 시 socket close + Promise reject. 0이면 무한 대기. 기본 10000 */
     connectTimeoutMs?: number;
 }
+/**
+ * `SocketTransport` adapter over lemon-model's owned WebSocket network.
+ *
+ * Raw network concerns (socket creation, OPEN send guard, actual close, raw event mapping) are owned by
+ * `OwnedWebSocketNetwork`. This adapter only translates that single-shot network into chatic's reconnectable,
+ * code-carrying, 4-event / 5-state lifecycle. The connect timeout stays here because it belongs to the
+ * reconnect/backoff policy, not the raw transport.
+ */
 export declare class WebSocketTransport implements SocketTransport {
     readonly url: string;
     readonly protocols?: string | string[];
-    private readonly socketFactory;
+    private readonly socketFactory?;
     private _state;
-    private socket?;
-    private unbinders;
+    private network?;
+    private networkUnsubs;
     private readonly listeners;
     private readonly connectTimeoutMs;
     private connecting?;
@@ -21,5 +29,7 @@ export declare class WebSocketTransport implements SocketTransport {
     disconnect: (code?: number, reason?: string) => Promise<void>;
     send: (raw: string) => void;
     private emit;
-    private cleanupSocket;
+    /** bridge chatic's `SocketLike` factory to the owned network's `WebSocketClosable` factory */
+    private buildSocketFactory;
+    private cleanupNetwork;
 }

package/dist/client-socket-v2/socket-transport.js

@@ -10,30 +10,24 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebSocketTransport = void 0;
-const common_1 = require("./common");
-const OPEN_STATE = 1;
-const bindSocketListener = (socket, type, listener) => {
-    if (socket.addEventListener) {
-        socket.addEventListener(type, listener);
-        return () => { var _a; return (_a = socket.removeEventListener) === null || _a === void 0 ? void 0 : _a.call(socket, type, listener); };
-    }
-    const key = `on${type}`;
-    const prev = socket[key];
-    socket[key] = listener;
-    return () => {
-        if (socket[key] === listener)
-            socket[key] = prev !== null && prev !== void 0 ? prev : null;
-    };
-};
+const lemon_model_1 = require("lemon-model");
 const DEFAULT_CONNECT_TIMEOUT_MS = 10000;
+/**
+ * `SocketTransport` adapter over lemon-model's owned WebSocket network.
+ *
+ * Raw network concerns (socket creation, OPEN send guard, actual close, raw event mapping) are owned by
+ * `OwnedWebSocketNetwork`. This adapter only translates that single-shot network into chatic's reconnectable,
+ * code-carrying, 4-event / 5-state lifecycle. The connect timeout stays here because it belongs to the
+ * reconnect/backoff policy, not the raw transport.
+ */
 class WebSocketTransport {
-    constructor(url, protocols, socketFactory = context => new globalThis.WebSocket(context.url, context.protocols), options) {
+    constructor(url, protocols, socketFactory, options) {
         var _a;
         this.url = url;
         this.protocols = protocols;
         this.socketFactory = socketFactory;
         this._state = 'idle';
-        this.unbinders = [];
+        this.networkUnsubs = [];
         this.listeners = new Map();
         this.on = (type, listener) => {
             var _a;
@@ -51,17 +45,23 @@ class WebSocketTransport {
                 return;
             if (this.connecting)
                 return this.connecting;
-            this.cleanupSocket();
+            this.cleanupNetwork();
             this._state = 'connecting';
-            const socket = this.socketFactory({ url: this.url, protocols: this.protocols });
-            this.socket = socket;
+            const network = (0, lemon_model_1.createOwnedWebSocketNetwork)({
+                url: this.url,
+                protocols: this.protocols,
+                socketFactory: this.buildSocketFactory(),
+                connectTimeoutMs: 0, // connect timeout is owned here (reconnect policy), not by the network
+            });
+            this.network = network;
             this.connecting = new Promise((resolve, reject) => {
-                let connectSettled = false;
+                var _a;
+                let settled = false;
                 let timeoutTimer;
                 const settleConnect = (handler) => {
-                    if (connectSettled)
+                    if (settled)
                         return;
-                    connectSettled = true;
+                    settled = true;
                     if (timeoutTimer)
                         clearTimeout(timeoutTimer);
                     this.connecting = undefined;
@@ -71,75 +71,73 @@ class WebSocketTransport {
                 this.cancelConnecting = error => settleConnect(() => reject(error));
                 if (this.connectTimeoutMs > 0) {
                     timeoutTimer = setTimeout(() => {
-                        if (connectSettled)
-                            return;
                         const error = new Error(`408 CONNECT TIMEOUT - WebSocketTransport.connect() after ${this.connectTimeoutMs}ms`);
                         settleConnect(() => reject(error));
-                        try {
-                            socket.close(1000, 'connect-timeout');
-                        }
-                        catch (_a) {
-                            /** ignore — best-effort cleanup */
-                        }
+                        network.close(1000, 'connect-timeout');
                     }, this.connectTimeoutMs);
                 }
-                this.unbinders = [
-                    bindSocketListener(socket, 'open', () => {
-                        this._state = 'connected';
-                        this.emit('open', undefined);
-                        settleConnect(() => resolve());
-                    }),
-                    bindSocketListener(socket, 'close', event => {
-                        this._state = 'closed';
-                        this.emit('close', {
-                            code: event === null || event === void 0 ? void 0 : event.code,
-                            reason: event === null || event === void 0 ? void 0 : event.reason,
-                            wasClean: event === null || event === void 0 ? void 0 : event.wasClean,
-                        });
-                        settleConnect(() => resolve());
-                    }),
-                    bindSocketListener(socket, 'error', event => {
+                const unsubOpen = (_a = network.onOpen) === null || _a === void 0 ? void 0 : _a.call(network, () => {
+                    this._state = 'connected';
+                    this.emit('open', undefined);
+                    settleConnect(() => resolve());
+                });
+                this.networkUnsubs = [
+                    network.onMessage(raw => this.emit('message', { data: raw })),
+                    network.onError((event, context) => {
                         var _a;
-                        const error = (_a = event === null || event === void 0 ? void 0 : event.error) !== null && _a !== void 0 ? _a : new Error(`socket transport error`);
+                        if (context.scope === 'ownedWebSocket.close') {
+                            const close = event;
+                            this._state = 'closed';
+                            this.emit('close', { code: close === null || close === void 0 ? void 0 : close.code, reason: close === null || close === void 0 ? void 0 : close.reason, wasClean: close === null || close === void 0 ? void 0 : close.wasClean });
+                            settleConnect(() => resolve()); // close-before-open resolves connect (reconnect drives off state)
+                            return;
+                        }
+                        const error = (_a = event === null || event === void 0 ? void 0 : event.error) !== null && _a !== void 0 ? _a : (event instanceof Error ? event : new Error(`socket transport error`));
                         this.emit('error', { error });
                         if (this._state !== 'connected')
                             this._state = 'closed';
                         settleConnect(() => reject(error));
                     }),
-                    bindSocketListener(socket, 'message', event => {
-                        this.emit('message', { data: (0, common_1.asString)(event === null || event === void 0 ? void 0 : event.data, '') });
-                    }),
                 ];
+                if (unsubOpen)
+                    this.networkUnsubs.push(unsubOpen);
             });
             return this.connecting;
         });
         this.disconnect = (code, reason) => __awaiter(this, void 0, void 0, function* () {
             var _b;
-            if (!this.socket) {
+            if (!this.network) {
                 this._state = 'closed';
                 return;
             }
             this._state = 'closing';
-            const socket = this.socket;
-            socket.close(code, reason);
+            const network = this.network;
+            network.close(code, reason);
             (_b = this.cancelConnecting) === null || _b === void 0 ? void 0 : _b.call(this, new Error(`499 CLIENT CLOSED REQUEST - disconnect during connecting`));
-            this.cleanupSocket();
+            this.cleanupNetwork();
             this._state = 'closed';
             this.emit('close', { code, reason, wasClean: true });
         });
         this.send = (raw) => {
-            if (!this.socket || this.socket.readyState !== undefined && this.socket.readyState !== OPEN_STATE) {
+            if (!this.network || this.network.readyState !== 'open') {
                 throw new Error(`503 SOCKET NOT CONNECTED - WebSocketTransport.send()`);
             }
-            this.socket.send(raw);
+            this.network.send(raw);
         };
         this.emit = (type, event) => {
             var _a;
             (_a = this.listeners.get(type)) === null || _a === void 0 ? void 0 : _a.forEach(listener => listener(event));
         };
-        this.cleanupSocket = () => {
-            this.unbinders.splice(0).forEach(unbind => unbind());
-            this.socket = undefined;
+        /** bridge chatic's `SocketLike` factory to the owned network's `WebSocketClosable` factory */
+        this.buildSocketFactory = () => {
+            const factory = this.socketFactory;
+            if (!factory)
+                return undefined;
+            return context => factory({ url: context.url, protocols: context.protocols });
+        };
+        this.cleanupNetwork = () => {
+            this.networkUnsubs.splice(0).forEach(unsub => unsub());
+            this.network = undefined;
         };
         this.connectTimeoutMs = (_a = options === null || options === void 0 ? void 0 : options.connectTimeoutMs) !== null && _a !== void 0 ? _a : DEFAULT_CONNECT_TIMEOUT_MS;
     }

package/dist/client-socket-v2/sync-scheduler.d.ts

@@ -1,10 +1,16 @@
-import type { ClientSocketV2, DomainSyncPlan, SharedTimerScheduler, SyncScheduler, SyncTargetDescriptor } from './types';
+import type { ClientSocketV2, DomainSyncPlan, SharedTimerScheduler, SyncBackoffOptions, SyncFailurePolicy, SyncScheduler, SyncTargetDescriptor } from './types';
+export type { SyncBackoffOptions } from './types';
 export interface SyncSchedulerOptions {
     client: ClientSocketV2;
     plans: DomainSyncPlan<any>[];
     now?: () => number;
     timerScheduler?: SharedTimerScheduler;
     timerPrefix?: string;
+    backoff?: SyncBackoffOptions;
+    idleBackoff?: SyncBackoffOptions;
+    failurePolicy?: SyncFailurePolicy;
+    jitterRatio?: number;
+    random?: () => number;
 }
 export declare class DomainSyncScheduler implements SyncScheduler {
     private readonly options;
@@ -14,6 +20,11 @@ export declare class DomainSyncScheduler implements SyncScheduler {
     private readonly now;
     private readonly timerScheduler?;
     private readonly timerPrefix;
+    private readonly backoff;
+    private readonly idleBackoff?;
+    private readonly failurePolicy;
+    private readonly jitterRatio;
+    private readonly random;
     private readonly unsubs;
     constructor(options: SyncSchedulerOptions);
     start: (target: SyncTargetDescriptor) => void;
@@ -30,7 +41,10 @@ export declare class DomainSyncScheduler implements SyncScheduler {
     private clearTimer;
     private scheduleNow;
     private scheduleNext;
+    private computeInterval;
+    private jitter;
     private toTimerKey;
     private runEntry;
+    private handleRunFailure;
     private handleTrigger;
 }

package/dist/client-socket-v2/sync-scheduler.js

@@ -10,9 +10,16 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DomainSyncScheduler = void 0;
+const defaultClassify = (error) => {
+    var _a;
+    const msg = error instanceof Error ? error.message : `${error !== null && error !== void 0 ? error : ''}`;
+    const code = (_a = /^\s*(\d{3})\b/.exec(msg)) === null || _a === void 0 ? void 0 : _a[1];
+    return code === '403' || code === '404' ? 'gone' : 'transient';
+};
+const DEFAULT_IDLE_BACKOFF = { factor: 2, maxMs: 60000 };
 class DomainSyncScheduler {
     constructor(options) {
-        var _a, _b;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         this.options = options;
         this.targets = new Map();
         this.snapshots = new Map();
@@ -95,12 +102,17 @@ class DomainSyncScheduler {
                 const key = entry ? entry.plan.getKey(entry.target) : this.resolvePlan(target).getKey(target);
                 yield this.runEntry(key);
             }),
+            stop: target => this.stop(target),
         });
         this.handleConnected = () => __awaiter(this, void 0, void 0, function* () {
-            var _c, _d;
+            var _k, _l;
             const ctx = this.buildContext();
             for (const [key, entry] of this.targets.entries()) {
-                yield ((_d = (_c = entry.plan).onConnected) === null || _d === void 0 ? void 0 : _d.call(_c, entry.target, ctx));
+                // reconnect = fresh start
+                entry.failures = 0;
+                entry.goneStreak = 0;
+                entry.idleStreak = 0;
+                yield ((_l = (_k = entry.plan).onConnected) === null || _l === void 0 ? void 0 : _l.call(_k, entry.target, ctx));
                 this.scheduleNow(key);
             }
         });
@@ -133,13 +145,28 @@ class DomainSyncScheduler {
             this.clearTimer(entry);
             if (this.options.client.state !== 'connected')
                 return;
-            const intervalMs = (_d = (_a = entry.target.intervalMs) !== null && _a !== void 0 ? _a : (_c = (_b = entry.plan).getIntervalMs) === null || _c === void 0 ? void 0 : _c.call(_b, entry.target)) !== null && _d !== void 0 ? _d : 5000;
+            const baseMs = (_d = (_a = entry.target.intervalMs) !== null && _a !== void 0 ? _a : (_c = (_b = entry.plan).getIntervalMs) === null || _c === void 0 ? void 0 : _c.call(_b, entry.target)) !== null && _d !== void 0 ? _d : 5000;
+            const intervalMs = this.computeInterval(entry, baseMs);
             if (this.timerScheduler) {
                 this.timerScheduler.schedule(this.toTimerKey(key), intervalMs, () => this.runEntry(key));
                 return;
             }
             entry.timer = setTimeout(() => void this.runEntry(key), intervalMs);
         };
+        this.computeInterval = (entry, baseMs) => {
+            var _a, _b, _c, _d, _e, _f;
+            const failures = (_a = entry.failures) !== null && _a !== void 0 ? _a : 0;
+            if (failures > 0)
+                return this.jitter(Math.min(baseMs * Math.pow(this.backoff.factor, failures), this.backoff.maxMs));
+            const idle = (_c = (_b = entry.plan.idleBackoff) !== null && _b !== void 0 ? _b : this.idleBackoff) !== null && _c !== void 0 ? _c : DEFAULT_IDLE_BACKOFF;
+            const idleFactor = Math.max(1, (_d = idle === null || idle === void 0 ? void 0 : idle.factor) !== null && _d !== void 0 ? _d : 1);
+            const idleStreak = (_e = entry.idleStreak) !== null && _e !== void 0 ? _e : 0;
+            if (idleFactor > 1 && idleStreak > 0) {
+                return this.jitter(Math.min(baseMs * Math.pow(idleFactor, idleStreak), (_f = idle === null || idle === void 0 ? void 0 : idle.maxMs) !== null && _f !== void 0 ? _f : 60000));
+            }
+            return baseMs;
+        };
+        this.jitter = (ms) => this.jitterRatio > 0 ? Math.max(0, Math.round(ms * (1 + (this.random() * 2 - 1) * this.jitterRatio))) : ms;
         this.toTimerKey = (key) => `${this.timerPrefix}${key}`;
         this.runEntry = (key) => __awaiter(this, void 0, void 0, function* () {
             const entry = this.targets.get(key);
@@ -148,33 +175,83 @@ class DomainSyncScheduler {
             if (entry.inFlight)
                 return;
             const ctx = this.buildContext();
-            entry.inFlight = Promise.resolve(entry.plan.run(entry.target, ctx))
-                .catch(() => undefined)
-                .then(() => {
+            // no snapshot write during run = unchanged = idle
+            const before = this.snapshots.get(key);
+            entry.inFlight = Promise.resolve(entry.plan.run(entry.target, ctx)).then(() => {
+                var _a;
                 entry.inFlight = undefined;
+                entry.failures = 0;
+                entry.goneStreak = 0;
+                const changed = this.snapshots.get(key) !== before;
+                entry.idleStreak = changed ? 0 : ((_a = entry.idleStreak) !== null && _a !== void 0 ? _a : 0) + 1;
                 this.scheduleNext(key);
+            }, error => {
+                entry.inFlight = undefined;
+                this.handleRunFailure(key, error, ctx);
             });
             yield entry.inFlight;
         });
+        this.handleRunFailure = (key, error, ctx) => {
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+            const entry = this.targets.get(key);
+            if (!entry)
+                return;
+            const plan = (_a = entry.plan.failurePolicy) !== null && _a !== void 0 ? _a : {};
+            const sched = this.failurePolicy;
+            const classify = (_c = (_b = plan.classify) !== null && _b !== void 0 ? _b : sched.classify) !== null && _c !== void 0 ? _c : defaultClassify;
+            const stopAfter = (_e = (_d = plan.stopAfter) !== null && _d !== void 0 ? _d : sched.stopAfter) !== null && _e !== void 0 ? _e : 2;
+            const decide = (_g = (_f = plan.decide) !== null && _f !== void 0 ? _f : sched.decide) !== null && _g !== void 0 ? _g : ((info) => (info.kind === 'gone' && info.goneStreak >= stopAfter ? 'stop' : 'retry'));
+            const kind = classify(error, entry.target);
+            entry.failures = ((_h = entry.failures) !== null && _h !== void 0 ? _h : 0) + 1;
+            entry.goneStreak = kind === 'gone' ? ((_j = entry.goneStreak) !== null && _j !== void 0 ? _j : 0) + 1 : 0;
+            entry.idleStreak = 0;
+            const info = {
+                target: Object.assign({}, entry.target),
+                error,
+                kind,
+                failures: entry.failures,
+                goneStreak: entry.goneStreak,
+            };
+            const decision = decide(info);
+            if (decision === 'stop') {
+                (_l = (_k = entry.plan).onStopped) === null || _l === void 0 ? void 0 : _l.call(_k, entry.target, info, ctx);
+                this.stop(entry.target);
+                return;
+            }
+            if (decision === 'keep') {
+                entry.failures = 0;
+                entry.goneStreak = 0;
+            }
+            this.scheduleNext(key);
+        };
         this.handleTrigger = (message) => __awaiter(this, void 0, void 0, function* () {
-            var _e;
-            const type = `${(_e = message === null || message === void 0 ? void 0 : message.type) !== null && _e !== void 0 ? _e : ''}`;
+            var _m;
+            const type = `${(_m = message === null || message === void 0 ? void 0 : message.type) !== null && _m !== void 0 ? _m : ''}`;
             if (!type.endsWith('.sync'))
                 return;
-            const targets = [...this.targets.values()];
+            const entries = [...this.targets.entries()];
             const ctx = this.buildContext();
-            yield Promise.all(targets.map((entry) => __awaiter(this, void 0, void 0, function* () {
+            yield Promise.all(entries.map(([key, entry]) => __awaiter(this, void 0, void 0, function* () {
                 if (!entry.plan.onTrigger)
                     return;
                 if (!type.startsWith(`${entry.target.type}.`))
                     return;
-                yield entry.plan.onTrigger(entry.target, message, ctx);
+                // nudge resets idle backoff (best-effort)
+                entry.idleStreak = 0;
+                yield entry.plan.onTrigger(entry.target, message, ctx).catch(() => undefined);
+                if (!entry.inFlight)
+                    this.scheduleNext(key);
             })));
         });
         this.plans = [...(options.plans || [])];
         this.now = (_a = options.now) !== null && _a !== void 0 ? _a : (() => Date.now());
         this.timerScheduler = options.timerScheduler;
         this.timerPrefix = (_b = options.timerPrefix) !== null && _b !== void 0 ? _b : 'sync:';
+        this.backoff = { factor: Math.max(1, (_d = (_c = options.backoff) === null || _c === void 0 ? void 0 : _c.factor) !== null && _d !== void 0 ? _d : 2), maxMs: (_f = (_e = options.backoff) === null || _e === void 0 ? void 0 : _e.maxMs) !== null && _f !== void 0 ? _f : 30000 };
+        this.idleBackoff = options.idleBackoff;
+        this.failurePolicy = (_g = options.failurePolicy) !== null && _g !== void 0 ? _g : {};
+        this.jitterRatio = Math.max(0, (_h = options.jitterRatio) !== null && _h !== void 0 ? _h : 0.1);
+        this.random = (_j = options.random) !== null && _j !== void 0 ? _j : Math.random;
         this.unsubs.push(options.client.onState(event => {
             if (event.next === 'connected')
                 void this.handleConnected();

package/dist/client-socket-v2/types.d.ts

@@ -2,20 +2,27 @@ import type { ResolveSocketPacketType, SocketMessage, SocketPacketInputType, Soc
 import type { DeviceBootstrapInput } from '../lib/device/types';
 export declare type ClientSocketState = 'idle' | 'connecting' | 'connected' | 'closing' | 'closed';
 export interface SocketLike {
-    readonly readyState?: number;
+    readonly readyState: number;
     send(data: string): void;
     close(code?: number, reason?: string): void;
-    addEventListener?(type: 'open' | 'close' | 'error' | 'message', listener: (event?: any) => void): void;
-    removeEventListener?(type: 'open' | 'close' | 'error' | 'message', listener: (event?: any) => void): void;
-    onopen?: ((event?: any) => void) | null;
-    onclose?: ((event?: any) => void) | null;
-    onerror?: ((event?: any) => void) | null;
-    onmessage?: ((event?: any) => void) | null;
+    addEventListener(type: 'open' | 'close' | 'error' | 'message', listener: (event?: any) => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: 'open' | 'close' | 'error' | 'message', listener: (event?: any) => void): void;
 }
 export interface SocketFactoryContext {
     url: string;
     protocols?: string | string[];
 }
+/** context for the pre-parse raw ownership filter */
+export interface ClientSocketInboundFilterContext {
+    raw: string;
+}
+/** context for the post-parse message ownership filter */
+export interface ClientSocketMessageFilterContext<T = any> {
+    raw: string;
+    message: SocketMessage<T>;
+}
 export interface SocketTransportEventMap {
     open: void;
     close: {
@@ -64,6 +71,8 @@ export interface ClientSocketOptions {
     protocols?: string | string[];
     device?: DeviceBootstrapInput | null;
     socketFactory?: (context: SocketFactoryContext) => SocketLike;
+    shouldHandleRaw?: (context: ClientSocketInboundFilterContext) => boolean;
+    shouldHandleMessage?: (context: ClientSocketMessageFilterContext) => boolean;
     aliases?: Partial<Record<SocketPacketInputType | string, SocketPacketType>>;
     timerScheduler?: SharedTimerScheduler;
     requestTimeoutMs?: number;
@@ -114,21 +123,43 @@ export interface SyncTargetDescriptor {
     intervalMs?: number;
     meta?: Record<string, unknown>;
 }
+export declare type SyncFailureKind = 'gone' | 'transient';
+export declare type SyncFailureDecision = 'stop' | 'keep' | 'retry';
+export interface SyncFailureInfo {
+    target: SyncTargetDescriptor;
+    error: unknown;
+    kind: SyncFailureKind;
+    failures: number;
+    goneStreak: number;
+}
+export interface SyncFailurePolicy {
+    classify?(error: unknown, target: SyncTargetDescriptor): SyncFailureKind;
+    decide?(info: SyncFailureInfo): SyncFailureDecision;
+    stopAfter?: number;
+}
+export interface SyncBackoffOptions {
+    factor?: number;
+    maxMs?: number;
+}
 export interface DomainSyncContext {
     client: ClientSocketV2;
     now(): number;
     readSnapshot<T = unknown>(target: SyncTargetDescriptor): T | undefined;
     writeSnapshot<T = unknown>(target: SyncTargetDescriptor, snapshot: T | undefined): void;
     requestResync(target: SyncTargetDescriptor): Promise<void>;
+    stop(target: SyncTargetDescriptor): void;
 }
 export interface DomainSyncPlan<TTarget extends SyncTargetDescriptor = SyncTargetDescriptor> {
     readonly domain: string;
+    readonly failurePolicy?: SyncFailurePolicy;
+    readonly idleBackoff?: SyncBackoffOptions;
     supports(target: SyncTargetDescriptor): target is TTarget;
     getKey(target: TTarget): string;
     getIntervalMs?(target: TTarget): number;
     onConnected?(target: TTarget, ctx: DomainSyncContext): Promise<void> | void;
     run(target: TTarget, ctx: DomainSyncContext): Promise<void>;
     onTrigger?(target: TTarget, message: SocketMessage<any>, ctx: DomainSyncContext): Promise<void>;
+    onStopped?(target: TTarget, info: SyncFailureInfo, ctx: DomainSyncContext): void;
     updateLocalState?(target: TTarget, snapshot: unknown, ctx: DomainSyncContext): void;
 }
 export interface SyncScheduler {