@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/core/src/hydration.ts

@@ -0,0 +1,239 @@
+/**
+ * The lossless serializer a client's `QueryClient` dehydrates and hydrates
+ * with, so a server render can hand its cache to the browser as JSON.
+ *
+ * Candid values are not JSON values. `nat`, `int` and every 64-bit integer
+ * decode to `bigint`, which `JSON.stringify` refuses; `blob` decodes to a
+ * `Uint8Array`, which it turns into an object of numbered keys; a float can be
+ * `NaN`, `±Infinity` or `-0`, which it turns into `null` or `0`. So
+ * {@link serializeData} rewrites those into tagged JSON objects and
+ * {@link deserializeData} rewrites them back, and everything JSON already
+ * keeps (strings such as principal text, `null`, booleans, arrays, records,
+ * variants as `{ tag, value }`) passes through unchanged.
+ *
+ * A tag is an object with the key `"$ic"`. A real object that has that key is
+ * escaped (wrapped in an `"object"` tag), so a canister record that happens to
+ * look like a tag comes back as the record it was.
+ *
+ * Internal: the client sets these as its `QueryClient`'s
+ * `defaultOptions.dehydrate.serializeData` and
+ * `defaultOptions.hydrate.deserializeData`; nothing else uses them and the
+ * package entry does not export them.
+ *
+ * @module
+ */
+
+/** A value `JSON.stringify` writes and `JSON.parse` reads back unchanged. */
+export type JsonValue =
+  null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
+
+/** The key that marks a tagged value. */
+const TAG = "$ic"
+
+/**
+ * What a tag stands for. `v` holds the payload:
+ *
+ * - `bigint`: decimal text, such as `"-18446744073709551616"`.
+ * - `bytes`: a `Uint8Array`, as base64.
+ * - `number`: `"NaN"`, `"Infinity"`, `"-Infinity"` or `"-0"`, the four numbers
+ *   JSON cannot write.
+ * - `undefined`: no payload. JSON drops a key whose value is `undefined` and
+ *   writes `null` in its place in an array; a tag keeps either as it was.
+ * - `object`: an object that has the key `"$ic"` itself, with its entries
+ *   encoded in `v`.
+ */
+type Tag = "bigint" | "bytes" | "number" | "undefined" | "object"
+
+const tagged = (tag: Tag, payload?: JsonValue): JsonValue =>
+  payload === undefined ? { [TAG]: tag } : { [TAG]: tag, v: payload }
+
+/**
+ * Sets `key` on `target` as an own, enumerable data property. A plain
+ * assignment of `"__proto__"` would replace the object's prototype instead of
+ * adding the key a Candid record (or `JSON.parse`) can give it.
+ */
+const setOwn = (target: object, key: string, value: unknown): void => {
+  if (key === "__proto__") {
+    Object.defineProperty(target, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    })
+  } else {
+    ;(target as Record<string, unknown>)[key] = value
+  }
+}
+
+/**
+ * Whether `value` is a `Uint8Array`, from this realm or another (a vm context,
+ * a test DOM), where `instanceof` would say no. Node's `Buffer` counts.
+ */
+const isBytes = (value: object): value is Uint8Array =>
+  Object.prototype.toString.call(value) === "[object Uint8Array]"
+
+const hasOwn = (value: object, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(value, key)
+
+/** Base64 of `bytes`, in chunks so a large blob does not overflow the argument list. */
+function toBase64(bytes: Uint8Array): string {
+  let binary = ""
+  for (let start = 0; start < bytes.length; start += 0x8000) {
+    binary += String.fromCharCode(
+      ...Array.from(bytes.subarray(start, start + 0x8000))
+    )
+  }
+  return btoa(binary)
+}
+
+function fromBase64(text: string): Uint8Array {
+  const binary = atob(text)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i)
+  return bytes
+}
+
+/** A number JSON cannot write, as its tag payload, or `undefined` for one it can. */
+const specialNumber = (value: number): string | undefined => {
+  if (Number.isNaN(value)) return "NaN"
+  if (value === Infinity) return "Infinity"
+  if (value === -Infinity) return "-Infinity"
+  if (Object.is(value, -0)) return "-0"
+  return undefined
+}
+
+const SPECIAL_NUMBERS: Readonly<Record<string, number>> = {
+  NaN: NaN,
+  Infinity: Infinity,
+  "-Infinity": -Infinity,
+  "-0": -0,
+}
+
+/** Whether JSON leaves `value` out of an object (and writes `null` for it in an array). */
+const isSkipped = (value: unknown): boolean =>
+  typeof value === "function" || typeof value === "symbol"
+
+/**
+ * Rewrites `data` into a value JSON keeps exactly. See the module comment for
+ * what is tagged.
+ *
+ * Anything that is not a Candid value is treated as `JSON.stringify` treats
+ * it, so data an app caches from elsewhere comes out no worse than it would
+ * without this serializer: an object with a `toJSON()` (a `Date`) is replaced
+ * by what that returns, another object is reduced to its own enumerable keys,
+ * and a function or symbol is dropped from an object and becomes `null` in an
+ * array.
+ *
+ * @throws TypeError on a cyclic structure, as `JSON.stringify` does.
+ */
+export function serializeData(data: unknown): JsonValue {
+  const ancestors = new Set<object>()
+
+  const encode = (value: unknown): JsonValue => {
+    switch (typeof value) {
+      case "string":
+      case "boolean":
+        return value
+      case "number": {
+        const special = specialNumber(value)
+        return special === undefined ? value : tagged("number", special)
+      }
+      case "bigint":
+        return tagged("bigint", value.toString())
+      case "undefined":
+        return tagged("undefined")
+      case "function":
+      case "symbol":
+        return null
+    }
+    if (value === null) return null
+    const object = value as object
+    if (isBytes(object)) return tagged("bytes", toBase64(object))
+    if (ancestors.has(object)) {
+      throw new TypeError(
+        "[ic-reactor] cannot dehydrate a query whose data is a cyclic structure"
+      )
+    }
+    ancestors.add(object)
+    try {
+      if (Array.isArray(object)) {
+        // An index loop, not `map`, so a hole comes back as `undefined`
+        // rather than as JSON's `null`.
+        const items: JsonValue[] = []
+        for (let i = 0; i < object.length; i += 1) {
+          const item: unknown = object[i]
+          items.push(isSkipped(item) ? null : encode(item))
+        }
+        return items
+      }
+      const toJSON = (object as { toJSON?: unknown }).toJSON
+      if (typeof toJSON === "function") {
+        return encode((toJSON as () => unknown).call(object))
+      }
+      const entries: { [key: string]: JsonValue } = {}
+      for (const key of Object.keys(object)) {
+        const item: unknown = (object as Record<string, unknown>)[key]
+        if (!isSkipped(item)) setOwn(entries, key, encode(item))
+      }
+      return hasOwn(object, TAG) ? tagged("object", entries) : entries
+    } finally {
+      ancestors.delete(object)
+    }
+  }
+
+  return encode(data)
+}
+
+const badTag = (detail: string): TypeError =>
+  new TypeError(
+    `[ic-reactor] cannot hydrate a query: ${detail}. Was it dehydrated by a client of another ic-reactor version?`
+  )
+
+/**
+ * Rewrites what {@link serializeData} produced, after a JSON round trip, back
+ * into the value it was made from.
+ *
+ * @throws TypeError on a tag it does not know, which means the data was not
+ * dehydrated by this serializer.
+ */
+export function deserializeData(data: unknown): unknown {
+  const decodeEntries = (object: object): Record<string, unknown> => {
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(object)) {
+      setOwn(out, key, decode((object as Record<string, unknown>)[key]))
+    }
+    return out
+  }
+
+  const decode = (value: unknown): unknown => {
+    if (typeof value !== "object" || value === null) return value
+    if (Array.isArray(value)) return value.map(decode)
+    if (!hasOwn(value, TAG)) return decodeEntries(value)
+    const { [TAG]: tag, v: payload } = value as Record<string, unknown>
+    switch (tag) {
+      case "bigint":
+        if (typeof payload === "string") return BigInt(payload)
+        break
+      case "bytes":
+        if (typeof payload === "string") return fromBase64(payload)
+        break
+      case "number":
+        if (typeof payload === "string" && hasOwn(SPECIAL_NUMBERS, payload)) {
+          return SPECIAL_NUMBERS[payload]
+        }
+        break
+      case "undefined":
+        return undefined
+      case "object":
+        if (typeof payload === "object" && payload !== null) {
+          return decodeEntries(payload)
+        }
+        break
+      default:
+        throw badTag(`unknown tag ${JSON.stringify(tag)}`)
+    }
+    throw badTag(`a malformed ${String(tag)} tag`)
+  }
+
+  return decode(data)
+}

