@gigadrive/network-config 5.0.0 → 5.1.0

package/dist/define-config.d.mts

@@ -37,6 +37,14 @@ type Runtime = (typeof RUNTIME_DEFINITIONS)[number];
 
 type UpstashAWSRegion = 'us-east-1' | 'us-east-2' | 'us-west-1' | 'us-west-2' | 'eu-central-1' | 'eu-west-1' | 'eu-west-2' | 'sa-east-1' | 'ap-south-1' | 'ap-northeast-1' | 'ap-southeast-1' | 'ap-southeast-2';
 type NeonAWSRegion = 'us-east-1' | 'us-east-2' | 'us-west-2' | 'ap-southeast-1' | 'ap-southeast-2' | 'eu-central-1' | 'eu-west-2' | 'sa-east-1';
+/**
+ * Runtime tag of an entrypoint that runs a container image instead of a
+ * managed language runtime. Such an entrypoint always carries a
+ * {@link NormalizedConfigEntrypoint.container} spec.
+ */
+declare const CONTAINER_RUNTIME = "docker";
+/** Runtime tag of a container entrypoint. */
+type ContainerRuntime = typeof CONTAINER_RUNTIME;
 type NormalizedConfigRouteMethod = 'ANY' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 type NormalizedConfigRouteMatchRequirements = [] | [
     {
@@ -153,6 +161,75 @@ interface ConfigV4 extends Config {
     env?: Record<string, string>;
     /** Declares managed services to provision for the deployment environment. */
     services?: ConfigV4Services;
+    /**
+     * Container images to run, keyed by name. A container without `sidecar: true`
+     * runs as a function that routes target with `destination: container:<name>`.
+     * A sidecar runs next to every function instance and answers at `<name>:<port>`.
+     * A name is 1 to 63 lowercase letters, digits, `-` or `_`, starts with a
+     * letter (so it never reads as an IP address), and is not `localhost`.
+     *
+     * @example
+     * ```yaml
+     * containers:
+     *   web:
+     *     build: .
+     *     port: 3000
+     *   redis:
+     *     image: redis:7-alpine
+     *     sidecar: true
+     * ```
+     */
+    containers?: Record<string, ConfigV4Container> | null;
+    /**
+     * Project-relative path of a Compose file whose services are imported as
+     * `containers`. Entries in `containers` win over imported services of the
+     * same name.
+     */
+    compose?: string | null;
+}
+/** One entry of the v4 `containers` map. Exactly one of `image` and `build` is required. */
+interface ConfigV4Container {
+    /** Registry image reference, e.g. `redis:7-alpine` or `ghcr.io/acme/api:1.4`. */
+    image?: string;
+    /** Build context directory, or the full build settings, for a Dockerfile in the repository. */
+    build?: string | ConfigV4ContainerBuild;
+    /** Run next to every function instance instead of serving routes. Defaults to `false`. */
+    sidecar?: boolean;
+    /** TCP port the container listens on. Defaults to the image's first exposed port, then 8080. */
+    port?: number;
+    /** Replaces the image `ENTRYPOINT`. A string is split into words the way Compose splits it. */
+    entrypoint?: string | string[];
+    /** Replaces the image `CMD`. A string is split into words the way Compose splits it. */
+    command?: string | string[];
+    /** Environment variables baked into the container, merged over the image `ENV`. */
+    env?: Record<string, string>;
+    /** Replaces the image `WORKDIR`. Must be absolute. */
+    working_dir?: string;
+    /**
+     * Replaces the image `USER`: a name, a uid, `name:group` or `uid:gid`. A bare
+     * uid may be written as a number. Root is never used: a root image runs as a
+     * dedicated non-root user.
+     */
+    user?: string | number;
+    /** Memory in MB, a whole number from 128 to 3009. Defaults to 512 for a container function and 256 for a sidecar. */
+    memory?: number;
+    /** Maximum lifetime of one request, in seconds. Container functions only. */
+    max_duration?: number;
+    /** Stream responses. Defaults to `true`. Container functions only. */
+    streaming?: boolean;
+    /** Run on a timer, like a function `schedule`. Container functions only. */
+    schedule?: string;
+}
+/** Dockerfile build settings for a container. */
+interface ConfigV4ContainerBuild {
+    /** Project-relative build context. Defaults to `.`. */
+    context?: string;
+    /** Dockerfile path relative to the context. Defaults to `Dockerfile`. */
+    dockerfile?: string;
+    /** Build stage to stop at. */
+    target?: string;
+    /** Build arguments. */
+    args?: Record<string, string>;
 }
 interface ConfigV4Service {
 }
@@ -200,6 +277,75 @@ interface ConfigV4Services {
     postgres?: ConfigV4ServicePostgres | null;
     /** Declarative File Storage buckets for the deployment environment. */
     storage?: ConfigV4ServiceStorage;
+    /**
+     * Queues for the deployment environment, keyed by name. `null` declares a
+     * pull queue with default settings.
+     *
+     * @example
+     * ```yaml
+     * services:
+     *   queues:
+     *     emails:
+     *       consumer: /api/queues/emails
+     *       maxAttempts: 5
+     *       schedules:
+     *         daily-digest:
+     *           cron: '0 8 * * MON-FRI'
+     *           timezone: Europe/Berlin
+     *           body: { kind: digest }
+     *     jobs: null
+     * ```
+     */
+    queues?: Record<string, ConfigV4Queue | null>;
+}
+/** A duration in seconds, or a string such as `30s`, `10m`, `1.5h` or `4d`. */
+type ConfigV4QueueDuration = number | `${number}${'s' | 'm' | 'h' | 'd'}`;
+/** Settings for a declaratively provisioned queue. Omitted settings keep the platform defaults. */
+interface ConfigV4Queue {
+    /**
+     * Deployment-relative path that receives each message as a signed POST, for
+     * example `/api/queues/emails`. Omit it for a pull queue.
+     */
+    consumer?: string | null;
+    /** How long a push delivery may run, or how long a received message stays leased. Defaults to 60 seconds. */
+    visibilityTimeout?: ConfigV4QueueDuration;
+    /** How long an undelivered message is kept. Defaults to 4 days, at most 14 days. */
+    retention?: ConfigV4QueueDuration;
+    /** Deliveries per message before it moves to the dead-letter list. Defaults to 10. */
+    maxAttempts?: number;
+    /** Exponential backoff between failed deliveries. Defaults to 5 seconds up to 15 minutes. */
+    retryBackoff?: {
+        min?: ConfigV4QueueDuration;
+        max?: ConfigV4QueueDuration;
+    };
+    /** How long a deduplication key is remembered. Defaults to 24 hours. */
+    deduplicationWindow?: ConfigV4QueueDuration;
+    /** Most push deliveries in flight at once. Defaults to 100. */
+    concurrency?: number | null;
+    /** Most deliveries started per period. The period defaults to one second. */
+    rateLimit?: {
+        count: number;
+        period?: ConfigV4QueueDuration;
+    } | null;
+    /** Keep messages that run out of attempts for inspection and redrive. Defaults to `true`. */
+    deadLetter?: boolean;
+    /** Cron schedules that send a message into this queue, keyed by schedule name. */
+    schedules?: Record<string, ConfigV4QueueSchedule>;
+}
+/** A recurring send into a queue. */
+interface ConfigV4QueueSchedule {
+    /** Five-field cron expression, or a macro such as `@hourly`. */
+    cron: string;
+    /** IANA time zone the expression is evaluated in. Defaults to `UTC`. */
+    timezone?: string;
+    /** Message body. Strings are sent as is; any other value is serialized as JSON. */
+    body?: unknown;
+    /** Content type of the body. Defaults to `text/plain` for a string body and `application/json` otherwise. */
+    contentType?: string;
+    /** Headers delivered with every message from this schedule. */
+    headers?: Record<string, string>;
+    /** Set to `false` to keep the schedule without sending. Defaults to `true`. */
+    enabled?: boolean;
 }
 /** Declarative File Storage configuration for one deployment environment. */
 interface ConfigV4ServiceStorage extends ConfigV4Service {
@@ -241,9 +387,17 @@ interface ConfigV4FunctionSettings {
      */
     max_duration?: number;
     /**
-     * The runtime to use for the function.
+     * The runtime to use for the function. `docker` builds the matched file as a
+     * Dockerfile, with its directory as the build context, and runs the image as
+     * the function. Routes target it by the Dockerfile's path, like any other
+     * function file.
+     */
+    runtime?: Runtime | ContainerRuntime;
+    /**
+     * TCP port the image listens on. Only for `runtime: docker`. Defaults to the
+     * image's first exposed port, then 8080.
      */
-    runtime?: Runtime;
+    port?: number;
     /**
      * Enable function response streaming. When omitted, Node and Bun runtimes stream by default.
      */

package/dist/define-config.d.ts

@@ -37,6 +37,14 @@ type Runtime = (typeof RUNTIME_DEFINITIONS)[number];
 
 type UpstashAWSRegion = 'us-east-1' | 'us-east-2' | 'us-west-1' | 'us-west-2' | 'eu-central-1' | 'eu-west-1' | 'eu-west-2' | 'sa-east-1' | 'ap-south-1' | 'ap-northeast-1' | 'ap-southeast-1' | 'ap-southeast-2';
 type NeonAWSRegion = 'us-east-1' | 'us-east-2' | 'us-west-2' | 'ap-southeast-1' | 'ap-southeast-2' | 'eu-central-1' | 'eu-west-2' | 'sa-east-1';
+/**
+ * Runtime tag of an entrypoint that runs a container image instead of a
+ * managed language runtime. Such an entrypoint always carries a
+ * {@link NormalizedConfigEntrypoint.container} spec.
+ */
+declare const CONTAINER_RUNTIME = "docker";
+/** Runtime tag of a container entrypoint. */
+type ContainerRuntime = typeof CONTAINER_RUNTIME;
 type NormalizedConfigRouteMethod = 'ANY' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
 type NormalizedConfigRouteMatchRequirements = [] | [
     {
@@ -153,6 +161,75 @@ interface ConfigV4 extends Config {
     env?: Record<string, string>;
     /** Declares managed services to provision for the deployment environment. */
     services?: ConfigV4Services;
+    /**
+     * Container images to run, keyed by name. A container without `sidecar: true`
+     * runs as a function that routes target with `destination: container:<name>`.
+     * A sidecar runs next to every function instance and answers at `<name>:<port>`.
+     * A name is 1 to 63 lowercase letters, digits, `-` or `_`, starts with a
+     * letter (so it never reads as an IP address), and is not `localhost`.
+     *
+     * @example
+     * ```yaml
+     * containers:
+     *   web:
+     *     build: .
+     *     port: 3000
+     *   redis:
+     *     image: redis:7-alpine
+     *     sidecar: true
+     * ```
+     */
+    containers?: Record<string, ConfigV4Container> | null;
+    /**
+     * Project-relative path of a Compose file whose services are imported as
+     * `containers`. Entries in `containers` win over imported services of the
+     * same name.
+     */
+    compose?: string | null;
+}
+/** One entry of the v4 `containers` map. Exactly one of `image` and `build` is required. */
+interface ConfigV4Container {
+    /** Registry image reference, e.g. `redis:7-alpine` or `ghcr.io/acme/api:1.4`. */
+    image?: string;
+    /** Build context directory, or the full build settings, for a Dockerfile in the repository. */
+    build?: string | ConfigV4ContainerBuild;
+    /** Run next to every function instance instead of serving routes. Defaults to `false`. */
+    sidecar?: boolean;
+    /** TCP port the container listens on. Defaults to the image's first exposed port, then 8080. */
+    port?: number;
+    /** Replaces the image `ENTRYPOINT`. A string is split into words the way Compose splits it. */
+    entrypoint?: string | string[];
+    /** Replaces the image `CMD`. A string is split into words the way Compose splits it. */
+    command?: string | string[];
+    /** Environment variables baked into the container, merged over the image `ENV`. */
+    env?: Record<string, string>;
+    /** Replaces the image `WORKDIR`. Must be absolute. */
+    working_dir?: string;
+    /**
+     * Replaces the image `USER`: a name, a uid, `name:group` or `uid:gid`. A bare
+     * uid may be written as a number. Root is never used: a root image runs as a
+     * dedicated non-root user.
+     */
+    user?: string | number;
+    /** Memory in MB, a whole number from 128 to 3009. Defaults to 512 for a container function and 256 for a sidecar. */
+    memory?: number;
+    /** Maximum lifetime of one request, in seconds. Container functions only. */
+    max_duration?: number;
+    /** Stream responses. Defaults to `true`. Container functions only. */
+    streaming?: boolean;
+    /** Run on a timer, like a function `schedule`. Container functions only. */
+    schedule?: string;
+}
+/** Dockerfile build settings for a container. */
+interface ConfigV4ContainerBuild {
+    /** Project-relative build context. Defaults to `.`. */
+    context?: string;
+    /** Dockerfile path relative to the context. Defaults to `Dockerfile`. */
+    dockerfile?: string;
+    /** Build stage to stop at. */
+    target?: string;
+    /** Build arguments. */
+    args?: Record<string, string>;
 }
 interface ConfigV4Service {
 }
@@ -200,6 +277,75 @@ interface ConfigV4Services {
     postgres?: ConfigV4ServicePostgres | null;
     /** Declarative File Storage buckets for the deployment environment. */
     storage?: ConfigV4ServiceStorage;
+    /**
+     * Queues for the deployment environment, keyed by name. `null` declares a
+     * pull queue with default settings.
+     *
+     * @example
+     * ```yaml
+     * services:
+     *   queues:
+     *     emails:
+     *       consumer: /api/queues/emails
+     *       maxAttempts: 5
+     *       schedules:
+     *         daily-digest:
+     *           cron: '0 8 * * MON-FRI'
+     *           timezone: Europe/Berlin
+     *           body: { kind: digest }
+     *     jobs: null
+     * ```
+     */
+    queues?: Record<string, ConfigV4Queue | null>;
+}
+/** A duration in seconds, or a string such as `30s`, `10m`, `1.5h` or `4d`. */
+type ConfigV4QueueDuration = number | `${number}${'s' | 'm' | 'h' | 'd'}`;
+/** Settings for a declaratively provisioned queue. Omitted settings keep the platform defaults. */
+interface ConfigV4Queue {
+    /**
+     * Deployment-relative path that receives each message as a signed POST, for
+     * example `/api/queues/emails`. Omit it for a pull queue.
+     */
+    consumer?: string | null;
+    /** How long a push delivery may run, or how long a received message stays leased. Defaults to 60 seconds. */
+    visibilityTimeout?: ConfigV4QueueDuration;
+    /** How long an undelivered message is kept. Defaults to 4 days, at most 14 days. */
+    retention?: ConfigV4QueueDuration;
+    /** Deliveries per message before it moves to the dead-letter list. Defaults to 10. */
+    maxAttempts?: number;
+    /** Exponential backoff between failed deliveries. Defaults to 5 seconds up to 15 minutes. */
+    retryBackoff?: {
+        min?: ConfigV4QueueDuration;
+        max?: ConfigV4QueueDuration;
+    };
+    /** How long a deduplication key is remembered. Defaults to 24 hours. */
+    deduplicationWindow?: ConfigV4QueueDuration;
+    /** Most push deliveries in flight at once. Defaults to 100. */
+    concurrency?: number | null;
+    /** Most deliveries started per period. The period defaults to one second. */
+    rateLimit?: {
+        count: number;
+        period?: ConfigV4QueueDuration;
+    } | null;
+    /** Keep messages that run out of attempts for inspection and redrive. Defaults to `true`. */
+    deadLetter?: boolean;
+    /** Cron schedules that send a message into this queue, keyed by schedule name. */
+    schedules?: Record<string, ConfigV4QueueSchedule>;
+}
+/** A recurring send into a queue. */
+interface ConfigV4QueueSchedule {
+    /** Five-field cron expression, or a macro such as `@hourly`. */
+    cron: string;
+    /** IANA time zone the expression is evaluated in. Defaults to `UTC`. */
+    timezone?: string;
+    /** Message body. Strings are sent as is; any other value is serialized as JSON. */
+    body?: unknown;
+    /** Content type of the body. Defaults to `text/plain` for a string body and `application/json` otherwise. */
+    contentType?: string;
+    /** Headers delivered with every message from this schedule. */
+    headers?: Record<string, string>;
+    /** Set to `false` to keep the schedule without sending. Defaults to `true`. */
+    enabled?: boolean;
 }
 /** Declarative File Storage configuration for one deployment environment. */
 interface ConfigV4ServiceStorage extends ConfigV4Service {
@@ -241,9 +387,17 @@ interface ConfigV4FunctionSettings {
      */
     max_duration?: number;
     /**
-     * The runtime to use for the function.
+     * The runtime to use for the function. `docker` builds the matched file as a
+     * Dockerfile, with its directory as the build context, and runs the image as
+     * the function. Routes target it by the Dockerfile's path, like any other
+     * function file.
+     */
+    runtime?: Runtime | ContainerRuntime;
+    /**
+     * TCP port the image listens on. Only for `runtime: docker`. Defaults to the
+     * image's first exposed port, then 8080.
      */
-    runtime?: Runtime;
+    port?: number;
     /**
      * Enable function response streaming. When omitted, Node and Bun runtimes stream by default.
      */