@enbox/dwn-clients 0.4.3 → 0.4.5

package/src/dwn-rpc-types.ts

@@ -1,4 +1,11 @@
-import type { GenericMessage, ProgressToken, RecordsReadReply, SubscriptionMessage, UnionMessageReply } from '@enbox/dwn-sdk-js';
+import type {
+  GenericMessage,
+  ProgressToken,
+  RecordsReadReply,
+  ReplicationApplyResult,
+  SubscriptionMessage,
+  UnionMessageReply,
+} from '@enbox/dwn-sdk-js';
 
 export interface SerializableDwnMessage {
   toJSON(): string;
@@ -74,6 +81,15 @@ export interface DwnRpc {
    * @returns A promise that resolves to the response from the DWN server.
    */
   sendDwnRequest(request: DwnRpcRequest): Promise<DwnRpcResponse>
+
+  /**
+   * Applies a replicated message through the DWN server's replication entry point.
+   *
+   * This differs from `sendDwnRequest()` in duplicate replay handling: the server
+   * calls `Dwn.applyReplicatedMessage()`, which repairs missing replication index
+   * entries when the message store already contains the exact message.
+   */
+  applyReplicatedMessage(request: DwnReplicationApplyRequest): Promise<ReplicationApplyResult>
 }
 
 
@@ -110,6 +126,13 @@ export type DwnRpcRequest = {
    */
   signal?: AbortSignal;
 
+  /**
+   * Optional HTTP per-attempt timeout in milliseconds. When supplied, this
+   * replaces the transport default timeout; use this for legitimate large
+   * uploads that need more than the default budget.
+   */
+  timeoutMs?: number;
+
   /**
    * Subscription options — only set for subscribe requests.
    * Groups the handler, resubscribe factory, and any future subscription
@@ -129,6 +152,34 @@ export type DwnRpcRequest = {
   };
 };
 
+/**
+ * Represents a JSON RPC request to apply a replicated DWN message through the
+ * server-side replication entry point.
+ */
+export type DwnReplicationApplyRequest = {
+  /** Optional data to be sent with the request. */
+  data?: any;
+
+  /** The URL of the DWN server to which the request is sent. */
+  dwnUrl: string;
+
+  /** The replicated message to apply. */
+  message: GenericMessage | SerializableDwnMessage;
+
+  /** The DID of the target tenant to which the message is addressed. */
+  targetDid: string;
+
+  /** Optional caller-provided abort signal. Honoured by the HTTP transport. */
+  signal?: AbortSignal;
+
+  /**
+   * Optional HTTP per-attempt timeout in milliseconds. When omitted, HTTP
+   * replicated apply uses a larger default for data-bearing RecordsWrite
+   * messages so large sync uploads are not aborted by the normal short budget.
+   */
+  timeoutMs?: number;
+};
+
 /**
  * Represents the JSON RPC response from a DWN server to a request, combining the results of various
  * DWN operations.

package/src/http-dwn-rpc-client.ts

@@ -1,10 +1,13 @@
 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 { DwnServerInfoCache, ServerInfo } from './server-info-types.js';
 
 import { CryptoUtils } from '@enbox/crypto';
 import { DataStream } from '@enbox/dwn-sdk-js';
+import { DwnRpcError } from './dwn-rpc-error.js';
 import { DwnServerInfoCacheMemory } from './dwn-server-info-cache-memory.js';
+import { parseReplicationApplyResult } from './replication-apply-result.js';
 import { RateLimitError } from './rate-limit-error.js';
 import { sleep } from '@enbox/common';
 import { createJsonRpcRequest, JsonRpcErrorCodes, parseJson } from './json-rpc.js';
@@ -25,6 +28,9 @@ const DEFAULT_MAX_DELAY_MS = 10_000;
 /** Per-request timeout in milliseconds (prevents hung connections / SSRF). */
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 
+/** Larger per-attempt timeout for data-bearing replicated apply uploads. */
+const DEFAULT_LARGE_REPLICATED_APPLY_TIMEOUT_MS = 300_000;
+
 /** HTTP status codes that are considered retryable. */
 const RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);
 
@@ -163,7 +169,7 @@ export class HttpDwnRpcClient implements DwnRpc {
       fetchOpts.body = requestBody;
     }
 
-    const resp = await this.fetchWithRetry(request.dwnUrl, fetchOpts);
+    const resp = await this.fetchWithRetry(request.dwnUrl, fetchOpts, { requestTimeoutMs: request.timeoutMs });
 
     // After retries are exhausted, a 429 means we're still rate-limited.
     // Per-IP 429s return plain JSON (not a JSON-RPC envelope), so we must
@@ -205,7 +211,7 @@ export class HttpDwnRpcClient implements DwnRpc {
         const retryAfter = dwnRpcResponse.error.data?.retryAfterSec ?? 1;
         throw new RateLimitError(retryAfter);
       }
-      throw new Error(`(${code}) - ${message}`);
+      throw new DwnRpcError(code, message, dwnRpcResponse.error.data);
     }
 
     // Materialise the response body before attaching to the reply.
