@api.global/typedsocket 6.2.0 → 6.3.0

package/readme.hints.md

@@ -20,13 +20,19 @@ is selected for the physical peer at upgrade time.
    facades require fixed manifests, principal/revision authority, and durable
    confirmation.
 
-4. **Lifecycle**: Client text work, native frames, callbacks, pending requests,
+4. **Messages**: `native-message-v1` is separately negotiated after the primary
+   negotiation. Its ordinary one-use descriptor is explicit application JSON;
+   grants expose the descriptor, receiver, open state, revocation, and disposal,
+   while receivers expose only `receive()`, `closed`, and `reject()`. ACK means
+   application dequeue, not raw-frame receipt.
+
+5. **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
+6. **Restoration**: `restoreConnection(context)` runs after both capability
+   negotiations 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.
 
@@ -35,7 +41,8 @@ is selected for the physical peer at upgrade time.
 `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.
+every sink call is try/catch-wrapped. Native message invariant closes use
+`scope: 'nativeMessage'`.
 
 The WebSocket JS `close()` API only permits codes 1000 and 3000-4999. All
 client-initiated invariant closes therefore go through
@@ -52,7 +59,9 @@ 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`.
+`helpers.*`, `interfaces.*`, `constants.*`, and `plugins.ts`. The native message
+codec/types/constants have `nativemessage` module names but intentionally share
+the one manager and transport owner.
 
 ### Release Artifact
 

package/readme.md

@@ -14,6 +14,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 - 🏷️ **Policy-Gated Connection Tagging** - Default-deny client tags and protected server metadata
 - 🌐 **Browser Compatible** - Works in both Node.js and browser environments
 - 🚀 **SmartServe Integration** - Native support for SmartServe's WebSocket handling
+- **Ephemeral Binary Messages** - Bounded, acknowledged binary messages up to 4 MiB without JSON/base64 expansion
 
 ## Install
 
@@ -195,6 +196,133 @@ Client and server options accept `nativeByteCapabilityMode`:
 - `required` fails client startup when negotiation does not return `native-byte-v1`. On servers it closes peers that do not negotiate the capability.
 - `disabled` advertises no native capability and keeps JSON RPC available.
 
