@thoughtpivot/flight 2.0.2 → 3.0.1

package/src/bun/backends.ts

@@ -0,0 +1,93 @@
+import { relative, sep } from 'node:path'
+
+import type { Handler } from './middleware'
+
+/** Method name to handler, as exported by a Bun-native `*.backend.ts` file. */
+export type MethodMap = Record<string, Handler>
+
+/** Path to a handler or a method map. This is the Bun-native backend contract. */
+export type RouteFragment = Record<string, Handler | MethodMap>
+
+/** Koa middleware: `(ctx, next) => Promise`. Existing Flight backends export this from `router.routes()`. */
+export type KoaMiddleware = (ctx: unknown, next: () => Promise<unknown>) => unknown
+
+/** Everything discovery found under an app root. */
+export interface DiscoveredBackends {
+    routes: Record<string, Handler | MethodMap>
+    koa: KoaMiddleware[]
+}
+
+/**
+ * True when every key is a URL path. That is the Bun route-fragment shape.
+ */
+function isRouteFragment(value: object): boolean {
+    const keys = Object.keys(value)
+    return keys.length > 0 && keys.every((key) => key.startsWith('/'))
+}
+
+/**
+ * Discover `*.backend.ts` and `*.backend.js` under `appHome`.
+ * An object whose keys are paths is the Bun contract. A function, or an object with `.routes()`,
+ * is the existing Koa contract and is kept so current apps can boot on Bun without a rewrite.
+ */
+export async function discoverBackends(appHome: string, excludePaths: string[]): Promise<DiscoveredBackends> {
+    const routes: Record<string, Handler | MethodMap> = {}
+    const koa: KoaMiddleware[] = []
+    const excluded = new Set(excludePaths)
+
+    for (const pattern of ['**/*.backend.ts', '**/*.backend.js']) {
+        const glob = new Bun.Glob(pattern)
+        for await (const abs of glob.scan({ cwd: appHome, absolute: true, onlyFiles: true })) {
+            const rel = relative(appHome, abs)
+            if (excluded.has(rel.split(sep)[0])) continue
+
+            let mod: { default?: unknown }
+            try {
+                mod = await import(abs)
+            } catch (err) {
+                console.error(`flight-bun: failed to load ${rel}:`, err)
+                continue
+            }
+
+            const exported = mod.default
+            if (!exported) {
+                console.warn(`flight-bun: ${rel} has no default export — skipping`)
+                continue
+            }
+
+            if (typeof exported === 'function') {
+                koa.push(exported as KoaMiddleware)
+                console.log(`flight-bun: mounted Koa backend ${rel}`)
+                continue
+            }
+
+            if (typeof exported === 'object') {
+                const record = exported as Record<string, unknown>
+                if (typeof record.routes === 'function' && !isRouteFragment(record)) {
+                    koa.push(record.routes() as KoaMiddleware)
+                    console.log(`flight-bun: mounted Koa router ${rel}`)
+                    continue
+                }
+                if (isRouteFragment(record)) {
+                    for (const [path, methods] of Object.entries(record)) {
+                        if (typeof methods === 'function') {
+                            routes[path] = methods as Handler
+                        } else if (methods && typeof methods === 'object') {
+                            const existing = routes[path]
+                            routes[path] = {
+                                ...(typeof existing === 'object' ? existing : {}),
+                                ...(methods as MethodMap)
+                            }
+                        }
+                    }
+                    console.log(`flight-bun: mounted backend ${rel}`)
+                    continue
+                }
+            }
+
+            console.warn(`flight-bun: ${rel} default export is not a route fragment or Koa middleware — skipping`)
+        }
+    }
+
+    return { routes, koa }
+}

package/src/bun/cache.ts

