Support function entry points (#301)

.changeset/fluffy-llamas-fix.md

@@ -0,0 +1,5 @@
+---
+'skuba': patch
+---
+
+**template/lambda-sqs-worker:** Add `start` script

.changeset/rich-tools-flow.md

@@ -0,0 +1,19 @@
+---
+'skuba': minor
+---
+
+**node, start:** Support function entry points
+
+You can now specify an entry point that targets an exported function:
+
+```bash
+skuba start --port 12345 src/app.ts#handler
+```
+
+This starts up a local HTTP server that you can POST arguments to:
+
+```bash
+curl --data '["event", {"awsRequestId": "123"}]' --include localhost:12345
+```
+
+You may find this useful to run Lambda function handlers locally.

.changeset/strong-fans-burn.md

@@ -0,0 +1,5 @@
+---
+'skuba': patch
+---
+
+**node, start:** Support `--port` option

README.md

@@ -302,6 +302,28 @@ Your entry point can be a simple module that runs on load:
 console.log('Hello world!');
 ```
 
+#### Start a Lambda function handler
+
+Your entry point can target an exported function:
+
+```bash
+skuba start --port 12345 src/app.ts#handler
+```
+
+```typescript
+export const handler = async (event: unknown, ctx: unknown) => {
+  // ...
+
+  return;
+};
+```
+
+This starts up a local HTTP server that you can POST arguments to:
+
+```bash
+curl --data '["event", {"awsRequestId": "123"}]' --include localhost:12345
+```
+
 #### Start an HTTP server
 
 Your entry point should export:

package.json

@@ -76,6 +76,7 @@
     "read-pkg-up": "^7.0.1",
     "runtypes": "^5.0.1",
     "semantic-release": "^17.2.3",
+    "serialize-error": "^7.0.1",
     "source-map-support": "^0.5.19",
     "ts-jest": "^26.4.1",
     "ts-node": "^9.0.0",

src/cli/configure/getEntryPoint.ts

@@ -38,7 +38,10 @@ export const getEntryPoint = ({
     name: 'entryPoint',
     result: (value) => (value.endsWith('.ts') ? value : `${value}.ts`),
     validate: async (value) => {
-      const exists = await tsFileExists(path.join(destinationRoot, value));
+      // Support exported function targeting, e.g. `src/module.ts#callMeMaybe`
+      const [modulePath] = value.split('#', 2);
+
+      const exists = await tsFileExists(path.join(destinationRoot, modulePath));
 
       return exists || `${chalk.bold(value)} is not a TypeScript file.`;
     },

src/cli/node.ts

@@ -23,13 +23,17 @@ const parseArgs = () => {
   return {
     entryPoint,
     inspect,
+    port: Number(yargs.port) || undefined,
   };
 };
 
 export const node = async () => {
   const args = parseArgs();
 
-  const [port, isBabel] = await Promise.all([getPort(), isBabelFromManifest()]);
+  const [availablePort, isBabel] = await Promise.all([
+    getPort(),
+    isBabelFromManifest(),
+  ]);
 
   const exec = createExec({
     env: isBabel ? undefined : { __SKUBA_REGISTER_MODULE_ALIASES: '1' },
@@ -42,13 +46,13 @@ export const node = async () => {
       '--extensions',
       ['.js', '.json', '.ts'].join(','),
       '--require',
-      path.join('skuba', 'lib', 'register'),
+      path.posix.join('skuba', 'lib', 'register'),
       ...(args.entryPoint === null
         ? []
         : [
             path.join(__dirname, '..', 'wrapper.js'),
             args.entryPoint,
-            String(port),
+            String(args.port ?? availablePort),
           ]),
     );
   }
@@ -57,10 +61,14 @@ export const node = async () => {
     'ts-node',
     ...args.inspect,
     '--require',
-    path.join('skuba', 'lib', 'register'),
+    path.posix.join('skuba', 'lib', 'register'),
     '--transpile-only',
     ...(args.entryPoint === null
       ? []
-      : [path.join(__dirname, '..', 'wrapper'), args.entryPoint, String(port)]),
+      : [
+          path.join(__dirname, '..', 'wrapper'),
+          args.entryPoint,
+          String(args.port ?? availablePort),
+        ]),
   );
 };

src/cli/start.ts

