@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/react/tests/client-time.test.ts

@@ -0,0 +1,40 @@
+/**
+ * `client.time()` of a test client under jsdom, where an app tests a component
+ * that stamps an ICRC-1 `created_at_time` (#949).
+ *
+ * Under jsdom the global `Uint8Array` is jsdom's, and `TextEncoder` hands out
+ * Node's. The `time` path of the `read_state` that `client.time()` sends was
+ * built with it, and the agent's CBOR encoder sent that label as a map, so the
+ * request the fake replica received was not the one the agent signed, and it
+ * refused a signed-in caller's signature. An anonymous one carries no
+ * signature, so it passes either way. Core's tests run in Node:
+ * `core/tests/time-realm.test.ts` covers the same case there.
+ */
+import { c } from "@meantjs/schema"
+import { createTestClient } from "@ic-reactor/core/testing"
+import { afterEach, expect, it } from "vitest"
+
+const LEDGER = "ryjl3-tyaaa-aaaaa-aaaba-cai"
+
+const FEE = c.service({ icrc1_fee: c.func([], [c.nat], "query") })
+type Fee = { icrc1_fee: () => Promise<bigint> }
+
+const tests: ReturnType<typeof createTestClient>[] = []
+afterEach(() => {
+  for (const test of tests.splice(0)) test.client.dispose()
+})
+
+it.each([false, true])(
+  "resolves the replica's time with signedIn: %s",
+  async (signedIn) => {
+    // The case this covers: TextEncoder's bytes are not the global Uint8Array's.
+    expect(new TextEncoder().encode("time")).not.toBeInstanceOf(Uint8Array)
+    const test = createTestClient({ signedIn })
+    tests.push(test)
+    test.mock<Fee>(FEE, LEDGER, { icrc1_fee: () => 1n })
+    const ledger = test.client.canister<Fee>(FEE, { id: LEDGER })
+
+    await expect(ledger.icrc1_fee()).resolves.toBe(1n)
+    await expect(test.client.time(ledger)).resolves.toEqual(expect.any(BigInt))
+  }
+)

package/packages/react/tests/entry.test.ts

