@greendrake/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Greendrake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @greendrake/server
+
+What a service binary needs around its request handler: health probes an orchestrator can route on, CORS, and the SIGTERM sequence that gets the process out of the way without dropping work. **Runs on [bun](https://bun.sh)** — it owns the `Bun.serve` call.
+
+It knows nothing about what the service serves; [`@greendrake/rpc-server`](../rpc-server) is one thing that can sit inside it, a plain `fetch` handler is another.
+
+## Install
+
+```sh
+bun add @greendrake/server
+```
+
+TypeScript source ships as-is (`src/main.ts` is the entry; no build step, no `.d.ts`). Extend `@greendrake/dev-config/tsconfig/node.json` with `"types": ["bun"]`.
+
+## Serving
+
+```ts
+import { serve } from '@greendrake/server'
+
+const service = serve({
+    name: 'billing-api',
+    port: 8080,
+    fetch: (request, server) => router(request, server),
+    checks: [
+        { name: 'db', check: signal => db.ping(signal) },
+        { name: 'cache', check: signal => cache.ping(signal) }
+    ],
+    probeTimeoutMs: 2000,
+    shutdown: { deadlineMs: 15_000, lameDuckMs: 3000 },
+    drain: () => worker.finish()
+})
+```
+
+`websocket` takes a `Bun.serve` WebSocket handler where the service has one. `cors` takes `{ origin?, allowHeaders?, exposeHeaders? }`, or `false` for a service no browser reaches.
+
+The returned handle carries the `Bun.Server`, a `draining` flag the application can read to stop taking on work of its own, and `stop()` — the same sequence the signal handlers run, so a test can drive it without the process exiting.
+
+## Probes
+
+`/healthz` — is this process still the process. It deliberately asks nothing of the dependencies: a database outage must not get the service killed and restarted into the same outage. 200, or 503 once draining.
+
+`/readyz` — can this process serve right now. Every check runs at once under `probeTimeoutMs`, and the body names each one's verdict, so a stalled deploy says which dependency and why rather than leaving a bare 503 to be guessed at:
+
+```json
+{ "db": "ok", "cache": "fail: connection refused" }
+```
+
+The deadline is enforced around each check rather than left to it: a dependency that has stopped answering typically stops answering its cancellation too, and a readiness probe that hangs is worse than one that fails. The check still receives the signal, and should pass it to its I/O.
+
+Both are answered before the application's `fetch` sees the request, and CORS wraps both — a preflight never reaches the app router, or any middleware hung off it that would charge a rate limit for a request the browser made on its own.
+
+## Shutting down
+
+On SIGINT or SIGTERM, in order:
+
+1. `draining` flips, so the probes report 503 and whatever routes traffic stops sending it.
+2. `lameDuckMs` passes, still serving — that gap is what gives the unready state time to propagate before the sockets stop accepting. Zero for a service nothing routes to.
+3. The listener stops accepting, then `drain()` runs: finish in-flight work, close pools, flush.
+
+The whole sequence races `deadlineMs`. Past it `stop()` answers `'forced'` and the signal handler exits non-zero — task brokers and HTTP clients recover from that (re-delivery, retry), whereas a binary that will not die has to be killed by something else.

package/package.json

@@ -0,0 +1,41 @@
+{
+    "name": "@greendrake/server",
+    "version": "0.1.0",
+    "description": "Service-binary scaffolding for bun: dependency health probes with /healthz + /readyz, CORS, and the SIGTERM-driven graceful-shutdown sequence",
+    "license": "MIT",
+    "author": "Eugene Greendrake <eugene@greendrake.nz>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/greendrake/lib.git",
+        "directory": "server"
+    },
+    "homepage": "https://github.com/greendrake/lib/tree/main/server#readme",
+    "bugs": {
+        "url": "https://github.com/greendrake/lib/issues"
+    },
+    "type": "module",
+    "main": "src/main.ts",
+    "types": "src/main.ts",
+    "exports": {
+        ".": {
+            "types": "./src/main.ts",
+            "default": "./src/main.ts"
+        }
+    },
+    "files": [
+        "src"
+    ],
+    "sideEffects": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "check": "tsc --noEmit"
+    },
+    "prettier": "@greendrake/dev-config/prettier",
+    "devDependencies": {
+        "@greendrake/dev-config": "0.1.0",
+        "@types/bun": "^1.3.5",
+        "typescript": "6.0.3"
+    }
+}

package/src/cors.ts

