@enbox/dwn-clients 0.0.2

package/src/json-rpc-socket.ts

@@ -0,0 +1,198 @@
+import type { JsonRpcId, JsonRpcRequest, JsonRpcResponse } from './json-rpc.js';
+
+import { CryptoUtils } from '@enbox/crypto';
+import { createJsonRpcSubscriptionRequest, parseJson } from './json-rpc.js';
+
+/**
+ * Converts WebSocket message data to a string.
+ * Bun's native WebSocket delivers `event.data` as an `ArrayBuffer`,
+ * whereas Node.js `ws` delivers it as a `string`.
+ */
+function toText(data: unknown): string {
+  if (typeof data === 'string') {
+    return data;
+  }
+  if (data instanceof ArrayBuffer) {
+    return new TextDecoder().decode(data);
+  }
+  // Buffer / Uint8Array fallback
+  if (data instanceof Uint8Array) {
+    return new TextDecoder().decode(data);
+  }
+  return String(data);
+}
+
+// These were arbitrarily chosen, but can be modified via connect options
+const CONNECT_TIMEOUT = 3_000;
+const RESPONSE_TIMEOUT = 30_000;
+
+export interface JsonRpcSocketOptions {
+  /** socket connection timeout in milliseconds */
+  connectTimeout?: number;
+  /** response timeout for rpc requests in milliseconds */
+  responseTimeout?: number;
+  /** optional connection close handler */
+  onclose?: () => void;
+  /** optional socket error handler */
+  onerror?: (error?: any) => void;
+}
+
+/**
+ * JSON RPC Socket Client for WebSocket request/response and long-running subscriptions.
+ */
+export class JsonRpcSocket {
+  private messageHandlers: Map<JsonRpcId, (event: { data: any }) => void> = new Map();
+
+  private constructor(private socket: WebSocket, private responseTimeout: number) {}
+
+  public static async connect(url: string, options: JsonRpcSocketOptions = {}): Promise<JsonRpcSocket> {
+    const { connectTimeout = CONNECT_TIMEOUT, responseTimeout = RESPONSE_TIMEOUT, onclose, onerror } = options;
+
+    const socket = new WebSocket(url);
+
+    if (!onclose) {
+      socket.onclose = ():void => {
+        console.info(`JSON RPC Socket close ${url}`);
+      };
+    } else {
+      socket.onclose = onclose;
+    }
+
+    if (!onerror) {
+      socket.onerror = (error?: any):void => {
+        console.error(`JSON RPC Socket error ${url}`, error);
+      };
+    } else {
+      socket.onerror = onerror;
+    }
+
+    return new Promise<JsonRpcSocket>((resolve, reject) => {
+      socket.addEventListener('open', () => {
+        const jsonRpcSocket = new JsonRpcSocket(socket, responseTimeout);
+
+        socket.addEventListener('message', (event: { data: any }) => {
+          const jsonRpcResponse = parseJson(toText(event.data)) as JsonRpcResponse;
+          const handler = jsonRpcSocket.messageHandlers.get(jsonRpcResponse.id);
+          if (handler) {
+            handler(event);
+          }
+        });
+
+        resolve(jsonRpcSocket);
+      });
+
+      socket.addEventListener('error', (error: any) => {
+        reject(error);
+      });
+
+      setTimeout(() => reject(new Error('connect timed out')), connectTimeout);
+    });
+  }
+
+  public close(): void {
+    this.socket.close();
+  }
+
+  /**
+   * Sends a JSON-RPC request through the socket and waits for a single response.
+   */
+  public async request(request: JsonRpcRequest): Promise<JsonRpcResponse> {
+    return new Promise((resolve, reject) => {
+      request.id ??= CryptoUtils.randomUuid();
+
+      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);
+          return resolve(jsonRpsResponse);
+        }
+      };
+
+      // 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);
+    });
+  }
+
+  /**
+   * Sends a JSON-RPC request through the socket and keeps a listener open to read associated responses as they arrive.
+   * Returns a close method to clean up the listener.
+   */
+  public async subscribe(request: JsonRpcRequest, listener: (response: JsonRpcResponse) => void): Promise<{
+    response: JsonRpcResponse;
+    close?: () => Promise<void>;
+   }> {
+
+    if (!request.method.startsWith('rpc.subscribe.')) {
+      throw new Error('subscribe rpc requests must include the `rpc.subscribe` prefix');
+    }
+
+    if (!request.subscription) {
+      throw new Error('subscribe rpc requests must include subscribe options');
+    }
+
+    const subscriptionId = request.subscription.id;
+
+    // Preserve any existing handler for this subscriptionId so that a rejected
+    // duplicate-subscribe attempt does not clobber an active subscription.
+    const existingHandler = this.messageHandlers.get(subscriptionId);
+
+    const socketEventListener = (event: { data: any }):void => {
+      const jsonRpcResponse = parseJson(toText(event.data)) as JsonRpcResponse;
+      if (jsonRpcResponse.id === subscriptionId) {
+        if (jsonRpcResponse.error !== undefined) {
+          // remove the event listener upon receipt of a JSON RPC Error.
+          this.messageHandlers.delete(subscriptionId);
+          this.closeSubscription(subscriptionId).catch(() => {
+            // swallow timeout errors; the subscription is already cleaned up locally.
+          });
+        }
+        listener(jsonRpcResponse);
+      }
+    };
+
+    this.messageHandlers.set(subscriptionId, socketEventListener);
+
+    const response = await this.request(request);
+    if (response.error) {
+      // Restore the previous handler if one existed, otherwise clean up.
+      if (existingHandler) {
+        this.messageHandlers.set(subscriptionId, existingHandler);
+      } else {
+        this.messageHandlers.delete(subscriptionId);
+      }
+      return { response };
+    }
+
+    // clean up listener and create a `rpc.subscribe.close` message to use when closing this JSON RPC subscription
+    const close = async (): Promise<void> => {
+      this.messageHandlers.delete(subscriptionId);
+      await this.closeSubscription(subscriptionId);
+    };
+
+    return {
+      response,
+      close
+    };
+  }
+
+  private closeSubscription(id: JsonRpcId): Promise<JsonRpcResponse> {
+    const requestId = CryptoUtils.randomUuid();
+    const request = createJsonRpcSubscriptionRequest(requestId, 'rpc.subscribe.close', {}, id);
+    return this.request(request);
+  }
+
+  /**
+   * Sends a JSON-RPC request through the socket. You must subscribe to a message listener separately to capture the response.
+   */
+  public send(request: JsonRpcRequest):void {
+    this.socket.send(JSON.stringify(request));
+  }
+}

