@enbox/dwn-server 0.0.2 → 0.0.4

package/src/index.ts

@@ -1,6 +1,17 @@
-export { DwnServerConfig } from './config.js';
+export { ActivityLog, AdminApi, AdminStore } from './admin/index.js';
+export type {
+  AdminActivityEvent,
+  AdminConnectionSnapshot,
+  AdminHealthCheck,
+  AdminServerStats,
+  AdminTenantDetail,
+  AdminTenantSummary,
+} from './admin/index.js';
+export { config as defaultDwnServerConfig, DwnServerConfig } from './config.js';
+export { DeliveryService } from './delivery-service.js';
 export { DwnServer, DwnServerOptions } from './dwn-server.js';
 export { HttpApi } from './http-api.js';
 export { jsonRpcRouter } from './json-rpc-api.js';
-export { StoreType, BackendTypes, DwnStore } from './storage.js';
+export type { MessageProcessedContext, MessageProcessedHook } from './message-processed-hook.js';
+export { getDwnConfig, StoreType, BackendTypes, DwnStore } from './storage.js';
 export { WsApi } from './ws-api.js';

package/src/json-rpc-api.ts

@@ -1,11 +1,12 @@
 import { JsonRpcRouter } from './lib/json-rpc-router.js';
 
 import { handleDwnProcessMessage } from './json-rpc-handlers/dwn/index.js';
-import { handleSubscriptionsClose } from './json-rpc-handlers/subscription/index.js';
+import { handleSubscriptionAck, handleSubscriptionsClose } from './json-rpc-handlers/subscription/index.js';
 
 export const jsonRpcRouter = new JsonRpcRouter();
 
 jsonRpcRouter.on('dwn.processMessage', handleDwnProcessMessage);
 jsonRpcRouter.on('rpc.subscribe.dwn.processMessage', handleDwnProcessMessage);
 
+jsonRpcRouter.on('rpc.ack', handleSubscriptionAck);
 jsonRpcRouter.on('rpc.subscribe.close', handleSubscriptionsClose);

package/src/json-rpc-handlers/dwn/process-message.ts

@@ -1,21 +1,22 @@
 import type { GenericMessage } from '@enbox/dwn-sdk-js';
 import { DwnInterfaceName, DwnMethodName } from '@enbox/dwn-sdk-js';
 
-import type { Readable as IsomorphicReadable } from 'readable-stream';
 import log from 'loglevel';
 import { v4 as uuidv4 } from 'uuid';
 
-import type { JsonRpcSubscription } from '../../lib/json-rpc.js';
+import type { JsonRpcSubscription } from '@enbox/dwn-clients';
 import type {
   HandlerResponse,
   JsonRpcHandler,
 } from '../../lib/json-rpc-router.js';
 
+import { DwnServerErrorCode } from '../../dwn-error.js';
+import { requestDataBytesTotal } from '../../metrics.js';
 import {
   createJsonRpcErrorResponse,
   createJsonRpcSuccessResponse,
   JsonRpcErrorCodes,
-} from '../../lib/json-rpc.js';
+} from '@enbox/dwn-clients';
 
 
 export const handleDwnProcessMessage: JsonRpcHandler = async (
@@ -28,7 +29,7 @@ export const handleDwnProcessMessage: JsonRpcHandler = async (
 
   try {
     // RecordsWrite is only supported on 'http' to support data stream for large data
-    // TODO: https://github.com/TBD54566975/dwn-server/issues/108
+    // TODO: https://github.com/enboxorg/enbox/issues/108
     if (
       transport !== 'http' &&
       message.descriptor.interface === DwnInterfaceName.Records &&
@@ -38,11 +39,11 @@ export const handleDwnProcessMessage: JsonRpcHandler = async (
         requestId,
         JsonRpcErrorCodes.InvalidParams,
         `RecordsWrite is not supported via ${context.transport}`
-      )
+      );
       return { jsonRpcResponse };
     }
 
-    // subscribe methods must come with a subscriptionRequest context 
+    // subscribe methods must come with a subscriptionRequest context
     if (message.descriptor.method === DwnMethodName.Subscribe && subscriptionRequest === undefined) {
       const jsonRpcResponse = createJsonRpcErrorResponse(
         requestId,
@@ -58,7 +59,7 @@ export const handleDwnProcessMessage: JsonRpcHandler = async (
         requestId,
         JsonRpcErrorCodes.InvalidParams,
         `subscriptions are not supported via ${context.transport}`
-      )
+      );
       return { jsonRpcResponse };
     }
 
@@ -70,12 +71,40 @@ export const handleDwnProcessMessage: JsonRpcHandler = async (
         requestId,
         JsonRpcErrorCodes.InvalidParams,
         `the subscribe id: ${subscriptionRequest.id} is in use by an active subscription`
-      )
+      );
       return { jsonRpcResponse };
     }
 
