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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/package.json +9 -9
  2. package/skill/SKILL.md +21 -17
  3. package/skill/references/app-setup.md +42 -11
  4. package/skill/references/endpoint.md +29 -22
  5. package/skill/references/errors.md +32 -31
  6. package/skill/references/jobs.md +22 -3
  7. package/skill/references/tests.md +29 -1
  8. package/src/build.ts +6 -1
  9. package/src/bun.ts +168 -5
  10. package/src/cloudflare/application.ts +546 -76
  11. package/src/cloudflare/bindings.ts +26 -5
  12. package/src/cloudflare/export.ts +621 -0
  13. package/src/cloudflare/import.ts +1097 -0
  14. package/src/cloudflare/maintenance.ts +518 -0
  15. package/src/cloudflare/names.ts +6 -0
  16. package/src/cloudflare/ops.ts +147 -18
  17. package/src/cloudflare/restore.ts +167 -0
  18. package/src/cloudflare/tracker.ts +192 -0
  19. package/src/cloudflare.ts +3 -2
  20. package/src/contract/artifact-schema.ts +13 -2
  21. package/src/contract/build.ts +38 -11
  22. package/src/contract/context.ts +26 -9
  23. package/src/contract/defaults.ts +22 -2
  24. package/src/contract/define.ts +1 -1
  25. package/src/contract/group.ts +10 -1
  26. package/src/contract/kit.ts +2 -1
  27. package/src/disk-assets.ts +8 -3
  28. package/src/files/kinds.ts +54 -24
  29. package/src/implement/anonymous.ts +1 -10
  30. package/src/implement/boot.ts +30 -12
  31. package/src/implement/capability.ts +3 -0
  32. package/src/implement/dispatch.ts +175 -37
  33. package/src/implement/egress.ts +367 -8
  34. package/src/implement/invocation.ts +60 -19
  35. package/src/implement/workload.ts +18 -3
  36. package/src/jobs/runner.ts +646 -98
  37. package/src/spa-fallback.ts +12 -0
  38. package/src/testing/endpoint-access.ts +135 -23
  39. package/src/testing/isolation.ts +8 -1
  40. package/src/testing/kit.ts +60 -0
  41. package/types/src/build.d.ts +1 -1
  42. package/types/src/bun.d.ts +34 -1
  43. package/types/src/cloudflare/application.d.ts +36 -5
  44. package/types/src/cloudflare/bindings.d.ts +6 -0
  45. package/types/src/cloudflare/export.d.ts +16 -0
  46. package/types/src/cloudflare/import.d.ts +58 -0
  47. package/types/src/cloudflare/maintenance.d.ts +117 -0
  48. package/types/src/cloudflare/names.d.ts +5 -0
  49. package/types/src/cloudflare/ops.d.ts +39 -4
  50. package/types/src/cloudflare/restore.d.ts +9 -0
  51. package/types/src/cloudflare/tracker.d.ts +29 -0
  52. package/types/src/cloudflare.d.ts +2 -1
  53. package/types/src/contract/artifact-schema.d.ts +2 -0
  54. package/types/src/contract/context.d.ts +24 -9
  55. package/types/src/contract/defaults.d.ts +19 -1
  56. package/types/src/contract/define.d.ts +1 -1
  57. package/types/src/contract/group.d.ts +9 -1
  58. package/types/src/contract/kit.d.ts +2 -2
  59. package/types/src/disk-assets.d.ts +4 -1
  60. package/types/src/files/kinds.d.ts +17 -6
  61. package/types/src/implement/anonymous.d.ts +0 -4
  62. package/types/src/implement/boot.d.ts +17 -0
  63. package/types/src/implement/capability.d.ts +2 -0
  64. package/types/src/implement/dispatch.d.ts +33 -1
  65. package/types/src/implement/egress.d.ts +36 -1
  66. package/types/src/implement/invocation.d.ts +20 -10
  67. package/types/src/implement/workload.d.ts +5 -0
  68. package/types/src/jobs/runner.d.ts +63 -2
  69. package/types/src/spa-fallback.d.ts +2 -0
  70. package/types/src/testing/endpoint-access.d.ts +25 -1
  71. package/types/src/testing/isolation.d.ts +1 -1
  72. package/types/src/testing/kit.d.ts +16 -0
package/src/bun.ts CHANGED
@@ -7,22 +7,24 @@
7
7
 
