@api.global/typedsocket 5.1.2 → 6.0.0

package/dist_ts/nativebytes.types.d.ts

@@ -0,0 +1,187 @@
+import type * as plugins from './typedsocket.plugins.js';
+import type { NATIVE_BYTE_FRAME_TYPES, NATIVE_BYTE_PROTOCOL } from './nativebytes.constants.js';
+export type TNativeByteCapabilityMode = 'disabled' | 'optional' | 'required';
+export type TNativeByteRole = 'producer' | 'consumer';
+export type TNativeByteAuthorityOperation = 'open' | 'data' | 'fin' | 'confirm' | 'reject';
+export interface INativeByteDescriptorTransport {
+    readonly [key: string]: plugins.typedrequestInterfaces.TNativeStreamTransportDescriptorPayload;
+    readonly protocolMajor: 6;
+    readonly role: 'producer';
+    readonly streamId: string;
+    readonly capability: string;
+    readonly byteLength: number;
+    readonly sha256: string;
+    readonly contentType: string;
+    readonly expiresAt: number;
+    readonly initialWindowBytes: number;
+}
+export interface INativeByteDescriptor extends plugins.typedrequestInterfaces.INativeByteStreamDescriptor {
+    readonly protocol: typeof NATIVE_BYTE_PROTOCOL;
+    readonly transport: INativeByteDescriptorTransport;
+}
+export interface INativeByteReceipt {
+    readonly streamId: string;
+    readonly byteLength: number;
+    readonly sha256: string;
+    readonly contentType: string;
+    readonly durable: true;
+}
+export interface INativeByteAuthorizationBinding extends INativeByteAuthorityRevisions {
+    readonly principalId: string;
+    readonly revalidate: TNativeByteRevalidate;
+}
+export interface INativeByteAuthorizationContext {
+    readonly target: plugins.IWebSocketPeer;
+    readonly manifest: plugins.typedrequestInterfaces.INativeByteStreamManifest;
+}
+export interface INativeByteAuthorizationAdapter {
+    bind(authorizationArg: unknown, contextArg: Readonly<INativeByteAuthorizationContext>): INativeByteAuthorizationBinding;
+}
+export interface INativeByteCreateVirtualStreamOptions {
+    readonly protocol: 'native-byte-v1';
+    readonly direction: 'receive';
+    readonly target: {
+        readonly peer: plugins.IWebSocketPeer;
+    } | plugins.IWebSocketPeer;
+    readonly byteLength: number;
+    readonly sha256: string;
+    readonly contentType: string;
+    readonly authorization: unknown;
+    readonly initialWindowBytes?: number;
+}
+export interface INativeByteAuthorityRevisions {
+    readonly credentialRevision: string;
+    readonly configRevision: string;
+    readonly bindingRevision: string;
+}
+export type TNativeByteConnectionBinding = {
+    readonly side: 'client';
+    readonly generation: number;
+    readonly webSocket: WebSocket;
+} | {
+    readonly side: 'server';
+    readonly peer: plugins.IWebSocketPeer;
+};
+export interface INativeByteRevalidationContext extends INativeByteAuthorityRevisions {
+    readonly operation: TNativeByteAuthorityOperation;
+    readonly descriptor: INativeByteDescriptor;
+    readonly connection: TNativeByteConnectionBinding;
+    readonly abortSignal: AbortSignal;
+    readonly deadline: number;
+}
+export type TNativeByteRevalidate = (contextArg: INativeByteRevalidationContext) => boolean | Promise<boolean>;
+export interface INativeByteCreateReceiveGrantOptions extends INativeByteAuthorityRevisions {
+    readonly principalId: string;
+    readonly byteLength: number;
+    readonly sha256: string;
+    readonly contentType: string;
+    readonly revalidate: TNativeByteRevalidate;
+    readonly target?: {
+        readonly peer: plugins.IWebSocketPeer;
+    } | plugins.IWebSocketPeer;
+    readonly initialWindowBytes?: number;
+}
+export interface INativeByteOpenSenderOptions {
+    readonly target?: {
+        readonly peer: plugins.IWebSocketPeer;
+    } | plugins.IWebSocketPeer;
+}
+export interface INativeByteReceiveGrant {
+    readonly descriptor: INativeByteDescriptor;
+    readonly stream: INativeByteReceiverLike;
+    readonly opened: Promise<INativeByteReceiverLike>;
+    readonly revoke: (reasonArg?: unknown) => Promise<void>;
+    readonly dispose: () => void;
+}
+export interface INativeByteReceiverLike extends plugins.typedrequestInterfaces.INativeStreamTransportEndpoint {
+    readonly protocol: 'native-byte-v1';
+    readonly direction: 'receive';
+    readonly manifest: plugins.typedrequestInterfaces.INativeByteStreamManifest;
+    readonly readable: ReadableStream<Uint8Array>;
+    readonly completion: Promise<INativeByteReceipt>;
+    confirmDurable(): Promise<INativeByteReceipt>;
+    reject(reasonArg?: unknown): Promise<void>;
+}
+export interface INativeByteSenderLike extends plugins.typedrequestInterfaces.INativeStreamTransportEndpoint {
+    readonly protocol: 'native-byte-v1';
+    readonly direction: 'send';
+    readonly manifest: plugins.typedrequestInterfaces.INativeByteStreamManifest;
+    readonly writable: WritableStream<Uint8Array>;
+    readonly completion: Promise<INativeByteReceipt>;
+}
+export interface INativeByteCapabilityStatus {
+    readonly protocolMajor: 6;
+    readonly capabilities: readonly (typeof NATIVE_BYTE_PROTOCOL)[];
+    readonly connection: 'none' | 'client' | 'server';
+}
+export interface INativeByteStats {
+    readonly connection: 'none' | 'client' | 'server';
+    readonly negotiated: boolean;
+    readonly activeStreams: number;
+    readonly receiveGrants: number;
+    readonly queuedPayloadBytes: number;
+    readonly rawQueueFrames: number;
+    readonly rawQueueBytes: number;
+    readonly processingRawBytes: number;
+    readonly outboundControlFrames: number;
+    readonly outboundDataFrames: number;
+    readonly tombstones: number;
+    readonly retainedRevalidations: number;
+    readonly serverConnections: number;
+    readonly serverStreams: number;
+    readonly serverRetainedBytes: number;
+    readonly serverRetainedRevalidations: number;
+}
+export interface INativeByteRuntime {
+    now(): number;
+    randomBytes(lengthArg: number): Uint8Array;
+    setTimer(callbackArg: () => void, delayMsArg: number): unknown;
+    clearTimer(timerArg: unknown): void;
+    scheduleMacrotask(callbackArg: () => void): unknown;
+}
+export type TNativeByteOpenFrame = {
+    readonly type: typeof NATIVE_BYTE_FRAME_TYPES.OPEN;
+    readonly streamId: string;
+    readonly capability: string;
+    readonly byteLength: number;
+    readonly sha256: string;
+    readonly contentType: string;
+    readonly initialWindowBytes: number;
+};
+export type TNativeByteOpenAckFrame = {
+    readonly type: typeof NATIVE_BYTE_FRAME_TYPES.OPEN_ACK;
+    readonly streamId: string;
+    readonly receiveLimitOffset: number;
+};
+export type TNativeByteDataFrame = {
+    readonly type: typeof NATIVE_BYTE_FRAME_TYPES.DATA;
+    readonly streamId: string;
+    readonly sequence: number;
+    readonly offset: number;
+    readonly payload: Uint8Array;
+};
+export type TNativeByteAckFrame = {
+    readonly type: typeof NATIVE_BYTE_FRAME_TYPES.ACK;
+    readonly streamId: string;
+    readonly acknowledgedOffset: number;
+    readonly receiveLimitOffset: number;
+};
+export type TNativeByteFinFrame = {
+    readonly type: typeof NATIVE_BYTE_FRAME_TYPES.FIN;
+    readonly streamId: string;
+    readonly byteLength: number;
+    readonly sha256: string;
+};
+export type TNativeByteFinAckFrame = {
+    readonly type: typeof NATIVE_BYTE_FRAME_TYPES.FIN_ACK;
+    readonly streamId: string;
+    readonly byteLength: number;
+    readonly sha256: string;
+};
+export type TNativeByteResetFrame = {
+    readonly type: typeof NATIVE_BYTE_FRAME_TYPES.RESET;
+    readonly streamId: string;
+    readonly code: number;
+    readonly reason: string;
+};
+export type TNativeByteFrame = TNativeByteOpenFrame | TNativeByteOpenAckFrame | TNativeByteDataFrame | TNativeByteAckFrame | TNativeByteFinFrame | TNativeByteFinAckFrame | TNativeByteResetFrame;

