@tsed/platform-serverless 8.0.1 → 8.0.3

package/src/domain/ServerlessResponse.ts

@@ -0,0 +1,226 @@
+import {getValue} from "@tsed/core";
+import {getStatusMessage} from "@tsed/schema";
+import type {APIGatewayProxyEvent} from "aws-lambda";
+import encodeUrl from "encodeurl";
+import mime from "mime";
+
+import {ServerlessContext} from "./ServerlessContext.js";
+
+export type HeaderValue = boolean | number | string;
+
+/**
+ * @platform
+ */
+export class ServerlessResponse<Event extends object = APIGatewayProxyEvent> {
+  #status: number = 200;
+  #body: any = undefined;
+  #headers: Record<string, HeaderValue> = {};
+  #locals: Record<string, any> = {};
+  #isHeadersSent = false;
+
+  constructor(protected $ctx: ServerlessContext<Event>) {}
+
+  get event() {
+    return this.$ctx.event;
+  }
+
+  get raw() {
+    return this.event;
+  }
+
+  get request() {
+    return this.$ctx.request;
+  }
+
+  /**
+   * Get the current statusCode
+   */
+  get statusCode() {
+    return this.#status;
+  }
+
+  set statusCode(status) {
+    this.#status = status;
+  }
+
+  /**
+   * An object that contains response local variables scoped to the request, and therefore available only to the view(s) rendered during that request / response cycle (if any). Otherwise, this property is identical to app.locals.
+   *
+   * This property is useful for exposing request-level information such as the request path name, authenticated user, user settings, and so on.
+   */
+  get locals() {
+    return this.#locals;
+  }
+
+  get isHeadersSent() {
+    return this.#isHeadersSent;
+  }
+
+  getStatus() {
+    return this.#status;
+  }
+
+  /**
+   * Sets the HTTP status for the response.
+   *
+   * @param status
+   */
+  status(status: number) {
+    this.#status = status;
+    return this;
+  }
+
+  set(name: string, value: any) {
+    return this.setHeader(name, value);
+  }
+
+  /**
+   * Returns the HTTP response header specified by field. The match is case-insensitive.
+   *
+   * ```typescript
+   * response.get('Content-Type') // => "text/plain"
+   * ```
+   *
+   * @param name
+   */
+  get(name: string): string | number | boolean | undefined {
+    return getValue(this.#headers, name.toLowerCase());
+  }
+
+  getHeaders(): Record<string, HeaderValue> {
+    return {
+      ...this.#headers
+    };
+  }
+
+  hasStatus() {
+    return this.#status !== 200;
+  }
+
+  /**
+   * Set header `field` to `val`, or pass
+   * an object of header fields.
+   *
+   * Examples:
+   * ```typescript
+   * response.setHeaders({ Accept: 'text/plain', 'X-API-Key': 'tobi' });
+   * ```
+   *
+   * Aliased as `res.header()`.
+   */
+  setHeaders(headers: Record<string, HeaderValue>) {
+    // apply headers
+    Object.entries(headers).forEach(([key, item]) => {
+      this.setHeader(key, item);
+    });
+
+    return this;
+  }
+
+  setHeader(key: string, item: HeaderValue | null | undefined) {
+    if (item !== null && item !== undefined) {
+      key = key.toLowerCase();
+
+      if (key === "location") {
+        // "back" is an alias for the referrer
+        if (item === "back") {
+          item = this.request.get("Referrer") || "/";
+        }
+
+        item = encodeUrl(String(item));
+      }
+
+      this.#headers = {
+        ...this.#headers,
+        [key.toLowerCase()]: item as any
+      };
+    }
+
+    return this;
+  }
+
+  /**
+   * Set `Content-Type` response header with `type` through `mime.lookup()`
+   * when it does not contain "/", or set the Content-Type to `type` otherwise.
+   *
+   * Examples:
+   *
+   *     res.type('.html');
+   *     res.type('html');
+   *     res.type('json');
+   *     res.type('application/json');
+   *     res.type('png');
+   */
+  contentType(contentType: string) {
+    this.setHeader("Content-Type", mime.getType(contentType));
+
+    return this;
+  }
+
+  contentLength(length: number) {
+    this.setHeader("Content-Length", length);
+    return this;
+  }
+
+  getContentLength() {
+    if (this.get("Content-Length")) {
+      return parseInt(this.get("Content-Length") as any, 10) || 0;
+    }
+  }
+
+  getContentType() {
+    return String(this.get("Content-Type") || "").split(";")[0];
+  }
+
+  /**
+   * Redirects to the URL derived from the specified path, with specified status, a positive integer that corresponds to an [HTTP status code](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).
+   * If not specified, status defaults to `302 Found`.
+   *
+   * @param status
+   * @param url
+   */
+  redirect(status: number, url: string) {
+    // Set location header
+    const address = this.location(url).get("Location");
+    const body = `${getStatusMessage(status)}. Redirecting to ${address}`;
+
+    this.status(status).set("Content-Length", Buffer.byteLength(body)).body(body);
+
+    return this;
+  }
+
+  /**
+   * Sets the response Location HTTP header to the specified path parameter.
+   *
+   * @param url
+   */
+  location(url: string) {
+    return this.set("Location", url);
+  }
+
+  /**
+   * Send any data to your consumer.
+   *
+   * This method accept a ReadableStream, a plain object, boolean, string, number, null and undefined data.
+   * It choose the better way to send the data.
+   *
+   * @param body
+   */
+  body(body: any) {
+    this.#body = body;
+
+    return this;
+  }
+
+  getBody() {
+    return this.#body;
+  }
+
+  isDone(): boolean {
+    return this.#isHeadersSent;
+  }
+
+  destroy() {
+    this.#isHeadersSent = true;
+  }
+}

