@ckb-ccc/core 1.19.1 → 1.20.0

package/src/client/jsonRpc/client.ts

@@ -10,8 +10,8 @@ import {
   RequestorJsonRpcConfig,
 } from "../../jsonRpc/requestor.js";
 import { Num, NumLike, numFrom, numToHex } from "../../num/index.js";
-import { apply } from "../../utils/index.js";
-import { ClientCache } from "../cache/index.js";
+import { Owner, apply } from "../../utils/index.js";
+import type { ClientConfig } from "../client.js";
 import { Client } from "../client.js";
 import { DEFAULT_MIN_FEE_RATE } from "../clientTypes.advanced.js";
 import {
@@ -68,10 +68,35 @@ const ERROR_PARSERS: [
   ],
 ];
 
-export type ClientJsonRpcConfig = RequestorJsonRpcConfig & {
-  cache?: ClientCache;
-  requestor?: RequestorJsonRpc;
-};
+function handleJsonRpcError(errAny: unknown): never {
+  if (
+    typeof errAny !== "object" ||
+    errAny === null ||
+    !("data" in errAny) ||
+    typeof errAny.data !== "string"
+  ) {
+    throw errAny;
+  }
+  const err = errAny as ErrorClientBaseLike;
+
+  for (const [regexp, builder] of ERROR_PARSERS) {
+    const match = err.data.match(regexp);
+    if (match) {
+      throw builder(err, match);
+    }
+  }
+
+  throw new ErrorClientBase(err);
+}
+
+export type ClientJsonRpcConfig = RequestorJsonRpcConfig &
+  ClientConfig & {
+    /**
+     * @deprecated Requestor injection is supported only by legacy constructors.
+     * Use a borrowed Transport with `Client.new` or let `Client.open` create one.
+     */
+    requestor?: RequestorJsonRpc;
+  };
 
 /**
  * An abstract class implementing JSON-RPC client functionality for a specific URL and timeout.
@@ -85,42 +110,64 @@ export abstract class ClientJsonRpc extends Client {
    *
    * @param url_ - The URL of the JSON-RPC server.
    * @param timeout - The timeout for requests in milliseconds
+   * @deprecated Use the concrete Client's `new` or `open` method.
    */
 
