reporting-middleware

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:

• Key is invalid <member-key>
• Value is invalid <URI-reference>

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