@thoughtpivot/flight 2.0.2 → 3.0.0

package/src/bun/koa-compat.ts

@@ -0,0 +1,166 @@
+import { EventEmitter } from 'node:events'
+import { Readable } from 'node:stream'
+
+import type { KoaMiddleware } from './backends'
+
+/** Node-style response stand-in that Koa's `res.end()` can finish. */
+class MockResponse extends EventEmitter {
+    statusCode = 404
+    headersSent = false
+    finished = false
+    writableEnded = false
+    /** Left unset so `on-finished` does not treat a plain object as a socket. */
+    socket: EventEmitter | null = null
+    flightMatched = false
+    private chunks: Buffer[] = []
+    private headers = new Map<string, string | string[]>()
+
+    /** Store a response header. Repeated Set-Cookie values accumulate. */
+    setHeader(name: string, value: string | number | string[]) {
+        const key = name.toLowerCase()
+        if (key === 'set-cookie') {
+            const next = (Array.isArray(value) ? value : [value]).map(String)
+            const prev = this.headers.get(key)
+            const existing = prev === undefined ? [] : Array.isArray(prev) ? prev : [prev]
+            this.headers.set(key, existing.concat(next))
+            return
+        }
+        this.headers.set(key, Array.isArray(value) ? value.map(String) : String(value))
+    }
+
+    /** Read a response header. */
+    getHeader(name: string): string | string[] | undefined {
+        return this.headers.get(name.toLowerCase())
+    }
+
+    /** Remove a response header. */
+    removeHeader(name: string) {
+        this.headers.delete(name.toLowerCase())
+    }
+
+    /** Record the status line. Koa calls this before `end` when headers are flushed. */
+    writeHead(status: number, headers?: Record<string, string | string[]>) {
+        this.statusCode = status
+        if (headers) {
+            for (const [key, value] of Object.entries(headers)) this.setHeader(key, value)
+        }
+        this.headersSent = true
+        return this
+    }
+
+    /** No-op. Koa sometimes flushes headers early. */
+    flushHeaders() {
+        this.headersSent = true
+    }
+
+    /** Buffer a chunk. */
+    write(chunk?: string | Buffer) {
+        if (chunk) this.chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
+        return true
+    }
+
+    /** Finish the response and emit the events `on-finished` listens for. */
+    end(chunk?: string | Buffer) {
+        if (chunk) this.write(chunk)
+        this.finished = true
+        this.writableEnded = true
+        this.headersSent = true
+        this.emit('finish')
+        this.emit('close')
+        return this
+    }
+
+    /** Build the Fetch response from the buffered status, headers, and body. */
+    toResponse(): Response {
+        const headers = new Headers()
+        for (const [key, value] of this.headers) {
+            if (Array.isArray(value)) {
+                for (const item of value) headers.append(key, item)
+            } else {
+                headers.set(key, value)
+            }
+        }
+        const body = this.chunks.length ? Buffer.concat(this.chunks) : null
+        return new Response(body, { status: this.statusCode, headers })
+    }
+}
+
+/**
+ * Adapt a Fetch request into the readable Node request Koa and bodyparser expect.
+ */
+function requestFromFetch(request: Request, body: Buffer): Readable {
+    const url = new URL(request.url)
+    const headers: Record<string, string> = {}
+    request.headers.forEach((value, key) => {
+        headers[key] = value
+    })
+    if (!headers['content-length']) headers['content-length'] = String(body.length)
+
+    const req = Readable.from(body.length ? [body] : []) as Readable & Record<string, unknown>
+    req.method = request.method
+    req.url = url.pathname + url.search
+    req.headers = headers
+    req.httpVersion = '1.1'
+    req.httpVersionMajor = 1
+    req.httpVersionMinor = 1
+    req.socket = { remoteAddress: '127.0.0.1', encrypted: false, readable: false, writable: true }
+    req.connection = req.socket
+    return req
+}
+
+/**
+ * Run one Fetch request through a Koa callback. Returns null when no route matched,
+ * so the caller can still serve the SPA.
+ */
+function callbackToFetch(callback: (req: Readable, res: MockResponse) => void) {
+    return async function dispatch(request: Request): Promise<Response | null> {
+        const body =
+            request.method === 'GET' || request.method === 'HEAD'
+                ? Buffer.alloc(0)
+                : Buffer.from(await request.arrayBuffer())
+        const req = requestFromFetch(request, body)
+        const res = new MockResponse()
+
+        await new Promise<void>((resolve, reject) => {
+            res.on('finish', () => resolve())
+            res.on('error', reject)
+            try {
+                callback(req, res)
+            } catch (err) {
+                reject(err)
+            }
+        })
+
+        if (!res.flightMatched) return null
+        return res.toResponse()
+    }
+}
+
+/**
+ * Build a Fetch dispatcher for existing Koa `router.routes()` backends.
+ * JSON bodies are parsed with `koa-bodyparser`. Unmatched paths return null.
+ */
+export async function createKoaDispatcher(
+    middlewares: KoaMiddleware[],
+    payloadLimit: string
+): Promise<(req: Request) => Promise<Response | null>> {
+    const koaModule = await import('koa')
+    const bodyParserModule = await import('koa-bodyparser')
+    const Koa = koaModule.default
+    const bodyParser = bodyParserModule.default
+    const app = new Koa()
+
+    app.use(async (ctx: any, next: () => Promise<void>) => {
+        await next()
+        ctx.res.flightMatched = Array.isArray(ctx.matched) && ctx.matched.length > 0
+    })
+    app.use(
+        bodyParser({
+            jsonLimit: payloadLimit,
+            enableTypes: ['json', 'form', 'text']
+        })
+    )
+    for (const middleware of middlewares) app.use(middleware as any)
+
+    return callbackToFetch(app.callback())
+}

