@lemoncloud/chatic-sockets-lib 0.1.0 → 0.2.0

package/dist/client-socket-v2/connection-rotation-controller.d.ts

@@ -4,6 +4,8 @@ export interface ConnectionRotationControllerOptions {
     reconnect?: ReconnectController;
     maxLifetimeMs?: number;
     refreshBeforeMs?: number;
+    /** rotation delay에 적용할 ±jitter 비율 (0~1). 동시 부트스트랩 클라이언트군의 일제 rotate burst 분산용. 기본 0.1 (±10%) */
+    jitterRatio?: number;
     timerScheduler?: SharedTimerScheduler;
     timerKey?: string;
 }
@@ -11,6 +13,7 @@ export declare class ConnectionRotationController {
     private readonly options;
     private readonly maxLifetimeMs;
     private readonly refreshBeforeMs;
+    private readonly jitterRatio;
     private readonly timerScheduler?;
     private readonly timerKey;
     private readonly unsubs;
@@ -21,6 +24,7 @@ export declare class ConnectionRotationController {
     stop: () => void;
     destroy: () => void;
     private scheduleRotation;
+    private computeRotationDelay;
     private rotate;
     private clearTimer;
 }

package/dist/client-socket-v2/connection-rotation-controller.js

@@ -12,7 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectionRotationController = void 0;
 class ConnectionRotationController {
     constructor(options) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         this.options = options;
         this.unsubs = [];
         this.active = false;
@@ -33,13 +33,18 @@ class ConnectionRotationController {
             this.clearTimer();
             if (!this.active)
                 return;
-            const delayMs = Math.max(0, this.maxLifetimeMs - this.refreshBeforeMs);
+            const delayMs = this.computeRotationDelay();
             if (this.timerScheduler) {
                 this.timerScheduler.schedule(this.timerKey, delayMs, () => this.rotate());
                 return;
             }
             this.timer = setTimeout(() => void this.rotate(), delayMs);
         };
+        this.computeRotationDelay = () => {
+            const baseDelay = Math.max(0, this.maxLifetimeMs - this.refreshBeforeMs);
+            const jitter = this.jitterRatio > 0 ? baseDelay * (Math.random() * 2 - 1) * this.jitterRatio : 0;
+            return Math.max(0, baseDelay + jitter);
+        };
         this.rotate = () => __awaiter(this, void 0, void 0, function* () {
             if (!this.active)
                 return;
@@ -64,8 +69,9 @@ class ConnectionRotationController {
         };
         this.maxLifetimeMs = (_a = options.maxLifetimeMs) !== null && _a !== void 0 ? _a : 1000 * 60 * 110;
         this.refreshBeforeMs = (_b = options.refreshBeforeMs) !== null && _b !== void 0 ? _b : 1000 * 60 * 10;
+        this.jitterRatio = Math.max(0, Math.min(1, (_c = options.jitterRatio) !== null && _c !== void 0 ? _c : 0.1));
         this.timerScheduler = options.timerScheduler;
-        this.timerKey = (_c = options.timerKey) !== null && _c !== void 0 ? _c : 'rotation';
+        this.timerKey = (_d = options.timerKey) !== null && _d !== void 0 ? _d : 'rotation';
         this.unsubs.push(options.client.onState(event => {
             if (!this.active)
                 return;

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

@@ -11,8 +11,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createClientSocketV2 = void 0;
 const common_1 = require("./common");
+const keep_alive_loop_1 = require("./keep-alive-loop");
 const message_router_1 = require("./message-router");
 const pending_request_store_1 = require("./pending-request-store");
+const reconnect_controller_1 = require("./reconnect-controller");
 const shared_timer_scheduler_1 = require("./shared-timer-scheduler");
 const socket_transport_1 = require("./socket-transport");
 const buildMid = () => `m-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
@@ -28,16 +30,29 @@ const parseMessage = (raw) => {
     }
     return (0, common_1.onlyDefined)(Object.assign(Object.assign({}, message), { type: (0, common_1.cleanString)(message.type) }));
 };
+const normalizeRequestCap = (value, fallback) => {
+    const n = value !== null && value !== void 0 ? value : fallback;
+    return n > 0 ? n : Number.POSITIVE_INFINITY;
+};
+const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+const DEFAULT_MAX_INFLIGHT_REQUESTS = 32;
+const DEFAULT_MAX_PENDING_REQUESTS = 512;
 class ClientSocketV2Impl {
     constructor(options) {
-        var _a;
+        var _a, _b;
         this.options = options;
         this.router = new message_router_1.MessageRouter();
         this.stateListeners = new Set();
         this.errorListeners = new Set();
         this.messageListeners = new Set();
+        this.requestQueue = [];
+        this.inflightRequests = 0;
+        this.transportUnsubs = [];
         this._state = 'idle';
+        /** reconnect.stop이 client.disconnect를 호출하므로 재귀 진입 차단용 */
+        this.disconnecting = false;
         this.connect = () => __awaiter(this, void 0, void 0, function* () {
+            var _c;
             if (this._state === 'connected' || this._state === 'connecting')
                 return;
             this.setState('connecting');
@@ -49,10 +64,27 @@ class ClientSocketV2Impl {
                 this.setState('closed');
                 throw error;
             }
+            finally {
+                void ((_c = this.reconnect) === null || _c === void 0 ? void 0 : _c.start().catch(() => undefined));
+            }
         });
         this.disconnect = (code, reason) => __awaiter(this, void 0, void 0, function* () {
             if (this._state === 'closed' || this._state === 'idle')
                 return;
+            if (this.reconnect && !this.disconnecting) {
+                this.disconnecting = true;
+                try {
+                    yield this.reconnect.stop(code, reason);
+                }
+                catch (error) {
+                    this.emitError({ error, phase: 'disconnect' });
+                    throw error;
+                }
+                finally {
+                    this.disconnecting = false;
+                }
+                return;
+            }
             this.setState('closing');
             try {
                 yield this.transport.disconnect(code, reason);
@@ -73,26 +105,22 @@ class ClientSocketV2Impl {
             this.transport.send(JSON.stringify(message));
         };
         this.request = (type, data, options) => __awaiter(this, void 0, void 0, function* () {
-            var _b, _c, _d, _e, _f;
-            const mid = (_d = (_c = (_b = this.options).createMid) === null || _c === void 0 ? void 0 : _c.call(_b)) !== null && _d !== void 0 ? _d : buildMid();
+            var _d, _e, _f, _g;
+            const mid = (_f = (_e = (_d = this.options).createMid) === null || _e === void 0 ? void 0 : _e.call(_d)) !== null && _f !== void 0 ? _f : buildMid();
             const canonicalType = this.normalizeType(type);
-            const promise = this.pending.create(mid, {
-                timeoutMs: (_e = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _e !== void 0 ? _e : this.options.requestTimeoutMs,
-                onTimeout: requestMid => new Error(`408 REQUEST TIMEOUT - ${canonicalType}[${requestMid}]`),
-            });
-            try {
-                this.transport.send(JSON.stringify((0, common_1.onlyDefined)({
-                    type: canonicalType,
-                    data: (_f = data) !== null && _f !== void 0 ? _f : null,
-                    mid,
-                })));
-            }
-            catch (error) {
-                this.pending.reject(mid, error);
-                this.emitError({ error, phase: 'request' });
-                throw error;
+            const timeoutMs = (_g = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _g !== void 0 ? _g : this.requestTimeoutMs;
+            const totalAccepted = this.inflightRequests + this.requestQueue.length;
+            if (totalAccepted >= this.maxPendingRequests) {
+                throw new Error(`429 TOO MANY REQUESTS - pending queue full (${totalAccepted}/${this.maxPendingRequests})`);
             }
-            return promise;
+            return new Promise((resolve, reject) => {
+                const job = { mid, type: canonicalType, data, timeoutMs, resolve, reject };
+                if (this.inflightRequests < this.maxInflightRequests) {
+                    this.dispatchRequest(job);
+                    return;
+                }
+                this.requestQueue.push(job);
+            });
         });
         this.onState = (listener) => {
             this.stateListeners.add(listener);
@@ -107,6 +135,80 @@ class ClientSocketV2Impl {
             return () => this.messageListeners.delete(listener);
         };
         this.onType = (type, listener) => this.router.onType(type, listener);
+        this.destroy = () => {
+            var _a, _b;
+            /** 순서 invariant: reconnect.destroy → keepAlive.destroy → transport.disconnect (그 close 이벤트를 reconnect가 못 듣게 하기 위함) → 나머지 정리 */
+            (_a = this.reconnect) === null || _a === void 0 ? void 0 : _a.destroy();
+            (_b = this.keepAlive) === null || _b === void 0 ? void 0 : _b.destroy();
+            void this.transport.disconnect().catch(() => undefined);
+            this.transportUnsubs.splice(0).forEach(unsub => unsub());
+            this.rejectQueuedRequests(new Error(`499 CLIENT CLOSED REQUEST - client destroyed`));
+            this.pending.clear(new Error(`499 CLIENT CLOSED REQUEST - client destroyed`));
+            this.router.clear();
+            this.stateListeners.clear();
+            this.errorListeners.clear();
+            this.messageListeners.clear();
+            if (this.ownsTimerScheduler)
+                this.timerScheduler.cancelAll();
+            this._state = 'closed';
+        };
+        this.dispatchRequest = (job) => {
+            var _a;
+            this.inflightRequests += 1;
+            let released = false;
+            const release = () => {
+                if (released)
+                    return;
+                released = true;
+                this.inflightRequests = Math.max(0, this.inflightRequests - 1);
+                this.dispatchNextQueuedRequest();
+            };
+            let pending;
+            try {
+                pending = this.pending.create(job.mid, {
+                    timeoutMs: job.timeoutMs,
+                    onTimeout: (requestMid) => new Error(`408 REQUEST TIMEOUT - ${job.type}[${requestMid}]`),
+                });
+            }
+            catch (error) {
+                release();
+                job.reject(error);
+                this.emitError({ error, phase: 'request' });
+                return;
+            }
+            void pending.then(value => {
+                job.resolve(value);
+                release();
+            }, error => {
+                job.reject(error);
+                release();
+            });
+            try {
+                this.transport.send(JSON.stringify((0, common_1.onlyDefined)({
+                    type: job.type,
+                    data: (_a = job.data) !== null && _a !== void 0 ? _a : null,
+                    mid: job.mid,
+                })));
+            }
+            catch (error) {
+                this.pending.reject(job.mid, error);
+                release();
+                this.emitError({ error, phase: 'request' });
+            }
+        };
+        this.dispatchNextQueuedRequest = () => {
+            while (this.inflightRequests < this.maxInflightRequests && this.requestQueue.length) {
+                const next = this.requestQueue.shift();
+                if (!next)
+                    return;
+                this.dispatchRequest(next);
+            }
+        };
+        this.rejectQueuedRequests = (reason) => {
+            const queued = this.requestQueue.splice(0);
+            queued.forEach(job => job.reject(reason));
+            return queued.length;
+        };
         this.normalizeType = (type) => {
             var _a;
             const source = (0, common_1.cleanString)(type);
@@ -127,6 +229,12 @@ class ClientSocketV2Impl {
                 this.emitError({ error, phase: 'message', raw });
             }
         };
+        this.closeTransportInternal = (code, reason) => {
+            if (this._state === 'closed' || this._state === 'idle')
+                return;
+            this.setState('closing');
+            void this.transport.disconnect(code, reason).catch(() => undefined);
+        };
         this.setState = (next) => {
             const prev = this._state;
             this._state = next;
@@ -139,22 +247,37 @@ class ClientSocketV2Impl {
             this.errorListeners.forEach(listener => listener(event));
         };
         this.deviceDefaults = options.device ? (0, common_1.omitKeys)(options.device, ['tick']) : undefined;
-        this.timerScheduler = (_a = options.timerScheduler) !== null && _a !== void 0 ? _a : new shared_timer_scheduler_1.InMemorySharedTimerScheduler(options.now ? { now: options.now } : {});
+        this.requestTimeoutMs = (_a = options.requestTimeoutMs) !== null && _a !== void 0 ? _a : DEFAULT_REQUEST_TIMEOUT_MS;
+        this.maxInflightRequests = normalizeRequestCap(options.maxInflightRequests, DEFAULT_MAX_INFLIGHT_REQUESTS);
+        this.maxPendingRequests = normalizeRequestCap(options.maxPendingRequests, DEFAULT_MAX_PENDING_REQUESTS);
+        this.ownsTimerScheduler = !options.timerScheduler;
+        this.timerScheduler =
+            (_b = options.timerScheduler) !== null && _b !== void 0 ? _b : new shared_timer_scheduler_1.InMemorySharedTimerScheduler(options.now ? { now: options.now } : {});
         this.pending = new pending_request_store_1.PendingRequestStore({
             timerScheduler: this.timerScheduler,
             timerPrefix: 'pending:',
         });
         this.aliases = Object.assign({ ping: 'system.ping' }, (options.aliases || {}));
-        this.transport = new socket_transport_1.WebSocketTransport(options.url, options.protocols, options.socketFactory);
-        this.transport.on('open', () => this.setState('connected'));
-        this.transport.on('close', () => {
+        this.transport = new socket_transport_1.WebSocketTransport(options.url, options.protocols, options.socketFactory, {
+            connectTimeoutMs: options.connectTimeoutMs,
+        });
+        this.transportUnsubs.push(this.transport.on('open', () => this.setState('connected')));
+        this.transportUnsubs.push(this.transport.on('close', () => {
+            this.rejectQueuedRequests(new Error(`499 CLIENT CLOSED REQUEST - socket closed`));
             this.pending.clear(new Error(`499 CLIENT CLOSED REQUEST - socket closed`));
             this.setState('closed');
-        });
-        this.transport.on('error', event => {
+        }));
+        this.transportUnsubs.push(this.transport.on('error', event => {
             this.emitError({ error: event === null || event === void 0 ? void 0 : event.error, phase: 'transport' });
-        });
-        this.transport.on('message', event => this.handleRawMessage(event.data));
+        }));
+        this.transportUnsubs.push(this.transport.on('message', event => this.handleRawMessage(event.data)));
+        if (options.keepAlive !== false) {
+            this.keepAlive = new keep_alive_loop_1.KeepAliveLoop(Object.assign({ client: this, timerScheduler: this.timerScheduler, onPongTimeout: () => this.closeTransportInternal(1001, 'pong-timeout') }, (options.keepAlive || {})));
+            this.keepAlive.start();
+        }
+        if (options.reconnect !== false) {
+            this.reconnect = new reconnect_controller_1.AutoReconnectController(Object.assign({ client: this, timerScheduler: this.timerScheduler }, (options.reconnect || {})));
+        }
     }
     get state() {
         return this._state;

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

@@ -1,5 +1,6 @@
 import '../lib/sockets/packets';
 import '../lib/device/types';
+import '../lib/auth/types';
 export * from './types';
 export * from './common';
 export { createClientSocketV2 as default } from './create-client-socket-v2';
@@ -21,3 +22,4 @@ export * from './gateways/device-gateway';
 export * from '../lib/types';
 export * from '../lib/device/types';
 export * from '../lib/device/contracts';
+export * from '../lib/auth/types';

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

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = void 0;
 require("../lib/sockets/packets");
 require("../lib/device/types");
+require("../lib/auth/types");
 __exportStar(require("./types"), exports);
 __exportStar(require("./common"), exports);
 var create_client_socket_v2_1 = require("./create-client-socket-v2");
@@ -39,3 +40,4 @@ __exportStar(require("./gateways/device-gateway"), exports);
 __exportStar(require("../lib/types"), exports);
 __exportStar(require("../lib/device/types"), exports);
 __exportStar(require("../lib/device/contracts"), exports);
+__exportStar(require("../lib/auth/types"), exports);

package/dist/client-socket-v2/keep-alive-loop.d.ts

@@ -1,16 +1,13 @@
-import type { KeepAliveLoopControl, ClientSocketV2, SharedTimerScheduler } from './types';
-export interface KeepAliveLoopOptions {
+import type { KeepAliveLoopControl, ClientSocketV2, SharedTimerScheduler, KeepAliveLoopOptionsPartial } from './types';
+export interface KeepAliveLoopOptions extends KeepAliveLoopOptionsPartial {
     client: ClientSocketV2;
-    intervalMs?: number;
-    timeoutMs?: number;
-    buildPayload?: () => unknown;
-    mode?: 'send' | 'request';
     timerScheduler?: SharedTimerScheduler;
-    timerKey?: string;
 }
 export declare class KeepAliveLoop implements KeepAliveLoopControl {
     private readonly options;
     private readonly intervalMs;
+    private readonly pingTimeoutMs;
+    private readonly maxMissedPongs;
     private readonly mode;
     private readonly timerScheduler?;
     private readonly timerKey;
@@ -18,6 +15,7 @@ export declare class KeepAliveLoop implements KeepAliveLoopControl {
     private timer?;
     private running;
     private inFlight?;
+    private missedPongs;
     constructor(options: KeepAliveLoopOptions);
     start: () => void;
     stop: () => void;

package/dist/client-socket-v2/keep-alive-loop.js

@@ -10,12 +10,15 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeepAliveLoop = void 0;
+const DEFAULT_PING_TIMEOUT_MS = 10000;
+const DEFAULT_MAX_MISSED_PONGS = 2;
 class KeepAliveLoop {
     constructor(options) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e;
         this.options = options;
         this.unsubs = [];
         this.running = false;
+        this.missedPongs = 0;
         this.start = () => {
             this.running = true;
             if (this.options.client.state === 'connected')
@@ -55,12 +58,12 @@ class KeepAliveLoop {
             this.timer = undefined;
         };
         this.tick = () => __awaiter(this, void 0, void 0, function* () {
-            var _d, _e, _f;
+            var _f, _g, _h;
             if (!this.running || this.options.client.state !== 'connected')
                 return;
             if (this.inFlight)
                 return;
-            const payload = (_f = (_e = (_d = this.options).buildPayload) === null || _e === void 0 ? void 0 : _e.call(_d)) !== null && _f !== void 0 ? _f : null;
+            const payload = (_h = (_g = (_f = this.options).buildPayload) === null || _g === void 0 ? void 0 : _g.call(_f)) !== null && _h !== void 0 ? _h : null;
             this.inFlight = Promise.resolve()
                 .then(() => __awaiter(this, void 0, void 0, function* () {
                 if (this.mode === 'send') {
@@ -68,10 +71,24 @@ class KeepAliveLoop {
                     return;
                 }
                 yield this.options.client.request('system.ping', payload, {
-                    timeoutMs: this.options.timeoutMs,
+                    timeoutMs: this.pingTimeoutMs,
                 });
+                this.missedPongs = 0;
+            }))
+                .catch(() => __awaiter(this, void 0, void 0, function* () {
+                if (this.mode !== 'request')
+                    return;
+                this.missedPongs += 1;
+                if (this.missedPongs < this.maxMissedPongs)
+                    return;
+                this.missedPongs = 0;
+                if (this.options.onPongTimeout) {
+                    yield Promise.resolve(this.options.onPongTimeout()).catch(() => undefined);
+                }
+                else {
+                    yield this.options.client.disconnect(1001, 'pong-timeout').catch(() => undefined);
+                }
             }))
-                .catch(() => undefined)
                 .then(() => {
                 this.inFlight = undefined;
                 this.scheduleNext();
@@ -79,14 +96,20 @@ class KeepAliveLoop {
             yield this.inFlight;
         });
         this.intervalMs = (_a = options.intervalMs) !== null && _a !== void 0 ? _a : 30000;
-        this.mode = (_b = options.mode) !== null && _b !== void 0 ? _b : 'request';
+        this.pingTimeoutMs = (_b = options.timeoutMs) !== null && _b !== void 0 ? _b : DEFAULT_PING_TIMEOUT_MS;
+        this.maxMissedPongs = Math.max(1, (_c = options.maxMissedPongs) !== null && _c !== void 0 ? _c : DEFAULT_MAX_MISSED_PONGS);
+        this.mode = (_d = options.mode) !== null && _d !== void 0 ? _d : 'request';
         this.timerScheduler = options.timerScheduler;
-        this.timerKey = (_c = options.timerKey) !== null && _c !== void 0 ? _c : 'keepalive';
+        this.timerKey = (_e = options.timerKey) !== null && _e !== void 0 ? _e : 'keepalive';
         this.unsubs.push(options.client.onState(event => {
-            if (event.next === 'connected' && this.running)
+            if (event.next === 'connected' && this.running) {
+                this.missedPongs = 0;
                 this.scheduleNow();
-            if (event.next === 'closing' || event.next === 'closed')
+            }
+            if (event.next === 'closing' || event.next === 'closed') {
+                this.missedPongs = 0;
                 this.clearTimer();
+            }
         }));
     }
 }

package/dist/client-socket-v2/message-router.d.ts

@@ -5,5 +5,6 @@ export declare class MessageRouter {
     private readonly typeListeners;
     onAny: (listener: MessageListener) => (() => void);
     onType: <T = any>(type: string, listener: MessageListener<T>) => (() => void);
+    clear: () => void;
     route: (message: SocketMessage<any>) => number;
 }

package/dist/client-socket-v2/message-router.js

@@ -23,6 +23,10 @@ class MessageRouter {
                     this.typeListeners.delete(key);
             };
         };
+        this.clear = () => {
+            this.anyListeners.clear();
+            this.typeListeners.clear();
+        };
         this.route = (message) => {
             var _a;
             const key = `${(_a = message === null || message === void 0 ? void 0 : message.type) !== null && _a !== void 0 ? _a : ''}`.trim();

package/dist/client-socket-v2/reconnect-controller.d.ts

@@ -1,32 +1,48 @@
-import type { ClientSocketV2, ReconnectController, SharedTimerScheduler } from './types';
-export interface AutoReconnectControllerOptions {
+import type { AutoReconnectOptionsPartial, ClientSocketV2, ReconnectController, SharedTimerScheduler } from './types';
+export interface AutoReconnectGiveUpEvent {
+    attempts: number;
+}
+export interface AutoReconnectConnectFailedEvent {
+    attempt: number;
+    error: unknown;
+}
+export interface AutoReconnectControllerOptions extends AutoReconnectOptionsPartial {
     client: ClientSocketV2;
-    minDelayMs?: number;
-    maxDelayMs?: number;
-    factor?: number;
     timerScheduler?: SharedTimerScheduler;
-    timerKey?: string;
 }
 export declare class AutoReconnectController implements ReconnectController {
     private readonly options;
     private readonly minDelayMs;
     private readonly maxDelayMs;
     private readonly factor;
+    private readonly jitterRatio;
+    private readonly jitterMode;
+    private readonly maxAttempts;
+    private readonly minStableMs;
     private readonly timerScheduler?;
     private readonly timerKey;
+    private readonly now;
     private readonly unsubs;
+    private readonly giveUpListeners;
+    private readonly connectFailedListeners;
     private timer?;
     private active;
     private manualStop;
     private restarting;
     private attempt;
     private connecting?;
+    private stableSince?;
     constructor(options: AutoReconnectControllerOptions);
     start: () => Promise<void>;
-    stop: () => Promise<void>;
+    stop: (code?: number, reason?: string) => Promise<void>;
     restart: () => Promise<void>;
+    onGiveUp: (listener: (event: AutoReconnectGiveUpEvent) => void) => (() => void);
+    onConnectFailed: (listener: (event: AutoReconnectConnectFailedEvent) => void) => (() => void);
     destroy: () => void;
+    private applyStableReset;
+    private giveUp;
     private scheduleReconnect;
     private tryConnect;
     private clearTimer;
+    private computeBackoffDelay;
 }

package/dist/client-socket-v2/reconnect-controller.js

@@ -10,11 +10,14 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AutoReconnectController = void 0;
+const DEFAULT_MIN_STABLE_MS = 5000;
 class AutoReconnectController {
     constructor(options) {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         this.options = options;
         this.unsubs = [];
+        this.giveUpListeners = new Set();
+        this.connectFailedListeners = new Set();
         this.active = false;
         this.manualStop = false;
         this.restarting = false;
@@ -23,17 +26,20 @@ class AutoReconnectController {
             this.active = true;
             this.manualStop = false;
             this.clearTimer();
+            this.attempt = 0;
+            this.stableSince = this.options.client.state === 'connected' ? this.now() : undefined;
             if (this.options.client.state !== 'connected') {
                 yield this.tryConnect();
             }
         });
-        this.stop = () => __awaiter(this, void 0, void 0, function* () {
+        this.stop = (code, reason) => __awaiter(this, void 0, void 0, function* () {
             this.active = false;
             this.manualStop = true;
             this.restarting = false;
             this.clearTimer();
             this.attempt = 0;
-            yield this.options.client.disconnect();
+            this.stableSince = undefined;
+            yield this.options.client.disconnect(code, reason);
         });
         this.restart = () => __awaiter(this, void 0, void 0, function* () {
             if (!this.active) {
@@ -42,6 +48,7 @@ class AutoReconnectController {
             }
             this.clearTimer();
             this.attempt = 0;
+            this.stableSince = undefined;
             this.restarting = true;
             try {
                 if (this.options.client.state === 'connected' || this.options.client.state === 'connecting') {
@@ -53,16 +60,48 @@ class AutoReconnectController {
                 this.restarting = false;
             }
         });
+        this.onGiveUp = (listener) => {
+            this.giveUpListeners.add(listener);
+            return () => {
+                this.giveUpListeners.delete(listener);
+            };
+        };
+        this.onConnectFailed = (listener) => {
+            this.connectFailedListeners.add(listener);
+            return () => {
+                this.connectFailedListeners.delete(listener);
+            };
+        };
         this.destroy = () => {
             this.clearTimer();
+            this.giveUpListeners.clear();
+            this.connectFailedListeners.clear();
             this.unsubs.splice(0).forEach(unsub => unsub());
         };
+        this.applyStableReset = () => {
+            if (this.stableSince === undefined)
+                return;
+            const stableMs = this.now() - this.stableSince;
+            this.stableSince = undefined;
+            if (stableMs >= this.minStableMs)
+                this.attempt = 0;
+        };
+        this.giveUp = () => {
+            const attempts = this.attempt;
+            this.active = false;
+            this.clearTimer();
+            this.giveUpListeners.forEach(listener => listener({ attempts }));
+        };
         this.scheduleReconnect = () => {
             if (!this.active || this.manualStop)
                 return;
             if (this.timer || this.connecting)
                 return;
-            const delayMs = Math.min(this.minDelayMs * Math.pow(this.factor, this.attempt), this.maxDelayMs);
+            if (this.maxAttempts > 0 && this.attempt >= this.maxAttempts) {
+                this.giveUp();
+                return;
+            }
+            const delayMs = this.computeBackoffDelay(this.attempt);
             if (this.timerScheduler) {
                 this.timerScheduler.schedule(this.timerKey, delayMs, () => {
                     void this.tryConnect();
@@ -81,13 +120,21 @@ class AutoReconnectController {
                 return;
             if (this.connecting)
                 return this.connecting;
+            const attempt = this.attempt;
+            let failed = false;
+            let failedError;
             this.connecting = this.options.client
                 .connect()
-                .catch(() => {
-                this.scheduleReconnect();
+                .catch(error => {
+                failed = true;
+                failedError = error;
             })
                 .then(() => {
                 this.connecting = undefined;
+                if (failed) {
+                    this.connectFailedListeners.forEach(listener => listener({ attempt, error: failedError }));
+                    this.scheduleReconnect();
+                }
             });
             return this.connecting;
         });
@@ -98,20 +145,36 @@ class AutoReconnectController {
                 clearTimeout(this.timer);
             this.timer = undefined;
         };
+        this.computeBackoffDelay = (attempt) => {
+            const expDelay = Math.min(this.minDelayMs * Math.pow(this.factor, attempt), this.maxDelayMs);
+            if (this.jitterMode === 'full') {
+                /** AWS full jitter: random in [0, expDelay). minDelay floor 적용. */
+                const delay = Math.random() * expDelay;
+                return Math.max(this.minDelayMs, Math.min(this.maxDelayMs, delay));
+            }
+            const jitter = this.jitterRatio > 0 ? expDelay * (Math.random() * 2 - 1) * this.jitterRatio : 0;
+            return Math.max(this.minDelayMs, Math.min(this.maxDelayMs, expDelay + jitter));
+        };
         this.minDelayMs = (_a = options.minDelayMs) !== null && _a !== void 0 ? _a : 500;
-        this.maxDelayMs = (_b = options.maxDelayMs) !== null && _b !== void 0 ? _b : 10000;
+        this.maxDelayMs = (_b = options.maxDelayMs) !== null && _b !== void 0 ? _b : 30000;
         this.factor = (_c = options.factor) !== null && _c !== void 0 ? _c : 2;
+        this.jitterRatio = Math.max(0, Math.min(1, (_d = options.jitterRatio) !== null && _d !== void 0 ? _d : 0.3));
+        this.jitterMode = (_e = options.jitterMode) !== null && _e !== void 0 ? _e : 'equal';
+        this.maxAttempts = Math.max(0, (_f = options.maxAttempts) !== null && _f !== void 0 ? _f : 0);
+        this.minStableMs = Math.max(0, (_g = options.minStableMs) !== null && _g !== void 0 ? _g : DEFAULT_MIN_STABLE_MS);
         this.timerScheduler = options.timerScheduler;
-        this.timerKey = (_d = options.timerKey) !== null && _d !== void 0 ? _d : 'reconnect';
+        this.timerKey = (_h = options.timerKey) !== null && _h !== void 0 ? _h : 'reconnect';
+        this.now = (_j = options.now) !== null && _j !== void 0 ? _j : (() => Date.now());
         this.unsubs.push(options.client.onState(event => {
             if (!this.active)
                 return;
             if (event.next === 'connected') {
-                this.attempt = 0;
+                this.stableSince = this.now();
                 this.clearTimer();
                 this.connecting = undefined;
             }
             if (event.next === 'closed' && !this.manualStop && !this.restarting) {
+                this.applyStableReset();
                 this.scheduleReconnect();
             }
         }));

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

@@ -17,7 +17,7 @@ const shared_timer_scheduler_1 = require("./shared-timer-scheduler");
 const sync_scheduler_1 = require("./sync-scheduler");
 class SocketRuntime {
     constructor(options) {
-        var _a, _b, _c, _d, _e, _f, _g;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         this.options = options;
         this.start = () => __awaiter(this, void 0, void 0, function* () {
             this.keepAlive.start();
@@ -42,11 +42,21 @@ class SocketRuntime {
                 timerScheduler: this.timerScheduler,
             });
         this.keepAlive =
-            (_e = options.keepAlive) !== null && _e !== void 0 ? _e : new keep_alive_loop_1.KeepAliveLoop(Object.assign({ client: options.client, timerScheduler: this.timerScheduler }, (options.keepAliveOptions || {})));
+            (_e = options.keepAlive) !== null && _e !== void 0 ? _e : (options.keepAliveOptions
+                ? new keep_alive_loop_1.KeepAliveLoop(Object.assign({ client: options.client, timerScheduler: this.timerScheduler }, options.keepAliveOptions))
+                : (_f = options.client.keepAlive) !== null && _f !== void 0 ? _f : new keep_alive_loop_1.KeepAliveLoop({
+                    client: options.client,
+                    timerScheduler: this.timerScheduler,
+                }));
         this.reconnect =
-            (_f = options.reconnect) !== null && _f !== void 0 ? _f : new reconnect_controller_1.AutoReconnectController(Object.assign({ client: options.client, timerScheduler: this.timerScheduler }, (options.reconnectOptions || {})));
+            (_g = options.reconnect) !== null && _g !== void 0 ? _g : (options.reconnectOptions
+                ? new reconnect_controller_1.AutoReconnectController(Object.assign({ client: options.client, timerScheduler: this.timerScheduler }, options.reconnectOptions))
+                : (_h = options.client.reconnect) !== null && _h !== void 0 ? _h : new reconnect_controller_1.AutoReconnectController({
+                    client: options.client,
+                    timerScheduler: this.timerScheduler,
+                }));
         this.rotation =
-            (_g = options.rotation) !== null && _g !== void 0 ? _g : new connection_rotation_controller_1.ConnectionRotationController(Object.assign({ client: options.client, reconnect: this.reconnect, timerScheduler: this.timerScheduler }, (options.rotationOptions || {})));
+            (_j = options.rotation) !== null && _j !== void 0 ? _j : new connection_rotation_controller_1.ConnectionRotationController(Object.assign({ client: options.client, reconnect: this.reconnect, timerScheduler: this.timerScheduler }, (options.rotationOptions || {})));
     }
 }
 exports.SocketRuntime = SocketRuntime;

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

@@ -1,4 +1,8 @@
 import type { ClientSocketState, SocketFactoryContext, SocketLike, SocketTransport, SocketTransportEventMap } from './types';
+export interface WebSocketTransportOptions {
+    /** connect() open 이벤트 대기 timeout. 만료 시 socket close + Promise reject. 0이면 무한 대기. 기본 10000 */
+    connectTimeoutMs?: number;
+}
 export declare class WebSocketTransport implements SocketTransport {
     readonly url: string;
     readonly protocols?: string | string[];
@@ -7,7 +11,10 @@ export declare class WebSocketTransport implements SocketTransport {
     private socket?;
     private unbinders;
     private readonly listeners;
-    constructor(url: string, protocols?: string | string[], socketFactory?: (context: SocketFactoryContext) => SocketLike);
+    private readonly connectTimeoutMs;
+    private connecting?;
+    private cancelConnecting?;
+    constructor(url: string, protocols?: string | string[], socketFactory?: (context: SocketFactoryContext) => SocketLike, options?: WebSocketTransportOptions);
     get state(): ClientSocketState;
     on: <TType extends keyof SocketTransportEventMap>(type: TType, listener: (event: SocketTransportEventMap[TType]) => void) => (() => void);
     connect: () => Promise<void>;

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

@@ -25,8 +25,10 @@ const bindSocketListener = (socket, type, listener) => {
             socket[key] = prev !== null && prev !== void 0 ? prev : null;
     };
 };
+const DEFAULT_CONNECT_TIMEOUT_MS = 10000;
 class WebSocketTransport {
-    constructor(url, protocols, socketFactory = context => new globalThis.WebSocket(context.url, context.protocols)) {
+    constructor(url, protocols, socketFactory = context => new globalThis.WebSocket(context.url, context.protocols), options) {
+        var _a;
         this.url = url;
         this.protocols = protocols;
         this.socketFactory = socketFactory;
@@ -47,20 +49,40 @@ class WebSocketTransport {
         this.connect = () => __awaiter(this, void 0, void 0, function* () {
             if (this._state === 'connected')
                 return;
-            if (this._state === 'connecting')
-                return;
+            if (this.connecting)
+                return this.connecting;
             this.cleanupSocket();
             this._state = 'connecting';
             const socket = this.socketFactory({ url: this.url, protocols: this.protocols });
             this.socket = socket;
-            yield new Promise((resolve, reject) => {
+            this.connecting = new Promise((resolve, reject) => {
                 let connectSettled = false;
+                let timeoutTimer;
                 const settleConnect = (handler) => {
                     if (connectSettled)
                         return;
                     connectSettled = true;
+                    if (timeoutTimer)
+                        clearTimeout(timeoutTimer);
+                    this.connecting = undefined;
+                    this.cancelConnecting = undefined;
                     handler();
                 };
+                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 */
+                        }
+                    }, this.connectTimeoutMs);
+                }
                 this.unbinders = [
                     bindSocketListener(socket, 'open', () => {
                         this._state = 'connected';
@@ -89,8 +111,10 @@ class WebSocketTransport {
                     }),
                 ];
             });
+            return this.connecting;
         });
         this.disconnect = (code, reason) => __awaiter(this, void 0, void 0, function* () {
+            var _b;
             if (!this.socket) {
                 this._state = 'closed';
                 return;
@@ -98,6 +122,7 @@ class WebSocketTransport {
             this._state = 'closing';
             const socket = this.socket;
             socket.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._state = 'closed';
             this.emit('close', { code, reason, wasClean: true });
@@ -116,6 +141,7 @@ class WebSocketTransport {
             this.unbinders.splice(0).forEach(unbind => unbind());
             this.socket = undefined;
         };
+        this.connectTimeoutMs = (_a = options === null || options === void 0 ? void 0 : options.connectTimeoutMs) !== null && _a !== void 0 ? _a : DEFAULT_CONNECT_TIMEOUT_MS;
     }
     get state() {
         return this._state;

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

@@ -39,6 +39,26 @@ export interface SocketTransport {
     send(raw: string): void;
     on<TType extends keyof SocketTransportEventMap>(type: TType, listener: (event: SocketTransportEventMap[TType]) => void): () => void;
 }
+export interface KeepAliveLoopOptionsPartial {
+    intervalMs?: number;
+    timeoutMs?: number;
+    maxMissedPongs?: number;
+    buildPayload?: () => unknown;
+    mode?: 'send' | 'request';
+    timerKey?: string;
+    onPongTimeout?: () => void | Promise<void>;
+}
+export interface AutoReconnectOptionsPartial {
+    minDelayMs?: number;
+    maxDelayMs?: number;
+    factor?: number;
+    jitterRatio?: number;
+    jitterMode?: 'equal' | 'full';
+    maxAttempts?: number;
+    minStableMs?: number;
+    timerKey?: string;
+    now?: () => number;
+}
 export interface ClientSocketOptions {
     url: string;
     protocols?: string | string[];
@@ -47,6 +67,11 @@ export interface ClientSocketOptions {
     aliases?: Partial<Record<SocketPacketInputType | string, SocketPacketType>>;
     timerScheduler?: SharedTimerScheduler;
     requestTimeoutMs?: number;
+    connectTimeoutMs?: number;
+    maxInflightRequests?: number;
+    maxPendingRequests?: number;
+    keepAlive?: false | KeepAliveLoopOptionsPartial;
+    reconnect?: false | AutoReconnectOptionsPartial;
     createMid?: () => string;
     now?: () => number;
 }
@@ -67,6 +92,8 @@ export interface ClientSocketV2 {
     readonly state: ClientSocketState;
     readonly deviceDefaults?: DeviceBootstrapInput;
     readonly timerScheduler?: SharedTimerScheduler;
+    readonly keepAlive?: KeepAliveLoopControl;
+    readonly reconnect?: ReconnectController;
     connect(): Promise<void>;
     disconnect(code?: number, reason?: string): Promise<void>;
     send<TType extends SocketPacketInputType>(type: TType, data?: SocketPacketRequestData<ResolveSocketPacketType<TType>>): void;
@@ -78,6 +105,7 @@ export interface ClientSocketV2 {
     onError(listener: (event: ClientSocketErrorEvent) => void): () => void;
     onMessage(listener: (event: ClientSocketMessageEvent) => void): () => void;
     onType<T = any>(type: string, listener: (message: SocketMessage<T>) => void): () => void;
+    destroy(): void;
 }
 export declare type SyncTargetType = string;
 export interface SyncTargetDescriptor {
@@ -116,7 +144,7 @@ export interface KeepAliveLoopControl {
 }
 export interface ReconnectController {
     start(): Promise<void>;
-    stop(): Promise<void>;
+    stop(code?: number, reason?: string): Promise<void>;
     restart(): Promise<void>;
 }
 export interface SharedTimerScheduler {

package/dist/lib/auth/types.d.ts

@@ -0,0 +1,36 @@
+import type { InferSocketError, InferSocketRequest, InferSocketResponse, SocketErrorMessage, SocketRequestMessage, SocketResponseMessage } from '../types';
+export declare type AuthUpdateState = '' | 'pending' | 'validating' | 'authenticated' | 'failed' | 'disconnected';
+export interface AuthUpdateRequestData {
+    token?: string;
+    dryRun?: boolean;
+}
+export interface AuthUpdateMemberHead {
+    id?: string;
+    name?: string;
+}
+export interface AuthUpdateResponseData {
+    connId?: string;
+    deviceId?: string;
+    authId?: string;
+    memberId?: string;
+    state?: AuthUpdateState;
+    stateAt?: number;
+    error?: string;
+    member$?: AuthUpdateMemberHead;
+}
+declare module '../types' {
+    interface SocketPacketRegistry {
+        'auth.update': {
+            request: AuthUpdateRequestData;
+            response: AuthUpdateResponseData;
+            error: null;
+        };
+    }
+}
+export declare type AuthUpdateType = 'auth.update';
+export declare type AuthUpdateInput = InferSocketRequest<AuthUpdateType>;
+export declare type AuthUpdateResponse = InferSocketResponse<AuthUpdateType>;
+export declare type AuthUpdateErrorData = InferSocketError<AuthUpdateType>;
+export declare type AuthUpdateRequestMessage = SocketRequestMessage<AuthUpdateType>;
+export declare type AuthUpdateResponseMessage = SocketResponseMessage<AuthUpdateType>;
+export declare type AuthUpdateErrorMessage = SocketErrorMessage<AuthUpdateType>;

package/dist/lib/auth/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lemoncloud/chatic-sockets-lib",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Client websocket transport and sync runtime for chatic sockets v2",
   "main": "dist/client-socket-v2/index.js",
   "types": "dist/client-socket-v2/index.d.ts",