ec2-instance-running-scheduler 0.1.9 → 0.2.1

package/.jsii

@@ -8435,14 +8435,20 @@
       }
     }
   },
-  "description": "ec2-instance-running-scheduler",
+  "description": "AWS CDK construct library that starts and stops EC2 instances on a cron schedule using EventBridge Scheduler and a Durable Execution Lambda. The handler discovers instances with the Resource Groups Tagging API, issues start/stop, polls until each instance reaches a stable target state (durable step / wait), processes multiple instances in parallel (bounded concurrency), and posts Slack summary and per-instance thread messages using a secret from Secrets Manager. The Lambda emits structured application logs alongside JSON platform logs.",
   "docs": {
     "stability": "stable"
   },
   "homepage": "https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler.git",
   "jsiiVersion": "5.9.44 (build 150b837)",
   "keywords": [
-    "cdk"
+    "cdk",
+    "durable",
+    "ec2",
+    "execution",
+    "lambda",
+    "scheduler",
+    "slack"
   ],
   "license": "Apache-2.0",
   "metadata": {
@@ -8455,7 +8461,7 @@
   },
   "name": "ec2-instance-running-scheduler",
   "readme": {
-    "markdown": "# EC2 Instance Running Scheduler (AWS CDK v2)\n\n[![GitHub](https://img.shields.io/github/license/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler?style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/blob/main/LICENSE)\n[![npm](https://img.shields.io/npm/v/ec2-instance-running-scheduler?style=flat-square)](https://www.npmjs.com/package/ec2-instance-running-scheduler)\n[![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/release.yml?branch=main&label=release&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/actions/workflows/release.yml)\n[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler?sort=semver&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/releases)\n\n[![View on Construct Hub](https://constructs.dev/badge?package=ec2-instance-running-scheduler)](https://constructs.dev/packages/ec2-instance-running-scheduler)\n\nAWS CDK construct that starts and stops EC2 instances on a cron schedule using **EventBridge Scheduler** and a **Durable Execution Lambda**. The handler discovers instances with the **Resource Groups Tagging API**, runs start/stop and **polls until the instance reaches the target state** (durable `step` / `wait`), processes **multiple instances in parallel** (bounded concurrency), and posts **Slack** summary and per-instance thread messages using a secret from **Secrets Manager**. The Lambda emits **structured application logs** (invocation, EC2 transitions, Slack steps, completion) alongside JSON platform logs.\n\n## Features\n\n- **Tag-based targeting** – Select EC2 instances by tag key and values (e.g. `Schedule` / `YES`) via `tag:GetResources`.\n- **EventBridge Scheduler** – Separate cron rules for start and stop, with per-rule timezone (`aws-cdk-lib` `TimeZone`).\n- **Durable Lambda** – One Lambda with AWS Lambda Durable Execution (`step`, `wait`, `map`, child contexts per instance) for long-running workflows without Step Functions.\n- **Stable-state polling** – After start/stop, the function waits and re-describes instances until `running` (start mode) or `stopped` (stop mode), or until a terminal error.\n- **Slack notifications** – Required for a successful run: parent message plus threaded updates per instance; credentials come from Secrets Manager (`token` and `channel` JSON). The secret name is passed as **`SLACK_SECRET_NAME`** on the function (from `secrets.slackSecretName`) and validated at runtime via **safe-env-getter**.\n- **Structured logging** – The handler uses the durable execution **`ctx.logger`** for traceable JSON application logs (e.g. invocation, describe/start/stop/wait loops, target count, Slack posts, errors before instance state failures).\n- **Scheduling toggle** – Enable or disable both schedules without removing the stack (`enableScheduling`).\n- **Configurable schedules** – Optional cron overrides for start and stop (`minute`, `hour`, `week`, `timezone`); sensible defaults if omitted.\n- **IAM and observability** – EC2 and tagging API permissions, Slack secret read grant, **Parameters and Secrets Lambda Extension** (configured on the function for secret access patterns), JSON logging with configurable system/application levels, and a dedicated log group (construct defaults).\n\n## Installation\n\n**npm**\n\n```bash\nnpm install ec2-instance-running-scheduler\n```\n\n**yarn**\n\n```bash\nyarn add ec2-instance-running-scheduler\n```\n\n**pnpm**\n\n```bash\npnpm add ec2-instance-running-scheduler\n```\n\n## Usage\n\nUse the **construct** `EC2InstanceRunningScheduler` when embedding the scheduler in an existing stack or other CDK scope.\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TimeZone } from 'aws-cdk-lib';\nimport { EC2InstanceRunningScheduler } from 'ec2-instance-running-scheduler';\n\nconst app = new cdk.App();\nconst stack = new cdk.Stack(app, 'MyStack');\n\nnew EC2InstanceRunningScheduler(stack, 'EC2InstanceRunningScheduler', {\n  targetResource: {\n    tagKey: 'Schedule',\n    tagValues: ['YES'],\n  },\n  secrets: {\n    slackSecretName: 'my-slack-secret',\n  },\n  startSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '55',\n    hour: '8',\n    week: 'MON-FRI',\n  },\n  stopSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '5',\n    hour: '19',\n    week: 'MON-FRI',\n  },\n  enableScheduling: true,\n});\n```\n\nUse the **stack** `EC2InstanceRunningScheduleStack` when deploying the scheduler as its own stack. It accepts the **same scheduler options** as the construct (plus standard `StackProps` such as `env`).\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TimeZone } from 'aws-cdk-lib';\nimport { EC2InstanceRunningScheduleStack } from 'ec2-instance-running-scheduler';\n\nconst app = new cdk.App();\n\nnew EC2InstanceRunningScheduleStack(app, 'EC2InstanceRunningScheduleStack', {\n  targetResource: {\n    tagKey: 'Schedule',\n    tagValues: ['YES'],\n  },\n  secrets: {\n    slackSecretName: 'my-slack-secret',\n  },\n  startSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '55',\n    hour: '8',\n    week: 'MON-FRI',\n  },\n  stopSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '5',\n    hour: '19',\n    week: 'MON-FRI',\n  },\n  enableScheduling: true,\n});\n```\n\nEventBridge Scheduler invokes the Lambda with `Params.TagKey`, `Params.TagValues`, and `Params.Mode` (`Start` or `Stop`); the construct wires this for you. The function environment includes **`SLACK_SECRET_NAME`** set to `secrets.slackSecretName`.\n\n## Options\n\nThese options apply to **`EC2InstanceRunningScheduler`** and to **`EC2InstanceRunningScheduleStack`** (stack props include them alongside `StackProps`).\n\n| Option | Type | Required | Description |\n|--------|------|----------|-------------|\n| `targetResource` | `TargetResource` | Yes | Tag key and values used to select EC2 instances. |\n| `secrets` | `Secrets` | Yes | Identifies the Secrets Manager secret used for Slack (`slackSecretName`). |\n| `startSchedule` | `Schedule` | No | Cron for starting instances (default: `50 7 ? * MON-FRI *` in `Etc/UTC`). |\n| `stopSchedule` | `Schedule` | No | Cron for stopping instances (default: `5 19 ? * MON-FRI *` in `Etc/UTC`). |\n| `enableScheduling` | `boolean` | No | Whether both scheduler rules are enabled (default: `true`). |\n\n### TargetResource\n\n- `tagKey` – Tag key used to select instances (e.g. `Schedule`).\n- `tagValues` – Tag values that must match (e.g. `['YES']`).\n\n### Schedule\n\n- `timezone` – `TimeZone` from `aws-cdk-lib` (e.g. `TimeZone.ASIA_TOKYO`, `TimeZone.ETC_UTC`).\n- `minute` – Cron minute (`0`–`59`).\n- `hour` – Cron hour (`0`–`23`).\n- `week` – Cron day-of-week field (e.g. `MON-FRI`).\n\n### Secrets\n\n- `slackSecretName` – Name of the AWS Secrets Manager secret. The Lambda expects JSON with **`token`** (Slack bot token) and **`channel`** (channel ID or name for `chat.postMessage`). The construct sets **`SLACK_SECRET_NAME`** on the function to this value; the handler reads and validates it at runtime (via **safe-env-getter**).\n\n## Requirements\n\n- **Node.js** ≥ 20.0.0 (for developing or synthesizing CDK apps that depend on this package).\n- **aws-cdk-lib** ^2.232.0 and **constructs** ^10.5.1 (peer dependencies).\n- **AWS** – EventBridge Scheduler; Lambda with **Durable Execution** (requires **Node.js 22+** in the deployment region—runtime is the latest Node.js available in the region per the construct), a **live alias**, **Parameters and Secrets Lambda Extension**; EC2 (describe/start/stop); Resource Groups Tagging API; Secrets Manager. The deployed function uses **arm64**, Durable Execution–compatible IAM and settings, and a bundled handler that loads secrets via **aws-lambda-secret-fetcher**.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n"
+    "markdown": "# EC2 Instance Running Scheduler (AWS CDK v2)\n\n[![GitHub](https://img.shields.io/github/license/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler?style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/blob/main/LICENSE)\n[![npm](https://img.shields.io/npm/v/ec2-instance-running-scheduler?style=flat-square)](https://www.npmjs.com/package/ec2-instance-running-scheduler)\n[![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/release.yml?branch=main&label=release&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/actions/workflows/release.yml)\n[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler?sort=semver&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/releases)\n[![View on Construct Hub](https://constructs.dev/badge?package=ec2-instance-running-scheduler)](https://constructs.dev/packages/ec2-instance-running-scheduler)\n\nAWS CDK construct library that starts and stops EC2 instances on a cron schedule using **EventBridge Scheduler** and a **Durable Execution Lambda**. The handler discovers instances with the **Resource Groups Tagging API**, issues start/stop, **polls until each instance reaches a stable target state** (durable `step` / `wait`), processes **multiple instances in parallel** (bounded concurrency), and posts **Slack** summary and per-instance thread messages using a secret from **Secrets Manager**. The Lambda emits **structured application logs** alongside JSON platform logs.\n\n## Features\n\n- **Tag-based targeting** – Select EC2 instances by tag key and values (e.g. `Schedule` / `YES`) via `tag:GetResources`.\n- **EventBridge Scheduler** – Separate cron rules for start and stop, with per-rule timezone (`aws-cdk-lib` `TimeZone`).\n- **Durable Lambda** – One Lambda with AWS Lambda Durable Execution (`step`, `wait`, `map`, child contexts per instance) for long-running workflows without Step Functions.\n- **Stable-state polling** – After start/stop, the function waits (20 seconds between attempts) and re-describes instances until `running` (start mode) or `stopped` (stop mode).\n- **Configurable polling limits** – Per-instance **max loop count** and **max elapsed time** via `resourcePolling` (default: 90 loops / 1800 seconds). Failures use explicit `ResourcePollingFailed:*` messages instead of running until the Durable execution timeout (construct default: 2 hours).\n- **Validated environment variables** – The bundled handler parses required and polling env vars at invocation using strict decimal integer rules; polling limits must be **positive integers** (`> 0`).\n- **Slack notifications** – Parent message plus threaded updates per instance; credentials from Secrets Manager JSON (`token`, `channel`). The construct sets **`SLACK_SECRET_NAME`** on the function.\n- **Structured logging** – Durable execution **`ctx.logger`** for traceable JSON application logs (invocation, describe/start/stop/wait loops, polling limit errors, Slack steps, completion).\n- **Scheduling toggle** – Enable or disable both schedules without removing the stack (`enableScheduling`).\n- **Configurable schedules** – Optional cron overrides for start and stop (`minute`, `hour`, `week`, `timezone`); sensible defaults if omitted.\n- **IAM and observability** – EC2 and tagging API permissions, Slack secret read grant, **Parameters and Secrets Lambda Extension**, JSON logging, and a dedicated log group (construct defaults).\n\n## Installation\n\n**npm**\n\n```bash\nnpm install ec2-instance-running-scheduler\n```\n\n**yarn**\n\n```bash\nyarn add ec2-instance-running-scheduler\n```\n\n**pnpm**\n\n```bash\npnpm add ec2-instance-running-scheduler\n```\n\n## Usage\n\nUse the **construct** `EC2InstanceRunningScheduler` when embedding the scheduler in an existing stack or other CDK scope.\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TimeZone } from 'aws-cdk-lib';\nimport { EC2InstanceRunningScheduler } from 'ec2-instance-running-scheduler';\n\nconst app = new cdk.App();\nconst stack = new cdk.Stack(app, 'MyStack');\n\nnew EC2InstanceRunningScheduler(stack, 'EC2InstanceRunningScheduler', {\n  targetResource: {\n    tagKey: 'Schedule',\n    tagValues: ['YES'],\n  },\n  secrets: {\n    slackSecretName: 'my-slack-secret',\n  },\n  startSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '55',\n    hour: '8',\n    week: 'MON-FRI',\n  },\n  stopSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '5',\n    hour: '19',\n    week: 'MON-FRI',\n  },\n  enableScheduling: true,\n  resourcePolling: {\n    maxLoopCount: 120,\n    maxElapsedSeconds: 3600,\n  },\n});\n```\n\nUse the **stack** `EC2InstanceRunningScheduleStack` when deploying the scheduler as its own stack. It accepts the same **targeting, schedules, secrets, and enable flag** as the construct (plus standard `StackProps` such as `env`). For **`resourcePolling`**, use the construct directly or extend the stack in your app.\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TimeZone } from 'aws-cdk-lib';\nimport { EC2InstanceRunningScheduleStack } from 'ec2-instance-running-scheduler';\n\nconst app = new cdk.App();\n\nnew EC2InstanceRunningScheduleStack(app, 'EC2InstanceRunningScheduleStack', {\n  targetResource: {\n    tagKey: 'Schedule',\n    tagValues: ['YES'],\n  },\n  secrets: {\n    slackSecretName: 'my-slack-secret',\n  },\n  startSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '55',\n    hour: '8',\n    week: 'MON-FRI',\n  },\n  stopSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '5',\n    hour: '19',\n    week: 'MON-FRI',\n  },\n  enableScheduling: true,\n});\n```\n\nEventBridge Scheduler invokes the Lambda with `Params.TagKey`, `Params.TagValues`, and `Params.Mode` (`Start` or `Stop`); the construct wires this for you. The function environment includes:\n\n| Variable | Source | Purpose |\n|----------|--------|---------|\n| `SLACK_SECRET_NAME` | `secrets.slackSecretName` | Secrets Manager secret for Slack (required) |\n| `PROCESS_RESOURCE_MAX_LOOP_COUNT` | `resourcePolling.maxLoopCount` (default `90`) | Max describe/poll iterations per instance |\n| `PROCESS_RESOURCE_MAX_ELAPSED_SECONDS` | `resourcePolling.maxElapsedSeconds` (default `1800`) | Max wall-clock seconds polling one instance |\n\nWhen you set polling limits via `resourcePolling`, the construct writes them as decimal integer strings. If you override these variables manually, each value must be a **strict decimal integer** (e.g. `\"120\"` is valid; `\"0x10\"`, `\"3.14\"`, or `\"10abc\"` are rejected) and **greater than zero**. Invalid or missing `SLACK_SECRET_NAME` causes the handler to fail at the start of an invocation.\n\n## Options\n\n### EC2InstanceRunningScheduler\n\n| Option | Type | Required | Description |\n|--------|------|----------|-------------|\n| `targetResource` | `TargetResource` | Yes | Tag key and values used to select EC2 instances. |\n| `secrets` | `Secrets` | Yes | Secrets Manager secret for Slack (`slackSecretName`). |\n| `startSchedule` | `Schedule` | No | Cron for starting instances (default: `50 7 ? * MON-FRI *` in `Etc/UTC`). |\n| `stopSchedule` | `Schedule` | No | Cron for stopping instances (default: `5 19 ? * MON-FRI *` in `Etc/UTC`). |\n| `enableScheduling` | `boolean` | No | Whether both scheduler rules are enabled (default: `true`). |\n| `resourcePolling` | `ResourcePollingLimits` | No | Per-instance polling caps (see below). |\n\n### EC2InstanceRunningScheduleStack\n\nIncludes `targetResource`, `secrets`, `startSchedule`, `stopSchedule`, `enableScheduling`, and standard `StackProps`. Does **not** expose `resourcePolling`; use `EC2InstanceRunningScheduler` when you need custom polling limits.\n\n### TargetResource\n\n- `tagKey` – Tag key used to select instances (e.g. `Schedule`).\n- `tagValues` – Tag values that must match (e.g. `['YES']`).\n\n### Schedule\n\n- `timezone` – `TimeZone` from `aws-cdk-lib` (e.g. `TimeZone.ASIA_TOKYO`, `TimeZone.ETC_UTC`).\n- `minute` – Cron minute (`0`–`59`).\n- `hour` – Cron hour (`0`–`23`).\n- `week` – Cron day-of-week field (e.g. `MON-FRI`).\n\n### Secrets\n\n- `slackSecretName` – Name of the AWS Secrets Manager secret. The Lambda expects JSON with **`token`** (Slack bot token) and **`channel`** (channel ID or name for `chat.postMessage`).\n\n### ResourcePollingLimits\n\nWritten to `PROCESS_RESOURCE_MAX_LOOP_COUNT` and `PROCESS_RESOURCE_MAX_ELAPSED_SECONDS` on the running scheduler Lambda.\n\n- `maxLoopCount` – Maximum describe/poll loop iterations per instance (default: **90**). Must be a positive integer when set.\n- `maxElapsedSeconds` – Maximum wall-clock seconds spent polling one instance (default: **1800**, 30 minutes). Must be a positive integer when set.\n\nWhen a limit is exceeded during polling, the handler throws an error with prefix `ResourcePollingFailed:` (`MaxLoopCountExceeded`, `MaxElapsedTimeExceeded`, or `UnexpectedInstanceState` for unknown EC2 states).\n\n## Requirements\n\n- **Node.js** ≥ 20.0.0 (for developing or synthesizing CDK apps that depend on this package).\n- **aws-cdk-lib** ^2.232.0 and **constructs** ^10.5.1 (peer dependencies).\n- **AWS** – EventBridge Scheduler; Lambda with **Durable Execution** (Node.js **24.x** runtime in the construct; Durable Execution requires a supported Node.js runtime in your region), a **live alias**, **Parameters and Secrets Lambda Extension**; EC2 (`DescribeInstances`, `StartInstances`, `StopInstances`); Resource Groups Tagging API (`tag:GetResources`); Secrets Manager. The deployed function uses **arm64**, Durable Execution IAM policies, a 2-hour Durable execution timeout (construct default), and a bundled handler that loads secrets via **aws-lambda-secret-fetcher**.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n"
   },
   "repository": {
     "type": "git",
@@ -8473,22 +8479,22 @@
       "base": "aws-cdk-lib.Stack",
       "docs": {
         "stability": "stable",
-        "summary": "CDK Stack that deploys the EC2 instance running scheduler (EventBridge Scheduler + Durable Lambda)."
+        "summary": "CDK stack that deploys the EC2 instance running scheduler (EventBridge Scheduler + Durable Lambda)."
       },
       "fqn": "ec2-instance-running-scheduler.EC2InstanceRunningScheduleStack",
       "initializer": {
         "docs": {
           "stability": "stable",
-          "summary": "Creates the stack and the EC2InstanceRunningScheduler construct."
+          "summary": "Creates the stack and wires {@link EC2InstanceRunningScheduler}."
         },
         "locationInModule": {
           "filename": "src/stacks/ec2-instance-running-schedule-stack.ts",
-          "line": 32
+          "line": 34
         },
         "parameters": [
           {
             "docs": {
-              "summary": "- Parent construct."
+              "summary": "- Parent construct or app."
             },
             "name": "scope",
             "type": {
@@ -8506,7 +8512,7 @@
           },
           {
             "docs": {
-              "summary": "- Stack props (target resource, schedules, secrets)."
+              "summary": "- Target resource, schedules, secrets, and standard stack props."
             },
             "name": "props",
             "type": {
@@ -8518,7 +8524,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/stacks/ec2-instance-running-schedule-stack.ts",
-        "line": 24
+        "line": 26
       },
       "name": "EC2InstanceRunningScheduleStack",
       "symbolId": "src/stacks/ec2-instance-running-schedule-stack:EC2InstanceRunningScheduleStack"
@@ -8527,6 +8533,7 @@
       "assembly": "ec2-instance-running-scheduler",
       "datatype": true,
       "docs": {
+        "see": "{@link EC2InstanceRunningSchedulerProps } for construct-level options not exposed here (e.g. `resourcePolling`).",
         "stability": "stable",
         "summary": "Props for the EC2 instance running schedule CDK stack."
       },
@@ -8537,7 +8544,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/stacks/ec2-instance-running-schedule-stack.ts",
-        "line": 8
+        "line": 10
       },
       "name": "EC2InstanceRunningScheduleStackProps",
       "properties": [
@@ -8550,7 +8557,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/stacks/ec2-instance-running-schedule-stack.ts",
-            "line": 14
+            "line": 16
           },
           "name": "secrets",
           "type": {
@@ -8566,7 +8573,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/stacks/ec2-instance-running-schedule-stack.ts",
-            "line": 10
+            "line": 12
           },
           "name": "targetResource",
           "type": {
@@ -8583,7 +8590,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/stacks/ec2-instance-running-schedule-stack.ts",
-            "line": 12
+            "line": 14
           },
           "name": "enableScheduling",
           "optional": true,
@@ -8600,7 +8607,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/stacks/ec2-instance-running-schedule-stack.ts",
-            "line": 18
+            "line": 20
           },
           "name": "startSchedule",
           "optional": true,
@@ -8617,7 +8624,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/stacks/ec2-instance-running-schedule-stack.ts",
-            "line": 16
+            "line": 18
           },
           "name": "stopSchedule",
           "optional": true,
@@ -8632,7 +8639,7 @@
       "assembly": "ec2-instance-running-scheduler",
       "base": "constructs.Construct",
       "docs": {
-        "remarks": "Each schedule invokes the function with `Params` (`TagKey`, `TagValues`, `Mode`). The function uses\nthe Resource Groups Tagging API and EC2 APIs; Slack notifications use the secret named in {@link Secrets.slackSecretName}.",
+        "remarks": "Each schedule invokes the function with `Params` (`TagKey`, `TagValues`, `Mode`). The function uses\nthe Resource Groups Tagging API and EC2 APIs; Slack notifications use the secret named in {@link Secrets.slackSecretName}.\n\nPer-instance polling timeouts are configured via {@link EC2InstanceRunningSchedulerProps.resourcePolling}\nand enforced in the handler before the Durable execution timeout.",
         "stability": "stable",
         "summary": "Provisions EventBridge Scheduler rules and a Durable Execution Lambda that start/stop tagged EC2 instances."
       },
@@ -8644,7 +8651,7 @@
         },
         "locationInModule": {
           "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-          "line": 73
+          "line": 109
         },
         "parameters": [
           {
@@ -8667,7 +8674,7 @@
           },
           {
             "docs": {
-              "summary": "- Target tags, optional cron overrides, Slack secret name, and schedule enable flag."
+              "summary": "- Target tags, schedules, Slack secret, schedule enable flag, and optional {@link ResourcePollingLimits}."
             },
             "name": "props",
             "type": {
@@ -8679,7 +8686,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-        "line": 65
+        "line": 101
       },
       "name": "EC2InstanceRunningScheduler",
       "symbolId": "src/constructs/ec2-instance-running-scheduler:EC2InstanceRunningScheduler"
@@ -8695,7 +8702,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-        "line": 46
+        "line": 73
       },
       "name": "EC2InstanceRunningSchedulerProps",
       "properties": [
@@ -8708,7 +8715,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 52
+            "line": 79
           },
           "name": "secrets",
           "type": {
@@ -8724,7 +8731,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 48
+            "line": 75
           },
           "name": "targetResource",
           "type": {
@@ -8741,7 +8748,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 50
+            "line": 77
           },
           "name": "enableScheduling",
           "optional": true,
@@ -8749,6 +8756,24 @@
             "primitive": "boolean"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "{@link DEFAULT_RESOURCE_POLLING_LIMITS }",
+            "stability": "stable",
+            "summary": "Per-instance polling limits for the running scheduler Lambda."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/ec2-instance-running-scheduler.ts",
+            "line": 89
+          },
+          "name": "resourcePolling",
+          "optional": true,
+          "type": {
+            "fqn": "ec2-instance-running-scheduler.ResourcePollingLimits"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -8758,7 +8783,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 56
+            "line": 83
           },
           "name": "startSchedule",
           "optional": true,
@@ -8775,7 +8800,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 54
+            "line": 81
           },
           "name": "stopSchedule",
           "optional": true,