+    // --- Per-tenant rate limiting (before any DWN processing) ---
+    if (context.tenantRateLimiter) {
+      const result = context.tenantRateLimiter.consume(target);
+      if (result.allowed === false) {
+        const retryAfterSec = Math.ceil(result.retryAfterMs / 1000);
+        const jsonRpcResponse = createJsonRpcErrorResponse(
+          requestId,
+          JsonRpcErrorCodes.TooManyRequests,
+          `${DwnServerErrorCode.RateLimitExceeded}: tenant rate limit exceeded, retry after ${retryAfterSec}s`,
+          { retryAfterSec },
+        );
+        return { jsonRpcResponse };
+      }
+    }
+
+    // --- Per-tenant storage quota enforcement (RecordsWrite only) ---
+    if (
+      context.config &&
+      context.adminStore &&
+      message.descriptor.interface === DwnInterfaceName.Records &&
+      message.descriptor.method === DwnMethodName.Write
+    ) {
+      const quotaResult = await enforceQuota(target, message, context);
+      if (quotaResult !== undefined) {
+        return quotaResult;
+      }
+    }
+
     const reply = await dwn.processMessage(target, message, {
-      dataStream: dataStream as IsomorphicReadable,
+      dataStream,
       subscriptionHandler: subscriptionRequest?.subscriptionHandler,
     });
 
@@ -83,7 +112,7 @@ export const handleDwnProcessMessage: JsonRpcHandler = async (
     const { entry } = reply;
     // RecordsRead or MessagesRead messages optionally return data as a stream to accommodate large amounts of data
     // we remove the data stream from the reply that will be serialized and return it as a separate property in the response payload.
-    let recordDataStream: IsomorphicReadable;
+    let recordDataStream: ReadableStream<Uint8Array>;
     if (entry !== undefined && entry.data !== undefined) {
       recordDataStream = entry.data;
       delete reply.entry.data; // not serializable via JSON
@@ -97,9 +126,9 @@ export const handleDwnProcessMessage: JsonRpcHandler = async (
       const subscriptionReply: JsonRpcSubscription = {
         id: subscriptionRequest.id,
         close,
-      }
+      };
       await socketConnection.addSubscription(subscriptionReply);
-      delete reply.subscription.close // delete the close method from the reply as it's not JSON serializable and has a held reference.
+      delete reply.subscription.close; // delete the close method from the reply as it's not JSON serializable and has a held reference.
     }
 
     const jsonRpcResponse = createJsonRpcSuccessResponse(requestId, { reply });
@@ -108,16 +137,121 @@ export const handleDwnProcessMessage: JsonRpcHandler = async (
       responsePayload.dataStream = recordDataStream;
     }
 
+    // --- Fire-and-forget: post-processing hooks ---
+    const statusCode = reply.status?.code ?? 0;
+    if (context.messageProcessedHooks) {
+      const hookContext = { tenant: target, message, status: reply.status, transport };
+      for (const hook of context.messageProcessedHooks) {
+        try {
+          const result = hook.onMessageProcessed(hookContext);
+          if (result instanceof Promise) {
+            result.catch((err: unknown): void => {
+              log.error('MessageProcessedHook error', err);
+            });
+          }
+        } catch (err) {
+          log.error('MessageProcessedHook error', err);
+        }
+      }
+    }
+
+    // Capture activity event and per-request metrics.
+    const dwnInterface = message.descriptor.interface as string;
+    const dwnMethod = message.descriptor.method as string;
+    const dataSizeBytes = (message.descriptor as { dataSize?: number }).dataSize;
+
+    if (dataSizeBytes !== undefined && dataSizeBytes > 0) {
+      requestDataBytesTotal.inc({ interface: dwnInterface, method: dwnMethod }, dataSizeBytes);
+    }
+
+    if (context.activityLog) {
+      context.activityLog.record({
+        tenant    : target,
+        interface : dwnInterface,
+        method    : dwnMethod,
+        statusCode,
+        transport,
+        dataSizeBytes,
+      });
+    }
+
     return responsePayload;
   } catch (error) {
+    // Log the full error internally but return a generic message to the client
+    // to avoid leaking implementation details (SQL errors, file paths, etc.).
+    log.error('handleDwnProcessMessage error', error);
+
     const jsonRpcResponse = createJsonRpcErrorResponse(
       requestId,
       JsonRpcErrorCodes.InternalError,
-      error.message,
+      'an unexpected error occurred while processing the message',
     );
 
-    // log the unhandled error response
-    log.error('handleDwnProcessMessage error', jsonRpcResponse, dwnRequest, error);
     return { jsonRpcResponse } as HandlerResponse;
   }
 };
