@enbox/dwn-server 0.0.3 → 0.0.5

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

@@ -4,14 +4,10 @@ import type {
   HandlerResponse,
   JsonRpcHandler,
 } from '../../lib/json-rpc-router.js';
-import type { JsonRpcId, JsonRpcResponse } from '../../lib/json-rpc.js';
+import type { JsonRpcId, JsonRpcResponse } from '@enbox/dwn-clients';
 
 import { DwnServerErrorCode } from '../../dwn-error.js';
-import {
-  createJsonRpcErrorResponse,
-  createJsonRpcSuccessResponse,
-  JsonRpcErrorCodes,
-} from '../../lib/json-rpc.js';
+import { createJsonRpcErrorResponse, createJsonRpcSuccessResponse, JsonRpcErrorCodes } from '@enbox/dwn-clients';
 
 /**
  * Closes a subscription tied to a specific `SocketConnection`.

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,8 +1,12 @@
-import type { Dwn, MessageSubscriptionHandler } from '@enbox/dwn-sdk-js';
-
-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,11 +16,23 @@ export type RequestContext = {
   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 `SubscriptionMessage` handler associated with a subscription request, only used in `ws` requests */
+    subscriptionHandler: SubscriptionListener;
   }
   /** 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 = {

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,4 +1,8 @@
-import { Counter, Histogram } from 'prom-client';
+import { Counter, Gauge, Histogram } from 'prom-client';
+
+// ---------------------------------------------------------------------------
+// Existing metrics
+// ---------------------------------------------------------------------------
 
 export const requestCounter = new Counter({
   name       : 'dwn_requests_total',
@@ -12,3 +16,48 @@ export const responseHistogram = new 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'],
+});