@enbox/dwn-clients 0.4.4 → 0.4.6

package/src/rpc-client.ts

@@ -1,5 +1,6 @@
 import type { JsonRpcResponse } from './json-rpc.js';
-import type { DwnRpc, DwnRpcRequest, DwnRpcResponse } from './dwn-rpc-types.js';
+import type { ReplicationApplyResult } from '@enbox/dwn-sdk-js';
+import type { DwnReplicationApplyRequest, DwnRpc, DwnRpcRequest, DwnRpcResponse } from './dwn-rpc-types.js';
 import type { DwnServerInfoRpc, ServerInfo } from './server-info-types.js';
 
 import { createJsonRpcRequest } from './json-rpc.js';
@@ -94,6 +95,20 @@ export class EnboxRpcClient implements EnboxRpc {
     return transportClient.sendDwnRequest(request);
   }
 
+  applyReplicatedMessage(request: DwnReplicationApplyRequest): Promise<ReplicationApplyResult> {
+    const url = new URL(request.dwnUrl);
+
+    const transportClient = this.transportClients.get(url.protocol);
+    if (!transportClient) {
+      const error = new Error(`no ${url.protocol} transport client available`);
+      error.name = 'NO_TRANSPORT_CLIENT';
+
+      throw error;
+    }
+
+    return transportClient.applyReplicatedMessage(request);
+  }
+
   async getServerInfo(dwnUrl: string): Promise<ServerInfo> {
     // will throw if url is invalid
     const url = new URL(dwnUrl);
@@ -153,8 +168,4 @@ export class WebSocketEnboxRpcClient extends WebSocketDwnRpcClient implements En
   async sendDidRequest(_request: DidRpcRequest): Promise<DidRpcResponse> {
     throw new Error(`not implemented for transports [${this.transportProtocols.join(', ')}]`);
   }
-
-  async getServerInfo(_dwnUrl: string): Promise<ServerInfo> {
-    throw new Error(`not implemented for transports [${this.transportProtocols.join(', ')}]`);
-  }
 }

package/src/web-socket-clients.ts

@@ -1,9 +1,31 @@
-import type { DwnRpc, DwnRpcRequest, DwnRpcResponse, DwnSubscriptionHandler, ResubscribeFactory } from './dwn-rpc-types.js';
-import type { GenericMessage, MessageSubscription, ProgressToken, SubscriptionMessage, UnionMessageReply } from '@enbox/dwn-sdk-js';
+import type {
+  DwnReplicationApplyRequest,
+  DwnRpc,
+  DwnRpcRequest,
+  DwnRpcResponse,
+  DwnSubscriptionHandler,
+  ResubscribeFactory,
+} from './dwn-rpc-types.js';
+import type { DwnServerInfoRpc, ServerInfo } from './server-info-types.js';
+import type {
+  GenericMessage,
+  MessageSubscription,
+  ProgressToken,
+  ReplicationApplyResult,
+  SubscriptionMessage,
+  UnionMessageReply,
+} from '@enbox/dwn-sdk-js';
 
 import { CryptoUtils } from '@enbox/crypto';
+import { DwnRpcError } from './dwn-rpc-error.js';
+import { HttpDwnRpcClient } from './http-dwn-rpc-client.js';
 import { JsonRpcSocket } from './json-rpc-socket.js';