package/src/json-rpc.ts

@@ -0,0 +1,142 @@
+export type JsonRpcId = string | number | null;
+export type JsonRpcParams = any;
+export type JsonRpcVersion = '2.0';
+
+export interface JsonRpcRequest {
+  jsonrpc: JsonRpcVersion;
+  id?: JsonRpcId;
+  method: string;
+  params?: any;
+  /** JSON RPC Subscription Extension Parameters */
+  subscription?: { id: JsonRpcId };
+}
+
+export interface JsonRpcError {
+  code: JsonRpcErrorCodes;
+  message: string;
+  data?: any;
+}
+
+export interface JsonRpcSubscription {
+  /** JSON RPC Id of the Subscription Request */
+  id: JsonRpcId;
+  close: () => Promise<void>;
+}
+
+export enum JsonRpcErrorCodes {
+  // JSON-RPC 2.0 pre-defined errors
+  InvalidRequest = -32600,
+  MethodNotFound = -32601,
+  InvalidParams = -32602,
+  InternalError = -32603,
+  ParseError = -32700,
+  TransportError = -32300,
+
+  // App defined errors
+  BadRequest = -50400, // equivalent to HTTP Status 400
+  Unauthorized = -50401, // equivalent to HTTP Status 401
+  Forbidden = -50403, // equivalent to HTTP Status 403
+  Conflict = -50409, // equivalent to HTTP Status 409
+}
+
+export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+
+export interface JsonRpcSuccessResponse {
+  jsonrpc: JsonRpcVersion;
+  id: JsonRpcId;
+  result: any;
+  error?: never;
+}
+
+export interface JsonRpcErrorResponse {
+  jsonrpc: JsonRpcVersion;
+  id: JsonRpcId;
+  result?: never;
+  error: JsonRpcError;
+}
+
+export const createJsonRpcErrorResponse = (
+  id: JsonRpcId,
+  code: JsonRpcErrorCodes,
+  message: string,
+  data?: any,
+): JsonRpcErrorResponse => {
+  const error: JsonRpcError = { code, message };
+  if (data != undefined) {
+    error.data = data;
+  }
+  return {
+    jsonrpc: '2.0',
+    id,
+    error,
+  };
+};
+
+export const createJsonRpcNotification = (
+  method: string,
+  params?: any,
+): JsonRpcRequest => {
+  return {
+    jsonrpc: '2.0',
+    method,
+    params,
+  };
+};
+
+export const createJsonRpcRequest = (
+  id: JsonRpcId,
+  method: string,
+  params?: JsonRpcParams,
+): JsonRpcRequest => {
+  return {
+    jsonrpc: '2.0',
+    id,
+    method,
+    params,
+  };
+};
+
+/**
+ * Creates a JSON-RPC subscription request.
+ *
+ * The caller is responsible for providing the full method name including
+ * any `rpc.subscribe.` prefix.
+ */
+export const createJsonRpcSubscriptionRequest = (
+  id: JsonRpcId,
+  method: string,
+  params?: any,
+  subscriptionId?: JsonRpcId,
+): JsonRpcRequest => {
+  return {
+    jsonrpc      : '2.0',
+    id,
+    method,
+    params,
+    subscription : {
+      id: subscriptionId ?? null,
+    }
+  };
+};
+
+export const createJsonRpcSuccessResponse = (
+  id: JsonRpcId,
+  result?: any,
+): JsonRpcSuccessResponse => {
+  return {
+    jsonrpc : '2.0',
+    id,
+    result  : result ?? null,
+  };
+};
+
+/**
+ * Safely parses a JSON string, returning `null` on failure instead of throwing.
+ */
+export function parseJson(text: string): object | null {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}

