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

main
ts 596 lines 23.1 KB
Raw
1 import * as mediaconnect from "@distilled.cloud/aws/mediaconnect";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
8 import * as Data from "effect/Data";
9 import * as Effect from "effect/Effect";
10 import * as Schedule from "effect/Schedule";
11 import * as Stream from "effect/Stream";
12 import type { Providers } from "../Providers.ts";
13
14 export class MediaConnectFlowNotReady extends Data.TaggedError("MediaConnectFlowNotReady")<{
15 readonly message: string;
16 readonly cause?: unknown;
17 }> {}
18
19 export class MediaConnectFlowUnexpectedResponse extends Data.TaggedError(
20 "MediaConnectFlowUnexpectedResponse",
21 )<{
22 readonly message: string;
23 readonly cause?: unknown;
24 }> {}
25
26 /**
27 * Every flow output managed by alchemy must carry a `Name` so the reconciler
28 * can converge outputs by identity across updates.
29 */
30 export class FlowOutputNameMissing extends Data.TaggedError("FlowOutputNameMissing")<{
31 message: string;
32 }> {}
33
34 export interface FlowProps {
35 /**
36 * Name of the flow. If omitted, a deterministic physical name is generated
37 * from the app, stage and logical ID. Changing the name replaces the flow
38 * (MediaConnect has no rename operation).
39 */
40 flowName?: string;
41 /**
42 * Availability Zone the flow is created in. Must be within the current
43 * region. Changing the Availability Zone replaces the flow.
44 * @default MediaConnect picks an Availability Zone
45 */
46 availabilityZone?: string;
47 /**
48 * The source the flow ingests. Raw distilled `SetSourceRequest` shape —
49 * e.g. `{ Protocol: "rtp", WhitelistCidr: "10.0.0.0/8", IngestPort: 5000 }`.
50 * Mutable source settings (protocol, whitelist CIDR, ingest port, bitrate,
51 * latency, stream id, sender address/port, description) are updated in
52 * place via UpdateFlowSource.
53 */
54 source: mediaconnect.SetSourceRequest;
55 /**
56 * Outputs of the flow (up to 50). Each output MUST have a `Name` — the
57 * reconciler converges outputs by name: missing outputs are added, extra
58 * non-entitlement outputs are removed, and changed settings (destination,
59 * port, protocol, CIDR allow list, latency, description) are updated in
60 * place.
61 * @default no outputs
62 */
63 outputs?: mediaconnect.AddOutputRequest[];
64 /**
65 * User-defined tags for the flow.
66 */
67 tags?: Record<string, string>;
68 }
69
70 export interface Flow extends Resource<
71 "AWS.MediaConnect.Flow",
72 FlowProps,
73 {
74 /** Name of the flow. */
75 flowName: string;
76 /** ARN of the flow. */
77 flowArn: string;
78 /** Current status — a freshly created flow is `STANDBY` (not billing for transport). */
79 status: string;
80 /** Availability Zone the flow runs in. */
81 availabilityZone: string;
82 /** Flow description, if any. */
83 description: string | undefined;
84 /** IP address the flow egresses media from. */
85 egressIp: string | undefined;
86 /** ARN of the flow's source. */
87 sourceArn: string | undefined;
88 /** IP address the flow listens on for incoming content. */
89 sourceIngestIp: string | undefined;
90 /** Port the flow listens on for incoming content. */
91 sourceIngestPort: number | undefined;
92 /** The flow's outputs (name, ARN, destination endpoint). */
93 outputs: {
94 name: string;
95 outputArn: string;
96 destination: string | undefined;
97 port: number | undefined;
98 listenerAddress: string | undefined;
99 }[];
100 /** Observed tags on the flow. */
101 tags: Record<string, string>;
102 },
103 never,
104 Providers
105 > {}
106
107 /**
108 * An AWS Elemental MediaConnect flow — a reliable live-video transport
109 * between a source and one or more outputs.
110 *
111 * Creating a flow leaves it in `STANDBY`; a flow only ingests/egresses media
112 * (and bills for transport) once started with the StartFlow API. Flows bill
113 * hourly while ACTIVE, so alchemy never starts a flow implicitly.
114 * ### Creating a Flow
115 * **Example:** RTP Flow with a CIDR-Whitelisted Source
116 * ```typescript
117 * const flow = yield* Flow("Broadcast", {
118 * source: {
119 * Name: "primary",
120 * Protocol: "rtp",
121 * WhitelistCidr: "10.24.34.0/23",
122 * IngestPort: 5000,
123 * },
124 * });
125 * ```
126 *
127 * ### Outputs
128 * **Example:** Flow with an RTP Output
129 * ```typescript
130 * const flow = yield* Flow("Distribution", {
131 * source: {
132 * Name: "primary",
133 * Protocol: "rtp",
134 * WhitelistCidr: "10.24.34.0/23",
135 * IngestPort: 5000,
136 * },
137 * outputs: [
138 * {
139 * Name: "affiliate-east",
140 * Protocol: "rtp",
141 * Destination: "198.51.100.11",
142 * Port: 5010,
143 * },
144 * ],
145 * });
146 * ```
147 *
148 * ### Tags
149 * **Example:** Tagged Flow
150 * ```typescript
151 * const flow = yield* Flow("Broadcast", {
152 * source: { Protocol: "rtp", WhitelistCidr: "10.0.0.0/8", IngestPort: 5000 },
153 * tags: { team: "live-video" },
154 * });
155 * ```
156 *
157 * @resource
158 */
159 export const Flow = Resource<Flow>("AWS.MediaConnect.Flow");
160
161 type DescribedFlow = NonNullable<mediaconnect.DescribeFlowResponse["Flow"]>;
162 // The element type of a described flow's Outputs, INCLUDING the response
163 // refinements (required Name/OutputArn). Note: DescribedFlow["Outputs"] is an
164 // intersection of array types, so `.map` resolves its callback against the
165 // base `Output[]` signature and drops these refinements — iterate with
166 // `for..of` (which uses the number-index element type) instead of `.map`.
167 type ObservedOutput = DescribedFlow["Outputs"][number];
168
169 const sameStringList = (a: string[] | undefined, b: string[] | undefined) => {
170 const l = [...(a ?? [])].sort();
171 const r = [...(b ?? [])].sort();
172 return l.length === r.length && l.every((v, i) => v === r[i]);
173 };
174
175 export const FlowProvider = () =>
176 Provider.effect(
177 Flow,
178 Effect.gen(function* () {
179 const toName = (id: string, props: { flowName?: string }) =>
180 props.flowName ? Effect.succeed(props.flowName) : createPhysicalName({ id, maxLength: 60 });
181
182 const readFlow = Effect.fn(function* (flowArn: string) {
183 const response = yield* mediaconnect
184 .describeFlow({ FlowArn: flowArn })
185 .pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
186 return response?.Flow;
187 });
188
189 // Flow names are not unique in MediaConnect — identity is the ARN.
190 // When the ARN cache is lost (state persistence failure) fall back to
191 // the first flow bearing our deterministic name.
192 const findFlowArnByName = Effect.fn(function* (name: string) {
193 const flows = yield* mediaconnect.listFlows.items({}).pipe(Stream.runCollect);
194 for (const flow of flows) {
195 if (flow.Name === name && flow.FlowArn !== undefined) {
196 return flow.FlowArn;
197 }
198 }
199 return undefined;
200 });
201
202 const readFlowTags = Effect.fn(function* (flowArn: string) {
203 const response = yield* mediaconnect
204 .listTagsForResource({ ResourceArn: flowArn })
205 .pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
206 const tags: Record<string, string> = {};
207 for (const [key, value] of Object.entries(response?.Tags ?? {})) {
208 if (value !== undefined) tags[key] = value;
209 }
210 return tags;
211 });
212
213 // Flow creation and in-place updates are async; wait (bounded, ~3 min)
214 // for the flow to settle into a steady state before mutating further.
215 const waitUntilSettled = Effect.fn(function* (flowArn: string) {
216 const policy = Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(36)]);
217 return yield* readFlow(flowArn).pipe(
218 Effect.flatMap((flow) => {
219 if (flow === undefined) {
220 return Effect.fail(
221 new MediaConnectFlowNotReady({
222 message: `MediaConnect flow '${flowArn}' not found`,
223 }),
224 );
225 }
226 if (flow.Status !== "STANDBY" && flow.Status !== "ACTIVE" && flow.Status !== "ERROR") {
227 return Effect.fail(
228 new MediaConnectFlowNotReady({
229 message: `MediaConnect flow '${flowArn}' still settling (status: ${flow.Status})`,
230 }),
231 );
232 }
233 return Effect.succeed(flow);
234 }),
235 Effect.retry({ schedule: policy }),
236 );
237 });
238
239 // Deletion is verified as fully gone (bounded, ~3 min) so dependents
240 // (and re-creates of the same name) never race a half-deleted flow.
241 const waitUntilGone = Effect.fn(function* (flowArn: string) {
242 const policy = Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(36)]);
243 yield* readFlow(flowArn).pipe(
244 Effect.flatMap((flow) =>
245 flow === undefined
246 ? Effect.void
247 : Effect.fail(
248 new MediaConnectFlowNotReady({
249 message: `MediaConnect flow '${flowArn}' still exists (status: ${flow.Status})`,
250 }),
251 ),
252 ),
253 Effect.retry({ schedule: policy }),
254 );
255 });
256
257 const toAttrs = Effect.fn(function* (flow: DescribedFlow) {
258 const outputs: {
259 name: string;
260 outputArn: string;
261 destination: string | undefined;
262 port: number | undefined;
263 listenerAddress: string | undefined;
264 }[] = [];
265 for (const output of flow.Outputs ?? []) {
266 outputs.push({
267 name: output.Name,
268 outputArn: output.OutputArn,
269 destination: output.Destination,
270 port: output.Port,
271 listenerAddress: output.ListenerAddress,
272 });
273 }
274 return {
275 flowName: flow.Name,
276 flowArn: flow.FlowArn,
277 status: flow.Status,
278 availabilityZone: flow.AvailabilityZone,
279 description: flow.Description,
280 egressIp: flow.EgressIp,
281 sourceArn: flow.Source?.SourceArn,
282 sourceIngestIp: flow.Source?.IngestIp,
283 sourceIngestPort: flow.Source?.IngestPort,
284 outputs,
285 tags: yield* readFlowTags(flow.FlowArn),
286 };
287 });
288
289 return {
290 stables: ["flowName", "flowArn", "availabilityZone"],
291
292 diff: Effect.fn(function* ({ id, olds, news }) {
293 if (!isResolved(news)) return undefined;
294 const oldName = yield* toName(id, { flowName: olds?.flowName });
295 const newName = yield* toName(id, { flowName: news?.flowName });
296 if (oldName !== newName) {
297 return { action: "replace" } as const;
298 }
299 // The Availability Zone is create-only.
300 if (
301 news?.availabilityZone !== undefined &&
302 olds?.availabilityZone !== undefined &&
303 news.availabilityZone !== olds.availabilityZone
304 ) {
305 return { action: "replace" } as const;
306 }
307 }),
308
309 read: Effect.fn(function* ({ id, olds, output }) {
310 const name = output?.flowName ?? (yield* toName(id, olds ?? {}));
311 const arn = output?.flowArn ?? (yield* findFlowArnByName(name));
312 if (arn === undefined) return undefined;
313 const flow = yield* readFlow(arn);
314 if (flow === undefined) return undefined;
315 const attrs = yield* toAttrs(flow);
316 return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
317 }),
318
319 reconcile: Effect.fn(function* ({ id, news, output, session }) {
320 const props = news!;
321 const name = output?.flowName ?? (yield* toName(id, props));
322 const internalTags = yield* createInternalTags(id);
323 const desiredTags = { ...internalTags, ...props.tags };
324
325 // Validate up front (before any AWS call): outputs are converged
326 // by name, so every desired output must carry one.
327 const desiredOutputs: (mediaconnect.AddOutputRequest & {
328 Name: string;
329 })[] = [];
330 for (const desired of props.outputs ?? []) {
331 if (desired.Name === undefined) {
332 return yield* new FlowOutputNameMissing({
333 message: `every output of MediaConnect flow '${name}' must set a Name — outputs are converged by name`,
334 });
335 }
336 desiredOutputs.push({ ...desired, Name: desired.Name });
337 }
338
339 // 1. Observe — cloud state is authoritative; output is only an
340 // ARN cache (flow names are not unique, so fall back to search).
341 let arn = output?.flowArn ?? (yield* findFlowArnByName(name));
342 let observed = arn !== undefined ? yield* readFlow(arn) : undefined;
343
344 // 2. Ensure — create if missing. Creation leaves the flow in
345 // STANDBY; alchemy never starts a flow (ACTIVE bills hourly).
346 if (observed === undefined) {
347 const created = yield* mediaconnect.createFlow({
348 Name: name,
349 AvailabilityZone: props.availabilityZone,
350 Source: props.source,
351 Outputs: desiredOutputs.length > 0 ? desiredOutputs : undefined,
352 });
353 arn = created.Flow?.FlowArn;
354 }
355 if (arn === undefined) {
356 return yield* new MediaConnectFlowUnexpectedResponse({
357 message: `MediaConnect flow '${name}' is missing its ARN`,
358 });
359 }
360 observed = yield* waitUntilSettled(arn);
361
362 // 3. Sync source — diff OBSERVED source settings against desired
363 // and apply only the delta via UpdateFlowSource.
364 const source = observed.Source;
365 if (source?.SourceArn !== undefined) {
366 const desired = props.source;
367 const transport = source.Transport;
368 const update: Omit<mediaconnect.UpdateFlowSourceRequest, "FlowArn" | "SourceArn"> = {};
369 let mutated = false;
370 if (desired.Description !== undefined && desired.Description !== source.Description) {
371 update.Description = desired.Description;
372 mutated = true;
373 }
374 if (desired.Protocol !== undefined && desired.Protocol !== transport?.Protocol) {
375 update.Protocol = desired.Protocol;
376 mutated = true;
377 }
378 if (
379 desired.WhitelistCidr !== undefined &&
380 desired.WhitelistCidr !== source.WhitelistCidr
381 ) {
382 update.WhitelistCidr = desired.WhitelistCidr;
383 mutated = true;
384 }
385 if (desired.IngestPort !== undefined && desired.IngestPort !== source.IngestPort) {
386 update.IngestPort = desired.IngestPort;
387 mutated = true;
388 }
389 if (desired.MaxBitrate !== undefined && desired.MaxBitrate !== transport?.MaxBitrate) {
390 update.MaxBitrate = desired.MaxBitrate;
391 mutated = true;
392 }
393 if (desired.MaxLatency !== undefined && desired.MaxLatency !== transport?.MaxLatency) {
394 update.MaxLatency = desired.MaxLatency;
395 mutated = true;
396 }
397 if (desired.MinLatency !== undefined && desired.MinLatency !== transport?.MinLatency) {
398 update.MinLatency = desired.MinLatency;
399 mutated = true;
400 }
401 if (desired.StreamId !== undefined && desired.StreamId !== transport?.StreamId) {
402 update.StreamId = desired.StreamId;
403 mutated = true;
404 }
405 if (
406 desired.SenderIpAddress !== undefined &&
407 desired.SenderIpAddress !== source.SenderIpAddress
408 ) {
409 update.SenderIpAddress = desired.SenderIpAddress;
410 mutated = true;
411 }
412 if (
413 desired.SenderControlPort !== undefined &&
414 desired.SenderControlPort !== source.SenderControlPort
415 ) {
416 update.SenderControlPort = desired.SenderControlPort;
417 mutated = true;
418 }
419 if (mutated) {
420 yield* mediaconnect.updateFlowSource({
421 ...update,
422 FlowArn: arn,
423 SourceArn: source.SourceArn,
424 });
425 observed = yield* waitUntilSettled(arn);
426 }
427 }
428
429 // 3b. Sync outputs by name — add missing, update drifted, remove
430 // extras (entitlement-generated outputs are not ours to remove).
431 const observedOutputs = observed.Outputs ?? [];
432 const observedByName = new Map<string, ObservedOutput>();
433 for (const observedOutput of observedOutputs) {
434 observedByName.set(observedOutput.Name, observedOutput);
435 }
436 const desiredNames = new Set(desiredOutputs.map((o) => o.Name));
437 let outputsMutated = false;
438
439 const toAdd = desiredOutputs.filter((o) => !observedByName.has(o.Name));
440 if (toAdd.length > 0) {
441 yield* mediaconnect.addFlowOutputs({
442 FlowArn: arn,
443 Outputs: toAdd,
444 });
445 outputsMutated = true;
446 }
447
448 for (const existing of observedOutputs) {
449 if (!desiredNames.has(existing.Name) && existing.EntitlementArn === undefined) {
450 yield* mediaconnect
451 .removeFlowOutput({
452 FlowArn: arn,
453 OutputArn: existing.OutputArn,
454 })
455 .pipe(Effect.catchTag("NotFoundException", () => Effect.void));
456 outputsMutated = true;
457 }
458 }
459
460 for (const desired of desiredOutputs) {
461 const existing = observedByName.get(desired.Name);
462 if (existing === undefined) continue;
463 const transport = existing.Transport;
464 const update: Omit<mediaconnect.UpdateFlowOutputRequest, "FlowArn" | "OutputArn"> = {};
465 let mutated = false;
466 if (desired.Description !== undefined && desired.Description !== existing.Description) {
467 update.Description = desired.Description;
468 mutated = true;
469 }
470 if (desired.Destination !== undefined && desired.Destination !== existing.Destination) {
471 update.Destination = desired.Destination;
472 mutated = true;
473 }
474 if (desired.Port !== undefined && desired.Port !== existing.Port) {
475 update.Port = desired.Port;
476 mutated = true;
477 }
478 if (desired.Protocol !== undefined && desired.Protocol !== transport?.Protocol) {
479 update.Protocol = desired.Protocol;
480 mutated = true;
481 }
482 if (
483 desired.CidrAllowList !== undefined &&
484 !sameStringList(desired.CidrAllowList, transport?.CidrAllowList)
485 ) {
486 update.CidrAllowList = desired.CidrAllowList;
487 mutated = true;
488 }
489 if (desired.MaxLatency !== undefined && desired.MaxLatency !== transport?.MaxLatency) {
490 update.MaxLatency = desired.MaxLatency;
491 mutated = true;
492 }
493 if (desired.MinLatency !== undefined && desired.MinLatency !== transport?.MinLatency) {
494 update.MinLatency = desired.MinLatency;
495 mutated = true;
496 }
497 if (
498 desired.SmoothingLatency !== undefined &&
499 desired.SmoothingLatency !== transport?.SmoothingLatency
500 ) {
501 update.SmoothingLatency = desired.SmoothingLatency;
502 mutated = true;
503 }
504 if (desired.StreamId !== undefined && desired.StreamId !== transport?.StreamId) {
505 update.StreamId = desired.StreamId;
506 mutated = true;
507 }
508 if (desired.RemoteId !== undefined && desired.RemoteId !== transport?.RemoteId) {
509 update.RemoteId = desired.RemoteId;
510 mutated = true;
511 }
512 if (mutated) {
513 yield* mediaconnect.updateFlowOutput({
514 ...update,
515 FlowArn: arn,
516 OutputArn: existing.OutputArn,
517 });
518 outputsMutated = true;
519 }
520 }
521 if (outputsMutated) {
522 observed = yield* waitUntilSettled(arn);
523 }
524
525 // 3c. Sync tags — diff against OBSERVED cloud tags.
526 const observedTags = yield* readFlowTags(arn);
527 const { removed, upsert } = diffTags(observedTags, desiredTags);
528 if (upsert.length > 0) {
529 yield* mediaconnect.tagResource({
530 ResourceArn: arn,
531 Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
532 });
533 }
534 if (removed.length > 0) {
535 yield* mediaconnect.untagResource({
536 ResourceArn: arn,
537 TagKeys: removed,
538 });
539 }
540
541 yield* session.note(name);
542 return yield* toAttrs(observed);
543 }),
544
545 delete: Effect.fn(function* ({ output }) {
546 const arn = output.flowArn;
547 const observed = yield* readFlow(arn);
548 if (observed === undefined) return;
549 // A flow must be stopped before it can be deleted. Alchemy never
550 // starts flows, but the flow may have been started out-of-band.
551 if (observed.Status === "ACTIVE" || observed.Status === "STARTING") {
552 yield* mediaconnect.stopFlow({ FlowArn: arn }).pipe(
553 // A STARTING flow rejects StopFlow until the start completes.
554 Effect.retry({
555 while: (e) => e._tag === "BadRequestException",
556 schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(12)]),
557 }),
558 Effect.catchTag("NotFoundException", () => Effect.void),
559 );
560 }
561 // Wait for any in-flight transition (STOPPING/UPDATING) to settle,
562 // then delete. A flow already DELETING (or gone) is success.
563 const settled = yield* waitUntilSettled(arn).pipe(Effect.orElseSucceed(() => undefined));
564 if (settled !== undefined) {
565 yield* mediaconnect.deleteFlow({ FlowArn: arn }).pipe(
566 // Status races (e.g. a transition that began after our read)
567 // surface as BadRequestException — bounded retry through it.
568 Effect.retry({
569 while: (e) => e._tag === "BadRequestException",
570 schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(12)]),
571 }),
572 Effect.catchTag("NotFoundException", () => Effect.void),
573 );
574 }
575 yield* waitUntilGone(arn);
576 }),
577
578 list: () =>
579 Effect.gen(function* () {
580 const listed = yield* mediaconnect.listFlows.items({}).pipe(Stream.runCollect);
581 const arns: string[] = [];
582 for (const flow of listed) {
583 if (flow.FlowArn !== undefined) arns.push(flow.FlowArn);
584 }
585 const flows = yield* Effect.forEach(arns, (arn) => readFlow(arn), {
586 concurrency: 4,
587 });
588 return yield* Effect.forEach(
589 flows.filter((flow): flow is DescribedFlow => flow !== undefined),
590 (flow) => toAttrs(flow),
591 { concurrency: 4 },
592 );
593 }),
594 };
595 }),
596 );