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

main
ts 478 lines 16.8 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 { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import * as Data from "effect/Data";
8 import * as Effect from "effect/Effect";
9 import * as Stream from "effect/Stream";
10 import { GcpEnvironment } from "../Environment.ts";
11 import { alchemyLabelKeys, createInternalLabels, hasAlchemyLabels } from "../Labels.ts";
12 import type { Providers } from "../Providers.ts";
13
14 const MAX_NAME_LENGTH = 100;
15
16 export type SinkExclusion = {
17 /**
18 * Client-assigned exclusion id. Limited to 100 characters (letters,
19 * digits, underscores, hyphens, periods). First character must be
20 * alphanumeric.
21 */
22 name: string;
23 /**
24 * Advanced logs filter matching entries to exclude from the export.
25 */
26 filter: string;
27 /**
28 * Human-readable description of this exclusion.
29 */
30 description?: string;
31 /**
32 * When true, the exclusion exists but does not exclude any entries.
33 * @default false
34 */
35 disabled?: boolean;
36 };
37
38 export type SinkBigQueryOptions = {
39 /**
40 * Use BigQuery partitioned tables instead of dated tables
41 * (`syslog_20170523`). Only applies when `destination` is a BigQuery
42 * dataset.
43 * @default false
44 */
45 usePartitionedTables?: boolean;
46 };
47
48 export type SinkProps = {
49 /**
50 * Sink id (the `{sink}` segment of `projects/{project}/sinks/{sink}`).
51 * If omitted, a unique name is generated from the stack, stage, and
52 * logical id. Limited to 100 characters: letters, digits, underscores,
53 * hyphens, periods; first character must be alphanumeric. Immutable —
54 * changing it replaces the sink.
55 */
56 sinkId?: string;
57 /**
58 * Export destination. One of:
59 * `storage.googleapis.com/[GCS_BUCKET]`,
60 * `bigquery.googleapis.com/projects/[PROJECT_ID]/datasets/[DATASET]`,
61 * `pubsub.googleapis.com/projects/[PROJECT_ID]/topics/[TOPIC_ID]`,
62 * `logging.googleapis.com/projects/[PROJECT_ID]`,
63 * `logging.googleapis.com/projects/[PROJECT_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]`.
64 */
65 destination: string;
66 /**
67 * Advanced logs filter. Only matching entries in the sink's parent are
68 * exported. Empty or omitted exports every entry.
69 */
70 filter?: string;
71 /**
72 * Human-readable description (max 8000 characters). Logging sinks have
73 * no labels field, so Alchemy ownership is stored in a `[alchemy …]`
74 * prefix and stripped from attributes.
75 */
76 description?: string;
77 /**
78 * When true, the sink exists but does not export any log entries.
79 * @default false
80 */
81 disabled?: boolean;
82 /**
83 * Exclusion filters. An entry matching `filter` and any exclusion is
84 * not exported.
85 */
86 exclusions?: SinkExclusion[];
87 /**
88 * BigQuery-specific export options. Ignored unless `destination` is a
89 * BigQuery dataset.
90 */
91 bigqueryOptions?: SinkBigQueryOptions;
92 /**
93 * When true, Cloud Logging assigns a unique writer service account as
94 * `writerIdentity`. When false (GCP default for project sinks), the
95 * shared `cloud-logs` identity is used and the destination must be in
96 * the same project. Sinks whose destination is a log bucket in the
97 * same project have no writer identity.
98 */
99 uniqueWriterIdentity?: boolean;
100 /**
101 * Caller-provided writer service account
102 * (`serviceAccount:some@email`). Only valid when routing to a log
103 * bucket in a different project.
104 */
105 customWriterIdentity?: string;
106 /**
107 * Organization/folder sinks only. When true, logs from child projects,
108 * folders, and billing accounts are also eligible for export.
109 * @default false
110 */
111 includeChildren?: boolean;
112 /**
113 * Organization/folder sinks only. When true (requires
114 * `includeChildren`), matching logs are intercepted and omitted from
115 * non-`_Required` child sinks.
116 * @default false
117 */
118 interceptChildren?: boolean;
119 };
120
121 export type Sink = Resource<
122 "GCP.Logging.Sink",
123 SinkProps,
124 {
125 /** Full resource name `projects/{project}/sinks/{sink}`. */
126 name: string;
127 /** Sink id (last path segment). */
128 sinkId: string;
129 /** Project id. */
130 project: string;
131 /** Export destination. */
132 destination: string;
133 /** Advanced logs filter, if set. */
134 filter: string | undefined;
135 /** User description with the Alchemy ownership prefix stripped. */
136 description: string | undefined;
137 /** Whether the sink is disabled. */
138 disabled: boolean;
139 /** Exclusion filters. */
140 exclusions: SinkExclusion[];
141 /** BigQuery export options, if set. */
142 bigqueryOptions: SinkBigQueryOptions | undefined;
143 /** Whether child resources are included (org/folder sinks). */
144 includeChildren: boolean;
145 /** Whether matching child logs are intercepted (org/folder sinks). */
146 interceptChildren: boolean;
147 /**
148 * IAM identity Cloud Logging uses to write to `destination`. Empty
149 * for same-project log-bucket destinations.
150 */
151 writerIdentity: string | undefined;
152 /** RFC3339 creation timestamp. */
153 createTime: string | undefined;
154 /** RFC3339 last-update timestamp. */
155 updateTime: string | undefined;
156 },
157 never,
158 Providers
159 >;
160
161 /**
162 * A Cloud Logging sink that routes log entries to a destination.
163 *
164 * Logging sinks have no labels field, so Alchemy stamps ownership into
165 * the description for `list` / nuke. Name is identity — changing `sinkId`
166 * replaces the sink. Filter, destination, description, disabled flag,
167 * exclusions, and BigQuery options update in place.
168 *
169 * ### Creating a Sink
170 * **Example:** Route errors to the `_Default` log bucket
171 * ```typescript
172 * const sink = yield* GCP.Logging.Sink("Errors", {
173 * destination:
174 * "logging.googleapis.com/projects/my-project/locations/global/buckets/_Default",
175 * filter: "severity>=ERROR",
176 * });
177 * ```
178 *
179 * **Example:** Named sink with a description
180 * ```typescript
181 * const sink = yield* GCP.Logging.Sink("Errors", {
182 * sinkId: "app-errors",
183 * destination:
184 * "logging.googleapis.com/projects/my-project/locations/global/buckets/_Default",
185 * filter: "severity>=ERROR",
186 * description: "application errors",
187 * });
188 * ```
189 *
190 * ### Updating a Sink
191 * **Example:** Change the filter and add an exclusion
192 * ```typescript
193 * const sink = yield* GCP.Logging.Sink("Errors", {
194 * destination:
195 * "logging.googleapis.com/projects/my-project/locations/global/buckets/_Default",
196 * filter: "severity>=WARNING",
197 * description: "warnings and errors",
198 * exclusions: [
199 * {
200 * name: "drop-healthchecks",
201 * filter: 'httpRequest.requestUrl="/healthz"',
202 * },
203 * ],
204 * });
205 * ```
206 *
207 * @resource
208 * @category Logging
209 */
210 export const Sink = Resource<Sink>("GCP.Logging.Sink");
211
212 export class SinkNotResolved extends Data.TaggedError("GCP.Logging.SinkNotResolved")<{
213 resourceName: string;
214 }> {}
215
216 const lastSegment = (value: string) => {
217 const trimmed = value.replace(/\/+$/, "");
218 const parts = trimmed.split("/");
219 return parts[parts.length - 1] || trimmed;
220 };
221
222 const resourceName = (project: string, sinkId: string) => `projects/${project}/sinks/${sinkId}`;
223
224 const sinkIdOf = (sink: logging.LogSink) => {
225 const raw = sink.name ?? sink.resourceName ?? "";
226 return raw.includes("/") ? lastSegment(raw) : raw;
227 };
228
229 const toId = (id: string, sinkId: string | undefined, existing?: string) =>
230 Effect.gen(function* () {
231 if (sinkId !== undefined) return sinkId;
232 if (existing !== undefined) return existing;
233 const generated = yield* createPhysicalName({
234 id,
235 maxLength: MAX_NAME_LENGTH,
236 lowercase: true,
237 });
238 return /^[a-z]/.test(generated) ? generated : `s${generated}`.slice(0, MAX_NAME_LENGTH);
239 });
240
241 const encodeDescription = (
242 labels: Record<string, string>,
243 description: string | undefined,
244 ): string => {
245 const marker = `[alchemy ${alchemyLabelKeys.stack}=${labels[alchemyLabelKeys.stack]} ${alchemyLabelKeys.stage}=${labels[alchemyLabelKeys.stage]} ${alchemyLabelKeys.id}=${labels[alchemyLabelKeys.id]}]`;
246 return description ? `${marker}\n${description}` : marker;
247 };
248
249 const parseDescription = (
250 description: string | undefined,
251 ): {
252 labels: Record<string, string>;
253 description: string | undefined;
254 } => {
255 if (!description?.startsWith("[alchemy ")) {
256 return { labels: {}, description };
257 }
258 const end = description.indexOf("]");
259 if (end < 0) return { labels: {}, description };
260 const labels: Record<string, string> = {};
261 for (const part of description.slice("[alchemy ".length, end).split(/\s+/)) {
262 const eq = part.indexOf("=");
263 if (eq > 0) {
264 labels[part.slice(0, eq)] = part.slice(eq + 1);
265 }
266 }
267 const rest = description.slice(end + 1).replace(/^\n/, "");
268 return { labels, description: rest.length > 0 ? rest : undefined };
269 };
270
271 const hasOwnershipMarker = (description: string | undefined) =>
272 Object.keys(parseDescription(description).labels).some((key) => key.startsWith("alchemy-"));
273
274 const exclusionsOf = (
275 list: readonly logging.LogExclusion[] | readonly SinkExclusion[] | undefined,
276 ): SinkExclusion[] =>
277 (list ?? [])
278 .map((exclusion) => ({
279 name: exclusion.name ?? "",
280 filter: exclusion.filter ?? "",
281 description: exclusion.description,
282 disabled: exclusion.disabled === true,
283 }))
284 .sort((left, right) => left.name.localeCompare(right.name));
285
286 const sameExclusions = (
287 left: readonly logging.LogExclusion[] | readonly SinkExclusion[] | undefined,
288 right: readonly logging.LogExclusion[] | readonly SinkExclusion[] | undefined,
289 ) => JSON.stringify(exclusionsOf(left)) === JSON.stringify(exclusionsOf(right));
290
291 const toExclusionsBody = (
292 list: readonly SinkExclusion[] | undefined,
293 ): logging.LogExclusion[] | undefined => {
294 if (list === undefined) return undefined;
295 return list.map((exclusion) => ({
296 name: exclusion.name,
297 filter: exclusion.filter,
298 description: exclusion.description,
299 disabled: exclusion.disabled === true ? true : undefined,
300 }));
301 };
302
303 const toAttrs = (sink: logging.LogSink, project: string) => {
304 const sinkId = sinkIdOf(sink);
305 const parsed = parseDescription(sink.description);
306 const bq = sink.bigqueryOptions;
307 return {
308 name: sink.resourceName ?? (sinkId ? resourceName(project, sinkId) : ""),
309 sinkId,
310 project,
311 destination: sink.destination ?? "",
312 filter: sink.filter,
313 description: parsed.description,
314 disabled: sink.disabled === true,
315 exclusions: exclusionsOf(sink.exclusions),
316 bigqueryOptions:
317 bq?.usePartitionedTables !== undefined
318 ? { usePartitionedTables: bq.usePartitionedTables }
319 : undefined,
320 includeChildren: sink.includeChildren === true,
321 interceptChildren: sink.interceptChildren === true,
322 writerIdentity: sink.writerIdentity,
323 createTime: sink.createTime,
324 updateTime: sink.updateTime,
325 };
326 };
327
328 const getByName = (name: string) =>
329 logging.getSinks({ sinkName: name }).pipe(Effect.catchTag("NotFound", () => Effect.undefined));
330
331 const toCreateBody = (sinkId: string, props: SinkProps, description: string): logging.LogSink => ({
332 name: sinkId,
333 destination: props.destination,
334 filter: props.filter,
335 description,
336 disabled: props.disabled === true ? true : undefined,
337 exclusions: toExclusionsBody(props.exclusions),
338 bigqueryOptions: props.bigqueryOptions,
339 includeChildren: props.includeChildren === true ? true : undefined,
340 interceptChildren: props.interceptChildren === true ? true : undefined,
341 });
342
343 export const SinkProvider = () =>
344 Provider.succeed(Sink, {
345 stables: ["name", "sinkId", "project", "createTime"],
346
347 diff: Effect.fn(function* ({ news, olds, output }) {
348 if (!isResolved(news)) return undefined;
349 const previous = olds?.sinkId ?? output?.sinkId;
350 if (previous !== undefined && news.sinkId !== undefined && news.sinkId !== previous) {
351 return { action: "replace" as const, deleteFirst: false };
352 }
353 return undefined;
354 }),
355
356 read: Effect.fn(function* ({ id, olds, output }) {
357 const env = yield* GcpEnvironment.current;
358 const sinkId = yield* toId(id, olds?.sinkId, output?.sinkId);
359 const name = output?.name ?? resourceName(env.project, sinkId);
360 const existing = yield* getByName(name);
361 if (existing === undefined) return undefined;
362 const attrs = toAttrs(existing, env.project);
363 const { labels } = parseDescription(existing.description);
364 return (yield* hasAlchemyLabels(id, labels)) ? attrs : Unowned(attrs);
365 }),
366
367 list: () =>
368 Effect.gen(function* () {
369 const env = yield* GcpEnvironment.current;
370 return yield* logging.listSinks
371 .pages({
372 parent: `projects/${env.project}`,
373 pageSize: 1000,
374 })
375 .pipe(
376 Stream.flatMap((page) => Stream.fromIterable(page.sinks ?? [])),
377 Stream.filter((sink) => hasOwnershipMarker(sink.description)),
378 Stream.map((sink) => toAttrs(sink, env.project)),
379 Stream.runCollect,
380 Effect.map((chunk) => Array.from(chunk)),
381 );
382 }),
383
384 reconcile: Effect.fn(function* ({ id, news, output }) {
385 const env = yield* GcpEnvironment.current;
386 const sinkId = yield* toId(id, news.sinkId, output?.sinkId);
387 const name = resourceName(env.project, sinkId);
388 const ownership = yield* createInternalLabels(id);
389 const desiredDescription = encodeDescription(ownership, news.description);
390
391 let current = yield* getByName(output?.name ?? name);
392
393 if (current === undefined) {
394 const created = yield* logging
395 .createSinks({
396 parent: `projects/${env.project}`,
397 uniqueWriterIdentity: news.uniqueWriterIdentity,
398 customWriterIdentity: news.customWriterIdentity,
399 body: toCreateBody(sinkId, news, desiredDescription),
400 })
401 .pipe(Effect.catchTag("Conflict", () => getByName(name)));
402 current = created ?? undefined;
403 }
404
405 if (current === undefined) {
406 return yield* new SinkNotResolved({ resourceName: name });
407 }
408
409 const desiredDisabled = news.disabled === true;
410 const desiredIncludeChildren = news.includeChildren === true;
411 const desiredInterceptChildren = news.interceptChildren === true;
412 const desiredBq = news.bigqueryOptions?.usePartitionedTables === true;
413 const observedBq = current.bigqueryOptions?.usePartitionedTables === true;
414
415 const destinationChanged = (current.destination ?? "") !== news.destination;
416 const filterChanged = (current.filter ?? "") !== (news.filter ?? "");
417 const descriptionChanged = (current.description ?? "") !== desiredDescription;
418 const disabledChanged = (current.disabled === true) !== desiredDisabled;
419 const exclusionsChanged = !sameExclusions(current.exclusions, news.exclusions);
420 const bqChanged = news.bigqueryOptions !== undefined && desiredBq !== observedBq;
421 const includeChildrenChanged =
422 news.includeChildren !== undefined &&
423 (current.includeChildren === true) !== desiredIncludeChildren;
424 const interceptChildrenChanged =
425 news.interceptChildren !== undefined &&
426 (current.interceptChildren === true) !== desiredInterceptChildren;
427
428 const updateMask = [
429 destinationChanged ? "destination" : undefined,
430 filterChanged ? "filter" : undefined,
431 descriptionChanged ? "description" : undefined,
432 disabledChanged ? "disabled" : undefined,
433 exclusionsChanged ? "exclusions" : undefined,
434 bqChanged ? "bigqueryOptions.usePartitionedTables" : undefined,
435 includeChildrenChanged ? "includeChildren" : undefined,
436 interceptChildrenChanged ? "interceptChildren" : undefined,
437 ].filter((field): field is string => field !== undefined);
438
439 if (updateMask.length > 0) {
440 const body: logging.LogSink = {
441 name: sinkId,
442 destination: news.destination,
443 filter: news.filter ?? "",
444 description: desiredDescription,
445 disabled: desiredDisabled,
446 };
447 if (exclusionsChanged) {
448 body.exclusions = toExclusionsBody(news.exclusions) ?? [];
449 }
450 if (bqChanged) {
451 body.bigqueryOptions = {
452 usePartitionedTables: desiredBq,
453 };
454 }
455 if (includeChildrenChanged) {
456 body.includeChildren = desiredIncludeChildren;
457 }
458 if (interceptChildrenChanged) {
459 body.interceptChildren = desiredInterceptChildren;
460 }
461 current = yield* logging.updateSinks({
462 sinkName: current.resourceName ?? name,
463 uniqueWriterIdentity: news.uniqueWriterIdentity,
464 customWriterIdentity: news.customWriterIdentity,
465 updateMask: updateMask.join(","),
466 body,
467 });
468 }
469
470 return toAttrs(current, env.project);
471 }),
472
473 delete: Effect.fn(function* ({ output }) {
474 yield* logging
475 .deleteSinks({ sinkName: output.name })
476 .pipe(Effect.catchTag("NotFound", () => Effect.void));
477 }),
478 });