@api.global/typedsocket 5.1.2 → 6.1.0

package/dist_ts/interfaces.nativebytes.d.ts

@@ -0,0 +1,187 @@
+import type * as plugins from './plugins.js';
+import type { NATIVE_BYTE_FRAME_TYPES, NATIVE_BYTE_PROTOCOL } from './constants.nativebytes.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/interfaces.nativebytes.js

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

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

@@ -1,18 +1,12 @@
-// @apiglobal scope
 import * as typedrequest from '@api.global/typedrequest';
 import * as typedrequestInterfaces from '@api.global/typedrequest-interfaces';
-
 export { typedrequest, typedrequestInterfaces };
-
-// @pushrocks scope
 import * as smartdelay from '@push.rocks/smartdelay';
+import * as smarthash from '@push.rocks/smarthash/web';
 import * as smartjson from '@push.rocks/smartjson';
 import * as smartpromise from '@push.rocks/smartpromise';
 import * as smartrx from '@push.rocks/smartrx';
 import * as smartstring from '@push.rocks/smartstring';
 import * as smarturl from '@push.rocks/smarturl';
-
-export { smartdelay, smartjson, smartpromise, smartrx, smartstring, smarturl };
-
-// SmartServe - required for server-side WebSocket support
-export type { SmartServe, IWebSocketPeer } from '@push.rocks/smartserve';
+export { smartdelay, smarthash, smartjson, smartpromise, smartrx, smartstring, smarturl };
+export type { SmartServe, IWebSocketPeer, IWebSocketTransportOwner, TWebSocketOutboundRawFrame, IWebSocketRawFrameSettlement, } from '@push.rocks/smartserve';

package/dist_ts/plugins.js

@@ -0,0 +1,14 @@
+// @apiglobal scope
+import * as typedrequest from '@api.global/typedrequest';
+import * as typedrequestInterfaces from '@api.global/typedrequest-interfaces';
+export { typedrequest, typedrequestInterfaces };
+// @pushrocks scope
+import * as smartdelay from '@push.rocks/smartdelay';
+import * as smarthash from '@push.rocks/smarthash/web';
+import * as smartjson from '@push.rocks/smartjson';
+import * as smartpromise from '@push.rocks/smartpromise';
+import * as smartrx from '@push.rocks/smartrx';
+import * as smartstring from '@push.rocks/smartstring';
+import * as smarturl from '@push.rocks/smarturl';
+export { smartdelay, smarthash, smartjson, smartpromise, smartrx, smartstring, smarturl };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsbUJBQW1CO0FBQ25CLE9BQU8sS0FBSyxZQUFZLE1BQU0sMEJBQTBCLENBQUM7QUFDekQsT0FBTyxLQUFLLHNCQUFzQixNQUFNLHFDQUFxQyxDQUFDO0FBRTlFLE9BQU8sRUFBRSxZQUFZLEVBQUUsc0JBQXNCLEVBQUUsQ0FBQztBQUVoRCxtQkFBbUI7QUFDbkIsT0FBTyxLQUFLLFVBQVUsTUFBTSx3QkFBd0IsQ0FBQztBQUNyRCxPQUFPLEtBQUssU0FBUyxNQUFNLDJCQUEyQixDQUFDO0FBQ3ZELE9BQU8sS0FBSyxTQUFTLE1BQU0sdUJBQXVCLENBQUM7QUFDbkQsT0FBTyxLQUFLLFlBQVksTUFBTSwwQkFBMEIsQ0FBQztBQUN6RCxPQUFPLEtBQUssT0FBTyxNQUFNLHFCQUFxQixDQUFDO0FBQy9DLE9BQU8sS0FBSyxXQUFXLE1BQU0seUJBQXlCLENBQUM7QUFDdkQsT0FBTyxLQUFLLFFBQVEsTUFBTSxzQkFBc0IsQ0FBQztBQUVqRCxPQUFPLEVBQUUsVUFBVSxFQUFFLFNBQVMsRUFBRSxTQUFTLEVBQUUsWUFBWSxFQUFFLE9BQU8sRUFBRSxXQUFXLEVBQUUsUUFBUSxFQUFFLENBQUMifQ==

package/{license → license.md}

@@ -1,4 +1,4 @@
-Copyright (c) 2020 Lossless GmbH (hello@lossless.com)
+Copyright (c) 2020 Task Venture Capital GmbH (hello@task.vc)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -16,4 +16,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "@api.global/typedsocket",
-  "version": "5.1.2",
+  "version": "6.1.0",
   "private": false,
   "description": "A library for creating typed WebSocket connections, supporting bi-directional communication with type safety.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist_ts/index.d.ts",
+      "import": "./dist_ts/index.js",
+      "default": "./dist_ts/index.js"
+    }
+  },
   "type": "module",
-  "author": "Lossless GmbH",
+  "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",
@@ -14,13 +21,14 @@
     "@git.zone/tsrun": "^2.0.6",
     "@git.zone/tstest": "^3.6.7",
     "@push.rocks/smartenv": "^6.1.0",