8
8
  import { HttpIamMembership, HttpIamTerminals } from '@fabrika/auth'
9
9
  import type { Database } from '@fabrika/db'
10
- import { isScopedDatabase } from '@fabrika/db/framework'
10
+ import { isScopedDatabase, type Session } from '@fabrika/db/framework'
11
11
  import type { PostgresOptions } from '@fabrika/db/postgres'
12
12
  import type { EmailProviderRegistry } from '@fabrika/email'
13
13
  import { directoryEmailProvider } from '@fabrika/email/directory'
14
14
  import { parseJwks } from '@fabrika/jwks'
15
15
  import type { FileObjectStore } from '@fabrika/platform'
16
16
  import { applicationRuntimeUrl, S3BlobStore } from '@fabrika/platform-node'
17
+ import { lookup } from 'node:dns/promises'
17
18
  import { diskAssets } from './disk-assets.js'
18
19
  import type { FetchService, RequestExecutionContext } from './fetch.js'
19
20
  import { clamscanScanner } from './files/clamscan.js'
20
21
  import { boot, BootError, type IamKeySource } from './implement/boot.js'
22
+ import { REQUEST_BUDGET_MS } from './implement/bounded.js'
21
23
  import { type CrashEvents, environmentCrashReporter, type ProcessCrashKind, reportFatalCrashes, reportWithin } from './implement/crashes.js'
22
24
  import { type CapturedEnvironment, captureEnvironment } from './implement/environment.js'
23
25
  import { type ContractImplementation, isContractImplementation } from './implement/implement.js'
24
26
  import { issuerWorkloadTokens, type WorkloadTokenSource } from './implement/workload.js'
25
- import { JOB_CHECK_INTERVAL_MS, type JobRunOptions, type JobRunResult } from './jobs/runner.js'
27
+ import { type ContractJobs, JOB_CHECK_INTERVAL_MS, type JobRunOptions, type JobRunResult } from './jobs/runner.js'
26
28
  import { makeProcessUndumpable } from './undumpable.js'
27
29
 
28
30
  export { diskAssets } from './disk-assets.js'
