feat: localstack front-door setup (#92)

feat:
This pull request introduces a local gateway server to the development
workflow, allowing users to run and debug Serverless applications
locally with improved configuration and routing. It adds support for
specifying a custom IaC (Infrastructure as Code) YAML file, implements a
robust local HTTP server with route parsing, and enhances context
resolution for IaC files.

The most important changes are:

**Local Gateway Server Implementation:**

* Introduced a new local HTTP server (`servLocal`) that parses incoming
requests, matches them to resource kinds (such as functions, buckets,
events), and dispatches them to appropriate handlers. This includes
robust parsing of resource identifiers and improved error handling.
(`src/stack/localStack/localServer.ts`, `src/types/localStack/index.ts`)
[[1]](diffhunk://#diff-8f8d2bc2b1e004f4d32fb87251a46ac6a79c4b9d216350c7013c59772c290dceR1-R122)
[[2]](diffhunk://#diff-6648cb6cd8f9b251cd085dbc3ea489c6509a3524096f040cc0d385740129dc38R1-R24)
* Updated `startLocalStack` to use the new server and register handlers
for function routes, with placeholders for additional resource kinds.
(`src/stack/localStack/index.ts`)

**CLI and IaC File Handling Improvements:**

* Added a `--file` (`-f`) option to the `local` CLI command, allowing
users to specify a custom YAML file for the stack, and passed this
location through the execution context. (`src/commands/index.ts`,
`src/commands/local.ts`)
[[1]](diffhunk://#diff-a6a1db61476382a80351bf0b40126b3cfca87878293a3fca70dfe04367f4a11fR108-R119)
[[2]](diffhunk://#diff-7ebaa5db45f467180b1c6d14302d60b301cdeeb31dbb6137303edd16707cb971L4-R15)
* Enhanced the IaC file resolution logic to search for default filenames
in both the project root and specified directories, providing clearer
error messages when files are not found. (`src/common/context.ts`)

**Constants and Configuration:**

* Added `SI_LOCALSTACK_GATEWAY_PORT` constant (default 4567) to
centralize the local server port configuration.
(`src/common/constants.ts`)

Refs: #10

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: Blankll

src/commands/index.ts

@@ -105,16 +105,18 @@ program
 program
   .command('local <stackName>')
   .description('run Serverless application locally for debugging')
+  .option('-f, --file <path>', 'specify the yaml file')
   .option('-s, --stage <stage>', 'specify the stage', 'default')
   .option('-p, --port <port>', 'specify the port', '3000')
   .option('-d, --debug', 'enable debug mode')
   .option('-w, --watch', 'enable file watch', true)
-  .action(async (stackName, { stage, port, debug, watch }) => {
+  .action(async (stackName, { stage, port, debug, watch, file }) => {
     await runLocal(stackName, {
       stage,
       port: Number(port) || 3000,
       debug: !!debug,
       watch: typeof watch === 'boolean' ? watch : true,
+      location: file,
     });
   });
 

src/commands/local.ts

@@ -1,17 +1,18 @@
 import { logger, setContext } from '../common';
 import { startLocalStack } from '../stack/localStack';
 
-export interface RunLocalOptions {
+export type RunLocalOptions = {
   stage: string;
   port: number;
   debug: boolean;
   watch: boolean;
-}
+  location: string | undefined;
+};
 
 export const runLocal = async (stackName: string, opts: RunLocalOptions) => {
-  const { stage, port, debug, watch } = opts;
+  const { stage, port, debug, watch, location } = opts;
 
-  await setContext({ stage });
+  await setContext({ stage, location });
 
   logger.info(
     `run-local starting: stack=${stackName} stage=${stage} port=${port} debug=${debug} watch=${watch}`,

src/common/constants.ts

@@ -2,3 +2,4 @@ export const CODE_ZIP_SIZE_LIMIT = 300 * 1000; // 300 KB ROS TemplateBody size l
 export const OSS_DEPLOYMENT_TIMEOUT = 3000; // in seconds
 export const SI_BOOTSTRAP_FC_PREFIX = 'si-bootstrap-api';
 export const SI_BOOTSTRAP_BUCKET_PREFIX = 'si-bootstrap-artifacts';
+export const SI_LOCALSTACK_GATEWAY_PORT = 4567;

src/common/context.ts

@@ -6,34 +6,55 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { getIamInfo } from './imsClient';
 
 const asyncLocalStorage = new AsyncLocalStorage<Context>();
+const DEFAULT_IAC_FILES = [
+  'serverlessinsight.yml',
+  'serverlessInsight.yml',
+  'ServerlessInsight.yml',
+  'serverless-insight.yml',
+];
 
 export const getIacLocation = (location?: string): string => {
   const projectRoot = path.resolve(process.cwd());
-  if (location) {
-    const candidate = path.isAbsolute(location) ? location : path.resolve(projectRoot, location);
-    if (fs.existsSync(candidate)) {
-      return candidate;
+  const searchTargets = location ? [location] : DEFAULT_IAC_FILES;
+  const attempted = new Set<string>();
+
+  const toAbsolutePath = (target: string) =>
+    path.isAbsolute(target) ? target : path.resolve(projectRoot, target);
+
+  const tryResolveCandidate = (target: string): string | undefined => {
+    const resolved = toAbsolutePath(target);
+    attempted.add(resolved);
+
+    if (!fs.existsSync(resolved)) {
+      return undefined;
     }
-    throw new Error(`IaC file not found at '${candidate}'`);
-  }
 
-  const candidates = [
-    'serverlessinsight.yml',
-    'serverlessInsight.yml',
-    'ServerlessInsight.yml',
-    'serverless-insight.yml',
-  ];
+    const stats = fs.statSync(resolved);
+    if (stats.isDirectory()) {
+      for (const fileName of DEFAULT_IAC_FILES) {
+        const nested = path.join(resolved, fileName);
+        attempted.add(nested);
+        if (fs.existsSync(nested) && fs.statSync(nested).isFile()) {
+          return nested;
+        }
+      }
+      return undefined;
+    }
+
+    return resolved;
+  };
 
-  for (const name of candidates) {
-    const candidate = path.resolve(projectRoot, name);
-    if (fs.existsSync(candidate)) {
-      return candidate;
+  for (const candidate of searchTargets) {
+    const match = tryResolveCandidate(candidate);
+    if (match) {
+      return match;
     }
   }
 
-  throw new Error(
-    `No IaC file found. Tried: ${candidates.map((n) => `'${path.resolve(projectRoot, n)}'`).join(', ')}`,
-  );
+  const attemptedList = Array.from(attempted)
+    .map((n) => `'${n}'`)
+    .join(', ');
+  throw new Error(`No IaC file found. Tried: ${attemptedList}`);
 };
 
 export const setContext = async (

src/stack/localStack/function.ts

@@ -1,6 +1,45 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { ParsedRequest, RouteHandler, RouteKind } from '../../types/localStack';
+import { servLocal } from './localServer';
+
 export * from './event';
 
+const handlers = [
+  {
+    kind: 'si_functions',
+    handler: (req: IncomingMessage, res: ServerResponse, parsed: ParsedRequest) => {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(
+        JSON.stringify({
+          message: `Function request received by local gateway ${parsed}`,
+        }),
+      );
+    },
+  },
+  // {
+  //   kind: 'event',
+  //   handler: async (req: IncomingMessage, res: ServerResponse, parsed: ParsedRequest) => {
+  //     res.writeHead(200, { 'Content-Type': 'application/json' });
+  //     res.end(
+  //       JSON.stringify({
+  //         message: 'Event route invoked locally',
+  //       }),
+  //     );
+  //   },
+  // },
+  // {
+  //   kind: 'bucket',
+  //   handler: async (req: IncomingMessage, res: ServerResponse, parsed: ParsedRequest) => {
+  //     res.writeHead(200, { 'Content-Type': 'application/json' });
+  //     res.end(
+  //       JSON.stringify({
+  //         message: 'Bucket API request received by local gateway',
+  //       }),
+  //     );
+  //   },
+  // },
+];
+
 export const startLocalStack = async () => {
-  // Placeholder for starting local stack logic
-  console.log('Local stack started');
+  await servLocal(handlers as Array<{ kind: RouteKind; handler: RouteHandler }>);
 };

src/stack/localStack/gateway.ts

@@ -0,0 +1,116 @@
+import { ParsedRequest, RouteHandler, RouteKind, ResourceIdentifier } from '../../types/localStack';
+import { logger, SI_LOCALSTACK_GATEWAY_PORT } from '../../common';
+import http, { IncomingMessage, ServerResponse } from 'node:http';
+
+let localServer: http.Server | undefined;
+
+const parseIdentifier = (segment: string): ResourceIdentifier | undefined => {
+  const parts = segment.split('-');
+  if (parts.length < 3) {
+    return undefined;
+  }
+
+  const id = parts.shift()!;
+  const region = parts.pop()!;
+  const name = parts.join('-');
+  if (!id || !name || !region) {
+    return undefined;
+  }
+
+  return { id, name, region };
+};
+
+const cleanPathSegments = (pathname: string): Array<string> =>
+  pathname
+    .split('/')
+    .map((segment) => segment.trim())
+    .filter((segment) => segment.length > 0);
+
+const respondText = (res: ServerResponse, status: number, text: string) => {
+  res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8' });
+  res.end(`${text}\n`);
+};
+
+const parseRequest = (req: IncomingMessage): ParsedRequest | undefined => {
+  const url = new URL(req.url ?? '/', 'http://localhost');
+  const [routeSegment, descriptorSegment, ...rest] = cleanPathSegments(url.pathname);
+
+  const kind = routeSegment as RouteKind;
+  if (!kind || !['si_functions', 'si_buckets', 'si_website_buckets', 'si_events'].includes(kind)) {
+    return undefined;
+  }
+
+  if (!descriptorSegment) {
+    return undefined;
+  }
+
+  const identifier = parseIdentifier(descriptorSegment);
+  if (!identifier) {
+    return undefined;
+  }
+
+  const subPath = rest.length > 0 ? `/${rest.join('/')}` : '/';
+  const query = Object.fromEntries(url.searchParams.entries());
+
+  return {
+    kind,
+    identifier,
+    subPath,
+    query,
+    method: req.method ?? 'GET',
+    rawPath: url.pathname,
+  };
+};
+
+export const servLocal = async (
+  handlers: Array<{ kind: RouteKind; handler: RouteHandler }>,
+): Promise<void> => {
+  if (localServer) {
+    logger.info(`Local gateway already running on http://localhost:${SI_LOCALSTACK_GATEWAY_PORT}`);
+    return;
+  }
+
+  localServer = http.createServer((req, res) => {
+    try {
+      const parsed = parseRequest(req);
+
+      if (!parsed) {
+        respondText(res, 404, 'Route not found');
+        logger.warn(`Local gateway 404 -> ${req.method ?? 'GET'} ${req.url ?? '/'} `);
+        return;
+      }
+      const requestHandler = handlers.find((h) => h.kind === parsed.kind);
+      if (!requestHandler) {
+        respondText(res, 501, `No handler for route kind: ${parsed.kind}`);
+        logger.warn(
+          `Local gateway 501 -> No handler for ${parsed.kind} ${req.method ?? 'GET'} ${
+            req.url ?? '/'
+          }`,
+        );
+        return;
+      }
+      requestHandler.handler(req, res, parsed);
+      logger.info(
+        `Local gateway handled ${parsed.kind}: ${parsed.identifier.name} (${parsed.identifier.region}) ${parsed.subPath}`,
+      );
+    } catch (error) {
+      respondText(res, 500, 'Internal server error');
+      logger.error(
+        { err: error },
+        `Local gateway error -> ${req.method ?? 'GET'} ${req.url ?? '/'}`,
+      );
+    }
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    localServer!.listen(SI_LOCALSTACK_GATEWAY_PORT, '0.0.0.0', () => {
+      logger.info(`Local Server listening on http://localhost:${SI_LOCALSTACK_GATEWAY_PORT}`);
+      resolve();
+    });
+
+    localServer!.once('error', (err) => {
+      logger.error({ err }, 'Failed to start local server');
+      reject(err);
+    });
+  });
+};

src/stack/localStack/index.ts

@@ -0,0 +1,24 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+export type RouteKind = 'si_functions' | 'si_buckets' | 'si_website_buckets' | 'si_events';
+
+export type ResourceIdentifier = {
+  id: string;
+  name: string;
+  region: string;
+};
+
+export type ParsedRequest = {
+  kind: RouteKind;
+  identifier: ResourceIdentifier;
+  subPath: string;
+  method: string;
+  query: Record<string, string>;
+  rawPath: string;
+};
+
+export type RouteHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  parsed: ParsedRequest,
+) => void;