sst-http 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# sst-http
+
+Decorator-based HTTP routing for [SST v3](https://sst.dev) that keeps your app on a single Lambda handler while still wiring routes directly into API Gateway. Build routes with NestJS-style decorators, secure them with Firebase JWT authorizers, and generate an infra-ready manifest from your source.
+
+## Install
+
+```bash
+pnpm add sst-http
+```
+
+## Define Routes
+
+Create routed functions anywhere in your project – no controller classes required.
+
+```ts
+// src/routes/users.ts
+import { Get, Post, FirebaseAuth, json } from "sst-http";
+
+export class UserRoutes {
+  @Get("/users/{id}")
+  @FirebaseAuth()
+  static async getUser({ params }: { params: { id: string } }) {
+    return json(200, { id: params.id });
+  }
+
+  @Post("/users")
+  @FirebaseAuth({ optional: false })
+  static async createUser({ body }: { body: { email: string } }) {
+    return json(201, { ok: true, email: body.email });
+  }
+}
+
+export const getUser = UserRoutes.getUser;
+export const createUser = UserRoutes.createUser;
+```
+
+Enable name-based inference once at bootstrap if you prefer omitting explicit path strings:
+
+```ts
+import { configureRoutes } from "sst-http";
+
+configureRoutes({ inferPathFromName: true });
+```
+
+Parameter decorators are available when you want granular control:
+
+```ts
+import { Body, Post } from "sst-http";
+import { z } from "zod";
+
+const CreateTodo = z.object({ title: z.string().min(1) });
+
+export class TodoRoutes {
+  @Post("/todos")
+  static createTodo(@Body(CreateTodo) payload: z.infer<typeof CreateTodo>) {
+    // payload is validated JSON
+    return { statusCode: 201, body: JSON.stringify(payload) };
+  }
+}
+
+export const createTodo = TodoRoutes.createTodo;
+```
+
+> **Note**
+> API Gateway route keys expect `{param}` placeholders. The router accepts either `{param}` or `:param` at runtime, but manifests and infra wiring emit `{param}` so your deployed routes line up with AWS.
+
+## Single Lambda Entry
+
+All decorated modules register themselves on import. The single exported handler performs routing and response formatting for both REST and HTTP API Gateway payloads.
+
+```ts
+// src/server.ts
+import "reflect-metadata";
+import { createHandler } from "sst-http";
+
+import "./routes/users";
+import "./routes/health";
+
+export const handler = createHandler();
+```
+
+Helpers such as `json()`, `text()`, and `noContent()` are available for concise responses, and thrown `HttpError` instances are turned into normalized JSON error payloads.
+
+## Scan & Manifest
+
+Use the CLI to inspect your source tree and materialize a routes manifest for infra wiring.
+
+```bash
+pnpm sst-http scan --glob "src/routes/**/*.ts" --out routes.manifest.json
+```
+
+Pass `--infer-name` to map routes without explicit paths using the kebab-case function name (matching the runtime `configureRoutes({ inferPathFromName: true })`).
+
+## Firebase JWT Authorizer
+
+Mark a route with `@FirebaseAuth()` and the manifest records it as protected. The core wiring function sets up an API Gateway JWT authorizer that points at your Firebase project (issuer `https://securetoken.google.com/<projectId>` and matching audience). Optional roles and optional-auth flags flow through to the adapter so you can fine-tune scopes.
+
+## Wire API Gateway
+
+`sst-http/infra` ships with a manifest-driven wiring utility plus adapters for HTTP API (ApiGatewayV2) and REST API (ApiGateway). The example below uses the HTTP API adapter inside `sst.config.ts`.
+
+```ts
+// sst.config.ts
+export default $config({
+  app() {
+    return { name: "sst-http-demo", home: "aws" };
+  },
+  async run() {
+    const {
+      loadRoutesManifest,
+      wireApiFromManifest,
+      httpApiAdapter,
+    } = await import("sst-http/infra");
+
+    const manifest = loadRoutesManifest("routes.manifest.json");
+    const { api, registerRoute, ensureJwtAuthorizer } = httpApiAdapter({
+      apiName: "Api",
+      apiArgs: {
+        transform: {
+          route: {
+            handler: {
+              runtime: "nodejs20.x",
+              timeout: "10 seconds",
+              memory: "512 MB",
+            },
+          },
+        },
+      },
+    });
+
+    wireApiFromManifest(manifest, {
+      handlerFile: "src/server.handler",
+      firebaseProjectId: process.env.FIREBASE_PROJECT_ID!,
+      registerRoute,
+      ensureJwtAuthorizer,
+    });
+
+    return { ApiUrl: api.url };
+  },
+});
+```
+
+Swap in `restApiAdapter` if you prefer API Gateway REST APIs—the wiring contract is identical.
+
+## Publishing
+
+```bash
+npm login
+npm version patch
+pnpm run release
+```
+
+The release script builds the ESM/CJS bundles via `tsup` before publishing.
+
+## License
+
+MIT

package/dist/cli.cjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/cli.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_process = require("process");
+var import_ts_morph = require("ts-morph");
+var METHOD_DECORATORS = {
+  Get: "GET",
+  Post: "POST",
+  Put: "PUT",
+  Patch: "PATCH",
+  Delete: "DELETE",
+  Head: "HEAD",
+  Options: "OPTIONS"
+};
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || command === "--help" || command === "-h") {
+    printUsage();
+    return;
+  }
+  switch (command) {
+    case "scan": {
+      await runScan(rest);
+      return;
+    }
+    default: {
+      import_node_process.stderr.write(`Unknown command: ${command}
+`);
+      printUsage();
+      process.exitCode = 1;
+    }
+  }
+}
+async function runScan(args) {
+  const options = parseScanArgs(args);
+  const project = options.project ? new import_ts_morph.Project({ tsConfigFilePath: options.project }) : new import_ts_morph.Project();
+  if (options.globs.length === 0) {
+    options.globs.push("src/**/*.ts");
+  }
+  project.addSourceFilesAtPaths(options.globs);
+  const manifest = { routes: [] };
+  for (const sourceFile of project.getSourceFiles()) {
+    for (const fn of sourceFile.getFunctions()) {
+      if (!fn.isExported() && !fn.isDefaultExport()) {
+        continue;
+      }
+      const route = extractRoute(fn, options.inferName);
+      if (route) {
+        manifest.routes.push(route);
+      }
+    }
+    for (const cls of sourceFile.getClasses()) {
+      if (!cls.isExported() && !cls.isDefaultExport()) {
+        continue;
+      }
+      for (const method of cls.getMethods()) {
+        if (!method.isStatic()) {
+          continue;
+        }
+        const route = extractRoute(method, options.inferName);
+        if (route) {
+          manifest.routes.push(route);
+        }
+      }
+    }
+  }
+  manifest.routes.sort((a, b) => {
+    if (a.path === b.path) {
+      return a.method.localeCompare(b.method);
+    }
+    return a.path.localeCompare(b.path);
+  });
+  const outPath = (0, import_node_path.resolve)((0, import_node_process.cwd)(), options.outFile);
+  (0, import_node_fs.writeFileSync)(outPath, JSON.stringify(manifest, null, 2));
+  import_node_process.stdout.write(`Wrote ${manifest.routes.length} route(s) to ${outPath}
+`);
+}
+function parseScanArgs(args) {
+  const result = {
+    globs: [],
+    outFile: "routes.manifest.json",
+    project: void 0,
+    inferName: false
+  };
+  for (let i = 0; i < args.length; i += 1) {
+    const value = args[i];
+    switch (value) {
+      case "--glob":
+      case "-g": {
+        const glob = args[++i];
+        if (!glob) {
+          throw new Error("Missing value for --glob");
+        }
+        result.globs.push(glob);
+        break;
+      }
+      case "--out":
+      case "-o": {
+        const out = args[++i];
+        if (!out) {
+          throw new Error("Missing value for --out");
+        }
+        result.outFile = out;
+        break;
+      }
+      case "--project":
+      case "-p": {
+        const project = args[++i];
+        if (!project) {
+          throw new Error("Missing value for --project");
+        }
+        result.project = project;
+        break;
+      }
+      case "--infer-name": {
+        result.inferName = true;
+        break;
+      }
+      default: {
+        throw new Error(`Unknown option: ${value}`);
+      }
+    }
+  }
+  return result;
+}
+function extractRoute(fn, inferName) {
+  const decorators = collectDecorators(fn);
+  const methodDecorators = decorators.filter((decorator) => {
+    const name = decorator.getName();
+    return Boolean(name && METHOD_DECORATORS[name]);
+  });
+  if (methodDecorators.length === 0) {
+    return void 0;
+  }
+  if (methodDecorators.length > 1) {
+    const funcName = fn.getName() ?? "<anonymous>";
+    throw new Error(`Route "${funcName}" has multiple HTTP method decorators.`);
+  }
+  const methodDecorator = methodDecorators[0];
+  const method = METHOD_DECORATORS[methodDecorator.getName() ?? ""];
+  const path = readPath(methodDecorator) ?? (inferName ? inferPathFromName(fn) : void 0);
+  if (!path) {
+    const funcName = fn.getName() ?? "<anonymous>";
+    throw new Error(`Route "${funcName}" is missing a path. Pass one to the decorator or enable --infer-name.`);
+  }
+  const firebaseDecorator = decorators.find((decorator) => decorator.getName() === "FirebaseAuth");
+  const auth = firebaseDecorator ? readFirebaseAuth(firebaseDecorator) : { type: "none" };
+  return {
+    method,
+    path,
+    auth
+  };
+}
+function collectDecorators(fn) {
+  if (import_ts_morph.Node.isMethodDeclaration(fn)) {
+    return fn.getDecorators();
+  }
+  return fn.getModifiers().filter(import_ts_morph.Node.isDecorator).map((modifier) => modifier.asKindOrThrow(import_ts_morph.SyntaxKind.Decorator));
+}
+function readPath(decorator) {
+  const args = decorator.getArguments();
+  if (args.length === 0) {
+    return void 0;
+  }
+  const first = args[0];
+  if (import_ts_morph.Node.isStringLiteral(first) || import_ts_morph.Node.isNoSubstitutionTemplateLiteral(first)) {
+    const value = first.getLiteralValue();
+    if (!value) {
+      return "/";
+    }
+    return value.startsWith("/") ? value : `/${value}`;
+  }
+  throw new Error(`Unsupported path expression: ${first.getText()}`);
+}
+function readFirebaseAuth(decorator) {
+  const args = decorator.getArguments();
+  if (args.length === 0) {
+    return { type: "firebase" };
+  }
+  const options = args[0];
+  if (!import_ts_morph.Node.isObjectLiteralExpression(options)) {
+    throw new Error("@FirebaseAuth() only supports object literal options");
+  }
+  let optional;
+  let roles;
+  for (const prop of options.getProperties()) {
+    if (!import_ts_morph.Node.isPropertyAssignment(prop)) {
+      continue;
+    }
+    const name = prop.getName();
+    const initializer = prop.getInitializer();
+    if (!initializer) {
+      continue;
+    }
+    if (name === "optional") {
+      if (initializer.getKind() === import_ts_morph.SyntaxKind.TrueKeyword) {
+        optional = true;
+      } else if (initializer.getKind() === import_ts_morph.SyntaxKind.FalseKeyword) {
+        optional = false;
+      } else {
+        throw new Error("@FirebaseAuth({ optional }) expects a boolean literal");
+      }
+    }
+    if (name === "roles") {
+      if (!import_ts_morph.Node.isArrayLiteralExpression(initializer)) {
+        throw new Error("@FirebaseAuth({ roles }) expects an array literal");
+      }
+      roles = initializer.getElements().map((element) => {
+        if (!import_ts_morph.Node.isStringLiteral(element) && !import_ts_morph.Node.isNoSubstitutionTemplateLiteral(element)) {
+          throw new Error("@FirebaseAuth roles must be string literals");
+        }
+        return element.getLiteralValue();
+      });
+    }
+  }
+  const auth = {
+    type: "firebase"
+  };
+  if (typeof optional === "boolean") {
+    auth.optional = optional;
+  }
+  if (roles && roles.length > 0) {
+    auth.roles = roles;
+  }
+  return auth;
+}
+function inferPathFromName(fn) {
+  const name = fn.getName();
+  if (!name) {
+    return void 0;
+  }
+  const slug = name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase();
+  return `/${slug}`;
+}
+function printUsage() {
+  import_node_process.stdout.write(`Usage: sst-http <command> [options]
+`);
+  import_node_process.stdout.write(`
+Commands:
+`);
+  import_node_process.stdout.write(`  scan            Scan for decorated routes and emit a manifest
+`);
+  import_node_process.stdout.write(`
+Options for scan:
+`);
+  import_node_process.stdout.write(`  --glob, -g      Glob pattern to include (repeatable). Defaults to src/**/*.ts
+`);
+  import_node_process.stdout.write(`  --out, -o       Output file for the manifest. Defaults to routes.manifest.json
+`);
+  import_node_process.stdout.write(`  --project, -p   Path to a tsconfig.json used to resolve source files
+`);
+  import_node_process.stdout.write(`  --infer-name    Infer missing paths from function names (kebab-case)
+`);
+}
+main().catch((error) => {
+  import_node_process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+  process.exitCode = 1;
+});