package/src/registration-types.ts

@@ -0,0 +1,26 @@
+/**
+ * Proof-of-work challenge returned by `GET /registration/proof-of-work`.
+ */
+export type ProofOfWorkChallengeModel = {
+  challengeNonce: string;
+  maximumAllowedHashValue: string;
+};
+
+/**
+ * Registration data included in the `POST /registration` request body.
+ */
+export type RegistrationData = {
+  did: string;
+  termsOfServiceHash: string;
+};
+
+/**
+ * Full registration request body for `POST /registration`.
+ */
+export type RegistrationRequest = {
+  proofOfWork: {
+    challengeNonce: string;
+    responseNonce: string;
+  },
+  registrationData: RegistrationData
+};

package/src/rpc-client.ts

@@ -0,0 +1,160 @@
+import type { JsonRpcResponse } from './json-rpc.js';
+import type { DwnRpc, DwnRpcRequest, DwnRpcResponse } from './dwn-rpc-types.js';
+import type { DwnServerInfoRpc, ServerInfo } from './server-info-types.js';
+
+import { createJsonRpcRequest } from './json-rpc.js';
+import { CryptoUtils } from '@enbox/crypto';
+import { HttpDwnRpcClient } from './http-dwn-rpc-client.js';
+import { WebSocketDwnRpcClient } from './web-socket-clients.js';
+
+/**
+ * Interface that can be implemented to communicate with {@link Web5Agent | Web5 Agent}
+ * implementations via JSON-RPC.
+ */
+export interface DidRpc {
+  get transportProtocols(): string[]
+  sendDidRequest(request: DidRpcRequest): Promise<DidRpcResponse>
+}
+
+export enum DidRpcMethod {
+  Create = 'did.create',
+  Resolve = 'did.resolve'
+}
+
+export type DidRpcRequest = {
+  data: string;
+  method: DidRpcMethod;
+  url: string;
+};
+
+export type DidRpcResponse = {
+  data?: string;
+  ok: boolean;
+  status: RpcStatus;
+};
+
+export type RpcStatus = {
+  code: number;
+  message: string;
+};
+
+export interface Web5Rpc extends DwnRpc, DidRpc, DwnServerInfoRpc {}
+
+/**
+ * Client used to communicate with Dwn Servers
+ */
+export class Web5RpcClient implements Web5Rpc {
+  private transportClients: Map<string, Web5Rpc>;
+
+  constructor(clients: Web5Rpc[] = []) {
+    this.transportClients = new Map();
+
+    // include http and socket clients as default.
+    // can be overwritten for 'http:', 'https:', 'ws: or ':wss' if instantiated with other clients.
+    clients = [new HttpWeb5RpcClient(), new WebSocketWeb5RpcClient(), ...clients];
+
+    for (const client of clients) {
+      for (const transportScheme of client.transportProtocols) {
+        this.transportClients.set(transportScheme, client);
+      }
+    }
+  }
+
+  get transportProtocols(): string[] {
+    return Array.from(this.transportClients.keys());
+  }
+
+  async sendDidRequest(request: DidRpcRequest): Promise<DidRpcResponse> {
+    // URL() will throw if provided `url` is invalid.
+    const url = new URL(request.url);
+
+    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.sendDidRequest(request);
+  }
+
+  sendDwnRequest(request: DwnRpcRequest): Promise<DwnRpcResponse> {
+    // will throw if url is invalid
+    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.sendDwnRequest(request);
+  }
+
+  async getServerInfo(dwnUrl: string): Promise<ServerInfo> {
+    // will throw if url is invalid
+    const url = new URL(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.getServerInfo(dwnUrl);
+  }
+}
+
+export class HttpWeb5RpcClient extends HttpDwnRpcClient implements Web5Rpc {
+  async sendDidRequest(request: DidRpcRequest): Promise<DidRpcResponse> {
+    const requestId = CryptoUtils.randomUuid();
+    const jsonRpcRequest = createJsonRpcRequest(requestId, request.method, {
+      data: request.data
+    });
+
+    const httpRequest = new Request(request.url, {
+      method  : 'POST',
+      headers : {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(jsonRpcRequest),
+    });
+
+    let jsonRpcResponse: JsonRpcResponse;
+
+    try {
+      const response = await fetch(httpRequest);
+
+      if (response.ok) {
+        jsonRpcResponse = await response.json();
+
+        // If the response is an error, throw an error.
+        if (jsonRpcResponse.error) {
+          const { code, message } = jsonRpcResponse.error;
+          throw new Error(`JSON RPC (${code}) - ${message}`);
+        }
+      } else {
+        throw new Error(`HTTP (${response.status}) - ${response.statusText}`);
+      }
+    } catch (error: any) {
+      throw new Error(`Error encountered while processing response from ${request.url}: ${error.message}`);
+    }
+
+    return jsonRpcResponse.result as DidRpcResponse;
+  }
+}
+
+export class WebSocketWeb5RpcClient extends WebSocketDwnRpcClient implements Web5Rpc {
+  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/server-info-types.ts

@@ -0,0 +1,29 @@
+import type { KeyValueStore } from '@enbox/common';
+
+export type ServerInfo = {
+  /** the maximum file size the user can request to store */
+  maxFileSize: number,
+  /**
+   * an array of strings representing the server's registration requirements.
+   *
+   * ie. ['proof-of-work-sha256-v0', 'terms-of-service']
+   */
+  registrationRequirements: string[],
+  /** the DWN server's package name */
+  server: string,
+  /** the DWN SDK version used by the server */
+  sdkVersion: string,
+  /** the base URL of the DWN server */
+  url: string,
+  /** the DWN server version */
+  version: string,
+  /** whether web socket support is enabled on this server */
+  webSocketSupport: boolean,
+};
+
+export interface DwnServerInfoCache extends KeyValueStore<string, ServerInfo| undefined> {}
+
+export interface DwnServerInfoRpc {
+  /** retrieves the DWN Sever info, used to detect features such as WebSocket Subscriptions */
+  getServerInfo(url: string): Promise<ServerInfo>;
+}

package/src/utils.ts

@@ -0,0 +1,14 @@
+/** Concatenates a base URL and a path ensuring that there is exactly one slash between them. */
+export function concatenateUrl(baseUrl: string, path: string): string {
+  // Remove trailing slash from baseUrl if it exists
+  if (baseUrl.endsWith('/')) {
+    baseUrl = baseUrl.slice(0, -1);
+  }
+
+  // Remove leading slash from path if it exists
+  if (path.startsWith('/')) {
+    path = path.slice(1);
+  }
+
+  return `${baseUrl}/${path}`;
+}

package/src/web-socket-clients.ts

@@ -0,0 +1,107 @@
+import type { JsonRpcSocketOptions } from './json-rpc-socket.js';
+import type { DwnRpc, DwnRpcRequest, DwnRpcResponse, DwnSubscriptionHandler } from './dwn-rpc-types.js';
+import type { GenericMessage, MessageSubscription, UnionMessageReply } from '@enbox/dwn-sdk-js';
+
+import { CryptoUtils } from '@enbox/crypto';
+import { JsonRpcSocket } from './json-rpc-socket.js';
+import { createJsonRpcRequest, createJsonRpcSubscriptionRequest } from './json-rpc.js';
+
+interface SocketConnection {
+  socket: JsonRpcSocket;
+  subscriptions: Map<string, MessageSubscription>;
+}
+
+export class WebSocketDwnRpcClient implements DwnRpc {
+  public get transportProtocols(): string[] { return ['ws:', 'wss:']; }
+  // a map of dwn host to WebSocket connection
+  private static connections = new Map<string, SocketConnection>();
+
+  async sendDwnRequest(request: DwnRpcRequest, jsonRpcSocketOptions?: JsonRpcSocketOptions): Promise<DwnRpcResponse> {
+
+    // validate that the dwn URL provided is a valid WebSocket URL
+    const url = new URL(request.dwnUrl);
+    if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+      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 socket = await JsonRpcSocket.connect(url.toString(), jsonRpcSocketOptions);
+        const subscriptions = new Map();
+        WebSocketDwnRpcClient.connections.set(url.host, { socket, subscriptions });
+      } catch (error) {
+        throw new Error(`Error connecting to ${url.host}: ${(error as Error).message}`);
+      }
+    }
+
+    const connection = WebSocketDwnRpcClient.connections.get(url.host)!;
+    const { targetDid, message, subscriptionHandler } = request;
+
+    if (subscriptionHandler) {
+      return WebSocketDwnRpcClient.subscriptionRequest(connection, targetDid, message, subscriptionHandler);
+    }
+
+    return WebSocketDwnRpcClient.processMessage(connection, targetDid, message);
+  }
+
+  private static async processMessage(
+    connection: SocketConnection, target: string, message: GenericMessage
+  ): Promise<DwnRpcResponse> {
+    const requestId = CryptoUtils.randomUuid();
+    const request = createJsonRpcRequest(requestId, 'dwn.processMessage', { target, message });
+
+    const { socket } = connection;
+    const response = await socket.request(request);
+
+    const { error, result } = response;
+    if (error !== undefined) {
+      throw new Error(`error sending DWN request: ${error.message}`);
+    }
+
+    return result.reply as DwnRpcResponse;
+  }
+
+  private static async subscriptionRequest(
+    connection: SocketConnection, target:string, message: GenericMessage, messageHandler: DwnSubscriptionHandler
+  ): Promise<DwnRpcResponse> {
+    const requestId = CryptoUtils.randomUuid();
+    const subscriptionId = CryptoUtils.randomUuid();
+    const request = createJsonRpcSubscriptionRequest(
+      requestId, 'rpc.subscribe.dwn.processMessage', { target, message }, subscriptionId
+    );
+
+    const { socket, subscriptions } = connection;
+    const { response, close } = await socket.subscribe(request, (response) => {
+      const { result, error } = response;
+      if (error) {
+
+        // if there is an error, close the subscription and delete it from the connection
+        const subscription = subscriptions.get(subscriptionId);
+        if (subscription) {
+          subscription.close();
+        }
+
+        subscriptions.delete(subscriptionId);
+        return;
+      }
+
+      const { event } = result;
+      messageHandler(event);
+    });
+
+    const { error, result } = response;
+    if (error) {
+      throw new Error(`could not subscribe via jsonrpc socket: ${error.message}`);
+    }
+
+    const { reply } = result as { reply: UnionMessageReply };
+    if (reply.subscription && close) {
+      subscriptions.set(subscriptionId, { ...reply.subscription, close });
+      reply.subscription.close = close;
+    }
+
+    return reply;
+  }
+}