@nu-art/build-and-install 0.401.0 → 0.401.1

package/units/implementations/firebase/Unit_FirebaseFunctionsApp.d.ts

@@ -0,0 +1,233 @@
+import { UnitPhaseImplementor } from '../../../core/types.js';
+import { FirebasePackageConfig } from '../../../config/types/index.js';
+import { StringMap } from '@nu-art/ts-common';
+import { Phase_BuildPushImage, Phase_Deploy, Phase_DeployImage, Phase_Launch } from '../../../phases/definitions/index.js';
+import { Unit_TypescriptLib, Unit_TypescriptLib_Config } from '../Unit_TypescriptLib.js';
+export declare const firebaseFunctionEmulator_ErrorStrings: string[];
+export declare const firebaseFunctionEmulator_WarningStrings: string[];
+type EnvConfig = {
+    defaultConfig?: string;
+    envConfig?: string;
+    projectId: string;
+    isLocal?: boolean;
+};
+export type FunctionTriggerType = 'http' | 'schedule' | 'eventarc';
+export type FunctionResourceConfig = {
+    cpu?: string | number;
+    memory?: string;
+    timeout?: number;
+    concurrency?: number;
+    minInstances?: number;
+    maxInstances?: number;
+};
+export type FunctionConfig = {
+    name: string;
+    trigger: FunctionTriggerType;
+    schedule?: string;
+    serviceAccountName?: string;
+    resources?: FunctionResourceConfig;
+};
+export type Unit_FirebaseFunctionsApp_Config = Unit_TypescriptLib_Config & {
+    firebaseConfig?: FirebasePackageConfig;
+    pathToFirebaseConfig: string;
+    envConfig: EnvConfig;
+    ignore?: string[];
+    debugPort: number;
+    basePort: number;
+    sslKey: string;
+    sslCert: string;
+    pathToEmulatorData: string;
+    sources?: string[];
+    functions: string[] | FunctionConfig[];
+    containerDeployment?: {
+        artifactRegistry: {
+            region: string;
+            repository: string;
+            projectId: string;
+        };
+        imageName: string;
+        dockerfile?: string;
+    };
+};
+/**
+ * Firebase Functions application unit.
+ *
+ * **Key Features**:
+ * - Extends Unit_TypescriptLib (compiles TypeScript)
+ * - Manages Firebase Functions configuration
+ * - Supports emulator with SSL and debug ports
+ * - Handles function deployment
+ *
+ * **Phases Implemented**:
+ * - `prepare()`: Sets up Firebase Functions config
+ * - `compile()`: Compiles TypeScript for functions
+ * - `launch()`: Starts Firebase Functions emulator
+ * - `deploy()`: Deploys functions to Firebase
+ *
+ * **Configuration**:
+ * - `debugPort`: Port for Node.js debugger
+ * - `basePort`: Base port for emulator
+ * - `sslKey`/`sslCert`: SSL certificates for emulator
+ * - `pathToEmulatorData`: Path for emulator data persistence
+ * - `envConfig`: Environment config (projectId, identityAccount)
+ *
+ * **Emulator**: Runs Firebase Functions emulator with log filtering and error detection.
+ */
+export declare class Unit_FirebaseFunctionsApp<C extends Unit_FirebaseFunctionsApp_Config = Unit_FirebaseFunctionsApp_Config> extends Unit_TypescriptLib<C> implements UnitPhaseImplementor<[Phase_Launch, Phase_Deploy, Phase_BuildPushImage, Phase_DeployImage]> {
+    functions: StringMap;
+    injectedMetadata: StringMap;
+    static staggerCount: number;
+    static DefaultConfig_FirebaseFunction: {
+        pathToFirebaseConfig: string;
+        debugPort: number;
+        basePort: number;
+        sslKey: string;
+        sslCert: string;
+        output: string;
+        pathToEmulatorData: string;
+    };
+    readonly emulatorLogStrings: {
+        error: string[];
+        warning: string[];
+    };
+    constructor(config: Unit_FirebaseFunctionsApp<C>['config']);
+    protected copyPackageJSONToOutput(): Promise<void>;
+    prepare(): Promise<void>;
+    resolveConfigs(): Promise<void>;
+    compile(): Promise<void>;
+    postCompile(): Promise<void>;
+    launch(): Promise<void>;
+    releaseEmulatorPorts(): Promise<void>;
+    deploy(): Promise<void>;
+    /**
+     * Builds Docker container image using Google Cloud Build and pushes it to Artifact Registry.
+     *
+     * **Process**:
+     * 1. Validates image tag is provided via CLI
+     * 2. Validates containerDeployment config exists
+     * 3. Constructs Artifact Registry image reference
+     * 4. Creates isolated staging directory with only required files (dist/, Dockerfile, .cloudbuild.yaml)
+     * 5. Builds and pushes image using Google Cloud Build from staging directory (no local Docker required)
+     *
+     * **Staging Directory Structure**:
+     * - `dist/` - Contains compiled code and package.json (copied from output)
+     * - `Dockerfile` - Container build instructions
+     * - `.cloudbuild.yaml` - Cloud Build configuration
+     *
+     * **Requirements**:
+     * - `--build-push-image <tag>` CLI flag with tag value
+     * - `containerDeployment` config in unit config
+     * - gcloud CLI installed and authenticated
+     * - Cloud Build API enabled in GCP project
+     * - No local Docker daemon required - Cloud Build handles everything
+     */
+    buildPushImage(): Promise<void>;
+    /**
+     * Discovers exported functions from the compiled dist/index.js file.
+     * Parses export statements to extract function names.
+     *
+     * @returns Array of function names found in exports
+     */
+    private discoverExportedFunctions;
+    /**
+     * Normalizes function configuration to FunctionConfig[] format.
+     * Handles both legacy format (string[]) and new format (FunctionConfig[]).
+     */
+    private normalizeFunctionConfigs;
+    /**
+     * Gets function names from configuration (for backward compatibility).
+     */
+    private getFunctionNames;
+    /**
+     * Gets function config by name.
+     */
+    private getFunctionConfig;
+    /**
+     * Validates that all configured functions exist in the compiled dist/index.js file.
+     * Throws ImplementationMissingException if any configured function is missing.
+     */
+    private validateFunctionsExist;
+    /**
+     * Deletes a single function using gcloud run services delete.
+     *
+     * @param functionName Name of the function to delete (original function name with underscores)
+     */
+    private deleteFunction;
+    /**
+     * Deletes multiple functions.
+     * Determines which functions to delete based on CLI parameters.
+     *
+     * @returns Array of function names that were deleted (or would be deleted in dry run)
+     */
+    private deleteFunctions;
+    /**
+     * Deploys container image from Artifact Registry to Firebase Functions using gcloud.
+     *
+     * **Process**:
+     * 1. Validates image tag is provided via CLI
+     * 2. Validates containerDeployment config exists
+     * 3. Validates configured functions exist in dist/index.js
+     * 4. Deletes functions if requested via CLI flags
+     * 5. Determines which functions to deploy (single or all)
+     * 6. Generates Cloud Run service YAML definitions for each function
+     * 7. Sets required environment variables (FIREBASE_CONFIG, GCLOUD_PROJECT, FUNCTION_TARGET, etc.)
+     * 8. Deploys each function using `gcloud run services replace` with YAML definition
+     * 9. Retrieves function URLs after successful deployment
+     *
+     * **Environment Variables Set**:
+     * - `FUNCTION_TARGET`: Function name to invoke
+     * - `GCLOUD_PROJECT`: Runtime project ID
+     * - `GOOGLE_CLOUD_PROJECT`: Runtime project ID (alternative)
+     * - `FIREBASE_CONFIG`: JSON string with projectId, databaseURL, storageBucket, locationId
+     * - `EVENTARC_CLOUD_EVENT_SOURCE`: Eventarc source path
+     * - `LOG_EXECUTION_ID`: Set to 'true' for execution ID logging
+     *
+     * **Function Configuration**:
+     * Functions can be configured in two formats:
+     * 1. **Legacy format** (string[]): Simple array of function names (all default to HTTP trigger)
+     * 2. **New format** (FunctionConfig[]): Array of function config objects with:
+     *    - `name`: Function name (must match exported function name)
+     *    - `trigger`: Trigger type ('http', 'schedule', or 'eventarc')
+     *    - `schedule`: Schedule expression (required for 'schedule' trigger, e.g., 'every 24 hours', '0 2 * * *')
+     *    - `resources`: Per-function resource configuration:
+     *      - `cpu`: CPU allocation (e.g., '1', '2', '4')
+     *      - `memory`: Memory allocation (e.g., '512Mi', '1Gi', '2Gi', '4Gi', '8Gi')
+     *      - `timeout`: Timeout in seconds (default: 300, max: 3600)
+     *      - `concurrency`: Container concurrency (default: 80, max: 1000)
+     *      - `minInstances`: Minimum number of instances (default: 0)
+     *      - `maxInstances`: Maximum number of instances (default: 100)
+     *
+     * **Trigger Types**:
+     * - `http`: HTTP-triggered function (deployed as Cloud Run service)
+     * - `schedule`: Scheduled function (requires `schedule` property, deployed as Cloud Run service with Cloud Scheduler)
+     * - `eventarc`: Event-triggered function (deployed as Cloud Run service with Eventarc)
+     *
+     * **Requirements**:
+     * - `--deploy-image <tag>` CLI flag with tag value
+     * - `containerDeployment` config in unit config
+     * - `functions` array in unit config (legacy or new format)
+     * - Image must already exist in Artifact Registry (built via buildPushImage)
+     * - gcloud CLI installed and authenticated
+     * - Cloud Functions API enabled in GCP project
+     * - Cloud Scheduler API enabled (for scheduled functions)
+     *
+     * **Note on Request Size Limits**:
+     * The `PayloadTooLargeError` is typically caused by Express body-parser limits, not Cloud Run limits.
+     * Configure `bodyParserLimit` in your HttpServer module config to increase the limit (default: 200kb).
+     * Cloud Run supports request bodies up to 32MB, but Express must be configured to accept them.
+     */
+    deployImage(): Promise<void>;
+    private getEnvConfig;
+    private resolveFunctionsRC;
+    private resolveProxyFile;
+    private pathToProxy;
+    private resolveConfigDir;
+    private resolveFunctionsJSON;
+    private resolveFunctionsRuntimeConfig;
+    private createAppVersionFile;
+    protected deriveDistDependencies(): StringMap;
+    private createDependenciesDir;
+    private runProxy;
+    private runEmulator;
+}
+export {};