@composurecdk/lambda 0.10.0 → 0.10.1

package/dist/esm/invoke-on-deploy.js

@@ -0,0 +1,151 @@
+import { Annotations, Duration } from "aws-cdk-lib";
+import { InvocationType, Trigger } from "aws-cdk-lib/triggers";
+import { addDependencies } from "@composurecdk/core";
+/**
+ * Suppression id for the deploy-time invocation timeout guard. Stable and part
+ * of the public surface — silence the warning with
+ * `Annotations.of(scope).acknowledgeWarning(INVOKE_ON_DEPLOY_TIMEOUT_WARNING_ID)`,
+ * so it must not be renamed casually.
+ */
+export const INVOKE_ON_DEPLOY_TIMEOUT_WARNING_ID = "@composurecdk/lambda:invoke-on-deploy-timeout";
+/**
+ * The deployment waits for the handler's response, so a handler that throws
+ * fails the stack. An invariant of the action rather than a default: the
+ * asynchronous alternative returns before the work happens, reporting success
+ * whatever the handler did, so there is nothing to override to.
+ *
+ * @see https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_tracking_change_management_deployment_management.html
+ */
+const INVOCATION_TYPE = InvocationType.REQUEST_RESPONSE;
+/**
+ * The trigger provider's own Lambda timeout. CDK builds that provider from
+ * `CustomResourceProviderBase`, which defaults to 15 minutes, and `Trigger`
+ * overrides nothing — so there is no seam to raise it through and no way to
+ * read it back. Asserted against a synthesised template in the test suite, so
+ * an `aws-cdk-lib` upgrade that changes the default fails loudly here rather
+ * than quietly reopening the hang this ceiling exists to prevent.
+ */
+const PROVIDER_TIMEOUT = Duration.minutes(15);
+/**
+ * Added to the function's own `timeout` to derive the wait, and subtracted
+ * from {@link PROVIDER_TIMEOUT} to derive {@link MAX_TIMEOUT} — the same slack
+ * at both ends, for the same reason: whoever is waiting must outlive whoever
+ * they are waiting for, or the error is never reported.
+ */
+const TIMEOUT_MARGIN = Duration.seconds(30);
+/**
+ * Ceiling for the wait. The provider must outlive the invocation it is waiting
+ * on, or it dies mid-wait and posts nothing back to CloudFormation. `Trigger`
+ * sets no `ServiceTimeout` on the custom resource, so that is not a failed
+ * deployment — it is a *hung* one, until CloudFormation abandons the stack
+ * operation of its own accord.
+ */
+const MAX_TIMEOUT = PROVIDER_TIMEOUT.minus(TIMEOUT_MARGIN);
+/**
+ * The wait applied when the function's own timeout is unset or a token, and so
+ * yields no concrete value to derive from. Matches the CDK `Trigger` default.
+ */
+const FALLBACK_TIMEOUT = Duration.minutes(2);
+/**
+ * How {@link IFunctionBuilder.invokeOnDeploy | `.invokeOnDeploy()`} derives the
+ * wait when the caller sets no {@link InvokeOnDeployOptions.timeout}. A public
+ * mirror of this module's constants, exported for visibility and testing — the
+ * rationale for each value is on the constant it mirrors.
+ */
+export const INVOKE_ON_DEPLOY_DEFAULTS = {
+    /** @see {@link TIMEOUT_MARGIN} */
+    timeoutMargin: TIMEOUT_MARGIN,
+    /** @see {@link FALLBACK_TIMEOUT} */
+    fallbackTimeout: FALLBACK_TIMEOUT,
+    /** @see {@link MAX_TIMEOUT} */
+    maxTimeout: MAX_TIMEOUT,
+};
+/**
+ * Creates the custom resource that invokes `handler` during deployment and
+ * fails the stack if it errors.
+ *
+ * The invocation is ordered after the function's execution role, so the policies
+ * attached *to it* by `.grant()` / `.configureRole()` — which CloudFormation
+ * does not otherwise sequence ahead of a custom resource — exist by the time the
+ * handler runs.
+ *
+ * That reaches the identity half of a grant only: one that also writes a
+ * resource policy (a KMS key policy, a cross-account bucket policy) leaves that
+ * half in the granting resource's tree, and an imported role contributes no
+ * resources to sequence at all. Both are the consumer's to declare through
+ * {@link InvokeOnDeployOptions.after}, as is anything else the call needs.
+ *
+ * @internal
+ */
+export function createDeploymentTrigger(scope, id, handler, executionRole, options, context) {
+    const timeout = resolveWait(options.timeout, handler.timeout, id);
+    warnOnShortWait(handler, id, timeout);
+    const trigger = new Trigger(scope, `${id}DeploymentTrigger`, {
+        handler,
+        invocationType: INVOCATION_TYPE,
+        timeout,
+        executeOnHandlerChange: options.executeOnHandlerChange,
+    });
+    addDependencies(trigger, [executionRole, ...(options.after ?? [])], context);
+    return trigger;
+}
+/**
+ * How long the deployment waits.
+ *
+ * {@link MAX_TIMEOUT} binds both branches, but differently. A derived wait is
+ * capped: the derivation is the library's, so quietly settling for less than it
+ * wanted is the library's business. An explicit wait over the ceiling throws —
+ * clamping would honour neither the duration the caller asked for nor the
+ * failing deployment they expected, and there is no working form to fall back
+ * to. Both are silent on a token, which has no value to compare.
+ */
+function resolveWait(explicitWait, handlerTimeout, id) {
+    if (explicitWait !== undefined) {
+        const waitSeconds = concreteSeconds(explicitWait);
+        if (waitSeconds !== undefined && waitSeconds > MAX_TIMEOUT.toSeconds()) {
+            throw new Error(`FunctionBuilder "${id}": .invokeOnDeploy() was given a timeout of ${String(waitSeconds)}s, ` +
+                `but the deployment cannot wait longer than ${String(MAX_TIMEOUT.toSeconds())}s — CDK's ` +
+                `trigger provider runs with a ${String(PROVIDER_TIMEOUT.toSeconds())}s Lambda timeout ` +
+                `and needs the remainder to report the result. A longer wait does not fail the ` +
+                `deployment, it hangs it: the provider dies mid-invocation and CloudFormation is never ` +
+                `told. Lower the timeout, or move work that needs longer out of the deployment.`);
+        }
+        return explicitWait;
+    }
+    const handlerSeconds = concreteSeconds(handlerTimeout);
+    if (handlerSeconds === undefined)
+        return FALLBACK_TIMEOUT;
+    const derived = handlerSeconds + TIMEOUT_MARGIN.toSeconds();
+    return Duration.seconds(Math.min(derived, MAX_TIMEOUT.toSeconds()));
+}
+/** A `Duration` in seconds, or `undefined` when it is unset or a token. */
+function concreteSeconds(duration) {
+    if (duration === undefined || duration.isUnresolved())
+        return undefined;
+    return duration.toSeconds();
+}
+/**
+ * Warns when the deployment would stop waiting before the handler's own timeout
+ * — a handler that runs long then fails the stack as an abandoned invocation
+ * rather than reporting the error it was about to produce.
+ *
+ * Checked against the final wait, whether the caller set it or it was derived,
+ * because the derived path can land here too: the cap leaves no margin once the
+ * function's own timeout reaches {@link MAX_TIMEOUT}.
+ * Silent whenever either value is a token, with nothing to compare.
+ */
+function warnOnShortWait(handler, id, wait) {
+    const waitSeconds = concreteSeconds(wait);
+    const handlerSeconds = concreteSeconds(handler.timeout);
+    if (waitSeconds === undefined || handlerSeconds === undefined)
+        return;
+    if (waitSeconds > handlerSeconds)
+        return;
+    Annotations.of(handler).addWarningV2(INVOKE_ON_DEPLOY_TIMEOUT_WARNING_ID, `FunctionBuilder "${id}": .invokeOnDeploy() waits ${String(waitSeconds)}s but the function's ` +
+        `own timeout is ${String(handlerSeconds)}s — the deployment stops waiting while the handler ` +
+        `is still running, so a slow call fails the stack as an abandoned invocation instead of ` +
+        `reporting the handler's error. Give the deployment longer than the function's timeout (up ` +
+        `to ${String(MAX_TIMEOUT.toSeconds())}s), shorten the function's ` +
+        `timeout, or acknowledge "${INVOKE_ON_DEPLOY_TIMEOUT_WARNING_ID}".`);
+}
+//# sourceMappingURL=invoke-on-deploy.js.map