package/src/domain/ServerlessResponseStream.spec.ts

@@ -0,0 +1,63 @@
+import {ServerlessResponseStream} from "./ServerlessResponseStream.js";
+
+describe("ServerlessResponseStream", () => {
+  describe("streamifyResponse", () => {
+    describe("when isInAWS", () => {
+      beforeEach(() => {
+        // @ts-ignore
+        globalThis.awslambda = {
+          streamifyResponse: vi.fn().mockImplementation((handler) => handler)
+        };
+      });
+      afterEach(() => {
+        // @ts-ignore
+        delete globalThis.awslambda;
+      });
+
+      it("should wrap then handler without fallback responseStream", async () => {
+        const handler = vi.fn();
+        const event = {};
+        const context = {};
+        const responseStream = new ServerlessResponseStream();
+
+        vi.spyOn(ServerlessResponseStream as any, "buildResponse").mockReturnValue({});
+
+        const wrapped = ServerlessResponseStream.streamifyResponse(handler);
+
+        const result = await wrapped(event as any, responseStream, context as any);
+
+        expect(result).toEqual(undefined);
+        expect(handler).toHaveBeenCalledWith(event, responseStream, context);
+        // @ts-ignore
+        expect(ServerlessResponseStream.buildResponse).not.toHaveBeenCalled();
+      });
+      it("should wrap then handler with fallback responseStream", async () => {
+        const handler = vi.fn();
+        const event = {};
+        const context = {};
+
+        vi.spyOn(ServerlessResponseStream as any, "buildResponse").mockReturnValue({
+          statusCode: 200
+        });
+        vi.spyOn(console, "warn").mockReturnValue(undefined);
+
+        const wrapped = ServerlessResponseStream.streamifyResponse(handler);
+
+        const result = await wrapped(event as any, context as any);
+
+        expect(handler).toHaveBeenCalledWith(event, expect.any(ServerlessResponseStream), context);
+
+        expect(result).toEqual({
+          statusCode: 200
+        });
+        // @ts-ignore
+        expect(ServerlessResponseStream.buildResponse).toHaveBeenCalledWith(expect.any(ServerlessResponseStream));
+        expect(console.warn).toHaveBeenCalledWith({
+          event: "WRONG_AWS_STREAM_CONFIGURATION",
+          message:
+            "The lambda didn't receive a ResponseStream from AWS. Ts.ED therefore generated a ServerlessResponseStream as a fallback. This mode is not optimized for use in PRODUCTION. Please check the AWS configuration of your lambda."
+        });
+      });
+    });
+  });
+});

package/src/domain/ServerlessResponseStream.ts

