@faable/faable 1.35.0 → 1.36.0

package/dist/commands/deploy/secrets/list.js

@@ -1,6 +1,7 @@
 import { requireApi } from '../../../api/context.js';
 import { log } from '../../../log.js';
 import { resolve_app_id } from '../resolve_app_id.js';
+import { managed_name, managed_warning } from './managed_names.js';
 import { mask_value } from './mask.js';
 
 const secrets_list = {
@@ -33,12 +34,28 @@ const secrets_list = {
         const sorted = [...secrets].sort((a, b) => a.name.localeCompare(b.name));
         for (const secret of sorted) {
             const value = args.show ? secret.value : mask_value(secret.value);
-            const origin = secret.related_model === 'profile' ? '  (inherited from team profile)' : '';
-            log.info(`  ${secret.name.padEnd(width)}  ${value}${origin}`);
+            const origin = secret.related_model === 'profile'
+                ? '  (inherited from team profile)'
+                : '';
+            // Flag names the platform manages: a stored PORT looks perfectly set
+            // here while being dropped at deploy time.
+            const managed = managed_name(secret.name);
+            const note = !managed
+                ? ''
+                : managed.kind === 'reserved'
+                    ? '  ⚠️ reserved, ignored at deploy'
+                    : '  ⚠️ overrides a platform default';
+            log.info(`  ${secret.name.padEnd(width)}  ${value}${origin}${note}`);
         }
         if (!args.show) {
             log.info(`Use --show to reveal full values.`);
         }
+        // The per-row marker says WHICH; this says why, once, with the docs link.
+        for (const secret of sorted) {
+            const warning = managed_warning(secret.name);
+            if (warning)
+                log.warn(`⚠️  ${warning}`);
+        }
     }
 };
 

package/dist/commands/deploy/secrets/managed_names.js

@@ -0,0 +1,68 @@
+/**
+ * Environment variables the platform already provides.
+ *
+ * Two very different failure modes, so they are warned about differently:
+ *
+ *  - `reserved`: the controller DROPS a user secret with this name before
+ *    building the Deployment's env list (controller-deploy
+ *    src/k8s/deployment.actions.ts, RESERVED). Setting it is a silent no-op —
+ *    the platform value always wins — which is exactly the kind of thing
+ *    people spend an afternoon debugging.
+ *  - `runtime_default`: the runtime image already exports it
+ *    (buildpacks/images/runtime-{node,python}/Dockerfile). A user value DOES
+ *    win here, so it is legal — just usually redundant, and occasionally the
+ *    reason a production build behaves like a dev one.
+ *
+ * Mirrored in the dashboard (dashboard components/apps/deploy/secrets/
+ * managed_names.ts) so both surfaces say the same thing. Keep in sync.
+ */
+const DOCS_BASE = 'https://faable.com/docs/deploy/environment';
+const MANAGED_DOCS_URL = {
+    reserved: `${DOCS_BASE}#reserved-names`,
+    runtime_default: `${DOCS_BASE}#runtime-defaults`
+};
+const MANAGED_ENV_NAMES = {
+    PORT: {
+        kind: 'reserved',
+        detail: 'to 80 — the port your app must listen on'
+    },
+    FAABLE_HOST: { kind: 'reserved', detail: "to your app's public host" },
+    FAABLE_APP_ID: { kind: 'reserved', detail: 'to this app id' },
+    FAABLE_DEPLOY_ID: { kind: 'reserved', detail: "to each deployment's id" },
+    FAABLE_RELEASE: {
+        kind: 'reserved',
+        detail: 'from --release or your latest git tag'
+    },
+    FAABLE_GIT_COMMIT: {
+        kind: 'reserved',
+        detail: 'to the commit the deployment was built from'
+    },
+    FAABLE_GIT_REF: { kind: 'reserved', detail: 'to the deployed git ref' },
+    START_COMMAND: {
+        kind: 'reserved',
+        detail: "to the artifact's start command"
+    },
+    NODE_ENV: {
+        kind: 'runtime_default',
+        detail: 'to "production" on Node runtimes'
+    },
+    PYTHONUNBUFFERED: {
+        kind: 'runtime_default',
+        detail: 'to "1" on Python runtimes'
+    }
+};
+const managed_name = (name) => MANAGED_ENV_NAMES[name.trim()];
+// One line, ready for a warning log. Undefined when the name is the user's
+// own business.
+const managed_warning = (name) => {
+    const managed = managed_name(name);
+    if (!managed)
+        return undefined;
+    const key = name.trim();
+    const url = MANAGED_DOCS_URL[managed.kind];
+    return managed.kind === 'reserved'
+        ? `${key} is reserved: your value is ignored. Faable sets it ${managed.detail}. ${url}`
+        : `${key} is already set ${managed.detail}; override it only if you mean to. ${url}`;
+};
+
+export { MANAGED_DOCS_URL, MANAGED_ENV_NAMES, managed_name, managed_warning };

