@fabrika/app 0.9.0-cloudflare.3 → 0.9.0-dev.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/package.json +9 -9
  2. package/skill/SKILL.md +6 -3
  3. package/skill/references/app-setup.md +8 -8
  4. package/skill/references/dev.md +3 -1
  5. package/skill/references/endpoint.md +9 -9
  6. package/skill/references/errors.md +42 -34
  7. package/skill/references/files.md +4 -2
  8. package/skill/references/jobs.md +18 -12
  9. package/skill/references/table-and-migration.md +31 -4
  10. package/skill/references/tests.md +22 -10
  11. package/src/bun.ts +0 -10
  12. package/src/cloudflare/import.ts +3 -212
  13. package/src/contract/artifact-schema.ts +1 -6
  14. package/src/contract/build.ts +10 -33
  15. package/src/contract/capability-cases.ts +30 -0
  16. package/src/contract/containers.ts +19 -0
  17. package/src/contract/group.ts +1 -10
  18. package/src/contract/index.ts +1 -0
  19. package/src/contract/kit.ts +1 -2
  20. package/src/files/handle.ts +2 -1
  21. package/src/files/kinds.ts +1 -1
  22. package/src/implement/boot.ts +12 -30
  23. package/src/implement/capability.ts +1 -4
  24. package/src/implement/dispatch.ts +8 -5
  25. package/src/implement/egress.ts +8 -367
  26. package/src/implement/failures.ts +42 -3
  27. package/src/implement/faults.ts +4 -1
  28. package/src/implement/invocation.ts +13 -11
  29. package/src/implement/tokens.ts +4 -2
  30. package/src/implement/types.ts +22 -4
  31. package/src/jobs/runner.ts +32 -20
  32. package/src/testing/endpoint-access.ts +30 -23
  33. package/src/testing/index.ts +1 -1
  34. package/src/testing/kit.ts +6 -2
  35. package/src/testing/policy-isolation.ts +2 -2
  36. package/types/src/cloudflare/import.d.ts +1 -12
  37. package/types/src/contract/capability-cases.d.ts +9 -0
  38. package/types/src/contract/containers.d.ts +3 -0
  39. package/types/src/contract/group.d.ts +1 -9
  40. package/types/src/contract/index.d.ts +1 -0
  41. package/types/src/contract/kit.d.ts +2 -2
  42. package/types/src/files/handle.d.ts +2 -1
  43. package/types/src/implement/boot.d.ts +6 -9
  44. package/types/src/implement/capability.d.ts +1 -3
  45. package/types/src/implement/dispatch.d.ts +1 -2
  46. package/types/src/implement/egress.d.ts +1 -36
  47. package/types/src/implement/failures.d.ts +21 -2
  48. package/types/src/implement/faults.d.ts +4 -1
  49. package/types/src/implement/invocation.d.ts +6 -5
  50. package/types/src/implement/types.d.ts +25 -5
  51. package/types/src/jobs/runner.d.ts +14 -8
  52. package/types/src/testing/endpoint-access.d.ts +4 -3
  53. package/types/src/testing/index.d.ts +1 -1
  54. package/types/src/testing/kit.d.ts +6 -2
@@ -87,7 +87,7 @@ import {
87
87
  } from './capability'
88
88
  import type { ChallengeIssuer, ChallengeVerifier } from './challenge'
89
89
  import { connectContext, type ImportWire } from './connect'
90
- import { runAsSite, type SiteEgress, siteEgress } from './egress'
90
+ import { runAsSite } from './egress'
91
91
  import type { FailureReports } from './failures'
92
92
  import { ServerFault } from './faults'
93
93
  import { type HeaderPolicy, withHeaderPolicy } from './headers'
@@ -250,7 +250,7 @@ export type ServedEndpoint =
250
250
  /** A staged-kit site, which gets `ctx.db`; a handler `implement` bound has none. */
251
251
  readonly site?: ServedSite
252
252
  /** The origins a staged-kit site's `fetch` reaches while its handler runs; absent for a handler `implement` bound. */
253
- readonly egress?: SiteEgress
253
+ readonly egress?: readonly string[]
254
254
  /** Its buckets and time limit; without them (a generated endpoint) no bucket and the request budget. */
255
255
  readonly admission?: ProcedureAdmission
256
256
  /** A POST's `query`, parsed from the URL beside the body: its schema and its shape. */
