@fabrika/app 0.9.0-dev.3 → 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.
Files changed (115) hide show
  1. package/package.json +14 -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 +641 -0
  18. package/src/cloudflare/import.ts +1021 -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 +84 -13
  38. package/src/dev/output.ts +13 -3
  39. package/src/disk-assets.ts +8 -3
  40. package/src/files/archive.ts +2 -2
  41. package/src/files/job-names.ts +12 -0
  42. package/src/files/kinds.ts +73 -31
  43. package/src/files/scan.ts +3 -4
  44. package/src/files/streams.ts +3 -1
  45. package/src/implement/anonymous.ts +12 -11
  46. package/src/implement/boot.ts +75 -6
  47. package/src/implement/bounded.ts +21 -2
  48. package/src/implement/capability.ts +15 -3
  49. package/src/implement/dispatch.ts +419 -177
  50. package/src/implement/failures.ts +17 -1
  51. package/src/implement/faults.ts +1 -0
  52. package/src/implement/index.ts +1 -0
  53. package/src/implement/invocation.ts +58 -10
  54. package/src/implement/principal.ts +25 -2
  55. package/src/implement/terminals.ts +93 -0
  56. package/src/implement/workload.ts +42 -16
  57. package/src/jobs/mail.ts +8 -0
  58. package/src/jobs/report.ts +5 -1
  59. package/src/jobs/runner.ts +672 -113
  60. package/src/jobs/schedule.ts +7 -1
  61. package/src/jobs/scrub.ts +14 -1
  62. package/src/jobs/types.ts +6 -0
  63. package/src/spa-fallback.ts +12 -0
  64. package/src/testing/endpoint-access.ts +307 -152
  65. package/src/testing/isolation.ts +8 -1
  66. package/src/testing/kit.ts +80 -2
  67. package/src/testing/proxy.ts +15 -10
  68. package/types/src/build-recipe.d.ts +70 -0
  69. package/types/src/build.d.ts +19 -1
  70. package/types/src/bun.d.ts +34 -1
  71. package/types/src/cloudflare/application.d.ts +73 -0
  72. package/types/src/cloudflare/bindings.d.ts +33 -0
  73. package/types/src/cloudflare/export.d.ts +16 -0
  74. package/types/src/cloudflare/import.d.ts +51 -0
  75. package/types/src/cloudflare/maintenance.d.ts +117 -0
  76. package/types/src/cloudflare/names.d.ts +11 -0
  77. package/types/src/cloudflare/ops.d.ts +81 -0
  78. package/types/src/cloudflare/r2-files.d.ts +9 -0
  79. package/types/src/cloudflare/restore.d.ts +9 -0
  80. package/types/src/cloudflare/tracker.d.ts +29 -0
  81. package/types/src/cloudflare.d.ts +12 -18
  82. package/types/src/contract/app-id.d.ts +2 -0
  83. package/types/src/contract/artifact-schema.d.ts +2 -0
  84. package/types/src/contract/context.d.ts +35 -11
  85. package/types/src/contract/declaration.d.ts +4 -0
  86. package/types/src/contract/defaults.d.ts +19 -1
  87. package/types/src/contract/define.d.ts +20 -3
  88. package/types/src/contract/kit.d.ts +2 -1
  89. package/types/src/contract/platform.d.ts +2 -2
  90. package/types/src/contract/vocabulary.d.ts +9 -7
  91. package/types/src/dev/output.d.ts +8 -2
  92. package/types/src/disk-assets.d.ts +4 -1
  93. package/types/src/files/job-names.d.ts +9 -0
  94. package/types/src/files/kinds.d.ts +21 -14
  95. package/types/src/files/scan.d.ts +1 -3
  96. package/types/src/implement/anonymous.d.ts +2 -4
  97. package/types/src/implement/boot.d.ts +17 -1
  98. package/types/src/implement/bounded.d.ts +11 -1
  99. package/types/src/implement/capability.d.ts +4 -2
  100. package/types/src/implement/dispatch.d.ts +34 -1
  101. package/types/src/implement/failures.d.ts +5 -0
  102. package/types/src/implement/faults.d.ts +1 -0
  103. package/types/src/implement/index.d.ts +1 -0
  104. package/types/src/implement/invocation.d.ts +22 -7
  105. package/types/src/implement/principal.d.ts +6 -1
  106. package/types/src/implement/terminals.d.ts +33 -0
  107. package/types/src/implement/workload.d.ts +5 -0
  108. package/types/src/jobs/runner.d.ts +66 -2
  109. package/types/src/jobs/schedule.d.ts +2 -0
  110. package/types/src/jobs/types.d.ts +6 -0
  111. package/types/src/spa-fallback.d.ts +2 -0
  112. package/types/src/testing/endpoint-access.d.ts +37 -5
  113. package/types/src/testing/isolation.d.ts +1 -1
  114. package/types/src/testing/kit.d.ts +22 -1
  115. package/types/src/testing/proxy.d.ts +4 -4
