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
| 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 | } |