@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
@@ -1,23 +1,107 @@
1
- // `egress`: while a site's handler runs, the global `fetch` reaches only the HTTPS origins the site declares. It stops a
2
- // mistake and makes a bypass conspicuous; it is not a sandbox (ADR-0012 §8): code that kept the `fetch` it found before
3
- // boot, or opens its own sockets, escapes it. The framework's own facilities (mail, connectors, IAM, the object store)
4
- // run outside the site's scope, under their own declarations.
1
+ // `egress`: while a site's handler runs, the global `fetch` reaches only the HTTPS origins the site declares, or, for a
2
+ // cron job that declares `egress: 'public'`, only public hosts (ADR-0071). It stops a mistake and makes a bypass
3
+ // conspicuous; it is not a sandbox (ADR-0012 §8): code that kept the `fetch` it found before boot, or opens its own
4
+ // sockets, escapes it. The framework's own facilities (mail, connectors, IAM, the object store) run outside the site's
5
+ // scope, under their own declarations.
5
6
 
7
+ import {
8
+ type DeclaredEgress,
9
+ FABRIKA_EGRESS_REFUSED_HOSTS,
10
+ isPublicAddress,
11
+ normalizedHost,
12
+ PUBLIC_EGRESS,
13
+ publicEgressRefusal,
14
+ } from '@fabrika/auth-core'
6
15
  import { AsyncLocalStorage } from 'node:async_hooks'
7
16
  import { CapabilityRefusedError } from './capability'
8
17
 
18
+ /** The addresses a host name resolves to, where the runtime exposes resolution: Bun's `node:dns`, never a Worker. */
19
+ export type HostResolver = (hostname: string) => Promise<readonly string[]>
20
+
21
+ /** What public egress refuses beyond what a URL alone shows (`publicEgressRefusal`). */
22
+ export interface PublicEgressRules {
23
+ /** The installation's own hosts, normalized: every host a framework variable names, and `FABRIKA_EGRESS_REFUSED_HOSTS`. */
24
+ readonly refusedHosts: ReadonlySet<string>
25
+ /** Resolves each hop's host before it is sent, so a public name of a private address is refused; `null` on Cloudflare. */
26
+ readonly resolve: HostResolver | null
27
+ }
28
+
29
+ /** What one site's `fetch` reaches: its declared origins, or the rules of public egress. */
30
+ export type SiteEgress = readonly string[] | PublicEgressRules
31
+
32
+ /**
33
+ * The bounds of one request under public egress, the redirects it follows included. The handler's own signal still
34
+ * aborts it sooner (`ctx.signal`, an `AbortSignal.timeout` of its own).
35
+ */
36
+ export const PUBLIC_EGRESS_LIMITS = {
37
+ /** One request, its redirects and the reading of its body included: the abort also stops a body still streaming. */
38
+ timeoutMs: 60_000,
39
+ /** One response's body as the handler reads it; a larger one is refused, by its `Content-Length` or while it streams. */
40
+ maxResponseBytes: 16 * 1024 * 1024,
41
+ /** The redirects one request follows when its `redirect` mode is `follow`, each hop checked again. */
42
+ maxRedirects: 10,
43
+ } as const
44
+
9
45
  interface EgressScope {
10
46
  /** The site, as a refusal names it. */
11
47
  readonly site: string
12
48
  readonly origins: ReadonlySet<string>
49
+ /** Public egress: `null` for a site that declares origins, or none. */
50
+ readonly open: PublicEgressRules | null
13
51
  }
14
52
 
15
53
  const scope = new AsyncLocalStorage<EgressScope>()
16
54
  const guards = new WeakSet<object>()
17
55
 
18
56
  /** Runs a site's handler: every `fetch` it starts reaches only `egress`. */
