@fabrika/app 0.9.0-dev.3 → 0.9.0-dev.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +14 -9
- package/skill/SKILL.md +41 -14
- package/skill/references/app-setup.md +43 -12
- package/skill/references/dev.md +2 -1
- package/skill/references/endpoint.md +30 -24
- package/skill/references/errors.md +40 -35
- package/skill/references/files.md +4 -2
- package/skill/references/jobs.md +21 -4
- package/skill/references/table-and-migration.md +19 -2
- package/skill/references/tests.md +40 -1
- package/skill/references/webhooks-links-connectors.md +1 -1
- package/src/build-recipe.ts +198 -0
- package/src/build.ts +60 -4
- package/src/bun.ts +181 -13
- package/src/cloudflare/application.ts +822 -0
- package/src/cloudflare/bindings.ts +159 -0
- package/src/cloudflare/export.ts +641 -0
- package/src/cloudflare/import.ts +1021 -0
- package/src/cloudflare/maintenance.ts +518 -0
- package/src/cloudflare/names.ts +16 -0
- package/src/cloudflare/ops.ts +375 -0
- package/src/cloudflare/r2-files.ts +172 -0
- package/src/cloudflare/restore.ts +167 -0
- package/src/cloudflare/tracker.ts +192 -0
- package/src/cloudflare.ts +100 -146
- package/src/contract/app-id.ts +5 -0
- package/src/contract/artifact-schema.ts +9 -1
- package/src/contract/build.ts +40 -2
- package/src/contract/compile.ts +1 -0
- package/src/contract/context.ts +35 -9
- package/src/contract/declaration.ts +2 -0
- package/src/contract/defaults.ts +22 -2
- package/src/contract/define.ts +29 -3
- package/src/contract/kit.ts +4 -1
- package/src/contract/platform.ts +3 -2
- package/src/contract/vocabulary.ts +26 -8
- package/src/dev/launcher.ts +84 -13
- package/src/dev/output.ts +13 -3
- package/src/disk-assets.ts +8 -3
- package/src/files/archive.ts +2 -2
- package/src/files/job-names.ts +12 -0
- package/src/files/kinds.ts +73 -31
- package/src/files/scan.ts +3 -4
- package/src/files/streams.ts +3 -1
- package/src/implement/anonymous.ts +12 -11
- package/src/implement/boot.ts +75 -6
- package/src/implement/bounded.ts +21 -2
- package/src/implement/capability.ts +15 -3
- package/src/implement/dispatch.ts +419 -177
- package/src/implement/failures.ts +17 -1
- package/src/implement/faults.ts +1 -0
- package/src/implement/index.ts +1 -0
- package/src/implement/invocation.ts +58 -10
- package/src/implement/principal.ts +25 -2
- package/src/implement/terminals.ts +93 -0
- package/src/implement/workload.ts +42 -16
- package/src/jobs/mail.ts +8 -0
- package/src/jobs/report.ts +5 -1
- package/src/jobs/runner.ts +672 -113
- package/src/jobs/schedule.ts +7 -1
- package/src/jobs/scrub.ts +14 -1
- package/src/jobs/types.ts +6 -0
- package/src/spa-fallback.ts +12 -0
- package/src/testing/endpoint-access.ts +307 -152
- package/src/testing/isolation.ts +8 -1
- package/src/testing/kit.ts +80 -2
- package/src/testing/proxy.ts +15 -10
- package/types/src/build-recipe.d.ts +70 -0
- package/types/src/build.d.ts +19 -1
- package/types/src/bun.d.ts +34 -1
- package/types/src/cloudflare/application.d.ts +73 -0
- package/types/src/cloudflare/bindings.d.ts +33 -0
- package/types/src/cloudflare/export.d.ts +16 -0
- package/types/src/cloudflare/import.d.ts +51 -0
- package/types/src/cloudflare/maintenance.d.ts +117 -0
- package/types/src/cloudflare/names.d.ts +11 -0
- package/types/src/cloudflare/ops.d.ts +81 -0
- package/types/src/cloudflare/r2-files.d.ts +9 -0
- package/types/src/cloudflare/restore.d.ts +9 -0
- package/types/src/cloudflare/tracker.d.ts +29 -0
- package/types/src/cloudflare.d.ts +12 -18
- package/types/src/contract/app-id.d.ts +2 -0
- package/types/src/contract/artifact-schema.d.ts +2 -0
- package/types/src/contract/context.d.ts +35 -11
- package/types/src/contract/declaration.d.ts +4 -0
- package/types/src/contract/defaults.d.ts +19 -1
- package/types/src/contract/define.d.ts +20 -3
- package/types/src/contract/kit.d.ts +2 -1
- package/types/src/contract/platform.d.ts +2 -2
- package/types/src/contract/vocabulary.d.ts +9 -7
- package/types/src/dev/output.d.ts +8 -2
- package/types/src/disk-assets.d.ts +4 -1
- package/types/src/files/job-names.d.ts +9 -0
- package/types/src/files/kinds.d.ts +21 -14
- package/types/src/files/scan.d.ts +1 -3
- package/types/src/implement/anonymous.d.ts +2 -4
- package/types/src/implement/boot.d.ts +17 -1
- package/types/src/implement/bounded.d.ts +11 -1
- package/types/src/implement/capability.d.ts +4 -2
- package/types/src/implement/dispatch.d.ts +34 -1
- package/types/src/implement/failures.d.ts +5 -0
- package/types/src/implement/faults.d.ts +1 -0
- package/types/src/implement/index.d.ts +1 -0
- package/types/src/implement/invocation.d.ts +22 -7
- package/types/src/implement/principal.d.ts +6 -1
- package/types/src/implement/terminals.d.ts +33 -0
- package/types/src/implement/workload.d.ts +5 -0
- package/types/src/jobs/runner.d.ts +66 -2
- package/types/src/jobs/schedule.d.ts +2 -0
- package/types/src/jobs/types.d.ts +6 -0
- package/types/src/spa-fallback.d.ts +2 -0
- package/types/src/testing/endpoint-access.d.ts +37 -5
- package/types/src/testing/isolation.d.ts +1 -1
- package/types/src/testing/kit.d.ts +22 -1
- package/types/src/testing/proxy.d.ts +4 -4
|
@@ -0,0 +1,518 @@
|
|
|
1
|
+
// The object's maintenance barrier (ADR-0069 §3): its mode and generation, whether R2 holds them, the transitions
|
|
2
|
+
// Control drives, the drain of what runs, and the write fence every invocation checks. The durable copy is an R2
|
|
3
|
+
// object in the environment's bucket, never SQLite or KV, which point-in-time recovery rewinds; so is the generation
|
|
4
|
+
// since which the object has written nothing (ADR-0070 §2), in an object of its own that no older release reads.
|
|
5
|
+
|
|
6
|
+
import {
|
|
7
|
+
OPS_MODES,
|
|
8
|
+
OPS_STATE_KEY,
|
|
9
|
+
type OpsMaintenance,
|
|
10
|
+
type OpsMode,
|
|
11
|
+
type OpsPublishedState,
|
|
12
|
+
type OpsStateAck,
|
|
13
|
+
opsTransitionRefused,
|
|
14
|
+
} from '@fabrika/auth-core'
|
|
15
|
+
import type { InvocationAdmission, InvocationGate, InvocationKind } from '../implement/dispatch.js'
|
|
16
|
+
import { LEASE_GRACE_MS } from '../jobs/runner.js'
|
|
17
|
+
import { method } from './bindings.js'
|
|
18
|
+
|
|
19
|
+
/** A handler's share of the drain's bound; a job's lease grace follows it, as Control's request timeout assumes. */
|
|
20
|
+
const DRAIN_HANDLER_MS = 25_000
|
|
21
|
+
export const DRAIN_BOUND_MS = DRAIN_HANDLER_MS + LEASE_GRACE_MS
|
|
22
|
+
|
|
23
|
+
/** How often a transition puts again after a conflict whose R2 state it did not adopt. */
|
|
24
|
+
const PUT_ATTEMPTS = 3
|
|
25
|
+
|
|
26
|
+
/** The state R2 holds, and its version: the etag a conditional put names. */
|
|
27
|
+
export interface StoredMaintenance {
|
|
28
|
+
readonly state: OpsPublishedState
|
|
29
|
+
readonly version: string
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Since which generation the object has written nothing, as of the published generation `generation`: kept only while
|
|
34
|
+
* it is `read-only`, `closed` or `inspect`.
|
|
35
|
+
*/
|
|
36
|
+
export interface FrozenRecord {
|
|
37
|
+
readonly generation: number
|
|
38
|
+
readonly since: number
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** The object's durable copy of its maintenance state. */
|
|
42
|
+
export interface MaintenanceStore {
|
|
43
|
+
/** `null` only for a definite not-found; every other failure throws, and is never read as absence. */
|
|
44
|
+
read(): Promise<StoredMaintenance | null>
|
|
45
|
+
/** Puts `state` if R2 still holds `version` (`null`: holds nothing); the new version, or `null` when the condition failed. */
|
|
46
|
+
put(state: OpsPublishedState, version: string | null): Promise<string | null>
|
|
47
|
+
/** The frozen record, `null` when none is stored. A store without these keeps the record in memory only. */
|
|
48
|
+
readFrozen?(): Promise<FrozenRecord | null>
|
|
49
|
+
putFrozen?(record: FrozenRecord): Promise<void>
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** `__fabrika/ops/<object>.json` in the environment's bucket (`bucket`, an R2 binding). */
|
|
53
|
+
export function r2MaintenanceStore(bucket: unknown, object: string): MaintenanceStore {
|
|
54
|
+
const key = OPS_STATE_KEY(object)
|
|
55
|
+
// Beside the state, never in it: an older release parses the state strictly and must still load it.
|
|
56
|
+
const frozenKey = `${key.slice(0, -'.json'.length)}.frozen.json`
|
|
57
|
+
const call = (name: string): (...args: unknown[]) => unknown => {
|
|
58
|
+
const found = method(bucket, name)
|
|
59
|
+
if (found === null) {
|
|
60
|
+
throw new Error(`the FABRIKA_FILES binding has no ${name}; the maintenance state lives in the environment's bucket`)
|
|
61
|
+
}
|
|
62
|
+
return found
|
|
63
|
+
}
|
|
64
|
+
return {
|
|
65
|
+
async read() {
|
|
66
|
+
const answer: unknown = await call('get')(key)
|
|
67
|
+
if (answer === null) {
|
|
68
|
+
return null
|
|
69
|
+
}
|
|
70
|
+
const version = typeof answer === 'object' ? Reflect.get(answer, 'etag') : undefined
|
|
71
|
+
const text = method(answer, 'text')
|
|
72
|
+
if (typeof version !== 'string' || version === '' || text === null) {
|
|
73
|
+
throw new Error('R2 answered the maintenance state without its etag or body')
|
|
74
|
+
}
|
|
75
|
+
const body: unknown = await text()
|
|
76
|
+
const state = typeof body === 'string' ? parseStoredState(body) : null
|
|
77
|
+
if (state === null) {
|
|
78
|
+
throw new Error('the maintenance state in R2 does not parse')
|
|
79
|
+
}
|
|
80
|
+
return { state, version }
|
|
81
|
+
},
|
|
82
|
+
async put(state, version) {
|
|
83
|
+
const onlyIf = version === null ? { etagDoesNotMatch: '*' } : { etagMatches: version }
|
|
84
|
+
const answer: unknown = await call('put')(key, JSON.stringify(state), { httpMetadata: { contentType: 'application/json' }, onlyIf })
|
|
85
|
+
if (answer === null) {
|
|
86
|
+
return null
|
|
87
|
+
}
|
|
88
|
+
const etag = typeof answer === 'object' ? Reflect.get(answer, 'etag') : undefined
|
|
89
|
+
if (typeof etag !== 'string' || etag === '') {
|
|
90
|
+
throw new Error('R2 answered the maintenance state put without its etag')
|
|
91
|
+
}
|
|
92
|
+
return etag
|
|
93
|
+
},
|
|
94
|
+
async readFrozen() {
|
|
95
|
+
const answer: unknown = await call('get')(frozenKey)
|
|
96
|
+
if (answer === null) {
|
|
97
|
+
return null
|
|
98
|
+
}
|
|
99
|
+
const text = method(answer, 'text')
|
|
100
|
+
const body: unknown = text === null ? null : await text()
|
|
101
|
+
const record = typeof body === 'string' ? parseFrozenRecord(body) : null
|
|
102
|
+
if (record === null) {
|
|
103
|
+
throw new Error('the frozen record in R2 does not parse')
|
|
104
|
+
}
|
|
105
|
+
return record
|
|
106
|
+
},
|
|
107
|
+
async putFrozen(record) {
|
|
108
|
+
await call('put')(frozenKey, JSON.stringify(record), { httpMetadata: { contentType: 'application/json' } })
|
|
109
|
+
},
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** Exactly two positive generations, the stretch's start not after the generation it was recorded at. */
|
|
114
|
+
function parseFrozenRecord(text: string): FrozenRecord | null {
|
|
115
|
+
let value: unknown
|
|
116
|
+
try {
|
|
117
|
+
value = JSON.parse(text)
|
|
118
|
+
} catch {
|
|
119
|
+
return null
|
|
120
|
+
}
|
|
121
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value) || Object.keys(value).length !== 2) {
|
|
122
|
+
return null
|
|
123
|
+
}
|
|
124
|
+
const generation: unknown = Reflect.get(value, 'generation')
|
|
125
|
+
const since: unknown = Reflect.get(value, 'since')
|
|
126
|
+
return positive(generation) && positive(since) && since <= generation ? { generation, since } : null
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
function positive(value: unknown): value is number {
|
|
130
|
+
return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/** The stored record, parsed strictly: exactly a positive generation and a mode. */
|
|
134
|
+
function parseStoredState(text: string): OpsPublishedState | null {
|
|
135
|
+
let value: unknown
|
|
136
|
+
try {
|
|
137
|
+
value = JSON.parse(text)
|
|
138
|
+
} catch {
|
|
139
|
+
return null
|
|
140
|
+
}
|
|
141
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value) || Object.keys(value).length !== 2) {
|
|
142
|
+
return null
|
|
143
|
+
}
|
|
144
|
+
const generation: unknown = Reflect.get(value, 'generation')
|
|
145
|
+
const mode = OPS_MODES.find((candidate) => candidate === Reflect.get(value, 'mode'))
|
|
146
|
+
if (typeof generation !== 'number' || !Number.isSafeInteger(generation) || generation <= 0 || mode === undefined) {
|
|
147
|
+
return null
|
|
148
|
+
}
|
|
149
|
+
return { generation, mode }
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/** What each mode admits of ordinary invocations; ops requests are admitted in every mode. */
|
|
153
|
+
const ADMITTED: Readonly<Record<OpsMode, ReadonlySet<InvocationKind>>> = {
|
|
154
|
+
open: new Set(['read', 'write', 'webhook', 'kick', 'job', 'framework-job']),
|
|
155
|
+
'read-only': new Set(['read']),
|
|
156
|
+
closed: new Set(),
|
|
157
|
+
inspect: new Set(),
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** The kinds a drain aborts at once; a request gets the handler's share of the bound and is fenced. */
|
|
161
|
+
const STOPPABLE: ReadonlySet<InvocationKind> = new Set(['kick', 'job', 'framework-job'])
|
|
162
|
+
|
|
163
|
+
export type TransitionResult =
|
|
164
|
+
| { readonly kind: 'acknowledged'; readonly ack: OpsStateAck }
|
|
165
|
+
/** The 409: what R2 holds as far as the object knows, `null` before the first publication. */
|
|
166
|
+
| { readonly kind: 'stale'; readonly published: OpsPublishedState | null }
|
|
167
|
+
/** R2 could not be read or written: the call fails and Control retries. */
|
|
168
|
+
| { readonly kind: 'failed' }
|
|
169
|
+
/** The caller's `frozen` held the object in `inspect`: nothing changed. */
|
|
170
|
+
| { readonly kind: 'frozen' }
|
|
171
|
+
|
|
172
|
+
export type MigrateResult<T> = { readonly kind: 'migrated'; readonly value: T } | {
|
|
173
|
+
readonly kind: 'stale'
|
|
174
|
+
readonly published: OpsPublishedState | null
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** What a step run in the barrier's turn answers, and what keeps the turn past the answer (`null`: nothing). */
|
|
178
|
+
export interface TurnStep<T> {
|
|
179
|
+
readonly value: T
|
|
180
|
+
readonly holdUntil: Promise<void> | null
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
export type StepResult<T> = { readonly kind: 'ran'; readonly value: T } | {
|
|
184
|
+
readonly kind: 'stale'
|
|
185
|
+
readonly published: OpsPublishedState | null
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/** One unit the drain waits for: an admitted invocation, or work it handed on that outlives it. */
|
|
189
|
+
interface Unit {
|
|
190
|
+
readonly kind: InvocationKind
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
export interface BarrierOptions {
|
|
194
|
+
/** The drain's bound; `DRAIN_BOUND_MS` by default. */
|
|
195
|
+
readonly drainBoundMs?: number
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
export class MaintenanceBarrier {
|
|
199
|
+
#mode: OpsMode
|
|
200
|
+
#generation: number | null
|
|
201
|
+
/** What R2 holds as far as this instance knows: as last read, written or adopted. */
|
|
202
|
+
#stored: OpsPublishedState | null
|
|
203
|
+
#version: string | null
|
|
204
|
+
/** The generation since which the object has written nothing, while it is published in a mode that writes nothing. */
|
|
205
|
+
#frozenSince: number | null
|
|
206
|
+
readonly #store: MaintenanceStore
|
|
207
|
+
readonly #drainBoundMs: number
|
|
208
|
+
/** One transition at a time: each waits for the one before it. */
|
|
209
|
+
#turn: Promise<void> = Promise.resolve()
|
|
210
|
+
readonly #units = new Set<Unit>()
|
|
211
|
+
readonly #stops = new Map<AbortController, InvocationKind>()
|
|
212
|
+
#settled: (() => void)[] = []
|
|
213
|
+
|
|
214
|
+
private constructor(store: MaintenanceStore, stored: StoredMaintenance | null, frozen: FrozenRecord | null, options: BarrierOptions) {
|
|
215
|
+
this.#store = store
|
|
216
|
+
this.#stored = stored?.state ?? null
|
|
217
|
+
this.#version = stored?.version ?? null
|
|
218
|
+
this.#mode = stored?.state.mode ?? 'open'
|
|
219
|
+
this.#generation = stored?.state.generation ?? null
|
|
220
|
+
this.#frozenSince = stored === null ? null : frozenOnLoad(stored.state, frozen)
|
|
221
|
+
this.#drainBoundMs = options.drainBoundMs ?? DRAIN_BOUND_MS
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/** The cold start: an absent state is `open`; a failed read rejects, and the caller retries on its next request. */
|
|
225
|
+
static async load(store: MaintenanceStore, options: BarrierOptions = {}): Promise<MaintenanceBarrier> {
|
|
226
|
+
const stored = await store.read()
|
|
227
|
+
const frozen = stored === null || stored.state.mode === 'open' ? null : ((await store.readFrozen?.()) ?? null)
|
|
228
|
+
return new MaintenanceBarrier(store, stored, frozen, options)
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
get mode(): OpsMode {
|
|
232
|
+
return this.#mode
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
view(): OpsMaintenance {
|
|
236
|
+
return { mode: this.#mode, generation: this.#generation, published: this.#isPublished() }
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/** What R2 holds as far as this instance knows, `null` before the first publication: what a stale refusal names. */
|
|
240
|
+
get published(): OpsPublishedState | null {
|
|
241
|
+
return this.#stored
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
/**
|
|
245
|
+
* The generation at which the object entered its current stretch of `read-only`, `closed` and `inspect`, or at which a
|
|
246
|
+
* data step last wrote within it; `null` outside such a stretch. A consistent dump is one state while it holds.
|
|
247
|
+
*/
|
|
248
|
+
get frozenSince(): number | null {
|
|
249
|
+
return this.#frozenSince
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* Called in a data step's turn before the step writes while the object writes nothing else (an import step, a
|
|
254
|
+
* restore's `arm`): the stretch starts again at the current generation, durably before the write. A failed put rejects.
|
|
255
|
+
*/
|
|
256
|
+
async restrictedWrite(): Promise<void> {
|
|
257
|
+
if (this.#mode === 'open' || this.#generation === null || this.#frozenSince === this.#generation) {
|
|
258
|
+
return
|
|
259
|
+
}
|
|
260
|
+
this.#frozenSince = this.#generation
|
|
261
|
+
await this.#store.putFrozen?.({ generation: this.#generation, since: this.#generation })
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
/** The scope of one invocation, admitted now: the generation and mode it captures, which its writes are fenced on. */
|
|
265
|
+
event(): BarrierEvent {
|
|
266
|
+
return new BarrierEvent(this, this.#generation, this.#mode)
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/** Whether a write of an invocation admitted at `generation` in `mode` may commit now. */
|
|
270
|
+
writable(generation: number | null, mode: OpsMode): boolean {
|
|
271
|
+
return mode === 'open' && this.#mode === 'open' && this.#generation === generation
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/** Admits an invocation of `kind` captured at `generation`, or `null` when the mode refuses it or a transition followed. */
|
|
275
|
+
admit(kind: InvocationKind, generation: number | null): InvocationAdmission | null {
|
|
276
|
+
if (!ADMITTED[this.#mode].has(kind) || this.#generation !== generation) {
|
|
277
|
+
return null
|
|
278
|
+
}
|
|
279
|
+
const unit: Unit = { kind }
|
|
280
|
+
const stop = new AbortController()
|
|
281
|
+
this.#units.add(unit)
|
|
282
|
+
this.#stops.set(stop, kind)
|
|
283
|
+
let released = false
|
|
284
|
+
return {
|
|
285
|
+
signal: stop.signal,
|
|
286
|
+
track: (work) => {
|
|
287
|
+
const outliving: Unit = { kind }
|
|
288
|
+
this.#units.add(outliving)
|
|
289
|
+
const done = () => this.#leave(outliving)
|
|
290
|
+
work.then(done, done)
|
|
291
|
+
},
|
|
292
|
+
release: () => {
|
|
293
|
+
if (!released) {
|
|
294
|
+
released = true
|
|
295
|
+
this.#stops.delete(stop)
|
|
296
|
+
this.#leave(unit)
|
|
297
|
+
}
|
|
298
|
+
},
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
/**
|
|
303
|
+
* `POST /__fabrika/ops/state`: the transition of ADR-0069 §3, acknowledged once published and drained. `frozen` is
|
|
304
|
+
* asked in the turn, after every data step before it: while it holds, no transition leaves `inspect`.
|
|
305
|
+
*/
|
|
306
|
+
transition(requested: OpsPublishedState, frozen: () => boolean = () => false): Promise<TransitionResult> {
|
|
307
|
+
// Exactly the state: what R2 stores and a stale refusal names.
|
|
308
|
+
const request: OpsPublishedState = { generation: requested.generation, mode: requested.mode }
|
|
309
|
+
return this.#inTurn(async () => {
|
|
310
|
+
const current = this.#generation === null ? null : { generation: this.#generation, mode: this.#mode }
|
|
311
|
+
if (opsTransitionRefused(current, request)) {
|
|
312
|
+
return { kind: 'stale', published: this.#stored }
|
|
313
|
+
}
|
|
314
|
+
if (this.#mode === 'inspect' && request.mode !== 'inspect' && frozen()) {
|
|
315
|
+
return { kind: 'frozen' }
|
|
316
|
+
}
|
|
317
|
+
const retry = current !== null && current.generation === request.generation
|
|
318
|
+
if (!retry || !this.#isPublished()) {
|
|
319
|
+
if (rank(request.mode) > rank(this.#mode)) {
|
|
320
|
+
// Before any await: from here no invocation of a class the mode forbids is admitted, and no older write commits.
|
|
321
|
+
this.#mode = request.mode
|
|
322
|
+
this.#generation = request.generation
|
|
323
|
+
}
|
|
324
|
+
const put = await this.#publish(request)
|
|
325
|
+
if (put.kind !== 'published') {
|
|
326
|
+
return put
|
|
327
|
+
}
|
|
328
|
+
await this.#froze(request)
|
|
329
|
+
}
|
|
330
|
+
const stillRunning = await this.#drain()
|
|
331
|
+
return { kind: 'acknowledged', ack: { generation: request.generation, mode: request.mode, stillRunning } }
|
|
332
|
+
})
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
/**
|
|
336
|
+
* `POST /__fabrika/ops/migrate`: `work` runs only under the published generation, in a mode that may migrate, and no
|
|
337
|
+
* transition runs meanwhile.
|
|
338
|
+
*/
|
|
339
|
+
migrate<T>(generation: number, work: () => Promise<T>): Promise<MigrateResult<T>> {
|
|
340
|
+
return this.#inTurn(async () => {
|
|
341
|
+
if (!this.#isPublished() || this.#generation !== generation || this.#mode === 'inspect') {
|
|
342
|
+
return { kind: 'stale', published: this.#stored }
|
|
343
|
+
}
|
|
344
|
+
return { kind: 'migrated', value: await work() }
|
|
345
|
+
})
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
/**
|
|
349
|
+
* A data step of Control's (ADR-0070): `work` runs in the barrier's turn, only under the published `generation`, with
|
|
350
|
+
* the mode it is in. No transition runs until `work` settles, nor, when it answers one, until `holdUntil` settles.
|
|
351
|
+
*/
|
|
352
|
+
async step<T>(generation: number, work: (mode: OpsMode) => Promise<TurnStep<T>>): Promise<StepResult<T>> {
|
|
353
|
+
const previous = this.#turn
|
|
354
|
+
const done = Promise.withResolvers<void>()
|
|
355
|
+
this.#turn = done.promise
|
|
356
|
+
let holdUntil: Promise<void> | null = null
|
|
357
|
+
await previous
|
|
358
|
+
try {
|
|
359
|
+
if (!this.#isPublished() || this.#generation !== generation) {
|
|
360
|
+
return { kind: 'stale', published: this.#stored }
|
|
361
|
+
}
|
|
362
|
+
const answered = await work(this.#mode)
|
|
363
|
+
holdUntil = answered.holdUntil
|
|
364
|
+
return { kind: 'ran', value: answered.value }
|
|
365
|
+
} finally {
|
|
366
|
+
if (holdUntil === null) {
|
|
367
|
+
done.resolve()
|
|
368
|
+
} else {
|
|
369
|
+
const release = () => done.resolve()
|
|
370
|
+
holdUntil.then(release, release)
|
|
371
|
+
}
|
|
372
|
+
}
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
/**
|
|
376
|
+
* After `request` is published: `open` ends the stretch, a mode that writes nothing keeps it or starts it at the
|
|
377
|
+
* request's generation. A failed put of the record is left to the cold start, which then starts the stretch anew.
|
|
378
|
+
*/
|
|
379
|
+
async #froze(request: OpsPublishedState): Promise<void> {
|
|
380
|
+
if (request.mode === 'open') {
|
|
381
|
+
this.#frozenSince = null
|
|
382
|
+
return
|
|
383
|
+
}
|
|
384
|
+
this.#frozenSince ??= request.generation
|
|
385
|
+
try {
|
|
386
|
+
await this.#store.putFrozen?.({ generation: request.generation, since: this.#frozenSince })
|
|
387
|
+
} catch {
|
|
388
|
+
// The stored record then names an older generation or none, which a cold start reads as a stretch starting anew.
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
#isPublished(): boolean {
|
|
393
|
+
return this.#stored !== null && this.#stored.generation === this.#generation && this.#stored.mode === this.#mode
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
/** Step 3: the conditional put; on success an opening transition switches memory, on a conflict R2 is read again. */
|
|
397
|
+
async #publish(request: OpsPublishedState): Promise<{ readonly kind: 'published' } | Exclude<TransitionResult, { kind: 'acknowledged' }>> {
|
|
398
|
+
for (let attempt = 0; attempt < PUT_ATTEMPTS; attempt++) {
|
|
399
|
+
let version: string | null
|
|
400
|
+
try {
|
|
401
|
+
version = await this.#store.put(request, this.#version)
|
|
402
|
+
} catch {
|
|
403
|
+
return { kind: 'failed' }
|
|
404
|
+
}
|
|
405
|
+
if (version !== null) {
|
|
406
|
+
this.#stored = request
|
|
407
|
+
this.#version = version
|
|
408
|
+
this.#mode = request.mode
|
|
409
|
+
this.#generation = request.generation
|
|
410
|
+
return { kind: 'published' }
|
|
411
|
+
}
|
|
412
|
+
let stored: StoredMaintenance | null
|
|
413
|
+
try {
|
|
414
|
+
stored = await this.#store.read()
|
|
415
|
+
} catch {
|
|
416
|
+
return { kind: 'failed' }
|
|
417
|
+
}
|
|
418
|
+
this.#version = stored?.version ?? null
|
|
419
|
+
this.#stored = stored?.state ?? null
|
|
420
|
+
// A higher generation, or the same one in another mode, is published elsewhere: adopted, never overwritten.
|
|
421
|
+
if (stored !== null && opsTransitionRefused(stored.state, request)) {
|
|
422
|
+
this.#mode = stored.state.mode
|
|
423
|
+
this.#generation = stored.state.generation
|
|
424
|
+
// What happened before it is unknown: its stretch starts at it.
|
|
425
|
+
this.#frozenSince = stored.state.mode === 'open' ? null : stored.state.generation
|
|
426
|
+
return { kind: 'stale', published: stored.state }
|
|
427
|
+
}
|
|
428
|
+
}
|
|
429
|
+
return { kind: 'failed' }
|
|
430
|
+
}
|
|
431
|
+
|
|
432
|
+
/** Step 4: stops every run the mode forbids, then waits for what it forbids to settle, within the bound. */
|
|
433
|
+
async #drain(): Promise<number> {
|
|
434
|
+
const admitted = ADMITTED[this.#mode]
|
|
435
|
+
for (const [stop, kind] of this.#stops) {
|
|
436
|
+
if (STOPPABLE.has(kind) && !admitted.has(kind)) {
|
|
437
|
+
stop.abort()
|
|
438
|
+
}
|
|
439
|
+
}
|
|
440
|
+
const running = () => [...this.#units].filter((unit) => !admitted.has(unit.kind)).length
|
|
441
|
+
if (running() === 0) {
|
|
442
|
+
return 0
|
|
443
|
+
}
|
|
444
|
+
const bound = Promise.withResolvers<void>()
|
|
445
|
+
const timer = setTimeout(bound.resolve, this.#drainBoundMs)
|
|
446
|
+
try {
|
|
447
|
+
while (running() > 0) {
|
|
448
|
+
const settled = Promise.withResolvers<void>()
|
|
449
|
+
this.#settled.push(settled.resolve)
|
|
450
|
+
if ((await Promise.race([settled.promise.then(() => 'settled' as const), bound.promise.then(() => 'bound' as const)])) === 'bound') {
|
|
451
|
+
break
|
|
452
|
+
}
|
|
453
|
+
}
|
|
454
|
+
} finally {
|
|
455
|
+
clearTimeout(timer)
|
|
456
|
+
}
|
|
457
|
+
return running()
|
|
458
|
+
}
|
|
459
|
+
|
|
460
|
+
#leave(unit: Unit): void {
|
|
461
|
+
this.#units.delete(unit)
|
|
462
|
+
const waiting = this.#settled
|
|
463
|
+
this.#settled = []
|
|
464
|
+
for (const resolve of waiting) {
|
|
465
|
+
resolve()
|
|
466
|
+
}
|
|
467
|
+
}
|
|
468
|
+
|
|
469
|
+
async #inTurn<T>(work: () => Promise<T>): Promise<T> {
|
|
470
|
+
const previous = this.#turn
|
|
471
|
+
const done = Promise.withResolvers<void>()
|
|
472
|
+
this.#turn = done.promise
|
|
473
|
+
await previous
|
|
474
|
+
try {
|
|
475
|
+
return await work()
|
|
476
|
+
} finally {
|
|
477
|
+
done.resolve()
|
|
478
|
+
}
|
|
479
|
+
}
|
|
480
|
+
}
|
|
481
|
+
|
|
482
|
+
/**
|
|
483
|
+
* The stretch a cold start resumes: none while `open`; the record's when it was written at the published generation;
|
|
484
|
+
* otherwise, conservatively, one starting at the published generation.
|
|
485
|
+
*/
|
|
486
|
+
function frozenOnLoad(state: OpsPublishedState, frozen: FrozenRecord | null): number | null {
|
|
487
|
+
if (state.mode === 'open') {
|
|
488
|
+
return null
|
|
489
|
+
}
|
|
490
|
+
return frozen !== null && frozen.generation === state.generation && frozen.since <= state.generation ? frozen.since : state.generation
|
|
491
|
+
}
|
|
492
|
+
|
|
493
|
+
/** How restrictive a mode is: `open` least, `inspect` most. */
|
|
494
|
+
function rank(mode: OpsMode): number {
|
|
495
|
+
return OPS_MODES.indexOf(mode)
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
/** One invocation's view of the barrier: the gate that admits and counts its work, and its write fence. */
|
|
499
|
+
export class BarrierEvent implements InvocationGate {
|
|
500
|
+
readonly #barrier: MaintenanceBarrier
|
|
501
|
+
readonly #generation: number | null
|
|
502
|
+
readonly #mode: OpsMode
|
|
503
|
+
|
|
504
|
+
constructor(barrier: MaintenanceBarrier, generation: number | null, mode: OpsMode) {
|
|
505
|
+
this.#barrier = barrier
|
|
506
|
+
this.#generation = generation
|
|
507
|
+
this.#mode = mode
|
|
508
|
+
}
|
|
509
|
+
|
|
510
|
+
admit(kind: InvocationKind): InvocationAdmission | null {
|
|
511
|
+
return this.#barrier.admit(kind, this.#generation)
|
|
512
|
+
}
|
|
513
|
+
|
|
514
|
+
/** Whether this invocation may commit a write now: still `open`, at the generation it was admitted under. */
|
|
515
|
+
writable(): boolean {
|
|
516
|
+
return this.#barrier.writable(this.#generation, this.#mode)
|
|
517
|
+
}
|
|
518
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
// The names the Cloudflare provider and the application's Worker share (ADR-0065); `@fabrika/app/build` exports them.
|
|
2
|
+
|
|
3
|
+
/** The Durable Object class the Cloudflare entry exports: one object per application environment runs it (ADR-0065). */
|
|
4
|
+
export const CLOUDFLARE_APPLICATION_CLASS = 'FabrikaApplication'
|
|
5
|
+
|
|
6
|
+
/** The binding through which the application's Worker reaches its object. */
|
|
7
|
+
export const CLOUDFLARE_APPLICATION_BINDING = 'FABRIKA_APPLICATION'
|
|
8
|
+
|
|
9
|
+
/** The R2 bucket binding of the environment's stored files. */
|
|
10
|
+
export const CLOUDFLARE_FILES_BINDING = 'FABRIKA_FILES'
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* The Workers Assets binding the SPA and link mounts serve their files from. Its directory mirrors the request paths:
|
|
14
|
+
* the mount `/admin` serves `<directory>/admin/…`, the root mount `<directory>/…`.
|
|
15
|
+
*/
|
|
16
|
+
export const CLOUDFLARE_ASSETS_BINDING = 'ASSETS'
|