@flisk-sh/flisk-export 0.4.2 → 0.6.0

package/README.md

@@ -45,9 +45,10 @@ flisk-export compose --check    # exit 1 when that file is out of date (for CI)
 ```
 
 Writes a **standalone** `docker-compose.yml` from the bring-your-own `service.json` files (`image` or `dockerfile`, `env`,
-`secrets.required`, `models`, `volumes`, `extraPorts`, `dependsOn`, `healthCheck`, `sidecarOf`, `container`). It runs without Flisk (`docker compose --env-file .env -f .autogenerated/docker-compose.yml up -d` from the project root, since Compose looks for `.env` next to the file it reads): no external
+`secrets.required`, `envFile`, `profiles`, `models`, `volumes`, `extraPorts`, `dependsOn`, `healthCheck`, `sidecarOf`, `container`). It runs without Flisk (`docker compose --env-file .env -f .autogenerated/docker-compose.yml up -d` from the project root, since Compose looks for `.env` next to the file it reads): no external
 networks, no `FLISK_*` variables, no generated secrets. `${VAR}` references in `env`, and every name in `secrets.required`, pass through as `${NAME}` for Compose to read from `.env`.
 A volume's `name` (the Docker volume an install already has) is kept, and the project is named after its stack, so `docker compose up` finds the same data as before.
+An `image` with Compose variables (`postgres:${POSTGRES_VERSION:-18}-alpine`) is written as it is, for Compose to resolve; `restart: "on-failure:N"` keeps N. From `container`: `stopGracePeriod` becomes `stop_grace_period`, `networkAliases` become `networks: { default: { aliases } }` (not on a `sidecarOf` service, which has no network of its own), `extraHosts` become `extra_hosts` and `ulimits` stay `ulimits`. Each value is checked so it cannot add YAML keys; one that does not fit is an error.
 `healthCheck.command` becomes a Compose `healthcheck`; a service that lists a checked service in `dependsOn` waits for `service_healthy`, and one that lists a `restart: "no"` job waits for `service_completed_successfully`.
 Other resource types and `command` (native) services are not exported. The file is generated: change `service.json` and run it
 again with `--force`. It never starts a container or calls an API.

package/dist/compose.js

@@ -7,14 +7,29 @@
  */
 import { relative, sep } from "node:path";
 import { ExportError } from "./errors.js";
-/** extraPorts `publish`: digits, dots, colons and `${NAME:-default}`, as flisk core accepts it (flisk#2947). */
-const PUBLISH = /^(?:[0-9.:]|\$\{[A-Za-z_][A-Za-z0-9_]*:-[0-9.:]+\})+$/;
+/** extraPorts `publish`: digits, dots, colons and `${NAME:-default}` / `${NAME-default}`, as flisk core accepts it (flisk#2947). */
+const PUBLISH = /^(?:[0-9.:]|\$\{[A-Za-z_][A-Za-z0-9_]*:?-[0-9.:]+\})+$/;
+/** An image reference, with Compose variables `${NAME}`, `${NAME:-default}` and `${NAME-default}` kept for Compose to resolve. */
+const IMAGE = /^(?:[A-Za-z0-9._/:@-]|\$\{[A-Za-z_][A-Za-z0-9_]*(?::?-[A-Za-z0-9._/:@-]*)?\})+$/;
 /** The only resource type the Compose export covers: it is the one whose service.json is a Compose service. */
 export const COMPOSE_TYPE = "bring-your-own";
 const RESTART_POLICIES = new Set(["no", "on-failure", "unless-stopped", "always"]);
+/** `on-failure:N` with a retry limit from 1 to 100. */
+const RESTART_LIMIT = /^on-failure:([1-9][0-9]?|100)$/;
+/** A Compose duration such as 30s, 1m30s or 500ms. */
+const DURATION = /^(?:[0-9]+(?:\.[0-9]+)?(?:h|ms|us|m|s))+$/;
+/** A DNS name: letters, digits, '-', '_' and '.'. */
+const DNS_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,252}$/;
+/** An extra_hosts address: host-gateway, IPv4, or IPv6 (optionally in brackets). */
+const HOST_ADDRESS = /^(?:host-gateway|[0-9]{1,3}(?:\.[0-9]{1,3}){3}|\[?[0-9A-Fa-f.]*:[0-9A-Fa-f.]*:[0-9A-Fa-f:.]*\]?)$/;
+const ULIMIT_NAME = /^[a-z]+$/;
 const SERVICE_NAME = /^[a-z0-9][a-z0-9_.-]*$/i;
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const SHM_SIZE = /^\d+(b|k|kb|m|mb|g|gb)?$/i;
+const TMPFS = /^\/[A-Za-z0-9_./-]*(:[a-z0-9=,_-]+)?$/;
+const CPUS = /^[0-9]+(\.[0-9]{1,2})?$/;
+const MEMORY = /^[0-9]+([bBkKmMgG][bB]?)?$/;
+const PROFILE = /^[a-z0-9][a-z0-9-]*$/;
 const DOCKER_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 export function isComposeExportable(resource) {
     return resource.type === COMPOSE_TYPE && typeof resource.config.command !== "string";
@@ -58,6 +73,11 @@ function serviceLines(resource, outDir, services) {
     const image = typeof c.image === "string" && c.image ? c.image : undefined;
     const dockerfile = typeof c.dockerfile === "string" && c.dockerfile ? c.dockerfile : undefined;
     const buildContext = typeof c.buildContext === "string" ? c.buildContext : undefined;
+    if (image && !IMAGE.test(image)) {
+        throw new ExportError(`${name}: image "${image}" is not an image reference`, [
+            "Use letters, digits, . _ / : @ - and Compose variables ${NAME}, ${NAME:-default} or ${NAME-default}",
+        ]);
+    }
     if (image)
         lines.push(`    image: ${q(image)}`);
     if (dockerfile || !image) {
@@ -70,7 +90,7 @@ function serviceLines(resource, outDir, services) {
     if (container.init !== false)
         lines.push("    init: true");
     if (typeof c.restart === "string") {
-        if (!RESTART_POLICIES.has(c.restart)) {
+        if (!RESTART_POLICIES.has(c.restart) && !RESTART_LIMIT.test(c.restart)) {
             throw new ExportError(`${name}: restart "${c.restart}" is not a Compose restart policy`);
         }
         lines.push(`    restart: ${q(c.restart)}`);
@@ -85,6 +105,18 @@ function serviceLines(resource, outDir, services) {
         }
         lines.push(`    network_mode: ${q(`service:${sidecarOf}`)}`);
     }
+    // Every exported service is on the default network, so its aliases go there. A sidecar has no network of its own.
+    const aliases = strings(container.networkAliases);
+    for (const alias of aliases) {
+        if (!DNS_NAME.test(alias)) {
+            throw new ExportError(`${name}: network alias "${alias}" is not a DNS name`, [
+                "Use letters, digits, '-', '_' and '.'",
+            ]);
+        }
+    }
+    if (aliases.length > 0 && !sidecarOf) {
+        lines.push("    networks:", "      default:", "        aliases:", ...aliases.map((a) => `          - ${q(a)}`));
+    }
     const env = record(c.env);
     // Secrets are listed by name only in service.json; Compose reads their values from the project .env.
     const values = new Map();
@@ -192,6 +224,77 @@ function serviceLines(resource, outDir, services) {
         }
         lines.push(`    shm_size: ${q(container.shmSize)}`);
     }
+    if (container.stopGracePeriod !== undefined) {
+        const period = container.stopGracePeriod;
+        if (typeof period !== "string" || !DURATION.test(period)) {
+            throw new ExportError(`${name}: stopGracePeriod ${JSON.stringify(period)} is not a duration such as 30s or 1m30s`);
+        }
+        lines.push(`    stop_grace_period: ${q(period)}`);
+    }
+    const extraHosts = strings(container.extraHosts);
+    for (const host of extraHosts) {
+        const at = host.indexOf(":");
+        if (at < 1 || !DNS_NAME.test(host.slice(0, at)) || !HOST_ADDRESS.test(host.slice(at + 1))) {
+            throw new ExportError(`${name}: extraHosts "${host}" is not name:address (an IP or host-gateway)`);
+        }
+    }
+    if (extraHosts.length > 0)
+        lines.push("    extra_hosts:", ...extraHosts.map((h) => `      - ${q(h)}`));
+    const ulimits = Object.entries(record(container.ulimits));
+    if (ulimits.length > 0) {
+        lines.push("    ulimits:");
+        for (const [limit, value] of ulimits) {
+            const pair = record(value);
+            if (!ULIMIT_NAME.test(limit)) {
+                throw new ExportError(`${name}: ulimit "${limit}" is not a ulimit name`);
+            }
+            if (typeof value === "number" && Number.isInteger(value)) {
+                lines.push(`      ${limit}: ${value}`);
+            }
+            else if (Number.isInteger(pair.soft) && Number.isInteger(pair.hard)) {
+                lines.push(`      ${limit}:`, `        soft: ${pair.soft}`, `        hard: ${pair.hard}`);
+            }
+            else {
+                throw new ExportError(`${name}: ulimit "${limit}" must be a whole number or { soft, hard } whole numbers`);
+            }
+        }
+    }
+    const tmpfs = strings(container.tmpfs);
+    if (tmpfs.length > 0) {
+        for (const t of tmpfs) {
+            if (!TMPFS.test(t))
+                throw new ExportError(`${name}: tmpfs "${t}" is not /path or /path:options`);
+        }
+        lines.push("    tmpfs:", ...tmpfs.map((t) => `      - ${q(t)}`));
+    }
+    const cpus = container.cpus === undefined ? undefined : String(container.cpus);
+    const memory = typeof container.memory === "string" ? container.memory : undefined;
+    if (cpus !== undefined && !CPUS.test(cpus))
+        throw new ExportError(`${name}: cpus "${cpus}" is not a number of CPUs`);
+    if (memory !== undefined && !MEMORY.test(memory))
+        throw new ExportError(`${name}: memory "${memory}" is not a size such as 2g`);
+    if (cpus !== undefined || memory !== undefined) {
+        lines.push("    deploy:", "      resources:", "        limits:", ...(cpus !== undefined ? [`          cpus: ${q(cpus)}`] : []), ...(memory !== undefined ? [`          memory: ${q(memory)}`] : []));
+    }
+    // Paths in envFile are relative to the service directory; a missing file is skipped, as Flisk does.
+    const envFiles = strings(c.envFile);
+    if (envFiles.length > 0) {
+        lines.push("    env_file:");
+        for (const file of envFiles) {
+            if (!/^[A-Za-z0-9_.-]+(\/[A-Za-z0-9_.-]+)*$/.test(file)) {
+                throw new ExportError(`${name}: envFile "${file}" is not a relative path`);
+            }
+            lines.push(`      - path: ${q(hostPath(outDir, resolveFrom(resource.path, file)))}`, "        required: false");
+        }
+    }
+    const profiles = strings(c.profiles);
+    if (profiles.length > 0) {
+        for (const p of profiles) {
+            if (!PROFILE.test(p))
+                throw new ExportError(`${name}: profile "${p}" is not a profile name`);
+        }
+        lines.push("    profiles:", ...profiles.map((p) => `      - ${q(p)}`));
+    }
     return { lines, namedVolumes, models };
 }
 /** What Compose waits for before starting a dependent: a passing check, a finished one-shot job, or the start. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flisk-sh/flisk-export",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Write a Render Blueprint (render.yaml), a Cloudflare wrangler.toml or a standalone docker-compose.yml from Flisk service.json files. Never deploys.",
   "type": "module",
   "license": "MIT",