nestjs-boost 0.0.0-stage → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +68 -0
- package/LICENSE +21 -0
- package/NOTICE.md +6 -0
- package/README.md +168 -2
- package/bin/nestjs-boost.mjs +148 -0
- package/guidelines/core.md +64 -0
- package/lib/agents.mjs +137 -0
- package/lib/installer.mjs +450 -0
- package/lib/prompt.mjs +131 -0
- package/lib/setup.mjs +60 -0
- package/manifest.json +676 -0
- package/package.json +67 -6
- package/scripts/postinstall.mjs +49 -0
- package/skills/nestjs-ai/SKILL.md +145 -0
- package/skills/nestjs-ai/references/ai-reference.md +143 -0
- package/skills/nestjs-architecture/SKILL.md +83 -0
- package/skills/nestjs-architecture/references/dynamic-modules.md +92 -0
- package/skills/nestjs-architecture/references/scopes-lifecycle.md +98 -0
- package/skills/nestjs-architecture/references/troubleshooting.md +77 -0
- package/skills/nestjs-authentication/SKILL.md +115 -0
- package/skills/nestjs-authentication/references/flows.md +180 -0
- package/skills/nestjs-authorization/SKILL.md +104 -0
- package/skills/nestjs-caching/SKILL.md +109 -0
- package/skills/nestjs-cli-tooling/SKILL.md +94 -0
- package/skills/nestjs-cli-tooling/references/nest-cli-json.md +91 -0
- package/skills/nestjs-configuration/SKILL.md +109 -0
- package/skills/nestjs-cqrs/SKILL.md +124 -0
- package/skills/nestjs-database-drizzle/SKILL.md +117 -0
- package/skills/nestjs-database-mikro-orm/SKILL.md +109 -0
- package/skills/nestjs-database-mongoose/SKILL.md +124 -0
- package/skills/nestjs-database-prisma/SKILL.md +126 -0
- package/skills/nestjs-database-sequelize/SKILL.md +88 -0
- package/skills/nestjs-database-typeorm/SKILL.md +110 -0
- package/skills/nestjs-deployment/SKILL.md +133 -0
- package/skills/nestjs-deployment/references/serverless-and-systemd.md +133 -0
- package/skills/nestjs-events/SKILL.md +78 -0
- package/skills/nestjs-file-storage/SKILL.md +111 -0
- package/skills/nestjs-file-storage/references/storage-reference.md +82 -0
- package/skills/nestjs-graphql/SKILL.md +119 -0
- package/skills/nestjs-graphql/references/federation.md +110 -0
- package/skills/nestjs-graphql/references/schema-features.md +133 -0
- package/skills/nestjs-health-checks/SKILL.md +114 -0
- package/skills/nestjs-http-client/SKILL.md +118 -0
- package/skills/nestjs-http-client/references/http-client-reference.md +116 -0
- package/skills/nestjs-http-platform/SKILL.md +104 -0
- package/skills/nestjs-http-platform/references/adapters.md +88 -0
- package/skills/nestjs-http-web-features/SKILL.md +113 -0
- package/skills/nestjs-http-web-features/references/uploads-streaming.md +108 -0
- package/skills/nestjs-i18n/SKILL.md +113 -0
- package/skills/nestjs-idempotency/SKILL.md +112 -0
- package/skills/nestjs-locks/SKILL.md +108 -0
- package/skills/nestjs-logging/SKILL.md +123 -0
- package/skills/nestjs-mail/SKILL.md +125 -0
- package/skills/nestjs-mail/references/mail-reference.md +90 -0
- package/skills/nestjs-mcp-server/SKILL.md +152 -0
- package/skills/nestjs-mcp-server/references/mcp-reference.md +146 -0
- package/skills/nestjs-microservices/SKILL.md +108 -0
- package/skills/nestjs-microservices/references/transports.md +117 -0
- package/skills/nestjs-observability/SKILL.md +108 -0
- package/skills/nestjs-observability/references/apm-and-otel.md +106 -0
- package/skills/nestjs-openapi/SKILL.md +90 -0
- package/skills/nestjs-openapi/references/swagger-reference.md +180 -0
- package/skills/nestjs-outbox/SKILL.md +119 -0
- package/skills/nestjs-outbox/references/outbox-reference.md +74 -0
- package/skills/nestjs-passport-auth/SKILL.md +125 -0
- package/skills/nestjs-queues/SKILL.md +118 -0
- package/skills/nestjs-queues/references/bull-legacy.md +75 -0
- package/skills/nestjs-request-pipeline/SKILL.md +146 -0
- package/skills/nestjs-request-pipeline/references/filters-interceptors.md +114 -0
- package/skills/nestjs-request-pipeline/references/pipes-decorators.md +80 -0
- package/skills/nestjs-resilience/SKILL.md +116 -0
- package/skills/nestjs-resilience/references/resilience-reference.md +74 -0
- package/skills/nestjs-scheduling/SKILL.md +100 -0
- package/skills/nestjs-security-hardening/SKILL.md +99 -0
- package/skills/nestjs-security-hardening/references/throttler-advanced.md +78 -0
- package/skills/nestjs-standalone-apps/SKILL.md +78 -0
- package/skills/nestjs-testing/SKILL.md +118 -0
- package/skills/nestjs-testing/references/advanced-testing.md +62 -0
- package/skills/nestjs-upgrading/SKILL.md +82 -0
- package/skills/nestjs-upgrading/references/esm-switch.md +114 -0
- package/skills/nestjs-validation-serialization/SKILL.md +124 -0
- package/skills/nestjs-validation-serialization/references/validation-options.md +84 -0
- package/skills/nestjs-webhooks/SKILL.md +116 -0
- package/skills/nestjs-webhooks/references/webhooks-reference.md +132 -0
- package/skills/nestjs-websockets/SKILL.md +108 -0
- package/skills/nestjs-workflows/SKILL.md +123 -0
- package/skills/nestjs-workflows/references/workflows-reference.md +85 -0
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# @nestjs/webhooks reference
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
- Module options
|
|
5
|
+
- Receiver options
|
|
6
|
+
- Stores, executors and migrations
|
|
7
|
+
- Services and decorators
|
|
8
|
+
- Testing recipe
|
|
9
|
+
- Events and errors
|
|
10
|
+
- Custom transports
|
|
11
|
+
- Production checklist
|
|
12
|
+
|
|
13
|
+
## Module options
|
|
14
|
+
|
|
15
|
+
`forRootAsync()` takes `outgoing`, `transport` (class), `imports`, `isGlobal` at the top level next to `useFactory`/`useClass`/`useExisting`; the factory returns the rest. Durations: ms or `'15s'`, `'24h'`, `'5d'`. Token: `WEBHOOKS_MODULE_OPTIONS`.
|
|
16
|
+
|
|
17
|
+
| Option | Default | Notes |
|
|
18
|
+
| --- | --- | --- |
|
|
19
|
+
| `eventTypes` | any | Types `dispatch()` and endpoints accept (endpoints also `*`) |
|
|
20
|
+
| `retry` | 10 attempts | `attempts`, `backoff`, `retryIf(error, attempt, delivery)`; number = attempts, `false` = one attempt |
|
|
21
|
+
| `retry.backoff` | `delay '5s'`, `factor 4`, `maxDelay '1d'`, `jitter 'equal'` | Or a function returning a duration |
|
|
22
|
+
| `disableEndpointAfter` | `'5d'` | Disable endpoints failing that long; `false` never |
|
|
23
|
+
| `secretRotationOverlap` | `'24h'` | Old secret keeps co-signing |
|
|
24
|
+
| `delivery.timeout` | `'15s'` | Must be shorter than `worker.lease` |
|
|
25
|
+
| `delivery.allowHttp` / `allowPrivateNetworks` | `false` | Development only; metadata addresses always blocked |
|
|
26
|
+
| `delivery.allowedAddresses` | none | CIDRs allowed despite blocking |
|
|
27
|
+
| `delivery.maxResponseSize` / `userAgent` | 4096 / `NestJS-Webhooks/1.0` | |
|
|
28
|
+
| `worker.enabled` / `pollInterval` / `batchSize` / `concurrency` / `lease` | `true` / `'1s'` / 50 / 10 / `'1m'` | |
|
|
29
|
+
| `encryption.keys` | off | 32-byte Buffers or ≥32-char strings, newest first |
|
|
30
|
+
| `receivers` | none | See below |
|
|
31
|
+
| `transport` | `HttpWebhookTransport` | Class (top level) or instance (factory) |
|
|
32
|
+
| `allowInMemoryStorage` | `false` | Allow production start without stores |
|
|
33
|
+
| `outgoing` | `true` | `false` for receive-only services |
|
|
34
|
+
| `isGlobal` | `true` | |
|
|
35
|
+
|
|
36
|
+
## Receiver options
|
|
37
|
+
|
|
38
|
+
| Option | Applies to | Default |
|
|
39
|
+
| --- | --- | --- |
|
|
40
|
+
| `scheme` | all | required: `'standard'`, `'stripe'`, `'github'`, or a `WebhookSignatureScheme` subclass instance |
|
|
41
|
+
| `secret` | all | required; array while rotating |
|
|
42
|
+
| `tolerance` | standard, stripe, custom | `'5m'` |
|
|
43
|
+
| `header` | stripe | `'stripe-signature'` |
|
|
44
|
+
| `id` | stripe, github | payload `id` / `X-GitHub-Delivery` (unsigned!) — `(payload, headers) => string` ≤255 chars |
|
|
45
|
+
| `dedupe` | all | `true` |
|
|
46
|
+
| `consumer` | all | `webhooks:<name>` — keep stable, ≤255 chars |
|
|
47
|
+
|
|
48
|
+
`WebhookVerifier.verify(receiver, { headers, rawBody })` verifies requests that didn't arrive over HTTP (e.g. from a queue).
|
|
49
|
+
|
|
50
|
+
## Stores, executors and migrations
|
|
51
|
+
|
|
52
|
+
`new PostgresWebhookStore({ executor, schema?, migrate? }, webhooksStorage)` from `@nestjs/webhooks/postgres`; `MySqlWebhookStore` from `@nestjs/webhooks/mysql` (MySQL 8.4 / 9.x). Outbox stores take the same options (`schema` default `nest_outbox`).
|
|
53
|
+
|
|
54
|
+
| Executor | Client | Transaction object for `dispatch()` / `processInTransaction()` |
|
|
55
|
+
| --- | --- | --- |
|
|
56
|
+
| `fromDrizzle(db)` | Drizzle (any PG driver; `drizzle-orm/mysql2` on MySQL) | `tx` from `db.transaction()` |
|
|
57
|
+
| `fromTypeOrm(dataSource)` | `DataSource` (postgres/mysql) | `EntityManager` from `dataSource.transaction()`, or a started `QueryRunner` |
|
|
58
|
+
| `fromPrisma(prisma, { maxWait, timeout })` | Prisma with a driver adapter (`@prisma/adapter-pg`, `@prisma/adapter-mariadb`) | tx client from `prisma.$transaction()` |
|
|
59
|
+
| `fromKysely(db)` | Kysely | tx from `db.transaction().execute()` |
|
|
60
|
+
| `fromPg(pool)` / `fromMysql2(pool)` | pool | connection after `BEGIN` / `beginTransaction()` |
|
|
61
|
+
|
|
62
|
+
The outbox store refuses the database itself (`OutboxTransactionRequiredError`).
|
|
63
|
+
|
|
64
|
+
Migrations:
|
|
65
|
+
- `migrate: true` except with `NODE_ENV=production`; a schema behind with `migrate: false` → `WebhookSchemaError` at startup and on every call.
|
|
66
|
+
- CLI (`--url`, default `DATABASE_URL`; `--schema`): `npx @nestjs/webhooks migrate | status | sql [--dialect mysql] [--statement-breakpoints]`; same for `npx @nestjs/outbox`.
|
|
67
|
+
- TypeORM migration: `queryRunner.query(PostgresOutboxStore.migrationSql())` then `PostgresWebhookStore.migrationSql()`; MySQL: loop over `migrationStatements()`.
|
|
68
|
+
- drizzle-kit: `npx drizzle-kit generate --custom --name=webhooks` and fill it with `npx @nestjs/webhooks sql --statement-breakpoints`.
|
|
69
|
+
- No down migrations. `CREATE SCHEMA` needs the CREATE privilege.
|
|
70
|
+
|
|
71
|
+
## Services and decorators
|
|
72
|
+
|
|
73
|
+
- `Webhooks.dispatch(tx, message | message[])`: `{ type, data, tenant, id? }`; `TypeError` for unknown type, non-JSON data, invalid id. `notify()` runs the relay now.
|
|
74
|
+
- `WebhookEndpoints`: `create({ url, eventTypes, tenant, description?, secret? })`, `list(query)`, `get(id, scope)`, `update(id, changes, scope)`, `delete(id, scope)`, `getSecret(id, scope)`, `rotateSecret(id, { tenant, overlap, secret })`.
|
|
75
|
+
- `WebhookDeliveries`: `list(query)`, `get(id, scope)`, `retry(idOrFilter, scope)` (a replay keeps the same `webhook-id`), `stats()` (`lagMs`, `failed` …), `prune(olderThan)`.
|
|
76
|
+
- `WebhookWorker`: `start()`, `stop()`, `running`, `notify()`, `runOnce()` → `{ claimed, delivered, retried, failed, released, leaseLost }`.
|
|
77
|
+
- `@VerifyWebhook(receiver)` (method or controller), `@IncomingWebhook()` → `{ receiver, id, timestamp, payload, rawBody, processInTransaction(tx, fn) }` (result has `duplicate`), `@WebhookPayload()` (accepts pipes).
|
|
78
|
+
- `WEBHOOKS_OUTBOX_TOPIC` = `'nestjs.webhooks.message'`: route it to `local` if the outbox routes topics to several transports.
|
|
79
|
+
|
|
80
|
+
## Testing recipe
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
const client = new PGlite();
|
|
84
|
+
const db = drizzle({ client });
|
|
85
|
+
const transport = new InMemoryWebhookTransport();
|
|
86
|
+
process.env.OUTBOX_RELAY = 'off';
|
|
87
|
+
process.env.WEBHOOKS_WORKER = 'off';
|
|
88
|
+
|
|
89
|
+
const moduleRef = await Test.createTestingModule({ imports: [AppModule] })
|
|
90
|
+
.overrideProvider(getDrizzleToken()).useValue(db) // stores follow, their factories inject it
|
|
91
|
+
.overrideProvider(WebhookTransport).useValue(transport)
|
|
92
|
+
.compile();
|
|
93
|
+
app = moduleRef.createNestApplication({ rawBody: true });
|
|
94
|
+
await app.init();
|
|
95
|
+
|
|
96
|
+
const deliver = async () => { await app.get(OutboxRelay).runOnce(); return app.get(WebhookWorker).runOnce(); };
|
|
97
|
+
|
|
98
|
+
// incoming
|
|
99
|
+
const paid = signWebhook({ scheme: 'standard', secret: PAYMENTS_SECRET, payload: { type: 'payment.succeeded', data } });
|
|
100
|
+
await request(app.getHttpServer()).post('/webhooks/payments').set(paid.headers).send(paid.body).expect(200);
|
|
101
|
+
|
|
102
|
+
// outgoing
|
|
103
|
+
await deliver();
|
|
104
|
+
const sent = transport.single({ type: 'order.shipped' });
|
|
105
|
+
expect(sent.isSignedWith(endpoint.secret)).toBe(true);
|
|
106
|
+
transport.respondWith(503); // simulate failures; or a function of (request, attempt)
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
`signWebhook()` and the store contract suites (`webhookEndpointStoreContract()`, `webhookDeliveryStoreContract()`, run with `{ concurrent: true }`) come from `@nestjs/webhooks/testing`. Standard secrets look like `whsec_<base64 32 bytes>`.
|
|
110
|
+
|
|
111
|
+
## Events and errors
|
|
112
|
+
|
|
113
|
+
`WebhooksEvents.events$` (also diagnostics channel `nestjs:webhooks:<type>`): `delivered`, `retry-scheduled`, `delivery-failed` (`reason`: `exhausted | rejected | endpoint-disabled | endpoint-deleted`), `endpoint-disabled` (`failing | gone`), `destination-blocked`, `verification-failed` (`missing-header | malformed-header | invalid-signature | timestamp-out-of-tolerance | invalid-payload`).
|
|
114
|
+
|
|
115
|
+
Errors (all extend `WebhooksError` except `NonRetryableWebhookError`): `InvalidWebhookEndpointError` 400 (`field`), `WebhookEndpointNotFoundError` 404, `WebhookDeliveryNotFoundError` 404, `WebhookVerificationError` 401/400, `WebhookDestinationBlockedError`, `WebhookResponseError` (`statusCode`, `retryAfterMs`), `WebhookDeliveryTimeoutError`, `WebhookSchemaError`.
|
|
116
|
+
|
|
117
|
+
Outcomes: 2xx delivered; other statuses/timeouts retried with backoff, `Retry-After` honored up to `maxDelay`; 410 Gone fails and disables the endpoint; redirects never followed.
|
|
118
|
+
|
|
119
|
+
## Custom transports
|
|
120
|
+
|
|
121
|
+
`HttpWebhookTransport` resolves and pins checked addresses, never follows redirects, ignores env proxies. Extra constructor options: `ca` (private CAs) and `lookup`. Pass an instance with the same `allowHttp`/`allowPrivateNetworks`/`allowedAddresses` as `delivery`. A custom class extends `WebhookTransport`, implements `send(request, { signal, attempt })` returning `{ statusCode, headers, body }`, throws only without a response; it replaces the SSRF guard.
|
|
122
|
+
|
|
123
|
+
## Production checklist
|
|
124
|
+
|
|
125
|
+
- Database stores registered; migrations applied before deploy; `status` checked in CI.
|
|
126
|
+
- READ COMMITTED on PostgreSQL; retry MySQL deadlocks (1213).
|
|
127
|
+
- SSRF options off; alert on `destination-blocked`, `endpoint-disabled`, `lagMs`, `failed`.
|
|
128
|
+
- Worker in a few instances; `enableShutdownHooks()`.
|
|
129
|
+
- Versioned payloads; delivery log and replay exposed to partners.
|
|
130
|
+
- Encryption keys in a secret manager; rotation with overlap.
|
|
131
|
+
- Scheduled `deliveries.prune()` and `OutboxInbox.prune()` (inbox window longer than any sender's retry schedule).
|
|
132
|
+
- Receivers: `rawBody: true`, short idempotent handlers.
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: nestjs-websockets
|
|
3
|
+
description: Builds real-time features with NestJS 12 WebSocket gateways — @WebSocketGateway, @SubscribeMessage handlers with @MessageBody, @ConnectedSocket, @Ack acknowledgements, WsResponse and Observable streaming, lifecycle hooks (afterInit, handleConnection, handleDisconnect), @WebSocketServer for broadcasting, request-scoped per-connection providers (v12), WsException with gateway-level filters (global filters don't apply), pipes, guards and interceptors, socket.io with the Redis adapter for multiple instances, the ws library WsAdapter with message parsers, and custom adapters. Use when adding chat, notifications, live dashboards, presence or any socket-based messaging, scaling sockets across pods, authenticating socket connections, or when gateway errors, validation or guards behave differently than HTTP. Not for SSE (nestjs-http-web-features), GraphQL subscriptions (nestjs-graphql) or microservice transports (nestjs-microservices).
|
|
4
|
+
compatibility: NestJS 12.x; @nestjs/websockets with @nestjs/platform-socket.io or @nestjs/platform-ws
|
|
5
|
+
metadata:
|
|
6
|
+
version: "0.1.0"
|
|
7
|
+
nestjs-major: "12"
|
|
8
|
+
docs-crawled: "2026-11-05"
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# NestJS WebSocket gateways
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm i @nestjs/websockets @nestjs/platform-socket.io # or @nestjs/platform-ws (native WebSockets, faster, no namespaces/rooms)
|
|
15
|
+
nest g gateway events
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Choose socket.io for rooms, namespaces, acks, reconnection and fallbacks; choose `ws` (`app.useWebSocketAdapter(new WsAdapter(app))`) for plain browser WebSockets and performance. Detect the existing adapter first.
|
|
19
|
+
|
|
20
|
+
## Gateway
|
|
21
|
+
|
|
22
|
+
```typescript
|
|
23
|
+
@WebSocketGateway({ namespace: 'events', cors: { origin: process.env.WEB_ORIGIN } }) // same port as HTTP by default
|
|
24
|
+
export class EventsGateway implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect {
|
|
25
|
+
@WebSocketServer() server: Server; // Namespace when a namespace is set
|
|
26
|
+
constructor(private readonly events: EventsService) {}
|
|
27
|
+
|
|
28
|
+
afterInit(server: Server) {
|
|
29
|
+
server.use((socket, next) => verifyToken(socket.handshake.auth.token) ? next() : next(new Error('unauthorized'))); // gate connections here
|
|
30
|
+
}
|
|
31
|
+
handleConnection(client: Socket) { /* not a gate: messages may arrive before an async check finishes */ }
|
|
32
|
+
handleDisconnect(client: Socket) {}
|
|
33
|
+
|
|
34
|
+
@SubscribeMessage('events')
|
|
35
|
+
handle(@MessageBody() data: CreateEventDto, @ConnectedSocket() client: Socket): WsResponse<EventDto> {
|
|
36
|
+
return { event: 'events', data: this.events.create(data) }; // or return a value → ack; or an Observable → stream
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
@SubscribeMessage('ping')
|
|
40
|
+
ping(@MessageBody() data: string, @Ack() ack: (r: { status: string }) => void) { ack({ status: 'ok' }); }
|
|
41
|
+
|
|
42
|
+
broadcastOrderUpdate(order: OrderDto) { this.server.to(`order:${order.id}`).emit('order.updated', order); } // call from services
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
@Module({ providers: [EventsGateway, EventsService] }) // gateways only start when listed as providers
|
|
46
|
+
export class EventsModule {}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
- `@MessageBody('id')` extracts a property. `handle(client, data)` positional style also works.
|
|
50
|
+
- Native WebSockets (`ws`) don't support acks; return `{ event, data }` (`WsResponse`) instead.
|
|
51
|
+
- With `ClassSerializerInterceptor`, return class instances (plain objects are ignored).
|
|
52
|
+
- Per-connection state: request-scoped providers (v12) get one instance per socket; `@Inject(REQUEST)` is the client socket. Use sparingly (overhead).
|
|
53
|
+
- Inject the gateway into services to emit from HTTP handlers or event listeners.
|
|
54
|
+
|
|
55
|
+
## Errors, pipes, guards, interceptors
|
|
56
|
+
|
|
57
|
+
| Enhancer | Global (`useGlobal*` / `APP_*`) applies? | Notes |
|
|
58
|
+
| --- | --- | --- |
|
|
59
|
+
| Filters | **No** | Bind with `@UseFilters()` on gateway/method; extend `BaseWsExceptionFilter` |
|
|
60
|
+
| Pipes | Yes | Throw `WsException`; set `exceptionFactory: (errors) => new WsException(errors)` on `ValidationPipe` / `StandardSchemaValidationPipe`, or other errors reach clients as "Internal server error" |
|
|
61
|
+
| Guards | Yes | `false` → `WsException('Forbidden resource')`; read the user from `context.switchToWs().getClient()` |
|
|
62
|
+
| Interceptors | Yes | Same API as HTTP |
|
|
63
|
+
|
|
64
|
+
- Throw `new WsException('Invalid credentials.')`; the client gets `{ status: 'error', message, cause: { pattern, data } }` on the `exception` event.
|
|
65
|
+
- Validation: `@MessageBody({ schema: createEventSchema })` with `StandardSchemaValidationPipe({ exceptionFactory: (issues) => new WsException(issues) })`.
|
|
66
|
+
- Auth: gate connections in `afterInit` middleware (socket.io) or `verifyClient` (ws options), and guard each message. With `@nestjs/authentication`, call `WsAuthenticator.authenticateConnection()` in `handleConnection` (see nestjs-authentication).
|
|
67
|
+
## Scaling across instances (socket.io)
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npm i redis socket.io @socket.io/redis-adapter
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
```typescript
|
|
74
|
+
export class RedisIoAdapter extends IoAdapter {
|
|
75
|
+
private adapterConstructor: ReturnType<typeof createAdapter>;
|
|
76
|
+
async connectToRedis(url: string) {
|
|
77
|
+
const pub = createClient({ url }); const sub = pub.duplicate();
|
|
78
|
+
await Promise.all([pub.connect(), sub.connect()]);
|
|
79
|
+
this.adapterConstructor = createAdapter(pub, sub);
|
|
80
|
+
}
|
|
81
|
+
createIOServer(port: number, options?: ServerOptions) {
|
|
82
|
+
const server = super.createIOServer(port, options);
|
|
83
|
+
server.adapter(this.adapterConstructor);
|
|
84
|
+
return server;
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
const adapter = new RedisIoAdapter(app); await adapter.connectToRedis(config.REDIS_URL); app.useWebSocketAdapter(adapter);
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Also either force `transports: ['websocket']` on clients or enable sticky sessions on the load balancer — Redis alone isn't enough with polling.
|
|
91
|
+
|
|
92
|
+
## ws adapter specifics
|
|
93
|
+
|
|
94
|
+
`new WsAdapter(app, { messageParser: (data) => { const [event, payload] = JSON.parse(data.toString()); return { event, data: payload }; } })`. No namespaces (throws): use `@WebSocketGateway({ path: '/users' })` per gateway. Custom adapters implement `WebSocketAdapter` (`create`, `bindClientConnect`, `bindMessageHandlers`, `close`).
|
|
95
|
+
|
|
96
|
+
## Testing
|
|
97
|
+
|
|
98
|
+
Unit-test handlers by calling gateway methods directly. E2E: `app.listen(0)`, connect with `socket.io-client` (or `ws`) to the server URL, emit, await the response/ack, and disconnect in `afterEach`.
|
|
99
|
+
|
|
100
|
+
## Workflow
|
|
101
|
+
|
|
102
|
+
- [ ] 1. Pick the adapter; install; `nest g gateway`; add to a module's providers.
|
|
103
|
+
- [ ] 2. Define message DTOs/schemas + validation pipe with `WsException` factory.
|
|
104
|
+
- [ ] 3. Connection auth (middleware/verifyClient) + per-message guards; gateway-level filters.
|
|
105
|
+
- [ ] 4. Broadcasting via `@WebSocketServer()`; rooms/namespaces; Redis adapter + sticky sessions for multi-instance.
|
|
106
|
+
- [ ] 5. Socket client e2e tests. Build, lint, run tests, start the app.
|
|
107
|
+
|
|
108
|
+
Sources: [Gateways](https://docs.nestjs.com/websockets/gateways) · [Exception filters](https://docs.nestjs.com/websockets/exception-filters) · [Pipes](https://docs.nestjs.com/websockets/pipes) · [Guards](https://docs.nestjs.com/websockets/guards) · [Interceptors](https://docs.nestjs.com/websockets/interceptors) · [Adapters](https://docs.nestjs.com/websockets/adapter)
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: nestjs-workflows
|
|
3
|
+
description: Builds durable, long-running processes in NestJS 12 with the first-party @nestjs/workflows package — @Workflow classes whose run() replays from a journal, ctx.step with idempotency keys, retries, timeouts, heartbeats and compensations (sagas with rollback), ctx.commit points of no return, durable timers and sleeps, typed WorkflowSignal waits and waitForAny races, run timeouts, WorkflowClient start (in your DB transaction), signal, getStatus, cancel, terminate, retry, purge, startAndWait, children, limits, priorities, schedules, versioning and deterministic replay rules, CQRS @StartOn/@SignalOn, Postgres/MySQL stores, and testing with ManualWorkflowClock and worker.drain(). Use when a business process spans minutes to weeks or multiple systems (order fulfilment, onboarding), must survive restarts and deploys, wait for webhooks or time, or undo completed steps on failure. Not for single background jobs (nestjs-queues), simple crons (nestjs-scheduling) or in-memory sagas (nestjs-cqrs).
|
|
4
|
+
compatibility: NestJS 12.x; @nestjs/workflows; PostgreSQL or MySQL 8.4/9.x store
|
|
5
|
+
metadata:
|
|
6
|
+
version: "0.1.0"
|
|
7
|
+
nestjs-major: "12"
|
|
8
|
+
docs-crawled: "2026-11-05"
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# NestJS durable workflows (@nestjs/workflows)
|
|
12
|
+
|
|
13
|
+
Choose: one unit of background work → BullMQ (nestjs-queues); in-process reactions where losing state on restart is fine → CQRS sagas; a multi-step process that waits, spans systems and must undo on failure → a workflow.
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm i @nestjs/workflows
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Register with a database store
|
|
20
|
+
|
|
21
|
+
```typescript
|
|
22
|
+
WorkflowsModule.forRoot({ worker: { concurrency: 10, leaseDuration: '30s', shutdownTimeout: '10s' } }),
|
|
23
|
+
// providers:
|
|
24
|
+
{ provide: PostgresWorkflowStore, inject: [getDrizzleToken(), WorkflowStorage],
|
|
25
|
+
useFactory: (db, storage: WorkflowStorage) => new PostgresWorkflowStore({ executor: fromDrizzle(db) }, storage) },
|
|
26
|
+
OrderFulfilmentWorkflow, // workflow classes are providers
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Store creates its own schema (`nest_workflows`); in production run `npx @nestjs/workflows migrate` and check `status` in CI. Executors: `fromDrizzle`, `fromTypeOrm`, `fromPg`/`fromMysql2`, `fromPrisma`, `fromKysely`. `app.enableShutdownHooks()`; keep `shutdownTimeout` below the platform grace period.
|
|
30
|
+
|
|
31
|
+
## Write the workflow
|
|
32
|
+
|
|
33
|
+
```typescript
|
|
34
|
+
export const shipmentDelivered = new WorkflowSignal<CarrierEvent>('shipment.delivered');
|
|
35
|
+
export const shipmentReturned = new WorkflowSignal<CarrierEvent>('shipment.returned');
|
|
36
|
+
|
|
37
|
+
@Workflow('order-fulfilment', { timeout: '30d', concurrency: { limit: 1, key: (o: Order) => o.userId }, rateLimit: { max: 10, duration: '1s' } })
|
|
38
|
+
export class OrderFulfilmentWorkflow implements WorkflowRunner<Order, FulfilmentResult> {
|
|
39
|
+
constructor(private readonly payments: PaymentsService, private readonly inventory: InventoryService, private readonly mail: MailService) {}
|
|
40
|
+
|
|
41
|
+
async run(ctx: WorkflowContext, order: Order): Promise<FulfilmentResult> {
|
|
42
|
+
const charge = await ctx.step('charge-payment', ({ idempotencyKey }) => this.payments.charge(order, idempotencyKey), {
|
|
43
|
+
retry: { attempts: 5, backoff: { delay: '2s' } },
|
|
44
|
+
compensate: (c, { idempotencyKey }) => this.payments.refund(c.chargeId, idempotencyKey),
|
|
45
|
+
});
|
|
46
|
+
await ctx.step('reserve-stock', ({ idempotencyKey }) => this.inventory.reserve(order.items, idempotencyKey),
|
|
47
|
+
{ compensate: ({ reservationId }) => this.inventory.release(reservationId) });
|
|
48
|
+
ctx.setStatus('awaiting-delivery');
|
|
49
|
+
|
|
50
|
+
const outcome = await ctx.waitForAny('await-delivery', {
|
|
51
|
+
delivered: ctx.signalWait(shipmentDelivered, { key: order.id }),
|
|
52
|
+
returned: ctx.signalWait(shipmentReturned, { key: order.id }),
|
|
53
|
+
timedOut: ctx.timer('3d'),
|
|
54
|
+
});
|
|
55
|
+
if (outcome.key !== 'delivered') ctx.fail(`Order ${order.id} was not delivered.`); // compensations run in reverse
|
|
56
|
+
|
|
57
|
+
ctx.commit('delivered'); // point of no return: discards compensations
|
|
58
|
+
await ctx.sleep('before-review-request', '7d'); // durable; holds no memory or worker
|
|
59
|
+
await ctx.step('send-review-request', ({ idempotencyKey }) => this.mail.sendReviewRequest(order, idempotencyKey));
|
|
60
|
+
return { chargeId: charge.chargeId, trackingNumber: outcome.value.trackingNumber };
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Rules for workflow code:
|
|
66
|
+
- `run()` **replays from the top** after every wait, sleep or crash; completed steps return journaled results. Put every side effect, random value or clock read in a step (use `ctx.now()`), never between steps.
|
|
67
|
+
- Steps run **at least once**: pass `idempotencyKey` to every side effect (and compensation). Throw `NonRetryableStepError` for permanent failures (declined card).
|
|
68
|
+
- The class is a shared singleton: per-instance state in local variables, never `this`.
|
|
69
|
+
- Step/sleep/wait names are a contract with running instances and part of the idempotency key. Renaming, removing, reordering or inserting earlier steps requires a **new version** (`@Workflow(name, { version: 2 })`, keep v1 registered until its instances finish). Safe without a version: changing a body's implementation, appending after the furthest point reached, changing retry/timeouts.
|
|
70
|
+
- Parallel steps: `Promise.all(items.map((it, i) => ctx.step(\`reserve-item-${i}\`, …)))`.
|
|
71
|
+
- Long steps: `({ progress, heartbeat, signal }: WorkflowStepContext<Checkpoint>)` with `heartbeat(checkpoint)` and `heartbeatTimeout`.
|
|
72
|
+
- Keep journals bounded (loops grow them).
|
|
73
|
+
|
|
74
|
+
## Start, signal, operate
|
|
75
|
+
|
|
76
|
+
```typescript
|
|
77
|
+
await this.db.transaction(async (tx) => {
|
|
78
|
+
await tx.insert(orders).values(order);
|
|
79
|
+
await this.workflows.start(OrderFulfilmentWorkflow, order, { id: `order-${order.id}`, transaction: tx, priority: order.express ? 1 : 2 });
|
|
80
|
+
}); // exists iff the order does; same id+input is idempotent
|
|
81
|
+
|
|
82
|
+
await this.workflows.signal(shipmentDelivered, event, { key: event.reference, id: event.eventId, transaction: tx }); // from a verified webhook
|
|
83
|
+
const instance = await this.workflows.getStatus(`order-${id}`, { journal: true }); // status, customStatus, waits, wakeAt, error, output
|
|
84
|
+
await this.workflows.cancel(id, reason); // runs compensations; terminate(id, reason) skips them
|
|
85
|
+
await this.workflows.retry(id); // failed/compensation_failed; delete(id, { force })
|
|
86
|
+
await this.workflows.purge({ olderThan: '30d' }); // nightly, @OnOneInstance (nestjs-locks)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- Statuses: `pending`, `running`, `suspended`, `compensating`, `completed`, `cancelled`, `failed`, `compensation_failed` (needs a person).
|
|
90
|
+
- Children: `ctx.executeChild(ShipmentWorkflow, order)` (throws `ChildWorkflowFailedError`), `ctx.startChild(...)`, `parentClose: 'cancel' | 'terminate' | 'abandon'`.
|
|
91
|
+
- Schedules: `@Workflow('invoice-batch', { schedules: [{ id: 'monthly-invoices', cron: '0 2 1 * *', tz: 'America/New_York', missed: 'once', priority: 10 }] })`; runtime: `workflows.schedules.upsert/trigger/pause/resume/remove`.
|
|
92
|
+
- `startAndWait(workflow, input, options, { timeout })` for request/response callers.
|
|
93
|
+
- CQRS: `WorkflowsCqrsModule` + `@StartOn(Event, { id, input })` / `@SignalOn(Event, { signal, key })`, publish with `{ transaction: tx }` (nestjs-cqrs).
|
|
94
|
+
- Encrypt stored payloads with a `codec`; ids and keys stay readable.
|
|
95
|
+
|
|
96
|
+
## Testing
|
|
97
|
+
|
|
98
|
+
```typescript
|
|
99
|
+
const clock = new ManualWorkflowClock();
|
|
100
|
+
// .overrideProvider(getDrizzleToken()).useValue(pgliteDb)
|
|
101
|
+
// .overrideProvider(WORKFLOWS_MODULE_OPTIONS).useValue({ clock, worker: { enabled: false, shutdownTimeout: 50 } })
|
|
102
|
+
await orders.place(dto);
|
|
103
|
+
await worker.drain(); // charge, reserve, park
|
|
104
|
+
clock.advance('3d');
|
|
105
|
+
await worker.drain(); // timeout → compensations
|
|
106
|
+
expect(await workflows.getStatus(id)).toMatchObject({ status: 'failed' });
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Test crash recovery by booting a second app on the same database and draining. Store authors: `workflowStoreContract()` from `@nestjs/workflows/testing`.
|
|
110
|
+
|
|
111
|
+
## Workflow
|
|
112
|
+
|
|
113
|
+
- [ ] 1. Install; register module + database store; migrations in the release step.
|
|
114
|
+
- [ ] 2. Model the process: steps with idempotency keys and compensations, signals, timers, commit point, run timeout.
|
|
115
|
+
- [ ] 3. Start in the business transaction with a deterministic id; signal from verified webhooks with ids.
|
|
116
|
+
- [ ] 4. Ops: status endpoint, staff cancel/retry, nightly purge, alerts on `compensation_failed` and non-determinism failures.
|
|
117
|
+
- [ ] 5. Manual-clock tests. Build, lint, run tests, start the app.
|
|
118
|
+
|
|
119
|
+
## Reference files
|
|
120
|
+
|
|
121
|
+
- `references/workflows-reference.md`: module and retry options, call options for every ctx/client method, schedule options, store/CLI details, events and errors. Read when using an option not shown above.
|
|
122
|
+
|
|
123
|
+
Sources: [Durable workflows](https://docs.nestjs.com/reliability/workflows)
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# @nestjs/workflows reference
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
- Module options
|
|
5
|
+
- Retry options
|
|
6
|
+
- Call options
|
|
7
|
+
- Schedule options
|
|
8
|
+
- Stores and CLI
|
|
9
|
+
- Events
|
|
10
|
+
- Errors
|
|
11
|
+
|
|
12
|
+
## Module options
|
|
13
|
+
|
|
14
|
+
`WorkflowsModule.forRoot()` / `forRootAsync()` (`WorkflowsOptionsFactory`). Token `WORKFLOWS_MODULE_OPTIONS`. The store is registered via `WorkflowStorage`, not an option.
|
|
15
|
+
|
|
16
|
+
| Option | Default |
|
|
17
|
+
| --- | --- |
|
|
18
|
+
| `worker.enabled` (`worker: false` shorthand) | `true` |
|
|
19
|
+
| `worker.id` | `hostname:pid:random` |
|
|
20
|
+
| `worker.concurrency` | 10 |
|
|
21
|
+
| `worker.pollInterval` | `'1s'` |
|
|
22
|
+
| `worker.leaseDuration` | `'30s'` (keep host clocks in sync) |
|
|
23
|
+
| `worker.heartbeatInterval` | lease ÷ 3 |
|
|
24
|
+
| `worker.shutdownTimeout` | `'10s'` |
|
|
25
|
+
| `retry` | 3 attempts, `'1s'` ×2 up to `'5m'`, no jitter |
|
|
26
|
+
| `journal.warnEntries` / `warnBytes` | 1000 / 1 MB (`journal-large` event) |
|
|
27
|
+
| `journal.maxEntries` / `maxBytes` | 10000 / 10 MB (fail with `WorkflowJournalLimitError`) |
|
|
28
|
+
| `clock` | system (`ManualWorkflowClock` in tests) |
|
|
29
|
+
| `allowInMemoryStorage` | `false` |
|
|
30
|
+
| `codec` | none (`WorkflowPayloadCodec` or list; first encodes) |
|
|
31
|
+
| `isGlobal` | `true` |
|
|
32
|
+
|
|
33
|
+
## Retry options
|
|
34
|
+
|
|
35
|
+
Number, `false`, or `{ attempts: 3, backoff: { delay: '1s', factor: 2, maxDelay: '5m', jitter: 'none' | 'full' | 'equal' }, retryIf(error, attempt) }`; `backoff` may be `(attempt, error) => duration`. Step `retry` merges over the module's per field. `NonRetryableStepError` never retries.
|
|
36
|
+
|
|
37
|
+
## Call options
|
|
38
|
+
|
|
39
|
+
| Call | Options |
|
|
40
|
+
| --- | --- |
|
|
41
|
+
| `@Workflow(name, …)` | `version` (1), `timeout`, `concurrency` (`limit`, `key`), `rateLimit` (`max`, `duration`, `key`), `schedules` |
|
|
42
|
+
| `ctx.step(name, fn, …)` | `retry`, `timeout`, `heartbeatTimeout`, `compensate`, `compensateRetry`; fn gets `idempotencyKey`, `attempt`, `signal`, `progress`, `heartbeat()` |
|
|
43
|
+
| `ctx.waitForSignal(name, signal, …)` | `key`, `timeout` (→ `null`), `match` (pure filter) |
|
|
44
|
+
| `ctx.sleep(name, duration \| { until })` | |
|
|
45
|
+
| `ctx.waitForAny(name, { k: ctx.signalWait(sig, { key, match }) \| ctx.timer(d) \| childHandle })` | resolves `{ key, value }` |
|
|
46
|
+
| `ctx.startChild` / `ctx.executeChild(workflow, input, …)` | `id` (default `<parent>/<workflow>#<n>`), `version`, `timeout`, `parentClose`, `priority`, `concurrencyKey`, `rateLimitKey` |
|
|
47
|
+
| `ctx.setStatus(json ≤16 KiB \| undefined)`, `ctx.commit(label)`, `ctx.fail(message)`, `ctx.now()`, `ctx.schedule` | |
|
|
48
|
+
| `client.start(workflow, input, …)` | `id`, `version`, `timeout`, `transaction`, `priority` (1–2,097,151; none goes first), `concurrencyKey`, `rateLimitKey` |
|
|
49
|
+
| `client.signal(signal, payload, …)` | `key`, `id` (dedupe), `transaction` |
|
|
50
|
+
| `client.startAndWait(workflow, input, opts, { timeout, signal })`, `client.result(id, { timeout, signal })` | |
|
|
51
|
+
| `client.getStatus(id, { journal, children })` | |
|
|
52
|
+
| `client.cancel(id, reason)`, `terminate(id, reason)` | |
|
|
53
|
+
| `client.list({ status, workflow, version, parentId, scheduleId, limit = 100, offset })` | |
|
|
54
|
+
| `client.retry(id, { timeout })`, `client.delete(id, { force })` | |
|
|
55
|
+
| `client.purge({ olderThan, status, batchSize = 500 })` → `{ instances, signals, rateLimits }` | |
|
|
56
|
+
| `client.schedules` / `WorkflowSchedules`: `upsert`, `get`, `list`, `remove`, `pause`, `resume`, `trigger` | declared schedules can't be upserted/removed |
|
|
57
|
+
| `@StartOn(Event, { id, input, priority, concurrencyKey, rateLimitKey })`, `@SignalOn(Event, { signal, key, id, payload })` | with `WorkflowsCqrsModule` |
|
|
58
|
+
|
|
59
|
+
## Schedule options
|
|
60
|
+
|
|
61
|
+
`id` (letters, digits, `.:_-`), one of `cron` (5 or 6 fields) / `every` (≥1 s) / `rrule`, `tz` (`'UTC'`), `startAt`, `endAt`, `limit`, `missed` (`'skip'` | `'once'` | `'all'`), `overlap` (`'skip'` | `'allow'` | `'cancel-previous'` | `'buffer-one'`), `priority`, `input` (JSON or function of the occurrence). Instance ids: `<schedule id>@<ISO time>`. Every worker whose code declares the schedule participates; dropped schedules disappear ~5 minutes after the last declaring worker stops.
|
|
62
|
+
|
|
63
|
+
## Stores and CLI
|
|
64
|
+
|
|
65
|
+
- `PostgresWorkflowStore` (`@nestjs/workflows/postgres`): `executor`, `schema` (`nest_workflows`), `migrate`. Keep READ COMMITTED.
|
|
66
|
+
- `MySqlWorkflowStore` (`@nestjs/workflows/mysql`): MySQL 8.4/9.x, strict sql_mode, not MariaDB; key length limits (ids 255, schedule ids 230, journal names 512).
|
|
67
|
+
- `migrate()`, `migrationSql()`, `migrationStatements()` (MySQL); CLI `npx @nestjs/workflows migrate | status | sql`.
|
|
68
|
+
- Custom stores: implement `WorkflowStore`, `registerSource(this)`, test with `workflowStoreContract(factory, { concurrent: true, transaction })`.
|
|
69
|
+
|
|
70
|
+
## Events
|
|
71
|
+
|
|
72
|
+
`WorkflowEvents.events$` + `nestjs:workflows:<type>`; payload `type`, `id`, `workflow`, `version`, `at`:
|
|
73
|
+
`workflow-started`, `workflow-resumed` (`run`), `workflow-suspended` (`wakeAt`, `waits`), `step-completed` (`step`, `attempt`, `durationMs`), `step-failed` (`retryAt` null = gave up), `signal-received`, `signal-timed-out`, `workflow-compensating`, `step-compensated`, `workflow-completed` (`output`), `workflow-failed`, `workflow-cancelled`, `workflow-compensation-failed`, `journal-large`, `workflow-retried`, `workflow-deleted`, `custom-status`, `child-started`, `schedule-skipped`. One trace per instance id.
|
|
74
|
+
|
|
75
|
+
## Errors
|
|
76
|
+
|
|
77
|
+
| Error | HTTP |
|
|
78
|
+
| --- | --- |
|
|
79
|
+
| `WorkflowIdConflictError` (same id, different input/workflow) | 409 |
|
|
80
|
+
| `WorkflowNotFoundError` | 404 |
|
|
81
|
+
| `WorkflowStateError` (invalid retry/delete, races, declared schedule edits) | 409 |
|
|
82
|
+
| `NonRetryableStepError` (yours) | — |
|
|
83
|
+
| `ChildWorkflowFailedError` (`status`, `cause`) | — |
|
|
84
|
+
| `WorkflowNonDeterminismError` (deploy broke replay; no compensations run) | — |
|
|
85
|
+
| `WorkflowJournalLimitError`, `WorkflowSchemaError`, `WorkflowTerminatedError` | — |
|