The best way to control Claude Code, Codex and more from any computer or phone
| 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 | }); |