Carlos Florêncio
77 lines
3.7 KiB
Markdown
77 lines
3.7 KiB
Markdown
---
|
|
status: approved
|
|
created: 2026-08-12
|
|
owner: kandev
|
|
---
|
|
|
|
# Setup and Launch Timeout
|
|
|
|
## Why
|
|
|
|
Environment setup can install dependencies or build a large project. A valid
|
|
setup that runs for more than one minute must not fail because a shorter,
|
|
hidden session-launch deadline expires first.
|
|
|
|
## What
|
|
|
|
- Kandev allows setup and prepare scripts to run for 10 minutes by default.
|
|
- Operators can set `tasks.preparationTimeout` in startup YAML or use
|
|
`KANDEV_TASK_PREPARATION_TIMEOUT` as its environment override. The value uses
|
|
Go duration syntax, such as `90s`, `10m`, or `1h`.
|
|
- The environment value overrides YAML when both are present.
|
|
- The configured value must be greater than zero. An unset, invalid, zero, or
|
|
negative value uses the 10-minute default.
|
|
- Kandev reads the resolved startup value when the backend process starts. A
|
|
change requires a restart.
|
|
- The timeout applies to repository setup scripts and executor-profile prepare
|
|
scripts on Local, Worktree, Docker, Sprite, and SSH launches.
|
|
- Runtime launch phases use the setup timeout plus a fixed five-minute
|
|
allowance. Each launch-phase context starts when that phase begins.
|
|
- Preparation scripts use their own setup context. Runtime setup work such as
|
|
Sprite uploads does not reduce the preparation-script budget.
|
|
- Manager shutdown still cancels a shared launch, and one caller leaving does
|
|
not cancel work that another caller still needs.
|
|
- A setup-script failure keeps the runtime-specific behavior documented in
|
|
[Executors](../../public/executors.md). This change does not make a non-fatal
|
|
setup failure fatal.
|
|
|
|
Decision: [ADR-2026-08-12-setup-timeout-owns-launch-budget](../../decisions/2026-08-12-setup-timeout-owns-launch-budget.md).
|
|
|
|
## Failure modes
|
|
|
|
| Condition | Behavior |
|
|
|---|---|
|
|
| `tasks.preparationTimeout` and `KANDEV_TASK_PREPARATION_TIMEOUT` are absent | Kandev uses 10 minutes. |
|
|
| The value is invalid, zero, or negative | Kandev uses 10 minutes. |
|
|
| A setup script reaches the configured limit | Kandev stops the script and reports the existing runtime-specific setup failure. |
|
|
| A runtime launch phase does not finish within its derived launch limit | The launch fails with a deadline error and releases its activity lease. |
|
|
| The backend stops during launch | Manager cancellation stops the shared launch. |
|
|
|
|
## Scenarios
|
|
|
|
- **GIVEN** no timeout override and a repository setup script that takes 90
|
|
seconds, **WHEN** a user launches a session, **THEN** setup completes without
|
|
a one-minute session-launch deadline error.
|
|
- **GIVEN** `tasks.preparationTimeout: 15m` at process start and a prepare
|
|
script that takes more than 10 minutes but less than 15 minutes, **WHEN** a
|
|
user launches a session, **THEN** Kandev allows the script to complete.
|
|
- **GIVEN** an invalid, zero, or negative timeout value, **WHEN** Kandev starts,
|
|
**THEN** launches use the 10-minute setup limit and the 15-minute launch
|
|
limit.
|
|
- **GIVEN** a setup script that exceeds the configured limit, **WHEN** the limit
|
|
expires, **THEN** Kandev stops the script and preserves that runtime's current
|
|
fatal or non-fatal setup-failure behavior.
|
|
- **GIVEN** a runtime launch phase blocks after setup, **WHEN** its derived
|
|
launch limit expires, **THEN** the launch returns a deadline error and
|
|
releases the manager activity lease.
|
|
- **GIVEN** two callers wait for one shared launch, **WHEN** one caller cancels,
|
|
**THEN** the launch continues for the remaining caller until it completes,
|
|
the manager stops, or the derived launch limit expires.
|
|
|
|
## Out of scope
|
|
|
|
- Separate timeout settings for each executor or hook.
|
|
- A configurable cleanup-script timeout.
|
|
- Database, API, or Settings UI configuration.
|
|
- Changing whether a setup-script failure is fatal for a runtime.
|