+
+// ---------------------------------------------------------------------------
+// Quota enforcement helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Checks whether the tenant has exceeded their message count or storage quota.
+ * Returns a JSON-RPC error response if the quota is exceeded, or `undefined` to proceed.
+ */
+async function enforceQuota(
+  target: string,
+  message: GenericMessage,
+  context: Parameters<JsonRpcHandler>[1],
+): Promise<HandlerResponse | undefined> {
+  const { config, adminStore, registrationStore } = context;
+  const requestId = (message as any).recordId ?? uuidv4();
+
+  // Resolve effective quota: per-tenant override > global config > unlimited.
+  let maxMessages = config!.quotaMaxMessages ?? 0;
+  let maxStorageBytes = config!.quotaMaxStorageBytes ?? 0;
+
+  if (registrationStore) {
+    const tenantQuota = await registrationStore.getQuota(target);
+    if (tenantQuota !== undefined) {
+      maxMessages = tenantQuota.maxMessages ?? maxMessages;
+      maxStorageBytes = tenantQuota.maxStorageBytes ?? maxStorageBytes;
+    }
+  }
+
+  // 0 means unlimited — skip enforcement.
+  if (maxMessages === 0 && maxStorageBytes === 0) {
+    return undefined;
+  }
+
+  // Check message count quota.
+  if (maxMessages > 0) {
+    const currentMessages = await adminStore!.getTenantMessageCount(target);
+    if (currentMessages >= maxMessages) {
+      return {
+        jsonRpcResponse: createJsonRpcErrorResponse(
+          requestId,
+          JsonRpcErrorCodes.InvalidRequest,
+          `${DwnServerErrorCode.TenantMessageQuotaExceeded}: tenant has reached the message limit of ${maxMessages}`,
+        ),
+      };
+    }
+  }
+
+  // Check storage size quota.
+  if (maxStorageBytes > 0) {
+    const dataSize = (message.descriptor as { dataSize?: number }).dataSize ?? 0;
+    const currentStorage = await adminStore!.getTenantStorageSize(target);
+    if (currentStorage + dataSize > maxStorageBytes) {
+      return {
+        jsonRpcResponse: createJsonRpcErrorResponse(
+          requestId,
+          JsonRpcErrorCodes.InvalidRequest,
+          `${DwnServerErrorCode.TenantStorageQuotaExceeded}: tenant would exceed storage limit of ${maxStorageBytes} bytes`,
+        ),
+      };
+    }
+  }
+
+  return undefined;
+}

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