@@ -0,0 +1,53 @@
+import type { FetchHandler } from './serve'
+
+// What a browser may send. The list is the union of what a JSON API over fetch
+// needs; a service whose clients send more names them in `allowHeaders`.
+const REQUEST_HEADERS = ['Accept', 'Authorization', 'Cache-Control', 'Content-Type', 'Origin', 'X-Requested-With']
+
+const METHODS = ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS']
+
+export interface CorsOptions {
+    // `*` by default. These APIs authorize by token rather than by cookie, so
+    // the browser's origin is not what controls access — locking it down is a
+    // defence in depth a deployment may still want.
+    origin?: string
+    // Added to the defaults above.
+    allowHeaders?: string[]
+    // Response headers a browser client may read. Everything else is hidden
+    // from it whatever the server sends.
+    exposeHeaders?: string[]
+}
+
+// CORS at the outermost layer, so a preflight is answered before it reaches
+// the application — and before any middleware hung off it that would charge a
+// rate limit or a captcha for a request the browser made on its own.
+export const withCors = <T>(fetch: FetchHandler<T>, options: CorsOptions = {}): FetchHandler<T> => {
+    const origin = options.origin ?? '*'
+    const headers: Record<string, string> = {
+        'Access-Control-Allow-Origin': origin,
+        'Access-Control-Allow-Headers': [...REQUEST_HEADERS, ...(options.allowHeaders ?? [])].join(', '),
+        'Access-Control-Allow-Methods': METHODS.join(', ')
+    }
+    // A browser refuses credentials against a wildcard origin, so claiming to
+    // allow them there is not merely useless but misleading.
+    if (origin !== '*') {
+        headers['Access-Control-Allow-Credentials'] = 'true'
+    }
+    if (options.exposeHeaders?.length) {
+        headers['Access-Control-Expose-Headers'] = options.exposeHeaders.join(', ')
+    }
+
+    return async (request, server) => {
+        if (request.method === 'OPTIONS') {
+            return new Response(null, { status: 204, headers })
+        }
+        const response = await fetch(request, server)
+        // Nothing to decorate: the request was upgraded to a WebSocket, whose
+        // handshake CORS does not govern.
+        if (!response) {
+            return undefined
+        }
+        Object.entries(headers).forEach(([name, value]) => response.headers.set(name, value))
+        return response
+    }
+}

package/src/main.ts

@@ -0,0 +1,3 @@
+export { healthz, readyz, runChecks, type CheckResult, type DependencyCheck } from './probes'
+export { withCors, type CorsOptions } from './cors'
+export { serve, type FetchHandler, type RunningService, type ServeOptions, type ShutdownOptions } from './serve'

package/src/probes.ts

@@ -0,0 +1,57 @@
+// One dependency this service cannot serve without, and how to ask it. The
+// signal is already bounded by the probe deadline — a check must not add a
+// timeout of its own on top.
+export interface DependencyCheck {
+    name: string
+    check(signal: AbortSignal): Promise<void>
+}
+
+export interface CheckResult {
+    ok: boolean
+    // "ok", or "fail: <reason>" — the readiness body is what an operator reads
+    // when a deploy stalls, so a failure says which dependency and why rather
+    // than leaving a bare 503 to be guessed at.
+    message: string
+}
+
+// Every check at once, each under the same deadline. The deadline is enforced
+// here rather than left to the check: a dependency that has stopped answering
+// typically stops answering its cancellation too, and a readiness probe that
+// hangs is worse than one that fails.
+export const runChecks = async (checks: DependencyCheck[], timeoutMs: number): Promise<Record<string, CheckResult>> => {
+    const results = await Promise.all(
+        checks.map(async ({ name, check }): Promise<[string, CheckResult]> => {
+            const signal = AbortSignal.timeout(timeoutMs)
+            const expiry = new Promise<never>((_, reject) => {
+                signal.addEventListener('abort', () => reject(new Error(`timed out after ${timeoutMs}ms`)), { once: true })
+            })
+            try {
+                await Promise.race([check(signal), expiry])
+                return [name, { ok: true, message: 'ok' }]
+            } catch (e) {
+                return [name, { ok: false, message: `fail: ${(e as Error).message}` }]
+            }
+        })
+    )
+    return Object.fromEntries(results)
+}
+
+const json = (status: number, body: Record<string, unknown>): Response => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json; charset=utf-8' } })
+
+// Liveness: is this process still the process. It deliberately asks nothing of
+// the dependencies — a database outage must not get the service killed and
+// restarted into the same outage. 503 while draining, so a load balancer stops
+// sending work before the sockets close.
+export const healthz = (draining: boolean): Response => json(draining ? 503 : 200, { status: draining ? 'draining' : 'ok' })
+
+// Readiness: can this process serve right now. Every dependency is probed, and
+// the body names each one's verdict.
+export const readyz = async (checks: DependencyCheck[], timeoutMs: number, draining: boolean): Promise<Response> => {
+    const results = await runChecks(checks, timeoutMs)
+    const body: Record<string, unknown> = Object.fromEntries(Object.entries(results).map(([name, result]) => [name, result.message]))
+    if (draining) {
+        body.draining = true
+    }
+    const ready = !draining && Object.values(results).every(result => result.ok)
+    return json(ready ? 200 : 503, body)
+}

package/src/serve.ts

