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

main
ts 480 lines 17.3 KB
Raw
1 import * as logging from "@distilled.cloud/gcp/logging_v2";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Data from "effect/Data";
7 import * as Effect from "effect/Effect";
8 import * as Schedule from "effect/Schedule";
9 import * as Stream from "effect/Stream";
10 import { GcpEnvironment } from "../Environment.ts";
11 import type { Providers } from "../Providers.ts";
12 import {
13 DEFAULT_LOCATION,
14 DEFAULT_RETENTION_DAYS,
15 canonIndexConfigs,
16 canonRestricted,
17 createOwnership,
18 encodeDescription,
19 hasOwnershipMarker,
20 isDeletedBucket,
21 isPendingBucket,
22 jsonEqual,
23 lastSegment,
24 locationParent,
25 ownedBy,
26 parseDescription,
27 parseLoggingName,
28 scopeParent,
29 toPhysicalId,
30 type LogBucketIndexConfig,
31 } from "./internal.ts";
32
33 export type FolderBucketIndexConfig = LogBucketIndexConfig;
34
35 export type FolderBucketCmekSettings = {
36 /**
37 * Cloud KMS key used to encrypt new log entries
38 * (`projects/{project}/locations/{location}/keyRings/{ring}/cryptoKeys/{key}`).
39 * Once set, CMEK cannot be disabled; the key may be rotated.
40 */
41 kmsKeyName: string;
42 };
43
44 export type FolderBucketProps = {
45 /**
46 * Folder id (`folders/{folder}` or the numeric id). When omitted, the
47 * stack project is used so the same distilled folder-location APIs can
48 * manage project buckets. Immutable — changing it replaces the bucket.
49 */
50 folderId?: string;
51 /**
52 * Bucket id (the `{bucket}` segment of
53 * `{parent}/locations/{location}/buckets/{bucket}`). If omitted, a unique
54 * name is generated from the stack, stage, and logical id. Limited to
55 * 100 characters: letters, digits, underscores, hyphens, periods; first
56 * character must be alphanumeric. Immutable — changing it replaces the
57 * bucket.
58 */
59 bucketId?: string;
60 /**
61 * Location that stores log entries. `global` leaves placement unspecified.
62 * Immutable after create — changing it replaces the bucket.
63 * @default "global"
64 */
65 location?: string;
66 /**
67 * Human-readable description. Log buckets have no labels field, so
68 * Alchemy ownership is stored in a `[alchemy …]` prefix and stripped
69 * from attributes.
70 */
71 description?: string;
72 /**
73 * Days to retain log entries before they are deleted. Minimum 1. `0` at
74 * create uses the GCP default of 30. Cannot be changed while the bucket
75 * is locked.
76 * @default 30
77 */
78 retentionDays?: number;
79 /**
80 * When true, retention cannot be reduced and the bucket can only be
81 * deleted if empty. Locking cannot be undone.
82 * @default false
83 */
84 locked?: boolean;
85 /**
86 * Enable Log Analytics. Once enabled, it cannot be disabled.
87 * @default false
88 */
89 analyticsEnabled?: boolean;
90 /**
91 * Log entry field paths denied in this bucket (e.g. `textPayload`,
92 * `jsonPayload`).
93 */
94 restrictedFields?: string[];
95 /**
96 * Custom indexed fields. Automatically indexed paths cannot be changed.
97 */
98 indexConfigs?: FolderBucketIndexConfig[];
99 /**
100 * Customer-managed encryption for new log entries. Once configured,
101 * CMEK cannot be disabled.
102 */
103 cmekSettings?: FolderBucketCmekSettings;
104 };
105
106 export type FolderBucket = Resource<
107 "GCP.Logging.FolderBucket",
108 FolderBucketProps,
109 {
110 /** Full resource name `{parent}/locations/{location}/buckets/{bucketId}`. */
111 name: string;
112 /** Bucket id (last path segment). */
113 bucketId: string;
114 /** Parent resource (`folders/{folder}` or `projects/{project}`). */
115 parent: string;
116 /** Folder id when the parent is a folder. */
117 folderId: string | undefined;
118 /** Location that stores log entries. */
119 location: string;
120 /** User description with the Alchemy ownership prefix stripped. */
121 description: string | undefined;
122 /** Retention period in days. */
123 retentionDays: number;
124 /** Whether the bucket is locked. */
125 locked: boolean;
126 /** Whether Log Analytics is enabled. */
127 analyticsEnabled: boolean;
128 /** Restricted field paths. */
129 restrictedFields: string[];
130 /** Custom index configs. */
131 indexConfigs: FolderBucketIndexConfig[];
132 /** CMEK key name, if configured. */
133 cmekSettings: FolderBucketCmekSettings | undefined;
134 /** Bucket lifecycle (`ACTIVE`, `DELETE_REQUESTED`, …). */
135 lifecycleState: string | undefined;
136 /** RFC3339 creation timestamp. Unset on GCP default buckets. */
137 createTime: string | undefined;
138 /** RFC3339 last-update timestamp. */
139 updateTime: string | undefined;
140 },
141 never,
142 Providers
143 >;
144
145 /**
146 * A Cloud Logging log bucket owned by a folder (or the stack project).
147 *
148 * Uses the folder-location Logging APIs (`createFoldersLocationsBuckets`
149 * and siblings). Log buckets have no labels field, so Alchemy stamps
150 * ownership into the description for `list` / nuke. `folderId`, `bucketId`,
151 * and `location` are identity — changing any of them replaces the bucket.
152 * Delete marks the bucket `DELETE_REQUESTED`; GCP purges it after 7 days.
153 *
154 * ### Creating a Folder Bucket
155 * **Example:** Generated name in `global` on the stack project
156 * ```typescript
157 * const bucket = yield* GCP.Logging.FolderBucket("AppLogs", {
158 * description: "application logs",
159 * });
160 * ```
161 *
162 * **Example:** Named bucket on a folder
163 * ```typescript
164 * const bucket = yield* GCP.Logging.FolderBucket("AppLogs", {
165 * folderId: "123456789",
166 * bucketId: "app-logs",
167 * location: "global",
168 * description: "application logs",
169 * retentionDays: 31,
170 * });
171 * ```
172 *
173 * ### Updating a Folder Bucket
174 * **Example:** Change description and retention
175 * ```typescript
176 * const bucket = yield* GCP.Logging.FolderBucket("AppLogs", {
177 * location: "global",
178 * description: "retained application logs",
179 * retentionDays: 60,
180 * });
181 * ```
182 *
183 * @resource
184 * @category Logging
185 */
186 export const FolderBucket = Resource<FolderBucket>("GCP.Logging.FolderBucket");
187
188 export class FolderBucketNotResolved extends Data.TaggedError(
189 "GCP.Logging.FolderBucketNotResolved",
190 )<{
191 resourceName: string;
192 }> {}
193
194 export class FolderBucketFailed extends Data.TaggedError("GCP.Logging.FolderBucketFailed")<{
195 resourceName: string;
196 state: string | undefined;
197 }> {}
198
199 const resourceName = (parent: string, location: string, bucketId: string) =>
200 `${locationParent(parent, location)}/buckets/${bucketId}`;
201
202 const folderIdOf = (parent: string) =>
203 parent.startsWith("folders/") ? lastSegment(parent) : undefined;
204
205 const toAttrs = (bucket: logging.LogBucket, parent: string, location: string) => {
206 const parsed = parseLoggingName(bucket.name ?? "");
207 const bucketId = parsed.bucketId ?? lastSegment(bucket.name ?? "");
208 const resolvedParent = parsed.parent || parent;
209 const resolvedLocation = parsed.location ?? location;
210 const description = parseDescription(bucket.description);
211 const cmekKey = bucket.cmekSettings?.kmsKeyName;
212 return {
213 name: bucket.name ?? (bucketId ? resourceName(resolvedParent, resolvedLocation, bucketId) : ""),
214 bucketId,
215 parent: resolvedParent,
216 folderId: folderIdOf(resolvedParent),
217 location: resolvedLocation,
218 description: description.description,
219 retentionDays: bucket.retentionDays ?? DEFAULT_RETENTION_DAYS,
220 locked: bucket.locked === true,
221 analyticsEnabled: bucket.analyticsEnabled === true,
222 restrictedFields: [...(bucket.restrictedFields ?? [])],
223 indexConfigs: canonIndexConfigs(bucket.indexConfigs),
224 cmekSettings: cmekKey ? { kmsKeyName: cmekKey } : undefined,
225 lifecycleState: bucket.lifecycleState,
226 createTime: bucket.createTime,
227 updateTime: bucket.updateTime,
228 };
229 };
230
231 const getByName = (name: string) =>
232 logging
233 .getFoldersLocationsBuckets({ name })
234 .pipe(Effect.catchTag("NotFound", () => Effect.undefined));
235
236 const undelete = (name: string) =>
237 logging
238 .undeleteFoldersLocationsBuckets({ name, body: {} })
239 .pipe(Effect.catchTag(["NotFound", "Conflict"], () => Effect.void));
240
241 const waitUntilActive = (name: string) =>
242 Effect.gen(function* () {
243 const bucket = yield* getByName(name);
244 if (bucket === undefined || isDeletedBucket(bucket)) {
245 return yield* new FolderBucketNotResolved({ resourceName: name });
246 }
247 if (bucket.lifecycleState === "FAILED") {
248 return yield* new FolderBucketFailed({
249 resourceName: name,
250 state: bucket.lifecycleState,
251 });
252 }
253 if (isPendingBucket(bucket.lifecycleState)) {
254 return yield* new FolderBucketNotResolved({ resourceName: name });
255 }
256 return bucket;
257 }).pipe(
258 Effect.retry({
259 while: (error) => error._tag === "GCP.Logging.FolderBucketNotResolved",
260 times: 8,
261 schedule: Schedule.spaced("1 second"),
262 }),
263 );
264
265 const waitUntilDeleted = (name: string) =>
266 getByName(name).pipe(
267 Effect.flatMap((bucket) =>
268 isDeletedBucket(bucket)
269 ? Effect.void
270 : Effect.fail(new FolderBucketNotResolved({ resourceName: name })),
271 ),
272 Effect.retry({
273 while: (error) => error._tag === "GCP.Logging.FolderBucketNotResolved",
274 times: 8,
275 schedule: Schedule.spaced("1 second"),
276 }),
277 );
278
279 const toCreateBody = (props: FolderBucketProps, description: string): logging.LogBucket => ({
280 description,
281 retentionDays: props.retentionDays,
282 locked: props.locked === true ? true : undefined,
283 analyticsEnabled: props.analyticsEnabled === true ? true : undefined,
284 restrictedFields:
285 props.restrictedFields && props.restrictedFields.length > 0
286 ? [...props.restrictedFields]
287 : undefined,
288 indexConfigs:
289 props.indexConfigs && props.indexConfigs.length > 0
290 ? props.indexConfigs.map((config) => ({
291 fieldPath: config.fieldPath,
292 type: config.type,
293 }))
294 : undefined,
295 cmekSettings: props.cmekSettings ? { kmsKeyName: props.cmekSettings.kmsKeyName } : undefined,
296 });
297
298 export const FolderBucketProvider = () =>
299 Provider.succeed(FolderBucket, {
300 stables: ["name", "bucketId", "parent", "folderId", "location", "createTime"],
301
302 diff: Effect.fn(function* ({ news, olds, output }) {
303 if (!isResolved(news)) return undefined;
304 const previousId = olds?.bucketId ?? output?.bucketId;
305 const idChanged =
306 previousId !== undefined && news.bucketId !== undefined && news.bucketId !== previousId;
307 const previousLocation = olds?.location ?? output?.location;
308 const locationChanged =
309 previousLocation !== undefined &&
310 news.location !== undefined &&
311 news.location !== previousLocation;
312 const previousFolder = olds?.folderId ?? output?.folderId;
313 const folderChanged = news.folderId !== undefined && news.folderId !== previousFolder;
314 if (!idChanged && !locationChanged && !folderChanged) return undefined;
315 return { action: "replace" as const, deleteFirst: false };
316 }),
317
318 read: Effect.fn(function* ({ id, olds, output }) {
319 const env = yield* GcpEnvironment.current;
320 const parent = scopeParent(env.project, olds?.folderId ?? output?.folderId);
321 const location = olds?.location ?? output?.location ?? DEFAULT_LOCATION;
322 const bucketId = yield* toPhysicalId(id, olds?.bucketId, output?.bucketId, "b");
323 const name = output?.name ?? resourceName(parent, location, bucketId);
324 const existing = yield* getByName(name);
325 if (isDeletedBucket(existing)) return undefined;
326 const attrs = toAttrs(existing, parent, location);
327 const { labels } = parseDescription(existing.description);
328 return (yield* ownedBy(id, labels)) ? attrs : Unowned(attrs);
329 }),
330
331 list: () =>
332 Effect.gen(function* () {
333 const env = yield* GcpEnvironment.current;
334 return yield* logging.listFoldersLocationsBuckets
335 .pages({
336 parent: `projects/${env.project}/locations/-`,
337 pageSize: 1000,
338 })
339 .pipe(
340 Stream.flatMap((page) => Stream.fromIterable(page.buckets ?? [])),
341 Stream.filter(
342 (bucket) => !isDeletedBucket(bucket) && hasOwnershipMarker(bucket.description),
343 ),
344 Stream.map((bucket) =>
345 toAttrs(
346 bucket,
347 parseLoggingName(bucket.name ?? "").parent || `projects/${env.project}`,
348 parseLoggingName(bucket.name ?? "").location ?? DEFAULT_LOCATION,
349 ),
350 ),
351 Stream.runCollect,
352 Effect.map((chunk) => Array.from(chunk)),
353 );
354 }),
355
356 reconcile: Effect.fn(function* ({ id, news, output }) {
357 const env = yield* GcpEnvironment.current;
358 const parent = scopeParent(env.project, news.folderId ?? output?.folderId);
359 const location = news.location ?? output?.location ?? DEFAULT_LOCATION;
360 const bucketId = yield* toPhysicalId(id, news.bucketId, output?.bucketId, "b");
361 const name = resourceName(parent, location, bucketId);
362 const ownership = yield* createOwnership(id);
363 const desiredDescription = encodeDescription(ownership, news.description);
364
365 let current = yield* getByName(output?.name ?? name);
366
367 if (current !== undefined && current.lifecycleState === "DELETE_REQUESTED") {
368 yield* undelete(current.name ?? name);
369 current = yield* waitUntilActive(current.name ?? name);
370 }
371
372 if (current === undefined) {
373 const created = yield* logging
374 .createFoldersLocationsBuckets({
375 parent: locationParent(parent, location),
376 bucketId,
377 body: toCreateBody(news, desiredDescription),
378 })
379 .pipe(Effect.catchTag("Conflict", () => getByName(name)));
380 current = created ?? undefined;
381 if (current !== undefined && current.lifecycleState === "DELETE_REQUESTED") {
382 yield* undelete(current.name ?? name);
383 current = yield* waitUntilActive(current.name ?? name);
384 } else if (current !== undefined && isPendingBucket(current.lifecycleState)) {
385 current = yield* waitUntilActive(current.name ?? name);
386 }
387 }
388
389 if (isDeletedBucket(current)) {
390 return yield* new FolderBucketNotResolved({ resourceName: name });
391 }
392
393 const desiredLocked = news.locked === true;
394 const desiredAnalytics = news.analyticsEnabled === true;
395 const descriptionChanged = (current.description ?? "") !== desiredDescription;
396 const retentionChanged =
397 news.retentionDays !== undefined &&
398 current.locked !== true &&
399 (current.retentionDays ?? DEFAULT_RETENTION_DAYS) !== news.retentionDays;
400 const restrictedChanged =
401 news.restrictedFields !== undefined &&
402 !jsonEqual(
403 canonRestricted(current.restrictedFields),
404 canonRestricted(news.restrictedFields),
405 );
406 const indexChanged =
407 news.indexConfigs !== undefined &&
408 !jsonEqual(canonIndexConfigs(current.indexConfigs), canonIndexConfigs(news.indexConfigs));
409 const analyticsChanged =
410 news.analyticsEnabled !== undefined &&
411 desiredAnalytics &&
412 current.analyticsEnabled !== true;
413 const cmekChanged =
414 news.cmekSettings !== undefined &&
415 (current.cmekSettings?.kmsKeyName ?? "") !== news.cmekSettings.kmsKeyName;
416 const lockedChanged = news.locked !== undefined && desiredLocked && current.locked !== true;
417
418 const syncMask = [
419 descriptionChanged ? "description" : undefined,
420 retentionChanged ? "retentionDays" : undefined,
421 restrictedChanged ? "restrictedFields" : undefined,
422 indexChanged ? "indexConfigs" : undefined,
423 analyticsChanged ? "analyticsEnabled" : undefined,
424 cmekChanged ? "cmekSettings" : undefined,
425 ].filter((field): field is string => field !== undefined);
426
427 if (syncMask.length > 0) {
428 const body: logging.LogBucket = {};
429 if (descriptionChanged) body.description = desiredDescription;
430 if (retentionChanged) body.retentionDays = news.retentionDays;
431 if (restrictedChanged) {
432 body.restrictedFields = [...(news.restrictedFields ?? [])];
433 }
434 if (indexChanged) {
435 body.indexConfigs = (news.indexConfigs ?? []).map((config) => ({
436 fieldPath: config.fieldPath,
437 type: config.type,
438 }));
439 }
440 if (analyticsChanged) body.analyticsEnabled = true;
441 if (cmekChanged) {
442 body.cmekSettings = { kmsKeyName: news.cmekSettings?.kmsKeyName };
443 }
444 current = yield* logging.patchFoldersLocationsBuckets({
445 name: current.name ?? name,
446 updateMask: syncMask.join(","),
447 body,
448 });
449 if (isPendingBucket(current.lifecycleState)) {
450 current = yield* waitUntilActive(current.name ?? name);
451 }
452 }
453
454 if (lockedChanged) {
455 current = yield* logging.patchFoldersLocationsBuckets({
456 name: current.name ?? name,
457 updateMask: "locked",
458 body: { locked: true },
459 });
460 if (isPendingBucket(current.lifecycleState)) {
461 current = yield* waitUntilActive(current.name ?? name);
462 }
463 }
464
465 return toAttrs(current, parent, location);
466 }),
467
468 delete: Effect.fn(function* ({ output }) {
469 if (output.lifecycleState === "DELETE_REQUESTED") return;
470 yield* logging.deleteFoldersLocationsBuckets({ name: output.name }).pipe(
471 Effect.catchTag("NotFound", () => Effect.void),
472 Effect.retry({
473 while: (error) => error._tag === "BadRequest" || error._tag === "Conflict",
474 times: 10,
475 schedule: Schedule.spaced("3 seconds"),
476 }),
477 );
478 yield* waitUntilDeleted(output.name);
479 }),
480 });