Merge pull request #298 from pulsar-edit/v2-endpoint-declaration

Endpoint `v2` declaration

Author: confused-Techie

src/buildContext.js

@@ -0,0 +1,69 @@
+// An ephemeral context that's built per every single request
+// Once tests stop relying on the structure of the `context.js` object
+// we can move this to be side-by-side of the original context
+const context = require("./context.js");
+
+module.exports = (req, res, endpoint) => {
+
+  // Build parameters
+  let params = {};
+  for (const param in endpoint.params) {
+    if (typeof endpoint.params[param] === "function") {
+      params[param] = endpoint.params[param](context, req);
+    } else {
+      // TODO use a JSON-Schema validator to extract params
+    }
+  }
+  
+  return {
+    req: req,
+    res: res,
+    endpoint: endpoint,
+    params: params,
+    timecop: new Timecop(),
+    ...context,
+    // Any items that need to overwrite original context keys should be put after
+    // the spread operator
+    callStack: new context.callStack(),
+    query: require("./query_parameters/index.js")
+  };
+};
+
+class Timecop {
+  constructor() {
+    this.timetable = {};
+  }
+
+  start(service) {
+    this.timetable[service] = {
+      start: performance.now(),
+      end: undefined,
+      duration: undefined
+    };
+  }
+
+  end(service) {
+    if (!this.timetable[service]) {
+      this.timetable[service] = {};
+      this.timetable[service].start = 0;
+      // Wildly incorrect date, more likely to be caught
+      // rather than letting the time taken be 0ms
+    }
+    this.timetable[service].end = performance.now();
+    this.timetable[service].duration = this.timetable[service].end - this.timetable[service].start;
+  }
+
+  toHeader() {
+    let str = "";
+
+    for (const service in this.timetable) {
+      if (str.length > 0) {
+        str = str + ", ";
+      }
+
+      str = str + `${service};dur=${Number(this.timetable[service].duration).toFixed(2)}`;
+    }
+
+    return str;
+  }
+}

src/controllers/README.md

@@ -0,0 +1,91 @@
+# Controllers (endpoints)
+
+Within this directory is the definition of each endpoint served by the Pulsar Package Registry Backend.
+
+Each file represents an endpoint, named like `methodPathSubpath`.
+Which would translate something like `GET /api/package/:packageName` => `getPackagePackageName.js`.
+
+Within the file is an object exported that defines the endpoint and all of it's key features.
+Which not only builds the actual endpoints that users interact with, it also builds the SwaggerUI documentation that's served alongside the site.
+
+In an attempt to support the most flexibility in any future changes of this schema, there are multiple valid versions, allowing any changes to the schema to be subtle and peice-mealed as needed.
+
+## Schema v1 (default)
+
+If the top level `version` key is absent, or set to `1` then the endpoint is using the `v1` schema, which is defined below:
+
+```js
+module.exports = {
+  // version: 1,
+  // endpointKind: "raw", // An optional endpointKind value, which if `raw` means once `logic` is called no further processing is done on the request.
+  docs: {
+    // Almost every key corresponds to SwaggerUIs schema
+    summary: "A summary of the endpoint, used directly in the SwaggerUI documentation.",
+    description: "Another SwaggerUI key for a more in-depth explanation.",
+    responses: {
+      // All intended responses of the endpoint
+      200: {
+        // The HTTP status followed by a description and a definition of the content within the response.
+        // Refer to SwaggerUIs documentation.
+        description: "",
+        content: { "application/json": "$userObjectPrivate" }
+        // ^^ A key difference is when defining the object, we can reference complex objects by appending a `$`
+      }
+    }
+  },
+  endpoint: {
+    method: "GET", // The endpoint method
+    paths: [""], // An array of exact endpoint paths, written in ExpressJS style
+    rateLimit: "", // An enum supporting different rate limit values.
+    successStatus: 200, // The HTTP status code returned on success
+    options: {
+      // Key-Value pairs of HTTP headers that should be returned on an `OPTIONS` request to the path.
+    },
+    params: {
+      // Parameters that are invoked automatically to decode their value from the HTTP req.
+      auth: (context, req) => {}
+    }
+  },
+  // The following are methods that will be called automatically during the HTTP request lifecycle
+  async preLogic(req, res, context) {}, // Called before the `logic` function. Helpful for modifying any request details
+  async logic(params, context) {}, // The main logic function called for the endpoint
+  async postLogic(req, res, context) {}, // Called right after the initial logic call.
+  async postReturnHTTP(req, res, context, obj) {}, // Called after returning to the client, allowing for any computations the user shouldn't wait on. `obj` is the return of the `logic` call
+};
+```
+
+## Schema v2
+
+If the top level `version` key is set to `1` then the endpoint schema is defined as:
+
+```js
+module.exports = {
+  version: 2,
+  docs: {}, // Identical to v1
+  headers: {}, // Key-Value pairs of headers. Which will be applied during an `OPTIONS`
+  // request, as well as automatically on every request to this path.
+  endpoint: {
+    method: "", // Same as v1
+    path: "", // A string or array of strings, defining the path, again in ExpressJS syntax.
+  },
+  params: {
+    auth: {
+      // A JSON Schema object of the parameters schema, that will be decoded automatically.
+      // Or if a function will retain backwards compatible behavior
+      type: "string"
+    }
+  },
+  async preLogic(ctx) {}, // Called with just the shared context
+  async logic(ctx) {}, // Called with just the shared context
+  async postLogic(ctx) {}, // Called with just the shared context
+  async postHttp(ctx, obj) {}, // Called with the shared context, and the return obj of `logic`
+};
+```
+
+As you may have noticed the biggest difference between v2 and v1 is that v2 only calls each method with a shared context variable. This shared context is built dynamically for each request and includes all details of the request within it, meaning we don't need specialized calls such as `preLogic` or `postLogic` (although they are still supported just in case).
+
+Additionally, `v2` takes even more values defined in this schema and automatically injects them into the documentation and live requests, attempting to define even more of the request semantics as an object.
+
+Lastly, in `v2` the value of a `header` key can begin with a `%` which means it's value will be replaced with the corresponding value from the shared context.
+
+Such as `%timecop.toHeader` => `return ctx.timecop.toHeader();`.