package/src/bun.ts CHANGED
@@ -5,9 +5,10 @@
5
5
  // contract application is served through `serveContract`, from the generated
6
6
  // entrypoint.
7
7
 
8
- import { HttpIamMembership } from '@fabrika/auth'
9
- import type { Database, PostgresOptions } from '@fabrika/db'
10
- import { isScopedDatabase } from '@fabrika/db/framework'
8
+ import { HttpIamMembership, HttpIamTerminals } from '@fabrika/auth'
9
+ import type { Database } from '@fabrika/db'
10
+ import { isScopedDatabase, type Session } from '@fabrika/db/framework'
11
+ import type { PostgresOptions } from '@fabrika/db/postgres'
11
12
  import type { EmailProviderRegistry } from '@fabrika/email'
12
13
  import { directoryEmailProvider } from '@fabrika/email/directory'
13
14
  import { parseJwks } from '@fabrika/jwks'
@@ -17,11 +18,12 @@ import { diskAssets } from './disk-assets.js'
17
18
  import type { FetchService, RequestExecutionContext } from './fetch.js'
18
19
  import { clamscanScanner } from './files/clamscan.js'
19
20
  import { boot, BootError, type IamKeySource } from './implement/boot.js'
21
+ import { REQUEST_BUDGET_MS } from './implement/bounded.js'
20
22
  import { type CrashEvents, environmentCrashReporter, type ProcessCrashKind, reportFatalCrashes, reportWithin } from './implement/crashes.js'
21
23
  import { type CapturedEnvironment, captureEnvironment } from './implement/environment.js'
22
24
  import { type ContractImplementation, isContractImplementation } from './implement/implement.js'
23
25
  import { issuerWorkloadTokens, type WorkloadTokenSource } from './implement/workload.js'
24
- import { JOB_CHECK_INTERVAL_MS, type JobRunOptions, type JobRunResult } from './jobs/runner.js'
26
+ import { type ContractJobs, JOB_CHECK_INTERVAL_MS, type JobRunOptions, type JobRunResult } from './jobs/runner.js'
25
27
  import { makeProcessUndumpable } from './undumpable.js'
26
28
 
27
29
  export { diskAssets } from './disk-assets.js'