@@ -0,0 +1,52 @@
+/**
+ * What the package entry is: exactly the three bindings, in a module that
+ * carries the `'use client'` directive. The export budget gate
+ * (`pnpm check:exports`) reads the built declarations; this reads what a
+ * bundler or Node would load.
+ */
+import { readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import ts from "typescript"
+import { describe, expect, it } from "vitest"
+import * as entry from "../src/index.js"
+
+const packageFile = (name: string) => resolve(import.meta.dirname, "..", name)
+
+describe("the package entry", () => {
+  it("exports exactly ReactorProvider, useClient and useAuth at runtime", () => {
+    // Pinned whole, as a list, so that a re-export of core, or a hook added
+    // without a decision, is a red test rather than a quiet extra name.
+    expect(Object.keys(entry).sort()).toEqual([
+      "ReactorProvider",
+      "useAuth",
+      "useClient",
+    ])
+    for (const name of Object.keys(entry)) {
+      expect(typeof (entry as Record<string, unknown>)[name]).toBe("function")
+    }
+  })
+
+  it("starts its emitted module with the 'use client' directive", () => {
+    // Compiled with the package's own tsconfig, which is what `pnpm build`
+    // compiles it with: a compiler or a configuration that dropped the
+    // directive would turn the entry into a server module, and a Next.js or
+    // other RSC build would then reject the hooks it imports.
+    const config = ts.readConfigFile(
+      packageFile("tsconfig.json"),
+      ts.sys.readFile
+    )
+    const { options } = ts.parseJsonConfigFileContent(
+      config.config,
+      ts.sys,
+      packageFile(".")
+    )
+    const source = packageFile("src/index.tsx")
+
+    const { outputText } = ts.transpileModule(readFileSync(source, "utf8"), {
+      compilerOptions: options,
+      fileName: source,
+    })
+
+    expect(outputText.trimStart()).toMatch(/^(["'])use client\1;?\r?\n/)
+  })
+})

package/packages/react/tests/helpers.tsx

@@ -0,0 +1,291 @@
+/**
+ * Fixtures for the binding tests: clients that never reach a network, a way
+ * to count the disposals of the clients a provider is given, and clients of a
+ * fake replica with one call to send through them.
+ */
+import { createClient, type AuthLike, type Client } from "@ic-reactor/core"
+import { createTestClient } from "@ic-reactor/core/testing"
+import { c } from "@meantjs/schema"
+import { createRequire } from "node:module"
+import { pathToFileURL } from "node:url"
+import { vi, type Mock } from "vitest"
+
+/** The controllable sign-in of a test client: `signIn`, `switchTo`, `expire` and the rest. */
+export type TestAuth = ReturnType<typeof createTestClient>["auth"]
+
+/**
+ * A sign-in a test controls, for the tests that build a client around it
+ * themselves (to count how often the client builds its auth, or to wrap it).
+ * It is the `auth` of a test client, the only place the testing entry hands
+ * one out; the fake replica next to it is never called, since no test here
+ * calls a canister. `identity` is a seed.
+ *
+ * The test client is disposed at once. A client builds its auth on first use
+ * and this one is never used, so it never took the auth over and disposing it
+ * leaves the auth alone: whichever client the test hands the auth to owns it
+ * from then on, as every client owns the auth it builds.
+ */
+export const testAuth = (
+  options?: Parameters<typeof createTestClient>[0]
+): TestAuth => {
+  const { client, auth } = createTestClient(options)
+  client.dispose()
+  return auth
+}
+
+/** A client on the IC whose caller is whatever `auth` says. Sends nothing. */
+export const clientWithAuth = (auth: () => AuthLike): Client =>
+  createClient({ network: "ic", auth })
+
+/** A client that is anonymous for good, as a server's is. */
+export const anonymousClient = (): Client =>
+  createClient({ network: "ic", identity: "anonymous" })
+
+/**
+ * The client a view that `useClient()` returned was made over, read through
+ * the seam core and the provider share (`ic-reactor.client.of`), or `client`
+ * itself when it is no view: a client built with `identity`, which
+ * `useClient()` returns as it is. `useClient()` returns a view per caller,
+ * never the provider's client object, so a test that asks which client a
+ * component got compares this.
+ */
+export const clientOf = (client: Client): Client =>
+  (client as unknown as { readonly [key: symbol]: Client | undefined })[
+    Symbol.for("ic-reactor.client.of")
+  ] ?? client
+
+/** A client the test can ask whether it was disposed, and how often. */
+export interface TrackedClient {
+  readonly client: Client
+  readonly dispose: Mock<() => void>
+}
+
+/**
+ * `real` with a counting `dispose` in front of its own. The real client is
+ * frozen, so this is an object over it, its prototype: every other member,
+ * and the stamps core puts on a client (its creation serial among them), are
+ * read from the real one.
+ */
+export function withDisposeSpy(real: Client): TrackedClient {
+  const dispose = vi.fn(() => real.dispose())
+  const client = Object.create(real, {
+    dispose: { value: dispose, enumerable: true },
+  }) as Client
+  return { client, dispose }
+}
+
+/**
+ * A client factory that records every client it builds, and counts the calls
+ * of their `dispose()` (see {@link withDisposeSpy}).
+ */
+export function trackedFactory(build: () => Client) {
+  const made: TrackedClient[] = []
+  const factory = vi.fn((): Client => {
+    const tracked = withDisposeSpy(build())
+    made.push(tracked)
+    return tracked.client
+  })
+  /** The record of the client a provider gave a component a view of. */
+  const trackOf = (client: Client): TrackedClient => {
+    const held = clientOf(client)
+    const found = made.find((entry) => entry.client === held)
+    if (found === undefined) {
+      throw new Error("the client was not built by this factory")
+    }
+    return found
+  }
+  /** How many times `dispose()` was called on any client this factory built. */
+  const disposals = (): number =>
+    made.reduce((sum, entry) => sum + entry.dispose.mock.calls.length, 0)
+  return { factory, made, trackOf, disposals }
+}
+
+/** Lets timers that are due, such as a provider's scheduled disposal, run. */
+export const macrotask = (): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, 5))
+
+/** One `register()` call that no `unregister()` has removed. */
+export interface Registration {
+  readonly target: object
+  readonly held: Client
+  readonly token: object
+}
+
+/**
+ * A `FinalizationRegistry` whose collections the test decides. A real one runs
+ * its cleanup at some garbage collection after a target became unreachable,
+ * which no test can wait for. This one records every call and runs the cleanup
+ * of every registration still standing when {@link collectAll} is called.
+ *
+ * Install it with {@link bindingsWith}: the provider makes its registry when
+ * its module is evaluated.
+ */
+export function fakeFinalizationRegistry() {
+  /** Registrations still standing. */
+  const live: Registration[] = []
+  /** The held value of every `register()` call, in order. */
+  const registered: Client[] = []
+  /** The token of every `unregister()` call, in order. */
+  const unregistered: object[] = []
+  const cleanups: Array<(held: Client) => void> = []
+
+  class Registry {
+    constructor(cleanup: (held: Client) => void) {
+      cleanups.push(cleanup)
+    }
+    register(target: object, held: Client, token: object): void {
+      live.push({ target, held, token })
+      registered.push(held)
+    }
+    unregister(token: object): boolean {
+      unregistered.push(token)
+      const before = live.length
+      live.splice(
+        0,
+        live.length,
+        ...live.filter((registration) => registration.token !== token)
+      )
+      return live.length < before
+    }
+  }
+
+  /**
+   * Runs the cleanup of every registration still standing, once, as a
+   * collection does once their targets are unreachable. A committed
+   * provider's state stays reachable, so a real collection would not reach
+   * it; a registration left standing for it is still the defect a test looks
+   * for, because the provider's unmount, not the registry, owns that client.
+   */
+  const collectAll = (): void => {
+    for (const { held } of live.splice(0)) {
+      for (const cleanup of cleanups) cleanup(held)
+    }
+  }
+
+  return { Registry, live, registered, unregistered, cleanups, collectAll }
+}
+
+/**
+ * A fresh copy of the bindings, evaluated with `registry` as the global
+ * `FinalizationRegistry`, or with none when it is `undefined`. Undo it with
+ * `vi.unstubAllGlobals()`.
+ */
+export async function bindingsWith(
+  registry: unknown
+): Promise<typeof import("../src/index.js")> {
+  vi.stubGlobal("FinalizationRegistry", registry)
+  vi.resetModules()
+  return import("../src/index.js")
+}
+
+/** The canister {@link callThrough} calls. */
+const CANISTER = "rdmx6-jaaaa-aaaaa-aaadq-cai"
+
+/** Candid's empty argument and reply, `()`. */
+const EMPTY = new Uint8Array([0x44, 0x49, 0x44, 0x4c, 0, 0])
+
+/** The service of that canister: one query that takes and returns nothing. */
+const PING = c.service({ ping: c.func([], [], "query") })
+
+/**
+ * A test client over a fake replica whose canister records who called it, and
+ * the sign-in the client calls as. `identity` is a seed, as for
+ * {@link testAuth}. The client is created when this is called, so a provider
+ * whose factory returns it borrows it, as one at module scope is.
+ */
+export function clientWithCanister(
+  options?: Parameters<typeof createTestClient>[0]
+): {
+  readonly client: Client
+  readonly auth: TestAuth
+  /** The callers the canister saw, as principal text, in order. */
+  readonly callers: string[]
+} {
+  const callers: string[] = []
+  const test = createTestClient(options)
+  test.mock<{ ping: () => Promise<void> }>(PING, CANISTER, {
+    ping: ({ caller }) => {
+      callers.push(caller)
+    },
+  })
+  return { client: test.client, auth: test.auth, callers }
+}
+
+/** What the tests use of core's internal fake replica. */
+interface FakeReplicaModule {
+  createFakeReplica(options: {
+    canisters: Record<string, { query?: (method: string) => Uint8Array }>
+  }): {
+    readonly host: string
+    readonly rootKey: Uint8Array
+    readonly fetch: typeof globalThis.fetch
+  }
+}
+
+/**
+ * Core's internal fake replica running `canisters`, for a client the test
+ * builds with `createClient` itself (one whose auth factory throws). The
+ * testing entry exports only `createTestClient`, so it is read from
+ * `testing/fake-replica.js` beside the entry, as {@link callPathOf} reads
+ * `client.js`.
+ */
+export async function fakeReplica(
+  canisters: Record<string, { query?: (method: string) => Uint8Array }>
+) {
+  const entry = createRequire(import.meta.url).resolve("@ic-reactor/core")
+  const internal = (await import(
+    new URL("testing/fake-replica.js", pathToFileURL(entry)).href
+  )) as FakeReplicaModule
+  return internal.createFakeReplica({ canisters })
+}
+
+/** What {@link callThrough} uses of core's internal `internalsOf`. */
+interface CallPath {
+  agentFor(
+    principal: string,
+    context: { readonly method: string; readonly canisterId: string }
+  ): Promise<{
+    query(
+      canisterId: string,
+      options: { methodName: string; arg: Uint8Array }
+    ): Promise<{ status: unknown }>
+  }>
+}
+
+/**
+ * Core's `internalsOf`, the one path every call of a client takes: the client
+ * hands out the agent of a caller there, and refuses one once it is disposed.
+ * No entry exports it, so it is read from `client.js` beside the entry that
+ * `@ic-reactor/core` resolves to, the module that entry itself imports and the
+ * only one that knows its clients.
+ *
+ * TODO(IR2t, #782): call through core's public canister builder once it has
+ * one.
+ */
+async function callPathOf(client: Client): Promise<CallPath> {
+  const entry = createRequire(import.meta.url).resolve("@ic-reactor/core")
+  const internal = (await import(
+    new URL("client.js", pathToFileURL(entry)).href
+  )) as { internalsOf(client: Client): CallPath }
+  return internal.internalsOf(client)
+}
+
+/**
+ * Sends a query through `client` as its caller now, and resolves once the
+ * replica answered. A disposed client rejects it before it is sent, as a
+ * `cancelled` error with the code `client_disposed`.
+ */
+export async function callThrough(client: Client): Promise<void> {
+  const callPath = await callPathOf(client)
+  const agent = await callPath.agentFor(client.caller(), {
+    method: "ping",
+    canisterId: CANISTER,
+  })
+  const response = await agent.query(CANISTER, {
+    methodName: "ping",
+    arg: EMPTY,
+  })
+  if (String(response.status) !== "replied") {
+    throw new Error(`the query was not answered: ${String(response.status)}`)
+  }
+}

package/packages/react/tests/hydration.test.tsx

@@ -0,0 +1,262 @@
+/**
+ * A server render has no session, so its HTML shows who calls as the
+ * anonymous principal. Hydration has to start from that same state even when
+ * the browser holds a session, and only then show the session: including in a
+ * component that hydrates after the root's `useAuth()` has already moved on,
+ * one inside a Suspense boundary whose code arrives later. React reports every
+ * mismatch through `onRecoverableError`, and logs it through `console.error`.
+ *
+ * The server render here runs in jsdom, where `useSyncExternalStore` takes its
+ * server snapshot in `renderToString` as it does anywhere; the server's client
+ * is anonymous, as a real server's is, so that a server snapshot that read the
+ * browser's state instead would produce different HTML on the two sides.
+ */
+import { act } from "@testing-library/react"
+import {
+  StrictMode,
+  Suspense,
+  lazy,
+  useEffect,
+  useState,
+  type ComponentType,
+  type ReactElement,
+} from "react"
+import { hydrateRoot, type Root } from "react-dom/client"
+import { renderToString } from "react-dom/server"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { ReactorProvider, useAuth } from "../src/index.js"
+import {
+  anonymousClient,
+  clientWithAuth,
+  macrotask,
+  type TestAuth,
+  testAuth,
+} from "./helpers.js"
+
+let root: Root | undefined
+let container: HTMLElement
+
+beforeEach(() => {
+  container = document.createElement("div")
+  document.body.appendChild(container)
+})
+
+afterEach(() => {
+  act(() => root?.unmount())
+  root = undefined
+  container.remove()
+  vi.restoreAllMocks()
+})
+
+/** What each render of the header saw, in order. */
+let headerStatuses: string[]
+
+function Header() {
+  const { status, principal } = useAuth()
+  headerStatuses.push(status)
+  return <header>{`${status}:${principal}`}</header>
+}
+
+const Profile = () => <main>{useAuth().status}</main>
+
+/** The page: the server renders it anonymous, the browser with `auth`. */
+function page(Late: ComponentType, auth?: TestAuth): ReactElement {
+  return (
+    <ReactorProvider
+      client={() =>
+        auth === undefined ? anonymousClient() : clientWithAuth(() => auth)
+      }
+    >
+      <Header />
+      <Suspense fallback={<p>loading</p>}>
+        <Late />
+      </Suspense>
+    </ReactorProvider>
+  )
+}
+
+/** Hydrates `container` with `element`, returning what React reported. */
+async function hydrate(element: ReactElement) {
+  const recoverable: string[] = []
+  const logged = vi.spyOn(console, "error").mockImplementation(() => {})
+  await act(async () => {
+    root = hydrateRoot(container, element, {
+      onRecoverableError: (error) =>
+        recoverable.push(String((error as Error).message)),
+    })
+  })
+  await act(macrotask)
+  return { recoverable, logged }
+}
+
+describe("hydrating the server's HTML", () => {
+  it("is rendered as the same HTML by a client that holds a session and one that does not", () => {
+    // The HTML below is the one the hydration tests start from, written by an
+    // anonymous client. A server's real client holds no session either, so the
+    // two renders have to agree: the server snapshot does not read the auth.
+    headerStatuses = []
+    const auth = testAuth({ identity: 7 })
+    const buildAuth = vi.fn(() => auth)
+    const anonymous = renderToString(page(Profile))
+
+    const withSession = renderToString(
+      <ReactorProvider client={() => clientWithAuth(buildAuth)}>
+        <Header />
+        <Suspense fallback={<p>loading</p>}>
+          <Profile />
+        </Suspense>
+      </ReactorProvider>
+    )
+
+    expect(withSession).toBe(anonymous)
+    expect(withSession).not.toContain("signed-in")
+    // The session was not even read, though jsdom has a `window` to read it in.
+    expect(buildAuth).not.toHaveBeenCalled()
+  })
+
+  it("starts anonymous while the browser is signed in, then shows the session", async () => {
+    headerStatuses = []
+    const auth = testAuth({ identity: 7 })
+    const principal = auth.getPrincipal()?.toText()
+    container.innerHTML = renderToString(page(Profile))
+    expect(container.textContent).toBe("anonymous:2vxsx-faeanonymous")
+    headerStatuses = []
+
+    const { recoverable, logged } = await hydrate(page(Profile, auth))
+
+    expect(recoverable).toEqual([])
+    expect(logged).not.toHaveBeenCalled()
+    // The first render matched the HTML; the next one showed the session.
+    expect(headerStatuses).toEqual(["anonymous", "signed-in"])
+    expect(container.querySelector("header")?.textContent).toBe(
+      `signed-in:${principal}`
+    )
+    expect(container.querySelector("main")?.textContent).toBe("signed-in")
+  })
+
+  it("hydrates a boundary that arrives after the session was shown", async () => {
+    headerStatuses = []
+    const auth = testAuth({ identity: 7 })
+    container.innerHTML = renderToString(page(Profile))
+
+    let deliver!: () => void
+    const Late = lazy(
+      () =>
+        new Promise<{ default: ComponentType }>((resolve) => {
+          deliver = () => resolve({ default: Profile })
+        })
+    )
+    const { recoverable, logged } = await hydrate(page(Late, auth))
+    // The header has hydrated and moved on; the boundary is still the server's.
+    expect(container.querySelector("header")?.textContent).toMatch(
+      /^signed-in:/
+    )
+    expect(container.querySelector("main")?.textContent).toBe("anonymous")
+
+    await act(async () => deliver())
+    await act(macrotask)
+
+    expect(recoverable).toEqual([])
+    expect(logged).not.toHaveBeenCalled()
+    expect(container.querySelector("main")?.textContent).toBe("signed-in")
+  })
+
+  it("stays anonymous when the browser holds no session", async () => {
+    headerStatuses = []
+    const auth = testAuth({ identity: 7, signedIn: false })
+    container.innerHTML = renderToString(page(Profile))
+
+    const { recoverable, logged } = await hydrate(page(Profile, auth))
+
+    expect(recoverable).toEqual([])
+    expect(logged).not.toHaveBeenCalled()
+    expect(container.textContent).toBe("anonymous:2vxsx-faeanonymous")
+  })
+})
+
+/**
+ * The redirect sign-in route of the auth guide, as the guide shows it: its
+ * effect starts the sign-in on a timer that its cleanup clears. Keep the two
+ * in step.
+ */
+function SignInPage() {
+  const { status, signIn } = useAuth()
+  const [failed, setFailed] = useState(false)
+  useEffect(() => {
+    if (status === "signed-in") return
+    const start = setTimeout(() => {
+      signIn({ returnTo: "/account" }).catch((error: unknown) => {
+        console.error(error)
+        setFailed(true)
+      })
+    })
+    return () => clearTimeout(start)
+  }, [status, signIn])
+  if (status === "signed-in") return <a href="/account">Continue</a>
+  if (failed) {
+    return (
+      <p>
+        The sign-in did not finish. <a href="/sign-in">Try again</a>
+      </p>
+    )
+  }
+  return <p>Signing you in…</p>
+}
+
+/** The sign-in route: the server renders it anonymous, the browser with `auth`. */
+const signInRoute = (auth?: TestAuth): ReactElement => (
+  <StrictMode>
+    <ReactorProvider
+      client={() =>
+        auth === undefined ? anonymousClient() : clientWithAuth(() => auth)
+      }
+    >
+      <SignInPage />
+    </ReactorProvider>
+  </StrictMode>
+)
+
+/** `real` with a `signIn` that counts its calls. */
+function countingSignIn(real: TestAuth) {
+  const signIn = vi.fn((_options?: unknown) => real.signIn())
+  return { auth: { ...real, signIn }, signIn }
+}
+
+describe("the auth guide's sign-in route, hydrated", () => {
+  it("sends nobody to sign in whose session the hydrating render did not show", async () => {
+    const { auth, signIn } = countingSignIn(testAuth({ identity: 7 }))
+    container.innerHTML = renderToString(signInRoute())
+
+    const { recoverable } = await hydrate(signInRoute(auth))
+
+    expect(recoverable).toEqual([])
+    expect(signIn).not.toHaveBeenCalled()
+    expect(container.textContent).toBe("Continue")
+  })
+
+  it("starts one sign-in in a browser that holds no session, under StrictMode", async () => {
+    const { auth, signIn } = countingSignIn(
+      testAuth({ identity: 7, signedIn: false })
+    )
+    container.innerHTML = renderToString(signInRoute())
+
+    await hydrate(signInRoute(auth))
+
+    expect(signIn).toHaveBeenCalledTimes(1)
+    expect(signIn).toHaveBeenCalledWith({ returnTo: "/account" })
+    expect(auth.getStatus().state).toBe("signed-in")
+  })
+
+  it("offers to try again when the sign-in fails", async () => {
+    const real = testAuth({ identity: 7, signedIn: false })
+    const cancelled = new Error("The user cancelled the sign-in.")
+    const auth = { ...real, signIn: vi.fn(() => Promise.reject(cancelled)) }
+    container.innerHTML = renderToString(signInRoute())
+
+    await hydrate(signInRoute(auth))
+
+    expect(auth.signIn).toHaveBeenCalledTimes(1)
+    expect(container.textContent).toBe("The sign-in did not finish. Try again")
+    expect(container.querySelector("a")?.getAttribute("href")).toBe("/sign-in")
+  })
+})