@enbox/dwn-server 0.0.1

package/src/json-rpc-handlers/subscription/close.ts

@@ -0,0 +1,59 @@
+import { v4 as uuidv4 } from 'uuid';
+
+import { DwnServerErrorCode } from '../../dwn-error.js';
+import type {
+  HandlerResponse,
+  JsonRpcHandler,
+} from '../../lib/json-rpc-router.js';
+
+import type { JsonRpcId, JsonRpcResponse } from '../../lib/json-rpc.js';
+import {
+  createJsonRpcErrorResponse,
+  createJsonRpcSuccessResponse,
+  JsonRpcErrorCodes,
+} from '../../lib/json-rpc.js';
+
+/**
+ * Closes a subscription tied to a specific `SocketConnection`.
+ *
+ * @param jsonRpcRequest must include JsonRpcId of the subscription request within a `subscription object`.
+ * @param context must include the associated `SocketConnection`.
+ *
+ */
+export const handleSubscriptionsClose: JsonRpcHandler = async (
+  jsonRpcRequest,
+  context,
+) => {
+  const requestId = jsonRpcRequest.id ?? uuidv4();
+  if (context.socketConnection === undefined) {
+    const jsonRpcResponse = createJsonRpcErrorResponse(requestId, JsonRpcErrorCodes.InvalidRequest, 'socket connection does not exist');
+    return { jsonRpcResponse };
+  }
+
+  if (jsonRpcRequest.subscription === undefined) {
+    const jsonRpcResponse = createJsonRpcErrorResponse(requestId, JsonRpcErrorCodes.InvalidRequest, 'subscribe options do not exist');
+    return { jsonRpcResponse };
+  }
+
+  const { socketConnection } = context;
+  const { id } = jsonRpcRequest.subscription as { id: JsonRpcId };
+
+  let jsonRpcResponse:JsonRpcResponse;
+  try {
+    // closing the subscription and cleaning up the reference within the given connection.
+    await socketConnection.closeSubscription(id);
+    jsonRpcResponse = createJsonRpcSuccessResponse(requestId, { reply: { status: 200, detail: 'Accepted' } });
+  } catch(error) {
+    if (error.code === DwnServerErrorCode.ConnectionSubscriptionJsonRpcIdNotFound) {
+      jsonRpcResponse = createJsonRpcErrorResponse(requestId, JsonRpcErrorCodes.InvalidParams, `subscription ${id} does not exist.`);
+    } else {
+      jsonRpcResponse = createJsonRpcErrorResponse(
+        requestId,
+        JsonRpcErrorCodes.InternalError,
+        `unknown subscription close error for ${id}: ${error.message}`
+      );
+    }
+  }
+
+  return { jsonRpcResponse } as HandlerResponse;
+}

package/src/json-rpc-handlers/subscription/index.ts

@@ -0,0 +1 @@
+export * from './close.js';

package/src/json-rpc-socket.ts

