import * as Lambda from "@distilled.cloud/aws/lambda";
import { deepEqual, 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 * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { AWSEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import {
observeEventInvokeConfig,
syncEventInvokeConfig,
type EventInvokeConfig,
type ObservedEventInvokeConfig,
} from "./EventInvokeConfig.ts";
import type { Version } from "./Version.ts";
export interface AliasProps {
/**
* Managed Lambda version that this alias invokes.
*/
version: Version;
/**
* Name of the alias. If omitted, a unique name is generated.
*/
aliasName?: string;
/**
* Description of the alias.
*/
description?: string;
/**
* Weighted routing configuration for shifting traffic to an additional
* function version.
*/
routingConfig?: Lambda.AliasRoutingConfiguration;
/**
* Asynchronous invocation settings (retries, event age, destinations)
* scoped to this alias. Omit to remove any existing alias-level config and
* fall back to Lambda's defaults (2 retries, 6-hour max event age, no
* destinations).
*/
eventInvokeConfig?: EventInvokeConfig;
}
export interface Alias extends Resource<
"AWS.Lambda.Alias",
AliasProps,
{
/**
* ARN of the Lambda alias.
*/
aliasArn: string;
/**
* Name of the alias.
*/
aliasName: string;
/**
* Name or ARN of the Lambda function this alias belongs to.
*/
functionName: string;
/**
* Lambda function version that this alias invokes.
*/
functionVersion: string;
/**
* API Gateway-compatible invocation ARN for this alias.
*/
invokeArn: string;
/**
* Description of the alias.
*/
description?: string;
/**
* Weighted routing configuration for this alias.
*/
routingConfig?: Lambda.AliasRoutingConfiguration;
/**
* Latest Lambda revision id for this alias.
*/
revisionId?: string;
/**
* Asynchronous invocation config (retries, maximum event age,
* destinations) scoped to the alias, as observed. Lets `alchemy drift`
* detect out-of-band changes.
*/
eventInvokeConfig?: ObservedEventInvokeConfig;
},
never,
Providers
> {}
type ResolvedAliasProps = Input.ResolveProps<AliasProps>;
const resolvedProps = (props: AliasProps): ResolvedAliasProps =>
props as unknown as ResolvedAliasProps;
/**
* A Lambda alias for routing invocations to a stable function version.
*
* ### Creating Aliases
* **Example:** Production Alias
* ```typescript
* const version = yield* Version("ProductionVersion", { function: fn });
* const alias = yield* Alias("ProductionAlias", {
* version,
* aliasName: "production",
* });
* ```
*
* ### Weighted Routing
* **Example:** Shift Traffic to Another Version
* ```typescript
* const version = yield* Version("LiveVersion", { function: fn });
* const alias = yield* Alias("LiveAlias", {
* version,
* aliasName: "live",
* routingConfig: {
* AdditionalVersionWeights: {
* "3": 0.1,
* },
* },
* });
* ```
*
* ### Async Invocation
* **Example:** Alias-Scoped Retry Behavior
* ```typescript
* const version = yield* Version("LiveVersion", { function: fn });
* const alias = yield* Alias("LiveAlias", {
* version,
* aliasName: "live",
* eventInvokeConfig: {
* maximumRetryAttempts: 0,
* destinationConfig: {
* OnFailure: {
* Destination: queue.queueArn,
* },
* },
* },
* });
* ```
*/
export const Alias = Resource<Alias>("AWS.Lambda.Alias");
const normalizeRoutingConfig = (
config: Lambda.AliasRoutingConfiguration | undefined,
): Lambda.AliasRoutingConfiguration | undefined => {
const weights = Object.fromEntries(
Object.entries(config?.AdditionalVersionWeights ?? {}).filter(
(entry): entry is [string, number] => entry[1] !== undefined,
),
);
return Object.keys(weights).length > 0 ? { AdditionalVersionWeights: weights } : undefined;
};
export const AliasProvider = () =>
Provider.effect(
Alias,
Effect.gen(function* () {
const createAliasName = (id: string, aliasName?: string) =>
aliasName
? Effect.succeed(aliasName)
: createPhysicalName({
id,
maxLength: 128,
delimiter: "-",
});
const retryOnAliasConflict = <A, E extends { _tag: string }, R>(
effect: Effect.Effect<A, E, R>,
) =>
effect.pipe(
Effect.retry({
while: (e) => e._tag === "ResourceConflictException",
schedule: Schedule.max([Schedule.exponential(500), Schedule.recurs(10)]),
}),
);
const snapshotAlias = (
functionName: string,
alias: Lambda.AliasConfiguration,
region: string,
): Alias["Attributes"] | undefined => {
if (!alias.AliasArn || !alias.Name || !alias.FunctionVersion) {
return undefined;
}
return {
aliasArn: alias.AliasArn,
aliasName: alias.Name,
functionName,
functionVersion: alias.FunctionVersion,
invokeArn: `arn:aws:apigateway:${region}:lambda:path/2015-03-31/functions/${alias.AliasArn}/invocations`,
description: alias.Description || undefined,
routingConfig: normalizeRoutingConfig(alias.RoutingConfig),
revisionId: alias.RevisionId,
};
};
return {
stables: ["aliasArn", "aliasName", "functionName"],
diff: Effect.fn(function* ({ id, olds, news }) {
if (!isResolved(news)) return;
const resolvedOlds = resolvedProps(olds);
const resolvedNews = resolvedProps(news);
// An interrupted create persists the Version reference as missing
// (see stripUnresolved); there is no old function to compare.
if (resolvedOlds.version === undefined) return;
const oldAliasName = yield* createAliasName(id, resolvedOlds.aliasName);
const newAliasName = yield* createAliasName(id, resolvedNews.aliasName);
if (
resolvedOlds.version.functionName !== resolvedNews.version.functionName ||
oldAliasName !== newAliasName
) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
// An interrupted create's first checkpoint strips the Version
// reference while the Version is still being created (see
// stripUnresolved), so `olds.version` can be missing.
const functionName =
output?.functionName ?? (olds ? resolvedProps(olds).version?.functionName : undefined);
if (!functionName) return undefined;
const aliasName =
output?.aliasName ??
(yield* createAliasName(id, olds ? resolvedProps(olds).aliasName : undefined));
const { region } = yield* AWSEnvironment.current;
const alias = yield* Lambda.getAlias({
FunctionName: functionName,
Name: aliasName,
}).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
const attrs = alias ? snapshotAlias(functionName, alias, region) : undefined;
if (!attrs) return undefined;
return {
...attrs,
eventInvokeConfig: yield* observeEventInvokeConfig(functionName, attrs.aliasName),
};
}),
list: () =>
Effect.gen(function* () {
const { region } = yield* AWSEnvironment.current;
const functionNames = yield* Lambda.listFunctions.pages({}).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.Functions ?? [])
.map((fn) => fn.FunctionName)
.filter((name): name is string => name !== undefined),
),
),
);
const aliases = yield* Effect.forEach(
functionNames,
(functionName) =>
Lambda.listAliases.items({ FunctionName: functionName }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((alias) => {
const attrs = snapshotAlias(functionName, alias, region);
return attrs ? [attrs] : [];
}),
),
Effect.catchTag("ResourceNotFoundException", () =>
Effect.succeed([] as Alias["Attributes"][]),
),
),
{ concurrency: 10 },
);
return aliases.flat();
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const resolvedNews = resolvedProps(news);
const functionName = resolvedNews.version.functionName;
const functionVersion = resolvedNews.version.version;
const { region } = yield* AWSEnvironment.current;
const aliasName =
output?.aliasName ?? (yield* createAliasName(id, resolvedNews.aliasName));
const desiredRoutingConfig = normalizeRoutingConfig(resolvedNews.routingConfig);
const getAlias = Lambda.getAlias({
FunctionName: functionName,
Name: aliasName,
}).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
let alias = yield* getAlias;
if (!alias) {
alias = yield* Lambda.createAlias({
FunctionName: functionName,
Name: aliasName,
FunctionVersion: functionVersion,
Description: resolvedNews.description,
RoutingConfig: desiredRoutingConfig,
}).pipe(Effect.catchTag("ResourceConflictException", () => getAlias));
}
const observedRoutingConfig = normalizeRoutingConfig(alias?.RoutingConfig);
if (
!alias ||
alias.FunctionVersion !== functionVersion ||
(alias.Description || undefined) !== resolvedNews.description ||
!deepEqual(observedRoutingConfig, desiredRoutingConfig)
) {
alias = yield* retryOnAliasConflict(
Lambda.updateAlias({
FunctionName: functionName,
Name: aliasName,
FunctionVersion: functionVersion,
Description: resolvedNews.description ?? "",
RoutingConfig:
desiredRoutingConfig ??
(observedRoutingConfig ? { AdditionalVersionWeights: {} } : undefined),
}),
);
}
const attrs = snapshotAlias(functionName, alias, region);
if (!attrs) {
return yield* Effect.die(
`Lambda alias ${aliasName} did not return complete attributes.`,
);
}
yield* syncEventInvokeConfig({
functionName,
qualifier: attrs.aliasName,
config: resolvedNews.eventInvokeConfig,
});
yield* session.note(`Alias ${attrs.aliasName} on ${attrs.functionName}`);
return {
...attrs,
eventInvokeConfig: yield* observeEventInvokeConfig(functionName, attrs.aliasName),
};
}),
delete: Effect.fn(function* ({ output }) {
// The alias-scoped async config does not die with the alias — clear
// it first so a later alias of the same name starts clean.
yield* syncEventInvokeConfig({
functionName: output.functionName,
qualifier: output.aliasName,
config: undefined,
});
yield* retryOnAliasConflict(
Lambda.deleteAlias({
FunctionName: output.functionName,
Name: output.aliasName,
}),
).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}),
};
}),
);