@fabrika/app 0.9.0-dev.4 → 0.9.0-dev.5
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.
- package/package.json +9 -9
- package/skill/SKILL.md +41 -14
- package/skill/references/app-setup.md +43 -12
- package/skill/references/dev.md +2 -1
- package/skill/references/endpoint.md +30 -24
- package/skill/references/errors.md +40 -35
- package/skill/references/files.md +4 -2
- package/skill/references/jobs.md +21 -4
- package/skill/references/table-and-migration.md +19 -2
- package/skill/references/tests.md +40 -1
- package/skill/references/webhooks-links-connectors.md +1 -1
- package/src/build-recipe.ts +198 -0
- package/src/build.ts +60 -4
- package/src/bun.ts +181 -13
- package/src/cloudflare/application.ts +822 -0
- package/src/cloudflare/bindings.ts +159 -0
- package/src/cloudflare/export.ts +641 -0
- package/src/cloudflare/import.ts +1021 -0
- package/src/cloudflare/maintenance.ts +518 -0
- package/src/cloudflare/names.ts +16 -0
- package/src/cloudflare/ops.ts +375 -0
- package/src/cloudflare/r2-files.ts +172 -0
- package/src/cloudflare/restore.ts +167 -0
- package/src/cloudflare/tracker.ts +192 -0
- package/src/cloudflare.ts +100 -146
- package/src/contract/app-id.ts +5 -0
- package/src/contract/artifact-schema.ts +9 -1
- package/src/contract/build.ts +40 -2
- package/src/contract/compile.ts +1 -0
- package/src/contract/context.ts +35 -9
- package/src/contract/declaration.ts +2 -0
- package/src/contract/defaults.ts +22 -2
- package/src/contract/define.ts +29 -3
- package/src/contract/kit.ts +4 -1
- package/src/contract/platform.ts +3 -2
- package/src/contract/vocabulary.ts +26 -8
- package/src/dev/launcher.ts +50 -4
- package/src/disk-assets.ts +8 -3
- package/src/files/archive.ts +2 -2
- package/src/files/job-names.ts +12 -0
- package/src/files/kinds.ts +73 -31
- package/src/files/scan.ts +3 -4
- package/src/files/streams.ts +3 -1
- package/src/implement/anonymous.ts +12 -11
- package/src/implement/boot.ts +75 -6
- package/src/implement/bounded.ts +21 -2
- package/src/implement/capability.ts +15 -3
- package/src/implement/dispatch.ts +419 -177
- package/src/implement/failures.ts +17 -1
- package/src/implement/faults.ts +1 -0
- package/src/implement/index.ts +1 -0
- package/src/implement/invocation.ts +58 -10
- package/src/implement/principal.ts +25 -2
- package/src/implement/terminals.ts +93 -0
- package/src/implement/workload.ts +42 -16
- package/src/jobs/mail.ts +8 -0
- package/src/jobs/report.ts +5 -1
- package/src/jobs/runner.ts +672 -113
- package/src/jobs/schedule.ts +7 -1
- package/src/jobs/scrub.ts +14 -1
- package/src/jobs/types.ts +6 -0
- package/src/spa-fallback.ts +12 -0
- package/src/testing/endpoint-access.ts +307 -152
- package/src/testing/isolation.ts +8 -1
- package/src/testing/kit.ts +80 -2
- package/src/testing/proxy.ts +15 -10
- package/types/src/build-recipe.d.ts +70 -0
- package/types/src/build.d.ts +19 -1
- package/types/src/bun.d.ts +34 -1
- package/types/src/cloudflare/application.d.ts +73 -0
- package/types/src/cloudflare/bindings.d.ts +33 -0
- package/types/src/cloudflare/export.d.ts +16 -0
- package/types/src/cloudflare/import.d.ts +51 -0
- package/types/src/cloudflare/maintenance.d.ts +117 -0
- package/types/src/cloudflare/names.d.ts +11 -0
- package/types/src/cloudflare/ops.d.ts +81 -0
- package/types/src/cloudflare/r2-files.d.ts +9 -0
- package/types/src/cloudflare/restore.d.ts +9 -0
- package/types/src/cloudflare/tracker.d.ts +29 -0
- package/types/src/cloudflare.d.ts +12 -18
- package/types/src/contract/app-id.d.ts +2 -0
- package/types/src/contract/artifact-schema.d.ts +2 -0
- package/types/src/contract/context.d.ts +35 -11
- package/types/src/contract/declaration.d.ts +4 -0
- package/types/src/contract/defaults.d.ts +19 -1
- package/types/src/contract/define.d.ts +20 -3
- package/types/src/contract/kit.d.ts +2 -1
- package/types/src/contract/platform.d.ts +2 -2
- package/types/src/contract/vocabulary.d.ts +9 -7
- package/types/src/disk-assets.d.ts +4 -1
- package/types/src/files/job-names.d.ts +9 -0
- package/types/src/files/kinds.d.ts +21 -14
- package/types/src/files/scan.d.ts +1 -3
- package/types/src/implement/anonymous.d.ts +2 -4
- package/types/src/implement/boot.d.ts +17 -1
- package/types/src/implement/bounded.d.ts +11 -1
- package/types/src/implement/capability.d.ts +4 -2
- package/types/src/implement/dispatch.d.ts +34 -1
- package/types/src/implement/failures.d.ts +5 -0
- package/types/src/implement/faults.d.ts +1 -0
- package/types/src/implement/index.d.ts +1 -0
- package/types/src/implement/invocation.d.ts +22 -7
- package/types/src/implement/principal.d.ts +6 -1
- package/types/src/implement/terminals.d.ts +33 -0
- package/types/src/implement/workload.d.ts +5 -0
- package/types/src/jobs/runner.d.ts +66 -2
- package/types/src/jobs/schedule.d.ts +2 -0
- package/types/src/jobs/types.d.ts +6 -0
- package/types/src/spa-fallback.d.ts +2 -0
- package/types/src/testing/endpoint-access.d.ts +37 -5
- package/types/src/testing/isolation.d.ts +1 -1
- package/types/src/testing/kit.d.ts +22 -1
- 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 * * * *'
|
package/src/files/kinds.ts
CHANGED
|
@@ -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
|
|
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
|
|
309
|
-
*
|
|
310
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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 ||
|
|
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
|
}
|
package/src/files/streams.ts
CHANGED
|
@@ -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 =
|
|
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')
|
package/src/implement/boot.ts
CHANGED
|
@@ -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 {
|
|
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 =
|
|
381
|
-
|
|
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,
|
package/src/implement/bounded.ts
CHANGED
|
@@ -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):
|
|
13
|
-
return
|
|
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 (
|
|
279
|
-
|
|
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)
|