import * as aas from "@distilled.cloud/aws/application-auto-scaling";
import * as cloudwatch from "@distilled.cloud/aws/cloudwatch";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { plainJson } from "../internal/Observe.ts";
import type { Providers } from "../Providers.ts";
import { SERVICE_NAMESPACES, retryWhileTargetPropagates } from "./internal.ts";
export interface ScalingPolicyProps {
/**
* Policy name. If omitted, a deterministic name is generated.
*
* Changing this triggers a replacement.
*/
policyName?: string;
/**
* The namespace of the AWS service that provides the scalable target,
* e.g. `ecs`, `dynamodb`.
*
* Changing this triggers a replacement.
*/
serviceNamespace: aas.ServiceNamespace;
/**
* The identifier of the resource the policy's scalable target scales,
* e.g. `service/{clusterName}/{serviceName}` or `table/{tableName}`.
*
* Changing this triggers a replacement.
*/
resourceId: string;
/**
* The scalable dimension of the scalable target,
* e.g. `ecs:service:DesiredCount` or `dynamodb:table:ReadCapacityUnits`.
*
* Changing this triggers a replacement.
*/
scalableDimension: aas.ScalableDimension;
/**
* Target tracking configuration — track a predefined metric
* (e.g. `ECSServiceAverageCPUUtilization`) or a customized CloudWatch
* metric specification against a target value.
*
* Exactly one of `targetTracking` or `stepScaling` must be provided.
*/
targetTracking?: aas.TargetTrackingScalingPolicyConfiguration;
/**
* Step scaling configuration — apply step adjustments in response to a
* CloudWatch alarm you manage.
*
* Exactly one of `targetTracking` or `stepScaling` must be provided.
*/
stepScaling?: aas.StepScalingPolicyConfiguration;
}
export interface ScalingPolicy extends Resource<
"AWS.ApplicationAutoScaling.ScalingPolicy",
ScalingPolicyProps,
{
/**
* Name of the scaling policy.
*/
policyName: string;
/**
* ARN of the scaling policy.
*/
policyArn: string;
/**
* Namespace of the AWS service that provides the scalable target.
*/
serviceNamespace: aas.ServiceNamespace;
/**
* Identifier of the scaled resource.
*/
resourceId: string;
/**
* Scalable dimension the policy applies to.
*/
scalableDimension: aas.ScalableDimension;
/**
* Policy type (`TargetTrackingScaling` or `StepScaling`).
*/
policyType: aas.PolicyType;
/**
* CloudWatch alarms created and managed by Application Auto Scaling for
* a target tracking policy.
*/
alarms: { alarmName: string; alarmArn: string }[];
/**
* Target-tracking configuration, as observed. Lets `alchemy drift`
* detect out-of-band changes.
*/
targetTracking?: unknown;
/**
* Step-scaling configuration, as observed. Lets `alchemy drift` detect
* out-of-band changes.
*/
stepScaling?: unknown;
},
never,
Providers
> {}
/**
* An Application Auto Scaling scaling policy attached to a scalable target.
*
* Supports `TargetTrackingScaling` (Application Auto Scaling creates and
* manages the CloudWatch alarms) and `StepScaling` (you attach the policy to
* your own alarm). The policy applies to the scalable target identified by
* the (`serviceNamespace`, `resourceId`, `scalableDimension`) triple, which
* must be registered (see {@link ScalableTarget}) before the policy is
* created — pass the target's outputs so deployment orders correctly.
* ### Target Tracking
* **Example:** Track ECS Service CPU
* ```typescript
* const target = yield* ScalableTarget("ApiScaling", {
* serviceNamespace: "ecs",
* resourceId: Output.interpolate`service/${cluster.clusterName}/${service.serviceName}`,
* scalableDimension: "ecs:service:DesiredCount",
* minCapacity: 1,
* maxCapacity: 3,
* });
*
* yield* ScalingPolicy("ApiCpuPolicy", {
* serviceNamespace: target.serviceNamespace,
* resourceId: target.resourceId,
* scalableDimension: target.scalableDimension,
* targetTracking: {
* TargetValue: 60,
* PredefinedMetricSpecification: {
* PredefinedMetricType: "ECSServiceAverageCPUUtilization",
* },
* ScaleOutCooldown: 60,
* ScaleInCooldown: 60,
* },
* });
* ```
*
* **Example:** Track a Customized Metric
* ```typescript
* yield* ScalingPolicy("QueueDepthPolicy", {
* serviceNamespace: target.serviceNamespace,
* resourceId: target.resourceId,
* scalableDimension: target.scalableDimension,
* targetTracking: {
* TargetValue: 100,
* CustomizedMetricSpecification: {
* MetricName: "ApproximateNumberOfMessagesVisible",
* Namespace: "AWS/SQS",
* Dimensions: [{ Name: "QueueName", Value: "my-queue" }],
* Statistic: "Average",
* },
* },
* });
* ```
*
* ### Step Scaling
* **Example:** Step Adjustments
* ```typescript
* yield* ScalingPolicy("ApiStepPolicy", {
* serviceNamespace: target.serviceNamespace,
* resourceId: target.resourceId,
* scalableDimension: target.scalableDimension,
* stepScaling: {
* AdjustmentType: "ChangeInCapacity",
* Cooldown: 60,
* MetricAggregationType: "Average",
* StepAdjustments: [
* { MetricIntervalLowerBound: 0, ScalingAdjustment: 1 },
* ],
* },
* });
* ```
*
* @resource
*/
export const ScalingPolicy = Resource<ScalingPolicy>("AWS.ApplicationAutoScaling.ScalingPolicy");
/**
* Raised before any AWS call when a `ScalingPolicy` declares both or neither
* of `targetTracking` / `stepScaling` — the two configurations are mutually
* exclusive and exactly one is required.
*/
export class ScalingPolicyConfigurationConflict extends Data.TaggedError(
"ScalingPolicyConfigurationConflict",
)<{ message: string }> {}
const validateConfiguration = (props: {
targetTracking?: aas.TargetTrackingScalingPolicyConfiguration;
stepScaling?: aas.StepScalingPolicyConfiguration;
}) =>
(props.targetTracking === undefined) === (props.stepScaling === undefined)
? Effect.fail(
new ScalingPolicyConfigurationConflict({
message: "Exactly one of targetTracking or stepScaling must be provided.",
}),
)
: Effect.void;
export const ScalingPolicyProvider = () =>
Provider.effect(
ScalingPolicy,
Effect.gen(function* () {
const toName = (id: string, props: { policyName?: string } = {}) =>
props.policyName
? Effect.succeed(props.policyName)
: createPhysicalName({ id, maxLength: 255 });
// Narrow by the target triple only when it is complete: the API rejects
// a ScalableDimension without a ResourceId ("Scalable dimension cannot
// be provided without a resource ID"), and a row persisted by an
// interrupted create can carry one without the other — which would
// wedge `read` and therefore every destroy of the stack.
const describe = (props: {
serviceNamespace: aas.ServiceNamespace;
policyName: string;
resourceId?: string;
scalableDimension?: aas.ScalableDimension;
}) =>
aas
.describeScalingPolicies({
ServiceNamespace: props.serviceNamespace,
PolicyNames: [props.policyName],
...(props.resourceId !== undefined && props.scalableDimension !== undefined
? {
ResourceId: props.resourceId,
ScalableDimension: props.scalableDimension,
}
: {}),
})
.pipe(
Effect.map((res) =>
res.ScalingPolicies?.find((p) => p.PolicyName === props.policyName),
),
);
const toAttributes = (policy: aas.ScalingPolicy): ScalingPolicy["Attributes"] => ({
policyName: policy.PolicyName,
policyArn: policy.PolicyARN,
serviceNamespace: policy.ServiceNamespace,
resourceId: policy.ResourceId,
scalableDimension: policy.ScalableDimension,
policyType: policy.PolicyType,
alarms: (policy.Alarms ?? []).map((alarm) => ({
alarmName: alarm.AlarmName,
alarmArn: alarm.AlarmARN,
})),
targetTracking: plainJson(policy.TargetTrackingScalingPolicyConfiguration),
stepScaling: plainJson(policy.StepScalingPolicyConfiguration),
});
return {
stables: ["policyName", "policyArn", "serviceNamespace", "resourceId", "scalableDimension"],
// Account/region-wide enumeration; the describe API requires a
// `ServiceNamespace` filter, so union the per-namespace pages.
list: () =>
Effect.forEach(
SERVICE_NAMESPACES,
(namespace) =>
aas.describeScalingPolicies.pages({ ServiceNamespace: namespace }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.ScalingPolicies ?? []).map(toAttributes),
),
),
),
{ concurrency: 4 },
).pipe(Effect.map((groups) => groups.flat())),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return undefined;
const oldName = yield* toName(id, olds ?? {});
const newName = yield* toName(id, news);
if (oldName !== newName) {
return { action: "replace" } as const;
}
// The target triple pins the policy to a scalable target — any
// change replaces the policy. Only compare sides that are known:
// a half-created state row may have lost Output-valued props.
for (const key of ["serviceNamespace", "resourceId", "scalableDimension"] as const) {
const oldValue = olds?.[key];
if (oldValue !== undefined && isResolved(oldValue) && oldValue !== news[key]) {
return { action: "replace" } as const;
}
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const serviceNamespace = output?.serviceNamespace ?? olds?.serviceNamespace;
if (serviceNamespace === undefined) return undefined;
const policyName = output?.policyName ?? (yield* toName(id, olds ?? {}));
const policy = yield* describe({
serviceNamespace,
policyName,
resourceId: output?.resourceId ?? olds?.resourceId,
scalableDimension: output?.scalableDimension ?? olds?.scalableDimension,
});
return policy ? toAttributes(policy) : undefined;
}),
reconcile: Effect.fn(function* ({ id, news, session }) {
yield* validateConfiguration(news);
const policyName = yield* toName(id, news);
const policyType: aas.PolicyType = news.targetTracking
? "TargetTrackingScaling"
: "StepScaling";
// Ensure + sync — `putScalingPolicy` is the single
// create-or-update API, keyed by (name, target triple); it
// overwrites the policy configuration on every call, so one
// unconditional put converges any starting state. A put issued
// immediately after the target registers can race its
// propagation — retry the typed ObjectNotFoundException briefly.
yield* retryWhileTargetPropagates(
aas.putScalingPolicy({
PolicyName: policyName,
ServiceNamespace: news.serviceNamespace,
ResourceId: news.resourceId,
ScalableDimension: news.scalableDimension,
PolicyType: policyType,
TargetTrackingScalingPolicyConfiguration: news.targetTracking,
StepScalingPolicyConfiguration: news.stepScaling,
}),
);
// Observe final state so attributes carry the generated ARN and
// the CloudWatch alarms Application Auto Scaling manages.
const policy = yield* describe({
serviceNamespace: news.serviceNamespace,
policyName,
resourceId: news.resourceId,
scalableDimension: news.scalableDimension,
});
if (policy === undefined) {
return yield* aas.ObjectNotFoundException.make({
message: `Scaling policy '${policyName}' was not readable after PutScalingPolicy`,
});
}
yield* session.note(policy.PolicyARN);
return toAttributes(policy);
}),
// Deleting the parent scalable target implicitly deletes its
// policies, so a policy that is already gone (typed
// `ObjectNotFoundException`) is success.
delete: Effect.fn(function* ({ olds, output }) {
// Observe before deleting: resolve the live policy by name (a row
// persisted by an interrupted create can lack the target triple)
// and delete with ITS triple; a policy that no longer exists is
// already gone.
const policy = yield* describe({
serviceNamespace: output.serviceNamespace,
policyName: output.policyName,
resourceId: output.resourceId ?? olds?.resourceId,
scalableDimension: output.scalableDimension ?? olds?.scalableDimension,
});
if (policy?.ResourceId && policy.ScalableDimension) {
yield* aas
.deleteScalingPolicy({
PolicyName: output.policyName,
ServiceNamespace: output.serviceNamespace,
ResourceId: policy.ResourceId,
ScalableDimension: policy.ScalableDimension,
})
.pipe(Effect.catchTag("ObjectNotFoundException", () => Effect.void));
}
// Reap the managed CloudWatch alarms of a target tracking policy.
// Application Auto Scaling deletes them asynchronously (and not at
// all when the policy went away via target deregistration), so an
// explicit delete keeps teardown deterministic. DeleteAlarms
// ignores names that no longer exist.
const alarms = [
...(output.alarms ?? []).map((alarm) => alarm.alarmName),
...(policy?.Alarms ?? []).map((alarm) => alarm.AlarmName),
].filter((name, i, all) => all.indexOf(name) === i);
if (alarms.length > 0) {
yield* cloudwatch
.deleteAlarms({ AlarmNames: alarms })
.pipe(Effect.catchTag("ResourceNotFound", () => Effect.void));
}
}),
};
}),
);