@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 504 lines 18.1 KB
Raw
1 import * as s3 from "@distilled.cloud/aws/s3";
2 import { decodeFqn, encodeFqn } from "alchemy/FQN";
3 import { encodeState, reviveState } from "alchemy/State/StateEncoding";
4 import * as Arr from "effect/Array";
5 import * as Clock from "effect/Clock";
6 import * as Data from "effect/Data";
7 import * as Effect from "effect/Effect";
8 import * as Schedule from "effect/Schedule";
9 import * as Semaphore from "effect/Semaphore";
10 import * as Stream from "effect/Stream";
11
12 /**
13 * The S3 state store's object layout, read and written directly: what the
14 * DynamoDB store checks for a stage that hasn't moved yet, and what
15 * `alchemy state migrate` copies from (and, rolling back, to).
16 *
17 * ```
18 * s3://{bucket}/{prefix}{stack}/{stage}/{fqn}.json
19 * s3://{bucket}/{prefix}{stack}/{stage}/__stack_output__.json
20 * s3://{bucket}/{prefix}{stack}/{stage}/__lease__.json
21 * ```
22 */
23
24 /** Where an S3 state store keeps its objects. */
25 export interface LegacyLocation {
26 readonly bucket: string;
27 /** Normalized: empty, or ending in `/`. */
28 readonly prefix: string;
29 }
30
31 const OUTPUT_FILE = "__stack_output__.json";
32 const LEASE_FILE = "__lease__.json";
33
34 /**
35 * The token of the lease a migrated stage keeps forever. Every S3 store
36 * since 2.0.0-beta.84 reads a lease that expires in the future as held by
37 * another deploy. Earlier versions take no lease; the bucket policy
38 * {@link setStageAccess} writes stops those.
39 */
40 export const FENCE_TOKEN = "migrated:dynamodb";
41
42 /** How a state store's error says another deploy holds a stage's lease. */
43 export const HELD_PREFIX = "another deploy holds";
44
45 /** Whether a state store failed because another deploy holds the stage. */
46 export const isLeaseHeld = (error: { readonly message: string }) =>
47 error.message.startsWith(HELD_PREFIX);
48
49 /** Maximum number of keys S3 accepts in one DeleteObjects call. */
50 const DELETE_BATCH_SIZE = 1000;
51
52 /** An S3 store object that can't be read, or a lease that can't be taken. */
53 export class LegacyStateError extends Data.TaggedError("LegacyStateError")<{
54 readonly message: string;
55 }> {}
56
57 class EmptyBody extends Data.TaggedError("EmptyBody") {}
58
59 export const normalizePrefix = (prefix: string | undefined) =>
60 prefix ? `${prefix.replace(/\/+$/, "")}/` : "";
61
62 const stagePrefix = (location: LegacyLocation, stack: string, stage: string) =>
63 `${location.prefix}${stack}/${stage}/`;
64
65 const recordKey = (location: LegacyLocation, stack: string, stage: string, fqn: string) =>
66 `${stagePrefix(location, stack, stage)}${encodeFqn(fqn)}.json`;
67
68 /** The JSON text of an object, or `undefined` when it or its bucket is missing. */
69 const readText = (bucket: string, key: string) =>
70 s3.getObject({ Bucket: bucket, Key: key }).pipe(
71 Effect.flatMap((result) =>
72 result.Body === undefined
73 ? Effect.undefined
74 : result.Body.pipe(
75 Stream.decodeText,
76 Stream.mkString,
77 Effect.map((text) => ({ text, etag: result.ETag })),
78 ),
79 ),
80 Effect.catchTag(["NoSuchKey", "NoSuchBucket"], () => Effect.undefined),
81 );
82
83 /** Every key under `prefix`, across pagination. A missing bucket has none. */
84 const listKeys = (bucket: string, prefix: string) =>
85 s3.listObjectsV2.pages({ Bucket: bucket, Prefix: prefix }).pipe(
86 Stream.flatMap((page) => Stream.fromIterable(page.Contents ?? [])),
87 Stream.map((object) => object.Key),
88 Stream.filter((key): key is string => key !== undefined),
89 Stream.runCollect,
90 Effect.map((keys) => Array.from(keys)),
91 Effect.catchTag("NoSuchBucket", () => Effect.succeed<string[]>([])),
92 );
93
94 /** The "directory" names directly under `prefix`. A missing bucket has none. */
95 const listChildren = (bucket: string, prefix: string) =>
96 s3.listObjectsV2.pages({ Bucket: bucket, Prefix: prefix, Delimiter: "/" }).pipe(
97 Stream.flatMap((page) => Stream.fromIterable(page.CommonPrefixes ?? [])),
98 Stream.map((common) => common.Prefix),
99 Stream.filter((p): p is string => p !== undefined),
100 Stream.map((p) => p.slice(prefix.length, -1)),
101 Stream.runCollect,
102 Effect.map((names) => Array.from(names)),
103 Effect.catchTag("NoSuchBucket", () => Effect.succeed<string[]>([])),
104 );
105
106 /** Whether the S3 store has any object, a lease included, for the stage. */
107 export const hasLegacyStage = (location: LegacyLocation, stack: string, stage: string) =>
108 s3
109 .listObjectsV2({
110 Bucket: location.bucket,
111 Prefix: stagePrefix(location, stack, stage),
112 MaxKeys: 1,
113 })
114 .pipe(
115 Effect.map((result) => (result.Contents?.length ?? 0) > 0),
116 Effect.catchTag("NoSuchBucket", () => Effect.succeed(false)),
117 );
118
119 export const listLegacyStacks = (location: LegacyLocation) =>
120 listChildren(location.bucket, location.prefix);
121
122 export const listLegacyStages = (location: LegacyLocation, stack: string) =>
123 listChildren(location.bucket, `${location.prefix}${stack}/`);
124
125 const parse = (text: string, key: string) =>
126 Effect.try({
127 try: () => JSON.parse(text, reviveState) as unknown,
128 catch: (cause) =>
129 new LegacyStateError({
130 message: `Failed to parse S3 state object '${key}': ${String(cause)}`,
131 }),
132 });
133
134 /** The stage's output, read without the S3 store's lease. */
135 export const readLegacyOutput = (location: LegacyLocation, stack: string, stage: string) => {
136 const key = `${stagePrefix(location, stack, stage)}${OUTPUT_FILE}`;
137 return readText(location.bucket, key).pipe(
138 Effect.flatMap((object) => (object === undefined ? Effect.undefined : parse(object.text, key))),
139 );
140 };
141
142 /** A stage's contents, each value encoded the way the DynamoDB store stores it. */
143 export interface StageContents {
144 /** Encoded state by FQN. */
145 readonly records: ReadonlyMap<string, string>;
146 readonly output: string | undefined;
147 }
148
149 /** Re-encode stored JSON into the DynamoDB store's canonical form. */
150 const canonical = (text: string, key: string) =>
151 parse(text, key).pipe(Effect.map((value) => JSON.stringify(encodeState(value))));
152
153 /** Read every record and the output of a stage. */
154 export const readLegacyStage = Effect.fn(function* (
155 location: LegacyLocation,
156 stack: string,
157 stage: string,
158 ) {
159 const prefix = stagePrefix(location, stack, stage);
160 const keys = yield* listKeys(location.bucket, prefix);
161 const recordKeys = keys.filter((key) => {
162 const file = key.slice(prefix.length);
163 return file !== OUTPUT_FILE && file !== LEASE_FILE && file.endsWith(".json");
164 });
165 const records = yield* Effect.forEach(
166 recordKeys,
167 (key) =>
168 Effect.gen(function* () {
169 const result = yield* s3.getObject({ Bucket: location.bucket, Key: key });
170 if (result.Body === undefined) return yield* new EmptyBody();
171 return yield* result.Body.pipe(
172 Stream.decodeText,
173 Stream.mkString,
174 Effect.mapError(
175 (cause) =>
176 new LegacyStateError({
177 message: `Failed to read S3 state object '${key}': ${cause}`,
178 }),
179 ),
180 );
181 }).pipe(
182 // A response without its body is a transport hiccup, and a key
183 // just listed can briefly read as missing: read again. Deletes are
184 // denied while the stage is fenced, so a key that stays missing
185 // was deleted by something the fence doesn't stop.
186 Effect.retry({
187 while: (error) => error._tag === "EmptyBody" || error._tag === "NoSuchKey",
188 schedule: Schedule.spaced("1 second"),
189 times: 4,
190 }),
191 Effect.catchTags({
192 EmptyBody: () =>
193 Effect.fail(new LegacyStateError({ message: `S3 state object '${key}' has no body` })),
194 // Listed but gone: something is writing the stage. Copying the
195 // rest would leave a resource untracked.
196 NoSuchKey: (error) =>
197 Effect.fail(
198 new LegacyStateError({
199 message: `S3 state object '${key}' was deleted while '${stack}/${stage}' was being read; another deploy is writing it (${error.message ?? "NoSuchKey"})`,
200 }),
201 ),
202 }),
203 Effect.flatMap((text) =>
204 canonical(text, key).pipe(
205 Effect.map((canonicalText) => [
206 [decodeFqn(key.slice(prefix.length).replace(/\.json$/, "")), canonicalText] as const,
207 ]),
208 ),
209 ),
210 ),
211 { concurrency: 16 },
212 );
213 const outputKey = `${prefix}${OUTPUT_FILE}`;
214 const output = keys.includes(outputKey)
215 ? yield* readText(location.bucket, outputKey).pipe(
216 Effect.flatMap((object) =>
217 object === undefined ? Effect.undefined : canonical(object.text, outputKey),
218 ),
219 )
220 : undefined;
221 return { records: new Map(records.flat()), output } satisfies StageContents;
222 });
223
224 /**
225 * Write a stage back in the S3 store's layout, deleting records it no longer
226 * has. The stage must be fenced, so no S3 store writes it meanwhile.
227 */
228 export const writeLegacyStage = Effect.fn(function* (
229 location: LegacyLocation,
230 stack: string,
231 stage: string,
232 contents: StageContents,
233 ) {
234 const prefix = stagePrefix(location, stack, stage);
235 const pretty = (text: string) => JSON.stringify(JSON.parse(text), null, 2);
236 yield* Effect.forEach(
237 Array.from(contents.records),
238 ([fqn, text]) =>
239 s3.putObject({
240 Bucket: location.bucket,
241 Key: recordKey(location, stack, stage, fqn),
242 Body: pretty(text),
243 ContentType: "application/json",
244 }),
245 { concurrency: 16, discard: true },
246 );
247 const outputKey = `${prefix}${OUTPUT_FILE}`;
248 if (contents.output !== undefined) {
249 yield* s3.putObject({
250 Bucket: location.bucket,
251 Key: outputKey,
252 Body: pretty(contents.output),
253 ContentType: "application/json",
254 });
255 }
256 const keep = new Set([
257 `${prefix}${LEASE_FILE}`,
258 ...(contents.output === undefined ? [] : [outputKey]),
259 ...Array.from(contents.records.keys(), (fqn) => recordKey(location, stack, stage, fqn)),
260 ]);
261 const stale = (yield* listKeys(location.bucket, prefix)).filter((key) => !keep.has(key));
262 yield* Effect.forEach(
263 Arr.chunksOf(stale, DELETE_BATCH_SIZE),
264 (batch) =>
265 s3.deleteObjects({
266 Bucket: location.bucket,
267 Delete: { Objects: batch.map((Key) => ({ Key })), Quiet: true },
268 }),
269 { discard: true },
270 );
271 });
272
273 const parseLease = (text: string) => {
274 try {
275 const parsed = JSON.parse(text) as { token?: unknown; expiresAt?: unknown };
276 return {
277 token: typeof parsed.token === "string" ? parsed.token : "",
278 expiresAt: typeof parsed.expiresAt === "number" ? parsed.expiresAt : 0,
279 };
280 } catch {
281 return { token: "", expiresAt: 0 };
282 }
283 };
284
285 export type FenceResult =
286 /** The stage is fenced: this call fenced it, or an earlier migration did. */
287 | { readonly fenced: true }
288 /** An S3 store holds the stage's lease. */
289 | { readonly fenced: false; readonly expiresAt: number };
290
291 /**
292 * Take the stage's S3 lease for good: write a lease that never expires, with
293 * the same conditional puts the S3 store uses, so a deploy holding the lease
294 * keeps it and a lapsed one is replaced.
295 */
296 export const fenceLegacyStage = (
297 location: LegacyLocation,
298 stack: string,
299 stage: string,
300 table: string,
301 ) => {
302 const key = `${stagePrefix(location, stack, stage)}${LEASE_FILE}`;
303 const body = JSON.stringify({
304 token: FENCE_TOKEN,
305 expiresAt: Number.MAX_SAFE_INTEGER,
306 migratedTo: `dynamodb:${table}`,
307 });
308 // `undefined` when a conditional put lost to another writer.
309 const attempt = Effect.gen(function* () {
310 const existing = yield* readText(location.bucket, key);
311 if (existing !== undefined) {
312 const lease = parseLease(existing.text);
313 if (lease.token === FENCE_TOKEN) return { fenced: true } as FenceResult;
314 if (lease.expiresAt > (yield* Clock.currentTimeMillis)) {
315 return { fenced: false, expiresAt: lease.expiresAt } as FenceResult;
316 }
317 }
318 return yield* s3
319 .putObject({
320 Bucket: location.bucket,
321 Key: key,
322 Body: body,
323 ContentType: "application/json",
324 ...(existing === undefined ? { IfNoneMatch: "*" } : { IfMatch: existing.etag }),
325 })
326 .pipe(
327 Effect.as<FenceResult | undefined>({ fenced: true }),
328 Effect.catchTag(
329 ["PreconditionFailed", "ConditionalRequestConflict"],
330 () => Effect.undefined,
331 ),
332 // No S3 store has ever written here: there is nothing to fence.
333 Effect.catchTag("NoSuchBucket", () => Effect.succeed<FenceResult>({ fenced: true })),
334 );
335 });
336 // A lost condition means another writer got there first: look again.
337 return attempt.pipe(
338 Effect.repeat({ until: (result) => result !== undefined, times: 4 }),
339 Effect.flatMap((result) =>
340 result === undefined
341 ? Effect.fail(
342 new LegacyStateError({
343 message: `Could not fence S3 state stage '${stack}/${stage}': its lease kept changing`,
344 }),
345 )
346 : Effect.succeed(result),
347 ),
348 );
349 };
350
351 /** Remove the stage's fence, so S3 stores can take its lease again. */
352 export const unfenceLegacyStage = (location: LegacyLocation, stack: string, stage: string) => {
353 const key = `${stagePrefix(location, stack, stage)}${LEASE_FILE}`;
354 return readText(location.bucket, key).pipe(
355 Effect.flatMap((existing) =>
356 existing === undefined || parseLease(existing.text).token !== FENCE_TOKEN
357 ? Effect.void
358 : s3
359 .deleteObject({ Bucket: location.bucket, Key: key, IfMatch: existing.etag })
360 .pipe(Effect.asVoid),
361 ),
362 );
363 };
364
365 /**
366 * What the bucket policy lets every principal do with a stage's objects:
367 *
368 * - `open`: what IAM allows.
369 * - `fenced`: no writes or deletes, while the stage is copied.
370 * - `migrated`: no reads, writes or deletes. A version of alchemy that takes
371 * no lease fails at its first read, before it deploys anything.
372 */
373 export type StageAccess = "open" | "fenced" | "migrated";
374
375 const FENCED_SID = "AlchemyStateFenced";
376 const MIGRATED_SID = "AlchemyStateMigrated";
377 const DENIED_ACTIONS = {
378 [FENCED_SID]: ["s3:PutObject", "s3:DeleteObject"],
379 [MIGRATED_SID]: ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
380 } as const;
381
382 /** S3's limit on the size of a bucket policy. */
383 const MAX_POLICY_BYTES = 20 * 1024;
384
385 interface PolicyStatement {
386 readonly Sid?: string;
387 readonly Resource?: string | ReadonlyArray<string>;
388 readonly [key: string]: unknown;
389 }
390
391 const asArray = <T>(value: T | ReadonlyArray<T> | undefined): ReadonlyArray<T> =>
392 value === undefined ? [] : Array.isArray(value) ? value : [value as T];
393
394 /** The bucket's policy statements; none when it has no policy or no bucket. */
395 const readPolicy = (bucket: string) =>
396 s3.getBucketPolicy({ Bucket: bucket }).pipe(
397 Effect.map((result) => result.Policy),
398 Effect.catchTag(["NoSuchBucketPolicy", "NoSuchBucket"], () => Effect.undefined),
399 Effect.flatMap((text) =>
400 Effect.try({
401 try: () =>
402 (text === undefined ? {} : JSON.parse(text)) as {
403 Version?: string;
404 Statement?: PolicyStatement | ReadonlyArray<PolicyStatement>;
405 },
406 catch: () =>
407 new LegacyStateError({ message: `The bucket policy of '${bucket}' is not valid JSON` }),
408 }),
409 ),
410 Effect.map((policy) => ({
411 version: policy.Version ?? "2012-10-17",
412 statements: asArray(policy.Statement),
413 })),
414 );
415
416 // Policy edits are read-modify-write; one at a time per process.
417 const policyLock = Semaphore.makeUnsafe(1);
418
419 /**
420 * Set what the bucket policy allows on one stage, keeping every statement
421 * alchemy doesn't own.
422 */
423 export const setStageAccess = (
424 location: LegacyLocation,
425 stack: string,
426 stage: string,
427 access: StageAccess,
428 ) =>
429 Semaphore.withPermits(
430 policyLock,
431 1,
432 )(
433 Effect.gen(function* () {
434 const arn = `arn:aws:s3:::${location.bucket}/${stagePrefix(location, stack, stage)}*`;
435 const { version, statements } = yield* readPolicy(location.bucket);
436 const resources = (sid: string) =>
437 new Set(asArray(statements.find((statement) => statement.Sid === sid)?.Resource));
438 const fenced = resources(FENCED_SID);
439 const migrated = resources(MIGRATED_SID);
440 const current: StageAccess = migrated.has(arn)
441 ? "migrated"
442 : fenced.has(arn)
443 ? "fenced"
444 : "open";
445 if (current === access) return;
446 fenced.delete(arn);
447 migrated.delete(arn);
448 if (access === "fenced") fenced.add(arn);
449 if (access === "migrated") migrated.add(arn);
450 const deny = (sid: keyof typeof DENIED_ACTIONS, arns: Set<string>) =>
451 arns.size === 0
452 ? []
453 : [
454 {
455 Sid: sid,
456 Effect: "Deny",
457 Principal: "*",
458 Action: DENIED_ACTIONS[sid],
459 Resource: Array.from(arns).sort(),
460 },
461 ];
462 const next = [
463 ...statements.filter(
464 (statement) => statement.Sid !== FENCED_SID && statement.Sid !== MIGRATED_SID,
465 ),
466 ...deny(FENCED_SID, fenced),
467 ...deny(MIGRATED_SID, migrated),
468 ];
469 if (next.length === 0) {
470 yield* s3.deleteBucketPolicy({ Bucket: location.bucket });
471 return;
472 }
473 const text = JSON.stringify({ Version: version, Statement: next });
474 if (new TextEncoder().encode(text).length > MAX_POLICY_BYTES) {
475 return yield* new LegacyStateError({
476 message: `The bucket policy of '${location.bucket}' has no room to fence '${stack}/${stage}' (S3 allows 20 KB). Migrate fewer stages at a time, or remove statements alchemy doesn't own.`,
477 });
478 }
479 yield* s3.putBucketPolicy({ Bucket: location.bucket, Policy: text });
480 }),
481 );
482
483 /** Remove every statement {@link setStageAccess} wrote, so the bucket can be emptied. */
484 export const openLegacyBucket = (bucket: string) =>
485 Semaphore.withPermits(
486 policyLock,
487 1,
488 )(
489 Effect.gen(function* () {
490 const { version, statements } = yield* readPolicy(bucket);
491 const kept = statements.filter(
492 (statement) => statement.Sid !== FENCED_SID && statement.Sid !== MIGRATED_SID,
493 );
494 if (kept.length === statements.length) return;
495 if (kept.length === 0) {
496 yield* s3.deleteBucketPolicy({ Bucket: bucket });
497 } else {
498 yield* s3.putBucketPolicy({
499 Bucket: bucket,
500 Policy: JSON.stringify({ Version: version, Statement: kept }),
501 });
502 }
503 }),
504 );