@bakery-framework/cli 2.0.0-alpha.3 → 2.0.0-alpha.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/cli",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0-alpha.5",
   "description": "Bakery entry point and process supervision: mode dispatch, dev watcher, cluster.",
   "keywords": [
     "bakery",
@@ -39,10 +39,10 @@
     "bun": ">=1.3.14"
   },
   "dependencies": {
-    "@bakery-framework/core": "^2.0.0-alpha.3"
+    "@bakery-framework/core": "^2.0.0-alpha.5"
   },
   "peerDependencies": {
-    "@bakery-framework/orm": "^2.0.0-alpha.3"
+    "@bakery-framework/orm": "^2.0.0-alpha.5"
   },
   "peerDependenciesMeta": {
     "@bakery-framework/orm": {

package/src/args.ts

@@ -0,0 +1,62 @@
+/**
+ * Command-line argument parsing for the `bakery` bin.
+ *
+ * Split out of `index.ts` so it can be tested: that file is the mode
+ * dispatcher, and importing it boots a server. Nothing here reads
+ * `process.argv` — the caller passes the slice, which is also what lets a test
+ * state the argv it means.
+ */
+
+/** Upper bound on the auto-detected worker count. */
+export const MAX_AUTO_THREADS = 8
+
+/** Fallback when `navigator.hardwareConcurrency` is unavailable. */
+export const FALLBACK_THREADS = 4
+
+/**
+ * Worker count for a bare `--threads` / `-t`, with no number after it.
+ *
+ * Capped rather than uncapped: past ~8 the workers contend on the same
+ * loopback accept queue and the shared pool's atomics, and a 64-core CI box
+ * forking 64 servers is not what the flag means.
+ */
+export function autoThreadCount(): number {
+  return Math.min(
+    Math.max(1, navigator.hardwareConcurrency || FALLBACK_THREADS),
+    MAX_AUTO_THREADS,
+  )
+}
+
+/**
+ * How many cluster workers `--threads` asks for, or `null` for "no cluster".
+ *
+ * `null` and `1` are different answers and `index.ts` branches on the
+ * difference: `null` takes the single-process path, `1` still goes through
+ * `handleThreadsMaster` with one worker.
+ *
+ * Both spellings of each flag are accepted (`--threads 4`, `--threads=4`, and
+ * the `-t` forms). A flag with a non-numeric or absent value is not an error —
+ * it falls back to `autoThreadCount()`, so `--threads --dev` asks for the
+ * default rather than rejecting. `Math.max(1, …)` is what keeps `--threads 0`
+ * from requesting a cluster with no workers in it.
+ */
+export function parseThreadsOption(args: string[]): number | null {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--threads' || arg === '-t') {
+      const next = args[i + 1]
+      if (next && /^\d+$/.test(next)) {
+        return Math.max(1, parseInt(next, 10))
+      }
+      return autoThreadCount()
+    }
+    if (arg.startsWith('--threads=') || arg.startsWith('-t=')) {
+      const val = arg.split('=')[1]
+      if (val && /^\d+$/.test(val)) {
+        return Math.max(1, parseInt(val, 10))
+      }
+      return autoThreadCount()
+    }
+  }
+  return null
+}

package/src/dev.ts

@@ -37,66 +37,6 @@ try {
   process.exit(1)
 }
 
