import * as config from "@distilled.cloud/aws/config-service";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import type { Providers } from "../Providers.ts";
export interface DeliveryChannelProps {
/**
* Name of the delivery channel. AWS allows only ONE delivery channel per
* account per region. Changing the name replaces the channel.
* @default ${app}-${stage}-${id}
*/
name?: string;
/**
* Name of the S3 bucket AWS Config delivers configuration snapshots and
* history files to. The bucket needs a policy granting
* `config.amazonaws.com` `s3:GetBucketAcl` on the bucket and
* `s3:PutObject` on `arn:aws:s3:::{bucket}/AWSLogs/{account}/Config/*`.
*/
s3BucketName: string;
/**
* Key prefix for the delivered objects.
*/
s3KeyPrefix?: string;
/**
* ARN of the KMS key AWS Config uses to encrypt objects delivered to the
* S3 bucket.
*/
s3KmsKeyArn?: string;
/**
* ARN of the SNS topic AWS Config sends notifications to.
*/
snsTopicArn?: string;
/**
* How often AWS Config delivers configuration snapshots to the bucket.
*/
snapshotDeliveryFrequency?:
| "One_Hour"
| "Three_Hours"
| "Six_Hours"
| "Twelve_Hours"
| "TwentyFour_Hours";
}
export interface DeliveryChannel extends Resource<
"AWS.Config.DeliveryChannel",
DeliveryChannelProps,
{
/** Physical name of the delivery channel. */
deliveryChannelName: string;
/** S3 bucket configuration snapshots and history are delivered to. */
s3BucketName: string;
},
never,
Providers
> {}
/**
* The AWS Config delivery channel that delivers configuration snapshots and
* configuration history to an S3 bucket (and optionally notifies an SNS
* topic).
*
* AWS allows only **one** delivery channel per account per region — treat
* this resource as an account-region singleton. A configuration recorder
* must exist before the channel can be created (see
* `AWS.Config.ConfigurationRecorder`).
* ### Creating the Channel
* **Example:** Deliver configuration history to S3
* ```typescript
* import * as Config from "@alchemy.run/aws/Config";
*
* const channel = yield* Config.DeliveryChannel("Channel", {
* s3BucketName: bucket.bucketName,
* });
* ```
*
* **Example:** Periodic snapshots with a key prefix
* ```typescript
* const channel = yield* Config.DeliveryChannel("Channel", {
* s3BucketName: bucket.bucketName,
* s3KeyPrefix: "config",
* snapshotDeliveryFrequency: "TwentyFour_Hours",
* });
* ```
*
* @resource
*/
export const DeliveryChannel = Resource<DeliveryChannel>("AWS.Config.DeliveryChannel");
/**
* `PutDeliveryChannel` validates the recorder's existence and the bucket
* policy at call time. A recorder or bucket policy created in the same
* deploy can take a few seconds to become visible, surfacing as
* `NoAvailableConfigurationRecorderException` /
* `InsufficientDeliveryPolicyException` / `NoSuchBucketException` — retry
* on a bounded schedule (~40s).
*
* Explicitly typed: inlining `Effect.retry` with options in provider
* lifecycle code can widen the provider layer to `unknown` in declaration
* emit.
*
* @internal
*/
const retryChannelPut = <A, E extends { readonly _tag: string }, R>(
self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
Effect.retry(self, {
while: (e) =>
e._tag === "NoAvailableConfigurationRecorderException" ||
e._tag === "InsufficientDeliveryPolicyException" ||
e._tag === "NoSuchBucketException",
schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(20)]),
});
/**
* Deleting the channel while the recorder is still running (or while the
* recorder is being stopped/deleted concurrently by the same destroy)
* rejects with `LastDeliveryChannelDeleteFailedException` — a dependency
* violation, retried on a bounded schedule (~40s).
* @internal
*/
const retryChannelDelete = <A, E extends { readonly _tag: string }, R>(
self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
Effect.retry(self, {
while: (e) => e._tag === "LastDeliveryChannelDeleteFailedException",
schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(20)]),
});
export const DeliveryChannelProvider = () =>
Provider.effect(
DeliveryChannel,
Effect.gen(function* () {
const createChannelName = Effect.fn(function* (
id: string,
props: Pick<DeliveryChannelProps, "name">,
) {
return props.name ?? (yield* createPhysicalName({ id, maxLength: 256 }));
});
const toWireChannel = (
name: string,
props: DeliveryChannelProps,
): config.DeliveryChannel => ({
name,
s3BucketName: props.s3BucketName,
s3KeyPrefix: props.s3KeyPrefix,
s3KmsKeyArn: props.s3KmsKeyArn,
snsTopicARN: props.snsTopicArn,
configSnapshotDeliveryProperties:
props.snapshotDeliveryFrequency === undefined
? undefined
: { deliveryFrequency: props.snapshotDeliveryFrequency },
});
const observeChannel = Effect.fn(function* (name: string) {
const response = yield* config
.describeDeliveryChannels({ DeliveryChannelNames: [name] })
.pipe(
Effect.catchTag("NoSuchDeliveryChannelException", () =>
Effect.succeed({ DeliveryChannels: [] }),
),
);
return (response.DeliveryChannels ?? []).at(0);
});
return DeliveryChannel.Provider.of({
stables: ["deliveryChannelName"],
list: () =>
config.describeDeliveryChannels({}).pipe(
Effect.map((response) =>
(response.DeliveryChannels ?? []).flatMap((channel) =>
channel.name && channel.s3BucketName
? [
{
deliveryChannelName: channel.name,
s3BucketName: channel.s3BucketName,
},
]
: [],
),
),
),
// Delivery channels are not taggable, so there is no ownership
// marker to check — an existing channel with our derived name is
// treated as ours.
read: Effect.fn(function* ({ id, olds, output }) {
const name = output?.deliveryChannelName ?? (yield* createChannelName(id, olds ?? {}));
const channel = yield* observeChannel(name);
if (channel?.name === undefined) return undefined;
return {
deliveryChannelName: channel.name,
s3BucketName: channel.s3BucketName!,
};
}),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return undefined;
const oldName = yield* createChannelName(id, olds ?? {});
const newName = yield* createChannelName(id, news);
if (oldName !== newName) {
return { action: "replace" } as const;
}
// fall through: engine default update logic for mutable fields
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const name = output?.deliveryChannelName ?? (yield* createChannelName(id, news));
const desired = toWireChannel(name, news);
// 1. OBSERVE — cloud state is authoritative.
const observed = yield* observeChannel(name);
// 2+3. ENSURE + SYNC — PutDeliveryChannel is a full upsert; apply
// when missing or when any declared aspect drifted. Comparing
// the full wire shape is safe here: AWS echoes exactly the
// members that were put (no server-side defaults).
const inSync =
observed !== undefined &&
observed.s3BucketName === desired.s3BucketName &&
(observed.s3KeyPrefix ?? undefined) === desired.s3KeyPrefix &&
(observed.s3KmsKeyArn ?? undefined) === desired.s3KmsKeyArn &&
(observed.snsTopicARN ?? undefined) === desired.snsTopicARN &&
(observed.configSnapshotDeliveryProperties?.deliveryFrequency ?? undefined) ===
desired.configSnapshotDeliveryProperties?.deliveryFrequency;
if (!inSync) {
yield* retryChannelPut(config.putDeliveryChannel({ DeliveryChannel: desired }));
}
yield* session.note(name);
return {
deliveryChannelName: name,
s3BucketName: news.s3BucketName,
};
}),
delete: Effect.fn(function* ({ output }) {
yield* retryChannelDelete(
config.deleteDeliveryChannel({
DeliveryChannelName: output.deliveryChannelName,
}),
).pipe(Effect.catchTag("NoSuchDeliveryChannelException", () => Effect.void));
}),
});
}),
);