@goldstack/template-lambda-api 0.3.73

package/schemas/package-configuration.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/ThisPackageConfiguration",
+  "definitions": {
+    "ThisPackageConfiguration": {
+      "$ref": "#/definitions/PackageConfiguration",
+      "description": "Configures this lambda.",
+      "title": "Lambda Configuration"
+    },
+    "PackageConfiguration": {
+      "type": "object",
+      "description": "Configuration of this package",
+      "title": "Configuration"
+    }
+  }
+}

package/schemas/package.schema.json

@@ -0,0 +1,224 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/ThisPackage",
+  "definitions": {
+    "ThisPackage": {
+      "type": "object",
+      "properties": {
+        "template": {
+          "$ref": "#/definitions/Template"
+        },
+        "templateVersion": {
+          "$ref": "#/definitions/TemplateVersion"
+        },
+        "name": {
+          "$ref": "#/definitions/Name"
+        },
+        "configuration": {
+          "$ref": "#/definitions/ThisPackageConfiguration"
+        },
+        "deployments": {
+          "$ref": "#/definitions/LambdaApiDeployments"
+        },
+        "$schema": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "$schema",
+        "configuration",
+        "deployments",
+        "name",
+        "template",
+        "templateVersion"
+      ],
+      "additionalProperties": false,
+      "description": "A deployment for a lambda API.",
+      "title": "Lambda API Package"
+    },
+    "Template": {
+      "type": "string",
+      "description": "Name of the template used for creating this package.",
+      "title": "Template",
+      "pattern": "^[^\\s]*$"
+    },
+    "TemplateVersion": {
+      "type": "string",
+      "description": "Latest template version that was applied to this package.",
+      "title": "Template Version"
+    },
+    "Name": {
+      "type": "string",
+      "description": "Name of this package.",
+      "title": "Package Name"
+    },
+    "ThisPackageConfiguration": {
+      "$ref": "#/definitions/PackageConfiguration",
+      "description": "Configures this lambda.",
+      "title": "Lambda Configuration"
+    },
+    "PackageConfiguration": {
+      "type": "object",
+      "description": "Configuration of this package",
+      "title": "Configuration"
+    },
+    "LambdaApiDeployments": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ThisDeployment"
+      },
+      "description": "Places where the lambda should be deployed to.",
+      "title": "Deployments"
+    },
+    "ThisDeployment": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "$ref": "#/definitions/DeploymentName"
+        },
+        "configuration": {
+          "$ref": "#/definitions/ThisDeploymentConfiguration"
+        },
+        "terraformVariables": {
+          "$ref": "#/definitions/TerraformVariables"
+        },
+        "tfStateKey": {
+          "$ref": "#/definitions/TerraformStateKey"
+        },
+        "awsRegion": {
+          "$ref": "#/definitions/AWSDeploymentRegion"
+        },
+        "awsUser": {
+          "$ref": "#/definitions/AWSUserName"
+        }
+      },
+      "required": [
+        "awsRegion",
+        "awsUser",
+        "configuration",
+        "name"
+      ]
+    },
+    "DeploymentName": {
+      "type": "string",
+      "description": "Identifier for this deployment. No spaces allowed in name.",
+      "title": "Deployment Name",
+      "pattern": "^[^\\s]*$"
+    },
+    "ThisDeploymentConfiguration": {
+      "type": "object",
+      "properties": {
+        "lambdaNamePrefix": {
+          "type": "string",
+          "description": "The prefix to be used for names of the generated lambdas for the API endpoints.",
+          "title": "Lambda Name Prefix",
+          "pattern": "^[A-Za-z0-9-_]*$"
+        },
+        "apiDomain": {
+          "$ref": "#/definitions/APIDomain"
+        },
+        "hostedZoneDomain": {
+          "$ref": "#/definitions/HostedZoneDomain"
+        },
+        "cors": {
+          "$ref": "#/definitions/CorsHeader"
+        },
+        "lambdas": {
+          "$ref": "#/definitions/LambdaRoutesConfig"
+        }
+      },
+      "required": [
+        "apiDomain",
+        "hostedZoneDomain",
+        "lambdas"
+      ]
+    },
+    "APIDomain": {
+      "type": "string",
+      "description": "The domain name that the API should be deployed to (e.g. api.mysite.com)",
+      "title": "API Domain",
+      "pattern": "^[^\\s]*"
+    },
+    "HostedZoneDomain": {
+      "type": "string",
+      "description": "The domain name of the Route 53 hosted zone that the domain for this API should be added to.",
+      "title": "Hosted Zone Domain",
+      "pattern": "^[^\\s]*"
+    },
+    "CorsHeader": {
+      "type": "string",
+      "description": "Optional URL for an UI that should be allowed to access this server.",
+      "title": "CORS Header",
+      "pattern": "^[^\\s]*"
+    },
+    "LambdaRoutesConfig": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/LambdaRouteConfig"
+      }
+    },
+    "LambdaRouteConfig": {
+      "type": "object",
+      "properties": {
+        "function_name": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "function_name"
+      ],
+      "additionalProperties": false
+    },
+    "TerraformVariables": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/TerraformVariable"
+      },
+      "description": "Define which of the deployment variables will be made available for terraform.",
+      "title": "Terraform Variables"
+    },
+    "TerraformVariable": {
+      "type": "string",
+      "description": "Name of the property that should be converted into a Terraform variable.",
+      "title": "Terraform Variable"
+    },
+    "TerraformStateKey": {
+      "type": "string",
+      "description": "Key used for Terraform state persisted in Terraform state bucket.\n\nWill be auto-generated upon first deployment if not provided.",
+      "title": "Terraform State Key"
+    },
+    "AWSDeploymentRegion": {
+      "type": "string",
+      "enum": [
+        "us-east-1",
+        "us-east-2",
+        "us-west-1",
+        "us-west-2",
+        "af-south-1",
+        "ap-east-1",
+        "ap-south-1",
+        "ap-northeast-3",
+        "ap-northeast-2",
+        "ap-southeast-1",
+        "ap-southeast-2",
+        "ap-northeast-1",
+        "ca-central-1",
+        "eu-central-1",
+        "eu-west-1",
+        "eu-west-2",
+        "eu-south-1",
+        "eu-west-3",
+        "eu-north-1",
+        "me-south-1",
+        "sa-east-1"
+      ],
+      "description": "AWS region that infrastructure should be deployed to.",
+      "title": "AWS Deployment Region"
+    },
+    "AWSUserName": {
+      "type": "string",
+      "description": "Name of the AWS user that is used to perform the deployment.",
+      "title": "AWS User Name"
+    }
+  }
+}