-/**
- * Hash everything the boot-time schema sync reads: the schema source files
- * (resolved with the same probe order as orm/sync/load.ts — configured path,
- * then the `orm/` folder layout, then a root `schema.ts`) plus the DB target,
- * since switching `DB_URL` changes what "synced" means.
- *
- * Returns `null` for any indeterminate state — a configured path that does not
- * exist, an unreadable file — so `classifySchemaSync` fails closed into
- * re-syncing. Total absence of a schema is *not* indeterminate (it is a
- * supported state for the defaults) and hashes to a stable value.
- */
-async function computeSchemaHash(
-  configured: string | undefined,
-): Promise<string | null> {
-  const { fs, Try } = await import('@bakery-framework/core/utils')
-
-  const files: string[] = []
-  const scanDir = async (dir: string) => {
-    for await (const file of new Bun.Glob('*.ts').scan({
-      cwd: dir,
-      absolute: true,
-    })) {
-      files.push(file)
-    }
-  }
-
-  const [error] = await Try.catch(
-    (async () => {
-      if (configured) {
-        const path = fs.resolve(fs.cwd, configured)
-        if (await fs.isDir(path)) {
-          await scanDir(path)
-        } else if (await Bun.file(path).exists()) {
-          files.push(path)
-        } else {
-          // Configured-but-missing is SyncService's SCHEMA_NOT_FOUND case:
-          // let the sync run and produce its proper error.
-          throw new Error(`configured schema path not found: ${path}`)
-        }
-      } else if (await Bun.file(`${fs.cwd}/orm/index.ts`).exists()) {
-        await scanDir(`${fs.cwd}/orm`)
-      } else if (await Bun.file(`${fs.cwd}/schema.ts`).exists()) {
-        files.push(`${fs.cwd}/schema.ts`)
-      }
-    })(),
-  )
-  if (error) return null
-
-  files.sort()
-  const hasher = new Bun.CryptoHasher('sha256')
-  hasher.update(process.env.DB_URL || process.env.DATABASE_URL || '')
-  for (const file of files) {
-    hasher.update(`\0${file}\0`)
-    const [readError, content] = await Try.catch(Bun.file(file).text())
-    if (readError) return null
-    hasher.update(content)
-  }
-  return hasher.digest('hex')
-}
-
 // The entire block is schema sync, so with no ORM there is nothing here to do.
 // Silently: a dev boot of an app that never had a database should not report
 // the absence of one on every reload.
@@ -108,6 +48,10 @@ if (hasORM()) {
     )
     const { schemaFromConfig } = await import('@bakery-framework/orm/sync/load')
     const { Try } = await import('@bakery-framework/core/utils')
+    // Dynamic, like every other import in this block: `schema-hash.ts` is only
+    // needed when the ORM is installed, and a static import would pull it (and
+    // its own dynamic core barrel) onto the no-ORM boot path.
+    const { computeSchemaHash } = await import('./schema-hash')
 
     const hashFile = `${Bakery.cacheDir}/schema-sync.hash`
     const currentHash = await computeSchemaHash(schemaFromConfig(config))

package/src/index.ts

@@ -4,34 +4,15 @@ import '@bakery-framework/core/core/init'
 // Safe as a static import: `core/port` reads `process.env` and imports nothing,
 // so it cannot be the edge that closes core's barrel cycle.
 import { applyPortFlag } from '@bakery-framework/core/core/port'
+// Safe as a static import for the same reason as `core/port`: `args.ts` imports
+// nothing at all.
+import { parseThreadsOption } from './args'
 
 const isDev = import.meta.env.DEV
 const isDevWorker = import.meta.env.DEV_WORKER
 const isThreadWorker = import.meta.env.THREAD_WORKER
 
-function getThreadsOption(): number | null {
-  const args = process.argv.slice(2)
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i]
-    if (arg === '--threads' || arg === '-t') {
-      const next = args[i + 1]
-      if (next && /^\d+$/.test(next)) {
-        return Math.max(1, parseInt(next, 10))
-      }
-      return Math.min(Math.max(1, navigator.hardwareConcurrency || 4), 8)
-    }
-    if (arg.startsWith('--threads=') || arg.startsWith('-t=')) {
-      const val = arg.split('=')[1]
-      if (val && /^\d+$/.test(val)) {
-        return Math.max(1, parseInt(val, 10))
-      }
-      return Math.min(Math.max(1, navigator.hardwareConcurrency || 4), 8)
-    }
-  }
-  return null
-}
-
-const threadsOption = getThreadsOption()
+const threadsOption = parseThreadsOption(process.argv.slice(2))
 
 // Before any mode takes over, and before the config is read: `applyPortFlag`
 // writes `process.env.PORT`, which is what the worker, the startup banner and

package/src/pipeline.ts

