@aurostack/stacks 0.1.1 → 0.2.0

package/templates/node-worker/files/src/instrumentation.ts

@@ -0,0 +1,110 @@
+/**
+ * Preloaded with `node --import` ahead of the worker (see the start scripts,
+ * ecosystem.config.cjs and the Dockerfile), for anything that has to run before
+ * the worker's own modules load.
+ */
+// @feature:start telemetry
+// OpenTelemetry: traces, logs and metrics over OTLP. It has to be preloaded
+// because ESM links the whole import graph before running any of it, so
+// patching modules from inside src/index.ts would be too late. Connection
+// settings are in src/telemetry/config.ts; without them this does nothing.
+import fs from 'node:fs';
+import path from 'node:path';
+import { register } from 'node:module';
+import { resolveTelemetry } from '#app/telemetry/config.js';
+
+// config.ts loads .env later; the connection settings are needed now.
+// Already-set variables are never overridden.
+try {
+	process.loadEnvFile();
+} catch {
+	// no .env — the environment is configured some other way
+}
+
+const telemetry = resolveTelemetry();
+
+if (telemetry.enabled) {
+	register('import-in-the-middle/hook.mjs', import.meta.url);
+
+	// Imported only when enabled, so a worker without telemetry never loads the SDK.
+	const [
+		{ NodeSDK },
+		{ getNodeAutoInstrumentations },
+		{ OTLPTraceExporter },
+		{ OTLPLogExporter },
+		{ OTLPMetricExporter },
+		{ BatchLogRecordProcessor },
+		{ PeriodicExportingMetricReader },
+		{ resourceFromAttributes },
+		{ ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION },
+		{ PrismaInstrumentation }
+	] = await Promise.all([
+		import('@opentelemetry/sdk-node'),
+		import('@opentelemetry/auto-instrumentations-node'),
+		import('@opentelemetry/exporter-trace-otlp-proto'),
+		import('@opentelemetry/exporter-logs-otlp-proto'),
+		import('@opentelemetry/exporter-metrics-otlp-proto'),
+		import('@opentelemetry/sdk-logs'),
+		import('@opentelemetry/sdk-metrics'),
+		import('@opentelemetry/resources'),
+		import('@opentelemetry/semantic-conventions'),
+		import('@prisma/instrumentation')
+	]);
+
+	const { urls, headers } = telemetry;
+	// Explicit URLs always come with their headers; without them the SDK reads
+	// OTEL_EXPORTER_OTLP_* itself.
+	const exporter = (url?: string) => (url && headers ? { url, headers } : {});
+
+	const sdk = new NodeSDK({
+		resource: resourceFromAttributes({
+			[ATTR_SERVICE_NAME]: telemetry.serviceName,
+			[ATTR_SERVICE_VERSION]: packageVersion(),
+			'deployment.environment.name': telemetry.environment
+		}),
+		traceExporter: new OTLPTraceExporter(exporter(urls?.traces)),
+		logRecordProcessors: [
+			new BatchLogRecordProcessor({
+				exporter: new OTLPLogExporter(exporter(urls?.logs))
+			})
+		],
+		metricReaders: [
+			new PeriodicExportingMetricReader({
+				exporter: new OTLPMetricExporter(exporter(urls?.metrics)),
+				exportIntervalMillis:
+					Number(process.env.OTEL_METRIC_EXPORT_INTERVAL) || 60_000
+			})
+		],
+		instrumentations: [
+			getNodeAutoInstrumentations({
+				// Every file read and DNS lookup as a span is noise, not signal.
+				'@opentelemetry/instrumentation-fs': { enabled: false },
+				'@opentelemetry/instrumentation-dns': { enabled: false },
+				'@opentelemetry/instrumentation-net': { enabled: false }
+			}),
+			new PrismaInstrumentation()
+		]
+	});
+	sdk.start();
+
+	// Flush what is buffered on the way out, then let the signal do what it
+	// would have done without a handler.
+	for (const signal of ['SIGTERM', 'SIGINT'] as const) {
+		process.once(signal, () => {
+			void sdk.shutdown().finally(() => process.kill(process.pid, signal));
+		});
+	}
+}
+
+function packageVersion(): string | undefined {
+	try {
+		const file = path.join(process.cwd(), 'package.json');
+		return (JSON.parse(fs.readFileSync(file, 'utf8')) as { version?: string })
+			.version;
+	} catch {
+		return undefined;
+	}
+}
+// @feature:end
+
+export {};