package/scripts/generateSchemas.ts

@@ -0,0 +1,3 @@
+import { run } from '@goldstack/utils-package-config-generate';
+
+run(process.argv);

package/src/generateLambdaConfig.spec.ts

@@ -0,0 +1,74 @@
+import { readLambdaConfig } from '@goldstack/utils-aws-lambda';
+import assert from 'assert';
+import {
+  generateFunctionName,
+  generateLambdaConfig,
+} from './generateLambdaConfig';
+import { LambdaApiDeployment } from './templateLambdaApi';
+import { getOutDirForLambda } from './templateLambdaApiBuild';
+
+const dummyDeployment: LambdaApiDeployment = {
+  awsRegion: 'ap-east-1',
+  awsUser: 'dummy',
+  configuration: {
+    lambdaNamePrefix: 'test-lambdas',
+    apiDomain: 'domain',
+    hostedZoneDomain: 'domain',
+    lambdas: {},
+  },
+  name: 'test',
+};
+
+describe('Generate Lambda config', () => {
+  const routesConfig = readLambdaConfig('./testData');
+  const config = generateLambdaConfig(dummyDeployment, routesConfig);
+  test('Should render config for Terraform', () => {
+    assert(config['$default'].function_name);
+    assert(
+      config['ANY /folder/nested'].function_name.indexOf(
+        dummyDeployment.configuration.lambdaNamePrefix || 'fail'
+      ) !== -1
+    );
+  });
+  test('Should determine correct output dirs for dist', () => {
+    const nestedRoute = routesConfig.find((e) => e.path === '/folder/nested');
+    assert(nestedRoute);
+    const dir = getOutDirForLambda(nestedRoute);
+    assert(dir === './distLambda/folder/nested');
+  });
+  test('Should determine path parametmers for file names', () => {
+    const nestedRoute = routesConfig.find(
+      (e) => e.path === '/folder/{pathparam}'
+    );
+    assert(nestedRoute);
+    const functionName = generateFunctionName(dummyDeployment, nestedRoute);
+    assert(functionName.indexOf('folder') !== -1);
+    assert(functionName.indexOf('{') === -1);
+    assert(functionName.indexOf('}') === -1);
+  });
+  test('Should determine path parametmers for folder names', () => {
+    const nestedRoute = routesConfig.find(
+      (e) => e.path === '/resource/{path}/object'
+    );
+    assert(nestedRoute);
+    const functionName = generateFunctionName(dummyDeployment, nestedRoute);
+    assert(functionName.indexOf('object') !== -1);
+    assert(functionName.indexOf('resource') !== -1);
+    assert(functionName.indexOf('{') === -1);
+    assert(functionName.indexOf('}') === -1);
+  });
+  test('Should provide a correct path for a nested index file', () => {
+    const nestedRoute = routesConfig.find((e) => e.path === '/health');
+    assert(nestedRoute);
+
+    const functionName = generateFunctionName(dummyDeployment, nestedRoute);
+    assert(functionName.indexOf('health') !== -1);
+  });
+  test('Should provide a correct path for a file in the API root', () => {
+    const nestedRoute = routesConfig.find((e) => e.path === '/resource');
+    assert(nestedRoute);
+
+    const functionName = generateFunctionName(dummyDeployment, nestedRoute);
+    assert(functionName.match(/resource/g)?.length === 1);
+  });
+});

