@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 158 lines 5.23 KB
Raw
1 import * as Context from "effect/Context";
2 import type * as Duration from "effect/Duration";
3 import * as Effect from "effect/Effect";
4 import type * as Stream from "effect/Stream";
5 import type { StartAt } from "./K2Types.ts";
6 import type { Stream as K2Stream, StreamConsumedRecord } from "./Stream.ts";
7 import type { Subscription } from "./Subscription.ts";
8
9 /** Settings for {@link consumeStreamRecords}. */
10 export interface ConsumeStreamRecordsProps {
11 /**
12 * Read through this subscription. Hosts sharing one subscription compete
13 * for batches. When omitted, a subscription owned by the consuming host is
14 * created, so every host reads every record.
15 */
16 subscription?: Subscription;
17 /**
18 * Where the auto-created subscription starts reading. Ignored when
19 * `subscription` is passed.
20 * @default "latest"
21 */
22 startAt?: StartAt;
23 /**
24 * At most this many records per batch, from 1 to 10000.
25 * @default 100
26 */
27 maxRecords?: number;
28 /**
29 * Number of concurrent pollers in this process, each with its own worker
30 * id (and lease).
31 * @default 1
32 */
33 concurrency?: number;
34 /**
35 * How long to wait after an empty batch (or a failed poll) before polling
36 * again.
37 * @default "1 second"
38 */
39 idleBackoff?: Duration.Input;
40 /**
41 * Prefix of the pollers' worker ids. Must be unique per process.
42 * @default `${hostLogicalId}-${random}`
43 */
44 workerId?: string;
45 }
46
47 export type ConsumeStreamRecordsHandler<Rec, Req> = (
48 records: Stream.Stream<Rec>,
49 ) => Effect.Effect<void, unknown, Req>;
50
51 export type StreamEventSourceService = (
52 stream: K2Stream<any>,
53 props: ConsumeStreamRecordsProps,
54 process: ConsumeStreamRecordsHandler<any, any>,
55 ) => Effect.Effect<void, never, never>;
56
57 /**
58 * Event source connecting a K2 {@link Stream} to the hosting compute. The
59 * only implementation is {@link StreamEventSourcePolling}, a pull loop for
60 * long-running hosts. Consume it through {@link consumeStreamRecords}.
61 *
62 * :::note
63 * TODO: Workers cannot consume K2 yet — K2 has no push consumers (they are
64 * on Cloudflare's roadmap), so no Worker layer ships.
65 * :::
66 */
67 export class StreamEventSource extends Context.Service<
68 StreamEventSource,
69 StreamEventSourceService
70 >()("Cloudflare.K2.StreamEventSource") {}
71
72 /**
73 * Subscribe a long-running host to a K2 stream with an Effect stream
74 * handler.
75 *
76 * - **Deploy-time**: creates a {@link Subscription} owned by the host
77 * (unless `subscription` is passed — hosts sharing one compete for
78 * batches).
79 * - **Runtime**: `concurrency` pollers lease batches of records, run the
80 * handler, and acknowledge each batch when the handler succeeds. When the
81 * stream was declared with a `schema`, each record's JSON content is
82 * decoded into `record.value`. A failed
83 * handler is logged and the batch is released for redelivery. Leases are
84 * extended every two minutes while the handler runs.
85 *
86 * Provide {@link StreamEventSourcePolling} together with a
87 * `ReadSubscription` implementation (`ReadSubscriptionHttp` on a deployed
88 * host). It runs on hosts with a long-lived process — Fly, ECS, EC2,
89 * Railway, Hetzner, Docker.
90 *
91 * :::note
92 * TODO: Workers cannot consume K2 yet — K2 has no push consumers (they are
93 * on Cloudflare's roadmap), so no Worker layer ships.
94 * :::
95 * ### Consuming a Stream
96 * **Example:** Log every record
97 * ```typescript
98 * yield* Cloudflare.K2.consumeStreamRecords(Orders, (records) =>
99 * records.pipe(
100 * Stream.runForEach((record) =>
101 * Effect.log(new TextDecoder().decode(record.content)),
102 * ),
103 * ),
104 * );
105 * ```
106 *
107 * ### Typed Records
108 * **Example:** Records decoded with the stream's schema
109 * ```typescript
110 * const Orders = Cloudflare.K2.Stream("Orders", { schema: Order });
111 *
112 * yield* Cloudflare.K2.consumeStreamRecords(
113 * Orders,
114 * { startAt: "earliest", concurrency: 4 },
115 * (records) =>
116 * records.pipe(Stream.runForEach((record) => Effect.log(record.value.id))),
117 * );
118 * ```
119 *
120 * ### Providing the Layers
121 * **Example:** Poll from a container host
122 * ```typescript
123 * Effect.gen(function* () {
124 * yield* Cloudflare.K2.consumeStreamRecords(Orders, handler);
125 * }).pipe(
126 * Effect.provide(
127 * Layer.provideMerge(
128 * Cloudflare.K2.StreamEventSourcePolling,
129 * Cloudflare.K2.ReadSubscriptionHttp,
130 * ),
131 * ),
132 * );
133 * ```
134 *
135 * @binding
136 * @product K2
137 * @category Storage & Databases
138 */
139 export function consumeStreamRecords<A, Req = never>(
140 stream: K2Stream<A>,
141 process: ConsumeStreamRecordsHandler<StreamConsumedRecord<A>, Req>,
142 ): Effect.Effect<void, never, StreamEventSource>;
143 export function consumeStreamRecords<A, Req = never>(
144 stream: K2Stream<A>,
145 props: ConsumeStreamRecordsProps,
146 process: ConsumeStreamRecordsHandler<StreamConsumedRecord<A>, Req>,
147 ): Effect.Effect<void, never, StreamEventSource>;
148 export function consumeStreamRecords(
149 stream: K2Stream<any>,
150 propsOrProcess: ConsumeStreamRecordsProps | ConsumeStreamRecordsHandler<any, any>,
151 maybeProcess?: ConsumeStreamRecordsHandler<any, any>,
152 ): Effect.Effect<void, never, StreamEventSource> {
153 const [props, process] =
154 typeof propsOrProcess === "function"
155 ? [{} as ConsumeStreamRecordsProps, propsOrProcess]
156 : [propsOrProcess, maybeProcess!];
157 return StreamEventSource.use((source) => source(stream, props, process));
158 }