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

package/dist/ServiceBootstrap-BjFoQDd_.d.ts

@@ -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 };