import * as ecs from "@distilled.cloud/aws/ecs";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Stream from "effect/Stream";
import { AWSEnvironment, type AccountID } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
export type CapacityProviderName = string;
export type CapacityProviderArn =
`arn:aws:ecs:${RegionID}:${AccountID}:capacity-provider/${CapacityProviderName}`;
export interface CapacityProviderProps {
/**
* Capacity provider name. If omitted, a deterministic name is generated;
* a generated name that would begin with a reserved prefix gets `cp-`
* prepended.
*
* Names beginning with `aws`, `ecs`, or `fargate` are reserved by AWS.
* Changing this triggers a replacement.
*/
name?: string;
/**
* ARN of the EC2 Auto Scaling Group that backs this capacity provider.
*
* Cannot be changed after creation; changing this triggers a replacement.
*/
autoScalingGroupArn: Input<string>;
/**
* Managed scaling configuration applied by ECS to the underlying ASG.
*/
managedScaling?: ecs.ManagedScaling;
/**
* Whether ECS protects in-use container instances from ASG scale-in.
* @default "DISABLED"
*/
managedTerminationProtection?: ecs.ManagedTerminationProtection;
/**
* Whether ECS sets container instances to DRAINING when terminated by ASG.
* @default "DISABLED"
*/
managedDraining?: ecs.ManagedDraining;
/**
* User-defined tags to apply to the capacity provider.
*/
tags?: Record<string, string>;
}
export interface CapacityProvider extends Resource<
"AWS.ECS.CapacityProvider",
CapacityProviderProps,
{
/** The ARN of the capacity provider. */
capacityProviderArn: CapacityProviderArn;
/** The name of the capacity provider. */
name: CapacityProviderName;
/** The current status, e.g. `ACTIVE`. */
status: ecs.CapacityProviderStatus;
/** The status of the most recent update to the provider. */
updateStatus: ecs.CapacityProviderUpdateStatus | undefined;
/** The Auto Scaling group backing the provider. */
autoScalingGroupArn: string;
/** The managed scaling configuration. */
managedScaling: ecs.ManagedScaling | undefined;
/** Whether managed termination protection is enabled. */
managedTerminationProtection: ecs.ManagedTerminationProtection | undefined;
/** Whether managed instance draining is enabled. */
managedDraining: ecs.ManagedDraining | undefined;
/** The tags attached to the capacity provider. */
tags: Record<string, string>;
},
never,
Providers
> {}
/**
* An Amazon ECS capacity provider backed by an EC2 Auto Scaling Group.
*
* Capacity providers are associated with one or more ECS clusters via
* {@link Cluster#capacityProviders} and are referenced by a service or task's
* capacity provider strategy.
*
* Only EC2 Auto Scaling Group-backed capacity providers are currently
* supported. The reserved AWS providers `FARGATE` and `FARGATE_SPOT` do not
* need to be created and can be referenced by name on a `Cluster` directly.
* ### Creating Capacity Providers
* **Example:** ASG-Backed Capacity Provider
* ```typescript
* const provider = yield* CapacityProvider("AppCapacityProvider", {
* autoScalingGroupArn: asg.autoScalingGroupArn,
* managedScaling: {
* status: "ENABLED",
* targetCapacity: 80,
* minimumScalingStepSize: 1,
* maximumScalingStepSize: 10,
* },
* managedTerminationProtection: "ENABLED",
* });
*
* yield* Cluster("AppCluster", {
* capacityProviders: [provider.name],
* defaultCapacityProviderStrategy: [
* { capacityProvider: provider.name, weight: 1 },
* ],
* });
* ```
*
* ### Adopting Existing Capacity Providers
* Foreign-tagged capacity providers (i.e. providers that exist in AWS but were
* not created by this stack/stage/logical-id) are surfaced as `Unowned` by
* `read`, and the engine fails with `OwnedBySomeoneElse` unless adoption is
* explicitly opted in via `--adopt` or {@link adopt}.
* **Example:** Adopt an existing provider
* ```typescript
* import { adopt } from "alchemy/AdoptPolicy";
*
* yield* CapacityProvider("AppCapacityProvider", {
* name: "existing-provider",
* autoScalingGroupArn: asg.autoScalingGroupArn,
* }).pipe(adopt());
* ```
*
* @resource
*/
export const CapacityProvider = Resource<CapacityProvider>("AWS.ECS.CapacityProvider");
export const CapacityProviderProvider = () =>
Provider.effect(
CapacityProvider,
Effect.gen(function* () {
const toEcsTags = (tags: Record<string, string>): ecs.Tag[] =>
Object.entries(tags).map(([key, value]) => ({ key, value }));
const fromEcsTags = (tags: ecs.Tag[] | undefined): Record<string, string> =>
Object.fromEntries(
(tags ?? [])
.filter(
(t): t is { key: string; value: string } =>
t.key !== undefined && t.value !== undefined,
)
.map((t) => [t.key, t.value]),
);
const toName = (id: string, props: { name?: string } = {}) =>
props.name
? Effect.succeed(props.name)
: createPhysicalName({ id, maxLength: 252, lowercase: true }).pipe(
// AWS rejects generated names that start with a reserved prefix
// (e.g. a stack named "AWS-...").
Effect.map((name) => (/^(aws|ecs|fargate)/.test(name) ? `cp-${name}` : name)),
);
const describe = (name: string) =>
ecs
.describeCapacityProviders({
capacityProviders: [name],
include: ["TAGS"],
})
.pipe(
// A deleted provider stays describable as INACTIVE for a while
// and can no longer be updated, so treat it as missing.
Effect.map((res) =>
res.capacityProviders?.find((p) => p.name === name && p.status !== "INACTIVE"),
),
);
return {
stables: ["capacityProviderArn", "name"],
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return;
const oldName = yield* toName(id, olds ?? {});
const newName = yield* toName(id, news);
if (oldName !== newName) {
return { action: "replace" } as const;
}
if (
isResolved(olds.autoScalingGroupArn) &&
olds.autoScalingGroupArn !== news.autoScalingGroupArn
) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const name = output?.name ?? (yield* toName(id, olds ?? {}));
const found = yield* describe(name);
if (!found?.name || !found.capacityProviderArn) {
return undefined;
}
const internalTags = yield* createInternalTags(id);
const existingTags = fromEcsTags(found.tags);
const attrs = {
capacityProviderArn: found.capacityProviderArn as CapacityProviderArn,
name: found.name,
status: (found.status ?? "ACTIVE") as ecs.CapacityProviderStatus,
updateStatus: found.updateStatus,
autoScalingGroupArn: found.autoScalingGroupProvider?.autoScalingGroupArn ?? "",
managedScaling: found.autoScalingGroupProvider?.managedScaling,
managedTerminationProtection:
found.autoScalingGroupProvider?.managedTerminationProtection,
managedDraining: found.autoScalingGroupProvider?.managedDraining,
tags: existingTags,
};
return hasTags(internalTags, existingTags) ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news, session }) {
const { accountId, region } = yield* AWSEnvironment.current;
const name = yield* toName(id, news);
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...internalTags, ...news.tags };
const autoScalingGroupArn = news.autoScalingGroupArn as string;
// Observe — fetch live cloud state. We fetch fresh on every
// reconcile so adoption, drift, and partial-prior-runs all
// converge.
let existing = yield* describe(name);
// Ensure — create the capacity provider if missing.
if (!existing?.name || !existing.capacityProviderArn) {
yield* ecs
.createCapacityProvider({
name,
autoScalingGroupProvider: {
autoScalingGroupArn,
managedScaling: news.managedScaling,
managedTerminationProtection: news.managedTerminationProtection,
managedDraining: news.managedDraining,
},
tags: toEcsTags(desiredTags),
})
.pipe(
// ECS may surface concurrent creation either as
// `LimitExceededException` or a generic `ClientException`
// with name conflict semantics — re-describe and continue.
Effect.catchTag("LimitExceededException", () => Effect.void),
);
existing = yield* describe(name);
}
const capacityProviderArn = (existing?.capacityProviderArn ??
`arn:aws:ecs:${region}:${accountId}:capacity-provider/${name}`) as CapacityProviderArn;
// Sync managed scaling — observed ↔ desired. ECS
// updateCapacityProvider only mutates managed* fields; ASG ARN is
// immutable (replacement-triggering, handled in diff).
yield* ecs.updateCapacityProvider({
name,
autoScalingGroupProvider: {
managedScaling: news.managedScaling,
managedTerminationProtection: news.managedTerminationProtection,
managedDraining: news.managedDraining,
},
});
// Sync tags — diff observed cloud tags against desired.
const observedTags = fromEcsTags(existing?.tags);
const { removed, upsert } = diffTags(observedTags, desiredTags);
if (upsert.length > 0) {
yield* ecs.tagResource({
resourceArn: capacityProviderArn,
tags: upsert.map((t) => ({ key: t.Key, value: t.Value })),
});
}
if (removed.length > 0) {
yield* ecs.untagResource({
resourceArn: capacityProviderArn,
tagKeys: removed,
});
}
// Re-read to capture status / updateStatus reflecting our changes.
const found = yield* describe(name);
yield* session.note(capacityProviderArn);
return {
capacityProviderArn,
name,
status: (found?.status ?? "ACTIVE") as ecs.CapacityProviderStatus,
updateStatus: found?.updateStatus,
autoScalingGroupArn:
found?.autoScalingGroupProvider?.autoScalingGroupArn ?? autoScalingGroupArn,
managedScaling: found?.autoScalingGroupProvider?.managedScaling ?? news.managedScaling,
managedTerminationProtection:
found?.autoScalingGroupProvider?.managedTerminationProtection ??
news.managedTerminationProtection,
managedDraining:
found?.autoScalingGroupProvider?.managedDraining ?? news.managedDraining,
tags: desiredTags,
};
}),
list: () =>
Effect.gen(function* () {
// Enumerate every capacity provider in the account/region.
// `describeCapacityProviders` with no filter returns all providers
// and paginates via `nextToken`; it is a plain operation (no
// `.pages`), so drive the pagination with `Stream.paginate`.
const all = yield* Stream.paginate(undefined as string | undefined, (token) =>
ecs
.describeCapacityProviders({
include: ["TAGS"],
...(token ? { nextToken: token } : {}),
})
.pipe(
Effect.map(
(res) =>
[
res.capacityProviders ?? [],
res.nextToken ? Option.some(res.nextToken) : Option.none<string>(),
] as const,
),
),
).pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk)),
);
return all
.filter(
(
p,
): p is ecs.CapacityProvider & {
name: string;
capacityProviderArn: string;
} =>
p.name != null &&
p.capacityProviderArn != null &&
// FARGATE / FARGATE_SPOT are AWS-managed reserved providers
// that this resource does not create or own.
p.name !== "FARGATE" &&
p.name !== "FARGATE_SPOT",
)
.map((p) => ({
capacityProviderArn: p.capacityProviderArn as CapacityProviderArn,
name: p.name,
status: (p.status ?? "ACTIVE") as ecs.CapacityProviderStatus,
updateStatus: p.updateStatus,
autoScalingGroupArn: p.autoScalingGroupProvider?.autoScalingGroupArn ?? "",
managedScaling: p.autoScalingGroupProvider?.managedScaling,
managedTerminationProtection:
p.autoScalingGroupProvider?.managedTerminationProtection,
managedDraining: p.autoScalingGroupProvider?.managedDraining,
tags: fromEcsTags(p.tags),
}));
}),
delete: Effect.fn(function* ({ output }) {
yield* ecs.deleteCapacityProvider({ capacityProvider: output.name }).pipe(
// Already gone — treat as success.
Effect.catchTags({
InvalidParameterException: () => Effect.void,
ClientException: () => Effect.void,
}),
);
}),
};
}),
);