@@ -0,0 +1,128 @@
+import type { Server, WebSocketHandler } from 'bun'
+import { withCors, type CorsOptions } from './cors'
+import { healthz, readyz, type DependencyCheck } from './probes'
+
+// Bun's request handler, including the `undefined` a handler returns once it
+// has upgraded the request to a WebSocket.
+export type FetchHandler<T = undefined> = (request: Request, server: Server<T>) => Response | undefined | Promise<Response | undefined>
+
+export interface ShutdownOptions {
+    // The whole sequence's budget. Past it the process exits non-zero: task
+    // brokers and HTTP clients recover from that (re-delivery, retry), whereas
+    // a binary that will not die has to be killed by something else.
+    deadlineMs: number
+    // How long to keep serving after the probes start reporting unready, so
+    // whatever routes traffic notices before the sockets stop accepting. Zero
+    // for anything nothing routes to.
+    lameDuckMs: number
+}
+
+export interface ServeOptions<T> {
+    // Appears in the startup and forced-exit log lines, so a host running
+    // several binaries says which one.
+    name: string
+    port: number
+    // The application's routes. Probes and CORS are answered before it.
+    fetch: FetchHandler<T>
+    websocket?: WebSocketHandler<T>
+    checks?: DependencyCheck[]
+    probeTimeoutMs: number
+    shutdown: ShutdownOptions
+    // false disables CORS entirely — for a service reached only by other
+    // services, where no browser is involved.
+    cors?: CorsOptions | false
+    // Application teardown, run once the listener has stopped accepting:
+    // finish in-flight work, close pools, flush.
+    drain?: () => Promise<void> | void
+}
+
+export interface RunningService<T> {
+    readonly server: Server<T>
+    // Set from the moment shutdown begins: the probes report it, and an
+    // application can read it to stop taking on new work of its own.
+    readonly draining: boolean
+    // The shutdown sequence, as the signal handlers run it. 'forced' means the
+    // deadline elapsed first — the caller decides what that is worth, which is
+    // what lets a test drive this without the process exiting.
+    stop(): Promise<'clean' | 'forced'>
+}
+
+// Runs a service binary: bind the port, answer the probes, and shut down on
+// SIGINT/SIGTERM the same way every time — unready first, then stop accepting,
+// then drain, all inside one deadline.
+export const serve = <T>(options: ServeOptions<T>): RunningService<T> => {
+    let draining = false
+    const app: FetchHandler<T> = (request, server) => {
+        const { pathname } = new URL(request.url)
+        if (pathname === '/healthz') {
+            return healthz(draining)
+        }
+        if (pathname === '/readyz') {
+            return readyz(options.checks ?? [], options.probeTimeoutMs, draining)
+        }
+        return options.fetch(request, server)
+    }
+    const fetch = options.cors === false ? app : withCors(app, options.cors)
+    // Bun's options are two distinct shapes, and an explicit
+    // `websocket: undefined` fits neither. The shapes differ in their fetch
+    // signature too: only the WebSocket one allows a handler to answer
+    // nothing, which is how a successful upgrade is reported.
+    const server = options.websocket
+        ? Bun.serve<T, never>({
+              port: options.port,
+              fetch,
+              websocket: options.websocket
+          })
+        : Bun.serve<T, never>({
+              port: options.port,
+              fetch: async (request, srv) => {
+                  const response = await fetch(request, srv)
+                  if (!response) {
+                      throw new Error(`${options.name}: no response for ${request.url}, and no WebSocket handler configured that could have upgraded it`)
+                  }
+                  return response
+              }
+          })
+    console.log(`${options.name} listening on ${server.url.href}`)
+
+    const stop = async (): Promise<'clean' | 'forced'> => {
+        draining = true
+        const { deadlineMs, lameDuckMs } = options.shutdown
+        let timer: ReturnType<typeof setTimeout> | undefined
+        const expiry = new Promise<'forced'>(resolve => {
+            timer = setTimeout(() => resolve('forced'), deadlineMs)
+        })
+        const sequence = async (): Promise<'clean'> => {
+            await Bun.sleep(lameDuckMs)
+            await server.stop()
+            await options.drain?.()
+            return 'clean'
+        }
+        try {
+            return await Promise.race([sequence(), expiry])
+        } finally {
+            clearTimeout(timer)
+        }
+    }
+
+    const onSignal = (): void => {
+        void stop().then(outcome => {
+            if (outcome === 'forced') {
+                console.error(`${options.name}: shutdown deadline (${options.shutdown.deadlineMs}ms) exceeded, forcing exit`)
+                process.exit(1)
+            }
+            console.log(`${options.name} stopped`)
+            process.exit(0)
+        })
+    }
+    process.on('SIGINT', onSignal)
+    process.on('SIGTERM', onSignal)
+
+    return {
+        server,
+        get draining() {
+            return draining
+        },
+        stop
+    }
+}