package/templates/node-worker/files/src/telemetry/config.ts

@@ -0,0 +1,61 @@
+/**
+ * Where telemetry goes, resolved from the environment before anything else
+ * loads (instrumentation is preloaded with `node --import`, ahead of config.ts).
+ *
+ * Two ways to connect, in order of precedence:
+ * - standard OpenTelemetry variables (OTEL_EXPORTER_OTLP_ENDPOINT and friends),
+ *   which the SDK reads itself, for any OTLP backend;
+ * - OPENOBSERVE_URL + OPENOBSERVE_ORG + OPENOBSERVE_TOKEN, from which the
+ *   OpenObserve endpoint and auth header are built.
+ * With neither, telemetry stays off and the SDK is never started.
+ */
+export interface TelemetryConfig {
+	enabled: boolean;
+	serviceName: string;
+	environment: string;
+	/** Signal URLs; undefined means the SDK resolves them from OTEL_* vars. */
+	urls?: { traces: string; logs: string; metrics: string };
+	headers?: Record<string, string>;
+}
+
+type Env = Record<string, string | undefined>;
+
+export function resolveTelemetry(
+	env: Env = process.env,
+	defaultServiceName = 'collector'
+): TelemetryConfig {
+	const serviceName = env.OTEL_SERVICE_NAME || defaultServiceName;
+	const environment = env.APP_ENV || 'development';
+	const off = { enabled: false, serviceName, environment };
+
+	if (env.OTEL_SDK_DISABLED === 'true') return off;
+	if (env.OTEL_EXPORTER_OTLP_ENDPOINT) {
+		return { enabled: true, serviceName, environment };
+	}
+
+	const {
+		OPENOBSERVE_URL: url,
+		OPENOBSERVE_ORG: org,
+		OPENOBSERVE_TOKEN: token
+	} = env;
+	if (!url || !org || !token) return off;
+
+	// OTLP/HTTP endpoints live under /api/<org>; an org ingestion token
+	// authenticates as `<org>:<token>`. Logs and traces land in the stream
+	// named here — one per service keeps an API and its workers apart.
+	const base = `${url.replace(/\/+$/, '')}/api/${org}`;
+	return {
+		enabled: true,
+		serviceName,
+		environment,
+		urls: {
+			traces: `${base}/v1/traces`,
+			logs: `${base}/v1/logs`,
+			metrics: `${base}/v1/metrics`
+		},
+		headers: {
+			Authorization: `Basic ${Buffer.from(`${org}:${token}`).toString('base64')}`,
+			'stream-name': env.OPENOBSERVE_STREAM || serviceName
+		}
+	};
+}

package/templates/node-worker/files/src/temporal/activities/index.ts

@@ -0,0 +1,14 @@
+import { Context, log } from '@temporalio/activity';
+
+/**
+ * Activities do the real work: I/O, database writes, calls to other services.
+ * Temporal retries a failed activity on its own (per the retry policy set in
+ * the workflow), so throw on failure and make each one safe to run twice.
+ */
+export async function greet(name: string): Promise<string> {
+	log.info('Greeting', { name });
+	// Stand-in for real work. The context's sleep is cancellation-aware: it
+	// rejects if the workflow cancels this activity.
+	await Context.current().sleep(100);
+	return `Hello, ${name}!`;
+}

package/templates/node-worker/files/src/temporal/worker.ts

