@fabrika/app 0.9.0-dev.4 → 0.9.0-dev.6

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 (113) hide show
  1. package/package.json +9 -9
  2. package/skill/SKILL.md +41 -14
  3. package/skill/references/app-setup.md +43 -12
  4. package/skill/references/dev.md +2 -1
  5. package/skill/references/endpoint.md +30 -24
  6. package/skill/references/errors.md +40 -35
  7. package/skill/references/files.md +4 -2
  8. package/skill/references/jobs.md +21 -4
  9. package/skill/references/table-and-migration.md +19 -2
  10. package/skill/references/tests.md +40 -1
  11. package/skill/references/webhooks-links-connectors.md +1 -1
  12. package/src/build-recipe.ts +198 -0
  13. package/src/build.ts +60 -4
  14. package/src/bun.ts +181 -13
  15. package/src/cloudflare/application.ts +822 -0
  16. package/src/cloudflare/bindings.ts +159 -0
  17. package/src/cloudflare/export.ts +621 -0
  18. package/src/cloudflare/import.ts +1013 -0
  19. package/src/cloudflare/maintenance.ts +518 -0
  20. package/src/cloudflare/names.ts +16 -0
  21. package/src/cloudflare/ops.ts +375 -0
  22. package/src/cloudflare/r2-files.ts +172 -0
  23. package/src/cloudflare/restore.ts +167 -0
  24. package/src/cloudflare/tracker.ts +192 -0
  25. package/src/cloudflare.ts +100 -146
  26. package/src/contract/app-id.ts +5 -0
  27. package/src/contract/artifact-schema.ts +9 -1
  28. package/src/contract/build.ts +40 -2
  29. package/src/contract/compile.ts +1 -0
  30. package/src/contract/context.ts +35 -9
  31. package/src/contract/declaration.ts +2 -0
  32. package/src/contract/defaults.ts +22 -2
  33. package/src/contract/define.ts +29 -3
  34. package/src/contract/kit.ts +4 -1
  35. package/src/contract/platform.ts +3 -2
  36. package/src/contract/vocabulary.ts +26 -8
  37. package/src/dev/launcher.ts +50 -4
  38. package/src/disk-assets.ts +8 -3
  39. package/src/files/archive.ts +2 -2
  40. package/src/files/job-names.ts +12 -0
  41. package/src/files/kinds.ts +73 -31
  42. package/src/files/scan.ts +3 -4
  43. package/src/files/streams.ts +3 -1
  44. package/src/implement/anonymous.ts +12 -11
  45. package/src/implement/boot.ts +75 -6
  46. package/src/implement/bounded.ts +21 -2
  47. package/src/implement/capability.ts +15 -3
  48. package/src/implement/dispatch.ts +419 -177
  49. package/src/implement/failures.ts +17 -1
  50. package/src/implement/faults.ts +1 -0
  51. package/src/implement/index.ts +1 -0
  52. package/src/implement/invocation.ts +58 -10
  53. package/src/implement/principal.ts +25 -2
  54. package/src/implement/terminals.ts +93 -0
  55. package/src/implement/workload.ts +42 -16
  56. package/src/jobs/mail.ts +8 -0
  57. package/src/jobs/report.ts +5 -1
  58. package/src/jobs/runner.ts +672 -113
  59. package/src/jobs/schedule.ts +7 -1
  60. package/src/jobs/scrub.ts +14 -1
  61. package/src/jobs/types.ts +6 -0
  62. package/src/spa-fallback.ts +12 -0
  63. package/src/testing/endpoint-access.ts +307 -152
  64. package/src/testing/isolation.ts +8 -1
  65. package/src/testing/kit.ts +80 -2
  66. package/src/testing/proxy.ts +15 -10
  67. package/types/src/build-recipe.d.ts +70 -0
  68. package/types/src/build.d.ts +19 -1
  69. package/types/src/bun.d.ts +34 -1
  70. package/types/src/cloudflare/application.d.ts +73 -0
  71. package/types/src/cloudflare/bindings.d.ts +33 -0
  72. package/types/src/cloudflare/export.d.ts +16 -0
  73. package/types/src/cloudflare/import.d.ts +51 -0
  74. package/types/src/cloudflare/maintenance.d.ts +117 -0
  75. package/types/src/cloudflare/names.d.ts +11 -0
  76. package/types/src/cloudflare/ops.d.ts +81 -0
  77. package/types/src/cloudflare/r2-files.d.ts +9 -0
  78. package/types/src/cloudflare/restore.d.ts +9 -0
  79. package/types/src/cloudflare/tracker.d.ts +29 -0
  80. package/types/src/cloudflare.d.ts +12 -18
  81. package/types/src/contract/app-id.d.ts +2 -0
  82. package/types/src/contract/artifact-schema.d.ts +2 -0
  83. package/types/src/contract/context.d.ts +35 -11
  84. package/types/src/contract/declaration.d.ts +4 -0
  85. package/types/src/contract/defaults.d.ts +19 -1
  86. package/types/src/contract/define.d.ts +20 -3
  87. package/types/src/contract/kit.d.ts +2 -1
  88. package/types/src/contract/platform.d.ts +2 -2
  89. package/types/src/contract/vocabulary.d.ts +9 -7
  90. package/types/src/disk-assets.d.ts +4 -1
  91. package/types/src/files/job-names.d.ts +9 -0
  92. package/types/src/files/kinds.d.ts +21 -14
  93. package/types/src/files/scan.d.ts +1 -3
  94. package/types/src/implement/anonymous.d.ts +2 -4
  95. package/types/src/implement/boot.d.ts +17 -1
  96. package/types/src/implement/bounded.d.ts +11 -1
  97. package/types/src/implement/capability.d.ts +4 -2
  98. package/types/src/implement/dispatch.d.ts +34 -1
  99. package/types/src/implement/failures.d.ts +5 -0
  100. package/types/src/implement/faults.d.ts +1 -0
  101. package/types/src/implement/index.d.ts +1 -0
  102. package/types/src/implement/invocation.d.ts +22 -7
  103. package/types/src/implement/principal.d.ts +6 -1
  104. package/types/src/implement/terminals.d.ts +33 -0
  105. package/types/src/implement/workload.d.ts +5 -0
  106. package/types/src/jobs/runner.d.ts +66 -2
  107. package/types/src/jobs/schedule.d.ts +2 -0
  108. package/types/src/jobs/types.d.ts +6 -0
  109. package/types/src/spa-fallback.d.ts +2 -0
  110. package/types/src/testing/endpoint-access.d.ts +37 -5
  111. package/types/src/testing/isolation.d.ts +1 -1
  112. package/types/src/testing/kit.d.ts +22 -1
  113. package/types/src/testing/proxy.d.ts +4 -4
