@quantcdn/edge-conformance 0.0.0-stage → 0.1.0

package/src/index.js

@@ -0,0 +1,215 @@
+/**
+ * The edge-conformance runner.
+ * It loads the JSON vectors, gives each case to an adapter and compares the
+ * adapter's answer with the case's expected values.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const VECTORS_DIR = fileURLToPath(new URL('../vectors/', import.meta.url));
+
+/** The suite tags. Each case has exactly one; it names the vector directory. */
+export const SUITE_TAGS = ['rules', 'static', 'functions'];
+
+/** Every tag that a case can have. */
+export const TAGS = [...SUITE_TAGS, 'unverified'];
+
+/** The adapter operations, and the arguments that each one gets from a case input. */
+export const OPS = {
+  matchRule: (input) => [input.rules, input.functions || [], input.request],
+  serveStatic: (input) => [input.files, input.request],
+  runFunction: (input) => [input],
+  serveSite: (input) => [input]
+};
+
+/** The arguments that the runner passes to adapter[op] for a case input. */
+export function adapterArgs(op, input) {
+  return OPS[op](input);
+}
+
+async function vectorFiles(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const nested = await Promise.all(entries
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((entry) => {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) return vectorFiles(full);
+      return entry.name.endsWith('.json') ? [full] : [];
+    }));
+  return nested.flat();
+}
+
+async function readVectorFile(file, dir) {
+  const suite = path.relative(dir, file).split(path.sep)[0];
+  const data = JSON.parse(await fs.readFile(file, 'utf8'));
+  return data.cases.map((item) => ({ ...item, suite, file: path.relative(dir, file) }));
+}
+
+/**
+ * Load every case from the vectors directory, in file order.
+ * @param {{ dir?: string }} [options]
+ */
+export async function loadCases({ dir = VECTORS_DIR } = {}) {
+  const files = await vectorFiles(dir);
+  const lists = await Promise.all(files.map((file) => readVectorFile(file, dir)));
+  return lists.flat();
+}
+
+/** The cases that have any of the tags. With no tags, every case. */
+export function selectCases(cases, tags) {
+  if (!tags || tags.length === 0) return cases;
+  return cases.filter((item) => item.tags.some((tag) => tags.includes(tag)));
+}
+
+// --- Comparison -------------------------------------------------------------
+
+function lowerKeys(headers = {}) {
+  const result = {};
+  for (const [name, value] of Object.entries(headers)) result[name.toLowerCase()] = value;
+  return result;
+}
+
+function asList(value) {
+  return Array.isArray(value) ? value : [value];
+}
+
+function asText(value) {
+  return Array.isArray(value) ? value.join(', ') : value;
+}
+
+function sameList(expected, actual) {
+  const list = asList(actual);
+  return list.length === expected.length && expected.every((item, i) => item === list[i]);
+}
+
+const MATCHERS = {
+  present: (_expected, actual) => actual !== undefined,
+  startsWith: (expected, actual) => typeof asText(actual) === 'string' && asText(actual).startsWith(expected),
+  includes: (expected, actual) => typeof asText(actual) === 'string' && asText(actual).includes(expected)
+};
+
+function headerMatches(matcher, actual) {
+  if (matcher === null) return actual === undefined;
+  if (Array.isArray(matcher)) return actual !== undefined && sameList(matcher, actual);
+  if (typeof matcher === 'string') return asText(actual) === matcher;
+  return Object.entries(matcher).every(([kind, value]) => MATCHERS[kind] && MATCHERS[kind](value, actual));
+}
+
+function headerFailures(expected = {}, actualHeaders = {}) {
+  const actual = lowerKeys(actualHeaders);
+  return Object.entries(expected)
+    .filter(([name, matcher]) => !headerMatches(matcher, actual[name.toLowerCase()]))
+    .map(([name, matcher]) => `header ${name}: expected ${JSON.stringify(matcher)}, got ${JSON.stringify(actual[name.toLowerCase()])}`);
+}
+
+function isSubset(expected, actual) {
+  if (Array.isArray(expected)) {
+    return Array.isArray(actual) && expected.length === actual.length && expected.every((item, i) => isSubset(item, actual[i]));
+  }
+  if (expected && typeof expected === 'object') {
+    return Boolean(actual) && typeof actual === 'object' && Object.keys(expected).every((key) => isSubset(expected[key], actual[key]));
+  }
+  return expected === actual;
+}
+
+function parseJson(text) {
+  try {
+    return { value: JSON.parse(text) };
+  } catch {
+    return null;
+  }
+}
+
+function jsonFailures(expected, body) {
+  if (expected === undefined) return [];
+  const parsed = parseJson(body);
+  if (!parsed) return [`body: expected JSON, got ${JSON.stringify(body)}`];
+  return isSubset(expected, parsed.value) ? [] : [`body JSON: expected to contain ${JSON.stringify(expected)}, got ${body}`];
+}
+
+function bodyFailures(expect, body) {
+  const failures = [];
+  if (expect.bodyText !== undefined && body !== expect.bodyText) {
+    failures.push(`body: expected ${JSON.stringify(expect.bodyText)}, got ${JSON.stringify(body)}`);
+  }
+  for (const part of expect.bodyIncludes || []) {
+    if (!body.includes(part)) failures.push(`body: expected to include ${JSON.stringify(part)}`);
+  }
+  for (const part of expect.bodyExcludes || []) {
+    if (body.includes(part)) failures.push(`body: expected not to include ${JSON.stringify(part)}`);
+  }
+  return [...failures, ...jsonFailures(expect.bodyJson, body)];
+}
+
+function ruleFailures(expect, actual) {
+  const ruleId = actual && actual.ruleId !== undefined ? actual.ruleId : null;
+  return ruleId === expect.ruleId ? [] : [`ruleId: expected ${JSON.stringify(expect.ruleId)}, got ${JSON.stringify(ruleId)}`];
+}
+
+function responseFailures(expect, actual) {
+  const status = actual.status === expect.status ? [] : [`status: expected ${expect.status}, got ${actual.status}`];
+  const body = actual.bodyText == null ? '' : String(actual.bodyText);
+  return [...status, ...headerFailures(expect.headers, actual.headers), ...bodyFailures(expect, body)];
+}
+
+/**
+ * Compare an adapter answer with a case's expected values.
+ * @returns {string[]} One message for each difference (empty when it passes).
+ */
+export function checkResult(expect, actual) {
+  if ('ruleId' in expect) return ruleFailures(expect, actual);
+  return responseFailures(expect, actual || {});
+}
+
+// --- Run ----------------------------------------------------------------------
+
+function skipReason(adapter, item) {
+  const capabilities = adapter.capabilities || {};
+  const ops = capabilities.ops || Object.keys(OPS).filter((op) => typeof adapter[op] === 'function');
+  if (!ops.includes(item.op) || typeof adapter[item.op] !== 'function') return `the adapter has no ${item.op}`;
+  const excluded = (capabilities.excludeTags || []).find((tag) => item.tags.includes(tag));
+  return excluded ? `the adapter excludes the tag ${excluded}` : null;
+}
+
+function errorText(err) {
+  return err && typeof err.message === 'string' ? err.message : String(err);
+}
+
+async function runCase(adapter, item) {
+  const summary = { id: item.id, op: item.op, tags: item.tags, file: item.file };
+  const reason = skipReason(adapter, item);
+  if (reason) return { ...summary, status: 'skipped', failures: [], reason };
+  try {
+    const input = structuredClone(item.input);
+    const actual = await adapter[item.op](...adapterArgs(item.op, input));
+    const failures = checkResult(item.expect, actual);
+    return { ...summary, status: failures.length ? 'failed' : 'passed', failures };
+  } catch (err) {
+    return { ...summary, status: 'failed', failures: [`the adapter threw: ${errorText(err)}`] };
+  }
+}
+
+function count(results, status) {
+  return results.filter((item) => item.status === status).length;
+}
+
+/**
+ * Run the cases against an adapter.
+ * @param {Object} options
+ * @param {import('./adapter').Adapter} options.adapter
+ * @param {string[]} [options.tags] Run only the cases with any of these tags.
+ * @param {Object[]} [options.cases] The cases (default: every vector).
+ * @returns {Promise<{ passed: number, failed: number, skipped: number, cases: Object[] }>}
+ */
+export async function run({ adapter, tags, cases }) {
+  const selected = selectCases(cases || await loadCases(), tags);
+  const results = [];
+  try {
+    for (const item of selected) results.push(await runCase(adapter, item));
+  } finally {
+    if (typeof adapter.dispose === 'function') await adapter.dispose();
+  }
+  return { passed: count(results, 'passed'), failed: count(results, 'failed'), skipped: count(results, 'skipped'), cases: results };
+}