package/dist/commands/deploy/secrets/parse_env.js

@@ -0,0 +1,101 @@
+import { validate_pair } from './parse_pairs.js';
+
+/**
+ * Parser for `.env` files, the format every runtime already agrees on
+ * (dotenv, docker, `source`). Deliberately a strict subset:
+ *
+ *  - `#` comments and blank lines are skipped; an inline `#` only starts a
+ *    comment when it follows whitespace in an UNQUOTED value.
+ *  - a leading `export ` is tolerated, so a file meant for `source` works.
+ *  - values may be single- or double-quoted; double quotes expand `\n`, `\r`,
+ *    `\t`, `\\` and `\"`, single quotes are literal. Quoted values may span
+ *    lines, which is how PEM keys survive.
+ *  - a line that is not a comment and has no `=` is an ERROR, not a silently
+ *    ignored line: a typo must not quietly drop a variable from the deploy.
+ *
+ * Repeated names keep the last occurrence, matching `source`.
+ */
+// Closing quote for `quote`, honouring backslash escapes inside double
+// quotes. Single quotes have no escapes, so the first one closes.
+const closing_quote = (text, quote) => {
+    if (quote === "'")
+        return text.indexOf(quote);
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === '\\') {
+            i++;
+            continue;
+        }
+        if (text[i] === quote)
+            return i;
+    }
+    return -1;
+};
+const ESCAPES = {
+    n: '\n',
+    r: '\r',
+    t: '\t',
+    '\\': '\\',
+    '"': '"',
+    "'": "'"
+};
+const unescape_double = (value) => value.replace(/\\(.)/g, (match, char) => ESCAPES[char] ?? match);
+// `VALUE # comment` → `VALUE`. Requires the whitespace, so `pa#ss` (no space)
+// stays whole; a value that really needs " #" has to be quoted.
+const strip_inline_comment = (value) => value.replace(/\s+#.*$/, '');
+const preview = (line) => line.length > 40 ? `${line.slice(0, 40)}…` : line;
+const parse_env = (content, source = '.env') => {
+    // A BOM would otherwise become part of the first variable's name.
+    const lines = content.replace(/^\uFEFF/, '').split(/\r?\n/);
+    const pairs = new Map();
+    for (let i = 0; i < lines.length; i++) {
+        const line_no = i + 1;
+        const trimmed = lines[i].trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const declaration = trimmed.replace(/^export\s+/, '');
+        const eq = declaration.indexOf('=');
+        if (eq < 0) {
+            throw new Error(`${source}:${line_no}: expected KEY=VALUE, got "${preview(declaration)}".`);
+        }
+        const name = declaration.slice(0, eq).trim();
+        if (!name) {
+            throw new Error(`${source}:${line_no}: missing name before '='.`);
+        }
+        const raw = declaration.slice(eq + 1).replace(/^[ \t]*/, '');
+        const quote = raw[0] === '"' || raw[0] === "'" ? raw[0] : undefined;
+        let value;
+        if (quote) {
+            let body = raw.slice(1);
+            let end = closing_quote(body, quote);
+            // Unterminated on this line: keep pulling raw lines in until the quote
+            // closes (multi-line values), reporting the line the value STARTED on.
+            while (end < 0) {
+                i++;
+                if (i >= lines.length) {
+                    throw new Error(`${source}:${line_no}: unterminated ${quote} quote for "${name}".`);
+                }
+                body += `\n${lines[i]}`;
+                end = closing_quote(body, quote);
+            }
+            const quoted = body.slice(0, end);
+            value = quote === '"' ? unescape_double(quoted) : quoted;
+        }
+        else {
+            value = strip_inline_comment(raw).trim();
+        }
+        // Re-throw with the file position: "exceeds 255 characters" is useless
+        // when the file has eighty lines.
+        try {
+            const pair = validate_pair(name, value);
+            pairs.set(pair.name, pair.value);
+        }
+        catch (err) {
+            throw new Error(`${source}:${line_no}: ${err.message}`, {
+                cause: err
+            });
+        }
+    }
+    return [...pairs.entries()].map(([name, value]) => ({ name, value }));
+};
+
+export { parse_env };

package/dist/commands/deploy/secrets/parse_pairs.js

@@ -1,6 +1,24 @@
 // API limits for a secret (mirrors the server-side schema).
 const NAME_MAX = 255;
 const VALUE_MAX = 50000;
+// Mirror of the API's secret-name rule (api/src/deploy/secrets/SecretsManager.ts):
+// printable ASCII (0x20-0x7E) except '=' (0x3D). Checked here so a bad name
+// fails before the request instead of 400-ing the whole batch.
+const PRINTABLE_ASCII_NO_EQUALS = /^[\x20-\x3C\x3E-\x7E]+$/;
+// Shared by the KEY=VALUE arguments and the --env-file parser, so both reject
+// the same names and sizes with the same wording.
+const validate_pair = (name, value) => {
+    if (name.length > NAME_MAX) {
+        throw new Error(`Secret name "${name.slice(0, 32)}…" exceeds ${NAME_MAX} characters.`);
+    }
+    if (!PRINTABLE_ASCII_NO_EQUALS.test(name)) {
+        throw new Error(`Invalid secret name "${name}". Names must be printable ASCII and cannot contain '='.`);
+    }
+    if (value.length > VALUE_MAX) {
+        throw new Error(`Value for "${name}" exceeds ${VALUE_MAX} characters.`);
+    }
+    return { name, value };
+};
 // Split each "KEY=VALUE" on the FIRST '=' only, so values may contain '='.
 // An empty value ("KEY=") is allowed — it is a legitimate way to blank a
 // secret. Throws on the first invalid pair so callers can validate the whole
@@ -11,16 +29,8 @@ const parse_pairs = (inputs) => {
         if (idx <= 0) {
             throw new Error(`Invalid secret "${raw}". Expected KEY=VALUE (e.g. DATABASE_URL=postgres://...).`);
         }
-        const name = raw.slice(0, idx);
-        const value = raw.slice(idx + 1);
-        if (name.length > NAME_MAX) {
-            throw new Error(`Secret name "${name.slice(0, 32)}…" exceeds ${NAME_MAX} characters.`);
-        }
-        if (value.length > VALUE_MAX) {
-            throw new Error(`Value for "${name}" exceeds ${VALUE_MAX} characters.`);
-        }
-        return { name, value };
+        return validate_pair(raw.slice(0, idx), raw.slice(idx + 1));
     });
 };
 
