@foxtware/mineral 0.1.1 → 0.1.2

package/.gcloudignore

@@ -0,0 +1,17 @@
+# This file specifies files that are *not* uploaded to Google Cloud
+# using gcloud. It follows the same syntax as .gitignore, with the addition of
+# "#!include" directives (which insert the entries of the given .gitignore-style
+# file at that point).
+#
+# For more information, run:
+#   $ gcloud topic gcloudignore
+#
+.gcloudignore
+# If you would like to upload your .git directory, .gitignore file or files
+# from your .gitignore file, remove the corresponding line
+# below:
+.git
+.gitignore
+
+node_modules
+#!include:.gitignore

package/.hosting.yml.sample

@@ -0,0 +1,23 @@
+google_cloud_info:
+  project:
+  region:
+
+# TODO: consider credsPayload in google_cloud_info instead of workspace .creds.yml
+
+functions:
+  exampleFunction:
+    max_instances: 1
+    timeout: 300s
+    wrappers:
+      - requireHostedApiKey
+    # entry_point: otherExportName
+
+  packagedFunction:
+    source: '@foxtware/mineral/api/pokemon/pokemonPokeballThrow.js'
+    max_instances: 1
+    wrappers:
+      - checkTrainer
+
+groups:
+  example_group:
+    - exampleFunction

package/README.md

