@terpjs/react-core 0.1.0

package/src/realtime.ts

@@ -0,0 +1,307 @@
+import { useEffect, useRef, useState } from "react";
+
+import { useTerpBaseUrl, useTerpClient } from "./TerpProvider";
+
+export type RealtimeTransport = "sse" | "websocket";
+export type RealtimeStatus = "connecting" | "open" | "closed" | "error";
+
+const INITIAL_RECONNECT_DELAY_MS = 1_000;
+const MAX_RECONNECT_DELAY_MS = 30_000;
+
+interface TicketResponse {
+  ticket: string;
+  expires_in: number;
+  channel: string;
+  transport: RealtimeTransport;
+}
+
+interface RealtimePaths {
+  "/api/v1/realtime/tickets": {
+    post: {
+      requestBody: {
+        content: {
+          "application/json": {
+            channel: string;
+            transport: RealtimeTransport;
+          };
+        };
+      };
+      responses: {
+        201: { content: { "application/json": TicketResponse } };
+      };
+    };
+  };
+}
+
+export interface RealtimeChannelOptions<Message> {
+  channel: string;
+  transport?: RealtimeTransport;
+  /** Runtime validation for the channel's Pydantic JSON wire payload. */
+  validate(value: unknown): value is Message;
+  /** Receive every validated message (lastMessage is also retained). */
+  onMessage?(message: Message): void;
+  /** Default true; false closes/does not open the transport. */
+  enabled?: boolean;
+}
+
+export interface RealtimeChannelState<Message> {
+  status: RealtimeStatus;
+  lastMessage: Message | null;
+  error: Error | null;
+  /** WebSocket only; throws unless the socket is open. */
+  send(message: unknown): void;
+  close(): void;
+}
+
+function httpBase(baseUrl: string): URL {
+  const browserBase =
+    typeof window === "undefined" ? "http://localhost/" : window.location.href;
+  return new URL(baseUrl || "/", browserBase);
+}
+
+function transportUrl(
+  baseUrl: string,
+  transport: RealtimeTransport,
+  channel: string,
+  ticket: string,
+): string {
+  const base = httpBase(baseUrl);
+  const kind = transport === "sse" ? "sse" : "ws";
+  const url = new URL(
+    `/api/v1/realtime/${kind}/${encodeURIComponent(channel)}`,
+    base,
+  );
+  if (transport === "websocket") {
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  }
+  url.searchParams.set("ticket", ticket);
+  return url.toString();
+}
+
+function parseMessage<Message>(
+  raw: string,
+  validate: (value: unknown) => value is Message,
+): Message {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error("Realtime channel received invalid JSON");
+  }
+  if (!validate(value)) {
+    throw new Error("Realtime channel received a payload outside its declared type");
+  }
+  return value;
+}
+
+/**
+ * Subscribe to one typed realtime channel through the sanctioned transport.
+ *
+ * The hook mints a 30-second, one-use ticket via the generated authenticated
+ * client, then opens EventSource or WebSocket internally. App modules never
+ * touch raw egress APIs, bearer tokens never enter URLs, and each inbound JSON
+ * payload passes the caller's runtime type guard before reaching state/code.
+ */
+export function useRealtimeChannel<Message>({
+  channel,
+  transport = "sse",
+  validate,
+  onMessage,
+  enabled = true,
+}: RealtimeChannelOptions<Message>): RealtimeChannelState<Message> {
+  const client = useTerpClient<RealtimePaths>();
+  const baseUrl = useTerpBaseUrl();
+  const socketRef = useRef<WebSocket | null>(null);
+  const eventSourceRef = useRef<EventSource | null>(null);
+  const validateRef = useRef(validate);
+  const onMessageRef = useRef(onMessage);
+  const closeRef = useRef<() => void>(() => {});
+  const terminalFailureRef = useRef<(cause: unknown) => void>(() => {});
+  validateRef.current = validate;
+  onMessageRef.current = onMessage;
+  const [status, setStatus] = useState<RealtimeStatus>(
+    enabled ? "connecting" : "closed",
+  );
+  const [lastMessage, setLastMessage] = useState<Message | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+
+  const receiveRef = useRef((raw: string) => {});
+  receiveRef.current = (raw: string) => {
+    try {
+      const message = parseMessage(raw, validateRef.current);
+      setLastMessage(message);
+      onMessageRef.current?.(message);
+    } catch (cause) {
+      terminalFailureRef.current(cause);
+    }
+  };
+
+  const failRef = useRef((cause: unknown) => {});
+  failRef.current = (cause: unknown) => {
+    setError(cause instanceof Error ? cause : new Error("Realtime connection failed"));
+    setStatus("error");
+  };
+
+  useEffect(() => {
+    let cancelled = false;
+    let stopped = false;
+    let source: EventSource | null = null;
+    let socket: WebSocket | null = null;
+    let retryTimer: ReturnType<typeof setTimeout> | null = null;
+    let retryAttempt = 0;
+
+    const active = () => !cancelled && !stopped;
+
+    const releaseTransport = (reason: string) => {
+      source?.close();
+      socket?.close(1000, reason);
+      if (eventSourceRef.current === source) eventSourceRef.current = null;
+      if (socketRef.current === socket) socketRef.current = null;
+      source = null;
+      socket = null;
+    };
+
+    const cancelRetry = () => {
+      if (retryTimer !== null) clearTimeout(retryTimer);
+      retryTimer = null;
+    };
+
+    const stop = () => {
+      stopped = true;
+      cancelRetry();
+      releaseTransport("closed by caller");
+      setStatus("closed");
+    };
+    closeRef.current = stop;
+
+    const terminalFailure = (cause: unknown) => {
+      if (!active()) return;
+      stopped = true;
+      cancelRetry();
+      releaseTransport("invalid message payload");
+      failRef.current(cause);
+    };
+    terminalFailureRef.current = terminalFailure;
+
+    if (!enabled) {
+      stopped = true;
+      setStatus("closed");
+      return () => {
+        cancelled = true;
+        if (closeRef.current === stop) closeRef.current = () => {};
+        if (terminalFailureRef.current === terminalFailure) {
+          terminalFailureRef.current = () => {};
+        }
+      };
+    }
+    setStatus("connecting");
+    setError(null);
+    setLastMessage(null);
+
+    const connect = async (): Promise<void> => {
+      if (!active()) return;
+      setStatus("connecting");
+      try {
+        const { data, error: apiError } = await client.POST(
+          "/api/v1/realtime/tickets",
+          { body: { channel, transport } },
+        );
+        if (!active()) return;
+        if (apiError || !data) {
+          throw new Error("Realtime ticket mint failed");
+        }
+        const url = transportUrl(baseUrl, transport, channel, data.ticket);
+        if (transport === "sse") {
+          source = new EventSource(url);
+          eventSourceRef.current = source;
+          const connectedSource = source;
+          source.onopen = () => {
+            if (!active() || source !== connectedSource) return;
+            retryAttempt = 0;
+            setError(null);
+            setStatus("open");
+          };
+          source.onmessage = (event) => {
+            if (!active() || source !== connectedSource) return;
+            receiveRef.current(event.data);
+          };
+          source.onerror = () => {
+            if (!active() || source !== connectedSource) return;
+            scheduleReconnect(new Error("Realtime SSE connection failed"));
+          };
+        } else {
+          socket = new WebSocket(url);
+          socketRef.current = socket;
+          const connectedSocket = socket;
+          socket.onopen = () => {
+            if (!active() || socket !== connectedSocket) return;
+            retryAttempt = 0;
+            setError(null);
+            setStatus("open");
+          };
+          socket.onmessage = (event) => {
+            if (!active() || socket !== connectedSocket) return;
+            receiveRef.current(String(event.data));
+          };
+          socket.onerror = () => {
+            if (!active() || socket !== connectedSocket) return;
+            scheduleReconnect(new Error("Realtime WebSocket connection failed"));
+          };
+          socket.onclose = (event) => {
+            if (!active() || socket !== connectedSocket) return;
+            scheduleReconnect(
+              new Error(`Realtime WebSocket connection closed (${event.code})`),
+            );
+          };
+        }
+      } catch (cause) {
+        if (active()) scheduleReconnect(cause);
+      }
+    };
+
+    const scheduleReconnect = (cause: unknown) => {
+      if (!active() || retryTimer !== null) return;
+      releaseTransport("reconnecting");
+      failRef.current(cause);
+      const delay = Math.min(
+        INITIAL_RECONNECT_DELAY_MS * 2 ** retryAttempt,
+        MAX_RECONNECT_DELAY_MS,
+      );
+      retryAttempt += 1;
+      retryTimer = setTimeout(() => {
+        retryTimer = null;
+        if (active()) void connect();
+      }, delay);
+    };
+
+    void connect();
+
+    return () => {
+      cancelled = true;
+      cancelRetry();
+      releaseTransport("component unmounted");
+      if (closeRef.current === stop) closeRef.current = () => {};
+      if (terminalFailureRef.current === terminalFailure) {
+        terminalFailureRef.current = () => {};
+      }
+    };
+  }, [baseUrl, channel, client, enabled, transport]);
+
+  return {
+    status,
+    lastMessage,
+    error,
+    send(message: unknown) {
+      const socket = socketRef.current;
+      if (transport !== "websocket" || socket?.readyState !== WebSocket.OPEN) {
+        throw new Error("Realtime WebSocket is not open");
+      }
+      socket.send(JSON.stringify(message));
+    },
+    close() {
+      closeRef.current();
+    },
+  };
+}
+
+export { parseMessage, transportUrl };