-export { NAME_MAX, VALUE_MAX, parse_pairs };
+export { NAME_MAX, VALUE_MAX, parse_pairs, validate_pair };

package/dist/commands/deploy/secrets/set.js

@@ -1,31 +1,96 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { requireApi } from '../../../api/context.js';
 import { log } from '../../../log.js';
 import { resolve_app_id } from '../resolve_app_id.js';
+import { managed_warning } from './managed_names.js';
 import { merge_app_secrets } from './merge.js';
+import { parse_env } from './parse_env.js';
 import { parse_pairs } from './parse_pairs.js';
 
+// `--env-file` with no value means "the .env in this directory", the case
+// people actually have.
+const DEFAULT_ENV_FILE = '.env';
+const read_env_file = (raw_path) => {
+    const path = raw_path || DEFAULT_ENV_FILE;
+    let content;
+    try {
+        content = readFileSync(resolve(path), 'utf8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT') {
+            throw new Error(`No such file: ${path}`, { cause: err });
+        }
+        if (code === 'EISDIR') {
+            throw new Error(`${path} is a directory, expected a .env file.`, {
+                cause: err
+            });
+        }
+        throw err;
+    }
+    return parse_env(content, path);
+};
+// Both sources upserted into one list, arguments last so an explicit
+// KEY=VALUE on the command line overrides the same name in the file.
+const combine = (from_file, from_args) => {
+    const merged = new Map(from_file.map(p => [p.name, p.value]));
+    for (const { name, value } of from_args)
+        merged.set(name, value);
+    return [...merged.entries()].map(([name, value]) => ({ name, value }));
+};
+// One line per secret reads well for a handful; a whole .env would bury the
+// summary under eighty lines.
+const MAX_DETAILED = 10;
 const secrets_set = {
-    command: 'set <pairs...>',
-    describe: 'Set one or more secrets as KEY=VALUE',
+    command: 'set [pairs...]',
+    describe: 'Set secrets as KEY=VALUE pairs or from a .env file',
     builder: yargs => yargs
         .positional('pairs', {
         type: 'string',
         array: true,
-        demandOption: true,
         description: 'KEY=VALUE pairs (quote values containing spaces)'
     })
         .option('app', {
         alias: 'a',
         type: 'string',
         description: 'App Identifier (defaults to the linked app)'
+    })
+        .option('env-file', {
+        alias: 'f',
+        type: 'string',
+        description: 'Load variables from a .env file (defaults to ./.env)'
     })
         .example('$0 deploy secrets set API_KEY=abc123', 'Set a single secret')
         .example('$0 deploy secrets set A=1 DB_URL=postgres://u:p@host/db', 'Set several at once (values may contain "=")')
+        .example('$0 deploy secrets set --env-file', 'Upload every variable in ./.env')
+        .example('$0 deploy secrets set -f .env.production', 'Upload another env file')
         .showHelpOnFail(false),
     handler: async (args) => {
-        // Validate ALL pairs before writing ANY, so one malformed pair aborts the
-        // whole command with no partial writes.
-        const parsed = parse_pairs(args.pairs);
+        const env_file = args['env-file'];
+        const pairs = args.pairs ?? [];
+        if (env_file === undefined && pairs.length === 0) {
+            throw new Error('Nothing to set. Pass KEY=VALUE pairs or --env-file [path] to load a .env file.');
+        }
+        // Validate EVERYTHING before writing ANY, so one malformed line or pair
+        // aborts the whole command with no partial writes.
+        const from_file = env_file === undefined ? [] : read_env_file(env_file);
+        const parsed = combine(from_file, parse_pairs(pairs));
+        if (env_file !== undefined) {
+            const path = env_file || DEFAULT_ENV_FILE;
+            if (from_file.length === 0) {
+                throw new Error(`${path} has no variables to set.`);
+            }
+            log.info(`📄 Read ${from_file.length} variable(s) from ${path}`);
+        }
+        // Warn BEFORE the write: a reserved name is accepted and stored, but the
+        // controller drops it when it builds the pod — without this line the
+        // command looks like it worked.
+        for (const { name } of parsed) {
+            const warning = managed_warning(name);
+            if (warning)
+                log.warn(`⚠️  ${warning}`);
+        }
         const ctx = await requireApi();
         const app_id = await resolve_app_id(args.app, ctx.appId, ctx.api);
         // getApp also validates access to the app and provides the team the
@@ -35,10 +100,16 @@ const secrets_set = {
         const merged = merge_app_secrets(existing, parsed);
         await ctx.api.createSecretsBatch(app.id, app.team, merged);
         const current = new Set(existing.filter(s => s.related_model === 'app').map(s => s.name));
-        for (const { name } of parsed) {
-            log.info(current.has(name)
-                ? `🔑 Updated secret ${name} on ${app_id}`
-                : `🔑 Added secret ${name} to ${app_id}`);
+        const updated = parsed.filter(({ name }) => current.has(name)).length;
+        if (parsed.length <= MAX_DETAILED) {
+            for (const { name } of parsed) {
+                log.info(current.has(name)
+                    ? `🔑 Updated secret ${name} on ${app_id}`
+                    : `🔑 Added secret ${name} to ${app_id}`);
+            }
+        }
+        else {
+            log.info(`🔑 ${parsed.length - updated} added, ${updated} updated`);
         }
         log.info(`✅ ${parsed.length} secret(s) saved to ${app_id}.`);
         log.info(`ℹ️ The app is restarting to apply the changes.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/faable",
-  "version": "1.35.0",
+  "version": "1.36.0",
   "main": "dist/index.js",
   "license": "MIT",
   "author": "Marc Pomar <marc@faable.com>",