@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/interface/load.ts

@@ -0,0 +1,249 @@
+// Isomorphic: what route loaders call to get a canister's interface, and how
+// a page rebuilds schemas from the payload on either side.
+import { serviceMethods, type AnySchema } from "@meantjs/schema"
+import { schemaFromContract } from "@meantjs/schema/contract"
+import { useMemo } from "react"
+import { checkCanisterId } from "../lib/ids.ts"
+import { CURATED, registryEntry, type RegistryEntry } from "../lib/registry.ts"
+import { Lru } from "./cache.ts"
+import { docFor } from "./docs.ts"
+import { fetchInterface } from "./functions.ts"
+import { serverResult } from "./server-result.ts"
+import { typedPayload } from "./typed.ts"
+import type {
+  CanisterInterface,
+  InterfacePayload,
+  MethodInfo,
+} from "./types.ts"
+
+export { typedModuleText } from "./typed.ts"
+
+type OkPayload = Extract<InterfacePayload, { ok: true }>
+
+/**
+ * The interface payload of a canister, on either side: a registry canister
+ * gives its typed payload (no network), any other canister its live one
+ * (`loadLivePayload`). Never throws: failures are `{ ok: false }` payloads.
+ */
+export async function loadInterfacePayload(
+  canisterId: string
+): Promise<InterfacePayload> {
+  const id = checkCanisterId(canisterId)
+  if (!id.ok) {
+    return { ok: false, canisterId, code: id.code, message: id.message }
+  }
+  const entry = registryEntry(id.id)
+  if (entry === undefined) return loadLivePayload(id.id)
+  try {
+    return await typedPayload(entry)
+  } catch (error) {
+    return { ok: false, canisterId, code: "network", message: messageOf(error) }
+  }
+}
+
+// Canisters whose next live load is an explicit retry: set by "Try again"
+// just before it re-runs the route loader, taken by that load.
+const retryNext = new Set<string>()
+
+/** Makes the next live load of this canister skip a remembered transient failure. */
+export function retryInterface(canisterId: string): void {
+  retryNext.add(canisterId)
+}
+
+/**
+ * The live interface payload of any canister, registry canisters included:
+ * through the `fetchInterface` server function. In the browser, when that
+ * call fails or gives no result (StackBlitz, where server functions cannot
+ * run), the browser reads the canister's certified metadata and compiles it
+ * with a lazily loaded compiler instead (`compiledIn: "browser"`). Never
+ * throws.
+ */
+export async function loadLivePayload(
+  canisterId: string
+): Promise<InterfacePayload> {
+  const id = checkCanisterId(canisterId)
+  if (!id.ok) {
+    return { ok: false, canisterId, code: id.code, message: id.message }
+  }
+  const retry = retryNext.delete(id.id)
+  try {
+    return await serverResult(
+      fetchInterface({ data: { canisterId: id.id, retry } })
+    )
+  } catch (error) {
+    if (import.meta.env.SSR) {
+      return {
+        ok: false,
+        canisterId,
+        code: "network",
+        message: messageOf(error),
+      }
+    }
+  }
+  try {
+    const { readInterfaceInBrowser } = await import("./browser.ts")
+    return await readInterfaceInBrowser(id.id, { retry })
+  } catch (error) {
+    return { ok: false, canisterId, code: "network", message: messageOf(error) }
+  }
+}
+
+/** The schemas and methods of one .did, shared by the canisters that have it. */
+type Built = {
+  actor: AnySchema
+  methods: readonly MethodInfo[]
+  byName: ReadonlyMap<string, MethodInfo>
+  omitted: CanisterInterface["omitted"]
+}
+
+// Module-level memos, so the same payload gives the same objects (and
+// `client.canister()` the same canister) on every render. Runtime interfaces
+// are keyed by did hash: the server holds one map for all requests, which
+// is safe because an interface is public data, and bounded.
+const builtByDid = new Lru<string, Built>({ maxEntries: 64 })
+const builtByRegistryId = new Map<string, Built>()
+const interfaces = new Lru<string, CanisterInterface>({ maxEntries: 128 })
+
+const CURATED_NAMES: ReadonlyMap<string, string> = new Map(
+  CURATED.map((c) => [c.id, c.name])
+)
+
+/**
+ * Rebuilds the interface from a payload: a registry canister's generated
+ * actor for a typed payload, `schemaFromContract` of the envelope for any
+ * other. Memoized (by registry id, or by `didSha256`), so the same payload
+ * gives the same object. Throws for a runtime payload whose envelope the
+ * schema loader refuses, which the server already ruled out.
+ */
+export function interfaceFromPayload(p: OkPayload): CanisterInterface {
+  const key = interfaceKey(p)
+  const known = interfaces.get(key)
+  if (known !== undefined) return known
+
+  const registry =
+    p.source.kind === "typed" ? registryEntry(p.canisterId) : undefined
+  if (p.source.kind === "typed" && registry === undefined) {
+    throw new Error(
+      `${p.canisterId} is not a registry canister, so it has no typed interface.`
+    )
+  }
+  const built =
+    registry === undefined
+      ? builtFromEnvelope(p)
+      : builtFromRegistry(registry, p)
+  const iface: CanisterInterface = {
+    canisterId: p.canisterId,
+    name: nameOf(p, registry),
+    actor: built.actor,
+    methods: built.methods,
+    method: (name) => built.byName.get(name),
+    source: p.source,
+    did: p.did,
+    didSha256: p.didSha256,
+    omitted: built.omitted,
+    ...(registry === undefined ? {} : { registry }),
+  }
+  interfaces.set(key, iface)
+  return iface
+}
+
+/** `interfaceFromPayload` for components; `undefined` for a failed payload. */
+export function useCanisterInterface(
+  p: InterfacePayload
+): CanisterInterface | undefined {
+  return useMemo(() => (p.ok ? interfaceFromPayload(p) : undefined), [p])
+}
+
+function interfaceKey(p: OkPayload): string {
+  const hash = "moduleHash" in p.source ? (p.source.moduleHash ?? "") : ""
+  return [p.source.kind, p.canisterId, p.didSha256, hash].join("\u0000")
+}
+
+function builtFromRegistry(entry: RegistryEntry, p: OkPayload): Built {
+  let built = builtByRegistryId.get(entry.id)
+  if (built === undefined) {
+    built = build(entry.actor, [], p.docs)
+    builtByRegistryId.set(entry.id, built)
+  }
+  return built
+}
+
+function builtFromEnvelope(p: OkPayload): Built {
+  const known = builtByDid.get(p.didSha256)
+  if (known !== undefined) return known
+  if (p.envelopeJson === undefined) {
+    throw new Error(
+      `The interface payload of ${p.canisterId} carries no envelope.`
+    )
+  }
+  // The envelope is JSON the server (or this browser) wrote with
+  // `JSON.stringify`; `schemaFromContract` takes `unknown` and validates all of it.
+  const result = schemaFromContract(JSON.parse(p.envelopeJson) as unknown)
+  if (!result.ok) {
+    const issues = result.issues
+      .slice(0, 3)
+      .map((i) => `${i.code} at ${i.path}`)
+    throw new Error(
+      `The interface of ${p.canisterId} did not load: ${issues.join("; ")}`
+    )
+  }
+  if (result.actor === undefined) {
+    throw new Error(`The interface of ${p.canisterId} declares no service.`)
+  }
+  const built = build(result.actor, result.omitted, p.docs)
+  builtByDid.set(p.didSha256, built)
+  return built
+}
+
+/**
+ * The methods of a service schema, sorted by name, each with its doc from
+ * `docs` when there is one.
+ */
+export function methodsOf(
+  actor: AnySchema,
+  docs: Readonly<Record<string, string>> = {}
+): MethodInfo[] {
+  const methods: MethodInfo[] = []
+  for (const m of serviceMethods(actor).values()) {
+    const doc = docFor(docs, m.name)
+    methods.push({
+      name: m.name,
+      mode: m.mode,
+      args: m.args,
+      results: m.results,
+      ...(doc === undefined ? {} : { doc }),
+    })
+  }
+  // Code-point order, not localeCompare: the server and the browser must
+  // agree whatever their locales.
+  return methods.sort((a, b) =>
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0
+  )
+}
+
+function build(
+  actor: AnySchema,
+  omitted: CanisterInterface["omitted"],
+  docs: Readonly<Record<string, string>>
+): Built {
+  const methods = methodsOf(actor, docs)
+  return {
+    actor,
+    methods,
+    byName: new Map(methods.map((m) => [m.name, m])),
+    omitted: omitted.map((o) => ({ ...o })),
+  }
+}
+
+function nameOf(p: OkPayload, registry: RegistryEntry | undefined): string {
+  if (registry !== undefined) return registry.name
+  const curated = CURATED_NAMES.get(p.canisterId)
+  if (curated !== undefined) return curated
+  if (p.source.kind === "pasted") return "Pasted interface"
+  return p.canisterId
+}
+
+function messageOf(error: unknown): string {
+  const text = error instanceof Error ? error.message : String(error)
+  return `The interface could not be loaded: ${text.slice(0, 300)}`
+}