+### Ephemeral Binary Message Channels
+
+TypedSocket separately negotiates `native-message-v1` with
+`__typedsocket_negotiateNativeMessages` after the existing primary capability
+negotiation. Client and server options accept an independent
+`nativeMessageCapabilityMode` (`disabled`, `optional`, or `required`). Optional
+clients tolerate servers that do not know the new private method. Disabled
+clients still call it and advertise an empty capability list when it exists.
+Required servers close peers that do not complete this negotiation within 10
+seconds.
+
+Message channels reuse the one `NativeByteManager`, SmartServe raw-frame owner,
+raw queue, control-first scheduler, exact outbound settlement identity, and
+aggregate connection/server accounting. They use a distinct `TSM1` codec and
+do not alter `native-byte-v1` frame encoding or byte-stream protocol semantics.
+
+The preferred server API is `createBinaryMessageChannel()`. It synchronously
+binds application authorization and returns a receive grant with an ordinary
+JSON descriptor. Applications explicitly carry that descriptor in their own
+typed DTO; TypedRequest and `VirtualStream` do not serialize it automatically.
+
+```typescript
+import {
+  TypedSocket,
+  type INativeMessageDescriptor,
+} from '@api.global/typedsocket';
+
+interface ICameraAuthorization {
+  principalId: string;
+  credentialRevision: string;
+  configRevision: string;
+  bindingRevision: string;
+}
+
+declare const cameraAuthorization: ICameraAuthorization;
+declare function isCameraAuthorizationCurrent(
+  authorizationArg: ICameraAuthorization,
+  operationArg: 'open' | 'message' | 'close' | 'reject',
+): boolean | Promise<boolean>;
+
+const server = TypedSocket.createServer(typedRouter, {
+  nativeMessageCapabilityMode: 'required',
+  nativeMessageAuthorizationAdapter: {
+    bind: (authorizationArg, contextArg) => {
+      const authorization = authorizationArg as ICameraAuthorization;
+      return {
+        ...authorization,
+        revalidate: async (revalidationArg) =>
+          revalidationArg.connection.side === 'server'
+          && revalidationArg.connection.peer === contextArg.target
+          && await isCameraAuthorizationCurrent(
+            authorization,
+            revalidationArg.operation,
+          ),
+      };
+    },
+  },
+});
+
+// Inside a server TypedHandler:
+const target = server.getServerConnectionForRequest(typedToolsArg);
+const grant = server.createBinaryMessageChannel({
+  direction: 'receive',
+  target,
+  authorization: cameraAuthorization,
+  maxMessageBytes: 4 * 1024 * 1024,
+});
+
+// Return grant.descriptor in an application-defined response DTO.
+const descriptor: INativeMessageDescriptor = grant.descriptor;
+
+void (async () => {
+  while (true) {
+    const message = await grant.receiver.receive();
+    if (message === undefined) break;
+    // Process one complete logical message.
+  }
+  await grant.receiver.closed;
+})().catch((errorArg) => grant.receiver.reject(errorArg));
+
+// On the descriptor recipient:
+const sender = await client.nativeBytes.messages.openSender(descriptor);
+await sender.send(jpegBytes);
+await sender.close();
+await sender.closed;
+```
+
+`INativeMessageReceiver` deliberately exposes only `receive()`, `closed`, and
+`reject()`. It has no `ReadableStream`. A complete message occupies one
+application slot, and `MESSAGE_ACK` is queued only when `receive()` dequeues it.
+`send()` snapshots its `Uint8Array` at admission and remains pending until the
+exact logical sequence is acknowledged. Sends serialize without fragment
+interleaving; `close()` queues after admitted sends and waits for `CLOSE_ACK`.
+Empty messages are valid.
+
+The receive grant also exposes `opened`, `revoke(reason?)`, and `dispose()`.
+`opened` settles when the peer successfully opens the channel. Use `revoke()`
+to reject an advertised grant, and use `dispose()` to release a descriptor that
+was never published or opened.
+
+Descriptors are single-use, expire after 10 seconds, and are bound to one exact
+physical peer or client generation. They are recreated after reconnect. The
+protocol has no durability claim, content hash, FIN, reconnect resume, or
+automatic business idempotency. `RESET` normally closes only its channel;
+malformed binary framing closes the physical connection because the routing
+identity cannot be trusted.
+
+| Message-channel limit | Exported constant | Value |
+|---|---|---:|
+| Complete raw frame | `NATIVE_MESSAGE_MAX_FRAME_BYTES` | 32 KiB |
+| Fragment payload | `NATIVE_MESSAGE_MAX_FRAGMENT_PAYLOAD_BYTES` | 32,720 bytes |
+| Logical message package ceiling/default | `NATIVE_MESSAGE_MAX_LOGICAL_MESSAGE_BYTES` / `NATIVE_MESSAGE_DEFAULT_MAX_LOGICAL_MESSAGE_BYTES` | 4 MiB |
+| Pending messages / bytes per channel | `NATIVE_MESSAGE_MAX_PENDING_MESSAGES_PER_CHANNEL` / `NATIVE_MESSAGE_MAX_PENDING_BYTES_PER_CHANNEL` | 8 / 8 MiB |
+| Message channels per connection | `NATIVE_MESSAGE_MAX_CHANNELS_PER_CONNECTION` | 32, also subject to the shared 32 stream+channel slots |
+| Closed-channel tombstones | `NATIVE_MESSAGE_MAX_TOMBSTONES_PER_CONNECTION` / `NATIVE_MESSAGE_TOMBSTONE_RETENTION_MS` | 64 / 60 seconds |
+| Negotiation and OPEN deadlines | `NATIVE_MESSAGE_NEGOTIATION_TIMEOUT_MS` / `NATIVE_MESSAGE_OPEN_TIMEOUT_MS` | 10 seconds |
+| Fragment, acknowledgement, receive, close, and frame progress | `NATIVE_MESSAGE_PROGRESS_TIMEOUT_MS` | 30 seconds |
+
+Pending outbound messages, inbound reassembly/completed slots, native-byte
+stream queues, the raw queue, and server-retained frame/authentication state are
+charged to shared bounded connection and server budgets. Message authorization
+reuses the native transport's principal, three authority revisions, callback
+deadline, and per-peer/principal/server retained-revalidation caps. Revalidation
+callbacks receive operation and authority metadata but never message payloads or
+capability secrets. `nativeBytes.messages.getCapability()` and `getStats()`
+likewise expose only bounded counters and status.
+
 #### Preferred VirtualStream Facade
 
 For bounded byte payloads, application code uses
@@ -422,7 +550,7 @@ opt-in. Byte DTOs must use the exact native facade returned by
 | Maximum receive window / queued payload per stream | `NATIVE_BYTE_MAX_WINDOW_BYTES` / `NATIVE_BYTE_MAX_QUEUED_PAYLOAD_BYTES_PER_STREAM` | 1 MiB |
 | Queued payload per connection | `NATIVE_BYTE_MAX_QUEUED_PAYLOAD_BYTES_PER_CONNECTION` | 8 MiB |
 | Queued receive chunks per stream | `NATIVE_BYTE_MAX_RECEIVE_QUEUE_CHUNKS` | 4,096 |