@@ -50,3 +50,5 @@ The [bedrock](https://github.com/GorgonFreeman/bedrock) middleware, refactored f
   ```
 - **Monorepo structure**
 Mineral gets pushed to from a larger repo that can also contain private functions. Mineral should be strictly useful stuff for the public, and can be used standalone, but needs to be instantiated for serving, setting stuff like which creds file to use. This allows it to be used as part of another repo in the same HTTP/curl way as by itself. Pass `--workspace` to locate `.creds.yml` and `--api_dirs` to serve additional function directories.
+
+For cloud deploy, workspaces use `.hosting.yml` and `npm run host` (same `--workspace` / `--api_dirs` flags as dev/serve). See `.hosting.yml.sample`.

package/_build_scripts/publish.js

@@ -12,8 +12,25 @@ const writePackageJson = (packageJson) => {
   fs.writeFileSync(packageJsonPath, `${ JSON.stringify(packageJson, null, 2) }\n`);
 };
 
+const parseVersion = (version) => version.split('.').map((part) => Number(part) || 0);
+
+const isVersionGreater = (left, right) => {
+  const [leftMajor, leftMinor, leftPatch] = parseVersion(left);
+  const [rightMajor, rightMinor, rightPatch] = parseVersion(right);
+
+  if (leftMajor !== rightMajor) {
+    return leftMajor > rightMajor;
+  }
+
+  if (leftMinor !== rightMinor) {
+    return leftMinor > rightMinor;
+  }
+
+  return leftPatch > rightPatch;
+};
+
 const bumpPatch = (version) => {
-  const [major, minor, patch] = version.split('.').map((part) => Number(part) || 0);
+  const [major, minor, patch] = parseVersion(version);
   return [major, minor, patch + 1].join('.');
 };
 
@@ -63,14 +80,17 @@ const publish = async () => {
 
   let version = localVersion;
 
-  if (localVersion === publishedVersion) {
-    const suggestedVersion = bumpPatch(localVersion);
-    version = await askWithDefault('What version should we use?', suggestedVersion);
+  const localIsAhead = publishedVersion && isVersionGreater(localVersion, publishedVersion);
 
-    packageJson.version = version;
-    writePackageJson(packageJson);
+  if (!localIsAhead) {
+    const latestVersion = publishedVersion || localVersion;
+    const suggestedVersion = bumpPatch(latestVersion);
+    version = await askWithDefault('What version should we use?', suggestedVersion);
   }
 
+  packageJson.version = version;
+  writePackageJson(packageJson);
+
   execSync('npm publish', {
     cwd: mineralRoot,
     stdio: 'inherit',

package/_deploy_scripts/deployFromHostingYml.js

@@ -0,0 +1,319 @@
+const readline = require('readline');
+const { toAbsolutePath, setWorkspace } = require('../api/workspace');
+const { getApiDirs, readCliFlag } = require('../cli');
+const { loadHandlers } = require('../server');
+const { readHostingYml, getCredsJsonForDeploy, getHostedApiKeyForDeploy, resolveHostedHandlersForDeploy, functionUsesWrapper } = require('../hosting.utils');
+const { writeHostedJs } = require('./generateHosted');
+const { execCommand } = require('./execCommand');
+const { formatSetEnvVarsForGcloud, shellQuoteSingle } = require('./setEnvVarsGcloud');
+
+const GCLOUD_NODEJS_MAX_MAJOR = 24;
+
+const gcloudRuntimeFromCurrentNode = () => {
+  const localMajor = Number.parseInt(process.versions.node.split('.')[0], 10);
+  const effective = Number.isNaN(localMajor) ? GCLOUD_NODEJS_MAX_MAJOR : localMajor;
+  const major = Math.min(effective, GCLOUD_NODEJS_MAX_MAJOR);
+  return `nodejs${ major }`;
+};
+
+const getHostConfig = (options = {}) => ({
+  workspace: toAbsolutePath(
+    options.workspace
+      ?? readCliFlag('--workspace')
+      ?? process.env.MINERAL_WORKSPACE
+      ?? process.cwd(),
+  ),
+  api_dirs: getApiDirs(options),
+});
+
+const chooseOption = async (prompt, options) => new Promise((resolve) => {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  console.log(prompt);
+  options.forEach((option, index) => {
+    console.log(`  ${ index + 1 }. ${ option }`);
+  });
+
+  rl.question('> ', (answer) => {
+    rl.close();
+    const choice = Number(answer) - 1;
+    resolve(options[choice] ?? options[0]);
+  });
+});
+
+const anyHostedEntryUsesWrapper = (hostedEntries, wrapperName) => (
+  hostedEntries.some((hostedEntry) => hostedEntry.wrappers?.includes(wrapperName))
+);
+
+const getDeployArgs = () => {
+  const args = process.argv.slice(2);
+  const deployArgs = [];
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+
+    if (arg === '--workspace' || arg === '--api_dirs') {
+      index++;
+      continue;
+    }
+
+    if (arg.startsWith('--workspace=') || arg.startsWith('--api_dirs=')) {
+      continue;
+    }
+
+    deployArgs.push(arg);
+  }
+
+  return deployArgs;
+};
+
+const handlerByRouteName = (handlers) => {
+  const byName = new Map();
+
+  for (const handler of handlers.values()) {
+    byName.set(handler.routeName, handler);
+  }
+
+  return byName;
+};
+
+const deployFunction = async ({
+  functionName,
+  functionConfig,
+  googleCloudInfo,
+  workspace,
+  credsJson,
+  hostedApiKey,
+}) => {
+  const config = {
+    ...googleCloudInfo,
+    ...functionConfig,
+  };
+
+  let {
+    project,
+    region,
+    trigger = 'http',
+    runtime = gcloudRuntimeFromCurrentNode(),
+    allow_unauthenticated: allowUnauthenticated = true,
+    gen2 = true,
+    set_env_vars: extraSetEnvVars,
+    entry_point: entryPoint,
+    schedules,
+    groups,
+    wrappers,
+    source,
+    ...gcloudArgs
+  } = config;
+
+  const resolvedEntryPoint = entryPoint || functionName;
+  const envParts = [
+    'HOSTED=true',
+    `CREDS=${ credsJson }`,
+  ];
+
+  if (hostedApiKey) {
+    envParts.push(`HOSTED_API_KEY=${ hostedApiKey }`);
+  }
+
+  if (extraSetEnvVars) {
+    envParts.push(extraSetEnvVars);
+  }
+
+  const rawSetEnvVars = envParts.join(',');
+  const setEnvVarsForGcloud = formatSetEnvVarsForGcloud(rawSetEnvVars);
+
+  const deployCommand = [
+    `gcloud functions deploy ${ functionName }`,
+    `--project ${ project }`,
+    `--region ${ region }`,
+    `--source ${ shellQuoteSingle(workspace) }`,
+    `--entry-point ${ resolvedEntryPoint }`,
+    `--trigger-${ trigger }`,
+    `--runtime ${ runtime }`,
+    `--set-env-vars ${ shellQuoteSingle(setEnvVarsForGcloud) }`,
+    ...(allowUnauthenticated ? ['--allow-unauthenticated'] : []),
+    ...(gen2 ? ['--gen2'] : []),
+    ...Object.entries(gcloudArgs).map(([key, value]) => `--${ key.replaceAll('_', '-') } ${ value }`),
+  ].join(' ');
+
+  console.log(deployCommand);
+
+  try {
+    await execCommand(deployCommand);
+  } catch (error) {
+    console.error(`Error deploying function ${ functionName }:`, error);
+    return;
+  }
+
+  if (!schedules?.length) {
+    return;
+  }
+
+  const requiresHostedApiKey = functionUsesWrapper(functionConfig, 'requireHostedApiKey');
+
+  for (const schedule of schedules) {
+    const {
+      name: jobName,
+      schedule: jobSchedule,
+      http_method: jobHttpMethod = 'POST',
+      headers: jobHeaders = '',
+      message_body: jobMessageBody,
+      ...schedulerArgs
+    } = schedule;
+
+    let schedulerHeaders = jobHeaders;
+    if (requiresHostedApiKey && hostedApiKey) {
+      schedulerHeaders = schedulerHeaders ? `${ schedulerHeaders },` : '';
+      schedulerHeaders += `x-api-key=${ hostedApiKey }`;
+    }
+
+    try {
+      const checkCommand = `gcloud scheduler jobs describe ${ jobName } --project=${ project } --location=${ region } 2>/dev/null || echo "NOT_FOUND"`;
+      const checkResult = await execCommand(checkCommand);
+      const jobExists = !checkResult.stdout.includes('NOT_FOUND');
+
+      const schedulerCommand = [
+        jobExists ? `gcloud scheduler jobs update http ${ jobName }` : `gcloud scheduler jobs create http ${ jobName }`,
+        `--schedule="${ jobSchedule }"`,
+        `--uri="https://${ region }-${ project }.cloudfunctions.net/${ functionName }"`,
+        `--http-method=${ jobHttpMethod }`,
+        `--project=${ project }`,
+        `--location=${ region }`,
+        jobExists ? `--update-headers ${ schedulerHeaders }` : `--headers ${ schedulerHeaders }`,
+        ...(jobMessageBody ? [`--message-body '${ jobMessageBody }'`] : []),
+        ...Object.entries(schedulerArgs).map(([key, value]) => `--${ key.replaceAll('_', '-') } ${ value }`),
+      ].join(' ');
+
+      console.log(schedulerCommand);
+      await execCommand(schedulerCommand);
+    } catch (error) {
+      console.error(`Error handling scheduler job ${ jobName }:`, error);
+    }
+  }
+};
+
+const deployFromHostingYml = async (options = {}) => {
+  const config = getHostConfig(options);
+  setWorkspace(config.workspace);
+
+  const hostingConfig = readHostingYml(config.workspace);
+  const {
+    google_cloud_info: googleCloudInfo,
+    functions = {},
+    groups = {},
+  } = hostingConfig;
+
+  if (!googleCloudInfo?.project || !googleCloudInfo?.region) {
+    throw new Error('.hosting.yml requires google_cloud_info.project and google_cloud_info.region');
+  }
+
+  const handlers = loadHandlers({
+    ...config,
+    host_mode: true,
+  });
+  const handlersByName = handlerByRouteName(handlers);
+  const hostedHandlers = resolveHostedHandlersForDeploy({
+    functions,
+    workspace: config.workspace,
+    handlersByName,
+  });
+
+  if (anyHostedEntryUsesWrapper(hostedHandlers, 'requireHostedApiKey')) {
+    const hostedApiKey = getHostedApiKeyForDeploy(config.workspace);
+    if (!hostedApiKey) {
+      throw new Error('HOSTED_API_KEY is required in workspace .env when using requireHostedApiKey wrapper');
+    }
+  }
+
+  writeHostedJs({
+    workspace: config.workspace,
+    hostedHandlers,
+  });
+
+  const credsJson = getCredsJsonForDeploy(config.workspace);
+  const hostedApiKey = getHostedApiKeyForDeploy(config.workspace);
+  const deployArgs = getDeployArgs();
+
+  const deployOne = async (functionName) => {
+    if (!functions[functionName]) {
+      console.log(`Function ${ functionName } not found in .hosting.yml, skipping`);
+      return;
+    }
+
+    await deployFunction({
+      functionName,
+      functionConfig: functions[functionName],
+      googleCloudInfo,
+      workspace: config.workspace,
+      credsJson,
+      hostedApiKey,
+    });
+  };
+
+  if (deployArgs.includes('group')) {
+    const groupNames = Object.keys(groups);
+    if (!groupNames.length) {
+      console.log('No groups defined in .hosting.yml');
+      return;
+    }
+
+    const selectedGroup = await chooseOption('Which group would you like to deploy?', groupNames);
+    for (const functionName of groups[selectedGroup] || []) {
+      await deployOne(functionName);
+    }
+    return;
+  }
+
+  if (deployArgs.includes('function')) {
+    const functionNames = Object.keys(functions);
+    if (!functionNames.length) {
+      console.log('No functions defined in .hosting.yml');
+      return;
+    }
+
+    const selectedFunction = await chooseOption('Which function would you like to deploy?', functionNames);
+    await deployOne(selectedFunction);
+    return;
+  }
+
+  if (deployArgs.includes('all')) {
+    for (const functionName of Object.keys(functions)) {
+      await deployOne(functionName);
+    }
+    return;
+  }
+
+  console.log(`
+Usage (from workspace repo):
+  npm run host --workspace . --api_dirs api all
+  npm run host --workspace . --api_dirs api function
+  npm run host --workspace . --api_dirs api group
+`);
+};
+
+if (require.main === module) {
+  deployFromHostingYml().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  deployFromHostingYml,
+  getHostConfig,
+};
+
+/*
+  Deploy everything:
+  npm run host all
+
+  Deploy a single function:
+  npm run host function
+
+  Deploy a group of functions:
+  npm run host group
+*/

package/_deploy_scripts/execCommand.js

@@ -0,0 +1,38 @@
+const { spawn } = require('child_process');
+
+const execCommand = (command) => new Promise((resolve, reject) => {
+  const childProcess = spawn(command, [], {
+    stdio: 'pipe',
+    shell: true,
+  });
+
+  let stdout = '';
+  let stderr = '';
+
+  childProcess.stdout.on('data', (data) => {
+    stdout += data.toString();
+    process.stdout.write(data);
+  });
+
+  childProcess.stderr.on('data', (data) => {
+    stderr += data.toString();
+    process.stderr.write(data);
+  });
+
+  childProcess.on('close', (code) => {
+    if (code === 0) {
+      resolve({ stdout, stderr, command });
+      return;
+    }
+
+    reject({ stdout, stderr, command, code });
+  });
+
+  childProcess.on('error', (error) => {
+    reject({ error, command });
+  });
+});
+
+module.exports = {
+  execCommand,
+};

package/_deploy_scripts/generateHosted.js

@@ -0,0 +1,44 @@
+const fs = require('fs');
+const { wrapHostedFunction } = require('../hosting.utils');
+
+const generateHostedJs = ({
+  hostedHandlers,
+}) => {
+  const exportLines = [];
+  const hostingUtilsRequire = '@foxtware/mineral/hosting.utils';
+
+  for (const hostedHandler of hostedHandlers) {
+    const { entryPoint, wrappers = [], requirePath } = hostedHandler;
+    const wrappersArg = wrappers.length ? `, ${ JSON.stringify(wrappers) }` : '';
+
+    exportLines.push(
+      `  ${ entryPoint }: wrapHostedFunction(() => require('${ requirePath }'), '${ entryPoint }'${ wrappersArg }),`,
+    );
+  }
+
+  return `// Generated by mineral — do not edit
+const { wrapHostedFunction } = require('${ hostingUtilsRequire }');
+
+module.exports = {
+${ exportLines.join('\n') }
+};
+`;
+};
+
+const writeHostedJs = ({
+  workspace,
+  hostedHandlers,
+}) => {
+  const hostedPath = `${ workspace.replace(/\/$/, '') }/hosted.js`;
+  const content = generateHostedJs({
+    hostedHandlers,
+  });
+
+  fs.writeFileSync(hostedPath, content);
+  return hostedPath;
+};
+
+module.exports = {
+  generateHostedJs,
+  writeHostedJs,
+};

package/_deploy_scripts/setEnvVarsGcloud.js

@@ -0,0 +1,51 @@
+function splitSetEnvVarsPairs(combined) {
+  const segments = combined.split(/,(?=[A-Za-z_][A-Za-z0-9_]*=)/);
+  return segments.map((segment) => {
+    const eq = segment.indexOf('=');
+    if (eq === -1) {
+      throw new Error(`Invalid set_env_vars segment (no =): ${ segment }`);
+    }
+
+    return {
+      key: segment.slice(0, eq).trim(),
+      value: segment.slice(eq + 1),
+    };
+  });
+}
+
+function pickDelimiter(pairs) {
+  const blob = pairs.map((pair) => `${ pair.key }=${ pair.value }`).join('');
+
+  for (let count = 3; count < 64; count++) {
+    const delimiter = '#'.repeat(count);
+    if (!blob.includes(delimiter)) {
+      return delimiter;
+    }
+  }
+
+  throw new Error('Could not find a delimiter for gcloud --set-env-vars');
+}
+
+function formatSetEnvVarsForGcloud(combined) {
+  const pairs = splitSetEnvVarsPairs(combined);
+  if (pairs.length === 0) {
+    return combined;
+  }
+
+  const needsDelimiter = pairs.length > 1 || pairs.some((pair) => pair.value.includes(','));
+  if (!needsDelimiter) {
+    return combined;
+  }
+
+  const delimiter = pickDelimiter(pairs);
+  return `^${ delimiter }^${ pairs.map((pair) => `${ pair.key }=${ pair.value }`).join(delimiter) }`;
+}
+
+function shellQuoteSingle(value) {
+  return `'${ String(value).replace(/'/g, `'\\''`) }'`;
+}
+
+module.exports = {
+  formatSetEnvVarsForGcloud,
+  shellQuoteSingle,
+};

