@ckb-ccc/libp2p 0.0.2

package/src/jsonRpcService.ts

@@ -0,0 +1,167 @@
+import { ccc, JsonRpcError } from "@ckb-ccc/core";
+import type { Connection, PeerId, Stream } from "@libp2p/interface";
+import type { Registrar } from "@libp2p/interface-internal";
+import { lpStream } from "@libp2p/utils";
+
+const DEFAULT_MAX_MESSAGE_LENGTH = 1024 * 1024;
+
+export type JsonRpcServiceComponents = {
+  registrar: Registrar;
+};
+
+export type JsonRpcServiceConfig = {
+  protocol: string;
+  maxMessageLength?: number;
+};
+
+export type JsonRpcRequest = {
+  peerId: PeerId;
+  payload: ccc.JsonRpcPayload;
+};
+
+export type JsonRpcRequestHandler<
+  Components extends JsonRpcServiceComponents = JsonRpcServiceComponents,
+> = (this: JsonRpcService<Components>, request: JsonRpcRequest) => unknown;
+
+export abstract class JsonRpcService<
+  Components extends JsonRpcServiceComponents = JsonRpcServiceComponents,
+> {
+  private readonly errorListeners = new Set<(error: Error) => void>();
+  readonly maxMessageLength: number;
+
+  constructor(
+    readonly components: Components,
+    readonly config: JsonRpcServiceConfig,
+  ) {
+    const maxMessageLength =
+      config.maxMessageLength ?? DEFAULT_MAX_MESSAGE_LENGTH;
+    if (!Number.isSafeInteger(maxMessageLength) || maxMessageLength <= 0) {
+      throw new Error(
+        "Maximum JSON-RPC message length must be a positive integer",
+      );
+    }
+
+    this.maxMessageLength = maxMessageLength;
+  }
+
+  protected abstract handleRequest(request: JsonRpcRequest): unknown;
+
+  onError(listener: (error: Error) => void) {
+    this.errorListeners.add(listener);
+    return () => this.errorListeners.delete(listener);
+  }
+
+  async start() {
+    await this.components.registrar.handle(
+      this.config.protocol,
+      this.handleProtocol.bind(this),
+      { runOnLimitedConnection: true },
+    );
+  }
+
+  async stop() {
+    await this.components.registrar.unhandle(this.config.protocol);
+  }
+
+  private async handleProtocol(stream: Stream, connection: Connection) {
+    let requestAborted = false;
+
+    try {
+      const rpcStream = lpStream(stream, {
+        maxDataLength: this.maxMessageLength,
+      });
+      const payload = parseJsonRpcRequest(
+        ccc.bytesTo((await rpcStream.read()).subarray(), "utf8"),
+      );
+
+      let response: ccc.JsonRpcResponse;
+      try {
+        response = {
+          jsonrpc: "2.0",
+          id: payload.id,
+          result: await this.handleRequest({
+            peerId: connection.remotePeer,
+            payload,
+          }),
+        };
+      } catch (cause) {
+        requestAborted = isAbortError(cause);
+        const error = toJsonRpcError(cause);
+        response = {
+          jsonrpc: "2.0",
+          id: payload.id,
+          error: {
+            code: error.code,
+            message: error.message,
+            data: error.data,
+          },
+        };
+      }
+
+      await rpcStream.write(ccc.bytesFrom(JSON.stringify(response), "utf8"));
+      await stream.close();
+    } catch (cause) {
+      if (requestAborted) {
+        return;
+      }
+      this.handleError(cause, stream);
+    }
+  }
+
+  private handleError(cause: unknown, stream?: Stream) {
+    const error = asJsonRpcError(cause);
+
+    stream?.abort(error);
+    this.errorListeners.forEach((listener) => listener(error));
+    return error;
+  }
+}
+
+function toJsonRpcError(cause: unknown) {
+  if (cause instanceof JsonRpcError) {
+    return cause;
+  }
+
+  return new JsonRpcError({
+    code: -32603,
+    message: asJsonRpcError(cause).message,
+  });
+}
+
+function parseJsonRpcRequest(data: string) {
+  const payload = JSON.parse(data) as Partial<ccc.JsonRpcPayload>;
+  if (
+    payload?.jsonrpc !== "2.0" ||
+    (typeof payload.id !== "number" && typeof payload.id !== "string") ||
+    typeof payload.method !== "string"
+  ) {
+    throw new Error("Invalid JSON-RPC request");
+  }
+
+  return payload as ccc.JsonRpcPayload;
+}
+
+function asJsonRpcError(cause: unknown) {
+  return cause instanceof Error ? cause : new Error("JSON-RPC request failed");
+}
+
+function isAbortError(cause: unknown) {
+  return (
+    cause instanceof Error &&
+    (cause.name === "AbortError" || cause.name === "TimeoutError")
+  );
+}
+
+export function jsonRpcService<
+  Components extends JsonRpcServiceComponents = JsonRpcServiceComponents,
+>(
+  config: JsonRpcServiceConfig,
+  handler: JsonRpcRequestHandler<Components>,
+): (components: Components) => JsonRpcService<Components> {
+  return (components: Components) =>
+    new (class extends JsonRpcService<Components> {
+      protected handleRequest(request: JsonRpcRequest) {
+        return handler.call(this, request);
+      }
+    })(components, config);
+}

