@crossdelta/infrastructure 0.4.1 → 0.5.1

package/bin/generate-env.ts

@@ -59,7 +59,7 @@ const extract = {
   },
 }
 
-const LOCK_FILES = ['bun.lock', 'bun.lockb', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock']
+const LOCK_FILES = ['bun.lock', 'bun.lockb', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml']
 
 const hasLockFile = (dir: string): boolean => LOCK_FILES.some((file) => existsSync(join(dir, file)))
 

package/dist/helpers/deploy-streams.d.ts

@@ -0,0 +1,70 @@
+/**
+ * NATS JetStream Stream Materialization
+ *
+ * Generic logic for materializing NATS JetStream streams from contract metadata.
+ * Contracts define events conceptually, this module materializes them with
+ * explicit retention policies and storage configuration.
+ *
+ * Architecture:
+ * - Libraries: Contain logic (this file)
+ * - Workspaces: Provide data (contracts, policies)
+ * - Contracts: Define conceptually (stream, subjects)
+ * - Infrastructure: Materializes (retention, storage, limits)
+ */
+/**
+ * Stream configuration policy
+ * Defines retention, storage, and limits per stream
+ */
+export interface StreamPolicy {
+    /** Stream name */
+    stream: string;
+    /** Retention policy (default: 7 days) */
+    maxAge?: number;
+    /** Storage type (default: 'file') */
+    storage?: 'file' | 'memory';
+    /** Number of replicas for HA (default: 1) */
+    replicas?: number;
+    /** Max message size (default: 1MB) */
+    maxMsgSize?: number;
+}
+/**
+ * Deploy NATS JetStream streams from contracts
+ *
+ * This function:
+ * 1. Collects stream definitions from contracts
+ * 2. Validates stream definitions
+ * 3. Applies stream policies (retention, storage, limits)
+ * 4. Materializes streams via ensureJetStreams()
+ *
+ * @param contractsModule - Contracts module (e.g., import * as contracts from '@my-org/contracts')
+ * @param natsUrl - NATS connection URL
+ * @param options - Optional configuration
+ * @param options.policies - Stream-specific policy overrides
+ * @param options.defaults - Default policy for all streams
+ * @returns Promise that resolves when streams are deployed
+ *
+ * @example
+ * ```typescript
+ * import { deployStreams } from '@crossdelta/infrastructure'
+ * import * as contracts from '@my-org/contracts'
+ *
+ * // Basic usage with defaults
+ * await deployStreams(contracts, 'nats://nats.my-platform.svc.cluster.local:4222')
+ *
+ * // With custom policies
+ * await deployStreams(contracts, natsUrl, {
+ *   policies: {
+ *     ORDERS: { maxAge: 14 * 24 * 60 * 60 * 1000, replicas: 3 },
+ *     CUSTOMERS: { maxAge: 30 * 24 * 60 * 60 * 1000, replicas: 2 },
+ *   },
+ *   defaults: {
+ *     maxAge: 7 * 24 * 60 * 60 * 1000,
+ *     replicas: 1,
+ *   },
+ * })
+ * ```
+ */
+export declare const deployStreams: (contractsModule: Record<string, unknown>, natsUrl: string, options?: {
+    policies?: Record<string, Partial<StreamPolicy>>;
+    defaults?: Partial<StreamPolicy>;
+}) => Promise<void>;

package/dist/helpers/index.d.ts

@@ -1,2 +1,5 @@
+export * from './deploy-streams';
 export * from './discover-services';
 export * from './docker-hub-image';
+export * from './otel';
+export * from './streams';

package/dist/helpers/otel.d.ts

@@ -0,0 +1,42 @@
+/**
+ * OpenTelemetry Environment Variables Builder
+ *
+ * Generic helper for building OTEL environment variables for services.
+ * Works with any OTLP-compatible backend (Better Stack, Jaeger, Grafana, etc.)
+ */
+import type * as pulumi from '@pulumi/pulumi';
+export interface OtelConfig {
+    /** OTLP traces endpoint URL */
+    tracesEndpoint?: pulumi.Input<string>;
+    /** OTLP metrics endpoint URL */
+    metricsEndpoint?: pulumi.Input<string>;
+    /** OTLP headers (e.g., "Authorization=Bearer token") */
+    headers?: pulumi.Input<string>;
+    /** Deployment environment (e.g., "production", "staging") */
+    environment?: string;
+}
+/**
+ * Build OpenTelemetry environment variables for a service
+ *
+ * @param serviceName - Service name (e.g., "api-gateway")
+ * @param config - OpenTelemetry configuration
+ * @returns Environment variables for the service
+ *
+ * @example
+ * ```typescript
+ * import { buildOtelEnv } from '@crossdelta/infrastructure'
+ *
+ * const env = buildOtelEnv('my-service', {
+ *   tracesEndpoint: 'https://in-otel.betterstack.com',
+ *   headers: 'Authorization=Bearer YOUR_TOKEN',
+ *   environment: 'production',
+ * })
+ * // {
+ * //   OTEL_SERVICE_NAME: 'my-service',
+ * //   OTEL_RESOURCE_ATTRIBUTES: 'service.name=my-service,deployment.environment=production',
+ * //   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: 'https://in-otel.betterstack.com',
+ * //   OTEL_EXPORTER_OTLP_HEADERS: 'Authorization=Bearer YOUR_TOKEN',
+ * // }
+ * ```
+ */
+export declare const buildOtelEnv: (serviceName: string, config: OtelConfig) => Record<string, pulumi.Input<string>>;

package/dist/helpers/streams.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Stream Collector Utility
+ *
+ * Generic logic for discovering and collecting stream definitions from event contracts.
+ * Contracts define events conceptually, this utility extracts
+ * the channel metadata for infrastructure materialization.
+ *
+ * Architecture:
+ * - Libraries: Contain logic (this file)
+ * - Workspaces: Provide data (contracts module)
+ * - Contracts: Define semantics (type, schema, channel)
+ * - Infra: Materializes streams via Pulumi
+ *
+ * @module @crossdelta/infrastructure/lib/helpers/streams
+ */
+/**
+ * Stream definition for infrastructure materialization
+ */
+export interface StreamDefinition {
+    /** Stream name (e.g., 'ORDERS') */
+    stream: string;
+    /** Unique subjects for this stream */
+    subjects: string[];
+}
+/**
+ * Validation result for stream definitions
+ */
+export interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * Collect all stream definitions from a contracts module
+ *
+ * This function:
+ * 1. Takes a contracts module (e.g., import * as contracts from '@my-org/contracts')
+ * 2. Filters contracts with channel metadata
+ * 3. Groups by stream name
+ * 4. Collects unique subjects per stream
+ *
+ * @param contractsModule - Contracts module object (e.g., import * as contracts from '@my-org/contracts')
+ * @returns Array of stream definitions with unique subjects
+ *
+ * @example
+ * ```typescript
+ * import * as contracts from '@my-org/contracts'
+ * import { collectStreamDefinitions } from '@crossdelta/infrastructure/lib/helpers/streams'
+ *
+ * const streams = collectStreamDefinitions(contracts)
+ * // [
+ * //   { stream: 'ORDERS', subjects: ['orders.created', 'orders.updated'] },
+ * //   { stream: 'CUSTOMERS', subjects: ['customers.updated'] }
+ * // ]
+ * ```
+ */
+export declare const collectStreamDefinitions: (contractsModule: Record<string, unknown>) => StreamDefinition[];
+/**
+ * Get stream definition for a specific stream name
+ *
+ * @param contractsModule - Contracts module object
+ * @param streamName - Name of the stream (e.g., 'ORDERS')
+ * @returns Stream definition or undefined if not found
+ */
+export declare const getStreamDefinition: (contractsModule: Record<string, unknown>, streamName: string) => StreamDefinition | undefined;
+/**
+ * Get all stream names
+ *
+ * @param contractsModule - Contracts module object
+ * @returns Array of stream names
+ */
+export declare const getStreamNames: (contractsModule: Record<string, unknown>) => string[];
+/**
+ * Validate stream definitions (pure function)
+ *
+ * @param streams - Stream definitions to validate
+ * @returns Validation result with errors
+ */
+export declare const validateStreamDefinitionsPure: (streams: StreamDefinition[]) => ValidationResult;
+/**
+ * Validate stream definitions and throw on error (side effect)
+ *
+ * @param contractsModule - Contracts module object
+ * @throws Error if validation fails
+ */
+export declare const validateStreamDefinitions: (contractsModule: Record<string, unknown>) => void;