@api.global/typedsocket 5.1.2 → 6.1.0

package/dist_ts/{typedsocket.classes.typedsocket.d.ts → classes.typedsocket.d.ts}

@@ -1,6 +1,53 @@
-import * as plugins from './typedsocket.plugins.js';
+import * as plugins from './plugins.js';
+import { NativeByteManager } from './classes.nativebytemanager.js';
+export { toClientWebSocketCloseCode } from './helpers.websocket.js';
+export { TYPEDSOCKET_MAX_RETAINED_CLIENT_TAG_MUTATIONS, TYPEDSOCKET_MAX_RETAINED_CLIENT_TAG_MUTATIONS_PER_NAME, } from './classes.clienttagreconciler.js';
+import type { TTypedSocketDiagnosticEvent } from './interfaces.diagnostics.js';
+import type { INativeByteAuthorizationAdapter, INativeByteCreateVirtualStreamOptions, TNativeByteCapabilityMode } from './interfaces.nativebytes.js';
+import type { ITypedSocketClientTagPolicy } from './classes.typedsockettagpolicymanager.js';
 export type TTypedSocketSide = 'server' | 'client';
 export type TConnectionStatus = 'new' | 'connecting' | 'connected' | 'disconnected' | 'reconnecting';
+export declare const TYPEDSOCKET_MAX_TEXT_FRAME_BYTES: number;
+export declare const TYPEDSOCKET_MAX_QUEUED_TEXT_FRAMES = 64;
+export declare const TYPEDSOCKET_MAX_QUEUED_TEXT_BYTES: number;
+export declare const TYPEDSOCKET_MAX_CONCURRENT_CLIENT_HANDLERS = 16;
+export declare const TYPEDSOCKET_MAX_RETAINED_CLIENT_CALLBACKS = 64;
+export declare const TYPEDSOCKET_MAX_PENDING_CLIENT_REQUESTS = 1024;
+export declare const TYPEDSOCKET_MAX_OUTBOUND_BUFFERED_BYTES: number;
+export declare const TYPEDSOCKET_MAX_METHOD_NAME_BYTES = 256;
+export declare const TYPEDSOCKET_MAX_CORRELATION_ID_BYTES = 256;
+export declare const TYPEDSOCKET_MAX_REQUEST_TIMEOUT_MS: number;
+export declare const TYPEDSOCKET_MAX_CONNECTION_RESTORE_TIMEOUT_MS = 10000;
+export declare const TYPEDSOCKET_MAX_RECONNECT_RETRIES = 100;
+export declare const TYPEDSOCKET_MAX_RECONNECT_BACKOFF_MS = 60000;
+export declare const TYPEDSOCKET_MAX_PENDING_SERVER_REQUESTS_PER_PEER = 64;
+export declare const TYPEDSOCKET_MAX_PENDING_SERVER_REQUESTS = 1024;
+export declare const TYPEDSOCKET_MAX_RETAINED_SERVER_INTERESTS_PER_PEER = 8;
+export declare const TYPEDSOCKET_MAX_RETAINED_SERVER_INTERESTS = 64;
+export interface ITypedSocketClientLimits {
+    readonly textFrameBytes: number;
+    readonly queuedTextFrames: number;
+    readonly queuedTextBytes: number;
+    readonly concurrentHandlers: number;
+    readonly retainedCallbacks: number;
+    readonly pendingRequests: number;
+    readonly outboundBufferedBytes: number;
+    readonly requestTimeoutMs: number;
+    readonly connectionRestoreTimeoutMs: number;
+}
+export interface ITypedSocketConnectionRestoreContext {
+    readonly connectionId: string;
+    readonly abortSignal: AbortSignal;
+    readonly deadline: number;
+    readonly createTypedRequest: TTypedSocketRestoreRequestFactory;
+}
+export type TTypedSocketRestoreRequestFactory = <T extends plugins.typedrequestInterfaces.ITypedRequest>(methodNameArg: T['method']) => plugins.typedrequest.TypedRequest<T>;
+export interface ITypedSocketRequestContext {
+    readonly localData: Readonly<Record<string, unknown>>;
+}
+export declare class TypedSocketConnectionRestoreDeniedError extends Error {
+    constructor(messageArg: string);
+}
 /**
  * Options for creating a TypedSocket client
  */
