The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import * as Binding from "alchemy/Binding"; |
| 2 | import * as Namespace from "alchemy/Namespace"; |
| 3 | import { ServerHost } from "alchemy/Runtime/Process"; |
| 4 | import type { RuntimeContext } from "alchemy/RuntimeContext"; |
| 5 | import * as Cause from "effect/Cause"; |
| 6 | import type * as Duration from "effect/Duration"; |
| 7 | import * as Effect from "effect/Effect"; |
| 8 | import * as Exit from "effect/Exit"; |
| 9 | import * as Layer from "effect/Layer"; |
| 10 | import * as Option from "effect/Option"; |
| 11 | import * as Schedule from "effect/Schedule"; |
| 12 | import * as Stream from "effect/Stream"; |
| 13 | import { decodeWithSchema } from "./K2Codec.ts"; |
| 14 | import type { Batch, ConsumedRecord, K2SchemaError } from "./K2Types.ts"; |
| 15 | import { ReadSubscription, type ReadSubscriptionClient } from "./ReadSubscription.ts"; |
| 16 | import type { Stream as K2Stream } from "./Stream.ts"; |
| 17 | import { |
| 18 | StreamEventSource, |
| 19 | type ConsumeStreamRecordsProps, |
| 20 | type ConsumeStreamRecordsHandler, |
| 21 | type StreamEventSourceService, |
| 22 | } from "./StreamEventSource.ts"; |
| 23 | import { Subscription } from "./Subscription.ts"; |
| 24 | |
| 25 | /** |
| 26 | * Polling implementation of {@link StreamEventSource} for hosts with a |
| 27 | * long-lived process (any host providing `ServerHost`: Fly, ECS, EC2, |
| 28 | * Railway, Hetzner, Docker). Requires a `ReadSubscription` implementation. |
| 29 | * |
| 30 | * :::note |
| 31 | * TODO: Workers cannot consume K2 yet — K2 has no push consumers (they are |
| 32 | * on Cloudflare's roadmap), so no Worker layer ships. |
| 33 | * ::: |
| 34 | * ### Providing the Layer |
| 35 | * **Example:** Poll with a scoped token |
| 36 | * ```typescript |
| 37 | * Effect.gen(function* () { |
| 38 | * yield* Cloudflare.K2.consumeStreamRecords(Orders, handler); |
| 39 | * }).pipe( |
| 40 | * Effect.provide( |
| 41 | * Layer.provideMerge( |
| 42 | * Cloudflare.K2.StreamEventSourcePolling, |
| 43 | * Cloudflare.K2.ReadSubscriptionHttp, |
| 44 | * ), |
| 45 | * ), |
| 46 | * ); |
| 47 | * ``` |
| 48 | * |
| 49 | * @layer |
| 50 | * @provides Cloudflare.K2.StreamEventSource |
| 51 | * @product K2 |
| 52 | * @category Storage & Databases |
| 53 | */ |
| 54 | export const StreamEventSourcePolling = Layer.effect( |
| 55 | StreamEventSource, |
| 56 | Effect.gen(function* () { |
| 57 | const { run } = yield* ServerHost; |
| 58 | const readSubscription = yield* ReadSubscription; |
| 59 | |
| 60 | return Effect.fn(function* ( |
| 61 | stream: K2Stream<any>, |
| 62 | props: ConsumeStreamRecordsProps, |
| 63 | process: ConsumeStreamRecordsHandler<any, any>, |
| 64 | ) { |
| 65 | const host = yield* Binding.Host; |
| 66 | const hostId = host?.LogicalId ?? "Host"; |
| 67 | // Declared in both phases: at runtime the declaration resolves to the |
| 68 | // deployed subscription's outputs, which the client reads. |
| 69 | const subscription = |
| 70 | props.subscription ?? |
| 71 | (yield* Namespace.push( |
| 72 | hostId, |
| 73 | Subscription(`${stream.LogicalId}Subscription`, { |
| 74 | stream, |
| 75 | startAt: props.startAt, |
| 76 | }), |
| 77 | )); |
| 78 | const client = yield* readSubscription(subscription); |
| 79 | const decode = stream.RecordSchema |
| 80 | ? decodeWithSchema(stream.RecordSchema) |
| 81 | : (records: ReadonlyArray<ConsumedRecord>) => Effect.succeed(records); |
| 82 | |
| 83 | yield* run( |
| 84 | Effect.gen(function* () { |
| 85 | const workerId = |
| 86 | props.workerId ?? |
| 87 | `${hostId}-${(yield* Effect.sync(() => crypto.randomUUID())).slice(0, 8)}`; |
| 88 | yield* pollSubscription({ |
| 89 | client, |
| 90 | workerId, |
| 91 | maxRecords: props.maxRecords, |
| 92 | idleBackoff: props.idleBackoff, |
| 93 | concurrency: props.concurrency, |
| 94 | decode, |
| 95 | process, |
| 96 | }); |
| 97 | }), |
| 98 | ); |
| 99 | }) as StreamEventSourceService; |
| 100 | }), |
| 101 | ); |
| 102 | |
| 103 | // ---- the pull loop ----------------------------------------------------------- |
| 104 | |
| 105 | /** `consume` errors that mean "try again", not "give up". */ |
| 106 | const RETRYABLE_CONSUME_ERRORS: ReadonlyArray<string> = [ |
| 107 | "K2Unavailable", |
| 108 | "K2ReadFailed", |
| 109 | "K2LeasesExhausted", |
| 110 | "K2BatchPending", |
| 111 | ]; |
| 112 | |
| 113 | /** Bounded backoff for retryable `consume` errors: ~30 s in total. */ |
| 114 | const consumeRetry = Schedule.max([ |
| 115 | Schedule.min([Schedule.exponential("250 millis"), Schedule.spaced("5 seconds")]), |
| 116 | Schedule.recurs(8), |
| 117 | ]); |
| 118 | |
| 119 | interface PollOptions<A, Req> { |
| 120 | client: ReadSubscriptionClient; |
| 121 | /** Worker id holding the leases. Must be unique per concurrent poller. */ |
| 122 | workerId: string; |
| 123 | /** @default 100 */ |
| 124 | maxRecords?: number; |
| 125 | /** Sleep after an empty batch or a failed iteration. @default "1 second" */ |
| 126 | idleBackoff?: Duration.Input; |
| 127 | /** Extend the five-minute lease this often while the handler runs. @default "2 minutes" */ |
| 128 | extendEvery?: Duration.Input; |
| 129 | /** Turn consumed records into the handler's elements (e.g. schema decode). */ |
| 130 | decode: ( |
| 131 | records: ReadonlyArray<ConsumedRecord>, |
| 132 | ) => Effect.Effect<ReadonlyArray<A>, K2SchemaError>; |
| 133 | process: (records: Stream.Stream<A>) => Effect.Effect<void, unknown, Req>; |
| 134 | } |
| 135 | |
| 136 | /** |
| 137 | * Keep a batch's lease alive while its handler runs. Stops on `K2LeaseLost` |
| 138 | * (the batch was acked, nacked, or redelivered elsewhere). |
| 139 | */ |
| 140 | const keepLeaseAlive = (client: ReadSubscriptionClient, batch: Batch, every: Duration.Input) => |
| 141 | Effect.sleep(every).pipe( |
| 142 | Effect.andThen(client.extend(batch)), |
| 143 | Effect.forever, |
| 144 | Effect.catchTag("K2LeaseLost", () => |
| 145 | Effect.logWarning(`K2 lease lost for batch ${batch.batchId}; it may be redelivered`), |
| 146 | ), |
| 147 | Effect.catchCause((cause) => |
| 148 | Effect.logWarning(`K2 lease extension failed for batch ${batch.batchId}`, cause), |
| 149 | ), |
| 150 | ); |
| 151 | |
| 152 | /** |
| 153 | * One poll: lease a batch, run the handler, then ack it on success or nack |
| 154 | * it on failure. Returns whether a batch was processed. |
| 155 | */ |
| 156 | const pollOnce = <A, Req>( |
| 157 | options: PollOptions<A, Req>, |
| 158 | ): Effect.Effect<boolean, unknown, Req | RuntimeContext> => |
| 159 | Effect.gen(function* () { |
| 160 | const { client } = options; |
| 161 | const leased = yield* client |
| 162 | .consume({ workerId: options.workerId, maxRecords: options.maxRecords }) |
| 163 | .pipe( |
| 164 | Effect.retry({ |
| 165 | while: (e) => RETRYABLE_CONSUME_ERRORS.includes(e._tag), |
| 166 | schedule: consumeRetry, |
| 167 | }), |
| 168 | ); |
| 169 | if (Option.isNone(leased)) return false; |
| 170 | const batch = leased.value; |
| 171 | |
| 172 | const outcome = yield* Effect.scoped( |
| 173 | Effect.gen(function* () { |
| 174 | yield* Effect.forkScoped(keepLeaseAlive(client, batch, options.extendEvery ?? "2 minutes")); |
| 175 | return yield* Effect.exit( |
| 176 | options |
| 177 | .decode(batch.records) |
| 178 | .pipe(Effect.flatMap((values) => options.process(Stream.fromIterable(values)))), |
| 179 | ); |
| 180 | }), |
| 181 | ); |
| 182 | |
| 183 | if (Exit.isSuccess(outcome)) { |
| 184 | yield* client.ack(batch); |
| 185 | } else { |
| 186 | yield* Effect.logWarning( |
| 187 | `K2 handler failed for batch ${batch.batchId}; releasing it for redelivery`, |
| 188 | Cause.pretty(outcome.cause), |
| 189 | ); |
| 190 | yield* client.nack(batch); |
| 191 | } |
| 192 | return true; |
| 193 | }); |
| 194 | |
| 195 | /** |
| 196 | * Poll forever: an empty batch or a failed iteration sleeps `idleBackoff`; |
| 197 | * a processed batch polls again immediately. Never fails. |
| 198 | */ |
| 199 | const pollForever = <A, Req>( |
| 200 | options: PollOptions<A, Req>, |
| 201 | ): Effect.Effect<never, never, Req | RuntimeContext> => |
| 202 | pollOnce(options).pipe( |
| 203 | Effect.catchCause((cause) => |
| 204 | Effect.logWarning(`K2 poll failed for worker ${options.workerId}`, cause).pipe( |
| 205 | Effect.as(false), |
| 206 | ), |
| 207 | ), |
| 208 | Effect.flatMap((processed) => |
| 209 | processed ? Effect.void : Effect.sleep(options.idleBackoff ?? "1 second"), |
| 210 | ), |
| 211 | Effect.forever, |
| 212 | ); |
| 213 | |
| 214 | /** Run `concurrency` pollers, each with its own worker id (`${workerId}-${i}`). */ |
| 215 | const pollSubscription = <A, Req>( |
| 216 | options: PollOptions<A, Req> & { concurrency?: number }, |
| 217 | ): Effect.Effect<void, never, Req | RuntimeContext> => |
| 218 | Effect.forEach( |
| 219 | Array.from({ length: Math.max(1, options.concurrency ?? 1) }, (_, i) => i), |
| 220 | (i) => pollForever({ ...options, workerId: `${options.workerId}-${i}` }), |
| 221 | { concurrency: "unbounded", discard: true }, |
| 222 | ); |