package/dist/cli.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { writeFileSync } from "fs";
+import { resolve } from "path";
+import { cwd, stderr, stdout } from "process";
+import {
+  Node,
+  Project,
+  SyntaxKind
+} from "ts-morph";
+var METHOD_DECORATORS = {
+  Get: "GET",
+  Post: "POST",
+  Put: "PUT",
+  Patch: "PATCH",
+  Delete: "DELETE",
+  Head: "HEAD",
+  Options: "OPTIONS"
+};
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || command === "--help" || command === "-h") {
+    printUsage();
+    return;
+  }
+  switch (command) {
+    case "scan": {
+      await runScan(rest);
+      return;
+    }
+    default: {
+      stderr.write(`Unknown command: ${command}
+`);
+      printUsage();
+      process.exitCode = 1;
+    }
+  }
+}
+async function runScan(args) {
+  const options = parseScanArgs(args);
+  const project = options.project ? new Project({ tsConfigFilePath: options.project }) : new Project();
+  if (options.globs.length === 0) {
+    options.globs.push("src/**/*.ts");
+  }
+  project.addSourceFilesAtPaths(options.globs);
+  const manifest = { routes: [] };
+  for (const sourceFile of project.getSourceFiles()) {
+    for (const fn of sourceFile.getFunctions()) {
+      if (!fn.isExported() && !fn.isDefaultExport()) {
+        continue;
+      }
+      const route = extractRoute(fn, options.inferName);
+      if (route) {
+        manifest.routes.push(route);
+      }
+    }
+    for (const cls of sourceFile.getClasses()) {
+      if (!cls.isExported() && !cls.isDefaultExport()) {
+        continue;
+      }
+      for (const method of cls.getMethods()) {
+        if (!method.isStatic()) {
+          continue;
+        }
+        const route = extractRoute(method, options.inferName);
+        if (route) {
+          manifest.routes.push(route);
+        }
+      }
+    }
+  }
+  manifest.routes.sort((a, b) => {
+    if (a.path === b.path) {
+      return a.method.localeCompare(b.method);
+    }
+    return a.path.localeCompare(b.path);
+  });
+  const outPath = resolve(cwd(), options.outFile);
+  writeFileSync(outPath, JSON.stringify(manifest, null, 2));
+  stdout.write(`Wrote ${manifest.routes.length} route(s) to ${outPath}
+`);
+}
+function parseScanArgs(args) {
+  const result = {
+    globs: [],
+    outFile: "routes.manifest.json",
+    project: void 0,
+    inferName: false
+  };
+  for (let i = 0; i < args.length; i += 1) {
+    const value = args[i];
+    switch (value) {
+      case "--glob":
+      case "-g": {
+        const glob = args[++i];
+        if (!glob) {
+          throw new Error("Missing value for --glob");
+        }
+        result.globs.push(glob);
+        break;
+      }
+      case "--out":
+      case "-o": {
+        const out = args[++i];
+        if (!out) {
+          throw new Error("Missing value for --out");
+        }
+        result.outFile = out;
+        break;
+      }
+      case "--project":
+      case "-p": {
+        const project = args[++i];
+        if (!project) {
+          throw new Error("Missing value for --project");
+        }
+        result.project = project;
+        break;
+      }
+      case "--infer-name": {
+        result.inferName = true;
+        break;
+      }
+      default: {
+        throw new Error(`Unknown option: ${value}`);
+      }
+    }
+  }
+  return result;
+}
+function extractRoute(fn, inferName) {
+  const decorators = collectDecorators(fn);
+  const methodDecorators = decorators.filter((decorator) => {
+    const name = decorator.getName();
+    return Boolean(name && METHOD_DECORATORS[name]);
+  });
+  if (methodDecorators.length === 0) {
+    return void 0;
+  }
+  if (methodDecorators.length > 1) {
+    const funcName = fn.getName() ?? "<anonymous>";
+    throw new Error(`Route "${funcName}" has multiple HTTP method decorators.`);
+  }
+  const methodDecorator = methodDecorators[0];
+  const method = METHOD_DECORATORS[methodDecorator.getName() ?? ""];
+  const path = readPath(methodDecorator) ?? (inferName ? inferPathFromName(fn) : void 0);
+  if (!path) {
+    const funcName = fn.getName() ?? "<anonymous>";
+    throw new Error(`Route "${funcName}" is missing a path. Pass one to the decorator or enable --infer-name.`);
+  }
+  const firebaseDecorator = decorators.find((decorator) => decorator.getName() === "FirebaseAuth");
+  const auth = firebaseDecorator ? readFirebaseAuth(firebaseDecorator) : { type: "none" };
+  return {
+    method,
+    path,
+    auth
+  };
+}
+function collectDecorators(fn) {
+  if (Node.isMethodDeclaration(fn)) {
+    return fn.getDecorators();
+  }
+  return fn.getModifiers().filter(Node.isDecorator).map((modifier) => modifier.asKindOrThrow(SyntaxKind.Decorator));
+}
+function readPath(decorator) {
+  const args = decorator.getArguments();
+  if (args.length === 0) {
+    return void 0;
+  }
+  const first = args[0];
+  if (Node.isStringLiteral(first) || Node.isNoSubstitutionTemplateLiteral(first)) {
+    const value = first.getLiteralValue();
+    if (!value) {
+      return "/";
+    }
+    return value.startsWith("/") ? value : `/${value}`;
+  }
+  throw new Error(`Unsupported path expression: ${first.getText()}`);
+}
+function readFirebaseAuth(decorator) {
+  const args = decorator.getArguments();
+  if (args.length === 0) {
+    return { type: "firebase" };
+  }
+  const options = args[0];
+  if (!Node.isObjectLiteralExpression(options)) {
+    throw new Error("@FirebaseAuth() only supports object literal options");
+  }
+  let optional;
+  let roles;
+  for (const prop of options.getProperties()) {
+    if (!Node.isPropertyAssignment(prop)) {
+      continue;
+    }
+    const name = prop.getName();
+    const initializer = prop.getInitializer();
+    if (!initializer) {
+      continue;
+    }
+    if (name === "optional") {
+      if (initializer.getKind() === SyntaxKind.TrueKeyword) {
+        optional = true;
+      } else if (initializer.getKind() === SyntaxKind.FalseKeyword) {
+        optional = false;
+      } else {
+        throw new Error("@FirebaseAuth({ optional }) expects a boolean literal");
+      }
+    }
+    if (name === "roles") {
+      if (!Node.isArrayLiteralExpression(initializer)) {
+        throw new Error("@FirebaseAuth({ roles }) expects an array literal");
+      }
+      roles = initializer.getElements().map((element) => {
+        if (!Node.isStringLiteral(element) && !Node.isNoSubstitutionTemplateLiteral(element)) {
+          throw new Error("@FirebaseAuth roles must be string literals");
+        }
+        return element.getLiteralValue();
+      });
+    }
+  }
+  const auth = {
+    type: "firebase"
+  };
+  if (typeof optional === "boolean") {
+    auth.optional = optional;
+  }
+  if (roles && roles.length > 0) {
+    auth.roles = roles;
+  }
+  return auth;
+}
+function inferPathFromName(fn) {
+  const name = fn.getName();
+  if (!name) {
+    return void 0;
+  }
+  const slug = name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase();
+  return `/${slug}`;
+}
+function printUsage() {
+  stdout.write(`Usage: sst-http <command> [options]
+`);
+  stdout.write(`
+Commands:
+`);
+  stdout.write(`  scan            Scan for decorated routes and emit a manifest
+`);
+  stdout.write(`
+Options for scan:
+`);
+  stdout.write(`  --glob, -g      Glob pattern to include (repeatable). Defaults to src/**/*.ts
+`);
+  stdout.write(`  --out, -o       Output file for the manifest. Defaults to routes.manifest.json
+`);
+  stdout.write(`  --project, -p   Path to a tsconfig.json used to resolve source files
+`);
+  stdout.write(`  --infer-name    Infer missing paths from function names (kebab-case)
+`);
+}
+main().catch((error) => {
+  stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+  process.exitCode = 1;
+});