@@ -134,6 +136,145 @@ async function loadDataLayer(): Promise<DataLayerOpeners> {
134
136
  /** How long a stopping process waits for the work its requests left running; a kicked run aborts at once. */
135
137
  const SHUTDOWN_DRAIN_MS = 10_000
136
138
 
139
+ /**
140
+ * 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,
141
+ * or the timer's last one), and looking at once would kick its job a second time before that kick took the lease.
142
+ */
143
+ export const WAKE_RETRY_MS = 1_000
144
+
145
+ /**
146
+ * How long after a write projected the timer a refresh that cannot see the projected wake looks again: the write may still
147
+ * be committing, and no transaction that writes a wake outlasts a request's budget.
148
+ */
149
+ export const WAKE_SETTLE_MS = REQUEST_BUDGET_MS + 5_000
150
+
151
+ /** A wake a write of this process projected and no refresh has seen yet: its time, and until when the timer looks for it. */
152
+ interface UnseenWake {
153
+ readonly at: number
154
+ readonly until: number
155
+ /** The next look's wait: it doubles from `WAKE_RETRY_MS`. */
156
+ readonly retry: number
157
+ }
158
+
159
+ /**
160
+ * The serving process's one timer to the jobs' next wake, Bun's side of the scheduler (ADR-0065 §5): it kicks each job
161
+ * whose wake came due through the kick path, so the lease admits one container. A write of this process lowers it in
162
+ * that write's transaction (`project`, `BootOptions.projectWakes`), by the delay on the database's clock; a wake another
163
+ * container wrote is found when the serving process refreshes it with its job check. Crontab still runs the schedule.
164
+ */
165
+ export class WakeTimer {
166
+ readonly #track: (kick: Promise<void>) => void
167
+ #jobs: ContractJobs | null = null
168
+ #timer: ReturnType<typeof setTimeout> | undefined
169
+ /** When the armed timer fires, in epoch milliseconds; `Infinity` while none is armed. */
170
+ #at = Number.POSITIVE_INFINITY
171
+ #stopped = false
172
+ /** The refresh under way: one at a time, and a refresh asked for meanwhile looks again after the retry wait. */
173
+ #refreshing: Promise<void> | null = null
174
+ #again = false
175
+ #unseen: UnseenWake | null = null
176
+
177
+ /** `track` holds each kick the timer starts until it ended, for the shutdown drain. */
178
+ constructor(track: (kick: Promise<void>) => void) {
179
+ this.#track = track
180
+ }
181
+
182
+ /** The booted application's jobs; until then nothing fires. */
183
+ attach(jobs: ContractJobs): void {
184
+ this.#jobs = jobs
185
+ }
186
+
187
+ /**
188
+ * `BootOptions.projectWakes`: never later than the next wake the write leaves, which a rollback only makes early. The
189
+ * timer may fire before the write commits, so the wake stays unseen until a refresh finds it.
190
+ */
191
+ readonly project = async (transaction: Session): Promise<void> => {
192
+ const delay = await this.#jobs?.scheduler?.untilNext(transaction)
193
+ if (delay === undefined || delay === null || this.#stopped) {
194
+ return
195
+ }
196
+ const now = Date.now()
197
+ this.#unseen = { at: Math.min(now + delay, this.#unseen?.at ?? Number.POSITIVE_INFINITY), until: now + WAKE_SETTLE_MS, retry: WAKE_RETRY_MS }
198
+ this.#lower(now + delay)
199
+ }
200
+
201
+ /** Kicks every job whose wake is due and arms the timer at the next one; it never rejects. */
202
+ refresh(): Promise<void> {
203
+ if (this.#stopped) {
204
+ return Promise.resolve()
205
+ }
206
+ if (this.#refreshing !== null) {
207
+ this.#again = true
208
+ return this.#refreshing
209
+ }
210
+ const refreshing = this.#refresh().finally(() => {
211
+ this.#refreshing = null
212
+ if (this.#again) {
213
+ this.#again = false
214
+ this.#lower(Date.now())
215
+ }
216
+ })
217
+ this.#refreshing = refreshing
218
+ return refreshing
219
+ }
220
+
221
+ async #refresh(): Promise<void> {
222
+ const jobs = this.#jobs
223
+ if (jobs === null) {
224
+ return
225
+ }
226
+ clearTimeout(this.#timer)
227
+ this.#at = Number.POSITIVE_INFINITY
228
+ const unseen = this.#unseen
229
+ this.#unseen = null
230
+ let delay: number | null
231
+ try {
232
+ delay = await jobs.wake(this.#track)
233
+ } catch {
234
+ // A driver error may quote the database URL.
235
+ console.error('fabrika: the wake timer could not read the jobs: driver_failed')
236
+ delay = 0
237
+ }
238
+ const now = Date.now()
239
+ // A projected wake this refresh did not find: its write may not have committed yet.
240
+ if (unseen !== null && (delay === null || now + delay > unseen.at + WAKE_RETRY_MS) && now < unseen.until) {
241
+ this.#keepUnseen(unseen)
242
+ this.#lower(now + unseen.retry)
243
+ }
244
+ if (delay !== null) {
245
+ this.#lower(now + delay)
246
+ }
247
+ }
248
+
249
+ /** Keeps looking for `unseen`, later next time, beside what writes projected during the refresh. */
250
+ #keepUnseen(unseen: UnseenWake): void {
251
+ const later = this.#unseen
252
+ this.#unseen = {
253
+ at: Math.min(unseen.at, later?.at ?? Number.POSITIVE_INFINITY),
254
+ until: Math.max(unseen.until, later?.until ?? 0),
255
+ retry: unseen.retry * 2,
256
+ }
257
+ }
258
+
259
+ /** Fires no more and refreshes no more; resolves once a refresh under way ended, so it starts no kick after it. */
260
+ async stop(): Promise<void> {
261
+ this.#stopped = true
262
+ clearTimeout(this.#timer)
263
+ await this.#refreshing
264
+ }
265
+
266
+ #lower(next: number): void {
267
+ const now = Date.now()
268
+ const at = next <= now ? now + WAKE_RETRY_MS : next
269
+ if (this.#stopped || at >= this.#at) {
270
+ return
271
+ }
272
+ clearTimeout(this.#timer)
273
+ this.#at = at
274
+ this.#timer = setTimeout(() => void this.refresh(), at - now)
275
+ }
276
+ }
277
+
137
278
  /** Waits for `drain`, at most `ms`; a drain the bound cuts short is logged. */
