@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.
- package/package.json +9 -9
- package/skill/SKILL.md +21 -17
- package/skill/references/app-setup.md +42 -11
- package/skill/references/endpoint.md +29 -22
- package/skill/references/errors.md +32 -31
- package/skill/references/jobs.md +22 -3
- package/skill/references/tests.md +29 -1
- package/src/build.ts +6 -1
- package/src/bun.ts +168 -5
- package/src/cloudflare/application.ts +546 -76
- package/src/cloudflare/bindings.ts +26 -5
- package/src/cloudflare/export.ts +621 -0
- package/src/cloudflare/import.ts +1097 -0
- package/src/cloudflare/maintenance.ts +518 -0
- package/src/cloudflare/names.ts +6 -0
- package/src/cloudflare/ops.ts +147 -18
- package/src/cloudflare/restore.ts +167 -0
- package/src/cloudflare/tracker.ts +192 -0
- package/src/cloudflare.ts +3 -2
- package/src/contract/artifact-schema.ts +13 -2
- package/src/contract/build.ts +38 -11
- package/src/contract/context.ts +26 -9
- package/src/contract/defaults.ts +22 -2
- package/src/contract/define.ts +1 -1
- package/src/contract/group.ts +10 -1
- package/src/contract/kit.ts +2 -1
- package/src/disk-assets.ts +8 -3
- package/src/files/kinds.ts +54 -24
- package/src/implement/anonymous.ts +1 -10
- package/src/implement/boot.ts +30 -12
- package/src/implement/capability.ts +3 -0
- package/src/implement/dispatch.ts +175 -37
- package/src/implement/egress.ts +367 -8
- package/src/implement/invocation.ts +60 -19
- package/src/implement/workload.ts +18 -3
- package/src/jobs/runner.ts +646 -98
- package/src/spa-fallback.ts +12 -0
- package/src/testing/endpoint-access.ts +135 -23
- package/src/testing/isolation.ts +8 -1
- package/src/testing/kit.ts +60 -0
- package/types/src/build.d.ts +1 -1
- package/types/src/bun.d.ts +34 -1
- package/types/src/cloudflare/application.d.ts +36 -5
- package/types/src/cloudflare/bindings.d.ts +6 -0
- package/types/src/cloudflare/export.d.ts +16 -0
- package/types/src/cloudflare/import.d.ts +58 -0
- package/types/src/cloudflare/maintenance.d.ts +117 -0
- package/types/src/cloudflare/names.d.ts +5 -0
- package/types/src/cloudflare/ops.d.ts +39 -4
- package/types/src/cloudflare/restore.d.ts +9 -0
- package/types/src/cloudflare/tracker.d.ts +29 -0
- package/types/src/cloudflare.d.ts +2 -1
- package/types/src/contract/artifact-schema.d.ts +2 -0
- package/types/src/contract/context.d.ts +24 -9
- package/types/src/contract/defaults.d.ts +19 -1
- package/types/src/contract/define.d.ts +1 -1
- package/types/src/contract/group.d.ts +9 -1
- package/types/src/contract/kit.d.ts +2 -2
- package/types/src/disk-assets.d.ts +4 -1
- package/types/src/files/kinds.d.ts +17 -6
- package/types/src/implement/anonymous.d.ts +0 -4
- package/types/src/implement/boot.d.ts +17 -0
- package/types/src/implement/capability.d.ts +2 -0
- package/types/src/implement/dispatch.d.ts +33 -1
- package/types/src/implement/egress.d.ts +36 -1
- package/types/src/implement/invocation.d.ts +20 -10
- package/types/src/implement/workload.d.ts +5 -0
- package/types/src/jobs/runner.d.ts +63 -2
- package/types/src/spa-fallback.d.ts +2 -0
- package/types/src/testing/endpoint-access.d.ts +25 -1
- package/types/src/testing/isolation.d.ts +1 -1
- 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
|
-
|
|
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.
|