sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Synthetics/ Canary.ts

import * as logs from "@distilled.cloud/aws/cloudwatch-logs";
import * as iam from "@distilled.cloud/aws/iam";
import * as lambda from "@distilled.cloud/aws/lambda";
import * as synthetics from "@distilled.cloud/aws/synthetics";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, createTagsList, diffTags, hasAlchemyTags } from "alchemy/Tags";
import { toWireDays, toWireSeconds } from "alchemy/Util/Duration";
import { sha256Object } from "alchemy/Util/sha256";
import { zipFiles } from "alchemy/Util/zip";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
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";

export interface CanaryProps {
  /**
   * Name of the canary. Must be lowercase, up to 255 characters, and match
   * `^[0-9a-z_-]+

	
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
		
	.repos/alchemy-effect/packages/aws/src/Synthetics/Canary.ts at main · sailfork/t3code-github · Sailfork
	
		
. Keep it to 21 characters or fewer so the derived Lambda * function name (`cwsyn-<name>-...`) stays within limits. * @default ${app}-${id}-${stage}-${suffix} (lowercased, truncated to 21 chars) */ canaryName?: string; /** * Inline canary script source. For Node.js runtimes * (`syn-nodejs-puppeteer-*`, `syn-nodejs-playwright-*`) the script is * packaged as `nodejs/node_modules/<file>.js`; for Python runtimes * (`syn-python-selenium-*`) as `python/<file>.py`, where `<file>` is the * first segment of `handler`. */ script: string; /** * The entry point of the canary script, `<fileName>.<functionName>`. * @default "index.handler" */ handler?: string; /** * The Synthetics runtime version to use. * @default "syn-nodejs-puppeteer-16.1" */ runtimeVersion?: string; /** * S3 location where the canary stores run artifacts (screenshots, HAR * files, logs), e.g. `s3://my-bucket/canary-artifacts`. The `s3://` prefix * is added automatically if missing. */ artifactS3Location: string; /** * ARN of the IAM role the canary's Lambda assumes. When omitted, a role is * created automatically with write access to the artifact bucket, * CloudWatch Logs, and the `CloudWatchSynthetics` metric namespace. */ executionRoleArn?: string; /** * How often the canary runs. */ schedule?: { /** * A `rate(...)` expression (`rate(1 minute)` to `rate(1 hour)`), a * `cron(...)` expression, or `rate(0 minute)` to run only once when * started. * @default "rate(5 minutes)" */ expression?: string; /** * How long the canary keeps running on this schedule after it starts * (up to 1 year), e.g. `"12 hours"` or `Duration.hours(12)` (a bare * number is milliseconds). Rounded to whole seconds on the wire. * `"0 seconds"` (or omitted) runs the canary continuously. */ duration?: Duration.Input; }; /** * Whether the canary is started (scheduled to run) after deployment. * When `false`, the canary is created in the `READY` state and never runs * until started. * @default false */ start?: boolean; /** * Per-run configuration of the canary's Lambda. */ runConfig?: { /** * Run timeout (max 840 seconds), e.g. `"60 seconds"` or * `Duration.minutes(1)` (a bare number is milliseconds). Rounded to * whole seconds on the wire. Defaults to the schedule frequency * capped at 14 minutes. */ timeout?: Duration.Input; /** * Memory in MB (multiple of 64, between 960 and 3008). */ memoryInMB?: number; /** * Enable X-Ray active tracing for canary runs. * @default false */ activeTracing?: boolean; /** * Environment variables exposed to the canary script. Not observable * from the API after creation. */ environmentVariables?: Record<string, string>; }; /** * How long to retain data on successful runs (1 - 455 days), e.g. * `"7 days"` or `Duration.days(7)` (a bare number is milliseconds). * Rounded to whole days on the wire. * @default 31 days */ successRetentionPeriod?: Duration.Input; /** * How long to retain data on failed runs (1 - 455 days), e.g. * `"31 days"` or `Duration.days(31)` (a bare number is milliseconds). * Rounded to whole days on the wire. * @default 31 days */ failureRetentionPeriod?: Duration.Input; /** * Run the canary inside a VPC. Both fields are required together. */ vpcConfig?: { /** Subnet IDs the canary's ENIs are placed in. */ subnetIds: string[]; /** Security group IDs applied to the canary's ENIs. */ securityGroupIds: string[]; }; /** * Whether the Lambda function and layers backing the canary are deleted * automatically when the canary is deleted. * @default "AUTOMATIC" */ provisionedResourceCleanup?: "AUTOMATIC" | "OFF"; /** * Tags to apply to the canary. Merged with internal Alchemy tags. */ tags?: Record<string, string>; } export interface Canary extends Resource< "AWS.Synthetics.Canary", CanaryProps, { /** * Physical name of the canary. */ canaryName: string; /** * ARN of the canary. */ canaryArn: string; /** * Service-assigned unique ID of the canary. */ canaryId: string; /** * ARN of the IAM role the canary runs as. */ executionRoleArn: string; /** * S3 location where run artifacts (screenshots, HAR files, logs) land. */ artifactS3Location: string; /** * Synthetics runtime version the canary executes on. */ runtimeVersion: string; /** Name of the auto-created execution role; `undefined` when the user supplied `executionRoleArn`. */ roleName: string | undefined; /** Hash of the last-applied desired configuration; used to skip no-op updates. */ configHash: string | undefined; /** Exact ARN of the service-created Lambda function backing the canary. */ engineArn: string | undefined; }, {}, Providers > {} /** * A CloudWatch Synthetics canary — a scripted probe that monitors your * endpoints and APIs on a schedule from the outside in. * * The canary script is provided inline and packaged automatically for the * chosen runtime. Unless you pass `executionRoleArn`, an IAM execution role * is created with least-privilege access to the artifact bucket, CloudWatch * Logs, and Synthetics metrics. * ### Creating Canaries * **Example:** Heartbeat Canary (created stopped) * ```typescript * import * as Synthetics from "@alchemy.run/aws/Synthetics"; * * const canary = yield* Synthetics.Canary("Heartbeat", { * script: ` * const synthetics = require("Synthetics"); * exports.handler = async () => { * return await synthetics.executeStep("heartbeat", async () => {}); * }; * `, * artifactS3Location: Output.interpolate`s3://${bucket.bucketName}/canary`, * }); * ``` * * **Example:** Started Canary on a Schedule * ```typescript * const canary = yield* Synthetics.Canary("ApiMonitor", { * script: myCanaryScript, * artifactS3Location: "s3://my-artifacts/api-monitor", * schedule: { expression: "rate(5 minutes)" }, * start: true, * }); * ``` * * ### Configuration * **Example:** Custom Runtime, Timeout and Environment * ```typescript * const canary = yield* Synthetics.Canary("Checkout", { * script: checkoutScript, * runtimeVersion: "syn-nodejs-puppeteer-16.1", * artifactS3Location: "s3://my-artifacts/checkout", * runConfig: { * timeout: "60 seconds", * environmentVariables: { TARGET_URL: "https://example.com" }, * }, * successRetentionPeriod: "7 days", * failureRetentionPeriod: "31 days", * }); * ``` * * **Example:** Bring Your Own Execution Role * ```typescript * const canary = yield* Synthetics.Canary("Probe", { * script: probeScript, * artifactS3Location: "s3://my-artifacts/probe", * executionRoleArn: role.roleArn, * }); * ``` * * @resource */ export const Canary = Resource<Canary>("AWS.Synthetics.Canary"); const DEFAULT_RUNTIME_VERSION = "syn-nodejs-puppeteer-16.1"; const DEFAULT_SCHEDULE_EXPRESSION = "rate(5 minutes)"; const ROLE_POLICY_NAME = "AlchemyCanaryPolicy"; const VPC_ACCESS_POLICY_ARN = "arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole"; /** * Canary create/update/start/stop are asynchronous; the canary reports a * transitional state while converging. Raised internally to drive the * bounded settle-polling retry loop. */ export class CanaryNotSettled extends Data.TaggedError("CanaryNotSettled")<{ canaryName: string; state: string | undefined; }> {} /** * Raised when a canary lands in the `ERROR` state after a create or update * instead of converging to `READY`/`STOPPED`. */ export class CanaryFailed extends Data.TaggedError("CanaryFailed")<{ canaryName: string; stateReasonCode: string | undefined; message: string; }> {} class CanaryBackingResourceStillVisible extends Data.TaggedError( "CanaryBackingResourceStillVisible", )<{ readonly canaryName: string; readonly resource: "LambdaFunction" | "LogGroup"; readonly identifier: string; }> {} class UnexpectedCanaryEngineArn extends Data.TaggedError("UnexpectedCanaryEngineArn")<{ readonly canaryName: string; readonly engineArn: string; }> {} const TRANSITIONAL_STATES = ["CREATING", "UPDATING", "STARTING", "STOPPING", "DELETING"]; /** * Retry an operation while the canary is briefly locked by a concurrent * state transition (`ConflictException`), on a bounded schedule (~60s). * Module-scope with an explicit return type so the conditional `Retry.Return` * type never leaks into declaration emit (which would widen the provider * layer to `unknown`). */ const retryWhileConflict = <A, E extends { _tag: string }, R>( self: Effect.Effect<A, E, R>, ): Effect.Effect<A, E, R> => Effect.retry(self, { while: (e) => e._tag === "ConflictException", schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(20)]), }); const parseArtifactLocation = (location: string) => { const stripped = location.startsWith("s3://") ? location.slice(5) : location; return { artifactS3Location: `s3://${stripped}`, artifactBucket: stripped.split("/")[0]!, }; }; const scriptFilePath = (runtimeVersion: string, handler: string) => { const fileName = handler.split(".")[0]!; return runtimeVersion.startsWith("syn-python") ? `python/${fileName}.py` : `nodejs/node_modules/${fileName}.js`; }; /** Package the inline script as the zip layout the runtime expects. */ const buildCode = Effect.fn(function* (script: string, handler: string, runtimeVersion: string) { const buffer = yield* zipFiles([ { path: scriptFilePath(runtimeVersion, handler), content: script }, ]); return { ZipFile: new Uint8Array(buffer), Handler: handler, } satisfies synthetics.CanaryCodeInput; }); const filterTags = ( tags: { [key: string]: string | undefined } | undefined, ): Record<string, string> => Object.fromEntries( Object.entries(tags ?? {}).filter((entry): entry is [string, string] => entry[1] !== undefined), ); export const CanaryProvider = () => Provider.effect( Canary, Effect.gen(function* () { const createCanaryName = Effect.fn(function* ( id: string, props: { canaryName?: string | undefined }, ) { if (props.canaryName) return props.canaryName; // Canary names must be lowercase [0-9a-z_-]; the console caps them at // 21 chars because the backing Lambda is named `cwsyn-<name>-<uuid>`. return yield* createPhysicalName({ id, maxLength: 21, suffixLength: 8, lowercase: true, }); }); const createRoleName = (id: string) => createPhysicalName({ id, maxLength: 64 }); const canaryArnOf = Effect.fn(function* (canaryName: string) { const { accountId, region } = yield* AWSEnvironment.current; return `arn:aws:synthetics:${region}:${accountId}:canary:${canaryName}`; }); const getCanaryOrUndefined = Effect.fn(function* (canaryName: string) { return yield* synthetics.getCanary({ Name: canaryName }).pipe( Effect.map((r) => r.Canary), Effect.catchTag("ResourceNotFoundException", () => Effect.undefined), ); }); // Poll until the canary leaves its transitional state. Create typically // settles in 30-90s; budget 3 minutes (60 * 3s). const waitForSettled = Effect.fn(function* (canaryName: string) { return yield* getCanaryOrUndefined(canaryName).pipe( Effect.flatMap((canary) => canary !== undefined && TRANSITIONAL_STATES.includes(canary.Status?.State ?? "") ? Effect.fail( new CanaryNotSettled({ canaryName, state: canary.Status?.State, }), ) : Effect.succeed(canary), ), Effect.retry({ while: (e) => e instanceof CanaryNotSettled, schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(60)]), }), ); }); const failIfErrored = (canaryName: string, canary: synthetics.Canary | undefined) => canary?.Status?.State === "ERROR" ? Effect.fail( new CanaryFailed({ canaryName, stateReasonCode: canary.Status?.StateReasonCode, message: canary.Status?.StateReason ?? `canary ${canaryName} is in ERROR state`, }), ) : Effect.void; // Deletion is asynchronous (DELETING); wait until gone so a // destroy-then-deploy of the same logical resource (same physical // name) does not race the pending delete. const waitUntilGone = Effect.fn(function* (canaryName: string) { yield* getCanaryOrUndefined(canaryName).pipe( Effect.flatMap((canary) => canary === undefined ? Effect.void : Effect.fail( new CanaryNotSettled({ canaryName, state: canary.Status?.State, }), ), ), Effect.retry({ while: (e) => e instanceof CanaryNotSettled, schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(40)]), }), ); }); // Stop (if running) + delete + wait-until-gone. Also used by reconcile // to self-heal a canary stuck in CREATE_FAILED. const deleteCanaryAndWait = Effect.fn(function* (canaryName: string) { const observed = yield* getCanaryOrUndefined(canaryName); if (observed === undefined) return; const state = observed.Status?.State; if (state === "RUNNING" || state === "STARTING") { yield* synthetics .stopCanary({ Name: canaryName }) .pipe( Effect.catchTag( ["ResourceNotFoundException", "ConflictException"], () => Effect.void, ), ); } // wait out any transitional state (STOPPING, UPDATING, ...) — a // canary can only be deleted from READY/STOPPED/ERROR. yield* waitForSettled(canaryName); yield* synthetics.deleteCanary({ Name: canaryName, DeleteLambda: true }).pipe( // e.g. a run is still finishing; bounded retry retryWhileConflict, Effect.catchTag("ResourceNotFoundException", () => Effect.void), ); yield* waitUntilGone(canaryName); }); const backingFunctionName = (canaryName: string, engineArn: string) => { const marker = ":function:"; const markerIndex = engineArn.indexOf(marker); const functionName = markerIndex === -1 ? undefined : engineArn.slice(markerIndex + marker.length).split(":")[0]; // EngineArn is observed directly from this owned canary. Retain an // explicit name check so a malformed or unexpectedly-shaped response // can never make deletion target another Lambda. return functionName?.startsWith(`cwsyn-${canaryName}-`) ? Effect.succeed(functionName) : Effect.fail(new UnexpectedCanaryEngineArn({ canaryName, engineArn })); }; const discoverBackingFunctionNames = Effect.fn(function* ( canaryName: string, engineArn: string | undefined, ) { if (engineArn) { return [yield* backingFunctionName(canaryName, engineArn)]; } // EngineArn is optional and is absent on some Synthetics runtimes. // The backing Lambda's only observable relationship is its service // name. Require the complete canonical UUID suffix so a canary named // `foo` can never capture another named `foo-bar`. const escapedCanaryName = canaryName.replace(/[.*+?^${}()|[\]\\]/g, "\\

Loading Sailfork

amp;"); const exactBackingName = new RegExp( `^cwsyn-${escapedCanaryName}-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12} .repos/alchemy-effect/packages/aws/src/Synthetics/Canary.ts at main · sailfork/t3code-github · Sailfork
, "i", ); const pages = yield* lambda.listFunctions.pages({}).pipe(Stream.runCollect); return Array.from(pages) .flatMap((page) => page.Functions ?? []) .flatMap((fn) => fn.FunctionName && exactBackingName.test(fn.FunctionName) ? [fn.FunctionName] : [], ); }); const backingFunctionExists = (functionName: string) => lambda.getFunction({ FunctionName: functionName }).pipe( Effect.as(true), Effect.catchTag("ResourceNotFoundException", () => Effect.succeed(false)), ); const exactLogGroupExists = (logGroupName: string) => logs .describeLogGroups({ logGroupNamePrefix: logGroupName, limit: 50, }) .pipe( Effect.map((response) => (response.logGroups ?? []).some((group) => group.logGroupName === logGroupName), ), ); const waitForBackingResourceGone = <E extends { readonly _tag: string }, R>( canaryName: string, resource: "LambdaFunction" | "LogGroup", identifier: string, exists: Effect.Effect<boolean, E, R>, ) => exists.pipe( Effect.flatMap((visible) => visible ? Effect.fail( new CanaryBackingResourceStillVisible({ canaryName, resource, identifier, }), ) : Effect.void, ), Effect.retry({ while: (error) => error._tag === "CanaryBackingResourceStillVisible", schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(20)]), }), ); const deleteBackingResources = Effect.fn(function* ( canaryName: string, functionName: string, ) { const logGroupName = `/aws/lambda/${functionName}`; yield* lambda.deleteFunction({ FunctionName: functionName }).pipe( Effect.retry({ while: (error) => error._tag === "ResourceConflictException", schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(20)]), }), Effect.catchTag("ResourceNotFoundException", () => Effect.void), ); yield* waitForBackingResourceGone( canaryName, "LambdaFunction", functionName, backingFunctionExists(functionName), ); // Lambda never owns its log group lifecycle. A just-finished // invocation can flush its final stream after Lambda deletion starts, // so reap this exact group across a short quiescence window. for (let attempt = 0; attempt < 5; attempt++) { if (yield* exactLogGroupExists(logGroupName)) { yield* logs.deleteLogGroup({ logGroupName }).pipe( Effect.retry({ while: (error) => error._tag === "OperationAbortedException", schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(15)]), }), Effect.catchTag("ResourceNotFoundException", () => Effect.void), ); } yield* Effect.sleep("2 seconds"); } yield* waitForBackingResourceGone( canaryName, "LogGroup", logGroupName, exactLogGroupExists(logGroupName), ); }); /** * Ensure the auto-created execution role exists and its inline policy * matches the artifact bucket. Every step is idempotent: create * tolerates AlreadyExists, putRolePolicy is an upsert. */ const ensureExecutionRole = Effect.fn(function* ({ id, roleName, artifactBucket, vpc, }: { id: string; roleName: string; artifactBucket: string; vpc: boolean; }) { const { accountId, region } = yield* AWSEnvironment.current; const internalTags = yield* createInternalTags(id); // Track whether we actually created the role on this pass — a fresh // role needs a propagation grace period before Synthetics can build // the backing Lambda with it. let created = true; yield* iam .createRole({ RoleName: roleName, AssumeRolePolicyDocument: JSON.stringify({ Version: "2012-10-17", Statement: [ { Effect: "Allow", Principal: { Service: "lambda.amazonaws.com" }, Action: "sts:AssumeRole", }, ], }), Tags: createTagsList(internalTags), }) .pipe( Effect.catchTag("EntityAlreadyExistsException", () => Effect.sync(() => { created = false; }), ), ); yield* iam.putRolePolicy({ RoleName: roleName, PolicyName: ROLE_POLICY_NAME, PolicyDocument: JSON.stringify({ Version: "2012-10-17", Statement: [ { Effect: "Allow", Action: ["s3:PutObject", "s3:GetObject"], Resource: [`arn:aws:s3:::${artifactBucket}/*`], }, { Effect: "Allow", Action: ["s3:GetBucketLocation"], Resource: [`arn:aws:s3:::${artifactBucket}`], }, { Effect: "Allow", Action: ["s3:ListAllMyBuckets"], Resource: ["*"], }, { Effect: "Allow", Action: ["cloudwatch:PutMetricData"], Resource: ["*"], Condition: { StringEquals: { "cloudwatch:namespace": "CloudWatchSynthetics", }, }, }, { Effect: "Allow", Action: ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"], Resource: [`arn:aws:logs:${region}:${accountId}:log-group:/aws/lambda/cwsyn-*`], }, { Effect: "Allow", Action: ["xray:PutTraceSegments"], Resource: ["*"], }, ], }), }); if (vpc) { yield* iam.attachRolePolicy({ RoleName: roleName, PolicyArn: VPC_ACCESS_POLICY_ARN, }); } if (created) { // IAM is eventually consistent — a canary created immediately after // the role lands in CREATE_FAILED with "The role defined for the // function cannot be assumed by Lambda". Give the role time to // propagate; the CREATE_FAILED recreate loop below covers stragglers. yield* Effect.sleep("10 seconds"); } return `arn:aws:iam::${accountId}:role/${roleName}`; }); // Tear down the auto-created execution role. Idempotent: every step // tolerates the entity being gone. const deleteExecutionRole = Effect.fn(function* (roleName: string) { yield* iam .deleteRolePolicy({ RoleName: roleName, PolicyName: ROLE_POLICY_NAME, }) .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void)); yield* iam .detachRolePolicy({ RoleName: roleName, PolicyArn: VPC_ACCESS_POLICY_ARN, }) .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void)); yield* iam.deleteRole({ RoleName: roleName }).pipe( Effect.retry({ while: (error) => error._tag === "ConcurrentModificationException" || error._tag === "DeleteConflictException" || error._tag === "LimitExceededException" || error._tag === "ServiceFailureException", schedule: Schedule.max([Schedule.fixed("1 second"), Schedule.recurs(20)]), }), Effect.catchTag("NoSuchEntityException", () => Effect.void), ); // IAM deletion is eventually consistent. Keep the canary's state // until its owned execution role is observably absent so a following // nuke cannot race the successful DeleteRole request. for (let attempt = 0; attempt < 30; attempt++) { const remaining = yield* iam .getRole({ RoleName: roleName }) .pipe(Effect.catchTag("NoSuchEntityException", () => Effect.undefined)); if (remaining === undefined) return; yield* Effect.sleep("1 second"); } return yield* Effect.die( new Error( `Synthetics execution role ${roleName} remained observable 30 seconds after delete`, ), ); }); const desiredConfigHash = ( props: CanaryProps, executionRoleArn: string, artifactS3Location: string, runtimeVersion: string, ) => sha256Object({ script: props.script, handler: props.handler ?? "index.handler", runtimeVersion, artifactS3Location, executionRoleArn, schedule: { expression: props.schedule?.expression ?? DEFAULT_SCHEDULE_EXPRESSION, durationInSeconds: toWireSeconds(props.schedule?.duration) ?? 0, }, runConfig: props.runConfig === undefined ? {} : { ...props.runConfig, timeout: undefined, timeoutInSeconds: toWireSeconds(props.runConfig.timeout), }, successRetentionPeriodInDays: toWireDays(props.successRetentionPeriod), failureRetentionPeriodInDays: toWireDays(props.failureRetentionPeriod), vpcConfig: props.vpcConfig, provisionedResourceCleanup: props.provisionedResourceCleanup ?? "AUTOMATIC", }); const toRunConfigInput = (props: CanaryProps): synthetics.CanaryRunConfigInput | undefined => props.runConfig === undefined ? undefined : { TimeoutInSeconds: toWireSeconds(props.runConfig.timeout), MemoryInMB: props.runConfig.memoryInMB, ActiveTracing: props.runConfig.activeTracing, EnvironmentVariables: props.runConfig.environmentVariables, }; const toScheduleInput = (props: CanaryProps): synthetics.CanaryScheduleInput => ({ Expression: props.schedule?.expression ?? DEFAULT_SCHEDULE_EXPRESSION, DurationInSeconds: toWireSeconds(props.schedule?.duration), }); const toVpcConfigInput = (props: CanaryProps): synthetics.VpcConfigInput | undefined => props.vpcConfig === undefined ? undefined : { SubnetIds: props.vpcConfig.subnetIds, SecurityGroupIds: props.vpcConfig.securityGroupIds, }; return Canary.Provider.of({ stables: ["canaryName", "canaryArn", "canaryId", "roleName", "engineArn"], // Enumerate every canary in the ambient account/region. list: () => Effect.gen(function* () { const pages = yield* synthetics.describeCanaries.pages({}).pipe(Stream.runCollect); const canaries = Array.from(pages).flatMap((page) => page.Canaries ?? []); const items: Canary["Attributes"][] = []; for (const canary of canaries) { if (!canary.Name) continue; items.push({ canaryName: canary.Name, canaryArn: yield* canaryArnOf(canary.Name), canaryId: canary.Id ?? "", executionRoleArn: canary.ExecutionRoleArn ?? "", artifactS3Location: canary.ArtifactS3Location ? parseArtifactLocation(canary.ArtifactS3Location).artifactS3Location : "", runtimeVersion: canary.RuntimeVersion ?? "", roleName: undefined, configHash: undefined, engineArn: canary.EngineArn, }); } return items; }), read: Effect.fn(function* ({ id, olds, output }) { const canaryName = output?.canaryName ?? (yield* createCanaryName(id, olds ?? {})); const canary = yield* getCanaryOrUndefined(canaryName); if (canary === undefined) return undefined; const attrs: Canary["Attributes"] = { canaryName, canaryArn: yield* canaryArnOf(canaryName), canaryId: canary.Id ?? "", executionRoleArn: canary.ExecutionRoleArn ?? "", artifactS3Location: canary.ArtifactS3Location ? parseArtifactLocation(canary.ArtifactS3Location).artifactS3Location : "", runtimeVersion: canary.RuntimeVersion ?? "", roleName: output?.roleName, configHash: output?.configHash, engineArn: canary.EngineArn ?? output?.engineArn, }; const tags = filterTags(canary.Tags); return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs); }), diff: Effect.fn(function* ({ id, news, olds }) { if (!isResolved(news)) return undefined; const oldName = yield* createCanaryName(id, olds); const newName = yield* createCanaryName(id, news); if (oldName !== newName) { return { action: "replace" } as const; } // everything else converges through updateCanary }), reconcile: Effect.fn(function* ({ id, news, output, session }) { const canaryName = output?.canaryName ?? (yield* createCanaryName(id, news)); const canaryArn = yield* canaryArnOf(canaryName); const internalTags = yield* createInternalTags(id); const desiredTags = { ...news.tags, ...internalTags }; const { artifactS3Location, artifactBucket } = parseArtifactLocation( news.artifactS3Location, ); const runtimeVersion = news.runtimeVersion ?? DEFAULT_RUNTIME_VERSION; const handler = news.handler ?? "index.handler"; // Ensure the execution role (user-supplied or auto-created, with // its inline policy converged to the current artifact bucket). let roleName: string | undefined; let executionRoleArn: string; if (news.executionRoleArn) { executionRoleArn = news.executionRoleArn; } else { roleName = output?.roleName ?? (yield* createRoleName(id)); executionRoleArn = yield* ensureExecutionRole({ id, roleName, artifactBucket, vpc: news.vpcConfig !== undefined, }); } const configHash = yield* desiredConfigHash( news, executionRoleArn, artifactS3Location, runtimeVersion, ); // 1. OBSERVE — cloud state is authoritative. let observed = yield* getCanaryOrUndefined(canaryName); // Self-heal a canary stuck in CREATE_FAILED (e.g. a crashed prior // deploy): it cannot be updated, only deleted and recreated. if ( observed?.Status?.State === "ERROR" && observed.Status?.StateReasonCode === "CREATE_FAILED" ) { yield* session.note( `canary ${canaryName} is in CREATE_FAILED (${observed.Status?.StateReason}); recreating`, ); yield* deleteCanaryAndWait(canaryName); observed = undefined; } // 2. ENSURE — create if missing; wait for the async create to // settle (CREATING → READY, typically 30-90s). if (observed === undefined) { const code = yield* buildCode(news.script, handler, runtimeVersion); // Canary creation is asynchronous and validated in the backend: // an execution role that hasn't finished propagating surfaces as // CREATE_FAILED ("role ... cannot be assumed by Lambda") only // AFTER the create settles. A CREATE_FAILED canary can't be // updated — delete it and recreate, bounded to 3 attempts. for (let attempt = 0; ; attempt++) { yield* synthetics.createCanary({ Name: canaryName, Code: code, ArtifactS3Location: artifactS3Location, ExecutionRoleArn: executionRoleArn, Schedule: toScheduleInput(news), RunConfig: toRunConfigInput(news), RuntimeVersion: runtimeVersion, SuccessRetentionPeriodInDays: toWireDays(news.successRetentionPeriod), FailureRetentionPeriodInDays: toWireDays(news.failureRetentionPeriod), VpcConfig: toVpcConfigInput(news), ProvisionedResourceCleanup: news.provisionedResourceCleanup ?? "AUTOMATIC", Tags: desiredTags, }); yield* session.note(`created canary ${canaryName}, waiting for it to become ready`); observed = yield* waitForSettled(canaryName); if ( observed?.Status?.State === "ERROR" && observed.Status?.StateReasonCode === "CREATE_FAILED" ) { // A failed create is not persisted by the engine, so leaving // the CREATE_FAILED canary behind would leak it — delete it // whether we retry or give up. yield* session.note( `canary create failed (${observed.Status?.StateReason}); deleting`, ); yield* deleteCanaryAndWait(canaryName); if (attempt < 2) { yield* Effect.sleep("10 seconds"); continue; } // Giving up — the engine does not persist a failed create, so // also remove the execution role we auto-created this pass. if (roleName !== undefined) { yield* deleteExecutionRole(roleName); } } yield* failIfErrored(canaryName, observed); break; } } else { // 3. SYNC config — the script content is not observable from the // API (only a source-location ARN), so we use the persisted // configHash as a skip-hint; on adoption (no hash) or any prop // change we push the full desired configuration, which is // idempotent. observed = yield* waitForSettled(canaryName); yield* failIfErrored(canaryName, observed); if (output?.configHash !== configHash) { const code = yield* buildCode(news.script, handler, runtimeVersion); yield* synthetics .updateCanary({ Name: canaryName, Code: code, ExecutionRoleArn: executionRoleArn, RuntimeVersion: runtimeVersion, Schedule: toScheduleInput(news), RunConfig: toRunConfigInput(news), SuccessRetentionPeriodInDays: toWireDays(news.successRetentionPeriod), FailureRetentionPeriodInDays: toWireDays(news.failureRetentionPeriod), VpcConfig: toVpcConfigInput(news), ArtifactS3Location: artifactS3Location, ProvisionedResourceCleanup: news.provisionedResourceCleanup ?? "AUTOMATIC", }) .pipe(retryWhileConflict); yield* session.note(`updated canary ${canaryName}`); observed = yield* waitForSettled(canaryName); yield* failIfErrored(canaryName, observed); } } // 4. SYNC run state — start/stop to match the `start` prop. const desiredRunning = news.start ?? false; const state = observed?.Status?.State; if (desiredRunning && state !== "RUNNING") { yield* synthetics.startCanary({ Name: canaryName }).pipe(retryWhileConflict); yield* session.note(`started canary ${canaryName}`); observed = yield* waitForSettled(canaryName); } else if (!desiredRunning && state === "RUNNING") { yield* synthetics .stopCanary({ Name: canaryName }) .pipe(Effect.catchTag("ConflictException", () => Effect.void)); yield* session.note(`stopped canary ${canaryName}`); observed = yield* waitForSettled(canaryName); } // 5. SYNC tags — diff against OBSERVED cloud tags so adoption // converges (create already applied them; update cannot). const currentTags = filterTags(observed?.Tags); const { upsert, removed } = diffTags(currentTags, desiredTags); if (upsert.length > 0) { yield* synthetics.tagResource({ ResourceArn: canaryArn, Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])), }); } if (removed.length > 0) { yield* synthetics.untagResource({ ResourceArn: canaryArn, TagKeys: removed, }); } yield* session.note(canaryName); return { canaryName, canaryArn, canaryId: observed?.Id ?? "", executionRoleArn, artifactS3Location, runtimeVersion, roleName, configHash, engineArn: observed?.EngineArn, }; }), delete: Effect.fn(function* ({ output, session }) { const observed = yield* getCanaryOrUndefined(output.canaryName); const engineArn = observed?.EngineArn ?? output.engineArn; const backingFunctions = yield* discoverBackingFunctionNames( output.canaryName, engineArn, ); yield* deleteCanaryAndWait(output.canaryName); for (const functionName of backingFunctions) { yield* session.note( `deleting exact backing Lambda ${functionName} and log group /aws/lambda/${functionName}`, ); yield* deleteBackingResources(output.canaryName, functionName); } // Clean up the auto-created execution role (never a user-supplied // one). if (output.roleName) { yield* deleteExecutionRole(output.roleName); } }), }); }), );
.repos/alchemy-effect/packages/aws/src/Synthetics/Canary.ts at main · sailfork/t3code-github · Sailfork
. Keep it to 21 characters or fewer so the derived Lambda\n * function name (`cwsyn-\u003cname>-...`) stays within limits.\n * @default ${app}-${id}-${stage}-${suffix} (lowercased, truncated to 21 chars)\n */\n canaryName?: string;\n /**\n * Inline canary script source. For Node.js runtimes\n * (`syn-nodejs-puppeteer-*`, `syn-nodejs-playwright-*`) the script is\n * packaged as `nodejs/node_modules/\u003cfile>.js`; for Python runtimes\n * (`syn-python-selenium-*`) as `python/\u003cfile>.py`, where `\u003cfile>` is the\n * first segment of `handler`.\n */\n script: string;\n /**\n * The entry point of the canary script, `\u003cfileName>.\u003cfunctionName>`.\n * @default \"index.handler\"\n */\n handler?: string;\n /**\n * The Synthetics runtime version to use.\n * @default \"syn-nodejs-puppeteer-16.1\"\n */\n runtimeVersion?: string;\n /**\n * S3 location where the canary stores run artifacts (screenshots, HAR\n * files, logs), e.g. `s3://my-bucket/canary-artifacts`. The `s3://` prefix\n * is added automatically if missing.\n */\n artifactS3Location: string;\n /**\n * ARN of the IAM role the canary's Lambda assumes. When omitted, a role is\n * created automatically with write access to the artifact bucket,\n * CloudWatch Logs, and the `CloudWatchSynthetics` metric namespace.\n */\n executionRoleArn?: string;\n /**\n * How often the canary runs.\n */\n schedule?: {\n /**\n * A `rate(...)` expression (`rate(1 minute)` to `rate(1 hour)`), a\n * `cron(...)` expression, or `rate(0 minute)` to run only once when\n * started.\n * @default \"rate(5 minutes)\"\n */\n expression?: string;\n /**\n * How long the canary keeps running on this schedule after it starts\n * (up to 1 year), e.g. `\"12 hours\"` or `Duration.hours(12)` (a bare\n * number is milliseconds). Rounded to whole seconds on the wire.\n * `\"0 seconds\"` (or omitted) runs the canary continuously.\n */\n duration?: Duration.Input;\n };\n /**\n * Whether the canary is started (scheduled to run) after deployment.\n * When `false`, the canary is created in the `READY` state and never runs\n * until started.\n * @default false\n */\n start?: boolean;\n /**\n * Per-run configuration of the canary's Lambda.\n */\n runConfig?: {\n /**\n * Run timeout (max 840 seconds), e.g. `\"60 seconds\"` or\n * `Duration.minutes(1)` (a bare number is milliseconds). Rounded to\n * whole seconds on the wire. Defaults to the schedule frequency\n * capped at 14 minutes.\n */\n timeout?: Duration.Input;\n /**\n * Memory in MB (multiple of 64, between 960 and 3008).\n */\n memoryInMB?: number;\n /**\n * Enable X-Ray active tracing for canary runs.\n * @default false\n */\n activeTracing?: boolean;\n /**\n * Environment variables exposed to the canary script. Not observable\n * from the API after creation.\n */\n environmentVariables?: Record\u003cstring, string>;\n };\n /**\n * How long to retain data on successful runs (1 - 455 days), e.g.\n * `\"7 days\"` or `Duration.days(7)` (a bare number is milliseconds).\n * Rounded to whole days on the wire.\n * @default 31 days\n */\n successRetentionPeriod?: Duration.Input;\n /**\n * How long to retain data on failed runs (1 - 455 days), e.g.\n * `\"31 days\"` or `Duration.days(31)` (a bare number is milliseconds).\n * Rounded to whole days on the wire.\n * @default 31 days\n */\n failureRetentionPeriod?: Duration.Input;\n /**\n * Run the canary inside a VPC. Both fields are required together.\n */\n vpcConfig?: {\n /** Subnet IDs the canary's ENIs are placed in. */\n subnetIds: string[];\n /** Security group IDs applied to the canary's ENIs. */\n securityGroupIds: string[];\n };\n /**\n * Whether the Lambda function and layers backing the canary are deleted\n * automatically when the canary is deleted.\n * @default \"AUTOMATIC\"\n */\n provisionedResourceCleanup?: \"AUTOMATIC\" | \"OFF\";\n /**\n * Tags to apply to the canary. Merged with internal Alchemy tags.\n */\n tags?: Record\u003cstring, string>;\n}\n\nexport interface Canary extends Resource\u003c\n \"AWS.Synthetics.Canary\",\n CanaryProps,\n {\n /**\n * Physical name of the canary.\n */\n canaryName: string;\n /**\n * ARN of the canary.\n */\n canaryArn: string;\n /**\n * Service-assigned unique ID of the canary.\n */\n canaryId: string;\n /**\n * ARN of the IAM role the canary runs as.\n */\n executionRoleArn: string;\n /**\n * S3 location where run artifacts (screenshots, HAR files, logs) land.\n */\n artifactS3Location: string;\n /**\n * Synthetics runtime version the canary executes on.\n */\n runtimeVersion: string;\n /** Name of the auto-created execution role; `undefined` when the user supplied `executionRoleArn`. */\n roleName: string | undefined;\n /** Hash of the last-applied desired configuration; used to skip no-op updates. */\n configHash: string | undefined;\n /** Exact ARN of the service-created Lambda function backing the canary. */\n engineArn: string | undefined;\n },\n {},\n Providers\n> {}\n\n/**\n * A CloudWatch Synthetics canary — a scripted probe that monitors your\n * endpoints and APIs on a schedule from the outside in.\n *\n * The canary script is provided inline and packaged automatically for the\n * chosen runtime. Unless you pass `executionRoleArn`, an IAM execution role\n * is created with least-privilege access to the artifact bucket, CloudWatch\n * Logs, and Synthetics metrics.\n * ### Creating Canaries\n * **Example:** Heartbeat Canary (created stopped)\n * ```typescript\n * import * as Synthetics from \"@alchemy.run/aws/Synthetics\";\n *\n * const canary = yield* Synthetics.Canary(\"Heartbeat\", {\n * script: `\n * const synthetics = require(\"Synthetics\");\n * exports.handler = async () => {\n * return await synthetics.executeStep(\"heartbeat\", async () => {});\n * };\n * `,\n * artifactS3Location: Output.interpolate`s3://${bucket.bucketName}/canary`,\n * });\n * ```\n *\n * **Example:** Started Canary on a Schedule\n * ```typescript\n * const canary = yield* Synthetics.Canary(\"ApiMonitor\", {\n * script: myCanaryScript,\n * artifactS3Location: \"s3://my-artifacts/api-monitor\",\n * schedule: { expression: \"rate(5 minutes)\" },\n * start: true,\n * });\n * ```\n *\n * ### Configuration\n * **Example:** Custom Runtime, Timeout and Environment\n * ```typescript\n * const canary = yield* Synthetics.Canary(\"Checkout\", {\n * script: checkoutScript,\n * runtimeVersion: \"syn-nodejs-puppeteer-16.1\",\n * artifactS3Location: \"s3://my-artifacts/checkout\",\n * runConfig: {\n * timeout: \"60 seconds\",\n * environmentVariables: { TARGET_URL: \"https://example.com\" },\n * },\n * successRetentionPeriod: \"7 days\",\n * failureRetentionPeriod: \"31 days\",\n * });\n * ```\n *\n * **Example:** Bring Your Own Execution Role\n * ```typescript\n * const canary = yield* Synthetics.Canary(\"Probe\", {\n * script: probeScript,\n * artifactS3Location: \"s3://my-artifacts/probe\",\n * executionRoleArn: role.roleArn,\n * });\n * ```\n *\n * @resource\n */\nexport const Canary = Resource\u003cCanary>(\"AWS.Synthetics.Canary\");\n\nconst DEFAULT_RUNTIME_VERSION = \"syn-nodejs-puppeteer-16.1\";\nconst DEFAULT_SCHEDULE_EXPRESSION = \"rate(5 minutes)\";\nconst ROLE_POLICY_NAME = \"AlchemyCanaryPolicy\";\nconst VPC_ACCESS_POLICY_ARN =\n \"arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole\";\n\n/**\n * Canary create/update/start/stop are asynchronous; the canary reports a\n * transitional state while converging. Raised internally to drive the\n * bounded settle-polling retry loop.\n */\nexport class CanaryNotSettled extends Data.TaggedError(\"CanaryNotSettled\")\u003c{\n canaryName: string;\n state: string | undefined;\n}> {}\n\n/**\n * Raised when a canary lands in the `ERROR` state after a create or update\n * instead of converging to `READY`/`STOPPED`.\n */\nexport class CanaryFailed extends Data.TaggedError(\"CanaryFailed\")\u003c{\n canaryName: string;\n stateReasonCode: string | undefined;\n message: string;\n}> {}\n\nclass CanaryBackingResourceStillVisible extends Data.TaggedError(\n \"CanaryBackingResourceStillVisible\",\n)\u003c{\n readonly canaryName: string;\n readonly resource: \"LambdaFunction\" | \"LogGroup\";\n readonly identifier: string;\n}> {}\n\nclass UnexpectedCanaryEngineArn extends Data.TaggedError(\"UnexpectedCanaryEngineArn\")\u003c{\n readonly canaryName: string;\n readonly engineArn: string;\n}> {}\n\nconst TRANSITIONAL_STATES = [\"CREATING\", \"UPDATING\", \"STARTING\", \"STOPPING\", \"DELETING\"];\n\n/**\n * Retry an operation while the canary is briefly locked by a concurrent\n * state transition (`ConflictException`), on a bounded schedule (~60s).\n * Module-scope with an explicit return type so the conditional `Retry.Return`\n * type never leaks into declaration emit (which would widen the provider\n * layer to `unknown`).\n */\nconst retryWhileConflict = \u003cA, E extends { _tag: string }, R>(\n self: Effect.Effect\u003cA, E, R>,\n): Effect.Effect\u003cA, E, R> =>\n Effect.retry(self, {\n while: (e) => e._tag === \"ConflictException\",\n schedule: Schedule.max([Schedule.fixed(\"3 seconds\"), Schedule.recurs(20)]),\n });\n\nconst parseArtifactLocation = (location: string) => {\n const stripped = location.startsWith(\"s3://\") ? location.slice(5) : location;\n return {\n artifactS3Location: `s3://${stripped}`,\n artifactBucket: stripped.split(\"/\")[0]!,\n };\n};\n\nconst scriptFilePath = (runtimeVersion: string, handler: string) => {\n const fileName = handler.split(\".\")[0]!;\n return runtimeVersion.startsWith(\"syn-python\")\n ? `python/${fileName}.py`\n : `nodejs/node_modules/${fileName}.js`;\n};\n\n/** Package the inline script as the zip layout the runtime expects. */\nconst buildCode = Effect.fn(function* (script: string, handler: string, runtimeVersion: string) {\n const buffer = yield* zipFiles([\n { path: scriptFilePath(runtimeVersion, handler), content: script },\n ]);\n return {\n ZipFile: new Uint8Array(buffer),\n Handler: handler,\n } satisfies synthetics.CanaryCodeInput;\n});\n\nconst filterTags = (\n tags: { [key: string]: string | undefined } | undefined,\n): Record\u003cstring, string> =>\n Object.fromEntries(\n Object.entries(tags ?? {}).filter((entry): entry is [string, string] => entry[1] !== undefined),\n );\n\nexport const CanaryProvider = () =>\n Provider.effect(\n Canary,\n Effect.gen(function* () {\n const createCanaryName = Effect.fn(function* (\n id: string,\n props: { canaryName?: string | undefined },\n ) {\n if (props.canaryName) return props.canaryName;\n // Canary names must be lowercase [0-9a-z_-]; the console caps them at\n // 21 chars because the backing Lambda is named `cwsyn-\u003cname>-\u003cuuid>`.\n return yield* createPhysicalName({\n id,\n maxLength: 21,\n suffixLength: 8,\n lowercase: true,\n });\n });\n\n const createRoleName = (id: string) => createPhysicalName({ id, maxLength: 64 });\n\n const canaryArnOf = Effect.fn(function* (canaryName: string) {\n const { accountId, region } = yield* AWSEnvironment.current;\n return `arn:aws:synthetics:${region}:${accountId}:canary:${canaryName}`;\n });\n\n const getCanaryOrUndefined = Effect.fn(function* (canaryName: string) {\n return yield* synthetics.getCanary({ Name: canaryName }).pipe(\n Effect.map((r) => r.Canary),\n Effect.catchTag(\"ResourceNotFoundException\", () => Effect.undefined),\n );\n });\n\n // Poll until the canary leaves its transitional state. Create typically\n // settles in 30-90s; budget 3 minutes (60 * 3s).\n const waitForSettled = Effect.fn(function* (canaryName: string) {\n return yield* getCanaryOrUndefined(canaryName).pipe(\n Effect.flatMap((canary) =>\n canary !== undefined && TRANSITIONAL_STATES.includes(canary.Status?.State ?? \"\")\n ? Effect.fail(\n new CanaryNotSettled({\n canaryName,\n state: canary.Status?.State,\n }),\n )\n : Effect.succeed(canary),\n ),\n Effect.retry({\n while: (e) => e instanceof CanaryNotSettled,\n schedule: Schedule.max([Schedule.fixed(\"3 seconds\"), Schedule.recurs(60)]),\n }),\n );\n });\n\n const failIfErrored = (canaryName: string, canary: synthetics.Canary | undefined) =>\n canary?.Status?.State === \"ERROR\"\n ? Effect.fail(\n new CanaryFailed({\n canaryName,\n stateReasonCode: canary.Status?.StateReasonCode,\n message: canary.Status?.StateReason ?? `canary ${canaryName} is in ERROR state`,\n }),\n )\n : Effect.void;\n\n // Deletion is asynchronous (DELETING); wait until gone so a\n // destroy-then-deploy of the same logical resource (same physical\n // name) does not race the pending delete.\n const waitUntilGone = Effect.fn(function* (canaryName: string) {\n yield* getCanaryOrUndefined(canaryName).pipe(\n Effect.flatMap((canary) =>\n canary === undefined\n ? Effect.void\n : Effect.fail(\n new CanaryNotSettled({\n canaryName,\n state: canary.Status?.State,\n }),\n ),\n ),\n Effect.retry({\n while: (e) => e instanceof CanaryNotSettled,\n schedule: Schedule.max([Schedule.fixed(\"3 seconds\"), Schedule.recurs(40)]),\n }),\n );\n });\n\n // Stop (if running) + delete + wait-until-gone. Also used by reconcile\n // to self-heal a canary stuck in CREATE_FAILED.\n const deleteCanaryAndWait = Effect.fn(function* (canaryName: string) {\n const observed = yield* getCanaryOrUndefined(canaryName);\n if (observed === undefined) return;\n const state = observed.Status?.State;\n if (state === \"RUNNING\" || state === \"STARTING\") {\n yield* synthetics\n .stopCanary({ Name: canaryName })\n .pipe(\n Effect.catchTag(\n [\"ResourceNotFoundException\", \"ConflictException\"],\n () => Effect.void,\n ),\n );\n }\n // wait out any transitional state (STOPPING, UPDATING, ...) — a\n // canary can only be deleted from READY/STOPPED/ERROR.\n yield* waitForSettled(canaryName);\n yield* synthetics.deleteCanary({ Name: canaryName, DeleteLambda: true }).pipe(\n // e.g. a run is still finishing; bounded retry\n retryWhileConflict,\n Effect.catchTag(\"ResourceNotFoundException\", () => Effect.void),\n );\n yield* waitUntilGone(canaryName);\n });\n\n const backingFunctionName = (canaryName: string, engineArn: string) => {\n const marker = \":function:\";\n const markerIndex = engineArn.indexOf(marker);\n const functionName =\n markerIndex === -1\n ? undefined\n : engineArn.slice(markerIndex + marker.length).split(\":\")[0];\n // EngineArn is observed directly from this owned canary. Retain an\n // explicit name check so a malformed or unexpectedly-shaped response\n // can never make deletion target another Lambda.\n return functionName?.startsWith(`cwsyn-${canaryName}-`)\n ? Effect.succeed(functionName)\n : Effect.fail(new UnexpectedCanaryEngineArn({ canaryName, engineArn }));\n };\n\n const discoverBackingFunctionNames = Effect.fn(function* (\n canaryName: string,\n engineArn: string | undefined,\n ) {\n if (engineArn) {\n return [yield* backingFunctionName(canaryName, engineArn)];\n }\n\n // EngineArn is optional and is absent on some Synthetics runtimes.\n // The backing Lambda's only observable relationship is its service\n // name. Require the complete canonical UUID suffix so a canary named\n // `foo` can never capture another named `foo-bar`.\n const escapedCanaryName = canaryName.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\

