@enbox/dwn-server 0.0.1

package/src/connection/socket-connection.ts

@@ -0,0 +1,221 @@
+import type { Dwn, GenericMessage, MessageEvent } from "@enbox/dwn-sdk-js";
+import { DwnMethodName } from "@enbox/dwn-sdk-js";
+
+import type { WebSocket } from "ws";
+import log from 'loglevel';
+import { v4 as uuidv4 } from 'uuid';
+
+import type { RequestContext } from "../lib/json-rpc-router.js";
+import type { JsonRpcErrorResponse, JsonRpcId, JsonRpcRequest, JsonRpcResponse, JsonRpcSubscription } from "../lib/json-rpc.js";
+
+import { requestCounter } from "../metrics.js";
+import { jsonRpcRouter } from "../json-rpc-api.js";
+import { JsonRpcErrorCodes, createJsonRpcErrorResponse, createJsonRpcSuccessResponse } from "../lib/json-rpc.js";
+import { DwnServerError, DwnServerErrorCode } from "../dwn-error.js";
+
+const HEARTBEAT_INTERVAL = 30_000;
+
+/**
+ * SocketConnection handles a WebSocket connection to a DWN using JSON RPC.
+ * It also manages references to the long running RPC subscriptions for the connection.
+ */
+export class SocketConnection {
+  private heartbeatInterval: NodeJS.Timer;
+  private subscriptions: Map<JsonRpcId, JsonRpcSubscription> = new Map();
+  private isAlive: boolean;
+
+  constructor(
+    private socket: WebSocket,
+    private dwn: Dwn,
+    private onClose?: () => void
+  ){
+    socket.on('message', this.message.bind(this));
+    socket.on('close', this.close.bind(this));
+    socket.on('error', this.error.bind(this));
+    socket.on('pong', this.pong.bind(this));
+
+    // Sometimes connections between client <-> server can get borked in such a way that
+    // leaves both unaware of the borkage. ping messages can be used as a means to verify
+    // that the remote endpoint is still responsive. Server will ping each socket every 30s
+    // if a pong hasn't received from a socket by the next ping, the server will terminate
+    // the socket connection
+    this.isAlive = true;
+    this.heartbeatInterval = setInterval(() => {
+      if (this.isAlive === false) {
+        this.close();
+      }
+      this.isAlive = false;
+      this.socket.ping();
+    }, HEARTBEAT_INTERVAL);
+  }
+
+  /**
+   * Checks to see if the incoming `JsonRpcId` is already in use for a subscription.
+   */
+  hasSubscription(id: JsonRpcId): boolean {
+    return this.subscriptions.has(id);
+  }
+
+  /**
+   * Adds a reference for the JSON RPC Subscription to this connection.
+   * Used for cleanup if the connection is closed.
+   */
+  async addSubscription(subscription: JsonRpcSubscription): Promise<void> {
+    if (this.subscriptions.has(subscription.id)) {
+      throw new DwnServerError(
+        DwnServerErrorCode.ConnectionSubscriptionJsonRpcIdExists,
+        `the subscription with id ${subscription.id} already exists`
+      )
+    }
+
+    this.subscriptions.set(subscription.id, subscription);
+  }
+
+  /**
+   * Closes and removes the reference for a given subscription from this connection.
+   *
+   * @param id the `JsonRpcId` of the JSON RPC subscription request.
+   */
+  async closeSubscription(id: JsonRpcId): Promise<void> {
+    if (!this.subscriptions.has(id)) {
+      throw new DwnServerError(
+        DwnServerErrorCode.ConnectionSubscriptionJsonRpcIdNotFound,
+        `the subscription with id ${id} was not found`
+      )
+    }
+
+    const connection = this.subscriptions.get(id);
+    await connection.close();
+    this.subscriptions.delete(id);
+  }
+
+  /**
+   * Closes the existing connection and cleans up any listeners or subscriptions.
+   */
+  async close(): Promise<void> {
+    clearInterval(this.heartbeatInterval);
+
+    // clean up all socket event listeners
+    this.socket.removeAllListeners();
+
+    const closePromises = [];
+    for (const [id, subscription] of this.subscriptions) {
+      closePromises.push(subscription.close());
+      this.subscriptions.delete(id);
+    }
+
+    // close all of the associated subscriptions
+    await Promise.all(closePromises);
+
+    // close the socket.
+    this.socket.close();
+
+    // if there was a close handler passed call it after the connection has been closed
+    if (this.onClose !== undefined) {
+      this.onClose();
+    }
+  }
+
+  /**
+   * Pong messages are automatically sent in response to ping messages as required by
+   * the websocket spec. So, no need to send explicit pongs.
+   */
+  private pong(): void {
+    this.isAlive = true;
+  }
+
+  /**
+   * Log the error and close the connection.
+   */
+  private async error(error:Error): Promise<void>{
+    log.error(`SocketConnection error, terminating connection`, error);
+    this.socket.terminate();
+    await this.close();
+  }
+
+  /**
+   * Handles a `JSON RPC 2.0` encoded message.
+   */
+  private async message(dataBuffer: Buffer): Promise<void> {
+    const requestData = dataBuffer.toString();
+    if (!requestData) {
+      return this.send(createJsonRpcErrorResponse(
+        uuidv4(),
+        JsonRpcErrorCodes.BadRequest,
+        'request payload required.'
+      ))
+    }
+
+    let jsonRequest: JsonRpcRequest;
+    try {
+      jsonRequest = JSON.parse(requestData);
+    } catch(error) {
+      const errorResponse = createJsonRpcErrorResponse(
+        uuidv4(),
+        JsonRpcErrorCodes.BadRequest,
+        (error as Error).message
+      );
+      return this.send(errorResponse);
+    };
+
+    const requestContext = await this.buildRequestContext(jsonRequest);
+    const { jsonRpcResponse } = await jsonRpcRouter.handle(jsonRequest, requestContext);
+    if (jsonRpcResponse.error) {
+      requestCounter.inc({ method: jsonRequest.method, error: 1 });
+    } else {
+      requestCounter.inc({
+        method: jsonRequest.method,
+        status: jsonRpcResponse?.result?.reply?.status?.code || 0,
+      });
+    }
+    this.send(jsonRpcResponse);
+  }
+
+  /**
+   * Sends a JSON encoded Buffer through the Websocket.
+   */
+  private send(response: JsonRpcResponse | JsonRpcErrorResponse): void {
+    this.socket.send(JSON.stringify(response));
+  }
+
+  /**
+   * Creates a subscription handler to send messages matching the subscription requested.
+   *
+   * Wraps the incoming `message` in a `JSON RPC Success Response` using the original subscription`JSON RPC Id` to send through the WebSocket.
+   */
+  private createSubscriptionHandler(id: JsonRpcId): (message: MessageEvent) => void {
+    return (event) => {
+      const response = createJsonRpcSuccessResponse(id, { event });
+      this.send(response);
+    }
+  }
+
+  /**
+   * Builds a `RequestContext` object to use with the `JSON RPC API`.
+   *
+   * Adds a `subscriptionHandler` for `Subscribe` messages.
+   */
+  private async buildRequestContext(request: JsonRpcRequest): Promise<RequestContext> {
+    const { params, method, subscription } = request;
+
+    const requestContext: RequestContext = {
+      transport        : 'ws',
+      dwn              : this.dwn,
+      socketConnection : this,
+    }
+
+    // methods that expect a long-running subscription begin with `rpc.subscribe.`
+    if (method.startsWith('rpc.subscribe.') && subscription) {
+      const { message } = params as { message?: GenericMessage };
+      if (message?.descriptor.method === DwnMethodName.Subscribe) {
+        const handlerFunc = this.createSubscriptionHandler(subscription.id);
+        requestContext.subscriptionRequest = {
+          id: subscription.id,
+          subscriptionHandler: (message): void => handlerFunc(message),
+        }
+      }
+    }
+
+    return requestContext;
+  }
+}

