# duroxide-node
Node.js/TypeScript SDK for the [Duroxide](https://github.com/microsoft/duroxide) durable execution runtime. Write reliable, long-running workflows in JavaScript using generator functions — backed by a Rust runtime that handles persistence, replay, and fault tolerance.
> See [CHANGELOG.md](https://github.com/microsoft/duroxide-node/blob/main/CHANGELOG.md) for release notes.
## Features
- **Durable orchestrations** — generator-based workflows that survive process restarts
- **Automatic replay** — the Rust runtime replays history on restart, your code picks up where it left off
- **Activities** — async functions for side effects (API calls, DB writes, etc.)
- **Timers** — durable delays that persist across restarts
- **Sub-orchestrations** — compose workflows from smaller workflows
- **External events** — pause workflows and wait for signals
- **Fan-out/fan-in** — run tasks in parallel with `ctx.all()` (supports all task types)
- **Race conditions** — wait for the first of multiple tasks with `ctx.race()` (supports all task types)
- **Cooperative cancellation** — activities detect when they're no longer needed via `ctx.isCancelled()`
- **Activity client access** — activities can start new orchestrations via `ctx.getClient()`
- **Custom status** — set orchestration progress visible to external clients via `ctx.setCustomStatus()`
- **Event queues** — persistent FIFO message passing with `ctx.dequeueEvent()` and `client.enqueueEvent()`
- **Continue-as-new** — restart orchestrations with fresh history for eternal workflows
- **Structured tracing** — orchestration and activity logs route through Rust's `tracing` crate
- **Runtime metrics** — `metricsSnapshot()` for orchestration/activity counters
- **Per-instance orchestration stats** — inspect history size, pending queue carry-forward, and KV usage with `client.getOrchestrationStats()`
- **SQLite & PostgreSQL** — pluggable storage backends
- **KV store** — durable per-instance key-value state with snapshots and pruning via `ctx.getKvAllValues()` / `client.getKvAllValues()`
## Quick Start
```bash
npm install duroxide
```
Prebuilt native packages are published for:
| OS | Architecture | Native package |
|----|--------------|----------------|
| macOS | arm64 | `duroxide-darwin-arm64` |
| macOS | x64 | `duroxide-darwin-x64` |
| Linux glibc | arm64 | `duroxide-linux-arm64-gnu` |
| Linux glibc | x64 | `duroxide-linux-x64-gnu` |
| Windows | x64 | `duroxide-windows-x64` |
```javascript
const { SqliteProvider, Client, Runtime } = require('duroxide');
async function main() {
// 1. Open a storage backend
const provider = await SqliteProvider.open('sqlite:myapp.db');
const client = new Client(provider);
const runtime = new Runtime(provider);
// 2. Register activities (async functions with side effects)
runtime.registerActivity('Greet', async (ctx, name) => {
ctx.traceInfo(`greeting ${name}`);
return `Hello, ${name}!`;
});
// 3. Register orchestrations (generator functions)
runtime.registerOrchestration('GreetWorkflow', function* (ctx, input) {
const greeting = yield ctx.scheduleActivity('Greet', input.name);
ctx.traceInfo(`got: ${greeting}`);
return greeting;
});
// 4. Start the runtime
await runtime.start();
// 5. Start an orchestration and wait for it
await client.startOrchestration('greet-1', 'GreetWorkflow', { name: 'World' });
const result = await client.waitForOrchestration('greet-1');
console.log(result.output); // "Hello, World!"
await runtime.shutdown();
}
main();
```
## Why Generators (not async/await)?
Duroxide uses `function*` generators instead of `async function` for orchestrations. This is a deliberate design choice — see [Architecture](https://github.com/microsoft/duroxide-node/blob/main/docs/architecture.md#yield-vs-await) for the full explanation. The short version: generators give Rust full control over when and how each step executes, which is essential for deterministic replay.
```javascript
// ✅ Orchestrations use yield
runtime.registerOrchestration('MyWorkflow', function* (ctx, input) {
const result = yield ctx.scheduleActivity('DoWork', input);
return result;
});
// ✅ Activities use async/await (normal async functions)
runtime.registerActivity('DoWork', async (ctx, input) => {
const data = await fetch(`https://api.example.com/${input}`);
return data;
});
```
## Orchestration Context API
All scheduling methods return descriptors that must be **yielded**:
| Method | Description |
|--------|-------------|
| `yield ctx.scheduleActivity(name, input)` | Run an activity |
| `yield ctx.scheduleActivityWithRetry(name, input, retryPolicy)` | Run with retry |
| `yield ctx.scheduleTimer(delayMs)` | Durable delay |
| `yield ctx.waitForEvent(eventName)` | Wait for external signal |
| `yield ctx.scheduleSubOrchestration(name, input)` | Run child workflow (await result) |
| `yield ctx.scheduleSubOrchestrationWithId(name, id, input)` | Child with explicit ID |
| `yield ctx.startOrchestration(name, id, input)` | Fire-and-forget orchestration |
| `yield ctx.all([task1, task2, ...])` | Parallel execution (like `Promise.all`) |
| `yield ctx.race(task1, task2)` | First-to-complete (like `Promise.race`) |
| `yield ctx.utcNow()` | Deterministic timestamp |
| `yield ctx.newGuid()` | Deterministic GUID |
| `yield ctx.dequeueEvent(queueName)` | Dequeue from persistent FIFO mailbox |
| `yield ctx.scheduleActivityWithRetryOnSession(name, input, retry, sessionId)` | Retry with session affinity |
| `yield ctx.continueAsNew(newInput)` | Restart with fresh history |
| `ctx.setValue(key, value)` | Set a durable KV entry (no yield) |
| `ctx.getValue(key)` | Read a KV entry for the current instance (no yield) |
| `ctx.clearValue(key)` | Remove a single KV entry (no yield) |
| `ctx.clearAllValues()` | Remove all KV entries (no yield) |
| `ctx.getKvAllValues()` | Snapshot all KV entries for the current instance |
| `ctx.getKvAllKeys()` | List all KV keys for the current instance, in key order |
| `ctx.getKvLength()` | Count KV entries for the current instance |
| `ctx.pruneKvValuesUpdatedBefore(cutoffMs)` | Remove persisted KV entries older than a cutoff |
| `yield ctx.getValueFromInstance(instanceId, key)` | Read another instance's KV entry |
Tracing methods are **fire-and-forget** (no yield needed):
| Method | Description |
|--------|-------------|
| `ctx.traceInfo(message)` | INFO log (suppressed during replay) |
| `ctx.traceWarn(message)` | WARN log |
| `ctx.traceError(message)` | ERROR log |
| `ctx.traceDebug(message)` | DEBUG log |
| `ctx.setCustomStatus(status)` | Set progress visible to clients |
| `ctx.resetCustomStatus()` | Clear custom status |
## Storage Backends
### SQLite
```javascript
const provider = await SqliteProvider.open('sqlite:path/to/db.db');
// or in-memory:
const provider = await SqliteProvider.inMemory();
```
### PostgreSQL
```javascript
const provider = await PostgresProvider.connectWithSchema(
'postgresql://user:pass@host:5432/db',
'my_schema'
);
```
#### Upgrading to 0.2.4
This release uses `duroxide-pg` 0.1.38. Connecting applies migration `0026`,
including a unique index on `instance_locks(lock_token)`. The index is not
built concurrently and blocks writes to that table while it builds.
Qualify the database upgrade and rollback before deployment. An older native
build can reject an unknown applied migration. Reinstalling an older npm package
does not undo a database migration. The JavaScript API is unchanged.
### PostgreSQL with Microsoft Entra ID (Azure)
For Azure Database for PostgreSQL Flexible Server, use Entra ID token authentication instead of a password:
```javascript
const provider = await PostgresProvider.connectWithEntra(
'myserver.postgres.database.azure.com',
5432,
'mydb',
'my-entra-user@contoso.onmicrosoft.com'
);
// With a custom schema and options:
const provider = await PostgresProvider.connectWithSchemaAndEntra(
'myserver.postgres.database.azure.com',
5432,
'mydb',
'my-entra-user@contoso.onmicrosoft.com',
'my_schema',
{ maxConnections: 20, acquireTimeoutMs: 45_000 }
);
```
Credentials are resolved automatically via the default chain:
- `WorkloadIdentityCredential` (AKS Workload Identity, if env vars present)
- `ManagedIdentityCredential` (Azure VMs, Container Apps, etc.)
- `DeveloperToolsCredential` (local development: `az login`)
All connections use TLS (`PgSslMode::VerifyFull`). See [`PostgresEntraOptions`](lib/duroxide.d.ts) for tunable options.
## Logging
Duroxide uses Rust's `tracing` crate. Control verbosity with `RUST_LOG`:
```bash
RUST_LOG=info node app.js # INFO and above
RUST_LOG=duroxide=debug node app.js # DEBUG for duroxide only
RUST_LOG=duroxide::activity=info node app.js # Activity traces only
```
## Management API
The `Client` class includes a management API for inspecting and managing orchestration instances:
```javascript
const client = new Client(provider);
// Event queues
await client.enqueueEvent(instanceId, 'queueName', JSON.stringify(data));
// Custom status polling
const change = await client.waitForStatusChange(instanceId, 0, 100, 30000);
// change: { customStatus, customStatusVersion } or null on timeout
// Instance management
const instances = await client.listAllInstances();
const info = await client.getInstanceInfo(instanceId);
const tree = await client.getInstanceTree(instanceId);
await client.deleteInstance(instanceId, false);
// Execution history with full event data
const executions = await client.listExecutions(instanceId);
const events = await client.readExecutionHistory(instanceId, executions[0]);
for (const event of events) {
console.log(event.kind, event.data);
// event.kind: "OrchestrationStarted" | "ActivityScheduled" | "ActivityCompleted" | ...
// event.data: JSON string with event-specific content (result, input, error, etc.)
}
// Metrics
const metrics = await client.getSystemMetrics();
const stats = await client.getOrchestrationStats(instanceId);
const depths = await client.getQueueDepths();
```
`getOrchestrationStats()` returns `null` for a missing instance, otherwise:
```javascript
{
historyEventCount: 2,
historySizeBytes: 184,
queuePendingCount: 0,
kvUserKeyCount: 1,
kvTotalValueBytes: 11
}
```
### KV Store
```javascript
// Read a KV entry from an orchestration instance
const value = await client.getValue(instanceId, 'myKey');
// Snapshot every KV entry for an orchestration instance
const allValues = await client.getKvAllValues(instanceId);
// Wait until a KV key is set (with timeout in ms)
const readyValue = await client.waitForValue(instanceId, 'myKey', 30000);
// Inside an orchestration, inspect or prune the local KV snapshot
const snapshot = ctx.getKvAllValues();
const keys = ctx.getKvAllKeys();
const size = ctx.getKvLength();
const removed = ctx.pruneKvValuesUpdatedBefore(cutoffMs);
```
`MAX_KV_KEYS` is now 150, and `MAX_KV_VALUE_BYTES` is now 65536.
## Documentation
- [Architecture](https://github.com/microsoft/duroxide-node/blob/main/docs/architecture.md) — how the Rust/JS interop works, yield vs await, limitations
- [User Guide](https://github.com/microsoft/duroxide-node/blob/main/docs/user-guide.md) — patterns, recipes, and best practices
## Tests
Requires PostgreSQL (see `.env.example`):
```bash
npm test # e2e tests (25 PG + 1 SQLite smoketest)
npm run test:races # Race/join composition tests (7 tests)
npm run test:admin # Admin API tests (14 tests)
npm run test:scenarios # Scenario tests (6 tests)
npm run test:all # Everything (52 tests)
```
## Releases
> **Releases are published by Microsoft's internal OSS infrastructure.** See
> [RELEASE_POLICY.md](RELEASE_POLICY.md) for details.
## Support
Use GitHub Issues for bug reports and feature requests. Do not report security vulnerabilities through public GitHub issues; follow the instructions in [SECURITY.md](SECURITY.md) instead.
## Code of Conduct
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or comments.
## Security
Microsoft takes the security of our software products and services seriously. Please do not report security vulnerabilities through public GitHub issues. See [SECURITY.md](SECURITY.md) for security reporting instructions.
## Privacy and Telemetry
duroxide-node does not send telemetry to Microsoft. Applications may configure their own logging or metrics exporters; those signals are controlled by the application owner.
## Trademarks
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos is subject to those third-party policies.
## License
MIT License - see [LICENSE](LICENSE) for details.