19
- export function runAsSite<T>(site: string, egress: readonly string[], work: () => Promise<T>): Promise<T> {
20
- return scope.run({ site, origins: new Set(egress) }, work)
57
+ export function runAsSite<T>(site: string, egress: SiteEgress, work: () => Promise<T>): Promise<T> {
58
+ return isOrigins(egress)
59
+ ? scope.run({ site, origins: new Set(egress), open: null }, work)
60
+ : scope.run({ site, origins: new Set(), open: egress }, work)
61
+ }
62
+
63
+ /**
64
+ * The egress a site runs with: its declared origins, or `rules` for `'public'`. Only a cron job's runner holds rules; a
65
+ * site run without them reaches nothing, though the build lets no other site declare `'public'`.
66
+ */
67
+ export function siteEgress(declared: DeclaredEgress, rules: PublicEgressRules | null): SiteEgress {
68
+ return declared === PUBLIC_EGRESS ? (rules ?? []) : declared
69
+ }
70
+
71
+ function isOrigins(egress: SiteEgress): egress is readonly string[] {
72
+ return Array.isArray(egress)
73
+ }
74
+
75
+ /**
76
+ * The rules of public egress in one environment: the hosts its framework variables name (IAM, Operations, its own
77
+ * origin, the platform's receivers, the object store), the installation hosts Control hands it, and the resolver the
78
+ * runtime adapter supplies.
79
+ */
80
+ export function publicEgressRules(framework: Readonly<Record<string, string>>, resolve: HostResolver | null): PublicEgressRules {
81
+ const hosts = new Set<string>()
82
+ for (const [name, value] of Object.entries(framework)) {
83
+ if (name === FABRIKA_EGRESS_REFUSED_HOSTS) {
84
+ for (const host of value.split(',')) {
85
+ const normalized = normalizedHost(host.trim())
86
+ if (normalized !== '') hosts.add(normalized)
87
+ }
88
+ continue
89
+ }
90
+ const host = urlHost(value)
91
+ if (host !== null) hosts.add(host)
92
+ }
93
+ return { refusedHosts: hosts, resolve }
94
+ }
95
+
96
+ /** The host of a framework variable's value when it is an http(s) URL, such as an origin or a DSN; `null` otherwise. */
97
+ function urlHost(value: string): string | null {
98
+ const text = value.trim()
99
+ if (!/^https?:\/\//i.test(text)) return null
100
+ try {
101
+ return normalizedHost(new URL(text).hostname)
102
+ } catch {
103
+ return null
104
+ }
21
105
  }
22
106
 
23
107
  /**
@@ -41,6 +125,8 @@ export function platformCall<T>(work: () => T): T {
41
125
  return scope.exit(work)
42
126
  }
43
127
 
128
+ type Fetch = (input: string, init: RequestInit) => Promise<Response>
129
+
44
130
  /**
45
131
  * Wraps the global `fetch` in the guard, once: a `fetch` that is already a guard stays. A test that replaces `fetch`
46
132
  * after boot replaces the guard with it.
@@ -50,15 +136,20 @@ export function installEgressGuard(): void {
50
136
  if (guards.has(current)) {
51
137
  return
52
138
  }
139
+ const send: Fetch = (input, init) => current(input, init)
53
140
  const guarded = Object.assign(
54
141
  (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
55
142
  const running = scope.getStore()
56
143
  if (running === undefined) {
57
144
  return current(input, init)
58
145
  }
146
+ if (running.open !== null) {
147
+ return publicFetch(send, running.site, running.open, input, init)
148
+ }
59
149
  const origin = originOf(input)
60
150
  if (origin !== null && running.origins.has(origin)) {
61
- return current(input, init)
151
+ // Only the standard fields: a runtime's own (Bun's `unix`, `proxy`, `tls`) would send the request elsewhere.
152
+ return current(input, standardInit(init))
62
153
  }
63
154
  return Promise.reject(
64
155
  new CapabilityRefusedError(
@@ -69,12 +160,47 @@ export function installEgressGuard(): void {
69
160
  ),
70
161
  )
71
162
  },
72
- { preconnect: current.preconnect },
163
+ {
164
+ // Inside a site's scope a preconnect reaches only a declared origin; public egress, which cannot check a hop
165
+ // before it connects, refuses every one.
166
+ preconnect: (...args: Parameters<typeof current.preconnect>): void => {
167
+ const running = scope.getStore()
168
+ if (running !== undefined) {
169
+ const origin = originOf(args[0])
170
+ if (running.open !== null || origin === null || !running.origins.has(origin)) {
171
+ throw new CapabilityRefusedError(
172
+ running.open === null ? 'undeclared_egress' : 'refused_egress',
173
+ `${running.site} preconnects to ${origin ?? 'a URL that is not absolute'}, which its egress does not reach`,
174
+ )
175
+ }
176
+ }
177
+ if (typeof current.preconnect === 'function') current.preconnect(...args)
178
+ },
179
+ },
73
180
  )
74
181
  guards.add(guarded)
75
182
  globalThis.fetch = guarded
76
183
  }
77
184
 
185
+ /** `init` with the fields of the Fetch standard only. */
186
+ function standardInit(init: RequestInit | undefined): RequestInit | undefined {
187
+ if (init === undefined) return undefined
188
+ return {
189
+ ...(init.method === undefined ? {} : { method: init.method }),
190
+ ...(init.headers === undefined ? {} : { headers: init.headers }),
191
+ ...(init.body === undefined ? {} : { body: init.body }),
192
+ ...(init.redirect === undefined ? {} : { redirect: init.redirect }),
193
+ ...(init.signal === undefined ? {} : { signal: init.signal }),
194
+ ...(init.keepalive === undefined ? {} : { keepalive: init.keepalive }),
195
+ ...(init.integrity === undefined ? {} : { integrity: init.integrity }),
196
+ ...(init.referrer === undefined ? {} : { referrer: init.referrer }),
197
+ ...(init.referrerPolicy === undefined ? {} : { referrerPolicy: init.referrerPolicy }),
198
+ ...(init.cache === undefined ? {} : { cache: init.cache }),
199
+ ...(init.credentials === undefined ? {} : { credentials: init.credentials }),
200
+ ...(init.mode === undefined ? {} : { mode: init.mode }),
201
+ }
202
+ }
203
+
78
204
  function originOf(input: string | URL | Request): string | null {
79
205
  try {
80
206
  return new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url).origin
@@ -82,3 +208,236 @@ function originOf(input: string | URL | Request): string | null {
82
208
  return null
83
209
  }
84
210
  }
211
+
212
+ const REDIRECTS: ReadonlySet<number> = new Set([301, 302, 303, 307, 308])
213
+ /** The headers a redirect that turns a request into a `GET` drops with its body (Fetch, "HTTP-redirect fetch"). */
214
+ const BODY_HEADERS = ['content-type', 'content-length', 'content-encoding', 'content-language', 'content-location']
215
+ /**
216
+ * The request headers public egress never sends, on any hop: the Fetch standard's forbidden request headers (`Host`
217
+ * among them, which would route a request for a public name to another site at the same address), the forwarding
218
+ * headers a proxy trusts, and the platform's own `X-Fabrika-*`.
219
+ */
220
+ const FORBIDDEN_HEADERS = [
221
+ 'accept-charset',
222
+ 'accept-encoding',
223
+ 'access-control-request-headers',
224
+ 'access-control-request-method',
225
+ 'connection',
226
+ 'content-length',
227
+ 'cookie2',
228
+ 'date',
229
+ 'dnt',
230
+ 'expect',
231
+ 'forwarded',
232
+ 'host',
233
+ 'keep-alive',
234
+ 'origin',
235
+ 'referer',
236
+ 'set-cookie',
237
+ 'te',
238
+ 'trailer',
239
+ 'transfer-encoding',
240
+ 'upgrade',
241
+ 'via',
242
+ 'x-http-method',
243
+ 'x-http-method-override',
244
+ 'x-method-override',
245
+ 'x-real-ip',
246
+ ]
247
+ const FORBIDDEN_HEADER_PREFIXES = ['proxy-', 'sec-', 'x-forwarded-', 'x-fabrika-']
248
+
249
+ function withoutForbiddenHeaders(headers: Headers): Headers {
250
+ for (const name of [...headers.keys()]) {
251
+ if (FORBIDDEN_HEADERS.includes(name) || FORBIDDEN_HEADER_PREFIXES.some((prefix) => name.startsWith(prefix))) {
252
+ headers.delete(name)
253
+ }
254
+ }
255
+ return headers
256
+ }
257
+
258
+ /** The credentials a redirect to another origin drops. */
259
+ const CREDENTIAL_HEADERS = ['authorization', 'proxy-authorization', 'cookie']
260
+
261
+ /**
262
+ * One request under public egress. Every hop is sent with `redirect: 'manual'`, so the runtime follows no redirect the
263
+ * guard has not checked: the caller's `follow` is done here, at most `maxRedirects` hops, each host checked again;
264
+ * `manual` hands the caller the redirect, whose next `fetch` passes the guard again; `error` refuses one. The request
265
+ * is bounded in time and its answer's body in size.
266
+ */
267
+ async function publicFetch(
268
+ send: Fetch,
269
+ site: string,
270
+ rules: PublicEgressRules,
271
+ input: string | URL | Request,
272
+ init?: RequestInit,
273
+ ): Promise<Response> {
274
+ const request = new Request(input, init)
275
+ // A timer the guard clears once the body is read, not `AbortSignal.timeout`: on workerd an uncleared timer keeps the
276
+ // Durable Object awake until it fires.
277
+ const deadline = new AbortController()
278
+ const timer = setTimeout(() => deadline.abort(new DOMException('public egress request timed out', 'TimeoutError')), PUBLIC_EGRESS_LIMITS.timeoutMs)
279
+ const done = (): void => clearTimeout(timer)
280
+ try {
281
+ return await follow(send, site, rules, request, AbortSignal.any([request.signal, deadline.signal]), done)
282
+ } catch (error) {
283
+ done()
284
+ throw error
285
+ }
286
+ }
287
+
288
+ /** The hops of one request; `done` clears its deadline once its last answer's body is read. */
289
+ async function follow(
290
+ send: Fetch,
291
+ site: string,
292
+ rules: PublicEgressRules,
293
+ request: Request,
294
+ signal: AbortSignal,
295
+ done: () => void,
296
+ ): Promise<Response> {
297
+ const mode = request.redirect
298
+ let url = new URL(request.url)
299
+ let method = request.method
300
+ const headers = withoutForbiddenHeaders(new Headers(request.headers))
301
+ // Read once, so that a 307 or a 308 sends it again.
302
+ let body: ArrayBuffer | null = request.body === null ? null : await untilAborted(signal, request.arrayBuffer())
303
+ for (let hop = 0;; hop++) {
304
+ await admit(site, rules, url, signal)
305
+ const response = await send(url.href, { method, headers: new Headers(headers), body, redirect: 'manual', signal })
306
+ const location = REDIRECTS.has(response.status) ? response.headers.get('location') : null
307
+ if (location === null || mode === 'manual') {
308
+ return await capped(site, response, url, hop > 0, signal, done)
309
+ }
310
+ await response.body?.cancel()
311
+ if (mode === 'error') {
312
+ throw new TypeError(`${site}: ${url.origin} redirects, and the request's redirect mode is 'error'`)
313
+ }
314
+ if (hop >= PUBLIC_EGRESS_LIMITS.maxRedirects) {
315
+ throw new TypeError(`${site}: more than ${PUBLIC_EGRESS_LIMITS.maxRedirects} redirects, the last from ${url.origin}`)
316
+ }
317
+ const next = new URL(location, url)
318
+ const toGet = (response.status === 303 && method !== 'GET' && method !== 'HEAD')
319
+ || ((response.status === 301 || response.status === 302) && method === 'POST')
320
+ if (toGet) {
321
+ method = 'GET'
322
+ body = null
323
+ for (const name of BODY_HEADERS) headers.delete(name)
324
+ }
325
+ if (next.origin !== url.origin) {
326
+ for (const name of CREDENTIAL_HEADERS) headers.delete(name)
327
+ }
328
+ url = next
329
+ }
330
+ }
331
+
332
+ /** Refuses a hop public egress does not reach: by the URL, by the installation's hosts, by what its name resolves to. */
333
+ async function admit(site: string, rules: PublicEgressRules, url: URL, signal: AbortSignal): Promise<void> {
334
+ const refusal = publicEgressRefusal(url, rules.refusedHosts)
335
+ if (refusal !== null) {
336
+ throw new CapabilityRefusedError('refused_egress', `${site} calls ${url.origin}, which public egress refuses: ${refusal}`)
337
+ }
338
+ const resolve = rules.resolve
339
+ if (resolve === null) {
340
+ return
341
+ }
342
+ const host = normalizedHost(url.hostname)
343
+ const addresses = await untilAborted(signal, platformCall(() => resolve(host)))
344
+ const internal = addresses.find((address) => !isPublicAddress(address))
345
+ if (addresses.length === 0 || internal !== undefined) {
346
+ throw new CapabilityRefusedError(
347
+ 'refused_egress',
348
+ `${site} calls ${url.origin}, which public egress refuses: ${
349
+ internal === undefined ? `${host} resolves to no address` : `${host} resolves to ${internal}, which is not a public address`
350
+ }`,
351
+ )
352
+ }
353
+ }
354
+
355
+ /**
356
+ * `response` with its body bounded by `maxResponseBytes`, and the URL and redirect flag of the request it answers,
357
+ * which a response the guard builds would otherwise lose.
358
+ */
359
+ async function capped(
360
+ site: string,
361
+ response: Response,
362
+ url: URL,
363
+ redirected: boolean,
364
+ signal: AbortSignal,
365
+ done: () => void,
366
+ ): Promise<Response> {
367
+ const max = PUBLIC_EGRESS_LIMITS.maxResponseBytes
368
+ const tooLarge = () =>
369
+ new CapabilityRefusedError(
370
+ 'oversized_egress',
371
+ `${site}: ${url.origin} answers more than ${max} bytes, the most public egress reads of one response`,
372
+ )
373
+ const declared = Number(response.headers.get('content-length') ?? '0')
374
+ if (Number.isFinite(declared) && declared > max) {
375
+ await response.body?.cancel()
376
+ throw tooLarge()
377
+ }
378
+ if (response.body === null || response.status < 200 || response.status > 599) {
379
+ done()
380
+ return withRequestUrl(response, url, redirected)
381
+ }
382
+ const reader = response.body.getReader()
383
+ let seen = 0
384
+ const bound = new ReadableStream<Uint8Array>({
385
+ async pull(controller) {
386
+ const read = await untilAborted(signal, reader.read()).catch(async (error: unknown) => {
387
+ done()
388
+ await reader.cancel(error).catch(() => undefined)
389
+ throw error
390
+ })
391
+ if (read.done) {
392
+ done()
393
+ controller.close()
394
+ return
395
+ }
396
+ seen += read.value.byteLength
397
+ if (seen > max) {
398
+ done()
399
+ await reader.cancel()
400
+ controller.error(tooLarge())
401
+ return
402
+ }
403
+ controller.enqueue(read.value)
404
+ },
405
+ async cancel(reason) {
406
+ done()
407
+ await reader.cancel(reason)
408
+ },
409
+ })
410
+ const answer = new Response(bound, {
411
+ status: response.status,
412
+ statusText: response.statusText,
413
+ headers: response.headers,
414
+ })
415
+ return withRequestUrl(answer, url, redirected)
416
+ }
417
+
418
+ /**
419
+ * `work`, or the signal's reason once it aborts, whichever comes first: a stage the runtime does not abort by the
420
+ * signal (a resolver, a body read) still ends at the deadline. The work itself is left to settle unobserved.
421
+ */
422
+ async function untilAborted<T>(signal: AbortSignal, work: Promise<T>): Promise<T> {
423
+ signal.throwIfAborted()
424
+ let abort = (): void => {}
425
+ const aborted = new Promise<never>((_resolve, reject) => {
426
+ abort = () => reject(signal.reason)
427
+ })
428
+ signal.addEventListener('abort', abort, { once: true })
429
+ try {
430
+ return await Promise.race([work, aborted])
431
+ } finally {
432
+ signal.removeEventListener('abort', abort)
433
+ }
434
+ }
435
+
436
+ function withRequestUrl(response: Response, url: URL, redirected: boolean): Response {
437
+ try {
438
+ Object.defineProperties(response, { url: { value: url.href }, redirected: { value: redirected } })
439
+ } catch {
440
+ // A runtime whose responses refuse own properties keeps its own `url`; the body bound holds either way.
441
+ }
442
+ return response
443
+ }
@@ -3,13 +3,14 @@
3
3
  // commits it after the handler returned and its output passed validation, and rolls it back otherwise. Every handle
4
4
  // is bound to the invocation: called from another request, another `boot`, or after it ended, it refuses.
5
5
 
6
- import { type ContractArtifact, JOB_MAILERS, type JobMailer } from '@fabrika/auth-core'
6
+ import { type ContractArtifact, type DeclaredEgress, JOB_MAILERS, type JobMailer, PUBLIC_EGRESS } from '@fabrika/auth-core'
7
7
  import {
8
8
  type DataAccess,
9
9
  type DataHandles,
10
10
  type DataSite,
11
11
  type FileBinding,
12
12
  type InvocationTransaction,
13
+ type NewWake,
13
14
  type QueryRefusal,
14
15
  QueryRefusedError,
15
16
  type Session,
@@ -34,8 +35,8 @@ export interface SiteDeclaration {
34
35
  readonly binds: string | null
35
36
  /** The token purposes `ctx.tokens.sign` may sign. */
36
37
  readonly signs: readonly string[]
37
- /** The HTTPS origins the global `fetch` reaches while the site's handler runs. */
38
- readonly egress: readonly string[]
38
+ /** The HTTPS origins the global `fetch` reaches while the site's handler runs, or `'public'`: every public host (a cron job). */
39
+ readonly egress: DeclaredEgress
39
40
  }
40
41
 
41
42
  /** A public procedure's reach: the texts the verified signed tokens of its request carry, which name the rows it changes. */
@@ -166,10 +167,11 @@ export function parseDeclaration(where: string, declared: unknown, kind: DataKin
166
167
  problems.push(`${where}: signs is not a list of token purposes`)
167
168
  }
168
169
  const egressField = ownField(declared, 'egress')
169
- const egress = Array.isArray(egressField) ? egressField.filter((origin): origin is string => typeof origin === 'string') : []
170
- if (egressField !== undefined && (!Array.isArray(egressField) || egress.length !== egressField.length)) {
171
- problems.push(`${where}: egress is not a list of origins`)
170
+ const origins = Array.isArray(egressField) ? egressField.filter((origin): origin is string => typeof origin === 'string') : []
171
+ if (egressField !== undefined && egressField !== PUBLIC_EGRESS && (!Array.isArray(egressField) || origins.length !== egressField.length)) {
172
+ problems.push(`${where}: egress is not a list of origins or '${PUBLIC_EGRESS}'`)
172
173
  }
174
+ const egress: DeclaredEgress = egressField === PUBLIC_EGRESS ? PUBLIC_EGRESS : Object.freeze([...new Set(origins)].sort())
173
175
  return Object.freeze({
174
176
  sql: sql === 'read' || sql === 'write' ? sql : null,
175
177
  unscoped: Object.freeze(unscoped),
@@ -179,7 +181,7 @@ export function parseDeclaration(where: string, declared: unknown, kind: DataKin
179
181
  kicks: Object.freeze([...new Set(kicks)].sort()),
180
182
  binds: typeof binds === 'string' ? binds : null,
181
183
  signs: Object.freeze([...new Set(signs)].sort()),
182
- egress: Object.freeze([...new Set(egress)].sort()),
184
+ egress,
183
185
  })
184
186
  }
185
187
 
@@ -224,7 +226,7 @@ export function approvedReach(site: string, artifact: ContractArtifact): SiteDec
224
226
  kicks: Object.freeze([...(reach.kicks ?? [])]),
225
227
  binds: reach.binds ?? null,
226
228
  signs: Object.freeze([...(reach.signs ?? [])]),
227
- egress: Object.freeze([...(reach.egress ?? [])]),
229
+ egress: reach.egress === PUBLIC_EGRESS ? PUBLIC_EGRESS : Object.freeze([...(reach.egress ?? [])]),
228
230
  })
229
231
  }
230
232
 
@@ -243,7 +245,7 @@ function describeDeclaration(declaration: SiteDeclaration): string {
243
245
  ...(declaration.kicks.length === 0 ? {} : { kicks: declaration.kicks }),
244
246
  ...(declaration.binds === null ? {} : { binds: declaration.binds }),
245
247
  ...(declaration.signs.length === 0 ? {} : { signs: declaration.signs }),
246
- ...(declaration.egress.length === 0 ? {} : { egress: declaration.egress }),
248
+ ...(declaration.egress !== PUBLIC_EGRESS && declaration.egress.length === 0 ? {} : { egress: declaration.egress }),
247
249
  })
