feat: createNodeMiddleware() (#509)

Author: gr2m

README.md

@@ -33,10 +33,13 @@
     "@types/jest": "^26.0.9",
     "@types/json-schema": "^7.0.7",
     "@types/node": "^14.0.14",
+    "@types/node-fetch": "^2.5.8",
     "@types/prettier": "^2.0.0",
     "axios": "^0.21.0",
+    "express": "^4.17.1",
     "get-port": "^5.0.0",
     "jest": "^26.2.2",
+    "node-fetch": "^2.6.1",
     "prettier": "^2.0.1",
     "prettier-plugin-packagejson": "^2.2.9",
     "semantic-release": "^17.0.0",

package-lock.json

@@ -1,8 +1,8 @@
 export interface Logger {
-  debug: (message: string) => unknown;
-  info: (message: string) => unknown;
-  warn: (message: string) => unknown;
-  error: (message: string) => unknown;
+  debug: (...data: any[]) => void;
+  info: (...data: any[]) => void;
+  warn: (...data: any[]) => void;
+  error: (...data: any[]) => void;
 }
 
 export const createLogger = (logger?: Partial<Logger>): Logger => ({

package.json

@@ -1,9 +1,9 @@
 import { IncomingMessage, ServerResponse } from "http";
 import { createLogger } from "./createLogger";
 import { createEventHandler } from "./event-handler/index";
-import { createMiddleware } from "./middleware/index";
-import { middleware } from "./middleware/middleware";
-import { verifyAndReceive } from "./middleware/verify-and-receive";
+import { createMiddleware } from "./middleware-legacy/index";
+import { middleware } from "./middleware-legacy/middleware";
+import { verifyAndReceive } from "./middleware-legacy/verify-and-receive";
 import { sign } from "./sign/index";
 import {
   EmitterWebhookEvent,
@@ -16,6 +16,8 @@ import {
 } from "./types";
 import { verify } from "./verify/index";
 
+export { createNodeMiddleware } from "./middleware/node/index";
+
 // U holds the return value of `transform` function in Options
 class Webhooks<TTransformed = unknown> {
   public sign: (payload: string | object) => string;
@@ -31,14 +33,18 @@ class Webhooks<TTransformed = unknown> {
     callback: HandlerFunction<E, TTransformed>
   ) => void;
   public receive: (event: EmitterWebhookEvent) => Promise<void>;
+  public verifyAndReceive: (
+    options: EmitterWebhookEvent & { signature: string }
+  ) => Promise<void>;
+
+  /**
+   * @deprecated use `createNodeMiddleware(webhooks)` instead
+   */
   public middleware: (
     request: IncomingMessage,
     response: ServerResponse,
     next?: (err?: any) => void
   ) => void | Promise<void>;
-  public verifyAndReceive: (
-    options: EmitterWebhookEvent & { signature: string }
-  ) => Promise<void>;
 
   constructor(options: Options<TTransformed>) {
     if (!options || !options.secret) {
@@ -53,21 +59,38 @@ class Webhooks<TTransformed = unknown> {
       log: createLogger(options.log),
     };
 
+    if ("path" in options) {
+      state.log.warn(
+        "[@octokit/webhooks] `path` option is deprecated and will be removed in a future release of `@octokit/webhooks`. Please use `createNodeMiddleware(webhooks, { path })` instead"
+      );
+    }
+
     this.sign = sign.bind(null, options.secret);
     this.verify = verify.bind(null, options.secret);
     this.on = state.eventHandler.on;
     this.onAny = state.eventHandler.onAny;
     this.onError = state.eventHandler.onError;
     this.removeListener = state.eventHandler.removeListener;
     this.receive = state.eventHandler.receive;
-    this.middleware = middleware.bind(null, state);
     this.verifyAndReceive = verifyAndReceive.bind(null, state);
+
+    this.middleware = function deprecatedMiddleware(
+      request: IncomingMessage,
+      response: ServerResponse,
+      next?: (err?: any) => void
+    ) {
+      state.log.warn(
+        "[@octokit/webhooks] `webhooks.middleware` is deprecated and will be removed in a future release of `@octokit/webhooks`. Please use `createNodeMiddleware(webhooks)` instead"
+      );
+      return middleware(state, request, response, next);
+    };
   }
 }
 
 /** @deprecated `createWebhooksApi()` is deprecated and will be removed in a future release of `@octokit/webhooks`, please use the `Webhooks` class instead */
 const createWebhooksApi = <TTransformed>(options: Options<TTransformed>) => {
-  console.error(
+  const log = createLogger(options.log);
+  log.warn(
     "[@octokit/webhooks] `createWebhooksApi()` is deprecated and will be removed in a future release of `@octokit/webhooks`, please use the `Webhooks` class instead"
   );
   return new Webhooks<TTransformed>(options);

src/createLogger.ts

@@ -3,15 +3,15 @@
 If you only need the middleware with access to the `.sign()`, `.verify()` or the receiver’s `.receive()` method, you can use the webhooks middleware directly
 
 ```js
-const { createMiddleware } = require('@octokit/webhooks')
+const { createMiddleware } = require("@octokit/webhooks");
 const middleware = createMiddleware({
-  secret: 'mysecret',
-  path: '/github-webhooks'
-})
+  secret: "mysecret",
+  path: "/github-webhooks",
+});
 
-middleware.on('installation', asyncInstallationHook)
+middleware.on("installation", asyncInstallationHook);
 
-require('http').createServer(middleware).listen(3000)
+require("http").createServer(middleware).listen(3000);
 ```
 
 ## API

src/index.ts

@@ -0,0 +1,12 @@
+import { IncomingMessage } from "http";
+
+const WEBHOOK_HEADERS = [
+  "x-github-event",
+  "x-hub-signature-256",
+  "x-github-delivery",
+];
+
+// https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#delivery-headers
+export function getMissingHeaders(request: IncomingMessage) {
+  return WEBHOOK_HEADERS.filter((header) => !(header in request.headers));
+}

src/middleware/README.md src/middleware-legacy/README.md

@@ -0,0 +1,36 @@
+import { WebhookEvent } from "@octokit/webhooks-definitions/schema";
+// @ts-ignore to address #245
+import AggregateError from "aggregate-error";
+import { IncomingMessage } from "http";
+
+declare module "http" {
+  interface IncomingMessage {
+    body?: WebhookEvent;
+  }
+}
+
+export function getPayload(request: IncomingMessage): Promise<WebhookEvent> {
+  // If request.body already exists we can stop here
+  // See https://github.com/octokit/webhooks.js/pull/23
+
+  if (request.body) return Promise.resolve(request.body);
+
+  return new Promise((resolve, reject) => {
+    let data = "";
+
+    request.setEncoding("utf8");
+
+    // istanbul ignore next
+    request.on("error", (error) => reject(new AggregateError([error])));
+    request.on("data", (chunk) => (data += chunk));
+    request.on("end", () => {
+      try {
+        resolve(JSON.parse(data));
+      } catch (error) {
+        error.message = "Invalid JSON";
+        error.status = 400;
+        reject(new AggregateError([error]));
+      }
+    });
+  });
+}

src/middleware/get-missing-headers.ts src/middleware-legacy/get-missing-headers.ts

@@ -0,0 +1,20 @@
+import { createLogger } from "../../createLogger";
+import { Webhooks } from "../../index";
+import { middleware } from "./middleware";
+import { onUnhandledRequestDefault } from "./on-unhandled-request-default";
+import { MiddlewareOptions } from "./types";
+
+export function createNodeMiddleware(
+  webhooks: Webhooks,
+  {
+    path = "/api/github/webhooks",
+    onUnhandledRequest = onUnhandledRequestDefault,
+    log = createLogger(),
+  }: MiddlewareOptions = {}
+) {
+  return middleware.bind(null, webhooks, {
+    path,
+    onUnhandledRequest,
+    log,
+  } as Required<MiddlewareOptions>);
+}

src/middleware/get-payload.ts src/middleware-legacy/get-payload.ts

@@ -0,0 +1,81 @@
+import { IncomingMessage, ServerResponse } from "http";
+
+import { WebhookEventName } from "@octokit/webhooks-definitions/schema";
+
+import { Webhooks } from "../../index";
+import { WebhookEventHandlerError } from "../../types";
+import { MiddlewareOptions } from "./types";
+import { onUnhandledRequestDefault } from "./on-unhandled-request-default";
+import { getMissingHeaders } from "./get-missing-headers";
+import { getPayload } from "./get-payload";
+
+export async function middleware(
+  webhooks: Webhooks,
+  options: Required<MiddlewareOptions>,
+  request: IncomingMessage,
+  response: ServerResponse,
+  next?: Function
+) {
+  const { pathname } = new URL(request.url as string, "http://localhost");
+
+  const isUnknownRoute = request.method !== "POST" || pathname !== options.path;
+  const isExpressMiddleware = typeof next === "function";
+  if (!isExpressMiddleware && isUnknownRoute) {
+    options.log.debug(`not found: ${request.method} ${request.url}`);
+    return onUnhandledRequestDefault(request, response);
+  }
+
+  const missingHeaders = getMissingHeaders(request).join(", ");
+
+  if (missingHeaders) {
+    response.writeHead(400, {
+      "content-type": "application/json",
+    });
+    response.end(
+      JSON.stringify({
+        error: `Required headers missing: ${missingHeaders}`,
+      })
+    );
+
+    return;
+  }
+
+  const eventName = request.headers["x-github-event"] as WebhookEventName;
+  const signatureSHA256 = request.headers["x-hub-signature-256"] as string;
+  const id = request.headers["x-github-delivery"] as string;
+
+  options.log.debug(`${eventName} event received (id: ${id})`);
+
+  // GitHub will abort the request if it does not receive a response within 10s
+  // See https://github.com/octokit/webhooks.js/issues/185
+  let didTimeout = false;
+  const timeout = setTimeout(() => {
+    didTimeout = true;
+    response.statusCode = 202;
+    response.end("still processing\n");
+  }, 9000).unref();
+
+  try {
+    const payload = await getPayload(request);
+
+    await webhooks.verifyAndReceive({
+      id: id,
+      name: eventName as any,
+      payload: payload as any,
+      signature: signatureSHA256,
+    });
+    clearTimeout(timeout);
+
+    if (didTimeout) return;
+
+    response.end("ok\n");
+  } catch (error) {
+    clearTimeout(timeout);
+
+    if (didTimeout) return;
+
+    const statusCode = Array.from(error as WebhookEventHandlerError)[0].status;
+    response.statusCode = typeof statusCode !== "undefined" ? statusCode : 500;
+    response.end(error.toString());
+  }
+}

src/middleware/index.ts src/middleware-legacy/index.ts

@@ -0,0 +1,15 @@
+import { IncomingMessage, ServerResponse } from "http";
+
+export function onUnhandledRequestDefault(
+  request: IncomingMessage,
+  response: ServerResponse
+) {
+  response.writeHead(404, {
+    "content-type": "application/json",
+  });
+  response.end(
+    JSON.stringify({
+      error: `Unknown route: ${request.method} ${request.url}`,
+    })
+  );
+}

src/middleware/isnt-webhook.ts src/middleware-legacy/isnt-webhook.ts

@@ -0,0 +1,12 @@
+import { IncomingMessage, ServerResponse } from "http";
+
+import { Logger } from "../../createLogger";
+
+export type MiddlewareOptions = {
+  path?: string;
+  log?: Logger;
+  onUnhandledRequest?: (
+    request: IncomingMessage,
+    response: ServerResponse
+  ) => void;
+};

src/middleware/middleware.ts src/middleware-legacy/middleware.ts

@@ -19,6 +19,7 @@ export function verify(
 
   const signatureBuffer = Buffer.from(signature);
   const algorithm = getAlgorithm(signature);
+
   const verificationBuffer = Buffer.from(
     sign({ secret, algorithm }, eventPayload)
   );

src/middleware/verify-and-receive.ts src/middleware-legacy/verify-and-receive.ts

@@ -1,6 +1,6 @@
 import { EventEmitter } from "events";
 import { Buffer } from "buffer";
-import { createMiddleware } from "../../src/middleware";
+import { createMiddleware } from "../../src/middleware-legacy";
 
 enum RequestMethodType {
   POST = "POST",