edge-functions 1.0.0

package/lib/main.js

@@ -0,0 +1,260 @@
+#! /usr/bin/env node
+import path from 'path';
+import { Command } from 'commander';
+import { createPromptModule } from 'inquirer';
+import { satisfies } from 'semver';
+import { feedback, debug } from '#utils';
+import { Messages } from '#constants';
+
+const MIN_NODE_VERSION = '18.0.0';
+
+const debugEnabled = process.env.DEBUG === 'true';
+const version = process.env.npm_package_version;
+const program = new Command();
+const prompt = createPromptModule();
+
+/**
+ * Validates if user is using the minimum Node version
+ * @returns {boolean} - indicates if is a valid version
+ */
+function validateNodeMinVersion() {
+  const isAValidVersion = satisfies(process.version, `>= ${MIN_NODE_VERSION}`);
+
+  return isAValidVersion;
+}
+
+/**
+ * Sets the global Vulcan environment.
+ *
+ * Validates the ENV value and sets it as the environment in the global 'vulcan' object.
+ * If the ENV value is invalid, it throws an error and terminates the process.
+ * @throws {Error} If ENV is not one of 'production', 'stage', 'dev'.
+ * @example
+ *    setVulcanEnvironment();
+ */
+function setVulcanEnvironment() {
+  const ENV = process.env.AZION_ENV || 'production';
+  if (!['production', 'stage', 'local'].includes(ENV)) {
+    feedback.error(Messages.env.errors.invalid_environment);
+    process.exit(1);
+  } else {
+    globalThis.vulcan = { env: ENV };
+  }
+}
+/**
+ * Starts the command-line interface program.
+ * @example
+ *    startProgram();
+ */
+function startVulcanProgram() {
+  program.version(version);
+
+  if (debugEnabled) {
+    program
+      .command('auth')
+      .option(
+        '--password <username>:<password>',
+        'Authenticate using username and password',
+      )
+      .option('--token <token>', 'Authenticate using personal token')
+      .description('Authenticate the CLI')
+      .action(async (options) => {
+        const { core } = await import('#platform');
+
+        const authOptions = [
+          {
+            name: 'Username and Password',
+            value: 'password',
+          },
+          {
+            name: 'Personal Token',
+            value: 'token',
+          },
+        ];
+
+        if (options.password) {
+          const [username, password] = options.password.split(':');
+          core.actions.auth('password', { username, password });
+        }
+
+        if (options.token) {
+          const { token } = options;
+          core.actions.auth('token', { token });
+        }
+
+        if (!options.token && !options.password) {
+          const { authOption } = await prompt([
+            {
+              type: 'list',
+              name: 'authOption',
+              message: 'Choose your login option:',
+              choices: authOptions.map((option) => option.name),
+            },
+          ]);
+
+          if (authOption === 'Username and Password') {
+            const { username, password } = await prompt([
+              {
+                type: 'input',
+                name: 'username',
+                message: 'Enter your username:',
+              },
+              {
+                type: 'password',
+                name: 'password',
+                message: 'Enter your password:',
+              },
+            ]);
+            core.actions.auth('password', { username, password });
+          }
+          if (authOption === 'Personal Token') {
+            const { token } = await prompt([
+              {
+                type: 'password',
+                name: 'token',
+                message: 'Enter your personal token:',
+              },
+            ]);
+            core.actions.auth('token', { token });
+          }
+        }
+      });
+
+    program
+      .command('run')
+      .description('Run Edge Function')
+      .arguments('<file>')
+      .option('-p, --port <port>', 'Specify the port', '3000')
+      .action(async (file, options) => {
+        const { port } = options;
+        const parsedPort = parseInt(port, 10);
+        const { server } = await import('#env');
+        const entryPoint = file || path.join(process.cwd(), '.edge/woker.js');
+        server(entryPoint, parsedPort);
+      });
+
+    program
+      .command('logs <type> [id]')
+      .description('Perform operations on function or application logs')
+      .option('-w, --watch', 'Show real-time logs')
+      .action(async (type, id, options) => {
+        const { functions } = await import('#platform');
+        const { watch } = options;
+
+        if (!['function', 'application'].includes(type)) {
+          feedback.error(Messages.platform.logs.errors.invalid_log_type);
+          return;
+        }
+
+        if (type === 'function') {
+          functions.actions.showFunctionLogs(id, watch);
+        }
+        if (type === 'application') {
+          feedback.info(Messages.platform.logs.info.unsupported_log_type);
+        }
+      });
+
+    program
+      .command('storage sync')
+      .description(
+        'Synchronize local .edge/statics with the Edge Function storage',
+      )
+      .action(async () => {
+        const { core } = await import('#platform');
+        const { getVulcanBuildId } = await import('#utils');
+
+        const versionId = getVulcanBuildId();
+        const basePath = path.join(process.cwd(), '.edge/statics/');
+        await core.actions.uploadStatics(versionId, basePath);
+      });
+
+    program
+      .command('deploy')
+      .description('Create and deploy an application with a function')
+      .action(async () => {
+        const { core } = await import('#platform');
+        const { getVulcanBuildId } = await import('#utils');
+
+        const versionId = getVulcanBuildId();
+        const staticsPath = path.join(process.cwd(), '/.edge/statics');
+
+        const answers = await prompt([
+          {
+            type: 'input',
+            name: 'applicationName',
+            message:
+              'Enter the name of the application (optional, leave empty for random name):',
+          },
+          {
+            type: 'input',
+            name: 'functionName',
+            message:
+              'Enter the name of the function (optional, leave empty for random name):',
+          },
+        ]);
+
+        const { applicationName, functionName } = answers;
+
+        await core.actions.uploadStatics(versionId, staticsPath);
+        const domain = await core.actions.deploy(applicationName, functionName);
+        core.actions.watchPropagation(domain);
+      });
+  }
+
+  program
+    .command('build')
+    .description('Build a project for edge deployment')
+    .option(
+      '--preset <type>',
+      'Preset of build target (e.g., vue, next, javascript)',
+      'javascript',
+    )
+    .option(
+      '--mode <type>',
+      'Mode of build target (e.g., deliver, compute)',
+      'compute',
+    )
+    .option(
+      '--entry <string>',
+      'Code entrypoint (default: ./main.js)',
+      './main.js',
+    )
+    .action(async ({
+      preset, mode, entry, versionId,
+    }) => {
+      // TODO: generate versionID in dispatcher (currently generated for webpackconfig)
+      const BuildDispatcher = (await import('#build')).default;
+      const buildDispatcher = new BuildDispatcher(
+        preset,
+        mode,
+        entry,
+        versionId,
+      );
+      await buildDispatcher.run();
+    });
+
+  program
+    .command('presets <type>')
+    .description('Create or use defined project presets for Edge.')
+    .action(async (type) => {
+      const { getPresetsList } = await import('#utils');
+      const presets = getPresetsList();
+
+      if (type === 'ls') {
+        presets.forEach((preset) => feedback.option(preset));
+      }
+    });
+  program.parse(process.argv);
+}
+
+try {
+  if (validateNodeMinVersion()) {
+    setVulcanEnvironment();
+    startVulcanProgram();
+  } else {
+    feedback.error(Messages.errors.invalid_node_version(MIN_NODE_VERSION));
+  }
+} catch (error) {
+  feedback.error(Messages.errors.unknown_error);
+  debug.error(error);
+}