package/src/dwn-error.ts

@@ -0,0 +1,38 @@
+/**
+ * A class that represents a DWN Server error.
+ */
+export class DwnServerError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+  ) {
+    super(`${code}: ${message}`);
+
+    this.name = 'DwnServerError';
+  }
+
+  /**
+   * Called by `JSON.stringify(...)` automatically.
+   */
+  public toJSON(): { code: string, message: string } {
+    return {
+      code: this.code,
+      message: this.message,
+    };
+  }
+}
+
+/**
+ * DWN Server error codes.
+ */
+export enum DwnServerErrorCode {
+  ConnectionSubscriptionJsonRpcIdExists = 'ConnectionSubscriptionJsonRpcIdExists',
+  ConnectionSubscriptionJsonRpcIdNotFound = 'ConnectionSubscriptionJsonRpcIdNotFound',
+  ProofOfWorkInsufficientSolutionNonce = 'ProofOfWorkInsufficientSolutionNonce',
+  ProofOfWorkInvalidOrExpiredChallenge = 'ProofOfWorkInvalidOrExpiredChallenge',
+  ProofOfWorkManagerInvalidChallengeNonce = 'ProofOfWorkManagerInvalidChallengeNonce',
+  ProofOfWorkManagerInvalidResponseNonceFormat = 'ProofOfWorkManagerInvalidResponseNonceFormat',
+  ProofOfWorkManagerResponseNonceReused = 'ProofOfWorkManagerResponseNonceReused',
+  RegistrationManagerInvalidOrOutdatedTermsOfServiceHash = 'RegistrationManagerInvalidOrOutdatedTermsOfServiceHash',
+  TenantRegistrationOutdatedTermsOfService = 'TenantRegistrationOutdatedTermsOfService',
+}