package/cli.js

@@ -0,0 +1,42 @@
+const splitCommaList = (value = '') => value
+  .split(',')
+  .map((item) => item.trim())
+  .filter(Boolean);
+
+const readCliFlag = (flag) => {
+  const args = process.argv.slice(2);
+  const equalsPrefix = `${ flag }=`;
+
+  for (let index = 0; index < args.length; index++) {
+    if (args[index].startsWith(equalsPrefix)) {
+      return args[index].slice(equalsPrefix.length);
+    }
+
+    if (args[index] === flag) {
+      return args[index + 1];
+    }
+  }
+};
+
+const getApiDirs = (options = {}) => {
+  if (options.api_dirs) {
+    return options.api_dirs;
+  }
+
+  const fromCli = readCliFlag('--api_dirs');
+  if (fromCli) {
+    return splitCommaList(fromCli);
+  }
+
+  if (process.env.MINERAL_API_DIRS) {
+    return splitCommaList(process.env.MINERAL_API_DIRS);
+  }
+
+  return [];
+};
+
+module.exports = {
+  splitCommaList,
+  readCliFlag,
+  getApiDirs,
+};

package/hosting.utils.js

@@ -0,0 +1,232 @@
+const fs = require('fs');
+const { createRequire } = require('module');
+const yaml = require('yaml');
+const {
+  respondJson,
+  errorToReadable,
+  getRequestBody,
+  argsFromBody,
+  funcApi,
+  wrapFunction,
+  requireHostedApiKey,
+  statusCodeFromResult,
+} = require('./server.utils');
+
+const wrappersByName = {
+  requireHostedApiKey,
+};
+
+const resolveWrappers = (wrapperNames = []) => (
+  wrapperNames.map((wrapperName) => {
+    const wrapper = wrappersByName[wrapperName];
+    if (!wrapper) {
+      throw new Error(`Unknown wrapper: ${ wrapperName }`);
+    }
+    return wrapper;
+  })
+);
+
+const getHostedEntries = (functions = {}) => {
+  const byEntryPoint = new Map();
+
+  for (const [functionName, functionConfig] of Object.entries(functions)) {
+    const entryPoint = functionConfig.entry_point || functionConfig.entryPoint || functionName;
+    const existing = byEntryPoint.get(entryPoint) || {
+      entryPoint,
+      wrappers: [],
+    };
+
+    if (Array.isArray(functionConfig.wrappers)) {
+      existing.wrappers.push(...functionConfig.wrappers);
+      existing.wrappers = [...new Set(existing.wrappers)];
+    }
+
+    if (functionConfig.source) {
+      existing.source = functionConfig.source;
+    }
+
+    byEntryPoint.set(entryPoint, existing);
+  }
+
+  return [...byEntryPoint.values()];
+};
+
+const functionUsesWrapper = (functionConfig = {}, wrapperName) => (
+  Array.isArray(functionConfig.wrappers) && functionConfig.wrappers.includes(wrapperName)
+);
+
+const getFuncApiConfig = ({
+  moduleExports,
+  routeName,
+}) => {
+  const { funcApiConfig } = moduleExports;
+  if (!funcApiConfig || typeof funcApiConfig !== 'object') {
+    return undefined;
+  }
+
+  if (funcApiConfig[routeName]) {
+    return funcApiConfig[routeName];
+  }
+
+  const exportNames = Object.keys(moduleExports).filter((key) => key !== 'funcApiConfig');
+  const configIsShared = !exportNames.some((name) => funcApiConfig[name]);
+
+  if (configIsShared) {
+    return funcApiConfig;
+  }
+};
+
+const wrapHostedFunction = (loader, exportName, wrapperNames = []) => {
+  let handler = null;
+  let usesFuncApi = false;
+  const wrappers = resolveWrappers(wrapperNames);
+
+  const coreHandler = async (req, res) => {
+    if (!handler) {
+      const moduleExports = loader();
+      const handlerFn = moduleExports[exportName];
+
+      if (typeof handlerFn !== 'function') {
+        throw new Error(`Hosted export not found: ${ exportName }`);
+      }
+
+      const funcApiConfig = getFuncApiConfig({
+        moduleExports,
+        routeName: exportName,
+      });
+
+      usesFuncApi = Boolean(funcApiConfig);
+      handler = usesFuncApi ? funcApi(handlerFn, funcApiConfig) : handlerFn;
+    }
+
+    const body = await getRequestBody(req);
+    const args = argsFromBody(body);
+    return usesFuncApi
+      ? await handler({ req, res, body, args })
+      : await handler(...args);
+  };
+
+  const wrappedHandler = wrapFunction(coreHandler, wrappers);
+
+  return async (req, res) => {
+    try {
+      const result = await wrappedHandler(req, res);
+
+      if (res.headersSent) {
+        return;
+      }
+
+      if (result === undefined) {
+        respondJson(res, 200, { ok: true });
+        return;
+      }
+
+      const statusCode = statusCodeFromResult(result);
+      respondJson(res, statusCode, result);
+    } catch (error) {
+      if (res.headersSent) {
+        return;
+      }
+
+      respondJson(res, 500, {
+        ok: false,
+        error: {
+          code: 'UNHANDLED_ERROR',
+          message: 'Unhandled server error.',
+          details: errorToReadable(error),
+        },
+      });
+    }
+  };
+};
+
+const readHostingYml = (workspace) => {
+  const hostingPath = `${ workspace }/.hosting.yml`;
+
+  if (!fs.existsSync(hostingPath)) {
+    throw new Error(`Missing .hosting.yml in workspace: ${ workspace }`);
+  }
+
+  const hostingText = fs.readFileSync(hostingPath, 'utf8');
+  const hostingConfig = yaml.parse(hostingText);
+
+  if (!hostingConfig || typeof hostingConfig !== 'object' || Array.isArray(hostingConfig)) {
+    throw new Error('Invalid .hosting.yml');
+  }
+
+  return hostingConfig;
+};
+
+const getCredsJsonForDeploy = (workspace) => {
+  const credsPath = `${ workspace }/.creds.yml`;
+
+  if (!fs.existsSync(credsPath)) {
+    throw new Error(`Missing .creds.yml in workspace: ${ workspace }`);
+  }
+
+  const credsText = fs.readFileSync(credsPath, 'utf8');
+  return JSON.stringify(yaml.parse(credsText));
+};
+
+const getHostedApiKeyForDeploy = (workspace) => {
+  const envPath = `${ workspace }/.env`;
+
+  if (!fs.existsSync(envPath)) {
+    return '';
+  }
+
+  const envText = fs.readFileSync(envPath, 'utf8');
+  const match = envText.match(/^HOSTED_API_KEY=(.*)$/m);
+  return match ? match[1].trim() : '';
+};
+
+const resolveHostedHandlersForDeploy = ({
+  functions = {},
+  workspace,
+  handlersByName,
+}) => {
+  const workspaceRequire = createRequire(`${ workspace.replace(/\/$/, '') }/package.json`);
+  const hostedEntries = getHostedEntries(functions);
+
+  return hostedEntries.map((hostedEntry) => {
+    const { entryPoint, source } = hostedEntry;
+
+    if (source) {
+      workspaceRequire.resolve(source);
+      const moduleExports = workspaceRequire(source);
+      if (typeof moduleExports[entryPoint] !== 'function') {
+        throw new Error(`Hosted export not found: ${ entryPoint } in ${ source }`);
+      }
+
+      return {
+        ...hostedEntry,
+        requirePath: source,
+      };
+    }
+
+    const handler = handlersByName.get(entryPoint);
+    if (!handler) {
+      throw new Error(
+        `entry_point "${ entryPoint }" not found in workspace handlers — add api/ handler or source in .hosting.yml`,
+      );
+    }
+
+    return {
+      ...hostedEntry,
+      requirePath: `./${ handler.filePath.slice(workspace.length + 1) }`,
+    };
+  });
+};
+
+// TODO: support credsPayload in google_cloud_info instead of full workspace .creds.yml
+
+module.exports = {
+  getFuncApiConfig,
+  wrapHostedFunction,
+  readHostingYml,
+  getCredsJsonForDeploy,
+  getHostedApiKeyForDeploy,
+  getHostedEntries,
+  resolveHostedHandlersForDeploy,
+  functionUsesWrapper,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxtware/mineral",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "bin": {
     "mineral": "bin/mineral.js"
   },