package/lib/notations/namespaces.js

@@ -0,0 +1,30 @@
+/**
+ * @namespace utils
+ * @description Provides utility functions for various tasks.
+ */
+
+/**
+ * @namespace platform
+ * @description Contains functions and actions to interact with the edge platform (Azion).
+ */
+
+/**
+ * @namespace build
+ * @description Represents the structure responsible for pre-build and build processes for the edge.
+ */
+
+/**
+ * @namespace env
+ * @description Contains codes and functions responsible for managing the local environment.
+ */
+
+/**
+ * @namespace presets
+ * @description Contains presets with pre-configured workers and
+ *  Presets available to run on the edge.
+ */
+
+/**
+ * @namespace edge
+ * @description Contains imported and computer-ready functions for use on the edge.
+ */

package/lib/notations/typedef.js

@@ -0,0 +1,10 @@
+/**
+ * @typedef {object} FetchEvent
+ * @property {Request} request - This interface represents a resource request.
+ * @property {Promise<Response>} respondWith - This interface prevents the browser's
+ * default fetch handling,  and allows you to provide a promise for a Response yourself.
+ * @property {function(): void} waitUntil  - his interface is used to inform the browser
+ * not to terminate the Service Worker until
+ * the promise passed to `waitUntil` is either resolved or rejected.
+ * @description Represents an event that is dispatched to a worker when a fetch event occurs.
+ */

package/lib/platform/actions/application/createApplication.actions.js

