@durable-streams/server 0.2.3 → 0.3.0

package/src/server.ts

@@ -36,6 +36,10 @@ const SSE_CLOSED_FIELD = `streamClosed`
 // Stream closure header
 const STREAM_CLOSED_HEADER = `Stream-Closed`
 
+// Fork headers (request headers only — not set on responses)
+const STREAM_FORKED_FROM_HEADER = `Stream-Forked-From`
+const STREAM_FORK_OFFSET_HEADER = `Stream-Fork-Offset`
+
 // Query params
 const OFFSET_QUERY_PARAM = `offset`
 const LIVE_QUERY_PARAM = `live`
@@ -427,7 +431,7 @@ export class DurableStreamTestServer {
     )
     res.setHeader(
       `access-control-allow-headers`,
-      `content-type, authorization, Stream-Seq, Stream-TTL, Stream-Expires-At, Stream-Closed, Producer-Id, Producer-Epoch, Producer-Seq`
+      `content-type, authorization, Stream-Seq, Stream-TTL, Stream-Expires-At, Stream-Closed, Producer-Id, Producer-Epoch, Producer-Seq, Stream-Forked-From, Stream-Fork-Offset`
     )
     res.setHeader(
       `access-control-expose-headers`,
@@ -511,7 +515,15 @@ export class DurableStreamTestServer {
       }
     } catch (err) {
       if (err instanceof Error) {
-        if (err.message.includes(`not found`)) {
+        if (err.message.includes(`active forks`)) {
+          res.writeHead(409, { "content-type": `text/plain` })
+          res.end(
+            `stream was deleted but still has active forks — path cannot be reused until all forks are removed`
+          )
+        } else if (err.message.includes(`soft-deleted`)) {
+          res.writeHead(410, { "content-type": `text/plain` })
+          res.end(`Stream is gone`)
+        } else if (err.message.includes(`not found`)) {
           res.writeHead(404, { "content-type": `text/plain` })
           res.end(`Stream not found`)
         } else if (
@@ -570,6 +582,14 @@ export class DurableStreamTestServer {
     const closedHeader = req.headers[STREAM_CLOSED_HEADER.toLowerCase()]
     const createClosed = closedHeader === `true`
 
+    // Parse fork headers
+    const forkedFromHeader = req.headers[
+      STREAM_FORKED_FROM_HEADER.toLowerCase()
+    ] as string | undefined
+    const forkOffsetHeader = req.headers[
+      STREAM_FORK_OFFSET_HEADER.toLowerCase()
+    ] as string | undefined
+
     // Validate TTL and Expires-At headers
     if (ttlHeader && expiresAtHeader) {
       res.writeHead(400, { "content-type": `text/plain` })
@@ -606,21 +626,59 @@ export class DurableStreamTestServer {
       }
     }
 
+    // Validate fork offset format if provided
+    if (forkOffsetHeader) {
+      const validOffsetPattern = /^\d+_\d+$/
+      if (!validOffsetPattern.test(forkOffsetHeader)) {
+        res.writeHead(400, { "content-type": `text/plain` })
+        res.end(`Invalid Stream-Fork-Offset format`)
+        return
+      }
+    }
+
     // Read body if present
     const body = await this.readBody(req)
 
     const isNew = !this.store.has(path)
 
     // Support both sync (StreamStore) and async (FileBackedStreamStore) create
-    await Promise.resolve(
-      this.store.create(path, {
-        contentType,
-        ttlSeconds,
-        expiresAt: expiresAtHeader,
-        initialData: body.length > 0 ? body : undefined,
-        closed: createClosed,
-      })
-    )
+    try {
+      await Promise.resolve(
+        this.store.create(path, {
+          contentType,
+          ttlSeconds,
+          expiresAt: expiresAtHeader,
+          initialData: body.length > 0 ? body : undefined,
+          closed: createClosed,
+          forkedFrom: forkedFromHeader,
+          forkOffset: forkOffsetHeader,
+        })
+      )
+    } catch (err) {
+      if (err instanceof Error) {
+        if (err.message.includes(`Source stream not found`)) {
+          res.writeHead(404, { "content-type": `text/plain` })
+          res.end(`Source stream not found`)
+          return
+        }
+        if (err.message.includes(`Invalid fork offset`)) {
+          res.writeHead(400, { "content-type": `text/plain` })
+          res.end(`Fork offset beyond source stream length`)
+          return
+        }
+        if (err.message.includes(`soft-deleted`)) {
+          res.writeHead(409, { "content-type": `text/plain` })
+          res.end(`source stream was deleted but still has active forks`)
+          return
+        }
+        if (err.message.includes(`Content type mismatch`)) {
+          res.writeHead(409, { "content-type": `text/plain` })
+          res.end(`Content type mismatch with source stream`)
+          return
+        }
+      }
+      throw err
+    }
 
     const stream = this.store.get(path)!
 
@@ -630,7 +688,7 @@ export class DurableStreamTestServer {
         this.options.onStreamCreated({
           type: `created`,
           path,
-          contentType,
+          contentType: stream.contentType ?? contentType,
           timestamp: Date.now(),
         })
       )
@@ -638,7 +696,7 @@ export class DurableStreamTestServer {
 
     // Return 201 for new streams, 200 for idempotent creates
     const headers: Record<string, string> = {
-      "content-type": contentType,
+      "content-type": stream.contentType ?? contentType,
       [STREAM_OFFSET_HEADER]: stream.currentOffset,
     }
 
@@ -667,6 +725,13 @@ export class DurableStreamTestServer {
       return
     }
 
+    // Check for soft-deleted streams
+    if (stream.softDeleted) {
+      res.writeHead(410, { "content-type": `text/plain` })
+      res.end()
+      return
+    }
+
     const headers: Record<string, string> = {
       [STREAM_OFFSET_HEADER]: stream.currentOffset,
       // HEAD responses should not be cached to avoid stale tail offsets (Protocol Section 5.4)
@@ -682,6 +747,14 @@ export class DurableStreamTestServer {
       headers[STREAM_CLOSED_HEADER] = `true`
     }
 
+    // Include TTL/Expiry metadata
+    if (stream.ttlSeconds !== undefined) {
+      headers[STREAM_TTL_HEADER] = String(stream.ttlSeconds)
+    }
+    if (stream.expiresAt) {
+      headers[STREAM_EXPIRES_AT_HEADER] = stream.expiresAt
+    }
+
     // Generate ETag: {path}:-1:{offset}[:c] (includes closure status)
     // The :c suffix ensures ETag changes when a stream is closed, even without new data
     const closedSuffix = stream.closed ? `:c` : ``
@@ -708,6 +781,13 @@ export class DurableStreamTestServer {
       return
     }
 
+    // Check for soft-deleted streams
+    if (stream.softDeleted) {
+      res.writeHead(410, { "content-type": `text/plain` })
+      res.end(`Stream is gone`)
+      return
+    }
+
     const offset = url.searchParams.get(OFFSET_QUERY_PARAM) ?? undefined
     const live = url.searchParams.get(LIVE_QUERY_PARAM)
     const cursor = url.searchParams.get(CURSOR_QUERY_PARAM) ?? undefined
@@ -802,6 +882,7 @@ export class DurableStreamTestServer {
 
     // Read current messages
     let { messages, upToDate } = this.store.read(path, effectiveOffset)
+    this.store.touchAccess(path)
 
     // Only wait in long-poll if:
     // 1. long-poll mode is enabled
@@ -828,6 +909,7 @@ export class DurableStreamTestServer {
         effectiveOffset ?? stream.currentOffset,
         this.options.longPollTimeout
       )
+      this.store.touchAccess(path)
 
       // If stream was closed during wait, return immediately with Stream-Closed
       if (result.streamClosed) {
@@ -1005,6 +1087,7 @@ export class DurableStreamTestServer {
     while (isConnected && !this.isShuttingDown) {
       // Read current messages from offset
       const { messages, upToDate } = this.store.read(path, currentOffset)
+      this.store.touchAccess(path)
 
       // Send data events for each message
       for (const message of messages) {
@@ -1093,6 +1176,7 @@ export class DurableStreamTestServer {
           currentOffset,
           this.options.longPollTimeout
         )
+        this.store.touchAccess(path)
 
         // Check if we should exit after wait returns (values can change during await)
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
@@ -1362,6 +1446,7 @@ export class DurableStreamTestServer {
         this.store.append(path, body, appendOptions)
       )
     }
+    this.store.touchAccess(path)
 
     // Handle AppendResult with producer validation or streamClosed
     if (result && typeof result === `object` && `message` in result) {
@@ -1491,14 +1576,21 @@ export class DurableStreamTestServer {
    * Handle DELETE - delete stream
    */
   private async handleDelete(path: string, res: ServerResponse): Promise<void> {
-    if (!this.store.has(path)) {
+    // Check for soft-deleted streams before attempting delete
+    const existing = this.store.get(path)
+    if (existing?.softDeleted) {
+      res.writeHead(410, { "content-type": `text/plain` })
+      res.end(`Stream is gone`)
+      return
+    }
+
+    const deleted = this.store.delete(path)
+    if (!deleted) {
       res.writeHead(404, { "content-type": `text/plain` })
       res.end(`Stream not found`)
       return
     }
 
-    this.store.delete(path)
-
     // Call lifecycle hook
     if (this.options.onStreamDeleted) {
       await Promise.resolve(