@@ -29,11 +29,12 @@ const parseArgs = async () => {
   return {
     entryPoint,
     inspect,
+    port: Number(yargs.port) || undefined,
   };
 };
 
 export const start = async () => {
-  const [args, port, isBabel] = await Promise.all([
+  const [args, availablePort, isBabel] = await Promise.all([
     parseArgs(),
     getPort(),
     isBabelFromManifest(),
@@ -55,22 +56,22 @@ export const start = async () => {
       '--extensions',
       ['.js', '.json', '.ts'].join(','),
       '--require',
-      path.join('skuba', 'lib', 'register'),
+      path.posix.join('skuba', 'lib', 'register'),
       path.join(__dirname, '..', 'wrapper.js'),
       args.entryPoint,
-      String(port),
+      String(args.port ?? availablePort),
     );
   }
 
   return execProcess(
     'ts-node-dev',
     ...args.inspect,
     '--require',
-    path.join('skuba', 'lib', 'register'),
+    path.posix.join('skuba', 'lib', 'register'),
     '--respawn',
     '--transpile-only',
     path.join(__dirname, '..', 'wrapper'),
     args.entryPoint,
-    String(port),
+    String(args.port ?? availablePort),
   );
 };

src/utils/validation.ts

@@ -1,3 +1,8 @@
+export const isFunction = (
+  data: unknown,
+): data is (...args: unknown[]) => unknown | Promise<unknown> =>
+  typeof data === 'function';
+
 export const isObject = (
   value: unknown,
 ): value is Record<PropertyKey, unknown> =>

src/wrapper/functionHandler.ts

@@ -0,0 +1,38 @@
+import { log } from '../utils/logging';
+import { isFunction, isObject } from '../utils/validation';
+
+import {
+  createRequestListenerFromFunction,
+  serveRequestListener,
+} from './http';
+
+interface Args {
+  availablePort?: number;
+  entryPoint: unknown;
+  functionName: string;
+}
+
+/**
+ * Create an HTTP server that calls into an exported function.
+ */
+export const runFunctionHandler = ({
+  availablePort,
+  entryPoint,
+  functionName,
+}: Args) => {
+  if (!isObject(entryPoint)) {
+    log.subtle(log.bold(functionName), 'is not exported');
+    return;
+  }
+
+  const fn = entryPoint[functionName];
+
+  if (!isFunction(fn)) {
+    log.subtle(log.bold(functionName), 'is not a function');
+    return;
+  }
+
+  const requestListener = createRequestListenerFromFunction(fn);
+
+  return serveRequestListener(requestListener, availablePort);
+};

src/wrapper/http.ts

@@ -0,0 +1,69 @@
+import http from 'http';
+import { AddressInfo } from 'net';
+
+import { serializeError } from 'serialize-error';
+
+import { log } from '../utils/logging';
+
+/**
+ * Create an HTTP request listener based on the supplied function.
+ *
+ * - The request body is JSON parsed and passed into the function as parameters.
+ * - The function's return value is JSON stringified into the response body.
+ */
+export const createRequestListenerFromFunction = (
+  fn: (...args: unknown[]) => unknown | Promise<unknown>,
+): http.RequestListener => async (req, res) => {
+  const writeJsonResponse = (statusCode: number, jsonResponse: unknown) =>
+    new Promise<void>((resolve) =>
+      res
+        .writeHead(statusCode, { 'Content-Type': 'application/json' })
+        .end(JSON.stringify(jsonResponse, null, 2), 'utf8', resolve),
+    );
+
+  try {
+    const requestBody = await new Promise<string>((resolve, reject) => {
+      let data = '';
+
+      req
+        .on('data', (chunk) => (data += chunk))
+        .on('end', () => resolve(data))
+        .on('error', (err) => reject(err));
+    });
+
+    const jsonRequest: unknown = JSON.parse(requestBody);
+
+    // Pass a non-array request body as the first parameter
+    const args = Array.isArray(jsonRequest) ? jsonRequest : [jsonRequest];
+
+    const response: unknown = await fn(...args);
+
+    await writeJsonResponse(200, response);
+  } catch (err: unknown) {
+    await writeJsonResponse(500, serializeError(err));
+  }
+};
+
+/**
+ * Create a HTTP server based on the supplied `http.RequestListener`.
+ *
+ * This function resolves when the server is closed.
+ */
+export const serveRequestListener = (
+  requestListener: http.RequestListener,
+  port?: number,
+) => {
+  const server = http.createServer(requestListener);
+
+  return new Promise<void>((resolve, reject) =>
+    server
+      .listen(port)
+      .on('close', resolve)
+      .on('error', reject)
+      .on('listening', () => {
+        const address = server.address() as AddressInfo;
+
+        log.ok('listening on port', log.bold(address.port));
+      }),
+  );
+};