Loading Sailfork

\");\n const exactBackingName = new RegExp(\n `^cwsyn-${escapedCanaryName}-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12} .repos/alchemy-effect/packages/aws/src/Synthetics/Canary.ts at main · sailfork/t3code-github · Sailfork
,\n \"i\",\n );\n const pages = yield* lambda.listFunctions.pages({}).pipe(Stream.runCollect);\n return Array.from(pages)\n .flatMap((page) => page.Functions ?? [])\n .flatMap((fn) =>\n fn.FunctionName && exactBackingName.test(fn.FunctionName) ? [fn.FunctionName] : [],\n );\n });\n\n const backingFunctionExists = (functionName: string) =>\n lambda.getFunction({ FunctionName: functionName }).pipe(\n Effect.as(true),\n Effect.catchTag(\"ResourceNotFoundException\", () => Effect.succeed(false)),\n );\n\n const exactLogGroupExists = (logGroupName: string) =>\n logs\n .describeLogGroups({\n logGroupNamePrefix: logGroupName,\n limit: 50,\n })\n .pipe(\n Effect.map((response) =>\n (response.logGroups ?? []).some((group) => group.logGroupName === logGroupName),\n ),\n );\n\n const waitForBackingResourceGone = \u003cE extends { readonly _tag: string }, R>(\n canaryName: string,\n resource: \"LambdaFunction\" | \"LogGroup\",\n identifier: string,\n exists: Effect.Effect\u003cboolean, E, R>,\n ) =>\n exists.pipe(\n Effect.flatMap((visible) =>\n visible\n ? Effect.fail(\n new CanaryBackingResourceStillVisible({\n canaryName,\n resource,\n identifier,\n }),\n )\n : Effect.void,\n ),\n Effect.retry({\n while: (error) => error._tag === \"CanaryBackingResourceStillVisible\",\n schedule: Schedule.max([Schedule.fixed(\"2 seconds\"), Schedule.recurs(20)]),\n }),\n );\n\n const deleteBackingResources = Effect.fn(function* (\n canaryName: string,\n functionName: string,\n ) {\n const logGroupName = `/aws/lambda/${functionName}`;\n\n yield* lambda.deleteFunction({ FunctionName: functionName }).pipe(\n Effect.retry({\n while: (error) => error._tag === \"ResourceConflictException\",\n schedule: Schedule.max([Schedule.fixed(\"2 seconds\"), Schedule.recurs(20)]),\n }),\n Effect.catchTag(\"ResourceNotFoundException\", () => Effect.void),\n );\n yield* waitForBackingResourceGone(\n canaryName,\n \"LambdaFunction\",\n functionName,\n backingFunctionExists(functionName),\n );\n\n // Lambda never owns its log group lifecycle. A just-finished\n // invocation can flush its final stream after Lambda deletion starts,\n // so reap this exact group across a short quiescence window.\n for (let attempt = 0; attempt \u003c 5; attempt++) {\n if (yield* exactLogGroupExists(logGroupName)) {\n yield* logs.deleteLogGroup({ logGroupName }).pipe(\n Effect.retry({\n while: (error) => error._tag === \"OperationAbortedException\",\n schedule: Schedule.max([Schedule.fixed(\"2 seconds\"), Schedule.recurs(15)]),\n }),\n Effect.catchTag(\"ResourceNotFoundException\", () => Effect.void),\n );\n }\n yield* Effect.sleep(\"2 seconds\");\n }\n yield* waitForBackingResourceGone(\n canaryName,\n \"LogGroup\",\n logGroupName,\n exactLogGroupExists(logGroupName),\n );\n });\n\n /**\n * Ensure the auto-created execution role exists and its inline policy\n * matches the artifact bucket. Every step is idempotent: create\n * tolerates AlreadyExists, putRolePolicy is an upsert.\n */\n const ensureExecutionRole = Effect.fn(function* ({\n id,\n roleName,\n artifactBucket,\n vpc,\n }: {\n id: string;\n roleName: string;\n artifactBucket: string;\n vpc: boolean;\n }) {\n const { accountId, region } = yield* AWSEnvironment.current;\n const internalTags = yield* createInternalTags(id);\n // Track whether we actually created the role on this pass — a fresh\n // role needs a propagation grace period before Synthetics can build\n // the backing Lambda with it.\n let created = true;\n yield* iam\n .createRole({\n RoleName: roleName,\n AssumeRolePolicyDocument: JSON.stringify({\n Version: \"2012-10-17\",\n Statement: [\n {\n Effect: \"Allow\",\n Principal: { Service: \"lambda.amazonaws.com\" },\n Action: \"sts:AssumeRole\",\n },\n ],\n }),\n Tags: createTagsList(internalTags),\n })\n .pipe(\n Effect.catchTag(\"EntityAlreadyExistsException\", () =>\n Effect.sync(() => {\n created = false;\n }),\n ),\n );\n yield* iam.putRolePolicy({\n RoleName: roleName,\n PolicyName: ROLE_POLICY_NAME,\n PolicyDocument: JSON.stringify({\n Version: \"2012-10-17\",\n Statement: [\n {\n Effect: \"Allow\",\n Action: [\"s3:PutObject\", \"s3:GetObject\"],\n Resource: [`arn:aws:s3:::${artifactBucket}/*`],\n },\n {\n Effect: \"Allow\",\n Action: [\"s3:GetBucketLocation\"],\n Resource: [`arn:aws:s3:::${artifactBucket}`],\n },\n {\n Effect: \"Allow\",\n Action: [\"s3:ListAllMyBuckets\"],\n Resource: [\"*\"],\n },\n {\n Effect: \"Allow\",\n Action: [\"cloudwatch:PutMetricData\"],\n Resource: [\"*\"],\n Condition: {\n StringEquals: {\n \"cloudwatch:namespace\": \"CloudWatchSynthetics\",\n },\n },\n },\n {\n Effect: \"Allow\",\n Action: [\"logs:CreateLogGroup\", \"logs:CreateLogStream\", \"logs:PutLogEvents\"],\n Resource: [`arn:aws:logs:${region}:${accountId}:log-group:/aws/lambda/cwsyn-*`],\n },\n {\n Effect: \"Allow\",\n Action: [\"xray:PutTraceSegments\"],\n Resource: [\"*\"],\n },\n ],\n }),\n });\n if (vpc) {\n yield* iam.attachRolePolicy({\n RoleName: roleName,\n PolicyArn: VPC_ACCESS_POLICY_ARN,\n });\n }\n if (created) {\n // IAM is eventually consistent — a canary created immediately after\n // the role lands in CREATE_FAILED with \"The role defined for the\n // function cannot be assumed by Lambda\". Give the role time to\n // propagate; the CREATE_FAILED recreate loop below covers stragglers.\n yield* Effect.sleep(\"10 seconds\");\n }\n return `arn:aws:iam::${accountId}:role/${roleName}`;\n });\n\n // Tear down the auto-created execution role. Idempotent: every step\n // tolerates the entity being gone.\n const deleteExecutionRole = Effect.fn(function* (roleName: string) {\n yield* iam\n .deleteRolePolicy({\n RoleName: roleName,\n PolicyName: ROLE_POLICY_NAME,\n })\n .pipe(Effect.catchTag(\"NoSuchEntityException\", () => Effect.void));\n yield* iam\n .detachRolePolicy({\n RoleName: roleName,\n PolicyArn: VPC_ACCESS_POLICY_ARN,\n })\n .pipe(Effect.catchTag(\"NoSuchEntityException\", () => Effect.void));\n yield* iam.deleteRole({ RoleName: roleName }).pipe(\n Effect.retry({\n while: (error) =>\n error._tag === \"ConcurrentModificationException\" ||\n error._tag === \"DeleteConflictException\" ||\n error._tag === \"LimitExceededException\" ||\n error._tag === \"ServiceFailureException\",\n schedule: Schedule.max([Schedule.fixed(\"1 second\"), Schedule.recurs(20)]),\n }),\n Effect.catchTag(\"NoSuchEntityException\", () => Effect.void),\n );\n\n // IAM deletion is eventually consistent. Keep the canary's state\n // until its owned execution role is observably absent so a following\n // nuke cannot race the successful DeleteRole request.\n for (let attempt = 0; attempt \u003c 30; attempt++) {\n const remaining = yield* iam\n .getRole({ RoleName: roleName })\n .pipe(Effect.catchTag(\"NoSuchEntityException\", () => Effect.undefined));\n if (remaining === undefined) return;\n yield* Effect.sleep(\"1 second\");\n }\n return yield* Effect.die(\n new Error(\n `Synthetics execution role ${roleName} remained observable 30 seconds after delete`,\n ),\n );\n });\n\n const desiredConfigHash = (\n props: CanaryProps,\n executionRoleArn: string,\n artifactS3Location: string,\n runtimeVersion: string,\n ) =>\n sha256Object({\n script: props.script,\n handler: props.handler ?? \"index.handler\",\n runtimeVersion,\n artifactS3Location,\n executionRoleArn,\n schedule: {\n expression: props.schedule?.expression ?? DEFAULT_SCHEDULE_EXPRESSION,\n durationInSeconds: toWireSeconds(props.schedule?.duration) ?? 0,\n },\n runConfig:\n props.runConfig === undefined\n ? {}\n : {\n ...props.runConfig,\n timeout: undefined,\n timeoutInSeconds: toWireSeconds(props.runConfig.timeout),\n },\n successRetentionPeriodInDays: toWireDays(props.successRetentionPeriod),\n failureRetentionPeriodInDays: toWireDays(props.failureRetentionPeriod),\n vpcConfig: props.vpcConfig,\n provisionedResourceCleanup: props.provisionedResourceCleanup ?? \"AUTOMATIC\",\n });\n\n const toRunConfigInput = (props: CanaryProps): synthetics.CanaryRunConfigInput | undefined =>\n props.runConfig === undefined\n ? undefined\n : {\n TimeoutInSeconds: toWireSeconds(props.runConfig.timeout),\n MemoryInMB: props.runConfig.memoryInMB,\n ActiveTracing: props.runConfig.activeTracing,\n EnvironmentVariables: props.runConfig.environmentVariables,\n };\n\n const toScheduleInput = (props: CanaryProps): synthetics.CanaryScheduleInput => ({\n Expression: props.schedule?.expression ?? DEFAULT_SCHEDULE_EXPRESSION,\n DurationInSeconds: toWireSeconds(props.schedule?.duration),\n });\n\n const toVpcConfigInput = (props: CanaryProps): synthetics.VpcConfigInput | undefined =>\n props.vpcConfig === undefined\n ? undefined\n : {\n SubnetIds: props.vpcConfig.subnetIds,\n SecurityGroupIds: props.vpcConfig.securityGroupIds,\n };\n\n return Canary.Provider.of({\n stables: [\"canaryName\", \"canaryArn\", \"canaryId\", \"roleName\", \"engineArn\"],\n\n // Enumerate every canary in the ambient account/region.\n list: () =>\n Effect.gen(function* () {\n const pages = yield* synthetics.describeCanaries.pages({}).pipe(Stream.runCollect);\n const canaries = Array.from(pages).flatMap((page) => page.Canaries ?? []);\n const items: Canary[\"Attributes\"][] = [];\n for (const canary of canaries) {\n if (!canary.Name) continue;\n items.push({\n canaryName: canary.Name,\n canaryArn: yield* canaryArnOf(canary.Name),\n canaryId: canary.Id ?? \"\",\n executionRoleArn: canary.ExecutionRoleArn ?? \"\",\n artifactS3Location: canary.ArtifactS3Location\n ? parseArtifactLocation(canary.ArtifactS3Location).artifactS3Location\n : \"\",\n runtimeVersion: canary.RuntimeVersion ?? \"\",\n roleName: undefined,\n configHash: undefined,\n engineArn: canary.EngineArn,\n });\n }\n return items;\n }),\n\n read: Effect.fn(function* ({ id, olds, output }) {\n const canaryName = output?.canaryName ?? (yield* createCanaryName(id, olds ?? {}));\n const canary = yield* getCanaryOrUndefined(canaryName);\n if (canary === undefined) return undefined;\n const attrs: Canary[\"Attributes\"] = {\n canaryName,\n canaryArn: yield* canaryArnOf(canaryName),\n canaryId: canary.Id ?? \"\",\n executionRoleArn: canary.ExecutionRoleArn ?? \"\",\n artifactS3Location: canary.ArtifactS3Location\n ? parseArtifactLocation(canary.ArtifactS3Location).artifactS3Location\n : \"\",\n runtimeVersion: canary.RuntimeVersion ?? \"\",\n roleName: output?.roleName,\n configHash: output?.configHash,\n engineArn: canary.EngineArn ?? output?.engineArn,\n };\n const tags = filterTags(canary.Tags);\n return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);\n }),\n\n diff: Effect.fn(function* ({ id, news, olds }) {\n if (!isResolved(news)) return undefined;\n const oldName = yield* createCanaryName(id, olds);\n const newName = yield* createCanaryName(id, news);\n if (oldName !== newName) {\n return { action: \"replace\" } as const;\n }\n // everything else converges through updateCanary\n }),\n\n reconcile: Effect.fn(function* ({ id, news, output, session }) {\n const canaryName = output?.canaryName ?? (yield* createCanaryName(id, news));\n const canaryArn = yield* canaryArnOf(canaryName);\n const internalTags = yield* createInternalTags(id);\n const desiredTags = { ...news.tags, ...internalTags };\n const { artifactS3Location, artifactBucket } = parseArtifactLocation(\n news.artifactS3Location,\n );\n const runtimeVersion = news.runtimeVersion ?? DEFAULT_RUNTIME_VERSION;\n const handler = news.handler ?? \"index.handler\";\n\n // Ensure the execution role (user-supplied or auto-created, with\n // its inline policy converged to the current artifact bucket).\n let roleName: string | undefined;\n let executionRoleArn: string;\n if (news.executionRoleArn) {\n executionRoleArn = news.executionRoleArn;\n } else {\n roleName = output?.roleName ?? (yield* createRoleName(id));\n executionRoleArn = yield* ensureExecutionRole({\n id,\n roleName,\n artifactBucket,\n vpc: news.vpcConfig !== undefined,\n });\n }\n\n const configHash = yield* desiredConfigHash(\n news,\n executionRoleArn,\n artifactS3Location,\n runtimeVersion,\n );\n\n // 1. OBSERVE — cloud state is authoritative.\n let observed = yield* getCanaryOrUndefined(canaryName);\n\n // Self-heal a canary stuck in CREATE_FAILED (e.g. a crashed prior\n // deploy): it cannot be updated, only deleted and recreated.\n if (\n observed?.Status?.State === \"ERROR\" &&\n observed.Status?.StateReasonCode === \"CREATE_FAILED\"\n ) {\n yield* session.note(\n `canary ${canaryName} is in CREATE_FAILED (${observed.Status?.StateReason}); recreating`,\n );\n yield* deleteCanaryAndWait(canaryName);\n observed = undefined;\n }\n\n // 2. ENSURE — create if missing; wait for the async create to\n // settle (CREATING → READY, typically 30-90s).\n if (observed === undefined) {\n const code = yield* buildCode(news.script, handler, runtimeVersion);\n // Canary creation is asynchronous and validated in the backend:\n // an execution role that hasn't finished propagating surfaces as\n // CREATE_FAILED (\"role ... cannot be assumed by Lambda\") only\n // AFTER the create settles. A CREATE_FAILED canary can't be\n // updated — delete it and recreate, bounded to 3 attempts.\n for (let attempt = 0; ; attempt++) {\n yield* synthetics.createCanary({\n Name: canaryName,\n Code: code,\n ArtifactS3Location: artifactS3Location,\n ExecutionRoleArn: executionRoleArn,\n Schedule: toScheduleInput(news),\n RunConfig: toRunConfigInput(news),\n RuntimeVersion: runtimeVersion,\n SuccessRetentionPeriodInDays: toWireDays(news.successRetentionPeriod),\n FailureRetentionPeriodInDays: toWireDays(news.failureRetentionPeriod),\n VpcConfig: toVpcConfigInput(news),\n ProvisionedResourceCleanup: news.provisionedResourceCleanup ?? \"AUTOMATIC\",\n Tags: desiredTags,\n });\n yield* session.note(`created canary ${canaryName}, waiting for it to become ready`);\n observed = yield* waitForSettled(canaryName);\n if (\n observed?.Status?.State === \"ERROR\" &&\n observed.Status?.StateReasonCode === \"CREATE_FAILED\"\n ) {\n // A failed create is not persisted by the engine, so leaving\n // the CREATE_FAILED canary behind would leak it — delete it\n // whether we retry or give up.\n yield* session.note(\n `canary create failed (${observed.Status?.StateReason}); deleting`,\n );\n yield* deleteCanaryAndWait(canaryName);\n if (attempt \u003c 2) {\n yield* Effect.sleep(\"10 seconds\");\n continue;\n }\n // Giving up — the engine does not persist a failed create, so\n // also remove the execution role we auto-created this pass.\n if (roleName !== undefined) {\n yield* deleteExecutionRole(roleName);\n }\n }\n yield* failIfErrored(canaryName, observed);\n break;\n }\n } else {\n // 3. SYNC config — the script content is not observable from the\n // API (only a source-location ARN), so we use the persisted\n // configHash as a skip-hint; on adoption (no hash) or any prop\n // change we push the full desired configuration, which is\n // idempotent.\n observed = yield* waitForSettled(canaryName);\n yield* failIfErrored(canaryName, observed);\n if (output?.configHash !== configHash) {\n const code = yield* buildCode(news.script, handler, runtimeVersion);\n yield* synthetics\n .updateCanary({\n Name: canaryName,\n Code: code,\n ExecutionRoleArn: executionRoleArn,\n RuntimeVersion: runtimeVersion,\n Schedule: toScheduleInput(news),\n RunConfig: toRunConfigInput(news),\n SuccessRetentionPeriodInDays: toWireDays(news.successRetentionPeriod),\n FailureRetentionPeriodInDays: toWireDays(news.failureRetentionPeriod),\n VpcConfig: toVpcConfigInput(news),\n ArtifactS3Location: artifactS3Location,\n ProvisionedResourceCleanup: news.provisionedResourceCleanup ?? \"AUTOMATIC\",\n })\n .pipe(retryWhileConflict);\n yield* session.note(`updated canary ${canaryName}`);\n observed = yield* waitForSettled(canaryName);\n yield* failIfErrored(canaryName, observed);\n }\n }\n\n // 4. SYNC run state — start/stop to match the `start` prop.\n const desiredRunning = news.start ?? false;\n const state = observed?.Status?.State;\n if (desiredRunning && state !== \"RUNNING\") {\n yield* synthetics.startCanary({ Name: canaryName }).pipe(retryWhileConflict);\n yield* session.note(`started canary ${canaryName}`);\n observed = yield* waitForSettled(canaryName);\n } else if (!desiredRunning && state === \"RUNNING\") {\n yield* synthetics\n .stopCanary({ Name: canaryName })\n .pipe(Effect.catchTag(\"ConflictException\", () => Effect.void));\n yield* session.note(`stopped canary ${canaryName}`);\n observed = yield* waitForSettled(canaryName);\n }\n\n // 5. SYNC tags — diff against OBSERVED cloud tags so adoption\n // converges (create already applied them; update cannot).\n const currentTags = filterTags(observed?.Tags);\n const { upsert, removed } = diffTags(currentTags, desiredTags);\n if (upsert.length > 0) {\n yield* synthetics.tagResource({\n ResourceArn: canaryArn,\n Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),\n });\n }\n if (removed.length > 0) {\n yield* synthetics.untagResource({\n ResourceArn: canaryArn,\n TagKeys: removed,\n });\n }\n\n yield* session.note(canaryName);\n return {\n canaryName,\n canaryArn,\n canaryId: observed?.Id ?? \"\",\n executionRoleArn,\n artifactS3Location,\n runtimeVersion,\n roleName,\n configHash,\n engineArn: observed?.EngineArn,\n };\n }),\n\n delete: Effect.fn(function* ({ output, session }) {\n const observed = yield* getCanaryOrUndefined(output.canaryName);\n const engineArn = observed?.EngineArn ?? output.engineArn;\n const backingFunctions = yield* discoverBackingFunctionNames(\n output.canaryName,\n engineArn,\n );\n yield* deleteCanaryAndWait(output.canaryName);\n for (const functionName of backingFunctions) {\n yield* session.note(\n `deleting exact backing Lambda ${functionName} and log group /aws/lambda/${functionName}`,\n );\n yield* deleteBackingResources(output.canaryName, functionName);\n }\n // Clean up the auto-created execution role (never a user-supplied\n // one).\n if (output.roleName) {\n yield* deleteExecutionRole(output.roleName);\n }\n }),\n });\n }),\n );\n","preview":null,"history":null,"version":"20fd5cfd3b5ec92fbee7714e2182968cf005583b"},"/_session?shell=1":null}