@@ -8786,6 +8811,61 @@
       ],
       "symbolId": "src/constructs/ec2-instance-running-scheduler:EC2InstanceRunningSchedulerProps"
     },
+    "ec2-instance-running-scheduler.ResourcePollingLimits": {
+      "assembly": "ec2-instance-running-scheduler",
+      "datatype": true,
+      "docs": {
+        "remarks": "Values are written to {@link PROCESS_RESOURCE_MAX_LOOP_COUNT_ENV} and\n{@link PROCESS_RESOURCE_MAX_ELAPSED_SECONDS_ENV} on the running scheduler function.\nPrevents abnormal or stuck transitions from running until the Durable execution timeout.",
+        "stability": "stable",
+        "summary": "CDK-side limits for per-instance stable-state polling in the Durable Lambda handler."
+      },
+      "fqn": "ec2-instance-running-scheduler.ResourcePollingLimits",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/constructs/ec2-instance-running-scheduler.ts",
+        "line": 55
+      },
+      "name": "ResourcePollingLimits",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "default": "{@link DEFAULT_RESOURCE_POLLING_LIMITS.maxElapsedSeconds } (1800, 30 minutes)",
+            "stability": "stable",
+            "summary": "Maximum wall-clock seconds spent polling a single instance."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/ec2-instance-running-scheduler.ts",
+            "line": 67
+          },
+          "name": "maxElapsedSeconds",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "{@link DEFAULT_RESOURCE_POLLING_LIMITS.maxLoopCount } (90)",
+            "stability": "stable",
+            "summary": "Maximum describe/poll loop iterations per instance."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/ec2-instance-running-scheduler.ts",
+            "line": 61
+          },
+          "name": "maxLoopCount",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        }
+      ],
+      "symbolId": "src/constructs/ec2-instance-running-scheduler:ResourcePollingLimits"
+    },
     "ec2-instance-running-scheduler.Schedule": {
       "assembly": "ec2-instance-running-scheduler",
       "datatype": true,
@@ -8797,7 +8877,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-        "line": 14
+        "line": 19
       },
       "name": "Schedule",
       "properties": [
@@ -8810,7 +8890,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 16
+            "line": 21
           },
           "name": "timezone",
           "type": {
@@ -8826,7 +8906,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 20
+            "line": 25
           },
           "name": "hour",
           "optional": true,