@@ -10,6 +57,16 @@ export interface ITypedSocketClientOptions {
     initialBackoffMs?: number;
     maxBackoffMs?: number;
     abortSignal?: AbortSignal;
+    nativeByteCapabilityMode?: TNativeByteCapabilityMode;
+    /** Limits may lower, but never raise, TypedSocket package ceilings. */
+    limits?: Partial<ITypedSocketClientLimits>;
+    /** Restores connection-bound authentication before desired tags are reconciled. */
+    restoreConnection?: (contextArg: ITypedSocketConnectionRestoreContext) => void | Promise<void>;
+}
+export interface ITypedSocketServerOptions {
+    nativeByteCapabilityMode?: TNativeByteCapabilityMode;
+    nativeByteAuthorizationAdapter?: INativeByteAuthorizationAdapter;
+    clientTagPolicy?: ITypedSocketClientTagPolicy;
 }
 /**
  * Lifecycle controls for one TypedRequest sent over a TypedSocket.
@@ -20,7 +77,7 @@ export interface ITypedSocketRequestOptions {
 }
 export type TTypedSocketServerRouterInput = plugins.typedrequest.TypedRouter | readonly plugins.typedrequest.TypedRouter[];
 /**
- * Wrapper for SmartServe's IWebSocketPeer to provide tag compatibility
+ * Typed connection wrapper for one exact SmartServe WebSocket peer.
  */
 export interface ISmartServeConnectionWrapper {
     peer: plugins.IWebSocketPeer;
@@ -60,7 +117,7 @@ export declare class TypedSocket {
      *
      * Call attachSmartServe() after constructing the SmartServe transport.
      */
-    static createServer(typedRouterOrRoutersArg: TTypedSocketServerRouterInput): TypedSocket;
+    static createServer(typedRouterOrRoutersArg: TTypedSocketServerRouterInput, optionsArg?: ITypedSocketServerOptions): TypedSocket;
     /**
      * Creates and attaches a TypedSocket server to an existing SmartServe
      * instance. Prefer createServer() plus attachSmartServe() when transport
@@ -75,24 +132,36 @@ export declare class TypedSocket {
      * const smartServe = new SmartServe({
      *   port: 3000,
      *   websocket: {
-     *     typedRouter,
-     *     onConnectionOpen: (peer) => peer.tags.add('client')
+     *     typedRouter
      *   }
      * });
      * await smartServe.start();
      * const typedSocket = TypedSocket.fromSmartServe(smartServe, typedRouter);
+     * // Authenticated server handlers assign protected connection metadata with:
+     * // typedSocket.setServerTag(peer, 'authenticated', { userId });
      * ```
      */
-    static fromSmartServe(smartServeArg: plugins.SmartServe, typedRouterArg: TTypedSocketServerRouterInput): TypedSocket;
+    static fromSmartServe(smartServeArg: plugins.SmartServe, typedRouterArg: TTypedSocketServerRouterInput, optionsArg?: ITypedSocketServerOptions): TypedSocket;
     /**
      * Registers built-in TypedHandlers for tag management
      */
-    private static registerTagHandlers;
+    private static registerProtocolHandlers;
     readonly side: TTypedSocketSide;
     readonly typedrouter: plugins.typedrequest.TypedRouter;
+    readonly nativeBytes: NativeByteManager;
+    readonly webSocketTransportOwner: plugins.IWebSocketTransportOwner;
     statusSubject: plugins.smartrx.rxjs.Subject<TConnectionStatus>;
+    /**
+     * Structured diagnostics: why a connection was closed, denied, or retried.
+     * Never completes, mirroring statusSubject; subscribers own unsubscription.
+     */
+    readonly diagnosticsSubject: plugins.smartrx.rxjs.Subject<TTypedSocketDiagnosticEvent>;
     private connectionStatus;
+    private reconnectExhaustedReported;
     private websocket;
+    private connectionGeneration;
+    private clientConnectionState;
+    private retainedClientCallbacks;
     private clientOptions;
     private serverUrl;
     private retryCount;
@@ -101,15 +170,22 @@ export declare class TypedSocket {
     private abortSignalListener?;
     private stopListeners;
     private pendingRequests;
-    private clientTags;
-    private clientTagMutations;
+    private readonly clientTagReconciler;
     private smartServeRef;
     private serverTypedRouters;
     private detachProtocolRouters;
+    private detachLegacyVirtualStreamPolicies;
     private serverStopping;
+    private serverLifecycleGeneration;
     private unsubscribeSmartServeConnectionClose;
+    private detachNativeStreamResolvers;
+    private detachResponseAuthorityGuards;
     private pendingServerRequests;
-    private pendingServerRequestIdsByPeerId;
+    private pendingServerRequestIdsByPeer;
+    private retainedServerInterests;
+    private retainedServerInterestsByPeer;
+    private readonly nativeByteAuthorizationAdapter;
+    private readonly tagPolicyManager;
     private constructor();
     /**
      * Attaches the SmartServe transport after server router composition.
@@ -119,14 +195,20 @@ export declare class TypedSocket {
      * Connects the client to the server using native WebSocket
      */
     private connect;
+    private negotiateClientCapabilities;
+    private restoreClientConnection;
     /**
      * Converts an HTTP(S) URL to a WebSocket URL
      */
     private toWebSocketUrl;
-    /**
-     * Handles incoming WebSocket messages
-     */
+    private toRedactedLogEndpoint;
+    private enqueueClientTextFrame;
+    private drainClientTextFrames;
+    private assertClientEnvelope;
     private handleMessage;
+    private sendClientTextEnvelope;
+    private isCurrentClientConnection;
+    private abortClientConnectionState;
     /**
      * Handles WebSocket disconnection
      */
@@ -153,12 +235,24 @@ export declare class TypedSocket {
      * Updates connection status and notifies subscribers
      */
     private updateStatus;
+    /**
+     * Diagnostics must never disturb transport code paths: subscriber errors
+     * are swallowed here.
+     */
+    private emitDiagnostic;
+    private emitConnectionClosedDiagnostic;
+    private emitTagDenialDiagnostic;
     /**
      * Sends a request to the server and waits for response (client-side)
      */
     private sendRequest;
     private normalizeRequestTimeout;
+    private requireClientOptions;
     private cancelPendingServerRequestsForPeer;
+    private retainServerInterestRegistration;
+    private authorizeIncomingServerResponse;
+    private isAttachedServerPeer;
+    private findServerPeerFromRequest;
     private sendServerRequest;
     /**
      * Creates a TypedRequest for the specified method.
@@ -166,6 +260,11 @@ export declare class TypedSocket {
      * On servers, sends to the specified target connection.
      */
     createTypedRequest<T extends plugins.typedrequestInterfaces.ITypedRequest>(methodName: T['method'], targetConnection?: ISmartServeConnectionWrapper, optionsArg?: ITypedSocketRequestOptions): plugins.typedrequest.TypedRequest<T>;
+    /**
+     * Creates an exact authorized native-byte receive facade for one server peer.
+     * TypedRequest carries its opaque descriptor when the facade enters a DTO.
+     */
+    createVirtualStream(optionsArg: INativeByteCreateVirtualStreamOptions): plugins.typedrequestInterfaces.INativeByteVirtualStreamReceiver<Uint8Array>;
     /**
      * Gets the current connection status
      */
@@ -174,6 +273,7 @@ export declare class TypedSocket {
      * Stops the TypedSocket client or cleans up server state
      */
     stop(): Promise<void>;
+    private releaseServerComposition;
     /**
      * Sets a tag on this client connection.
      * Tags are stored on the server and can be used for filtering.
@@ -190,6 +290,15 @@ export declare class TypedSocket {
      * @client-only
      */
     removeTag(name: string): Promise<void>;
+    /**
+     * Resolves the exact SmartServe transport peer for one incoming TypedRequest.
+     * Server handlers can pass their TypedTools argument without type assertions.
+     */
+    getServerConnectionForRequest(typedToolsArg: ITypedSocketRequestContext | undefined): ISmartServeConnectionWrapper;
+    /** Assigns a protected server-owned tag to one connection. */
+    setServerTag(connectionArg: ISmartServeConnectionWrapper | plugins.IWebSocketPeer, nameArg: string, payloadArg?: unknown): void;
+    /** Removes a server-owned tag while keeping its name protected from clients. */
+    removeServerTag(connectionArg: ISmartServeConnectionWrapper | plugins.IWebSocketPeer, nameArg: string): void;
     /**
      * Finds all connections matching the filter function.
      * @server-only