import * as mediaconnect from "@distilled.cloud/aws/mediaconnect";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
export class MediaConnectFlowNotReady extends Data.TaggedError("MediaConnectFlowNotReady")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class MediaConnectFlowUnexpectedResponse extends Data.TaggedError(
"MediaConnectFlowUnexpectedResponse",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
/**
* Every flow output managed by alchemy must carry a `Name` so the reconciler
* can converge outputs by identity across updates.
*/
export class FlowOutputNameMissing extends Data.TaggedError("FlowOutputNameMissing")<{
message: string;
}> {}
export interface FlowProps {
/**
* Name of the flow. If omitted, a deterministic physical name is generated
* from the app, stage and logical ID. Changing the name replaces the flow
* (MediaConnect has no rename operation).
*/
flowName?: string;
/**
* Availability Zone the flow is created in. Must be within the current
* region. Changing the Availability Zone replaces the flow.
* @default MediaConnect picks an Availability Zone
*/
availabilityZone?: string;
/**
* The source the flow ingests. Raw distilled `SetSourceRequest` shape —
* e.g. `{ Protocol: "rtp", WhitelistCidr: "10.0.0.0/8", IngestPort: 5000 }`.
* Mutable source settings (protocol, whitelist CIDR, ingest port, bitrate,
* latency, stream id, sender address/port, description) are updated in
* place via UpdateFlowSource.
*/
source: mediaconnect.SetSourceRequest;
/**
* Outputs of the flow (up to 50). Each output MUST have a `Name` — the
* reconciler converges outputs by name: missing outputs are added, extra
* non-entitlement outputs are removed, and changed settings (destination,
* port, protocol, CIDR allow list, latency, description) are updated in
* place.
* @default no outputs
*/
outputs?: mediaconnect.AddOutputRequest[];
/**
* User-defined tags for the flow.
*/
tags?: Record<string, string>;
}
export interface Flow extends Resource<
"AWS.MediaConnect.Flow",
FlowProps,
{
/** Name of the flow. */
flowName: string;
/** ARN of the flow. */
flowArn: string;
/** Current status — a freshly created flow is `STANDBY` (not billing for transport). */
status: string;
/** Availability Zone the flow runs in. */
availabilityZone: string;
/** Flow description, if any. */
description: string | undefined;
/** IP address the flow egresses media from. */
egressIp: string | undefined;
/** ARN of the flow's source. */
sourceArn: string | undefined;
/** IP address the flow listens on for incoming content. */
sourceIngestIp: string | undefined;
/** Port the flow listens on for incoming content. */
sourceIngestPort: number | undefined;
/** The flow's outputs (name, ARN, destination endpoint). */
outputs: {
name: string;
outputArn: string;
destination: string | undefined;
port: number | undefined;
listenerAddress: string | undefined;
}[];
/** Observed tags on the flow. */
tags: Record<string, string>;
},
never,
Providers
> {}
/**
* An AWS Elemental MediaConnect flow — a reliable live-video transport
* between a source and one or more outputs.
*
* Creating a flow leaves it in `STANDBY`; a flow only ingests/egresses media
* (and bills for transport) once started with the StartFlow API. Flows bill
* hourly while ACTIVE, so alchemy never starts a flow implicitly.
* ### Creating a Flow
* **Example:** RTP Flow with a CIDR-Whitelisted Source
* ```typescript
* const flow = yield* Flow("Broadcast", {
* source: {
* Name: "primary",
* Protocol: "rtp",
* WhitelistCidr: "10.24.34.0/23",
* IngestPort: 5000,
* },
* });
* ```
*
* ### Outputs
* **Example:** Flow with an RTP Output
* ```typescript
* const flow = yield* Flow("Distribution", {
* source: {
* Name: "primary",
* Protocol: "rtp",
* WhitelistCidr: "10.24.34.0/23",
* IngestPort: 5000,
* },
* outputs: [
* {
* Name: "affiliate-east",
* Protocol: "rtp",
* Destination: "198.51.100.11",
* Port: 5010,
* },
* ],
* });
* ```
*
* ### Tags
* **Example:** Tagged Flow
* ```typescript
* const flow = yield* Flow("Broadcast", {
* source: { Protocol: "rtp", WhitelistCidr: "10.0.0.0/8", IngestPort: 5000 },
* tags: { team: "live-video" },
* });
* ```
*
* @resource
*/
export const Flow = Resource<Flow>("AWS.MediaConnect.Flow");
type DescribedFlow = NonNullable<mediaconnect.DescribeFlowResponse["Flow"]>;
// The element type of a described flow's Outputs, INCLUDING the response
// refinements (required Name/OutputArn). Note: DescribedFlow["Outputs"] is an
// intersection of array types, so `.map` resolves its callback against the
// base `Output[]` signature and drops these refinements — iterate with
// `for..of` (which uses the number-index element type) instead of `.map`.
type ObservedOutput = DescribedFlow["Outputs"][number];
const sameStringList = (a: string[] | undefined, b: string[] | undefined) => {
const l = [...(a ?? [])].sort();
const r = [...(b ?? [])].sort();
return l.length === r.length && l.every((v, i) => v === r[i]);
};
export const FlowProvider = () =>
Provider.effect(
Flow,
Effect.gen(function* () {
const toName = (id: string, props: { flowName?: string }) =>
props.flowName ? Effect.succeed(props.flowName) : createPhysicalName({ id, maxLength: 60 });
const readFlow = Effect.fn(function* (flowArn: string) {
const response = yield* mediaconnect
.describeFlow({ FlowArn: flowArn })
.pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
return response?.Flow;
});
// Flow names are not unique in MediaConnect — identity is the ARN.
// When the ARN cache is lost (state persistence failure) fall back to
// the first flow bearing our deterministic name.
const findFlowArnByName = Effect.fn(function* (name: string) {
const flows = yield* mediaconnect.listFlows.items({}).pipe(Stream.runCollect);
for (const flow of flows) {
if (flow.Name === name && flow.FlowArn !== undefined) {
return flow.FlowArn;
}
}
return undefined;
});
const readFlowTags = Effect.fn(function* (flowArn: string) {
const response = yield* mediaconnect
.listTagsForResource({ ResourceArn: flowArn })
.pipe(Effect.catchTag("NotFoundException", () => Effect.undefined));
const tags: Record<string, string> = {};
for (const [key, value] of Object.entries(response?.Tags ?? {})) {
if (value !== undefined) tags[key] = value;
}
return tags;
});
// Flow creation and in-place updates are async; wait (bounded, ~3 min)
// for the flow to settle into a steady state before mutating further.
const waitUntilSettled = Effect.fn(function* (flowArn: string) {
const policy = Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(36)]);
return yield* readFlow(flowArn).pipe(
Effect.flatMap((flow) => {
if (flow === undefined) {
return Effect.fail(
new MediaConnectFlowNotReady({
message: `MediaConnect flow '${flowArn}' not found`,
}),
);
}
if (flow.Status !== "STANDBY" && flow.Status !== "ACTIVE" && flow.Status !== "ERROR") {
return Effect.fail(
new MediaConnectFlowNotReady({
message: `MediaConnect flow '${flowArn}' still settling (status: ${flow.Status})`,
}),
);
}
return Effect.succeed(flow);
}),
Effect.retry({ schedule: policy }),
);
});
// Deletion is verified as fully gone (bounded, ~3 min) so dependents
// (and re-creates of the same name) never race a half-deleted flow.
const waitUntilGone = Effect.fn(function* (flowArn: string) {
const policy = Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(36)]);
yield* readFlow(flowArn).pipe(
Effect.flatMap((flow) =>
flow === undefined
? Effect.void
: Effect.fail(
new MediaConnectFlowNotReady({
message: `MediaConnect flow '${flowArn}' still exists (status: ${flow.Status})`,
}),
),
),
Effect.retry({ schedule: policy }),
);
});
const toAttrs = Effect.fn(function* (flow: DescribedFlow) {
const outputs: {
name: string;
outputArn: string;
destination: string | undefined;
port: number | undefined;
listenerAddress: string | undefined;
}[] = [];
for (const output of flow.Outputs ?? []) {
outputs.push({
name: output.Name,
outputArn: output.OutputArn,
destination: output.Destination,
port: output.Port,
listenerAddress: output.ListenerAddress,
});
}
return {
flowName: flow.Name,
flowArn: flow.FlowArn,
status: flow.Status,
availabilityZone: flow.AvailabilityZone,
description: flow.Description,
egressIp: flow.EgressIp,
sourceArn: flow.Source?.SourceArn,
sourceIngestIp: flow.Source?.IngestIp,
sourceIngestPort: flow.Source?.IngestPort,
outputs,
tags: yield* readFlowTags(flow.FlowArn),
};
});
return {
stables: ["flowName", "flowArn", "availabilityZone"],
diff: Effect.fn(function* ({ id, olds, news }) {
if (!isResolved(news)) return undefined;
const oldName = yield* toName(id, { flowName: olds?.flowName });
const newName = yield* toName(id, { flowName: news?.flowName });
if (oldName !== newName) {
return { action: "replace" } as const;
}
// The Availability Zone is create-only.
if (
news?.availabilityZone !== undefined &&
olds?.availabilityZone !== undefined &&
news.availabilityZone !== olds.availabilityZone
) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const name = output?.flowName ?? (yield* toName(id, olds ?? {}));
const arn = output?.flowArn ?? (yield* findFlowArnByName(name));
if (arn === undefined) return undefined;
const flow = yield* readFlow(arn);
if (flow === undefined) return undefined;
const attrs = yield* toAttrs(flow);
return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const props = news!;
const name = output?.flowName ?? (yield* toName(id, props));
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...internalTags, ...props.tags };
// Validate up front (before any AWS call): outputs are converged
// by name, so every desired output must carry one.
const desiredOutputs: (mediaconnect.AddOutputRequest & {
Name: string;
})[] = [];
for (const desired of props.outputs ?? []) {
if (desired.Name === undefined) {
return yield* new FlowOutputNameMissing({
message: `every output of MediaConnect flow '${name}' must set a Name — outputs are converged by name`,
});
}
desiredOutputs.push({ ...desired, Name: desired.Name });
}
// 1. Observe — cloud state is authoritative; output is only an
// ARN cache (flow names are not unique, so fall back to search).
let arn = output?.flowArn ?? (yield* findFlowArnByName(name));
let observed = arn !== undefined ? yield* readFlow(arn) : undefined;
// 2. Ensure — create if missing. Creation leaves the flow in
// STANDBY; alchemy never starts a flow (ACTIVE bills hourly).
if (observed === undefined) {
const created = yield* mediaconnect.createFlow({
Name: name,
AvailabilityZone: props.availabilityZone,
Source: props.source,
Outputs: desiredOutputs.length > 0 ? desiredOutputs : undefined,
});
arn = created.Flow?.FlowArn;
}
if (arn === undefined) {
return yield* new MediaConnectFlowUnexpectedResponse({
message: `MediaConnect flow '${name}' is missing its ARN`,
});
}
observed = yield* waitUntilSettled(arn);
// 3. Sync source — diff OBSERVED source settings against desired
// and apply only the delta via UpdateFlowSource.
const source = observed.Source;
if (source?.SourceArn !== undefined) {
const desired = props.source;
const transport = source.Transport;
const update: Omit<mediaconnect.UpdateFlowSourceRequest, "FlowArn" | "SourceArn"> = {};
let mutated = false;
if (desired.Description !== undefined && desired.Description !== source.Description) {
update.Description = desired.Description;
mutated = true;
}
if (desired.Protocol !== undefined && desired.Protocol !== transport?.Protocol) {
update.Protocol = desired.Protocol;
mutated = true;
}
if (
desired.WhitelistCidr !== undefined &&
desired.WhitelistCidr !== source.WhitelistCidr
) {
update.WhitelistCidr = desired.WhitelistCidr;
mutated = true;
}
if (desired.IngestPort !== undefined && desired.IngestPort !== source.IngestPort) {
update.IngestPort = desired.IngestPort;
mutated = true;
}
if (desired.MaxBitrate !== undefined && desired.MaxBitrate !== transport?.MaxBitrate) {
update.MaxBitrate = desired.MaxBitrate;
mutated = true;
}
if (desired.MaxLatency !== undefined && desired.MaxLatency !== transport?.MaxLatency) {
update.MaxLatency = desired.MaxLatency;
mutated = true;
}
if (desired.MinLatency !== undefined && desired.MinLatency !== transport?.MinLatency) {
update.MinLatency = desired.MinLatency;
mutated = true;
}
if (desired.StreamId !== undefined && desired.StreamId !== transport?.StreamId) {
update.StreamId = desired.StreamId;
mutated = true;
}
if (
desired.SenderIpAddress !== undefined &&
desired.SenderIpAddress !== source.SenderIpAddress
) {
update.SenderIpAddress = desired.SenderIpAddress;
mutated = true;
}
if (
desired.SenderControlPort !== undefined &&
desired.SenderControlPort !== source.SenderControlPort
) {
update.SenderControlPort = desired.SenderControlPort;
mutated = true;
}
if (mutated) {
yield* mediaconnect.updateFlowSource({
...update,
FlowArn: arn,
SourceArn: source.SourceArn,
});
observed = yield* waitUntilSettled(arn);
}
}
// 3b. Sync outputs by name — add missing, update drifted, remove
// extras (entitlement-generated outputs are not ours to remove).
const observedOutputs = observed.Outputs ?? [];
const observedByName = new Map<string, ObservedOutput>();
for (const observedOutput of observedOutputs) {
observedByName.set(observedOutput.Name, observedOutput);
}
const desiredNames = new Set(desiredOutputs.map((o) => o.Name));
let outputsMutated = false;
const toAdd = desiredOutputs.filter((o) => !observedByName.has(o.Name));
if (toAdd.length > 0) {
yield* mediaconnect.addFlowOutputs({
FlowArn: arn,
Outputs: toAdd,
});
outputsMutated = true;
}
for (const existing of observedOutputs) {
if (!desiredNames.has(existing.Name) && existing.EntitlementArn === undefined) {
yield* mediaconnect
.removeFlowOutput({
FlowArn: arn,
OutputArn: existing.OutputArn,
})
.pipe(Effect.catchTag("NotFoundException", () => Effect.void));
outputsMutated = true;
}
}
for (const desired of desiredOutputs) {
const existing = observedByName.get(desired.Name);
if (existing === undefined) continue;
const transport = existing.Transport;
const update: Omit<mediaconnect.UpdateFlowOutputRequest, "FlowArn" | "OutputArn"> = {};
let mutated = false;
if (desired.Description !== undefined && desired.Description !== existing.Description) {
update.Description = desired.Description;
mutated = true;
}
if (desired.Destination !== undefined && desired.Destination !== existing.Destination) {
update.Destination = desired.Destination;
mutated = true;
}
if (desired.Port !== undefined && desired.Port !== existing.Port) {
update.Port = desired.Port;
mutated = true;
}
if (desired.Protocol !== undefined && desired.Protocol !== transport?.Protocol) {
update.Protocol = desired.Protocol;
mutated = true;
}
if (
desired.CidrAllowList !== undefined &&
!sameStringList(desired.CidrAllowList, transport?.CidrAllowList)
) {
update.CidrAllowList = desired.CidrAllowList;
mutated = true;
}
if (desired.MaxLatency !== undefined && desired.MaxLatency !== transport?.MaxLatency) {
update.MaxLatency = desired.MaxLatency;
mutated = true;
}
if (desired.MinLatency !== undefined && desired.MinLatency !== transport?.MinLatency) {
update.MinLatency = desired.MinLatency;
mutated = true;
}
if (
desired.SmoothingLatency !== undefined &&
desired.SmoothingLatency !== transport?.SmoothingLatency
) {
update.SmoothingLatency = desired.SmoothingLatency;
mutated = true;
}
if (desired.StreamId !== undefined && desired.StreamId !== transport?.StreamId) {
update.StreamId = desired.StreamId;
mutated = true;
}
if (desired.RemoteId !== undefined && desired.RemoteId !== transport?.RemoteId) {
update.RemoteId = desired.RemoteId;
mutated = true;
}
if (mutated) {
yield* mediaconnect.updateFlowOutput({
...update,
FlowArn: arn,
OutputArn: existing.OutputArn,
});
outputsMutated = true;
}
}
if (outputsMutated) {
observed = yield* waitUntilSettled(arn);
}
// 3c. Sync tags — diff against OBSERVED cloud tags.
const observedTags = yield* readFlowTags(arn);
const { removed, upsert } = diffTags(observedTags, desiredTags);
if (upsert.length > 0) {
yield* mediaconnect.tagResource({
ResourceArn: arn,
Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
});
}
if (removed.length > 0) {
yield* mediaconnect.untagResource({
ResourceArn: arn,
TagKeys: removed,
});
}
yield* session.note(name);
return yield* toAttrs(observed);
}),
delete: Effect.fn(function* ({ output }) {
const arn = output.flowArn;
const observed = yield* readFlow(arn);
if (observed === undefined) return;
// A flow must be stopped before it can be deleted. Alchemy never
// starts flows, but the flow may have been started out-of-band.
if (observed.Status === "ACTIVE" || observed.Status === "STARTING") {
yield* mediaconnect.stopFlow({ FlowArn: arn }).pipe(
// A STARTING flow rejects StopFlow until the start completes.
Effect.retry({
while: (e) => e._tag === "BadRequestException",
schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(12)]),
}),
Effect.catchTag("NotFoundException", () => Effect.void),
);
}
// Wait for any in-flight transition (STOPPING/UPDATING) to settle,
// then delete. A flow already DELETING (or gone) is success.
const settled = yield* waitUntilSettled(arn).pipe(Effect.orElseSucceed(() => undefined));
if (settled !== undefined) {
yield* mediaconnect.deleteFlow({ FlowArn: arn }).pipe(
// Status races (e.g. a transition that began after our read)
// surface as BadRequestException — bounded retry through it.
Effect.retry({
while: (e) => e._tag === "BadRequestException",
schedule: Schedule.max([Schedule.fixed("5 seconds"), Schedule.recurs(12)]),
}),
Effect.catchTag("NotFoundException", () => Effect.void),
);
}
yield* waitUntilGone(arn);
}),
list: () =>
Effect.gen(function* () {
const listed = yield* mediaconnect.listFlows.items({}).pipe(Stream.runCollect);
const arns: string[] = [];
for (const flow of listed) {
if (flow.FlowArn !== undefined) arns.push(flow.FlowArn);
}
const flows = yield* Effect.forEach(arns, (arn) => readFlow(arn), {
concurrency: 4,
});
return yield* Effect.forEach(
flows.filter((flow): flow is DescribedFlow => flow !== undefined),
(flow) => toAttrs(flow),
{ concurrency: 4 },
);
}),
};
}),
);