@fabrika/app 0.9.0-cloudflare.1 → 0.9.0-cloudflare.3

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 (72) hide show
  1. package/package.json +9 -9
  2. package/skill/SKILL.md +21 -17
  3. package/skill/references/app-setup.md +42 -11
  4. package/skill/references/endpoint.md +29 -22
  5. package/skill/references/errors.md +32 -31
  6. package/skill/references/jobs.md +22 -3
  7. package/skill/references/tests.md +29 -1
  8. package/src/build.ts +6 -1
  9. package/src/bun.ts +168 -5
  10. package/src/cloudflare/application.ts +546 -76
  11. package/src/cloudflare/bindings.ts +26 -5
  12. package/src/cloudflare/export.ts +621 -0
  13. package/src/cloudflare/import.ts +1097 -0
  14. package/src/cloudflare/maintenance.ts +518 -0
  15. package/src/cloudflare/names.ts +6 -0
  16. package/src/cloudflare/ops.ts +147 -18
  17. package/src/cloudflare/restore.ts +167 -0
  18. package/src/cloudflare/tracker.ts +192 -0
  19. package/src/cloudflare.ts +3 -2
  20. package/src/contract/artifact-schema.ts +13 -2
  21. package/src/contract/build.ts +38 -11
  22. package/src/contract/context.ts +26 -9
  23. package/src/contract/defaults.ts +22 -2
  24. package/src/contract/define.ts +1 -1
  25. package/src/contract/group.ts +10 -1
  26. package/src/contract/kit.ts +2 -1
  27. package/src/disk-assets.ts +8 -3
  28. package/src/files/kinds.ts +54 -24
  29. package/src/implement/anonymous.ts +1 -10
  30. package/src/implement/boot.ts +30 -12
  31. package/src/implement/capability.ts +3 -0
  32. package/src/implement/dispatch.ts +175 -37
  33. package/src/implement/egress.ts +367 -8
  34. package/src/implement/invocation.ts +60 -19
  35. package/src/implement/workload.ts +18 -3
  36. package/src/jobs/runner.ts +646 -98
  37. package/src/spa-fallback.ts +12 -0
  38. package/src/testing/endpoint-access.ts +135 -23
  39. package/src/testing/isolation.ts +8 -1
  40. package/src/testing/kit.ts +60 -0
  41. package/types/src/build.d.ts +1 -1
  42. package/types/src/bun.d.ts +34 -1
  43. package/types/src/cloudflare/application.d.ts +36 -5
  44. package/types/src/cloudflare/bindings.d.ts +6 -0
  45. package/types/src/cloudflare/export.d.ts +16 -0
  46. package/types/src/cloudflare/import.d.ts +58 -0
  47. package/types/src/cloudflare/maintenance.d.ts +117 -0
  48. package/types/src/cloudflare/names.d.ts +5 -0
  49. package/types/src/cloudflare/ops.d.ts +39 -4
  50. package/types/src/cloudflare/restore.d.ts +9 -0
  51. package/types/src/cloudflare/tracker.d.ts +29 -0
  52. package/types/src/cloudflare.d.ts +2 -1
  53. package/types/src/contract/artifact-schema.d.ts +2 -0
  54. package/types/src/contract/context.d.ts +24 -9
  55. package/types/src/contract/defaults.d.ts +19 -1
  56. package/types/src/contract/define.d.ts +1 -1
  57. package/types/src/contract/group.d.ts +9 -1
  58. package/types/src/contract/kit.d.ts +2 -2
  59. package/types/src/disk-assets.d.ts +4 -1
  60. package/types/src/files/kinds.d.ts +17 -6
  61. package/types/src/implement/anonymous.d.ts +0 -4
  62. package/types/src/implement/boot.d.ts +17 -0
  63. package/types/src/implement/capability.d.ts +2 -0
  64. package/types/src/implement/dispatch.d.ts +33 -1
  65. package/types/src/implement/egress.d.ts +36 -1
  66. package/types/src/implement/invocation.d.ts +20 -10
  67. package/types/src/implement/workload.d.ts +5 -0
  68. package/types/src/jobs/runner.d.ts +63 -2
  69. package/types/src/spa-fallback.d.ts +2 -0
  70. package/types/src/testing/endpoint-access.d.ts +25 -1
  71. package/types/src/testing/isolation.d.ts +1 -1
  72. package/types/src/testing/kit.d.ts +16 -0
@@ -14,12 +14,14 @@ import {
14
14
  FILE_RESPONSE_KINDS,
15
15
  isOwnWorkloadName,
16
16
  JOB_MAILERS,
17
+ JOB_SITE_PREFIX,
17
18
  LOCALES,
18
19
  mailTemplateProblems,
19
20
  MAX_CACHE_AGE_SECONDS,
20
21
  type MessageKind,
21
22
  type NumberShape,
22
23
  type OutputShape,
24
+ PUBLIC_EGRESS,
23
25
  type RecordShape,
24
26
  type SchemaShape,
25
27
  type StringShape,
@@ -49,6 +51,12 @@ const record = <T extends z.core.$ZodType>(value: T) => z.record(z.string().min(
49
51
  /** A contract's actions are exact: IAM treats `*` as a pattern, which would widen every grant naming it. */
50
52
  const action = name.refine((value) => !value.includes('*'), 'an action is exact; * is not an action')
51
53
  const actions = z.array(action)
54
+ /** A file's object key starts with its kind: the framework keeps its own objects in the files bucket under this prefix. */
55
+ export const RESERVED_FILE_KIND_PREFIX = '__fabrika'
56
+ const fileKindName = name.refine(
57
+ (kind) => !kind.startsWith(RESERVED_FILE_KIND_PREFIX),
58
+ `a file kind name the framework reserves (${RESERVED_FILE_KIND_PREFIX}*)`,
59
+ )
52
60
  /** IAM's own role keys win over an application role of the same key at resolution. */
53
61
  const roleKey = name.refine((key) => !BUILTIN_ROLE_KEYS.includes(key), 'a built-in IAM role key is not a contract role name')
54
62
 
@@ -357,7 +365,7 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
357
365
  link: z.union([z.boolean(), z.array(name).nonempty()]),
358
366
  scan: z.literal(true).optional(),
359
367
  })),