@@ -0,0 +1,33 @@
+import { debug } from '#utils';
+import ApplicationService from '../../services/application.service.js';
+/**
+ * @function
+ * @memberof platform
+ * @name createApplication
+ * @description Creates a new application using the specified application name.
+ * @param {string} applicationName - The name of the new application.
+ * @returns {Promise<object>} A promise that resolves to the newly created application object.
+ * @throws Will throw an error if the creation process fails.
+ * @example
+ * try {
+ *    const newApp = await createApplication('My New Application');
+ *    console.log(newApp);
+ * } catch (error) {
+ *    console.error(error);
+ * }
+ */
+async function createApplication(applicationName) {
+  try {
+    const payload = {
+      name: applicationName,
+      delivery_protocol: 'http,https',
+    };
+    const response = await (await ApplicationService.create(payload)).json();
+    return response.results;
+  } catch (error) {
+    debug.error(error);
+    throw error;
+  }
+}
+
+export default createApplication;

package/lib/platform/actions/application/enableEdgeFunctions.actions.js

@@ -0,0 +1,34 @@
+import { debug } from '#utils';
+import ApplicationService from '../../services/application.service.js';
+/**
+ * @function
+ * @memberof platform
+ * @name enableEdgeFunctions
+ * @description Enables edge functions for the specified application.
+ * @param {number} applicationId - The unique identifier of the application.
+ * @returns {Promise<object>} A promise that resolves to the updated application
+ * object with edge functions enabled.
+ * @throws Will throw an error if the update process fails.
+ * @example
+ * try {
+ *    const updatedApp = await enableEdgeFunctions(12345);
+ *    console.log(updatedApp);
+ * } catch (error) {
+ *    console.error(error);
+ * }
+ */
+async function enableEdgeFunctions(applicationId) {
+  try {
+    const payload = {
+      edge_functions: true,
+    };
+
+    const response = await (await ApplicationService.update(applicationId, payload)).json();
+    return response.results;
+  } catch (error) {
+    debug.error(error);
+    throw error;
+  }
+}
+
+export default enableEdgeFunctions;

package/lib/platform/actions/application/instantiateFunction.actions.js

@@ -0,0 +1,37 @@
+import { debug } from '#utils';
+import ApplicationService from '../../services/application.service.js';
+
+/**
+ * @function
+ * @memberof platform
+ * @name instantiateFunction
+ * @description Instantiates an edge function in the specified application.
+ * @param {string} functionName - The name of the function to be instantiated.
+ * @param {number} functionId - The unique identifier of the function to be instantiated.
+ * @param {number} applicationId - The unique identifier of the application.
+ * @returns {Promise<object>} A promise that resolves to the instantiated edge function object.
+ * @throws Will throw an error if the instantiation process fails.
+ * @example
+ * try {
+ *    const instantiatedFunc = await instantiateFunction('My Function', 123, 456);
+ *    console.log(instantiatedFunc);
+ * } catch (error) {
+ *    console.error(error);
+ * }
+ */
+async function instantiateFunction(functionName, functionId, applicationId) {
+  const payload = {
+    name: functionName,
+    edge_function_id: functionId,
+    args: {},
+  };
+  try {
+    const response = await (await ApplicationService.instantiate(applicationId, payload)).json();
+    return response.results;
+  } catch (error) {
+    debug.error(error);
+    throw error;
+  }
+}
+
+export default instantiateFunction;

package/lib/platform/actions/application/setFunctionAsDefaultRule.actions.js

@@ -0,0 +1,33 @@
+import { debug } from '#utils';
+import ApplicationService from '../../services/application.service.js';
+/**
+ * Sets a function as the default rule in an application's rules engine.
+ * @param {number} applicationId - The ID of the application.
+ * @param {number} functionInstanceId - The ID of the edge function instance.
+ * @returns {Promise<object>} The updated rules engine rules.
+ */
+async function setFunctionAsDefaultRule(applicationId, functionInstanceId) {
+  try {
+    const rulesResponse = await (await ApplicationService.getRules(applicationId)).json();
+    const defaultRuleId = rulesResponse.results[0].id;
+
+    const payload = {
+      behaviors: [
+        {
+          name: 'run_function',
+          target: functionInstanceId,
+        },
+      ],
+    };
+
+    const response = await
+    (await ApplicationService.updateRule(applicationId, defaultRuleId, payload))
+      .json();
+    return response.results;
+  } catch (error) {
+    debug.error(error);
+    throw error;
+  }
+}
+
+export default setFunctionAsDefaultRule;

package/lib/platform/actions/core/auth.actions.js