package/examples/canister-studio/src/interface/read-candid.test.ts

@@ -0,0 +1,185 @@
+// @vitest-environment node
+// What a verified certificate proves, read through the agent-backed source.
+// The certificate is stubbed (no BLS signature), but each path is looked up
+// with the agent's own `lookup_path` over a hand-built hash tree, so a
+// pruned branch answers Unknown and a missing label Absent, as on mainnet.
+import {
+  lookup_path,
+  NodeType,
+  type HashTree,
+  type HttpAgent,
+  type KnownPath,
+  type NodeHash,
+  type NodeLabel,
+  type NodeValue,
+} from "@icp-sdk/core/agent"
+import { Principal } from "@icp-sdk/core/principal"
+import { describe, expect, it, vi } from "vitest"
+import { createLiveInterfaceLoader } from "./live-loader.ts"
+import {
+  agentCandidSource,
+  classifyReadError,
+  UnprovenPathError,
+} from "./read-candid.ts"
+
+const ICP_LEDGER = "ryjl3-tyaaa-aaaaa-aaaba-cai"
+const DID = "service : { icrc1_symbol : () -> (text) query }"
+const HASH = new Uint8Array(32).fill(0xa1)
+
+// The tree's byte types are branded; these are plain bytes.
+const utf8 = (text: string) => new TextEncoder().encode(text)
+const labelled = (bytes: Uint8Array, tree: HashTree): HashTree => [
+  NodeType.Labeled,
+  bytes as NodeLabel,
+  tree,
+]
+const label = (text: string, tree: HashTree): HashTree =>
+  labelled(utf8(text), tree)
+const leaf = (bytes: Uint8Array): HashTree => [
+  NodeType.Leaf,
+  bytes as NodeValue,
+]
+const fork = (left: HashTree, right: HashTree): HashTree => [
+  NodeType.Fork,
+  left,
+  right,
+]
+// What a party between the replica and the server can put in place of any
+// subtree without changing the root hash.
+const pruned: HashTree = [
+  NodeType.Pruned,
+  new Uint8Array(32).fill(7) as NodeHash,
+]
+
+type Part = "present" | "absent" | "pruned"
+
+// canister/<id>/{metadata/candid:service, module_hash}, labels in order.
+function treeOf(candid: Part, hash: Part): HashTree {
+  const metadata =
+    candid === "present"
+      ? label("candid:service", leaf(utf8(DID)))
+      : candid === "pruned"
+        ? label("candid:service", pruned)
+        : label("candid:args", leaf(utf8("()")))
+  const children = [label("metadata", metadata)]
+  if (hash === "present") children.push(label("module_hash", leaf(HASH)))
+  if (hash === "pruned") children.push(label("module_hash", pruned))
+  const [first, second] = children
+  if (first === undefined) throw new Error("unreachable")
+  return label(
+    "canister",
+    labelled(
+      Principal.fromText(ICP_LEDGER).toUint8Array(),
+      second === undefined ? first : fork(first, second)
+    )
+  )
+}
+
+/**
+ * An agent whose read_state answers with a certificate over `tree`. Its
+ * `values` map behaves as the agent's does (null for any lookup that is not
+ * Found), which is what the source must not rely on.
+ */
+function agentOver(tree: HashTree) {
+  const query = vi.fn(() => {
+    throw new Error("the tmp hack query was sent")
+  })
+  const agent = {
+    readState: vi.fn(async () => ({
+      certificate: new Uint8Array(),
+      verifiedCertificate: {
+        lookup_path: (path: Uint8Array[]) => lookup_path(path, tree),
+      },
+      values: {
+        get<T>(path: KnownPath<T>): T | null {
+          const found = lookup_path(path.path, tree)
+          return found.status === "Found" ? path.decode(found.value) : null
+        },
+      },
+    })),
+    query,
+  }
+  return { agent: agent as unknown as HttpAgent, query }
+}
+
+function loaderOver(tree: HashTree) {
+  const { agent, query } = agentOver(tree)
+  const compile = vi.fn(async () => ({
+    ok: true as const,
+    envelopeJson: "{}",
+    interfaceId: "",
+    docs: {},
+    omitted: [],
+  }))
+  const loader = createLiveInterfaceLoader({
+    source: agentCandidSource(agent),
+    compile,
+    compiledIn: "server",
+  })
+  return { loader, query, compile }
+}
+
+describe("agentCandidSource", () => {
+  it("reads the candid:service and the module hash the certificate shows", async () => {
+    const { agent } = agentOver(treeOf("present", "present"))
+    const read = await agentCandidSource(agent).readCandidAndHash(ICP_LEDGER)
+    expect(read).toEqual({ did: DID, moduleHash: HASH })
+  })
+
+  it("gives null only for what the certificate proves absent", async () => {
+    const { agent } = agentOver(treeOf("absent", "absent"))
+    const source = agentCandidSource(agent)
+    expect(await source.readCandidAndHash(ICP_LEDGER)).toEqual({
+      did: null,
+      moduleHash: null,
+    })
+    expect(await source.readModuleHash(ICP_LEDGER)).toBeNull()
+  })
+
+  it.each([
+    ["a pruned candid:service", treeOf("pruned", "present")],
+    ["a pruned module_hash", treeOf("present", "pruned")],
+  ])("throws for %s, which proves nothing", async (_, tree) => {
+    const { agent } = agentOver(tree)
+    const error: unknown = await agentCandidSource(agent)
+      .readCandidAndHash(ICP_LEDGER)
+      .catch((e) => e)
+    expect(error).toBeInstanceOf(UnprovenPathError)
+    expect(classifyReadError(error, "metadata")).toMatchObject({
+      kind: "failed",
+      code: "trust_error",
+    })
+  })
+
+  it("throws for a pruned module_hash read alone", async () => {
+    const { agent } = agentOver(treeOf("present", "pruned"))
+    await expect(
+      agentCandidSource(agent).readModuleHash(ICP_LEDGER)
+    ).rejects.toBeInstanceOf(UnprovenPathError)
+  })
+})
+
+describe("the loader over a pruned certificate", () => {
+  it("never takes a pruned candid:service for an absent one: no tmp hack", async () => {
+    const { loader, query } = loaderOver(treeOf("pruned", "present"))
+    expect(await loader.load(ICP_LEDGER)).toMatchObject({
+      ok: false,
+      code: "trust_error",
+    })
+    expect(query).not.toHaveBeenCalled()
+  })
+
+  it("never takes a pruned module_hash for 'no module installed'", async () => {
+    const { loader } = loaderOver(treeOf("absent", "pruned"))
+    expect(await loader.load(ICP_LEDGER)).toMatchObject({
+      ok: false,
+      code: "trust_error",
+    })
+  })
+
+  it("falls back only when the certificate proves the metadata absent", async () => {
+    const { loader, query } = loaderOver(treeOf("absent", "present"))
+    await loader.load(ICP_LEDGER)
+    expect(query).toHaveBeenCalled()
+  })
+})

