import * as Lambda from "@distilled.cloud/aws/lambda";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import * as Provider from "alchemy/Provider";
import { Resource, type ResourceClassLike } from "alchemy/Resource";
import { Stack } from "alchemy/Stack";
import { Stage } from "alchemy/Stage";
import { sha256Object } from "alchemy/Util/sha256";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import type { Function } from "./Function.ts";
export interface VersionProps {
/**
* Managed Lambda function whose current code and versioned configuration
* should be published.
*/
function: Function;
}
type VersionAttributes = {
/**
* Name of the Lambda function this version belongs to.
*/
functionName: string;
/**
* Unqualified ARN of the Lambda function.
*/
functionArn: string;
/**
* Immutable version number assigned by Lambda, represented as a string.
*/
version: string;
/**
* ARN qualified with this immutable version number.
*/
versionArn: string;
/**
* Secret-safe fingerprint of the function ARN, code, and versioned
* configuration.
*/
sourceHash: string;
/**
* Base64-encoded SHA-256 of the published function code, as reported by
* Lambda.
*/
codeSha256: string;
/**
* SHA-256 of the post-binding, versioned Lambda configuration. Secret values
* contribute to this digest but are never stored in state.
*/
configSha256: string;
};
export interface Version extends Resource<
"AWS.Lambda.Version",
VersionProps,
VersionAttributes,
never,
Providers
> {}
interface VersionResourceProps extends VersionProps {
/**
* Internal dependency on a non-stable Function attribute. Its value is not
* the release identity; it prevents publication from racing a Function
* update whose publishable configuration has not settled yet.
*/
deploymentHash: string;
}
interface VersionResource extends Resource<
"AWS.Lambda.Version",
VersionResourceProps,
VersionAttributes,
never,
Providers
> {}
type ResolvedVersionProps = Input.ResolveProps<VersionResourceProps>;
/**
* Resource references resolve to their Attributes before provider lifecycle
* methods run. Provider's generic Props type intentionally preserves the
* author-facing resource type, so expose that engine guarantee in one place.
*/
const resolvedProps = (props: VersionResourceProps): ResolvedVersionProps =>
props as unknown as ResolvedVersionProps;
const VersionResource = Resource<VersionResource>("AWS.Lambda.Version", {
defaultRemovalPolicy: "retain",
});
export interface VersionClass extends ResourceClassLike<Version> {
(id: string, props: { function: Function }): Effect.Effect<Version, never, Providers>;
ref(id: string, options?: { stage?: string; stack?: string }): Effect.Effect<Version>;
}
/**
* An immutable numbered version of a managed Lambda function.
*
* The provider publishes only after the Function's code and configuration
* have settled. Re-applying unchanged code and versioned configuration reuses
* the existing version. Function-level operational changes, such as reserved
* concurrency, do not publish a new version.
*
* Versions default to **retain** on removal. Moving or deleting an alias never
* deletes an older version, so in-flight durable executions can continue
* replaying against the code that started them. Use `destroy()` only when the
* exact numbered version is safe to remove.
*
* ### Publishing a Version
* **Example:** Publish a Managed Function
* ```typescript
* const fn = yield* AWS.Lambda.Function("Handler", {
* main: import.meta.resolve("./handler.ts"),
* });
* const version = yield* AWS.Lambda.Version("HandlerVersion", {
* function: fn,
* });
* ```
*
* ### Promoting with an Alias
* **Example:** Stable Production Alias
* ```typescript
* const version = yield* AWS.Lambda.Version("CampaignRunVersion", {
* function: campaign.function,
* });
* const live = yield* AWS.Lambda.Alias("CampaignRunLive", {
* version,
* aliasName: "live",
* });
* ```
*
* ### Explicit Deletion
* **Example:** Delete the Exact Version on Stack Destroy
* ```typescript
* import { destroy } from "alchemy/RemovalPolicy";
*
* const disposable = yield* AWS.Lambda.Version("PreviewVersion", {
* function: fn,
* }).pipe(destroy());
* ```
*
* @resource
*/
export const Version = Object.assign(
(id: string, props: VersionProps) =>
VersionResource(id, {
function: props.function,
deploymentHash: props.function.code.hash,
}) as unknown as Effect.Effect<Version, never, Providers>,
{
Type: VersionResource.Type,
Provider: VersionResource.Provider,
Self: VersionResource.Self,
Aliases: VersionResource.Aliases,
ref: ((id, options) => VersionResource.ref(id, options)) as VersionClass["ref"],
},
) as unknown as VersionClass;
interface VersionMarker {
ownerHash: string;
instanceHash: string;
sourceHash: string;
}
const MARKER_RE = /^\[alchemy:v=1;o=([a-f0-9]{64});i=([a-f0-9]{64});s=([a-f0-9]{64})\]$/;
const parseMarker = (description: string | undefined): VersionMarker | undefined => {
const match = description?.match(MARKER_RE);
return match
? {
ownerHash: match[1],
instanceHash: match[2],
sourceHash: match[3],
}
: undefined;
};
const isNumberedVersion = (version: string | undefined): version is string =>
version !== undefined && /^[1-9]\d*$/.test(version);
export const VersionProvider = () =>
Provider.effect(
VersionResource,
Effect.gen(function* () {
const ownerIdentity = Effect.fn(function* (id: string, fqn: string, instanceId: string) {
const stack = yield* Stack;
const stage = yield* Stage;
return {
ownerHash: yield* sha256Object({
stack: stack.name,
stage,
fqn,
id,
}),
instanceHash: yield* sha256Object({ instanceId }),
};
});
const sourceHashOf = (functionArn: string, codeSha256: string, configSha256: string) =>
sha256Object({
functionArn,
codeSha256,
configSha256,
});
const markerFor = Effect.fn(function* (
id: string,
fqn: string,
instanceId: string,
sourceHash: string,
) {
const identity = yield* ownerIdentity(id, fqn, instanceId);
return {
...identity,
sourceHash,
description: `[alchemy:v=1;o=${identity.ownerHash};i=${identity.instanceHash};s=${sourceHash}]`,
};
});
const publishableConfiguration = (configuration: Lambda.FunctionConfiguration) => ({
runtime: configuration.Runtime,
role: configuration.Role,
handler: configuration.Handler,
timeout: configuration.Timeout,
memorySize: configuration.MemorySize,
vpc: configuration.VpcConfig
? {
subnetIds: [...(configuration.VpcConfig.SubnetIds ?? [])].sort(),
securityGroupIds: [...(configuration.VpcConfig.SecurityGroupIds ?? [])].sort(),
ipv6AllowedForDualStack: configuration.VpcConfig.Ipv6AllowedForDualStack,
}
: undefined,
deadLetterConfig: configuration.DeadLetterConfig,
environment: Object.fromEntries(
Object.entries(configuration.Environment?.Variables ?? {}).map(([key, value]) => [
key,
Redacted.isRedacted(value) ? Redacted.value(value) : value,
]),
),
kmsKeyArn: configuration.KMSKeyArn,
tracingConfig: configuration.TracingConfig,
layers: configuration.Layers?.map((layer) => layer.Arn),
fileSystemConfigs: configuration.FileSystemConfigs,
packageType: configuration.PackageType,
imageConfig: configuration.ImageConfigResponse?.ImageConfig,
architectures: configuration.Architectures,
ephemeralStorage: configuration.EphemeralStorage,
snapStart: configuration.SnapStart?.ApplyOn,
loggingConfig: configuration.LoggingConfig,
tenancyConfig: configuration.TenancyConfig,
capacityProviderConfig: configuration.CapacityProviderConfig,
durableConfig: configuration.DurableConfig,
});
const completeConfiguration = Effect.fn(function* (
functionName: string,
configuration: Lambda.FunctionConfiguration,
) {
if (
!configuration.FunctionArn ||
!configuration.FunctionName ||
!configuration.CodeSha256
) {
throw new Error(
`Lambda function ${functionName} did not return the hashes required to publish a version.`,
);
}
return {
functionArn: configuration.FunctionArn.replace(/:(?:\$LATEST|[1-9]\d*)$/, ""),
functionName: configuration.FunctionName,
codeSha256: configuration.CodeSha256,
configSha256: yield* sha256Object(publishableConfiguration(configuration)),
};
});
const snapshot = Effect.fn(function* (configuration: Lambda.FunctionConfiguration) {
if (!isNumberedVersion(configuration.Version)) return undefined;
const complete = yield* completeConfiguration(
configuration.FunctionName ?? "unknown",
configuration,
);
const sourceHash = yield* sourceHashOf(
complete.functionArn,
complete.codeSha256,
complete.configSha256,
);
return {
...complete,
version: configuration.Version,
versionArn: `${complete.functionArn}:${configuration.Version}`,
sourceHash,
} satisfies Version["Attributes"];
});
const getVersion = (functionName: string, version: string) =>
Lambda.getFunctionConfiguration({
FunctionName: functionName,
Qualifier: version,
}).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
const listVersions = (functionName: string) =>
Lambda.listVersionsByFunction.items({ FunctionName: functionName }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).filter((version) => isNumberedVersion(version.Version)),
),
Effect.catchTag("ResourceNotFoundException", () => Effect.succeed([])),
);
const waitForLatest = Effect.fn(function* (functionName: string) {
const configuration = yield* Lambda.getFunctionConfiguration({
FunctionName: functionName,
Qualifier: "$LATEST",
}).pipe(
Effect.repeat({
schedule: Schedule.spaced("1 second"),
until: (current) =>
current.State !== "Pending" &&
current.State !== "Deactivating" &&
current.LastUpdateStatus !== "InProgress",
times: 45,
}),
);
if (
configuration.State === "Failed" ||
configuration.State === "Deactivated" ||
configuration.State === "Deleting" ||
configuration.LastUpdateStatus === "Failed"
) {
return yield* Effect.die(
new Error(
`Lambda function ${functionName} did not settle successfully: ${
configuration.LastUpdateStatusReason ??
configuration.StateReason ??
configuration.LastUpdateStatus ??
configuration.State ??
"unknown state"
}`,
),
);
}
return configuration;
});
const findOwnedVersion = Effect.fn(function* (functionName: string, marker: VersionMarker) {
const versions = yield* listVersions(functionName);
const matches = versions
.flatMap((version) => {
const parsed = parseMarker(version.Description);
return parsed?.ownerHash === marker.ownerHash && parsed.sourceHash === marker.sourceHash
? [version]
: [];
})
.sort((a, b) => Number.parseInt(b.Version!, 10) - Number.parseInt(a.Version!, 10));
return (
matches.find(
(version) => parseMarker(version.Description)?.instanceHash === marker.instanceHash,
) ?? matches[0]
);
});
return {
nuke: { skip: true },
stables: ["functionName", "functionArn"],
diff: Effect.fn(function* ({ olds, news, output }) {
const pendingFunctionName = (
news as unknown as {
function?: { functionName?: Input<string> };
}
).function?.functionName;
if (
output &&
pendingFunctionName !== undefined &&
isResolved(pendingFunctionName) &&
resolvedProps(olds).function.functionName !== pendingFunctionName
) {
return { action: "replace" } as const;
}
if (!isResolved(news)) {
return output ? ({ action: "update" } as const) : undefined;
}
const resolvedOlds = resolvedProps(olds);
const resolvedNews = resolvedProps(news);
if (!output) return undefined;
if (
!Object.prototype.hasOwnProperty.call(resolvedNews.function, "code") ||
!deepEqual(resolvedOlds.function, resolvedNews.function)
) {
return { action: "update" } as const;
}
return { action: "noop" } as const;
}),
read: Effect.fn(function* ({ id, fqn, instanceId, olds, output }) {
if (output) {
const observed = yield* getVersion(output.functionName, output.version);
if (!observed) return undefined;
const attrs = yield* snapshot(observed);
if (!attrs) return undefined;
const marker = parseMarker(observed.Description);
const identity = yield* ownerIdentity(id, fqn, instanceId);
return marker?.ownerHash === identity.ownerHash &&
marker.sourceHash === attrs.sourceHash
? attrs
: Unowned(attrs);
}
// An interrupted create's first checkpoint strips the Function
// reference while the Function is still being created (see
// stripUnresolved), so `olds.function` can be missing. With no
// function name there is no version to recover.
const functionName = olds ? resolvedProps(olds).function?.functionName : undefined;
if (!functionName) return undefined;
const latest = yield* waitForLatest(functionName);
const complete = yield* completeConfiguration(functionName, latest);
const sourceHash = yield* sourceHashOf(
complete.functionArn,
complete.codeSha256,
complete.configSha256,
);
const desired = yield* markerFor(id, fqn, instanceId, sourceHash);
const recovered = yield* findOwnedVersion(functionName, desired);
return recovered ? yield* snapshot(recovered) : undefined;
}),
list: () =>
Effect.gen(function* () {
const functionNames = yield* Lambda.listFunctions.items({}).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk)
.map((fn) => fn.FunctionName)
.filter((name): name is string => name !== undefined),
),
);
const versions = yield* Effect.forEach(
functionNames,
(functionName) =>
listVersions(functionName).pipe(
Effect.flatMap((items) => Effect.forEach(items, snapshot, { concurrency: 10 })),
Effect.map((items) =>
items.filter((item): item is Version["Attributes"] => item !== undefined),
),
),
{ concurrency: 10 },
);
return versions.flat();
}),
reconcile: Effect.fn(function* ({ id, fqn, instanceId, news, session }) {
const resolvedNews = resolvedProps(news);
const ensure = Effect.gen(function* () {
const latest = yield* waitForLatest(resolvedNews.function.functionName);
const complete = yield* completeConfiguration(
resolvedNews.function.functionName,
latest,
);
const sourceHash = yield* sourceHashOf(
complete.functionArn,
complete.codeSha256,
complete.configSha256,
);
const marker = yield* markerFor(id, fqn, instanceId, sourceHash);
const existing = yield* findOwnedVersion(complete.functionName, marker);
if (existing) {
const attrs = yield* snapshot(existing);
if (attrs) return attrs;
}
const published = yield* Lambda.publishVersion({
FunctionName: complete.functionName,
CodeSha256: complete.codeSha256,
RevisionId: latest.RevisionId,
Description: marker.description,
});
const attrs = yield* snapshot(published);
if (
!attrs ||
attrs.sourceHash !== sourceHash ||
published.Description !== marker.description
) {
return yield* Effect.die(
new Error(
`Lambda function ${complete.functionName} did not return the expected published version.`,
),
);
}
return attrs;
}).pipe(
Effect.retry({
while: (error) =>
error._tag === "PreconditionFailedException" ||
error._tag === "ResourceConflictException",
schedule: Schedule.max([Schedule.exponential("250 millis"), Schedule.recurs(8)]),
}),
);
const attrs = yield* ensure;
yield* session.note(`Version ${attrs.functionName}:${attrs.version}`);
return attrs;
}),
delete: Effect.fn(function* ({ output }) {
yield* Lambda.deleteFunction({
FunctionName: output.functionName,
Qualifier: output.version,
}).pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
}),
};
}),
);