Skip to content

docs: execution modes + cooperative timeout/cancellation #186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merencia merged 2 commits into from
Jun 19, 2026
Merged

docs: execution modes + cooperative timeout/cancellation #186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fc4e216
docs: document execution modes and cooperative timeout/cancellation
merencia Jun 19, 2026
1a56dcf
docs: drop references to the not-yet-released @sidequest/nestjs package
merencia Jun 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/docs/.vitepress/config.mts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ export default defineConfig({
collapsed: false,
items: [
{ text: "Backends", link: "/backends" },
{ text: "Execution Modes", link: "/execution-modes" },
{ text: "Graceful Shutdown", link: "/graceful-shutdown" },
{ text: "Cleanup", link: "/cleanup" },
{ text: "Manual Job Resolution", link: "/manual-resolution" },
Expand Down
58 changes: 32 additions & 26 deletions packages/docs/getting-started/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,9 @@ await Sidequest.start({
minThreads: 4,
maxThreads: 8,
idleWorkerTimeout: 10000, // 10 seconds
fork: true, // run the engine in a child process
runner: "thread", // "thread" (worker pool) or "inline"
abortGracePeriodMs: 0, // grace before force-killing a timed-out/canceled thread job

// 4. Migration and startup
skipMigration: false,
Expand Down Expand Up @@ -179,32 +182,35 @@ await Sidequest.start({

### Configuration Options

| Option | Description | Default |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `backend.driver` | Backend driver package name (SQLite, Postgres, MySQL, MongoDB) | `@sidequest/sqlite-backend` |
| `backend.config` | Backend-specific connection string or [Knex configuration object](https://knexjs.org/guide/#configuration-options) | `./sidequest.sqlite` |
| `dashboard.enabled` | Whether to enable the dashboard web interface | `true` |
| `dashboard.port` | Port for the dashboard web interface | `8678` |
| `dashboard.auth` | Basic auth configuration with `user` and `password`. If omitted, no auth is required. | `undefined` |
| `queues` | Array of queue configurations with name, concurrency, priority, and state | `[]` |
| `maxConcurrentJobs` | Maximum number of jobs processed simultaneously across all queues | `10` |
| `minThreads` | Minimum number of worker threads to use | Number of CPU cores |
| `maxThreads` | Maximum number of worker threads to use | `minThreads * 2` |
| `idleWorkerTimeout` | Timeout (milliseconds) for idle workers before they are terminated | `10000` (10 seconds) |
| `skipMigration` | Whether to skip database migration on startup | `false` |
| `releaseStaleJobsIntervalMin` | Frequency (minutes) for releasing stale jobs. Set to `false` to disable | `60` |
| `releaseStaleJobsMaxStaleMs` | Maximum age (milliseconds) for a running job to be considered stale | `600000` (10 minutes) |
| `releaseStaleJobsMaxClaimedMs` | Maximum age (milliseconds) for a claimed job to be considered stale | `60000` (1 minute) |
| `cleanupFinishedJobsIntervalMin` | Frequency (minutes) for cleaning up finished jobs. Set to `false` to disable | `60` |
| `cleanupFinishedJobsOlderThan` | Age (milliseconds) after which finished jobs are deleted | `2592000000` (30 days) |
| `logger.level` | Minimum log level (`debug`, `info`, `warn`, `error`) | `info` |
| `logger.json` | Whether to output logs in JSON format | `false` |
| `gracefulShutdown` | Whether to enable graceful shutdown handling | `true` |
| `jobDefaults` | Default values for new jobs. Used while enqueueing | `undefined` |
| `queueDefaults` | Default values for auto-created queues | `undefined` |
| `manualJobResolution` | Whether to manually resolve job classes. See [Manual Job Resolution](/production/manual-resolution) | `false` |
| `jobsFilePath` | Optional path to the file where job classes are exported. Ignored if `manualJobResolution` is `false`. | `undefined` |
| `jobPollingInterval` | Interval (milliseconds) for polling new jobs to process. Increase this number to reduce DB load at the cost of job start latency. | `100` (100 milliseconds) |
| Option | Description | Default |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `backend.driver` | Backend driver package name (SQLite, Postgres, MySQL, MongoDB) | `@sidequest/sqlite-backend` |
| `backend.config` | Backend-specific connection string or [Knex configuration object](https://knexjs.org/guide/#configuration-options) | `./sidequest.sqlite` |
| `dashboard.enabled` | Whether to enable the dashboard web interface | `true` |
| `dashboard.port` | Port for the dashboard web interface | `8678` |
| `dashboard.auth` | Basic auth configuration with `user` and `password`. If omitted, no auth is required. | `undefined` |
| `queues` | Array of queue configurations with name, concurrency, priority, and state | `[]` |
| `maxConcurrentJobs` | Maximum number of jobs processed simultaneously across all queues | `10` |
| `fork` | Run the engine in a child process (crash isolation). Set `false` to run in-process. See [Execution Modes](/production/execution-modes#fork-process-isolation) | `true` |
| `runner` | How jobs run: `"thread"` (worker pool) or `"inline"` (current thread). See [Execution Modes](/production/execution-modes#runner-thread-pool-vs-inline) | `"thread"` |
| `abortGracePeriodMs` | Grace period (ms) before a timed-out/canceled job's worker **thread** is force-killed. `0` kills immediately. No effect with `runner: "inline"`. See [Execution Modes](/production/execution-modes#cooperative-timeout-and-cancellation) | `0` |
| `minThreads` | Minimum number of worker threads to use (`runner: "thread"` only) | Number of CPU cores |
| `maxThreads` | Maximum number of worker threads to use (`runner: "thread"` only) | `minThreads * 2` |
| `idleWorkerTimeout` | Timeout (milliseconds) for idle workers before they are terminated (`runner: "thread"` only) | `10000` (10 seconds) |
| `skipMigration` | Whether to skip database migration on startup | `false` |
| `releaseStaleJobsIntervalMin` | Frequency (minutes) for releasing stale jobs. Set to `false` to disable | `60` |
| `releaseStaleJobsMaxStaleMs` | Maximum age (milliseconds) for a running job to be considered stale | `600000` (10 minutes) |
| `releaseStaleJobsMaxClaimedMs` | Maximum age (milliseconds) for a claimed job to be considered stale | `60000` (1 minute) |
| `cleanupFinishedJobsIntervalMin` | Frequency (minutes) for cleaning up finished jobs. Set to `false` to disable | `60` |
| `cleanupFinishedJobsOlderThan` | Age (milliseconds) after which finished jobs are deleted | `2592000000` (30 days) |
| `logger.level` | Minimum log level (`debug`, `info`, `warn`, `error`) | `info` |
| `logger.json` | Whether to output logs in JSON format | `false` |
| `gracefulShutdown` | Whether to enable graceful shutdown handling | `true` |
| `jobDefaults` | Default values for new jobs. Used while enqueueing | `undefined` |
| `queueDefaults` | Default values for auto-created queues | `undefined` |
| `manualJobResolution` | Whether to manually resolve job classes. See [Manual Job Resolution](/production/manual-resolution) | `false` |
| `jobsFilePath` | Optional path to the file where job classes are exported. Ignored if `manualJobResolution` is `false`. | `undefined` |
| `jobPollingInterval` | Interval (milliseconds) for polling new jobs to process. Increase this number to reduce DB load at the cost of job start latency. | `100` (100 milliseconds) |

::: danger
If `auth` is not configured and `dashboard: true` is enabled in production, the dashboard will be publicly accessible. This is a security risk and **not recommended**.
Expand Down
6 changes: 5 additions & 1 deletion packages/docs/guide/jobs/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,11 @@ Jobs can be manually canceled at any point before completion:

- Waiting jobs are immediately marked as `canceled`
- Claimed jobs are marked as `canceled` before execution an are prevented from running
- Running jobs receive a cancellation signal and transition to `canceled`
- Running jobs receive a cancellation signal via `this.abortSignal` and transition to `canceled`

::: warning
Stopping a _running_ job depends on the [execution mode](/production/execution-modes#cooperative-timeout-and-cancellation). With the default thread pool the worker is terminated. In `runner: "inline"` mode the job cannot be force-stopped, so it must honor `this.abortSignal`; a running inline job that ignores it finishes with its own result instead of `canceled`. The same applies to job timeouts.
:::

## Best Practices

Expand Down
Loading