@bakery-framework/core 1.1.0 → 1.2.0

package/src/global.d.ts

@@ -44,15 +44,30 @@ declare global {
     inBody?: boolean
   }
 
+  /**
+   * What a middleware may return to stop the chain: a `Response`, or a
+   * `response.json.*` envelope. Anything else — including a bare object or a
+   * string — is ignored and the next middleware runs. See `$middleware.ts`.
+   */
+  type MiddlewareResponse =
+    | Response
+    | import('./utils/common/json').JsonResponseData
+
   type HostEntry = {
     root?: string
     importMap?: Record<string, string>
     middleware?: ((
       req: Request,
       server: Bun.Server<any>,
-    ) => MixedPromise<Response | void>)[]
+    ) => MixedPromise<MiddlewareResponse | void>)[]
     onRequest?(req: Request): MixedPromise<any>
     onError?(error: Handler.Error.Data): MixedPromise<any>
+    /**
+     * Cross-origin resource sharing. Absent means no CORS headers at all,
+     * which is the browser default and the safe one — there is deliberately no
+     * permissive default, not even in development.
+     */
+    cors?: import('./utils/http/cors').CorsOptions | null
     head?: string
     body?: string
     proxy?: Record<string, string>
@@ -79,6 +94,12 @@ declare global {
 
     proxy?: Record<string, string>
 
+    /**
+     * Cross-origin resource sharing. Absent means no CORS headers at all,
+     * which is the browser default and the safe one — there is deliberately no
+     * permissive default, not even in development.
+     */
+    cors?: import('./utils/http/cors').CorsOptions | null
     head?: string
 
     body?: string
@@ -94,7 +115,7 @@ declare global {
     middleware?: ((
       req: Request,
       server: Bun.Server<any>,
-    ) => MixedPromise<Response | void>)[]
+    ) => MixedPromise<MiddlewareResponse | void>)[]
 
     plugins?: ServerPlugin[]
 

package/src/handlers/core/$middleware.ts

@@ -1,15 +1,39 @@
 import { Bakery } from '../../core/bakery'
 import { errorMsg, handlerLog } from '../../logger/serve-log'
+import { JsonResponseData } from '../../utils/common/json'
 import { injectIfHtml, response } from '../../utils/http'
 import { Handler } from './$base'
 
+/**
+ * What a middleware may return to stop the chain.
+ *
+ * A `Response` and a `response.json.*` envelope, and deliberately nothing
+ * else. `JsonResponseData` is the framework's one-envelope idiom (convention
+ * 7) and `processResponse` already renders it with its own `status`, so an
+ * `ApiHandler` route returning `response.json.error(401, …)` answered 401
+ * while the identical line in a middleware did not — the value was not a
+ * `Response`, so the chain ignored it and the request carried on.
+ *
+ * Widening further, to "anything truthy", is the tempting version and is
+ * wrong: a middleware that returns a stray string or object would then halt
+ * the request by accident, and returning a value is how middleware signals
+ * *nothing* in plenty of code (`arr.map`, an assignment expression, an
+ * implicit arrow return). Two named shapes, both of which mean "I am the
+ * response".
+ */
+type MiddlewareResult = Response | JsonResponseData
+
+function isMiddlewareResult(value: unknown): value is MiddlewareResult {
+  return value instanceof Response || value instanceof JsonResponseData
+}
+
 /**
  * Per-request slot for the response produced during `canHandle`, so `handle`
  * can return it without re-running the chain. This was previously a static
  * field, which meant two concurrent requests could swap responses — including
  * each other's `Set-Cookie` headers — at any `await` boundary.
  */