@@ -0,0 +1,84 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+	DefaultLogger,
+	NativeConnection,
+	Runtime,
+	Worker,
+	type LogLevel,
+	type TLSConfig
+} from '@temporalio/worker';
+import config from '#app/config.js';
+import logger from '#app/logger.js';
+import * as activities from './activities/index.js';
+
+const here = fileURLToPath(import.meta.url);
+
+const PINO_LEVEL = {
+	TRACE: 'trace',
+	DEBUG: 'debug',
+	INFO: 'info',
+	WARN: 'warn',
+	ERROR: 'error'
+} as const satisfies Record<LogLevel, string>;
+
+/**
+ * Connects to Temporal and returns a worker for TEMPORAL_TASK_QUEUE, running
+ * the workflows in ./workflows and the activities in ./activities. Temporal's
+ * own logs go through pino, like everything else here.
+ */
+export async function createTemporalWorker(): Promise<Worker> {
+	Runtime.install({
+		logger: new DefaultLogger(runtimeLogLevel(), ({ level, message, meta }) =>
+			logger[PINO_LEVEL[level]](meta ?? {}, message)
+		)
+	});
+
+	const { address, namespace, taskQueue, tls } = config.temporal;
+	const connection = await NativeConnection.connect({
+		address,
+		tls: temporalTls(tls)
+	});
+
+	return Worker.create({
+		connection,
+		namespace,
+		taskQueue,
+		// Workflows run in a sandbox from their own bundle, built from this
+		// entry point when the worker starts: index.ts under tsx, index.js in dist.
+		workflowsPath: path.join(
+			path.dirname(here),
+			'workflows',
+			`index${path.extname(here)}`
+		),
+		activities
+	});
+}
+
+/**
+ * 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
+}: typeof 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) }
+	};
+}
+
+/** LOG_LEVEL as Temporal's level; pino's fatal/silent map to ERROR. */
+function runtimeLogLevel(): LogLevel {
+	const level = config.app.logLevel.toUpperCase();
+	if (level in PINO_LEVEL) return level as LogLevel;
+	return level === 'FATAL' || level === 'SILENT' ? 'ERROR' : 'INFO';
+}

package/templates/node-worker/files/src/temporal/workflows/index.ts

@@ -0,0 +1,23 @@
+import { proxyActivities, sleep } from '@temporalio/workflow';
+import type * as activities from '../activities/index.js';
+
+/**
+ * Workflows orchestrate; activities act. This code is replayed from history to
+ * rebuild state, so it must be deterministic: no I/O, no Date.now() or
+ * Math.random() of its own (the SDK makes both replay-safe), no imports that
+ * touch the network or filesystem. Anything like that belongs in an activity.
+ *
+ * Every function exported from this module is a workflow type, started by name
+ * (see the API's TemporalService).
+ */
+const { greet } = proxyActivities<typeof activities>({
+	startToCloseTimeout: '1 minute',
+	retry: { maximumAttempts: 5 }
+});
+
+export async function example(input: { name: string }): Promise<string> {
+	// A durable timer: survives worker restarts and deploys, for as long as
+	// you like ('30 days' works the same way).
+	await sleep('1 second');
+	return await greet(input.name);
+}

package/templates/node-worker/files/src/utils/worker.ts

@@ -1,4 +1,5 @@
 import { Worker, type WorkerOptions, type Processor } from 'bullmq';
+import { BullMQOtel } from 'bullmq-otel';
 import config from '#app/config.js';
 
 export const createWorker = <
@@ -19,7 +20,14 @@ export const createWorker = <
 
 	const defaultOptions = {
 		concurrency: 1,
-		autorun: false
+		autorun: false,
+		// Job spans and metrics; a no-op unless the OpenTelemetry SDK is running
+		// (see src/instrumentation.ts).
+		telemetry: new BullMQOtel({
+			tracerName: 'collector',
+			meterName: 'collector',
+			enableMetrics: true
+		})
 	};
 
 	const options = !opts