138
279
  async function drainWithin(drain: Promise<void>, ms: number): Promise<void> {
139
280
  const expired = Promise.withResolvers<void>()
@@ -396,6 +537,11 @@ async function startContractServer(
396
537
  // Zerops is where a Bun application runs, and a namespace there is one private network (ADR-0022 rule 5).
397
538
  const files = openFileStorage(environment.framework)
398
539
  const workloadTokens = workloadTokensOf(environment.framework)
540
+ const timerKicks = new Set<Promise<void>>()
541
+ const wakes = new WakeTimer((kick) => {
542
+ timerKicks.add(kick)
543
+ void kick.finally(() => timerKicks.delete(kick))
544
+ })
399
545
  const served = boot(app, {
400
546
  environment,
401
547
  iam,
@@ -405,33 +551,49 @@ async function startContractServer(
405
551
  membership,
406
552
  terminals,
407
553
  workloadTokens,
554
+ resolveHost,
408
555
  requireProxySecret: true,
409
556
  localEmailProviders: LOCAL_EMAIL_PROVIDERS,
410
557
  connections: databaseConnections(environment.framework[DATABASE_CONNECTIONS]) ?? DEFAULT_DATABASE_CONNECTIONS,
558
+ projectWakes: wakes.project,
411
559
  ...(operationsFetch === undefined ? {} : { operationsFetch }),
412
560
  })
561
+ wakes.attach(served.jobs)
413
562
  // The work a request leaves running (a failure's report, a kicked run) is drained, within a bound, before the database closes.
414
563
  const handler = createBunHandler({ fetch: (request, _env: undefined, exec) => served.fetch(request, exec) }, undefined, {
415
564
  onBackgroundError: () => console.error('fabrika: a background task of a request failed'),
416
565
  })
417
566
  const server = Bun.serve({ port, hostname: '0.0.0.0', fetch: (request) => handler.fetch(request) })
418
- // The crontab may never fire; the serving process notices a job that stopped succeeding without being invoked.
419
- const check = () => void served.jobs.check()
567
+ // The crontab may never fire; the serving process notices a job that stopped succeeding without being invoked, and a
568
+ // wake another container wrote.
569
+ const check = () => {
570
+ void served.jobs.check()
571
+ void wakes.refresh()
572
+ }
420
573
  const checks = served.jobs.names.length === 0 ? undefined : setInterval(check, JOB_CHECK_INTERVAL_MS)
421
574
  if (checks !== undefined) {
422
575
  check()
423
576
  }
424
577
  const stop = async (): Promise<void> => {
425
578
  clearInterval(checks)
579
+ // Before the kicks stop and the drain takes the timer's kicks: a refresh under way may still start one.
580
+ await drainWithin(wakes.stop(), SHUTDOWN_DRAIN_MS)
426
581
  served.stopKicks()
427
582
  await server.stop(false)
428
- await drainWithin(handler.drain(), SHUTDOWN_DRAIN_MS)
583
+ await drainWithin(Promise.all([handler.drain(), ...timerKicks]).then(() => undefined), SHUTDOWN_DRAIN_MS)
429
584
  await database?.close()
430
585
  }
431
586
  process.once('SIGTERM', () => void stop().then(() => process.exit(0)))
432
587
  return { port: server.port ?? port, stop }
433
588
  }
434
589
 
590
+ /**
591
+ * Every address `hostname` resolves to, as the operating system's resolver answers Bun's own `fetch`: a cron job's public
592
+ * egress refuses a hop whose name resolves to any private one (ADR-0071).
593
+ */
594
+ const resolveHost = async (hostname: string): Promise<readonly string[]> =>
595
+ (await lookup(hostname, { all: true, verbatim: true })).map((entry) => entry.address)
596
+
435
597
  /** The application module at `path`, imported when the loader runs; its default export must be what `serve` returned. */
436
598
  export function implementationAt(path: string): ImplementationLoader {
437
599
  return async () => {
@@ -478,6 +640,7 @@ export async function runContractJob(
478
640
  membership,
479
641
  terminals,
480
642
  workloadTokens,
643
+ resolveHost,
481
644
  requireProxySecret: true,
482
645
  localEmailProviders: LOCAL_EMAIL_PROVIDERS,
483
646
  // ClamAV on PATH, as the provider's build installs it for a `scan: true` file kind; missing, the scan fails closed.