package/dist/esm/invoke-on-deploy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke-on-deploy.js","sourceRoot":"","sources":["../../src/invoke-on-deploy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,EAAE,eAAe,EAAyB,MAAM,oBAAoB,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,+CAA+C,CAAC;AAEnG;;;;;;;GAOG;AACH,MAAM,eAAe,GAAG,cAAc,CAAC,gBAAgB,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAG,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,cAAc,GAAG,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,GAAG,gBAAgB,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;AAE3D;;;GAGG;AACH,MAAM,gBAAgB,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,kCAAkC;IAClC,aAAa,EAAE,cAAc;IAE7B,oCAAoC;IACpC,eAAe,EAAE,gBAAgB;IAEjC,+BAA+B;IAC/B,UAAU,EAAE,WAAW;CACf,CAAC;AA2CX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAiB,EACjB,EAAU,EACV,OAAuB,EACvB,aAAyB,EACzB,OAA8B,EAC9B,OAA+B;IAE/B,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAClE,eAAe,CAAC,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IAEtC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,mBAAmB,EAAE;QAC3D,OAAO;QACP,cAAc,EAAE,eAAe;QAC/B,OAAO;QACP,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;KACvD,CAAC,CAAC;IAEH,eAAe,CAAC,OAAO,EAAE,CAAC,aAAa,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC7E,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,WAAW,CAClB,YAAkC,EAClC,cAAoC,EACpC,EAAU;IAEV,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,WAAW,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;QAClD,IAAI,WAAW,KAAK,SAAS,IAAI,WAAW,GAAG,WAAW,CAAC,SAAS,EAAE,EAAE,CAAC;YACvE,MAAM,IAAI,KAAK,CACb,oBAAoB,EAAE,+CAA+C,MAAM,CAAC,WAAW,CAAC,KAAK;gBAC3F,8CAA8C,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC,YAAY;gBACzF,gCAAgC,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,mBAAmB;gBACvF,gFAAgF;gBAChF,wFAAwF;gBACxF,gFAAgF,CACnF,CAAC;QACJ,CAAC;QACD,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,MAAM,cAAc,GAAG,eAAe,CAAC,cAAc,CAAC,CAAC;IACvD,IAAI,cAAc,KAAK,SAAS;QAAE,OAAO,gBAAgB,CAAC;IAE1D,MAAM,OAAO,GAAG,cAAc,GAAG,cAAc,CAAC,SAAS,EAAE,CAAC;IAC5D,OAAO,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,2EAA2E;AAC3E,SAAS,eAAe,CAAC,QAA8B;IACrD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,YAAY,EAAE;QAAE,OAAO,SAAS,CAAC;IACxE,OAAO,QAAQ,CAAC,SAAS,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,eAAe,CAAC,OAAuB,EAAE,EAAU,EAAE,IAAc;IAC1E,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,cAAc,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD,IAAI,WAAW,KAAK,SAAS,IAAI,cAAc,KAAK,SAAS;QAAE,OAAO;IACtE,IAAI,WAAW,GAAG,cAAc;QAAE,OAAO;IAEzC,WAAW,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,YAAY,CAClC,mCAAmC,EACnC,oBAAoB,EAAE,8BAA8B,MAAM,CAAC,WAAW,CAAC,uBAAuB;QAC5F,kBAAkB,MAAM,CAAC,cAAc,CAAC,qDAAqD;QAC7F,yFAAyF;QACzF,4FAA4F;QAC5F,MAAM,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC,6BAA6B;QAClE,4BAA4B,mCAAmC,IAAI,CACtE,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composurecdk/lambda",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Composable Lambda function builder with well-architected defaults",
   "repository": {
     "type": "git",
@@ -59,8 +59,8 @@
   "devDependencies": {
     "@composurecdk/cdk-testing": "*",
     "@composurecdk/iam": "^0.10.0",
-    "@types/node": "^26.5.1",
-    "aws-cdk-lib": "^2.268.0",
+    "@types/node": "^26.6.1",
+    "aws-cdk-lib": "^2.269.0",
     "constructs": "^10.8.1",
     "ts-fake": "^1.2.0",
     "typescript": "^6.0.3",