-| Grants plus active streams per connection | `NATIVE_BYTE_MAX_STREAMS_PER_CONNECTION` | 32 |
+| Native-byte grants/streams plus native-message grants/channels per connection | `NATIVE_BYTE_MAX_STREAMS_PER_CONNECTION` | 32 shared slots |
 | Pending admitted DATA operations per connection | `NATIVE_BYTE_MAX_PENDING_DATA_OPERATIONS_PER_CONNECTION` | 64 |
 | Raw inbound queue | `NATIVE_BYTE_MAX_RAW_QUEUE_FRAMES` / `NATIVE_BYTE_MAX_RAW_QUEUE_BYTES` | 64 frames / 2 MiB |
 | Grant and OPEN timeout | `NATIVE_BYTE_GRANT_OPEN_TIMEOUT_MS` | 10 seconds |
@@ -430,7 +558,7 @@ opt-in. Byte DTOs must use the exact native facade returned by
 | Closed-stream tombstones | `NATIVE_BYTE_MAX_TOMBSTONES` / `NATIVE_BYTE_TOMBSTONE_RETENTION_MS` | 64, oldest-first, 60 seconds |
 | Principal and each authority revision | `NATIVE_BYTE_MAX_PRINCIPAL_ID_BYTES` / `NATIVE_BYTE_MAX_AUTHORITY_REVISION_BYTES` | 256 UTF-8 bytes |
 | Retained revalidation callbacks | `NATIVE_BYTE_MAX_REVALIDATIONS_PER_PEER` / `_PER_PRINCIPAL` / `_PER_SERVER` | 4 per peer / 16 per principal / 128 per server |
-| Server connections / streams | `NATIVE_BYTE_MAX_CONNECTIONS_PER_SERVER` / `NATIVE_BYTE_MAX_STREAMS_PER_SERVER` | 1,024 / 1,024 |
+| Server connections / native-byte and native-message endpoints | `NATIVE_BYTE_MAX_CONNECTIONS_PER_SERVER` / `NATIVE_BYTE_MAX_STREAMS_PER_SERVER` | 1,024 / 1,024 shared slots |
 | Server retained bytes / receive reservations | `NATIVE_BYTE_MAX_RETAINED_BYTES_PER_SERVER` | 64 MiB / 64 MiB |
 
 SmartServe owner sends prioritize control frames over DATA and pull one binary