package/src/generateLambdaConfig.ts

@@ -0,0 +1,61 @@
+import { LambdaConfig } from '@goldstack/utils-aws-lambda';
+import {
+  LambdaRoutesConfig,
+  LambdaApiDeployment,
+} from './types/LambdaApiPackage';
+
+const santiseFunctionName = (input: string): string => {
+  return input
+    .replace(/\//g, '-')
+    .replace(/\$/g, '_')
+    .replace(/\{/g, '_')
+    .replace(/\}/g, '_')
+    .replace(/\+/g, '_')
+    .replace(/[^\w\-_]/gi, '_');
+};
+
+/**
+ * Generates a valid function name for a route
+ */
+export const generateFunctionName = (
+  deployment: LambdaApiDeployment,
+  config: LambdaConfig
+): string => {
+  let name = config.name;
+  if (name === '$default') {
+    // '$' is not a valid character in a lambda function name
+    name = 'default_gateway_lambda_2281';
+  }
+  if (name === '$index') {
+    name = 'index_root_lambda_4423';
+  }
+  name = santiseFunctionName(name);
+
+  let pathPrefix = '';
+  const segments = config.path.split('/');
+  if (segments.length === 2 && name === 'index_root_lambda_4423') {
+    pathPrefix = `${segments[1]}-`;
+  }
+  if (segments.length > 2) {
+    segments.shift(); // remove first element since path starts with '/' and thus the first element is always ''
+    segments.pop(); // remove the last element since that is the name of the function in the route
+    pathPrefix = santiseFunctionName(segments.join('-'));
+    pathPrefix = `${pathPrefix}-`;
+  }
+
+  name = `${pathPrefix}${name}`;
+  name = (`${deployment.configuration.lambdaNamePrefix}-` || '') + name;
+  return name;
+};
+
+export const generateLambdaConfig = (
+  deployment: LambdaApiDeployment,
+  config: LambdaConfig[]
+): LambdaRoutesConfig => {
+  return config.reduce((last, curr) => {
+    last[curr.route] = {
+      function_name: generateFunctionName(deployment, curr),
+    };
+    return last;
+  }, {});
+};

package/src/templateLambdaApi.ts

@@ -0,0 +1,82 @@
+import { buildCli, buildDeployCommands } from '@goldstack/utils-package';
+import { wrapCli } from '@goldstack/utils-cli';
+import { infraCommands } from '@goldstack/utils-terraform';
+import { deployCli } from './templateLambdaApiDeploy';
+import { terraformAwsCli } from '@goldstack/utils-terraform-aws';
+import { PackageConfig } from '@goldstack/utils-package-config';
+import { writePackageConfig } from '@goldstack/utils-package';
+export * from './types/LambdaApiPackage';
+import yargs from 'yargs';
+import fs from 'fs';
+import {
+  LambdaApiPackage,
+  LambdaApiDeployment,
+} from './types/LambdaApiPackage';
+import { readLambdaConfig } from '@goldstack/utils-aws-lambda';
+import { generateLambdaConfig } from './generateLambdaConfig';
+import { defaultRoutesPath } from './templateLambdaConsts';
+import { buildLambdas } from './templateLambdaApiBuild';
+
+export const run = async (args: string[]): Promise<void> => {
+  await wrapCli(async () => {
+    const argv = buildCli({
+      yargs,
+      deployCommands: buildDeployCommands(),
+      infraCommands: infraCommands(),
+    })
+      .command('build [deployment]', 'Build all lambdas', () => {
+        return yargs.positional('deployment', {
+          type: 'string',
+          describe: 'Name of the deployment this command should be applied to',
+          default: '',
+        });
+      })
+      .help().argv;
+
+    const packageConfig = new PackageConfig<
+      LambdaApiPackage,
+      LambdaApiDeployment
+    >({
+      packagePath: './',
+    });
+
+    const config = packageConfig.getConfig();
+
+    // update routes
+    if (!fs.existsSync('./src/routes')) {
+      throw new Error(
+        'Please specify lambda function handlers in ./src/routes so that API Gateway route configuration can be generated.'
+      );
+    }
+    const lambdaRoutes = readLambdaConfig(defaultRoutesPath);
+    config.deployments = config.deployments.map((e) => {
+      const lambdasConfigs = generateLambdaConfig(e, lambdaRoutes);
+      e.configuration.lambdas = lambdasConfigs;
+      return e;
+    });
+    writePackageConfig(config);
+
+    const command = argv._[0];
+    const [, , , ...opArgs] = args;
+
+    if (command === 'infra') {
+      await terraformAwsCli(opArgs);
+      return;
+    }
+
+    if (command === 'build') {
+      await buildLambdas(lambdaRoutes);
+      return;
+    }
+
+    if (command === 'deploy') {
+      await deployCli(
+        packageConfig.getDeployment(config, opArgs[0]),
+        lambdaRoutes
+      );
+      return;
+    }
+
+    throw new Error('Unknown command: ' + command);
+  });
+};

package/src/templateLambdaApiBuild.ts

@@ -0,0 +1,33 @@
+import { build } from 'esbuild';
+import { pnpPlugin } from '@yarnpkg/esbuild-plugin-pnp';
+import { LambdaConfig } from '@goldstack/utils-aws-lambda';
+import { mkdir } from '@goldstack/utils-sh';
+import { defaultRoutesPath } from './templateLambdaConsts';
+
+export const getOutDirForLambda = (config: LambdaConfig): string => {
+  if (config.path === '$default') {
+    return `./distLambda/${config.path}`;
+  }
+  return `./distLambda${config.path}`;
+};
+
+export const getOutFileForLambda = (config: LambdaConfig): string => {
+  return `${getOutDirForLambda(config)}/lambda.js`;
+};
+
+export const buildLambdas = async (configs: LambdaConfig[]): Promise<void> => {
+  for await (const config of configs) {
+    mkdir('-p', getOutDirForLambda(config));
+    await build({
+      plugins: [pnpPlugin()],
+      bundle: true,
+      entryPoints: [`${defaultRoutesPath}/${config.relativeFilePath}`],
+      external: ['aws-sdk'],
+      minify: true,
+      format: 'cjs',
+      target: 'node12.0',
+      sourcemap: true,
+      outfile: getOutFileForLambda(config),
+    });
+  }
+};

package/src/templateLambdaApiDeploy.ts

@@ -0,0 +1,48 @@
+import { LambdaApiDeployment } from './types/LambdaApiPackage';
+import { getAWSUser } from '@goldstack/infra-aws';
+import { deployFunction, LambdaConfig } from '@goldstack/utils-aws-lambda';
+
+import { readLambdaConfig } from '@goldstack/utils-aws-lambda';
+import { defaultRoutesPath } from './templateLambdaConsts';
+
+import { mkdir } from '@goldstack/utils-sh';
+import { generateFunctionName } from './generateLambdaConfig';
+import { getOutDirForLambda } from './templateLambdaApiBuild';
+
+interface DeployLambdaParams {
+  deployment: LambdaApiDeployment;
+  config: LambdaConfig[];
+}
+
+export const deployLambdas = async (
+  params: DeployLambdaParams
+): Promise<void> => {
+  const lambdaConfig = readLambdaConfig(defaultRoutesPath);
+
+  const operations = lambdaConfig.map(async (config) => {
+    const functionName = generateFunctionName(params.deployment, config);
+    console.log(`[${functionName}]: Starting deployment`);
+    const functionDir = getOutDirForLambda(config);
+    mkdir('-p', functionDir);
+    const targetArchive = `${functionDir}/${config.name}.zip`;
+    await deployFunction({
+      targetArchiveName: targetArchive,
+      lambdaPackageDir: functionDir,
+      awsCredentials: await getAWSUser(params.deployment.awsUser),
+      region: params.deployment.awsRegion,
+      functionName,
+    });
+    console.log(`[${functionName}]: Deployment completed`);
+  });
+  await Promise.all(operations);
+};
+
+export const deployCli = async (
+  deployment: LambdaApiDeployment,
+  config: LambdaConfig[]
+): Promise<void> => {
+  await deployLambdas({
+    deployment,
+    config,
+  });
+};

package/src/templateLambdaConsts.ts

@@ -0,0 +1 @@
+export const defaultRoutesPath = './src/routes';

package/src/types/LambdaApiPackage.ts

@@ -0,0 +1,89 @@
+import { AWSDeployment } from '@goldstack/infra-aws';
+import { TerraformDeployment } from '@goldstack/utils-terraform';
+import { Deployment, DeploymentConfiguration } from '@goldstack/infra';
+import { Package, Configuration } from '@goldstack/utils-package';
+
+/**
+ * The prefix to be used for names of the generated lambdas for the API endpoints.
+ *
+ * @title Lambda Name Prefix
+ * @pattern ^[A-Za-z0-9-_]*$
+ */
+type LambdaNamePrefix = string;
+
+/**
+ * The domain name that the API should be deployed to (e.g. api.mysite.com)
+ *
+ * @title API Domain
+ * @pattern ^[^\s]*
+ */
+export type APIDomain = string;
+
+/**
+ * The domain name of the Route 53 hosted zone that the domain for this API should be added to.
+ *
+ * @title Hosted Zone Domain
+ * @pattern ^[^\s]*
+ */
+export type HostedZoneDomain = string;
+
+/**
+ * Optional URL for an UI that should be allowed to access this server.
+ *
+ * @title CORS Header
+ * @pattern ^[^\s]*
+ */
+export type CorsHeader = string;
+
+export interface LambdaRouteConfig {
+  function_name: string;
+}
+
+export type LambdaRoutesConfig = {
+  [key: string]: LambdaRouteConfig;
+};
+
+export interface ThisDeploymentConfiguration extends DeploymentConfiguration {
+  lambdaNamePrefix?: LambdaNamePrefix;
+  apiDomain: APIDomain;
+  hostedZoneDomain: HostedZoneDomain;
+  cors?: CorsHeader;
+  lambdas: LambdaRoutesConfig;
+}
+
+export interface ThisDeployment
+  extends Deployment,
+    AWSDeployment,
+    TerraformDeployment {
+  configuration: ThisDeploymentConfiguration;
+}
+
+/**
+ * Places where the lambda should be deployed to.
+ *
+ * @title Deployments
+ */
+export type LambdaApiDeployments = ThisDeployment[];
+
+/**
+ * Configures this lambda.
+ *
+ * @title Lambda Configuration
+ *
+ */
+export type ThisPackageConfiguration = Configuration;
+
+/**
+ * A deployment for a lambda API.
+ *
+ * @title Lambda API Package
+ */
+export interface ThisPackage extends Package {
+  configuration: ThisPackageConfiguration;
+  deployments: LambdaApiDeployments;
+}
+
+export { ThisDeploymentConfiguration as LambdaApiDeploymentConfiguration };
+export { ThisDeployment as LambdaApiDeployment };
+export { ThisPackageConfiguration as LambdaApiConfiguration };
+export { ThisPackage as LambdaApiPackage };

package/tsconfig.generate.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "include": [
+    "./src/**/*"
+  ],
+  "compilerOptions": {
+    "incremental": false,
+    "declarationMap": false,
+    "outDir": "dist",
+    "baseUrl": "."
+  }
+}