@@ -0,0 +1,113 @@
+import {Stream} from "node:stream";
+
+import type {APIGatewayProxyEventV2, Callback, Context, Handler} from "aws-lambda";
+
+import {isInAWS} from "../utils/isInAWS.js";
+
+export type ServerlessResponseMeta = {statusCode: number; headers: Record<string, string>};
+
+declare global {
+  const awsLambda: {
+    streamifyResponse(handler: Handler): unknown | Promise<unknown>;
+    HttpResponseStream: {
+      from(resStream: ServerlessResponseStream | unknown, meta: ServerlessResponseMeta): ServerlessResponseStream;
+    };
+  };
+}
+
+export type RequestHandler = (
+  ev: APIGatewayProxyEventV2,
+  streamResponse?: ServerlessResponseStream,
+  ctx?: Context,
+  callback?: Callback
+) => unknown | Promise<unknown>;
+
+export class ServerlessResponseStream extends Stream.Writable {
+  public _meta: ServerlessResponseMeta = {statusCode: 200, headers: {}};
+  #response: Buffer[];
+
+  constructor() {
+    super();
+    this.#response = [];
+  }
+
+  static setMeta(resStream: ServerlessResponseStream, meta: ServerlessResponseMeta) {
+    if (isInAWS()) {
+      // @ts-ignore
+      return awslambda.HttpResponseStream.from(resStream, meta);
+    }
+
+    resStream.setMeta(meta);
+
+    return resStream;
+  }
+
+  static streamifyResponse(handler: RequestHandler): RequestHandler {
+    // Check for global awslambda
+    if (isInAWS()) {
+      // @ts-ignore
+      return awslambda.streamifyResponse(
+        async (event: APIGatewayProxyEventV2, responseStream: ServerlessResponseStream | Context | undefined, context?: Context) => {
+          const isFallbackMode = context === undefined;
+
+          if (context === undefined) {
+            context = responseStream as Context;
+            responseStream = new ServerlessResponseStream();
+
+            console.warn({
+              event: "WRONG_AWS_STREAM_CONFIGURATION",
+              message:
+                "The lambda didn't receive a ResponseStream from AWS. Ts.ED therefore generated a ServerlessResponseStream as a fallback. This mode is not optimized for use in PRODUCTION. Please check the AWS configuration of your lambda."
+            });
+          }
+
+          await handler(event, responseStream as ServerlessResponseStream, context);
+
+          if (isFallbackMode) {
+            return ServerlessResponseStream.buildResponse(responseStream as ServerlessResponseStream);
+          }
+        }
+      );
+    } else {
+      return async (event, response, context) => {
+        const args: any[] = patchArgs([event, response, context]);
+        const responseStream: ServerlessResponseStream = args[1];
+
+        await (handler as any)(...args);
+
+        return ServerlessResponseStream.buildResponse(responseStream);
+      };
+    }
+  }
+
+  private static buildResponse(responseStream: ServerlessResponseStream) {
+    return {
+      ...responseStream._meta,
+      body: responseStream.getBufferedData().toString()
+    };
+  }
+
+  // streams, `chunk` may be any JavaScript value.
+  _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    this.#response.push(Buffer.from(chunk, encoding));
+    callback();
+  }
+
+  setMeta(meta: ServerlessResponseMeta) {
+    this._meta = meta;
+  }
+
+  getBufferedData(): Buffer {
+    return Buffer.concat(this.#response);
+  }
+}
+
+function patchArgs(args: any[]) {
+  if (!(args[1] instanceof ServerlessResponseStream)) {
+    const responseStream = new ServerlessResponseStream();
+
+    return [args[0], responseStream, ...args.splice(1, -1)];
+  }
+
+  return args;
+}

package/src/exports.ts

@@ -0,0 +1 @@
+export {Operation as Lambda} from "@tsed/schema";

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @file Automatically generated by @tsed/barrels.
+ */
+export * from "./builder/PlatformServerless.js";
+export * from "./builder/PlatformServerlessHandler.js";
+export * from "./domain/ServerlessContext.js";
+export * from "./domain/ServerlessEvent.js";
+export * from "./domain/ServerlessRequest.js";
+export * from "./domain/ServerlessResponse.js";
+export * from "./domain/ServerlessResponseStream.js";
+export * from "./exports.js";
+export * from "./utils/getRequestId.js";
+export * from "./utils/isInAWS.js";
+export * from "./utils/setResponseHeaders.js";

package/src/utils/getRequestId.spec.ts