-    "@push.rocks/smartserve": "^2.6.0",
+    "@push.rocks/smartserve": "^4.2.1",
     "@types/node": "26.1.1"
   },
   "dependencies": {
-    "@api.global/typedrequest": "^3.7.0",
-    "@api.global/typedrequest-interfaces": "^4.0.0",
+    "@api.global/typedrequest": "^5.2.1",
+    "@api.global/typedrequest-interfaces": "^5.1.1",
     "@push.rocks/smartdelay": "^3.1.0",
+    "@push.rocks/smarthash": "^3.3.0",
     "@push.rocks/smartjson": "^6.0.1",
     "@push.rocks/smartpromise": "^4.2.4",
     "@push.rocks/smartrx": "^3.0.12",
@@ -28,22 +36,17 @@
     "@push.rocks/smarturl": "^3.1.0"
   },
   "peerDependencies": {
-    "@push.rocks/smartserve": ">=2.3.0 <4"
+    "@push.rocks/smartserve": ">=4.2.1 <5"
   },
   "browserslist": [
     "last 1 chrome versions"
   ],
   "files": [
-    "ts/**/*",
-    "ts_web/**/*",
-    "dist/**/*",
-    "dist_*/**/*",
-    "dist_ts/**/*",
-    "dist_ts_web/**/*",
-    "assets/**/*",
-    "cli.js",
-    "npmextra.json",
-    "readme.md"
+    "dist_ts/**/*.js",
+    "dist_ts/**/*.d.ts",
+    "license.md",
+    "readme.md",
+    "readme.hints.md"
   ],
   "keywords": [
     "WebSocket",
@@ -55,7 +58,8 @@
   ],
   "scripts": {
     "test": "(tstest test/ --verbose)",
-    "build": "(tsbuild --web --allowimplicitany --skiplibcheck)",
-    "buildDocs": "tsdoc"
+    "build": "(tsbuild --web --disallowimplicitany)",
+    "buildDocs": "tsdoc",
+    "verify:package": "tsrun verify.package.ts"
   }
 }

package/readme.hints.md

@@ -1,21 +1,62 @@
 # TypedSocket Hints
 
-## SmartServe Integration (Added v3.1.0)
-
-TypedSocket now supports SmartServe as an alternative WebSocket backend via `TypedSocket.fromSmartServe()`.
-
-### Key Differences from Smartsocket Mode
-
-1. **Tag System**: SmartServe uses `Set<string>` for tags, while Smartsocket uses `{id, payload}`. The wrapper stores payloads in `peer.data` with `__typedsocket_tag__` prefix.
-
-2. **Request/Response**: Uses TypedRouter's `fireEventInterestMap` for async correlation when sending server-initiated requests.
-
-3. **Lifecycle**: SmartServe manages WebSocket lifecycle. `typedSocket.stop()` only clears internal state.
-
-4. **eventSubject**: Not fully supported in SmartServe mode - use SmartServe's `onConnectionOpen`/`onConnectionClose` hooks instead.
-
-### Files Modified for SmartServe Support
-
-- `ts/typedsocket.classes.typedsocket.ts` - Main implementation
-- `ts/typedsocket.plugins.ts` - Type imports
-- `package.json` - Optional peer dependency
+## TypedSocket 6 Integration
+
+TypedSocket 6 requires SmartServe 4.2.1 and TypedRequest 5.2.1. Compose the
+TypedSocket server before constructing SmartServe so `webSocketTransportOwner`
+is selected for the physical peer at upgrade time.
+
+### Authority Rules
+
+1. **Peer identity**: Incoming server handlers call
+   `getServerConnectionForRequest(typedTools)` to obtain the exact typed transport
+   connection without assertions. Tag validators receive opaque `connectionId`
+   and `routingSurfaceId` identities instead of mutable peer/router objects.
+
+2. **Tags**: Client tags are default-deny exact rules. Authentication, roles,
+   registration, and reserved names are assigned only with `setServerTag()`.
+
+3. **Bytes**: Generic legacy VirtualStreams are always denied. Exact native-byte
+   facades require fixed manifests, principal/revision authority, and durable
+   confirmation.
+
+4. **Lifecycle**: Client text work, native frames, callbacks, pending requests,
+   tag mutations, and server request interests have fixed resource ceilings and
+   generation fencing. SmartServe settlements authorize only the exact frame
+   object returned by `pullBinaryFrame()`.
+
+5. **Restoration**: `restoreConnection(context)` runs after capability
+   negotiation and before desired tags or `connected`. Use
+   `context.createTypedRequest()` for authenticated restoration RPCs; it inherits
+   the restoration deadline and abort signal and becomes invalid afterward.
+
+### Diagnostics and Close Codes
+
+`diagnosticsSubject` (and `onDiagnostic` on a standalone `NativeByteManager`)
+publishes structured invariant-close, peer-rejection, reconnect, tag-denial,
+and implicit-targeting events. Emission must never disturb transport paths:
+every sink call is try/catch-wrapped.
+
+The WebSocket JS `close()` API only permits codes 1000 and 3000-4999. All
+client-initiated invariant closes therefore go through
+`toClientWebSocketCloseCode()` (1009 -> 4009). Calling `close(1008)` on a real
+client WebSocket throws `InvalidAccessError` — under Node/undici that escapes
+`onmessage` as an uncaught exception and kills the process, and inside
+`NativeByteManager`'s try/catch it silently left the socket open. Server-side
+`peer.close()` keeps protocol codes; diagnostics always report the semantic
+protocol code.
+
+### Source Layout
+
+Files are named after their main class: `classes.typedsocket.ts`,
+`classes.typedsockettagpolicymanager.ts`, `classes.clienttagreconciler.ts`
+(client desired/acknowledged tag state machine behind a transport adapter),
+`classes.nativebytemanager.ts`, `classes.nativebyteerror.ts`, plus
+`helpers.*`, `interfaces.*`, `constants.*`, and `plugins.ts`.
+
+### Release Artifact
+
+Only compiled `dist_ts` JavaScript/declarations, package metadata, documentation,
+and the license are published. `pnpm run verify:package` performs the deterministic
+two-pack entry, hash, metadata, and smoke-import gate (exact artifact count is
+asserted in `verify.package.ts` — update it when adding source files).