TON-1531: abort controllers in api client

packages/walletkit/src/api/interfaces/ApiClient.ts

@@ -8,6 +8,7 @@
 
 import type { Address } from '@ton/core';
 
+import type { RequestOptions } from '../../clients/types';
 import type { ToncenterResponseJettonMasters, ToncenterTracesResponse } from '../../types/toncenter/emulation';
 import type { Event } from '../../types/toncenter/AccountEvent';
 import type {
@@ -99,17 +100,22 @@ export interface GetEventsResponse {
 export interface ApiClient {
     getNetwork(): Network;
 
-    nftItemsByAddress(request: NFTsRequest): Promise<NFTsResponse>;
-    nftItemsByOwner(request: UserNFTsRequest): Promise<NFTsResponse>;
-    fetchEmulation(messageBoc: Base64String, ignoreSignature?: boolean): Promise<EmulationResult>;
-    sendBoc(boc: Base64String): Promise<string>;
+    nftItemsByAddress(request: NFTsRequest, opts?: RequestOptions): Promise<NFTsResponse>;
+    nftItemsByOwner(request: UserNFTsRequest, opts?: RequestOptions): Promise<NFTsResponse>;
+    fetchEmulation(
+        messageBoc: Base64String,
+        ignoreSignature?: boolean,
+        opts?: RequestOptions,
+    ): Promise<EmulationResult>;
+    sendBoc(boc: Base64String, opts?: RequestOptions): Promise<string>;
     runGetMethod(
         address: UserFriendlyAddress,
         method: string,
         stack?: RawStackItem[],
         seqno?: number,
+        opts?: RequestOptions,
     ): Promise<GetMethodResult>; // TODO - Make serializable
-    getAccountState(address: UserFriendlyAddress, seqno?: number): Promise<AccountState>;
+    getAccountState(address: UserFriendlyAddress, seqno?: number, opts?: RequestOptions): Promise<AccountState>;
 
     /**
      * Fetches blockchain state for multiple accounts in a single batched request.
@@ -123,25 +129,31 @@ export interface ApiClient {
      * Throws on any HTTP failure. Has no `seqno` parameter — bulk endpoints
      * of both toncenter and tonapi do not support historical state queries.
      */
-    getAccountStates(addresses: UserFriendlyAddress[]): Promise<AccountStates>;
+    getAccountStates(addresses: UserFriendlyAddress[], opts?: RequestOptions): Promise<AccountStates>;
 
-    getBalance(address: UserFriendlyAddress, seqno?: number): Promise<TokenAmount>;
+    getBalance(address: UserFriendlyAddress, seqno?: number, opts?: RequestOptions): Promise<TokenAmount>;
 
-    getAccountTransactions(request: TransactionsByAddressRequest): Promise<TransactionsResponse>;
-    getTransactionsByHash(request: GetTransactionByHashRequest): Promise<TransactionsResponse>;
+    getAccountTransactions(request: TransactionsByAddressRequest, opts?: RequestOptions): Promise<TransactionsResponse>;
+    getTransactionsByHash(request: GetTransactionByHashRequest, opts?: RequestOptions): Promise<TransactionsResponse>;
 
-    getPendingTransactions(request: GetPendingTransactionsRequest): Promise<TransactionsResponse>;
+    getPendingTransactions(
+        request: GetPendingTransactionsRequest,
+        opts?: RequestOptions,
+    ): Promise<TransactionsResponse>;
 
-    getTrace(request: GetTraceRequest): Promise<ToncenterTracesResponse>;
-    getPendingTrace(request: GetPendingTraceRequest): Promise<ToncenterTracesResponse>;
+    getTrace(request: GetTraceRequest, opts?: RequestOptions): Promise<ToncenterTracesResponse>;
+    getPendingTrace(request: GetPendingTraceRequest, opts?: RequestOptions): Promise<ToncenterTracesResponse>;
 
-    resolveDnsWallet(domain: string): Promise<string | undefined>;
-    backResolveDnsWallet(address: UserFriendlyAddress): Promise<string | undefined>;
+    resolveDnsWallet(domain: string, opts?: RequestOptions): Promise<string | undefined>;
+    backResolveDnsWallet(address: UserFriendlyAddress, opts?: RequestOptions): Promise<string | undefined>;
 
-    jettonsByAddress(request: GetJettonsByAddressRequest): Promise<ToncenterResponseJettonMasters>;
-    jettonsByOwnerAddress(request: GetJettonsByOwnerRequest): Promise<JettonsResponse>;
+    jettonsByAddress(
+        request: GetJettonsByAddressRequest,
+        opts?: RequestOptions,
+    ): Promise<ToncenterResponseJettonMasters>;
+    jettonsByOwnerAddress(request: GetJettonsByOwnerRequest, opts?: RequestOptions): Promise<JettonsResponse>;
 
-    getEvents(request: GetEventsRequest): Promise<GetEventsResponse>;
+    getEvents(request: GetEventsRequest, opts?: RequestOptions): Promise<GetEventsResponse>;
 
-    getMasterchainInfo(): Promise<MasterchainInfo>;
+    getMasterchainInfo(opts?: RequestOptions): Promise<MasterchainInfo>;
 }

packages/walletkit/src/clients/BaseApiClient.spec.ts

@@ -0,0 +1,69 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { BaseApiClient } from './BaseApiClient';
+import type { BaseApiClientConfig } from './BaseApiClient';
+import { ApiClientTimeoutError } from './errors';
+
+class TestClient extends BaseApiClient {
+    constructor(config: BaseApiClientConfig) {
+        super(config, 'https://example.test');
+    }
+    protected appendAuthHeaders(): void {}
+}
+
+/** Resolves with a JSON response. */
+const jsonFetch = (body: unknown, status = 200): typeof fetch =>
+    (async () =>
+        new Response(JSON.stringify(body), {
+            status,
+            headers: { 'content-type': 'application/json' },
+        })) as typeof fetch;
+
+/** Never resolves on its own — only rejects (with the abort reason) once its signal aborts. */
+const hangingFetch = (): typeof fetch =>
+    ((_input: RequestInfo | URL, init?: RequestInit) =>
+        new Promise<Response>((_resolve, reject) => {
+            const signal = init?.signal;
+            signal?.addEventListener(
+                'abort',
+                () => reject(signal.reason ?? new DOMException('Aborted', 'AbortError')),
+                {
+                    once: true,
+                },
+            );
+        })) as typeof fetch;
+
+describe('BaseApiClient', () => {
+    it('returns parsed JSON on success', async () => {
+        const client = new TestClient({ fetchApi: jsonFetch({ ok: 1 }), timeout: 1000 });
+        await expect(client.getJson('/x')).resolves.toEqual({ ok: 1 });
+    });
+
+    it('throws ApiClientTimeoutError when the request exceeds the timeout', async () => {
+        const client = new TestClient({ fetchApi: hangingFetch(), timeout: 10 });
+        await expect(client.getJson('/x')).rejects.toBeInstanceOf(ApiClientTimeoutError);
+    });
+
+    it('propagates a caller abort without converting it to a timeout', async () => {
+        const controller = new AbortController();
+        const client = new TestClient({ fetchApi: hangingFetch(), timeout: 1000 });
+        const promise = client.getJson('/x', undefined, { signal: controller.signal });
+        controller.abort();
+        await expect(promise).rejects.not.toBeInstanceOf(ApiClientTimeoutError);
+    });
+
+    it('aborts before touching the network when the signal is already aborted', async () => {
+        const fetchApi = vi.fn(hangingFetch());
+        const client = new TestClient({ fetchApi, timeout: 1000 });
+        await expect(client.getJson('/x', undefined, { signal: AbortSignal.abort() })).rejects.toThrow();
+        expect(fetchApi).not.toHaveBeenCalled();
+    });
+});

packages/walletkit/src/clients/BaseApiClient.ts

@@ -7,7 +7,9 @@
  */
 
 import { Network } from '../api/models';
-import { TonClientError } from './TonClientError';
+import { combineSignals } from './combine-signals';
+import { ApiClientHttpError, ApiClientTimeoutError } from './errors';
+import type { RequestOptions } from './types';
 
 export interface BaseApiClientConfig {
     endpoint?: string;
@@ -37,34 +39,37 @@ export abstract class BaseApiClient {
 
     protected abstract appendAuthHeaders(headers: Headers): void;
 
-    async fetch<T>(url: URL, props: globalThis.RequestInit = {}): Promise<T> {
+    async fetch<T>(url: URL, props: globalThis.RequestInit = {}, opts: RequestOptions = {}): Promise<T> {
         const headers = new Headers(props.headers);
         headers.set('accept', 'application/json');
         this.appendAuthHeaders(headers);
-        props = { ...props, headers };
-        const response = await this.doRequest(url, props);
+        const response = await this.doRequest(url, { ...props, headers }, opts.signal);
         if (!response.ok) {
             throw await this.buildError(response);
         }
         const contentType = response.headers.get('content-type') || '';
         if (!contentType.includes('application/json')) {
             const text = await (response as globalThis.Response).text();
-            throw new TonClientError('Unexpected non-JSON response', response.status, text.slice(0, 200));
+            throw new ApiClientHttpError('Unexpected non-JSON response', response.status, text.slice(0, 200));
         }
         const json = await response.json();
         return json as Promise<T>;
     }
 
-    async getJson<T>(path: string, query?: Record<string, unknown>): Promise<T> {
-        return this.fetch(this.buildUrl(path, query), { method: 'GET' });
+    async getJson<T>(path: string, query?: Record<string, unknown>, opts?: RequestOptions): Promise<T> {
+        return this.fetch(this.buildUrl(path, query), { method: 'GET' }, opts);
     }
 
-    async postJson<T>(path: string, props: unknown): Promise<T> {
-        return this.fetch(this.buildUrl(path), {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(props),
-        });
+    async postJson<T>(path: string, props: unknown, opts?: RequestOptions): Promise<T> {
+        return this.fetch(
+            this.buildUrl(path),
+            {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(props),
+            },
+            opts,
+        );
     }
 
     protected buildUrl(path: string, query: Record<string, unknown> = {}): URL {
@@ -94,21 +99,42 @@ export abstract class BaseApiClient {
         } catch {
             /* empty */
         }
-        return new TonClientError(`HTTP ${response.status}: ${message}`, code, detail);
+        return new ApiClientHttpError(`HTTP ${response.status}: ${message}`, code, detail);
     }
 
-    private async doRequest(url: URL, init: globalThis.RequestInit = {}): Promise<globalThis.Response> {
+    private async doRequest(
+        url: URL,
+        init: globalThis.RequestInit = {},
+        externalSignal?: AbortSignal,
+    ): Promise<globalThis.Response> {
         const fetchFn = this.fetchApi;
 
-        if (!this.timeout || this.timeout <= 0) {
-            return fetchFn(url, init);
+        // Bail out before touching the network if the caller already aborted.
+        externalSignal?.throwIfAborted();
+
+        const hasTimeout = this.timeout > 0;
+        if (!hasTimeout) {
+            return fetchFn(url, externalSignal ? { ...init, signal: externalSignal } : init);
         }
 
+        // Fresh controller per attempt — a timeout aborts it, so it cannot be
+        // reused once spent. A flag (not the abort reason) distinguishes a
+        // timeout from a caller abort, so the underlying AbortError surfaces as
+        // a typed ApiClientTimeoutError while the caller's abort propagates as-is.
         const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        let timedOut = false;
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, this.timeout);
 
         try {
-            return await fetchFn(url, { ...init, signal: controller.signal });
+            return await fetchFn(url, { ...init, signal: combineSignals(externalSignal, controller.signal) });
+        } catch (error) {
+            if (timedOut) {
+                throw new ApiClientTimeoutError(`Request timed out after ${this.timeout}ms`, this.timeout);
+            }
+            throw error;
         } finally {
             clearTimeout(timeoutId);
         }

packages/walletkit/src/clients/combine-signals.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/**
+ * Combines a caller-provided abort signal with the client's internal timeout
+ * signal into one: the result aborts when *either* fires. Uses native
+ * `AbortSignal.any` where available, falling back to manual listener wiring on
+ * older runtimes (some mobile WebViews) so a caller's abort is still honored.
+ */
+export function combineSignals(external: AbortSignal | undefined, internal: AbortSignal): AbortSignal {
+    if (!external) {
+        return internal;
+    }
+    if (typeof AbortSignal !== 'undefined' && typeof AbortSignal.any === 'function') {
+        return AbortSignal.any([external, internal]);
+    }
+    const controller = new AbortController();
+    const abortWith = (signal: AbortSignal) => () => {
+        if (!controller.signal.aborted) {
+            controller.abort(signal.reason);
+        }
+    };
+    if (external.aborted) {
+        controller.abort(external.reason);
+    } else if (internal.aborted) {
+        controller.abort(internal.reason);
+    } else {
+        external.addEventListener('abort', abortWith(external), { once: true });
+        internal.addEventListener('abort', abortWith(internal), { once: true });
+    }
+    return controller.signal;
+}

packages/walletkit/src/clients/errors.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/**
+ * Base class for every error surfaced by the API clients. Catch this to handle
+ * any client-originated failure uniformly; narrow to a subclass for specifics.
+ */
+export class ApiClientError extends Error {
+    constructor(message: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = 'ApiClientError';
+    }
+}
+
+/**
+ * The server responded, but with a non-2xx status (or an unexpected body).
+ * Carries the HTTP `status` and any parsed error `details`.
+ */
+export class ApiClientHttpError extends ApiClientError {
+    public readonly status: number;
+    public readonly details?: unknown;
+
+    constructor(message: string, status: number, details?: unknown) {
+        super(message);
+        this.name = 'ApiClientHttpError';
+        this.status = status;
+        this.details = details;
+    }
+}
+
+/**
+ * The request did not complete within the configured `timeout`. Distinct from a
+ * caller-initiated abort: a timeout is retryable (when `retryOnTimeout` is set),
+ * an abort never is.
+ */
+export class ApiClientTimeoutError extends ApiClientError {
+    public readonly timeoutMs?: number;
+
+    constructor(message = 'Request timed out', timeoutMs?: number) {
+        super(message);
+        this.name = 'ApiClientTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+
+/**
+ * The request never reached a response — a transport-level failure (DNS, refused
+ * connection, offline, TLS). There is no HTTP status. The original `fetch`
+ * `TypeError` is preserved as `cause`.
+ */
+export class ApiClientNetworkError extends ApiClientError {
+    constructor(message: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = 'ApiClientNetworkError';
+    }
+}