@typespec/http-server-js 0.58.0-alpha.10-dev.3

package/src/helpers/multipart.ts

@@ -0,0 +1,228 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import type * as http from "node:http";
+
+export interface HttpPart {
+  headers: { [k: string]: string | undefined };
+  body: ReadableStream<Buffer>;
+}
+
+/**
+ * Consumes a stream of incoming data and splits it into individual streams for each part of a multipart request, using
+ * the provided `boundary` value.
+ */
+function MultipartBoundaryTransformStream(
+  boundary: string,
+): ReadableWritablePair<ReadableStream<Buffer>, Buffer> {
+  let buffer: Buffer = Buffer.alloc(0);
+  // Initialize subcontroller to an object that does nothing. Multipart bodies may contain a preamble before the first
+  // boundary, so this dummy controller will discard it.
+  let subController: { enqueue(chunk: Buffer): void; close(): void } | null = {
+    enqueue() {},
+    close() {},
+  };
+
+  let boundarySplit = Buffer.from(`--${boundary}`);
+  let initialized = false;
+
+  // We need to keep at least the length of the boundary split plus room for CRLFCRLF in the buffer to detect the boundaries.
+  // We subtract one from this length because if the whole thing were in the buffer, we would detect it and move past it.
+  const bufferKeepLength = boundarySplit.length + BUF_CRLFCRLF.length - 1;
+  let _readableController: ReadableStreamDefaultController<ReadableStream<Buffer>> = null as any;
+
+  const readable = new ReadableStream<ReadableStream<Buffer>>({
+    start(controller) {
+      _readableController = controller;
+    },
+  });
+
+  const readableController = _readableController;
+
+  const writable = new WritableStream<Buffer>({
+    write: async (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+
+      let index: number;
+
+      while ((index = buffer.indexOf(boundarySplit)) !== -1) {
+        // We found a boundary, emit everything before it and initialize a new stream for the next part.
+
+        // We are initialized if we have found the boundary at least once.
+        //
+        // Cases
+        // 1. If the index is zero and we aren't initialized, there was no preamble.
+        // 2. If the index is zero and we are initialized, then we had to have found \r\n--boundary, nothing special to do.
+        // 3. If the index is not zero, and we are initialized, then we found \r\n--boundary somewhere in the middle,
+        //    nothing special to do.
+        // 4. If the index is not zero and we aren't initialized, then we need to check that boundarySplit was preceded
+        //    by \r\n for validity, because the preamble must end with \r\n.
+
+        if (index > 0) {
+          if (!initialized) {
+            if (!buffer.subarray(index - 2, index).equals(Buffer.from("\r\n"))) {
+              readableController.error(new Error("Invalid preamble in multipart body."));
+            } else {
+              await enqueueSub(buffer.subarray(0, index - 2));
+            }
+          } else {
+            await enqueueSub(buffer.subarray(0, index));
+          }
+        }
+
+        // We enqueued everything before the boundary, so we clear the buffer past the boundary
+        buffer = buffer.subarray(index + boundarySplit.length);
+
+        // We're done with the current part, so close the stream. If this is the opening boundary, there won't be a
+        // subcontroller yet.
+        subController?.close();
+        subController = null;
+
+        if (!initialized) {
+          initialized = true;
+          boundarySplit = Buffer.from(`\r\n${boundarySplit}`);
+        }
+      }
+
+      if (buffer.length > bufferKeepLength) {
+        await enqueueSub(buffer.subarray(0, -bufferKeepLength));
+        buffer = buffer.subarray(-bufferKeepLength);
+      }
+    },
+    close() {
+      if (!/--(\r\n)?/.test(buffer.toString("utf-8"))) {
+        readableController.error(new Error("Unexpected characters after final boundary."));
+      }
+
+      subController?.close();
+
+      readableController.close();
+    },
+  });
+
+  async function enqueueSub(s: Buffer) {
+    subController ??= await new Promise<ReadableStreamDefaultController>((resolve) => {
+      readableController.enqueue(
+        new ReadableStream<Buffer>({
+          start: (controller) => resolve(controller),
+        }),
+      );
+    });
+
+    subController.enqueue(s);
+  }
+
+  return { readable, writable };
+}
+
+const BUF_CRLFCRLF = Buffer.from("\r\n\r\n");
+
+/**
+ * Consumes a stream of the contents of a single part of a multipart request and emits an `HttpPart` object for each part.
+ * This consumes just enough of the stream to read the headers, and then forwards the rest of the stream as the body.
+ */
+class HttpPartTransform extends TransformStream<ReadableStream<Buffer>, HttpPart> {
+  constructor() {
+    super({
+      transform: async (partRaw, controller) => {
+        const reader = partRaw.getReader();
+
+        let buf = Buffer.alloc(0);
+        let idx;
+
+        while ((idx = buf.indexOf(BUF_CRLFCRLF)) === -1) {
+          const { done, value } = await reader.read();
+          if (done) {
+            throw new Error("Unexpected end of part.");
+          }
+          buf = Buffer.concat([buf, value]);
+        }
+
+        const headerText = buf.subarray(0, idx).toString("utf-8").trim();
+
+        const headers = Object.fromEntries(
+          headerText.split("\r\n").map((line) => {
+            const [name, value] = line.split(": ", 2);
+
+            return [name.toLowerCase(), value];
+          }),
+        ) as { [k: string]: string };
+
+        const body = new ReadableStream<Buffer>({
+          start(controller) {
+            controller.enqueue(buf.subarray(idx + BUF_CRLFCRLF.length));
+          },
+          async pull(controller) {
+            const { done, value } = await reader.read();
+
+            if (done) {
+              controller.close();
+            } else {
+              controller.enqueue(value);
+            }
+          },
+        });
+
+        controller.enqueue({ headers, body });
+      },
+    });
+  }
+}
+
+/**
+ * Processes a request as a multipart request, returning a stream of `HttpPart` objects, each representing an individual
+ * part in the multipart request.
+ *
+ * Only call this function if you have already validated the content type of the request and confirmed that it is a
+ * multipart request.
+ *
+ * @throws Error if the content-type header is missing or does not contain a boundary field.
+ *
+ * @param request - the incoming request to parse as multipart
+ * @returns a stream of HttpPart objects, each representing an individual part in the multipart request
+ */
+export function createMultipartReadable(request: http.IncomingMessage): ReadableStream<HttpPart> {
+  const boundary = request.headers["content-type"]
+    ?.split(";")
+    .find((s) => s.includes("boundary="))
+    ?.split("=", 2)[1];
+  if (!boundary) {
+    throw new Error("Invalid request: missing boundary in content-type.");
+  }
+
+  const bodyStream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      request.on("data", (chunk: Buffer) => {
+        controller.enqueue(chunk);
+      });
+      request.on("end", () => controller.close());
+    },
+  });
+
+  return bodyStream
+    .pipeThrough(MultipartBoundaryTransformStream(boundary))
+    .pipeThrough(new HttpPartTransform());
+}
+
+// Gross polyfill because Safari doesn't support this yet.
+//
+// https://bugs.webkit.org/show_bug.cgi?id=194379
+// https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream#browser_compatibility
+(ReadableStream.prototype as any)[Symbol.asyncIterator] ??= async function* () {
+  const reader = this.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) return value;
+      yield value;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+};
+
+declare global {
+  interface ReadableStream<R> {
+    [Symbol.asyncIterator](): AsyncIterableIterator<R>;
+  }
+}