package/vectors/functions/event.json

@@ -0,0 +1,343 @@
+{
+  "cases": [
+    {
+      "id": "functions-event-request-method",
+      "description": "event.request.method is the request method.",
+      "tags": [
+        "functions"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0001-4000-8000-000000000001",
+        "type": "function",
+        "body": "return new Response(event.request.method);",
+        "request": {
+          "method": "POST",
+          "url": "https://www.example.com/api",
+          "body": "x"
+        }
+      },
+      "expect": {
+        "status": 200,
+        "bodyText": "POST"
+      }
+    },
+    {
+      "id": "functions-event-request-header-names-ignore-case",
+      "description": "event.request.headers.get() ignores the case of the header name.",
+      "tags": [
+        "functions"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0001-4000-8000-000000000001",
+        "type": "function",
+        "body": "return new Response(event.request.headers.get('x-CUSTOM'));",
+        "request": {
+          "method": "GET",
+          "url": "https://www.example.com/api",
+          "headers": {
+            "X-Custom": "abc"
+          }
+        }
+      },
+      "expect": {
+        "status": 200,
+        "bodyText": "abc"
+      }
+    },
+    {
+      "id": "functions-event-request-text-body",
+      "description": "A POST body is readable with event.request.text().",
+      "tags": [
+        "functions"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0001-4000-8000-000000000001",
+        "type": "function",
+        "body": "return new Response(await event.request.text());",
+        "request": {
+          "method": "POST",
+          "url": "https://www.example.com/api",
+          "headers": {
+            "content-type": "text/plain"
+          },
+          "body": "name=ada"
+        }
+      },
+      "expect": {
+        "status": 200,
+        "bodyText": "name=ada"
+      }
+    },
+    {
+      "id": "functions-event-request-json-body",
+      "description": "A JSON POST body is readable with event.request.json().",
+      "tags": [
+        "functions"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0001-4000-8000-000000000001",
+        "type": "function",
+        "body": "return new Response((await event.request.json()).name);",
+        "request": {
+          "method": "POST",
+          "url": "https://www.example.com/api",
+          "headers": {
+            "content-type": "application/json"
+          },
+          "body": "{\"name\":\"ada\"}"
+        }
+      },
+      "expect": {
+        "status": 200,
+        "bodyText": "ada"
+      }
+    },
+    {
+      "id": "functions-get-request-has-no-body",
+      "description": "A GET request has a null body.",
+      "tags": [
+        "functions",
+        "unverified"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0001-4000-8000-000000000001",
+        "type": "function",
+        "body": "return new Response(String(event.request.body === null));",
+        "request": {
+          "method": "GET",
+          "url": "https://www.example.com/api"
+        }
+      },
+      "expect": {
+        "status": 200,
+        "bodyText": "true"
+      }
+    },
+    {
+      "id": "functions-event-request-url",
+      "description": "event.request.url keeps the path and the query of the request.",
+      "tags": [
+        "functions"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0001-4000-8000-000000000001",
+        "type": "function",
+        "body": "const u = new URL(event.request.url);\nreturn new Response(u.pathname + u.search);",
+        "request": {
+          "method": "GET",
+          "url": "https://www.example.com/api/items?page=2"
+        }
+      },
+      "expect": {
+        "status": 200,
+        "bodyText": "/api/items?page=2"
+      }
+    },
+    {
+      "id": "functions-event-url-keeps-the-query",
+      "description": "For a function rule, event.url keeps the query of the request.",
+      "tags": [
+        "functions"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0001-4000-8000-000000000001",
+        "type": "function",
+        "body": "return new Response(new URL(event.url).search);",
+        "request": {
+          "method": "GET",
+          "url": "https://www.example.com/api/items?page=2"
+        }
+      },
+      "expect": {
+        "status": 200,
+        "bodyText": "?page=2"
+      }
+    },
+    {
+      "id": "functions-auth-event-url-is-the-request-url",
+      "description": "For an auth rule, event.url has the request path.",
+      "tags": [
+        "functions"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0002-4000-8000-000000000002",
+        "type": "auth",
+        "body": "return new Response(new URL(event.url).pathname, { status: 401 });",
+        "request": {
+          "method": "GET",
+          "url": "https://www.example.com/members/area"
+        }
+      },
+      "expect": {
+        "status": 401,
+        "bodyText": "/members/area"
+      }
+    },
+    {
+      "id": "functions-client-ip-header",
+      "description": "The quant-client-ip request header holds the client address.",
+      "tags": [
+        "functions"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0001-4000-8000-000000000001",
+        "type": "function",
+        "body": "const ip = event.request.headers.get('quant-client-ip');\nreturn new Response(String(typeof ip === 'string' && ip.length > 0));",
+        "request": {
+          "method": "GET",
+          "url": "https://www.example.com/api"
+        }
+      },
+      "expect": {
+        "status": 200,
+        "bodyText": "true"
+      }
+    },
+    {
+      "id": "functions-client-ip-header-cannot-be-set-by-the-client",
+      "description": "A quant-client-ip header that the client sends does not reach the function.",
+      "tags": [
+        "functions"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0001-4000-8000-000000000001",
+        "type": "function",
+        "body": "return new Response(String(event.request.headers.get('quant-client-ip') !== '203.0.113.9'));",
+        "request": {
+          "method": "GET",
+          "url": "https://www.example.com/api",
+          "headers": {
+            "quant-client-ip": "203.0.113.9"
+          }
+        }
+      },
+      "expect": {
+        "status": 200,
+        "bodyText": "true"
+      }
+    },
+    {
+      "id": "functions-geo-fields",
+      "description": "event.geo has the documented geolocation fields.",
+      "tags": [
+        "functions"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0001-4000-8000-000000000001",
+        "type": "function",
+        "body": "return new Response(JSON.stringify({ country_code: typeof event.geo.country_code, country_name: typeof event.geo.country_name, city: typeof event.geo.city, continent: typeof event.geo.continent, latitude: typeof event.geo.latitude, longitude: typeof event.geo.longitude, utc_offset: typeof event.geo.utc_offset }), { headers: { 'content-type': 'application/json' } });",
+        "request": {
+          "method": "GET",
+          "url": "https://www.example.com/api"
+        }
+      },
+      "expect": {
+        "status": 200,
+        "bodyJson": {
+          "country_code": "string",
+          "country_name": "string",
+          "city": "string",
+          "continent": "string",
+          "latitude": "number",
+          "longitude": "number",
+          "utc_offset": "number"
+        }
+      }
+    },
+    {
+      "id": "functions-node-globals-are-absent",
+      "description": "Node.js globals such as process and require do not exist in a function.",
+      "tags": [
+        "functions"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0001-4000-8000-000000000001",
+        "type": "function",
+        "body": "return new Response(JSON.stringify({ process: typeof process, require: typeof require, module: typeof module, exports: typeof exports, __dirname: typeof __dirname, __filename: typeof __filename }), { headers: { 'content-type': 'application/json' } });",
+        "request": {
+          "method": "GET",
+          "url": "https://www.example.com/api"
+        }
+      },
+      "expect": {
+        "status": 200,
+        "bodyJson": {
+          "process": "undefined",
+          "require": "undefined",
+          "module": "undefined",
+          "exports": "undefined",
+          "__dirname": "undefined",
+          "__filename": "undefined"
+        }
+      }
+    },
+    {
+      "id": "functions-web-globals-are-present",
+      "description": "The web platform globals exist in a function.",
+      "tags": [
+        "functions"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0001-4000-8000-000000000001",
+        "type": "function",
+        "body": "return new Response(JSON.stringify({ fetch: typeof fetch, Request: typeof Request, Response: typeof Response, Headers: typeof Headers, URL: typeof URL, URLSearchParams: typeof URLSearchParams, TextEncoder: typeof TextEncoder, TextDecoder: typeof TextDecoder, TransformStream: typeof TransformStream, atob: typeof atob, btoa: typeof btoa, crypto: typeof crypto, setTimeout: typeof setTimeout }), { headers: { 'content-type': 'application/json' } });",
+        "request": {
+          "method": "GET",
+          "url": "https://www.example.com/api"
+        }
+      },
+      "expect": {
+        "status": 200,
+        "bodyJson": {
+          "fetch": "function",
+          "Request": "function",
+          "Response": "function",
+          "Headers": "function",
+          "URL": "function",
+          "URLSearchParams": "function",
+          "TextEncoder": "function",
+          "TextDecoder": "function",
+          "TransformStream": "function",
+          "atob": "function",
+          "btoa": "function",
+          "crypto": "object",
+          "setTimeout": "function"
+        }
+      }
+    },
+    {
+      "id": "functions-btoa",
+      "description": "btoa encodes a string as base64, as the basic auth example uses it.",
+      "tags": [
+        "functions"
+      ],
+      "op": "runFunction",
+      "input": {
+        "uuid": "b2c3d4e5-0001-4000-8000-000000000001",
+        "type": "function",
+        "body": "return new Response(btoa('user:pass'));",
+        "request": {
+          "method": "GET",
+          "url": "https://www.example.com/api"
+        }
+      },
+      "expect": {
+        "status": 200,
+        "bodyText": "dXNlcjpwYXNz"
+      }
+    }
+  ]
+}