248
250
  }
249
251
 
@@ -466,22 +468,61 @@ export function jobSql(frame: RequestFrame, data: DataAccess, mode: SqlMode, ses
466
468
  return data.sql({ mode, check: boundTo(frame, ended, 'tx.sql'), session: async () => session, fail: () => session.fail() })
467
469
  }
468
470
 
471
+ /** The kicks of one invocation, as `ctx.kick` recorded them. */
472
+ export interface KickRecorder {
473
+ readonly kick: (job: string, options?: unknown) => void
474
+ /** The jobs kicked without `at`, each once: what the dispatcher starts after the commit. */
475
+ readonly kicked: () => readonly string[]
476
+ /** Whether the invocation kicked anything, now or for later. */
477
+ readonly recorded: () => boolean
478
+ /**
479
+ * Every kick's wake, one per job and due second (`kick:<job>:<due second>`); a kick without `at` is due at `now`. The
480
+ * site writes them in its transaction, so a rollback leaves none.
481
+ */
482
+ readonly wakes: (now: Date) => readonly NewWake[]
483
+ }
484
+
485
+ /** A kick's due time: `undefined` for one without options; anything but `{ at: <valid Date> }` is refused. */
486
+ function kickAt(site: string, options: unknown): Date | undefined {
487
+ if (options === undefined) {
488
+ return undefined
489
+ }
490
+ const keys = isPlainObject(options) ? Object.keys(options) : null
491
+ const at: unknown = isPlainObject(options) ? ownField(options, 'at') : undefined
492
+ if (keys === null || keys.length !== 1 || keys[0] !== 'at' || !(at instanceof Date) || Number.isNaN(at.getTime())) {
493
+ throw new QueryRefusedError('invalid_argument', `${site}: ctx.kick takes a job and optionally { at: <Date> }; a kick carries nothing else`)
494
+ }
495
+ return new Date(at.getTime())
496
+ }
497
+
498
+ const kickKey = (job: string, due: Date): string => `kick:${job}:${Math.floor(due.getTime() / 1_000)}`
499
+
469
500
  /**
470
- * `ctx.kick` of one invocation: it names only a declared job, and records it; the dispatcher sends each recorded job once,
471
- * after the commit, and nothing on a rollback.
501
+ * `ctx.kick` of one invocation: it names only a declared job, and records it; the site writes each kick's wake in its
502
+ * transaction, and the dispatcher starts each job kicked without `at` once, after the commit, and nothing on a rollback.
472
503
  */
