@foxtware/mineral 0.1.0 → 0.1.2

package/api/workspace.js

@@ -0,0 +1,43 @@
+const fs = require('fs');
+const dotenv = require('dotenv');
+
+let workspace = process.cwd();
+
+// Turn ".", "geode", or "/full/path" into an absolute directory.
+const toAbsolutePath = (dir) => {
+  if (!dir || dir === '.') {
+    return process.cwd();
+  }
+
+  if (dir.startsWith('/')) {
+    return dir;
+  }
+
+  return `${ process.cwd() }/${ dir }`;
+};
+
+const getWorkspace = () => workspace;
+
+const setWorkspace = (dir) => {
+  workspace = toAbsolutePath(dir);
+  process.env.MINERAL_WORKSPACE = workspace;
+};
+
+const loadWorkspaceEnv = () => {
+  const envFile = `${ workspace }/.env`;
+  if (!fs.existsSync(envFile)) {
+    return;
+  }
+
+  dotenv.config({
+    path: envFile,
+    override: true,
+  });
+};
+
+module.exports = {
+  getWorkspace,
+  setWorkspace,
+  loadWorkspaceEnv,
+  toAbsolutePath,
+};

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,7 +1,9 @@
 {
   "name": "@foxtware/mineral",
-  "version": "0.1.0",
-  "bin": { "mineral": "bin/mineral.js" },
+  "version": "0.1.2",
+  "bin": {
+    "mineral": "bin/mineral.js"
+  },
   "main": "server.js",
   "publishConfig": {
     "access": "public"
@@ -12,7 +14,7 @@
     "new": "node _build_scripts/createNewFunction.js",
     "serve": "PORT=8100 node server.js",
     "start": "node server.js",
-    "npm:publish": "npm publish"
+    "npm:publish": "node _build_scripts/publish.js"
   },
   "dependencies": {
     "csvtojson": "^2.0.14",

package/server.js

@@ -1,45 +1,64 @@
-require('dotenv').config();
-
 const fs = require('fs');
-const path = require('path');
 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`;
+
+const getConfig = (options = {}) => ({
+  port: Number(options.port ?? process.env.PORT ?? 8000),
+  workspace: toAbsolutePath(
+    options.workspace
+      ?? readCliFlag('--workspace')
+      ?? process.env.MINERAL_WORKSPACE
+      ?? process.cwd(),
+  ),
+  api_dirs: getApiDirs(options),
+  host_mode: Boolean(options.host_mode),
+});
 
-const apiDirectory = path.join(__dirname, 'api');
+// --- Handler discovery ---
 
-const shouldSkipApiFile = (fileName) => {
+const isHandlerFile = (fileName) => {
   if (!fileName.endsWith('.js')) {
-    return true;
+    return false;
   }
 
   if (fileName.startsWith('_')) {
-    return true;
+    return false;
   }
 
   if (fileName.endsWith('.utils.js')) {
-    return true;
+    return false;
   }
 
-  const skippedFiles = new Set([
-    'utils.js',
-    'validators.js',
-  ]);
+  return true;
+};
 
-  return skippedFiles.has(fileName);
+const routeNameFromFile = (filePath) => {
+  const fileName = filePath.split('/').pop();
+  return fileName.slice(0, -3);
 };
 
-const walkFilesRecursive = (directory) => {
-  const entries = fs.readdirSync(directory, { withFileTypes: true });
+const listJsFiles = (directory) => {
+  if (!fs.existsSync(directory)) {
+    return [];
+  }
+
   const files = [];
+  const entries = fs.readdirSync(directory, { withFileTypes: true });
 
   for (const entry of entries) {
-    const entryPath = path.join(directory, entry.name);
+    const entryPath = `${ directory }/${ entry.name }`;
+
     if (entry.isDirectory()) {
-      files.push(...walkFilesRecursive(entryPath));
+      files.push(...listJsFiles(entryPath));
       continue;
     }
 
-    if (entry.isFile()) {
+    if (entry.isFile() && isHandlerFile(entry.name)) {
       files.push(entryPath);
     }
   }
@@ -47,92 +66,91 @@ const walkFilesRecursive = (directory) => {
   return files;
 };
 
-const loadHandlers = () => {
-  const files = walkFilesRecursive(apiDirectory).filter((filePath) => !shouldSkipApiFile(path.basename(filePath)));
-  const routeToHandler = new Map();
+const directoriesToScan = ({
+  workspace,
+  api_dirs,
+  host_mode = false,
+}) => {
+  const extraDirs = api_dirs.map((dir) => (
+    dir.startsWith('/')
+      ? dir
+      : `${ workspace }/${ dir }`
+  ));
+
+  if (host_mode && api_dirs.length) {
+    return extraDirs;
+  }
 
-  for (const filePath of files) {
-    const moduleExports = require(filePath);
-    if (!moduleExports || typeof moduleExports !== 'object') {
-      continue;
-    }
+  return [MINERAL_API_DIR, ...extraDirs];
+};
 
-    const fileBaseName = path.basename(filePath, '.js');
-    const exportedValue = moduleExports[fileBaseName];
+const getFuncApiConfigFromModule = getFuncApiConfig;
 
-    if (typeof exportedValue !== 'function') {
-      continue;
-    }
+const addHandlerFromFile = (filePath, handlers) => {
+  const moduleExports = require(filePath);
+  if (!moduleExports || typeof moduleExports !== 'object') {
+    return;
+  }
 
-    const {
-      funcApiConfig,
-    } = moduleExports;
-    const functionExportNames = Object.entries(moduleExports)
-      .filter(([exportName, exportValue]) => exportName !== 'funcApiConfig' && typeof exportValue === 'function')
-      .map(([exportName]) => exportName);
-
-    const getFuncApiConfigForExport = (exportName) => {
-      if (!funcApiConfig || typeof funcApiConfig !== 'object') {
-        return undefined;
-      }
-
-      const configByExportName = funcApiConfig[exportName];
-      if (configByExportName && typeof configByExportName === 'object' && !Array.isArray(configByExportName)) {
-        return configByExportName;
-      }
-
-      // If config isn't keyed by function names and this export matches the filename,
-      // treat funcApiConfig as the config for that function.
-      const configIsKeyedByFunctionName = functionExportNames.some((functionExportName) => funcApiConfig[functionExportName] !== undefined);
-      if (!configIsKeyedByFunctionName && exportName === fileBaseName) {
-        return funcApiConfig;
-      }
-    };
-
-    const exportFuncApiConfig = getFuncApiConfigForExport(fileBaseName);
-    const handler = exportFuncApiConfig
-      ? funcApi(exportedValue, exportFuncApiConfig)
-      : exportedValue;
-
-    const routePath = `/${ fileBaseName }`;
-    if (routeToHandler.has(routePath)) {
-      const existing = routeToHandler.get(routePath);
-      throw new Error(`Duplicate handler route '${ routePath }' from ${ filePath } and ${ existing.filePath }`);
-    }
+  const routeName = routeNameFromFile(filePath);
+  const handlerFn = moduleExports[routeName];
+  if (typeof handlerFn !== 'function') {
+    return;
+  }
 
-    routeToHandler.set(routePath, {
-      filePath,
-      exportName: fileBaseName,
-      handler,
-      usesFuncApi: Boolean(exportFuncApiConfig),
-    });
+  const funcApiConfig = getFuncApiConfigFromModule({
+    moduleExports,
+    routeName,
+  });
+
+  const route = `/${ routeName }`;
+  if (handlers.has(route)) {
+    const existing = handlers.get(route);
+    throw new Error(`Duplicate route '${ route }' from ${ filePath } and ${ existing.filePath }`);
+  }
+
+  handlers.set(route, {
+    filePath,
+    routeName,
+    handler: funcApiConfig ? funcApi(handlerFn, funcApiConfig) : handlerFn,
+    usesFuncApi: Boolean(funcApiConfig),
+  });
+};
+
+const loadHandlers = (config) => {
+  const handlers = new Map();
+
+  for (const directory of directoriesToScan(config)) {
+    for (const filePath of listJsFiles(directory)) {
+      addHandlerFromFile(filePath, handlers);
+    }
   }
 
-  return routeToHandler;
+  return handlers;
 };
 
-const handlers = loadHandlers();
+// --- HTTP ---
 
-const server = http.createServer(async (req, res) => {
+const createServer = (handlers) => http.createServer(async (req, res) => {
   if (req.method === 'GET' && req.url === '/') {
-    const routes = Array.from(handlers.keys()).sort();
     respondJson(res, 200, {
       ok: true,
       data: {
-        routes,
+        routes: [...handlers.keys()].sort(),
+        workspace: getWorkspace(),
       },
     });
     return;
   }
 
-  const pathOnly = (req.url || '/').split('?')[0];
-  const matchedHandler = handlers.get(pathOnly);
-  if (!matchedHandler) {
+  const route = (req.url || '/').split('?')[0];
+  const handler = handlers.get(route);
+  if (!handler) {
     respondJson(res, 404, {
       ok: false,
       error: {
         code: 'NOT_FOUND',
-        message: `No handler found for route ${ pathOnly }`,
+        message: `No handler found for route ${ route }`,
       },
     });
     return;
@@ -141,23 +159,16 @@ const server = http.createServer(async (req, res) => {
   try {
     const body = await getRequestBody(req);
     const args = argsFromBody(body);
-    const result = matchedHandler.usesFuncApi
-      ? await matchedHandler.handler({
-        req,
-        res,
-        body,
-        args,
-      })
-      : await matchedHandler.handler(...args);
+    const result = handler.usesFuncApi
+      ? await handler.handler({ req, res, body, args })
+      : await handler.handler(...args);
 
     if (result === undefined) {
-      respondJson(res, 200, {
-        ok: true,
-      });
+      respondJson(res, 200, { ok: true });
       return;
     }
 
-    respondJson(res, 200, result);
+    respondJson(res, statusCodeFromResult(result), result);
   } catch (error) {
     respondJson(res, 500, {
       ok: false,
@@ -170,25 +181,64 @@ const server = http.createServer(async (req, res) => {
   }
 });
 
-const startServer = ({
-  port = process.env.PORT || 8000,
-} = {}) => {
-  server.listen(port, () => {
-    console.log(`Mineral server running on port ${ port }`);
-    console.log('Registered routes:');
-    for (const route of Array.from(handlers.keys()).sort()) {
-      console.log(route);
-    }
-  });
+// --- Start ---
+
+let server = null;
+let handlers = null;
+
+const logStartup = ({
+  port,
+  workspace,
+  api_dirs,
+  handlers: routeHandlers,
+}) => {
+  console.log(`Mineral server running on port ${ port }`);
+  console.log(`Workspace: ${ workspace }`);
+
+  if (api_dirs.length) {
+    console.log('Extra API dirs:', api_dirs.join(', '));
+  }
+
+  console.log('Registered routes:');
+  for (const route of [...routeHandlers.keys()].sort()) {
+    console.log(route);
+  }
+};
+
+const startServer = (options = {}) => {
+  const config = getConfig(options);
+
+  setWorkspace(config.workspace);
+  loadWorkspaceEnv();
+
+  handlers = loadHandlers(config);
+  server = createServer(handlers);
+
+  server.listen(config.port, () => logStartup({
+    ...config,
+    handlers,
+  }));
 
   return server;
 };
 
 module.exports = {
-  server,
-  handlers,
-  loadHandlers,
   startServer,
+  loadHandlers,
+  get server() {
+    if (!server) {
+      startServer();
+    }
+
+    return server;
+  },
+  get handlers() {
+    if (!handlers) {
+      startServer();
+    }
+
+    return handlers;
+  },
 };
 
 if (require.main === module) {