@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, 06:00 UTC

main
ts 172 lines 6.47 KB
Raw
1 import type { NonEmptyReadonlyArray } from "effect/Array";
2 import * as Data from "effect/Data";
3 import * as Effect from "effect/Effect";
4 import * as Ref from "effect/Ref";
5 import * as Schedule from "effect/Schedule";
6 import * as Sink from "effect/Sink";
7
8 /**
9 * Raised when a batch API keeps reporting entries as unprocessed after the
10 * bounded retry schedule is exhausted. Carries the stranded entries (in input
11 * order) so callers can decide what to do with them (DLQ, die, drop).
12 */
13 export class BatchRetryExhaustedError<In> extends Data.TaggedError("BatchRetryExhaustedError")<{
14 /** The entries that were still unprocessed when retries ran out, in input order. */
15 readonly entries: readonly In[];
16 }> {}
17
18 export interface BatchedSinkOptions<In, Out, Err> {
19 /**
20 * API max records per call (10 for SQS `SendMessageBatch` / SNS
21 * `PublishBatch`, 25 for `BatchWriteItem`, 500 for Kinesis `PutRecords`,
22 * 500 for Firehose, 10 for EventBridge, ...).
23 */
24 readonly maxRecords: number;
25 /** API max payload bytes per call; entries are greedily packed. */
26 readonly maxBytes?: number;
27 /** Approximate wire size of one record; required for `maxBytes` packing. */
28 readonly sizeOf?: (record: In) => number;
29 /** One API call per packed batch. Receives entries in input order. */
30 readonly send: (batch: readonly In[]) => Effect.Effect<Out, Err>;
31 /**
32 * Extract entries the API reports as *transiently* unprocessed (returned in
33 * input order). These are re-submitted on the bounded `retrySchedule`.
34 */
35 readonly unprocessed?: (out: Out, batch: readonly In[]) => readonly In[];
36 /**
37 * Extract entries the API reports as *permanently* rejected (returned in
38 * input order). Distinct from `unprocessed`: rejected entries are never
39 * retried — they are dropped and surfaced via `onRejected`.
40 */
41 readonly rejected?: (out: Out, batch: readonly In[]) => readonly In[];
42 /**
43 * Invoked with permanently-rejected entries before they are dropped.
44 * @default logs a warning with the rejected entry count
45 */
46 readonly onRejected?: (entries: readonly In[]) => Effect.Effect<void>;
47 /**
48 * Bounded retry for the unprocessed subset.
49 * @default Schedule.recurs(5) ∩ Schedule.exponential("200 millis")
50 */
51 readonly retrySchedule?: Schedule.Schedule<unknown>;
52 }
53
54 /**
55 * The shared engine behind every AWS batch-API sink (`SQS.QueueSink`,
56 * `SNS.TopicSink`, `Kinesis.StreamSink`, ...).
57 *
58 * Semantics:
59 * - each upstream chunk is split into `<= maxRecords` / `<= maxBytes` batches
60 * **preserving input order**;
61 * - batches are sent **sequentially** (order-preservation is the default);
62 * - after each `send`, the `rejected` subset is surfaced via `onRejected` and
63 * dropped, and the `unprocessed` subset is re-submitted (in order) on the
64 * bounded `retrySchedule`;
65 * - exhausting retries fails the sink with a typed
66 * {@link BatchRetryExhaustedError} carrying the stranded entries.
67 *
68 * Internal — NOT exported from the `AWS` barrel.
69 */
70 export const makeBatchedSink = <In, Out, Err>(
71 options: BatchedSinkOptions<In, Out, Err>,
72 ): Sink.Sink<void, In, never, Err | BatchRetryExhaustedError<In>> => {
73 const schedule =
74 options.retrySchedule ?? Schedule.max([Schedule.recurs(5), Schedule.exponential("200 millis")]);
75
76 const onRejected =
77 options.onRejected ??
78 ((entries: readonly In[]) =>
79 Effect.logWarning(
80 `BatchedSink dropped ${entries.length} permanently rejected entr${
81 entries.length === 1 ? "y" : "ies"
82 }`,
83 ));
84
85 // One attempt over the currently-pending subset. Returns the entries that
86 // are still unprocessed after this attempt (empty = converged).
87 const attempt = (pendingRef: Ref.Ref<readonly In[]>): Effect.Effect<readonly In[], Err> =>
88 Effect.gen(function* () {
89 const pending = yield* Ref.get(pendingRef);
90 if (pending.length === 0) {
91 return pending;
92 }
93 const out = yield* options.send(pending);
94 const rejected = options.rejected?.(out, pending) ?? [];
95 if (rejected.length > 0) {
96 yield* onRejected(rejected);
97 }
98 const remaining = options.unprocessed?.(out, pending) ?? [];
99 yield* Ref.set(pendingRef, remaining);
100 return remaining;
101 });
102
103 const flushBatch = (
104 batch: readonly In[],
105 ): Effect.Effect<void, Err | BatchRetryExhaustedError<In>> =>
106 Effect.gen(function* () {
107 const pendingRef = yield* Ref.make(batch);
108 yield* repeatWhilePending(attempt(pendingRef), schedule);
109 const stranded = yield* Ref.get(pendingRef);
110 if (stranded.length > 0) {
111 return yield* new BatchRetryExhaustedError({ entries: stranded });
112 }
113 });
114
115 return Sink.forEachArray((chunk: NonEmptyReadonlyArray<In>) =>
116 Effect.gen(function* () {
117 const batches = yield* Effect.sync(() => packBatches(chunk, options));
118 yield* Effect.forEach(batches, flushBatch, { discard: true });
119 }),
120 );
121 };
122
123 /**
124 * Re-runs `step` (which re-submits the pending subset) on the bounded
125 * schedule until it reports nothing left to send.
126 *
127 * Extracted with an explicit return type so `Repeat.Return`'s conditional
128 * type never leaks into declaration emit (see PATTERNS §7 on inlined
129 * retry/repeat poisoning `.d.ts` inference).
130 */
131 const repeatWhilePending = <In, Err>(
132 step: Effect.Effect<readonly In[], Err>,
133 schedule: Schedule.Schedule<unknown>,
134 ): Effect.Effect<readonly In[], Err> =>
135 Effect.repeat(step, {
136 schedule,
137 until: (remaining: readonly In[]) => remaining.length === 0,
138 });
139
140 /** Greedily pack a chunk into `<= maxRecords` / `<= maxBytes` batches, preserving order. */
141 const packBatches = <In>(
142 chunk: NonEmptyReadonlyArray<In>,
143 options: {
144 readonly maxRecords: number;
145 readonly maxBytes?: number;
146 readonly sizeOf?: (record: In) => number;
147 },
148 ): readonly (readonly In[])[] => {
149 const { maxBytes, maxRecords, sizeOf } = options;
150 const batches: In[][] = [];
151 let current: In[] = [];
152 let currentBytes = 0;
153 for (const record of chunk) {
154 const size = sizeOf?.(record) ?? 0;
155 const overRecords = current.length >= maxRecords;
156 const overBytes =
157 maxBytes !== undefined && current.length > 0 && currentBytes + size > maxBytes;
158 if (overRecords || overBytes) {
159 batches.push(current);
160 current = [];
161 currentBytes = 0;
162 }
163 // A single record larger than maxBytes still ships alone; the API
164 // rejects it and the error surfaces through the sink's error channel.
165 current.push(record);
166 currentBytes += size;
167 }
168 if (current.length > 0) {
169 batches.push(current);
170 }
171 return batches;
172 };