@@ -0,0 +1,63 @@
+import { v4 as uuidv4 } from 'uuid';
+
+import type { JsonRpcId } from '@enbox/dwn-clients';
+import type {
+  HandlerResponse,
+  JsonRpcHandler,
+} from '../../lib/json-rpc-router.js';
+
+import { createJsonRpcErrorResponse, createJsonRpcSuccessResponse, JsonRpcErrorCodes } from '@enbox/dwn-clients';
+
+/**
+ * Handles `rpc.ack` — acknowledges receipt of subscription events up to the
+ * given cursor, advancing the per-subscription flow-control window.
+ *
+ * Request shape:
+ * ```json
+ * {
+ *   "jsonrpc": "2.0",
+ *   "method": "rpc.ack",
+ *   "params": { "cursor": "<opaque-cursor>" },
+ *   "subscription": { "id": "<subscription-id>" }
+ * }
+ * ```
+ *
+ * This is a notification (no `id` required), but the server sends a response
+ * if validation fails (missing params, unknown subscription, etc.).
+ */
+export const handleSubscriptionAck: 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.InvalidParams, 'subscription options are required'
+    );
+    return { jsonRpcResponse };
+  }
+
+  const { id: subscriptionId } = jsonRpcRequest.subscription as { id: JsonRpcId };
+  const { cursor } = (jsonRpcRequest.params ?? {}) as { cursor?: string };
+
+  if (cursor === undefined || typeof cursor !== 'string' || cursor === '') {
+    const jsonRpcResponse = createJsonRpcErrorResponse(
+      requestId, JsonRpcErrorCodes.InvalidParams, 'params.cursor is required and must be a non-empty string'
+    );
+    return { jsonRpcResponse };
+  }
+
+  const { socketConnection } = context;
+  socketConnection.ackSubscription(subscriptionId, cursor);
+
+  const jsonRpcResponse = createJsonRpcSuccessResponse(requestId, { reply: { status: 200, detail: 'OK' } });
+  return { jsonRpcResponse } as HandlerResponse;
+};

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

@@ -1,17 +1,13 @@
 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 '@enbox/dwn-clients';
 
-import type { JsonRpcId, JsonRpcResponse } from '../../lib/json-rpc.js';
-import {
-  createJsonRpcErrorResponse,
-  createJsonRpcSuccessResponse,
-  JsonRpcErrorCodes,
-} from '../../lib/json-rpc.js';
+import { DwnServerErrorCode } from '../../dwn-error.js';
+import { createJsonRpcErrorResponse, createJsonRpcSuccessResponse, JsonRpcErrorCodes } from '@enbox/dwn-clients';
 
 /**
  * Closes a subscription tied to a specific `SocketConnection`.
@@ -43,7 +39,7 @@ export const handleSubscriptionsClose: JsonRpcHandler = async (
     // 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) {
+  } catch (error) {
     if (error.code === DwnServerErrorCode.ConnectionSubscriptionJsonRpcIdNotFound) {
       jsonRpcResponse = createJsonRpcErrorResponse(requestId, JsonRpcErrorCodes.InvalidParams, `subscription ${id} does not exist.`);
     } else {
@@ -56,4 +52,4 @@ export const handleSubscriptionsClose: JsonRpcHandler = async (
   }
 
   return { jsonRpcResponse } as HandlerResponse;
-}
+};

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

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

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

@@ -1,9 +1,12 @@
-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 { ActivityLog } from '../admin/activity-log.js';
+import type { AdminStore } from '../admin/admin-store.js';
+import type { DwnServerConfig } from '../config.js';
+import type { MessageProcessedHook } from '../message-processed-hook.js';
+import type { RateLimiter } from '../rate-limiter.js';
+import type { RegistrationStore } from '../registration/registration-store.js';
 import type { SocketConnection } from '../connection/socket-connection.js';
+import type { Dwn, SubscriptionListener } from '@enbox/dwn-sdk-js';
+import type { JsonRpcId, JsonRpcRequest, JsonRpcResponse } from '@enbox/dwn-clients';
 
 export type RequestContext = {
   transport: 'http' | 'ws';
@@ -12,17 +15,29 @@ export type RequestContext = {
   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;
+    id: JsonRpcId;
+    /** The `SubscriptionMessage` handler associated with a subscription request, only used in `ws` requests */
+    subscriptionHandler: SubscriptionListener;
   }