package/src/helpers/router.ts

@@ -0,0 +1,238 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import type * as http from "node:http";
+
+/** A policy that can be applied to a route or a set of routes. */
+export interface Policy {
+  /** Optional policy name. */
+  name?: string;
+
+  /**
+   * Applies the policy to the request.
+   *
+   * Policies _MUST_ call `next()` to pass the request to the next policy _OR_ call `response.end()` to terminate,
+   * and _MUST NOT_ do both.
+   *
+   * If the policy passes a `request` object to `next()`, that request object will be used instead of the original
+   * request object for the remainder of the policy chain. If the policy does _not_ pass a request object to `next()`,
+   * the same object that was passed to this policy will be forwarded to the next policy automatically.
+   *
+   * @param request - The incoming HTTP request.
+   * @param response - The outgoing HTTP response.
+   * @param next - Calls the next policy in the chain.
+   */
+  (ctx: HttpContext, next: (request?: http.IncomingMessage) => void): void;
+}
+
+/**
+ * Create a function from a chain of policies.
+ *
+ * This returns a single function that will apply the policy chain and eventually call the provided `next()` function.
+ *
+ * @param name - The name to give to the policy chain function.
+ * @param policies - The policies to apply to the request.
+ * @param out - The function to call after the policies have been applied.
+ */
+export function createPolicyChain<Out extends (ctx: HttpContext, ...rest: any[]) => void>(
+  name: string,
+  policies: Policy[],
+  out: Out,
+): Out {
+  let outParams: any[];
+  if (policies.length === 0) {
+    return out;
+  }
+
+  function applyPolicy(ctx: HttpContext, index: number) {
+    if (index >= policies.length) {
+      return out(ctx, ...outParams);
+    }
+
+    policies[index](ctx, function nextPolicy(nextRequest) {
+      applyPolicy(
+        {
+          ...ctx,
+          request: nextRequest ?? ctx.request,
+        },
+        index + 1,
+      );
+    });
+  }
+
+  return {
+    [name](ctx: HttpContext, ...params: any[]) {
+      outParams = params;
+      applyPolicy(ctx, 0);
+    },
+  }[name] as Out;
+}
+
+/**
+ * The type of an error encountered during request validation.
+ */
+export type ValidationError = string;
+
+/**
+ * An object specifying the policies for a given route configuration.
+ */
+export type RoutePolicies<RouteConfig extends { [k: string]: object }> = {
+  [Interface in keyof RouteConfig]?: {
+    before?: Policy[];
+    after?: Policy[];
+    methodPolicies?: {
+      [Method in keyof RouteConfig[Interface]]?: Policy[];
+    };
+  };
+};
+
+/**
+ * Create a policy chain for a given route.
+ *
+ * This function calls `createPolicyChain` internally and orders the policies based on the route configuration.
+ *
+ * Interface-level `before` policies run first, then method-level policies, then Interface-level `after` policies.
+ *
+ * @param name - The name to give to the policy chain function.
+ * @param routePolicies - The policies to apply to the routes (part of the route configuration).
+ * @param interfaceName - The name of the interface that the route belongs to.
+ * @param methodName - The name of the method that the route corresponds to.
+ * @param out - The function to call after the policies have been applied.
+ */
+export function createPolicyChainForRoute<
+  RouteConfig extends { [k: string]: object },
+  InterfaceName extends keyof RouteConfig,
+  Out extends (ctx: HttpContext, ...rest: any[]) => void,
+>(
+  name: string,
+  routePolicies: RoutePolicies<RouteConfig>,
+  interfaceName: InterfaceName,
+  methodName: keyof RouteConfig[InterfaceName],
+  out: Out,
+): Out {
+  return createPolicyChain(
+    name,
+    [
+      ...(routePolicies[interfaceName]?.before ?? []),
+      ...(routePolicies[interfaceName]?.methodPolicies?.[methodName] ?? []),
+      ...(routePolicies[interfaceName]?.after ?? []),
+    ],
+    out,
+  );
+}
+
+/**
+ * Options for configuring a router with additional functionality.
+ */
+export interface RouterOptions<
+  RouteConfig extends { [k: string]: object } = { [k: string]: object },
+> {
+  /**
+   * The base path of the router.
+   *
+   * This should include any leading slashes, but not a trailing slash, and should not include any component
+   * of the URL authority (e.g. the scheme, host, or port).
+   *
+   * Defaults to "".
+   */
+  basePath?: string;
+
+  /**
+   * A list of policies to apply to all routes _before_ routing.
+   *
+   * Policies are applied in the order they are listed.
+   *
+   * By default, the policy list is empty.
+   *
+   * Policies _MUST_ call `next()` to pass the request to the next policy _OR_ call `response.end()` to terminate
+   * the response and _MUST NOT_ do both.
+   */
+  policies?: Policy[];
+
+  /**
+   * A record of policies that apply to specific routes.
+   *
+   * The policies are provided as a nested record where the keys are the business-logic interface names, and the values
+   * are records of the method names in the given interface and the policies that apply to them.
+   *
+   * By default, no additional policies are applied to the routes.
+   *
+   * Policies _MUST_ call `next()` to pass the request to the next policy _OR_ call `response.end()` to terminate
+   * the response and _MUST NOT_ do both.
+   */
+  routePolicies?: RoutePolicies<RouteConfig>;
+
+  /**
+   * A handler for requests where the resource is not found.
+   *
+   * The router will call this function when no route matches the incoming request.
+   *
+   * If this handler is not provided, a 404 Not Found response with a text body will be returned.
+   *
+   * You _MUST_ call `response.end()` to terminate the response.
+   *
+   * This handler is unreachable when using the Express middleware, as it will forward non-matching requests to the
+   * next middleware layer in the stack.
+   *
+   * @param ctx - The HTTP context for the request.
+   */
+  onRequestNotFound?: (ctx: HttpContext) => void;
+
+  /**
+   * A handler for requests that fail to validate inputs.
+   *
+   * If this handler is not provided, a 400 Bad Request response with a JSON body containing some basic information
+   * about the error will be returned to the client.
+   *
+   * You _MUST_ call `response.end()` to terminate the response.
+   *
+   * @param ctx - The HTTP context for the request.
+   * @param route - The route that was matched.
+   * @param error - The validation error that was thrown.
+   */
+  onInvalidRequest?: (ctx: HttpContext, route: string, error: ValidationError) => void;
+
+  /**
+   * A handler for requests that throw an error during processing.
+   *
+   * If this handler is not provided, a 500 Internal Server Error response with a text body and no error details will be
+   * returned to the client.
+   *
+   * You _MUST_ call `response.end()` to terminate the response.
+   *
+   * If this handler itself throws an Error, the router will respond with a 500 Internal Server Error
+   *
+   * @param ctx - The HTTP context for the request.
+   * @param error - The error that was thrown.
+   */
+  onInternalError?(ctx: HttpContext, error: Error): void;
+}
+
+/** Context information for operations carried over the HTTP protocol. */
+export interface HttpContext {
+  /** The incoming request to the server. */
+  request: http.IncomingMessage;
+  /** The outgoing response object. */
+  response: http.ServerResponse;
+
+  /**
+   * Error handling functions provided by the HTTP router. Service implementations may call these methods in case a
+   * resource is not found, a request is invalid, or an internal error occurs.
+   *
+   * These methods will respond to the client with the appropriate status code and message.
+   */
+  errorHandlers: {
+    /**
+     * Signals that the requested resource was not found.
+     */
+    onRequestNotFound: Exclude<RouterOptions["onRequestNotFound"], undefined>;
+    /**
+     * Signals that the request was invalid.
+     */
+    onInvalidRequest: Exclude<RouterOptions["onInvalidRequest"], undefined>;
+    /**
+     * Signals that an internal error occurred.
+     */
+    onInternalError: Exclude<RouterOptions["onInternalError"], undefined>;
+  };
+}