package/packages/core/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * `@ic-reactor/core` 4: the thin layer over a `meant gen` module.
+ *
+ * The public surface is added slice by slice (milestone 1, #790): the error
+ * union, network resolution, units, the client and its canister builders.
+ *
+ * @packageDocumentation
+ */
+export type { Network } from "./network.js"
+export {
+  createClient,
+  type AuthLike,
+  type AuthState,
+  type Client,
+  type ClientOptions,
+} from "./client.js"
+export {
+  isReactorError,
+  type ReactorError,
+  type ReactorErrorKind,
+} from "./errors.js"
+export type { Canister, CanisterTarget } from "./types.js"
+export { formatUnits, parseUnits } from "./units.js"

package/packages/core/src/keys.ts

@@ -0,0 +1,108 @@
+/**
+ * Query keys (DECISIONS Q5):
+ *
+ *     ['ic-reactor', network, caller, canisterId, method, args, ('certified')]
+ *
+ * - `caller` is the principal the read is made as, so a key never holds
+ *   another principal's data, and a sign-in, a sign-out or a switch of account
+ *   moves every read to a new key.
+ * - `canisterId` is `"$unresolved:<name>"` for a `{ name }` target the
+ *   `ic_env` cookie does not resolve.
+ * - `args` is the hex of the Candid encoding of the arguments. The bytes depend
+ *   only on the values and the Candid types, never on how the schema was built
+ *   (a generated module and `schemaFromContract` agree), and never on the order
+ *   of a record's keys. Two tags take its place: `"$skip"` for `skipToken`, and
+ *   `"$invalid", <text>` for arguments that do not encode, so building the key
+ *   never throws. Hex never starts with `$`.
+ * - `"certified"` ends every full key of a certified canister, so an
+ *   uncertified answer is never served where a certified one was asked for. A
+ *   prefix without it matches both.
+ *
+ * Internal: not exported from the package entry.
+ *
+ * @module
+ */
+
+/** The first segment of every key ic-reactor builds. */
+export const KEY_ROOT = "ic-reactor"
+
+/** The trailing segment of a certified read's key. */
+export const CERTIFIED = "certified"
+
+/** The args segment of a skipped read. */
+export const SKIP = "$skip"
+
+/** The tag before the text of arguments that do not encode. */
+export const INVALID = "$invalid"
+
+/** The canisterId segment of a `{ name }` target that did not resolve. */
+export const unresolvedSlot = (name: string): string => `$unresolved:${name}`
+
+/** Lower-case hex of `bytes`. */
+export const toHex = (bytes: Uint8Array): string => {
+  let out = ""
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0")
+  return out
+}
+
+/** How deep {@link stableText} walks before it writes `…`. */
+const TEXT_DEPTH = 32
+
+/**
+ * A deterministic text for any value, for the key of arguments that do not
+ * encode: the same value gives the same text, different values almost always
+ * different text, and nothing throws. Object keys are sorted, `bigint` ends in
+ * `n`, bytes are written as hex, and cycles, getters that throw and very deep
+ * values are written as markers rather than followed.
+ */
+export function stableText(value: unknown): string {
+  const seen = new Set<object>()
+  const write = (item: unknown, depth: number): string => {
+    switch (typeof item) {
+      case "string":
+        return JSON.stringify(item)
+      case "bigint":
+        return `${item}n`
+      case "number":
+        return Object.is(item, -0) ? "-0" : String(item)
+      case "boolean":
+        return String(item)
+      case "undefined":
+        return "undefined"
+      case "symbol":
+        return item.toString()
+      case "function":
+        return "function"
+    }
+    if (item === null) return "null"
+    const object = item as object
+    if (depth >= TEXT_DEPTH) return "…"
+    if (seen.has(object)) return "[circular]"
+    if (Object.prototype.toString.call(object) === "[object Uint8Array]") {
+      return `0x${toHex(object as Uint8Array)}`
+    }
+    seen.add(object)
+    try {
+      if (Array.isArray(object)) {
+        return `[${object.map((entry) => write(entry, depth + 1)).join(",")}]`
+      }
+      const keys = Object.keys(object).sort()
+      return `{${keys
+        .map((key) => {
+          let entry: unknown
+          try {
+            entry = (object as Record<string, unknown>)[key]
+          } catch {
+            return `${JSON.stringify(key)}:[unreadable]`
+          }
+          return `${JSON.stringify(key)}:${write(entry, depth + 1)}`
+        })
+        .join(",")}}`
+    } catch {
+      return "[unreadable]"
+    } finally {
+      seen.delete(object)
+    }
+  }
+  return write(value, 0)
+}

package/packages/core/src/management.ts

@@ -0,0 +1,138 @@
+/**
+ * The effective canister id of a call to the management canister (`aaaaa-aa`).
+ *
+ * A request is routed by its *effective* canister id: the subnet that holds it
+ * takes the request. For an ordinary canister that is the canister itself. The
+ * management canister lives on every subnet, so a call to it has to name the
+ * canister it is about. The IC interface specification, section "Effective
+ * canister id" (`#http-effective-canister-id`, dfinity/portal
+ * `docs/references/ic-interface-spec.md` at fe646b2), says:
+ *
+ * > If the request is an update call to the Management Canister (`aaaaa-aa`):
+ * > if the call is to the `create_canister` or
+ * > `provisional_create_canister_with_cycles` method, then any principal can be
+ * > used as the effective canister id for this call. If the call is to the
+ * > `install_chunked_code` method and the `arg` is a Candid-encoded record with
+ * > a `target_canister` field of type `principal`, then the effective canister
+ * > id must be that principal. Otherwise, if the `arg` is a Candid-encoded
+ * > record with a `canister_id` field of type `principal`, then the effective
+ * > canister id must be that principal. Otherwise, the call is rejected by the
+ * > system independently of the effective canister id.
+ *
+ * and the same for a query call, with `list_canisters` as the method that
+ * takes any principal. It adds that "the effective canister id of a request
+ * submitted to a node must be a canister id from the canister ranges of the
+ * subnet to which the node belongs": "any principal" is any principal *of the
+ * right subnet*, which a client cannot know.
+ *
+ * So the client routes by an explicit table, one row per method, and refuses
+ * before sending (`invalid_args`, code `"effective_canister_id_unknown"`) every
+ * call it has no row for, and every call whose row names a field the arguments
+ * leave empty:
+ *
+ * - `canister_id`: the methods an external caller can send whose argument is a
+ *   record with a `canister_id : principal` field.
+ * - `target_canister`: `install_chunked_code`.
+ * - `specified_id`: `provisional_create_canister_with_cycles` (development
+ *   instances only; mainnet rejects it). It is routed to the canister it asks
+ *   for, which is the subnet that will hold it. Without `specified_id` the
+ *   spec allows any principal of a subnet the client cannot name, so it is
+ *   refused: pass `specified_id`.
+ *
+ * Left out: the methods the spec says "can only be called by canisters"
+ * (`canister_info`, `canister_metadata`, `deposit_cycles`, `raw_rand`, the
+ * threshold-signature, `http_request`, bitcoin, `node_metrics_history` and
+ * `subnet_info` methods), whose ingress calls the system rejects whatever the
+ * routing, and the subnet-admin methods `create_canister` and `list_canisters`,
+ * which take "any principal" and so have nothing to route by.
+ *
+ * Internal: not exported from the package entry.
+ *
+ * @module
+ */
+
+/** The management canister's id. */
+export const MANAGEMENT_CANISTER = "aaaaa-aa"
+
+/** Which field of the call's one argument names the effective canister. */
+export type EffectiveIdField =
+  "canister_id" | "target_canister" | "specified_id"
+
+/**
+ * The routing table, method by method, as of the management canister
+ * interface (`ic.did`) in dfinity/portal at fe646b2.
+ */
+export const EFFECTIVE_ID_FIELD: Readonly<Record<string, EffectiveIdField>> =
+  Object.freeze({
+    canister_metrics: "canister_id",
+    canister_status: "canister_id",
+    clear_chunk_store: "canister_id",
+    delete_canister: "canister_id",
+    delete_canister_snapshot: "canister_id",
+    fetch_canister_logs: "canister_id",
+    install_code: "canister_id",
+    list_canister_snapshots: "canister_id",
+    load_canister_snapshot: "canister_id",
+    provisional_top_up_canister: "canister_id",
+    read_canister_snapshot_data: "canister_id",
+    read_canister_snapshot_metadata: "canister_id",
+    start_canister: "canister_id",
+    stop_canister: "canister_id",
+    stored_chunks: "canister_id",
+    take_canister_snapshot: "canister_id",
+    uninstall_code: "canister_id",
+    update_settings: "canister_id",
+    upload_canister_snapshot_data: "canister_id",
+    upload_canister_snapshot_metadata: "canister_id",
+    upload_chunk: "canister_id",
+    install_chunked_code: "target_canister",
+    provisional_create_canister_with_cycles: "specified_id",
+  })
+
+/** The effective canister id of a management call, or why there is none. */
+export type EffectiveId =
+  | { readonly ok: true; readonly id: string }
+  | { readonly ok: false; readonly reason: string }
+
+const own = (object: object, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(object, key)
+
+/**
+ * Whether `method` of the management canister has a row in the table. Asked
+ * before the arguments are encoded, so a method the client cannot route is
+ * refused for what it is, whatever its arguments.
+ */
+export const isRoutable = (method: string): boolean =>
+  own(EFFECTIVE_ID_FIELD, method)
+
+/**
+ * The effective canister id of a call to `method` of `aaaaa-aa` with
+ * `values`, its arguments as given (already checked against the schema).
+ */
+export function effectiveCanisterId(
+  method: string,
+  values: readonly unknown[]
+): EffectiveId {
+  if (!isRoutable(method)) {
+    return {
+      ok: false,
+      reason:
+        `the management canister method ${method} has no effective canister id the client can choose: ` +
+        `it is either callable only by canisters, or routed by a principal of a subnet the client cannot name`,
+    }
+  }
+  const field = EFFECTIVE_ID_FIELD[method]
+  const [arg] = values
+  const value =
+    typeof arg === "object" && arg !== null && own(arg, field)
+      ? (arg as Record<string, unknown>)[field]
+      : undefined
+  if (typeof value === "string" && value !== "") return { ok: true, id: value }
+  return {
+    ok: false,
+    reason:
+      field === "specified_id"
+        ? `${method} without specified_id can be routed to any subnet the client cannot name; pass specified_id`
+        : `${method} is routed by the ${field} field of its argument, and the argument has none`,
+  }
+}