-  /** The `Readable` stream associated with a `RecordsWrite` request only used in `http` requests */
-  dataStream?: Readable;
+  /** The `ReadableStream` associated with a `RecordsWrite` request only used in `http` requests */
+  dataStream?: ReadableStream<Uint8Array>;
+  /** The admin activity log for capturing DWN request events (optional). */
+  activityLog?: ActivityLog;
+  /** The admin store for quota usage queries (optional). */
+  adminStore?: AdminStore;
+  /** The registration store for per-tenant quota lookups (optional). */
+  registrationStore?: RegistrationStore;
+  /** Server configuration for global quota/rate-limit defaults (optional). */
+  config?: DwnServerConfig;
+  /** Per-tenant rate limiter (optional). */
+  tenantRateLimiter?: RateLimiter;
+  /** Hooks invoked after every `dwn.processMessage()` call (fire-and-forget). */
+  messageProcessedHooks?: MessageProcessedHook[];
 };
 
 export type HandlerResponse = {
   jsonRpcResponse: JsonRpcResponse;
-  dataStream?: Readable;
+  dataStream?: ReadableStream<Uint8Array>;
 };
 
 export type JsonRpcHandler = (

package/src/lib/sql-utils.ts

@@ -0,0 +1,7 @@
+/**
+ * Escapes SQL LIKE wildcard characters (`%`, `_`, `\`) in user-supplied input
+ * so that they are treated as literal characters rather than pattern operators.
+ */
+export function escapeLikeWildcards(input: string): string {
+  return input.replace(/[%_\\]/g, '\\$&');
+}

package/src/main.ts

@@ -1,14 +1,6 @@
 #!/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/message-processed-hook.ts

@@ -0,0 +1,33 @@
+import type { GenericMessage } from '@enbox/dwn-sdk-js';
+
+/**
+ * Context provided to hooks after `dwn.processMessage()` returns.
+ */
+export type MessageProcessedContext = {
+  /** The tenant DID that owns the DWN. */
+  tenant: string;
+  /** The original signed DWN message. */
+  message: GenericMessage;
+  /** The reply status from the DWN engine. */
+  status: { code: number; detail: string };
+  /** The transport over which the message was received. */
+  transport: 'http' | 'ws';
+};
+
+/**
+ * Hook that is invoked after every successful `dwn.processMessage()` call.
+ *
+ * Hooks are fire-and-forget: they run asynchronously and their return values
+ * are ignored. Errors thrown by hooks are logged but never propagate to the
+ * request handler or the client.
+ *
+ * Implementations should return quickly and schedule any expensive work
+ * (network I/O, retries) internally.
+ */
+export interface MessageProcessedHook {
+  /**
+   * Called after a DWN message has been processed.
+   * May return void or a Promise — both are handled gracefully.
+   */
+  onMessageProcessed(context: MessageProcessedContext): void | Promise<void>;
+}

package/src/metrics.ts

@@ -1,14 +1,63 @@
-import { Counter, Histogram } from 'prom-client';
+import { Counter, Gauge, Histogram } from 'prom-client';
+
+// ---------------------------------------------------------------------------
+// Existing metrics
+// ---------------------------------------------------------------------------
 
 export const requestCounter = new Counter({
-  name: 'dwn_requests_total',
-  help: 'all dwn requests processed',
-  labelNames: ['method', 'status', 'error'],
+  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'],
+  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'],
+});
+
+// ---------------------------------------------------------------------------
+// Enhanced gauges — updated periodically by AdminApi.startMetricsUpdater()
+// ---------------------------------------------------------------------------
+
+/** Number of active (registered) tenants. */
+export const activeTenants = new Gauge({
+  name : 'dwn_active_tenants',
+  help : 'number of active registered tenants',
+});
+
+/** Total messages stored across all tenants. */
+export const totalMessages = new Gauge({
+  name : 'dwn_total_messages',
+  help : 'total messages stored across all tenants',
+});
+
+/** Total data storage in bytes across all tenants. */
+export const totalDataBytes = new Gauge({
+  name : 'dwn_total_data_bytes',
+  help : 'total data storage bytes across all tenants',
+});
+
+/** Number of active WebSocket connections. */
+export const websocketConnections = new Gauge({
+  name : 'dwn_websocket_connections',
+  help : 'number of active websocket connections',
+});
+
+/** Number of active WebSocket subscriptions. */
+export const websocketSubscriptions = new Gauge({
+  name : 'dwn_websocket_subscriptions',
+  help : 'number of active websocket subscriptions',
+});
+
+// ---------------------------------------------------------------------------
+// Enhanced counters — incremented per-request
+// ---------------------------------------------------------------------------
+
+/** Total data bytes written via RecordsWrite, labeled by interface + method. */
+export const requestDataBytesTotal = new Counter({
+  name       : 'dwn_request_data_bytes_total',
+  help       : 'total data bytes processed in DWN requests',
+  labelNames : ['interface', 'method'],
 });