package/templates/node-worker/template.json

@@ -47,7 +47,49 @@
 			],
 			"packageJson": {
 				"dependencies": [
-					"bullmq"
+					"bullmq",
+					"bullmq-otel",
+					"ioredis"
+				]
+			}
+		},
+		"temporal": {
+			"title": "Temporal worker",
+			"description": "Runs durable workflows and activities from src/temporal (an example of each included) on TEMPORAL_TASK_QUEUE, next to the BullMQ consumers. Pair with the API's temporal feature, which starts them.",
+			"files": [
+				"src/temporal/**"
+			],
+			"packageJson": {
+				"dependencies": [
+					"@temporalio/activity",
+					"@temporalio/worker",
+					"@temporalio/workflow"
+				]
+			}
+		},
+		"telemetry": {
+			"title": "OpenTelemetry → OpenObserve",
+			"description": "Traces, logs and metrics pushed over OTLP (set OPENOBSERVE_URL/ORG/TOKEN, or any OTEL_* backend). Off at runtime until connected.",
+			"default": true,
+			"files": [
+				"src/telemetry/**"
+			],
+			"packageJson": {
+				"dependencies": [
+					"@opentelemetry/api",
+					"@opentelemetry/core",
+					"@opentelemetry/sdk-node",
+					"@opentelemetry/auto-instrumentations-node",
+					"@opentelemetry/exporter-trace-otlp-proto",
+					"@opentelemetry/exporter-logs-otlp-proto",
+					"@opentelemetry/exporter-metrics-otlp-proto",
+					"@opentelemetry/sdk-logs",
+					"@opentelemetry/sdk-metrics",
+					"@opentelemetry/resources",
+					"@opentelemetry/semantic-conventions",
+					"@opentelemetry/instrumentation",
+					"import-in-the-middle",
+					"@prisma/instrumentation"
 				]
 			}
 		},

package/templates/py-worker/files/.env.example

@@ -18,3 +18,31 @@ REDIS_HOST="localhost"
 REDIS_PORT=6379
 REDIS_USER=
 REDIS_PASSWORD=""
+# @feature:start telemetry
+
+# OpenTelemetry → OpenObserve: traces, logs and metrics. Leave empty and
+# telemetry stays off. Per project: OPENOBSERVE_ORG is the organization
+# identifier, OPENOBSERVE_TOKEN its ingestion token (IAM → Ingestion Tokens).
+# 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-py"
+# @feature:end
+
+# @feature:start temporal
+# Temporal: this process also runs the workflows in temporal/. Locally, the
+# API's dev server (its compose.yml; UI on http://localhost:8233), no TLS. 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"
+# The queue this worker polls. Its own, not the Node worker's: a workflow task
+# handed to a worker that doesn't know the type fails and retries. Start
+# Python workflows on this queue.
+TEMPORAL_TASK_QUEUE="python"
+TEMPORAL_TLS_CA=""
+TEMPORAL_TLS_CERT=""
+TEMPORAL_TLS_KEY=""
+# @feature:end

package/templates/py-worker/files/config.py

@@ -30,11 +30,30 @@ class Redis:
     password: str | None
 
 
+# @feature:start temporal
+@dataclass
+class TemporalTLS:
+    # PEM; all empty means plaintext (the local dev server).
+    ca: str
+    cert: str
+    key: str
+
+
+@dataclass
+class Temporal:
+    address: str
+    namespace: str
+    task_queue: str
+    tls: TemporalTLS
+# @feature:end
+
+
 @dataclass
 class Env:
     path: ProjectPath
     db: DB
     redis: Redis
+    temporal: Temporal  # @feature temporal
 
 
 class Config:
@@ -67,7 +86,19 @@ class Config:
                     port=int(os.getenv('REDIS_PORT', 0)),
                     user=os.getenv('REDIS_USER'),
                     password=os.getenv('REDIS_PASSWORD')
