import * as oam from "@distilled.cloud/aws/oam";
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 { hasAlchemyTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { deleteSinkAndWait, readOamTags, retryOamMutation, syncOamTags } from "./internal.ts";
export interface SinkProps {
/**
* Name of the sink. If omitted, a unique name is generated from the app,
* stage and logical ID. Changing the name replaces the sink.
*/
sinkName?: string;
/**
* The IAM resource policy that grants source accounts permission to link
* to this sink (`oam:CreateLink` / `oam:UpdateLink`). Provided as a JSON
* string or a plain policy document object.
*
* OAM has no delete-sink-policy API, so removing this prop leaves the
* last applied policy in place.
*/
policy?: string | Record<string, any>;
/**
* User tags to attach to the sink. Merged with internal Alchemy tags.
*/
tags?: Record<string, string>;
}
export interface Sink extends Resource<
"AWS.OAM.Sink",
SinkProps,
{
/** The name of the sink. */
sinkName: string;
/** The ARN of the sink (used as the `sinkIdentifier` of a `Link`). */
sinkArn: string;
/** The random ID string that AWS generated as part of the sink ARN. */
sinkId: string;
},
never,
Providers
> {}
/**
* A CloudWatch cross-account observability **sink** — the attachment point
* in a monitoring account that source accounts link to in order to share
* metrics, logs, traces, and Application Signals data.
*
* Each account can contain **one sink per region**. After creating a sink,
* attach a sink policy (the `policy` prop) that authorizes source accounts
* (or an entire organization) to create links to it.
*
* ### Creating a Sink
* **Example:** Basic Sink
* ```typescript
* import * as OAM from "@alchemy.run/aws/OAM";
*
* const sink = yield* OAM.Sink("MonitoringSink");
* ```
*
* **Example:** Sink with a policy authorizing source accounts
* ```typescript
* const sink = yield* OAM.Sink("MonitoringSink", {
* policy: {
* Version: "2012-10-17",
* Statement: [
* {
* Effect: "Allow",
* Principal: { AWS: ["111122223333"] },
* Action: ["oam:CreateLink", "oam:UpdateLink"],
* Resource: "*",
* Condition: {
* "ForAllValues:StringEquals": {
* "oam:ResourceTypes": [
* "AWS::CloudWatch::Metric",
* "AWS::Logs::LogGroup",
* ],
* },
* },
* },
* ],
* },
* });
* ```
*
* **Example:** Authorize an entire organization
* ```typescript
* const sink = yield* OAM.Sink("OrgSink", {
* policy: {
* Version: "2012-10-17",
* Statement: [
* {
* Effect: "Allow",
* Principal: "*",
* Action: ["oam:CreateLink", "oam:UpdateLink"],
* Resource: "*",
* Condition: {
* "ForAnyValue:StringEquals": { "aws:PrincipalOrgID": "o-xxxxxxxxxx" },
* },
* },
* ],
* },
* });
* ```
*
* @resource
*/
export const Sink = Resource<Sink>("AWS.OAM.Sink");
/** Normalize a `policy` prop to a JSON string for `putSinkPolicy`. */
const toPolicyString = (policy: string | Record<string, any>): string =>
typeof policy === "string" ? policy : JSON.stringify(policy);
/**
* Semantic policy equality — AWS normalizes documents (e.g. account-ID
* principals become `arn:aws:iam::…:root`), so a raw string compare would
* re-put an unchanged policy forever. We compare parsed JSON; a normalized
* difference still re-puts, which is idempotent and harmless.
*/
const samePolicy = (a: string | undefined, b: string | undefined): boolean => {
if (a === undefined || b === undefined) return a === b;
try {
return JSON.stringify(JSON.parse(a)) === JSON.stringify(JSON.parse(b));
} catch {
return a === b;
}
};
export const SinkProvider = () =>
Provider.effect(
Sink,
Effect.gen(function* () {
// `props` may be undefined at runtime — all SinkProps fields are
// optional, so callers can omit the props object entirely.
const createName = Effect.fn(function* (id: string, props: SinkProps | undefined) {
return props?.sinkName ?? (yield* createPhysicalName({ id }));
});
// Find a sink by name via the (small — quota is 1/region) list API.
const findByName = Effect.fn(function* (sinkName: string) {
const pages = yield* oam.listSinks.pages({}).pipe(Stream.runCollect);
return Array.from(pages)
.flatMap((page) => page.Items)
.find((item) => item.Name === sinkName);
});
return Sink.Provider.of({
stables: ["sinkName", "sinkArn", "sinkId"],
list: () =>
oam.listSinks.pages({}).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
page.Items.filter(
(item) => item.Name != null && item.Arn != null && item.Id != null,
).map((item) => ({
sinkName: item.Name!,
sinkArn: item.Arn!,
sinkId: item.Id!,
})),
),
),
),
read: Effect.fn(function* ({ id, olds, output }) {
const sinkName = output?.sinkName ?? (yield* createName(id, olds ?? {}));
const found = output?.sinkArn
? yield* oam
.getSink({ Identifier: output.sinkArn })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined))
: yield* findByName(sinkName);
if (!found?.Arn) return undefined;
const attrs = {
sinkName: found.Name ?? sinkName,
sinkArn: found.Arn,
sinkId: found.Id!,
};
const tags = yield* readOamTags(found.Arn);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return undefined;
const oldName = yield* createName(id, olds);
const newName = yield* createName(id, news);
if (oldName !== newName) return { action: "replace" } as const;
return undefined;
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const sinkName = output?.sinkName ?? (yield* createName(id, news));
// OBSERVE — cloud state is authoritative; `output` is only an
// identifier cache. A cached ARN that no longer resolves falls
// through to "missing".
let live = output?.sinkArn
? yield* oam
.getSink({ Identifier: output.sinkArn })
.pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined))
: yield* findByName(sinkName);
// ENSURE — create when missing; a ConflictException means a peer
// created the same-named sink concurrently, so re-observe.
if (live?.Arn == null) {
live = yield* retryOamMutation(
oam.createSink({ Name: sinkName, Tags: news?.tags }),
).pipe(Effect.catchTag("ConflictException", () => findByName(sinkName)));
}
const sinkArn = live!.Arn!;
const sinkId = live!.Id!;
// SYNC policy — diff the OBSERVED sink policy against the desired
// document and put only on change. There is no delete-policy API,
// so an absent `policy` prop leaves the current policy untouched.
const desiredPolicy = news?.policy;
if (desiredPolicy !== undefined) {
const desired = toPolicyString(desiredPolicy);
const observed = yield* oam.getSinkPolicy({ SinkIdentifier: sinkArn }).pipe(
Effect.map((r) => r.Policy),
Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
);
if (!samePolicy(observed, desired)) {
yield* retryOamMutation(
oam.putSinkPolicy({
SinkIdentifier: sinkArn,
Policy: desired,
}),
);
}
}
// SYNC tags — against observed cloud tags (adoption-safe).
yield* syncOamTags(sinkArn, id, news?.tags);
yield* session.note(sinkArn);
return { sinkName, sinkArn, sinkId };
}),
delete: Effect.fn(function* ({ output }) {
yield* deleteSinkAndWait(output.sinkArn);
}),
});
}),
);