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

main
ts 311 lines 10.4 KB
Raw
1 import * as pubsub from "@distilled.cloud/gcp/pubsub_v1";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import { tagRecord } from "alchemy/Tags";
8 import * as Data from "effect/Data";
9 import * as Effect from "effect/Effect";
10 import * as Schedule from "effect/Schedule";
11 import * as Stream from "effect/Stream";
12 import { GcpEnvironment } from "../Environment.ts";
13 import {
14 createInternalLabels,
15 diffLabels,
16 hasAlchemyLabels,
17 stripInternalLabels,
18 toLabels,
19 } from "../Labels.ts";
20 import type { Providers } from "../Providers.ts";
21
22 export type SnapshotProps = {
23 /**
24 * Snapshot id (the `{snapshot}` segment of
25 * `projects/{project}/snapshots/{snapshot}`). If omitted, a unique name
26 * is generated from the stack, stage, and logical id. Changing it
27 * replaces the snapshot.
28 */
29 snapshotId?: string;
30 /**
31 * Subscription whose backlog this snapshot retains. Accepts a full
32 * resource name (`projects/{project}/subscriptions/{subscription}`) or
33 * a subscription id. Immutable — changing it replaces the snapshot.
34 */
35 subscription: string;
36 /**
37 * User labels. Alchemy ownership labels are merged in automatically.
38 */
39 labels?: Record<string, string>;
40 };
41
42 export type Snapshot = Resource<
43 "GCP.PubSub.Snapshot",
44 SnapshotProps,
45 {
46 /** Full resource name `projects/{project}/snapshots/{snapshot}`. */
47 name: string;
48 /** Snapshot id (last path segment). */
49 snapshotId: string;
50 /** Project id. */
51 project: string;
52 /** Topic this snapshot is retaining messages from. */
53 topic: string | undefined;
54 /** RFC3339 time after which the snapshot is no longer guaranteed. */
55 expireTime: string | undefined;
56 /** User labels (Alchemy ownership labels stripped). */
57 labels: Record<string, string>;
58 },
59 never,
60 Providers
61 >;
62
63 /**
64 * A Google Cloud Pub/Sub snapshot of a subscription's message backlog.
65 *
66 * Snapshots capture unacked messages at creation time (and subsequent
67 * publishes to the topic) so a subscription can later `Seek` back to that
68 * point. The source `subscription` is immutable — changing it replaces the
69 * snapshot. Labels can be updated in place.
70 *
71 * ### Creating a Snapshot
72 * **Example:** Snapshot of a pull subscription
73 * ```typescript
74 * const topic = yield* GCP.PubSub.Topic("events", {});
75 * const subscription = yield* GCP.PubSub.Subscription("orders", {
76 * topic: topic.name,
77 * });
78 * const snapshot = yield* GCP.PubSub.Snapshot("checkpoint", {
79 * subscription: subscription.name,
80 * });
81 * ```
82 *
83 * **Example:** Explicit id and labels
84 * ```typescript
85 * const topic = yield* GCP.PubSub.Topic("events", {});
86 * const subscription = yield* GCP.PubSub.Subscription("orders", {
87 * topic: topic.name,
88 * });
89 * const snapshot = yield* GCP.PubSub.Snapshot("checkpoint", {
90 * snapshotId: "order-checkpoint",
91 * subscription: subscription.name,
92 * labels: { env: "prod" },
93 * });
94 * ```
95 *
96 * @resource
97 * @category PubSub
98 */
99 export const Snapshot = Resource<Snapshot>("GCP.PubSub.Snapshot");
100
101 export class SnapshotNotResolved extends Data.TaggedError("GCP.PubSub.SnapshotNotResolved")<{
102 resourceName: string;
103 }> {}
104
105 export class SnapshotStillExists extends Data.TaggedError("GCP.PubSub.SnapshotStillExists")<{
106 resourceName: string;
107 }> {}
108
109 const snapshotIdOf = (name: string) => name.split("/").pop() ?? name;
110
111 const resourceName = (project: string, snapshotId: string) =>
112 `projects/${project}/snapshots/${snapshotId}`;
113
114 const subscriptionNameOf = (project: string, subscription: string) =>
115 subscription.startsWith("projects/")
116 ? subscription
117 : `projects/${project}/subscriptions/${subscription}`;
118
119 const resourceKey = (value: string | undefined) =>
120 value === undefined ? undefined : snapshotIdOf(value);
121
122 const userLabels = (
123 labels: Record<string, string | undefined> | null | undefined,
124 ): Record<string, string> => stripInternalLabels(tagRecord(labels));
125
126 const toId = (id: string, snapshotId: string | undefined, existing?: string) =>
127 Effect.gen(function* () {
128 if (snapshotId !== undefined) return snapshotId;
129 if (existing !== undefined) return existing;
130 const generated = yield* createPhysicalName({
131 id,
132 maxLength: 255,
133 lowercase: true,
134 forbiddenPrefixes: ["goog"],
135 });
136 return /^[a-z]/.test(generated) ? generated : `s${generated}`.slice(0, 255);
137 });
138
139 const toAttrs = (snapshot: pubsub.Snapshot, project: string) => {
140 const name = snapshot.name ?? "";
141 return {
142 name,
143 snapshotId: snapshotIdOf(name),
144 project,
145 topic: snapshot.topic,
146 expireTime: snapshot.expireTime,
147 labels: userLabels(snapshot.labels),
148 };
149 };
150
151 const getByName = (name: string) =>
152 pubsub
153 .getProjectsSnapshots({ snapshot: name })
154 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
155
156 const waitUntilGone = (name: string) =>
157 getByName(name).pipe(
158 Effect.filterOrFail(
159 (existing): existing is undefined => existing === undefined,
160 () => new SnapshotStillExists({ resourceName: name }),
161 ),
162 Effect.asVoid,
163 Effect.retry({
164 while: (error) => error._tag === "GCP.PubSub.SnapshotStillExists",
165 // Pub/Sub reads lag deletes; allow up to a minute.
166 schedule: Schedule.spaced("2 seconds"),
167 times: 30,
168 }),
169 );
170
171 const CONSISTENT_READS = 3;
172
173 const waitUntilPresent = (name: string) =>
174 Effect.gen(function* () {
175 let found: pubsub.Snapshot | undefined;
176 for (let read = 0; read < CONSISTENT_READS; read++) {
177 if (read > 0) yield* Effect.sleep("1 second");
178 found = yield* getByName(name);
179 if (found === undefined) return yield* new SnapshotNotResolved({ resourceName: name });
180 }
181 return found!;
182 }).pipe(
183 Effect.retry({
184 while: (error) => error._tag === "GCP.PubSub.SnapshotNotResolved",
185 schedule: Schedule.spaced("1 second"),
186 times: 60,
187 }),
188 );
189
190 export const SnapshotProvider = () =>
191 Provider.succeed(Snapshot, {
192 stables: ["name", "snapshotId", "project", "topic"],
193
194 diff: Effect.fn(function* ({ news, olds, output }) {
195 if (!isResolved(news)) return undefined;
196 const previousId = olds?.snapshotId ?? output?.snapshotId;
197 const nameChanged =
198 news.snapshotId !== undefined && previousId !== undefined && news.snapshotId !== previousId;
199 const previousSubscription = olds?.subscription;
200 const subscriptionChanged =
201 previousSubscription !== undefined &&
202 resourceKey(news.subscription) !== resourceKey(previousSubscription);
203 if (!nameChanged && !subscriptionChanged) {
204 return undefined;
205 }
206 return {
207 action: "replace" as const,
208 deleteFirst:
209 !nameChanged &&
210 previousId !== undefined &&
211 (news.snapshotId ?? previousId) === previousId,
212 };
213 }),
214
215 read: Effect.fn(function* ({ id, olds, output }) {
216 const env = yield* GcpEnvironment.current;
217 const snapshotId = yield* toId(id, olds?.snapshotId, output?.snapshotId);
218 const name = output?.name ?? resourceName(env.project, snapshotId);
219 const existing = yield* getByName(name);
220 if (existing === undefined) return undefined;
221 const attrs = toAttrs(existing, env.project);
222 return (yield* hasAlchemyLabels(id, tagRecord(existing.labels))) ? attrs : Unowned(attrs);
223 }),
224
225 list: () =>
226 Effect.gen(function* () {
227 const env = yield* GcpEnvironment.current;
228 return yield* pubsub.listProjectsSnapshots
229 .pages({
230 project: `projects/${env.project}`,
231 pageSize: 1000,
232 })
233 .pipe(
234 Stream.flatMap((page) => Stream.fromIterable(page.snapshots ?? [])),
235 Stream.filter((snapshot) =>
236 Object.keys(snapshot.labels ?? {}).some((key) => key.startsWith("alchemy-")),
237 ),
238 Stream.map((snapshot) => toAttrs(snapshot, env.project)),
239 Stream.runCollect,
240 Effect.map((chunk) => Array.from(chunk)),
241 );
242 }),
243
244 reconcile: Effect.fn(function* ({ id, news, olds, output }) {
245 const env = yield* GcpEnvironment.current;
246 const snapshotId = yield* toId(id, news.snapshotId, output?.snapshotId);
247 const name = resourceName(env.project, snapshotId);
248 const subscriptionName = subscriptionNameOf(env.project, news.subscription);
249 const desiredLabels = {
250 ...toLabels(news.labels),
251 ...(yield* createInternalLabels(id)),
252 };
253 // Snapshot GET does not return the source subscription. Recreate when
254 // persisted props show it changed — the field is immutable.
255 const subscriptionChanged =
256 olds?.subscription !== undefined &&
257 resourceKey(news.subscription) !== resourceKey(olds.subscription);
258
259 let current = yield* getByName(name);
260 if (current !== undefined && subscriptionChanged) {
261 yield* pubsub
262 .deleteProjectsSnapshots({ snapshot: name })
263 .pipe(Effect.catchTag("NotFound", () => Effect.void));
264 yield* waitUntilGone(name);
265 current = undefined;
266 }
267
268 if (current === undefined) {
269 yield* pubsub
270 .createProjectsSnapshots({
271 name,
272 body: {
273 subscription: subscriptionName,
274 labels: desiredLabels,
275 },
276 })
277 .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
278 // Block until Pub/Sub consistently serves the snapshot; the next
279 // call (label patch) can otherwise hit a lagging replica.
280 current = yield* waitUntilPresent(name);
281 }
282
283 if (current === undefined) {
284 return yield* new SnapshotNotResolved({ resourceName: name });
285 }
286
287 const observedLabels = tagRecord(current.labels);
288 const { upsert, removed } = diffLabels(observedLabels, desiredLabels);
289 if (upsert.length > 0 || removed.length > 0) {
290 current = yield* pubsub.patchProjectsSnapshots({
291 name,
292 body: {
293 snapshot: {
294 name,
295 labels: desiredLabels,
296 },
297 updateMask: "labels",
298 },
299 });
300 }
301
302 return toAttrs(current, env.project);
303 }),
304
305 delete: Effect.fn(function* ({ output }) {
306 yield* pubsub
307 .deleteProjectsSnapshots({ snapshot: output.name })
308 .pipe(Effect.catchTag("NotFound", () => Effect.void));
309 yield* waitUntilGone(output.name);
310 }),
311 });