@@ -426,6 +426,7 @@ export class ContractRuntime {
426
426
 
427
427
  async #answer(request: Request, plan: EndpointPlan, exec: RequestExecutionContext | undefined): Promise<Response | FileDownload> {
428
428
  let where = 'request'
429
+ let selected = false
429
430
  try {
430
431
  const served = plan.outcome === 'endpoint' ? this.#parts.endpoints.get(plan.endpoint.id) : undefined
431
432
  // Before any other answer: a direct dial learns nothing, not even whether its path exists.
@@ -439,6 +440,7 @@ export class ContractRuntime {
439
440
  throw new NotFoundError(`No endpoint serves ${request.method} ${rawRequestTarget(request.url).pathname}`)
440
441
  }
441
442
  where = served.row.id
443
+ selected = true
442
444
  this.#checkEndpoint(served, request)
443
445
  // Counted from here, while it authorizes and uploads too, until it settled.
444
446
  const admission = admitInvocation(invocationKind(served))
@@ -457,7 +459,7 @@ export class ContractRuntime {
457
459
  }
458
460
  const response = errorResponse(error, where)
459
461
  if (response.status >= 500) {
460
- const failure = { endpoint: where, requestId: request.headers.get(REQUEST_ID_HEADER), status: response.status, error }
462
+ const failure = { endpoint: where, selected, requestId: request.headers.get(REQUEST_ID_HEADER), status: response.status, error }
461
463
  const delivery = this.#parts.failures.record(failure)
462
464
  exec?.waitUntil(delivery)
463
465
  }
@@ -961,6 +963,7 @@ export class ContractRuntime {
961
963
  /**
962
964
  * Several capabilities, each minted as its single access form mints it, in their declared order, so the first one
963
965
  * refused answers. Each reads its value from the input as the caller sent it; the fields they read are removed after.
966
+ * `HandlerInput` (`types.ts`) removes the same fields from the handler's input type.
964
967
  */
965
968
  async #capabilities(
966
969
  requirement: CapabilitiesRequirement,
@@ -1216,7 +1219,7 @@ export class ContractRuntime {
1216
1219
  kick: kicks.kick,
1217
1220
  })
1218
1221
  const args = { input, ctx, ...(query === undefined ? {} : { query }) }
1219
- return await runAsSite(`'${served.row.id}'`, siteEgress(served.site.declaration.egress, null), async () => await served.handler(args))
1222
+ return await runAsSite(`'${served.row.id}'`, served.site.declaration.egress, async () => await served.handler(args))
1220
1223
  })
1221
1224
  } finally {
1222
1225
  frame.end()
@@ -1370,7 +1373,7 @@ export class ContractRuntime {
1370
1373
  if (site === undefined) {
1371
1374
  await served.handler(args)
1372
1375
  } else {
1373
- await runAsSite(`webhook '${served.webhook}'`, siteEgress(site.egress, null), async () => await served.handler(args))
1376
+ await runAsSite(`webhook '${served.webhook}'`, site.egress, async () => await served.handler(args))
1374
1377
  }
1375
1378
  })
