@durable-streams/server 0.1.0

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * In-memory test server for durable-stream e2e testing.
+ *
+ * @packageDocumentation
+ */
+
+export { DurableStreamTestServer } from "./server"
+export { StreamStore } from "./store"
+export { FileBackedStreamStore } from "./file-store"
+export { encodeStreamPath, decodeStreamPath } from "./path-encoding"
+export { createRegistryHooks } from "./registry-hook"
+export {
+  calculateCursor,
+  handleCursorCollision,
+  generateResponseCursor,
+  DEFAULT_CURSOR_EPOCH,
+  DEFAULT_CURSOR_INTERVAL_SECONDS,
+  type CursorOptions,
+} from "./cursor"
+export type {
+  Stream,
+  StreamMessage,
+  TestServerOptions,
+  PendingLongPoll,
+  StreamLifecycleEvent,
+  StreamLifecycleHook,
+} from "./types"

package/src/path-encoding.ts

@@ -0,0 +1,61 @@
+/**
+ * Path encoding utilities for converting stream paths to filesystem-safe directory names.
+ */
+
+import { createHash } from "node:crypto"
+
+const MAX_ENCODED_LENGTH = 200
+
+/**
+ * Encode a stream path to a filesystem-safe directory name using base64url encoding.
+ * Long paths (>200 chars) are hashed to keep directory names manageable.
+ *
+ * @example
+ * encodeStreamPath("/stream/users:created") → "L3N0cmVhbS91c2VyczpjcmVhdGVk"
+ */
+export function encodeStreamPath(path: string): string {
+  // Base64url encoding (RFC 4648 §5)
+  // Replace + with - and / with _, remove padding =
+  const base64 = Buffer.from(path, `utf-8`)
+    .toString(`base64`)
+    .replace(/\+/g, `-`)
+    .replace(/\//g, `_`)
+    .replace(/=/g, ``)
+
+  // Hash long paths to keep directory names manageable
+  if (base64.length > MAX_ENCODED_LENGTH) {
+    const hash = createHash(`sha256`).update(path).digest(`hex`).slice(0, 16)
+    // Use ~ as separator since it cannot appear in base64url output
+    return `${base64.slice(0, 180)}~${hash}`
+  }
+
+  return base64
+}
+
+/**
+ * Decode a filesystem-safe directory name back to the original stream path.
+ *
+ * @example
+ * decodeStreamPath("L3N0cmVhbS91c2VyczpjcmVhdGVk") → "/stream/users:created"
+ */
+export function decodeStreamPath(encoded: string): string {
+  // Remove hash suffix if present (hash is always 16 chars after ~ separator)
+  // Use ~ as separator since it cannot appear in base64url output
+  let base = encoded
+  const tildeIndex = encoded.lastIndexOf(`~`)
+  if (tildeIndex !== -1) {
+    const possibleHash = encoded.slice(tildeIndex + 1)
+    // Verify it's a 16-char hex hash before removing it
+    if (possibleHash.length === 16 && /^[0-9a-f]+$/.test(possibleHash)) {
+      base = encoded.slice(0, tildeIndex)
+    }
+  }
+
+  // Restore base64 from base64url
+  const normalized = base.replace(/-/g, `+`).replace(/_/g, `/`)
+
+  // Add padding back
+  const padded = normalized + `=`.repeat((4 - (normalized.length % 4)) % 4)
+
+  return Buffer.from(padded, `base64`).toString(`utf-8`)
+}

package/src/registry-hook.ts

@@ -0,0 +1,118 @@
+/**
+ * Helper to create lifecycle hooks that maintain a __registry__ stream.
+ * This stream records all create/delete events for observability.
+ */
+
+import { DurableStream } from "@durable-streams/client"
+import { createStateSchema } from "@durable-streams/state"
+import type { StreamLifecycleHook } from "./types"
+import type { StreamStore } from "./store"
+import type { FileBackedStreamStore } from "./file-store"
+
+const REGISTRY_PATH = `/v1/stream/__registry__`
+
+// Registry schema for the server
+interface StreamMetadata {
+  path: string
+  contentType: string
+  createdAt: number
+}
+
+const streamMetadataSchema = {
+  "~standard": {
+    version: 1 as const,
+    vendor: `durable-streams`,
+    validate: (value: unknown) => {
+      if (typeof value !== `object` || value === null) {
+        return { issues: [{ message: `value must be an object` }] }
+      }
+      const data = value as any
+      if (typeof data.path !== `string` || data.path.length === 0) {
+        return { issues: [{ message: `path must be a non-empty string` }] }
+      }
+      if (
+        typeof data.contentType !== `string` ||
+        data.contentType.length === 0
+      ) {
+        return {
+          issues: [{ message: `contentType must be a non-empty string` }],
+        }
+      }
+      if (typeof data.createdAt !== `number`) {
+        return { issues: [{ message: `createdAt must be a number` }] }
+      }
+      return { value: data as StreamMetadata }
+    },
+  },
+}
+
+const registryStateSchema = createStateSchema({
+  streams: {
+    schema: streamMetadataSchema,
+    type: `stream`,
+    primaryKey: `path`,
+  },
+})
+
+/**
+ * Creates lifecycle hooks that write to a __registry__ stream.
+ * Any client can read this stream to discover all streams and their lifecycle events.
+ */
+export function createRegistryHooks(
+  store: StreamStore | FileBackedStreamStore,
+  serverUrl: string
+): {
+  onStreamCreated: StreamLifecycleHook
+  onStreamDeleted: StreamLifecycleHook
+} {
+  const registryStream = new DurableStream({
+    url: `${serverUrl}${REGISTRY_PATH}`,
+    contentType: `application/json`,
+  })
+
+  const ensureRegistryExists = async () => {
+    if (!store.has(REGISTRY_PATH)) {
+      await DurableStream.create({
+        url: `${serverUrl}${REGISTRY_PATH}`,
+        contentType: `application/json`,
+      })
+    }
+  }
+
+  // Helper to extract stream name from full path
+  const extractStreamName = (fullPath: string): string => {
+    // Remove /v1/stream/ prefix if present
+    return fullPath.replace(/^\/v1\/stream\//, ``)
+  }
+
+  return {
+    onStreamCreated: async (event) => {
+      await ensureRegistryExists()
+
+      const streamName = extractStreamName(event.path)
+
+      const changeEvent = registryStateSchema.streams.insert({
+        key: streamName,
+        value: {
+          path: streamName,
+          contentType: event.contentType || `application/octet-stream`,
+          createdAt: event.timestamp,
+        },
+      })
+
+      await registryStream.append(changeEvent)
+    },
+
+    onStreamDeleted: async (event) => {
+      await ensureRegistryExists()
+
+      const streamName = extractStreamName(event.path)
+
+      const changeEvent = registryStateSchema.streams.delete({
+        key: streamName,
+      })
+
+      await registryStream.append(changeEvent)
+    },
+  }
+}