@@ -0,0 +1,67 @@
+import { vulcan } from '#env';
+import { Messages } from '#constants';
+import { feedback, debug } from '#utils';
+import TokensService from '../../services/tokens.service.js';
+import FunctionService from '../../services/function.service.js';
+
+/**
+ * @function
+ * @memberof platform
+ * @name auth
+ * @description Authenticates the user with the provided credentials.
+ * @param {string} loginOption - The chosen login method. Valid values are
+ * 'username/password' and 'token'.
+ * @param {object} credentials - The user credentials required for authentication.
+ * @param {string} [credentials.username] - Required for 'username/password' option.
+ *  Represents the username for password-based authentication.
+ * @param {string} [credentials.password] - Required for 'username/password' option.
+ * Represents the password for password-based authentication.
+ * @param {string} [credentials.token] - Required for 'token' option.
+ * Represents the personal token for token-based authentication.
+ * @returns {void}
+ * @throws Will throw an error if the authentication process fails.
+ * @example
+ * // For 'username/password' option
+ * try {
+ *    await auth('password', { username: 'exampleUser', password: 'examplePass' });
+ * } catch (error) {
+ *    console.error(error);
+ * }
+ * // For 'token' option
+ * try {
+ *    await auth('token', { token: 'exampleToken' });
+ * } catch (error) {
+ *    console.error(error);
+ * }
+ */
+async function auth(loginOption, credentials) {
+  try {
+    if (loginOption === 'password') {
+      const response = await TokensService.create(credentials.username, credentials.password);
+      const responseJSON = await response.json();
+
+      if (!responseJSON.token) {
+        feedback.error(responseJSON);
+      }
+      if (responseJSON.token) {
+        await vulcan.createVulcanEnv('API_TOKEN', responseJSON.token);
+        feedback.success(Messages.platform.auth.success.api_auth_success);
+      }
+    }
+    if (loginOption === 'token') {
+      await vulcan.createVulcanEnv('API_TOKEN', credentials.token);
+      const validateTokenJSON = await (await FunctionService.getAll()).json();
+      if (validateTokenJSON.results) {
+        feedback.success(Messages.platform.auth.success.auth_success);
+      }
+      if (!validateTokenJSON.results) {
+        throw new Error(JSON.stringify(validateTokenJSON));
+      }
+    }
+  } catch (error) {
+    debug.error(error);
+    feedback.success(Messages.platform.auth.error.auth_failed);
+  }
+}
+
+export default auth;

package/lib/platform/actions/core/deploy.actions.js

@@ -0,0 +1,73 @@
+import { feedback, generateTimestamp, debug } from '#utils';
+import { Messages } from '#constants';
+
+import createApplication from '../application/createApplication.actions.js';
+
+import instantiateFunction from '../application/instantiateFunction.actions.js';
+import enableEdgeFunctions from '../application/enableEdgeFunctions.actions.js';
+import setFunctionAsDefaultRule from '../application/setFunctionAsDefaultRule.actions.js';
+import createDomain from '../domain/createDomain.actions.js';
+import createFunction from '../function/createFunction.actions.js';
+
+/**
+ * @function
+ * @memberof platform
+ * @name deploy
+ * @description Creates a new application from scratch, performing several steps including
+ * function creation, application creation, enabling edge functions, function instantiation,
+ * rule setting, and domain creation. If names are not provided, they will be auto-generated
+ * using a timestamp.
+ * @param {string} [applicationName] - The name of the application to be created. If not provided,
+ * it will be auto-generated as `vulcan-${generateTimestamp()}`.
+ * @param {string} [functionName] - The name of the function to be instantiated. If not provided,
+ * it will be auto-generated as `vulcan-${generateTimestamp()}`.
+ * @param {string} [domainName] - The name of the domain to be created. If not provided, it will be
+ * auto-generated as `vulcan-${generateTimestamp()}`.
+ * @returns {Promise<string>} A promise that resolves to the domain of the newly
+ * created application.
+ * @throws Will throw an error if any step in the deployment process fails.
+ * @example
+ * try {
+ *    const domain = await deploy('myApplication', 'myFunction', 'myDomain');
+ *    console.log('Domain of the new application:', domain);
+ * } catch (error) {
+ *    console.error(error);
+ * }
+ */
+async function deploy(applicationName, functionName, domainName) {
+  try {
+    const timestamp = generateTimestamp();
+    const deployId = `vulcan-${timestamp}`;
+
+    feedback.platform.interactive.await(`[%d/6] - ${Messages.platform.deploy.info.creating_edge_function}`, 1);
+    const generatedFunctionName = functionName || deployId;
+    const edgeFunctionId = (await createFunction(generatedFunctionName)).id;
+
+    feedback.platform.interactive.await(`[%d/6] - ${Messages.platform.deploy.info.creating_edge_application}`, 2);
+    const generatedApplicationName = applicationName || deployId;
+    const edgeApplicationId = (await createApplication(generatedApplicationName)).id;
+
+    feedback.platform.interactive.await(`[%d/6] - ${Messages.platform.deploy.info.activating_edge_function}`, 3);
+    await enableEdgeFunctions(edgeApplicationId);
+
+    feedback.platform.interactive.await(`[%d/6] - ${Messages.platform.deploy.info.instantiating_edge_function}`, 4);
+    const functionInstanceId = (await
+    instantiateFunction(generatedFunctionName, edgeFunctionId, edgeApplicationId)).id;
+
+    feedback.platform.interactive.await(`[%d/6] - ${Messages.platform.deploy.info.creating_rule_engine}`, 5);
+    await setFunctionAsDefaultRule(edgeApplicationId, functionInstanceId);
+
+    feedback.platform.interactive.await(`[%d/6] - ${Messages.platform.deploy.info.creating_domain}`, 6);
+    const generatedDomainName = domainName || deployId;
+    const domain = (await createDomain(generatedDomainName, edgeApplicationId)).domain_name;
+    feedback.platform.interactive.complete(Messages.platform.deploy.success.deploy_finished);
+    feedback.platform.interactive.breakInteractiveChain();
+
+    return domain;
+  } catch (error) {
+    feedback.platform.error(Messages.platform.deploy.error.deploy_failed);
+    debug.error(error);
+    throw error;
+  }
+}
+export default deploy;