package/src/refresh-session.test.tsx

@@ -0,0 +1,114 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { RequireAuth } from "./RequireAuth";
+import { TerpProvider, useAuth, useTerpClient } from "./TerpProvider";
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function me(token: string) {
+  return json({ id: "1", email: `${token}@acme.test`, role_rank: 20, role_name: "editor" });
+}
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function CurrentEmail() {
+  const auth = useAuth();
+  return <p>{auth.currentUser()?.email ?? "signed out"}</p>;
+}
+
+function DoWork() {
+  const client = useTerpClient();
+  return (
+    <button type="button" onClick={() => void client.GET("/api/v1/me/", {})}>
+      Do work
+    </button>
+  );
+}
+
+describe("refresh-token sessions (ADR 0054)", () => {
+  it("silently restores the session on boot from the httpOnly refresh cookie", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn<typeof fetch>(async (input) => {
+        const request = input as Request;
+        if (request.url.endsWith("/api/v1/auth/refresh")) {
+          return json({ access_token: "restored", token_type: "bearer" });
+        }
+        if (request.url.endsWith("/api/v1/me/")) {
+          return me("restored");
+        }
+        return json({}, 404);
+      }),
+    );
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <RequireAuth fallback={<p>Please sign in</p>}>
+          <CurrentEmail />
+        </RequireAuth>
+      </TerpProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByText("restored@acme.test")).toBeInTheDocument());
+    expect(screen.queryByText("Please sign in")).not.toBeInTheDocument();
+  });
+
+  it("refreshes and retries an expired access token without logging out", async () => {
+    const fetchMock = vi.fn<typeof fetch>(async (input) => {
+      const request = input as Request;
+      if (request.url.endsWith("/api/v1/auth/refresh")) {
+        return json({ access_token: "fresh", token_type: "bearer" });
+      }
+      if (request.url.endsWith("/api/v1/auth/login")) {
+        return json({ access_token: "expired", token_type: "bearer" });
+      }
+      if (request.url.endsWith("/api/v1/me/")) {
+        const auth = request.headers.get("Authorization");
+        if (auth === "Bearer expired") return json({ detail: "expired" }, 401);
+        return me("fresh");
+      }
+      return json({}, 404);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    function LogIn() {
+      const auth = useAuth();
+      return (
+        <button
+          type="button"
+          onClick={() => void auth.login({ email: "e@acme.test", password: "pw" })}
+        >
+          Sign in
+        </button>
+      );
+    }
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogIn />
+        <RequireAuth fallback={<p>Please sign in</p>}>
+          <DoWork />
+        </RequireAuth>
+      </TerpProvider>,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Sign in" }));
+    await waitFor(() => expect(screen.getByRole("button", { name: "Do work" })).toBeInTheDocument());
+
+    fireEvent.click(screen.getByRole("button", { name: "Do work" }));
+
+    await waitFor(() => expect(screen.getByRole("button", { name: "Do work" })).toBeInTheDocument());
+    expect(screen.queryByText("Please sign in")).not.toBeInTheDocument();
+    expect(fetchMock.mock.calls.some(([input]) => (input as Request).headers.get("Authorization") === "Bearer fresh")).toBe(true);
+  });
+});