@@ -0,0 +1,69 @@
+import { is } from '@bakery-framework/core/utils/common'
+import { getClientIp } from '@bakery-framework/core/utils/http'
+import { retryAfterSeconds } from './rate-limit'
+
+/**
+ * The three decisions `worker.ts`'s `fetch` makes that are pure functions of
+ * their arguments.
+ *
+ * They were inline in the `Bun.serve` callback, which is unreachable from a
+ * test: `worker.ts` calls `Bun.serve` at module scope, so importing it binds a
+ * port. Nothing about them is server-specific, so they live here and the
+ * callback calls them — the serve options are otherwise unchanged.
+ */
+
+/** The `rateLimit` config with the `false` (disabled) arm removed. */
+export type RateLimitConfig = Exclude<ProcessedAppConfig['rateLimit'], false>
+
+/**
+ * Whether a handler's return value should be routed into the error registry.
+ *
+ * Two shapes count, and they are not interchangeable. A `Response` is an error
+ * by its status; anything else is an error by carrying `errorCode`, which is
+ * what `ErrorHandler.extractErrorData` reads.
+ *
+ * The `is.object` guard is load-bearing twice over. `'errorCode' in res` is a
+ * `TypeError` on a primitive, and `Try.return`'s failure sentinel is a
+ * `symbol` — so the guard is what keeps the rejection path from throwing
+ * inside the code that exists to handle throws. Note `is.object([])` is
+ * deliberately `true` (see CLAUDE.md); an array simply has no `errorCode`.
+ *
+ * 400 is included: `>= 400`, not `> 400`. A handler returning a bare
+ * `new Response(…, {status: 404})` must still reach `TSXErrorHandler` and get
+ * the app's error page rather than an empty body.
+ */
+export function isErrorResult(res: unknown): boolean {
+  if (res instanceof Response) return res.status >= 400
+  return is.object(res) && 'errorCode' in res
+}
+
+/**
+ * Which token bucket this request spends from.
+ *
+ * The `|| hostname` is not a tidy-up. An empty key is a *valid* string that
+ * hashes to one fixed slot, so every client whose IP could not be determined —
+ * which is all of them when `Bakery.server` is not yet assigned, and any of
+ * them behind a proxy with `trustProxy` off — would share a single bucket and
+ * 429 each other. Falling back to the hostname keeps the collision at
+ * per-host, which is the coarsest grouping that is still meaningful.
+ */
+export function rateLimitKey(
+  rl: RateLimitConfig,
+  req: Request,
+  hostname: string,
+): string {
+  return (rl.keyBy ? rl.keyBy(req) : getClientIp(req)) || hostname
+}
+
+/**
+ * The 429 a rejected request receives.
+ *
+ * `Retry-After` is whole seconds per RFC 9110 and never 0 — see
+ * `retryAfterSeconds`.
+ */
+export function tooManyRequests(refill: number): Response {
+  return new Response('Too Many Requests', {
+    status: 429,
+    headers: { 'Retry-After': String(retryAfterSeconds(refill)) },
+  })
+}

package/src/schema-hash.ts

@@ -0,0 +1,70 @@
+/**
+ * Hash everything the boot-time schema sync reads: the schema source files
+ * (resolved with the same probe order as orm/sync/load.ts — configured path,
+ * then the `orm/` folder layout, then a root `schema.ts`) plus the DB target,
+ * since switching `DB_URL` changes what "synced" means.
+ *
+ * Returns `null` for any indeterminate state — a configured path that does not
+ * exist, an unreadable file — so `classifySchemaSync` fails closed into
+ * re-syncing. Total absence of a schema is *not* indeterminate (it is a
+ * supported state for the defaults) and hashes to a stable value.
+ *
+ * `base` defaults to the app's cwd, which is what `dev.ts` wants and the only
+ * value it passes. It is a parameter at all because `fs.cwd` is a module-level
+ * constant evaluated at import time, so a test cannot reach this function's
+ * probe any other way without `process.chdir` before the import — process-global
+ * state of exactly the kind convention 9 exists to keep out of the suite.
+ *
+ * The `@bakery-framework/core/utils` import stays dynamic, as it was inline in
+ * `dev.ts`: that barrel must not enter the module graph at `dev.ts` import time.
+ */
+export async function computeSchemaHash(
+  configured: string | undefined,
+  base?: string,
+): Promise<string | null> {
+  const { fs, Try } = await import('@bakery-framework/core/utils')
+  const cwd = base ?? fs.cwd
+
+  const files: string[] = []
+  const scanDir = async (dir: string) => {
+    for await (const file of new Bun.Glob('*.ts').scan({
+      cwd: dir,
+      absolute: true,
+    })) {
+      files.push(file)
+    }
+  }
+
+  const [error] = await Try.catch(
+    (async () => {
+      if (configured) {
+        const path = fs.resolve(cwd, configured)
+        if (await fs.isDir(path)) {
+          await scanDir(path)
+        } else if (await Bun.file(path).exists()) {
+          files.push(path)
+        } else {
+          // Configured-but-missing is SyncService's SCHEMA_NOT_FOUND case:
+          // let the sync run and produce its proper error.
+          throw new Error(`configured schema path not found: ${path}`)
+        }
+      } else if (await Bun.file(`${cwd}/orm/index.ts`).exists()) {
+        await scanDir(`${cwd}/orm`)
+      } else if (await Bun.file(`${cwd}/schema.ts`).exists()) {
+        files.push(`${cwd}/schema.ts`)
+      }
+    })(),
+  )
+  if (error) return null
+
+  files.sort()
+  const hasher = new Bun.CryptoHasher('sha256')
+  hasher.update(process.env.DB_URL || process.env.DATABASE_URL || '')
+  for (const file of files) {
+    hasher.update(`\0${file}\0`)
+    const [readError, content] = await Try.catch(Bun.file(file).text())
+    if (readError) return null
+    hasher.update(content)
+  }
+  return hasher.digest('hex')
+}