package/src/http/index.ts

@@ -0,0 +1,81 @@
+// Copyright (c) Microsoft Corporation
+// Licensed under the MIT license.
+
+import { NoTarget } from "@typespec/compiler";
+import { HttpServer, HttpService, getHttpService, getServers } from "@typespec/http";
+import { JsContext, Module, createModule } from "../ctx.js";
+import { reportDiagnostic } from "../lib.js";
+import { getOpenApi3Emitter, getOpenApi3ServiceRecord, tryGetOpenApi3 } from "../util/openapi3.js";
+import { emitRawServer } from "./server/index.js";
+import { emitRouter } from "./server/router.js";
+
+/**
+ * Additional context items used by the HTTP emitter.
+ */
+export interface HttpContext extends JsContext {
+  /**
+   * The HTTP-level representation of the service.
+   */
+  httpService: HttpService;
+  /**
+   * The root module for HTTP-specific code.
+   */
+  httpModule: Module;
+  /**
+   * The server definitions of the service (\@server decorator)
+   */
+  servers: HttpServer[];
+}
+
+/**
+ * Emits bindings for the service to be carried over the HTTP protocol.
+ */
+export async function emitHttp(ctx: JsContext) {
+  const [httpService, diagnostics] = getHttpService(ctx.program, ctx.service.type);
+
+  const diagnosticsAreError = diagnostics.some((d) => d.severity === "error");
+
+  if (diagnosticsAreError) {
+    reportDiagnostic(ctx.program, {
+      code: "http-emit-disabled",
+      target: NoTarget,
+      messageId: "default",
+    });
+    return;
+  }
+
+  const servers = getServers(ctx.program, ctx.service.type) ?? [];
+
+  const httpModule = createModule("http", ctx.generatedModule);
+
+  const httpContext: HttpContext = {
+    ...ctx,
+    httpService,
+    httpModule,
+    servers,
+  };
+
+  const openapi3Emitter = await getOpenApi3Emitter();
+  const openapi3 = await tryGetOpenApi3(ctx.program, ctx.service);
+
+  if (openapi3) {
+    const openApiDocumentModule = createModule("openapi3", httpModule);
+
+    openApiDocumentModule.declarations.push([
+      `export const openApiDocument = ${JSON.stringify(openapi3)}`,
+    ]);
+  } else if (openapi3Emitter) {
+    const serviceRecord = await getOpenApi3ServiceRecord(ctx.program, ctx.service);
+
+    reportDiagnostic(ctx.program, {
+      code: "openapi3-document-not-generated",
+      target: ctx.service.type,
+      messageId: serviceRecord?.versioned ? "versioned" : "unable",
+    });
+  }
+
+  const operationsModule = createModule("operations", httpModule);
+
+  const serverRawModule = emitRawServer(httpContext, operationsModule);
+  emitRouter(httpContext, httpService, serverRawModule);
+}