package/server.js

@@ -1,49 +1,12 @@
 const fs = require('fs');
 const http = require('http');
-const { respondJson, errorToReadable, getRequestBody, argsFromBody, funcApi } = require('./server.utils');
+const { respondJson, errorToReadable, getRequestBody, argsFromBody, funcApi, statusCodeFromResult } = require('./server.utils');
 const { getWorkspace, setWorkspace, loadWorkspaceEnv, toAbsolutePath } = require('./api/workspace');
+const { getApiDirs, readCliFlag } = require('./cli');
+const { getFuncApiConfig } = require('./hosting.utils');
 
 const MINERAL_API_DIR = `${ __dirname }/api`;
 
-// --- Config ---
-
-const splitCommaList = (value = '') => value
-  .split(',')
-  .map((item) => item.trim())
-  .filter(Boolean);
-
-const readCliFlag = (flag) => {
-  const args = process.argv.slice(2);
-  const equalsPrefix = `${ flag }=`;
-
-  for (let index = 0; index < args.length; index++) {
-    if (args[index].startsWith(equalsPrefix)) {
-      return args[index].slice(equalsPrefix.length);
-    }
-
-    if (args[index] === flag) {
-      return args[index + 1];
-    }
-  }
-};
-
-const getApiDirs = (options = {}) => {
-  if (options.api_dirs) {
-    return options.api_dirs;
-  }
-
-  const fromCli = readCliFlag('--api_dirs');
-  if (fromCli) {
-    return splitCommaList(fromCli);
-  }
-
-  if (process.env.MINERAL_API_DIRS) {
-    return splitCommaList(process.env.MINERAL_API_DIRS);
-  }
-
-  return [];
-};
-
 const getConfig = (options = {}) => ({
   port: Number(options.port ?? process.env.PORT ?? 8000),
   workspace: toAbsolutePath(
@@ -53,6 +16,7 @@ const getConfig = (options = {}) => ({
       ?? process.cwd(),
   ),
   api_dirs: getApiDirs(options),
+  host_mode: Boolean(options.host_mode),
 });
 
 // --- Handler discovery ---
@@ -105,6 +69,7 @@ const listJsFiles = (directory) => {
 const directoriesToScan = ({
   workspace,
   api_dirs,
+  host_mode = false,
 }) => {
   const extraDirs = api_dirs.map((dir) => (
     dir.startsWith('/')
@@ -112,30 +77,15 @@ const directoriesToScan = ({
       : `${ workspace }/${ dir }`
   ));
 
-  return [MINERAL_API_DIR, ...extraDirs];
-};
-
-const getFuncApiConfig = ({
-  moduleExports,
-  routeName,
-}) => {
-  const { funcApiConfig } = moduleExports;
-  if (!funcApiConfig || typeof funcApiConfig !== 'object') {
-    return undefined;
+  if (host_mode && api_dirs.length) {
+    return extraDirs;
   }
 
-  if (funcApiConfig[routeName]) {
-    return funcApiConfig[routeName];
-  }
-
-  const exportNames = Object.keys(moduleExports).filter((key) => key !== 'funcApiConfig');
-  const configIsShared = !exportNames.some((name) => funcApiConfig[name]);
-
-  if (configIsShared) {
-    return funcApiConfig;
-  }
+  return [MINERAL_API_DIR, ...extraDirs];
 };
 
+const getFuncApiConfigFromModule = getFuncApiConfig;
+
 const addHandlerFromFile = (filePath, handlers) => {
   const moduleExports = require(filePath);
   if (!moduleExports || typeof moduleExports !== 'object') {
@@ -148,7 +98,7 @@ const addHandlerFromFile = (filePath, handlers) => {
     return;
   }
 
-  const funcApiConfig = getFuncApiConfig({
+  const funcApiConfig = getFuncApiConfigFromModule({
     moduleExports,
     routeName,
   });
@@ -218,7 +168,7 @@ const createServer = (handlers) => http.createServer(async (req, res) => {
       return;
     }
 
-    respondJson(res, 200, result);
+    respondJson(res, statusCodeFromResult(result), result);
   } catch (error) {
     respondJson(res, 500, {
       ok: false,

package/server.utils.js

@@ -1,5 +1,6 @@
 const { logDeep } = require('./api/utils');
 const { StringDecoder } = require('string_decoder');
+const { HOSTED } = require('./api/constants');
 
 const respondJson = (res, statusCode, payload) => {
   logDeep(payload);
@@ -116,6 +117,42 @@ const runRequestHandler = async (requestHandler, requestContext) => {
   return mergeRequestContext(requestContext, handlerOutput);
 };
 
+const wrapFunction = (func, wrappers = []) => async (req, res, ...rest) => {
+  for (const wrapper of wrappers) {
+    const rejected = await wrapper(req, res);
+    if (rejected) {
+      return rejected;
+    }
+  }
+
+  return func(req, res, ...rest);
+};
+
+const requireHostedApiKey = async (req) => {
+  if (!HOSTED) {
+    return;
+  }
+
+  if (req.headers['x-api-key'] !== process.env.HOSTED_API_KEY) {
+    return {
+      ok: false,
+      error: {
+        code: 'UNAUTHORIZED',
+        message: 'Unauthorized',
+        statusCode: 401,
+      },
+    };
+  }
+};
+
+const statusCodeFromResult = (result) => {
+  if (result?.ok === false) {
+    return result?.error?.statusCode ?? 400;
+  }
+
+  return 200;
+};
+
 const funcApi = (func, config = {}) => {
   const {
     requestHandler,
@@ -224,5 +261,8 @@ module.exports = {
   errorToReadable,
   getRequestBody,
   argsFromBody,
+  wrapFunction,
+  requireHostedApiKey,
+  statusCodeFromResult,
   funcApi,
 };