360
- fileKinds: z.record(name, z.strictObject({ types: names, maxBytes: z.int().positive(), scan: z.literal(true).optional() })).optional(),
368
+ fileKinds: z.record(fileKindName, z.strictObject({ types: names, maxBytes: z.int().positive(), scan: z.literal(true).optional() })).optional(),
361
369
  jobs: record(z.strictObject({
362
370
  schedule: name,
363
371
  actions,
@@ -411,9 +419,12 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
411
419
  kicks: z.array(name).nonempty().optional(),
412
420
  binds: name.optional(),
413
421
  signs: z.array(name).nonempty().optional(),
414
- egress: z.array(z.string().refine((origin) => isPolicyOrigin(origin))).nonempty().optional(),
422
+ egress: z.union([z.array(z.string().refine((origin) => isPolicyOrigin(origin))).nonempty(), z.literal(PUBLIC_EGRESS)]).optional(),
415
423
  })).superRefine((declared, context) => {
416
424
  for (const [site, reach] of Object.entries(declared)) {
425
+ if (reach.egress === PUBLIC_EGRESS && !site.startsWith(JOB_SITE_PREFIX)) {
426
+ context.addIssue({ code: 'custom', path: [site, 'egress'], message: "egress: 'public' belongs to a cron job, keyed by job:<name>" })
427
+ }
417
428
  if (reach.actions !== undefined && !isOwnWorkloadName('public', site)) {
418
429
  context.addIssue({ code: 'custom', path: [site, 'actions'], message: 'workload actions belong to a public procedure, keyed by its endpoint id' })
419
430
  }
@@ -18,6 +18,7 @@ import {
18
18
  type ContractArtifact,
19
19
  type CspExtensions,
20
20
  type CspSource,
21
+ type DeclaredEgress,
21
22
  type DeclaredReach,
22
23
  type DimensionArtifact,
23
24
  directoryReach,
@@ -52,6 +53,7 @@ import {
52
53
  planEndpoint,
53
54
  type ProcedureArtifact,
54
55
  type ProcedureChallenge,
56
+ PUBLIC_EGRESS,
55
57
  type RoleArtifact,
56
58
  type SchemaShape,
57
59
  type ScopeBinding,
@@ -65,7 +67,7 @@ import {
65
67
  import { isPolicyOrigin, MAX_CSP_ORIGINS, WORKER_BLOB_SOURCE } from '@fabrika/proxy-core/headers'
66
68
  import { z } from 'zod/v4'
67
69
  import { CONTRACT_APP_ID_PATTERN as APP_ID } from './app-id'
68
- import { contractArtifactSchema } from './artifact-schema'
70
+ import { contractArtifactSchema, RESERVED_FILE_KIND_PREFIX } from './artifact-schema'
69
71
  import {
70
72
  type AccessDeclaration,
71
73
  type Builder,
@@ -147,7 +149,7 @@ const FRAMEWORK_TABLE_PREFIX = 'fabrika_'
147
149
  /** The most origins one site calls: a site that reaches more is an integration hub, which a connector import serves. */
148
150
  const MAX_EGRESS_ORIGINS = 16
149
151
  const DECLARED_ALLOWED =
150
- "sql: 'read' | 'write', unscoped: { <table>: 'read' | 'write' }, connect: ['<import>'], issues: '<link mount>', mailer: 'installation' | 'own', kicks: ['<cron job>'], binds: '<webhook>', signs: ['<token purpose>'], egress: ['https://<host>']"
152
+ "sql: 'read' | 'write', unscoped: { <table>: 'read' | 'write' }, connect: ['<import>'], issues: '<link mount>', mailer: 'installation' | 'own', kicks: ['<cron job>'], binds: '<webhook>', signs: ['<token purpose>'], egress: ['https://<host>'] | 'public' (a cron job)"
151
153
  const CSP_FIELDS = ['connectSrc', 'imgSrc', 'frameAncestors', 'scriptSrc', 'frameSrc', 'styleSrc', 'fontSrc']
152
154
  /** An environment variable an application reads; a challenge names its secret by one. */
153
155
  const APPLICATION_VARIABLE = /^[A-Z][A-Z0-9_]*$/
@@ -1712,6 +1714,10 @@ class ArtifactBuilder {
1712
1714
  const kinds: Record<string, FileKindArtifact> = {}
1713
1715
  for (const [name, declared] of Object.entries(this.#contract.files)) {
1714
1716
  const where = `files '${name}'`
1717
+ if (name.startsWith(RESERVED_FILE_KIND_PREFIX)) {
1718
+ this.#problem(where, `is a file kind name the framework reserves (${RESERVED_FILE_KIND_PREFIX}*)`)
1719
+ continue
1720
+ }
1715
1721
  if (!this.#name(where, name) || !this.#kind(where, declared, 'file-kind', 'c.files({ types, maxBytes, scan? })')) {
1716
1722
  continue
1717
1723
  }
@@ -2106,7 +2112,7 @@ class ArtifactBuilder {
2106
2112
  ...(kicks.length === 0 ? {} : { kicks }),
2107
2113
  ...(binds === undefined ? {} : { binds }),
2108
2114
  ...(signs.length === 0 ? {} : { signs }),
2109
- ...(egress.length === 0 ? {} : { egress }),
2115
+ ...(egress === null ? {} : { egress }),
2110
2116
  }
2111
2117
  if (place.kind !== 'rpc') {
2112
2118
  this.#rpcOnly(where, 'connect', value['connect'])
@@ -2305,12 +2311,13 @@ class ArtifactBuilder {
2305
2311
 
2306
2312
  /**
2307
2313
  * The HTTPS origins a site's code calls: a credentialed procedure of an RPC mount, a webhook or a job, never a public,
2308
- * export or link procedure. Each is an exact origin with no path or wildcard, once; `[]` when it declares none or after
2309
- * a problem.
2314
+ * export or link procedure. Each is an exact origin with no path or wildcard, once. Or `'public'`, every public host
2315
+ * (ADR-0071), which only a cron job declares: it calls outside any transaction, and its schedule, not a caller,
2316
+ * decides when. `null` when it declares none or after a problem.
2310
2317
  */
2311
- #egress(where: string, value: unknown, place: DeclaringSite): string[] {
2318
+ #egress(where: string, value: unknown, place: DeclaringSite): DeclaredEgress | null {
2312
2319
  if (value === undefined) {
2313
- return []
2320
+ return null
2314
2321
  }
2315
2322
  const refusedBy = place.kind === 'export'
2316
2323
  ? 'an export procedure'
@@ -2321,15 +2328,35 @@ class ArtifactBuilder {
2321
2328
  : null
2322
2329
  if (refusedBy !== null) {
2323
2330
  this.#problem(where, `declares egress, which ${refusedBy} never does: a credentialed procedure, a webhook or a job calls out`)
2324
- return []
2331
+ return null
2332
+ }
2333
+ if (value === PUBLIC_EGRESS) {
2334
+ if (place.kind !== 'job') {
2335
+ this.#problem(
2336
+ where,
2337
+ `declares egress: '${PUBLIC_EGRESS}', which only a cron job declares: a procedure or a webhook names its origins (allowed: egress: ['https://api.example.com'])`,
2338
+ )
2339
+ return null
2340
+ }
2341
+ return PUBLIC_EGRESS
2325
2342
  }
2326
2343
  if (!Array.isArray(value) || value.length === 0 || !value.every((origin) => typeof origin === 'string')) {
2327
- this.#problem(where, "egress is not a list of origins (allowed: egress: ['https://api.example.com'])")
2328
- return []
2344
+ this.#problem(
2345
+ where,
2346
+ place.kind === 'job'
2347
+ ? "egress is not a list of origins or 'public' (allowed: egress: ['https://api.example.com'] or egress: 'public')"
2348
+ : "egress is not a list of origins (allowed: egress: ['https://api.example.com'])",
2349
+ )
2350
+ return null
2329
2351
  }
2330
2352
  const origins: string[] = value.filter((origin) => typeof origin === 'string')
2331
2353
  if (origins.length > MAX_EGRESS_ORIGINS) {
2332
- this.#problem(where, `${origins.length} egress origins exceed the limit of ${MAX_EGRESS_ORIGINS}`)
2354
+ this.#problem(
2355
+ where,
2356
+ `${origins.length} egress origins exceed the limit of ${MAX_EGRESS_ORIGINS}${
2357
+ place.kind === 'job' ? " (a cron job that calls the websites its operators name declares egress: 'public')" : ''
2358
+ }`,
2359
+ )
2333
2360
  }
2334
2361
  for (const origin of origins) {
2335
2362
  if (!isPolicyOrigin(origin)) {
@@ -118,20 +118,31 @@ export type SqlValue = string | number | boolean | bigint | Date | null | readon
118
118
  export interface SqlTag<Ix extends AnyDbIndex = AnyDbIndex, M extends SqlMode = SqlMode> {
119
119
  <Row extends Schema>(row: Row): (text: TemplateStringsArray, ...values: readonly (SqlValue | SqlScope)[]) => Promise<z.output<Row>[]>
120
120
  /**
121
- * The capability's whole predicate on `table` (`alias` its name in the statement, the table's by default): the
122
- * object's key and every link of its chain for a `Ref`, what `ctx.db.within` matches for a `Within`, every row for
123
- * `ctx.app`. Interpolated as `where ${ctx.sql.scope(ctx.target, 'tasks', 't')}`, its values are bound parameters.
124
- * A table the capability reaches for no use of this site is a type error here; at run time the fragment on the
125
- * statement's UPDATE or DELETE target needs that operation's action, and anywhere else an action the table reads
126
- * with.
121
+ * The capability's whole predicate on `table`: the object's key and every link of its chain for a `Ref`, what
122
+ * `ctx.db.within` matches for a `Within`, every row for `ctx.app`. Interpolated as
123
+ * `where ${ctx.sql.scope(ctx.target, 'tasks', { alias: 't' })}`, its values are bound parameters. `alias` is the
124
+ * table's name in the statement (the table's own by default). `use` states what the statement does with the table:
125
+ * `'read'` (the default) needs an action the table reads with, `'update'` or `'delete'` (a `'write'` site only) that
126
+ * operation's action, checked when the fragment is built. The statement is not read for where the fragment stands:
127
+ * using it as stated is the author's and the approver's to check. A table the capability reaches for no use of this
128
+ * site is a type error here.
127
129
  */
128
130
  scope<C extends Ref<string, string> | Within<string, string> | AppCapability<string>, T extends FragmentTable<Ix, C, M>>(
129
131
  capability: C,
130
132
  table: T,
131
- alias?: string,
133
+ options?: SqlScopeOptions,
132
134
  ): SqlScope
133
135
  }
134
136
 
137
+ /**
138
+ * The third argument of `ctx.sql.scope`: the table's alias in the statement, and what the statement does with it. A
139
+ * `'read'` site's `ctx.sql` is refused `'update'` and `'delete'` at run time; a `'write'` site's stays assignable to it.
140
+ */
141
+ export interface SqlScopeOptions {
142
+ readonly alias?: string
143
+ readonly use?: 'read' | 'update' | 'delete'
144
+ }
145
+
135
146
  declare const sqlScope: unique symbol
136
147
 
137
148
  /** What `ctx.sql.scope(…)` builds: only the framework makes one, and only its own tag takes it. */
@@ -420,13 +431,19 @@ export type PublicContext<K extends KitTypes, Kind extends DataKind, Acts extend
420
431
 
421
432
  /**
422
433
  * `ctx.kick('<job>')` of a site that declares `kicks`: the job runs in the background after the site's transaction
423
- * committed, once however often it is kicked, and not at all on a rollback.
434
+ * committed, once however often it is kicked, and not at all on a rollback. `ctx.kick('<job>', { at })` runs it at `at`
435
+ * instead. Either way the kick is a durable wake written in the site's transaction, and it carries nothing.
424
436
  */
425
437
  export type KickContext<Ks> = [Ks] extends [never]
426
438
  ? { readonly kick: Unavailable<"declare kicks: ['<cron job>'] on this site to kick a job after its commit"> }
427
- : Ks extends readonly (infer N extends string)[] ? { kick(job: N): void }
439
+ : Ks extends readonly (infer N extends string)[] ? { kick(job: N, options?: KickOptions): void }
428
440
  : never
429
441
 
442
+ /** When a kicked job runs: at `at`, a `Date`; without options, as soon as the site committed. */
443
+ export interface KickOptions {
444
+ readonly at: Date
445
+ }
446
+
430
447
  /** `ctx.tokens.sign('<purpose>', claims, { days })` of a site that declares `signs`: a token of one of those purposes. */
431
448
  export type TokensContext<K extends KitTypes, Sg> = [Sg] extends [never]
432
449
  ? { readonly tokens: Unavailable<"declare signs: ['<token purpose>'] on this site to sign its tokens"> }
@@ -29,6 +29,17 @@ export const PROCEDURE_LIMITS = {
29
29
  maxPartHeaderBytes: 8 * 1024,
30
30
  } as const
31
31
 
32
+ /**
33
+ * The slowest body a procedure or a webhook waits for: its deadline is `maxBytes` at `bytesPerSecond`, `minMs` at least.
34
+ * The handler's own `timeoutMs` starts after the last byte, so the approval diff names both.
35
+ */
36
+ export const BODY_DEADLINE = { bytesPerSecond: 16 * 1024, minMs: 30_000 } as const
37
+
38
+ /** How long a body of at most `maxBytes` may take to arrive. */
39
+ export function bodyDeadlineMs(maxBytes: number): number {
40
+ return Math.max(BODY_DEADLINE.minMs, Math.ceil((maxBytes / BODY_DEADLINE.bytesPerSecond) * 1000))
41
+ }
42
+
32
43
  /**
33
44
  * A procedure with file fields is `multipart/form-data`: its JSON input travels in the first part, named `input`, and
34
45
  * each file in a part named after its field. A field of several files sends one part per file, under its name.
@@ -46,9 +57,18 @@ export const WEBHOOK_LIMITS = {
46
57
  timeoutMs: PROCEDURE_LIMITS.timeoutMs,
47
58
  } as const
48
59
 
49
- /** A job attempt's time limit (`limits.timeoutMs`) and its ceiling, which keeps a lease and a timer within a day. */
60
+ /**
61
+ * The longest job segment on Cloudflare: setup, one attempt and its finish. A framework policy inside the 15 minutes
62
+ * `waitUntil` keeps an object alive, not a platform guarantee; longer work chunks through claims.
63
+ */
64
+ export const CLOUDFLARE_MAX_JOB_SEGMENT_MS = 14 * 60_000
65
+
66
+ /**
67
+ * A job attempt's time limit (`limits.timeoutMs`) and its ceiling, which keeps a lease and a timer within a day. The
68
+ * default is one Cloudflare segment, so a job that declares no limit deploys on either provider.
69
+ */
50
70
  export const JOB_LIMITS = {
51
- timeoutMs: 15 * 60_000,
71
+ timeoutMs: CLOUDFLARE_MAX_JOB_SEGMENT_MS,
52
72
  maxTimeoutMs: 24 * 60 * 60_000,
53
73
  } as const
54
74
 
@@ -31,7 +31,7 @@ export function isPath(value: string): value is Path {
31
31
  return value.startsWith('/')
32
32
  }
33
33
 
34
- /** A job attempt's time limit: 15 minutes by default, at most a day. A job reads no body, so it has no `maxBytes`. */
34
+ /** A job attempt's time limit: 14 minutes by default, at most a day. A job reads no body, so it has no `maxBytes`. */
35
35
  export interface JobLimitsOption {
36
36
  readonly timeoutMs?: number
37
37
  }
@@ -115,7 +115,16 @@ export type SignsField<Sg, Purposes extends string> =
115
115
  * `fetch` refuses any other while the site runs; a public procedure declares none.
116
116
  */
117
117
  export interface EgressField {
118
- readonly egress?: readonly `https://${string}`[]
118
+ readonly egress?: readonly `https://${string}`[] | Unavailable<"egress: 'public' is a cron job's only: record a row and kick a job that declares it">
119
+ }
120
+
121
+ /**
122
+ * A cron job's `egress`: its exact HTTPS origins, or `'public'`, every public host over HTTPS or HTTP on its default
123
+ * port, for a job that calls the websites its operators name (ADR-0071). The guard refuses IP addresses, local and
124
+ * internal names and the installation's own hosts, checks each redirect, and bounds each request's time and body.
125
+ */
126
+ export interface JobEgressField {
127
+ readonly egress?: readonly `https://${string}`[] | 'public'
119
128
  }
120
129
 
121
130
  /** Each purpose `signs` names is one of `defineApp`'s `tokens`. */
@@ -57,6 +57,7 @@ import type {
57
57
  GroupBuild,
58
58
  GroupInput,
59
59
  GroupKit,
60
+ JobEgressField,
60
61
  KicksField,
61
62
  LimitsOption,
62
63
  LinkGroupKit,
@@ -96,7 +97,7 @@ export type CronOptions<Acts, S, U, Is, Ix extends AnyDbIndex, M = never, Ks = n
96
97
  & MailerField<M>
97
98
  & KicksField<Ks>
98
99
  & SignsField<Sg, Purposes>
99
- & EgressField
100
+ & JobEgressField
100
101
 
101
102
  /** The mail transport a job reaches, inferred from its optional field and then required, like a declared field. */
102
103
  type MailerField<M> =
@@ -4,8 +4,12 @@
4
4
  import { rawRequestTarget } from '@fabrika/auth-core'
5
5
  import { join, resolve, sep } from 'node:path'
6
6
  import type { SpaAssets } from './implement/dispatch.js'
7
+ import { isPageRoute } from './spa-fallback.js'
7
8
 
8
- /** Serves each SPA mount from its build directory under `root`; a path that names no file gets the SPA's `index.html`. */
9
+ /**
10
+ * Serves each SPA mount from its build directory under `root`; a page route that names no file gets the SPA's
11
+ * `index.html` (`isPageRoute`), and a missing asset is 404.
12
+ */
9
13
  export function diskAssets(root: string): SpaAssets {
10
14
  return {
11
15
  async serve(mount, request) {
@@ -15,8 +19,9 @@ export function diskAssets(root: string): SpaAssets {
15
19
  // The path is canonical, so every segment decodes and none is `.` or `..`.
16
20
  const file = join(dir, ...relative.split('/').filter((segment) => segment !== '').map((segment) => decodeURIComponent(segment)))
17
21
  const candidate = file.startsWith(`${dir}${sep}`) ? Bun.file(file) : null
18
- const served = candidate !== null && (await candidate.exists()) ? candidate : Bun.file(join(dir, 'index.html'))
19
- if (!(await served.exists())) {
22
+ const found = candidate !== null && (await candidate.exists()) ? candidate : null
23
+ const served = found ?? (isPageRoute(request) ? Bun.file(join(dir, 'index.html')) : null)
24
+ if (served === null || !(await served.exists())) {
20
25
  return new Response('Not found', { status: 404 })
21
26
  }
22
27
  return new Response(served)
@@ -2,7 +2,8 @@
2
2
  // the table's policy is its authority. This module stages a file (an incoming part or a `ctx.files.put`): its pending
3
3
  // row first, on a connection of its own, then its object, sniffed and bounded by the kind. It serves and opens a file
4
4
  // only through a reference the work holds and may read, and only a live one, by its scanned version. The sweep
5
- // deletes the files no declared column references, and the scan job decides about the quarantined ones (`scan.ts`).
5
+ // deletes the files no declared column references, and their objects once past the runtime's retention window, and the
6
+ // scan job decides about the quarantined ones (`scan.ts`).
6
7
 
7
8
  import type { ContractArtifact, FileKindArtifact } from '@fabrika/auth-core'
8
9
  import {
@@ -17,6 +18,7 @@ import {
17
18
  type StoredFiles,
18
19
  } from '@fabrika/db/framework'
19
20
  import { type FileObjectStore, type StoredObject, uuidv7 } from '@fabrika/platform'
21
+ import { RESERVED_FILE_KIND_PREFIX } from '../contract/artifact-schema'
20
22
  import type { FileRef } from '../contract/file'
21
23
  import { HttpError, NotFoundError } from '../errors'
22
24
  import { CapabilityRefusedError } from '../implement/capability'
@@ -33,6 +35,11 @@ export { FILE_SWEEP_JOB, FILE_SWEEP_SCHEDULE } from './job-names'
33
35
  export const FILE_SWEEP_TIMEOUT_MS = 10 * 60_000
34
36
  /** How long a staged file waits for its first reference before the sweep may delete it. */
35
37
  export const FILE_PENDING_GRACE_MS = 60 * 60 * 1000
38
+ /**
39
+ * How long a removed file's object outlives its row on Cloudflare, so the rows of a restored backup still find their
40
+ * files: the 30 days backups are kept, which never exceeds this window.
41
+ */
42
+ export const FILE_TOMBSTONE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000
36
43
  /** How many files one sweep batch handles; the next batch, or the next run, takes the rest. */
37
44
  const SWEEP_BATCH = 20
38
45
 
@@ -96,12 +103,16 @@ export class StoredFileKinds {
96
103
  readonly #store: FileObjectStore
97
104
  readonly #files: StoredFiles
98
105
  readonly #columns: readonly FileColumnRef[]
106
+ readonly #retentionMs: number
107
+ /** Serializes each object deletion of the sweep with a cancel, so no deletion is in flight once a cancel resolves. */
108
+ #deletions: Promise<void> = Promise.resolve()
99
109
 
100
- constructor(kinds: readonly Kind[], store: FileObjectStore, files: StoredFiles, columns: readonly FileColumnRef[]) {
110
+ constructor(kinds: readonly Kind[], store: FileObjectStore, files: StoredFiles, columns: readonly FileColumnRef[], retentionMs: number) {
101
111
  this.#kinds = new Map(kinds.map((kind) => [kind.name, kind]))
102
112
  this.#store = store
103
113
  this.#files = files
104
114
  this.#columns = columns
115
+ this.#retentionMs = retentionMs
105
116
  }
106
117
 
107
118
  /** Whether the contract declares kind `name`. */
@@ -316,41 +327,54 @@ export class StoredFileKinds {
316
327
  return new FileDownload({ body: object.body, size: file.size, contentType: file.type, name: file.name })
317
328
  }
318
329
 
330
+ #serialized<T>(work: () => Promise<T>): Promise<T> {
331
+ const result = this.#deletions.then(work)
332
+ this.#deletions = result.then(() => undefined, () => undefined)
333
+ return result
334
+ }
335
+
336
+ /**
337
+ * Cancels the tombstones of `objectKeys`, so their objects stay: a restore cancels every key its restored rows
338
+ * reference. Once it resolves, no deletion of this sweep is in flight. Answers how many it cancelled.
339
+ */
340
+ cancelDeletions(objectKeys: readonly string[]): Promise<number> {
341
+ return this.#serialized(() => this.#files.cancelDeletions(objectKeys))
342
+ }
343
+
319
344
  /**
320
- * The sweep: it finishes deletions a crash interrupted, adopts the migrated files a declared column references, then
321
- * deletes, batch by batch, every file past the grace that no declared column references: its row and the record of
322
- * its object in one transaction (the foreign key keeps a referenced one), then the object, then the record.
345
+ * The sweep: it adopts the migrated files a declared column references, then removes, batch by batch, every file past
346
+ * the grace that no declared column references: its row and the record of its object in one transaction (the foreign
347
+ * key keeps a referenced one). Last it claims each recorded object past the retention window, then deletes it.
323
348
  */
324
349
  async sweep(signal: AbortSignal): Promise<void> {
325
350
  let step = 'rows_read_failed'
326
351
  try {
327
- for (let keys = await this.#files.unfinishedDeletions(SWEEP_BATCH); keys.length > 0 && !signal.aborted;) {
328
- for (const key of keys) {
329
- step = 'object_delete_failed'
330
- await this.#store.delete(key)
331
- step = 'deletion_record_failed'
332
- await this.#files.forgetDeletion(key)
333
- }
334
- step = 'rows_read_failed'
335
- keys = keys.length === SWEEP_BATCH ? await this.#files.unfinishedDeletions(SWEEP_BATCH) : []
336
- }
337
352
  await this.#files.adoptReferenced(this.#columns)
338
353
  for (let more = true; more && !signal.aborted;) {
339
354
  step = 'rows_read_failed'
340
355
  const batch = await this.#files.unreferenced(this.#columns, SWEEP_BATCH, FILE_PENDING_GRACE_MS)
341
356
  for (const id of batch) {
342
357
  step = 'row_delete_failed'
343
- const key = await this.#files.remove(id, FILE_PENDING_GRACE_MS)
344
- if (key === null) {
345
- continue
346
- }
347
- step = 'object_delete_failed'
348
- await this.#store.delete(key)
349
- step = 'deletion_record_failed'
350
- await this.#files.forgetDeletion(key)
358
+ await this.#files.remove(id, FILE_PENDING_GRACE_MS)
351
359
  }
352
360
  more = batch.length === SWEEP_BATCH
353
361
  }
362
+ const cutoff = new Date(Date.now() - this.#retentionMs)
363
+ for (let more = true; more && !signal.aborted;) {
364
+ step = 'rows_read_failed'
365
+ const keys = await this.#files.dueDeletions(SWEEP_BATCH, cutoff)
366
+ for (const key of keys) {
367
+ await this.#serialized(async () => {
368
+ step = 'deletion_claim_failed'
369
+ // A crash or a failed delete after the claim leaks this object's bytes; it loses no data.
370
+ if (await this.#files.claimDeletion(key, cutoff)) {
371
+ step = 'object_delete_failed'
372
+ await this.#store.delete(key)
373
+ }
374
+ })
375
+ }
376
+ more = keys.length === SWEEP_BATCH
377
+ }
354
378
  } catch {
355
379
  console.error(`fabrika: stored files sweep: ${step}`)
356
380
  throw new ServerFault('file_sweep_failed', 'the sweep of stored files failed; the next run retries it')
@@ -430,13 +454,15 @@ function fileColumns(artifact: ContractArtifact): FileColumnRef[] {
430
454
 
431
455
  /**
432
456
  * The file kinds of `artifact`, or `null` when it declares none. Every reason a kind cannot be served goes into
433
- * `problems`, so `boot` refuses to start rather than take a file it cannot check.
457
+ * `problems`, so `boot` refuses to start rather than take a file it cannot check. A removed file's object outlives its
458
+ * row by `retentionMs`.
434
459
  */
435
460
  export function storedFileKinds(
436
461
  artifact: ContractArtifact,
437
462
  database: ImplementationDatabase | null,
438
463
  store: FileObjectStore | undefined,
439
464
  problems: string[],
465
+ retentionMs: number,
440
466
  ): StoredFileKinds | null {
441
467
  const entries = Object.entries(artifact.fileKinds ?? {})
442
468
  if (entries.length === 0) {
@@ -450,6 +476,9 @@ export function storedFileKinds(
450
476
  return null
451
477
  }
452
478
  for (const [name, kind] of entries) {
479
+ if (name.startsWith(RESERVED_FILE_KIND_PREFIX)) {
480
+ problems.push(`files '${name}' is a file kind name the framework reserves (${RESERVED_FILE_KIND_PREFIX}*)`)
481
+ }
453
482
  for (const type of kind.types.filter((candidate) => !SNIFFABLE_TYPES.includes(candidate))) {
454
483
  problems.push(`files '${name}' admits '${type}', whose bytes the framework cannot verify (allowed: ${SNIFFABLE_TYPES.join(', ')})`)
455
484
  }
@@ -462,5 +491,6 @@ export function storedFileKinds(
462
491
  store,
463
492
  frameworkTablesOf(database).files,
464
493
  fileColumns(artifact),
494
+ retentionMs,
465
495
  )
466
496
  }
@@ -2,19 +2,10 @@
2
2
  // body, so the framework enforces it) and the share SPA's fragment bootstrap. A form's admission is
3
3
  // `form-admission.ts`, a webhook's signature `verifiers.ts`.
4
4
 
5
- import { LINK_BOOTSTRAP_FILE, SHARE_KEY_GLOBAL } from '../contract/defaults'
5
+ import { bodyDeadlineMs, LINK_BOOTSTRAP_FILE, SHARE_KEY_GLOBAL } from '../contract/defaults'
6
6
  import { HttpError } from '../errors'
7
7
  import { deadline, readBoundedBytes } from './bounded'
8
8
 
9
- /** The slowest body a procedure waits for, in bytes per second: its deadline is `maxBytes` at this rate, 30 s at least. */
10
- export const BODY_RATE_FLOOR = 16 * 1024
11
- const MIN_BODY_DEADLINE_MS = 30_000
12
-
13
- /** How long a body of at most `maxBytes` may take to arrive. */
14
- export function bodyDeadlineMs(maxBytes: number): number {
15
- return Math.max(MIN_BODY_DEADLINE_MS, Math.ceil((maxBytes / BODY_RATE_FLOOR) * 1000))
16
- }
17
-
18
9
  /**
19
10
  * The body as bytes, read until `maxBytes`; a longer one stops the read and is a 413. A body whose stream fails before
20
11
  * its end (the client closed the connection) is the sender's 400 `aborted`, never a failure of the application.
@@ -31,6 +31,7 @@ import {
31
31
  type FrameworkTables,
32
32
  frameworkTablesOf,
33
33
  isScopedDatabase,
34
+ type Session,
34
35
  } from '@fabrika/db/framework'
35
36
  import type { DataKind } from '@fabrika/db/tables'
36
37
  import type { EmailProviderRegistry } from '@fabrika/email'
@@ -65,7 +66,7 @@ import {
65
66
  type ServedSite,
66
67
  type SpaAssets,
67
68
  } from './dispatch'
68
- import { installEgressGuard, platformCall, platformFacility } from './egress'
69
+ import { type HostResolver, installEgressGuard, platformCall, platformFacility, publicEgressRules, type SiteEgress, siteEgress } from './egress'
69
70
  import type { CapturedEnvironment } from './environment'
70
71
  import { FailureReports } from './failures'
71
72
  import { applicationPolicy } from './headers'
@@ -99,6 +100,11 @@ export interface BootOptions {
99
100
  readonly requireProxySecret?: boolean
100
101
  /** The object storage of the stored files, which the Bun adapter opens. Without it, a contract with file kinds does not boot. */
101
102
  readonly files?: FileObjectStore
103
+ /**
104
+ * How long a removed file's object outlives its row, so a restored backup's rows find their files:
105
+ * `FILE_TOMBSTONE_RETENTION_MS` on Cloudflare. Zero when omitted, as on Bun.
106
+ */
107
+ readonly fileRetentionMs?: number
102
108
  /**
103
109
  * The malware scanner of the scan job of `scan: true` file kinds, which the Bun adapter supplies to a job run
104
110
  * (`clamscanScanner`). Without it the scan job leaves every quarantined file quarantined and reports.
@@ -124,6 +130,11 @@ export interface BootOptions {
124
130
  * with a job or a webhook does not boot.
125
131
  */
126
132
  readonly workloadTokens?: WorkloadTokenSource
133
+ /**
134
+ * Resolves a host name to its addresses, which the Bun adapter supplies (`node:dns`): a cron job's public egress then
135
+ * refuses a public name of a private address before each hop. A Worker exposes no resolution and passes none.
136
+ */
137
+ readonly resolveHost?: HostResolver
127
138
  /** What posts a report to Operations' ingest; `fetch` by default. */
128
139
  readonly operationsFetch?: (request: Request) => Promise<Response>
129
140
  /** What asks a public procedure's challenge provider to verify a token; `fetch` by default. */
@@ -163,6 +174,11 @@ export interface BootOptions {
163
174
  * then `null`.
164
175
  */
165
176
  readonly clientAddress?: 'vouched'
177
+ /**
178
+ * Runs in the transaction of every change of a job's wakes or lease (`DataLayerRuntime.projectWakes`): the Cloudflare
179
+ * object arms its alarm there. Bun supplies none.
180
+ */
181
+ readonly projectWakes?: (transaction: Session) => Promise<void>
166
182
  }
167
183
 
168
184
  /** The pool size a runtime adapter that names none is assumed to have: the Bun adapter's default. */
@@ -275,16 +291,11 @@ function readProxySecret(framework: Readonly<Record<string, string>>, required:
275
291
  return proxySecretDigest(secret)
276
292
  }
277
293
 
278
- /** What an application's SQLite database (a Durable Object's, ADR-0065) cannot serve: raw SQL and a scanning file kind. */
294
+ /** What an application's SQLite database (a Durable Object's, ADR-0065) cannot serve: a scanning file kind. */
279
295
  function sqliteProblems(artifact: ContractArtifact, database: Database | undefined, problems: string[]): void {
280
296
  if (database?.dialect !== 'sqlite') {
281
297
  return
282
298
  }
283
- for (const [site, reach] of Object.entries(artifact.declared ?? {})) {
284
- if (reach.sql !== null) {
285
- problems.push(`'${site}' declares sql: '${reach.sql}'; ctx.sql runs only on Postgres, and this application's database is SQLite (Cloudflare)`)
286
- }
287
- }
288
299
  for (const [name, kind] of Object.entries(artifact.fileKinds ?? {})) {
289
300
  if (kind.scan === true) {
290
301
  problems.push(`files '${name}' declares scan: true; no malware scanner runs on Cloudflare, so a scanning file kind is not served there`)
@@ -392,6 +403,7 @@ function contractDatabase(
392
403
  database: ImplementationDatabase | null,
393
404
  connection: Database | undefined,
394
405
  capabilities: CapabilityAuthority,
406
+ projectWakes: ((transaction: Session) => Promise<void>) | undefined,
395
407
  problems: string[],
396
408
  ): BoundDatabase | null {
397
409
  if (database === null) {
@@ -409,7 +421,12 @@ function contractDatabase(
409
421
  return null
410
422
  }
411
423
  try {
412
- const { locate, release } = bindScopedDatabaseProvisionally(database, { database: connection, capabilities, readOnly: requestIsReadOnly })
424
+ const { locate, release } = bindScopedDatabaseProvisionally(database, {
425
+ database: connection,
426
+ capabilities,
427
+ readOnly: requestIsReadOnly,
428
+ ...(projectWakes === undefined ? {} : { projectWakes }),
429
+ })
413
430
  return { database: { tables: database.tables, locate }, framework: frameworkTablesOf(database), data: dataAccessOf(database), release }
414
431
  } catch {
415
432
  problems.push('the data layer was bound before boot; only the framework binds it, so remove @fabrika/db/framework from the application')
@@ -460,8 +477,8 @@ function boundHandler(
460
477
  }
461
478
 
462
479
  /** The origins a staged-kit site's handler reaches, a kit without tables included; nothing for a bare handler. */
463
- function egressOf(bound: BoundHandler): { readonly egress?: readonly string[] } {
464
- return !bound.site || bound.declaration === null ? {} : { egress: bound.declaration.egress }
480
+ function egressOf(bound: BoundHandler): { readonly egress?: SiteEgress } {
481
+ return !bound.site || bound.declaration === null ? {} : { egress: siteEgress(bound.declaration.egress, null) }
465
482
  }
466
483
 
467
484
  /** A staged-kit contract's endpoint gets `ctx.links` only for the link mount it declares it `issues`. */
@@ -725,8 +742,8 @@ function bootOnce(app: ContractImplementation, options: BootOptions, binding: Bi
725
742
  sqliteProblems(artifact, options.database, problems)
726
743
  // This runtime's own: what another `boot` call mints, application code's included, its stores refuse.
727
744
  const issuer = createCapabilityIssuer()
728
- const fileKinds = storedFileKinds(artifact, app.database, objects, problems)
729
- const bound = contractDatabase(app.database, options.database, issuer.authority, problems)
745
+ const fileKinds = storedFileKinds(artifact, app.database, objects, problems, options.fileRetentionMs ?? 0)
746
+ const bound = contractDatabase(app.database, options.database, issuer.authority, options.projectWakes, problems)
730
747
  binding.release = bound?.release ?? null
731
748
  const framework = bound?.framework ?? null
732
749
  frameworkProblems(artifact, framework, problems)
@@ -899,6 +916,7 @@ function bootOnce(app: ContractImplementation, options: BootOptions, binding: Bi
899
916
  mail,
900
917
  tokens,
901
918
  url,
919
+ publicEgress: publicEgressRules(options.environment.framework, options.resolveHost ?? null),
902
920
  }, problems)
903
921
  for (const id of jobs.declared) {
904
922
  declared.add(id)
@@ -34,6 +34,9 @@ export const CAPABILITY_REFUSALS = {
34
34
  undeclared_binding: 'the site named a webhook it does not declare in binds',
35
35
  undeclared_signs: 'the site signed a token of a purpose it does not declare in signs, or for longer than the purpose allows',
36
36
  undeclared_egress: 'the site called an origin it does not declare in egress',
37
+ refused_egress:
38
+ "the site's public egress refused the host: an IP address, a local or internal name, a non-default port, a host of this installation, or a name that resolves to a private address",
39
+ oversized_egress: "a response to the site's public egress was larger than it reads",
37
40
  wrong_binding: 'a webhook binding was handed a capability of another kind or dimension than the webhook is bound to',
38
41
  missing_id: 'the job named an object without an id',
39
42
  wrong_capability: 'an operation was handed a capability of another dimension or action than it needs',