1376
1379
  } finally {
@@ -1,107 +1,23 @@
1
- // `egress`: while a site's handler runs, the global `fetch` reaches only the HTTPS origins the site declares, or, for a
2
- // cron job that declares `egress: 'public'`, only public hosts (ADR-0071). It stops a mistake and makes a bypass
3
- // conspicuous; it is not a sandbox (ADR-0012 §8): code that kept the `fetch` it found before boot, or opens its own
4
- // sockets, escapes it. The framework's own facilities (mail, connectors, IAM, the object store) run outside the site's
5
- // scope, under their own declarations.
1
+ // `egress`: while a site's handler runs, the global `fetch` reaches only the HTTPS origins the site declares. It stops a
2
+ // mistake and makes a bypass conspicuous; it is not a sandbox (ADR-0012 §8): code that kept the `fetch` it found before
3
+ // boot, or opens its own sockets, escapes it. The framework's own facilities (mail, connectors, IAM, the object store)
4
+ // run outside the site's scope, under their own declarations.
6
5
 
7
- import {
8
- type DeclaredEgress,
9
- FABRIKA_EGRESS_REFUSED_HOSTS,
10
- isPublicAddress,
11
- normalizedHost,
12
- PUBLIC_EGRESS,
13
- publicEgressRefusal,
14
- } from '@fabrika/auth-core'
15
6
  import { AsyncLocalStorage } from 'node:async_hooks'
16
7
  import { CapabilityRefusedError } from './capability'
17
8
 
18
- /** The addresses a host name resolves to, where the runtime exposes resolution: Bun's `node:dns`, never a Worker. */
19
- export type HostResolver = (hostname: string) => Promise<readonly string[]>
20
-
21
- /** What public egress refuses beyond what a URL alone shows (`publicEgressRefusal`). */
22
- export interface PublicEgressRules {
23
- /** The installation's own hosts, normalized: every host a framework variable names, and `FABRIKA_EGRESS_REFUSED_HOSTS`. */
24
- readonly refusedHosts: ReadonlySet<string>
25
- /** Resolves each hop's host before it is sent, so a public name of a private address is refused; `null` on Cloudflare. */
26
- readonly resolve: HostResolver | null
27
- }
28
-
29
- /** What one site's `fetch` reaches: its declared origins, or the rules of public egress. */
30
- export type SiteEgress = readonly string[] | PublicEgressRules
31
-
32
- /**
33
- * The bounds of one request under public egress, the redirects it follows included. The handler's own signal still
34
- * aborts it sooner (`ctx.signal`, an `AbortSignal.timeout` of its own).
35
- */
36
- export const PUBLIC_EGRESS_LIMITS = {
37
- /** One request, its redirects and the reading of its body included: the abort also stops a body still streaming. */
38
- timeoutMs: 60_000,
39
- /** One response's body as the handler reads it; a larger one is refused, by its `Content-Length` or while it streams. */
40
- maxResponseBytes: 16 * 1024 * 1024,
41
- /** The redirects one request follows when its `redirect` mode is `follow`, each hop checked again. */
42
- maxRedirects: 10,
43
- } as const
44
-
45
9
  interface EgressScope {
46
10
  /** The site, as a refusal names it. */
47
11
  readonly site: string
48
12
  readonly origins: ReadonlySet<string>
49
- /** Public egress: `null` for a site that declares origins, or none. */
50
- readonly open: PublicEgressRules | null
51
13
  }
52
14
 
53
15
  const scope = new AsyncLocalStorage<EgressScope>()
54
16
  const guards = new WeakSet<object>()
55
17
 
56
18
  /** Runs a site's handler: every `fetch` it starts reaches only `egress`. */
57
- export function runAsSite<T>(site: string, egress: SiteEgress, work: () => Promise<T>): Promise<T> {
58
- return isOrigins(egress)
59
- ? scope.run({ site, origins: new Set(egress), open: null }, work)
60
- : scope.run({ site, origins: new Set(), open: egress }, work)
61
- }
62
-
63
- /**
64
- * The egress a site runs with: its declared origins, or `rules` for `'public'`. Only a cron job's runner holds rules; a
65
- * site run without them reaches nothing, though the build lets no other site declare `'public'`.
66
- */
67
- export function siteEgress(declared: DeclaredEgress, rules: PublicEgressRules | null): SiteEgress {
68
- return declared === PUBLIC_EGRESS ? (rules ?? []) : declared
69
- }
70
-
71
- function isOrigins(egress: SiteEgress): egress is readonly string[] {
72
- return Array.isArray(egress)
73
- }
74
-
75
- /**
76
- * The rules of public egress in one environment: the hosts its framework variables name (IAM, Operations, its own
77
- * origin, the platform's receivers, the object store), the installation hosts Control hands it, and the resolver the
78
- * runtime adapter supplies.
79
- */
80
- export function publicEgressRules(framework: Readonly<Record<string, string>>, resolve: HostResolver | null): PublicEgressRules {
81
- const hosts = new Set<string>()
82
- for (const [name, value] of Object.entries(framework)) {
83
- if (name === FABRIKA_EGRESS_REFUSED_HOSTS) {
84
- for (const host of value.split(',')) {
85
- const normalized = normalizedHost(host.trim())
86
- if (normalized !== '') hosts.add(normalized)
87
- }
88
- continue
89
- }
90
- const host = urlHost(value)
91
- if (host !== null) hosts.add(host)
92
- }
93
- return { refusedHosts: hosts, resolve }
94
- }
95
-
96
- /** The host of a framework variable's value when it is an http(s) URL, such as an origin or a DSN; `null` otherwise. */
97
- function urlHost(value: string): string | null {
98
- const text = value.trim()
99
- if (!/^https?:\/\//i.test(text)) return null
100
- try {
101
- return normalizedHost(new URL(text).hostname)
102
- } catch {
103
- return null
104
- }
19
+ export function runAsSite<T>(site: string, egress: readonly string[], work: () => Promise<T>): Promise<T> {
20
+ return scope.run({ site, origins: new Set(egress) }, work)
105
21
  }
106
22
 
107
23
  /**
@@ -125,8 +41,6 @@ export function platformCall<T>(work: () => T): T {
125
41
  return scope.exit(work)
126
42
  }
127
43
 
128
- type Fetch = (input: string, init: RequestInit) => Promise<Response>
129
-
130
44
  /**
131
45
  * Wraps the global `fetch` in the guard, once: a `fetch` that is already a guard stays. A test that replaces `fetch`
132
46
  * after boot replaces the guard with it.
@@ -136,20 +50,15 @@ export function installEgressGuard(): void {
136
50
  if (guards.has(current)) {
137
51
  return
138
52
  }
139
- const send: Fetch = (input, init) => current(input, init)
140
53
  const guarded = Object.assign(
141
54
  (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
142
55
  const running = scope.getStore()
143
56
  if (running === undefined) {
144
57
  return current(input, init)
145
58
  }
146
- if (running.open !== null) {
147
- return publicFetch(send, running.site, running.open, input, init)
148
- }
149
59
  const origin = originOf(input)
150
60
  if (origin !== null && running.origins.has(origin)) {
151
- // Only the standard fields: a runtime's own (Bun's `unix`, `proxy`, `tls`) would send the request elsewhere.
152
- return current(input, standardInit(init))
61
+ return current(input, init)
153
62
  }
154
63
  return Promise.reject(
155
64
  new CapabilityRefusedError(
@@ -160,47 +69,12 @@ export function installEgressGuard(): void {
160
69
  ),
161
70
  )
162
71
  },
163
- {
164
- // Inside a site's scope a preconnect reaches only a declared origin; public egress, which cannot check a hop
165
- // before it connects, refuses every one.
166
- preconnect: (...args: Parameters<typeof current.preconnect>): void => {
167
- const running = scope.getStore()
168
- if (running !== undefined) {
169
- const origin = originOf(args[0])
170
- if (running.open !== null || origin === null || !running.origins.has(origin)) {
171
- throw new CapabilityRefusedError(
172
- running.open === null ? 'undeclared_egress' : 'refused_egress',
173
- `${running.site} preconnects to ${origin ?? 'a URL that is not absolute'}, which its egress does not reach`,
174
- )
175
- }
176
- }
177
- if (typeof current.preconnect === 'function') current.preconnect(...args)
178
- },
179
- },
72
+ { preconnect: current.preconnect },
180
73
  )
181
74
  guards.add(guarded)
182
75
  globalThis.fetch = guarded
183
76
  }
184
77
 
185
- /** `init` with the fields of the Fetch standard only. */
186
- function standardInit(init: RequestInit | undefined): RequestInit | undefined {
187
- if (init === undefined) return undefined
188
- return {
189
- ...(init.method === undefined ? {} : { method: init.method }),
190
- ...(init.headers === undefined ? {} : { headers: init.headers }),
191
- ...(init.body === undefined ? {} : { body: init.body }),
192
- ...(init.redirect === undefined ? {} : { redirect: init.redirect }),
193
- ...(init.signal === undefined ? {} : { signal: init.signal }),
194
- ...(init.keepalive === undefined ? {} : { keepalive: init.keepalive }),
195
- ...(init.integrity === undefined ? {} : { integrity: init.integrity }),
196
- ...(init.referrer === undefined ? {} : { referrer: init.referrer }),
197
- ...(init.referrerPolicy === undefined ? {} : { referrerPolicy: init.referrerPolicy }),
198
- ...(init.cache === undefined ? {} : { cache: init.cache }),
199
- ...(init.credentials === undefined ? {} : { credentials: init.credentials }),
200
- ...(init.mode === undefined ? {} : { mode: init.mode }),
201
- }
202
- }
203
-
204
78
  function originOf(input: string | URL | Request): string | null {
205
79
  try {
206
80
  return new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url).origin
@@ -208,236 +82,3 @@ function originOf(input: string | URL | Request): string | null {
208
82
  return null
209
83
  }
210
84
  }
211
-
212
- const REDIRECTS: ReadonlySet<number> = new Set([301, 302, 303, 307, 308])
213
- /** The headers a redirect that turns a request into a `GET` drops with its body (Fetch, "HTTP-redirect fetch"). */
214
- const BODY_HEADERS = ['content-type', 'content-length', 'content-encoding', 'content-language', 'content-location']
215
- /**
216
- * The request headers public egress never sends, on any hop: the Fetch standard's forbidden request headers (`Host`
217
- * among them, which would route a request for a public name to another site at the same address), the forwarding
218
- * headers a proxy trusts, and the platform's own `X-Fabrika-*`.
219
- */
220
- const FORBIDDEN_HEADERS = [
221
- 'accept-charset',
222
- 'accept-encoding',
223
- 'access-control-request-headers',
224
- 'access-control-request-method',
225
- 'connection',
226
- 'content-length',
227
- 'cookie2',
228
- 'date',
229
- 'dnt',
230
- 'expect',
231
- 'forwarded',
232
- 'host',
233
- 'keep-alive',
234
- 'origin',
235
- 'referer',
236
- 'set-cookie',
237
- 'te',
238
- 'trailer',
239
- 'transfer-encoding',
240
- 'upgrade',
241
- 'via',
242
- 'x-http-method',
243
- 'x-http-method-override',
244
- 'x-method-override',
245
- 'x-real-ip',
246
- ]
247
- const FORBIDDEN_HEADER_PREFIXES = ['proxy-', 'sec-', 'x-forwarded-', 'x-fabrika-']
248
-
249
- function withoutForbiddenHeaders(headers: Headers): Headers {
250
- for (const name of [...headers.keys()]) {
251
- if (FORBIDDEN_HEADERS.includes(name) || FORBIDDEN_HEADER_PREFIXES.some((prefix) => name.startsWith(prefix))) {
252
- headers.delete(name)
253
- }
254
- }
255
- return headers
256
- }
257
-
258
- /** The credentials a redirect to another origin drops. */
259
- const CREDENTIAL_HEADERS = ['authorization', 'proxy-authorization', 'cookie']
260
-
261
- /**
262
- * One request under public egress. Every hop is sent with `redirect: 'manual'`, so the runtime follows no redirect the
263
- * guard has not checked: the caller's `follow` is done here, at most `maxRedirects` hops, each host checked again;
264
- * `manual` hands the caller the redirect, whose next `fetch` passes the guard again; `error` refuses one. The request
265
- * is bounded in time and its answer's body in size.
266
- */
267
- async function publicFetch(
268
- send: Fetch,
269
- site: string,
270
- rules: PublicEgressRules,
271
- input: string | URL | Request,
272
- init?: RequestInit,
273
- ): Promise<Response> {
274
- const request = new Request(input, init)
275
- // A timer the guard clears once the body is read, not `AbortSignal.timeout`: on workerd an uncleared timer keeps the
276
- // Durable Object awake until it fires.
277
- const deadline = new AbortController()
278
- const timer = setTimeout(() => deadline.abort(new DOMException('public egress request timed out', 'TimeoutError')), PUBLIC_EGRESS_LIMITS.timeoutMs)
279
- const done = (): void => clearTimeout(timer)
280
- try {
281
- return await follow(send, site, rules, request, AbortSignal.any([request.signal, deadline.signal]), done)
282
- } catch (error) {
283
- done()
284
- throw error
285
- }
286
- }
287
-
288
- /** The hops of one request; `done` clears its deadline once its last answer's body is read. */
289
- async function follow(
290
- send: Fetch,
291
- site: string,
292
- rules: PublicEgressRules,
293
- request: Request,
294
- signal: AbortSignal,
295
- done: () => void,
296
- ): Promise<Response> {
297
- const mode = request.redirect
298
- let url = new URL(request.url)
299
- let method = request.method
300
- const headers = withoutForbiddenHeaders(new Headers(request.headers))
301
- // Read once, so that a 307 or a 308 sends it again.
302
- let body: ArrayBuffer | null = request.body === null ? null : await untilAborted(signal, request.arrayBuffer())
303
- for (let hop = 0;; hop++) {
304
- await admit(site, rules, url, signal)
305
- const response = await send(url.href, { method, headers: new Headers(headers), body, redirect: 'manual', signal })
306
- const location = REDIRECTS.has(response.status) ? response.headers.get('location') : null
307
- if (location === null || mode === 'manual') {
308
- return await capped(site, response, url, hop > 0, signal, done)
309
- }
310
- await response.body?.cancel()
311
- if (mode === 'error') {
312
- throw new TypeError(`${site}: ${url.origin} redirects, and the request's redirect mode is 'error'`)
313
- }
314
- if (hop >= PUBLIC_EGRESS_LIMITS.maxRedirects) {
315
- throw new TypeError(`${site}: more than ${PUBLIC_EGRESS_LIMITS.maxRedirects} redirects, the last from ${url.origin}`)
316
- }
317
- const next = new URL(location, url)
318
- const toGet = (response.status === 303 && method !== 'GET' && method !== 'HEAD')
319
- || ((response.status === 301 || response.status === 302) && method === 'POST')
320
- if (toGet) {
321
- method = 'GET'
322
- body = null
323
- for (const name of BODY_HEADERS) headers.delete(name)
324
- }
325
- if (next.origin !== url.origin) {
326
- for (const name of CREDENTIAL_HEADERS) headers.delete(name)
327
- }
328
- url = next
329
- }
330
- }
331
-
332
- /** Refuses a hop public egress does not reach: by the URL, by the installation's hosts, by what its name resolves to. */
333
- async function admit(site: string, rules: PublicEgressRules, url: URL, signal: AbortSignal): Promise<void> {
334
- const refusal = publicEgressRefusal(url, rules.refusedHosts)
335
- if (refusal !== null) {
336
- throw new CapabilityRefusedError('refused_egress', `${site} calls ${url.origin}, which public egress refuses: ${refusal}`)
337
- }
338
- const resolve = rules.resolve
339
- if (resolve === null) {
340
- return
341
- }
342
- const host = normalizedHost(url.hostname)
343
- const addresses = await untilAborted(signal, platformCall(() => resolve(host)))
344
- const internal = addresses.find((address) => !isPublicAddress(address))
345
- if (addresses.length === 0 || internal !== undefined) {
346
- throw new CapabilityRefusedError(
347
- 'refused_egress',
348
- `${site} calls ${url.origin}, which public egress refuses: ${
349
- internal === undefined ? `${host} resolves to no address` : `${host} resolves to ${internal}, which is not a public address`
350
- }`,
351
- )
352
- }
353
- }
354
-
355
- /**
356
- * `response` with its body bounded by `maxResponseBytes`, and the URL and redirect flag of the request it answers,
357
- * which a response the guard builds would otherwise lose.
358
- */
359
- async function capped(
360
- site: string,
361
- response: Response,
362
- url: URL,
363
- redirected: boolean,
364
- signal: AbortSignal,
365
- done: () => void,
366
- ): Promise<Response> {
367
- const max = PUBLIC_EGRESS_LIMITS.maxResponseBytes
368
- const tooLarge = () =>
369
- new CapabilityRefusedError(
370
- 'oversized_egress',
371
- `${site}: ${url.origin} answers more than ${max} bytes, the most public egress reads of one response`,
372
- )
373
- const declared = Number(response.headers.get('content-length') ?? '0')
374
- if (Number.isFinite(declared) && declared > max) {
375
- await response.body?.cancel()
376
- throw tooLarge()
377
- }
378
- if (response.body === null || response.status < 200 || response.status > 599) {
379
- done()
380
- return withRequestUrl(response, url, redirected)
381
- }
382
- const reader = response.body.getReader()
383
- let seen = 0
384
- const bound = new ReadableStream<Uint8Array>({
385
- async pull(controller) {
386
- const read = await untilAborted(signal, reader.read()).catch(async (error: unknown) => {
387
- done()
388
- await reader.cancel(error).catch(() => undefined)
389
- throw error
390
- })
391
- if (read.done) {
392
- done()
393
- controller.close()
394
- return
395
- }
396
- seen += read.value.byteLength
397
- if (seen > max) {
398
- done()
399
- await reader.cancel()
400
- controller.error(tooLarge())
401
- return
402
- }
403
- controller.enqueue(read.value)
404
- },
405
- async cancel(reason) {
406
- done()
407
- await reader.cancel(reason)
408
- },
409
- })
410
- const answer = new Response(bound, {
411
- status: response.status,
412
- statusText: response.statusText,
413
- headers: response.headers,
414
- })
415
- return withRequestUrl(answer, url, redirected)
416
- }
417
-
418
- /**
419
- * `work`, or the signal's reason once it aborts, whichever comes first: a stage the runtime does not abort by the
420
- * signal (a resolver, a body read) still ends at the deadline. The work itself is left to settle unobserved.
421
- */
422
- async function untilAborted<T>(signal: AbortSignal, work: Promise<T>): Promise<T> {
423
- signal.throwIfAborted()
424
- let abort = (): void => {}
425
- const aborted = new Promise<never>((_resolve, reject) => {
426
- abort = () => reject(signal.reason)
427
- })
428
- signal.addEventListener('abort', abort, { once: true })
429
- try {
430
- return await Promise.race([work, aborted])
431
- } finally {
432
- signal.removeEventListener('abort', abort)
433
- }
434
- }
435
-
436
- function withRequestUrl(response: Response, url: URL, redirected: boolean): Response {
437
- try {
438
- Object.defineProperties(response, { url: { value: url.href }, redirected: { value: redirected } })
439
- } catch {
440
- // A runtime whose responses refuse own properties keeps its own `url`; the body bound holds either way.
441
- }
442
- return response
443
- }
@@ -3,6 +3,8 @@
3
3
  // framework's own refusals can put request data there. The event adds what was thrown as its cause chain, scrubbed of
4
4
  // the environment's secrets and of credential patterns, a framework failure's message replaced by its catalog text
5
5
  // (ADR-0059). A writing invocation that held its Durable Object's transaction too long is an event on the same budget.
6
+ // The author's own run (`fabrika app dev`, a test that passes `revealHandlerErrors`) also sees what was thrown, whole,
7
+ // beside the log line; no deployed application sets that sink.
6
8
 
7
9
  import { CAPABILITY_ERRORS, CapabilityError, QUERY_REFUSALS, QueryRefusedError } from '@fabrika/db/framework'
8
10
  import { isStructuralError } from '../errors'
@@ -18,6 +20,27 @@ export type RequestFailureCode =
18
20
  | 'handler_status'
19
21
  | 'handler_failed'
20
22
 
23
+ /**
24
+ * Where the author's own run shows what a request's 5xx or a job attempt threw, whole, with where it happened:
25
+ * `fabrika app dev` sets one, and a test may pass one to the kit. No deployed application has one.
26
+ */
27
+ export type HandlerErrorSink = (where: string, error: unknown) => void
28
+
29
+ /**
30
+ * Hands `error` to the author's sink, if there is one. A sink that throws (a test's `expect` inside it) changes nothing
31
+ * of the failure it was shown: the failure is classified, logged and reported as without it.
32
+ */
33
+ export function reveal(sink: HandlerErrorSink | null, where: string, error: unknown): void {
34
+ if (sink === null) {
35
+ return
36
+ }
37
+ try {
38
+ sink(where, error)
39
+ } catch {
40
+ console.error(`fabrika: revealHandlerErrors threw while it showed ${where}; the failure stands as it was`)
41
+ }
42
+ }
43
+
21
44
  /** At most this many request failures per process and minute become Operations events; every one is logged. */
22
45
  export const MAX_FAILURE_REPORTS_PER_MINUTE = 30
23
46
 
@@ -65,6 +88,8 @@ export function failureReason(error: unknown): FailureReason | null {
65
88
  export interface RequestFailure {
66
89
  /** The endpoint id the request selected, or `request` before one was selected. */
67
90
  readonly endpoint: string
91
+ /** Whether the request selected an endpoint, so `endpoint` is its id and not the fallback. */
92
+ readonly selected: boolean
68
93
  /** The proxy's `X-Request-Id`. */
69
94
  readonly requestId: string | null
70
95
  readonly status: number
@@ -94,14 +119,24 @@ export class MinuteBudget {
94
119
  }
95
120
  }
96
121
 
122
+ export interface FailureReportsOptions {
123
+ readonly now?: () => number
124
+ readonly reveal?: HandlerErrorSink | null
125
+ }
126
+
97
127
  export class FailureReports {
98
128
  readonly #reporter: OperationsReporter | null
99
129
  readonly #budget: MinuteBudget
130
+ readonly #reveal: HandlerErrorSink | null
100
131
 
101
- /** `reporter` is `null` without an Operations DSN: the log line is then the only record. */
102
- constructor(reporter: OperationsReporter | null, now: () => number = Date.now) {
132
+ /**
133
+ * `reporter` is `null` without an Operations DSN: the log line is then the only record. `reveal` is `boot`'s
134
+ * `revealHandlerErrors`, set on the author's own run only; `now` is the budget's clock.
135
+ */
136
+ constructor(reporter: OperationsReporter | null, options: FailureReportsOptions = {}) {
103
137
  this.#reporter = reporter
104
- this.#budget = new MinuteBudget(MAX_FAILURE_REPORTS_PER_MINUTE, now)
138
+ this.#budget = new MinuteBudget(MAX_FAILURE_REPORTS_PER_MINUTE, options.now ?? Date.now)
139
+ this.#reveal = options.reveal ?? null
105
140
  }
106
141
 
107
142
  /** Never rejects. The returned delivery may outlive the response; a runtime with `waitUntil` keeps it alive. */
@@ -109,6 +144,10 @@ export class FailureReports {
109
144
  const code = failureCode(failure.error)
110
145
  const why = failureReason(failure.error)
111
146
  console.error(`fabrika: ${failure.endpoint}: ${code}${why === null ? '' : `: ${why.reason}: ${why.text}`}`)
147
+ if (this.#reveal !== null) {
148
+ // What the line withholds (a refusal's message names the place: a column, a line of ctx.sql) on the author's own run.
149
+ reveal(this.#reveal, failure.selected ? `endpoint '${failure.endpoint}'` : 'a request', failure.error)
150
+ }
112
151
  if (this.#reporter === null || !this.#budget.admit()) {
113
152
  return Promise.resolve()
114
153
  }
@@ -43,7 +43,10 @@ export const SERVER_FAULTS = {
43
43
 
44
44
  export type ServerFaultReason = keyof typeof SERVER_FAULTS
45
45
 
46
- /** A failure the framework itself describes. Its message is for the author's own run, never the response or a log. */
46
+ /**
47
+ * A failure the framework itself describes. Its message is for the author's own run (`revealHandlerErrors`), never the
48
+ * response or a log.
49
+ */
47
50
  export class ServerFault extends Error {
48
51
  override readonly name = 'ServerFault'
49
52
  readonly reason: ServerFaultReason
@@ -3,7 +3,7 @@
3
3
  // commits it after the handler returned and its output passed validation, and rolls it back otherwise. Every handle
4
4
  // is bound to the invocation: called from another request, another `boot`, or after it ended, it refuses.
5
5
 
6
- import { type ContractArtifact, type DeclaredEgress, JOB_MAILERS, type JobMailer, PUBLIC_EGRESS } from '@fabrika/auth-core'
6
+ import { type ContractArtifact, JOB_MAILERS, type JobMailer } from '@fabrika/auth-core'
7
7
  import {
8
8
  type DataAccess,
9
9
  type DataHandles,
@@ -35,8 +35,8 @@ export interface SiteDeclaration {
35
35
  readonly binds: string | null
36
36
  /** The token purposes `ctx.tokens.sign` may sign. */
37
37
  readonly signs: readonly string[]
38
- /** The HTTPS origins the global `fetch` reaches while the site's handler runs, or `'public'`: every public host (a cron job). */
39
- readonly egress: DeclaredEgress
38
+ /** The HTTPS origins the global `fetch` reaches while the site's handler runs. */
39
+ readonly egress: readonly string[]
40
40
  }
41
41
 
42
42
  /** A public procedure's reach: the texts the verified signed tokens of its request carry, which name the rows it changes. */
@@ -167,11 +167,10 @@ export function parseDeclaration(where: string, declared: unknown, kind: DataKin
167
167
  problems.push(`${where}: signs is not a list of token purposes`)
168
168
  }
169
169
  const egressField = ownField(declared, 'egress')
170
- const origins = Array.isArray(egressField) ? egressField.filter((origin): origin is string => typeof origin === 'string') : []
171
- if (egressField !== undefined && egressField !== PUBLIC_EGRESS && (!Array.isArray(egressField) || origins.length !== egressField.length)) {
172
- problems.push(`${where}: egress is not a list of origins or '${PUBLIC_EGRESS}'`)
170
+ const egress = Array.isArray(egressField) ? egressField.filter((origin): origin is string => typeof origin === 'string') : []
171
+ if (egressField !== undefined && (!Array.isArray(egressField) || egress.length !== egressField.length)) {
172
+ problems.push(`${where}: egress is not a list of origins`)
173
173
  }
174
- const egress: DeclaredEgress = egressField === PUBLIC_EGRESS ? PUBLIC_EGRESS : Object.freeze([...new Set(origins)].sort())
175
174
  return Object.freeze({
176
175
  sql: sql === 'read' || sql === 'write' ? sql : null,
177
176
  unscoped: Object.freeze(unscoped),
@@ -181,7 +180,7 @@ export function parseDeclaration(where: string, declared: unknown, kind: DataKin
181
180
  kicks: Object.freeze([...new Set(kicks)].sort()),
182
181
  binds: typeof binds === 'string' ? binds : null,
183
182
  signs: Object.freeze([...new Set(signs)].sort()),
184
- egress,
183
+ egress: Object.freeze([...new Set(egress)].sort()),
185
184
  })
186
185
  }
187
186
 
@@ -226,7 +225,7 @@ export function approvedReach(site: string, artifact: ContractArtifact): SiteDec
226
225
  kicks: Object.freeze([...(reach.kicks ?? [])]),
227
226
  binds: reach.binds ?? null,
228
227
  signs: Object.freeze([...(reach.signs ?? [])]),
229
- egress: reach.egress === PUBLIC_EGRESS ? PUBLIC_EGRESS : Object.freeze([...(reach.egress ?? [])]),
228
+ egress: Object.freeze([...(reach.egress ?? [])]),
230
229
  })
231
230
  }
232
231
 
@@ -245,7 +244,7 @@ function describeDeclaration(declaration: SiteDeclaration): string {
245
244
  ...(declaration.kicks.length === 0 ? {} : { kicks: declaration.kicks }),
246
245
  ...(declaration.binds === null ? {} : { binds: declaration.binds }),
247
246
  ...(declaration.signs.length === 0 ? {} : { signs: declaration.signs }),
248
- ...(declaration.egress !== PUBLIC_EGRESS && declaration.egress.length === 0 ? {} : { egress: declaration.egress }),
247
+ ...(declaration.egress.length === 0 ? {} : { egress: declaration.egress }),
249
248
  })
250
249
  }
251
250
 
@@ -417,7 +416,8 @@ export function boundWebhookApp(webhook: string): (action: string) => never {
417
416
 
418
417
  /**
419
418
  * The handles of a job attempt, outside its fenced transaction (`'job'`, each read on its own) or inside it. `tickMs`,
420
- * the job's schedule period, is a queue claim's first backoff.
419
+ * the job's schedule period, is a queue claim's first backoff; `holds`, the actions the job holds, decide which file
420
+ * references of a claimed row it may open.
421
421
  */
422
422
  export function jobHandles(
423
423
  frame: RequestFrame,
@@ -429,6 +429,7 @@ export function jobHandles(
429
429
  ended: () => boolean,
430
430
  tickMs?: number,
431
431
  files?: FileBinding,
432
+ holds?: readonly string[],
432
433
  ): DataHandles {
433
434
  return data.handles({
434
435
  kind,
@@ -438,6 +439,7 @@ export function jobHandles(
438
439
  session,
439
440
  ...(tickMs === undefined ? {} : { tickMs }),
440
441
  ...(files === undefined ? {} : { files }),
442
+ ...(holds === undefined ? {} : { holds }),
441
443
  })
442
444
  }
443
445