package/src/dwn-server.ts

@@ -0,0 +1,178 @@
+import type { DidResolver } from '@enbox/dids';
+import type { EventStream } from '@enbox/dwn-sdk-js';
+import type { ProcessHandlers } from './process-handlers.js';
+import type { Server } from 'http';
+import type { WebSocketServer } from 'ws';
+import type { DwnServerConfig } from './config.js';
+
+import log from 'loglevel';
+import prefix from 'loglevel-plugin-prefix';
+import { config as defaultConfig } from './config.js';
+import { getDwnConfig } from './storage.js';
+import { HttpServerShutdownHandler } from './lib/http-server-shutdown-handler.js';
+import { HttpApi } from './http-api.js';
+import { PluginLoader } from './plugin-loader.js';
+import { RegistrationManager } from './registration/registration-manager.js';
+import { WsApi } from './ws-api.js';
+import { Dwn, EventEmitterStream } from '@enbox/dwn-sdk-js';
+import { removeProcessHandlers, setProcessHandlers } from './process-handlers.js';
+
+/**
+ * Options for the DwnServer constructor.
+ * This is different to DwnServerConfig in that the DwnServerConfig defines configuration that come from environment variables so (more) user facing.
+ * Where as DwnServerOptions wraps DwnServerConfig with additional overrides that can be used for testing.
+ */
+export type DwnServerOptions = {
+  /**
+   * A custom DID resolver to use in the DWN.
+   * Mainly for testing purposes. Ignored if `dwn` is provided.
+   */
+  didResolver?: DidResolver;
+  dwn?: Dwn;
+  config?: DwnServerConfig;
+};
+
+/**
+ * State of the DwnServer, either Stopped or Started, to help short-circuit start and stop logic.
+ */
+enum DwnServerState {
+  Stopped,
+  Started
+}
+
+export class DwnServer {
+  serverState = DwnServerState.Stopped;
+  processHandlers: ProcessHandlers;
+  
+  /**
+   * A custom DID resolver to use in the DWN.
+   * Mainly for testing purposes. Ignored if `dwn` is provided.
+   */
+  didResolver?: DidResolver;
+  dwn?: Dwn;
+  config: DwnServerConfig;
+  #httpServerShutdownHandler: HttpServerShutdownHandler;
+  #httpApi: HttpApi;
+  #wsApi: WsApi;
+
+  /**
+   * @param options.dwn - Dwn instance to use as an override. Registration endpoint will not be enabled if this is provided.
+   */
+  constructor(options: DwnServerOptions = {}) {
+    this.config = options.config ?? defaultConfig;
+
+    this.didResolver = options.didResolver;
+    this.dwn = options.dwn;
+
+    log.setLevel(this.config.logLevel as log.LogLevelDesc);
+
+    prefix.reg(log);
+    prefix.apply(log);
+  }
+
+  /**
+   * Starts the DWN server.
+   */
+  async start(): Promise<void> {
+    if (this.serverState === DwnServerState.Started) {
+      return;
+    }
+
+    await this.#setupServer();
+    this.processHandlers = setProcessHandlers(this);
+    this.serverState = DwnServerState.Started;
+  }
+
+  /**
+   * Function to setup the servers (HTTP and WebSocket)
+   * The DWN creation is secondary and only happens if it hasn't already been done.
+   */
+  async #setupServer(): Promise<void> {
+
+    let registrationManager: RegistrationManager;
+    if (!this.dwn) {
+      // undefined registrationStoreUrl is used as a signal that there is no need for tenant registration, DWN is open for all.
+      registrationManager = await RegistrationManager.create({
+        registrationStoreUrl: this.config.registrationStoreUrl,
+        termsOfServiceFilePath: this.config.termsOfServiceFilePath,
+        proofOfWorkChallengeNonceSeed: this.config.registrationProofOfWorkSeed,
+        proofOfWorkInitialMaximumAllowedHash: this.config.registrationProofOfWorkInitialMaxHash,
+      });
+
+      let eventStream: EventStream | undefined;
+      if (this.config.webSocketSupport) {
+        // If Even Stream plugin is not specified, use `EventEmitterStream` implementation as default.
+        if (this.config.eventStreamPluginPath === undefined || this.config.eventStreamPluginPath === '') {
+          eventStream = new EventEmitterStream();
+        } else {
+          eventStream = await PluginLoader.loadPlugin<EventStream>(this.config.eventStreamPluginPath);
+        }
+
+      }
+
+      const dwnConfig = await getDwnConfig(this.config, {
+        didResolver: this.didResolver,
+        tenantGate: registrationManager,
+        eventStream,
+      })
+      this.dwn = await Dwn.create(dwnConfig);
+    }
+
+    this.#httpApi = await HttpApi.create(this.config, this.dwn, registrationManager);
+
+    await this.#httpApi.start(this.config.port);
+    log.info(`HttpServer listening on port ${this.config.port}`);
+
+    this.#httpServerShutdownHandler = new HttpServerShutdownHandler(
+      this.#httpApi.server,
+    );
+
+    if (this.config.webSocketSupport) {
+      this.#wsApi = new WsApi(this.#httpApi.server, this.dwn);
+      this.#wsApi.start();
+      log.info('WebSocketServer ready...');
+    }
+  }
+
+  /**
+   * Stops the DWN server.
+   */
+  async stop(): Promise<void> {
+    if (this.serverState === DwnServerState.Stopped) {
+      return;
+    }
+
+    await this.dwn.close();
+    await this.#httpApi.close();
+
+    // close WebSocket server if it was initialized
+    if (this.#wsApi !== undefined) {
+      await this.#wsApi.close();
+    }
+
+    await new Promise<void>((resolve) => {
+      this.#httpServerShutdownHandler.stop(() => {
+        resolve();
+      });
+    });
+
+    removeProcessHandlers(this.processHandlers);
+
+    this.serverState = DwnServerState.Stopped;
+  }
+
+  get httpServer(): Server {
+    return this.#httpApi.server;
+  }
+
+  get wsServer(): WebSocketServer | undefined {
+    return this.#wsApi?.server;
+  }
+
+  /**
+   * Gets the RegistrationManager for testing purposes.
+   */
+  get registrationManager(): RegistrationManager {
+    return this.#httpApi.registrationManager;
+  }
+}