@bakery-framework/core 2.1.2 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/core",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Bakery framework core: handlers, router, config, session, caches, logger, compiler.",
   "keywords": [
     "bakery",

package/src/cache/tiered.ts

@@ -202,6 +202,15 @@ export class TieredCache<K extends string | number, V> {
     return fromRAM || info.changes > 0
   }
 
+  /**
+   * The value if it is in the memory tier. Records no access and reads
+   * nothing from disk: for a caller that needs the live object, if there is
+   * one, without promoting a row that nothing is using.
+   */
+  peek(key: K): V | undefined {
+    return this.memoryStore.get(key)?.value
+  }
+
   getAccessedAt(key: K): number | undefined {
     if (this.memoryStore.has(key)) return this.memoryStore.get(key)!.accessedAt
     return (

package/src/compiler/compiler.ts

@@ -56,6 +56,16 @@ function getDefines(): Promise<MapOf<string>> {
   return definesPromise
 }
 
+/**
+ * The `import.meta.env.*` values browser code is compiled with: the table the
+ * transpiler applies to a served `.ts` module. Public for a plugin bundling
+ * the same modules (plugin-vue's `bakery --build`), which has to apply the
+ * same values or a bundled page would read different ones than a served page.
+ */
+export function clientDefines(): Promise<MapOf<string>> {
+  return getDefines()
+}
+
 let transpilerPromise: Promise<Bun.Transpiler> | null = null
 function getTranspiler(): Promise<Bun.Transpiler> {
   transpilerPromise ??= getDefines().then(

package/src/core/config.ts

@@ -54,6 +54,13 @@ const defaultConfig: Required<AppConfig> = {
   // Empty means auto-detect, matching `head`/`body` above. There is no default
   // *path* to give here: the default behavior is the probe itself.
   schema: '',
+  // Empty means migrations mode is off, and the schema declarations are the
+  // truth that db:sync enforces.
+  migrations: '',
+  // No store means the built-in one: memory, with bakery/sessions.db behind
+  // it. No account key means `Session.endForAccount` has nothing to look up,
+  // and says so rather than ending nothing.
+  sessions: {},
   root: 'src',
   hosts: {},
   websocket: {
@@ -179,6 +186,15 @@ export function __resetTestConfig(): void {
   testOverrides = null
 }
 
+/**
+ * The config once `initConfig()` has run, and null before it: for code that
+ * also runs outside a server, where the defaults are the answer. Sessions are
+ * the case: a unit test or a script builds one without booting anything.
+ */
+export function peekConfig(): Readonly<ProcessedAppConfig> | null {
+  return cachedConfig ? getConfig() : null
+}
+
 export function getConfig(): Readonly<ProcessedAppConfig> {
   if (!cachedConfig) {
     throw new Error('Config has not been initialized. Call initConfig() first.')

package/src/core/context.ts

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
+import type { Handler } from '../handlers/core/$base'
 import { matchBlocked } from '../utils/constants'
 import { fs } from '../utils/fs'
 
@@ -35,6 +36,13 @@ export type HostContext = {
    * globs, which are frozen for the life of the store.
    */
   blockedPaths?: Map<string, boolean>
+  /**
+   * The handler routing chose for this request, set by `handleRequest` just
+   * before it is called. The rate limiter reads it once the response is
+   * ready, to ask `isAsset`. Absent when no handler answered: a CORS
+   * preflight, a plugin's `onRequest`, a forbidden path, a WebSocket upgrade.
+   */
+  handler?: typeof Handler
 }
 
 export const hostStore = new AsyncLocalStorage<HostContext>()

package/src/core/index.ts

@@ -51,6 +51,11 @@ export type {
 } from '../types'
 /** Configured in `server.config.ts`; the type is exported so an app can build one. */
 export type { CorsOptions } from '../utils/http/cors'
+export type {
+  RateLimitKey,
+  RateLimitOptions,
+  RateLimitRule,
+} from '../utils/http/rate-limit'
 export type { SSEMessage, SSEOptions, SSEStream } from '../utils/http/sse'
 // The validation surface, so an app can type its own schemas and validators.
 export type {

package/src/core/plugins.ts

@@ -111,6 +111,30 @@ export namespace PluginHooks {
     }
   }
 
+  /**
+   * Every plugin's `build`, in order. A failure is logged and the rest still
+   * run, so one command reports every plugin that cannot build rather than
+   * the first. Returns the names of the plugins that built and that failed.
+   */
+  export async function build(): Promise<{
+    built: string[]
+    failed: string[]
+  }> {
+    const built: string[] = []
+    const failed: string[] = []
+    for (const plugin of getPlugins()) {
+      if (!plugin.build) continue
+      const [err] = await Try.catch(() => plugin.build!(Bakery.config))
+      if (err) {
+        pluginLog.UNHANDLED_ERR({ error: `${plugin.name}: ${errorMsg(err)}` })
+        failed.push(plugin.name)
+      } else {
+        built.push(plugin.name)
+      }
+    }
+    return { built, failed }
+  }
+
   export async function onCompile(
     content: string,
     path: string,

package/src/global.d.ts

@@ -72,13 +72,7 @@ declare global {
     body?: string
     proxy?: Record<string, string>
     blocked?: string[]
-    rateLimit?:
-      | {
-          max: number
-          refill: number
-          keyBy?: (req: Request) => string
-        }
-      | false
+    rateLimit?: import('./utils/http/rate-limit').RateLimitOptions | false
   }
 
   type AppConfig = {
@@ -132,13 +126,7 @@ declare global {
 
     blocked?: string[]
 
-    rateLimit?:
-      | {
-          max: number
-          refill: number
-          keyBy?: (req: Request) => string
-        }
-      | false
+    rateLimit?: import('./utils/http/rate-limit').RateLimitOptions | false
 
     trustProxy?: boolean
 
@@ -156,6 +144,29 @@ declare global {
      */
     schema?: string
 
+    /**
+     * The folder of SQL migration files, relative to the app's cwd, which
+     * turns on migrations mode: the files are the schema's source of truth,
+     * `db:migrate` applies them in order, and `db:sync` only checks the
+     * declared tables against the database, never altering or dropping
+     * anything. Empty (the default) leaves the declarations as the truth, the
+     * way `db:sync` has always worked.
+     *
+     * A plain string for the reason `schema` is one.
+     */
+    migrations?: string
+
+    /**
+     * Where sessions live, and which session key holds the account id.
+     *
+     * `store` replaces the built-in store (memory, with `bakery/sessions.db`
+     * behind it) with one every worker shares and nothing caches, such as
+     * `databaseSessions()` from `@bakery-framework/orm/sessions`. `account`
+     * names the key a store indexes, which is what lets
+     * `Session.endForAccount()` find every session of one account.
+     */
+    sessions?: import('./session').SessionOptions
+
     hosts?: Record<string, HostEntry>
   }
 

package/src/handlers/assets/nm.ts

@@ -13,6 +13,11 @@ export class NMHandler extends Handler {
     return path.startsWith('/_nm/')
   }
 
+  /** A bundled package. The bundling is bounded by what is installed, and cached. */
+  static isAsset(): boolean {
+    return true
+  }
+
   /**
    * The file a `/_nm/` path names.
    *

package/src/handlers/assets/public.ts

@@ -8,6 +8,10 @@ export class PublicHandler extends Handler {
     return path.startsWith('/uploads/')
   }
 
+  static isAsset(): boolean {
+    return true
+  }
+
   static async handle(path: string) {
     const resolved = await getStatic(path, Bakery.publicRoot)
     if (!resolved) return response.error('Not Found')

package/src/handlers/assets/static.ts

@@ -12,6 +12,11 @@ export class StaticHandler extends Handler {
     return true
   }
 
+  /** A file from the serve root. A missing one is a 404, which never counts as an asset. */
+  static isAsset(): boolean {
+    return true
+  }
+
   static get cacheDir() {
     return fs.resolve(Bakery.cacheDir, 'static')
   }

package/src/handlers/assets/ts.ts

@@ -20,6 +20,11 @@ export class TSHandler extends DynamicHandler {
     return fs.resolve(Bakery.cacheDir, 'ts_cache')
   }
 
+  /** A browser module, compiled once per file and cached on disk by the file. */
+  static isAsset(): boolean {
+    return true
+  }
+
   static async canHandle(path: string, req: Request) {
     if (path.endsWith('.ts')) return true
     return await super.canHandle(normalizePath(path), req)

package/src/handlers/assets/virtual-asset.ts

@@ -17,6 +17,11 @@ export class VirtualAssetHandler extends Handler {
     return fs.resolve(Bakery.cacheDir, 'virtual')
   }
 
+  /** The framework's own client files. */
+  static isAsset(): boolean {
+    return true
+  }
+
   static get clientAssets(): MapOf<string> {
     // frameworkPath, not Bakery.root: these ship with the framework, so they
     // must resolve relative to it rather than to the application's cwd.

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

@@ -269,6 +269,34 @@ export class Handler {
    */
   static namespace: string | null = null
 
+  /**
+   * Whether this handler's successful answer to `req` was an asset, which the
+   * rate limiter then stops counting: a file from the serve root, a compiled
+   * module, a stylesheet. Asked after the response, with the status already
+   * known to be under 400, so it describes what was served rather than
+   * guessing from the request.
+   *
+   * An asset's URL is remembered, and a later request for the same URL
+   * (host, path, query and `Sec-Fetch-Dest`) skips the bucket entirely, which
+   * is what keeps a page's forty modules from counting forty times, and
+   * keeps a school behind one address from sharing one budget for them. A
+   * first request still borrows a token for the duration and gets it back
+   * once this answers true.
+   *
+   * So answer true only when a successful answer costs about what reading a
+   * file costs, *and* the work behind a first answer (a compile, a bundle) is
+   * bounded by the app's own files: a client must not be able to mint new
+   * work by varying the URL. That rules out `ImageHandler`, where each new
+   * size is a new resize, and `GoogleFontHandler`, where each new family is
+   * an upstream fetch. A handler that runs app code per request (pages, API
+   * routes, middleware, Vue server blocks) is not serving an asset either.
+   *
+   * False by default, so a plugin's handler counts unless it says otherwise.
+   */
+  static isAsset(_path: string, _req: Request): boolean {
+    return false
+  }
+
   protected constructor() {}
 
   static get cache(): HandlerCache<string, Route.Info> {

package/src/logger/serve-log.ts

@@ -18,8 +18,19 @@ const serveMsgs = {
   SCHEMA_DRIFT:
     'W %yDatabase no longer matches the last schema Bakery applied%*: {reason}. Run %cdb:history%* to see what was applied, or %cdb:sync --dry-run%* to see what the difference means.',
   UNHANDLED_ERR: 'E Unhandled Server Error: %r{error}%*',
+  // A configured session store that could not be read: the request is
+  // answered as an error rather than as a visitor with no session, which
+  // would sign everybody out for as long as the store is down.
+  SESSION_LOAD_ERR: 'E Could not read the session store: %r{error}%*',
+  SESSION_PRUNE_ERR: 'E Could not prune expired sessions: %r{error}%*',
+  BUILD_FAILED: 'E %rbakery --build failed%* in: %y{plugins}%*',
+  BUILD_NOTHING:
+    'I Nothing to build: no plugin in %yserver.config.ts%* has a build step.',
   SHUTTING_DOWN: 'W %yShutting down server...%*',
   BACKEND_CHANGE: 'I Backend change detected: %y{file}%*',
+  // The banner's first line: the framework serving the app, which is the
+  // version a bug report needs and a log otherwise never said.
+  BAKERY_VERSION: 'I Bakery v{version}',
   SERVER_STARTED: 'I %gServer running at:%*',
   SERVER_URL: 'I   ➜ %w{type}%*: %bhttp://{host}:{port}%*',
   WATCHER_ERR: 'E Watcher error: %r{error}%*',
@@ -67,6 +78,11 @@ const serveMsgs = {
   // lines back; the "30s" must stay in step with RATE_LIMIT_LOG_WINDOW_MS.
   RATE_LIMITED_SUPPRESSED:
     'W Rate limited: %y{ip}%* (%y{count}%* rejections suppressed in the last 30s)',
+  // The same two for a request charged to a `rateLimit.routes` rule, named by
+  // its prefix, so a sign-in limit firing reads differently from a flood.
+  RATE_LIMITED_ROUTE: 'W Rate limited: %y{ip}%* on %y{prefix}%*',
+  RATE_LIMITED_ROUTE_SUPPRESSED:
+    'W Rate limited: %y{ip}%* on %y{prefix}%* (%y{count}%* rejections suppressed in the last 30s)',
   // Printed only when the *default* limit is in effect: an unconfigured rate
   // limit silently 429s load tests and shared-NAT offices, so its existence
   // gets one announcement. An app-configured value prints nothing.

package/src/plugins/types.ts

@@ -89,6 +89,14 @@ export interface ServerPlugin {
   onError?(error: Handler.Error.Data, req?: Request): ValidResponses
   onShutdown?(): MixedPromise<void>
   onCompile?(content: string, path: string): MixedPromise<string>
+
+  /**
+   * `bakery --build`: work done once, ahead of a production start, such as
+   * plugin-vue bundling every page. Runs after `setup()`, with no server and
+   * no database connection. A throw fails the command, which is what lets a
+   * deploy stop on it rather than serve what did not build.
+   */
+  build?(config: ProcessedAppConfig): MixedPromise<void>
 }
 
 export function definePlugin<T extends ServerPlugin>(plugin: T): T {

package/src/router.ts

@@ -143,6 +143,11 @@ export async function handleRequest(req: Request) {
     return new Response('Forbidden', { status: 403 })
   }
 
+  // Recorded for the rate limiter, which asks the handler afterwards whether
+  // what it served was an asset. See `Handler.isAsset`.
+  const store = hostStore.getStore()
+  if (store) store.handler = handler
+
   return handler.handle(path, req)
 }
 
@@ -315,8 +320,18 @@ export async function processResponse(
   let status = 200
   let type = 'text/plain; charset=utf-8'
   if (data === WebSocketHandler.WS_UPGRADE) return
-  if (data === null || data === undefined)
-    return new Response(null, { status: 204 })
+
+  // Every other response commits the session, the empty one below included.
+  // A handler answering 204 used to skip this, so a session it wrote was
+  // never stored when it was new; with a configured store, whose writes wait
+  // for the commit, a logout answered 204 would not have ended anything.
+  const cookie = await Session.commit(req)
+
+  if (data === null || data === undefined) {
+    const empty = new Response(null, { status: 204 })
+    if (cookie) empty.headers.append('Set-Cookie', cookie)
+    return empty
+  }
 
   const resp = await (async function getResponse() {
     if (data instanceof Response) {
@@ -347,11 +362,9 @@ export async function processResponse(
     return ETag.sendText(String(data), req, type, status)
   })()
 
-  const sess = Session.getCookie(req)
-
   // 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)
+  if (cookie) resp.headers.append('Set-Cookie', cookie)
 
   // 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