@aurostack/stacks 0.1.1 → 0.2.0

package/README.md

@@ -115,6 +115,65 @@ The shared code is literally the same files: `templates/react-app/derive.sh`
 re-flattens `packages/*` into `src/shared/*` and rewrites the import specifiers,
 so a fix in one lands in the other. See that template's README.
 
+### Observability
+
+Every template ships with OpenTelemetry (backend) or OpenObserve RUM (browser)
+wired in and switched on by default (`--without observability` for `nest-api`,
+`--without telemetry` for the rest). Nothing is sent until a project is
+connected; unset, the SDKs are never even loaded.
+
+| Template | Sends |
+|---|---|
+| `nest-api` | Traces (HTTP, GraphQL, Prisma, pg, ioredis, BullMQ jobs), logs with trace ids, runtime/HTTP/queue metrics |
+| `node-worker` | Job traces, Prisma/Redis spans, logs, metrics |
+| `py-worker` | One trace per job, Redis spans, logs, metrics |
+| `react-app` / `react-monorepo` | Page views, errors (including the error boundary's), slow resources, user actions, the signed-in user id, console errors as logs. API calls carry `traceparent`, so a click links to the backend trace it caused |
+
+To connect a project to its OpenObserve organization:
+
+1. Create an organization for the project in OpenObserve.
+2. **Backend:** from IAM → Ingestion Tokens, copy the org's ingestion token
+   (`o2oi_…`) and set `OPENOBSERVE_ORG` and `OPENOBSERVE_TOKEN`
+   (`OPENOBSERVE_URL` defaults to `https://o2.aurostack.co`). Each service
+   writes to its own stream, named after `OTEL_SERVICE_NAME`.
+3. **Frontend:** from Ingestion → RUM, copy the RUM token and set
+   `VITE_OPENOBSERVE_ORG` and `VITE_OPENOBSERVE_CLIENT_TOKEN`. It is a
+   write-only token built to ship in a bundle. Never put the backend's
+   ingestion token there.
+4. Add each app origin to the instance's `ZO_CORS_ALLOWED_ORIGINS`, or the
+   browser's RUM posts are blocked.
+
+Any other OTLP backend works too: set `OTEL_EXPORTER_OTLP_ENDPOINT` (and
+`_HEADERS`) instead of the `OPENOBSERVE_*` variables. `OTEL_SDK_DISABLED=true`
+turns telemetry off. Session replay is off by default
+(`sessionReplaySampleRate` in `initTelemetry`). The first request or two of a
+page load go out before the RUM SDK has started, so they carry no trace header.
+Source-map upload for readable browser stack traces needs OpenObserve
+Enterprise.
+
+### Background work: BullMQ or Temporal
+
+BullMQ is built in. Temporal is opt-in (`--with temporal`) for the backend
+templates, alongside the queues rather than instead of them:
+
+- **BullMQ** for fire-and-forget jobs: send an email, resize an image, a
+  cron-style sweep.
+- **Temporal** for work that spans many steps, waits (minutes to months, or
+  for a signal), or must resume exactly where it stopped after a crash or
+  deploy: onboarding sequences, payments and refunds, multi-service sagas.
+
+| Template | `--with temporal` adds |
+|---|---|
+| `nest-api` | `TemporalService` (a lazily-connected client for starting and querying workflows) and Temporal's dev server in `compose.yml` (UI on `:8233`) |
+| `node-worker` | A Temporal worker next to the BullMQ consumers, with an example workflow and activity in `src/temporal`. Its image switches to Debian: Temporal's native core doesn't run on Alpine |
+| `py-worker` | The same in Python (`temporal/`), with a span per workflow and activity when telemetry is on |
+
+Every template reads the same settings: `TEMPORAL_ADDRESS`,
+`TEMPORAL_NAMESPACE`, `TEMPORAL_TASK_QUEUE`, and for production mTLS the
+`TEMPORAL_TLS_CA`, `TEMPORAL_TLS_CERT` and `TEMPORAL_TLS_KEY` PEMs. Locally
+they default to the dev server with no TLS. The API starts workflows on the
+task queue a worker polls: `main` for node-worker, `python` for py-worker.
+
 ## How it works
 
 Templates are **subtractive**. `templates/<name>/files` is a complete, runnable

package/cli/src/generate.mjs

@@ -197,7 +197,19 @@ export function generate(manifest, target, options) {
 
 		const prune = prunes.get(destRel);
 		if (prune && path.basename(destRel) === 'package.json') {
-			const result = prunePackageJson(content, prune);
+			// Keys name packages as the template spells them (`@acme/telemetry`),
+			// but the content has already been through the rename map.
+			const renamed = (keys) =>
+				new Set(
+					[...keys].map((key) =>
+						applyReplacements(key, replacements, enabled, evalExpr)
+					)
+				);
+			const result = prunePackageJson(content, {
+				dependencies: renamed(prune.dependencies),
+				devDependencies: renamed(prune.devDependencies),
+				scripts: prune.scripts
+			});
 			content = result.raw;
 			report.pruned += result.removed;
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aurostack/stacks",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"description": "Scaffold new projects from house templates: a NestJS API, React app or Turborepo monorepo, and Node or Python workers. Subtractive templates plus a zero-dependency generator.",
 	"license": "MIT",
 	"author": "Aurostack (https://github.com/aurostack-org)",

package/templates/nest-api/files/.env.example

@@ -31,6 +31,17 @@ OAUTH_GOOGLE_CLIENT_SECRET=''
 LOG_LEVEL='debug'
 
 # @feature:start observability
+# OpenTelemetry → OpenObserve: traces, logs and metrics. Leave empty and
+# telemetry stays off (local development, tests). Per project:
+#   OPENOBSERVE_ORG    the project's organization identifier
+#   OPENOBSERVE_TOKEN  that org's ingestion token (IAM → Ingestion Tokens, o2oi_…)
+# OPENOBSERVE_STREAM defaults to the service name (OTEL_SERVICE_NAME).
+# Any other OTLP backend: set OTEL_EXPORTER_OTLP_ENDPOINT/HEADERS instead.
+OPENOBSERVE_URL='https://o2.aurostack.co'
+OPENOBSERVE_ORG=''
+OPENOBSERVE_TOKEN=''
+OTEL_SERVICE_NAME='acme-api'
+
 # Limits past which /health reports down. Size them to the container's real
 # limits: an orchestrator restarts instances that fail this check.
 HEALTH_HEAP_MAX_MB='300'
@@ -40,8 +51,8 @@ HEALTH_DISK_THRESHOLD='0.8'
 HEALTH_DISK_PATH='/'
 # @feature:end
 
-# @feature:start openapi, queue, observability
-# Guards /docs, /openapi-json, /dashboard and /metrics.
+# @feature:start openapi, queue
+# Guards /docs, /openapi-json and /dashboard.
 BASIC_AUTH_USER='admin'
 BASIC_AUTH_PASS='Secret@1'
 # @feature:end
@@ -72,6 +83,22 @@ S3_ACCESS_KEY_ID=''
 S3_SECRET_ACCESS_KEY=''
 # @feature:end
 
+# @feature:start temporal
+# Temporal: durable workflows. Locally, the dev server in compose.yml (no TLS;
+# UI on http://localhost:8233). In production, the server address, the
+# project's namespace and its mTLS client certificate (plus the CA that signed
+# the server's), as PEM. Escaped \n are accepted, so each fits on one line.
+TEMPORAL_ADDRESS='localhost:7233'
+TEMPORAL_NAMESPACE='default'
+# Where workflows started here are queued. The worker that runs them must poll
+# the same queue (its TEMPORAL_TASK_QUEUE); a mismatch is silent, workflows
+# just sit waiting.
+TEMPORAL_TASK_QUEUE='main'
+TEMPORAL_TLS_CA=''
+TEMPORAL_TLS_CERT=''
+TEMPORAL_TLS_KEY=''
+# @feature:end
+
 # @feature:start rate-limit
 RATE_LIMIT_ENABLED='true'
 # Throttler TTLs are in milliseconds.

package/templates/nest-api/files/.env.test.example

@@ -26,7 +26,7 @@ OAUTH_GOOGLE_CLIENT_SECRET=''
 
 LOG_LEVEL='silent'
 
-# @feature:start openapi, queue, observability
+# @feature:start openapi, queue
 BASIC_AUTH_USER='admin'
 BASIC_AUTH_PASS='Secret@1'
 # @feature:end

package/templates/nest-api/files/compose.yml

@@ -34,6 +34,22 @@ services:
     ports:
       - 6379:6379
   # @feature:end
+  # @feature:start temporal
+  # Temporal's development server (the CLI's `server start-dev`): gRPC on 7233,
+  # Web UI on http://localhost:8233, state kept in the temporal volume.
+  temporal:
+    container_name: acme-temporal
+    image: temporalio/temporal:1.9.1
+    restart: always
+    command: server start-dev --ip 0.0.0.0 --db-filename /home/temporal/temporal.db
+    ports:
+      - 7233:7233
+      - 8233:8233
+    volumes:
+      # The image runs as `temporal`; mounting its home keeps the volume writable.
+      - temporal:/home/temporal
+  # @feature:end
 
 volumes:
   database:
+  temporal: # @feature temporal

package/templates/nest-api/files/package.json

@@ -71,29 +71,44 @@
 		"@nestjs/terminus": "^12.1.0",
 		"@nestjs/throttler": "^6.7.1",
 		"@nestjs/websockets": "^12.1.0",
+		"@opentelemetry/api": "^1.9.1",
+		"@opentelemetry/auto-instrumentations-node": "^0.80.0",
+		"@opentelemetry/core": "^2.11.0",
+		"@opentelemetry/exporter-logs-otlp-proto": "^0.222.0",
+		"@opentelemetry/exporter-metrics-otlp-proto": "^0.222.0",
+		"@opentelemetry/exporter-trace-otlp-proto": "^0.222.0",
+		"@opentelemetry/instrumentation": "^0.222.0",
+		"@opentelemetry/instrumentation-express": "^0.70.0",
+		"@opentelemetry/resources": "^2.11.0",
+		"@opentelemetry/sdk-logs": "^0.222.0",
+		"@opentelemetry/sdk-metrics": "^2.11.0",
+		"@opentelemetry/sdk-node": "^0.222.0",
+		"@opentelemetry/semantic-conventions": "^1.43.0",
 		"@paralleldrive/cuid2": "^3.3.0",
 		"@prisma/adapter-pg": "^7.4.2",
 		"@prisma/client": "^7.4.2",
+		"@prisma/instrumentation": "^7.10.0",
 		"@react-email/components": "^0.0.7",
 		"@react-email/render": "^0.0.7",
 		"@scalar/nestjs-api-reference": "^1.2.22",
 		"@socket.io/redis-adapter": "^8",
+		"@temporalio/client": "^1.24.0",
 		"@thallesp/nestjs-better-auth": "^2.8.0",
-		"@willsoto/nestjs-prometheus": "^6.1.1",
 		"axios": "^1.4.0",
 		"better-auth": "^1.7.6",
-		"bullmq": "^5.79.2",
+		"bullmq": "^6.3.9",
+		"bullmq-otel": "^2.0.1",
 		"express": "^5.2.1",
 		"express-basic-auth": "^1.2.1",
 		"graphql": "^16.12.0",
 		"helmet": "^7.0.0",
+		"import-in-the-middle": "^3.5.1",
 		"ioredis": "^5.4.1",
 		"moment": "^2.29.4",
 		"nestjs-pino": "^5.2.0",
 		"nodemailer": "^8.0.11",
 		"pino": "^10.3.1",
 		"pino-http": "^11.0.0",
-		"prom-client": "^15.1.3",
 		"randomstring": "^1.3.0",
 		"react": "^18.2.0",
 		"react-email": "^1.9.4",

package/templates/nest-api/files/src/app.module.ts

@@ -4,6 +4,7 @@ import { HttpModule } from '@nestjs/axios'; // @feature http-client
 import { ScheduleModule } from '@nestjs/schedule'; // @feature scheduler
 import { MailerModule } from '@nestjs-modules/mailer'; // @feature mail
 import { BullModule } from '@nestjs/bullmq'; // @feature queue
+import { BullMQOtel } from 'bullmq-otel'; // @feature queue
 import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler'; // @feature rate-limit
 import { AuthModule, AuthGuard } from '@thallesp/nestjs-better-auth';
 import { betterAuth } from 'better-auth';
@@ -204,7 +205,14 @@ import { OriginBuilder } from 'common/misc';
 				},
 				defaultJobOptions: {
 					removeOnComplete: true
-				}
+				},
+				// Job spans for producers and workers; a no-op unless the
+				// OpenTelemetry SDK is running (see src/instrumentation.ts).
+				telemetry: new BullMQOtel({
+					tracerName: 'acme-api',
+					meterName: 'acme-api',
+					enableMetrics: true
+				})
 			})
 		}),
 		BullBoardModule.forRoot({

package/templates/nest-api/files/src/app.setup.ts

@@ -10,7 +10,7 @@ import { SwaggerModule } from '@nestjs/swagger'; // @feature openapi
 import { HttpAdapterHost, Reflector } from '@nestjs/core';
 import helmet from 'helmet';
 import express from 'express';
-import expressBasicAuth from 'express-basic-auth'; // @feature openapi, queue, observability
+import expressBasicAuth from 'express-basic-auth'; // @feature openapi, queue
 import { apiReference } from '@scalar/nestjs-api-reference'; // @feature openapi
 import { AuthService } from '@thallesp/nestjs-better-auth'; // @feature openapi
 import { Logger as PinoLogger } from 'nestjs-pino';
@@ -117,11 +117,11 @@ export const enableHelmet = (app: INestApplication) => {
 	app.use(helmet());
 };
 
-// @feature:start openapi, queue, observability
+// @feature:start openapi, queue
 /**
  * Lock the operator-facing surfaces behind basic auth. Every path added here is
- * something that leaks internals if left open — the API reference, the queue
- * dashboard, the metrics scrape endpoint — so a new one belongs in this list on
+ * something that leaks internals if left open — the API reference and the queue
+ * dashboard — so a new one belongs in this list on
  * the same commit that mounts it.
  */
 export const enableBasicAuth = (app: INestApplication) => {
@@ -132,8 +132,7 @@ export const enableBasicAuth = (app: INestApplication) => {
 		[
 			'/docs', // @feature openapi
 			'/openapi-json', // @feature openapi
-			'/dashboard', // @feature queue
-			'/metrics' // @feature observability
+			'/dashboard' // @feature queue
 		],
 		expressBasicAuth({
 			users: { [user]: password },

package/templates/nest-api/files/src/common/__tests__/temporal.service.spec.ts

@@ -0,0 +1,66 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { CustomConfigService, TemporalService, temporalTls } from 'common/services';
+
+const tls = { ca: '', cert: '', key: '' };
+
+describe('TemporalService', () => {
+	let service: TemporalService;
+
+	beforeAll(async () => {
+		const module: TestingModule = await Test.createTestingModule({
+			providers: [
+				TemporalService,
+				{
+					provide: CustomConfigService,
+					useValue: {
+						temporal: {
+							address: 'localhost:7233',
+							namespace: 'acme',
+							taskQueue: 'main',
+							tls
+						}
+					}
+				}
+			]
+		}).compile();
+
+		service = module.get(TemporalService);
+	});
+
+	it('builds a client for the configured namespace without connecting', () => {
+		expect(service.client.options.namespace).toBe('acme');
+		expect(service.taskQueue).toBe('main');
+	});
+
+	it('closes cleanly even if it never connected', async () => {
+		await expect(service.onApplicationShutdown()).resolves.toBeUndefined();
+	});
+});
+
+describe('temporalTls', () => {
+	const cert = '-----BEGIN CERTIFICATE-----\\nMIIB\\n-----END CERTIFICATE-----';
+	const key = '-----BEGIN PRIVATE KEY-----\\nMIGH\\n-----END PRIVATE KEY-----';
+
+	it('is plaintext when nothing is set', () => {
+		expect(temporalTls(tls)).toBeNull();
+	});
+
+	it('builds a client certificate pair, unescaping one-line PEM', () => {
+		const result = temporalTls({ ca: cert, cert, key });
+		expect(result?.clientCertPair?.crt.toString()).toBe(
+			'-----BEGIN CERTIFICATE-----\nMIIB\n-----END CERTIFICATE-----'
+		);
+		expect(result?.clientCertPair?.key.toString()).toContain('\nMIGH\n');
+		expect(result?.serverRootCACertificate?.toString()).toContain('\nMIIB\n');
+	});
+
+	it('omits the CA when only the client pair is set (publicly trusted server)', () => {
+		const result = temporalTls({ ca: '', cert, key });
+		expect(result?.serverRootCACertificate).toBeUndefined();
+		expect(result?.clientCertPair).toBeDefined();
+	});
+
+	it('rejects a certificate without its key', () => {
+		expect(() => temporalTls({ ...tls, cert })).toThrow(/set together/);
+	});
+});

package/templates/nest-api/files/src/common/common.module.ts

@@ -2,7 +2,6 @@ import { Global, Module } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
 import { TerminusModule } from '@nestjs/terminus'; // @feature observability
 import { LoggerModule } from './modules';
-import { MetricsModule } from './modules'; // @feature observability
 // The queue module itself is generic; here it is only needed to register the
 // `mail` queue, so it rides on the mail feature.
 import { QueueModule } from './modules'; // @feature mail
@@ -16,6 +15,7 @@ import { CacheService } from './services'; // @feature cache
 import { MailService } from './services'; // @feature mail
 import { RedisThrottlerStorage } from './services'; // @feature rate-limit
 import { FeatureFlagService } from './services'; // @feature feature-flags
+import { TemporalService } from './services'; // @feature temporal
 import { HealthController } from './controllers'; // @feature observability
 import { MailProcessor } from './processors'; // @feature mail
 import { FeatureFlagGuard } from './guards'; // @feature feature-flags
@@ -37,7 +37,6 @@ import Config from './services/config.service';
 		LoggerModule,
 		// @feature:start observability
 		TerminusModule,
-		MetricsModule,
 		// @feature:end
 		QueueModule.register('mail') // @feature mail
 	],
@@ -56,6 +55,7 @@ import Config from './services/config.service';
 		RedisThrottlerStorage, // @feature rate-limit
 		FeatureFlagService, // @feature feature-flags
 		FeatureFlagGuard, // @feature feature-flags
+		TemporalService, // @feature temporal
 		PrismaHealthIndicator // @feature observability
 	],
 	exports: [
@@ -66,7 +66,8 @@ import Config from './services/config.service';
 		CacheService, // @feature cache
 		MailService, // @feature mail
 		RedisThrottlerStorage, // @feature rate-limit
-		FeatureFlagService // @feature feature-flags
+		FeatureFlagService, // @feature feature-flags
+		TemporalService // @feature temporal
 	]
 })
 export class CommonModule {}

package/templates/nest-api/files/src/common/controllers/index.ts

@@ -1,2 +1 @@
-export * from './metrics.controller'; // @feature observability
 export * from './health.controller'; // @feature observability

package/templates/nest-api/files/src/common/modules/index.ts

@@ -1,3 +1,2 @@
-export * from './metrics.module'; // @feature observability
 export * from './logger.module';
 export * from './queue.module'; // @feature queue

package/templates/nest-api/files/src/common/modules/logger.module.ts

@@ -19,10 +19,7 @@ import {
 				config: CustomConfigService,
 				gen: GeneratorService
 			) => ({
-				exclude: [
-					{ method: RequestMethod.ALL, path: 'health' },
-					{ method: RequestMethod.ALL, path: 'metrics' }
-				],
+				exclude: [{ method: RequestMethod.ALL, path: 'health' }],
 				pinoHttp: {
 					level: config.logger.level,
 					transport:
@@ -41,8 +38,7 @@ import {
 								'/dashboard',
 								'/openapi',
 								'/openapi-json',
-								'/docs',
-								'/metrics'
+								'/docs'
 							]; // Bull Board + API docs, all mounted outside Nest
 							return muted.some((p) => path === p || path.startsWith(p + '/'));
 						}

package/templates/nest-api/files/src/common/services/config.service.ts

@@ -54,7 +54,7 @@ namespace Config {
 	}
 	// @feature:end
 
-	// @feature:start openapi, queue, observability
+	// @feature:start openapi, queue
 	export interface BasicAuth {
 		user: string;
 		password: string;
@@ -114,6 +114,17 @@ namespace Config {
 	}
 	// @feature:end
 
+	// @feature:start temporal
+	export interface Temporal {
+		address: string;
+		namespace: string;
+		/** Where workflows started from here are queued (the worker polls it). */
+		taskQueue: string;
+		/** PEM; all empty means plaintext (the local dev server). */
+		tls: { ca: string; cert: string; key: string };
+	}
+	// @feature:end
+
 	export interface OAuthGoogle {
 		clientId: string;
 		clientSecret: string;
@@ -129,13 +140,14 @@ namespace Config {
 		health: Health; // @feature observability
 		database: Database;
 		redis: Redis; // @feature cache
-		basicAuth: BasicAuth; // @feature openapi, queue, observability
+		basicAuth: BasicAuth; // @feature openapi, queue
 		betterAuth: BetterAuth;
 		growthbook: Growthbook; // @feature feature-flags
 		superuser: Superuser;
 		smtp: SMTP; // @feature mail
 		s3: S3; // @feature media
 		rateLimit: RateLimit; // @feature rate-limit
+		temporal: Temporal; // @feature temporal
 		oauth: OAuth;
 	}
 
@@ -173,7 +185,7 @@ namespace Config {
 		HEALTH_DISK_THRESHOLD: num(z.number().min(0).max(1)).default(0.8),
 		HEALTH_DISK_PATH: str().default('/'),
 		// @feature:end
-		// @feature:start openapi, queue, observability
+		// @feature:start openapi, queue
 		BASIC_AUTH_USER: str(),
 		BASIC_AUTH_PASS: str(),
 		// @feature:end
@@ -207,6 +219,14 @@ namespace Config {
 		RATE_LIMIT_AUTH_MAX: num().default(100),
 		RATE_LIMIT_IP_HEADERS: str().default('x-forwarded-for'),
 		// @feature:end
+		// @feature:start temporal
+		TEMPORAL_ADDRESS: str().default('localhost:7233'),
+		TEMPORAL_NAMESPACE: str().default('default'),
+		TEMPORAL_TASK_QUEUE: str().default('main'),
+		TEMPORAL_TLS_CA: z.string().default(''),
+		TEMPORAL_TLS_CERT: z.string().default(''),
+		TEMPORAL_TLS_KEY: z.string().default(''),
+		// @feature:end
 		// @feature:start feature-flags
 		GROWTHBOOK_API_HOST: str(),
 		GROWTHBOOK_CLIENT_KEY: str()
@@ -249,7 +269,7 @@ namespace Config {
 			password: env.REDIS_PASSWORD || ''
 		},
 		// @feature:end
-		// @feature:start openapi, queue, observability
+		// @feature:start openapi, queue
 		basicAuth: {
 			user: env.BASIC_AUTH_USER || 'user',
 			password: env.BASIC_AUTH_PASS || 'password'
@@ -305,6 +325,18 @@ namespace Config {
 				.filter(Boolean)
 		},
 		// @feature:end
+		// @feature:start temporal
+		temporal: {
+			address: env.TEMPORAL_ADDRESS || 'localhost:7233',
+			namespace: env.TEMPORAL_NAMESPACE || 'default',
+			taskQueue: env.TEMPORAL_TASK_QUEUE || 'main',
+			tls: {
+				ca: env.TEMPORAL_TLS_CA || '',
+				cert: env.TEMPORAL_TLS_CERT || '',
+				key: env.TEMPORAL_TLS_KEY || ''
+			}
+		},
+		// @feature:end
 		oauth: {
 			google: {
 				clientId: env.OAUTH_GOOGLE_CLIENT_ID || '',
@@ -342,7 +374,7 @@ export class CustomConfigService {
 	}
 	// @feature:end
 
-	// @feature:start openapi, queue, observability
+	// @feature:start openapi, queue
 	get basicAuth() {
 		return this.config.get('basicAuth', { infer: true });
 	}
@@ -380,6 +412,12 @@ export class CustomConfigService {
 	}
 	// @feature:end
 
+	// @feature:start temporal
+	get temporal() {
+		return this.config.get('temporal', { infer: true });
+	}
+	// @feature:end
+
 	get oauth() {
 		return this.config.get('oauth', { infer: true });
 	}

package/templates/nest-api/files/src/common/services/index.ts

@@ -8,3 +8,4 @@ export * from './mail.service'; // @feature mail
 export * from './throttler-storage.service'; // @feature rate-limit
 export * from './auth-rate-limit.storage'; // @feature rate-limit
 export * from './feature-flag.service'; // @feature feature-flags
+export * from './temporal.service'; // @feature temporal

package/templates/nest-api/files/src/common/services/temporal.service.ts

@@ -0,0 +1,66 @@
+import { Injectable, OnApplicationShutdown } from '@nestjs/common';
+import { Client, Connection, type TLSConfig } from '@temporalio/client';
+import { CustomConfigService } from './config.service';
+import type Config from './config.service';
+
+/**
+ * A Temporal client for starting and querying workflows; a worker (node-worker
+ * or py-worker) polling the same namespace and task queue runs them.
+ *
+ * The connection is lazy: nothing is dialled until the first call, so the API
+ * boots, and serves everything else, while Temporal is unreachable.
+ *
+ * ```ts
+ * const handle = await this.temporal.client.workflow.start('example', {
+ *   taskQueue: this.temporal.taskQueue,
+ *   workflowId: `example-${user.id}`, // one run per id: a natural dedupe key
+ *   args: [{ name: user.name }]
+ * });
+ * const result = await handle.result(); // or return handle.workflowId
+ * ```
+ *
+ * Reach for Temporal over the BullMQ queue when the work spans many steps,
+ * waits (for minutes to months, or on a signal), or must resume exactly where
+ * it stopped after a crash. A fire-and-forget job is still a queue job.
+ */
+@Injectable()
+export class TemporalService implements OnApplicationShutdown {
+	readonly client: Client;
+	/** The default task queue, from TEMPORAL_TASK_QUEUE. */
+	readonly taskQueue: string;
+	private readonly connection: Connection;
+
+	constructor(config: CustomConfigService) {
+		const { address, namespace, taskQueue, tls } = config.temporal;
+		this.connection = Connection.lazy({ address, tls: temporalTls(tls) });
+		this.client = new Client({ connection: this.connection, namespace });
+		this.taskQueue = taskQueue;
+	}
+
+	async onApplicationShutdown() {
+		await this.connection.close();
+	}
+}
+
+/**
+ * mTLS settings from PEM strings; none at all means plaintext (`null`).
+ * Escaped `\n` are unescaped, so a certificate fits on one line of an env
+ * file.
+ */
+export function temporalTls({
+	ca,
+	cert,
+	key
+}: Config.Temporal['tls']): TLSConfig | null {
+	if (!ca && !cert && !key) return null;
+	if (!cert || !key) {
+		throw new Error(
+			'TEMPORAL_TLS_CERT and TEMPORAL_TLS_KEY must be set together'
+		);
+	}
+	const pem = (value: string) => Buffer.from(value.replace(/\\n/g, '\n'));
+	return {
+		...(ca && { serverRootCACertificate: pem(ca) }),
+		clientCertPair: { crt: pem(cert), key: pem(key) }
+	};
+}