@@ -228,6 +234,65 @@ export class HttpDwnRpcClient implements DwnRpc {
     return reply as DwnRpcResponse;
   }
 
+  async applyReplicatedMessage(request: DwnReplicationApplyRequest): Promise<ReplicationApplyResult> {
+    const requestId = CryptoUtils.randomUuid();
+    const jsonRpcRequest = createJsonRpcRequest(requestId, 'dwn.applyReplicatedMessage', {
+      target  : request.targetDid,
+      message : request.message
+    });
+
+    const requestHeaders: Record<string, string> = {
+      'dwn-request': JSON.stringify(jsonRpcRequest)
+    };
+
+    const fetchOpts: RequestInit = {
+      method  : 'POST',
+      headers : requestHeaders,
+      ...(request.signal ? { signal: request.signal } : {}),
+    };
+
+    if (request.data) {
+      requestHeaders['content-type'] = 'application/octet-stream';
+      let requestBody = request.data;
+
+      if (requestBody instanceof ReadableStream) {
+        if (HttpDwnRpcClient.isBunRuntime()) {
+          const bodyBytes = await DataStream.toBytes(requestBody as ReadableStream<Uint8Array>);
+          requestBody = new Blob([bodyBytes as BlobPart], { type: 'application/octet-stream' });
+        } else {
+          (fetchOpts as Record<string, unknown>).duplex = 'half';
+        }
+      }
+
+      fetchOpts.body = requestBody;
+    }
+
+    const resp = await this.fetchWithRetry(request.dwnUrl, fetchOpts, {
+      requestTimeoutMs: request.timeoutMs ?? defaultReplicationApplyTimeoutMs(request.message),
+    });
+    if (resp.status === 429) {
+      const retryAfter = Number.parseInt(resp.headers.get('retry-after') ?? '1', 10);
+      throw new RateLimitError(retryAfter);
+    }
+
+    const responseBody = await resp.text();
+    const jsonRpcResponse = parseJson(responseBody) as JsonRpcResponse;
+    if (jsonRpcResponse == null) {
+      throw new Error(`failed to parse json rpc response. dwn url: ${request.dwnUrl}, status: ${resp.status}`);
+    }
+
+    if (jsonRpcResponse.error) {
+      const { code, message } = jsonRpcResponse.error;
+      if (code === JsonRpcErrorCodes.TooManyRequests) {
+        const retryAfter = jsonRpcResponse.error.data?.retryAfterSec ?? 1;
+        throw new RateLimitError(retryAfter);
+      }
+      throw new DwnRpcError(code, message, jsonRpcResponse.error.data);
+    }
+
+    return parseReplicationApplyResult(jsonRpcResponse.result.result);
+  }
+
   async getServerInfo(dwnUrl: string): Promise<ServerInfo> {
     const serverInfo = await this.serverInfoCache.get(dwnUrl);
     if (serverInfo) {
@@ -279,8 +344,9 @@ export class HttpDwnRpcClient implements DwnRpc {
    * retryable HTTP status codes with exponential backoff and jitter.
    * Honours the `Retry-After` response header when present.
    */
-  private async fetchWithRetry(url: string, init?: RequestInit): Promise<Response> {
+  private async fetchWithRetry(url: string, init?: RequestInit, options: { requestTimeoutMs?: number } = {}): Promise<Response> {
     const { maxRetries, baseDelayMs, maxDelayMs } = this._retryOptions;
+    const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
 
     let lastError: unknown;
     let lastResponse: Response | undefined;
@@ -290,7 +356,7 @@ export class HttpDwnRpcClient implements DwnRpc {
         // Apply a per-attempt timeout to prevent hung connections / SSRF.
         // If the caller already supplied a signal, combine it with the timeout
         // via AbortSignal.any(); otherwise create a fresh timeout signal.
-        const timeoutSignal = AbortSignal.timeout(DEFAULT_REQUEST_TIMEOUT_MS);
+        const timeoutSignal = AbortSignal.timeout(requestTimeoutMs);
         const attemptInit: RequestInit = {
           ...init,
           signal: init?.signal
@@ -328,3 +394,10 @@ export class HttpDwnRpcClient implements DwnRpc {
     throw lastError;
   }
 }
+
+function defaultReplicationApplyTimeoutMs(message: DwnReplicationApplyRequest['message']): number | undefined {
+  const dataSize = (message as { descriptor?: { dataSize?: unknown } }).descriptor?.dataSize;
+  return typeof dataSize === 'number' && dataSize > 1_048_576
+    ? DEFAULT_LARGE_REPLICATED_APPLY_TIMEOUT_MS
+    : undefined;
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './dwn-registrar.js';
+export * from './dwn-rpc-error.js';
 export * from './dwn-rpc-types.js';
 export * from './dwn-server-info-cache-memory.js';
 export * from './http-dwn-rpc-client.js';
@@ -9,6 +10,7 @@ export * from './rate-limit-error.js';
 export * from './registration-types.js';
 export * from './rpc-client.js';
 export * from './server-info-types.js';
+export * from './ws-payload-size.js';
 // `./utils.js` removed: `concatenateUrl` (its only export) lives in
 // `@enbox/common` now — import from there if you need it.
 export * from './web-socket-clients.js';

package/src/json-rpc-socket.ts

@@ -177,12 +177,17 @@ export class JsonRpcSocket {
   public async request(request: JsonRpcRequest): Promise<JsonRpcResponse> {
     return new Promise((resolve, reject) => {
       request.id ??= CryptoUtils.randomUuid();
+      const timeout = setTimeout(() => {
+        this.messageHandlers.delete(request.id!);
+        reject(new Error('request timed out'));
+      }, this.responseTimeout);
 
       const handleResponse = (event: { data: any }):void => {
         const jsonRpsResponse = parseJson(toText(event.data)) as JsonRpcResponse;
         if (jsonRpsResponse.id === request.id) {
           // if the incoming response id matches the request id, we will remove the listener and resolve the response
           this.messageHandlers.delete(request.id);
+          clearTimeout(timeout);
           return resolve(jsonRpsResponse);
         }
       };
@@ -190,12 +195,6 @@ export class JsonRpcSocket {
       // add the listener to the map of message handlers
       this.messageHandlers.set(request.id!, handleResponse);
       this.send(request);
-
-      // reject this promise if we don't receive any response back within the timeout period
-      setTimeout(() => {
-        this.messageHandlers.delete(request.id!);
-        reject(new Error('request timed out'));
-      }, this.responseTimeout);
     });
   }
 

package/src/replication-apply-result.ts

@@ -0,0 +1,92 @@
+import type { DependencyRef, ReplicationApplyResult } from '@enbox/dwn-sdk-js';
+
+import { DwnRpcError } from './dwn-rpc-error.js';
+import { JsonRpcErrorCodes } from './json-rpc.js';
+
+const deferredReasons = new Set(['tenant-inactive', 'resolver-unavailable', 'storage']);
+
+export function parseReplicationApplyResult(value: unknown): ReplicationApplyResult {
+  if (!isObject(value) || typeof value.kind !== 'string') {
+    throw malformedReplicationApplyResult('result must be an object with a string kind');
+  }
+
+  switch (value.kind) {
+    case 'Applied':
+    case 'Duplicate':
+    case 'Superseded':
+      return { kind: value.kind };
+    case 'Incomplete':
+      if (!Array.isArray(value.missing) || !value.missing.every(isDependencyRef)) {
+        throw malformedReplicationApplyResult('Incomplete result must include missing dependency refs');
+      }
+      return { kind: 'Incomplete', missing: value.missing };
+    case 'Invalid':
+      if (typeof value.reason !== 'string') {
+        throw malformedReplicationApplyResult('Invalid result must include a string reason');
+      }
+      return { kind: 'Invalid', reason: value.reason };
+    case 'Deferred':
+      if (typeof value.reason !== 'string' || !deferredReasons.has(value.reason)) {
+        throw malformedReplicationApplyResult('Deferred result must include a valid reason');
+      }
+      return { kind: 'Deferred', reason: value.reason as Extract<ReplicationApplyResult, { kind: 'Deferred' }>['reason'] };
+    default:
+      throw malformedReplicationApplyResult(`unknown result kind ${value.kind}`);
+  }
+}
+
+function malformedReplicationApplyResult(detail: string): DwnRpcError {
+  return new DwnRpcError(
+    JsonRpcErrorCodes.InternalError,
+    `malformed dwn.applyReplicatedMessage result: ${detail}`,
+  );
+}
+
+function isDependencyRef(value: unknown): value is DependencyRef {
+  if (!isObject(value) || typeof value.type !== 'string') {
+    return false;
+  }
+  if (!isOptionalString(value.messageCid) || !isOptionalBoolean(value.terminal)) {
+    return false;
+  }
+
+  switch (value.type) {
+    case 'Protocol':
+      return typeof value.protocol === 'string';
+    case 'InitialWrite':
+      return typeof value.recordId === 'string' && isOptionalString(value.protocol);
+    case 'Parent':
+      return typeof value.recordId === 'string' && typeof value.protocol === 'string';
+    case 'Ancestor':
+      return typeof value.recordId === 'string' && isOptionalString(value.protocol);
+    case 'Role':
+      return typeof value.protocol === 'string' &&
+        typeof value.protocolPath === 'string' &&
+        typeof value.recipient === 'string' &&
+        isOptionalString(value.contextPrefix);
+    case 'Grant':
+      return typeof value.permissionGrantId === 'string';
+    case 'KeyDelivery':
+      return typeof value.protocol === 'string' && typeof value.contextId === 'string';
+    case 'CrossProtocolRef':
+      return typeof value.protocol === 'string' && typeof value.recordId === 'string';
+    case 'RecordData':
+      return typeof value.recordId === 'string' &&
+        typeof value.dataCid === 'string' &&
+        isOptionalString(value.protocol);
+    default:
+      return false;
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isOptionalString(value: unknown): value is string | undefined {
+  return value === undefined || typeof value === 'string';
+}
+
+function isOptionalBoolean(value: unknown): value is boolean | undefined {
+  return value === undefined || typeof value === 'boolean';
+}

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
@@ -55,6 +77,9 @@ export class WebSocketDwnRpcClient implements DwnRpc {
   public get transportProtocols(): string[] { return ['ws:', 'wss:']; }
   // a map of dwn host to WebSocket connection
   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 +89,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,6 +101,59 @@ 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 existing = WebSocketDwnRpcClient.connections.get(url.host);
+    if (existing !== undefined) {
+      return existing;
+    }
+
+    let pending = WebSocketDwnRpcClient.pendingConnections.get(url.host);
+    if (pending === undefined) {
+      pending = WebSocketDwnRpcClient.createConnection(url)
+        .then((connection) => {
+          WebSocketDwnRpcClient.connections.set(url.host, connection);
+          return connection;
+        })
+        .catch((error: unknown) => {
+          throw new Error(`Error connecting to ${url.host}: ${(error as Error).message}`);
+        })
+        .finally(() => {
+          WebSocketDwnRpcClient.pendingConnections.delete(url.host);
+        });
+      WebSocketDwnRpcClient.pendingConnections.set(url.host, pending);
+    }
+
+    return pending;
+  }
+
   /**
    * Creates a new `SocketConnection` with lifecycle wiring for reconnection.
    */
@@ -141,6 +208,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 +366,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);
+}