473
- export function kickRecorder(
474
- site: string,
475
- declared: readonly string[],
476
- ): { readonly kick: (job: string) => void; readonly kicked: () => readonly string[] } {
477
- const kicked = new Set<string>()
504
+ export function kickRecorder(site: string, declared: readonly string[]): KickRecorder {
505
+ const kicks: { readonly job: string; readonly at: Date | undefined }[] = []
478
506
  return {
479
- kick: (job: string) => {
507
+ kick: (job: string, options?: unknown) => {
480
508
  if (!declared.includes(job)) {
481
509
  throw new CapabilityRefusedError('undeclared_kick', `${site} does not declare kicks: ['${String(job)}']`)
482
510
  }
483
- kicked.add(job)
511
+ kicks.push({ job, at: kickAt(site, options) })
512
+ },
513
+ kicked: () => [...new Set(kicks.filter((kick) => kick.at === undefined).map((kick) => kick.job))],
514
+ recorded: () => kicks.length > 0,
515
+ wakes: (now: Date) => {
516
+ const wakes = new Map<string, NewWake>()
517
+ for (const { job, at } of kicks) {
518
+ const dueAt = at ?? now
519
+ const dedupe = kickKey(job, dueAt)
520
+ const kept = wakes.get(dedupe)
521
+ if (kept === undefined || dueAt < kept.dueAt) {
522
+ wakes.set(dedupe, { job, reason: 'kick', dueAt, dedupe })
523
+ }
524
+ }
525
+ return [...wakes.values()]
484
526
  },
485
- kicked: () => [...kicked],
486
527
  }
487
528
  }
@@ -102,12 +102,27 @@ export class WorkloadCredential {
102
102
  if (cached !== null && cached.exp - Math.floor(Date.now() / 1000) > TOKEN_REFRESH_SKEW_SECONDS) {
103
103
  return Promise.resolve({ ok: true, perms: cached.perms, token: cached.token })
104
104
  }
105
- this.#pending ??= this.#exchange().finally(() => {
106
- this.#pending = null
107
- })
105
+ if (this.#pending === null) {
106
+ const pending: Promise<WorkloadAuthority> = this.#exchange().finally(() => {
107
+ if (this.#pending === pending) {
108
+ this.#pending = null
109
+ }
110
+ })
111
+ this.#pending = pending
112
+ }
108
113
  return this.#pending
109
114
  }
110
115
 
116
+ /**
117
+ * The caller stopped waiting for `pending`, an answer of `authority()` (its attempt timed out or was stopped): the
118
+ * next call exchanges afresh instead of waiting on an exchange that may never answer.
119
+ */
120
+ abandon(pending: Promise<WorkloadAuthority>): void {
121
+ if (this.#pending === pending) {
122
+ this.#pending = null
123
+ }
124
+ }
125
+
111
126
  async #exchange(): Promise<WorkloadAuthority> {
112
127
  const { kind, name, key, audience, source, verifier } = this.#options
113
128
  let minted: MintFromKeyResult