-const pending = new WeakMap<Request, Response>()
+const pending = new WeakMap<Request, MiddlewareResult>()
 
 export class MiddlewareHandler extends Handler {
   /** Answers from app code, not from disk. See `Handler.servesFiles`. */
@@ -48,12 +72,12 @@ export class MiddlewareHandler extends Handler {
       return (await injectIfHtml(intercepted)) || intercepted
     }
 
-    let data: any
+    let data: MiddlewareResult | undefined
 
     for (const middleware of config.middleware) {
       try {
         const result = await middleware(req, Bakery.server!)
-        if (result instanceof Response) {
+        if (isMiddlewareResult(result)) {
           data = result
           break
         }
@@ -65,7 +89,12 @@ export class MiddlewareHandler extends Handler {
       }
     }
 
-    const injectedRes = await injectIfHtml(data)
+    // An envelope is JSON by construction, so it skips injection rather than
+    // paying `DOMTools.isHTML` to be told so. `processResponse` reads its
+    // `status` and serialises it.
+    if (data instanceof JsonResponseData) return data
+
+    const injectedRes = await injectIfHtml(data!)
     return injectedRes || data
   }
 }

package/src/logger/serve-log.ts

@@ -25,6 +25,17 @@ const serveMsgs = {
   WATCHER_ERR: 'E Watcher error: %r{error}%*',
   TSCONFIG_SYNCED:
     'I Synced %ytsconfig.json%* paths with %yserver.config.ts%*!',
+  TSCONFIG_PROJECTS_WRITTEN:
+    'I Wrote %y{count}%* tsconfig project(s) to %y.cache/tsconfig/%*',
+  // A plugin asking for a project name that is taken. Named rather than
+  // silent: the symptom otherwise is one plugin's types quietly not applying,
+  // discovered much later and blamed on the wrong thing.
+  TSCONFIG_PROJECT_CLASH:
+    'W Plugin %y{plugin}%* wants tsconfig project %y{project}%*, which already exists — %rskipped%*',
+  // Degrades to "no types" rather than failing the boot: a missing declaration
+  // is a worse editor experience, not a broken server.
+  TSCONFIG_FILE_UNRESOLVED:
+    'W Could not resolve tsconfig files entry %y{entry}%* — %rskipped%*',
   MANUAL_RELOAD: 'I %yManual reload%* triggered from client logger!',
   CONFIG_IMPORT_ERR: 'E Failed to import %yserver.config.ts%*: %r{error}%*',
   // Multi-line on purpose: a present-but-broken config booting on defaults is

package/src/plugins/types.ts

@@ -3,9 +3,68 @@ import type { MixedPromise } from '../types'
 
 export type ValidResponses = Handler.Response
 
+/**
+ * A TypeScript project a plugin contributes to the app.
+ *
+ * Written to `.cache/tsconfig/<name>.json` on every dev boot and referenced
+ * from the app's root `tsconfig.json`, so the editor typechecks each file under
+ * the project that owns it. Regenerated rather than committed: it is derived
+ * from the plugin list and the app's config, and `.cache/` is the disposable
+ * half of the two runtime directories.
+ */
+export interface PluginTsProject {
+  /** File name under `.cache/tsconfig/`, and the project's identity. */
+  name: string
+  /** Usually one of core's three bases. Written through as-is. */
+  extends: string
+  /** Globs, relative to the **app root** — the generator rewrites them. */
+  include?: string[]
+  exclude?: string[]
+  /**
+   * Ambient declarations the plugin owns.
+   *
+   * Package specifiers are allowed here and resolved to real paths before
+   * writing, because TypeScript resolves `files` as paths and would treat
+   * `@scope/pkg/x.d.ts` as a missing file rather than a module.
+   */
+  files?: string[]
+  compilerOptions?: Record<string, unknown>
+  /**
+   * Whether this project should receive `paths` derived from `importMap`.
+   *
+   * Off by default, and that default is the correction: the generator used to
+   * write those `paths` into *every* project on the reasoning that an alias is
+   * app-wide. It is not. `importMap` is a **browser** import map — the framework
+   * serves it as `<script type="importmap">` and the browser is what resolves
+   * its specifiers. An alias in the server project therefore typechecks an
+   * import that only the browser can satisfy, which is the same class of bug the
+   * server/client split was introduced to end.
+   *
+   * A plugin whose project compiles browser code should set it.
+   */
+  importMapPaths?: boolean
+}
+
+/** What a plugin contributes to the generated tsconfig projects. */
+export interface PluginTsConfig {
+  /** A project this plugin owns outright — Vue SFCs, for instance. */
+  project?: PluginTsProject
+}
+
 export interface ServerPlugin {
   name: string
   setup?(config: ProcessedAppConfig): MixedPromise<void>
+
+  /**
+   * Declarative, unlike every hook below it: read by the tsconfig generator at
+   * dev boot, never by the running server.
+   *
+   * A plugin that brings its own file type or its own ambient globals needs a
+   * project to typecheck them under. `@bakery-framework/plugin-vue` is the
+   * worked example — it owns `.vue` and declares `req`/`body` for SFC scope,
+   * globals core deliberately does not provide.
+   */
+  tsconfig?: PluginTsConfig
   onStart?(server: Bun.Server<any>): MixedPromise<void>
   onRequest?(req: Request): ValidResponses
   onRoute?(req: Request): MixedPromise<void>

package/src/router.ts

@@ -18,6 +18,7 @@ import {
   response,
   withStatus,
 } from './utils/http'
+import { applyCors, preflightResponse } from './utils/http/cors'
 
 /**
  * Resolve a WebSocket upgrade, refusing cross-origin handshakes first.
@@ -97,6 +98,19 @@ export async function handleRequest(req: Request) {
   // itself, so that was a second full path resolution of the same string on
   // every request.
   const config = Bakery.config
+
+  // Before anything else, including the forbidden-path check: a preflight names
+  // the route it is asking about in a *header*, not the path, so running it
+  // through routing would answer a question nobody asked. The browser sends no
+  // credentials with it either, which is why it cannot be authorised.
+  //
+  // Only when `cors` is configured. Absent, this is not reached at all and the
+  // browser's own default applies.
+  if (config.cors) {
+    const preflight = preflightResponse(config.cors, req)
+    if (preflight) return preflight
+  }
+
   const serveRoot = config.root
   if (fs.isForbidden(serveRoot + path, serveRoot)) {
     return new Response('Forbidden', { status: 403 })
@@ -338,6 +352,14 @@ export async function processResponse(
   // append, not set: a handler may already have issued its own Set-Cookie
   // (e.g. an auth cookie from a login route) that must not be overwritten.
   sess && resp.headers.append('Set-Cookie', sess)
+
+  // Every response funnels through here — pages, API JSON, static files, error
+  // pages — so this is the one place that cannot miss one. Applied before ETag
+  // so the negotiated `Vary` sees the `Origin` entry and merges with it rather
+  // than either overwriting the other.
+  const cors = Bakery.config.cors
+  if (cors) applyCors(cors, req, resp)
+
   const final = ETag.sendResponse(req, resp)
   if (!(final instanceof Response)) {
     log({

package/src/utils/http/cors.ts

@@ -0,0 +1,170 @@
+/**
+ * Cross-origin resource sharing.
+ *
+ * Bakery already ships the pieces of an API server — `ApiHandler`, sessions,
+ * CSRF, rate limiting — and had no way to serve one to a browser on another
+ * origin. This is that.
+ *
+ * Two halves, and both are needed: a preflight `OPTIONS` has to be answered
+ * before routing (there is no route to run, and the browser will not send the
+ * real request until it is answered), and every *other* response needs the
+ * headers appended on the way out.
+ *
+ * **Nothing happens unless `cors` is configured.** No default origin, not even
+ * a permissive one in development: a framework that quietly allows every origin
+ * teaches people it works and then surprises them in production. An absent
+ * config means the headers are never written, which is the browser's own
+ * default and the safe one.
+ */
+
+/** What the app writes in `server.config.ts`. */
+export interface CorsOptions {
+  /**
+   * Origins allowed to read responses.
+   *
+   * `'*'` is honoured literally, and is refused in combination with
+   * `credentials` — see `resolveOrigin`. A function receives the request's
+   * `Origin` and returns the value to echo, or `null` to deny.
+   */
+  origin: string | string[] | ((origin: string) => string | null)
+  /** Defaults to the methods a browser will preflight for. */
+  methods?: string[]
+  /** Request headers the browser may send. Defaults to echoing what it asks. */
+  allowHeaders?: string[]
+  /** Response headers JavaScript may read. Nothing is exposed by default. */
+  exposeHeaders?: string[]
+  /** Send `Access-Control-Allow-Credentials`. Incompatible with `origin: '*'`. */
+  credentials?: boolean
+  /** Preflight cache lifetime in seconds. */
+  maxAge?: number
+}
+
+const DEFAULT_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE']
+
+/**
+ * The value for `Access-Control-Allow-Origin`, or `null` to send nothing.
+ *
+ * **`'*'` with credentials is refused rather than silently downgraded.** The
+ * browser rejects that pairing anyway, so honouring it would produce a request
+ * that fails in the client with a CORS error and a server that believes it
+ * allowed the call. Echoing the origin instead would be a *quiet widening* of
+ * what the app asked for. Returning null makes the misconfiguration visible as
+ * a denied request, which is the direction a security control should fail in.
+ */
+export function resolveOrigin(
+  options: CorsOptions,
+  requestOrigin: string | null,
+): string | null {
+  const { origin, credentials } = options
+
+  if (origin === '*') return credentials ? null : '*'
+  if (!requestOrigin) return null
+
+  if (typeof origin === 'function') return origin(requestOrigin)
+  if (Array.isArray(origin)) {
+    return origin.includes(requestOrigin) ? requestOrigin : null
+  }
+  return origin === requestOrigin ? requestOrigin : null
+}
+
+/**
+ * Headers for a non-preflight response, or `null` when the origin is denied.
+ *
+ * `Vary: Origin` is always set when the allowed origin is anything but `'*'`,
+ * because the response now differs per origin and a shared cache that ignored
+ * that would serve one origin's response to another.
+ */
+export function corsHeaders(
+  options: CorsOptions,
+  requestOrigin: string | null,
+): Record<string, string> | null {
+  const allowed = resolveOrigin(options, requestOrigin)
+  if (allowed === null) return null
+
+  const headers: Record<string, string> = {
+    'Access-Control-Allow-Origin': allowed,
+  }
+  if (allowed !== '*') headers.Vary = 'Origin'
+  if (options.credentials) {
+    headers['Access-Control-Allow-Credentials'] = 'true'
+  }
+  if (options.exposeHeaders?.length) {
+    headers['Access-Control-Expose-Headers'] = options.exposeHeaders.join(', ')
+  }
+  return headers
+}
+
+/**
+ * The response to a preflight, or `null` if this is not one.
+ *
+ * A preflight is `OPTIONS` *with* `Access-Control-Request-Method` — plain
+ * `OPTIONS` is a normal request and must fall through to routing, or an app
+ * with its own OPTIONS route would find it shadowed.
+ *
+ * 204 rather than 200: there is no body, and some proxies treat a 200 with no
+ * content-length as needing one.
+ */
+export function preflightResponse(
+  options: CorsOptions,
+  req: Request,
+): Response | null {
+  if (req.method !== 'OPTIONS') return null
+  if (!req.headers.get('Access-Control-Request-Method')) return null
+
+  const base = corsHeaders(options, req.headers.get('Origin'))
+  // A denied origin still gets an answer, just without the headers that would
+  // permit the call. Returning 403 here would be a worse signal: the browser
+  // reports a CORS failure either way, and a 403 invites debugging the route.
+  if (!base) return new Response(null, { status: 204 })
+
+  const headers: Record<string, string> = {
+    ...base,
+    'Access-Control-Allow-Methods': (options.methods ?? DEFAULT_METHODS).join(
+      ', ',
+    ),
+  }
+
+  // Echoing the requested headers is what makes a default config usable:
+  // enumerating every header a client might send is a list nobody maintains,
+  // and getting it wrong fails at request time in the browser only.
+  const requested = req.headers.get('Access-Control-Request-Headers')
+  const allow = options.allowHeaders?.length
+    ? options.allowHeaders.join(', ')
+    : requested
+  if (allow) headers['Access-Control-Allow-Headers'] = allow
+
+  if (options.maxAge !== undefined) {
+    headers['Access-Control-Max-Age'] = String(options.maxAge)
+  }
+
+  // Vary on the negotiated request headers too, for the same caching reason.
+  headers.Vary = [headers.Vary, 'Access-Control-Request-Headers']
+    .filter(Boolean)
+    .join(', ')
+
+  return new Response(null, { status: 204, headers })
+}
+
+/** Append the headers to a response that already exists. */
+export function applyCors(
+  options: CorsOptions,
+  req: Request,
+  res: Response,
+): Response {
+  const headers = corsHeaders(options, req.headers.get('Origin'))
+  if (!headers) return res
+
+  for (const [key, value] of Object.entries(headers)) {
+    // `Vary` may already carry a value from ETag negotiation; appending keeps
+    // both rather than dropping whichever ran second.
+    if (key === 'Vary' && res.headers.has('Vary')) {
+      const existing = res.headers.get('Vary') ?? ''
+      if (!existing.split(',').some(v => v.trim() === value)) {
+        res.headers.set('Vary', `${existing}, ${value}`)
+      }
+      continue
+    }
+    res.headers.set(key, value)
+  }
+  return res
+}

package/src/utils/http/index.ts

@@ -6,3 +6,4 @@ export * from './etag'
 export * from './html'
 export * from './ip'
 export * from './response'
+export * from './sse'

package/src/utils/http/sse.ts

@@ -0,0 +1,200 @@
+/**
+ * Server-sent events.
+ *
+ * Bakery had WebSockets and nothing for one-way streaming, which is the cheaper
+ * half of that pair and the right shape for progress, notifications and tailing
+ * — no upgrade, no protocol, reconnects handled by the browser.
+ *
+ * A route could always return a `Response` wrapping a `ReadableStream` and it
+ * would reach the client intact: `ETag.sendResponse` returns early without an
+ * `ETag` header, and `injectIfHtml` ignores anything that is not HTML. What was
+ * missing is the framing, and framing is where this goes wrong — a payload
+ * containing a newline silently truncates unless every line is prefixed, and a
+ * write after the client has gone throws where nobody is catching.
+ */
+
+/** One event. Every field is optional except the payload. */
+export interface SSEMessage {
+  /** Serialised with `JSON.stringify` unless it is already a string. */
+  data: unknown
+  /** `event:` — the client listens for this name instead of `message`. */
+  event?: string
+  /** `id:` — echoed back as `Last-Event-ID` when the browser reconnects. */
+  id?: string
+  /** `retry:` — how long the browser waits before reconnecting, in ms. */
+  retry?: number
+}
+
+/** The handle a producer writes to. */
+export interface SSEStream {
+  /** Send one event. A no-op once the stream is closed. */
+  send(message: SSEMessage | unknown): void
+  /** Send a `:` comment. Useful as a keep-alive through idle proxies. */
+  comment(text?: string): void
+  /** Close the stream. Idempotent. */
+  close(): void
+  /** True once the client has gone or `close()` has run. */
+  readonly closed: boolean
+}
+
+export interface SSEOptions {
+  /**
+   * Milliseconds between automatic keep-alive comments. `0` disables them.
+   *
+   * Defaults to 15s because idle proxies and load balancers commonly cut a
+   * connection at 30–60s, and a dead SSE stream is invisible: the browser
+   * reconnects silently, so the symptom is duplicated work on the server rather
+   * than an error anyone sees.
+   */
+  keepAlive?: number
+  /** Initial `retry:` hint sent once, before any event. */
+  retry?: number
+}
+
+/**
+ * Encode one message as an SSE frame.
+ *
+ * **Every line of `data` is prefixed.** A payload containing a newline is
+ * otherwise cut short at that newline — the rest is read as a new field, and
+ * the client sees a truncated message rather than an error. Pretty-printed JSON
+ * and stack traces both hit this.
+ */
+export function encodeSSE(message: SSEMessage): string {
+  const lines: string[] = []
+
+  if (message.event) lines.push(`event: ${message.event}`)
+  if (message.id !== undefined) lines.push(`id: ${message.id}`)
+  if (message.retry !== undefined) lines.push(`retry: ${message.retry}`)
+
+  const payload =
+    typeof message.data === 'string'
+      ? message.data
+      : JSON.stringify(message.data)
+
+  // `?? ''` rather than skipping: `JSON.stringify(undefined)` is undefined, and
+  // a frame with no `data:` line at all is a comment to the client — the event
+  // would vanish rather than arrive empty.
+  for (const line of (payload ?? '').split('\n')) lines.push(`data: ${line}`)
+
+  // The blank line terminates the frame. Without it the client buffers forever.
+  return `${lines.join('\n')}\n\n`
+}
+
+/**
+ * Build an SSE response and hand the producer a stream to write to.
+ *
+ *     export default defineRoute(req =>
+ *       sse(req, stream => {
+ *         const timer = setInterval(() => stream.send({ now: Date.now() }), 1000)
+ *         return () => clearInterval(timer)
+ *       }),
+ *     )
+ *
+ * The producer may return a cleanup function, which runs exactly once when the
+ * client disconnects or `close()` is called. That is the only reliable place to
+ * stop a timer or unsubscribe: without it, a closed connection leaves the
+ * interval running for the life of the process, and the leak is silent.
+ */
+export function sse(
+  req: Request,
+  producer: (
+    stream: SSEStream,
+  ) => void | (() => void) | Promise<void | (() => void)>,
+  options: SSEOptions = {},
+): Response {
+  const encoder = new TextEncoder()
+  const { keepAlive = 15_000, retry } = options
+
+  let controller: ReadableStreamDefaultController<Uint8Array> | null = null
+  let closed = false
+  let cleanup: (() => void) | void
+  let keepAliveTimer: ReturnType<typeof setInterval> | undefined
+
+  const write = (chunk: string) => {
+    if (closed || !controller) return
+    try {
+      controller.enqueue(encoder.encode(chunk))
+    } catch {
+      // The client went away between the `closed` check and the enqueue. That
+      // is a normal race on every disconnect, not an error worth surfacing —
+      // and throwing here would reject inside a timer callback, where nothing
+      // is catching.
+      finish()
+    }
+  }
+
+  function finish() {
+    if (closed) return
+    closed = true
+    if (keepAliveTimer) clearInterval(keepAliveTimer)
+    try {
+      cleanup?.()
+    } catch {
+      // A producer's cleanup that throws must not prevent the stream closing;
+      // the connection is already going away either way.
+    }
+    try {
+      controller?.close()
+    } catch {
+      // Already closed by the runtime when the client disconnected.
+    }
+  }
+
+  const stream: SSEStream = {
+    send(message) {
+      const normalised: SSEMessage =
+        message && typeof message === 'object' && 'data' in (message as object)
+          ? (message as SSEMessage)
+          : { data: message }
+      write(encodeSSE(normalised))
+    },
+    comment(text = '') {
+      write(`: ${text}\n\n`)
+    },
+    close: finish,
+    get closed() {
+      return closed
+    },
+  }
+
+  const body = new ReadableStream<Uint8Array>({
+    async start(c) {
+      controller = c
+
+      // The client aborting is the common ending, not an exception. Without
+      // this the producer keeps writing into a dead socket.
+      req.signal?.addEventListener('abort', finish, { once: true })
+      if (req.signal?.aborted) return finish()
+
+      if (retry !== undefined) write(`retry: ${retry}\n\n`)
+      if (keepAlive > 0) {
+        keepAliveTimer = setInterval(
+          () => stream.comment('keep-alive'),
+          keepAlive,
+        )
+      }
+
+      try {
+        cleanup = await producer(stream)
+      } catch {
+        // A producer that throws ends the stream rather than leaving the client
+        // hanging on a connection nobody will write to again.
+        finish()
+      }
+    },
+    cancel: finish,
+  })
+
+  return new Response(body, {
+    headers: {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      // A cached event stream is a stream that never arrives.
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      // nginx buffers proxied responses by default, which holds every event
+      // until the buffer fills — the stream appears to work in development and
+      // to hang in production. This is the documented opt-out.
+      'X-Accel-Buffering': 'no',
+    },
+  })
+}