package/dist_ts/nativebytes.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibmF0aXZlYnl0ZXMudHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9uYXRpdmVieXRlcy50eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dist_ts/typedsocket.classes.typedsocket.d.ts

@@ -1,6 +1,52 @@
 import * as plugins from './typedsocket.plugins.js';
+import { NativeByteManager } from './nativebytes.manager.js';
+import type { INativeByteAuthorizationAdapter, INativeByteCreateVirtualStreamOptions, TNativeByteCapabilityMode } from './nativebytes.types.js';
+import type { ITypedSocketClientTagPolicy } from './typedsocket.tags.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_RETAINED_CLIENT_TAG_MUTATIONS_PER_NAME = 8;
+export declare const TYPEDSOCKET_MAX_RETAINED_CLIENT_TAG_MUTATIONS = 64;
+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 +56,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 +76,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 +116,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 +131,30 @@ 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>;
     private connectionStatus;
     private websocket;
+    private connectionGeneration;
+    private clientConnectionState;
+    private retainedClientCallbacks;
     private clientOptions;
     private serverUrl;
     private retryCount;
@@ -102,14 +164,28 @@ export declare class TypedSocket {
     private stopListeners;
     private pendingRequests;
     private clientTags;
-    private clientTagMutations;
+    private clientTagRevisions;
+    private desiredClientTags;
+    private clientTagDesiredMutationQueues;
+    private clientTagMutationSequence;
+    private clientTagMutationTails;
+    private retainedClientTagMutations;
+    private retainedClientTagMutationsByName;
     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
      */
@@ -158,7 +240,12 @@ export declare class TypedSocket {
      */
     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 +253,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 +266,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 +283,22 @@ export declare class TypedSocket {
      * @client-only
      */
     removeTag(name: string): Promise<void>;
+    private retainClientTagMutation;
+    private setDesiredClientTag;
+    private settleDesiredClientTag;
+    private serializeClientTagMutation;
+    private submitDesiredClientTag;
+    private requireTagMutationSuccess;
+    private applyClientTagMutation;
+    /**
+     * 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