package/examples/canister-studio/src/interface/read-candid.ts

@@ -0,0 +1,233 @@
+// Reading a live canister's Candid from mainnet, on the server or in the
+// browser. The loader takes a `CandidSource`, so tests hand it a fake one and
+// never touch the network.
+import {
+  Actor,
+  AgentError,
+  HttpAgent,
+  HttpErrorCode,
+  HttpFetchErrorCode,
+  LookupPathStatus,
+  RejectError,
+  StatePaths,
+  TrustError,
+  type KnownPath,
+  type ReadStateResponse,
+} from "@icp-sdk/core/agent"
+import { Principal } from "@icp-sdk/core/principal"
+import type { InterfaceErrorCode } from "./types.ts"
+
+/**
+ * The one host the studio reads interfaces from: mainnet's API boundary
+ * nodes. No URL is ever built from user input; a canister id only goes into
+ * the request path, after `checkCanisterId` accepted it.
+ */
+export const IC_API_HOST = "https://icp-api.io"
+
+/** Each HTTP request to the IC gives up after this long. */
+const REQUEST_TIMEOUT_MS = 10_000
+
+/**
+ * Where a canister's Candid comes from. The agent-backed source reads
+ * mainnet; each method throws the agent's own errors, which
+ * `classifyReadError` sorts into the loader's error codes.
+ */
+export interface CandidSource {
+  /**
+   * One certified `read_state` of `candid:service` and `module_hash`: a
+   * `null` value means the certificate proves the path absent (no such
+   * metadata section, or no module installed). A path the certificate
+   * neither shows nor proves absent throws an `UnprovenPathError`.
+   */
+  readCandidAndHash(canisterId: string): Promise<{
+    did: string | null
+    moduleHash: Uint8Array | null
+  }>
+  /** A certified `read_state` of `module_hash` alone, read the same way. */
+  readModuleHash(canisterId: string): Promise<Uint8Array | null>
+  /**
+   * The canister's `__get_candid_interface_tmp_hack` query: the answer of
+   * one replica, not certified.
+   */
+  readTmpHack(canisterId: string): Promise<string>
+}
+
+/**
+ * A path a verified certificate leaves unproven: its tree holds neither the
+ * value nor a proof that there is none, only a pruned branch. An honest
+ * replica answers every path it was asked; a party between it and the
+ * server (a boundary node) can prune a genuine certificate without breaking
+ * its signature. `classifyReadError` reports it as `trust_error`, so the
+ * loader never takes it for an absence and falls back.
+ */
+export class UnprovenPathError extends Error {
+  override name = "UnprovenPathError"
+}
+
+/** A `CandidSource` over an agent. Paths are built from the parsed principal. */
+export function agentCandidSource(agent: HttpAgent): CandidSource {
+  return {
+    async readCandidAndHash(canisterId) {
+      const id = Principal.fromText(canisterId)
+      const candid = StatePaths.canisterCandid(id)
+      const hash = StatePaths.canisterModuleHash(id)
+      const response = await agent.readState(
+        { canisterId: id },
+        { paths: [candid, hash] }
+      )
+      return {
+        did: provenValue(response, candid, "candid:service"),
+        moduleHash: provenValue(response, hash, "module_hash"),
+      }
+    },
+    async readModuleHash(canisterId) {
+      const id = Principal.fromText(canisterId)
+      const hash = StatePaths.canisterModuleHash(id)
+      const response = await agent.readState(
+        { canisterId: id },
+        { paths: [hash] }
+      )
+      return provenValue(response, hash, "module_hash")
+    },
+    async readTmpHack(canisterId) {
+      const service = Actor.createActor<{
+        __get_candid_interface_tmp_hack: () => Promise<string>
+      }>(
+        ({ IDL: idl }) =>
+          idl.Service({
+            __get_candid_interface_tmp_hack: idl.Func(
+              [],
+              [idl.Text],
+              ["query"]
+            ),
+          }),
+        { agent, canisterId }
+      )
+      return service.__get_candid_interface_tmp_hack()
+    },
+  }
+}
+
+// The value at `path`, `null` only when the certificate proves it absent.
+// The agent's `values` map gives null for an unproven path too, so this
+// asks the verified certificate itself.
+function provenValue<T>(
+  response: ReadStateResponse,
+  path: KnownPath<T>,
+  label: string
+): T | null {
+  const found = response.verifiedCertificate.lookup_path(path.path)
+  switch (found.status) {
+    case LookupPathStatus.Found:
+      return path.decode(found.value)
+    case LookupPathStatus.Absent:
+      return null
+    default:
+      throw new UnprovenPathError(
+        `The certificate neither shows nor rules out the canister's ${label}.`
+      )
+  }
+}
+
+/**
+ * The agent the loader reads metadata with: mainnet, anonymous, the
+ * hard-coded mainnet root key (every certificate is verified against it),
+ * and `retryTimes: 0`. HttpAgent otherwise re-sends every non-2xx response
+ * (a 403 or a `canister_not_found` too) three times with backoff, which
+ * turns each miss into 3 to 5 seconds.
+ */
+export function createMetadataAgent(): HttpAgent {
+  return HttpAgent.createSync({
+    host: IC_API_HOST,
+    retryTimes: 0,
+    fetch: boundedFetch,
+  })
+}
+
+const boundedFetch: typeof fetch = (input, init) => {
+  const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  const signal =
+    init?.signal != null && typeof AbortSignal.any === "function"
+      ? AbortSignal.any([init.signal, timeout])
+      : timeout
+  return fetch(input, { ...init, signal })
+}
+
+/** Which read failed, for `classifyReadError`. */
+export type ReadStage = "metadata" | "module_hash" | "tmp_hack"
+
+/** A read failure, sorted into what the loader does next. */
+export type ReadError =
+  /** `candid:service` is readable by the canister's controllers only. */
+  | { kind: "private" }
+  /** The tmp hack query was rejected: the canister has no such method. */
+  | { kind: "no_tmp_hack" }
+  | { kind: "failed"; code: InterfaceErrorCode; message: string }
+
+/**
+ * Sorts an error thrown by a `CandidSource` read. A `TrustError` (a
+ * certificate or signature that did not verify) and an `UnprovenPathError`
+ * are always `trust_error`, at every stage, so the loader never falls back
+ * past them. A 403 at the metadata stage is `private`: it is not signed,
+ * so it only ever leads to the labelled, uncertified tmp hack.
+ */
+export function classifyReadError(error: unknown, stage: ReadStage): ReadError {
+  if (error instanceof TrustError || error instanceof UnprovenPathError) {
+    return {
+      kind: "failed",
+      code: "trust_error",
+      message: `The IC's answer did not verify, so it was not used: ${agentMessage(error)}`,
+    }
+  }
+  if (error instanceof AgentError && error.code instanceof HttpErrorCode) {
+    const { status, bodyText = "" } = error.code
+    if (status === 403 && stage === "metadata") return { kind: "private" }
+    if (status === 400 && bodyText.includes("canister_not_found")) {
+      return {
+        kind: "failed",
+        code: "canister_not_found",
+        message: "No canister has this id on mainnet.",
+      }
+    }
+    return {
+      kind: "failed",
+      code: "network",
+      message: `The IC answered HTTP ${status}: ${bodyText.slice(0, 200) || error.code.statusText}`,
+    }
+  }
+  if (stage === "tmp_hack" && error instanceof RejectError) {
+    return { kind: "no_tmp_hack" }
+  }
+  if (isRequestTimeout(error)) {
+    return {
+      kind: "failed",
+      code: "timeout",
+      message: `The IC did not answer within ${REQUEST_TIMEOUT_MS / 1000} s.`,
+    }
+  }
+  return {
+    kind: "failed",
+    code: "network",
+    message: `Reading the interface failed: ${agentMessage(error)}`,
+  }
+}
+
+// The agent wraps a failed fetch, so the abort of `boundedFetch` arrives as
+// an HttpFetchErrorCode holding the TimeoutError.
+function isRequestTimeout(error: unknown): boolean {
+  const cause =
+    error instanceof AgentError && error.code instanceof HttpFetchErrorCode
+      ? error.code.error
+      : error
+  // A DOMException, which is not an Error subclass in every runtime.
+  return (
+    typeof cause === "object" &&
+    cause !== null &&
+    Reflect.get(cause, "name") === "TimeoutError"
+  )
+}
+
+function agentMessage(error: unknown): string {
+  const text = error instanceof Error ? error.message : String(error)
+  return text.split("\n")[0]?.slice(0, 200) ?? ""
+}