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

main
ts 184 lines 6.44 KB
Raw
1 import type * as storage from "@distilled.cloud/gcp/storage_v1";
2 import * as Binding from "alchemy/Binding";
3 import * as Effect from "effect/Effect";
4 import type * as Stream from "effect/Stream";
5 import type { TopicEventSourceProps, TopicMessage } from "../PubSub/TopicEventSource.ts";
6 import type { Bucket } from "./Bucket.ts";
7
8 /** Cloud Storage object event types delivered through Pub/Sub. */
9 export type BucketEventType =
10 | "OBJECT_FINALIZE"
11 | "OBJECT_DELETE"
12 | "OBJECT_ARCHIVE"
13 | "OBJECT_METADATA_UPDATE";
14
15 /** One Cloud Storage object change. */
16 export interface BucketEvent {
17 /** What happened to the object. */
18 eventType: BucketEventType;
19 /** Bucket the object lives in. */
20 bucket: string;
21 /** Object name (key). */
22 object: string;
23 /** Object generation the event refers to. */
24 generation: string;
25 /** RFC3339 time the event occurred. */
26 eventTime: string;
27 /**
28 * Object metadata at the time of the event (the `JSON_API_V1` payload):
29 * `size`, `contentType`, `md5Hash`, `metadata`, …
30 */
31 metadata: storage.Storage_Object;
32 }
33
34 export interface BucketEventSourceProps extends Omit<TopicEventSourceProps, "filter"> {
35 /**
36 * Event types to deliver. Filtered by the bucket notification, so other
37 * events never reach the host.
38 * @default ["OBJECT_FINALIZE"]
39 */
40 eventTypes?: BucketEventType[];
41 /**
42 * Only deliver events for objects whose names start with this prefix.
43 * Filtered by the bucket notification.
44 */
45 prefix?: string;
46 }
47
48 export type BucketEventsHandler<Req> = (
49 events: Stream.Stream<BucketEvent>,
50 ) => Effect.Effect<void, never, Req>;
51
52 export type BucketEventSourceService = <Req = never>(
53 bucket: Bucket,
54 props: BucketEventSourceProps,
55 process: BucketEventsHandler<Req>,
56 ) => Effect.Effect<void, never, never>;
57
58 /**
59 * Event source streaming a Cloud Storage {@link Bucket}'s object changes
60 * (created, deleted, archived, metadata updated) into the hosting compute.
61 *
62 * `GCP.Storage.BucketEventSourceLive` provisions a Pub/Sub topic owned by
63 * the host plus a `JSON_API_V1` bucket notification on it (filtered by
64 * event type and object prefix), then delegates delivery to whichever
65 * `GCP.PubSub.TopicEventSource` implementation is provided alongside it:
66 * `GCP.Run.TopicEventSource` (push, for `GCP.Function` /
67 * `GCP.CloudFunctions.Function`) or `GCP.Run.TopicPullEventSource` (pull,
68 * for `GCP.Run.Job` / `GCP.Run.WorkerPool`).
69 *
70 * Consume it through {@link consumeBucketEvents}.
71 *
72 * ### Consuming Bucket Events
73 * **Example:** Process uploads on a Cloud Run service
74 * ```typescript
75 * export class Thumbnails extends GCP.Function<Thumbnails>()(
76 * "Thumbnails",
77 * { main: import.meta.url },
78 * Effect.gen(function* () {
79 * const uploads = yield* GCP.Storage.Bucket("Uploads", {});
80 * yield* GCP.Storage.consumeBucketEvents(
81 * uploads,
82 * { prefix: "incoming/" },
83 * (events) =>
84 * events.pipe(
85 * Stream.runForEach((event) =>
86 * Effect.log(`${event.object} (${event.metadata.size} bytes)`),
87 * ),
88 * ),
89 * );
90 * }).pipe(
91 * Effect.provide(GCP.Storage.BucketEventSourceLive),
92 * Effect.provide(GCP.Run.TopicEventSource),
93 * ),
94 * ) {}
95 * ```
96 *
97 * **Example:** Deletions on a worker pool
98 * ```typescript
99 * yield* GCP.Storage.consumeBucketEvents(
100 * uploads,
101 * { eventTypes: ["OBJECT_DELETE", "OBJECT_ARCHIVE"] },
102 * (events) => events.pipe(Stream.runForEach(handle)),
103 * );
104 * // …provided with GCP.Storage.BucketEventSourceLive
105 * // and GCP.Run.TopicPullEventSource
106 * ```
107 *
108 * @binding
109 * @category Storage
110 */
111 export interface BucketEventSource extends Binding.Service<
112 BucketEventSource,
113 "GCP.Storage.BucketEventSource",
114 BucketEventSourceService
115 > {}
116
117 export const BucketEventSource = Binding.Service<BucketEventSource>(
118 "GCP.Storage.BucketEventSource",
119 );
120
121 /**
122 * Subscribe an Effect handler to object changes in a Cloud Storage
123 * {@link Bucket}. See {@link BucketEventSource} for the implementations.
124 */
125 export function consumeBucketEvents<Req = never, ResourceReq = never>(
126 bucket: Bucket | Effect.Effect<Bucket, never, ResourceReq>,
127 process: BucketEventsHandler<Req>,
128 ): Effect.Effect<void, never, BucketEventSource | ResourceReq>;
129 export function consumeBucketEvents<Req = never, ResourceReq = never>(
130 bucket: Bucket | Effect.Effect<Bucket, never, ResourceReq>,
131 props: BucketEventSourceProps,
132 process: BucketEventsHandler<Req>,
133 ): Effect.Effect<void, never, BucketEventSource | ResourceReq>;
134 export function consumeBucketEvents<Req = never, ResourceReq = never>(
135 bucket: Bucket | Effect.Effect<Bucket, never, ResourceReq>,
136 propsOrProcess: BucketEventSourceProps | BucketEventsHandler<Req>,
137 maybeProcess?: BucketEventsHandler<Req>,
138 ): Effect.Effect<void, never, BucketEventSource | ResourceReq> {
139 const [props, process] =
140 typeof propsOrProcess === "function"
141 ? [{} as BucketEventSourceProps, propsOrProcess]
142 : [propsOrProcess, maybeProcess!];
143 // Accept the resource or the Effect that declares it, like bindings do.
144 const resolved = Effect.isEffect(bucket) ? bucket : Effect.succeed(bucket);
145 return resolved.pipe(
146 Effect.flatMap((value) => BucketEventSource.use((source) => source(value, props, process))),
147 );
148 }
149
150 const decodeBase64Utf8 = (data: string) => {
151 const binary = atob(data);
152 const bytes = new Uint8Array(binary.length);
153 for (let index = 0; index < binary.length; index++) {
154 bytes[index] = binary.charCodeAt(index);
155 }
156 return new TextDecoder().decode(bytes);
157 };
158
159 /**
160 * Parse a Cloud Storage Pub/Sub notification into a {@link BucketEvent}.
161 * The routing fields come from the message attributes; `metadata` is the
162 * `JSON_API_V1` object resource in `data` (empty when the notification
163 * uses `NONE` or the payload is unreadable).
164 */
165 export const toBucketEvent = ({ message }: TopicMessage) =>
166 Effect.sync((): BucketEvent => {
167 const attributes = message.attributes ?? {};
168 let metadata: storage.Storage_Object = {};
169 try {
170 if (message.data) {
171 metadata = JSON.parse(decodeBase64Utf8(message.data)) as storage.Storage_Object;
172 }
173 } catch {
174 metadata = {};
175 }
176 return {
177 eventType: (attributes.eventType ?? "OBJECT_FINALIZE") as BucketEventType,
178 bucket: attributes.bucketId ?? metadata.bucket ?? "",
179 object: attributes.objectId ?? metadata.name ?? "",
180 generation: attributes.objectGeneration ?? String(metadata.generation ?? ""),
181 eventTime: attributes.eventTime ?? message.publishTime ?? "",
182 metadata,
183 };
184 });