@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 551 lines 19.1 KB
Raw
1 import * as r2 from "@distilled.cloud/cloudflare/r2";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { deepEqual } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Effect from "effect/Effect";
7 import * as Predicate from "effect/Predicate";
8 import * as Schedule from "effect/Schedule";
9 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
10 import type { Providers } from "../Providers.ts";
11 import type { Bucket } from "./Bucket.ts";
12
13 const TypeId = "Cloudflare.R2.BucketEventNotification" as const;
14 type TypeId = typeof TypeId;
15
16 /**
17 * An R2 object action that can trigger an event notification.
18 *
19 * - `PutObject` — an object is uploaded via a single PUT
20 * - `CopyObject` — an object is copied into the bucket
21 * - `DeleteObject` — an object is deleted
22 * - `CompleteMultipartUpload` — a multipart upload completes
23 * - `LifecycleDeletion` — an object is deleted by a lifecycle rule
24 */
25 export type BucketEventNotificationAction =
26 | "PutObject"
27 | "CopyObject"
28 | "DeleteObject"
29 | "CompleteMultipartUpload"
30 | "LifecycleDeletion";
31
32 /**
33 * A single notification rule. An event message is delivered to the queue
34 * when an object matching the rule's `prefix`/`suffix` undergoes one of
35 * the rule's `actions`.
36 */
37 export interface BucketEventNotificationRule {
38 /**
39 * Object actions that trigger a notification for this rule.
40 */
41 actions: BucketEventNotificationAction[];
42 /**
43 * Only notify for objects whose key starts with this prefix.
44 * @default "" (match all objects)
45 */
46 prefix?: string;
47 /**
48 * Only notify for objects whose key ends with this suffix.
49 * @default "" (match all objects)
50 */
51 suffix?: string;
52 /**
53 * Human-readable description of the rule. Cloudflare auto-generates one
54 * when omitted.
55 */
56 description?: string;
57 }
58
59 export interface BucketEventNotificationProps {
60 /**
61 * Name of the R2 bucket that produces the events. Pass
62 * `bucket.bucketName` from a `Cloudflare.R2.Bucket`.
63 *
64 * Immutable — changing the bucket triggers a replacement.
65 */
66 bucketName: string;
67 /**
68 * ID of the Queue that receives the event messages. Pass
69 * `queue.queueId` from a `Cloudflare.Queues.Queue`.
70 *
71 * Immutable — changing the queue triggers a replacement.
72 */
73 queueId: string;
74 /**
75 * Jurisdiction of the bucket (must match the bucket's own jurisdiction).
76 *
77 * Immutable — changing the jurisdiction triggers a replacement.
78 * @default "default"
79 */
80 jurisdiction?: Bucket.Jurisdiction;
81 /**
82 * Rules that decide which object events are delivered to the queue.
83 * The full set is replaced on every update (the provider clears the
84 * pair's configuration and re-creates the desired rules when they
85 * drift).
86 *
87 * Note: Cloudflare rejects rule sets whose `prefix`/`suffix` key ranges
88 * overlap ("invalid overlap"), even when their actions are disjoint —
89 * scope each rule to a distinct key range.
90 */
91 rules: BucketEventNotificationRule[];
92 }
93
94 export interface BucketEventNotificationAttributes {
95 /** Name of the bucket that produces the events. */
96 bucketName: string;
97 /** ID of the queue that receives the event messages. */
98 queueId: string;
99 /** Name of the queue that receives the event messages, if reported. */
100 queueName: string | undefined;
101 /** Account the configuration lives in. */
102 accountId: string;
103 /** Jurisdiction of the bucket. */
104 jurisdiction: Bucket.Jurisdiction;
105 /** The active notification rules, including server-assigned rule IDs. */
106 rules: BucketEventNotification.Rule[];
107 }
108
109 export type BucketEventNotification = Resource<
110 TypeId,
111 BucketEventNotificationProps,
112 BucketEventNotificationAttributes,
113 never,
114 Providers
115 >;
116
117 /**
118 * Event notifications for a Cloudflare R2 bucket, delivered to a Queue.
119 *
120 * When objects in the bucket are created, deleted, or copied, R2 publishes
121 * an event message to the configured Queue. One configuration exists per
122 * (bucket, queue) pair and holds a list of rules; consume the messages with
123 * a Queue consumer Worker.
124 *
125 * The configuration's identity is the (bucket, queue) pair — changing
126 * either triggers a replacement, while rule changes are applied in place
127 * (the provider converges the pair's configuration to exactly the
128 * declared rule set).
129 * ### Notifying a Queue
130 * **Example:** Notify on every upload and delete
131 * ```typescript
132 * const bucket = yield* Cloudflare.R2.Bucket("Uploads");
133 * const queue = yield* Cloudflare.Queues.Queue("UploadEvents");
134 *
135 * yield* Cloudflare.R2.BucketEventNotification("UploadNotifications", {
136 * bucketName: bucket.bucketName,
137 * queueId: queue.queueId,
138 * rules: [
139 * {
140 * actions: ["PutObject", "CompleteMultipartUpload", "DeleteObject"],
141 * },
142 * ],
143 * });
144 * ```
145 *
146 * **Example:** Scope notifications to a key prefix and suffix
147 * ```typescript
148 * yield* Cloudflare.R2.BucketEventNotification("ImageNotifications", {
149 * bucketName: bucket.bucketName,
150 * queueId: queue.queueId,
151 * rules: [
152 * {
153 * actions: ["PutObject"],
154 * prefix: "images/",
155 * suffix: ".png",
156 * description: "new PNG images",
157 * },
158 * ],
159 * });
160 * ```
161 *
162 * ### Multiple rules
163 * **Example:** Separate rules per key range
164 * ```typescript
165 * // Rules must cover non-overlapping key ranges — Cloudflare rejects
166 * // overlapping prefixes/suffixes even when the actions are disjoint.
167 * yield* Cloudflare.R2.BucketEventNotification("Notifications", {
168 * bucketName: bucket.bucketName,
169 * queueId: queue.queueId,
170 * rules: [
171 * { actions: ["PutObject"], prefix: "incoming/" },
172 * { actions: ["DeleteObject", "LifecycleDeletion"], prefix: "logs/" },
173 * ],
174 * });
175 * ```
176 *
177 * @see https://developers.cloudflare.com/r2/buckets/event-notifications/
178 *
179 * @resource
180 * @product R2
181 * @category Storage & Databases
182 */
183 export const BucketEventNotification = Resource<BucketEventNotification>(TypeId);
184
185 export declare namespace BucketEventNotification {
186 export type Rule = {
187 actions: BucketEventNotificationAction[];
188 prefix: string;
189 suffix: string;
190 description: string | undefined;
191 ruleId: string | undefined;
192 createdAt: string | undefined;
193 };
194 }
195
196 /**
197 * Returns true if the given value is an BucketEventNotification resource.
198 */
199 export const isBucketEventNotification = (value: unknown): value is BucketEventNotification =>
200 Predicate.hasProperty(value, "Type") && value.Type === TypeId;
201
202 export const BucketEventNotificationProvider = () =>
203 Provider.succeed(BucketEventNotification, {
204 stables: ["bucketName", "queueId", "accountId", "jurisdiction"],
205
206 diff: Effect.fn(function* ({ olds = {}, news }) {
207 const o = olds as Partial<BucketEventNotificationProps>;
208 const n = news as BucketEventNotificationProps;
209 // No prior props to compare against — let the engine decide.
210 if (o.bucketName === undefined) return undefined;
211 // bucketName/queueId are Input<string>; compare only once both
212 // sides are concrete strings.
213 if (
214 typeof o.bucketName === "string" &&
215 typeof n.bucketName === "string" &&
216 o.bucketName !== n.bucketName
217 ) {
218 return { action: "replace" } as const;
219 }
220 if (
221 typeof o.queueId === "string" &&
222 typeof n.queueId === "string" &&
223 o.queueId !== n.queueId
224 ) {
225 return { action: "replace" } as const;
226 }
227 if ((o.jurisdiction ?? "default") !== (n.jurisdiction ?? "default")) {
228 return { action: "replace" } as const;
229 }
230 return undefined;
231 }),
232
233 read: Effect.fn(function* ({ output, olds }) {
234 const { accountId } = yield* yield* CloudflareEnvironment;
235 const acct = output?.accountId ?? accountId;
236 // The (bucket, queue) pair is the configuration's identity; cold
237 // reads derive it from the last-persisted props.
238 const bucketName =
239 output?.bucketName ?? (typeof olds?.bucketName === "string" ? olds.bucketName : undefined);
240 const queueId =
241 output?.queueId ?? (typeof olds?.queueId === "string" ? olds.queueId : undefined);
242 if (bucketName === undefined || queueId === undefined) return undefined;
243 const jurisdiction = output?.jurisdiction ?? olds?.jurisdiction ?? "default";
244
245 const observed = yield* getConfiguration(acct, bucketName, queueId, jurisdiction);
246 if (!observed) return undefined;
247
248 const attrs = toAttributes(observed, acct, bucketName, queueId, jurisdiction);
249 // Event notification configs carry no ownership markers. With no
250 // prior output we cannot prove we created this configuration —
251 // brand it `Unowned` so takeover is gated behind the adopt policy.
252 return output ? attrs : Unowned(attrs);
253 }),
254
255 reconcile: Effect.fn(function* ({ news, output }) {
256 const { accountId } = yield* yield* CloudflareEnvironment;
257 const acct = output?.accountId ?? accountId;
258 // Inputs have been resolved to concrete strings by Plan.
259 const bucketName = news.bucketName as string;
260 const queueId = news.queueId as string;
261 const jurisdiction = news.jurisdiction ?? "default";
262
263 // 1. Observe — the configuration may or may not exist; `output` is
264 // only a cache of the identity, never proof of existence.
265 const observed = yield* getConfiguration(acct, bucketName, queueId, jurisdiction);
266
267 // 2/3. Ensure + sync — skip the API entirely when the observed rules
268 // already match the desired set.
269 if (!observed || !sameRules(observed.rules ?? [], news.rules)) {
270 // The PUT *appends* rules to the queue's configuration (it is not
271 // a full replace — verified against the live API), so on drift
272 // the existing configuration must be cleared first. The brief gap
273 // is unavoidable; each step is independently idempotent.
274 if (observed) {
275 yield* r2
276 .deleteBucketEventNotification({
277 accountId: acct,
278 bucketName,
279 queueId,
280 jurisdiction,
281 })
282 .pipe(
283 Effect.catchTag(
284 ["EventNotificationConfigNotFound", "BucketNotFound", "QueueNotFound"],
285 () => Effect.void,
286 ),
287 );
288 }
289 yield* r2
290 .putBucketEventNotification({
291 accountId: acct,
292 bucketName,
293 queueId,
294 jurisdiction,
295 rules: news.rules.map((rule) => ({
296 actions: [...rule.actions],
297 prefix: rule.prefix,
298 suffix: rule.suffix,
299 description: rule.description,
300 })),
301 })
302 .pipe(
303 // A freshly-created bucket or queue can briefly 404 on the
304 // event-notification endpoint — ride out the consistency lag.
305 Effect.retry({
306 while: (e) => e._tag === "BucketNotFound" || e._tag === "QueueNotFound",
307 schedule: r2EventNotificationConsistencySchedule,
308 }),
309 );
310 }
311
312 // 4. Return — re-read so the attributes carry the server-assigned
313 // per-rule IDs. The read can lag the PUT briefly.
314 if (news.rules.length === 0) {
315 // An empty rule set reads back as "no configuration".
316 return toAttributes(
317 { queueId, queueName: undefined, rules: [] },
318 acct,
319 bucketName,
320 queueId,
321 jurisdiction,
322 );
323 }
324 const final = yield* r2
325 .getBucketEventNotification({
326 accountId: acct,
327 bucketName,
328 queueId,
329 jurisdiction,
330 })
331 .pipe(
332 Effect.retry({
333 while: (e) =>
334 e._tag === "NoEventNotificationConfig" ||
335 e._tag === "EventNotificationConfigNotFound" ||
336 e._tag === "BucketNotFound" ||
337 e._tag === "QueueNotFound",
338 schedule: r2EventNotificationConsistencySchedule,
339 }),
340 );
341 return toAttributes(final, acct, bucketName, queueId, jurisdiction);
342 }),
343
344 delete: Effect.fn(function* ({ output }) {
345 // Idempotent — the configuration, bucket, or queue may already be
346 // gone (all typed not-found variants in the operation's union).
347 yield* r2
348 .deleteBucketEventNotification({
349 accountId: output.accountId,
350 bucketName: output.bucketName,
351 queueId: output.queueId,
352 jurisdiction: output.jurisdiction,
353 })
354 .pipe(
355 Effect.catchTag(
356 ["EventNotificationConfigNotFound", "BucketNotFound", "QueueNotFound"],
357 () => Effect.void,
358 ),
359 );
360 }),
361
362 // Parent fan-out: a notification configuration is keyed by (bucket,
363 // queue) and there is no account-wide enumeration. Enumerate every R2
364 // bucket (account-scoped), then list each bucket's event-notification
365 // queues — one (bucket, queue) pair is one BucketEventNotification.
366 list: Effect.fn(function* () {
367 const { accountId } = yield* yield* CloudflareEnvironment;
368 const buckets = yield* listAllBuckets(accountId);
369 const perBucket = yield* Effect.forEach(
370 buckets,
371 (bucket) => {
372 const bucketName = bucket.name;
373 if (bucketName == null) {
374 return Effect.succeed([] as BucketEventNotificationAttributes[]);
375 }
376 const jurisdiction = (bucket.jurisdiction ?? "default") as Bucket.Jurisdiction;
377 return r2
378 .listBucketEventNotifications({
379 accountId,
380 bucketName,
381 jurisdiction,
382 })
383 .pipe(
384 Effect.map((res) =>
385 (res.queues ?? [])
386 .filter((q): q is typeof q & { queueId: string } => q.queueId != null)
387 .map((q): BucketEventNotificationAttributes => ({
388 bucketName,
389 // The endpoint echoes the queue ID in dashed-UUID
390 // form; normalise to the undashed form
391 // `Queue.queueId` uses so list items match `read`.
392 queueId: q.queueId.replace(/-/g, ""),
393 queueName: q.queueName ?? undefined,
394 accountId,
395 jurisdiction,
396 rules: (q.rules ?? []).map(toRuleAttributes),
397 })),
398 ),
399 // A bucket with no event-notification config (or a bucket
400 // that vanished mid-enumeration) is not an error — skip it.
401 Effect.catchTag(
402 [
403 "NoEventNotificationConfig",
404 "BucketNotFound",
405 "NoSuchBucket",
406 // Plan-gated / partial buckets reject the route.
407 "InvalidRoute",
408 ],
409 () => Effect.succeed([] as BucketEventNotificationAttributes[]),
410 ),
411 );
412 },
413 { concurrency: 10 },
414 );
415 return perBucket.flat();
416 }),
417 });
418
419 // R2 can make a freshly-created bucket/queue visible to its own endpoints
420 // before the event-notification endpoints accept it. Retry only that narrow
421 // not-found lag with a bounded budget.
422 const r2EventNotificationConsistencySchedule = Schedule.max([
423 Schedule.exponential(250),
424 Schedule.recurs(6),
425 ]);
426
427 type ObservedBucket = NonNullable<r2.ListBucketsResponse["buckets"]>[number];
428
429 // `listBuckets` is a non-paginated distilled op that returns at most one
430 // page (default ordering by name). Page through it exhaustively with the
431 // `startAfter` cursor so `list()` enumerates *every* bucket in the account.
432 const listAllBuckets = (accountId: string) =>
433 Effect.gen(function* () {
434 const pageSize = 1000;
435 const all: ObservedBucket[] = [];
436 let startAfter: string | undefined;
437 while (true) {
438 const { buckets } = yield* r2.listBuckets({
439 accountId,
440 perPage: pageSize,
441 startAfter,
442 });
443 const page = buckets ?? [];
444 all.push(...page);
445 const last = page.at(-1)?.name;
446 if (page.length < pageSize || last == null) break;
447 startAfter = last;
448 }
449 return all;
450 });
451
452 const getConfiguration = (
453 accountId: string,
454 bucketName: string,
455 queueId: string,
456 jurisdiction: Bucket.Jurisdiction,
457 ) =>
458 r2
459 .getBucketEventNotification({
460 accountId,
461 bucketName,
462 queueId,
463 jurisdiction,
464 })
465 .pipe(
466 Effect.map((config): r2.GetBucketEventNotificationResponse | undefined => config),
467 // "Gone" comes in several typed flavors: the bucket has no event
468 // notification config at all (`NoEventNotificationConfig`, code
469 // 11015), no config for this queue (`EventNotificationConfigNotFound`,
470 // code 11011), or the bucket/queue themselves are gone.
471 Effect.catchTag(
472 [
473 "NoEventNotificationConfig",
474 "EventNotificationConfigNotFound",
475 "BucketNotFound",
476 "QueueNotFound",
477 ],
478 () => Effect.undefined,
479 ),
480 );
481
482 type ObservedRule = NonNullable<r2.GetBucketEventNotificationResponse["rules"]>[number];
483
484 const toRuleAttributes = (rule: ObservedRule): BucketEventNotification.Rule => ({
485 // Distilled widens generated string enums to open unions; the API only
486 // returns the known action variants.
487 actions: [...rule.actions] as BucketEventNotificationAction[],
488 prefix: rule.prefix ?? "",
489 suffix: rule.suffix ?? "",
490 description: rule.description ?? undefined,
491 ruleId: rule.ruleId ?? undefined,
492 createdAt: rule.createdAt ?? undefined,
493 });
494
495 const toAttributes = (
496 config: r2.GetBucketEventNotificationResponse,
497 accountId: string,
498 bucketName: string,
499 queueId: string,
500 jurisdiction: Bucket.Jurisdiction,
501 ): BucketEventNotificationAttributes => ({
502 bucketName,
503 // The endpoint echoes the queue ID in dashed-UUID form while the Queues
504 // API uses the undashed form — keep the canonical input ID so attributes
505 // compare cleanly against `Queue.queueId`.
506 queueId,
507 queueName: config.queueName ?? undefined,
508 accountId,
509 jurisdiction,
510 rules: (config.rules ?? []).map(toRuleAttributes),
511 });
512
513 /**
514 * A rule's identity within the configuration: its matched actions (order-
515 * insensitive) plus prefix/suffix. The server-assigned `ruleId` and
516 * auto-generated description are deliberately excluded.
517 */
518 const ruleIdentity = (rule: {
519 actions: readonly string[];
520 prefix?: string | null;
521 suffix?: string | null;
522 }) =>
523 JSON.stringify({
524 actions: [...rule.actions].sort(),
525 prefix: rule.prefix ?? "",
526 suffix: rule.suffix ?? "",
527 });
528
529 /**
530 * Compares the observed rules against the desired rules as an unordered
531 * set. Descriptions are compared only when the desired rule specifies one —
532 * Cloudflare auto-generates a description otherwise.
533 */
534 const sameRules = (
535 observed: readonly ObservedRule[],
536 desired: readonly BucketEventNotificationRule[],
537 ): boolean => {
538 if (observed.length !== desired.length) return false;
539 const observedKeys = observed.map(ruleIdentity).sort();
540 const desiredKeys = desired.map(ruleIdentity).sort();
541 if (!deepEqual(observedKeys, desiredKeys)) return false;
542 return desired.every(
543 (rule) =>
544 rule.description === undefined ||
545 observed.some(
546 (candidate) =>
547 ruleIdentity(candidate) === ruleIdentity(rule) &&
548 (candidate.description ?? "") === rule.description,
549 ),
550 );
551 };