-                )
+                ),
+                # @feature:start temporal
+                temporal=Temporal(
+                    address=os.getenv('TEMPORAL_ADDRESS') or 'localhost:7233',
+                    namespace=os.getenv('TEMPORAL_NAMESPACE') or 'default',
+                    task_queue=os.getenv('TEMPORAL_TASK_QUEUE') or 'python',
+                    tls=TemporalTLS(
+                        ca=os.getenv('TEMPORAL_TLS_CA', ''),
+                        cert=os.getenv('TEMPORAL_TLS_CERT', ''),
+                        key=os.getenv('TEMPORAL_TLS_KEY', '')
+                    )
+                ),
+                # @feature:end
             )
 
             cls._instance = instance

package/templates/py-worker/files/requirements.txt

@@ -4,15 +4,31 @@ certifi==2026.5.20
 charset-normalizer==3.4.7
 cuid2==2.0.1
 dotenv==0.9.9
+googleapis-common-protos==1.75.4
 greenlet==3.5.1
 idna==3.18
 msgpack==1.1.2
+nexus-rpc==1.4.0
+opentelemetry-api==1.45.0
+opentelemetry-exporter-http-transport==0.66b0
+opentelemetry-exporter-otlp-common==0.66b0
+opentelemetry-exporter-otlp-proto-common==1.45.0
+opentelemetry-exporter-otlp-proto-http==1.45.0
+opentelemetry-instrumentation==0.66b0
+opentelemetry-instrumentation-redis==0.66b0
+opentelemetry-proto==1.45.0
+opentelemetry-sdk==1.45.0
+opentelemetry-semantic-conventions==0.66b0
+protobuf==7.36.2
 psycopg2-binary==2.9.12
 python-dotenv==1.2.2
 redis==6.4.0
 requests==2.34.2
 semver==3.0.4
 SQLAlchemy==2.0.50
+temporalio==1.33.0
+types-protobuf==7.35.1.20260906
 typing_extensions==4.15.0
 urllib3==2.7.0
 websockets==16.0
+wrapt==2.5.0

package/templates/py-worker/files/temporal/activities.py

@@ -0,0 +1,13 @@
+from temporalio import activity
+
+
+@activity.defn
+async def greet(name: str) -> str:
+    """
+    Activities do the real work: I/O, database writes, calls to other
+    services. Temporal retries a failed activity on its own (per the retry
+    policy set in the workflow), so raise on failure and make each one safe to
+    run twice.
+    """
+    activity.logger.info("Greeting %s", name)
+    return f"Hello, {name}!"

package/templates/py-worker/files/temporal/workflows.py

@@ -0,0 +1,38 @@
+from dataclasses import dataclass
+from datetime import timedelta
+
+from temporalio import workflow
+from temporalio.common import RetryPolicy
+
+# Workflows run in a sandbox that re-imports modules for each run; activities
+# are only referenced here, never executed, so pass them straight through.
+with workflow.unsafe.imports_passed_through():
+    from temporal.activities import greet
+
+
+@dataclass
+class ExampleInput:
+    name: str
+
+
+@workflow.defn(name="example")
+class Example:
+    """
+    Workflows orchestrate; activities act. This code is replayed from history
+    to rebuild state, so it must be deterministic: no I/O, no datetime.now() or
+    random of its own (use workflow.now() and workflow.random()), nothing that
+    touches the network or filesystem. Anything like that belongs in an
+    activity.
+    """
+
+    @workflow.run
+    async def run(self, input: ExampleInput) -> str:
+        # A durable timer: survives worker restarts and deploys, for as long
+        # as you like (timedelta(days=30) works the same way).
+        await workflow.sleep(timedelta(seconds=1))
+        return await workflow.execute_activity(
+            greet,
+            input.name,
+            start_to_close_timeout=timedelta(minutes=1),
+            retry_policy=RetryPolicy(maximum_attempts=5),
+        )