@@ -0,0 +1,43 @@
+import {getRequestId} from "./getRequestId.js";
+
+describe("getRequestId", () => {
+  it("should return request id (uuid)", () => {
+    const event: any = {};
+    const context: any = {};
+
+    expect(typeof getRequestId(event, context)).toEqual("string");
+  });
+
+  it("should return request id (requestId)", () => {
+    const event: any = {
+      requestContext: {
+        requestId: "requestId"
+      }
+    };
+    const context: any = {};
+
+    expect(getRequestId(event, context)).toEqual("requestId");
+  });
+
+  it("should return request id (awsRequestId)", () => {
+    const event: any = {};
+    const context: any = {
+      awsRequestId: "awsRequestId"
+    };
+
+    expect(getRequestId(event, context)).toEqual("awsRequestId");
+  });
+
+  it("should return request id (headers)", () => {
+    const event: any = {
+      headers: {
+        "x-request-id": "x-request-id"
+      }
+    };
+    const context: any = {
+      awsRequestId: "awsRequestId"
+    };
+
+    expect(getRequestId(event, context)).toEqual("x-request-id");
+  });
+});

package/src/utils/getRequestId.ts

@@ -0,0 +1,16 @@
+import type {Context} from "aws-lambda";
+import {v4} from "uuid";
+
+import type {ServerlessEvent} from "../domain/ServerlessEvent.js";
+
+export function getRequestId(event: ServerlessEvent, context: Context) {
+  if ("headers" in event && event.headers["x-request-id"]) {
+    return event.headers["x-request-id"];
+  }
+
+  if ("requestContext" in event) {
+    return event?.requestContext?.requestId;
+  }
+
+  return context?.awsRequestId || v4().replace(/-/gi, "");
+}

package/src/utils/isInAWS.ts

@@ -0,0 +1,8 @@
+export function isInAWS(): boolean {
+  return (
+    // @ts-ignore
+    globalThis.awslambda !== undefined &&
+    // @ts-ignore
+    awslambda.streamifyResponse !== undefined
+  );
+}

package/src/utils/setResponseHeaders.spec.ts

@@ -0,0 +1,156 @@
+import {PlatformTest} from "@tsed/platform-http/testing";
+import {Get, JsonEntityStore, Redirect, Returns} from "@tsed/schema";
+
+import {createServerlessContext} from "../../test/utils/createServerlessContext.js";
+import {setResponseHeaders} from "./setResponseHeaders.js";
+
+describe("setResponseHeaders", () => {
+  beforeEach(() => PlatformTest.create());
+  afterEach(() => PlatformTest.reset());
+
+  it("should set headers, status and contentType", async () => {
+    class Test {
+      @Get("/")
+      @(Returns(200).Header("x-header", "test"))
+      test() {}
+    }
+
+    const ctx = createServerlessContext({
+      endpoint: JsonEntityStore.fromMethod(Test, "test")
+    });
+
+    vi.spyOn(ctx.response, "setHeaders");
+    vi.spyOn(ctx.response, "status");
+    // WHEN
+    await setResponseHeaders(ctx);
+
+    // THEN
+    expect(ctx.response.setHeaders).toHaveBeenCalledWith({"x-header": "test"});
+    expect(ctx.response.status).toHaveBeenCalledWith(200);
+  });
+  it("should not set headers automatically", async () => {
+    class Test {
+      @Get("/")
+      @(Returns(200).Header("x-header"))
+      test() {}
+    }
+
+    const ctx = createServerlessContext({
+      endpoint: JsonEntityStore.fromMethod(Test, "test")
+    });
+
+    vi.spyOn(ctx.response, "setHeaders");
+    vi.spyOn(ctx.response, "status");
+    // WHEN
+    await setResponseHeaders(ctx);
+
+    // THEN
+    expect(ctx.response.setHeaders).toHaveBeenCalledWith({});
+    expect(ctx.response.status).toHaveBeenCalledWith(200);
+  });
+  it("should redirect with 301", async () => {
+    class Test {
+      @Get("/")
+      @Redirect(301, "/path")
+      test() {}
+    }
+
+    const ctx = createServerlessContext({
+      endpoint: JsonEntityStore.fromMethod(Test, "test")
+    });
+
+    vi.spyOn(ctx.response, "redirect");
+
+    // WHEN
+    await setResponseHeaders(ctx as any);
+
+    // THEN
+    expect(ctx.response.redirect).toHaveBeenCalledWith(301, "/path");
+  });
+  it("should redirect with default", async () => {
+    class Test {
+      @Get("/")
+      @Redirect(302, "/path")
+      test() {}
+    }
+
+    const ctx = createServerlessContext({
+      endpoint: JsonEntityStore.fromMethod(Test, "test")
+    });
+    vi.spyOn(ctx.response, "redirect");
+
+    // WHEN
+    await setResponseHeaders(ctx as any);
+
+    // THEN
+    expect(ctx.response.redirect).toHaveBeenCalledWith(302, "/path");
+  });
+  it("should redirect with assigned value", async () => {
+    class Test {
+      @Get("/")
+      @Redirect(302, "/path")
+      test() {}
+    }
+
+    const ctx = createServerlessContext({
+      endpoint: JsonEntityStore.fromMethod(Test, "test")
+    });
+    vi.spyOn(ctx.response, "redirect");
+
+    ctx.response.setHeaders({Location: "/path/other"});
+
+    // WHEN
+    await setResponseHeaders(ctx as any);
+
+    // THEN
+    expect(ctx.response.redirect).toHaveBeenCalledWith(302, "/path/other");
+  });
+  it("should do nothing when headers is already sent", async () => {
+    class Test {
+      @Get("/")
+      @(Returns(200).Header("x-header", "test"))
+      test() {}
+    }
+
+    const ctx = createServerlessContext({
+      endpoint: JsonEntityStore.fromMethod(Test, "test")
+    });
+
+    await ctx.destroy();
+
+    vi.spyOn(ctx.response, "setHeaders");
+    vi.spyOn(ctx.response, "isDone");
+
+    // WHEN
+    await setResponseHeaders(ctx);
+
+    // THEN
+    return expect(ctx.response.isDone).toHaveBeenCalled();
+  });
+  it("should do nothing if the endpoint isn't an operation", async () => {
+    class Test {
+      test() {}
+    }
+
+    const endpoint = JsonEntityStore.fromMethod(Test, "test");
+
+    const ctx = createServerlessContext({
+      endpoint: {} as never
+    });
+
+    vi.spyOn(ctx.response, "setHeaders");
+    vi.spyOn(ctx.response, "isDone");
+    vi.spyOn(ctx.logger, "debug");
+
+    // WHEN
+    await setResponseHeaders(ctx);
+
+    // THEN
+    expect(ctx.response.isDone).toHaveBeenCalled();
+    expect(ctx.logger.debug).toHaveBeenCalledWith({
+      event: "MISSING_OPERATION_METADATA",
+      message: "No operation found on the endpoint. The response headers are not set.",
+      endpoint: {}
+    });
+  });
+});