package/src/bun/middleware.ts

@@ -0,0 +1,217 @@
+import type { CompressionConfig, CorsConfig, RateLimitConfig, SecurityConfig } from './config'
+
+/** Web-standard request handler used by discovered routes. */
+export type Handler = (req: Request) => Response | Promise<Response>
+
+/** Continues the onion to the next middleware or the core handler. */
+export type Next = () => Promise<Response>
+
+/** Koa-style middleware over the Fetch API. */
+export type Middleware = (req: Request, next: Next) => Response | Promise<Response>
+
+/** Minimal server surface used to read the peer address. */
+export interface AddressServer {
+    requestIP(req: Request): { address: string } | null
+}
+
+/**
+ * Compose middleware so index 0 is outermost. A middleware may return without calling `next`.
+ */
+export function compose(middlewares: Middleware[]): (req: Request, core: Handler) => Promise<Response> {
+    return function run(req: Request, core: Handler): Promise<Response> {
+        const dispatch = (index: number): Promise<Response> => {
+            const middleware = middlewares[index]
+            if (!middleware) return Promise.resolve(core(req))
+            return Promise.resolve(middleware(req, () => dispatch(index + 1)))
+        }
+        return dispatch(0)
+    }
+}
+
+/**
+ * Copy a response and set extra headers. Works for streaming bodies.
+ */
+export function withHeaders(response: Response, extra: Record<string, string>): Response {
+    const headers = new Headers(response.headers)
+    for (const [key, value] of Object.entries(extra)) headers.set(key, value)
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers
+    })
+}
+
+/**
+ * Log method, path, status, and duration. Off in production unless `FLIGHT_LOGGING` is set.
+ */
+export function logger(): Middleware {
+    return async (req, next) => {
+        const start = performance.now()
+        const response = await next()
+        const ms = (performance.now() - start).toFixed(1)
+        const { pathname } = new URL(req.url)
+        console.log(`${req.method} ${pathname} ${response.status} ${ms}ms`)
+        return response
+    }
+}
+
+const SECURITY_HEADERS: Record<string, string> = {
+    'x-content-type-options': 'nosniff',
+    'x-frame-options': 'SAMEORIGIN',
+    'x-dns-prefetch-control': 'off',
+    'referrer-policy': 'no-referrer',
+    'x-download-options': 'noopen',
+    'x-permitted-cross-domain-policies': 'none',
+    'cross-origin-opener-policy': 'same-origin',
+    'origin-agent-cluster': '?1'
+}
+
+/**
+ * Apply a helmet-style header set. CSP is omitted because a wrong policy breaks the SPA.
+ */
+export function security(cfg: SecurityConfig): Middleware {
+    const headers = { ...SECURITY_HEADERS }
+    if (cfg.hsts) headers['strict-transport-security'] = `max-age=${cfg.hstsMaxAge}; includeSubDomains`
+    return async (_req, next) => withHeaders(await next(), headers)
+}
+
+/**
+ * Build the CORS header set for this request.
+ */
+function corsHeaders(req: Request, cfg: CorsConfig): Record<string, string> {
+    const requestOrigin = req.headers.get('origin')
+    const allowOrigin = cfg.origin === '*' ? (cfg.credentials ? (requestOrigin ?? '*') : '*') : cfg.origin
+    const headers: Record<string, string> = {
+        'access-control-allow-origin': allowOrigin,
+        'access-control-allow-methods': cfg.methods,
+        'access-control-allow-headers': cfg.headers || req.headers.get('access-control-request-headers') || '*',
+        'access-control-max-age': String(cfg.maxAge)
+    }
+    if (cfg.credentials) headers['access-control-allow-credentials'] = 'true'
+    if (allowOrigin !== '*') headers.vary = 'Origin'
+    return headers
+}
+
+/**
+ * Answer CORS preflight and attach `Access-Control-*` headers to every other response.
+ */
+export function cors(cfg: CorsConfig): Middleware {
+    return async (req, next) => {
+        if (req.method === 'OPTIONS') {
+            return new Response(null, { status: 204, headers: corsHeaders(req, cfg) })
+        }
+        return withHeaders(await next(), corsHeaders(req, cfg))
+    }
+}
+
+/**
+ * True when the content type is worth gzipping.
+ */
+function compressible(contentType: string): boolean {
+    return /^(text\/|application\/(json|javascript|xml|.*\+json|.*\+xml)|image\/svg)/i.test(contentType)
+}
+
+/**
+ * Append a Vary token if it is not already present.
+ */
+function appendVary(existing: string | null, value: string): string {
+    if (!existing) return value
+    const parts = existing.split(',').map((part) => part.trim().toLowerCase())
+    return parts.includes(value.toLowerCase()) ? existing : `${existing}, ${value}`
+}
+
+/**
+ * Gzip text and JSON bodies above the threshold when the client accepts gzip.
+ */
+export function compress(cfg: CompressionConfig): Middleware {
+    return async (req, next) => {
+        const response = await next()
+        if (req.method === 'HEAD' || !response.body || response.status === 204 || response.status === 304) {
+            return response
+        }
+        if (response.headers.get('content-encoding')) return response
+        if (!(req.headers.get('accept-encoding') || '').includes('gzip')) return response
+        if (!compressible(response.headers.get('content-type') || '')) return response
+
+        const bytes = new Uint8Array(await response.arrayBuffer())
+        if (bytes.byteLength < cfg.threshold) {
+            return new Response(bytes, {
+                status: response.status,
+                statusText: response.statusText,
+                headers: response.headers
+            })
+        }
+
+        const gzipped = Bun.gzipSync(bytes)
+        const headers = new Headers(response.headers)
+        headers.set('content-encoding', 'gzip')
+        headers.set('content-length', String(gzipped.byteLength))
+        headers.set('vary', appendVary(headers.get('vary'), 'Accept-Encoding'))
+        return new Response(gzipped, {
+            status: response.status,
+            statusText: response.statusText,
+            headers
+        })
+    }
+}
+
+/**
+ * Identity for the rate limiter.
+ * Forwarded headers count only when `FLIGHT_TRUST_PROXY` is on, so a client cannot spoof past the limit.
+ */
+export function clientKey(req: Request, trustProxy: boolean, server?: AddressServer): string {
+    if (trustProxy) {
+        const forwarded = req.headers.get('x-forwarded-for')
+        if (forwarded) return forwarded.split(',')[0].trim()
+        const realIp = req.headers.get('x-real-ip')
+        if (realIp) return realIp
+    }
+    return server?.requestIP(req)?.address || 'local'
+}
+
+/**
+ * True when this GET or HEAD should not consume a rate-limit token.
+ */
+function shouldSkip(pathname: string, method: string, prefixes: string[]): boolean {
+    if (method !== 'GET' && method !== 'HEAD') return false
+    return prefixes.some((prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`))
+}
+
+/**
+ * Fixed-window rate limit. Hashed static prefixes are skipped so assets do not burn the API budget.
+ */
+export function rateLimit(cfg: RateLimitConfig, addressOf: (req: Request) => string): Middleware {
+    const windows = new Map<string, { count: number; resetAt: number }>()
+    return async (req, next) => {
+        const pathname = new URL(req.url).pathname
+        if (shouldSkip(pathname, req.method, cfg.skipPrefixes)) return next()
+
+        const now = Date.now()
+        const key = addressOf(req)
+        let window = windows.get(key)
+        if (!window || window.resetAt <= now) {
+            window = { count: 0, resetAt: now + cfg.durationMs }
+            windows.set(key, window)
+            if (windows.size > 10000) {
+                for (const [storedKey, stored] of windows) {
+                    if (stored.resetAt <= now) windows.delete(storedKey)
+                }
+            }
+        }
+        window.count++
+        const remaining = Math.max(0, cfg.max - window.count)
+        const resetSec = Math.ceil((window.resetAt - now) / 1000)
+        const limitHeaders = {
+            'x-ratelimit-limit': String(cfg.max),
+            'x-ratelimit-remaining': String(remaining),
+            'x-ratelimit-reset': String(resetSec)
+        }
+        if (window.count > cfg.max) {
+            return new Response('Too Many Requests', {
+                status: 429,
+                headers: { ...limitHeaders, 'retry-after': String(resetSec) }
+            })
+        }
+        return withHeaders(await next(), limitHeaders)
+    }
+}

package/src/bun/server.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env bun
+import { loadConfig } from './config'
+import { openFlight } from './app'
+
+const cfg = loadConfig()
+await openFlight(cfg)
+
+if (cfg.mode === 'development') {
+    Bun.spawn(['bunx', 'vite', '--port', '3001', '--host', '0.0.0.0'], {
+        cwd: cfg.appHome,
+        stdout: 'inherit',
+        stderr: 'inherit',
+        stdin: 'inherit'
+    })
+    console.log('flight-bun: spawned Vite dev server on :3001')
+}

package/src/bun/session.ts

@@ -0,0 +1,120 @@
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto'
+
+import type { SessionConfig } from './config'
+import type { Middleware } from './middleware'
+import type { KVStore } from './store'
+
+/** Request carrying the mutable session object. */
+export interface SessionRequest extends Request {
+    session?: Record<string, unknown>
+}
+
+/**
+ * HMAC-sign a session id. The mac is base64url so it is cookie-safe.
+ */
+function sign(value: string, secret: string): string {
+    const mac = createHmac('sha256', secret).update(value).digest('base64url')
+    return `${value}.${mac}`
+}
+
+/**
+ * Return the value when the HMAC matches. Reject tampered cookies.
+ */
+function unsign(signed: string, secret: string): string | null {
+    const splitAt = signed.lastIndexOf('.')
+    if (splitAt < 0) return null
+    const value = signed.slice(0, splitAt)
+    const mac = signed.slice(splitAt + 1)
+    const expected = createHmac('sha256', secret).update(value).digest('base64url')
+    const actualBytes = Buffer.from(mac)
+    const expectedBytes = Buffer.from(expected)
+    if (actualBytes.length !== expectedBytes.length) return null
+    return timingSafeEqual(actualBytes, expectedBytes) ? value : null
+}
+
+/**
+ * Parse a Cookie header into a name/value map.
+ */
+function parseCookies(header: string | null): Record<string, string> {
+    const cookies: Record<string, string> = {}
+    if (!header) return cookies
+    for (const part of header.split(';')) {
+        const eq = part.indexOf('=')
+        if (eq < 0) continue
+        const name = part.slice(0, eq).trim()
+        const value = part.slice(eq + 1).trim()
+        if (name) cookies[name] = decodeURIComponent(value)
+    }
+    return cookies
+}
+
+/**
+ * Serialize one Set-Cookie attribute string.
+ */
+function serializeCookie(name: string, value: string, maxAgeSec: number): string {
+    return [`${name}=${encodeURIComponent(value)}`, 'Path=/', 'HttpOnly', 'SameSite=Lax', `Max-Age=${maxAgeSec}`].join(
+        '; '
+    )
+}
+
+/**
+ * Append a Set-Cookie header without dropping ones already on the response.
+ */
+function appendSetCookie(response: Response, cookie: string): Response {
+    const headers = new Headers(response.headers)
+    headers.append('set-cookie', cookie)
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers
+    })
+}
+
+/**
+ * Signed-cookie sessions backed by the KV store.
+ * The cookie is issued only after the session holds data, so anonymous requests stay cookie-free.
+ * There is no default secret: sessions stay off until `FLIGHT_SESSION_SECRET` is set.
+ */
+export function session(cfg: SessionConfig, store: KVStore): Middleware {
+    return async (req, next) => {
+        const cookies = parseCookies(req.headers.get('cookie'))
+        const raw = cookies[cfg.cookie]
+        const sessionRequest = req as SessionRequest
+
+        let sid: string | null = null
+        let data: Record<string, unknown> = {}
+        if (raw) {
+            const verified = unsign(raw, cfg.secret)
+            if (verified) {
+                sid = verified
+                const stored = await store.get(`sess:${sid}`)
+                if (stored) {
+                    try {
+                        data = JSON.parse(stored) as Record<string, unknown>
+                    } catch {
+                        data = {}
+                    }
+                }
+            }
+        }
+
+        const before = JSON.stringify(data)
+        sessionRequest.session = data
+        const response = await next()
+        const after = JSON.stringify(sessionRequest.session ?? {})
+        const isEmpty = after === '{}'
+
+        if (sid && isEmpty && before !== '{}') {
+            await store.del(`sess:${sid}`)
+            return appendSetCookie(response, serializeCookie(cfg.cookie, '', 0))
+        }
+        if (isEmpty) return response
+
+        if (!sid) sid = randomUUID()
+        await store.set(`sess:${sid}`, after, cfg.ttlSec)
+        if (!raw || unsign(raw, cfg.secret) !== sid) {
+            return appendSetCookie(response, serializeCookie(cfg.cookie, sign(sid, cfg.secret), cfg.ttlSec))
+        }
+        return response
+    }
+}

package/src/bun/static.ts

@@ -0,0 +1,72 @@
+import { join, resolve, sep } from 'node:path'
+
+/**
+ * True when the last path segment looks like a file name (`app.js`, `secret.txt`).
+ */
+function lastSegmentLooksLikeFile(pathname: string): boolean {
+    const base = pathname.slice(pathname.lastIndexOf('/') + 1)
+    return base.includes('.')
+}
+
+/**
+ * True when `pathname` is exactly `prefix` or a child of it.
+ */
+function hasPrefix(pathname: string, prefix: string): boolean {
+    return pathname === prefix || (prefix !== '/' && pathname.startsWith(`${prefix}/`))
+}
+
+/**
+ * Resolve `pathname` under `root`. Returns null when the target escapes the root.
+ */
+export function safeTarget(root: string, pathname: string): string | null {
+    const base = resolve(root)
+    const target = resolve(base, `.${pathname}`)
+    if (target !== base && !target.startsWith(base + sep)) return null
+    return target
+}
+
+/**
+ * Serve a built SPA from `distPath` with an `index.html` fallback for document navigations.
+ * Development mode returns null so Vite owns the UI. `/api`, `/health`, and `/healthz` never fall back.
+ */
+export function makeStaticHandler(distPath: string, mode: string, denyPrefixes: string[]) {
+    const indexPath = join(distPath, 'index.html')
+    const root = resolve(distPath)
+
+    return async function serveStatic(req: Request): Promise<Response | null> {
+        if (mode !== 'production') return null
+        if (req.method !== 'GET' && req.method !== 'HEAD') return null
+
+        const url = new URL(req.url)
+        let pathname: string
+        try {
+            pathname = decodeURIComponent(url.pathname)
+        } catch {
+            return new Response('Bad Request', { status: 400 })
+        }
+
+        if (denyPrefixes.some((prefix) => hasPrefix(pathname, prefix))) return null
+
+        const target = safeTarget(root, pathname)
+        if (!target) return new Response('Forbidden', { status: 403 })
+
+        if (target !== root) {
+            const file = Bun.file(target)
+            if (await file.exists()) {
+                return new Response(req.method === 'HEAD' ? null : file)
+            }
+        }
+
+        const accept = req.headers.get('accept') || ''
+        const wantsHtml = !accept || accept.includes('text/html') || accept.includes('*/*')
+        if (!wantsHtml || lastSegmentLooksLikeFile(pathname)) return null
+
+        const index = Bun.file(indexPath)
+        if (await index.exists()) {
+            return new Response(req.method === 'HEAD' ? null : index, {
+                headers: { 'content-type': 'text/html; charset=utf-8' }
+            })
+        }
+        return null
+    }
+}