-  constructor(url_: string, config?: ClientJsonRpcConfig) {
+  constructor(
+    private readonly url_: string,
+    config?: ClientJsonRpcConfig,
+  ) {
     super(config);
 
-    this.requestor =
-      config?.requestor ??
-      new RequestorJsonRpc(url_, config, (errAny) => {
-        if (
-          typeof errAny !== "object" ||
-          errAny === null ||
-          !("data" in errAny) ||
-          typeof errAny.data !== "string"
-        ) {
-          throw errAny;
-        }
-        const err = errAny as ErrorClientBaseLike;
-
-        for (const [regexp, builder] of ERROR_PARSERS) {
-          const match = err.data.match(regexp);
-          if (match) {
-            throw builder(err, match);
-          }
-        }
-
-        throw new ErrorClientBase(err);
+    const requestor = config?.requestor;
+    if (requestor) {
+      this.requestor = requestor;
+    } else if (config?.transport) {
+      this.requestor = RequestorJsonRpc.new({
+        transport: config.transport,
+        maxConcurrent: config.maxConcurrent,
+        onError: handleJsonRpcError,
       });
+    } else {
+      // Legacy constructor intentionally discards ownership.
+      this.requestor = RequestorJsonRpc.open({
+        urls: [url_, ...(config?.fallbacks ?? [])],
+        timeout: config?.timeout,
+        maxConcurrent: config?.maxConcurrent,
+        onError: handleJsonRpcError,
+      }).value;
+    }
+  }
+
+  /** Creates a Requestor that borrows an existing Transport. */
+  protected static newRequestor(
+    config: Omit<Parameters<typeof RequestorJsonRpc.new>[0], "onError">,
+  ): RequestorJsonRpc {
+    return RequestorJsonRpc.new({
+      ...config,
+      onError: handleJsonRpcError,
+    });
+  }
+
+  /** Opens a Requestor with ownership of its default Transport. */
+  protected static openRequestor(
+    config: Omit<Parameters<typeof RequestorJsonRpc.open>[0], "onError">,
+  ): Owner<RequestorJsonRpc> {
+    return RequestorJsonRpc.open({
+      ...config,
+      onError: handleJsonRpcError,
+    });
   }
 
   /**
-   * Returns the URL of the JSON-RPC server.
+   * Returns the legacy primary URL of the JSON-RPC server.
    *
    * @returns The URL of the JSON-RPC server.
+   * @deprecated A Client may use multiple endpoints or a Transport without a
+   * URL, so this value does not reliably identify its connection.
    */
   get url(): string {
-    return this.requestor.url;
+    return this.url_;
   }
 
   /**

package/src/client/jsonRpc/transformers.ts

@@ -212,10 +212,10 @@ export class JsonRpcTransformers {
     return {
       compactTarget: numFrom(header.compact_target),
       dao: {
-        c: numLeFromBytes(dao.slice(0, 8)),
-        ar: numLeFromBytes(dao.slice(8, 16)),
-        s: numLeFromBytes(dao.slice(16, 24)),
-        u: numLeFromBytes(dao.slice(24, 32)),
+        c: numLeFromBytes(dao.subarray(0, 8)),
+        ar: numLeFromBytes(dao.subarray(8, 16)),
+        s: numLeFromBytes(dao.subarray(16, 24)),
+        u: numLeFromBytes(dao.subarray(24, 32)),
       },
       epoch: Epoch.fromNum(header.epoch),
       extraHash: header.extra_hash,

package/src/jsonRpc/index.ts

@@ -1 +1,2 @@
 export * from "./requestor.js";
+export * from "./transports/index.js";

package/src/jsonRpc/requestor.ts

@@ -1,9 +1,24 @@
+import { OwnerAggregated } from "../utils/owner/aggregated.js";
+import { Owner } from "../utils/owner/owner.js";
+import { jsonRpcTransportFromUri } from "./transports/factory.js";
+import { JsonRpcTransportFallback } from "./transports/fallback.js";
 import {
   JsonRpcPayload,
-  Transport,
-  TransportFallback,
-  transportFromUri,
-} from "./transports/advanced.js";
+  JsonRpcResponse,
+  JsonRpcTransport,
+} from "./transports/index.js";
+
+function openTransports(
+  urls: readonly [string, ...string[]],
+  config?: { timeout?: number },
+): Owner<JsonRpcTransportFallback> {
+  const transportOwners = Array.from(new Set(urls), (url) =>
+    jsonRpcTransportFromUri(url, config),
+  );
+  return OwnerAggregated.from(transportOwners).map(
+    (transports) => new JsonRpcTransportFallback([...transports]),
+  );
+}
 
 /**
  * Applies a transformation function to a value if the transformer is provided.
@@ -25,11 +40,15 @@ function transform(value: unknown, transformer?: (i: unknown) => unknown) {
   return value;
 }
 
+/**
+ * @deprecated Used only by the legacy positional constructor. Use the static
+ * {@link RequestorJsonRpc.new} or {@link RequestorJsonRpc.open} methods.
+ */
 export type RequestorJsonRpcConfig = {
   fallbacks?: string[];
   timeout?: number;
   maxConcurrent?: number;
-  transport?: Transport;
+  transport?: JsonRpcTransport;
 };
 
 export class RequestorJsonRpc {
@@ -37,15 +56,17 @@ export class RequestorJsonRpc {
   private concurrent = 0;
   private readonly pending: (() => void)[] = [];
 
-  public readonly transport: Transport;
+  public readonly transport: JsonRpcTransport;
 
   private id = 0;
 
   /**
-   * Creates an instance of ClientJsonRpc.
+   * Creates a Requestor using legacy positional arguments.
    *
    * @param url_ - The URL of the JSON-RPC server.
    * @param timeout - The timeout for requests in milliseconds
+   * @deprecated Use {@link RequestorJsonRpc.new} with a borrowed Transport or
+   * {@link RequestorJsonRpc.open} when creating Transports.
    */
   constructor(
     private readonly url_: string,
@@ -53,20 +74,56 @@ export class RequestorJsonRpc {
     private readonly onError?: (err: unknown) => Promise<void> | void,
   ) {
     this.maxConcurrent = config?.maxConcurrent;
-    this.transport =
-      config?.transport ??
-      new TransportFallback(
-        Array.from(
-          new Set([url_, ...(config?.fallbacks ?? [])]).values(),
-          (url) => transportFromUri(url, config),
-        ),
-      );
+    if (config?.transport) {
+      this.transport = config.transport;
+    } else {
+      this.transport = openTransports(
+        [url_, ...(config?.fallbacks ?? [])],
+        config,
+      ).value;
+    }
+  }
+
+  /** Creates a Requestor that borrows an existing Transport. */
+  static new({
+    transport,
+    maxConcurrent,
+    onError,
+  }: {
+    transport: JsonRpcTransport;
+    maxConcurrent?: number;
+    onError?: (err: unknown) => Promise<void> | void;
+  }): RequestorJsonRpc {
+    return new RequestorJsonRpc("", { transport, maxConcurrent }, onError);
+  }
+
+  /** Opens a Requestor with ownership of its default transports. */
+  static open({
+    urls: [url, ...fallbacks],
+    onError,
+    ...config
+  }: {
+    urls: readonly [string, ...string[]];
+    timeout?: number;
+    maxConcurrent?: number;
+    onError?: (err: unknown) => Promise<void> | void;
+  }): Owner<RequestorJsonRpc> {
+    const transportOwner = openTransports([url, ...fallbacks], config);
+    return transportOwner.map((transport) =>
+      RequestorJsonRpc.new({
+        transport,
+        ...config,
+        onError,
+      }),
+    );
   }
 
   /**
    * Returns the URL of the JSON-RPC server.
    *
    * @returns The URL of the JSON-RPC server.
+   * @deprecated URL belongs to Transport construction and is unavailable for
+   * Requestors created with {@link RequestorJsonRpc.new}.
    */
 
   get url(): string {
@@ -129,7 +186,7 @@ export class RequestorJsonRpc {
       await pending;
     }
 
-    const res = (await (async () => {
+    const res: JsonRpcResponse = await (async () => {
       this.concurrent += 1;
       try {
         return await this.transport.request(payload);
@@ -137,11 +194,7 @@ export class RequestorJsonRpc {
         this.concurrent -= 1;
         this.pending.shift()?.();
       }
-    })()) as {
-      id: number;
-      error: unknown;
-      result: unknown;
-    };
+    })();
 
     if (res.id !== payload.id) {
       throw new Error(`Id mismatched, got ${res.id}, expected ${payload.id}`);

package/src/jsonRpc/transports/advanced.ts

@@ -1,5 +1 @@
 export * from "./factory.js";
-export * from "./fallback.js";
-export * from "./http.js";
-export * from "./transport.js";
-export * from "./webSocket.js";

package/src/jsonRpc/transports/factory.ts

@@ -1,10 +1,17 @@
-import { TransportHttp } from "./http.js";
-import { TransportWebSocket } from "./webSocket.js";
+import { OwnerUnique } from "../../utils/owner/unique.js";
+import { JsonRpcTransportHttp } from "./http.js";
+import { JsonRpcTransportWebSocket } from "./webSocket.js";
 
-export function transportFromUri(uri: string, config?: { timeout?: number }) {
+export function jsonRpcTransportFromUri(
+  uri: string,
+  config?: { timeout?: number },
+) {
   if (uri.startsWith("wss://") || uri.startsWith("ws://")) {
-    return new TransportWebSocket(uri, config?.timeout);
+    return JsonRpcTransportWebSocket.open(uri, config?.timeout);
   }
 
-  return new TransportHttp(uri, config?.timeout);
+  return new OwnerUnique(
+    new JsonRpcTransportHttp(uri, config?.timeout),
+    () => {},
+  );
 }

package/src/jsonRpc/transports/fallback.ts

@@ -1,15 +1,19 @@
-import { JsonRpcPayload, Transport } from "./transport.js";
+import {
+  JsonRpcPayload,
+  JsonRpcResponse,
+  JsonRpcTransport,
+} from "./transport.js";
 
-export class TransportFallback implements Transport {
+export class JsonRpcTransportFallback implements JsonRpcTransport {
   // Current transport index
   private i = 0;
 
-  constructor(private readonly transports: Transport[]) {}
+  constructor(private readonly transports: JsonRpcTransport[]) {}
 
-  async request(data: JsonRpcPayload): Promise<unknown> {
+  async request(data: JsonRpcPayload): Promise<JsonRpcResponse> {
     const startI = this.i;
     let lastErr: unknown = new Error(
-      "TransportFallback requires at least one transport",
+      "JsonRpcTransportFallback requires at least one transport",
     );
 
     for (let tried = 0; tried < this.transports.length; tried += 1) {

package/src/jsonRpc/transports/http.ts

@@ -1,28 +1,32 @@
-import { JsonRpcPayload, Transport } from "./transport.js";
+import {
+  JsonRpcPayload,
+  JsonRpcResponse,
+  JsonRpcTransport,
+} from "./transport.js";
 
-export class TransportHttp implements Transport {
+export class JsonRpcTransportHttp implements JsonRpcTransport {
   constructor(
     private readonly url: string,
     private readonly timeout = 30000,
   ) {}
 
-  async request(payload: JsonRpcPayload) {
+  async request(payload: JsonRpcPayload): Promise<JsonRpcResponse> {
     const aborter = new AbortController();
     const abortTimer = setTimeout(() => aborter.abort(), this.timeout);
 
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-    const raw = await (
-      await fetch(this.url, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-        },
-        body: JSON.stringify(payload),
-        signal: aborter.signal,
-      })
-    ).json();
-    clearTimeout(abortTimer);
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-    return raw;
+    try {
+      return (await (
+        await fetch(this.url, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+          },
+          body: JSON.stringify(payload),
+          signal: aborter.signal,
+        })
+      ).json()) as JsonRpcResponse;
+    } finally {
+      clearTimeout(abortTimer);
+    }
   }
 }

package/src/jsonRpc/transports/index.ts

@@ -0,0 +1,4 @@
+export * from "./fallback.js";
+export * from "./http.js";
+export * from "./transport.js";
+export * from "./webSocket.js";

package/src/jsonRpc/transports/transport.ts

@@ -1,18 +1,44 @@
+export type JsonRpcId = string | number;
+
 export type JsonRpcPayload = {
-  id: number;
+  id: JsonRpcId;
   jsonrpc: "2.0";
   method: string;
   params: unknown[] | Record<string, unknown>;
 };
 
-export interface Transport {
+export type JsonRpcErrorLike<Data = unknown> = {
+  code: number;
+  message: string;
+  data?: Data;
+};
+
+export class JsonRpcError<Data = unknown> extends Error {
+  readonly code: number;
+  readonly data?: Data;
+
+  constructor(error: JsonRpcErrorLike<Data>) {
+    super(error.message);
+    this.name = "JsonRpcError";
+    this.code = error.code;
+    this.data = error.data;
+  }
+}
+
+export type JsonRpcResponse<Result = unknown, ErrorData = unknown> = {
+  id: JsonRpcId;
+  jsonrpc: "2.0";
+} & (
+  | { result: Result; error?: never }
+  | { result?: never; error: JsonRpcErrorLike<ErrorData> }
+);
+
+export interface JsonRpcTransport {
   /**
    * Sends a JSON-RPC request to the server.
    *
    * @param payload - The JSON-RPC payload to send.
-   * @returns The result of the JSON-RPC request.
-   *
-   * @throws Will throw an error if the response ID does not match the request ID, or if the response contains an error.
+   * @returns The JSON-RPC response.
    */
-  request(data: JsonRpcPayload): Promise<unknown>;
+  request(payload: JsonRpcPayload): Promise<JsonRpcResponse>;
 }

package/src/jsonRpc/transports/webSocket.ts

@@ -1,46 +1,76 @@
 import WebSocket from "isomorphic-ws";
-import { JsonRpcPayload, Transport } from "./transport.js";
+import { OwnerUnique } from "../../utils/owner/unique.js";
+import {
+  JsonRpcId,
+  JsonRpcPayload,
+  JsonRpcResponse,
+  JsonRpcTransport,
+} from "./transport.js";
 
-export class TransportWebSocket implements Transport {
+export class JsonRpcTransportWebSocket implements JsonRpcTransport {
   private ongoing: Map<
-    number,
+    JsonRpcId,
     [
-      (response: unknown) => unknown,
+      (response: JsonRpcResponse) => unknown,
       (error: unknown) => unknown,
       ReturnType<typeof setTimeout>,
     ]
   > = new Map();
+  private disposed = false;
   private socket?: WebSocket;
   private openSocket?: Promise<WebSocket>;
 
+  /**
+   * @deprecated Use {@link JsonRpcTransportWebSocket.open} to make lifecycle
+   * ownership explicit. This constructor will become private in a future
+   * release.
+   */
   constructor(
     private readonly url: string,
     private readonly timeout = 30000,
   ) {}
 
-  request(data: JsonRpcPayload) {
-    const socket = (() => {
+  /** Opens an owned WebSocket transport. */
+  static open(
+    url: string,
+    timeout = 30000,
+  ): OwnerUnique<JsonRpcTransportWebSocket> {
+    const transport = new JsonRpcTransportWebSocket(url, timeout);
+    return new OwnerUnique(transport, (transport) => transport.dispose());
+  }
+
+  request(data: JsonRpcPayload): Promise<JsonRpcResponse> {
+    if (this.disposed) {
+      return Promise.reject(
+        new Error("Cannot use a disposed JsonRpcTransportWebSocket"),
+      );
+    }
+
+    const [socketUnsafe, socket] = (() => {
       if (
         this.socket &&
         this.socket.readyState !== this.socket.CLOSING &&
         this.socket.readyState !== this.socket.CLOSED &&
         this.openSocket
       ) {
-        return this.openSocket;
+        return [this.socket, this.openSocket] as const;
       }
       const socket = new WebSocket(this.url);
       const onMessage = ({ data }: WebSocket.MessageEvent) => {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-        const res = JSON.parse(data as string);
+        let res: JsonRpcResponse;
+        try {
+          res = JSON.parse(data as string) as JsonRpcResponse;
+        } catch (_) {
+          return;
+        }
         if (
           typeof res !== "object" ||
           res === null ||
-          typeof res.id !== "number"
+          (typeof res.id !== "number" && typeof res.id !== "string")
         ) {
-          throw new Error(`Unknown response ${data as string}`);
+          return;
         }
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-        const id: number = res.id;
+        const id = res.id;
 
         const req = this.ongoing.get(id);
         if (!req) {
@@ -74,12 +104,12 @@ export class TransportWebSocket implements Transport {
           };
         }
       });
-      return this.openSocket;
+      return [socket, this.openSocket] as const;
     })();
 
-    return new Promise((resolve, reject) => {
+    return new Promise<JsonRpcResponse>((resolve, reject) => {
       const req: [
-        (res: unknown) => unknown,
+        (res: JsonRpcResponse) => unknown,
         (err: unknown) => unknown,
         ReturnType<typeof setTimeout>,
       ] = [
@@ -87,9 +117,7 @@ export class TransportWebSocket implements Transport {
         reject,
         setTimeout(() => {
           this.ongoing.delete(data.id);
-          void socket
-            .then((socket) => socket.close())
-            .catch((err) => reject(err));
+          socketUnsafe.close();
           reject(new Error("Request timeout"));
         }, this.timeout),
       ];
@@ -97,6 +125,9 @@ export class TransportWebSocket implements Transport {
 
       void socket
         .then((socket) => {
+          if (!this.ongoing.has(data.id)) {
+            return;
+          }
           if (
             socket.readyState === socket.CLOSED ||
             socket.readyState === socket.CLOSING
@@ -108,7 +139,23 @@ export class TransportWebSocket implements Transport {
             socket.send(JSON.stringify(data));
           }
         })
-        .catch((err) => reject(err));
+        .catch((err) => {
+          clearTimeout(req[2]);
+          this.ongoing.delete(data.id);
+          reject(err);
+        });
+    });
+  }
+
+  private async dispose(): Promise<void> {
+    this.disposed = true;
+    const socket = this.socket;
+
+    if (!socket || socket.readyState === socket.CLOSED) return;
+
+    await new Promise<void>((resolve) => {
+      socket.addEventListener("close", () => resolve(), { once: true });
+      socket.close();
     });
   }
 }

package/src/keystore/index.ts

@@ -14,7 +14,7 @@ const DEFAULT_SCRYPT_PARAM_N = 262144;
 
 function mac(derivedKey: Bytes, cipherText: Bytes) {
   return hexFrom(
-    keccak_256(bytesConcat(derivedKey.slice(16, 32), cipherText)),
+    keccak_256(bytesConcat(derivedKey.subarray(16, 32), cipherText)),
   ).slice(2);
 }
 
@@ -60,7 +60,7 @@ export async function keystoreEncrypt(
     dkLen: kdfparams.dklen,
   });
   const cipher = ctr(
-    derivedKey.slice(0, 16),
+    derivedKey.subarray(0, 16),
     iv.map((v) => v),
   );
   const ciphertext = cipher.encrypt(
@@ -151,7 +151,7 @@ export async function keystoreDecrypt(
     throw Error("Invalid password");
   }
   const cipher = ctr(
-    derivedKey.slice(0, 16),
+    derivedKey.subarray(0, 16),
     bytesFrom(crypto.cipherparams.iv),
   );
   const result = cipher.decrypt(ciphertext);