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

main
ts 85 lines 2.98 KB
Raw
1 import * as Binding from "alchemy/Binding";
2 import type { RuntimeContext } from "alchemy/RuntimeContext";
3 import type * as Effect from "effect/Effect";
4 import type * as Option from "effect/Option";
5 import type { AckError, Batch, ConsumeError, ExtendError, NackError } from "./K2Types.ts";
6 import type { Subscription } from "./Subscription.ts";
7
8 /** Options for {@link ReadSubscriptionClient.consume}. */
9 export interface ConsumeOptions {
10 /**
11 * The consumer requesting the lease, 1 to 256 characters. A worker that
12 * already holds a lease gets the same batch back. Use a distinct id per
13 * concurrent consumer.
14 */
15 workerId: string;
16 /**
17 * At most this many records, from 1 to 10000.
18 * @default 100
19 */
20 maxRecords?: number;
21 }
22
23 /**
24 * Binding service that turns a K2 {@link Subscription} into a pull client:
25 * lease a batch of records, then acknowledge it (advance the subscription),
26 * nack it (redeliver), or extend its five-minute lease.
27 *
28 * The native `k2` Worker binding can only produce, so this service ships
29 * HTTP implementations only: {@link ReadSubscriptionHttp} (scoped
30 * `K2 Consume` token) and {@link ReadSubscriptionLocal} (current
31 * credentials). For a long-running consumer loop, see
32 * `consumeStreamRecords`.
33 * ### Pulling Records
34 * **Example:** Lease, process, and acknowledge a batch
35 * ```typescript
36 * const inbox = yield* Cloudflare.K2.ReadSubscription(Analytics);
37 *
38 * const batch = yield* inbox.consume({ workerId: "worker-1", maxRecords: 100 });
39 * if (Option.isSome(batch)) {
40 * yield* Effect.forEach(batch.value.records, (record) =>
41 * Effect.log(new TextDecoder().decode(record.content)),
42 * );
43 * yield* inbox.ack(batch.value);
44 * }
45 * ```
46 *
47 * ### Redelivery
48 * **Example:** Release a batch for redelivery
49 * ```typescript
50 * yield* process(batch.records).pipe(
51 * Effect.andThen(inbox.ack(batch)),
52 * Effect.catch(() => inbox.nack(batch)),
53 * );
54 * ```
55 *
56 * @binding
57 * @product K2
58 * @category Storage & Databases
59 */
60 export interface ReadSubscription extends Binding.Service<
61 ReadSubscription,
62 "Cloudflare.K2.ReadSubscription",
63 (subscription: Subscription) => Effect.Effect<ReadSubscriptionClient>
64 > {}
65
66 export const ReadSubscription = Binding.Service<ReadSubscription>("Cloudflare.K2.ReadSubscription");
67
68 export interface ReadSubscriptionClient {
69 /**
70 * Lease the next batch of records for five minutes. `None` when there are
71 * no records to read.
72 */
73 consume(
74 options: ConsumeOptions,
75 ): Effect.Effect<Option.Option<Batch>, ConsumeError, RuntimeContext>;
76 /** Mark a batch processed and release its lease. Acknowledging twice succeeds. */
77 ack(batch: Batch): Effect.Effect<void, AckError, RuntimeContext>;
78 /** Release a batch for redelivery (under a new batch id). */
79 nack(batch: Batch): Effect.Effect<void, NackError, RuntimeContext>;
80 /**
81 * Extend a held lease to five minutes from now. Fails with `K2LeaseLost`
82 * when the worker no longer holds it.
83 */
84 extend(batch: Batch): Effect.Effect<Batch, ExtendError, RuntimeContext>;
85 }