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

main
ts 308 lines 10.6 KB
Raw
1 import * as kvs from "@distilled.cloud/aws/cloudfront-keyvaluestore";
2 import type { Input } from "alchemy/Input";
3 import * as Provider from "alchemy/Provider";
4 import { Resource } from "alchemy/Resource";
5 import * as Effect from "effect/Effect";
6 import type { Providers } from "../Providers.ts";
7 import {
8 extractValue,
9 getKvsEtag,
10 isKvsPreconditionFailed,
11 cappedKvsRetrySchedule,
12 retryForKvsReadiness,
13 withKvsRegionFn,
14 } from "./common.ts";
15
16 export interface KvEntriesProps {
17 /** ARN of the CloudFront KeyValueStore. */
18 store: string;
19 /** Namespace prefix for all keys. Keys are stored as `{namespace}:{key}`. */
20 namespace: string;
21 /** Map of key → value entries to manage. */
22 entries: Record<string, Input<string>>;
23 /**
24 * Whether to delete keys under this namespace that are not in `entries`.
25 * With `purge`, deleting this resource clears the whole namespace; without
26 * it, only the keys in `entries` are removed.
27 * @default false
28 */
29 purge?: boolean;
30 }
31
32 export interface KvEntries extends Resource<
33 "AWS.CloudFront.KvEntries",
34 KvEntriesProps,
35 {
36 /** ARN of the CloudFront KeyValueStore. */
37 store: string;
38 /** Namespace prefix used for keys. */
39 namespace: string;
40 /** Current entries managed under the namespace. */
41 entries: Record<string, string>;
42 },
43 never,
44 Providers
45 > {}
46
47 /**
48 * Manages namespaced key-value entries in a CloudFront KeyValueStore.
49 *
50 * Entries are stored with a `{namespace}:{key}` prefix to allow multiple
51 * logical groups within a single store. Updates use batched optimistic
52 * concurrency with automatic ETag retry.
53 * ### Managing Entries
54 * **Example:** Basic Entries
55 * ```typescript
56 * const entries = yield* KvEntries("Routes", {
57 * store: store.keyValueStoreArn,
58 * namespace: "routes",
59 * entries: {
60 * "/": "/index.html",
61 * "/about": "/about.html",
62 * },
63 * });
64 * ```
65 *
66 * **Example:** Purge Stale Keys
67 * ```typescript
68 * const entries = yield* KvEntries("Routes", {
69 * store: store.keyValueStoreArn,
70 * namespace: "routes",
71 * entries: { "/": "/index.html" },
72 * purge: true,
73 * });
74 * ```
75 *
76 * @resource
77 */
78 export const KvEntries = Resource<KvEntries>("AWS.CloudFront.KvEntries");
79
80 const BATCH_SIZE = 50;
81 type ResolvedEntries = {
82 [key: string]: Input.Resolve<KvEntriesProps["entries"][string]>;
83 };
84
85 const resolveEntries = (entries: KvEntriesProps["entries"]): ResolvedEntries =>
86 Object.fromEntries(
87 Object.entries(entries).map(([key, value]) => [key, value]),
88 ) as ResolvedEntries;
89
90 export const KvEntriesProvider = () =>
91 Provider.effect(
92 KvEntries,
93 // @ts-expect-error
94 Effect.gen(function* () {
95 const collectAllKeys = Effect.fn(function* (store: string) {
96 const keys: { Key: string; Value: string }[] = [];
97 let nextToken: string | undefined;
98 do {
99 const resp = yield* kvs.listKeys({
100 KvsARN: store,
101 NextToken: nextToken,
102 });
103 for (const item of resp.Items ?? []) {
104 keys.push({
105 Key: item.Key,
106 Value: extractValue(item.Value),
107 });
108 }
109 nextToken = resp.NextToken;
110 } while (nextToken);
111 return keys;
112 });
113
114 const sendBatch = Effect.fn(function* (
115 store: string,
116 etag: string,
117 puts: kvs.PutKeyRequestListItem[],
118 deletes: kvs.DeleteKeyRequestListItem[],
119 ) {
120 return yield* kvs.updateKeys({
121 KvsARN: store,
122 IfMatch: etag,
123 Puts: puts.length > 0 ? puts : undefined,
124 Deletes: deletes.length > 0 ? deletes : undefined,
125 });
126 });
127
128 const batchUpdateKeys = Effect.fn(function* (
129 store: string,
130 etag: string | undefined,
131 puts: kvs.PutKeyRequestListItem[],
132 deletes: kvs.DeleteKeyRequestListItem[],
133 ) {
134 let remainingPuts = puts;
135 let remainingDeletes = deletes;
136 let currentEtag: string | undefined = etag;
137
138 while (remainingPuts.length > 0 || remainingDeletes.length > 0) {
139 const batchPuts = remainingPuts.slice(0, BATCH_SIZE);
140 const batchDeletes = remainingDeletes.slice(0, BATCH_SIZE - batchPuts.length);
141
142 // A precondition failure means a concurrent writer (another
143 // KvEntries / KvRoutesUpdate on the same store) advanced the
144 // etag between our read and this batch — the retry MUST re-read
145 // the etag or it can never succeed. `stale` drops the cached
146 // etag on the failed attempt so the retried generator fetches a
147 // fresh one.
148 let stale = currentEtag;
149 const resp = yield* Effect.gen(function* () {
150 const attemptEtag = stale ?? (yield* getKvsEtag(store));
151 stale = undefined;
152 return yield* sendBatch(store, attemptEtag, batchPuts, batchDeletes);
153 }).pipe(
154 Effect.retry({
155 while: (error) =>
156 error._tag === "ValidationException" && isKvsPreconditionFailed(error),
157 schedule: cappedKvsRetrySchedule,
158 }),
159 );
160
161 currentEtag = resp.ETag;
162 remainingPuts = remainingPuts.slice(batchPuts.length);
163 remainingDeletes = remainingDeletes.slice(batchDeletes.length);
164 }
165 });
166
167 const upload = Effect.fn(function* (
168 store: string,
169 namespace: string,
170 entries: ResolvedEntries,
171 oldEntries: ResolvedEntries | undefined,
172 ) {
173 const puts: kvs.PutKeyRequestListItem[] = [];
174 for (const [key, value] of Object.entries(entries)) {
175 if (oldEntries === undefined || oldEntries[key] !== value) {
176 puts.push({ Key: `${namespace}:${key}`, Value: value as any });
177 }
178 }
179 if (puts.length > 0) {
180 yield* batchUpdateKeys(store, undefined, puts, []);
181 }
182 });
183
184 const purge = Effect.fn(function* (
185 store: string,
186 namespace: string,
187 keepEntries: ResolvedEntries | undefined,
188 ) {
189 const allKeys = yield* collectAllKeys(store);
190 const prefix = `${namespace}:`;
191 const deletes: kvs.DeleteKeyRequestListItem[] = [];
192 for (const item of allKeys) {
193 if (!item.Key.startsWith(prefix)) continue;
194 const unprefixed = item.Key.slice(prefix.length);
195 if (keepEntries && unprefixed in keepEntries) continue;
196 deletes.push({ Key: item.Key });
197 }
198 if (deletes.length > 0) {
199 yield* batchUpdateKeys(store, undefined, [], deletes);
200 }
201 });
202
203 const remove = Effect.fn(function* (
204 store: string,
205 namespace: string,
206 entries: ResolvedEntries,
207 ) {
208 const allKeys = yield* collectAllKeys(store);
209 const prefix = `${namespace}:`;
210 const deletes: kvs.DeleteKeyRequestListItem[] = [];
211 for (const item of allKeys) {
212 if (!item.Key.startsWith(prefix)) continue;
213 if (!(item.Key.slice(prefix.length) in entries)) continue;
214 deletes.push({ Key: item.Key });
215 }
216 if (deletes.length > 0) {
217 yield* batchUpdateKeys(store, undefined, [], deletes);
218 }
219 });
220
221 /**
222 * The live values of a namespace's keys: every key under it with
223 * `purge` (the namespace is owned), otherwise only `managed` keys.
224 */
225 const observeEntries = Effect.fn(function* (
226 store: string,
227 namespace: string,
228 managed: Record<string, unknown>,
229 owned: boolean,
230 ) {
231 const prefix = `${namespace}:`;
232 const entries: Record<string, string> = {};
233 for (const item of yield* collectAllKeys(store)) {
234 if (!item.Key.startsWith(prefix)) continue;
235 const key = item.Key.slice(prefix.length);
236 if (owned || key in managed) entries[key] = item.Value;
237 }
238 return entries;
239 });
240
241 return {
242 // Non-listable: a KvEntries resource is a logical group of key/value
243 // data keyed entirely by its parent store ARN + namespace (both chosen
244 // by the user). There is no account-wide API to enumerate these groups,
245 // and the entries are managed content rather than nuke-able infra.
246 list: () => Effect.succeed([]),
247 read: withKvsRegionFn(
248 Effect.fn(function* ({ olds, output }) {
249 if (output === undefined) return undefined;
250 // The entries are the managed state: report their live values
251 // so drift sees edits, deletions and (with purge) extra keys.
252 const entries = yield* retryForKvsReadiness(
253 observeEntries(output.store, output.namespace, output.entries, olds?.purge ?? false),
254 ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
255 if (entries === undefined) return undefined;
256 return { ...output, entries };
257 }),
258 ),
259 reconcile: withKvsRegionFn(
260 Effect.fn(function* ({ news }) {
261 return yield* retryForKvsReadiness(
262 Effect.gen(function* () {
263 const entries = resolveEntries(news.entries);
264
265 // Observe — diff against the live entries so we only `Put`
266 // keys whose values actually differ.
267 const priorEntries = yield* observeEntries(
268 news.store,
269 news.namespace,
270 entries,
271 false,
272 );
273
274 // Sync entries — push the changed keys.
275 yield* upload(news.store, news.namespace, entries, priorEntries);
276
277 // Sync stale keys — when `purge` is set, list every key
278 // under the namespace and delete anything not in the
279 // desired set. This converges adopted/drifted state.
280 if (news.purge) {
281 yield* purge(news.store, news.namespace, entries);
282 }
283
284 return {
285 store: news.store,
286 namespace: news.namespace,
287 entries,
288 };
289 }),
290 );
291 }),
292 ),
293 delete: withKvsRegionFn(
294 Effect.fn(function* ({ olds, output }) {
295 if (!output.store) return;
296 // Without `purge` the namespace may hold keys this resource
297 // doesn't own (e.g. a Router's `routes` table), so only remove
298 // the entries it wrote.
299 yield* retryForKvsReadiness(
300 olds.purge
301 ? purge(output.store, output.namespace, undefined)
302 : remove(output.store, output.namespace, resolveEntries(output.entries)),
303 ).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
304 }),
305 ),
306 };
307 }),
308 );