@@ -0,0 +1,57 @@
+import type { CacheConfig } from './config'
+import { isStreamingResponse, withHeaders, type Middleware } from './middleware'
+import type { KVStore } from './store'
+
+/** Stored GET response. Only text and JSON bodies are kept. */
+interface CachedEntry {
+    status: number
+    headers: [string, string][]
+    body: string
+}
+
+/**
+ * Cache GET responses that opt in with `Cache-Control: max-age`.
+ * Hits and misses are marked with `X-Flight-Cache`.
+ */
+export function cache(cfg: CacheConfig, store: KVStore): Middleware {
+    return async (req, next) => {
+        if (req.method !== 'GET' && req.method !== 'HEAD') return next()
+
+        const url = new URL(req.url)
+        const key = `cash:${url.pathname}${url.search}`
+        const hit = await store.get(key)
+        if (hit) {
+            try {
+                const entry = JSON.parse(hit) as CachedEntry
+                const headers = new Headers(entry.headers)
+                headers.set('x-flight-cache', 'HIT')
+                return new Response(req.method === 'HEAD' ? null : entry.body, {
+                    status: entry.status,
+                    headers
+                })
+            } catch {
+                // A corrupt entry is regenerated below.
+            }
+        }
+
+        const response = await next()
+        if (isStreamingResponse(response)) return withHeaders(response, { 'x-flight-cache': 'MISS' })
+        const cacheControl = response.headers.get('cache-control') || ''
+        const match = /max-age=(\d+)/.exec(cacheControl)
+        if (response.status === 200 && match && req.method === 'GET') {
+            const ttl = Math.min(Number(match[1]), cfg.maxTtl)
+            const contentType = response.headers.get('content-type') || ''
+            if (ttl > 0 && /^(text\/|application\/(json|javascript)|application\/.*\+json)/i.test(contentType)) {
+                const body = await response.clone().text()
+                const entry: CachedEntry = {
+                    status: 200,
+                    headers: [...response.headers.entries()],
+                    body
+                }
+                await store.set(key, JSON.stringify(entry), ttl)
+            }
+        }
+
+        return withHeaders(response, { 'x-flight-cache': 'MISS' })
+    }
+}

package/src/bun/config.ts

