@dwk/host-meta 0.1.0-beta.0

package/src/handler.ts

@@ -0,0 +1,159 @@
+/**
+ * The host-meta fetch handler (RFC 6415): a stateless `GET` endpoint, mountable
+ * at both `/.well-known/host-meta` and `/.well-known/host-meta.json`, that
+ * serves one request-invariant document in either the XRD (`application/xrd+xml`,
+ * the default) or JRD (`application/jrd+json`) representation depending on
+ * content negotiation. Discovery data is public, so every response carries
+ * permissive CORS (mirroring RFC 7033 §10.2).
+ */
+
+import { type LogFields } from "@dwk/log";
+
+import {
+  resolveConfig,
+  type ResolvedConfig,
+  type HostMetaConfig,
+} from "./config";
+import { HostMetaLogEvent } from "./log";
+import { negotiateFormat, type Format } from "./negotiation";
+
+/**
+ * Cloudflare bindings required by the host-meta handler: **none**. The document
+ * is config-supplied (composition contract), so this fragment is empty and
+ * contributes nothing to the composed Worker's `Env`.
+ */
+export type HostMetaEnv = Record<never, never>;
+
+/** A `fetch`-compatible Worker handler. */
+export type HostMetaHandler = (
+  request: Request,
+  env: HostMetaEnv,
+  ctx: ExecutionContext,
+) => Promise<Response>;
+
+/** Media type for an XRD document (RFC 6415 §2). */
+const XRD_CONTENT_TYPE = "application/xrd+xml; charset=utf-8";
+/** Media type for a JSON Resource Descriptor (RFC 7033 §10.2). */
+const JRD_CONTENT_TYPE = "application/jrd+json; charset=utf-8";
+const TEXT_CONTENT_TYPE = "text/plain; charset=utf-8";
+
+/**
+ * host-meta serves public discovery data to any origin, so every response —
+ * success or error — advertises permissive CORS, mirroring the WebFinger policy
+ * (RFC 7033 §10.2) it links to.
+ */
+const CORS_HEADERS: Readonly<Record<string, string>> = {
+  "access-control-allow-origin": "*",
+};
+
+/**
+ * Emit a structured event on both the logger and the metrics seam, which share
+ * one event vocabulary (see `@dwk/log`): `warn` for rejections, `info` for a
+ * served document.
+ */
+function emit(
+  config: ResolvedConfig,
+  level: "info" | "warn",
+  event: string,
+  fields?: LogFields,
+): void {
+  config.logger[level](event, fields);
+  config.metrics.count(event, fields);
+}
+
+function documentResponse(
+  body: string,
+  contentLength: string,
+  format: Format,
+  method: string,
+): Response {
+  return new Response(method === "HEAD" ? null : body, {
+    status: 200,
+    headers: {
+      "content-type": format === "jrd" ? JRD_CONTENT_TYPE : XRD_CONTENT_TYPE,
+      // RFC 9110 §9.3.2: a HEAD response carries the same Content-Length the
+      // corresponding GET would, so it is set explicitly (the body is dropped
+      // for HEAD, which would otherwise omit the header).
+      "content-length": contentLength,
+      // The representation varies on the negotiated content type; advertise it
+      // so shared caches key XRD and JRD responses separately.
+      vary: "Accept",
+      ...CORS_HEADERS,
+    },
+  });
+}
+
+function errorResponse(
+  status: number,
+  message: string,
+  extraHeaders?: Readonly<Record<string, string>>,
+): Response {
+  return new Response(message, {
+    status,
+    headers: {
+      "content-type": TEXT_CONTENT_TYPE,
+      ...CORS_HEADERS,
+      ...extraHeaders,
+    },
+  });
+}
+
+/**
+ * Build the host-meta handler from configuration.
+ *
+ * The returned handler is mountable at `/.well-known/host-meta` and
+ * `/.well-known/host-meta.json`. It accepts `GET` (and `HEAD`) and returns
+ * `200` with the host-meta document: XRD by default, JRD when the client
+ * prefers it (`?format=json`, the `host-meta.json` path, or an Accept header
+ * favouring `application/jrd+json`). `OPTIONS` returns a CORS preflight; other
+ * methods get `405`. Fails loudly at construction if no link source is
+ * configured.
+ */
+export function createHostMeta(config: HostMetaConfig): HostMetaHandler {
+  const resolved = resolveConfig(config);
+
+  // Pre-serialized bodies and their byte lengths, computed once: nothing about
+  // the document varies per request, so a response is pure header assembly.
+  const byteLength = (body: string): string =>
+    String(new TextEncoder().encode(body).length);
+  const representations: Record<Format, { body: string; length: string }> = {
+    xrd: { body: resolved.xrdBody, length: byteLength(resolved.xrdBody) },
+    jrd: { body: resolved.jrdBody, length: byteLength(resolved.jrdBody) },
+  };
+
+  return async (request, _env, _ctx) => {
+    const method = request.method;
+
+    if (method === "OPTIONS") {
+      return new Response(null, {
+        status: 204,
+        headers: {
+          ...CORS_HEADERS,
+          "access-control-allow-methods": "GET, HEAD, OPTIONS",
+          "access-control-allow-headers": "*",
+        },
+      });
+    }
+
+    if (method !== "GET" && method !== "HEAD") {
+      emit(resolved, "warn", HostMetaLogEvent.Rejected, {
+        reason: "method_not_allowed",
+      });
+      return errorResponse(405, "method_not_allowed: use GET", {
+        allow: "GET, HEAD, OPTIONS",
+      });
+    }
+
+    const url = new URL(request.url);
+    const isJsonPath = url.pathname.endsWith(".json");
+    const format = negotiateFormat(
+      url,
+      request.headers.get("accept"),
+      isJsonPath,
+    );
+
+    const { body, length } = representations[format];
+    emit(resolved, "info", HostMetaLogEvent.Served, { format });
+    return documentResponse(body, length, format, method);
+  };
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * `@dwk/host-meta` — Web Host Metadata (RFC 6415) host-meta discovery endpoint.
+ *
+ * Endpoint package: exports a factory returning a `fetch`-compatible handler,
+ * mountable at `/.well-known/host-meta` and `/.well-known/host-meta.json` so it
+ * composes with other `@dwk` packages in one Worker. It serves one host-wide
+ * resource-discovery document — a set of top-level `Link`s, at minimum an
+ * `lrdd` template pointing at the site's WebFinger endpoint — in either the XRD
+ * (`application/xrd+xml`, the default) or JRD (`application/jrd+json`)
+ * representation, chosen by content negotiation (RFC 6415 §3, RFC 7033 §10.1).
+ *
+ * It exists because host-meta is **borderline static**: a single-identity site
+ * can emit fixed files, but only request logic can negotiate XRD ⇄ JRD from the
+ * one URL and template a dynamic `lrdd` link. The package is pure and stateless
+ * — the document is config-supplied (a WebFinger URL and/or static links),
+ * never read from the global environment — so it ships no Durable Object and
+ * needs no bindings, and the serializers unit-test under Node without a Workers
+ * runtime. The XRD serializer is the only surface new to this package; the JRD
+ * link shaping is reused from `@dwk/webfinger`.
+ *
+ * @see spec/packages/host-meta.md
+ * @packageDocumentation
+ */
+
+export { createHostMeta } from "./handler";
+export type { HostMetaEnv, HostMetaHandler } from "./handler";
+
+export {
+  resolveConfig,
+  type HostMetaConfig,
+  type ResolvedConfig,
+} from "./config";
+
+export {
+  buildDocument,
+  lrddTemplate,
+  type HostMetaDocument,
+  type Link,
+} from "./document";
+
+export { buildHostMetaJrd, serializeJrd, type HostMetaJrd } from "./jrd";
+
+export { serializeXrd, escapeXml, XRD_NAMESPACE } from "./xrd";
+
+export { negotiateFormat, type Format } from "./negotiation";
+
+export { HostMetaLogEvent } from "./log";
+export type { Logger, Metrics } from "@dwk/log";

package/src/jrd.ts

@@ -0,0 +1,51 @@
+/**
+ * JRD (JSON Resource Descriptor) rendering of a host-meta document
+ * (RFC 7033 §10.1, the `host-meta.json` variant of RFC 6415). The host-meta
+ * `Link` objects are already the WebFinger JRD link shape — reused verbatim
+ * from `@dwk/webfinger` — so rendering is just assembling the top-level members
+ * and dropping any the document did not supply, mirroring `@dwk/webfinger`'s
+ * `buildJrd`. The XRD serializer (`xrd.ts`) renders the *same* document model,
+ * keeping the two representations information-equivalent.
+ */
+
+import type { HostMetaDocument, Link } from "./document";
+
+/**
+ * A fully-rendered host-meta JRD. `links` is always present (possibly empty);
+ * `subject` and `properties` appear only when the document supplied them, so the
+ * JSON stays minimal.
+ */
+export interface HostMetaJrd {
+  /** The subject the metadata describes, when configured. */
+  readonly subject?: string;
+  /** Host-level properties, when configured. */
+  readonly properties?: Readonly<Record<string, string | null>>;
+  /** The top-level link set. */
+  readonly links: readonly Link[];
+}
+
+/**
+ * Shape a {@link HostMetaDocument} into its {@link HostMetaJrd} object: carry
+ * through `subject`/`properties` only when present, and emit the links as-is
+ * (they are already JRD-shaped). Exposed so callers can embed the JRD object
+ * rather than re-parse the serialized string.
+ */
+export function buildHostMetaJrd(document: HostMetaDocument): HostMetaJrd {
+  const jrd: {
+    subject?: string;
+    properties?: Readonly<Record<string, string | null>>;
+    links: readonly Link[];
+  } = { links: document.links };
+  if (document.subject !== undefined) {
+    jrd.subject = document.subject;
+  }
+  if (document.properties && Object.keys(document.properties).length > 0) {
+    jrd.properties = document.properties;
+  }
+  return jrd;
+}
+
+/** Serialize a host-meta document to a JRD (`application/jrd+json`) body. */
+export function serializeJrd(document: HostMetaDocument): string {
+  return JSON.stringify(buildHostMetaJrd(document));
+}

package/src/log.ts

@@ -0,0 +1,32 @@
+/**
+ * `@dwk/host-meta` — structured observability event taxonomy.
+ *
+ * host-meta is public, request-invariant discovery data, so the stakes are low
+ * — but which representation clients actually negotiate (XRD vs JRD) is useful
+ * signal, and a flood of rejected non-`GET` probes is worth a counter. Logging
+ * and metrics are opt-in via an injected {@link Logger}/{@link Metrics} (see
+ * `@dwk/log`) and **share this one vocabulary**: the same dotted event name is
+ * passed to the logger and the metrics sink so a log line and its counter line
+ * up. No request carries user data — the document is host-wide — so fields are
+ * limited to the chosen `format` and a machine-readable `reason`.
+ *
+ * @packageDocumentation
+ */
+
+/** Stable event names emitted by `@dwk/host-meta`. */
+export const HostMetaLogEvent = {
+  /**
+   * The host-meta document was served. Field: `format` (`"xrd"` or `"jrd"`),
+   * the negotiated representation.
+   */
+  Served: "host-meta.served",
+  /**
+   * A request was rejected before the document could be served. Field: `reason`
+   * (`method_not_allowed`).
+   */
+  Rejected: "host-meta.rejected",
+} as const;
+
+/** Union of the event-name string literals in {@link HostMetaLogEvent}. */
+export type HostMetaLogEvent =
+  (typeof HostMetaLogEvent)[keyof typeof HostMetaLogEvent];

package/src/negotiation.ts

@@ -0,0 +1,65 @@
+/**
+ * Representation selection for the one `/.well-known/host-meta` URL (RFC 6415
+ * §3). The document is served as XRD (`application/xrd+xml`) **by default** and
+ * as JRD (`application/jrd+json`) only when the client specifically prefers it,
+ * via — in priority order — an explicit `?format=` override, the
+ * `host-meta.json` path (RFC 7033 §10.1, always JRD), or a higher-q Accept
+ * preference for JRD over XRD.
+ */
+
+/** The chosen representation. */
+export type Format = "xrd" | "jrd";
+
+/**
+ * The best (highest) q-value among the given exact media types in an `Accept`
+ * header, or `0` if none of them appear. Wildcards (`* /*`) are deliberately
+ * ignored: they express no preference between XRD and JRD, so a bare `Accept:
+ * * /*` (or a missing header) must fall through to the XRD default.
+ */
+function acceptQuality(accept: string, mediaTypes: readonly string[]): number {
+  let best = 0;
+  for (const part of accept.split(",")) {
+    const segments = part.trim().split(";");
+    const type = segments[0]?.trim().toLowerCase();
+    if (type === undefined || !mediaTypes.includes(type)) continue;
+    let q = 1;
+    for (const segment of segments.slice(1)) {
+      const match = /^\s*q=(.*)$/i.exec(segment);
+      if (match && match[1] !== undefined) {
+        const parsed = Number.parseFloat(match[1]);
+        if (!Number.isNaN(parsed)) q = parsed;
+      }
+    }
+    if (q > best) best = q;
+  }
+  return best;
+}
+
+/**
+ * Decide which representation to serve.
+ *
+ * 1. `?format=json`/`jrd` → JRD; `?format=xml`/`xrd` → XRD (explicit override
+ *    wins over everything, per RFC 6415 §3's `?format=` mechanism).
+ * 2. A request to the `host-meta.json` path → JRD (RFC 7033 §10.1).
+ * 3. Otherwise compare Accept q-values: JRD only when it is *strictly*
+ *    preferred over XRD; XRD is the default for ties, wildcards, and no header.
+ */
+export function negotiateFormat(
+  url: URL,
+  accept: string | null,
+  isJsonPath: boolean,
+): Format {
+  const format = url.searchParams.get("format")?.toLowerCase();
+  if (format === "json" || format === "jrd") return "jrd";
+  if (format === "xml" || format === "xrd") return "xrd";
+
+  if (isJsonPath) return "jrd";
+
+  if (accept === null || accept.length === 0) return "xrd";
+  const jrdQuality = acceptQuality(accept, [
+    "application/jrd+json",
+    "application/json",
+  ]);
+  const xrdQuality = acceptQuality(accept, ["application/xrd+xml"]);
+  return jrdQuality > xrdQuality ? "jrd" : "xrd";
+}

package/src/xrd.ts

@@ -0,0 +1,114 @@
+/**
+ * XRD (Extensible Resource Descriptor) rendering of a host-meta document — the
+ * default `application/xrd+xml` representation of RFC 6415 §2. This is the only
+ * serializer new to `@dwk/host-meta`: the JRD side reuses `@dwk/webfinger`'s
+ * link shape. It renders the *same* {@link HostMetaDocument} the JRD serializer
+ * does, so the two stay information-equivalent (RFC 6415 §3).
+ *
+ * Output maps the model onto the XRD 1.0 schema: `Subject`, `Property`
+ * (`xsi:nil="true"` for an absent/`null` value), and `Link` elements with
+ * `rel`/`type`/`href`/`template` attributes and nested `Title`/`Property`
+ * children. All text and attribute values are XML-escaped.
+ */
+
+import type { HostMetaDocument, Link } from "./document";
+
+/** The XRD 1.0 default namespace (OASIS). */
+export const XRD_NAMESPACE = "http://docs.oasis-open.org/ns/xri/xrd-1.0";
+/** The XML Schema instance namespace, used for `xsi:nil` on absent properties. */
+const XSI_NAMESPACE = "http://www.w3.org/2001/XMLSchema-instance";
+
+/**
+ * Escape a string for inclusion in XML text or a double-quoted attribute value:
+ * the five predefined entities. Applied to every dynamic value so operator- or
+ * resource-supplied content can never break out of the document structure.
+ */
+export function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/** Whether any property (top-level or per-link) is `null`, requiring the `xsi` namespace. */
+function needsXsi(document: HostMetaDocument): boolean {
+  // Mirror linkXml's null-safety: a missing properties bag (`undefined` or a
+  // runtime `null` from untyped callers) carries no nil values to declare.
+  const hasNil = (
+    props?: Readonly<Record<string, string | null>> | null,
+  ): boolean =>
+    props !== undefined &&
+    props !== null &&
+    Object.values(props).some((v) => v === null);
+  if (hasNil(document.properties)) return true;
+  return document.links.some((link) => hasNil(link.properties));
+}
+
+/** Render a single `<Property>` element at the given indent. */
+function propertyXml(
+  type: string,
+  value: string | null,
+  indent: string,
+): string {
+  if (value === null) {
+    return `${indent}<Property type="${escapeXml(type)}" xsi:nil="true"/>`;
+  }
+  return `${indent}<Property type="${escapeXml(type)}">${escapeXml(value)}</Property>`;
+}
+
+/** Render a single `<Link>` element, expanding to a child block only when it has titles/properties. */
+function linkXml(link: Link): string[] {
+  const attrs = [`rel="${escapeXml(link.rel)}"`];
+  if (link.type !== undefined) attrs.push(`type="${escapeXml(link.type)}"`);
+  if (link.href !== undefined) attrs.push(`href="${escapeXml(link.href)}"`);
+  if (link.template !== undefined) {
+    attrs.push(`template="${escapeXml(link.template)}"`);
+  }
+  const open = `  <Link ${attrs.join(" ")}`;
+
+  const titles = link.titles ? Object.entries(link.titles) : [];
+  const properties = link.properties ? Object.entries(link.properties) : [];
+  if (titles.length === 0 && properties.length === 0) {
+    return [`${open}/>`];
+  }
+
+  const lines = [`${open}>`];
+  for (const [lang, title] of titles) {
+    // RFC 7033 §4.4.4.3 uses "und" for an undetermined language; XRD omits the
+    // attribute in that case rather than emitting `xml:lang="und"`.
+    const langAttr = lang === "und" ? "" : ` xml:lang="${escapeXml(lang)}"`;
+    lines.push(`    <Title${langAttr}>${escapeXml(title)}</Title>`);
+  }
+  for (const [type, value] of properties) {
+    lines.push(propertyXml(type, value, "    "));
+  }
+  lines.push("  </Link>");
+  return lines;
+}
+
+/** Serialize a host-meta document to an XRD (`application/xrd+xml`) body. */
+export function serializeXrd(document: HostMetaDocument): string {
+  const rootAttrs = needsXsi(document)
+    ? `xmlns="${XRD_NAMESPACE}" xmlns:xsi="${XSI_NAMESPACE}"`
+    : `xmlns="${XRD_NAMESPACE}"`;
+
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<XRD ${rootAttrs}>`,
+  ];
+  if (document.subject !== undefined) {
+    lines.push(`  <Subject>${escapeXml(document.subject)}</Subject>`);
+  }
+  if (document.properties) {
+    for (const [type, value] of Object.entries(document.properties)) {
+      lines.push(propertyXml(type, value, "  "));
+    }
+  }
+  for (const link of document.links) {
+    lines.push(...linkXml(link));
+  }
+  lines.push("</XRD>");
+  return lines.join("\n") + "\n";
+}