@thoughtpivot/flight 2.0.2 → 3.0.1

package/src/bun/koa-compat.ts

@@ -0,0 +1,381 @@
+import { EventEmitter } from 'node:events'
+import { Readable } from 'node:stream'
+
+import type { KoaMiddleware } from './backends'
+import { markStreaming } from './middleware'
+
+type WriteCallback = (error?: Error | null) => void
+
+/** 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
+    /** Re-read whether any mounted router has matched. Runs before the dispatcher decides. */
+    refreshMatch: () => void = () => {}
+    private chunks: Buffer[] = []
+    private headers = new Map<string, string | string[]>()
+    /** True once `writeHead`, `write`, or `ctx.respond = false` starts a live body. */
+    private streaming = false
+    /** True while `end()` is copying its final chunk, so that write does not start a stream. */
+    private ending = false
+    private closeEmitted = false
+    private clientAborted = false
+    private controller: ReadableStreamDefaultController<Uint8Array> | null = null
+
+    /** 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. Calling this begins a streamed body. */
+    writeHead(
+        status: number,
+        reason?: string | Record<string, string | number | string[]>,
+        maybeHeaders?: Record<string, string | number | string[]>
+    ) {
+        this.statusCode = status
+        const headers = typeof reason === 'string' || reason === undefined ? maybeHeaders : reason
+        if (headers) {
+            for (const [key, value] of Object.entries(headers)) this.setHeader(key, value)
+        }
+        this.headersSent = true
+        if (!this.finished && !this.ending) this.startStream()
+        return this
+    }
+
+    /** Flush headers and begin a streamed body. */
+    flushHeaders() {
+        this.headersSent = true
+        if (!this.finished && !this.ending) this.startStream()
+    }
+
+    /**
+     * Begin a streamed body without waiting for `end()`.
+     * Headers set in the same turn are included; the Fetch response resolves on the next microtask.
+     */
+    startStream() {
+        if (this.streaming || this.finished || this.writableEnded) return
+        this.streaming = true
+        this.refreshMatch()
+        queueMicrotask(() => {
+            this.emit('stream-open')
+        })
+    }
+
+    /** Buffer a chunk, or enqueue it when a live stream is already open. */
+    write(chunk?: string | Buffer | Uint8Array, encoding?: BufferEncoding | WriteCallback, callback?: WriteCallback) {
+        if (this.writableEnded || this.clientAborted) return false
+        let cb: WriteCallback | undefined
+        let enc: BufferEncoding | undefined
+        if (typeof encoding === 'function') cb = encoding
+        else {
+            enc = encoding
+            if (typeof callback === 'function') cb = callback
+        }
+        if (chunk != null && chunk.length !== 0) {
+            const bytes = typeof chunk === 'string' ? Buffer.from(chunk, enc) : Buffer.from(chunk)
+            this.enqueue(bytes)
+        }
+        if (!this.ending) this.startStream()
+        if (cb) queueMicrotask(() => cb!())
+        return true
+    }
+
+    /** Finish the response and emit the events `on-finished` listens for. */
+    end(chunk?: string | Buffer | Uint8Array, encoding?: BufferEncoding | WriteCallback, callback?: WriteCallback) {
+        if (this.writableEnded) return this
+        this.ending = true
+        if (chunk != null && chunk !== '') this.write(chunk, encoding, callback)
+        else if (typeof encoding === 'function') queueMicrotask(() => encoding())
+        else if (typeof callback === 'function') queueMicrotask(() => callback())
+        this.finished = true
+        this.writableEnded = true
+        this.headersSent = true
+        this.refreshMatch()
+        this.closeController()
+        this.emit('finish')
+        this.emitClose()
+        return this
+    }
+
+    /** Client went away. `res.on('close')` handlers use this to drop heartbeats and subscribers. */
+    clientDisconnect() {
+        if (this.clientAborted) return
+        this.clientAborted = true
+        this.closeController()
+        this.emitClose()
+    }
+
+    /** Build the Fetch response from the buffered status, headers, and body. */
+    toResponse(): Response {
+        if (this.streaming && !this.finished) return this.liveResponse()
+        const body = this.chunks.length ? Buffer.concat(this.chunks) : null
+        return new Response(body, { status: this.statusCode, headers: this.headerInit() })
+    }
+
+    /** Push bytes into the live controller, or hold them until that controller exists. */
+    private enqueue(bytes: Buffer) {
+        if (!this.controller) {
+            this.chunks.push(bytes)
+            return
+        }
+        try {
+            this.controller.enqueue(bytes)
+        } catch {
+            // The stream is already closed.
+        }
+    }
+
+    /** Close the live body if the consumer has already attached. */
+    private closeController() {
+        if (!this.controller) return
+        try {
+            this.controller.close()
+        } catch {
+            // Already closed or cancelled.
+        }
+    }
+
+    /** Emit `close` once, whether the route finished or the client aborted. */
+    private emitClose() {
+        if (this.closeEmitted) return
+        this.closeEmitted = true
+        this.emit('close')
+    }
+
+    /** Copy stored headers into a Fetch `Headers` object. */
+    private headerInit(): Headers {
+        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)
+            }
+        }
+        return headers
+    }
+
+    /**
+     * Return a Fetch response whose body stays open until `end()` or the client disconnects.
+     * Chunks written before this runs are flushed first.
+     */
+    private liveResponse(): Response {
+        const stream = new ReadableStream<Uint8Array>({
+            start: (controller) => {
+                this.controller = controller
+                for (const chunk of this.chunks.splice(0)) controller.enqueue(chunk)
+                if (this.finished || this.clientAborted) this.closeController()
+            },
+            cancel: () => {
+                this.clientDisconnect()
+            }
+        })
+        markStreaming(stream)
+        return new Response(stream, { status: this.statusCode, headers: this.headerInit() })
+    }
+}
+
+/**
+ * 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
+}
+
+/** Koa context fields the compat layer observes. */
+interface KoaCtx {
+    matched?: unknown
+    /** Set by `@koa/router` when the path and the method both match. */
+    _matchedRoute?: unknown
+    respond?: unknown
+    res: MockResponse
+}
+
+/** Arrays whose `push` already updates `flightMatched`. Later routers append instead of assigning. */
+const observedMatches = new WeakSet<object>()
+
+/**
+ * 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()
+
+        const onAbort = () => res.clientDisconnect()
+        if (request.signal.aborted) onAbort()
+        else request.signal.addEventListener('abort', onAbort, { once: true })
+        res.once('finish', () => request.signal.removeEventListener('abort', onAbort))
+
+        await new Promise<void>((resolve, reject) => {
+            let settled = false
+            const finish = () => {
+                res.refreshMatch()
+                if (settled) return
+                settled = true
+                resolve()
+            }
+            res.on('finish', finish)
+            res.on('stream-open', finish)
+            res.on('error', (err) => {
+                if (settled) return
+                settled = true
+                reject(err)
+            })
+            try {
+                callback(req, res)
+            } catch (err) {
+                if (!settled) {
+                    settled = true
+                    reject(err)
+                }
+            }
+        })
+
+        if (!res.flightMatched) return null
+        return res.toResponse()
+    }
+}
+
+/**
+ * True when this request hit a route.
+ * `@koa/router` assigns `ctx.matched` for the first router only. Every later router
+ * `push`es onto that same array, and sets `_matchedRoute` when the method matches.
+ */
+function hasMatch(ctx: KoaCtx): boolean {
+    const matched = ctx.matched
+    if (Array.isArray(matched) && matched.length > 0) return true
+    return typeof ctx._matchedRoute === 'string' && ctx._matchedRoute.length > 0
+}
+
+/**
+ * Notice routes appended with `push` after the first router assigned `ctx.matched`.
+ */
+function observePushes(ctx: KoaCtx, layers: unknown[]) {
+    if (observedMatches.has(layers)) return
+    observedMatches.add(layers)
+    const original = Array.prototype.push
+    layers.push = function (this: unknown[], ...items: unknown[]) {
+        const result = original.apply(this, items)
+        ctx.res.refreshMatch()
+        return result
+    }
+}
+
+/**
+ * Keep `flightMatched` current for every router, including ones that only `push`.
+ * The dispatcher reads it again when a stream opens or the response finishes.
+ */
+function trackMatch(ctx: KoaCtx) {
+    ctx.res.refreshMatch = () => {
+        ctx.res.flightMatched = hasMatch(ctx)
+    }
+    let matched = ctx.matched
+    if (Array.isArray(matched)) observePushes(ctx, matched)
+    Object.defineProperty(ctx, 'matched', {
+        configurable: true,
+        enumerable: true,
+        get() {
+            return matched
+        },
+        set(value: unknown) {
+            matched = value
+            if (Array.isArray(value)) observePushes(ctx, value)
+            ctx.res.refreshMatch()
+        }
+    })
+}
+
+/**
+ * `ctx.respond = false` means the route owns the raw response and Koa must not wait for `end()`.
+ */
+function trackRespond(ctx: KoaCtx) {
+    let respond = ctx.respond
+    Object.defineProperty(ctx, 'respond', {
+        configurable: true,
+        enumerable: true,
+        get() {
+            return respond
+        },
+        set(value: unknown) {
+            respond = value
+            if (value === false) ctx.res.startStream()
+        }
+    })
+}
+
+/**
+ * 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: KoaCtx, next: () => Promise<void>) => {
+        trackMatch(ctx)
+        trackRespond(ctx)
+        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,256 @@
+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 preserveStreaming(
+        response,
+        new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers
+        })
+    )
+}
+
+/**
+ * Keep a live-stream mark when a middleware copies the body onto a new `Response`.
+ */
+export function preserveStreaming(source: Response, target: Response): Response {
+    if (source.body && target.body && streamingBodies.has(source.body)) streamingBodies.add(target.body)
+    return target
+}
+
+/**
+ * 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))
+    }
+}
+
+/** Bodies that must not be read to completion. Keyed by the stream so header copies keep the mark. */
+const streamingBodies = new WeakSet<ReadableStream<Uint8Array>>()
+
+/**
+ * Remember a body that stays open until the producer ends it.
+ * Compression and the response cache must not buffer it.
+ */
+export function markStreaming(body: ReadableStream<Uint8Array>) {
+    streamingBodies.add(body)
+}
+
+/**
+ * True for `text/event-stream` and for any body marked as a live stream.
+ */
+export function isStreamingResponse(response: Response): boolean {
+    const type = response.headers.get('content-type') || ''
+    if (/text\/event-stream/i.test(type)) return true
+    return response.body != null && streamingBodies.has(response.body)
+}
+
+/**
+ * True when this response is a server-sent event stream.
+ */
+export function isEventStream(response: Response): boolean {
+    return /text\/event-stream/i.test(response.headers.get('content-type') || '')
+}
+
+/**
+ * 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 (isStreamingResponse(response)) 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')
+}