@fabrika/app 0.9.0-dev.1 → 0.9.0-dev.11

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 (222) hide show
  1. package/package.json +32 -26
  2. package/skill/SKILL.md +46 -15
  3. package/skill/references/app-setup.md +43 -12
  4. package/skill/references/dev.md +5 -2
  5. package/skill/references/endpoint.md +39 -28
  6. package/skill/references/errors.md +50 -37
  7. package/skill/references/files.md +8 -4
  8. package/skill/references/jobs.md +39 -7
  9. package/skill/references/table-and-migration.md +47 -3
  10. package/skill/references/tests.md +73 -16
  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 +888 -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/capability-cases.ts +30 -0
  30. package/src/contract/compile.ts +1 -0
  31. package/src/contract/containers.ts +19 -0
  32. package/src/contract/context.ts +35 -9
  33. package/src/contract/declaration.ts +2 -0
  34. package/src/contract/defaults.ts +27 -4
  35. package/src/contract/define.ts +29 -3
  36. package/src/contract/index.ts +1 -0
  37. package/src/contract/kit.ts +4 -1
  38. package/src/contract/platform.ts +3 -2
  39. package/src/contract/vocabulary.ts +26 -8
  40. package/src/dev/changes.ts +5 -43
  41. package/src/dev/contract-digest.ts +17 -0
  42. package/src/dev/index.ts +1 -1
  43. package/src/dev/launcher.ts +197 -41
  44. package/src/dev/output.ts +13 -3
  45. package/src/dev/wire.ts +11 -1
  46. package/src/disk-assets.ts +8 -3
  47. package/src/files/archive.ts +2 -2
  48. package/src/files/handle.ts +2 -1
  49. package/src/files/job-names.ts +12 -0
  50. package/src/files/kinds.ts +74 -32
  51. package/src/files/scan.ts +3 -4
  52. package/src/files/streams.ts +3 -1
  53. package/src/implement/anonymous.ts +12 -11
  54. package/src/implement/boot.ts +84 -27
  55. package/src/implement/bounded.ts +21 -2
  56. package/src/implement/capability.ts +16 -4
  57. package/src/implement/dispatch.ts +423 -178
  58. package/src/implement/failures.ts +59 -4
  59. package/src/implement/faults.ts +5 -1
  60. package/src/implement/index.ts +1 -0
  61. package/src/implement/invocation.ts +62 -11
  62. package/src/implement/principal.ts +25 -2
  63. package/src/implement/terminals.ts +93 -0
  64. package/src/implement/tokens.ts +4 -2
  65. package/src/implement/types.ts +22 -4
  66. package/src/implement/workload.ts +42 -16
  67. package/src/jobs/mail.ts +8 -0
  68. package/src/jobs/report.ts +5 -1
  69. package/src/jobs/runner.ts +702 -126
  70. package/src/jobs/schedule.ts +7 -1
  71. package/src/jobs/scrub.ts +14 -1
  72. package/src/jobs/types.ts +6 -0
  73. package/src/spa-fallback.ts +12 -0
  74. package/src/testing/endpoint-access.ts +493 -202
  75. package/src/testing/index.ts +1 -1
  76. package/src/testing/isolation.ts +8 -1
  77. package/src/testing/kit.ts +86 -4
  78. package/src/testing/policy-isolation.ts +2 -2
  79. package/src/testing/proxy.ts +15 -10
  80. package/types/src/agent-skill.d.ts +29 -0
  81. package/types/src/build-recipe.d.ts +70 -0
  82. package/types/src/build.d.ts +29 -0
  83. package/types/src/bun.d.ts +99 -0
  84. package/types/src/client/caller.d.ts +19 -0
  85. package/types/src/client/contract.d.ts +131 -0
  86. package/types/src/client/error-reporting.d.ts +66 -0
  87. package/types/src/client/index.d.ts +4 -0
  88. package/types/src/client/rpc.d.ts +14 -0
  89. package/types/src/client/share.d.ts +2 -0
  90. package/types/src/client/transport.d.ts +42 -0
  91. package/types/src/cloudflare/application.d.ts +73 -0
  92. package/types/src/cloudflare/bindings.d.ts +33 -0
  93. package/types/src/cloudflare/export.d.ts +16 -0
  94. package/types/src/cloudflare/import.d.ts +47 -0
  95. package/types/src/cloudflare/maintenance.d.ts +117 -0
  96. package/types/src/cloudflare/names.d.ts +11 -0
  97. package/types/src/cloudflare/ops.d.ts +81 -0
  98. package/types/src/cloudflare/r2-files.d.ts +9 -0
  99. package/types/src/cloudflare/restore.d.ts +9 -0
  100. package/types/src/cloudflare/tracker.d.ts +29 -0
  101. package/types/src/cloudflare.d.ts +43 -0
  102. package/types/src/contract/app-id.d.ts +2 -0
  103. package/types/src/contract/artifact-schema.d.ts +10 -0
  104. package/types/src/contract/attachment.d.ts +41 -0
  105. package/types/src/contract/build.d.ts +12 -0
  106. package/types/src/contract/capability-cases.d.ts +9 -0
  107. package/types/src/contract/compile.d.ts +11 -0
  108. package/types/src/contract/connect.d.ts +51 -0
  109. package/types/src/contract/containers.d.ts +3 -0
  110. package/types/src/contract/context.d.ts +525 -0
  111. package/types/src/contract/declaration.d.ts +307 -0
  112. package/types/src/contract/defaults.d.ts +228 -0
  113. package/types/src/contract/define.d.ts +376 -0
  114. package/types/src/contract/file.d.ts +44 -0
  115. package/types/src/contract/group.d.ts +274 -0
  116. package/types/src/contract/handled.d.ts +18 -0
  117. package/types/src/contract/index.d.ts +20 -0
  118. package/types/src/contract/kit.d.ts +211 -0
  119. package/types/src/contract/platform.d.ts +9 -0
  120. package/types/src/contract/problems.d.ts +14 -0
  121. package/types/src/contract/redirect.d.ts +25 -0
  122. package/types/src/contract/schema-from-shape.d.ts +10 -0
  123. package/types/src/contract/schema-shape.d.ts +5 -0
  124. package/types/src/contract/snapshot-source.d.ts +15 -0
  125. package/types/src/contract/token.d.ts +58 -0
  126. package/types/src/contract/vocabulary.d.ts +32 -0
  127. package/types/src/contract/webhook-binding.d.ts +24 -0
  128. package/types/src/contract/webhook-scheme.d.ts +23 -0
  129. package/types/src/dev/changes.d.ts +7 -0
  130. package/types/src/dev/contract-digest.d.ts +1 -0
  131. package/types/src/dev/index.d.ts +2 -0
  132. package/types/src/dev/launcher.d.ts +32 -0
  133. package/types/src/dev/output.d.ts +28 -0
  134. package/types/src/dev/wire.d.ts +126 -0
  135. package/types/src/disk-assets.d.ts +6 -0
  136. package/types/src/errors.d.ts +46 -0
  137. package/types/src/fetch.d.ts +7 -0
  138. package/types/src/files/archive.d.ts +26 -0
  139. package/types/src/files/clamscan.d.ts +32 -0
  140. package/types/src/files/handle.d.ts +107 -0
  141. package/types/src/files/job-names.d.ts +9 -0
  142. package/types/src/files/kinds.d.ts +112 -0
  143. package/types/src/files/scan.d.ts +78 -0
  144. package/types/src/files/sniff.d.ts +7 -0
  145. package/types/src/files/streams.d.ts +17 -0
  146. package/types/src/files/treatment.d.ts +18 -0
  147. package/types/src/from-row.d.ts +20 -0
  148. package/types/src/honeypot.d.ts +2 -0
  149. package/types/src/implement/anonymous.d.ts +24 -0
  150. package/types/src/implement/attachment.d.ts +14 -0
  151. package/types/src/implement/boot.d.ts +128 -0
  152. package/types/src/implement/bounded.d.ts +32 -0
  153. package/types/src/implement/browser-config.d.ts +19 -0
  154. package/types/src/implement/capability.d.ts +142 -0
  155. package/types/src/implement/challenge.d.ts +75 -0
  156. package/types/src/implement/client-address.d.ts +11 -0
  157. package/types/src/implement/connect.d.ts +67 -0
  158. package/types/src/implement/crashes.d.ts +31 -0
  159. package/types/src/implement/dispatch.d.ts +251 -0
  160. package/types/src/implement/egress.d.ts +14 -0
  161. package/types/src/implement/environment.d.ts +14 -0
  162. package/types/src/implement/failures.d.ts +58 -0
  163. package/types/src/implement/faults.d.ts +48 -0
  164. package/types/src/implement/headers.d.ts +7 -0
  165. package/types/src/implement/implement.d.ts +58 -0
  166. package/types/src/implement/index.d.ts +25 -0
  167. package/types/src/implement/invocation.d.ts +136 -0
  168. package/types/src/implement/membership.d.ts +201 -0
  169. package/types/src/implement/multipart.d.ts +36 -0
  170. package/types/src/implement/params.d.ts +7 -0
  171. package/types/src/implement/principal.d.ts +57 -0
  172. package/types/src/implement/project.d.ts +11 -0
  173. package/types/src/implement/public.d.ts +61 -0
  174. package/types/src/implement/serve.d.ts +25 -0
  175. package/types/src/implement/terminals.d.ts +33 -0
  176. package/types/src/implement/tokens.d.ts +49 -0
  177. package/types/src/implement/types.d.ts +263 -0
  178. package/types/src/implement/urls.d.ts +15 -0
  179. package/types/src/implement/verifiers.d.ts +19 -0
  180. package/types/src/implement/webhook.d.ts +55 -0
  181. package/types/src/implement/workload.d.ts +61 -0
  182. package/types/src/implement/xlsx.d.ts +6 -0
  183. package/types/src/index.d.ts +12 -0
  184. package/types/src/jobs/exception.d.ts +40 -0
  185. package/types/src/jobs/mail.d.ts +67 -0
  186. package/types/src/jobs/report.d.ts +56 -0
  187. package/types/src/jobs/runner.d.ts +218 -0
  188. package/types/src/jobs/schedule.d.ts +17 -0
  189. package/types/src/jobs/scrub.d.ts +12 -0
  190. package/types/src/jobs/types.d.ts +98 -0
  191. package/types/src/react/caller.d.ts +30 -0
  192. package/types/src/react/errors.d.ts +40 -0
  193. package/types/src/react/hooks.d.ts +110 -0
  194. package/types/src/react/index.d.ts +5 -0
  195. package/types/src/react/provider.d.ts +58 -0
  196. package/types/src/react/store.d.ts +68 -0
  197. package/types/src/react/testing.d.ts +28 -0
  198. package/types/src/react/types.d.ts +33 -0
  199. package/types/src/rpc/builder.d.ts +52 -0
  200. package/types/src/rpc/contract.d.ts +23 -0
  201. package/types/src/rpc/dispatcher.d.ts +11 -0
  202. package/types/src/rpc/types.d.ts +62 -0
  203. package/types/src/service/define.d.ts +42 -0
  204. package/types/src/service/index.d.ts +3 -0
  205. package/types/src/service/serve.d.ts +28 -0
  206. package/types/src/spa-fallback.d.ts +2 -0
  207. package/types/src/standard-schema.d.ts +55 -0
  208. package/types/src/testing/caller.d.ts +95 -0
  209. package/types/src/testing/challenge.d.ts +11 -0
  210. package/types/src/testing/dev.d.ts +97 -0
  211. package/types/src/testing/endpoint-access.d.ts +132 -0
  212. package/types/src/testing/index.d.ts +12 -0
  213. package/types/src/testing/isolation.d.ts +3 -0
  214. package/types/src/testing/kit.d.ts +207 -0
  215. package/types/src/testing/membership.d.ts +132 -0
  216. package/types/src/testing/policy-isolation.d.ts +113 -0
  217. package/types/src/testing/preload.d.ts +1 -0
  218. package/types/src/testing/proxy.d.ts +40 -0
  219. package/types/src/testing/runner.d.ts +8 -0
  220. package/types/src/testing/sample-file.d.ts +5 -0
  221. package/types/src/testing/status.d.ts +4 -0
  222. package/types/src/undumpable.d.ts +5 -0