@@ -0,0 +1,155 @@
+import log from 'loglevel';
+import { v4 as uuidv4 } from 'uuid';
+import WebSocket from 'ws';
+
+import type { JsonRpcId, JsonRpcRequest, JsonRpcResponse } from "./lib/json-rpc.js";
+import { createJsonRpcSubscriptionRequest } from "./lib/json-rpc.js";
+
+// 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 constructor(private socket: WebSocket, private responseTimeout: number) {}
+
+  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 => {
+        log.info(`JSON RPC Socket close ${url}`);
+      };
+    } else {
+      socket.onclose = onclose;
+    }
+
+    if (!onerror) {
+      socket.onerror = (error?: any):void => {
+        log.error(`JSON RPC Socket error ${url}`, error);
+      };
+    } else {
+      socket.onerror = onerror;
+    }
+
+    return new Promise<JsonRpcSocket>((resolve, reject) => {
+      socket.addEventListener('open', () => {
+        resolve(new JsonRpcSocket(socket, responseTimeout));
+      });
+
+      socket.addEventListener('error', (error) => {
+        reject(error);
+      });
+
+      setTimeout(() => reject, connectTimeout);
+    });
+  }
+
+  close(): void {
+    this.socket.close();
+  }
+
+  /**
+   * Sends a JSON-RPC request through the socket and waits for a single response.
+   */
+  async request(request: JsonRpcRequest): Promise<JsonRpcResponse> {
+    return new Promise((resolve, reject) => {
+      request.id ??= uuidv4();
+
+      const handleResponse = (event: { data: any }):void => {
+        const jsonRpsResponse = JSON.parse(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.socket.removeEventListener('message', handleResponse);
+          return resolve(jsonRpsResponse);
+        }
+      };
+      // subscribe to the listener before sending the request
+      this.socket.addEventListener('message', handleResponse);
+      this.send(request);
+
+      // reject this promise if we don't receive any response back within the timeout period
+      setTimeout(() => {
+        this.socket.removeEventListener('message', handleResponse);
+        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.
+   */
+  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;
+    const socketEventListener = (event: { data: any }):void => {
+      const jsonRpcResponse = JSON.parse(event.data.toString()) as JsonRpcResponse;
+      if (jsonRpcResponse.id === subscriptionId) {
+        if (jsonRpcResponse.error !== undefined) {
+          // remove the event listener upon receipt of a JSON RPC Error.
+          this.socket.removeEventListener('message', socketEventListener);
+          this.closeSubscription(subscriptionId);
+        }
+        listener(jsonRpcResponse);
+      }
+    };
+    this.socket.addEventListener('message', socketEventListener);
+
+    const response = await this.request(request);
+    if (response.error) {
+      this.socket.removeEventListener('message', socketEventListener);
+      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.socket.removeEventListener('message', socketEventListener);
+      await this.closeSubscription(subscriptionId);
+    };
+
+    return {
+      response,
+      close
+    };
+  }
+
+  private closeSubscription(id: JsonRpcId): Promise<JsonRpcResponse> {
+    const requestId = uuidv4();
+    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.
+   */
+  send(request: JsonRpcRequest):void {
+    this.socket.send(JSON.stringify(request));
+  }
+}

package/src/lib/http-server-shutdown-handler.ts

@@ -0,0 +1,79 @@
+import type { Server } from 'http';
+import type { Socket } from 'net';
+
+const SOCKET_IDLE_SYMBOL = Symbol('idle');
+
+export class HttpServerShutdownHandler {
+  private tcpSockets: { [socketId: number]: Socket };
+  private tcpSocketId: number;
+  private server: Server;
+  private stopping: boolean;
+
+  constructor(server: Server) {
+    this.tcpSockets = {};
+    this.tcpSocketId = 1;
+    this.server = server;
+    this.stopping = false;
+
+    // This event is emitted when a new TCP stream is established
+    this.server.on('connection', (socket) => {
+      // set socket to idle. this same socket will be accessible within the `http.on('request', (req, res))` event listener
+      // as `request.connection`
+      socket[SOCKET_IDLE_SYMBOL] = true;
+      const tcpSocketId = this.tcpSocketId++;
+      this.tcpSockets[tcpSocketId] = socket;
+
+      // This event is emitted when a tcp stream is `destroy`ed
+      socket.on('close', () => {
+        delete this.tcpSockets[tcpSocketId];
+      });
+    });
+
+    // Emitted each time there is a request. There may be multiple requests
+    // per connection (in the case of HTTP Keep-Alive connections).
+    this.server.on('request', (request, response) => {
+      const { socket } = request;
+
+      // set __idle to false because this socket is being used for an incoming request
+      socket[SOCKET_IDLE_SYMBOL] = false;
+
+      // Emitted when the response has been sent. More specifically, this event is emitted
+      // when the last segment of the response headers and body have been handed off to the
+      // operating system for transmission over the network.
+      // It does not imply that the client has received anything yet.
+      response.on('finish', () => {
+        // set __idle back to true because the socket has finished facilitating a request. This socket may be used again without being
+        // destroyed if keep-alive is being leveraged
+        socket[SOCKET_IDLE_SYMBOL] = true;
+
+        if (this.stopping) {
+          socket.destroy();
+        }
+      });
+    });
+  }
+
+  stop(callback): void {
+    this.stopping = true;
+
+    // Stops the server from accepting new connections and keeps existing connections. This function is asynchronous,
+    // the server is finally closed when all connections are ended and the server emits a 'close' event.
+    // The optional callback will be called once the 'close' event occurs.
+    // The callback will be called with an Error as its only argument if the server was not open when close is called.
+    this.server.close(() => {
+      this.tcpSocketId = 0;
+      this.stopping = false;
+      callback();
+    });
+
+    // close all idle sockets. the remaining sockets facilitating active requests
+    // will be closed after they've served responses back.
+    for (const tcpSocketId in this.tcpSockets) {
+      const socket = this.tcpSockets[tcpSocketId];
+
+      if (socket[SOCKET_IDLE_SYMBOL]) {
+        socket.destroy();
+      }
+    }
+  }
+}

package/src/lib/json-rpc-router.ts

@@ -0,0 +1,52 @@
+import type { Dwn, MessageSubscriptionHandler } from '@enbox/dwn-sdk-js';
+
+import type { Readable } from 'node:stream';
+
+import type { JsonRpcId, JsonRpcRequest, JsonRpcResponse } from './json-rpc.js';
+import type { SocketConnection } from '../connection/socket-connection.js';
+
+export type RequestContext = {
+  transport: 'http' | 'ws';
+  dwn: Dwn;
+  /** the socket connection associated with this request if over sockets */
+  socketConnection?: SocketConnection;
+  subscriptionRequest?: {
+    /** The JsonRpcId of the subscription handler */
+    id: JsonRpcId; 
+    /** The `MessageEvent` handler associated with a subscription request, only used in `ws` requests */
+    subscriptionHandler: MessageSubscriptionHandler;
+  }
+  /** The `Readable` stream associated with a `RecordsWrite` request only used in `http` requests */
+  dataStream?: Readable;
+};
+
+export type HandlerResponse = {
+  jsonRpcResponse: JsonRpcResponse;
+  dataStream?: Readable;
+};
+
+export type JsonRpcHandler = (
+  JsonRpcRequest: JsonRpcRequest,
+  context: RequestContext,
+) => Promise<HandlerResponse>;
+
+export class JsonRpcRouter {
+  private methodHandlers: { [method: string]: JsonRpcHandler };
+
+  constructor() {
+    this.methodHandlers = {};
+  }
+
+  on(methodName: string, handler: JsonRpcHandler): void {
+    this.methodHandlers[methodName] = handler;
+  }
+
+  async handle(
+    rpcRequest: JsonRpcRequest,
+    context: RequestContext,
+  ): Promise<HandlerResponse> {
+    const handler = this.methodHandlers[rpcRequest.method];
+
+    return await handler(rpcRequest, context);
+  }
+}

package/src/lib/json-rpc.ts

@@ -0,0 +1,126 @@
+export type JsonRpcId = string | number | null;
+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,
+
+  /** App defined error equivalent to HTTP Status 400 */
+  BadRequest = -50400,
+  /** App defined error equivalent to HTTP Status 401 */
+  Unauthorized = -50401,
+  /** App defined error equivalent to HTTP Status 403 */
+  Forbidden = -50403,
+}
+
+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 createJsonRpcSubscriptionRequest = (
+  id: JsonRpcId,
+  method: string,
+  params?: any,
+  subscriptionId?: JsonRpcId
+): JsonRpcRequest => {
+  return {
+    jsonrpc: '2.0',
+    id,
+    method,
+    params,
+    subscription: {
+      id: subscriptionId,
+    }
+  }
+}
+
+export const createJsonRpcRequest = (
+  id: JsonRpcId,
+  method: string,
+  params?: any,
+): JsonRpcRequest => {
+  return {
+    jsonrpc: '2.0',
+    id,
+    method,
+    params,
+  };
+};
+
+export const createJsonRpcSuccessResponse = (
+  id: JsonRpcId,
+  result?: any,
+): JsonRpcSuccessResponse => {
+  return {
+    jsonrpc: '2.0',
+    id,
+    result: result ?? null,
+  };
+};

package/src/main.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// node.js 18 and earlier, needs globalThis.crypto polyfill. needed for dwn-sdk-js
+import { webcrypto } from 'node:crypto';
+
+import { DwnServer } from './dwn-server.js';
+
+if (!globalThis.crypto) {
+  // @ts-ignore
+  globalThis.crypto = webcrypto;
+}
+
+const dwnServer = new DwnServer();
+
+await dwnServer.start();

package/src/metrics.ts

@@ -0,0 +1,14 @@
+import { Counter, Histogram } from 'prom-client';
+
+export const requestCounter = new Counter({
+  name: 'dwn_requests_total',
+  help: 'all dwn requests processed',
+  labelNames: ['method', 'status', 'error'],
+});
+
+export const responseHistogram = new Histogram({
+  name: 'http_response',
+  help: 'response histogram',
+  buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+  labelNames: ['route', 'code'],
+});

package/src/plugin-loader.ts

@@ -0,0 +1,17 @@
+/**
+ * A utility class for dynamically loading plugins from file paths.
+ */
+export class PluginLoader {
+  /**
+   * Dynamically loads a plugin from a file path by invoking the argument-less constructor of the default exported class.
+   */
+  public static async loadPlugin<T>(filePath: string): Promise<T> {
+    try {
+      const module = await import(filePath);
+      const instance: T = new module.default() as T;
+      return instance;
+    } catch (error) {
+      throw new Error(`Failed to load component at ${filePath}: ${error.message}`);
+    }
+  }
+}

package/src/process-handlers.ts

@@ -0,0 +1,65 @@
+import type { DwnServer } from './dwn-server.js';
+
+export const gracefulShutdown = async (dwnServer: DwnServer): Promise<void> => {
+  await dwnServer.stop();
+  console.log('http server stopped.. exiting');
+  process.exit(0);
+};
+
+export type ProcessHandlers = {
+  unhandledRejectionHandler: (reason: any, promise: Promise<any>) => void,
+  uncaughtExceptionHandler: (err: Error) => void,
+  sigintHandler: () => Promise<void>,
+  sigtermHandler: () => Promise<void>
+};
+
+export const setProcessHandlers = (dwnServer: DwnServer): ProcessHandlers => {
+  const unhandledRejectionHandler = (reason: any, promise: Promise<any>): void => {
+    console.error(
+      `Unhandled promise rejection. Reason: ${reason}. Promise: ${JSON.stringify(
+        promise,
+      )}`,
+    );
+  };
+
+  const uncaughtExceptionHandler = (err: Error): void => {
+    console.error('Uncaught exception:', err.stack || err);
+  };
+
+  const sigintHandler = async (): Promise<void> => {
+    console.log('exit signal received [SIGINT]. starting graceful shutdown');
+    await gracefulShutdown(dwnServer);
+  };
+
+  const sigtermHandler = async (): Promise<void> => {
+    console.log('exit signal received [SIGTERM]. starting graceful shutdown');
+    await gracefulShutdown(dwnServer);
+  };
+
+  process.on('unhandledRejection', unhandledRejectionHandler);
+  process.on('uncaughtException', uncaughtExceptionHandler);
+  process.on('SIGINT', sigintHandler);
+  process.on('SIGTERM', sigtermHandler);
+
+  // Store handlers to be able to remove them later
+  return {
+    unhandledRejectionHandler,
+    uncaughtExceptionHandler,
+    sigintHandler,
+    sigtermHandler
+  };
+};
+
+export const removeProcessHandlers = (handlers: ProcessHandlers): void => {
+  const { 
+    unhandledRejectionHandler, 
+    uncaughtExceptionHandler, 
+    sigintHandler, 
+    sigtermHandler 
+  } = handlers;
+
+  process.removeListener('unhandledRejection', unhandledRejectionHandler);
+  process.removeListener('uncaughtException', uncaughtExceptionHandler);
+  process.removeListener('SIGINT', sigintHandler);
+  process.removeListener('SIGTERM', sigtermHandler);
+};