Skip to content

Latest commit

 

History

History
89 lines (75 loc) · 3.42 KB

README.md

File metadata and controls

89 lines (75 loc) · 3.42 KB
Raw

Middlewares for Common Environments

If you want to use Node.js middleware, read main README.md instead. If you need to implement a handler/middleware for another environment, read this document.

The middleware directory contains the generic HTTP handler. Each sub-directory (e.g., node) exposes an HTTP handler/middleware for a specific environment.

middleware
├── handle-request.ts
├── on-unhandled-request-default.ts
├── types.ts
├── node/
├── web-worker/ (Cloudflare Workers & Deno)
└── deno/ (to be implemented)

Generic HTTP Handler

handleRequest function is an abstract HTTP handler which accepts an OctokitRequest and returns an OctokitResponse if the request matches any predefined route.

Different environments (e.g., Node.js, Cloudflare Workers, Deno, etc.) exposes different APIs when processing HTTP requests (e.g., IncomingMessage for Node.js, Request for Cloudflare workers, etc.). Two HTTP-related types (OctokitRequest and OctokitResponse) are generalized to make an abstract HTTP handler possible.

To share the behavior and capability with the existing Node.js middleware (and be compatible with OAuth user authentication strategy in the browser), it is better to implement your HTTP handler/middleware based on handleRequest function.

handleRequest function takes three parameters:

name type description
app OAuthApp instance Required.
options.pathPrefix string

All exposed paths will be prefixed with the provided prefix. Defaults to "/api/github/oauth"
request OctokitRequest Generalized HTTP request in `OctokitRequest` type.

Adapt for an Environment

Implementing an HTTP handler/middleware for a certain environment involves three steps:

  1. Write a function to parse the HTTP request (e.g., IncomingMessage in Node.js) into an OctokitRequest object. See node/parse-request.ts for reference.
  2. Write a function to render an OctokitResponse object (e.g., as ServerResponse in Node.js). See node/send-response.ts for reference.
  3. Expose an HTTP handler/middleware in the dialect of the environment which performs three steps:
    1. Parse the HTTP request using (1).
    2. Process the OctokitRequest object using handleRequest. If the request is not handled by handleRequest (the request does not match any predefined route), onUnhandledRequestDefault can be used to generate a 404 response consistently.
    3. Render the OctokitResponse object using (2).