@@ -117,7 +119,7 @@ export interface ContractServer {
117
119
 
118
120
  /**
119
121
  * What the adapter takes from `@fabrika/db` before the application loads, so no application module can stand in for
120
- * it: a replaced `Database.postgres` would receive the database URL.
122
+ * it: a replaced `openPostgres` would receive the database URL.
121
123
  */
122
124
  interface DataLayerOpeners {
123
125
  readonly postgres: (options: PostgresOptions) => Database
@@ -126,13 +128,152 @@ interface DataLayerOpeners {
126
128
 
127
129
  /** Loads `@fabrika/db` before the application: it captures its built-ins and freezes the Kysely compiler at load. */
128
130
  async function loadDataLayer(): Promise<DataLayerOpeners> {
129
- const { Database, applicationSchema } = await import('@fabrika/db')
130
- return { postgres: Database.postgres, applicationSchema }
131
+ const [{ applicationSchema }, { openPostgres }] = await Promise.all([import('@fabrika/db'), import('@fabrika/db/postgres')])
132
+ return { postgres: openPostgres, applicationSchema }
131
133
  }
132
134
 
133
135
  /** How long a stopping process waits for the work its requests left running; a kicked run aborts at once. */
134
136
  const SHUTDOWN_DRAIN_MS = 10_000
135
137
 
138
+ /**
139
+ * How long the wake timer waits for a wake that is already due: such a wake's own kick is under way (the post-commit start,
140
+ * or the timer's last one), and looking at once would kick its job a second time before that kick took the lease.
141
+ */
142
+ export const WAKE_RETRY_MS = 1_000
143
+
144
+ /**
145
+ * How long after a write projected the timer a refresh that cannot see the projected wake looks again: the write may still
146
+ * be committing, and no transaction that writes a wake outlasts a request's budget.
147
+ */
148
+ export const WAKE_SETTLE_MS = REQUEST_BUDGET_MS + 5_000
149
+
150
+ /** A wake a write of this process projected and no refresh has seen yet: its time, and until when the timer looks for it. */
151
+ interface UnseenWake {
152
+ readonly at: number
153
+ readonly until: number
154
+ /** The next look's wait: it doubles from `WAKE_RETRY_MS`. */
155
+ readonly retry: number
156
+ }
157
+
158
+ /**
159
+ * The serving process's one timer to the jobs' next wake, Bun's side of the scheduler (ADR-0065 §5): it kicks each job
160
+ * whose wake came due through the kick path, so the lease admits one container. A write of this process lowers it in
161
+ * that write's transaction (`project`, `BootOptions.projectWakes`), by the delay on the database's clock; a wake another
162
+ * container wrote is found when the serving process refreshes it with its job check. Crontab still runs the schedule.
163
+ */
164
+ export class WakeTimer {
165
+ readonly #track: (kick: Promise<void>) => void
166
+ #jobs: ContractJobs | null = null
167
+ #timer: ReturnType<typeof setTimeout> | undefined
168
+ /** When the armed timer fires, in epoch milliseconds; `Infinity` while none is armed. */
169
+ #at = Number.POSITIVE_INFINITY
170
+ #stopped = false
171
+ /** The refresh under way: one at a time, and a refresh asked for meanwhile looks again after the retry wait. */
172
+ #refreshing: Promise<void> | null = null
173
+ #again = false
174
+ #unseen: UnseenWake | null = null
175
+
176
+ /** `track` holds each kick the timer starts until it ended, for the shutdown drain. */
177
+ constructor(track: (kick: Promise<void>) => void) {
178
+ this.#track = track
179
+ }
180
+
181
+ /** The booted application's jobs; until then nothing fires. */
182
+ attach(jobs: ContractJobs): void {
183
+ this.#jobs = jobs
184
+ }
185
+
186
+ /**
187
+ * `BootOptions.projectWakes`: never later than the next wake the write leaves, which a rollback only makes early. The
188
+ * timer may fire before the write commits, so the wake stays unseen until a refresh finds it.
189
+ */
190
+ readonly project = async (transaction: Session): Promise<void> => {
191
+ const delay = await this.#jobs?.scheduler?.untilNext(transaction)
192
+ if (delay === undefined || delay === null || this.#stopped) {
193
+ return
194
+ }
195
+ const now = Date.now()
196
+ this.#unseen = { at: Math.min(now + delay, this.#unseen?.at ?? Number.POSITIVE_INFINITY), until: now + WAKE_SETTLE_MS, retry: WAKE_RETRY_MS }
197
+ this.#lower(now + delay)
198
+ }
199
+
200
+ /** Kicks every job whose wake is due and arms the timer at the next one; it never rejects. */
201
+ refresh(): Promise<void> {
202
+ if (this.#stopped) {
203
+ return Promise.resolve()
204
+ }
205
+ if (this.#refreshing !== null) {
206
+ this.#again = true
207
+ return this.#refreshing
208
+ }
209
+ const refreshing = this.#refresh().finally(() => {
210
+ this.#refreshing = null
211
+ if (this.#again) {
212
+ this.#again = false
213
+ this.#lower(Date.now())
214
+ }
215
+ })
216
+ this.#refreshing = refreshing
217
+ return refreshing
218
+ }
219
+
220
+ async #refresh(): Promise<void> {
221
+ const jobs = this.#jobs
222
+ if (jobs === null) {
223
+ return
224
+ }
225
+ clearTimeout(this.#timer)
226
+ this.#at = Number.POSITIVE_INFINITY
227
+ const unseen = this.#unseen
228
+ this.#unseen = null
229
+ let delay: number | null
230
+ try {
231
+ delay = await jobs.wake(this.#track)
232
+ } catch {
233
+ // A driver error may quote the database URL.
234
+ console.error('fabrika: the wake timer could not read the jobs: driver_failed')
235
+ delay = 0
236
+ }
237
+ const now = Date.now()
238
+ // A projected wake this refresh did not find: its write may not have committed yet.
239
+ if (unseen !== null && (delay === null || now + delay > unseen.at + WAKE_RETRY_MS) && now < unseen.until) {
240
+ this.#keepUnseen(unseen)
241
+ this.#lower(now + unseen.retry)
242
+ }
243
+ if (delay !== null) {
244
+ this.#lower(now + delay)
245
+ }
246
+ }
247
+
248
+ /** Keeps looking for `unseen`, later next time, beside what writes projected during the refresh. */
249
+ #keepUnseen(unseen: UnseenWake): void {
250
+ const later = this.#unseen
251
+ this.#unseen = {
252
+ at: Math.min(unseen.at, later?.at ?? Number.POSITIVE_INFINITY),
253
+ until: Math.max(unseen.until, later?.until ?? 0),
254
+ retry: unseen.retry * 2,
255
+ }
256
+ }
257
+
258
+ /** Fires no more and refreshes no more; resolves once a refresh under way ended, so it starts no kick after it. */
259
+ async stop(): Promise<void> {
260
+ this.#stopped = true
261
+ clearTimeout(this.#timer)
262
+ await this.#refreshing
263
+ }
264
+
265
+ #lower(next: number): void {
266
+ const now = Date.now()
267
+ const at = next <= now ? now + WAKE_RETRY_MS : next
268
+ if (this.#stopped || at >= this.#at) {
269
+ return
270
+ }
271
+ clearTimeout(this.#timer)
272
+ this.#at = at
273
+ this.#timer = setTimeout(() => void this.refresh(), at - now)
274
+ }
275
+ }
276
+
136
277
  /** Waits for `drain`, at most `ms`; a drain the bound cuts short is logged. */
137
278
  async function drainWithin(drain: Promise<void>, ms: number): Promise<void> {
138
279
  const expired = Promise.withResolvers<void>()
@@ -277,12 +418,22 @@ export function openFileStorage(framework: Readonly<Record<string, string>>): Fi
277
418
  /**
278
419
  * IAM's membership transport, when the platform gives the process `FABRIKA_IAM_RPC_URL` (IAM's public origin) and
279
420
  * `FABRIKA_IAM_RPC_KEY` (this environment's membership transport key); without both, there is none, and `boot` refuses
280
- * a contract that needs one.
421
+ * a contract that needs one. The identifications at a terminal travel on the same transport.
281
422
  */
282
- function httpMembership(framework: Readonly<Record<string, string>>): HttpIamMembership | undefined {
423
+ function httpIamTransport(framework: Readonly<Record<string, string>>): { readonly origin: string; readonly key: string } | undefined {
283
424
  const origin = framework['FABRIKA_IAM_RPC_URL']?.trim() ?? ''
284
425
  const key = framework['FABRIKA_IAM_RPC_KEY']?.trim() ?? ''
285
- return origin === '' || key === '' ? undefined : new HttpIamMembership({ origin, key })
426
+ return origin === '' || key === '' ? undefined : { origin, key }
427
+ }
428
+
429
+ function httpMembership(framework: Readonly<Record<string, string>>): HttpIamMembership | undefined {
430
+ const transport = httpIamTransport(framework)
431
+ return transport === undefined ? undefined : new HttpIamMembership(transport)
432
+ }
433
+
434
+ function httpTerminals(framework: Readonly<Record<string, string>>): HttpIamTerminals | undefined {
435
+ const transport = httpIamTransport(framework)
436
+ return transport === undefined ? undefined : new HttpIamTerminals(transport)
286
437
  }
287
438
 
288
439
  /** IAM's public token exchange, at the issuer every deploy names; `boot` reports a missing issuer itself. */
@@ -381,9 +532,15 @@ async function startContractServer(
381
532
  const iam = issuerJwks(environment.framework['FABRIKA_IAM_ISSUER'])
382
533
  const database = isScopedDatabase(app.database) ? openApplicationDatabase(data, environment.framework) : undefined
383
534
  const membership = httpMembership(environment.framework)
535
+ const terminals = httpTerminals(environment.framework)
384
536
  // Zerops is where a Bun application runs, and a namespace there is one private network (ADR-0022 rule 5).
385
537
  const files = openFileStorage(environment.framework)
386
538
  const workloadTokens = workloadTokensOf(environment.framework)
539
+ const timerKicks = new Set<Promise<void>>()
540
+ const wakes = new WakeTimer((kick) => {
541
+ timerKicks.add(kick)
542
+ void kick.finally(() => timerKicks.delete(kick))
543
+ })
387
544
  const served = boot(app, {
388
545
  environment,
389
546
  iam,
@@ -391,28 +548,37 @@ async function startContractServer(
391
548
  database,
392
549
  files,
393
550
  membership,
551
+ terminals,
394
552
  workloadTokens,
395
553
  requireProxySecret: true,
396
554
  localEmailProviders: LOCAL_EMAIL_PROVIDERS,
397
555
  connections: databaseConnections(environment.framework[DATABASE_CONNECTIONS]) ?? DEFAULT_DATABASE_CONNECTIONS,
556
+ projectWakes: wakes.project,
398
557
  ...(operationsFetch === undefined ? {} : { operationsFetch }),
399
558
  })
559
+ wakes.attach(served.jobs)
400
560
  // The work a request leaves running (a failure's report, a kicked run) is drained, within a bound, before the database closes.
401
561
  const handler = createBunHandler({ fetch: (request, _env: undefined, exec) => served.fetch(request, exec) }, undefined, {
402
562
  onBackgroundError: () => console.error('fabrika: a background task of a request failed'),
403
563
  })
404
564
  const server = Bun.serve({ port, hostname: '0.0.0.0', fetch: (request) => handler.fetch(request) })
405
- // The crontab may never fire; the serving process notices a job that stopped succeeding without being invoked.
406
- const check = () => void served.jobs.check()
565
+ // The crontab may never fire; the serving process notices a job that stopped succeeding without being invoked, and a
566
+ // wake another container wrote.
567
+ const check = () => {
568
+ void served.jobs.check()
569
+ void wakes.refresh()
570
+ }
407
571
  const checks = served.jobs.names.length === 0 ? undefined : setInterval(check, JOB_CHECK_INTERVAL_MS)
408
572
  if (checks !== undefined) {
409
573
  check()
410
574
  }
411
575
  const stop = async (): Promise<void> => {
412
576
  clearInterval(checks)
577
+ // Before the kicks stop and the drain takes the timer's kicks: a refresh under way may still start one.
578
+ await drainWithin(wakes.stop(), SHUTDOWN_DRAIN_MS)
413
579
  served.stopKicks()
414
580
  await server.stop(false)
415
- await drainWithin(handler.drain(), SHUTDOWN_DRAIN_MS)
581
+ await drainWithin(Promise.all([handler.drain(), ...timerKicks]).then(() => undefined), SHUTDOWN_DRAIN_MS)
416
582
  await database?.close()
417
583
  }
418
584
  process.once('SIGTERM', () => void stop().then(() => process.exit(0)))
@@ -454,6 +620,7 @@ export async function runContractJob(
454
620
  try {
455
621
  const workloadTokens = workloadTokensOf(environment.framework)
456
622
  const membership = httpMembership(environment.framework)
623
+ const terminals = httpTerminals(environment.framework)
457
624
  const files = openFileStorage(environment.framework)
458
625
  return await boot(app, {
459
626
  environment,
@@ -462,6 +629,7 @@ export async function runContractJob(
462
629
  database,
463
630
  files,
464
631
  membership,
632
+ terminals,
465
633
  workloadTokens,
466
634
  requireProxySecret: true,
467
635
  localEmailProviders: LOCAL_EMAIL_PROVIDERS,