refactor(session-broker): split broker into reusable runtime-neutral packages (#205)

Author: benvinegar

.github/workflows/benchmarks.yml

@@ -11,6 +11,9 @@ on:
       - "LICENSE"
   workflow_dispatch:
 
+env:
+  SKIP_INSTALL_SIMPLE_GIT_HOOKS: "1"
+
 concurrency:
   group: benchmarks-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true

.github/workflows/ci.yml

@@ -10,6 +10,9 @@ on:
       - "assets/**"
       - "LICENSE"
 
+env:
+  SKIP_INSTALL_SIMPLE_GIT_HOOKS: "1"
+
 concurrency:
   group: main-ci-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true

.github/workflows/pr-ci.yml

@@ -8,6 +8,9 @@ on:
       - "assets/**"
       - "LICENSE"
 
+env:
+  SKIP_INSTALL_SIMPLE_GIT_HOOKS: "1"
+
 concurrency:
   group: pr-ci-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true

.github/workflows/release-prebuilt-npm.yml

@@ -17,6 +17,9 @@ on:
     tags:
       - "v*"
 
+env:
+  SKIP_INSTALL_SIMPLE_GIT_HOOKS: "1"
+
 concurrency:
   group: release-prebuilt-${{ github.ref }}
   cancel-in-progress: false

bun.lock

@@ -22,6 +22,9 @@
   "bin": {
     "hunk": "./bin/hunk.cjs"
   },
+  "workspaces": [
+    "packages/*"
+  ],
   "files": [
     "bin",
     "dist/npm",
@@ -55,7 +58,7 @@
     "lint": "oxlint . --deny-warnings",
     "lint:fix": "oxlint . --fix",
     "prepare": "simple-git-hooks",
-    "test": "\"${npm_execpath:-bun}\" test ./src ./scripts ./test/cli ./test/session",
+    "test": "\"${npm_execpath:-bun}\" test ./src ./packages ./scripts ./test/cli ./test/session",
     "test:integration": "\"${npm_execpath:-bun}\" test ./test/pty",
     "test:tty-smoke": "HUNK_RUN_TTY_SMOKE=1 \"${npm_execpath:-bun}\" test ./test/smoke",
     "check:pack": "bun run ./scripts/check-pack.ts",
@@ -76,10 +79,15 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@hunk/session-broker": "workspace:*",
+    "@hunk/session-broker-bun": "workspace:*",
+    "@hunk/session-broker-core": "workspace:*",
+    "@hunk/session-broker-node": "workspace:*",
     "@opentui/core": "^0.1.88",
     "@opentui/react": "^0.1.88",
     "@types/bun": "latest",
     "@types/react": "^19.2.14",
+    "@types/ws": "^8.18.1",
     "lint-staged": "^16.4.0",
     "oxfmt": "^0.41.0",
     "oxlint": "^1.56.0",

package.json

@@ -0,0 +1,62 @@
+# @hunk/session-broker-bun
+
+Bun HTTP and websocket adapter for `@hunk/session-broker`.
+
+Use this package when you want to serve a runtime-neutral `SessionBrokerDaemon` through `Bun.serve(...)`.
+
+## What it does
+
+- binds a broker daemon to a Bun HTTP server
+- upgrades websocket requests on the daemon socket path
+- forwards websocket messages and close events into the daemon
+- exposes a `stopped` promise compatible with Hunk's daemon lifecycle
+- lets callers override or add custom HTTP routes before the generic broker routes
+
+## Usage
+
+```ts
+import { SessionBroker, createSessionBrokerDaemon } from "@hunk/session-broker";
+import { serveSessionBrokerDaemon } from "@hunk/session-broker-bun";
+
+const broker = new SessionBroker({
+  parseRegistration,
+  parseSnapshot,
+});
+
+const daemon = createSessionBrokerDaemon({
+  broker,
+  capabilities: { version: 1, name: "example-broker" },
+});
+
+const server = serveSessionBrokerDaemon({
+  daemon,
+  hostname: "127.0.0.1",
+  port: 47657,
+});
+```
+
+## Custom routes
+
+You can override or extend request handling with `handleRequest`.
+
+```ts
+const server = serveSessionBrokerDaemon({
+  daemon,
+  hostname: "127.0.0.1",
+  port: 47657,
+  handleRequest: async (request) => {
+    const url = new URL(request.url);
+    if (url.pathname === "/health") {
+      return Response.json({ ok: true, overridden: true });
+    }
+
+    return undefined;
+  },
+});
+```
+
+Return `undefined` to fall through to the generic broker routes.
+
+## License
+
+MIT

packages/session-broker-bun/README.md

@@ -0,0 +1,25 @@
+{
+  "name": "@hunk/session-broker-bun",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Bun HTTP and websocket adapter for @hunk/session-broker.",
+  "license": "MIT",
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@hunk/session-broker": "workspace:*"
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18"
+  }
+}

packages/session-broker-bun/package.json

@@ -0,0 +1 @@
+export * from "./serve";