@@ -8843,7 +8923,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 18
+            "line": 23
           },
           "name": "minute",
           "optional": true,
@@ -8860,7 +8940,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 22
+            "line": 27
           },
           "name": "week",
           "optional": true,
@@ -8882,7 +8962,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-        "line": 38
+        "line": 43
       },
       "name": "Secrets",
       "properties": [
@@ -8895,7 +8975,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 40
+            "line": 45
           },
           "name": "slackSecretName",
           "type": {
@@ -8916,7 +8996,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-        "line": 28
+        "line": 33
       },
       "name": "TargetResource",
       "properties": [
@@ -8929,7 +9009,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 30
+            "line": 35
           },
           "name": "tagKey",
           "type": {
@@ -8945,7 +9025,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 32
+            "line": 37
           },
           "name": "tagValues",
           "type": {
@@ -8961,6 +9041,6 @@
       "symbolId": "src/constructs/ec2-instance-running-scheduler:TargetResource"
     }
   },
-  "version": "0.1.9",
-  "fingerprint": "NhbEVB4Eupkewuj9QQwAkG4aAo23KlDXBbUhUbHDvFg="
+  "version": "0.2.1",
+  "fingerprint": "9K/8AR/LR8ZaDeXdKmKC9w88DTanW5BE+7ejCcdUEj8="
 }