package/src/utils/setResponseHeaders.ts

@@ -0,0 +1,58 @@
+import {JsonHeader, JsonOperation} from "@tsed/schema";
+
+import {ServerlessContext} from "../domain/ServerlessContext.js";
+import type {ServerlessEvent} from "../domain/ServerlessEvent.js";
+import {HeaderValue} from "../domain/ServerlessResponse.js";
+
+function mergeHeaders(specHeaders: Record<string, JsonHeader & {example: string}>, headers: Record<string, HeaderValue>) {
+  return Object.entries(specHeaders).reduce((headers, [key, item]) => {
+    key = key.toLowerCase();
+
+    const value = headers[key] === undefined ? item.example : headers[key];
+
+    if (value !== undefined) {
+      return {
+        ...headers,
+        [key]: String(value)
+      };
+    }
+
+    return headers;
+  }, headers);
+}
+
+/**
+ * @ignore
+ */
+export function setResponseHeaders(ctx: ServerlessContext<ServerlessEvent>) {
+  const {response, endpoint} = ctx;
+  if (ctx.isDone()) {
+    return;
+  }
+
+  const operation = endpoint.operation as JsonOperation | undefined;
+
+  if (!operation) {
+    ctx.logger.debug({
+      event: "MISSING_OPERATION_METADATA",
+      message: "No operation found on the endpoint. The response headers are not set.",
+      endpoint: endpoint
+    });
+    return;
+  }
+
+  if (!response.hasStatus()) {
+    // apply status only if isn't already modified
+    response.status(operation.getStatus());
+  }
+
+  const statusCode = response.statusCode;
+  const headers = operation.getHeadersOf(response.statusCode);
+  const mergedHeaders = mergeHeaders(headers, response.getHeaders());
+
+  response.setHeaders(mergedHeaders);
+
+  if (operation.isRedirection(statusCode)) {
+    response.redirect(statusCode, String(mergedHeaders["location"]));
+  }
+}