package/src/worker.ts

@@ -19,15 +19,12 @@ import {
 } from '@bakery-framework/core/router'
 import { Session } from '@bakery-framework/core/session'
 import { runStartupBanner, setupServer } from '@bakery-framework/core/startup'
-import { deferredValue, is, Try } from '@bakery-framework/core/utils/common'
-import { getClientIp } from '@bakery-framework/core/utils/http'
+import { deferredValue, Try } from '@bakery-framework/core/utils/common'
+import { parsedUrl } from '@bakery-framework/core/utils/http'
 import { COUNTER_SLOTS } from '@bakery-framework/core/utils/shared-pool'
 import { hasORM } from './orm'
-import {
-  rateLimitSlot,
-  retryAfterSeconds,
-  sampleRateLimitLog,
-} from './rate-limit'
+import { isErrorResult, rateLimitKey, tooManyRequests } from './pipeline'
+import { rateLimitSlot, sampleRateLimitLog } from './rate-limit'
 import { runShutdownSequence } from './shutdown'
 
 /**
@@ -142,10 +139,10 @@ try {
     maxRequestBodySize: Bakery.config.maxBodySize,
 
     async fetch(req) {
-      // Parsed once here and attached: `new URL` measures ~1.7us and the
-      // router, body parser and proxy all want the same parse.
-      const url = new URL(req.url)
-      ;(req as any).__parsedUrl = url
+      // Memoized for the lifetime of the request: the router, body parser and
+      // proxy all want the same parse, and every one of them asks for it the
+      // same way.
+      const url = parsedUrl(req)
       const hostname = getHostname(req)
       const hostConfig = resolveHostConfig(hostname)
 
@@ -157,7 +154,7 @@ try {
 
         const rl = Bakery.config.rateLimit
         if (rl) {
-          const key = (rl.keyBy ? rl.keyBy(req) : getClientIp(req)) || hostname
+          const key = rateLimitKey(rl, req, hostname)
           const slot = rateLimitSlot(key)
           if (!Bakery.sharedPool.consumeToken(slot, rl.max, rl.refill)) {
             // Sampled — availability under flood: stdout is effectively
@@ -171,12 +168,7 @@ try {
                 serveLog.RATE_LIMITED({ ip: key })
               }
             }
-            return new Response('Too Many Requests', {
-              status: 429,
-              headers: {
-                'Retry-After': String(retryAfterSeconds(rl.refill)),
-              },
-            })
+            return tooManyRequests(rl.refill)
           }
         }
 
@@ -186,10 +178,7 @@ try {
           async function fetchHandler() {
             const res = await handleRequest(req)
 
-            const isResError = res instanceof Response && res.status >= 400
-            const isObjError = is.object(res) && 'errorCode' in res
-
-            if (isResError || isObjError) {
+            if (isErrorResult(res)) {
               Bakery.sharedPool.incrementCounter(COUNTER_SLOTS.TOTAL_ERRORS, 1)
               return await handleRequestError(path, req, res)
             }