@emmett-community/emmett-google-services-bootstrap 0.3.0 → 0.5.0

package/README.md

@@ -87,6 +87,7 @@ await bootstrap.startApi({
 - `FIREBASE_DATABASE_EMULATOR_HOST`: Realtime DB emulator host
 - `PUBSUB_PROJECT_ID`: PubSub project id
 - `PUBSUB_EMULATOR_HOST`: PubSub emulator host
+- `PUBSUB_TOPIC_PREFIX`: prefix of topics and subscriptions (used when `pubsub.topicPrefix` is not set; defaults to the service name)
 - `LOG_LEVEL`: default log level for built-in logger
 - `NODE_ENV`: forwarded to logging helpers
 
@@ -104,6 +105,7 @@ const config: ServiceBootstrapConfig = {
   pubsub: {
     projectId: 'demo-project',
     topicPrefix: 'user-service',
+    subscriptionId: 'user-service',
     autoCreateResources: true,
   },
   eventStore: {
@@ -118,16 +120,30 @@ const config: ServiceBootstrapConfig = {
     logLevel: 'info',
   },
   includeDefaultDependencyChecks: true,
+  includeRealtimeDatabaseCheck: true,
   autoStartMessageBus: true,
   shutdownOnDependencyFailure: true,
 };
 ```
 
+### Subscriptions
+
+Event and command subscriptions are named after the service, so they survive restarts and the replicas of a service share them:
+
+- Events: `<topicPrefix>-evt-<EventType>-<subscriptionId>`. An event normally reaches one replica, but it can be delivered again, so handlers must be idempotent.
+- Commands: `<topicPrefix>-cmd-<CommandType>-<subscriptionId>`, so a command has one handler.
+
+`pubsub.subscriptionId` defaults to the service name. `includeRealtimeDatabaseCheck: false` leaves the Realtime Database out of the default dependency checks, for services that do not use it.
+
 ### Event store collection names
 
 - `eventStore.collections.streams`: Firestore collection that stores stream metadata (defaults to `"streams"`).
 - `eventStore.collections.counters`: Firestore collection for shared counters (defaults to `"_counters"`).
 
+### Event store hooks
+
+`eventStore.hooks` is passed as is to the Firestore event store. `hooks.beforeCommit(transaction, events)` runs inside the transaction of every append, so what it writes on the transaction commits atomically with the events. See the readme of `@emmett-community/emmett-google-firestore` for the rules of the hook. `ctx.eventStore.appendToStream` returns `messageIds`, the `messageId` stored on each event.
+
 ## API
 
 ### ServiceBootstrap
@@ -138,13 +154,45 @@ const config: ServiceBootstrapConfig = {
 - `shutdown(reason, exitCode?)` runs graceful shutdown tasks.
 - `registerSignalHandlers()` installs SIGINT/SIGTERM handlers.
 - `startApi()` initializes, runs checks, creates the app, and starts the HTTP server.
+- `checkReadiness()` runs the readiness checks (also available as `ctx.checkReadiness`).
+
+`ctx.eventStore` follows Emmett's `EventStore` contract: `readStream` returns `{ events, currentStreamVersion, streamExists }`.
+
+### Health and readiness
+
+The probes are routes of the service contract. Declare `GET /health` and `GET /ready` in the OpenAPI document and wire them to the handlers of the package:
+
+```typescript
+// handlers/health.ts: the module of x-eov-operation-handler: health
+import type { NextFunction, Request, Response } from 'express';
+import {
+  getHealth as health,
+  getReady as ready,
+  type ServiceBootstrapContext,
+} from '@emmett-community/emmett-google-services-bootstrap';
+
+let readyHandler: ReturnType<typeof ready>;
+
+// Called from the initializeHandlers option of startApi()/createApp()
+export const initializeHandlers = (ctx: ServiceBootstrapContext) => {
+  readyHandler = ready(ctx);
+};
+
+export const getHealth = health;
+export const getReady = (req: Request, res: Response, next: NextFunction) =>
+  readyHandler(req, res, next);
+```
+
+`/health` answers `200 { "status": "ok" }`. `/ready` answers `200 { "status": "ready", "checks": [...] }` when Firestore, the Realtime Database (unless `includeRealtimeDatabaseCheck` is `false`), the message bus and the configured `dependencies` answer, and `503 { "status": "unavailable", "checks": [...] }` otherwise. Each check has a 3 s timeout.
 
 ### Lifecycle utilities
 
 - `DependencyChecker` and `startDependency()` for health checks.
-- `GracefulShutdown` for ordered shutdown tasks.
+- `GracefulShutdown` for ordered shutdown tasks (`registerFirst()` adds a task that runs before the others).
 - `registerSignalHandlers()` to attach process signals.
 
+`startApi()` closes the HTTP server first, then the message bus, Firestore and the Firebase app.
+
 ## What this package intentionally does NOT do
 
 - Hide application infrastructure choices behind magic defaults
@@ -154,6 +202,35 @@ const config: ServiceBootstrapConfig = {
 
 ## Testing
 
+`@emmett-community/emmett-google-services-bootstrap/testing` builds a service bootstrap on the in-memory Firestore, Realtime Database and Pub/Sub of the `/testing` entries of the platform libraries, with no emulator and no network. The event store, the projections and the message bus are the real ones:
+
+```typescript
+import { createTestServiceBootstrap } from '@emmett-community/emmett-google-services-bootstrap/testing';
+
+const { bootstrap, firestore, database, messageBus } = createTestServiceBootstrap({
+  serviceName: 'user-service',
+  projections: [userDetailsProjection],
+});
+
+const ctx = await bootstrap.start();
+```
+
+Use `overrides` to replace any piece, for example to share one `pubsub` between two services.
+
+For API tests, use `ApiSpecification` and `ApiE2ESpecification` from `@event-driven-io/emmett-expressjs` (install it in `devDependencies`, with the same version as `@event-driven-io/emmett`). They take the application right away, so wrap the one built by `createApp()` with `lazyApplication`, which this package re-exports:
+
+```typescript
+import { ApiSpecification, expectResponse } from '@event-driven-io/emmett-expressjs';
+import { lazyApplication } from '@emmett-community/emmett-google-services-bootstrap';
+
+const given = ApiSpecification.for(
+  () => getInMemoryEventStore(),
+  (eventStore) => lazyApplication(createTestApp(eventStore)),
+);
+```
+
+To test this package:
+
 ```bash
 npm run test:unit
 npm run test:int

package/dist/ServiceBootstrap-BjFoQDd_.d.cts

@@ -0,0 +1,338 @@
+import { Application } from 'express';
+import { ImportedHandlerModules, OpenApiValidatorOptions, ApplicationOptions, startAPI } from '@emmett-community/emmett-expressjs-with-openapi';
+import { MessageBus, EventSubscription, CommandProcessor, ScheduledMessageProcessor, EventStore } from '@event-driven-io/emmett';
+import { Firestore } from '@google-cloud/firestore';
+import { PubSub } from '@google-cloud/pubsub';
+import { Auth } from 'firebase-admin/auth';
+import { app } from 'firebase-admin';
+import { Database } from 'firebase-admin/database';
+import { PubSubMessageBusLifecycle, SubscriptionOptions } from '@emmett-community/emmett-google-pubsub';
+import { RealtimeDBInlineProjectionDefinition } from '@emmett-community/emmett-google-realtime-db';
+import { FirestoreEventStoreOptions } from '@emmett-community/emmett-google-firestore';
+
+type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent';
+/**
+ * Canonical logger contract used across Emmett packages.
+ * Matches Pino style (context, message).
+ */
+interface Logger {
+    debug(context: Record<string, unknown>, message?: string): void;
+    info(context: Record<string, unknown>, message?: string): void;
+    warn(context: Record<string, unknown>, message?: string): void;
+    error(context: Record<string, unknown>, message?: string): void;
+}
+type ObservabilityConfig = {
+    logger?: Logger;
+    logLevel?: LogLevel;
+    environment?: string;
+    createLogger?: boolean;
+};
+type FirebaseConfig = {
+    projectId?: string;
+    databaseURL?: string;
+    firestoreEmulatorHost?: string;
+    databaseEmulatorHost?: string;
+};
+type PubSubConfig = {
+    projectId?: string;
+    emulatorHost?: string;
+    /** Prefix of topics and subscriptions. Defaults to `PUBSUB_TOPIC_PREFIX`, then the service name. */
+    topicPrefix?: string;
+    /**
+     * Stable id of this service's subscriptions, shared by its replicas and kept across restarts.
+     * Defaults to the service name.
+     */
+    subscriptionId?: string;
+    subscriptionOptions?: SubscriptionOptions;
+    autoCreateResources?: boolean;
+    cleanupOnClose?: boolean;
+    closePubSubClient?: boolean;
+};
+type DependencyCheck = {
+    name: string;
+    check: () => Promise<void>;
+    successMessage?: string;
+    timeoutMs?: number;
+    required?: boolean;
+};
+type GracefulShutdownConfig = {
+    timeoutMs?: number;
+    exitOnComplete?: boolean;
+    exitFn?: (code: number) => void;
+};
+type MessageBusWithLifecycle = MessageBus & EventSubscription & CommandProcessor & ScheduledMessageProcessor & PubSubMessageBusLifecycle;
+interface FirebaseAdminLike {
+    initializeApp(options: {
+        projectId: string;
+        databaseURL?: string;
+    }, name?: string): app.App;
+    app?: () => app.App;
+    apps?: Array<app.App | null>;
+}
+type ServiceBootstrapOverrides = {
+    firebaseAdmin?: FirebaseAdminLike;
+    firestore?: Firestore;
+    database?: Database;
+    auth?: Auth;
+    pubsub?: PubSub;
+    eventStore?: EventStore;
+    messageBus?: MessageBusWithLifecycle;
+};
+/**
+ * Main configuration for ServiceBootstrap.
+ * Values can be provided explicitly or via environment variables.
+ */
+type ServiceBootstrapConfig = {
+    serviceName: string;
+    firebase?: FirebaseConfig;
+    pubsub?: PubSubConfig;
+    eventStore?: {
+        collections?: FirestoreEventStoreOptions['collections'];
+        hooks?: FirestoreEventStoreOptions['hooks'];
+    };
+    observability?: ObservabilityConfig;
+    projections?: RealtimeDBInlineProjectionDefinition[];
+    getCurrentTime?: () => Date;
+    dependencies?: DependencyCheck[];
+    includeDefaultDependencyChecks?: boolean;
+    /** Check the Realtime Database with the default checks. Set to `false` for services that do not use it. */
+    includeRealtimeDatabaseCheck?: boolean;
+    autoStartMessageBus?: boolean;
+    shutdownOnDependencyFailure?: boolean;
+    shutdown?: GracefulShutdownConfig;
+    _testOverrides?: ServiceBootstrapOverrides;
+};
+type ResolvedFirebaseConfig = {
+    projectId: string;
+    databaseURL: string;
+    firestoreEmulatorHost?: string;
+    databaseEmulatorHost?: string;
+};
+type ResolvedPubSubConfig = {
+    projectId: string;
+    emulatorHost?: string;
+    topicPrefix: string;
+    subscriptionId: string;
+    subscriptionOptions?: SubscriptionOptions;
+    autoCreateResources: boolean;
+    cleanupOnClose: boolean;
+    closePubSubClient: boolean;
+};
+type ResolvedServiceBootstrapConfig = {
+    serviceName: string;
+    firebase: ResolvedFirebaseConfig;
+    pubsub: ResolvedPubSubConfig;
+    eventStore: {
+        collections?: FirestoreEventStoreOptions['collections'];
+        hooks?: FirestoreEventStoreOptions['hooks'];
+    };
+    observability: ObservabilityConfig;
+    projections: RealtimeDBInlineProjectionDefinition[];
+    getCurrentTime: () => Date;
+    dependencies: DependencyCheck[];
+    includeDefaultDependencyChecks: boolean;
+    includeRealtimeDatabaseCheck: boolean;
+    autoStartMessageBus: boolean;
+    shutdownOnDependencyFailure: boolean;
+    shutdown: GracefulShutdownConfig;
+    _testOverrides?: ServiceBootstrapOverrides;
+};
+
+declare class DependencyTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+type DependencyCheckResult = {
+    name: string;
+    ok: boolean;
+    required: boolean;
+    durationMs: number;
+    timedOut: boolean;
+    error?: unknown;
+};
+type DependencyCheckSummary = {
+    ok: boolean;
+    results: DependencyCheckResult[];
+};
+/**
+ * Helper for one-off dependency checks with optional logging.
+ */
+declare const startDependency: (dependency: string, startFn: () => Promise<void>, options?: {
+    logger?: Logger;
+    successMessage?: string;
+    timeoutMs?: number;
+}) => Promise<boolean>;
+/**
+ * Executes dependency checks with optional timeouts.
+ */
+declare class DependencyChecker {
+    private readonly logger?;
+    private readonly defaultTimeoutMs?;
+    constructor(options?: {
+        logger?: Logger;
+        defaultTimeoutMs?: number;
+    });
+    check(dependency: DependencyCheck): Promise<DependencyCheckResult>;
+    checkAll(dependencies: DependencyCheck[]): Promise<DependencyCheckSummary>;
+}
+
+declare class ShutdownTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+type ShutdownTask = {
+    name: string;
+    close: () => Promise<void>;
+    timeoutMs?: number;
+};
+type ShutdownTaskResult = {
+    name: string;
+    ok: boolean;
+    timedOut: boolean;
+    durationMs: number;
+    error?: unknown;
+};
+type GracefulShutdownResult = {
+    reason: string;
+    exitCode: number;
+    tasks: ShutdownTaskResult[];
+};
+/**
+ * Runs shutdown tasks with timeout handling and optional exit.
+ */
+declare class GracefulShutdown {
+    private readonly logger?;
+    private readonly timeoutMs?;
+    private readonly exitOnComplete;
+    private readonly exitFn;
+    private readonly tasks;
+    private shuttingDown;
+    private lastResult?;
+    constructor(options?: GracefulShutdownConfig & {
+        logger?: Logger;
+    });
+    /**
+     * Register a shutdown task.
+     */
+    register(task: ShutdownTask): void;
+    /**
+     * Register a shutdown task that runs before the ones already registered.
+     */
+    registerFirst(task: ShutdownTask): void;
+    /**
+     * Execute all shutdown tasks and return the aggregated result.
+     */
+    shutdown(reason: string, exitCode?: number): Promise<GracefulShutdownResult>;
+}
+
+/**
+ * Runtime context produced by ServiceBootstrap.
+ */
+type ServiceBootstrapContext = {
+    serviceName: string;
+    firebase: {
+        app: app.App;
+        firestore: Firestore;
+        database: Database;
+        auth: Auth;
+    };
+    firestore: Firestore;
+    database: Database;
+    auth: Auth;
+    pubsub: PubSub;
+    eventStore: EventStore;
+    messageBus: MessageBusWithLifecycle;
+    logger?: Logger;
+    getCurrentTime: () => Date;
+    config: ResolvedServiceBootstrapConfig;
+    /**
+     * Runs the readiness checks (the same dependencies the startup checks, without starting the
+     * message bus again). Used by the `/ready` handler.
+     */
+    checkReadiness: () => Promise<DependencyCheckSummary>;
+};
+/**
+ * Error thrown when required dependencies fail health checks.
+ */
+declare class DependencyUnavailableError extends Error {
+    readonly summary: DependencyCheckSummary;
+    constructor(summary: DependencyCheckSummary);
+}
+type CreateAppOptions = {
+    openApiPath: string;
+    handlersPath: string;
+    initializeHandlers: (handlers?: ImportedHandlerModules) => void | Promise<void>;
+    openApiOptions?: Partial<Omit<OpenApiValidatorOptions, 'apiSpec' | 'operationHandlers' | 'initializeHandlers'>>;
+    appOptions?: Omit<ApplicationOptions, 'openApiValidator' | 'observability'>;
+};
+type StartApiOptions = Omit<CreateAppOptions, 'initializeHandlers'> & {
+    initializeHandlers: (handlers: ImportedHandlerModules | undefined, ctx: ServiceBootstrapContext) => void | Promise<void>;
+    port?: number;
+    registerSignalHandlers?: boolean;
+    beforeStart?: (ctx: ServiceBootstrapContext) => void | Promise<void>;
+};
+/**
+ * Orchestrates Firebase, PubSub, event store, and lifecycle utilities.
+ */
+declare class ServiceBootstrap {
+    private readonly config;
+    private resolvedConfig?;
+    private logger?;
+    private context?;
+    private dependencyChecker?;
+    private shutdownManager?;
+    constructor(config: ServiceBootstrapConfig);
+    /**
+     * Resolve configuration with defaults and environment variables.
+     */
+    getConfig(): ResolvedServiceBootstrapConfig;
+    /**
+     * Return the initialized context if available.
+     */
+    getContext(): ServiceBootstrapContext | undefined;
+    /**
+     * Register process signal handlers that trigger shutdown.
+     */
+    registerSignalHandlers(options?: {
+        signals?: NodeJS.Signals[];
+        exitCode?: number;
+    }): () => void;
+    /**
+     * Create an Express app using emmett-expressjs-with-openapi defaults.
+     */
+    createApp(options: CreateAppOptions): Promise<Application>;
+    /**
+     * Initialize, run dependency checks, create the app, and start the HTTP server.
+     */
+    startApi(options: StartApiOptions): Promise<{
+        app: Application;
+        server: ReturnType<typeof startAPI>;
+        context: ServiceBootstrapContext;
+    }>;
+    /**
+     * Initialize Firebase, PubSub, and event store wiring.
+     * Does not execute dependency checks.
+     */
+    initialize(): Promise<ServiceBootstrapContext>;
+    /**
+     * Initialize and run dependency checks before returning context.
+     */
+    start(): Promise<ServiceBootstrapContext>;
+    /**
+     * Run the readiness checks: the stores and the message bus must answer, plus the configured
+     * dependencies. A hung dependency fails the check instead of hanging the probe.
+     */
+    checkReadiness(): Promise<DependencyCheckSummary>;
+    /**
+     * Execute graceful shutdown tasks and return the shutdown result.
+     */
+    shutdown(reason: string, exitCode?: number): Promise<GracefulShutdownResult>;
+    private getLogger;
+    private resolveConfig;
+    private getDatabaseURL;
+    private getDependencyChecker;
+    private getShutdownManager;
+    private registerDefaultShutdownTasks;
+    private buildDefaultDependencyChecks;
+    private buildStoreDependencyChecks;
+}
+
+export { type CreateAppOptions as C, DependencyUnavailableError as D, type FirebaseAdminLike as F, type GracefulShutdownConfig as G, type Logger as L, type MessageBusWithLifecycle as M, type ObservabilityConfig as O, type PubSubConfig as P, type ResolvedFirebaseConfig as R, type ServiceBootstrapContext as S, type StartApiOptions as a, ServiceBootstrap as b, type LogLevel as c, type FirebaseConfig as d, type DependencyCheck as e, type ServiceBootstrapOverrides as f, type ServiceBootstrapConfig as g, type ResolvedPubSubConfig as h, type ResolvedServiceBootstrapConfig as i, DependencyTimeoutError as j, type DependencyCheckResult as k, type DependencyCheckSummary as l, DependencyChecker as m, ShutdownTimeoutError as n, type ShutdownTask as o, type ShutdownTaskResult as p, type GracefulShutdownResult as q, GracefulShutdown as r, startDependency as s };