@@ -0,0 +1,182 @@
+import { join, resolve } from 'node:path'
+
+/** CORS settings for the Bun runtime. */
+export interface CorsConfig {
+    enabled: boolean
+    origin: string
+    methods: string
+    headers: string
+    credentials: boolean
+    maxAge: number
+}
+
+/** Security-header settings. Content-Security-Policy stays app-specific. */
+export interface SecurityConfig {
+    enabled: boolean
+    hsts: boolean
+    hstsMaxAge: number
+}
+
+/** Gzip settings. Bodies smaller than `threshold` are left unchanged. */
+export interface CompressionConfig {
+    enabled: boolean
+    threshold: number
+}
+
+/** Fixed-window rate limit. Off unless `max` is greater than zero. */
+export interface RateLimitConfig {
+    enabled: boolean
+    max: number
+    durationMs: number
+    trustProxy: boolean
+    skipPrefixes: string[]
+}
+
+/** Signed-cookie sessions. Disabled until a secret is set. */
+export interface SessionConfig {
+    enabled: boolean
+    secret: string
+    cookie: string
+    ttlSec: number
+}
+
+/** Opt-in response cache. Handlers opt in with `Cache-Control: max-age`. */
+export interface CacheConfig {
+    enabled: boolean
+    maxTtl: number
+}
+
+/** Resolved Flight Bun configuration. */
+export interface Config {
+    mode: string
+    port: number
+    hostname: string
+    appHome: string
+    distPath: string
+    excludePaths: string[]
+    spaDenyPrefixes: string[]
+    payloadLimit: string
+    logging: boolean
+    /**
+     * Seconds `Bun.serve` waits on an idle socket.
+     * Explicit `0` disables it. Positive fractions round up to at least 1. Clamped to 255.
+     */
+    idleTimeout: number
+    redisUrl?: string
+    cors: CorsConfig
+    security: SecurityConfig
+    compression: CompressionConfig
+    rateLimit: RateLimitConfig
+    session: SessionConfig
+    cache: CacheConfig
+}
+
+type Env = Record<string, string | undefined>
+
+/**
+ * Parse a boolean environment flag. Empty or missing values use the default.
+ */
+function bool(value: string | undefined, fallback: boolean): boolean {
+    if (value === undefined || value === '') return fallback
+    return value === '1' || value === 'true' || value === 'yes'
+}
+
+/**
+ * Parse a finite number. Empty or invalid values use the default.
+ */
+function num(value: string | undefined, fallback: number): number {
+    if (value === undefined || value === '') return fallback
+    const parsed = Number(value)
+    return Number.isFinite(parsed) ? parsed : fallback
+}
+
+/**
+ * Parse `FLIGHT_IDLE_TIMEOUT` seconds. Missing, blank, negative, and non-numeric values use 10.
+ * An explicit `0` disables the timeout. Positive fractions round up to at least 1.
+ * Anything above Bun's maximum of 255 is clamped.
+ */
+function idleSeconds(value: string | undefined): number {
+    if (value === undefined || value.trim() === '') return 10
+    const parsed = Number(value)
+    if (!Number.isFinite(parsed) || parsed < 0) return 10
+    if (parsed === 0) return 0
+    return Math.min(255, Math.max(1, Math.ceil(parsed)))
+}
+
+/**
+ * Split a comma-separated prefix list and ensure each entry starts with `/`.
+ */
+function prefixes(value: string | undefined, fallback: string): string[] {
+    const raw = (value ?? fallback).trim()
+    if (!raw) return []
+    return raw
+        .split(',')
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .map((part) => (part.startsWith('/') ? part : `/${part}`))
+}
+
+/**
+ * Build a config object from an environment map.
+ * Defaults keep sessions, caching, and rate limiting off so a load test is not throttled by surprise.
+ */
+export function loadConfig(env: Env = process.env): Config {
+    const mode = env.FLIGHT_MODE || 'production'
+    const appHome = resolve(env.FLIGHT_APP_HOME || '.')
+    const sessionSecret = env.FLIGHT_SESSION_SECRET || ''
+    const rateMax = num(env.FLIGHT_RATE_LIMIT_MAX, 0)
+
+    return {
+        mode,
+        port: num(env.FLIGHT_PORT, 3000),
+        hostname: env.FLIGHT_HOSTNAME || '0.0.0.0',
+        appHome,
+        distPath: env.FLIGHT_DIST_PATH ? resolve(env.FLIGHT_DIST_PATH) : join(appHome, 'dist'),
+        excludePaths: (env.FLIGHT_EXCLUDE_PATHS || 'node_modules,dist')
+            .split(',')
+            .map((part) => part.trim())
+            .filter(Boolean),
+        spaDenyPrefixes: prefixes(env.FLIGHT_SPA_DENY_PREFIXES, '/api,/health,/healthz'),
+        payloadLimit: env.FLIGHT_PAYLOAD_LIMIT || '1mb',
+        logging: bool(env.FLIGHT_LOGGING, mode === 'development'),
+        idleTimeout: idleSeconds(env.FLIGHT_IDLE_TIMEOUT),
+        redisUrl: env.FLIGHT_REDIS_URL || undefined,
+        cors: {
+            enabled: bool(env.FLIGHT_CORS_ENABLED, true),
+            origin: env.FLIGHT_CORS_ORIGIN || '*',
+            methods: env.FLIGHT_CORS_METHODS || 'GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS',
+            headers: env.FLIGHT_CORS_HEADERS || '',
+            credentials: bool(env.FLIGHT_CORS_CREDENTIALS, false),
+            maxAge: num(env.FLIGHT_CORS_MAX_AGE, 86400)
+        },
+        security: {
+            enabled: bool(env.FLIGHT_SECURITY_ENABLED, true),
+            hsts: bool(env.FLIGHT_HSTS, false),
+            hstsMaxAge: num(env.FLIGHT_HSTS_MAX_AGE, 15552000)
+        },
+        compression: {
+            enabled: bool(env.FLIGHT_COMPRESS_ENABLED, true),
+            threshold: num(env.FLIGHT_COMPRESS_THRESHOLD, 1024)
+        },
+        rateLimit: {
+            enabled: !bool(env.FLIGHT_RATE_LIMIT_DISABLE, false) && rateMax > 0,
+            max: rateMax,
+            durationMs: num(env.FLIGHT_RATE_LIMIT_DURATION_MS, 60000),
+            trustProxy: bool(env.FLIGHT_TRUST_PROXY, false),
+            skipPrefixes: [
+                ...prefixes(env.FLIGHT_STATIC_PREFIXES, '/assets,/fonts'),
+                ...prefixes(env.FLIGHT_RATE_LIMIT_EXCLUDE_PREFIXES, '')
+            ]
+        },
+        session: {
+            enabled: sessionSecret.length > 0,
+            secret: sessionSecret,
+            cookie: env.FLIGHT_SESSION_COOKIE || 'flight.sid',
+            ttlSec: num(env.FLIGHT_SESSION_TTL, 86400)
+        },
+        cache: {
+            enabled: bool(env.FLIGHT_CACHE_ENABLED, false),
+            maxTtl: num(env.FLIGHT_CACHE_MAX_TTL, 3600)
+        }
+    }
+}