package/src/revocation.test.tsx

@@ -0,0 +1,81 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { useEffect } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { RequireAuth } from "./RequireAuth";
+import { TerpProvider, useAuth, useTerpClient } from "./TerpProvider";
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+/** Login + the first `/me` succeed; every later authenticated request 401s (a server-revoked session). */
+function revokingFetch() {
+  let meCalls = 0;
+  return vi.fn<typeof fetch>(async (input) => {
+    const url = (input as Request).url;
+    if (url.endsWith("/api/v1/auth/login")) {
+      return json({ access_token: "t", token_type: "bearer" });
+    }
+    if (url.endsWith("/api/v1/me/")) {
+      meCalls += 1;
+      if (meCalls === 1) {
+        return json({ id: "1", email: "e@acme.test", role_rank: 20, role_name: "editor" });
+      }
+    }
+    return json({ code: "authentication_required", detail: "token revoked" }, 401);
+  });
+}
+
+function LogInOnMount() {
+  const auth = useAuth();
+  useEffect(() => {
+    void auth.login({ email: "e@acme.test", password: "pw" });
+  }, []);
+  return null;
+}
+
+function DoWork() {
+  const client = useTerpClient();
+  return (
+    <button type="button" onClick={() => void client.GET("/api/v1/me/", {})}>
+      Do work
+    </button>
+  );
+}
+
+describe("session revocation (ADR 0031)", () => {
+  it("clears the session and falls back to login when an authenticated request 401s", async () => {
+    vi.stubGlobal("fetch", revokingFetch());
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RequireAuth fallback={<p>Please sign in</p>}>
+          <DoWork />
+        </RequireAuth>
+      </TerpProvider>,
+    );
+
+    // After login the authenticated app (its "Do work" action) is shown.
+    await waitFor(() =>
+      expect(screen.getByRole("button", { name: "Do work" })).toBeInTheDocument(),
+    );
+
+    // The token is revoked server-side: the next authenticated request 401s, which clears the
+    // session so the app falls back to the login screen — not a signed-in shell over empty data.
+    fireEvent.click(screen.getByRole("button", { name: "Do work" }));
+
+    await waitFor(() => expect(screen.getByText("Please sign in")).toBeInTheDocument());
+    expect(screen.queryByRole("button", { name: "Do work" })).not.toBeInTheDocument();
+  });
+});