@@ -0,0 +1,12 @@
1
+ // The framework's own file jobs, in a module of their own: the build recipe schedules them without the file stack.
2
+
3
+ /** The reserved name of the scan job: a `c.cron` job name cannot contain `-`, so no application job takes it. */
4
+ export const FILE_SCAN_JOB = 'fabrika-file-scan'
5
+ export const FILE_SCAN_SCHEDULE = '* * * * *'
6
+
7
+ /**
8
+ * The framework's sweep job: hourly, it deletes the files no declared column references and the pending ones past the
9
+ * grace, so none waits for the next request. A reserved name with `-`, which no `c.cron` name can take.
10
+ */
11
+ export const FILE_SWEEP_JOB = 'fabrika-file-sweep'
12
+ export const FILE_SWEEP_SCHEDULE = '41 * * * *'
@@ -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'
@@ -29,16 +31,15 @@ import { bytesAreOfType, SNIFF_BYTES, SNIFFABLE_TYPES } from './sniff'
29
31
  import { cleanName, digesting, isNamed, readExactly, readHead } from './streams'
30
32
  import { FileDownload } from './treatment'
31
33
 
32
- /**
33
- * The framework's sweep job: hourly, it deletes the files no declared column references and the pending ones past the
34
- * grace, so none waits for the next request. A reserved name with `-`, which no `c.cron` name can take;
35
- * `@fabrika/provider-zerops` writes it into the crontab on this schedule (`ZEROPS_FILE_SWEEP_JOB`).
36
- */
37
- export const FILE_SWEEP_JOB = 'fabrika-file-sweep'
38
- export const FILE_SWEEP_SCHEDULE = '41 * * * *'
34
+ export { FILE_SWEEP_JOB, FILE_SWEEP_SCHEDULE } from './job-names'
39
35
  export const FILE_SWEEP_TIMEOUT_MS = 10 * 60_000