package/src/jsonRpcTransport.ts

@@ -0,0 +1,85 @@
+import { ccc } from "@ckb-ccc/core";
+import type { Libp2p, PeerId, Stream } from "@libp2p/interface";
+import { lpStream } from "@libp2p/utils";
+
+const DEFAULT_MAX_MESSAGE_LENGTH = 1024 * 1024;
+const DEFAULT_TIMEOUT = 120_000;
+
+export type JsonRpcTransportLibp2pConfig = {
+  protocol: string;
+  maxMessageLength?: number;
+  timeout?: number;
+  signal?: AbortSignal;
+  onResponse?: (response: ccc.JsonRpcResponse) => void;
+};
+
+export class JsonRpcTransportLibp2p implements ccc.JsonRpcTransport {
+  private readonly maxMessageLength: number;
+  private readonly timeout: number;
+
+  constructor(
+    private readonly node: Libp2p,
+    readonly peerId: PeerId,
+    private readonly config: JsonRpcTransportLibp2pConfig,
+  ) {
+    const maxMessageLength =
+      config.maxMessageLength ?? DEFAULT_MAX_MESSAGE_LENGTH;
+    if (!Number.isSafeInteger(maxMessageLength) || maxMessageLength <= 0) {
+      throw new Error(
+        "Maximum JSON-RPC message length must be a positive integer",
+      );
+    }
+
+    this.maxMessageLength = maxMessageLength;
+
+    const timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    if (!Number.isSafeInteger(timeout) || timeout <= 0) {
+      throw new Error("JSON-RPC request timeout must be a positive integer");
+    }
+
+    this.timeout = timeout;
+  }
+
+  async request(payload: ccc.JsonRpcPayload): Promise<ccc.JsonRpcResponse> {
+    const timeoutSignal = AbortSignal.timeout(this.timeout);
+    const signal = this.config.signal
+      ? ccc.abortSignalAny([this.config.signal, timeoutSignal])
+      : timeoutSignal;
+
+    let stream: Stream | undefined;
+    let response: ccc.JsonRpcResponse;
+    try {
+      // dialProtocol handles the signal, so no separate entry check is needed.
+      stream = await this.node.dialProtocol(this.peerId, this.config.protocol, {
+        runOnLimitedConnection: true,
+        signal,
+      });
+
+      const rpcStream = lpStream(stream, {
+        maxDataLength: this.maxMessageLength,
+      });
+
+      await rpcStream.write(ccc.bytesFrom(JSON.stringify(payload), "utf8"), {
+        signal,
+      });
+      await stream.close({ signal });
+
+      response = JSON.parse(
+        ccc.bytesTo((await rpcStream.read({ signal })).subarray(), "utf8"),
+      ) as ccc.JsonRpcResponse;
+      await stream.closeRead({ signal });
+      signal.throwIfAborted();
+    } catch (cause) {
+      const error = asJsonRpcError(cause);
+      stream?.abort(error);
+      throw error;
+    }
+
+    this.config.onResponse?.(response);
+    return response;
+  }
+}
+
+function asJsonRpcError(cause: unknown) {
+  return cause instanceof Error ? cause : new Error("JSON-RPC request failed");
+}

package/src/pairingEndpoint.ts

