Skip to content

feat: add streams server (Hono + durable-streams) #1203

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Kitenite merged 7 commits into from
Feb 5, 2026
Merged

feat: add streams server (Hono + durable-streams) #1203

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e9263b9
feat: add streams server (Hono + durable-streams)
Kitenite Feb 4, 2026
fd587b3
Merge remote-tracking branch 'origin' into split-ai-chat/streams-server
Kitenite Feb 4, 2026
71a6539
docs(streams): replace mermaid diagrams with ASCII art for universal …
Kitenite Feb 4, 2026
e05c366
feat(streams): listen on 0.0.0.0 and add startup error handling
Kitenite Feb 5, 2026
abc3150
Address comments
Kitenite Feb 5, 2026
16f1d00
Fix lint
Kitenite Feb 5, 2026
b3b875f
Fix test CI
Kitenite Feb 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,3 +67,6 @@ next-env.d.ts

# Reference material downloaded for agents
examples

# Streams data
apps/streams/data/
1 change: 1 addition & 0 deletions apps/streams/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
data/
139 changes: 139 additions & 0 deletions apps/streams/ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
# Durable Streams Architecture

## System Overview

```
┌─────────────────────────────────────────────────────────┐
│ Clients (packages/ai-chat) │
│ │
│ ┌─────────────────────────┐ ┌───────────────────────┐ │
│ │ @durable-streams/client │ │ @durable-streams/state│ │
│ │ │ │ │ │
│ │ DurableStream │ │ State Protocol │ │
│ │ .create(url) │ │ │ │ │
│ │ .append(data) │ │ ▼ TanStack DB │ │
│ │ .read(offset?) │ │ Reactive Collections │ │
│ │ .subscribe(cb) │ │ │ │
│ └────────────┬────────────┘ └───────────┬───────────┘ │
└───────────────┼───────────────────────────┼─────────────┘
│ HTTP + SSE │ HTTP + SSE
▼ ▼
┌─────────────────────────────────────────────────────────┐
│ Server (apps/streams) │
│ │
│ ┌───────────────────────────────────────────────────┐ │
│ │ @durable-streams/server │ │
│ │ │ │
│ │ DurableStreamTestServer (port, host, dataDir) │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ HTTP Protocol │ │ │
│ │ │ │ │ │
│ │ │ PUT /streams/:id ─ Create stream │ │ │
│ │ │ POST /streams/:id ─ Append data │ │ │
│ │ │ GET /streams/:id ─ Read / SSE │ │ │
│ │ │ HEAD /streams/:id ─ Metadata │ │ │
│ │ │ DELETE /streams/:id ─ Delete │ │ │
│ │ └──────────────────┬──────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ FileBackedStreamStore │ │
│ └─────────────────────┬─────────────────────────────┘ │
└────────────────────────┼────────────────────────────────┘
┌────┴─────┐
▼ ▼
┌─────────────────────────────────────────────────────────┐
│ Storage (./data) │
│ │
│ ┌──────────────────┐ ┌────────────────────────────┐ │
│ │ LMDB │ │ Append-Only Logs │ │
│ │ Metadata Index │ │ Stream Data │ │
│ └──────────────────┘ └────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
Comment on lines +5 to +53
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language identifiers to fenced code blocks to satisfy markdownlint.

markdownlint MD040 is triggered because the fences don’t specify a language. Using a neutral language like text keeps rendering the same while passing lint.

✅ Minimal fix 
-```
+```text
...
-```
+```text
...
-```
+```text
...
-```
+```text

Also applies to: 57-95, 99-118, 122-139

🧰 Tools
🪛 markdownlint-cli2 (0.20.0)

[warning] 5-5: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In `@apps/streams/ARCHITECTURE.md` around lines 5 - 53, The markdown code fences
in ARCHITECTURE.md lack language identifiers and trigger markdownlint MD040;
update every triple-backtick fenced block (the ASCII diagrams/code blocks shown
throughout the file) to include a neutral language tag such as "text" (i.e.,
change ``` to ```text for each fenced block including the diagram at the top and
the other blocks referenced), ensuring all occurrences (including the blocks
around lines 57-95, 99-118, 122-139) are updated so lint passes while rendering
remains unchanged.


## Request/Response Flow

```
Agent A (Writer) Server Agent B (Reader)
│ │ │
│ PUT /streams/session-123 │ │
│ Content-Type: app/json │ │
│ ─────────────────────────>│ │
│ │ │
│ 201 Created │ │
│ Stream-Next-Offset: 0_0 │ │
│ <─────────────────────────│ │
│ │ │
│ POST /streams/session-123│ │
│ Producer-Id: agent-a │ │
│ Producer-Epoch: 0 │ │
│ Producer-Seq: 0 │ │
│ [{"type":"message",...}] │ │
│ ─────────────────────────>│ │
│ │ │
│ 204 No Content │ │
│ Stream-Next-Offset: 0_45 │ │
│ <─────────────────────────│ │
│ │ │
│ │ GET /streams/session-123 │
│ │ Accept: text/event-stream│
│ │ <─────────────────────────│
│ │ │
│ │ SSE: event: data │
│ │ [{"type":"message",...}] │
│ │ ─────────────────────────>│
│ │ │
│ POST (more messages) │ │
│ Producer-Seq: 1 │ │
│ ─────────────────────────>│ │
│ │ │
│ 204 No Content │ │
│ <─────────────────────────│ SSE: event: data │
│ │ (real-time update) │
│ │ ─────────────────────────>│
```

## Producer Idempotency Headers

```
POST Request Headers Response Headers
┌──────────────────────────────────┐ ┌────────────────────────────────┐
│ Producer-Id ─ Unique ID │ │ Stream-Next-Offset ─ Next pos │
│ Producer-Epoch ─ Leader election│ │ Stream-Up-To-Date ─ No more │
│ Producer-Seq ─ Sequence num │ │ Stream-Cursor ─ Cache key │
└────────────────┬─────────────────┘ └────────────────────────────────┘
│
│ Enables
▼
┌──────────────────────────────────┐
│ Features │
│ │
│ • Idempotent Writes ─ Dedup │
│ • Zombie Fencing ─ Stale │
│ producer rejection │
│ • Ordering ─ Gap │
│ detection │
└──────────────────────────────────┘
```

## Package Dependencies

```
┌──────────────────────────┐ ┌───────────────────────────────────┐
│ apps/streams │ │ packages/ai-chat │
│ │ │ │
│ src/index.ts │ │ src/index.ts │
│ │ │ │ ├──▶ @durable-streams/client │
│ ▼ │ │ │ DurableStream │
│ @durable-streams/server │ │ │ │
│ DurableStreamTestServer│ │ └──▶ @durable-streams/state │
│ FileBackedStreamStore │ │ State Protocol │
│ │ │ TanStack DB │
└────────────┬─────────────┘ └──────┬──────────────┬─────────────┘
│ │ │
│ Server API │ Client API │ State API
│◄────────────────────────────┘ │
│◄───────────────────────────────────────────┘
│ HTTP / SSE
```
41 changes: 41 additions & 0 deletions apps/streams/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
FROM oven/bun:1.3.0 AS builder

# Build context must be the repo root (docker build -f apps/streams/Dockerfile .)

WORKDIR /app

# Install dependencies (workspace root)
COPY package.json bun.lock ./
COPY tooling/typescript/package.json tooling/typescript/
COPY apps/streams/package.json apps/streams/
RUN bun install --frozen-lockfile

Comment thread
Kitenite marked this conversation as resolved.
# Copy source
COPY tooling/typescript tooling/typescript
COPY apps/streams apps/streams

# Build
WORKDIR /app/apps/streams
RUN bun run build

# Production image
FROM oven/bun:1.3.0

WORKDIR /app

ENV NODE_ENV=production

# Install production dependencies (workspace root)
COPY package.json bun.lock ./
COPY tooling/typescript/package.json tooling/typescript/
COPY apps/streams/package.json apps/streams/
RUN bun install --frozen-lockfile --production

# Copy built files
COPY --from=builder /app/apps/streams/dist ./apps/streams/dist

WORKDIR /app/apps/streams

EXPOSE 8080

CMD ["bun", "dist/index.js"]
36 changes: 36 additions & 0 deletions apps/streams/fly.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# fly.toml for Superset Stream Server
app = "superset-stream"
primary_region = "iad"

[build]
# Deploy from repo root so Docker build context includes workspaces.
dockerfile = "apps/streams/Dockerfile"

[env]
PORT = "8080"
NODE_ENV = "production"
DATA_DIR = "/data"

[http_service]
internal_port = 8080
force_https = true
auto_stop_machines = "stop"
auto_start_machines = true
min_machines_running = 1
processes = ["app"]

[[http_service.checks]]
interval = "15s"
timeout = "2s"
grace_period = "5s"
method = "GET"
path = "/health"

[mounts]
source = "stream_data"
destination = "/data"

[[vm]]
memory = "256mb"
cpu_kind = "shared"
cpus = 1
29 changes: 29 additions & 0 deletions apps/streams/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
{
"name": "@superset/streams",
"version": "0.0.1",
"description": "Durable Stream server for real-time token streaming",
"type": "module",
"main": "./dist/index.js",
"scripts": {
"dev": "tsx watch src/index.ts",
"build": "tsup src/index.ts --format esm --dts",
"start": "node dist/index.js",
"typecheck": "tsc --noEmit",
"test": "vitest run --passWithNoTests",
"test:conformance": "npx @durable-streams/server-conformance-tests --run http://localhost:8080"
},
"dependencies": {
"@durable-streams/server": "^0.2.0"
},
"devDependencies": {
"@durable-streams/client": "^0.2.0",
"@durable-streams/server-conformance-tests": "^0.2.0",
"@superset/typescript": "workspace:*",
"@types/node": "^24.9.1",
"fast-check": "^4.5.3",
"tsup": "^8.5.0",
"tsx": "^4.19.3",
"typescript": "^5.9.3",
"vitest": "^4.0.0"
Comment thread
Kitenite marked this conversation as resolved.
}
}
Loading