package/API.md

@@ -9,6 +9,9 @@ Provisions EventBridge Scheduler rules and a Durable Execution Lambda that start
 Each schedule invokes the function with `Params` (`TagKey`, `TagValues`, `Mode`). The function uses
 the Resource Groups Tagging API and EC2 APIs; Slack notifications use the secret named in {@link Secrets.slackSecretName}.
 
+Per-instance polling timeouts are configured via {@link EC2InstanceRunningSchedulerProps.resourcePolling}
+and enforced in the handler before the Durable execution timeout.
+
 #### Initializers <a name="Initializers" id="ec2-instance-running-scheduler.EC2InstanceRunningScheduler.Initializer"></a>
 
 ```typescript
@@ -21,7 +24,7 @@ new EC2InstanceRunningScheduler(scope: Construct, id: string, props: EC2Instance
 | --- | --- | --- |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduler.Initializer.parameter.scope">scope</a></code> | <code>constructs.Construct</code> | - Parent construct. |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduler.Initializer.parameter.id">id</a></code> | <code>string</code> | - Construct id. |
-| <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduler.Initializer.parameter.props">props</a></code> | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps">EC2InstanceRunningSchedulerProps</a></code> | - Target tags, optional cron overrides, Slack secret name, and schedule enable flag. |
+| <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduler.Initializer.parameter.props">props</a></code> | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps">EC2InstanceRunningSchedulerProps</a></code> | - Target tags, schedules, Slack secret, schedule enable flag, and optional {@link ResourcePollingLimits}. |
 
 ---
 
@@ -45,7 +48,7 @@ Construct id.
 
 - *Type:* <a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps">EC2InstanceRunningSchedulerProps</a>
 
-Target tags, optional cron overrides, Slack secret name, and schedule enable flag.
+Target tags, schedules, Slack secret, schedule enable flag, and optional {@link ResourcePollingLimits}.
 
 ---
 
@@ -150,7 +153,7 @@ The tree node.
 
 ### EC2InstanceRunningScheduleStack <a name="EC2InstanceRunningScheduleStack" id="ec2-instance-running-scheduler.EC2InstanceRunningScheduleStack"></a>
 
-CDK Stack that deploys the EC2 instance running scheduler (EventBridge Scheduler + Durable Lambda).
+CDK stack that deploys the EC2 instance running scheduler (EventBridge Scheduler + Durable Lambda).
 
 #### Initializers <a name="Initializers" id="ec2-instance-running-scheduler.EC2InstanceRunningScheduleStack.Initializer"></a>
 
@@ -162,9 +165,9 @@ new EC2InstanceRunningScheduleStack(scope: Construct, id: string, props: EC2Inst
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
-| <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduleStack.Initializer.parameter.scope">scope</a></code> | <code>constructs.Construct</code> | - Parent construct. |
+| <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduleStack.Initializer.parameter.scope">scope</a></code> | <code>constructs.Construct</code> | - Parent construct or app. |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduleStack.Initializer.parameter.id">id</a></code> | <code>string</code> | - Stack id. |
-| <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduleStack.Initializer.parameter.props">props</a></code> | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduleStackProps">EC2InstanceRunningScheduleStackProps</a></code> | - Stack props (target resource, schedules, secrets). |
+| <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduleStack.Initializer.parameter.props">props</a></code> | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduleStackProps">EC2InstanceRunningScheduleStackProps</a></code> | - Target resource, schedules, secrets, and standard stack props. |
 
 ---
 
@@ -172,7 +175,7 @@ new EC2InstanceRunningScheduleStack(scope: Construct, id: string, props: EC2Inst
 
 - *Type:* constructs.Construct
 
-Parent construct.
+Parent construct or app.
 
 ---
 
@@ -188,7 +191,7 @@ Stack id.
 
 - *Type:* <a href="#ec2-instance-running-scheduler.EC2InstanceRunningScheduleStackProps">EC2InstanceRunningScheduleStackProps</a>
 
-Stack props (target resource, schedules, secrets).
+Target resource, schedules, secrets, and standard stack props.
 
 ---
 
@@ -1126,6 +1129,7 @@ const eC2InstanceRunningSchedulerProps: EC2InstanceRunningSchedulerProps = { ...
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.secrets">secrets</a></code> | <code><a href="#ec2-instance-running-scheduler.Secrets">Secrets</a></code> | Secrets (e.g. Slack) used for notifications. |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.targetResource">targetResource</a></code> | <code><a href="#ec2-instance-running-scheduler.TargetResource">TargetResource</a></code> | Tag-based targeting for EC2 instances to start/stop. |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.enableScheduling">enableScheduling</a></code> | <code>boolean</code> | Whether EventBridge Scheduler rules are enabled. |
+| <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.resourcePolling">resourcePolling</a></code> | <code><a href="#ec2-instance-running-scheduler.ResourcePollingLimits">ResourcePollingLimits</a></code> | Per-instance polling limits for the running scheduler Lambda. |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.startSchedule">startSchedule</a></code> | <code><a href="#ec2-instance-running-scheduler.Schedule">Schedule</a></code> | Cron schedule for starting instances. |
 | <code><a href="#ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.stopSchedule">stopSchedule</a></code> | <code><a href="#ec2-instance-running-scheduler.Schedule">Schedule</a></code> | Cron schedule for stopping instances. |
 
@@ -1169,6 +1173,19 @@ Defaults to true if omitted.
 
 ---
 
+##### `resourcePolling`<sup>Optional</sup> <a name="resourcePolling" id="ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.resourcePolling"></a>
+
+```typescript
+public readonly resourcePolling: ResourcePollingLimits;
+```
+
+- *Type:* <a href="#ec2-instance-running-scheduler.ResourcePollingLimits">ResourcePollingLimits</a>
+- *Default:* {@link DEFAULT_RESOURCE_POLLING_LIMITS }
+
+Per-instance polling limits for the running scheduler Lambda.
+
+---
+
 ##### `startSchedule`<sup>Optional</sup> <a name="startSchedule" id="ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps.property.startSchedule"></a>
 
 ```typescript