@@ -0,0 +1,17 @@
1
+ // The launcher's child that answers whether a commit changed the contract (ADR-0049). It runs in the application root
2
+ // with no credential in its environment, loads the application module the launcher itself never loads, and prints the
3
+ // digest the application's boot compares with `FABRIKA_CONTRACT_DIGEST`.
4
+
5
+ import { contractDigest } from '@fabrika/auth-core'
6
+ import { join } from 'node:path'
7
+ import { IMPLEMENTATION_FILE } from '../build.js'
8
+ import { compileContract } from '../contract/compile.js'
9
+ import { isContractImplementation } from '../implement/implement.js'
10
+
11
+ const module: unknown = await import(join(process.cwd(), IMPLEMENTATION_FILE))
12
+ const app = typeof module === 'object' && module !== null ? Reflect.get(module, 'default') : undefined
13
+ if (!isContractImplementation(app)) {
14
+ console.error(`${IMPLEMENTATION_FILE} does not default-export serve(contract, { … })`)
15
+ process.exit(1)
16
+ }
17
+ console.log(contractDigest(compileContract(app.contract, app.database?.tables ?? {})))
package/src/dev/index.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  // @fabrika/app/dev — the launcher of a `dev` environment, which the generated dev entrypoint runs (Bun only).
2
2
 
