@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 257 lines 8.97 KB
Raw
1 import * as k2 from "@distilled.cloud/cloudflare/k2";
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 Predicate from "effect/Predicate";
10 import type { Providers } from "../Providers.ts";
11 import type { StartAt } from "./K2Types.ts";
12 import type { Stream } from "./Stream.ts";
13
14 const SubscriptionTypeId = "Cloudflare.K2.Subscription" as const;
15 type SubscriptionTypeId = typeof SubscriptionTypeId;
16
17 export interface SubscriptionProps {
18 /**
19 * The stream to read from: a `Cloudflare.K2.Stream` resource (orders the
20 * subscription after the stream) or a stream ID. Changing it replaces the
21 * subscription.
22 */
23 stream: string | Stream<any>;
24 /**
25 * Name of the subscription: 1 to 128 letters, numbers, underscores, or
26 * hyphens, unique within the stream (not case-sensitive). If omitted, a
27 * unique name is generated from the app, stage, and logical ID. Changing
28 * it replaces the subscription.
29 * @default ${app}-${id}-${stage}-${suffix}
30 */
31 name?: string;
32 /**
33 * Where the subscription starts reading: `earliest` from the oldest
34 * retained record, `latest` from after the newest one. Changing it
35 * replaces the subscription.
36 * @default "latest"
37 */
38 startAt?: StartAt;
39 }
40
41 export interface SubscriptionAttributes {
42 /** The subscription ID. */
43 subscriptionId: string;
44 /** The subscription name (unique within the stream). */
45 subscriptionName: string;
46 /** ID of the stream the subscription reads from. */
47 streamId: string;
48 /** Where the subscription started reading. */
49 startAt: StartAt;
50 /** When the subscription was created. */
51 createdAt: string;
52 /** When the subscription was last modified. */
53 modifiedAt: string;
54 }
55
56 export type Subscription = Resource<
57 SubscriptionTypeId,
58 SubscriptionProps,
59 SubscriptionAttributes,
60 never,
61 Providers
62 >;
63
64 /**
65 * A K2 subscription — a named read position on a {@link Stream}. Consumers
66 * lease batches of records from a subscription, then acknowledge them to
67 * advance it. Every subscription on a stream reads every record
68 * independently; consumers sharing one subscription compete for batches.
69 *
70 * Subscriptions are immutable: changing the stream, name, or start position
71 * replaces the subscription.
72 * ### Creating a Subscription
73 * **Example:** Read new records
74 * ```typescript
75 * const orders = yield* Cloudflare.K2.Stream("Orders");
76 * const analytics = yield* Cloudflare.K2.Subscription("Analytics", {
77 * stream: orders,
78 * });
79 * ```
80 *
81 * **Example:** Read from the oldest retained record
82 * ```typescript
83 * const backfill = yield* Cloudflare.K2.Subscription("Backfill", {
84 * stream: orders,
85 * startAt: "earliest",
86 * });
87 * ```
88 *
89 * ### Pulling Records
90 * **Example:** Lease, process, and acknowledge a batch
91 * ```typescript
92 * const inbox = yield* Cloudflare.K2.ReadSubscription(analytics);
93 * const batch = yield* inbox.consume({ workerId: "worker-1", maxRecords: 100 });
94 * if (Option.isSome(batch)) {
95 * yield* Effect.forEach(batch.value.records, handle);
96 * yield* inbox.ack(batch.value);
97 * }
98 * ```
99 *
100 * @resource
101 * @product K2
102 * @category Storage & Databases
103 */
104 export const Subscription = Resource<Subscription>(SubscriptionTypeId);
105
106 /** Returns true if the given value is a K2 Subscription resource. */
107 export const isSubscription = (value: unknown): value is Subscription =>
108 Predicate.hasProperty(value, "Type") && value.Type === SubscriptionTypeId;
109
110 export const SubscriptionProvider = () =>
111 Provider.succeed(Subscription, {
112 stables: ["subscriptionId", "subscriptionName", "streamId", "startAt", "createdAt"],
113
114 diff: Effect.fn(function* ({ id, olds, news, output }) {
115 if (!isResolved(news)) return undefined;
116 const oldName = output?.subscriptionName ?? (yield* subscriptionName(id, olds?.name));
117 const newName = news.name ?? oldName;
118 const oldStartAt = output?.startAt ?? olds?.startAt ?? "latest";
119 const streamChanged =
120 (output?.streamId ?? streamIdOf(olds?.stream)) !== streamIdOf(news.stream);
121 if (
122 streamChanged ||
123 newName.toLowerCase() !== oldName.toLowerCase() ||
124 (news.startAt ?? "latest") !== oldStartAt
125 ) {
126 // An explicit name is reused by the replacement; K2 rejects the same
127 // name with different settings, so delete the old one first.
128 return {
129 action: "replace",
130 deleteFirst: news.name !== undefined && !streamChanged,
131 } as const;
132 }
133 return undefined;
134 }),
135
136 read: Effect.fn(function* ({ id, output, olds, previous }) {
137 const streamId = output?.streamId ?? streamIdOf(olds?.stream);
138 if (!streamId) return undefined;
139 if (output?.subscriptionId) {
140 const observed = yield* getSubscription(streamId, output.subscriptionId);
141 if (observed) return toAttributes(observed, streamId);
142 }
143 const name = yield* subscriptionName(id, olds?.name);
144 const match = yield* findSubscriptionByName(streamId, name);
145 if (match) {
146 const attrs = toAttributes(match, streamId);
147 // The generation a replacement is replacing is ours.
148 return olds?.name !== undefined && attrs.subscriptionId !== previous?.subscriptionId
149 ? Unowned(attrs)
150 : attrs;
151 }
152 return undefined;
153 }),
154
155 reconcile: Effect.fn(function* ({ id, news, output }) {
156 const streamId = streamIdOf(news.stream);
157 if (streamId === undefined) {
158 return yield* new SubscriptionStreamUnresolved({
159 message: "`stream` did not resolve to a stream ID",
160 });
161 }
162 const name =
163 output?.streamId === streamId
164 ? output.subscriptionName
165 : yield* subscriptionName(id, news.name);
166 const startAt = news.startAt ?? "latest";
167
168 // Observe — the cached id is only valid on the same stream.
169 let observed =
170 output?.subscriptionId && output.streamId === streamId
171 ? yield* getSubscription(streamId, output.subscriptionId)
172 : undefined;
173
174 // Ensure — creating with the same name and settings returns the
175 // existing subscription's id, so a lost state write converges here.
176 if (!observed) {
177 const created = yield* k2.createSubscription({
178 streamId,
179 name,
180 startAt: { type: startAt },
181 });
182 observed = yield* k2.getSubscription({ streamId, subscriptionId: created.id });
183 }
184
185 // Subscriptions have no mutable settings; every change is a replace.
186 return toAttributes(observed, streamId);
187 }),
188
189 delete: Effect.fn(function* ({ output }) {
190 yield* k2
191 .deleteSubscription({
192 streamId: output.streamId,
193 subscriptionId: output.subscriptionId,
194 })
195 .pipe(Effect.catchTag(["K2SubscriptionNotFound", "K2StreamNotFound"], () => Effect.void));
196 }),
197 });
198
199 interface ObservedSubscription {
200 id: string;
201 name: string;
202 startAt: k2.SubscriptionStartAt;
203 createdAt: string;
204 modifiedAt: string;
205 }
206
207 const subscriptionName = (id: string, name: string | undefined) =>
208 Effect.gen(function* () {
209 if (name) return name;
210 const generated = yield* createPhysicalName({ id, maxLength: 128 });
211 return generated.replaceAll(/[^a-zA-Z0-9_-]/g, "-");
212 });
213
214 /** The `stream` prop did not resolve to a stream ID. */
215 export class SubscriptionStreamUnresolved extends Data.TaggedError(
216 "K2SubscriptionStreamUnresolved",
217 )<{ message: string }> {}
218
219 /**
220 * The stream ID behind a `stream` prop: the string itself, or the `streamId`
221 * attribute of a resolved `Cloudflare.K2.Stream`.
222 */
223 const streamIdOf = (stream: unknown): string | undefined =>
224 typeof stream === "string"
225 ? stream
226 : stream !== null &&
227 typeof stream === "object" &&
228 typeof (stream as { streamId?: unknown }).streamId === "string"
229 ? (stream as { streamId: string }).streamId
230 : undefined;
231
232 const getSubscription = (streamId: string, subscriptionId: string) =>
233 k2.getSubscription({ streamId, subscriptionId }).pipe(
234 Effect.map((s): ObservedSubscription | undefined => s),
235 Effect.catchTag(["K2SubscriptionNotFound", "K2StreamNotFound"], () => Effect.undefined),
236 );
237
238 /** `listSubscriptions` filters by name server-side (at most one match). */
239 const findSubscriptionByName = (streamId: string, name: string) =>
240 k2.listSubscriptions({ streamId, name }).pipe(
241 Effect.map((subs): ObservedSubscription | undefined =>
242 subs.find((s) => s.name.toLowerCase() === name.toLowerCase()),
243 ),
244 Effect.catchTag("K2StreamNotFound", () => Effect.undefined),
245 );
246
247 const toAttributes = (
248 observed: ObservedSubscription,
249 streamId: string,
250 ): SubscriptionAttributes => ({
251 subscriptionId: observed.id,
252 subscriptionName: observed.name,
253 streamId,
254 startAt: observed.startAt.type === "earliest" ? "earliest" : "latest",
255 createdAt: observed.createdAt,
256 modifiedAt: observed.modifiedAt,
257 });