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

main
ts 282 lines 9.66 KB
Raw
1 import * as kv from "@distilled.cloud/aws/kinesis-video";
2 import * as Data from "effect/Data";
3 import * as Effect from "effect/Effect";
4 import * as Schedule from "effect/Schedule";
5
6 /**
7 * Raised when a Kinesis Video stream or signaling channel fails to reach
8 * `ACTIVE` within the bounded polling budget after a create/update.
9 */
10 export class KinesisVideoNotConverged extends Data.TaggedError("KinesisVideoNotConverged")<{
11 readonly resource: string;
12 readonly status: string | undefined;
13 }> {}
14
15 /**
16 * Raised when `GetSignalingChannelEndpoint` returns no endpoint for the
17 * requested protocol.
18 */
19 export class SignalingEndpointUnavailable extends Data.TaggedError("SignalingEndpointUnavailable")<{
20 readonly channelArn: string;
21 readonly protocol: string;
22 }> {}
23
24 /**
25 * Bounded retry through transient `ResourceInUseException` states — e.g.
26 * deleting a stream or channel that is still `CREATING`/`UPDATING`, or
27 * re-creating one whose previous incarnation is still `DELETING`.
28 *
29 * Expressed as an explicitly-typed module-scope helper: inlining
30 * `Effect.retry` in lifecycle code leaves its conditional return type
31 * unresolved in the provider's declaration emit, which widens the
32 * `AWS.providers()` layer type for every downstream consumer.
33 */
34 export const retryWhileResourceInUse = <A, E extends { _tag: string }, R>(
35 self: Effect.Effect<A, E, R>,
36 ): Effect.Effect<A, E, R> =>
37 Effect.retry(self, {
38 while: (e) => e._tag === "ResourceInUseException",
39 schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(30)]),
40 });
41
42 /**
43 * Bounded retry through the transient states a mutation can hit while a
44 * previous async transition settles: `ResourceInUseException` and the
45 * synthetic `StreamNotActive` (Kinesis Video overloads
46 * `ResourceNotFoundException` with "not found or not active" while a
47 * stream/channel is CREATING/UPDATING — patched into a typed tag in
48 * distilled). Explicitly typed for the declaration-emit reason above.
49 */
50 export const retryWhileSettling = <A, E extends { _tag: string }, R>(
51 self: Effect.Effect<A, E, R>,
52 ): Effect.Effect<A, E, R> =>
53 Effect.retry(self, {
54 while: (e) => e._tag === "ResourceInUseException" || e._tag === "StreamNotActive",
55 schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(15)]),
56 });
57
58 /**
59 * Bounded retry through `ResourceNotFoundException` — a freshly-created
60 * stream/channel can be invisible to `Describe*` for a few seconds
61 * (eventual consistency). Explicitly typed for the same declaration-emit
62 * reason as above.
63 */
64 export const retryWhileNotFound = <A, E extends { _tag: string }, R>(
65 self: Effect.Effect<A, E, R>,
66 ): Effect.Effect<A, E, R> =>
67 Effect.retry(self, {
68 while: (e) => e._tag === "ResourceNotFoundException",
69 schedule: Schedule.max([Schedule.fixed("1 second"), Schedule.recurs(10)]),
70 });
71
72 /**
73 * Repeat a describe poll until `done` holds (bounded — streams and channels
74 * typically become active within seconds). Explicitly typed for the
75 * declaration-emit reason above.
76 */
77 const untilConverged = <A, E, R>(
78 self: Effect.Effect<A, E, R>,
79 done: (a: A) => boolean,
80 times = 30,
81 ): Effect.Effect<A, E, R> =>
82 Effect.repeat(self, {
83 schedule: Schedule.spaced("2 seconds"),
84 until: done,
85 times,
86 });
87
88 /**
89 * Poll `DescribeStream` until the stream is `ACTIVE`. Tolerates the brief
90 * post-create window where the stream is not yet describable.
91 *
92 * Mutations (`UpdateStream`/`UpdateDataRetention`) are asynchronous AND bump
93 * the stream version — a describe issued immediately after can still show
94 * the pre-mutation `ACTIVE` state with the stale version. Pass
95 * `previousVersion` after a mutation to also wait for the version bump, so
96 * the returned `Version` is safe to use in the next versioned call.
97 */
98 export const waitForStreamActive = Effect.fn("AWS.KinesisVideo.waitForStreamActive")(function* (
99 streamName: string,
100 previousVersion?: string,
101 ) {
102 const done = (info: kv.StreamInfo | undefined): boolean =>
103 info?.Status === "ACTIVE" &&
104 (previousVersion === undefined || info.Version !== previousVersion);
105 const info = yield* untilConverged(
106 retryWhileNotFound(kv.describeStream({ StreamName: streamName })).pipe(
107 Effect.map((r) => r.StreamInfo),
108 ),
109 done,
110 );
111 if (!done(info)) {
112 return yield* new KinesisVideoNotConverged({
113 resource: streamName,
114 status: info?.Status,
115 });
116 }
117 return info!;
118 });
119
120 /**
121 * Poll `DescribeSignalingChannel` until the channel is `ACTIVE`. Tolerates
122 * the brief post-create window where the channel is not yet describable.
123 * Pass `previousVersion` after `UpdateSignalingChannel` to also wait for the
124 * version bump (see {@link waitForStreamActive}).
125 */
126 export const waitForChannelActive = Effect.fn("AWS.KinesisVideo.waitForChannelActive")(function* (
127 channelName: string,
128 previousVersion?: string,
129 ) {
130 const done = (info: kv.ChannelInfo | undefined): boolean =>
131 info?.ChannelStatus === "ACTIVE" &&
132 (previousVersion === undefined || info.Version !== previousVersion);
133 const info = yield* untilConverged(
134 retryWhileNotFound(kv.describeSignalingChannel({ ChannelName: channelName })).pipe(
135 Effect.map((r) => r.ChannelInfo),
136 ),
137 done,
138 );
139 if (!done(info)) {
140 return yield* new KinesisVideoNotConverged({
141 resource: channelName,
142 status: info?.ChannelStatus,
143 });
144 }
145 return info!;
146 });
147
148 /**
149 * Poll `DescribeStream` until the stream is fully purged (NotFound).
150 * A stream in `DELETING` blocks re-creation of the same name with
151 * `ResourceInUseException`, so reconcilers wait it out before recreating.
152 */
153 export const waitForStreamGone = Effect.fn("AWS.KinesisVideo.waitForStreamGone")(function* (
154 streamName: string,
155 ) {
156 const info = yield* untilConverged(
157 kv.describeStream({ StreamName: streamName }).pipe(
158 Effect.map((r) => r.StreamInfo),
159 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
160 ),
161 (i) => i === undefined,
162 // full purge can take noticeably longer than activation (~90s bound)
163 45,
164 );
165 if (info !== undefined) {
166 return yield* new KinesisVideoNotConverged({
167 resource: streamName,
168 status: info.Status,
169 });
170 }
171 });
172
173 /**
174 * Poll `DescribeSignalingChannel` until the channel is fully purged
175 * (NotFound) — see {@link waitForStreamGone}.
176 */
177 export const waitForChannelGone = Effect.fn("AWS.KinesisVideo.waitForChannelGone")(function* (
178 channelName: string,
179 ) {
180 const info = yield* untilConverged(
181 kv.describeSignalingChannel({ ChannelName: channelName }).pipe(
182 Effect.map((r) => r.ChannelInfo),
183 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
184 ),
185 (i) => i === undefined,
186 45,
187 );
188 if (info !== undefined) {
189 return yield* new KinesisVideoNotConverged({
190 resource: channelName,
191 status: info.ChannelStatus,
192 });
193 }
194 });
195
196 /**
197 * Drop `undefined` values from a distilled tag map (`{ [key]: string |
198 * undefined }`) so it can be diffed as a plain `Record<string, string>`.
199 */
200 export const compactTags = (
201 tags: { [key: string]: string | undefined } | undefined,
202 ): Record<string, string> => {
203 const out: Record<string, string> = {};
204 for (const [key, value] of Object.entries(tags ?? {})) {
205 if (value !== undefined) {
206 out[key] = value;
207 }
208 }
209 return out;
210 };
211
212 // Per-stream data endpoints are stable for the life of the stream — cache
213 // them per (arn, API) so repeated data-plane calls skip the extra
214 // GetDataEndpoint round-trip.
215 const dataEndpointCache = new Map<string, string>();
216
217 /**
218 * Discover (and cache) the per-stream data endpoint for `apiName`.
219 * Parameterized over the `GetDataEndpoint` operation so binding layers can
220 * pass an operation captured via yield-first (`yield* op`) whose calls are
221 * requirement-free.
222 */
223 export const discoverDataEndpoint = <E, R>(
224 streamArn: string,
225 apiName: kv.APIName,
226 getDataEndpoint: (
227 input: kv.GetDataEndpointInput,
228 ) => Effect.Effect<kv.GetDataEndpointOutput, E, R>,
229 ): Effect.Effect<string, E, R> =>
230 Effect.gen(function* () {
231 const key = `${streamArn}#${apiName}`;
232 const cached = dataEndpointCache.get(key);
233 if (cached !== undefined) {
234 return cached;
235 }
236 const response = yield* getDataEndpoint({
237 StreamARN: streamArn,
238 APIName: apiName,
239 });
240 const url = response.DataEndpoint!;
241 dataEndpointCache.set(key, url);
242 return url;
243 });
244
245 // Signaling endpoints are likewise stable per (channel, protocol, role).
246 const signalingEndpointCache = new Map<string, string>();
247
248 /**
249 * Discover (and cache) the per-channel signaling endpoint for `protocol` +
250 * `role` via `GetSignalingChannelEndpoint`. Parameterized over the operation
251 * for the same yield-first reason as {@link discoverDataEndpoint}.
252 */
253 export const discoverSignalingEndpoint = <E, R>(
254 channelArn: string,
255 protocol: kv.ChannelProtocol,
256 role: kv.ChannelRole,
257 getSignalingChannelEndpoint: (
258 input: kv.GetSignalingChannelEndpointInput,
259 ) => Effect.Effect<kv.GetSignalingChannelEndpointOutput, E, R>,
260 ): Effect.Effect<string, E | SignalingEndpointUnavailable, R> =>
261 Effect.gen(function* () {
262 const key = `${channelArn}#${protocol}#${role}`;
263 const cached = signalingEndpointCache.get(key);
264 if (cached !== undefined) {
265 return cached;
266 }
267 const response = yield* getSignalingChannelEndpoint({
268 ChannelARN: channelArn,
269 SingleMasterChannelEndpointConfiguration: {
270 Protocols: [protocol],
271 Role: role,
272 },
273 });
274 const endpoint = (response.ResourceEndpointList ?? []).find(
275 (item) => item.Protocol === protocol,
276 )?.ResourceEndpoint;
277 if (endpoint === undefined) {
278 return yield* new SignalingEndpointUnavailable({ channelArn, protocol });
279 }
280 signalingEndpointCache.set(key, endpoint);
281 return endpoint;
282 });