@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,375 @@
1
+ // The object's side of Control's ops channel (ADR-0069 §1, §2): it authenticates the caller before it reads anything
2
+ // the request names, answers every refusal with `opsRefusal()`, and serves the view from its storage alone, so it
3
+ // works while the application cannot boot. Framework code only: an ops request never reaches the contract.
4
+
5
+ import {
6
+ type ApplicationObjects,
7
+ ENDPOINT_HEADER,
8
+ FABRIKA_APPLICATION_OBJECT,
9
+ FABRIKA_APPLICATION_OBJECTS,
10
+ FABRIKA_OPS_KEY_DIGESTS,
11
+ formatEndpointHeader,
12
+ OPS_DATA_REFUSED_STATUS,
13
+ OPS_METHOD,
14
+ OPS_ROW_COUNT_CAP,
15
+ OPS_STALE_STATUS,
16
+ type OpsBootFailureContent,
17
+ type OpsContentView,
18
+ type OpsDataRefusal,
19
+ opsKeyDigest,
20
+ type OpsOperation,
21
+ type OpsPublishedState,
22
+ opsRefusal,
23
+ type OpsStaleRefusal,
24
+ type OpsView,
25
+ parseApplicationObjects,
26
+ parseOpsContentView,
27
+ parseOpsExportRequest,
28
+ parseOpsImportRequest,
29
+ parseOpsInspectRequest,
30
+ parseOpsKeyDigests,
31
+ parseOpsMigrateAck,
32
+ parseOpsMigrateRequest,
33
+ parseOpsOperation,
34
+ parseOpsRestoreRequest,
35
+ parseOpsStateRequest,
36
+ parseOpsTimersRequest,
37
+ parseOpsView,
38
+ } from '@fabrika/auth-core'
39
+ import { FILES_TABLE, JOB_LEASES_TABLE, WEBHOOK_BINDINGS_TABLE, WEBHOOK_DELIVERIES_TABLE } from '@fabrika/db/migrations'
40
+ import type { SqliteCursor, SqliteStorage, SqliteValue } from '@fabrika/db/sqlite'
41
+ import type { SqliteMigrationBundle } from '@fabrika/db/sqlite-migrate'
42
+ import { opsProxyRow } from '@fabrika/proxy-core/manifest'
43
+ import { timingSafeEqual } from 'node:crypto'
44
+ import appPackage from '../../package.json' with { type: 'json' }
45
+ import { jsonResponse } from '../errors.js'
46
+ import { serveExport } from './export.js'
47
+ import { importInProgress, serveImport } from './import.js'
48
+ import type { MaintenanceBarrier, TransitionResult } from './maintenance.js'
49
+ import { serveRestore } from './restore.js'
50
+ import { serveTimers } from './tracker.js'
51
+
52
+ /** What the view reads of the object's storage; workerd's `DurableObjectStorage` has every optional member. */
53
+ export interface OpsStorage {
54
+ readonly sql: {
55
+ exec(query: string, ...bindings: SqliteValue[]): SqliteCursor
56
+ /** The bun:sqlite test double has no size. */
57
+ readonly databaseSize?: number
58
+ }
59
+ /** The bun:sqlite test double has no alarm. */
60
+ getAlarm?(): Promise<number | null>
61
+ /** The object's KV storage, which point-in-time recovery rewinds with its SQLite; the bun:sqlite double has none. */
62
+ get?(key: string): Promise<unknown>
63
+ put?(key: string, value: unknown): Promise<void>
64
+ /** The synchronous KV of a SQLite-backed object, in the same database; the bun:sqlite test double has none. */
65
+ readonly kv?: {
66
+ get(key: string): unknown
67
+ put(key: string, value: unknown): void
68
+ delete(key: string): boolean
69
+ }
70
+ /** Wipes the object's database, its KV and its alarm; the bun:sqlite test double has none. */
71
+ deleteAll?(): Promise<void>
72
+ }
73
+
74
+ /**
75
+ * The object's point-in-time recovery: workerd's storage bookmarks and the abort that resets the object. `null` where the
76
+ * storage has none (the bun:sqlite double, a runtime without PITR).
77
+ */
78
+ export interface OpsRecovery {
79
+ getCurrentBookmark(): Promise<string>
80
+ getBookmarkForTime(time: number): Promise<string>
81
+ onNextSessionRestoreBookmark(bookmark: string): Promise<string>
82
+ abort(reason: string): void
83
+ }
84
+
85
+ const OPS_ROW = opsProxyRow()
86
+
87
+ /** `X-Fabrika-Endpoint` of the composed ops row, the only value an ops request may carry (ADR-0022 rule 3). */
88
+ export const OPS_ENDPOINT = formatEndpointHeader(OPS_ROW.id, OPS_ROW.digest)
89
+
90
+ /** A view with no data but one table, through which `admittedTableName` asks the wire's own parser about a name. */
91
+ const ONE_TABLE_VIEW = {
92
+ release: '0.0.0',
93
+ maintenance: { mode: 'open', generation: null, published: false },
94
+ migrations: [],
95
+ scheduler: { alarm: null },
96
+ jobs: [],
97
+ files: [],
98
+ webhooks: [],
99
+ bootFailure: null,
100
+ }
101
+
102
+ /** The migration ledger `@fabrika/db/sqlite-migrate` keeps in the object's SQLite. */
103
+ const MIGRATION_LEDGER = 'fabrika_migrations'
104
+
105
+ /** What the platform wrote for the ops channel: the key digests and the objects a request may name. */
106
+ export interface OpsAccess {
107
+ readonly digests: readonly Uint8Array[]
108
+ readonly objects: ApplicationObjects
109
+ }
110
+
111
+ /** The environment's ops access, or `null` (an older deploy, or a malformed value), which refuses every ops request. */
112
+ export function opsAccess(env: Readonly<Record<string, unknown>>): OpsAccess | null {
113
+ const digests = parseOpsKeyDigests(stringOf(env[FABRIKA_OPS_KEY_DIGESTS]) ?? '')
114
+ const objects = parseApplicationObjects(stringOf(env[FABRIKA_APPLICATION_OBJECT]), stringOf(env[FABRIKA_APPLICATION_OBJECTS]))
115
+ if (digests === null || objects === null) {
116
+ return null
117
+ }
118
+ return { digests: digests.map((digest) => new TextEncoder().encode(digest)), objects }
119
+ }
120
+
121
+ /** What an ops request reads of the object it reached. */
122
+ export interface OpsTarget {
123
+ readonly storage: OpsStorage & SqliteStorage
124
+ /** The environment's bucket (the `FABRIKA_FILES` R2 binding), where dumps and the maintenance state live. */
125
+ readonly bucket: unknown
126
+ readonly recovery: OpsRecovery | null
127
+ /** The digest of the contract this release was deployed with (`FABRIKA_CONTRACT_DIGEST`); a dump's manifest records it. */
128
+ readonly contractDigest: string | null
129
+ /** The release's migration bundles in the order the object applies them: the framework's, then the application's. */
130
+ readonly migrations: readonly SqliteMigrationBundle[]
131
+ /**
132
+ * The instance's last failed boot, the application's error text included. Asked only after authentication: it
133
+ * waits for a boot under way and never starts one.
134
+ */
135
+ bootFailure(): Promise<OpsBootFailureContent | null>
136
+ /** The barrier of the object named `object`, read from R2 on a cold start; rejects while R2 cannot be read. */
137
+ maintenance(object: string): Promise<MaintenanceBarrier>
138
+ /** Runs the pending migrations and boots the application; `false` when the boot failed. */
139
+ migrate(): Promise<boolean>
140
+ }
141
+
142
+ /**
143
+ * Answers an ops request the Worker forwarded with the proxy secret, which the object checked before. Authentication
144
+ * runs first; an unknown operation, a malformed body and an object name the list lacks are refused after it. Every
145
+ * operation needs the barrier, so while R2 cannot be read each answers 503.
146
+ */
147
+ export async function serveOps(request: Request, access: OpsAccess | null, target: OpsTarget): Promise<Response> {
148
+ if (access === null || !opsAuthenticated(request, access)) {
149
+ return opsRefusal()
150
+ }
151
+ const operation = parseOpsOperation(new URL(request.url).pathname)
152
+ if (operation === null) {
153
+ return opsRefusal()
154
+ }
155
+ const body = await jsonBody(request)
156
+ const object = objectNamed(operation, body)
157
+ if (object === null || !access.objects.objects.includes(object)) {
158
+ return opsRefusal()
159
+ }
160
+ let barrier: MaintenanceBarrier
161
+ try {
162
+ barrier = await target.maintenance(object)
163
+ } catch {
164
+ return new Response(null, { status: 503 })
165
+ }
166
+ switch (operation) {
167
+ case 'inspect': {
168
+ const inspect = parseOpsInspectRequest(body)
169
+ return inspect === null ? opsRefusal() : jsonResponse(await inspectView(target, barrier, inspect.content), 200)
170
+ }
171
+ case 'state': {
172
+ const transition = parseOpsStateRequest(body)
173
+ const { kv } = target.storage
174
+ // ADR-0070 §6: an object that holds an import marker never leaves `inspect`.
175
+ const frozen = () => kv !== undefined && importInProgress({ kv })
176
+ return transition === null ? opsRefusal() : transitionAnswer(await barrier.transition(transition, frozen))
177
+ }
178
+ case 'migrate': {
179
+ const migration = parseOpsMigrateRequest(body)
180
+ return migration === null ? opsRefusal() : await migrateAnswer(target, barrier, migration.generation)
181
+ }
182
+ case 'export': {
183
+ const step = parseOpsExportRequest(body)
184
+ return step === null ? opsRefusal() : await serveExport(target, barrier, step)
185
+ }
186
+ case 'import': {
187
+ const step = parseOpsImportRequest(body)
188
+ return step === null ? opsRefusal() : await serveImport(target, barrier, step, access.objects.object)
189
+ }
190
+ case 'restore': {
191
+ const step = parseOpsRestoreRequest(body)
192
+ return step === null ? opsRefusal() : await serveRestore(target, barrier, step, object === access.objects.object)
193
+ }
194
+ case 'timers': {
195
+ const timers = parseOpsTimersRequest(body)
196
+ return timers === null ? opsRefusal() : serveTimers(timers)
197
+ }
198
+ }
199
+ }
200
+
201
+ /** A transition's answer: the acknowledgement, the 409 naming what is published, or a 503 that Control retries. */
202
+ function transitionAnswer(result: TransitionResult): Response {
203
+ switch (result.kind) {
204
+ case 'acknowledged':
205
+ return jsonResponse(result.ack, 200)
206
+ case 'stale':
207
+ return staleRefusal(result.published)
208
+ case 'failed':
209
+ return new Response(null, { status: 503 })
210
+ case 'frozen': {
211
+ const refusal: OpsDataRefusal = { refused: 'wrong_mode', table: null }
212
+ return jsonResponse(refusal, OPS_DATA_REFUSED_STATUS)
213
+ }
214
+ }
215
+ }
216
+
217
+ /** Runs the migrations under the published generation and acknowledges with the new ledger; a failed boot is a 500. */
218
+ async function migrateAnswer(target: OpsTarget, barrier: MaintenanceBarrier, generation: number): Promise<Response> {
219
+ const result = await barrier.migrate(generation, () => target.migrate())
220
+ if (result.kind === 'stale') {
221
+ return staleRefusal(result.published)
222
+ }
223
+ if (!result.value) {
224
+ return new Response(null, { status: 500 })
225
+ }
226
+ const migrations = tableNames(target.storage).includes(MIGRATION_LEDGER) ? migrationLedger(target.storage) : []
227
+ const ack = parseOpsMigrateAck({ generation, migrations })
228
+ if (ack === null) {
229
+ throw new Error("the object's migration ledger does not parse as the wire's acknowledgement")
230
+ }
231
+ return jsonResponse(ack, 200)
232
+ }
233
+
234
+ function staleRefusal(published: OpsPublishedState | null): Response {
235
+ const refusal: OpsStaleRefusal = { refused: 'stale_generation', published }
236
+ return jsonResponse(refusal, OPS_STALE_STATUS)
237
+ }
238
+
239
+ /** The object an ops request names, read with its operation's strict parser; `null` for a body that does not parse. */
240
+ export function objectNamed(operation: OpsOperation, body: unknown): string | null {
241
+ switch (operation) {
242
+ case 'inspect':
243
+ return parseOpsInspectRequest(body)?.object ?? null
244
+ case 'state':
245
+ return parseOpsStateRequest(body)?.object ?? null
246
+ case 'migrate':
247
+ return parseOpsMigrateRequest(body)?.object ?? null
248
+ case 'export':
249
+ return parseOpsExportRequest(body)?.object ?? null
250
+ case 'import':
251
+ return parseOpsImportRequest(body)?.object ?? null
252
+ case 'restore':
253
+ return parseOpsRestoreRequest(body)?.object ?? null
254
+ case 'timers':
255
+ return parseOpsTimersRequest(body)?.object ?? null
256
+ }
257
+ }
258
+
259
+ /** The request's body as JSON, or `undefined` when it is none: every parser refuses `undefined`. */
260
+ export async function jsonBody(request: { text(): Promise<string> }): Promise<unknown> {
261
+ try {
262
+ return JSON.parse(await request.text())
263
+ } catch {
264
+ return undefined
265
+ }
266
+ }
267
+
268
+ /**
269
+ * Control's credentials on an ops request: the row's method, its endpoint header, and a key whose digest is one the
270
+ * platform wrote, compared in constant time. The Worker and the object both run it; it reads nothing the body names.
271
+ */
272
+ export function opsAuthenticated(request: Request, access: OpsAccess): boolean {
273
+ if (request.method !== OPS_METHOD || request.headers.get(ENDPOINT_HEADER) !== OPS_ENDPOINT) {
274
+ return false
275
+ }
276
+ const authorization = request.headers.get('Authorization') ?? ''
277
+ const key = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : ''
278
+ if (key === '') {
279
+ return false
280
+ }
281
+ const presented = new TextEncoder().encode(opsKeyDigest(key))
282
+ let matched = false
283
+ for (const digest of access.digests) {
284
+ // Every digest is compared, so the answer's timing does not say which one matched.
285
+ if (timingSafeEqual(presented, digest)) {
286
+ matched = true
287
+ }
288
+ }
289
+ return matched
290
+ }
291
+
292
+ /**
293
+ * The view of the object's storage, read and never written. A table the framework has not created yet (a boot that
294
+ * failed before its migrations) reads as empty. What the storage holds is parsed by the wire's own parser.
295
+ */
296
+ async function inspectView(target: OpsTarget, barrier: MaintenanceBarrier, content: boolean): Promise<OpsView | OpsContentView> {
297
+ const { storage } = target
298
+ const bootFailure = await target.bootFailure()
299
+ const tables = tableNames(storage)
300
+ const has = (name: string) => tables.includes(name)
301
+ const alarm = storage.getAlarm === undefined ? missing('getAlarm') : await storage.getAlarm()
302
+ const view = {
303
+ release: appPackage.version,
304
+ maintenance: barrier.view(),
305
+ database: {
306
+ sizeBytes: storage.sql.databaseSize ?? missing('sql.databaseSize'),
307
+ tables: tables.filter(admittedTableName).map((name) => ({ name, rows: cappedCount(storage, name) })),
308
+ },
309
+ migrations: has(MIGRATION_LEDGER) ? migrationLedger(storage) : [],
310
+ scheduler: { alarm: alarm === null ? null : new Date(alarm).toISOString() },
311
+ jobs: has(JOB_LEASES_TABLE)
312
+ ? rows(
313
+ storage,
314
+ `select job, last_status as lastStatus, last_started_at as lastStartedAt, last_finished_at as lastFinishedAt,
315
+ last_duration_ms as lastDurationMs from ${JOB_LEASES_TABLE} order by job`,
316
+ )
317
+ : [],
318
+ files: has(FILES_TABLE)
319
+ ? rows(storage, `select kind, status, count(*) as count from ${FILES_TABLE} group by kind, status order by kind, status`)
320
+ : [],
321
+ webhooks: has(WEBHOOK_BINDINGS_TABLE) && has(WEBHOOK_DELIVERIES_TABLE)
322
+ ? rows(
323
+ storage,
324
+ `select b.webhook as webhook, case when d.lease_until is null then 'completed' else 'claimed' end as state, count(*) as count
325
+ from ${WEBHOOK_DELIVERIES_TABLE} d join ${WEBHOOK_BINDINGS_TABLE} b on b.id = d.binding_id
326
+ group by 1, 2 order by 1, 2`,
327
+ )
328
+ : [],
329
+ bootFailure: content || bootFailure === null ? bootFailure : { at: bootFailure.at },
330
+ }
331
+ const parsed = content ? parseOpsContentView(view) : parseOpsView(view)
332
+ if (parsed === null) {
333
+ throw new Error("the object's ops view does not parse as the wire's view")
334
+ }
335
+ return parsed
336
+ }
337
+
338
+ /** The ledger `@fabrika/db/sqlite-migrate` keeps, as the wire names its rows; read only once the table exists. */
339
+ function migrationLedger(storage: OpsStorage): Record<string, SqliteValue>[] {
340
+ return rows(storage, `select bundle, name, checksum, applied_at as appliedAt from ${MIGRATION_LEDGER} order by bundle, name`)
341
+ }
342
+
343
+ /** Cloudflare's own `_cf_*` tables and SQLite's `sqlite_*` are no table of the application or the framework. */
344
+ function tableNames(storage: OpsStorage): string[] {
345
+ return storage.sql.exec(
346
+ `select name from sqlite_schema where type = 'table' and name not like '\\_cf\\_%' escape '\\' and name not like 'sqlite\\_%' escape '\\'
347
+ order by name`,
348
+ ).toArray().flatMap((row) => typeof row['name'] === 'string' ? [row['name']] : [])
349
+ }
350
+
351
+ /**
352
+ * Whether the view admits `name`. A table SQLite allows but the wire does not (`"MixedCase"`, from a raw migration) is
353
+ * left out, so one such table never takes the whole view down with it.
354
+ */
355
+ function admittedTableName(name: string): boolean {
356
+ return parseOpsView({ ...ONE_TABLE_VIEW, database: { sizeBytes: 0, tables: [{ name, rows: 0 }] } }) !== null
357
+ }
358
+
359
+ /** At most `OPS_ROW_COUNT_CAP`: a full count bills every row read. */
360
+ function cappedCount(storage: OpsStorage, table: string): unknown {
361
+ const quoted = `"${table.replaceAll('"', '""')}"`
362
+ return storage.sql.exec(`select count(*) as count from (select 1 from ${quoted} limit ${OPS_ROW_COUNT_CAP})`).toArray()[0]?.['count']
363
+ }
364
+
365
+ function rows(storage: OpsStorage, query: string): Record<string, SqliteValue>[] {
366
+ return storage.sql.exec(query).toArray()
367
+ }
368
+
369
+ function missing(member: string): never {
370
+ throw new Error(`the object's storage has no ${member}; a Durable Object's storage has it`)
371
+ }
372
+
373
+ function stringOf(value: unknown): string | undefined {
374
+ return typeof value === 'string' ? value : undefined
375
+ }
@@ -0,0 +1,172 @@
1
+ // The stored files of an application environment in its R2 bucket (`FABRIKA_FILES`, ADR-0065 §6): the
2
+ // `FileObjectStore` port, as the S3 store serves it on Zerops. A version is the object's etag.
3
+
4
+ import { type FileObjectStore, ObjectExistsError, type ObjectMetadata, ObjectTooLargeError, type StoredObject } from '@fabrika/platform'
5
+ import { method } from './bindings.js'
6
+
7
+ /**
8
+ * R2 stores a stream only when its length is known up front, which an upload's is not. A body up to this size is
9
+ * buffered and written in one conditional put; a longer one goes up in parts of this size, so an object holds at most
10
+ * one part in memory. R2 takes parts of at least 5 MiB, all but the last of one size.
11
+ */
12
+ export const R2_PART_BYTES = 8 * 1024 * 1024
13
+
14
+ interface R2Info {
15
+ readonly size: number
16
+ readonly etag: string
17
+ readonly contentType: string | null
18
+ readonly body: ReadableStream<Uint8Array> | null
19
+ }
20
+
21
+ /** An R2 answer's object, or `null` for anything else. */
22
+ function infoOf(value: unknown): R2Info | null {
23
+ if (typeof value !== 'object' || value === null) {
24
+ return null
25
+ }
26
+ const size: unknown = Reflect.get(value, 'size')
27
+ const etag: unknown = Reflect.get(value, 'etag')
28
+ if (typeof size !== 'number' || !Number.isSafeInteger(size) || typeof etag !== 'string' || etag === '') {
29
+ return null
30
+ }
31
+ const metadata: unknown = Reflect.get(value, 'httpMetadata')
32
+ const type: unknown = typeof metadata === 'object' && metadata !== null ? Reflect.get(metadata, 'contentType') : undefined
33
+ const body: unknown = 'body' in value ? Reflect.get(value, 'body') : null
34
+ return { size, etag, contentType: typeof type === 'string' && type !== '' ? type : null, body: body instanceof ReadableStream ? body : null }
35
+ }
36
+
37
+ function required(binding: unknown, name: string): (...args: unknown[]) => unknown {
38
+ const found = method(binding, name)
39
+ if (found === null) {
40
+ throw new Error(`the FABRIKA_FILES binding has no ${name}; it is an R2 bucket`)
41
+ }
42
+ return found
43
+ }
44
+
45
+ function joined(chunks: readonly Uint8Array[], length: number): Uint8Array {
46
+ const bytes = new Uint8Array(length)
47
+ let offset = 0
48
+ for (const chunk of chunks) {
49
+ bytes.set(chunk, offset)
50
+ offset += chunk.byteLength
51
+ }
52
+ return bytes
53
+ }
54
+
55
+ interface MultipartUpload {
56
+ uploadPart(bytes: Uint8Array): Promise<void>
57
+ complete(): Promise<void>
58
+ abort(): Promise<void>
59
+ }
60
+
61
+ async function multipartUpload(bucket: unknown, key: string, contentType: string): Promise<MultipartUpload> {
62
+ const upload: unknown = await required(bucket, 'createMultipartUpload')(key, { httpMetadata: { contentType } })
63
+ const parts: { readonly partNumber: number; readonly etag: string }[] = []
64
+ return {
65
+ async uploadPart(bytes) {
66
+ const partNumber = parts.length + 1
67
+ const uploaded: unknown = await required(upload, 'uploadPart')(partNumber, bytes)
68
+ const etag: unknown = typeof uploaded === 'object' && uploaded !== null ? Reflect.get(uploaded, 'etag') : undefined
69
+ if (typeof etag !== 'string') {
70
+ throw new Error('R2 answered a part upload without its etag')
71
+ }
72
+ parts.push({ partNumber, etag })
73
+ },
74
+ async complete() {
75
+ await required(upload, 'complete')(parts)
76
+ },
77
+ async abort() {
78
+ await required(upload, 'abort')()
79
+ },
80
+ }
81
+ }
82
+
83
+ /** `bucket` (an R2 binding) as the files' object store, or `undefined` when the environment binds none. */
84
+ export function r2FileObjectStore(bucket: unknown): FileObjectStore | undefined {
85
+ if (!['head', 'get', 'put', 'delete'].every((name) => method(bucket, name) !== null)) {
86
+ return undefined
87
+ }
88
+ const head = required(bucket, 'head')
89
+ const get = required(bucket, 'get')
90
+ const put = required(bucket, 'put')
91
+ const remove = required(bucket, 'delete')
92
+
93
+ const stored = (answer: unknown): StoredObject | null => {
94
+ const info = infoOf(answer)
95
+ // An object without a body is R2's answer to a failed condition: the object was replaced.
96
+ if (info === null || info.body === null) {
97
+ return null
98
+ }
99
+ return { size: info.size, contentType: info.contentType, version: info.etag, body: info.body }
100
+ }
101
+ const stopped = (signal: AbortSignal | undefined): void => {
102
+ if (signal?.aborted === true) {
103
+ throw new Error('the object read was stopped')
104
+ }
105
+ }
106
+
107
+ return {
108
+ async write(key, body, options): Promise<ObjectMetadata> {
109
+ // A file's key is a fresh UUID behind a unique row; the conditional put refuses a reused key atomically, and
110
+ // this check refuses one before a multipart upload, which takes no condition.
111
+ if ((await head(key)) !== null) {
112
+ await body.cancel()
113
+ throw new ObjectExistsError()
114
+ }
115
+ const httpMetadata = { contentType: options.contentType }
116
+ const reader = body.getReader()
117
+ const pending: Uint8Array[] = []
118
+ let buffered = 0
119
+ let size = 0
120
+ let upload: MultipartUpload | null = null
121
+ try {
122
+ for (;;) {
123
+ const { done, value } = await reader.read()
124
+ if (done) {
125
+ break
126
+ }
127
+ size += value.byteLength
128
+ if (size > options.maxBytes) {
129
+ await reader.cancel()
130
+ throw new ObjectTooLargeError(options.maxBytes)
131
+ }
132
+ pending.push(value)
133
+ buffered += value.byteLength
134
+ while (buffered >= R2_PART_BYTES) {
135
+ const all = joined(pending, buffered)
136
+ pending.length = 0
137
+ pending.push(all.subarray(R2_PART_BYTES))
138
+ buffered -= R2_PART_BYTES
139
+ upload ??= await multipartUpload(bucket, key, options.contentType)
140
+ await upload.uploadPart(all.subarray(0, R2_PART_BYTES))
141
+ }
142
+ }
143
+ const rest = joined(pending, buffered)
144
+ if (upload === null) {
145
+ if ((await put(key, rest, { httpMetadata, onlyIf: { etagDoesNotMatch: '*' } })) === null) {
146
+ throw new ObjectExistsError()
147
+ }
148
+ } else {
149
+ if (rest.byteLength > 0) {
150
+ await upload.uploadPart(rest)
151
+ }
152
+ await upload.complete()
153
+ }
154
+ } catch (error) {
155
+ await upload?.abort().catch(() => undefined)
156
+ throw error
157
+ }
158
+ return { size, contentType: options.contentType }
159
+ },
160
+ async read(key, signal) {
161
+ stopped(signal)
162
+ return stored(await get(key))
163
+ },
164
+ async readVersion(key, version, signal) {
165
+ stopped(signal)
166
+ return stored(await get(key, { onlyIf: { etagMatches: version } }))
167
+ },
168
+ async delete(key) {
169
+ await remove(key)
170
+ },
171
+ }
172
+ }