-import { createJsonRpcAck, createJsonRpcRequest, createJsonRpcSubscriptionRequest } from './json-rpc.js';
+import { parseReplicationApplyResult } from './replication-apply-result.js';
+import { createJsonRpcAck, createJsonRpcRequest, createJsonRpcSubscriptionRequest, JsonRpcErrorCodes } from './json-rpc.js';
+import { DataStream, Encoder } from '@enbox/dwn-sdk-js';
+import { DEFAULT_MAX_WS_RAW_RECORD_DATA_BYTES, maxWsJsonRpcPayloadBytes } from './ws-payload-size.js';
+
+const DEFAULT_MAX_WS_JSON_RPC_PAYLOAD_BYTES = maxWsJsonRpcPayloadBytes(DEFAULT_MAX_WS_RAW_RECORD_DATA_BYTES);
 
 /**
  * Metadata for a tracked subscription, including everything needed to
@@ -39,6 +61,14 @@ interface SocketConnection {
   url: string;
 }
 
+function connectionCacheKey(url: URL): string {
+  return stripTrailingSlash(url.toString());
+}
+
+function stripTrailingSlash(url: string): string {
+  return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+
 function shouldReplaceLastCursor(current: ProgressToken | undefined, candidate: ProgressToken): boolean {
   if (current === undefined) {
     return true;
@@ -53,8 +83,11 @@ function shouldReplaceLastCursor(current: ProgressToken | undefined, candidate:
 
 export class WebSocketDwnRpcClient implements DwnRpc {
   public get transportProtocols(): string[] { return ['ws:', 'wss:']; }
-  // a map of dwn host to WebSocket connection
+  // a map of normalized DWN WebSocket endpoint URLs to WebSocket connections
   private static readonly connections = new Map<string, SocketConnection>();
+  private static readonly pendingConnections = new Map<string, Promise<SocketConnection>>();
+
+  public constructor(private readonly serverInfoRpc: DwnServerInfoRpc = new HttpDwnRpcClient()) {}
 
   async sendDwnRequest(request: DwnRpcRequest): Promise<DwnRpcResponse> {
 
@@ -64,18 +97,7 @@ export class WebSocketDwnRpcClient implements DwnRpc {
       throw new Error(`Invalid websocket protocol ${url.protocol}`);
     }
 
-    // check if there is already a connection to this host, if it does not exist, initiate a new connection
-    const hasConnection = WebSocketDwnRpcClient.connections.has(url.host);
-    if (!hasConnection) {
-      try {
-        const connection = await WebSocketDwnRpcClient.createConnection(url);
-        WebSocketDwnRpcClient.connections.set(url.host, connection);
-      } catch (error) {
-        throw new Error(`Error connecting to ${url.host}: ${(error as Error).message}`);
-      }
-    }
-
-    const connection = WebSocketDwnRpcClient.connections.get(url.host)!;
+    const connection = await WebSocketDwnRpcClient.getConnection(request.dwnUrl);
     const { targetDid, message, subscription } = request;
 
     if (subscription) {
@@ -87,17 +109,71 @@ export class WebSocketDwnRpcClient implements DwnRpc {
     return WebSocketDwnRpcClient.processMessage(connection, targetDid, message);
   }
 
+  async applyReplicatedMessage(request: DwnReplicationApplyRequest): Promise<ReplicationApplyResult> {
+    WebSocketDwnRpcClient.assertReplicatedApplyDataIsPresent(request);
+    const maxPayloadBytes = await this.maxPayloadBytesForReplicatedApply(request);
+    WebSocketDwnRpcClient.assertReplicatedApplyDataSizeIsSupported(request, maxPayloadBytes);
+    const connection = await WebSocketDwnRpcClient.getConnection(request.dwnUrl);
+    const encodedData = request.data === undefined ? undefined : await dataToBase64Url(request.data);
+    return WebSocketDwnRpcClient.applyReplicatedMessage(connection, request.targetDid, request.message, encodedData, maxPayloadBytes);
+  }
+
+  async getServerInfo(dwnUrl: string): Promise<ServerInfo> {
+    return this.serverInfoRpc.getServerInfo(httpUrlForWsDwnUrl(dwnUrl));
+  }
+
+  private async maxPayloadBytesForReplicatedApply(request: DwnReplicationApplyRequest): Promise<number> {
+    const dataSize = recordsWriteDataSize(request.message);
+    if (dataSize === undefined) {
+      return DEFAULT_MAX_WS_JSON_RPC_PAYLOAD_BYTES;
+    }
+
+    const serverInfo = await this.getServerInfo(request.dwnUrl);
+    return maxWsJsonRpcPayloadBytes(serverInfo.maxFileSize);
+  }
+
+  private static async getConnection(dwnUrl: string): Promise<SocketConnection> {
+    const url = new URL(dwnUrl);
+    if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+      throw new Error(`Invalid websocket protocol ${url.protocol}`);
+    }
+
+    const key = connectionCacheKey(url);
+    const existing = WebSocketDwnRpcClient.connections.get(key);
+    if (existing !== undefined) {
+      return existing;
+    }
+
+    let pending = WebSocketDwnRpcClient.pendingConnections.get(key);
+    if (pending === undefined) {
+      pending = WebSocketDwnRpcClient.createConnection(url)
+        .then((connection) => {
+          WebSocketDwnRpcClient.connections.set(key, connection);
+          return connection;
+        })
+        .catch((error: unknown) => {
+          throw new Error(`Error connecting to ${key}: ${(error as Error).message}`);
+        })
+        .finally(() => {
+          WebSocketDwnRpcClient.pendingConnections.delete(key);
+        });
+      WebSocketDwnRpcClient.pendingConnections.set(key, pending);
+    }
+
+    return pending;
+  }
+
   /**
    * Creates a new `SocketConnection` with lifecycle wiring for reconnection.
    */
   private static async createConnection(url: URL): Promise<SocketConnection> {
-    const host = url.host;
+    const key = connectionCacheKey(url);
     const subscriptions = new Map<string, TrackedSubscription>();
 
     const socket = await JsonRpcSocket.connect(url.toString(), {
       onclose: (): void => {
         // Remove the stale connection from the map so new requests create a fresh one.
-        WebSocketDwnRpcClient.connections.delete(host);
+        WebSocketDwnRpcClient.connections.delete(key);
 
         // Notify all subscription handlers of disconnection.
         for (const tracked of subscriptions.values()) {
@@ -114,7 +190,7 @@ export class WebSocketDwnRpcClient implements DwnRpc {
       onreconnected: (): void => {
         // Re-register this connection in the map (it was deleted on close).
         const conn = { socket, subscriptions, url: url.toString() };
-        WebSocketDwnRpcClient.connections.set(host, conn);
+        WebSocketDwnRpcClient.connections.set(key, conn);
 
         // Resubscribe all tracked subscriptions with their last known cursor.
         WebSocketDwnRpcClient.resubscribeAll(conn);
@@ -141,6 +217,32 @@ export class WebSocketDwnRpcClient implements DwnRpc {
     return result.reply as DwnRpcResponse;
   }
 
+  private static async applyReplicatedMessage(
+    connection: SocketConnection,
+    target: string,
+    message: DwnReplicationApplyRequest['message'],
+    encodedData?: string,
+    maxPayloadBytes: number = DEFAULT_MAX_WS_JSON_RPC_PAYLOAD_BYTES,
+  ): Promise<ReplicationApplyResult> {
+    const requestId = CryptoUtils.randomUuid();
+    const request = createJsonRpcRequest(requestId, 'dwn.applyReplicatedMessage', {
+      target,
+      message,
+      ...(encodedData === undefined ? {} : { encodedData }),
+    });
+    WebSocketDwnRpcClient.assertPayloadFitsFrame(request, encodedData, maxPayloadBytes);
+
+    const { socket } = connection;
+    const response = await socket.request(request);
+
+    const { error, result } = response;
+    if (error !== undefined) {
+      throw new DwnRpcError(error.code, error.message, error.data);
+    }
+
+    return parseReplicationApplyResult(result.result);
+  }
+
   private static async subscriptionRequest(
     connection: SocketConnection,
     target: string,
@@ -273,4 +375,93 @@ export class WebSocketDwnRpcClient implements DwnRpc {
       }
     }
   }
+
+  private static assertReplicatedApplyDataIsPresent(request: DwnReplicationApplyRequest): void {
+    const dataSize = recordsWriteDataSize(request.message);
+    if (dataSize !== undefined && dataSize > 0 && request.data === undefined) {
+      throw new DwnRpcError(
+        JsonRpcErrorCodes.InvalidParams,
+        'data-bearing RecordsWrite replicated apply over WebSocket requires encoded data',
+      );
+    }
+  }
+
+  private static assertReplicatedApplyDataSizeIsSupported(request: DwnReplicationApplyRequest, maxPayloadBytes: number): void {
+    const dataSize = recordsWriteDataSize(request.message);
+    if (dataSize !== undefined && maxWsJsonRpcPayloadBytes(dataSize) > maxPayloadBytes) {
+      throw new DwnRpcError(
+        JsonRpcErrorCodes.InvalidParams,
+        `RecordsWrite replicated apply data is too large for WebSocket JSON-RPC framing`,
+      );
+    }
+  }
+
+  private static assertPayloadFitsFrame(
+    request: ReturnType<typeof createJsonRpcRequest>,
+    encodedData: string | undefined,
+    maxPayloadBytes: number,
+  ): void {
+    const payloadBytes = estimatedJsonRpcPayloadBytes(request, encodedData);
+    if (payloadBytes > maxPayloadBytes) {
+      throw new DwnRpcError(
+        JsonRpcErrorCodes.InvalidParams,
+        `replicated apply JSON-RPC payload is too large for WebSocket transport`,
+      );
+    }
+  }
+}
+
+function httpUrlForWsDwnUrl(dwnUrl: string): string {
+  const url = new URL(dwnUrl);
+  if (url.protocol === 'ws:') {
+    url.protocol = 'http:';
+  } else if (url.protocol === 'wss:') {
+    url.protocol = 'https:';
+  }
+  return url.toString();
+}
+
+function estimatedJsonRpcPayloadBytes(request: ReturnType<typeof createJsonRpcRequest>, encodedData: string | undefined): number {
+  if (encodedData === undefined) {
+    return utf8ByteLength(JSON.stringify(request));
+  }
+
+  const params = request.params as Record<string, unknown>;
+  const requestWithoutData = {
+    ...request,
+    params: {
+      ...params,
+      encodedData: '',
+    },
+  };
+  return utf8ByteLength(JSON.stringify(requestWithoutData)) + encodedData.length;
+}
+
+function utf8ByteLength(text: string): number {
+  return new TextEncoder().encode(text).byteLength;
+}
+
+async function dataToBase64Url(data: DwnReplicationApplyRequest['data']): Promise<string> {
+  if (data instanceof Blob) {
+    return Encoder.bytesToBase64Url(new Uint8Array(await data.arrayBuffer()));
+  }
+
+  if (data instanceof ReadableStream) {
+    return Encoder.bytesToBase64Url(await DataStream.toBytes(data as ReadableStream<Uint8Array>));
+  }
+
+  if (data instanceof Uint8Array) {
+    return Encoder.bytesToBase64Url(data);
+  }
+
+  return Encoder.bytesToBase64Url(new Uint8Array(await new Blob([data] as BlobPart[]).arrayBuffer()));
+}
+
+function recordsWriteDataSize(message: DwnReplicationApplyRequest['message']): number | undefined {
+  const descriptor = (message as { descriptor?: { interface?: unknown; method?: unknown; dataSize?: unknown } }).descriptor;
+  return descriptor?.interface === 'Records' &&
+    descriptor.method === 'Write' &&
+    typeof descriptor.dataSize === 'number'
+    ? descriptor.dataSize
+    : undefined;
 }

package/src/ws-payload-size.ts

@@ -0,0 +1,14 @@
+export const DEFAULT_MAX_WS_RAW_RECORD_DATA_BYTES = 100 * 1024 * 1024;
+export const WS_JSON_RPC_ENVELOPE_BYTES = 64 * 1024;
+
+export function base64UrlEncodedLength(byteLength: number): number {
+  return Math.ceil(byteLength / 3) * 4;
+}
+
+export function estimatedWsJsonRpcPayloadBytes(rawDataSize: number): number {
+  return base64UrlEncodedLength(rawDataSize) + WS_JSON_RPC_ENVELOPE_BYTES;
+}
+
+export function maxWsJsonRpcPayloadBytes(maxRecordDataSize: number): number {
+  return estimatedWsJsonRpcPayloadBytes(maxRecordDataSize);
+}