Skip to content

httpland/reporting-middleware

Repository files navigation

reporting-middleware

deno land deno doc GitHub release (latest by date) codecov GitHub

test NPM

HTTP reporting middleware.

Compliant with Reporting API v1 and Reporting API v0.

Middleware

For a definition of Universal HTTP middleware, see the http-middleware project.

reportingEndpoints

Middleware adds the Reporting-Endpoints header to the response.

import {
  type Handler,
  reportingEndpoints,
} from "https://deno.land/x/reporting_middleware@$VERSION/mod.ts";
import { assert } from "https://deno.land/std/testing/asserts.ts";

declare const request: Request;
declare const handler: Handler;

const middleware = reportingEndpoints({
  default: "https://test.test/report",
});
const response = await middleware(request, handler);

assert(response.headers.has("reporting-endpoints"));

yield:

Reporting-Endpoints: default="https://test.test/report"

Endpoints

Specifying endpoints is mandatory.

Endpoints must be specified as pairs consisting of key and value.

The key is the endpoint-name and the value is the endpoint-url.

The following formats are supported:

  • Record
  • Entries

The result of serialization is the same for both formats.

Record

Supports record format.

import {
  reportingEndpoints,
} from "https://deno.land/x/reporting_middleware@$VERSION/middleware.ts";

const middleware = reportingEndpoints({
  default: "https://test.test/report",
  csp: "https://test.test/csp",
});

Serialized as an ordered map.

Note that the order of the properties is reflected as is.

Entries

Supports entires format (an array of entry).

import {
  reportingEndpoints,
} from "https://deno.land/x/reporting_middleware@$VERSION/middleware.ts";

const middleware = reportingEndpoints([
  ["default", "https://test.test/report"],
  ["csp", "https://test.test/csp"],
]);

Serialization error

If serialization fails, an error may be thrown.

Cases that throw an error are as follows:

import { reportingEndpoints } from "https://deno.land/x/reporting_middleware@$VERSION/middleware.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

assertThrows(() =>
  reportingEndpoints({ "<member-key>": "<invalid:URI-reference>" })
);
assertThrows(() =>
  reportingEndpoints({ "<invalid:member-key>": "<URI-reference>" })
);

Conditions

Middleware will execute if all of the following conditions are met:

  • Reporting-Endpoints header does not exist in response

Effects

Middleware may make changes to the following elements of the HTTP message.

  • HTTP Headers
    • Reporting-Endpoints

reportTo

Middleware adds the Report-To header to the response.

import {
  type Handler,
  reportTo,
} from "https://deno.land/x/reporting_middleware@$VERSION/mod.ts";
import { assert } from "https://deno.land/std/testing/asserts.ts";

declare const request: Request;
declare const handler: Handler;

const middleware = reportTo([
  {
    endpoints: [{ url: "https://test.test/report" }],
    max_age: 86400,
  },
]);
const response = await middleware(request, handler);

assert(response.headers.has("report-to"));

yield:

Report-To: {"endpoints",[{"url":"https://test.test/report"}],"max_age":86400}

Endpoint group

The middleware factory requires an array of endpoint group.

Endpoint group is a structure with the following fields:

Name Type Required Description
endpoints Endpoint[] Endpoint list.
max_age number Endpoint group’s lifetime
group string - Endpoint group name.
include_subdomains boolean - Whether to enable this endpoint group for all subdomains of the current origin host.

Endpoint

Endpoint is following structure:

Name Type Required Description
url string The location of the endpoint.
priority number - Number that defines which failover class the endpoint belongs to.
weight number - Number that defines load balancing for the failover class that the endpoint belongs to.

Serialization error

The endpoint group array is serialized.

If serialization fails, an error may be thrown.

Cases that throw an error are as follows:

  • Numeric field is not a non-negative integer
import { reportTo } from "https://deno.land/x/reporting_middleware@$VERSION/middleware.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

assertThrows(() => reportTo([{ max_age: NaN, endpoints: [] }]));
assertThrows(() =>
  reportTo([{
    max_age: 0,
    endpoints: [{ url: "https://test.test/report", priority: 1.2 }],
  }])
);

Conditions

Middleware will execute if all of the following conditions are met:

  • Report-To header does not exist in response

Effects

Middleware may make changes to the following elements of the HTTP message.

  • HTTP Headers
    • Report-To

API

All APIs can be found in the deno doc.

License

Copyright © 2023-present httpland.

Released under the MIT license