oblaka-iac 0.0.19 → 0.0.21

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/README.md CHANGED
@@ -41,7 +41,7 @@ export default define(({ env }) => {
41
41
  EmailQueue: new Queue({ name: 'email-queue', binding: 'both' }),
42
42
  Room: new DurableObject({ name: 'Room', className: 'Room' }),
43
43
 
44
- // Sub-worker — gets its own wrangler.jsonc
44
+ // Sub-worker: gets its own wrangler.jsonc
45
45
  Admin: new Worker({
46
46
  dir: './packages/admin',
47
47
  name: 'my-app-admin',
@@ -92,21 +92,77 @@ bunx oblaka oblaka.ts \
92
92
 
93
93
  ## Resources
94
94
 
95
- | Resource | Description |
96
- | ------------------ | ------------------------------- |
97
- | `Worker` | Cloudflare Worker with bindings |
98
- | `D1Database` | D1 SQL database |
99
- | `KVNamespace` | KV key-value storage |
100
- | `R2Bucket` | R2 object storage |
101
- | `Queue` | Queue (producer/consumer) |
102
- | `DurableObject` | Durable Object |
103
- | `Workflow` | Cloudflare Workflow |
104
- | `Container` | Container |
105
- | `AnalyticsEngine` | Analytics Engine dataset |
106
- | `Browser` | Browser Rendering API binding |
107
- | `Images` | Image Optimization binding |
108
- | `ServiceReference` | Reference to another worker |
109
- | `VersionMetadata` | Version metadata binding |
95
+ Resources marked as provisioned are created through the Cloudflare API with `--remote` and tracked in the state. Workflows and containers get a per-environment name in the state and are created by `wrangler deploy`. Analytics Engine datasets are created by Cloudflare on the first write. The rest only add a binding to the generated config.
96
+
97
+ | Resource | Description | Provisioned |
98
+ | ------------------ | --------------------------------------------------- | ----------- |
99
+ | `Worker` | Cloudflare Worker with bindings | yes |
100
+ | `D1Database` | D1 SQL database, optional `migrationsDir` | yes |
101
+ | `KVNamespace` | KV key-value storage | yes |
102
+ | `R2Bucket` | R2 object storage | yes |
103
+ | `Queue` | Queue (producer, consumer or both) | yes |
104
+ | `DurableObject` | Durable Object class, see [below](#durable-objects) | |
105
+ | `Workflow` | Cloudflare Workflow | |
106
+ | `Container` | Container attached to a Durable Object class | |
107
+ | `AnalyticsEngine` | Analytics Engine dataset | |
108
+ | `VectorizeIndex` | Vectorize index | yes |
109
+ | `AiGateway` | Workers AI binding (`ai`) | |
110
+ | `AiSearch` | AI Search namespace | |
111
+ | `Browser` | Browser Rendering API binding | |
112
+ | `Images` | Image Optimization binding | |
113
+ | `EmailService` | Send Email binding | |
114
+ | `Flagship` | Flagship feature flags | |
115
+ | `VpcNetwork` | VPC network or Cloudflare Tunnel (`mesh`, `tunnel`) | |
116
+ | `WorkerLoader` | Worker Loader for dynamic workers | |
117
+ | `ServiceReference` | Reference to another worker by name | |
118
+ | `VersionMetadata` | Version metadata binding | |
119
+
120
+ ## Conditional bindings
121
+
122
+ A binding set to `false`, `null` or `undefined` is skipped, so it can depend on the environment:
123
+
124
+ ```typescript
125
+ bindings: {
126
+ Cache: new KVNamespace({ name: 'cache' }),
127
+ Analytics: env === 'production' && new AnalyticsEngine({ name: 'events' }),
128
+ },
129
+ ```
130
+
131
+ Don't make `DurableObject` or `Container` bindings conditional. All environments share one migration history in the generated file, so a run for an environment without the class would see it as removed (see [Durable Objects](#durable-objects)).
132
+
133
+ ## Durable Objects
134
+
135
+ Oblaka writes the Durable Object migrations (`new_sqlite_classes`, `renamed_classes`, `deleted_classes`) into the generated config and reads the history back from it on the next run, so the generated file has to be kept between runs.
136
+
137
+ Deleting a class deletes all its stored data, so oblaka never does it just because a binding disappeared. When a class that was bound in the previous generated config is no longer bound, the run fails before anything is created or written, until you say what should happen:
138
+
139
+ ```typescript
140
+ new Worker({
141
+ // ...
142
+ bindings: {
143
+ // Renamed from Room: the data moves to ChatRoom.
144
+ ChatRoom: new DurableObject({
145
+ name: 'chat-room',
146
+ className: 'ChatRoom',
147
+ renamedFrom: 'Room',
148
+ }),
149
+ },
150
+ // Deleted together with all their data.
151
+ deletedDurableObjects: ['OldCounter'],
152
+ })
153
+ ```
154
+
155
+ `renamedFrom` and `deletedDurableObjects` can stay in the definition after the change is deployed; once the migration is in the history they do nothing. Remove a `deletedDurableObjects` entry before binding a new class with the same name. `deleteDurableObjectsOnRemoval: true` deletes every removed class without listing it, and `false` keeps removed classes alive (for example a class used only through `ctx.exports`).
156
+
157
+ ## Types for `env`
158
+
159
+ Generate the `Env` type from the generated config with Wrangler:
160
+
161
+ ```bash
162
+ bunx oblaka oblaka.ts && bunx wrangler types
163
+ ```
164
+
165
+ `wrangler types` reads `wrangler.jsonc` in the worker directory and writes `worker-configuration.d.ts`, including Durable Object namespaces typed by their class from `main`. Run it in each worker directory, and pass `-c` when the config has a different name.
110
166
 
111
167
  ## CLI options
112
168
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "oblaka-iac",
3
- "version": "0.0.19",
3
+ "version": "0.0.21",
4
4
  "main": "./src/index.ts",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/src/auth.ts CHANGED
@@ -113,8 +113,10 @@ interface TokenEndpointResponse {
113
113
  refresh_token?: string
114
114
  }
115
115
 
116
+ type FetchFn = (url: string, init: RequestInit) => Promise<Response>
117
+
116
118
  interface RefreshDeps {
117
- fetch?: typeof fetch
119
+ fetch?: FetchFn
118
120
  tokenUrl?: string
119
121
  clientId?: string
120
122
  now?: () => number
@@ -140,7 +142,7 @@ export async function refreshAccessToken(
140
142
  })
141
143
  if (!response.ok) {
142
144
  throw new Error(
143
- `Failed to refresh Cloudflare OAuth token (${response.status}). Run \`wrangler login\` to re-authenticate.`,
145
+ `Failed to refresh Cloudflare OAuth token (${response.status}): ${await response.text()}\nRun \`wrangler login\` to re-authenticate.`,
144
146
  )
145
147
  }
146
148
  const data = (await response.json()) as TokenEndpointResponse
@@ -166,47 +168,92 @@ function tokenUrlFromEnv(): string {
166
168
  export interface WranglerTokenProviderOptions {
167
169
  configPath?: string
168
170
  now?: () => number
169
- fetch?: typeof fetch
171
+ fetch?: FetchFn
170
172
  /** Persist the refreshed token back to default.toml (default true). */
171
173
  persist?: boolean
172
174
  }
173
175
 
176
+ export interface WranglerTokenProvider {
177
+ /** Returns a valid access token, refreshing it once it is within the expiry buffer. */
178
+ getToken(): Promise<string>
179
+ /** Returns a replacement for an access token the API rejected, even if its stored expiry still looks valid. */
180
+ refreshToken(rejected: string): Promise<string>
181
+ }
182
+
174
183
  /**
175
- * Returns a token provider backed by wrangler's stored OAuth credentials. It
176
- * returns the access token while valid, refreshing (and persisting) it once it
177
- * is within the expiry buffer. The result is cached in memory for the process.
184
+ * Returns a token provider backed by wrangler's stored OAuth credentials. The
185
+ * current token is cached in memory for the process; refreshed tokens are
186
+ * persisted so wrangler and later runs pick them up.
178
187
  */
179
- export function createWranglerTokenProvider(options: WranglerTokenProviderOptions = {}): () => Promise<string> {
188
+ export function createWranglerTokenProvider(options: WranglerTokenProviderOptions = {}): WranglerTokenProvider {
180
189
  const configPath = options.configPath ?? getWranglerConfigPath()
181
190
  const now = options.now ?? Date.now
182
191
  const persist = options.persist ?? true
183
- let cached: { token: string; expiresAt: number } | null = null
192
+ // The newest credentials known to this process. With persist off (or a failed
193
+ // write) they are newer than the file, including a rotated refresh token.
194
+ let current: RefreshedCredentials & { expiresAt: number } | null = null
195
+ // The file's access token as of our last read or write; a different value
196
+ // means wrangler (or another run) updated the file since.
197
+ let lastFileToken: string | null = null
198
+ const rejectedTokens = new Set<string>()
199
+ // Shared so concurrent callers don't each spend the refresh token; Cloudflare
200
+ // may rotate it, which would make every refresh but the first fail.
201
+ let refreshing: Promise<string> | null = null
184
202
 
185
- return async () => {
186
- if (cached && cached.expiresAt - EXPIRY_BUFFER_MS > now()) {
187
- return cached.token
188
- }
203
+ const usable = (creds: { oauthToken: string; expiresAt: number } | null) =>
204
+ creds !== null && !rejectedTokens.has(creds.oauthToken) && Number.isFinite(creds.expiresAt)
205
+ && creds.expiresAt - EXPIRY_BUFFER_MS > now()
206
+
207
+ const syncFromFile = () => {
189
208
  const creds = readWranglerCredentials(configPath)
190
209
  if (!creds) {
191
210
  throw new Error(
192
211
  `No Cloudflare credentials found. Set CLOUDFLARE_API_TOKEN, or run \`wrangler login\` (looked in ${configPath}).`,
193
212
  )
194
213
  }
195
- const expiresAt = Date.parse(creds.expirationTime)
196
- if (Number.isFinite(expiresAt) && expiresAt - EXPIRY_BUFFER_MS > now()) {
197
- cached = { token: creds.oauthToken, expiresAt }
198
- return creds.oauthToken
214
+ if (current === null || creds.oauthToken !== lastFileToken) {
215
+ lastFileToken = creds.oauthToken
216
+ current = { ...creds, expiresAt: Date.parse(creds.expirationTime) }
199
217
  }
218
+ return current
219
+ }
200
220
 
201
- const refreshed = await refreshAccessToken(creds.refreshToken, { fetch: options.fetch, now })
221
+ const doRefresh = async (refreshToken: string): Promise<string> => {
222
+ const refreshed = await refreshAccessToken(refreshToken, { fetch: options.fetch, now })
223
+ current = { ...refreshed, expiresAt: Date.parse(refreshed.expirationTime) }
202
224
  if (persist) {
203
225
  try {
204
226
  writeWranglerCredentials(configPath, refreshed)
227
+ lastFileToken = refreshed.oauthToken
205
228
  } catch (error) {
206
229
  console.warn(`Warning: refreshed Cloudflare OAuth token but could not persist it to ${configPath}: ${error}`)
207
230
  }
208
231
  }
209
- cached = { token: refreshed.oauthToken, expiresAt: Date.parse(refreshed.expirationTime) }
210
232
  return refreshed.oauthToken
211
233
  }
234
+
235
+ const obtain = async (): Promise<string> => {
236
+ if (refreshing) {
237
+ return refreshing
238
+ }
239
+ if (current && usable(current)) {
240
+ return current.oauthToken
241
+ }
242
+ const latest = syncFromFile()
243
+ if (usable(latest)) {
244
+ return latest.oauthToken
245
+ }
246
+ refreshing = doRefresh(latest.refreshToken).finally(() => {
247
+ refreshing = null
248
+ })
249
+ return refreshing
250
+ }
251
+
252
+ return {
253
+ getToken: obtain,
254
+ refreshToken(rejected) {
255
+ rejectedTokens.add(rejected)
256
+ return obtain()
257
+ },
258
+ }
212
259
  }
package/src/client.ts CHANGED
@@ -5,6 +5,8 @@ export class CloudflareClient {
5
5
  private readonly config: {
6
6
  accountId: string
7
7
  getToken: () => Promise<string>
8
+ /** Returns a replacement for a token the API rejected with 401; the request is then retried once. */
9
+ refreshToken?: (rejected: string) => Promise<string>
8
10
  },
9
11
  ) {
10
12
  this.baseUrl = `https://api.cloudflare.com/client/v4/accounts/${config.accountId}`
@@ -16,19 +18,36 @@ export class CloudflareClient {
16
18
  body?: any
17
19
  headers?: Record<string, string>
18
20
  }): Promise<T> {
21
+ const send = (token: string) =>
22
+ fetch(`${this.baseUrl}${url}`, {
23
+ method,
24
+ headers: {
25
+ Authorization: `Bearer ${token}`,
26
+ ...(body ? { 'Content-Type': 'application/json' } : {}),
27
+ ...headers,
28
+ },
29
+ body: JSON.stringify(body),
30
+ })
31
+
19
32
  const token = await this.config.getToken()
20
- const response = await fetch(`${this.baseUrl}${url}`, {
21
- method,
22
- headers: {
23
- Authorization: `Bearer ${token}`,
24
- ...(body ? { 'Content-Type': 'application/json' } : {}),
25
- ...headers,
26
- },
27
- body: JSON.stringify(body),
28
- })
33
+ let response = await send(token)
34
+ let refreshed = false
35
+ if (response.status === 401 && this.config.refreshToken) {
36
+ const rejectedBody = await response.text()
37
+ let replacement: string
38
+ try {
39
+ replacement = await this.config.refreshToken(token)
40
+ } catch (error) {
41
+ const reason = error instanceof Error ? error.message : String(error)
42
+ throw new Error(`Failed to fetch ${url}: ${response.statusText} ${rejectedBody}\nRefreshing the token failed: ${reason}`, { cause: error })
43
+ }
44
+ response = await send(replacement)
45
+ refreshed = true
46
+ }
29
47
 
30
48
  if (!response.ok) {
31
- throw new Error(`Failed to fetch ${url}: ${response.statusText} ${await response.text()}`)
49
+ const hint = refreshed && response.status === 401 ? '\nThe refreshed token was rejected too; run `wrangler login` to re-authenticate.' : ''
50
+ throw new Error(`Failed to fetch ${url}: ${response.statusText} ${await response.text()}${hint}`)
32
51
  }
33
52
 
34
53
  const res: any = await response.json()
@@ -20,13 +20,12 @@ export class CloudflareDeployExecutor implements ResourceApplier {
20
20
  }): Promise<GeneratedConfig[]> {
21
21
  // An explicit API token wins; otherwise fall back to wrangler's stored
22
22
  // OAuth credentials (`wrangler login`).
23
- const getToken = input.apiToken
24
- ? async () => input.apiToken
25
- : createWranglerTokenProvider({ persist: input.persistToken })
26
- const cfClient = new CloudflareClient({
27
- accountId: input.accountId,
28
- getToken,
29
- })
23
+ const apiToken = input.apiToken
24
+ const cfClient = new CloudflareClient(
25
+ apiToken
26
+ ? { accountId: input.accountId, getToken: async () => apiToken }
27
+ : { accountId: input.accountId, ...createWranglerTokenProvider({ persist: input.persistToken }) },
28
+ )
30
29
 
31
30
  const stateStore = new KVStateStorage(cfClient, input.stateNamespace, input.stateNamespaceId)
32
31
  const stateKey = { env: input.env }
@@ -0,0 +1,169 @@
1
+ import { Container, DurableObject, type Worker } from '../resources'
2
+ import type { Config } from '../types'
3
+ import { type DurableObjectMigration, getLiveDurableObjectClasses, getNextMigrationTag, withDurableObjectClass } from '../utils/migrations'
4
+
5
+ export const getBoundDurableObjectClasses = (config: Config): Set<string> =>
6
+ new Set((config.durable_objects?.bindings ?? []).map((b: { class_name: string }) => b.class_name))
7
+
8
+ /**
9
+ * Checks the worker's Durable Object changes against its existing generated config, so a
10
+ * mistake fails the run before any resource is created or any config is written.
11
+ */
12
+ export const validateDurableObjects = (worker: Worker, existingConfig: Config): void => {
13
+ const workerName = worker.options.name
14
+ const deletedDurableObjects = worker.options.deletedDurableObjects ?? []
15
+ const classes = Object.values(worker.options.bindings ?? {}).flatMap(binding => {
16
+ if (binding instanceof DurableObject) {
17
+ return [{ className: binding.options.className, renamedFrom: binding.options.renamedFrom || undefined }]
18
+ }
19
+ if (binding instanceof Container) {
20
+ return [{ className: binding.options.className, renamedFrom: undefined }]
21
+ }
22
+ return []
23
+ })
24
+ const bound = new Set(classes.map(c => c.className))
25
+ const existingClasses = getLiveDurableObjectClasses(existingConfig.migrations)
26
+
27
+ // Bindings are configured one by one, so for a class that does not exist yet, differing renamedFrom values
28
+ // would make the outcome depend on their order. For an existing class renamedFrom does nothing.
29
+ const renamedFromByClass = new Map<string, string | undefined>()
30
+ for (const { className, renamedFrom } of classes) {
31
+ const other = renamedFromByClass.get(className)
32
+ if (renamedFromByClass.has(className) && other !== renamedFrom && !existingClasses.has(className)) {
33
+ throw new Error(
34
+ `Worker '${workerName}': Durable Object class '${className}' is bound more than once with a different renamedFrom `
35
+ + `(${formatRenamedFrom(other)} and ${formatRenamedFrom(renamedFrom)}). `
36
+ + 'Set the same renamedFrom on every DurableObject binding of the class. A Container binding cannot set renamedFrom.',
37
+ )
38
+ }
39
+ renamedFromByClass.set(className, other ?? renamedFrom)
40
+ }
41
+
42
+ const renameTargets = new Map<string, string>()
43
+ for (const [className, renamedFrom] of renamedFromByClass) {
44
+ if (!renamedFrom) {
45
+ continue
46
+ }
47
+ if (bound.has(renamedFrom)) {
48
+ throw new Error(
49
+ `Worker '${workerName}': Durable Object class '${className}' is renamed from '${renamedFrom}', which is still bound. `
50
+ + `Remove the '${renamedFrom}' binding.`,
51
+ )
52
+ }
53
+ const otherTarget = renameTargets.get(renamedFrom)
54
+ if (otherTarget) {
55
+ throw new Error(
56
+ `Worker '${workerName}': Durable Object classes '${otherTarget}' and '${className}' are both renamed from '${renamedFrom}'.`,
57
+ )
58
+ }
59
+ renameTargets.set(renamedFrom, className)
60
+ }
61
+
62
+ const deletedAndBound = deletedDurableObjects.filter(c => bound.has(c))
63
+ if (deletedAndBound.length > 0) {
64
+ throw new Error(
65
+ `Worker '${workerName}': Durable Object class ${formatClasses(deletedAndBound)} is listed in deletedDurableObjects but bound. `
66
+ + 'Remove the binding, or remove the class from deletedDurableObjects.',
67
+ )
68
+ }
69
+
70
+ // The same migrations the bindings will produce, so renames are taken into account.
71
+ let migrations: DurableObjectMigration[] | undefined = existingConfig.migrations
72
+ for (const [className, renamedFrom] of renamedFromByClass) {
73
+ migrations = withDurableObjectClass({ migrations }, className, renamedFrom)
74
+ }
75
+
76
+ getRemovedDurableObjects({
77
+ workerName,
78
+ migrations,
79
+ previouslyBound: getBoundDurableObjectClasses(existingConfig),
80
+ bound,
81
+ deletedDurableObjects,
82
+ deleteDurableObjectsOnRemoval: worker.options.deleteDurableObjectsOnRemoval,
83
+ })
84
+ }
85
+
86
+ /**
87
+ * Returns the Durable Object classes to delete: live classes that are not bound and either
88
+ * listed in `deletedDurableObjects`, or bound in the previous config with
89
+ * `deleteDurableObjectsOnRemoval: true`. Throws for a class that was bound in the previous
90
+ * config and is no longer, when neither says what to do with it, because deleting a class
91
+ * deletes all its stored data. Live classes that were not bound before are left alone.
92
+ */
93
+ export const getRemovedDurableObjects = (args: {
94
+ workerName: string
95
+ migrations: DurableObjectMigration[] | undefined
96
+ previouslyBound: Set<string>
97
+ bound: Set<string>
98
+ deletedDurableObjects: string[]
99
+ deleteDurableObjectsOnRemoval: boolean | undefined
100
+ }): string[] => {
101
+ const unbound = [...getLiveDurableObjectClasses(args.migrations)].filter(c => !args.bound.has(c))
102
+ const toDelete = unbound.filter(c =>
103
+ args.deletedDurableObjects.includes(c) || (args.previouslyBound.has(c) && args.deleteDurableObjectsOnRemoval === true)
104
+ )
105
+ const unresolved = unbound.filter(c => args.previouslyBound.has(c) && !toDelete.includes(c))
106
+
107
+ if (unresolved.length > 0 && args.deleteDurableObjectsOnRemoval !== false) {
108
+ throw new Error(
109
+ `Worker '${args.workerName}': Durable Object class ${formatClasses(unresolved)} is no longer bound. `
110
+ + 'Deleting a class deletes all its stored data, so oblaka will not do it implicitly. '
111
+ + 'Add the class to deletedDurableObjects to delete it, set renamedFrom on the new DurableObject binding if it was renamed '
112
+ + '(a Container binding cannot rename a class), '
113
+ + 'or set deleteDurableObjectsOnRemoval: false to keep it without a binding.',
114
+ )
115
+ }
116
+ return toDelete
117
+ }
118
+
119
+ /**
120
+ * Appends a `deleted_classes` migration. A class that was created once and never renamed,
121
+ * transferred or deleted before is also dropped from its `new_sqlite_classes` entry; with a
122
+ * longer history the earlier migrations are kept, so they stay consistent with each other.
123
+ */
124
+ export const deleteDurableObjectClasses = (config: Config, classes: string[]): Config => {
125
+ if (classes.length === 0) {
126
+ return config
127
+ }
128
+ const migrations = config.migrations ?? []
129
+ const stripped = new Set(classes.filter(c => hasSingleCreation(migrations, c)))
130
+
131
+ return {
132
+ ...config,
133
+ migrations: [
134
+ ...(config.migrations ?? []).flatMap(m => {
135
+ if (!m.new_sqlite_classes) return [m]
136
+ const filtered = m.new_sqlite_classes.filter((c: string) => !stripped.has(c))
137
+ if (filtered.length === 0) {
138
+ const { new_sqlite_classes: _, ...rest } = m
139
+ return Object.keys(rest).length > 1 ? [rest as typeof m] : []
140
+ }
141
+ return [{ ...m, new_sqlite_classes: filtered }]
142
+ }),
143
+ {
144
+ tag: getNextMigrationTag(config),
145
+ deleted_classes: classes,
146
+ },
147
+ ],
148
+ }
149
+ }
150
+
151
+ const hasSingleCreation = (migrations: DurableObjectMigration[], className: string): boolean => {
152
+ let creations = 0
153
+ for (const m of migrations) {
154
+ creations += (m.new_sqlite_classes ?? []).filter(c => c === className).length
155
+ if (
156
+ m.new_classes?.includes(className)
157
+ || m.deleted_classes?.includes(className)
158
+ || m.renamed_classes?.some(r => r.from === className || r.to === className)
159
+ || m.transferred_classes?.some(t => t.to === className)
160
+ ) {
161
+ return false
162
+ }
163
+ }
164
+ return creations === 1
165
+ }
166
+
167
+ const formatClasses = (classes: string[]) => classes.map(c => `'${c}'`).join(', ')
168
+
169
+ const formatRenamedFrom = (renamedFrom: string | undefined) => (renamedFrom ? `'${renamedFrom}'` : 'none')
@@ -3,7 +3,7 @@ import * as fs from 'node:fs/promises'
3
3
  import * as path from 'node:path'
4
4
  import { Worker } from '../resources'
5
5
  import type { Config, DefineFn, Resource } from '../types'
6
- import { getNextMigrationTag } from '../utils/migrations'
6
+ import { deleteDurableObjectClasses, getBoundDurableObjectClasses, getRemovedDurableObjects, validateDurableObjects } from './durable-objects'
7
7
  import { tryReadFile } from './utils/fs'
8
8
 
9
9
  export const DEFAULT_CONFIG_FILE_NAME = 'wrangler.jsonc'
@@ -54,6 +54,7 @@ export class ResourceProcessor {
54
54
  const generated: GeneratedConfig[] = []
55
55
 
56
56
  if (definition) {
57
+ await this.validate(definition)
57
58
  this.workers.push(definition)
58
59
  }
59
60
 
@@ -67,14 +68,33 @@ export class ResourceProcessor {
67
68
  return generated
68
69
  }
69
70
 
71
+ /** Checks every worker in the tree before any resource is applied or any config is written. */
72
+ private async validate(root: Worker): Promise<void> {
73
+ const queue = [root]
74
+ while (queue.length) {
75
+ const worker = queue.shift()!
76
+ validateDurableObjects(worker, await this.readExistingConfig(worker))
77
+ for (const binding of Object.values(worker.options.bindings ?? {})) {
78
+ if (binding instanceof Worker) {
79
+ queue.push(binding)
80
+ }
81
+ }
82
+ }
83
+ }
84
+
85
+ private async readExistingConfig(worker: Worker): Promise<Config> {
86
+ const configPath = path.join(worker.options.dir, this.configFileName)
87
+ return jsoncParser.parse((await tryReadFile(configPath)) || '{}') as Config
88
+ }
89
+
70
90
  private async processWorker(env: string): Promise<GeneratedConfig | undefined> {
71
91
  const worker = this.workers.shift()
72
92
  if (!worker) {
73
93
  return undefined
74
94
  }
75
95
  const configPath = path.join(worker.options.dir, this.configFileName)
76
- const existingConfig = jsoncParser.parse((await tryReadFile(configPath)) || '{}') as Config
77
- const { bindings, dir, deleteDurableObjectsOnRemoval, ...workerConfig } = worker.options
96
+ const existingConfig = await this.readExistingConfig(worker)
97
+ const { bindings, dir, deleteDurableObjectsOnRemoval, deletedDurableObjects, ...workerConfig } = worker.options
78
98
 
79
99
  let config: Config = {
80
100
  ...workerConfig,
@@ -84,7 +104,10 @@ export class ResourceProcessor {
84
104
  const selfState = await this.resourceHandler.applyResource(worker)
85
105
  config = worker.configureSelf({ config, state: selfState })
86
106
 
87
- for (const [bindingName, binding] of Object.entries(worker.options.bindings ?? {})) {
107
+ for (const [bindingName, binding] of Object.entries(bindings ?? {})) {
108
+ if (!binding) {
109
+ continue
110
+ }
88
111
  if (binding instanceof Worker) {
89
112
  this.workers.push(binding)
90
113
  }
@@ -92,34 +115,15 @@ export class ResourceProcessor {
92
115
  config = binding.configureBinding({ config, binding: bindingName, state, env })
93
116
  }
94
117
 
95
- if (deleteDurableObjectsOnRemoval !== false) {
96
- const oldClasses = new Set((existingConfig.durable_objects?.bindings ?? []).map((b: { class_name: string }) => b.class_name))
97
- const newClasses = new Set((config.durable_objects?.bindings ?? []).map((b: { class_name: string }) => b.class_name))
98
- const deletedClasses = [...oldClasses].filter(c => !newClasses.has(c))
99
-
100
- if (deletedClasses.length > 0) {
101
- const deletedClassesSet = new Set(deletedClasses)
102
- config = {
103
- ...config,
104
- migrations: [
105
- ...(config.migrations ?? [])
106
- .flatMap(m => {
107
- if (!m.new_sqlite_classes) return [m]
108
- const filtered = m.new_sqlite_classes.filter((c: string) => !deletedClassesSet.has(c))
109
- if (filtered.length === 0) {
110
- const { new_sqlite_classes: _, ...rest } = m
111
- return Object.keys(rest).length > 1 ? [rest as typeof m] : []
112
- }
113
- return [{ ...m, new_sqlite_classes: filtered }]
114
- }),
115
- {
116
- tag: getNextMigrationTag(config),
117
- deleted_classes: deletedClasses,
118
- },
119
- ],
120
- }
121
- }
122
- }
118
+ const removedDurableObjects = getRemovedDurableObjects({
119
+ workerName: worker.options.name,
120
+ migrations: config.migrations,
121
+ previouslyBound: getBoundDurableObjectClasses(existingConfig),
122
+ bound: getBoundDurableObjectClasses(config),
123
+ deletedDurableObjects: deletedDurableObjects ?? [],
124
+ deleteDurableObjectsOnRemoval,
125
+ })
126
+ config = deleteDurableObjectClasses(config, removedDurableObjects)
123
127
 
124
128
  const content = `/**\n * File is auto generated DO NOT EDIT\n */\n${JSON.stringify(config, null, '\t')}\n`
125
129
  await this.configWriter(configPath, content)
@@ -1,5 +1,5 @@
1
1
  import type { BindableResource, Config, Context, ResourceDestroyer } from '../types'
2
- import { getNextMigrationTag } from '../utils/migrations'
2
+ import { withDurableObjectClass } from '../utils/migrations'
3
3
 
4
4
  export interface ContainerState {
5
5
  name: string
@@ -47,23 +47,9 @@ export class Container implements BindableResource<ContainerState> {
47
47
  }
48
48
 
49
49
  configureBinding(args: { config: Config; binding: string; state?: ContainerState; env: string }): Config {
50
- const hasMigration = args.config?.migrations?.find((it: { new_sqlite_classes?: string[] }) =>
51
- it.new_sqlite_classes?.includes(this.options.className)
52
- )
53
-
54
50
  return {
55
51
  ...args.config,
56
- migrations: [
57
- ...(args.config.migrations ?? []),
58
- ...(hasMigration
59
- ? []
60
- : [
61
- {
62
- tag: getNextMigrationTag(args.config),
63
- new_sqlite_classes: [this.options.className],
64
- },
65
- ]),
66
- ],
52
+ migrations: withDurableObjectClass(args.config, this.options.className),
67
53
  containers: [
68
54
  ...(args.config.containers ?? []),
69
55
  {
@@ -1,5 +1,5 @@
1
1
  import type { BindableResource, Config, ResourceDestroyer } from '../types'
2
- import { getNextMigrationTag } from '../utils/migrations'
2
+ import { withDurableObjectClass } from '../utils/migrations'
3
3
 
4
4
  export interface DurableObjectState {
5
5
  name: string
@@ -10,6 +10,12 @@ export class DurableObject implements BindableResource<DurableObjectState> {
10
10
  public readonly options: {
11
11
  name: string
12
12
  className: string
13
+ /**
14
+ * Previous class name when the class was renamed. Generates a `renamed_classes`
15
+ * migration, so the stored data moves to the new class instead of being deleted.
16
+ * Safe to keep after the rename is deployed.
17
+ */
18
+ renamedFrom?: string
13
19
  },
14
20
  ) {}
15
21
 
@@ -24,21 +30,9 @@ export class DurableObject implements BindableResource<DurableObjectState> {
24
30
  }
25
31
 
26
32
  configureBinding(args: { config: Config; state?: DurableObjectState; binding: string; env: string }): Config {
27
- const hasMigration = args.config?.migrations?.find(
28
- (it: { new_sqlite_classes?: string[]; renamed_classes?: { from: string; to: string }[] }) =>
29
- it.new_sqlite_classes?.includes(this.options.className)
30
- || it.renamed_classes?.some(r => r.to === this.options.className),
31
- )
32
-
33
33
  return {
34
34
  ...args.config,
35
- migrations: [
36
- ...(args.config.migrations ?? []),
37
- ...(hasMigration ? [] : [{
38
- tag: getNextMigrationTag(args.config),
39
- new_sqlite_classes: [this.options.className],
40
- }]),
41
- ],
35
+ migrations: withDurableObjectClass(args.config, this.options.className, this.options.renamedFrom),
42
36
  durable_objects: {
43
37
  ...(args.config?.durable_objects ?? {}),
44
38
  bindings: [
@@ -11,7 +11,21 @@ export class Worker implements BindableResource<WorkerState> {
11
11
  dir: string
12
12
  name: string
13
13
  compatibility_flags: CompatibilityFlags[]
14
- bindings: Record<string, AnyBindable>
14
+ /** Entries set to `false`, `null` or `undefined` are skipped, so a binding can be conditional. */
15
+ bindings: Record<string, AnyBindable | false | null | undefined>
16
+ /**
17
+ * Durable Object classes to delete together with all their stored data. A class
18
+ * removed from `bindings` without being listed here fails the run, so data is never
19
+ * deleted by accident. Entries for classes that are already deleted do nothing; remove
20
+ * the entry before binding a new class with the same name.
21
+ */
22
+ deletedDurableObjects?: string[]
23
+ /**
24
+ * What to do with a Durable Object class that was bound in the previous generated config,
25
+ * is no longer bound and is not listed in `deletedDurableObjects`. Unset fails the run,
26
+ * `true` deletes the class and its data, `false` keeps the class (for example when it is
27
+ * used only through `ctx.exports`).
28
+ */
15
29
  deleteDurableObjectsOnRemoval?: boolean
16
30
  }
17
31
  & Partial<
@@ -10,3 +10,60 @@ export const getNextMigrationTag = (config: { migrations?: { tag: string }[] })
10
10
  const nextVersion = currentVersion + 1
11
11
  return `v${String(nextVersion).padStart(4, '0')}`
12
12
  }
13
+
14
+ export interface DurableObjectMigration {
15
+ tag: string
16
+ new_classes?: string[]
17
+ new_sqlite_classes?: string[]
18
+ renamed_classes?: { from: string; to: string }[]
19
+ deleted_classes?: string[]
20
+ transferred_classes?: { from: string; from_script: string; to: string }[]
21
+ }
22
+
23
+ /**
24
+ * Replays the migration history in tag order and returns the Durable Object classes
25
+ * that exist after the last migration.
26
+ */
27
+ export const getLiveDurableObjectClasses = (migrations: DurableObjectMigration[] | undefined): Set<string> => {
28
+ const live = new Set<string>()
29
+ // Same ordering as getNextMigrationTag.
30
+ const ordered = [...(migrations ?? [])].sort((a, b) => (a.tag < b.tag ? -1 : a.tag > b.tag ? 1 : 0))
31
+ for (const migration of ordered) {
32
+ for (const className of [...(migration.new_classes ?? []), ...(migration.new_sqlite_classes ?? [])]) {
33
+ live.add(className)
34
+ }
35
+ for (const { from, to } of migration.renamed_classes ?? []) {
36
+ live.delete(from)
37
+ live.add(to)
38
+ }
39
+ for (const { to } of migration.transferred_classes ?? []) {
40
+ live.add(to)
41
+ }
42
+ for (const className of migration.deleted_classes ?? []) {
43
+ live.delete(className)
44
+ }
45
+ }
46
+ return live
47
+ }
48
+
49
+ /**
50
+ * Returns the migrations with one appended that creates `className`, or renames
51
+ * `renamedFrom` to it when that class still exists. Returns them unchanged when
52
+ * `className` already exists.
53
+ */
54
+ export const withDurableObjectClass = <TMigration extends { tag: string }>(
55
+ config: { migrations?: TMigration[] },
56
+ className: string,
57
+ renamedFrom?: string,
58
+ ): (TMigration | DurableObjectMigration)[] => {
59
+ const migrations = config.migrations ?? []
60
+ const live = getLiveDurableObjectClasses(migrations)
61
+ if (live.has(className)) {
62
+ return migrations
63
+ }
64
+ const tag = getNextMigrationTag(config)
65
+ if (renamedFrom && live.has(renamedFrom)) {
66
+ return [...migrations, { tag, renamed_classes: [{ from: renamedFrom, to: className }] }]
67
+ }
68
+ return [...migrations, { tag, new_sqlite_classes: [className] }]
69
+ }