src/controllers/getOwnersOwnerName.js

@@ -1,4 +1,5 @@
 module.exports = {
+  version: 2,
   docs: {
     summary: "List all packages published under a single owner.",
     responses: {
@@ -10,15 +11,15 @@ module.exports = {
       },
     },
   },
+  headers: {
+    Allow: "GET",
+    "X-Content-Type-Options": "nosniff",
+    "Server-Timing": "%timecop.toHeader"
+  },
   endpoint: {
     method: "GET",
-    paths: ["/api/owners/:ownerName"],
-    rateLimit: "generic",
-    successStatus: 200,
-    options: {
-      Allow: "GET",
-      "X-Content-Type-Options": "nosniff",
-    },
+    path: "/api/owners/:ownerName",
+    rateLimit: "generic"
   },
   params: {
     page: (context, req) => {
@@ -35,37 +36,40 @@ module.exports = {
     },
   },
 
-  async logic(params, context) {
-    const callStack = new context.callStack();
+  async logic(ctx) {
 
-    const packages = await context.database.getSortedPackages(params);
+    ctx.timecop.start("db");
+    const packages = await ctx.database.getSortedPackages(ctx.params);
+    ctx.timecop.end("db");
 
-    callStack.addCall("db.getSortedPackages", packages);
+    ctx.callStack.addCall("db.getSortedPackages", packages);
 
     if (!packages.ok) {
-      const sso = new context.sso();
+      const sso = new ctx.sso();
 
-      return sso.notOk().addContent(packages).assignCalls(callStack);
+      return sso.notOk().addContent(packages).assignCalls(ctx.callStack);
     }
 
-    const packObjShort = await context.models.constructPackageObjectShort(
+    ctx.timecop.start("construct");
+    const packObjShort = await ctx.models.constructPackageObjectShort(
       packages.content
     );
 
     const packArray = Array.isArray(packObjShort)
       ? packObjShort
       : [packObjShort];
 
-    const ssoP = new context.ssoPaginate();
+    const ssoP = new ctx.ssoPaginate();
 
     ssoP.resultCount = packages.pagination.count;
     ssoP.totalPages = packages.pagination.total;
     ssoP.limit = packages.pagination.limit;
     ssoP.buildLink(
-      `${context.config.server_url}/api/owners/${params.owner}`,
+      `${ctx.config.server_url}/api/owners/${ctx.params.owner}`,
       packages.pagination.page,
-      params
+      ctx.params
     );
+    ctx.timecop.end("construct");
 
     return ssoP.isOk().addContent(packArray);
   },

src/setupEndpoints.js

@@ -4,6 +4,7 @@ const { MemoryStore } = require("express-rate-limit");
 
 const endpoints = require("./controllers/endpoints.js");
 const context = require("./context.js");
+const buildContext = require("./buildContext.js");
 
 const app = express();
 
@@ -45,6 +46,66 @@ app.set("trust proxy", true);
 
 app.use("/swagger-ui", express.static("docs/swagger"));
 
+const endpointHandlerV2 = async function (node, req, res) {
+  const ctx = buildContext(req, res, node);
+
+  if (typeof node.preLogic === "function") {
+    await node.preLogic(ctx);
+  }
+
+  let obj; // Logic return
+  try {
+    obj = await node.logic(ctx);
+  } catch(err) {
+    // Main logic of endpoint has failed, return gracefully
+    obj = new ctx.sso();
+    obj.notOk()
+       .addContent(err)
+       .addMessage("An unexpected error has occurred.")
+       .addShort("server_error");
+  }
+
+  if (typeof node.postLogic === "function") {
+    await node.postLogic(ctx);
+  }
+
+  // Before letting SSO take over the HTTP return, lets add headers
+  for (const header in node.headers) {
+    if (node.headers[header].startsWith("%")) {
+      // This is a replacement header value
+      const headerFuncCall = node.headers[header].replace("%", "");
+
+      // Drill down keypath defined in the func call
+      let headerCallCtx = ctx;
+      const namespaces = headerFuncCall.split(".");
+      let func = namespaces.pop();
+      for (let i = 0; i < namespaces.length; i++) {
+        headerCallCtx = headerCallCtx[namespaces[i]];
+      }
+
+      let headerFuncResult;
+
+      if (typeof headerCallCtx[func] === "function") {
+        headerFuncResult = headerCallCtx[func]();
+      } else {
+        console.log(`Couldn't locate value for header: Key: ${header}; Value: ${node.headers[header]}`);
+        headerFuncResult = "";
+      }
+
+      res.append(header, headerFuncResult);
+    } else {
+      res.append(header, node.headers[header]);
+    }
+  }
+  obj.handleReturnHTTP(req, res, context);
+
+  if (typeof node.postReturnHTTP === "function") {
+    await node.postReturnHTTP(ctx, obj);
+  }
+
+  return;
+};
+
 const endpointHandler = async function (node, req, res) {
   let params = {};
 
@@ -97,9 +158,23 @@ const endpointHandler = async function (node, req, res) {
 const pathOptions = [];
 
 for (const node of endpoints) {
-  for (const path of node.endpoint.paths) {
-    let limiter = genericLimit;
+  let paths;
+
+  if (node.version === 2) {
+    if (!Array.isArray(node.endpoint.path)) {
+      paths = [node.endpoint.path];
+    } else {
+      paths = node.endpoint.path;
+    }
+  } else {
+    // implict V1
+    paths = node.endpoint.paths;
+  }
 
+  for (const path of paths) {
+    let limiter = genericLimit;
+    // TODO should v2 endpoints determine ratelimit by strings like this?
+    // Or by decoding a `RateLimit-Policy` header?
     if (node.endpoint.rateLimit === "auth") {
       limiter = authLimit;
     } else if (node.endpoint.rateLimit === "generic") {
@@ -108,28 +183,44 @@ for (const node of endpoints) {
 
     if (!pathOptions.includes(path)) {
       app.options(path, genericLimit, async (req, res) => {
-        res.header(node.endpoint.options);
+        let headerObj;
+
+        if (node.version === 2) {
+          headerObj = node.headers;
+          // TODO handle header value replacements
+        } else {
+          // v1
+          headerObj = node.endpoint.options;
+        }
+
+        res.header(headerObj);
         res.sendStatus(204);
         return;
       });
 
       pathOptions.push(path);
     }
 
+    let handlerFunc = endpointHandler;
+
+    if (node.version === 2) {
+      handlerFunc = endpointHandlerV2;
+    }
+
     switch (node.endpoint.method) {
       case "GET":
         app.get(path, limiter, async (req, res) => {
-          await endpointHandler(node, req, res);
+          await handlerFunc(node, req, res);
         });
         break;
       case "POST":
         app.post(path, limiter, async (req, res) => {
-          await endpointHandler(node, req, res);
+          await handlerFunc(node, req, res);
         });
         break;
       case "DELETE":
         app.delete(path, limiter, async (req, res) => {
-          await endpointHandler(node, req, res);
+          await handlerFunc(node, req, res);
         });
         break;
       default: