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

main
ts 474 lines 16.9 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 type { PropsInput } from "alchemy/Input";
5 import { createPhysicalName } from "alchemy/PhysicalName";
6 import * as Provider from "alchemy/Provider";
7 import { Resource, type ResourceClass } from "alchemy/Resource";
8 import { toWireSeconds } from "alchemy/Util/Duration";
9 import type * as Duration from "effect/Duration";
10 import * as Effect from "effect/Effect";
11 import * as Effectable from "effect/Effectable";
12 import * as Option from "effect/Option";
13 import * as Predicate from "effect/Predicate";
14 import * as EffectStream from "effect/Stream";
15 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
16 import type { Providers } from "../Providers.ts";
17 import type { ConsumedRecord, DecodedRecord, Record as K2Record, RecordSchema } from "./K2Types.ts";
18
19 const StreamTypeId = "Cloudflare.K2.Stream" as const;
20 type StreamTypeId = typeof StreamTypeId;
21
22 /** K2's default retention: seven days. */
23 const DEFAULT_RETENTION_SECONDS = 604_800;
24
25 /**
26 * HTTP input configuration of a K2 stream.
27 */
28 export interface StreamHttpInput {
29 /**
30 * Require an API token with the `K2 Produce` permission on `/produce`.
31 * When `false` the endpoint is public.
32 * @default true
33 */
34 authentication?: boolean;
35 /**
36 * Origins allowed to produce from a browser: `http(s)://host[:port]`
37 * without a path, or `*` alone. Up to five.
38 */
39 cors?: string[];
40 }
41
42 export interface StreamProps {
43 /**
44 * Name of the stream: 1 to 128 letters, numbers, or underscores, unique in
45 * the account (not case-sensitive). If omitted, a unique name is generated
46 * from the app, stage, and logical ID. Changing the name replaces the
47 * stream.
48 * @default ${app}_${id}_${stage}_${suffix}
49 */
50 name?: string;
51 /**
52 * How long records are retained, from one hour to 30 days. Rounded to whole
53 * seconds. Mutable in place.
54 * @default "7 days"
55 */
56 retention?: Duration.Input;
57 /**
58 * The stream's HTTP input (`POST https://<id>.k2.cloudflarestorage.com/produce`).
59 * `false` disables it, `true` enables it with token authentication, and an
60 * object enables it with the given settings. Mutable in place.
61 * @default false
62 */
63 http?: boolean | StreamHttpInput;
64 /**
65 * Whether Workers can produce to the stream through a `k2` binding
66 * (`Cloudflare.K2.WriteStream` with `WriteStreamBinding`). Mutable in place.
67 * At least one of `http` and `workerBinding` must be enabled.
68 * @default true
69 */
70 workerBinding?: boolean;
71 }
72
73 export interface StreamAttributes {
74 /** The stream ID: 32 lowercase hexadecimal characters. */
75 streamId: string;
76 /** The stream name (unique in the account). */
77 streamName: string;
78 /** The stream's HTTP endpoint, `https://<id>.k2.cloudflarestorage.com`. */
79 endpoint: string;
80 /** How long records are retained, in seconds. */
81 retentionSeconds: number;
82 /** Whether the HTTP input accepts records. */
83 httpEnabled: boolean;
84 /** Whether the HTTP input requires a `K2 Produce` API token. */
85 httpAuthentication: boolean;
86 /** Origins allowed to produce from a browser. */
87 corsOrigins: string[] | undefined;
88 /** Whether Workers can produce through a `k2` binding. */
89 workerBindingEnabled: boolean;
90 /** Account that owns the stream. */
91 accountId: string;
92 /** When the stream was created. */
93 createdAt: string;
94 /** When the stream was last modified. */
95 modifiedAt: string;
96 }
97
98 /**
99 * A K2 stream. `A` is the record type its producers send and its consumers
100 * decode — the Effect Schema's `Type` when the stream was declared with
101 * `schema`, unknown otherwise.
102 */
103 export interface Stream<A = unknown> extends Resource<
104 StreamTypeId,
105 StreamProps,
106 StreamAttributes,
107 never,
108 Providers
109 > {
110 /**
111 * The Effect Schema the stream was declared with, if any. Producers encode
112 * records with it and consumers decode them; it is never persisted, because
113 * K2 itself stores bytes.
114 */
115 readonly RecordSchema: RecordSchema<any> | undefined;
116 /** Phantom record type. */
117 readonly "~record"?: A;
118 }
119
120 /**
121 * The record a producer sends to a `Stream<A>`: the schema's type, or raw
122 * bytes plus headers ({@link K2Record}) for a stream without a schema.
123 */
124 export type StreamRecord<A> = unknown extends A ? K2Record : A;
125
126 /**
127 * The record a consumer receives from a `Stream<A>`: decoded into `value` for
128 * a stream with a schema, raw bytes otherwise.
129 */
130 export type StreamConsumedRecord<A> = unknown extends A ? ConsumedRecord : DecodedRecord<A>;
131
132 /** Props of a stream declared with an Effect Schema. */
133 export type StreamSchemaProps<S extends RecordSchema<any>> = PropsInput<StreamProps> & {
134 /**
135 * Encode every record as JSON with this schema on the way in, and decode
136 * it on the way out. A client-side codec only: K2 stores bytes, so
137 * changing the schema never updates or replaces the stream.
138 */
139 schema: S;
140 };
141
142 const StreamResource = Resource<Stream>(StreamTypeId);
143
144 /**
145 * The Stream constructor: the plain resource constructor plus an overload
146 * that types the stream's records from an Effect Schema `schema`.
147 */
148 export type StreamClass = {
149 <const S extends RecordSchema<any>>(
150 id: string,
151 props: StreamSchemaProps<S>,
152 ): Effect.Effect<Stream<S["Type"]>, never, Providers>;
153 } & ResourceClass<Stream>;
154
155 /** Split the client-side `schema` off the props the engine persists. */
156 const splitSchema = (props: unknown): { props: unknown; schema: RecordSchema<any> | undefined } => {
157 if (props === null || typeof props !== "object" || !("schema" in props)) {
158 return { props, schema: undefined };
159 }
160 const { schema, ...rest } = props as { schema?: RecordSchema<any> };
161 return { props: rest, schema };
162 };
163
164 const constructStream = (id: string, props: unknown) =>
165 Effect.gen(function* () {
166 let schema: RecordSchema<any> | undefined;
167 const capture = (split: { props: unknown; schema: RecordSchema<any> | undefined }) => {
168 schema = split.schema;
169 return split.props;
170 };
171 const persisted = Effect.isEffect(props)
172 ? // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- props are untyped; Effect-valued props are resolved by the engine
173 (props as Effect.Effect<unknown>).pipe(Effect.map((p) => capture(splitSchema(p))))
174 : capture(splitSchema(props));
175 const construct = StreamResource as unknown as (
176 id: string,
177 props: unknown,
178 ) => Effect.Effect<Stream, never, Providers>;
179 const stream = yield* construct(id, persisted);
180 (stream as { RecordSchema: RecordSchema<any> | undefined }).RecordSchema = schema;
181 return stream;
182 });
183
184 /**
185 * A Cloudflare K2 stream — a durable, ordered log of records. Producers
186 * append records over HTTP or from Workers through a `k2` binding;
187 * consumers read them through a {@link Subscription}, each with its own
188 * position in the stream.
189 *
190 * The name is fixed at creation (changing it replaces the stream);
191 * retention and the HTTP / Worker-binding inputs are mutable in place.
192 * ### Creating a Stream
193 * **Example:** Stream with default settings
194 * ```typescript
195 * // Worker-binding input enabled, HTTP input disabled, 7-day retention.
196 * const orders = yield* Cloudflare.K2.Stream("Orders");
197 * ```
198 *
199 * **Example:** Custom retention
200 * ```typescript
201 * const orders = yield* Cloudflare.K2.Stream("Orders", {
202 * retention: "30 days",
203 * });
204 * ```
205 *
206 * ### Typed Records
207 * **Example:** Stream with an Effect Schema
208 * ```typescript
209 * const Order = Schema.Struct({ orderId: Schema.String, amountCents: Schema.Number });
210 *
211 * // Producers send `Order`s; consumers receive them decoded in `record.value`.
212 * const orders = yield* Cloudflare.K2.Stream("Orders", { schema: Order });
213 * ```
214 *
215 * ### HTTP Input
216 * **Example:** Authenticated HTTP input
217 * ```typescript
218 * // POST records to orders.endpoint + "/produce" with a K2 Produce token.
219 * const orders = yield* Cloudflare.K2.Stream("Orders", {
220 * http: true,
221 * });
222 * ```
223 *
224 * **Example:** Public HTTP input for browsers
225 * ```typescript
226 * const clicks = yield* Cloudflare.K2.Stream("Clicks", {
227 * http: { authentication: false, cors: ["https://app.example.com"] },
228 * workerBinding: false,
229 * });
230 * ```
231 *
232 * ### Producing from a Worker
233 * **Example:** Send records through the Worker binding
234 * ```typescript
235 * export default Cloudflare.Worker(
236 * "Api",
237 * { main: import.meta.url },
238 * Effect.gen(function* () {
239 * const orders = yield* Cloudflare.K2.WriteStream(Orders);
240 * return {
241 * fetch: Effect.gen(function* () {
242 * yield* orders.send([{ content: JSON.stringify({ id: 1 }) }]);
243 * return HttpServerResponse.empty({ status: 202 });
244 * }),
245 * };
246 * }).pipe(Effect.provide(Cloudflare.K2.WriteStreamBinding)),
247 * );
248 * ```
249 *
250 * ### Consuming
251 * **Example:** A subscription reading from the start of the stream
252 * ```typescript
253 * const analytics = yield* Cloudflare.K2.Subscription("Analytics", {
254 * stream: orders,
255 * startAt: "earliest",
256 * });
257 * ```
258 *
259 * @see https://developers.cloudflare.com/k2/
260 *
261 * @resource
262 * @product K2
263 * @category Storage & Databases
264 */
265 export const Stream: StreamClass = Object.assign(
266 (...args: [id: string, props?: unknown] | [methods: object]) =>
267 typeof args[0] === "object"
268 ? Object.assign(Stream, args[0])
269 : constructStream(args[0], (args as [string, unknown])[1]),
270 StreamResource,
271 Effectable.Prototype({
272 label: `Resource<${StreamTypeId}>`,
273 evaluate: () => Effect.succeed((id: string, props: unknown) => constructStream(id, props)),
274 }),
275 ) as unknown as StreamClass;
276
277 /** Returns true if the given value is a K2 Stream resource. */
278 export const isStream = (value: unknown): value is Stream =>
279 Predicate.hasProperty(value, "Type") && value.Type === StreamTypeId;
280
281 export const StreamProvider = () =>
282 Provider.succeed(Stream, {
283 stables: ["streamId", "streamName", "endpoint", "accountId", "createdAt"],
284
285 diff: Effect.fn(function* ({ id, olds, news = {}, output }) {
286 const { accountId } = yield* yield* CloudflareEnvironment;
287 if (!isResolved(news)) return undefined;
288 if ((output?.accountId ?? accountId) !== accountId) {
289 return { action: "replace" } as const;
290 }
291 // A generated name is engine-owned: the deployed name stays
292 // authoritative. Only a different explicit name forces a replace.
293 const oldName = output?.streamName ?? (yield* streamName(id, olds?.name));
294 const newName = news.name ?? oldName;
295 if (newName.toLowerCase() !== oldName.toLowerCase()) {
296 return { action: "replace" } as const;
297 }
298 return undefined;
299 }),
300
301 read: Effect.fn(function* ({ id, output, olds }) {
302 const { accountId } = yield* yield* CloudflareEnvironment;
303 const acct = output?.accountId ?? accountId;
304 if (output?.streamId) {
305 const observed = yield* getStream(acct, output.streamId);
306 if (observed) return toAttributes(observed, acct);
307 }
308 // Cold read: names are unique per account. A generated name embeds the
309 // instance id (proof of ownership); an explicit name does not, so gate
310 // takeover behind the adopt policy.
311 const name = yield* streamName(id, olds?.name);
312 const match = yield* findStreamByName(acct, name);
313 if (match) {
314 const attrs = toAttributes(match, acct);
315 return olds?.name !== undefined ? Unowned(attrs) : attrs;
316 }
317 return undefined;
318 }),
319
320 reconcile: Effect.fn(function* ({ id, news = {}, output }) {
321 const { accountId } = yield* yield* CloudflareEnvironment;
322 const acct = output?.accountId ?? accountId;
323 const name = output?.streamName ?? (yield* streamName(id, news.name));
324 const desired = desiredState(news);
325
326 // Observe — the cached id is a hint; fall back to the name.
327 let observed = output?.streamId ? yield* getStream(acct, output.streamId) : undefined;
328 if (!observed) {
329 observed = yield* findStreamByName(acct, name);
330 }
331
332 // Ensure — create when missing. A taken name is a race or a lost state
333 // write: adopt the stream with that name.
334 if (!observed) {
335 observed = yield* k2
336 .createStream({
337 accountId: acct,
338 name,
339 retentionSeconds: desired.retentionSeconds,
340 http: desired.http,
341 workerBinding: desired.workerBinding,
342 })
343 .pipe(
344 Effect.catchTag("K2NameAlreadyExists", (error) =>
345 findStreamByName(acct, name).pipe(
346 Effect.flatMap((match) => (match ? Effect.succeed(match) : Effect.fail(error))),
347 ),
348 ),
349 );
350 }
351
352 // Sync — diff observed cloud state against desired and PATCH only the
353 // delta. A provided input object replaces the existing one.
354 const patch: k2.UpdateStreamRequest = { accountId: acct, streamId: observed.id };
355 let dirty = false;
356 if (observed.retentionSeconds !== desired.retentionSeconds) {
357 patch.retentionSeconds = desired.retentionSeconds;
358 dirty = true;
359 }
360 if (!sameHttp(desired.http, observed.http)) {
361 // An omitted `cors` keeps the existing origins; clear them explicitly.
362 patch.http =
363 desired.http.enabled && !desired.http.cors && observed.http.cors?.origins?.length
364 ? { ...desired.http, cors: { origins: [] } }
365 : desired.http;
366 dirty = true;
367 }
368 if (observed.workerBinding.enabled !== desired.workerBinding.enabled) {
369 patch.workerBinding = desired.workerBinding;
370 dirty = true;
371 }
372 if (dirty) {
373 observed = yield* k2.updateStream(patch);
374 }
375
376 return toAttributes(observed, acct);
377 }),
378
379 delete: Effect.fn(function* ({ output }) {
380 // Deleting a stream that does not exist succeeds.
381 yield* k2.deleteStream({ accountId: output.accountId, streamId: output.streamId });
382 }),
383
384 list: Effect.fn(function* () {
385 const { accountId } = yield* yield* CloudflareEnvironment;
386 return yield* k2.listStreams.items({ accountId }).pipe(
387 EffectStream.runCollect,
388 Effect.map((chunk) => Array.from(chunk).map((s) => toAttributes(s, accountId))),
389 );
390 }),
391 });
392
393 /** The stream state shared by the get/list/create/update responses. */
394 interface ObservedStream {
395 id: string;
396 name: string;
397 retentionSeconds: number;
398 endpoint: string;
399 http: k2.StreamHttpInput;
400 workerBinding: k2.StreamWorkerBindingInput;
401 createdAt: string;
402 modifiedAt: string;
403 }
404
405 /**
406 * Stream names allow letters, numbers, and underscores only, so swap the
407 * default hyphen delimiter for underscores.
408 */
409 const streamName = (id: string, name: string | undefined) =>
410 Effect.gen(function* () {
411 if (name) return name;
412 const generated = yield* createPhysicalName({
413 id,
414 lowercase: true,
415 delimiter: "_",
416 maxLength: 128,
417 });
418 return generated.replaceAll(/[^a-zA-Z0-9_]/g, "_");
419 });
420
421 const getStream = (accountId: string, streamId: string) =>
422 k2.getStream({ accountId, streamId }).pipe(
423 Effect.map((s): ObservedStream | undefined => s),
424 Effect.catchTag("K2StreamNotFound", () => Effect.undefined),
425 );
426
427 /** Names are unique per account and not case-sensitive. */
428 const findStreamByName = (accountId: string, name: string) =>
429 k2.listStreams.items({ accountId }).pipe(
430 EffectStream.filter((s) => s.name.toLowerCase() === name.toLowerCase()),
431 EffectStream.runHead,
432 Effect.map((match): ObservedStream | undefined => Option.getOrUndefined(match)),
433 );
434
435 const desiredState = (props: StreamProps) => {
436 const http: k2.StreamHttpInput =
437 props.http === undefined || props.http === false
438 ? { enabled: false }
439 : props.http === true
440 ? { enabled: true, authentication: true }
441 : {
442 enabled: true,
443 authentication: props.http.authentication ?? true,
444 ...(props.http.cors ? { cors: { origins: props.http.cors } } : {}),
445 };
446 return {
447 retentionSeconds: toWireSeconds(props.retention) ?? DEFAULT_RETENTION_SECONDS,
448 http,
449 workerBinding: { enabled: props.workerBinding ?? true },
450 };
451 };
452
453 const sameHttp = (desired: k2.StreamHttpInput, observed: k2.StreamHttpInput) => {
454 if (!desired.enabled && !observed.enabled) return true;
455 if (desired.enabled !== observed.enabled) return false;
456 if ((desired.authentication ?? false) !== (observed.authentication ?? false)) return false;
457 const want = [...(desired.cors?.origins ?? [])].sort().join(",");
458 const have = [...(observed.cors?.origins ?? [])].sort().join(",");
459 return want === have;
460 };
461
462 const toAttributes = (observed: ObservedStream, accountId: string): StreamAttributes => ({
463 streamId: observed.id,
464 streamName: observed.name,
465 endpoint: observed.endpoint,
466 retentionSeconds: observed.retentionSeconds,
467 httpEnabled: observed.http.enabled,
468 httpAuthentication: observed.http.authentication ?? false,
469 corsOrigins: observed.http.cors?.origins ? [...observed.http.cors.origins] : undefined,
470 workerBindingEnabled: observed.workerBinding.enabled,
471 accountId,
472 createdAt: observed.createdAt,
473 modifiedAt: observed.modifiedAt,
474 });