package/lib/platform/actions/core/propagation.actions.js

@@ -0,0 +1,75 @@
+import { AzionEdges, Messages } from '#constants';
+import { feedback, debug } from '#utils';
+import open from 'open';
+/**
+ * @function
+ * @memberof platform
+ * @name watchPropagation
+ * @description Monitors the propagation of a domain across the edge networks after the FIRST
+ * deployment. This function fetches the specified domain at regular intervals to check for
+ *  propagation status. It interprets a 404 response as indicating that the domain is still
+ *  propagating. Any other response is taken to mean that the domain has successfully
+ * propagated to the edge networks and is ready for access.
+ * @param {string} domain - The domain to monitor for propagation across the edge networks.
+ * @throws Will throw an error if there is a failure during the monitoring process.
+ * @example
+ * try {
+ *    watchPropagation('myDomain.com');
+ * } catch (error) {
+ *    console.error(error);
+ * }
+ */
+function watchPropagation(domain) {
+  let currentEdgeIndex = 0;
+  let intervalId = null;
+  const f = feedback.propagation; // TODO: workaround -> improve
+
+  const performFetch = async () => {
+    try {
+      const response = await fetch(`https://${domain}`);
+      if (response.status === 404) {
+        f.interactive.await(
+          Messages.platform.propagation.info.propagating(
+            AzionEdges[currentEdgeIndex],
+          ),
+        );
+        currentEdgeIndex = (currentEdgeIndex + 1) % AzionEdges.length;
+      } else {
+        clearInterval(intervalId);
+
+        let remainingEdgeIndex = currentEdgeIndex + 1;
+        const remainingEdgesIntervalId = setInterval(() => {
+          if (remainingEdgeIndex >= AzionEdges.length) {
+            clearInterval(remainingEdgesIntervalId);
+            f.interactive.complete(
+              Messages.platform.propagation.success.propagation_complete,
+            );
+            open(`https://${domain}`);
+            process.exit(0);
+          } else {
+            const remainingEdge = AzionEdges[remainingEdgeIndex];
+            f.interactive.await(
+              Messages.platform.propagation.info.propagating(remainingEdge),
+            );
+            // eslint-disable-next-line no-plusplus
+            remainingEdgeIndex++;
+          }
+        }, 150);
+      }
+    } catch (error) {
+      debug.error(error);
+      f.interactive.fatal(
+        Messages.propagation.errors.watch_propagation_failed,
+      );
+    }
+  };
+
+  // Perform the first fetch immediately
+  performFetch();
+
+  // Start the interval
+  intervalId = setInterval(performFetch, 10000);
+}
+
+// eslint-disable-next-line import/prefer-default-export
+export { watchPropagation };