@statewalker/httpeers-share 0.0.0-stage → 0.1.0

package/src/probe.ts

@@ -0,0 +1,86 @@
+/**
+ * "Test again": one request through the same Upstream Guests use.
+ */
+
+import type { Upstream } from "@statewalker/webrun-http-proxy";
+import {
+  BRIDGE_COOKIES_KEPT_HEADER,
+  BRIDGE_GUEST_HEADER,
+  BRIDGE_SET_COOKIE_HEADER,
+  PROBE_GUEST,
+  unreachable,
+} from "./upstreams.js";
+
+export type Health = "ok" | "slow" | "down";
+export type ProbeCause = "service-down" | "bridge-down" | "cors-missing";
+export type ProbeWarning = "ws-needed" | "cookies-set";
+
+export interface ProbeReport {
+  health: Health;
+  cause?: ProbeCause;
+  warnings: ProbeWarning[];
+  ms: number;
+}
+
+/** What Guests notice: a page that takes longer than this feels broken. */
+export const SLOW_MS = 1500;
+
+export async function probe(
+  upstream: Upstream,
+  opts: { slowMs?: number; direct?: string } = {},
+): Promise<ProbeReport> {
+  const started = performance.now();
+  // As a Guest of its own: a Bridge with cookie jars treats the Probe like anyone else.
+  const response = await upstream(
+    new Request("http://probe.peershare/", { headers: { [BRIDGE_GUEST_HEADER]: PROBE_GUEST } }),
+  );
+  const body = await response.text();
+  const ms = Math.round(performance.now() - started);
+
+  const down = unreachable(response);
+  if (down === "service" && opts.direct != null && (await answersWithoutCors(opts.direct))) {
+    return { health: "down", cause: "cors-missing", warnings: [], ms };
+  }
+  if (down != null) return { health: "down", cause: `${down}-down`, warnings: [], ms };
+  // A 404 at `/` is an app that answers; a 5xx is one that does not work.
+  if (response.status >= 500) return { health: "down", cause: "service-down", warnings: [], ms };
+
+  const health = ms >= (opts.slowMs ?? SLOW_MS) ? "slow" : "ok";
+  const warnings: ProbeWarning[] = [];
+  if (isHtml(response) && WEBSOCKET_CLIENTS.some((re) => re.test(body))) warnings.push("ws-needed");
+  // Only the Bridge's marker: a page never sees `Set-Cookie` itself.
+  // A cookie login breaks for Guests only when nothing keeps the cookies for them.
+  const kept = response.headers.get(BRIDGE_COOKIES_KEPT_HEADER) === "kept";
+  if (response.headers.has(BRIDGE_SET_COOKIE_HEADER) && !kept) warnings.push("cookies-set");
+  return { health, warnings, ms };
+}
+
+/**
+ * Pages whose scripts open a WebSocket: dev servers' hot-reload clients, and
+ * pages that do it themselves. Guests' traffic is HTTP only, so these break.
+ * Matched in script tags and code, not in prose.
+ */
+const WEBSOCKET_CLIENTS = [
+  /<script[^>]+src="[^"]*\/@vite\/client"/,
+  /<script[^>]+src="[^"]*webpack-dev-server/,
+  /<script[^>]+src="[^"]*\/_next\/webpack-hmr/,
+  /new\s+WebSocket\s*\(/,
+];
+
+function isHtml(response: Response): boolean {
+  return (response.headers.get("content-type") ?? "").includes("text/html");
+}
+
+/**
+ * In a browser a missing CORS header fails exactly like a dead server. A
+ * `no-cors` request is not subject to CORS: an (opaque) answer means the
+ * site is up, so what is missing is its permission for other origins.
+ */
+async function answersWithoutCors(target: string): Promise<boolean> {
+  try {
+    await fetch(target, { mode: "no-cors" });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/service-table.ts

@@ -0,0 +1,91 @@
+/**
+ * The Sharer's Services as Guests see them: a live catalog at `/s/`, and
+ * each Service at `/s/<id>/…`.
+ *
+ * The hub's own advertisements are posted once, when it is created (there is
+ * no way to update them), so they cannot carry a Service that was added or
+ * paused later. One static advertisement says "Dirk shares services"; what
+ * they are, and which are paused, is read here, per request.
+ */
+
+import type { FetchHandler, Upstream } from "@statewalker/webrun-http-proxy";
+import { shareRouter } from "./share-router.js";
+import { SOCKET_HEADER } from "./socket-frames.js";
+import { sharerSocket } from "./socket-tunnel.js";
+
+export interface ServiceEntry {
+  id: string;
+  name: string;
+  upstream: Upstream;
+  /** The Service's WebSocket at `path` (M9); without it, sockets are refused. */
+  socket?: (path: string, protocols: string[]) => WebSocket;
+  enabled: boolean;
+  isDefault: boolean;
+}
+
+export interface CatalogEntry {
+  id: string;
+  name: string;
+  isDefault: boolean;
+  paused: boolean;
+}
+
+/** Marks the table's own answers (paused, unknown), so they are never taken for a Service's. */
+export const SERVICE_MARKER = "x-peershare-service";
+
+export function serviceTable(
+  services: () => readonly ServiceEntry[],
+  /** `sharerName` may be a function: read per request, so a name set later shows. */
+  opts: { sharerName?: string | (() => string) } = {},
+): FetchHandler {
+  const nameOf =
+    typeof opts.sharerName === "function"
+      ? opts.sharerName
+      : () => opts.sharerName as string | undefined;
+  const router = shareRouter({ services: () => services().filter((s) => s.enabled) });
+
+  return async (request) => {
+    const sharer = nameOf() || "The Sharer";
+    const { pathname } = new URL(request.url);
+    if (pathname === "/s/" || pathname === "/s") {
+      const catalog: CatalogEntry[] = [...services()]
+        .sort((a, b) => Number(b.isDefault) - Number(a.isDefault))
+        .map((s) => ({ id: s.id, name: s.name, isDefault: s.isDefault, paused: !s.enabled }));
+      return Response.json(catalog);
+    }
+    const id = pathname.split("/")[2] ?? "";
+    const service = services().find((s) => s.id === id);
+    if (service == null) return own(404, "unknown", `There is no service "${id}" here.`);
+    if (!service.enabled) {
+      return own(
+        503,
+        "paused",
+        `${sharer} paused ${service.name}. It is back when ${sharer} turns it on again.`,
+      );
+    }
+    const protocols = request.headers.get(SOCKET_HEADER);
+    if (protocols != null) {
+      if (service.socket == null)
+        return own(501, "no-socket", `${service.name} cannot carry live connections.`);
+      const url = new URL(request.url);
+      const rest = url.pathname.slice(`/s/${id}`.length) || "/";
+      const open = service.socket;
+      return sharerSocket(request, () =>
+        open(`${rest}${url.search}`, protocols.split(",").filter(Boolean)),
+      );
+    }
+    return router(request);
+  };
+}
+
+function own(status: number, marker: string, message: string): Response {
+  const body = `<!doctype html><meta charset="utf-8"><title>${escapeHtml(message)}</title><p>${escapeHtml(message)}</p>`;
+  return new Response(body, {
+    status,
+    headers: { "content-type": "text/html; charset=utf-8", [SERVICE_MARKER]: marker },
+  });
+}
+
+function escapeHtml(text: string): string {
+  return text.replace(/[&<>"]/g, (c) => `&#${c.charCodeAt(0)};`);
+}

package/src/share-router.ts

@@ -0,0 +1,43 @@
+/**
+ * What the Sharer's member mounts for Guests: `/s/<serviceId>/<path>`.
+ *
+ * The router knows nothing about upstream kinds: it strips the mount, hands
+ * the rest of the path to the Service's `Upstream`, and that is all.
+ */
+
+import { bodyOf } from "@statewalker/httpeers-core";
+import type { FetchHandler, Upstream } from "@statewalker/webrun-http-proxy";
+import { Hono } from "hono";
+
+export interface SharedService {
+  id: string;
+  upstream: Upstream;
+}
+
+export function shareRouter(init: { services: () => readonly SharedService[] }): FetchHandler {
+  const app = new Hono();
+
+  app.all("/s/:id/*", async (c) => {
+    const id = c.req.param("id");
+    // Read per request, so adding or pausing a Service needs no rebuild.
+    const service = init.services().find((s) => s.id === id);
+    if (service == null) return c.notFound();
+
+    const url = new URL(c.req.url);
+    const rest = url.pathname.slice(`/s/${id}`.length) || "/";
+    // Through `bodyOf`, not `request.body`: Firefox has no `Request.body`,
+    // and a rewritten request silently lost its body there.
+    const body = await bodyOf(c.req.raw);
+    return service.upstream(
+      new Request(new URL(`${rest}${url.search}`, url.origin), {
+        method: c.req.method,
+        headers: c.req.raw.headers,
+        body,
+        ...(body instanceof ReadableStream ? { duplex: "half" as const } : {}),
+        signal: c.req.raw.signal,
+      }),
+    );
+  });
+
+  return async (request) => app.fetch(request);
+}

package/src/socket-frames.ts

@@ -0,0 +1,83 @@
+/**
+ * WebSocket messages inside one streaming HTTP request over the mesh (rung 15:
+ * a mesh request is full-duplex). Each frame: 1 byte type, 4 bytes length
+ * (big-endian), payload.
+ *
+ *   text   (1): UTF-8
+ *   binary (2): bytes
+ *   close  (3): 2 bytes code, then the reason in UTF-8
+ *   open   (4): the subprotocol the app accepted, in UTF-8 (first frame back)
+ */
+
+export type SocketFrame =
+  | { type: "text"; data: string }
+  | { type: "binary"; data: Uint8Array }
+  | { type: "close"; code: number; reason: string }
+  | { type: "open"; protocol: string };
+
+/** Asks a Service's upstream for a socket instead of a response: the header names the subprotocols. */
+export const SOCKET_HEADER = "x-peershare-websocket";
+
+const TEXT = 1;
+const BINARY = 2;
+const CLOSE = 3;
+const OPEN = 4;
+const HEAD = 5;
+
+export function encodeFrame(frame: SocketFrame): Uint8Array {
+  const enc = new TextEncoder();
+  let type: number;
+  let payload: Uint8Array;
+  if (frame.type === "text") {
+    type = TEXT;
+    payload = enc.encode(frame.data);
+  } else if (frame.type === "binary") {
+    type = BINARY;
+    payload = frame.data;
+  } else if (frame.type === "open") {
+    type = OPEN;
+    payload = enc.encode(frame.protocol);
+  } else {
+    type = CLOSE;
+    const reason = enc.encode(frame.reason);
+    payload = new Uint8Array(2 + reason.length);
+    new DataView(payload.buffer).setUint16(0, frame.code);
+    payload.set(reason, 2);
+  }
+  const out = new Uint8Array(HEAD + payload.length);
+  const view = new DataView(out.buffer);
+  view.setUint8(0, type);
+  view.setUint32(1, payload.length);
+  out.set(payload, HEAD);
+  return out;
+}
+
+/** Bytes, chunked any way, to frames. */
+export function decodeFrames(): TransformStream<Uint8Array, SocketFrame> {
+  let buffer = new Uint8Array(0);
+  const dec = new TextDecoder();
+  return new TransformStream({
+    transform(chunk, controller) {
+      const joined = new Uint8Array(buffer.length + chunk.length);
+      joined.set(buffer);
+      joined.set(chunk, buffer.length);
+      buffer = joined;
+      while (buffer.length >= HEAD) {
+        const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+        const length = view.getUint32(1);
+        if (buffer.length < HEAD + length) break;
+        const type = view.getUint8(0);
+        const payload = buffer.slice(HEAD, HEAD + length);
+        buffer = buffer.slice(HEAD + length);
+        if (type === TEXT) controller.enqueue({ type: "text", data: dec.decode(payload) });
+        else if (type === BINARY) controller.enqueue({ type: "binary", data: payload });
+        else if (type === CLOSE) {
+          const code = new DataView(payload.buffer, payload.byteOffset).getUint16(0);
+          controller.enqueue({ type: "close", code, reason: dec.decode(payload.slice(2)) });
+        } else if (type === OPEN)
+          controller.enqueue({ type: "open", protocol: dec.decode(payload) });
+        else controller.error(new Error(`unknown socket frame type ${type}`));
+      }
+    },
+  });
+}

package/src/socket-tunnel.ts

@@ -0,0 +1,167 @@
+/**
+ * A WebSocket inside one request over the mesh (M9; rung 15 measured that a
+ * mesh request is full-duplex). The Guest's `openTunnel` sends frames in the
+ * request body and reads them from the response body; the Sharer's
+ * `sharerSocket` relays them to the Service's own socket.
+ */
+
+import type { FetchHandler } from "@statewalker/webrun-http-proxy";
+import { decodeFrames, encodeFrame, SOCKET_HEADER, type SocketFrame } from "./socket-frames.js";
+
+/** The Sharer's side: answer a tunnel request by relaying to `open()`'s socket. */
+export function sharerSocket(request: Request, open: () => WebSocket): Response {
+  const ws = open();
+  ws.binaryType = "arraybuffer";
+  const held: Array<string | ArrayBuffer> = [];
+  let out!: ReadableStreamDefaultController<Uint8Array>;
+  let done = false;
+  const emit = (frame: SocketFrame) => {
+    if (!done) out.enqueue(encodeFrame(frame));
+  };
+  const end = (code: number, reason: string) => {
+    emit({ type: "close", code, reason });
+    if (!done) {
+      done = true;
+      out.close();
+    }
+  };
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      out = controller;
+      ws.onopen = () => {
+        emit({ type: "open", protocol: ws.protocol });
+        for (const data of held.splice(0)) ws.send(data);
+      };
+      ws.onmessage = (e) =>
+        emit(
+          typeof e.data === "string"
+            ? { type: "text", data: e.data }
+            : { type: "binary", data: new Uint8Array(e.data as ArrayBuffer) },
+        );
+      ws.onclose = (e) => end(e.code, e.reason);
+      ws.onerror = () => end(1011, "the Service's socket failed");
+    },
+    cancel() {
+      done = true;
+      ws.close();
+    },
+  });
+
+  // The Guest's frames, as they arrive: the request is still open.
+  void (async () => {
+    if (request.body == null) return;
+    for await (const frame of request.body.pipeThrough(decodeFrames())) {
+      if (frame.type === "close") {
+        ws.close(frame.code === 1000 || frame.code >= 3000 ? frame.code : 1000, frame.reason);
+      } else if (frame.type === "text" || frame.type === "binary") {
+        const data = frame.type === "text" ? frame.data : frame.data.slice().buffer;
+        if (ws.readyState === WebSocket.OPEN) ws.send(data);
+        else held.push(data);
+      }
+    }
+    // A client may close only with 1000 or 3000–4999 (1011 throws `InvalidAccessError`).
+  })().catch(() => ws.close(1000, "the Guest's stream ended abnormally"));
+
+  return new Response(body, { headers: { "content-type": "application/octet-stream" } });
+}
+
+type Listener<E> = ((event: E) => void) | null;
+
+/** What a Guest holds: shaped like a browser WebSocket, carried over `fetch`. */
+export class TunnelSocket {
+  static readonly CONNECTING = 0;
+  static readonly OPEN = 1;
+  static readonly CLOSING = 2;
+  static readonly CLOSED = 3;
+
+  readyState = TunnelSocket.CONNECTING;
+  protocol = "";
+  onopen: Listener<{ type: "open" }> = null;
+  onmessage: Listener<{ type: "message"; data: string | ArrayBuffer }> = null;
+  onclose: Listener<{ type: "close"; code: number; reason: string; wasClean: boolean }> = null;
+  onerror: Listener<{ type: "error" }> = null;
+
+  private out!: ReadableStreamDefaultController<Uint8Array>;
+  private sentClose = false;
+
+  constructor(fetch: FetchHandler, path: string, protocols: string[]) {
+    const body = new ReadableStream<Uint8Array>({
+      start: (controller) => {
+        this.out = controller;
+      },
+    });
+    // `path` may be a full URL (`http://local/peers/<sharer>/s/<id>/live`), so
+    // the caller's `fetch` gets the Request as built, streaming body and all.
+    void fetch(
+      new Request(/^https?:/.test(path) ? path : `http://tunnel${path}`, {
+        method: "POST",
+        headers: { [SOCKET_HEADER]: protocols.join(",") },
+        body,
+        duplex: "half",
+      } as RequestInit),
+    )
+      .then((res) => this.read(res))
+      .catch(() => this.closed(1006, "the tunnel failed"));
+  }
+
+  send(data: string | ArrayBuffer | ArrayBufferView): void {
+    if (this.readyState !== TunnelSocket.OPEN) throw new Error("the socket is not open");
+    const frame: SocketFrame =
+      typeof data === "string"
+        ? { type: "text", data }
+        : {
+            type: "binary",
+            data:
+              data instanceof ArrayBuffer
+                ? new Uint8Array(data)
+                : new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
+          };
+    this.out.enqueue(encodeFrame(frame));
+  }
+
+  close(code = 1000, reason = ""): void {
+    if (this.readyState >= TunnelSocket.CLOSING) return;
+    this.readyState = TunnelSocket.CLOSING;
+    this.endRequest(code, reason);
+  }
+
+  private endRequest(code: number, reason: string): void {
+    if (this.sentClose) return;
+    this.sentClose = true;
+    try {
+      this.out.enqueue(encodeFrame({ type: "close", code, reason }));
+      this.out.close();
+    } catch {
+      /* already closed */
+    }
+  }
+
+  private async read(res: Response): Promise<void> {
+    if (!res.ok || res.body == null) {
+      this.onerror?.({ type: "error" });
+      return this.closed(1011, `refused: ${res.status}`);
+    }
+    for await (const frame of res.body.pipeThrough(decodeFrames())) {
+      if (frame.type === "open") {
+        this.protocol = frame.protocol;
+        this.readyState = TunnelSocket.OPEN;
+        this.onopen?.({ type: "open" });
+      } else if (frame.type === "text") this.onmessage?.({ type: "message", data: frame.data });
+      else if (frame.type === "binary")
+        this.onmessage?.({ type: "message", data: frame.data.slice().buffer });
+      else return this.closed(frame.code, frame.reason);
+    }
+    this.closed(1006, "the tunnel ended");
+  }
+
+  private closed(code: number, reason: string): void {
+    if (this.readyState === TunnelSocket.CLOSED) return;
+    this.readyState = TunnelSocket.CLOSED;
+    this.endRequest(1000, "");
+    this.onclose?.({ type: "close", code, reason, wasClean: code === 1000 });
+  }
+}
+
+export function openTunnel(fetch: FetchHandler, path: string, protocols: string[]): TunnelSocket {
+  return new TunnelSocket(fetch, path, protocols);
+}

package/src/stamp-guest.ts

@@ -0,0 +1,18 @@
+/**
+ * The Sharer's half of the cookie jars: name the Guest on every request to
+ * `/s`, from the peer id the mesh proved, never from what the Guest sent.
+ */
+
+import { ANONYMOUS, type FetchHandler, lookupPeer } from "@statewalker/httpeers-core";
+import { BRIDGE_GUEST_HEADER } from "./upstreams.js";
+
+export function stampGuest(handler: FetchHandler): FetchHandler {
+  return (request) => {
+    const peer = lookupPeer(request) ?? ANONYMOUS;
+    const headers = new Headers(request.headers);
+    // Overwritten, not merged: a Guest's own value would let it pick a jar.
+    headers.delete(BRIDGE_GUEST_HEADER);
+    if (peer !== ANONYMOUS) headers.set(BRIDGE_GUEST_HEADER, peer);
+    return handler(new Request(request, { headers }));
+  };
+}

package/src/targets.ts

@@ -0,0 +1,51 @@
+/**
+ * Where the Bridge may relay: the Sharer's own machine, LAN and tailnet,
+ * nothing else.
+ *
+ * Literal addresses are checked as they are. A DNS name is decided by whoever
+ * controls its zone at request time (DNS rebinding), so names are refused,
+ * with two exceptions: `localhost`, and mDNS `.local` names, which are
+ * resolved FIRST and allowed only if every address they resolve to is
+ * private. (Some company networks serve `.local` from ordinary DNS, so the
+ * name alone proves nothing.)
+ */
+
+export type TargetVerdict = "allowed" | "forbidden" | { resolve: string };
+
+export function checkTarget(target: string): TargetVerdict {
+  let url: URL;
+  try {
+    url = new URL(target);
+  } catch {
+    return "forbidden";
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return "forbidden";
+
+  const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  if (host === "localhost") return "allowed";
+  if (isAddress(host)) return isPrivateAddress(host) ? "allowed" : "forbidden";
+  if (/^[a-z0-9-]+(\.[a-z0-9-]+)*\.local$/.test(host)) return { resolve: host };
+  return "forbidden";
+}
+
+function isAddress(host: string): boolean {
+  return /^\d+\.\d+\.\d+\.\d+$/.test(host) || host.includes(":");
+}
+
+/** Loopback, RFC 1918, carrier-grade NAT (Tailscale), IPv6 loopback and unique-local. */
+export function isPrivateAddress(address: string): boolean {
+  const v4 = address.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+  if (v4 != null) {
+    const [a, b] = [Number(v4[1]), Number(v4[2])];
+    return (
+      a === 127 ||
+      a === 10 ||
+      (a === 172 && b >= 16 && b <= 31) ||
+      (a === 192 && b === 168) ||
+      (a === 100 && b >= 64 && b <= 127)
+    );
+  }
+  // Link-local (fe80::/10) and IPv4-mapped addresses are refused.
+  const v6 = address.toLowerCase();
+  return v6 === "::1" || /^f[cd][0-9a-f]{0,2}:/.test(v6);
+}