@@ -0,0 +1,181 @@
+import { ccc } from "@ckb-ccc/core";
+import { multiaddr, type Multiaddr } from "@multiformats/multiaddr";
+import * as lp from "it-length-prefixed";
+import type { PairingTarget } from "./pairingService.js";
+
+const MAX_DECOMPRESSED_ADDRESSES_LENGTH = 16 * 1024;
+const MAX_ADDRESSES = 16;
+const PAIRING_PARAMETER_NAMES = ["addresses", "role", "secret"] as const;
+
+export class PairingEndpointRoleError extends Error {
+  constructor(
+    readonly expectedRole: string,
+    readonly actualRole: string | undefined,
+  ) {
+    super(
+      `Expected a ${expectedRole} pairing endpoint, received ${actualRole ? `role "${actualRole}"` : "an endpoint without a role"}`,
+    );
+    this.name = "PairingEndpointRoleError";
+  }
+}
+
+export async function encodePairingEndpoint(
+  endpointUrl: string,
+  addresses: readonly Multiaddr[],
+  secret: string,
+  role?: string,
+) {
+  if (addresses.length === 0) {
+    throw new Error("Pairing endpoint requires at least one address");
+  }
+  if (addresses.length > MAX_ADDRESSES) {
+    throw new Error(
+      `Pairing endpoint supports at most ${MAX_ADDRESSES} addresses`,
+    );
+  }
+
+  const addressBytes = encodeAddresses(addresses);
+  if (addressBytes.byteLength > MAX_DECOMPRESSED_ADDRESSES_LENGTH) {
+    throw new Error("Pairing endpoint address data is too large");
+  }
+
+  const compressedAddressBytes = await transformBytes(
+    addressBytes,
+    new CompressionStream("deflate"),
+  );
+
+  const encodedAddresses = ccc.bytesTo(compressedAddressBytes, "base64url");
+
+  const url = new URL(endpointUrl);
+  const { params, route } = fragmentParameters(url);
+
+  PAIRING_PARAMETER_NAMES.forEach((name) => {
+    params.delete(name);
+  });
+  if (role) {
+    params.set("role", role);
+  }
+  params.set("addresses", encodedAddresses);
+  params.set("secret", secret);
+  url.hash = `${route}?${params.toString()}`;
+
+  return url.toString();
+}
+
+export async function decodePairingEndpoint(
+  endpoint: string,
+  expectedRole?: string,
+): Promise<PairingTarget> {
+  const url = new URL(endpoint.trim());
+  const { params } = fragmentParameters(url);
+  if (expectedRole) {
+    const actualRole = params.get("role")?.trim() || undefined;
+    if (actualRole !== expectedRole) {
+      throw new PairingEndpointRoleError(expectedRole, actualRole);
+    }
+  }
+  const compressedAddresses = params.get("addresses")?.trim();
+  const secret = params.get("secret")?.trim();
+
+  if (!compressedAddresses || !secret) {
+    throw new Error("Pairing endpoint is incomplete");
+  }
+
+  const addresses = await decodeCompressedAddresses(compressedAddresses);
+
+  return { addresses, secret };
+}
+
+function fragmentParameters(url: URL) {
+  const fragment = url.hash.slice(1);
+  const separator = fragment.indexOf("?");
+  if (separator === -1) {
+    return { params: new URLSearchParams(), route: fragment };
+  }
+
+  return {
+    params: new URLSearchParams(fragment.slice(separator + 1)),
+    route: fragment.slice(0, separator),
+  };
+}
+
+function encodeAddresses(addresses: readonly Multiaddr[]): Uint8Array {
+  return ccc.bytesConcat(
+    ...lp.encode(addresses.map((address) => address.bytes)),
+  );
+}
+
+async function decodeCompressedAddresses(value: string): Promise<Multiaddr[]> {
+  try {
+    const compressedBytes = ccc.bytesFrom(value, "base64url");
+    const bytes = await transformBytes(
+      compressedBytes,
+      new DecompressionStream("deflate"),
+      MAX_DECOMPRESSED_ADDRESSES_LENGTH,
+    );
+    const addresses: Multiaddr[] = [];
+    for (const address of lp.decode([bytes], {
+      maxDataLength: MAX_DECOMPRESSED_ADDRESSES_LENGTH,
+    })) {
+      if (addresses.length >= MAX_ADDRESSES) {
+        throw new Error("Too many addresses");
+      }
+      addresses.push(multiaddr(address.subarray()));
+    }
+
+    if (addresses.length === 0) {
+      throw new Error("Missing addresses");
+    }
+    return addresses;
+  } catch (cause) {
+    throw new Error("Pairing endpoint contains invalid compressed addresses", {
+      cause,
+    });
+  }
+}
+
+async function transformBytes(
+  bytes: Uint8Array,
+  transform: CompressionStream | DecompressionStream,
+  maxOutputLength?: number,
+) {
+  const readable =
+    maxOutputLength === undefined
+      ? transform.readable
+      : transform.readable.pipeThrough(limitBytes(maxOutputLength));
+  const output = new Response(readable).arrayBuffer().then(
+    (buffer) => ({ buffer, ok: true }) as const,
+    (error: unknown) => ({ error, ok: false }) as const,
+  );
+  const writer = transform.writable.getWriter();
+  try {
+    await writer.write(Uint8Array.from(bytes));
+    await writer.close();
+  } catch (cause) {
+    const result = await output;
+    if (!result.ok) {
+      throw result.error;
+    }
+    throw cause;
+  }
+
+  const result = await output;
+  if (!result.ok) {
+    throw result.error;
+  }
+  return new Uint8Array(result.buffer);
+}
+
+function limitBytes(maxLength: number) {
+  let length = 0;
+
+  return new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      if (chunk.byteLength > maxLength - length) {
+        throw new Error("Decompressed address data is too large");
+      }
+      length += chunk.byteLength;
+      controller.enqueue(chunk);
+    },
+  });
+}