3
- export { bootstrapReason, contractModules, migrationsChanged, webSourceChanged } from './changes.js'
3
+ export { bootstrapReason, migrationsChanged, webSourceChanged } from './changes.js'
4
4
  export {
5
5
  type DevLauncher,
6
6
  type DevLauncherOptions,
@@ -3,16 +3,25 @@
3
3
  // runtime credential only. It holds a long poll on Control's source receiver (ADR-0064); a new head brings the changed
4
4
  // files, which it writes, then it migrates when `db/migrations/` changed, runs the SPA commands when a web source
5
5
  // changed, and respawns the application. A change the build owns is refused with one line: it needs a bootstrap run.
6
+ // A new container migrates and verifies its schema here, not in an init command: only after Control said whether a reset
7
+ // is pending, since the database still holds what the previous container left.
6
8
 
7
- import { DEV_LAUNCHER_CONFIG_FILE, DEV_LAUNCHER_STATE_FILE, type DevLauncherConfig, platformTransportVariables } from '@fabrika/auth-core'
9
+ import {
10
+ DEV_LAUNCHER_BOOTED_FILE,
11
+ DEV_LAUNCHER_CONFIG_FILE,
12
+ DEV_LAUNCHER_STATE_FILE,
13
+ type DevLauncherConfig,
14
+ FABRIKA_CONTRACT_DIGEST,
15
+ platformTransportVariables,
16
+ } from '@fabrika/auth-core'
8
17
  import { applicationRuntimeUrl, dropApplicationDatabase } from '@fabrika/platform-node'
9
- import { existsSync, readFileSync } from 'node:fs'
10
18
  import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
11
19
  import { dirname, join } from 'node:path'
20
+ import { fileURLToPath } from 'node:url'
12
21
  import { z } from 'zod/v4'
13
22
  import { makeProcessUndumpable } from '../undumpable.js'
14
- import { bootstrapReason, migrationsChanged, type SourceReader, webSourceChanged } from './changes.js'
15
- import { OutputRing, type OutputSink, processOutput, readLines } from './output.js'
23
+ import { bootstrapReason, migrationsChanged, webSourceChanged } from './changes.js'
24
+ import { OutputRing, type OutputSink, type OutputStream, processOutput, readLines } from './output.js'
16
25
  import {
17
26
  DEV_SOURCE_REPORT_PATH,
18
27
  DEV_SOURCE_WAIT_MS,
@@ -41,6 +50,9 @@ const STOP_GRACE_MS = 3_000
41
50
  const CHECK_TIMEOUT_MS = 10 * 60_000
42
51
  const CRASH_BACKOFF_MS = [1_000, 2_000, 5_000, 10_000] as const
43
52
  const FORWARDED_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'] as const
53
+ const DIGEST_TIMEOUT_MS = 60_000
54
+ const CONTRACT_DIGEST = /^sha256:[0-9a-f]{64}$/
55
+ const CONTRACT_DIGEST_CHILD = fileURLToPath(new URL('./contract-digest.ts', import.meta.url))
44
56
 
45
57
  const commitSha = z.string().regex(/^[0-9a-f]{40}$/)
46
58
  /** A literal path of unreserved characters, as the provider's readiness probe requests it. */
@@ -82,6 +94,13 @@ async function readState(root: string, config: DevLauncherConfig): Promise<Launc
82
94
  return parsed?.success === true ? parsed.data : { head: config.head, reset: null, checks: null }
83
95
  }
84
96
 
97
+ /**
98
+ * `fabrika db codegen --verify` of the CLI that runs the configured `fabrika db migrate`. The configuration names no
99
+ * command for it, and a key of its own would fail the strict reader of every earlier 0.9 launcher.
100
+ */
101
+ const verifyCommand = (migrate: readonly string[]): readonly string[] | null =>
102
+ migrate.at(-2) === 'db' && migrate.at(-1) === 'migrate' ? [...migrate.slice(0, -1), 'codegen', '--verify'] : null
103
+
85
104
  export interface DevSourceTransport {
86
105
  readonly url: string
87
106
  readonly key: string
@@ -114,13 +133,23 @@ interface RunningApplication {
114
133
 
115
134
  interface CommandResult {
116
135
  readonly exitCode: number | null
136
+ /** The signal that ended the command, when one did: it never exited on its own. */
137
+ readonly signal: string | null
117
138
  readonly lines: readonly string[]
118
139
  }
119
140
 
141
+ /** Bun echoes the script it runs (`$ bun build-web.ts`) on stderr; it names the command, not a failure. */
142
+ const BUN_SCRIPT_ECHO = /^\$ \S/
143
+
120
144
  type SyncOutcome =
121
- | { readonly kind: 'applied'; readonly migrations: boolean; readonly web: boolean }
145
+ | { readonly kind: 'applied'; readonly migrations: boolean; readonly spaFailure: string | null }
122
146
  | { readonly kind: 'refused'; readonly reason: string }
123
147
 
148
+ /** Control answers 409 to the container of a bootstrap run that a newer one replaced. */
149
+ class SupersededError extends Error {}
150
+
151
+ const SUPERSEDED = 'a newer bootstrap run replaced this container; it stops following Control and serves until it is stopped'
152
+
124
153
  const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
125
154
 
126
155
  /** Every value of the environment a log line must never show: the database credentials and every key, secret or token. */
@@ -167,6 +196,10 @@ class Launcher {
167
196
  private crashes = 0
168
197
  private stopped = false
169
198
  private reportFailing = false
199
+ /** A newer bootstrap run replaced this container: it keeps serving until the platform stops it, and asks nothing. */
200
+ private superseded = false
201
+ /** A new container checks the schema types at boot, as a bootstrap does; a restarted one holds synced files instead. */
202
+ private verifyAtBoot = false
170
203
 
171
204
  constructor(private readonly options: DevLauncherOptions) {
172
205
  this.root = options.root
@@ -186,9 +219,25 @@ class Launcher {
186
219
  }
187
220
 
188
221
  async start(): Promise<void> {
222
+ const booted = join(this.root, DEV_LAUNCHER_BOOTED_FILE)
223
+ await rm(booted, { force: true })
189
224
  this.state = await readState(this.root, this.config)
190
- const answer = await this.firstAnswer()
191
- await this.enqueue(() => this.apply(answer ?? { sync: null, reset: this.state.reset ?? 0, checks: this.state.checks ?? 0 }, true))
225
+ const fresh = this.state.reset === null
226
+ this.verifyAtBoot = fresh
227
+ let answer = await this.firstAnswer()
228
+ // A new container's first answer carries the reset generation the previous container applied; the second, any
229
+ // reset still pending, which the boot then runs before it migrates over the previous container's schema.
230
+ if (fresh && answer !== null && !this.superseded) {
231
+ this.state = { ...this.state, reset: answer.reset, checks: answer.checks }
232
+ answer = (await this.firstAnswer()) ?? answer
233
+ }
234
+ const boot = answer ?? { sync: null, reset: this.state.reset ?? 0, checks: this.state.checks ?? 0 }
235
+ try {
236
+ await this.enqueue(() => this.apply(boot, true))
237
+ } finally {
238
+ await mkdir(dirname(booted), { recursive: true })
239
+ await writeFile(booted, '')
240
+ }
192
241
  void this.follow()
193
242
  }
194
243
 
@@ -216,7 +265,12 @@ class Launcher {
216
265
  while (!this.stopped) {
217
266
  try {
218
267
  return await this.wait(false)
219
- } catch {
268
+ } catch (error) {
269
+ if (error instanceof SupersededError) {
270
+ this.say(SUPERSEDED, 'stderr')
271
+ this.superseded = true
272
+ return null
273
+ }
220
274
  if (Date.now() >= deadline) {
221
275
  this.say('Control did not answer at boot; serving the files this container holds', 'stderr')
222
276
  return null
@@ -229,13 +283,18 @@ class Launcher {
229
283
 
230
284
  private async follow(): Promise<void> {
231
285
  let backoff = 1_000
232
- while (!this.stopped) {
286
+ while (!this.stopped && !this.superseded) {
233
287
  let answer: DevWaitAnswer
234
288
  try {
235
289
  answer = await this.wait(true)
236
290
  backoff = 1_000
237
- } catch {
291
+ } catch (error) {
238
292
  if (this.stopped) return
293
+ if (error instanceof SupersededError) {
294
+ this.say(SUPERSEDED, 'stderr')
295
+ this.superseded = true
296
+ return
297
+ }
239
298
  this.say(`the long poll on Control failed; retrying in ${backoff / 1000} s`, 'stderr')
240
299
  await sleep(backoff)
241
300
  backoff = Math.min(backoff * 2, 15_000)
@@ -246,9 +305,19 @@ class Launcher {
246
305
  }
247
306
 
248
307
  private async wait(hold: boolean): Promise<DevWaitAnswer> {
249
- const body = encodeDevWaitRequest({ head: this.state.head, reset: this.state.reset, checks: this.state.checks, hold })
308
+ const body = encodeDevWaitRequest({
309
+ bootstrap: this.config.head,
310
+ head: this.state.head,
311
+ reset: this.state.reset,
312
+ checks: this.state.checks,
313
+ hold,
314
+ })
250
315
  const signal = AbortSignal.any([this.controller.signal, AbortSignal.timeout(DEV_SOURCE_WAIT_MS + 15_000)])
251
316
  const response = await this.fetch(this.request(DEV_SOURCE_WAIT_PATH, body, signal))
317
+ if (response.status === 409) {
318
+ await response.body?.cancel()
319
+ throw new SupersededError()
320
+ }
252
321
  if (!response.ok) throw new Error(`the source receiver answered ${response.status}`)
253
322
  const parsed = parseDevWaitAnswer(await response.json())
254
323
  if (!parsed.ok) throw new Error('the source receiver answered a body this release does not read')
@@ -265,7 +334,9 @@ class Launcher {
265
334
  }
266
335
 
267
336
  private async report(): Promise<void> {
337
+ if (this.superseded) return
268
338
  const body = encodeDevReport({
339
+ bootstrap: this.config.head,
269
340
  head: this.state.head,
270
341
  status: this.status,
271
342
  target: this.target,
@@ -290,7 +361,9 @@ class Launcher {
290
361
  if (this.state.checks === null) this.state = { ...this.state, checks: answer.checks }
291
362
  let changed = boot
292
363
  let migrate = boot
293
- let web = false
364
+ let spaFailure: string | null = null
365
+ const reset = answer.reset > (this.state.reset ?? answer.reset)
366
+ if (answer.sync !== null || reset) this.ring.mark()
294
367
  if (answer.sync !== null) {
295
368
  const outcome = await this.writeSync(answer.sync)
296
369
  if (outcome.kind === 'refused') {
@@ -302,28 +375,32 @@ class Launcher {
302
375
  } else {
303
376
  changed = true
304
377
  migrate ||= outcome.migrations
305
- web = outcome.web
378
+ spaFailure = outcome.spaFailure
306
379
  }
307
380
  }
308
- const reset = answer.reset > (this.state.reset ?? answer.reset)
309
- if (changed || reset) await this.converge({ migrate: migrate || reset, reset, web, resetTo: answer.reset })
381
+ if (changed || reset) {
382
+ await this.converge({ migrate: migrate || reset, verify: (boot && this.verifyAtBoot) || reset, reset, spaFailure, resetTo: answer.reset })
383
+ }
310
384
  if (answer.checks > (this.state.checks ?? answer.checks)) await this.check(answer.checks)
311
385
  }
312
386
 
313
387
  /** Bring the database, the SPA and the running application to the files on disk, then report. */
314
- private async converge(steps: { migrate: boolean; reset: boolean; web: boolean; resetTo: number }): Promise<void> {
388
+ private async converge(
389
+ steps: { migrate: boolean; verify: boolean; reset: boolean; spaFailure: string | null; resetTo: number },
390
+ ): Promise<void> {
315
391
  this.status = steps.reset ? 'resetting' : 'syncing'
316
392
  void this.report()
317
393
  let failure: string | null = null
318
394
  // A migration's ALTER would queue behind the live version's locks, and a reset drops the role it connects as.
319
395
  if (this.provisioningUrl !== null && steps.migrate) await this.stopApplication()
320
396
  if (steps.reset) {
321
- failure = await this.resetDatabase()
397
+ failure = await this.timed('the reset', () => this.resetDatabase())
322
398
  this.state = { ...this.state, reset: steps.resetTo }
323
399
  }
324
- if (failure === null && steps.migrate) failure = await this.migrate()
325
- if (failure === null && steps.web) failure = await this.buildSpa()
326
- const served = await this.restartApplication()
400
+ if (failure === null && steps.migrate) failure = await this.timed('the migration', () => this.migrate())
401
+ if (failure === null && steps.verify) failure = await this.timed('the schema check', () => this.verifySchema())
402
+ if (failure === null) failure = steps.spaFailure
403
+ const served = await this.timed('the restart until healthy', () => this.restartApplication())
327
404
  failure ??= served
328
405
  this.status = failure === null ? 'serving' : 'failed'
329
406
  this.target = null
@@ -332,17 +409,44 @@ class Launcher {
332
409
  await this.report()
333
410
  }
334
411
 
412
+ /** Run one step of a sync and log how long it took: what a slow `apply_changes` is read from. */
413
+ private async timed(step: string, run: () => Promise<string | null>): Promise<string | null> {
414
+ const started = performance.now()
415
+ const failure = await run()
416
+ this.say(`${step} ${failure === null ? 'took' : 'failed after'} ${Math.round(performance.now() - started)} ms`)
417
+ return failure
418
+ }
419
+
335
420
  private async writeSync(sync: DevSync): Promise<SyncOutcome> {
336
421
  if (sync.from !== this.state.head) {
337
422
  return { kind: 'refused', reason: `Control sent changes from ${sync.from}, and this container holds ${this.state.head}; call bind_dev again` }
338
423
  }
339
424
  const paths = sync.files.map((file) => file.path)
340
- const incoming = new Map(sync.files.map((file) => [file.path, file.content]))
341
- const before: SourceReader = (path) => this.readLocal(path)
342
- const after: SourceReader = (path) => incoming.has(path) ? incoming.get(path) ?? null : this.readLocal(path)
343
- const reason = bootstrapReason(paths, before, after)
425
+ const reason = bootstrapReason(paths)
344
426
  if (reason !== null) return { kind: 'refused', reason }
345
- for (const file of sync.files) {
427
+ const previous = await Promise.all(
428
+ sync.files.map(async (file) => ({ path: file.path, content: await readFile(join(this.root, file.path)).catch(() => null) })),
429
+ )
430
+ await this.writeFiles(sync.files)
431
+ const web = this.config.spaBuild.length > 0 && webSourceChanged(paths)
432
+ // The SPA build runs beside the digest: a refusal is rare, and then the build runs again over the restored files.
433
+ const [changedContract, spaFailure] = await Promise.all([this.contractChange(), web ? this.spaBuild() : null])
434
+ if (changedContract !== null) {
435
+ await this.writeFiles(previous)
436
+ if (web) await this.spaBuild()
437
+ return { kind: 'refused', reason: changedContract }
438
+ }
439
+ this.state = { ...this.state, head: sync.to }
440
+ this.say(`synced ${sync.files.length} files to ${sync.to}`)
441
+ return { kind: 'applied', migrations: migrationsChanged(paths), spaFailure }
442
+ }
443
+
444
+ private spaBuild(): Promise<string | null> {
445
+ return this.timed('the SPA build', () => this.buildSpa())
446
+ }
447
+
448
+ private async writeFiles(files: readonly { readonly path: string; readonly content: string | Uint8Array | null }[]): Promise<void> {
449
+ for (const file of files) {
346
450
  const path = join(this.root, file.path)
347
451
  if (file.content === null) {
348
452
  await rm(path, { force: true })
@@ -352,19 +456,37 @@ class Launcher {
352
456
  await writeFile(`${path}.fabrika-dev`, file.content)
353
457
  await rename(`${path}.fabrika-dev`, path)
354
458
  }
355
- this.state = { ...this.state, head: sync.to }
356
- this.say(`synced ${sync.files.length} files to ${sync.to}`)
357
- return { kind: 'applied', migrations: migrationsChanged(paths), web: this.config.spaBuild.length > 0 && webSourceChanged(paths) }
358
459
  }
359
460
 
360
- private readLocal(path: string): string | null {
361
- const absolute = join(this.root, path)
362
- if (!existsSync(absolute)) return null
363
- try {
364
- return readFileSync(absolute, 'utf8')
365
- } catch {
461
+ /**
462
+ * Why the files on disk need a bootstrap run because their contract digest is not the one the bootstrap run deployed,
463
+ * or null. A child computes it: it loads the application module, which the launcher never does, with no credential.
464
+ * A digest it cannot compute is no reason: the respawned application then fails to boot and reports why.
465
+ */
466
+ private async contractChange(): Promise<string | null> {
467
+ const deployed = this.options.environment[FABRIKA_CONTRACT_DIGEST] ?? ''
468
+ if (deployed === '') return null
469
+ const started = performance.now()
470
+ const child = Bun.spawn(['bun', CONTRACT_DIGEST_CHILD], {
471
+ cwd: this.root,
472
+ env: { PATH: this.options.environment['PATH'] ?? '', HOME: this.options.environment['HOME'] ?? '' },
473
+ stdin: 'ignore',
474
+ stdout: 'pipe',
475
+ stderr: 'pipe',
476
+ })
477
+ const timer = setTimeout(() => child.kill('SIGKILL'), DIGEST_TIMEOUT_MS)
478
+ const [stdout, stderr] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited])
479
+ clearTimeout(timer)
480
+ const digest = stdout.trim()
481
+ if (child.exitCode !== 0 || !CONTRACT_DIGEST.test(digest)) {
482
+ for (const line of stderr.split('\n').filter((text) => text.trim() !== '').slice(-5)) this.ring.push('stderr', line)
483
+ this.say('the contract digest could not be computed; the application is respawned and reports why', 'stderr')
366
484
  return null
367
485
  }
486
+ this.say(`contract digest computed in ${Math.round(performance.now() - started)} ms`)
487
+ if (digest === deployed) return null
488
+ return `the change alters the contract (its digest is ${digest}, and the bootstrap run deployed ${deployed}): the proxy table and `
489
+ + 'the approval follow the contract, so that needs a bootstrap run: call bind_dev again'
368
490
  }
369
491
 
370
492
  private async persist(): Promise<void> {
@@ -385,6 +507,19 @@ class Launcher {
385
507
  return `fabrika db migrate failed: ${lastLine(result)}; if an applied migration changed, call reset_dev`
386
508
  }
387
509
 
510
+ /** The committed schema types against the migrated schema, as a bootstrap verifies them: at a new container's boot and after a reset. */
511
+ private async verifySchema(): Promise<string | null> {
512
+ const command = verifyCommand(this.config.migrate)
513
+ if (this.provisioningUrl === null || command === null) return null
514
+ const result = await this.run(command, {
515
+ ...this.commandEnvironment,
516
+ FABRIKA_APP_ID: this.config.appId,
517
+ [PROVISIONING_DATABASE_URL]: this.provisioningUrl,
518
+ })
519
+ if (result.exitCode === 0) return null
520
+ return `fabrika db codegen --verify failed: ${lastLine(result)}; if the database holds another commit's schema, call reset_dev`
521
+ }
522
+
388
523
  private async resetDatabase(): Promise<string | null> {
389
524
  if (this.provisioningUrl === null) return null
390
525
  this.say(`dropping the schema and roles of ${this.config.appId}`)
@@ -400,7 +535,12 @@ class Launcher {
400
535
 
401
536
  private async buildSpa(): Promise<string | null> {
402
537
  for (const command of this.config.spaBuild) {
403
- const result = await this.run(['sh', '-c', command], this.commandEnvironment)
538
+ const result = await this.run(
539
+ ['sh', '-c', command],
540
+ this.commandEnvironment,
541
+ CHECK_TIMEOUT_MS,
542
+ (stream, line) => stream === 'stderr' && BUN_SCRIPT_ECHO.test(line) ? 'stdout' : stream,
543
+ )
404
544
  if (result.exitCode !== 0) return `the SPA command \`${command}\` failed: ${lastLine(result)}`
405
545
  }
406
546
  return null
@@ -413,15 +553,20 @@ class Launcher {
413
553
  const results: DevCheckResult[] = []
414
554
  for (const check of this.config.checks) {
415
555
  this.say(`check ${check.name}: ${check.command}`)
556
+ const started = performance.now()
416
557
  const result = await this.run(['sh', '-c', check.command], this.commandEnvironment, CHECK_TIMEOUT_MS)
558
+ const durationMs = Math.round(performance.now() - started)
559
+ const killed = result.signal === null ? [] : [killedLine(check.name, result.signal, durationMs >= CHECK_TIMEOUT_MS)]
560
+ for (const line of killed) this.say(line, 'stderr')
417
561
  results.push({
418
562
  name: check.name,
419
563
  ok: result.exitCode === 0,
420
564
  exitCode: result.exitCode,
421
- output: result.lines.slice(-CHECK_OUTPUT_LINES).map((line) => line.slice(0, 2_000)),
565
+ durationMs,
566
+ output: [...result.lines.slice(-(CHECK_OUTPUT_LINES - killed.length)), ...killed].map((line) => line.slice(0, 2_000)),
422
567
  })
423
568
  }
424
- this.checkResults = { request, results }
569
+ this.checkResults = { request, head: this.state.head, results }
425
570
  this.state = { ...this.state, checks: request }
426
571
  this.status = before.status
427
572
  this.message = before.message
@@ -430,17 +575,22 @@ class Launcher {
430
575
  }
431
576
 
432
577
  /** Run a command in the root; its output goes to the log, and its lines are returned. */
433
- private async run(argv: readonly string[], env: Record<string, string>, timeoutMs = CHECK_TIMEOUT_MS): Promise<CommandResult> {
578
+ private async run(
579
+ argv: readonly string[],
580
+ env: Record<string, string>,
581
+ timeoutMs = CHECK_TIMEOUT_MS,
582
+ classify: (stream: OutputStream, line: string) => OutputStream = (stream) => stream,
583
+ ): Promise<CommandResult> {
434
584
  const child = Bun.spawn([...argv], { cwd: this.root, env, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
435
585
  const lines: string[] = []
436
- const collect = (stream: 'stdout' | 'stderr') => (line: string) => {
586
+ const collect = (stream: OutputStream) => (line: string) => {
437
587
  lines.push(line)
438
- this.ring.push(stream, line)
588
+ this.ring.push(classify(stream, line), line)
439
589
  }
440
590
  const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs)
441
591
  await Promise.all([readLines(child.stdout, collect('stdout')), readLines(child.stderr, collect('stderr')), child.exited])
442
592
  clearTimeout(timer)
443
- return { exitCode: child.exitCode, lines }
593
+ return { exitCode: child.exitCode, signal: child.signalCode === null ? null : String(child.signalCode), lines }
444
594
  }
445
595
 
446
596
  private async restartApplication(): Promise<string | null> {
@@ -524,6 +674,12 @@ class Launcher {
524
674
  }
525
675
  }
526
676
 
677
+ /** Why a check has no exit code: the launcher's timeout, or a signal from outside, most often the out-of-memory killer. */
678
+ const killedLine = (name: string, signal: string, timedOut: boolean): string =>
679
+ timedOut
680
+ ? `check ${name} was killed (${signal}) after the ${CHECK_TIMEOUT_MS / 60_000}-minute timeout; it failed`
681
+ : `check ${name} was killed (${signal}) before it finished, most likely because the container ran out of memory; it failed`
682
+
527
683
  const lastLine = (result: CommandResult): string => [...result.lines].reverse().find((line) => line.trim() !== '')?.trim() ?? 'no output'
528
684
 
529
685
  /** The process environment with its string values only. */
package/src/dev/output.ts CHANGED
@@ -16,10 +16,14 @@ export const processOutput: OutputSink = {
16
16
  },
17
17
  }
18
18
 
19
- /** The newest `capacity` lines, numbered from 0 since the launcher started, with every known secret value replaced. */
19
+ /**
20
+ * The newest `capacity` lines, numbered from 0 since the launcher started, with every known secret value replaced. A
21
+ * mark starts the lines a report carries: those of the newest sync or reset, and the output after it.
22
+ */
20
23
  export class OutputRing {
21
24
  private readonly lines: DevLogLine[] = []
22
25
  private next = 0
26
+ private marked = 0
23
27
 
24
28
  constructor(private readonly capacity: number, private readonly secrets: readonly string[], private readonly sink: OutputSink) {}
25
29
 
@@ -31,9 +35,15 @@ export class OutputRing {
31
35
  if (this.lines.length > this.capacity) this.lines.shift()
32
36
  }
33
37
 
34
- /** The newest `count` lines, oldest first. */
38
+ /** Report from the next line on: the lines before it belong to an older head. */
39
+ mark(): void {
40
+ this.marked = this.next
41
+ }
42
+
43
+ /** The newest `count` lines since the mark, oldest first. */
35
44
  tail(count: number): DevLogLine[] {
36
- return this.lines.slice(Math.max(0, this.lines.length - count))
45
+ const since = this.lines.filter((line) => line.n >= this.marked)
46
+ return since.slice(Math.max(0, since.length - count))
37
47
  }
38
48
 
39
49
  private redact(text: string): string {
package/src/dev/wire.ts CHANGED
@@ -32,7 +32,14 @@ export function isSourcePath(path: string): boolean {
32
32
 
33
33
  const sourcePath = z.string().refine(isSourcePath, 'not a repository-relative path')
34
34
 
35
+ /**
36
+ * The commit the container's bootstrap run built (`DevLauncherConfig.head`). Control answers only the container of the
37
+ * newest bootstrap run: a container a newer bootstrap replaces still runs for a while, and must not sync or report.
38
+ */
39
+ const bootstrap = commitSha
40
+
35
41
  export const devWaitRequestSchema = z.object({
42
+ bootstrap,
36
43
  /** The commit whose files the container holds now. */
37
44
  head: commitSha,
38
45
  /** The reset generation it applied last; null for a container with no record of one, which adopts the answer's. */
@@ -81,6 +88,7 @@ export const devCheckResultSchema = z.object({
81
88
  name: z.string().min(1).max(64),
82
89
  ok: z.boolean(),
83
90
  exitCode: z.number().int().nullable(),
91
+ durationMs: z.number().int().min(0),
84
92
  /** The last lines of its output. */
85
93
  output: z.array(z.string().max(DEV_REPORT_MAX_LINE_CHARACTERS)).max(DEV_REPORT_MAX_LINES),
86
94
  }).strict()
@@ -88,6 +96,7 @@ export const devCheckResultSchema = z.object({
88
96
  export type DevCheckResult = z.infer<typeof devCheckResultSchema>
89
97
 
90
98
  export const devReportSchema = z.object({
99
+ bootstrap,
91
100
  /** The commit whose files the container holds now. */
92
101
  head: commitSha,
93
102
  status: z.enum(DEV_STATUSES),
@@ -98,7 +107,8 @@ export const devReportSchema = z.object({
98
107
  /** The newest lines of the application's and the launcher's output, oldest first. */
99
108
  log: z.array(devLogLineSchema).max(DEV_REPORT_MAX_LINES),
100
109
  reset: generation.nullable(),
101
- checks: z.object({ request: generation, results: z.array(devCheckResultSchema).max(8) }).strict().nullable(),
110
+ /** The newest check run: the request it answers, the commit whose files it checked, and each check's result. */
111
+ checks: z.object({ request: generation, head: commitSha, results: z.array(devCheckResultSchema).max(8) }).strict().nullable(),
102
112
  }).strict()
103
113
 
104
114
  export type DevReport = z.infer<typeof devReportSchema>
@@ -4,8 +4,12 @@
4
4
  import { rawRequestTarget } from '@fabrika/auth-core'
5
5
  import { join, resolve, sep } from 'node:path'
6
6
  import type { SpaAssets } from './implement/dispatch.js'
7
+ import { isPageRoute } from './spa-fallback.js'
7
8
 
8
- /** Serves each SPA mount from its build directory under `root`; a path that names no file gets the SPA's `index.html`. */
9
+ /**
10
+ * Serves each SPA mount from its build directory under `root`; a page route that names no file gets the SPA's
11
+ * `index.html` (`isPageRoute`), and a missing asset is 404.
12
+ */
9
13
  export function diskAssets(root: string): SpaAssets {
10
14
  return {
11
15
  async serve(mount, request) {
@@ -15,8 +19,9 @@ export function diskAssets(root: string): SpaAssets {
15
19
  // The path is canonical, so every segment decodes and none is `.` or `..`.
16
20
  const file = join(dir, ...relative.split('/').filter((segment) => segment !== '').map((segment) => decodeURIComponent(segment)))
17
21
  const candidate = file.startsWith(`${dir}${sep}`) ? Bun.file(file) : null
18
- const served = candidate !== null && (await candidate.exists()) ? candidate : Bun.file(join(dir, 'index.html'))
19
- if (!(await served.exists())) {
22
+ const found = candidate !== null && (await candidate.exists()) ? candidate : null
23
+ const served = found ?? (isPageRoute(request) ? Bun.file(join(dir, 'index.html')) : null)
24
+ if (served === null || !(await served.exists())) {
20
25
  return new Response('Not found', { status: 404 })
21
26
  }
22
27
  return new Response(served)
@@ -4,7 +4,7 @@
4
4
  // stored or deflated entries, no encryption, a layout in which every byte belongs to an entry or the directory, sizes
5
5
  // and CRCs that match, bounded counts and sizes, and nested ZIPs to a small depth. Any other archive is refused.
6
6
 
7
- import { inflateRawSync } from 'node:zlib'
7
+ import { crc32, inflateRawSync } from 'node:zlib'
8
8
 
9
9
  export const ARCHIVE_LIMITS = {
10
10
  /** Entries of one archive, nested ones counted with their parent's. */
@@ -236,7 +236,7 @@ function unpacked(entry: Entry, data: Uint8Array, budget: Budget): Uint8Array {
236
236
  throw new Refused('malformed')
237
237
  }
238
238
  }
239
- if (content.length !== entry.uncompressed || Bun.hash.crc32(content) !== entry.crc) throw new Refused('malformed')
239
+ if (content.length !== entry.uncompressed || crc32(content) !== entry.crc) throw new Refused('malformed')
240
240
  return content
241
241
  }
242
242
 
@@ -102,7 +102,8 @@ export type StoredFileBody = Uint8Array | ReadableStream<Uint8Array> | Blob
102
102
  /**
103
103
  * `ctx.files.put` and `ctx.files.open`: the stored files of a site (`c.files` kinds). A put stages a file this request
104
104
  * holds; writing its reference into a file column is what keeps it. `open` reads a live file whose reference this
105
- * request holds and may read: an input file, a put, or a file column read under its table's read action.
105
+ * request holds and may read: an input file, a put, or a file column read under its table's read action (or claimed by
106
+ * a job that holds it).
106
107
  */
107
108
  export interface StoredFilesHandle {
108
109
  /** A file of `kind` with these bytes, which must be of `type`; it is pending until a column references it. */
@@ -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 * * * *'