@@ -509,11 +637,11 @@ const client = await TypedSocket.createClient(clientRouter, serverUrl, {
 
 | Client limit | Exported constant | Package ceiling |
 |---|---|---:|
-| Complete text frame | `TYPEDSOCKET_MAX_TEXT_FRAME_BYTES` | 1 MiB |
-| Queued text frames / bytes | `TYPEDSOCKET_MAX_QUEUED_TEXT_FRAMES` / `TYPEDSOCKET_MAX_QUEUED_TEXT_BYTES` | 64 / 4 MiB |
+| Complete text frame | `TYPEDSOCKET_MAX_TEXT_FRAME_BYTES` | 16 MiB |
+| Queued text frames / bytes | `TYPEDSOCKET_MAX_QUEUED_TEXT_FRAMES` / `TYPEDSOCKET_MAX_QUEUED_TEXT_BYTES` | 64 / 32 MiB |
 | Concurrent handlers / retained callbacks | `TYPEDSOCKET_MAX_CONCURRENT_CLIENT_HANDLERS` / `TYPEDSOCKET_MAX_RETAINED_CLIENT_CALLBACKS` | 16 / 64 |
 | Pending client requests | `TYPEDSOCKET_MAX_PENDING_CLIENT_REQUESTS` | 1,024 |
-| Outbound WebSocket buffered bytes | `TYPEDSOCKET_MAX_OUTBOUND_BUFFERED_BYTES` | 4 MiB |
+| Outbound WebSocket buffered bytes | `TYPEDSOCKET_MAX_OUTBOUND_BUFFERED_BYTES` | 32 MiB |
 | Method name / correlation ID | `TYPEDSOCKET_MAX_METHOD_NAME_BYTES` / `TYPEDSOCKET_MAX_CORRELATION_ID_BYTES` | 256 UTF-8 bytes each |
 | Request timeout | `TYPEDSOCKET_MAX_REQUEST_TIMEOUT_MS` | 5 minutes |
 | Connection restoration timeout | `TYPEDSOCKET_MAX_CONNECTION_RESTORE_TIMEOUT_MS` | 10 seconds |
@@ -818,8 +946,8 @@ await smartServe.stop();
 
 | Method | Description |
 |--------|-------------|
-| `createClient(router, serverUrl, options?)` | Creates a WebSocket client. Options include reconnect controls, `abortSignal`, `nativeByteCapabilityMode`, lowering-only `limits`, and `restoreConnection`. |
-| `createServer(routerOrRouters, options?)` | Synchronously composes protocol handling. Options include `nativeByteCapabilityMode`, `nativeByteAuthorizationAdapter`, and the default-deny `clientTagPolicy`. |
+| `createClient(router, serverUrl, options?)` | Creates a WebSocket client. Options include reconnect controls, `abortSignal`, independent `nativeByteCapabilityMode` and `nativeMessageCapabilityMode`, lowering-only `limits`, and `restoreConnection`. |
+| `createServer(routerOrRouters, options?)` | Synchronously composes protocol handling. Options include independent native byte/message capability modes and authorization adapters, plus the default-deny `clientTagPolicy`. |
 | `fromSmartServe(smartServe, routerOrRouters, options?)` | Creates and attaches a JSON-only server-side TypedSocket to an existing SmartServe instance. |
 | `useWindowLocationOriginUrl()` | Returns the current window location origin (browser only). |
 
@@ -829,10 +957,10 @@ await smartServe.stop();
 |----------|-------------|
 | `side` | Whether this instance is a `'server'` or `'client'`. |
 | `typedrouter` | The TypedRouter instance handling requests. |
-| `nativeBytes` | Advanced native-byte grant, sender, capability, and statistics API for transport integrations. |
+| `nativeBytes` | Native transport API. Existing stream methods stay on this object; ephemeral message channels are under `nativeBytes.messages`. |
 | `webSocketTransportOwner` | Stable SmartServe 4 raw-frame owner selected during SmartServe construction. |
 | `statusSubject` | RxJS Subject for client connection status events. Server instances do not publish lifecycle transitions here. |
-| `diagnosticsSubject` | RxJS Subject of structured `TTypedSocketDiagnosticEvent` values: invariant closes, peer rejections, reconnect scheduling/exhaustion, tag denials, and deprecated implicit targeting. Never completes. |
+| `diagnosticsSubject` | RxJS Subject of structured `TTypedSocketDiagnosticEvent` values: invariant closes (including `scope: 'nativeMessage'`), peer rejections, reconnect scheduling/exhaustion, tag denials, and deprecated implicit targeting. Never completes. |
 
 #### Instance Methods
 
@@ -840,6 +968,7 @@ await smartServe.stop();
 |--------|-------------|
 | `attachSmartServe(smartServe)` | Attaches one SmartServe transport to a composed server-side TypedSocket before listening. |
 | `createVirtualStream(options)` | Creates the preferred exact, authorized native-byte receive facade for one server peer. TypedRequest transfers its descriptor automatically. |
+| `createBinaryMessageChannel(options)` | Creates an authorized ephemeral binary-message receive grant and ordinary descriptor for one exact server peer. |
 | `createTypedRequest(method, targetConnection?, options?)` | Creates a typed request. Options include the transport `timeoutMs` and `abortSignal`; per-call `fire()` deadlines are also forwarded to the transport. |
 | `getServerConnectionForRequest(typedTools)` | Resolves the exact transport connection for an incoming server handler without assertions. |
 | `getStatus()` | Returns the client connection lifecycle status. Server instances remain in the initial `new` state. |
@@ -861,6 +990,10 @@ await smartServe.stop();
 | `nativeBytes.openSender(descriptor, options?)` | Opens an explicit sender for an opaque descriptor on the exact target connection. |
 | `nativeBytes.getCapability(target?)` | Reports negotiated native-byte capability without exposing tokens or descriptors. |
 | `nativeBytes.getStats(target?)` | Reports bounded connection, stream, queue, and tombstone counts. |
+| `nativeBytes.messages.createReceiveGrant(options)` | Advanced explicit receive-grant API for one ephemeral message channel. The grant exposes `opened`, `revoke(reason?)`, and `dispose()` in addition to its descriptor and receiver. |
+| `nativeBytes.messages.openSender(descriptor, options?)` | Opens the descriptor on the exact physical client generation or required server peer target. |
+| `nativeBytes.messages.getCapability(target?)` | Reports separately negotiated `native-message-v1` status. |
+| `nativeBytes.messages.getStats(target?)` | Reports bounded channel, pending message, reassembly, queue, and aggregate accounting. |
 
 ## License and Legal Information