@@ -1197,6 +1214,8 @@ Cron schedule for stopping instances.
 
 Props for the EC2 instance running schedule CDK stack.
 
+> [{@link EC2InstanceRunningSchedulerProps } for construct-level options not exposed here (e.g. `resourcePolling`).]({@link EC2InstanceRunningSchedulerProps } for construct-level options not exposed here (e.g. `resourcePolling`).)
+
 #### Initializer <a name="Initializer" id="ec2-instance-running-scheduler.EC2InstanceRunningScheduleStackProps.Initializer"></a>
 
 ```typescript
@@ -1535,6 +1554,57 @@ Cron schedule for stopping instances.
 
 ---
 
+### ResourcePollingLimits <a name="ResourcePollingLimits" id="ec2-instance-running-scheduler.ResourcePollingLimits"></a>
+
+CDK-side limits for per-instance stable-state polling in the Durable Lambda handler.
+
+Values are written to {@link PROCESS_RESOURCE_MAX_LOOP_COUNT_ENV} and
+{@link PROCESS_RESOURCE_MAX_ELAPSED_SECONDS_ENV} on the running scheduler function.
+Prevents abnormal or stuck transitions from running until the Durable execution timeout.
+
+#### Initializer <a name="Initializer" id="ec2-instance-running-scheduler.ResourcePollingLimits.Initializer"></a>
+
+```typescript
+import { ResourcePollingLimits } from 'ec2-instance-running-scheduler'
+
+const resourcePollingLimits: ResourcePollingLimits = { ... }
+```
+
+#### Properties <a name="Properties" id="Properties"></a>
+
+| **Name** | **Type** | **Description** |
+| --- | --- | --- |
+| <code><a href="#ec2-instance-running-scheduler.ResourcePollingLimits.property.maxElapsedSeconds">maxElapsedSeconds</a></code> | <code>number</code> | Maximum wall-clock seconds spent polling a single instance. |
+| <code><a href="#ec2-instance-running-scheduler.ResourcePollingLimits.property.maxLoopCount">maxLoopCount</a></code> | <code>number</code> | Maximum describe/poll loop iterations per instance. |
+
+---
+
+##### `maxElapsedSeconds`<sup>Optional</sup> <a name="maxElapsedSeconds" id="ec2-instance-running-scheduler.ResourcePollingLimits.property.maxElapsedSeconds"></a>
+
+```typescript
+public readonly maxElapsedSeconds: number;
+```
+
+- *Type:* number
+- *Default:* {@link DEFAULT_RESOURCE_POLLING_LIMITS.maxElapsedSeconds } (1800, 30 minutes)
+
+Maximum wall-clock seconds spent polling a single instance.
+
+---
+
+##### `maxLoopCount`<sup>Optional</sup> <a name="maxLoopCount" id="ec2-instance-running-scheduler.ResourcePollingLimits.property.maxLoopCount"></a>
+
+```typescript
+public readonly maxLoopCount: number;
+```
+
+- *Type:* number
+- *Default:* {@link DEFAULT_RESOURCE_POLLING_LIMITS.maxLoopCount } (90)
+
+Maximum describe/poll loop iterations per instance.
+
+---
+
 ### Schedule <a name="Schedule" id="ec2-instance-running-scheduler.Schedule"></a>
 
 Cron-style schedule configuration for start/stop actions.