40
36
  /** How long a staged file waits for its first reference before the sweep may delete it. */
41
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
42
43
  /** How many files one sweep batch handles; the next batch, or the next run, takes the rest. */
43
44
  const SWEEP_BATCH = 20
44
45
 
@@ -67,6 +68,7 @@ export class FileWork {
67
68
  readonly holder: object
68
69
  readonly request: string
69
70
  readonly #staged: string[] = []
71
+ readonly #written = new Map<string, string>()
70
72
 
71
73
  constructor(holder: object, request: string) {
72
74
  this.holder = holder
@@ -77,9 +79,18 @@ export class FileWork {
77
79
  this.#staged.push(id)
78
80
  }
79
81
 
82
+ /** The work wrote the object of a file it staged, under a key no other file has. */
83
+ wrote(id: string, objectKey: string): void {
84
+ this.#written.set(id, objectKey)
85
+ }
86
+
80
87
  get stagedIds(): readonly string[] {
81
88
  return [...this.#staged]
82
89
  }
90
+
91
+ writtenKey(id: string): string | null {
92
+ return this.#written.get(id) ?? null
93
+ }
83
94
  }
84
95
 
85
96
  interface Kind {
@@ -92,12 +103,16 @@ export class StoredFileKinds {
92
103
  readonly #store: FileObjectStore
93
104
  readonly #files: StoredFiles
94
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()
95
109
 
96
- 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) {
97
111
  this.#kinds = new Map(kinds.map((kind) => [kind.name, kind]))
98
112
  this.#store = store
99
113
  this.#files = files
100
114
  this.#columns = columns
115
+ this.#retentionMs = retentionMs
101
116
  }
102
117
 
103
118
  /** Whether the contract declares kind `name`. */
@@ -188,6 +203,7 @@ export class StoredFileKinds {
188
203
  const body = digesting(stream, null)
189
204
  try {
190
205
  const { size } = await this.#store.write(objectKey, body.stream, { contentType: type, maxBytes: artifact.maxBytes })
206
+ work.wrote(id, objectKey)
191
207
  const sha256 = body.digest()
192
208
  await this.#files.written(id, { size, sha256 })
193
209
  return fileReference({ id, kind: kind.name, name, type, size, status: 'pending' }, work.holder, true)
@@ -212,6 +228,13 @@ export class StoredFileKinds {
212
228
  try {
213
229
  const objectKey = await this.#files.abandon(id, work.request)
214
230
  if (objectKey === null) {
231
+ // On SQLite the pending row is written in the work's own transaction and rolled back with it, so only the
232
+ // work knows the object; a row still there is a file something claimed, whose object stays.
233
+ const written = work.writtenKey(id)
234
+ if (written !== null && (await this.#files.find(id)) === null) {
235
+ step = 'object_delete_failed'
236
+ await this.#store.delete(written)
237
+ }
215
238
  return
216
239
  }
217
240
  step = 'object_delete_failed'
@@ -304,41 +327,54 @@ export class StoredFileKinds {
304
327
  return new FileDownload({ body: object.body, size: file.size, contentType: file.type, name: file.name })
305
328
  }
306
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
+
307
344
  /**
308
- * The sweep: it finishes deletions a crash interrupted, adopts the migrated files a declared column references, then
309
- * deletes, batch by batch, every file past the grace that no declared column references: its row and the record of
310
- * 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.
311
348
  */
312
349
  async sweep(signal: AbortSignal): Promise<void> {
313
350
  let step = 'rows_read_failed'
314
351
  try {
315
- for (let keys = await this.#files.unfinishedDeletions(SWEEP_BATCH); keys.length > 0 && !signal.aborted;) {
316
- for (const key of keys) {
317
- step = 'object_delete_failed'
318
- await this.#store.delete(key)
319
- step = 'deletion_record_failed'
320
- await this.#files.forgetDeletion(key)
321
- }
322
- step = 'rows_read_failed'
323
- keys = keys.length === SWEEP_BATCH ? await this.#files.unfinishedDeletions(SWEEP_BATCH) : []
324
- }
325
352
  await this.#files.adoptReferenced(this.#columns)
326
353
  for (let more = true; more && !signal.aborted;) {
327
354
  step = 'rows_read_failed'
328
355
  const batch = await this.#files.unreferenced(this.#columns, SWEEP_BATCH, FILE_PENDING_GRACE_MS)
329
356
  for (const id of batch) {
330
357
  step = 'row_delete_failed'
331
- const key = await this.#files.remove(id, FILE_PENDING_GRACE_MS)
332
- if (key === null) {
333
- continue
334
- }
335
- step = 'object_delete_failed'
336
- await this.#store.delete(key)
337
- step = 'deletion_record_failed'
338
- await this.#files.forgetDeletion(key)
358
+ await this.#files.remove(id, FILE_PENDING_GRACE_MS)
339
359
  }
340
360
  more = batch.length === SWEEP_BATCH
341
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
+ }
342
378
  } catch {
343
379
  console.error(`fabrika: stored files sweep: ${step}`)
344
380
  throw new ServerFault('file_sweep_failed', 'the sweep of stored files failed; the next run retries it')
@@ -418,13 +454,15 @@ function fileColumns(artifact: ContractArtifact): FileColumnRef[] {
418
454
 
419
455
  /**
420
456
  * The file kinds of `artifact`, or `null` when it declares none. Every reason a kind cannot be served goes into
421
- * `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`.
422
459
  */
423
460
  export function storedFileKinds(
424
461
  artifact: ContractArtifact,
425
462
  database: ImplementationDatabase | null,
426
463
  store: FileObjectStore | undefined,
427
464
  problems: string[],
465
+ retentionMs: number,
428
466
  ): StoredFileKinds | null {
429
467
  const entries = Object.entries(artifact.fileKinds ?? {})
430
468
  if (entries.length === 0) {
@@ -438,6 +476,9 @@ export function storedFileKinds(
438
476
  return null
439
477
  }
440
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
+ }
441
482
  for (const type of kind.types.filter((candidate) => !SNIFFABLE_TYPES.includes(candidate))) {
442
483
  problems.push(`files '${name}' admits '${type}', whose bytes the framework cannot verify (allowed: ${SNIFFABLE_TYPES.join(', ')})`)
443
484
  }
@@ -450,5 +491,6 @@ export function storedFileKinds(
450
491
  store,
451
492
  frameworkTablesOf(database).files,
452
493
  fileColumns(artifact),
494
+ retentionMs,
453
495
  )
454
496
  }
package/src/files/scan.ts CHANGED
@@ -7,13 +7,12 @@
7
7
 
8
8
  import type { QuarantinedStoredFile } from '@fabrika/db/framework'
9
9
  import type { FileObjectStore } from '@fabrika/platform'
10
+ import { createHash } from 'node:crypto'
10
11
  import type { OperationsReporter } from '../jobs/report'
11
12
  import { type ArchiveRefusal, checkArchive } from './archive'
12
13
  import { ZIP_TYPES } from './sniff'
13
14
 
14
- /** The reserved name of the scan job: a `c.cron` job name cannot contain `-`, so no application job takes it. */
15
- export const FILE_SCAN_JOB = 'fabrika-file-scan'
16
- export const FILE_SCAN_SCHEDULE = '* * * * *'
15
+ export { FILE_SCAN_JOB, FILE_SCAN_SCHEDULE } from './job-names'
17
16
 
18
17
  export const SCAN_LIMITS = {
19
18
  /** One pass scans at most this many files, and at most `batchBytes` of them; the next pass takes the rest. */
@@ -181,7 +180,7 @@ class ScanPass {
181
180
  }
182
181
  const bytes = object.size === file.size ? await readExactly(object.body, file.size, signal) : null
183
182
  if (object.size !== file.size) await object.body.cancel()
184
- if (bytes === null || new Bun.CryptoHasher('sha256').update(bytes).digest('hex') !== file.sha256) {
183
+ if (bytes === null || createHash('sha256').update(bytes).digest('hex') !== file.sha256) {
185
184
  if (!signal.aborted) this.#states.set(file.id, { kind: 'mismatch' })
186
185
  throw new Error('the object differs from its upload')
187
186
  }
@@ -1,6 +1,8 @@
1
1
  // The byte streams of a stored file on its way in and out: the head the sniff reads, the digest and the deadline of a
2
2
  // write, the exact read of a file a site opens, and the client's file name as metadata.
3
3
 
4
+ import { createHash } from 'node:crypto'
5
+
4
6
  const MAX_NAME_CODE_POINTS = 255
5
7
 
6
8
  /** The client's file name, metadata only: at most 255 code points, never half a character, no control characters. */
@@ -62,7 +64,7 @@ export function digesting(body: ReadableStream<Uint8Array>, timeoutMs: number |
62
64
  timedOut(): boolean
63
65
  stop(): void
64
66
  } {
65
- const hasher = new Bun.CryptoHasher('sha256')
67
+ const hasher = createHash('sha256')
66
68
  let timer: ReturnType<typeof setTimeout> | undefined
67
69
  let expired = false
68
70
  const stream = body.pipeThrough(
@@ -2,18 +2,9 @@
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
- import { readBoundedBytes } from './bounded'
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
- }
7
+ import { deadline, readBoundedBytes } from './bounded'
17
8
 
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
@@ -36,6 +27,16 @@ export async function readBoundedBody(request: Request, maxBytes: number, deadli
36
27
  return body
37
28
  }
38
29
 
30
+ /** `readBoundedBody` within the deadline `maxBytes` derives; the deadline ends with the read. */
31
+ export async function readBodyInTime(request: Request, maxBytes: number): Promise<Uint8Array<ArrayBuffer>> {
32
+ const timer = deadline(bodyDeadlineMs(maxBytes))
33
+ try {
34
+ return await readBoundedBody(request, maxBytes, timer.signal)
35
+ } finally {
36
+ timer.clear()
37
+ }
38
+ }
39
+
39
40
  /** What a request answers whose body did not arrive whole: nobody reads it, and no failure is reported. */
40
41
  export function abortedBody(): HttpError {
41
42
  return new HttpError(400, 'aborted', 'The body could not be read to its end')
@@ -17,13 +17,22 @@ import {
17
17
  FABRIKA_IAM_APP_ID,
18
18
  FABRIKA_PROXY_SECRET,
19
19
  type IamMembershipRpc,
20
+ type IamTerminalRpc,
20
21
  isLoopbackHost,
21
22
  type Jwks,
22
23
  parseAppEnvironmentId,
23
24
  } from '@fabrika/auth-core'
24
25
  import type { Database } from '@fabrika/db'
25
26
  import type { CapabilityAuthority } from '@fabrika/db/capability'
26
- import { bindScopedDatabase, type DataAccess, dataAccessOf, type FrameworkTables, frameworkTablesOf, isScopedDatabase } from '@fabrika/db/framework'
27
+ import {
28
+ bindScopedDatabaseProvisionally,
29
+ type DataAccess,
30
+ dataAccessOf,
31
+ type FrameworkTables,
32
+ frameworkTablesOf,
33
+ isScopedDatabase,
34
+ type Session,
35
+ } from '@fabrika/db/framework'
27
36
  import type { DataKind } from '@fabrika/db/tables'
28
37
  import type { EmailProviderRegistry } from '@fabrika/email'
29
38
  import { builtinEmailProviders } from '@fabrika/email/providers'
@@ -91,6 +100,11 @@ export interface BootOptions {
91
100
  readonly requireProxySecret?: boolean
92
101
  /** The object storage of the stored files, which the Bun adapter opens. Without it, a contract with file kinds does not boot. */
93
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
94
108
  /**
95
109
  * The malware scanner of the scan job of `scan: true` file kinds, which the Bun adapter supplies to a job run
96
110
  * (`clamscanScanner`). Without it the scan job leaves every quarantined file quarantined and reports.
@@ -101,6 +115,11 @@ export interface BootOptions {
101
115
  * creates scopes, manages members or issues share links does not boot.
102
116
  */
103
117
  readonly membership?: IamMembershipRpc
118
+ /**
119
+ * IAM's identification operations at a terminal (ADR-0067): the IAM binding on Cloudflare, `HttpIamTerminals`
120
+ * elsewhere. Without it, a contract that declares a terminal does not boot.
121
+ */
122
+ readonly terminals?: IamTerminalRpc
104
123
  /**
105
124
  * Cloudflare service bindings to the owners' proxy Workers, by binding name (`FABRIKA_CONNECT_<IMPORT>`). An import
106
125
  * without one calls its owner with `fetch`.
@@ -150,6 +169,11 @@ export interface BootOptions {
150
169
  * then `null`.
151
170
  */
152
171
  readonly clientAddress?: 'vouched'
172
+ /**
173
+ * Runs in the transaction of every change of a job's wakes or lease (`DataLayerRuntime.projectWakes`): the Cloudflare
174
+ * object arms its alarm there. Bun supplies none.
175
+ */
176
+ readonly projectWakes?: (transaction: Session) => Promise<void>
153
177
  }
154
178
 
155
179
  /** The pool size a runtime adapter that names none is assumed to have: the Bun adapter's default. */
@@ -262,6 +286,18 @@ function readProxySecret(framework: Readonly<Record<string, string>>, required:
262
286
  return proxySecretDigest(secret)
263
287
  }
264
288
 
289
+ /** What an application's SQLite database (a Durable Object's, ADR-0065) cannot serve: a scanning file kind. */
290
+ function sqliteProblems(artifact: ContractArtifact, database: Database | undefined, problems: string[]): void {
291
+ if (database?.dialect !== 'sqlite') {
292
+ return
293
+ }
294
+ for (const [name, kind] of Object.entries(artifact.fileKinds ?? {})) {
295
+ if (kind.scan === true) {
296
+ problems.push(`files '${name}' declares scan: true; no malware scanner runs on Cloudflare, so a scanning file kind is not served there`)
297
+ }
298
+ }
299
+ }
300
+
265
301
  /** What this version cannot serve yet; a contract that declares it does not boot rather than answer nothing. */
266
302
  function unservable(
267
303
  artifact: ContractArtifact,
@@ -350,6 +386,8 @@ interface BoundDatabase {
350
386
  readonly framework: FrameworkTables | null
351
387
  /** The mini-ORM behind a staged-kit site's `ctx.db`; only a `scoped(tables)` layer has it. */
352
388
  readonly data: DataAccess | null
389
+ /** Disconnects a `scoped(tables)` layer this boot bound; `null` for any other database. */
390
+ readonly release: (() => void) | null
353
391
  }
354
392
 
355
393
  /**
@@ -360,6 +398,7 @@ function contractDatabase(
360
398
  database: ImplementationDatabase | null,
361
399
  connection: Database | undefined,
362
400
  capabilities: CapabilityAuthority,
401
+ projectWakes: ((transaction: Session) => Promise<void>) | undefined,
363
402
  problems: string[],
364
403
  ): BoundDatabase | null {
365
404
  if (database === null) {
@@ -367,7 +406,7 @@ function contractDatabase(
367
406
  }
368
407
  if (!isScopedDatabase(database)) {
369
408
  if ('locate' in database) {
370
- return { database, framework: null, data: null }
409
+ return { database, framework: null, data: null, release: null }
371
410
  }
372
411
  problems.push('serve(contract, { database }) takes the scoped(tables) result of @fabrika/db itself, not a copy or a wrapper of it')
373
412
  return null
@@ -377,8 +416,13 @@ function contractDatabase(
377
416
  return null
378
417
  }
379
418
  try {
380
- const locate = bindScopedDatabase(database, { database: connection, capabilities, readOnly: requestIsReadOnly })
381
- return { database: { tables: database.tables, locate }, framework: frameworkTablesOf(database), data: dataAccessOf(database) }
419
+ const { locate, release } = bindScopedDatabaseProvisionally(database, {
420
+ database: connection,
421
+ capabilities,
422
+ readOnly: requestIsReadOnly,
423
+ ...(projectWakes === undefined ? {} : { projectWakes }),
424
+ })
425
+ return { database: { tables: database.tables, locate }, framework: frameworkTablesOf(database), data: dataAccessOf(database), release }
382
426
  } catch {
383
427
  problems.push('the data layer was bound before boot; only the framework binds it, so remove @fabrika/db/framework from the application')
384
428
  return null
@@ -651,11 +695,28 @@ function runtimePurposes(contract: AnyContract, artifact: ContractArtifact): Rea
651
695
  }
652
696
 
653
697
  export function boot(app: ContractImplementation, options: BootOptions): ContractApp {
698
+ const binding: Binding = { release: null }
699
+ try {
700
+ return bootOnce(app, options, binding)
701
+ } catch (error) {
702
+ // A failed boot releases the data layer it bound, so a later boot of the same application binds it again.
703
+ binding.release?.()
704
+ throw error
705
+ }
706
+ }
707
+
708
+ /** What `bootOnce` bound: released when the boot fails, kept when it succeeds. */
709
+ interface Binding {
710
+ release: (() => void) | null
711
+ }
712
+
713
+ function bootOnce(app: ContractImplementation, options: BootOptions, binding: Binding): ContractApp {
654
714
  const problems: string[] = []
655
715
  installEgressGuard()
656
716
  // What a handler reaches through these is the platform's own request, which no site's egress covers.
657
717
  const objects = options.files === undefined ? undefined : platformFacility(options.files)
658
718
  const membershipRpc = options.membership === undefined ? undefined : platformFacility(options.membership)
719
+ const terminalRpc = options.terminals === undefined ? undefined : platformFacility(options.terminals)
659
720
  const workloadTokens = options.workloadTokens === undefined ? undefined : platformFacility(options.workloadTokens)
660
721
  const variables = readFramework(options.environment.framework, app.contract.vocabulary.app, problems)
661
722
  const artifact = compileContract(app.contract, app.database?.tables ?? {})
@@ -673,10 +734,12 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
673
734
  const owned = new Set(Object.values(artifact.tables).flatMap((table) => table.scope.mode === 'dimension' ? [table.scope.dimension] : []))
674
735
  const containers = containersOf(artifact)
675
736
  unservable(artifact, options.assets, owned, containers, problems)
737
+ sqliteProblems(artifact, options.database, problems)
676
738
  // This runtime's own: what another `boot` call mints, application code's included, its stores refuse.
677
739
  const issuer = createCapabilityIssuer()
678
- const fileKinds = storedFileKinds(artifact, app.database, objects, problems)
679
- const bound = contractDatabase(app.database, options.database, issuer.authority, problems)
740
+ const fileKinds = storedFileKinds(artifact, app.database, objects, problems, options.fileRetentionMs ?? 0)
741
+ const bound = contractDatabase(app.database, options.database, issuer.authority, options.projectWakes, problems)
742
+ binding.release = bound?.release ?? null
680
743
  const framework = bound?.framework ?? null
681
744
  frameworkProblems(artifact, framework, problems)
682
745
  const database = bound?.database ?? null
@@ -896,6 +959,11 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
896
959
  if (site !== undefined && data === null) {
897
960
  problems.push(`'${site.row.id}' reaches data through ctx.db, which runs on @fabrika/db: pass serve(contract, { database: scoped(tables) })`)
898
961
  }
962
+ if (artifact.terminal !== undefined && options.terminals === undefined) {
963
+ problems.push(
964
+ 'the contract declares a terminal, and the runtime adapter supplies no IAM transport for its identifications (the IAM binding on Cloudflare; FABRIKA_IAM_RPC_URL and FABRIKA_IAM_RPC_KEY on Bun)',
965
+ )
966
+ }
899
967
  const asking = [...endpoints.values()].find(asksIam)
900
968
  if (asking !== undefined && options.membership === undefined) {
901
969
  problems.push(
@@ -919,6 +987,7 @@ export function boot(app: ContractImplementation, options: BootOptions): Contrac
919
987
  containers,
920
988
  assets: options.assets ?? null,
921
989
  membership,
990
+ terminals: artifact.terminal === undefined ? null : (terminalRpc ?? null),
922
991
  framework,
923
992
  mint: issuer.mint,
924
993
  capabilities: issuer.authority,
@@ -8,9 +8,28 @@
8
8
  */
9
9
  export const REQUEST_BUDGET_MS = 10_000
10
10
 
11
+ /** A signal that aborts once its time passed, and a `clear` its work calls when it settles. */
12
+ export interface Deadline {
13
+ readonly signal: AbortSignal
14
+ clear(): void
15
+ }
16
+
17
+ /**
18
+ * Aborts like `AbortSignal.timeout(ms)`, or when `parent` aborts. Its timer is cleared by `clear`, which every caller
19
+ * runs in `finally`: workerd counts a pending timer as work, so an uncleared one keeps a Durable Object awake.
20
+ */
21
+ export function deadline(ms: number, parent?: AbortSignal): Deadline {
22
+ const controller = new AbortController()
23
+ const timer = setTimeout(() => controller.abort(new DOMException('The operation timed out.', 'TimeoutError')), ms)
24
+ return {
25
+ signal: parent === undefined ? controller.signal : AbortSignal.any([parent, controller.signal]),
26
+ clear: () => clearTimeout(timer),
27
+ }
28
+ }
29
+
11
30
  /** A handler's `ctx.signal`: aborted when the client leaves (`request.signal`) or once `budgetMs` passed. */
12
- export function handlerSignal(request: Request, budgetMs: number = REQUEST_BUDGET_MS): AbortSignal {
13
- return AbortSignal.any([request.signal, AbortSignal.timeout(budgetMs)])
31
+ export function handlerSignal(request: Request, budgetMs: number = REQUEST_BUDGET_MS): Deadline {
32
+ return deadline(budgetMs, request.signal)
14
33
  }
15
34
 
16
35
  export interface BoundedRead {
@@ -269,14 +269,18 @@ export class Within<D extends string, A extends string> implements WithinCapabil
269
269
  principal: string,
270
270
  values: readonly string[] | 'all',
271
271
  containers: readonly ContainerGrant[],
272
+ contained: readonly ContainerGrant[],
272
273
  ) {
273
274
  if (token !== MINT) {
274
275
  throw new CapabilityRefusedError('not_minted', 'a Within is minted by the framework only; declare the access form in fabrika.contract.ts')
275
276
  }
276
277
  const held = values === 'all' ? freeze([]) : containerGrantsOf(containers)
278
+ const inside = values === 'all' ? freeze([]) : containerGrantsOf(contained)
277
279
  let count = values === 'all' ? 0 : values.length
278
- for (let index = 0; index < held.length; index++) {
279
- count += held[index]?.values.length ?? 0
280
+ for (const group of [held, inside]) {
281
+ for (let index = 0; index < group.length; index++) {
282
+ count += group[index]?.values.length ?? 0
283
+ }
280
284
  }
281
285
  if (count > MAX_WITHIN_VALUES) {
282
286
  throw new CapabilityLimitError(
@@ -292,6 +296,7 @@ export class Within<D extends string, A extends string> implements WithinCapabil
292
296
  principal,
293
297
  values: values === 'all' ? 'all' : copyOf(values),
294
298
  containers: held,
299
+ contained: inside,
295
300
  })
296
301
  this.#frame = frame
297
302
  this.#issuer = issuer
@@ -315,6 +320,11 @@ export class Within<D extends string, A extends string> implements WithinCapabil
315
320
  return this.#grant.containers
316
321
  }
317
322
 
323
+ /** The dimensions inside this one in which the caller holds the action: `note → [n1]` for a workspace list. */
324
+ get contained(): readonly ContainerGrant[] {
325
+ return this.#grant.contained
326
+ }
327
+
318
328
  static {
319
329
  readWithin = (value) =>
320
330
  typeof value === 'object' && value !== null && #grant in value ? { grant: value.#grant, frame: value.#frame, issuer: value.#issuer } : undefined
@@ -434,6 +444,7 @@ export interface CapabilityMint {
434
444
  principal: string,
435
445
  values: readonly string[] | 'all',
436
446
  containers?: readonly ContainerGrant[],
447
+ contained?: readonly ContainerGrant[],
437
448
  ): Within<D, A>
438
449
  app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A>
439
450
  }
@@ -469,8 +480,9 @@ export function createCapabilityIssuer(): CapabilityIssuer {
469
480
  principal: string,
470
481
  values: readonly string[] | 'all',
471
482
  containers: readonly ContainerGrant[] = [],
483
+ contained: readonly ContainerGrant[] = [],
472
484
  ): Within<D, A> {
473
- return new Within(MINT, issuer, frame, dimension, action, principal, values, containers)
485
+ return new Within(MINT, issuer, frame, dimension, action, principal, values, containers, contained)
474
486
  },
475
487
  app<A extends string>(frame: RequestFrame, action: A, principal: string): AppCapability<A> {
476
488
  return new AppCapability(MINT, issuer, frame, action, principal)