@hyperttp/transport-bun 0.2.2 → 0.2.4

package/README.md

@@ -1,25 +1,24 @@
 # BunTransport
 
-`BunTransport` is a network transport implementation for `HyperTransport`, designed to run in the **Bun runtime**.
+`BunTransport` is a high-performance HTTP transport for the
+[HyperTransport](https://github.com/IT-IF-OR) ecosystem, designed for the **Bun runtime**.
 
-It wraps `fetch` and adds:
+It wraps native `fetch` and adds:
 
-- concurrency limiting
+- concurrency limiting with FIFO queue
 - request timeouts via `AbortSignal`
-- automatic cookie handling
+- automatic cookie handling with TTL and LRU eviction
+- response caching for GET/HEAD requests
+- stealth / fingerprint mimicry (JA3/JA4)
 - header normalization
 - `keepalive` support
-- access to Bun `tls` options
+- TLS configuration (ciphers, `rejectUnauthorized`)
 
 ---
 
 ## Interface
 
 ```ts
-/**
- * @ru Общий интерфейс для реализации сетевых транспортов.
- * @en Unified interface for building runtime-specific network transports.
- */
 export interface HyperTransport {
   execute(req: TransportRequest): Promise<TransportResponse>;
   close?(): Promise<void>;
@@ -34,43 +33,65 @@ export interface HyperTransport {
 ## Features
 
 - `fetch`-based implementation with `signal` support
-- `redirect: "manual"`
 - automatic merging of cookies from responses and subsequent requests
-- cookie cache per domain
-- request concurrency limiting
+- cookie cache per domain with configurable TTL
+- response cache for GET/HEAD requests (optional, via `hcacher`)
+- request concurrency limiting with FIFO queue
 - request timeout support
-- automatic `User-Agent` injection from config (if not provided manually)
+- stealth mode: browser-like TLS fingerprint emulation (Chrome, Firefox, Safari, Edge)
+- `baseUrl` support for relative URLs
 - compatibility with `TransportRequest` / `TransportResponse`
 
 ---
 
+## Benchmark
+
+Benchmark results on **Bun 1.3.14** (20K requests, 200 concurrent, 60s duration):
+
+```text
+Environment: linux 7.1.3-zen2-1-zen | Intel Core i5-8600K @ 3.60GHz
+```
+
+| Rank | Client         | RPS    | Avg      | p50      | p90      | p99      | Errors |
+| ---- | -------------- | ------ | -------- | -------- | -------- | -------- | ------ |
+| 1    | bun-fetch      | 25.92K | 7.65 ms  | 7.69 ms  | 10.41 ms | 14.00 ms | 0      |
+| 2    | undici         | 21.47K | 9.28 ms  | 9.54 ms  | 12.80 ms | 14.77 ms | 0      |
+| 3    | @hyperttp/core | 14.70K | 13.53 ms | 12.03 ms | 17.36 ms | 19.72 ms | 0      |
+| 4    | axios          | 6.24K  | 31.85 ms | 31.83 ms | 33.82 ms | 36.10 ms | 0      |
+
+`BunTransport` (via `@hyperttp/core`) delivers **2.4x higher throughput** than `axios` with **2.3x lower latency** (p50).
+
+---
+
 ## Installation
 
 `BunTransport` is designed for Bun, so the project must run in the Bun runtime.
 
 ```bash
-bun install
+bun add @hyperttp/transport-bun
 ```
 
+Peer dependencies: `@hyperttp/types`, `hcacher`.
+
 ---
 
 ## Usage
 
 ```ts
-import { BunTransport } from "./BunTransport";
+import { BunTransport } from "@hyperttp/transport-bun";
 
 const transport = new BunTransport({
+  baseUrl: "https://api.example.com",
   network: {
     timeout: 10_000,
     maxConcurrent: 32,
-    userAgent: "Hyperttp/1.0",
     keepAliveTimeout: 30_000,
     rejectUnauthorized: true,
   },
 });
 
 const response = await transport.execute({
-  url: "https://example.com",
+  url: "/users",
   method: "GET",
   headers: {},
   body: null,
@@ -84,54 +105,71 @@ console.log(await response.text());
 
 ## Configuration
 
-`BunTransport` reads configuration from `HttpClientOptions.network`.
+`BunTransport` accepts a `BunTransportConfig` object:
+
+```ts
+interface BunTransportConfig extends HttpClientOptions {
+  baseUrl?: string;
+  stealth?: StealthOptions;
+}
+```
 
-Supported options:
+### Network options
 
 ```ts
 network?: {
   maxConcurrent?: number;
   timeout?: number;
-  userAgent?: string;
   keepAliveTimeout?: number;
   rejectUnauthorized?: boolean;
+  cookieCache?: {
+    enabled?: boolean;
+    maxSize?: number;
+    ttl?: number;
+  };
+  cache?: {
+    enabled?: boolean;
+    maxSize?: number;
+    ttl?: number;
+  };
 }
 ```
 
-### Option behavior
-
-- `maxConcurrent` — maximum number of concurrent active requests.
-- `timeout` — global request timeout in milliseconds.
-- `userAgent` — injected into `User-Agent` header if not explicitly set.
-- `keepAliveTimeout` — enables `keepalive` mode when provided.
-- `rejectUnauthorized` — passed to Bun `fetch` via `tls` configuration.
+| Option               | Description                                                                                    |
+| -------------------- | ---------------------------------------------------------------------------------------------- |
+| `maxConcurrent`      | Maximum number of concurrent active requests (0 = unlimited)                                   |
+| `timeout`            | Global request timeout in milliseconds (0 = no timeout)                                        |
+| `keepAliveTimeout`   | Enables `keepalive` mode when provided                                                         |
+| `rejectUnauthorized` | Passed to Bun `fetch` via `tls` configuration                                                  |
+| `cookieCache`        | Cookie cache settings: `enabled` (default true), `maxSize` (default 256), `ttl` (default 300s) |
+| `cache`              | Response cache settings for GET/HEAD: `enabled`, `maxSize` (default 256), `ttl` (default 30s)  |
 
 ---
 
 ## Cookies
 
-The transport supports persistent cookie storage and reuse between requests.
+The transport supports persistent cookie storage with TTL and LRU eviction, backed by `hcacher`.
 
 ### How it works
 
-1. When the server returns `Set-Cookie`, cookies are stored per domain.
+1. When the server returns `Set-Cookie`, cookies are stored per domain with a TTL.
 2. On subsequent requests to the same domain, cookies are automatically attached to the `Cookie` header.
 3. If the user provides their own `Cookie` header, it is merged with stored cookies.
+4. Expired entries are evicted automatically (LRU).
 
 ### Example
 
 ```ts
 await transport.execute({
-  url: "https://example.com/login",
+  url: "/login",
   method: "POST",
-  headers: {
-    "Content-Type": "application/json",
-  },
+  headers: { "Content-Type": "application/json" },
   body: JSON.stringify({ login: "demo", password: "secret" }),
 });
 
+// Cookies from /login are automatically sent
 const res = await transport.execute({
-  url: "https://example.com/profile",
+  url: "/profile",
   method: "GET",
   headers: {},
   body: null,
@@ -140,6 +178,26 @@ const res = await transport.execute({
 
 ---
 
+## Response caching
+
+When `network.cache` is configured, GET and HEAD requests are cached automatically with TTL and LRU eviction.
+
+```ts
+const transport = new BunTransport({
+  network: {
+    cache: {
+      enabled: true,
+      maxSize: 512,
+      ttl: 60_000, // 1 minute
+    },
+  },
+});
+```
+
+Cached responses are returned instantly on repeated requests to the same URL within the TTL window.
+
+---
+
 ## Concurrency limiting
 
 If `maxConcurrent > 0`, incoming requests are queued until a slot becomes available.
@@ -164,16 +222,45 @@ If a request is aborted, the signal reason (or a default `AbortError`) is thrown
 
 ---
 
+## Stealth / fingerprint mimicry
+
+`BunTransport` supports browser-like TLS fingerprint emulation to bypass fingerprint-based protections (JA3/JA4).
+
+### Supported profiles
+
+| Profile | TLS ciphers   | sec-ch-ua     | User-Agent  |
+| ------- | ------------- | ------------- | ----------- |
+| chrome  | Chrome suite  | Chrome 126    | Chrome 126  |
+| firefox | Firefox suite | Firefox-style | Firefox 126 |
+| safari  | Safari suite  | —             | Safari 17.0 |
+| edge    | Chrome suite  | Chrome 126    | Edge 126    |
+
+### Example
+
+```ts
+const transport = new BunTransport({
+  stealth: {
+    fingerprint: "chrome",
+  },
+});
+```
+
+Stealth presets are applied per-request. Manual headers always take priority over preset values.
+
+---
+
 ## Response API
 
-`BunTransportResponse` wraps the native `Response` and provides:
+`execute()` returns a plain `TransportResponse` object:
 
-- `status`
-- `url`
-- `body`
-- `text()`
-- `json()`
-- `headers`
+```ts
+interface TransportResponse {
+  status: number;
+  url: string;
+  headers: Record<string, string | string[]>;
+  body: TransportResponsePayload | null;
+}
+```
 
 ### Body behavior
 
@@ -185,22 +272,15 @@ If `body` exists, a `dump()` method may be attached to it, allowing safe stream
 
 ### `fastGetHostname(url: string): string`
 
-Fast hostname extraction from a URL without full parsing.
-
-### `normalizeHeaderValue(name, value)`
-
-Normalizes header values:
-
-- `Cookie` headers are joined using `;`
-- other arrays are joined using `,`
+Fast hostname extraction from a URL with single-entry LRU cache. Handles `//`, `scheme://`, `user@host`, and port stripping.
 
-### `normalizeCookieHeader(value)`
+### `resolveUrl(baseUrl: string, url: string): string`
 
-Converts cookie header values into a normalized string.
+Resolves a relative URL against a `baseUrl`. Absolute URLs are returned as-is.
 
-### `throwIfAborted(signal)`
+### `normalizeHeaders(headers): Record<string, string>`
 
-Checks whether an operation has been aborted and throws if so.
+Normalizes headers: lowercases all keys, joins arrays (`;` for `cookie`, `,` for others).
 
 ---
 
@@ -216,8 +296,10 @@ await transport.destroy();
 Both methods clear:
 
 - pending request queue
-- cookie jar
-- cookie cache
+- cookie store
+- cookie string cache
+- response cache
+- active request counter
 
 ---
 
@@ -226,7 +308,7 @@ Both methods clear:
 - Designed specifically for the **Bun runtime**, not Node.js.
 - Uses `redirect: "manual"` for fetch requests.
 - Minimal interference with request data; only headers, cookies, and signals are normalized or extended.
-- `TransportRequest.body` is treated as `BodyInit | null`.
+- `TransportRequest.body` is passed directly as `BodyInit | null`.
 
 ---
 

package/bun.d.ts

@@ -1,36 +1,71 @@
-import type { HttpClientOptions, HyperTransport, TransportRequest, TransportResponse } from "@hyperttp/types";
+import type { HyperTransport, TransportRequest, TransportResponse } from "@hyperttp/types";
+import type { BunTransportConfig } from "./types/index.js";
 /**
- * @ru Конфигурация транспорта Bun.
- * @en Bun transport configuration.
+ * @ru Высокопроизводительный HTTP-транспорт для Bun с нативными оптимизациями и поддержкой Stealth-мимикрии.
+ * Включает управление параллелизмом, cookie jar и кэширование доменов.
+ * @en High-performance HTTP transport for Bun with native optimizations and Stealth mimicry support.
+ * Includes concurrency management, cookie jar, and domain caching.
  */
-export interface BunTransportConfig extends HttpClientOptions {
+export declare class BunTransport implements HyperTransport {
     /**
-     * @ru Базовый URL для всех запросов.
-     * @en Base URL for all requests.
+     * @ru Конфигурация транспорта.
+     * @en Transport configuration.
      */
-    baseUrl?: string;
-}
-/**
- * @ru Высокопроизводительный HTTP-транспорт для Bun с нативными оптимизациями.
- * Поддерживает cookies, concurrency control, таймауты, keepalive и TLS конфигурацию.
- * @en High-performance HTTP transport for Bun with native optimizations.
- * Supports cookies, concurrency control, timeouts, keepalive, and TLS configuration.
- */
-export declare class BunTransport implements HyperTransport {
     config: BunTransportConfig;
-    private cookieJar;
-    private readonly cookieDomains;
-    private cookieCache;
-    private cookieCacheSize;
+    /**
+     * @ru Кэш cookies по доменам с TTL и LRU-эвикцией (domain -> name -> value).
+     * @en Cookie cache by domain with TTL and LRU eviction (domain -> name -> value).
+     */
+    private readonly cookieStore;
+    /**
+     * @ru Кэш сгенерированных строк cookies с TTL.
+     * @en Cache of generated cookie strings with TTL.
+     */
+    private readonly cookieStringCache;
+    /**
+     * @ru Опциональный кэш HTTP-ответов для GET/HEAD запросов.
+     * @en Optional HTTP response cache for GET/HEAD requests.
+     */
+    private readonly responseCache?;
+    /**
+     * @ru Счётчик активных (выполняющихся) запросов.
+     * @en Counter of active (in-flight) requests.
+     */
     private activeRequests;
+    /**
+     * @ru Очередь запросов, ожидающих свободного слота при достижении лимита параллелизма.
+     * @en Queue of requests waiting for a free slot when concurrency limit is reached.
+     */
     private concurrencyQueue;
+    /**
+     * @ru Индекс начала очереди (для FIFO обработки).
+     * @en Queue head index (for FIFO processing).
+     */
     private queueHead;
+    /**
+     * @ru Индекс конца очереди (для добавления новых элементов).
+     * @en Queue tail index (for adding new elements).
+     */
     private queueTail;
-    private hasCookies;
+    /**
+     * @ru Максимальное количество одновременных запросов (0 = без лимита).
+     * @en Maximum number of concurrent requests (0 = unlimited).
+     */
     private _maxConcurrent;
+    /**
+     * @ru Таймаут запроса в миллисекундах (0 = без таймаута).
+     * @en Request timeout in milliseconds (0 = no timeout).
+     */
     private _timeout;
-    private _userAgent;
+    /**
+     * @ru Флаг использования keep-alive соединений.
+     * @en Flag for using keep-alive connections.
+     */
     private _keepalive;
+    /**
+     * @ru Конфигурация TLS (отклонение невалидных сертификатов и шифры).
+     * @en TLS configuration (reject unauthorized certificates and ciphers).
+     */
     private _tlsConfig;
     /**
      * @ru Создаёт экземпляр BunTransport.
@@ -39,53 +74,62 @@ export declare class BunTransport implements HyperTransport {
      */
     constructor(config: BunTransportConfig);
     /**
-     * @ru Инвалидирует кэшированные настройки при изменении конфигурации.
-     * @en Invalidates cached settings when configuration changes.
+     * @ru Обновляет внутреннее состояние на основе конфигурации.
+     * Вызывается при создании и может быть вызвано при изменении конфига.
+     * @en Updates internal state based on configuration.
+     * Called on creation and can be called when config changes.
      */
     private invalidateConfig;
     /**
-     * @ru Выполняет HTTP-запрос через нативный fetch Bun.
-     * @en Executes an HTTP request via Bun's native fetch.
+     * @ru Выполняет HTTP-запрос через нативный fetch Bun с управлением параллелизмом и таймаутами.
+     * @en Executes an HTTP request via Bun's native fetch with concurrency management and timeouts.
      * @param req - The normalized transport request.
      * @returns Promise resolving to the transport response.
+     * @throws Error if the request is aborted or times out.
      */
     execute(req: TransportRequest): Promise<TransportResponse>;
     /**
-     * @ru Подготавливает заголовки запроса, добавляя User-Agent и cookies.
-     * @en Prepares request headers, adding User-Agent and cookies.
-     * @param req - The transport request.
-     * @returns The prepared headers or undefined.
+     * @ru Получает строку cookies для указанного домена с учётом родительских доменов.
+     * @en Gets the cookie string for the specified domain, considering parent domains.
+     * @param requestDomain - The domain to get cookies for.
+     * @returns Semicolon-separated cookie string.
+     */
+    private getCookiesForDomain;
+    /**
+     * @ru Возвращает все домены из cookie store.
+     * @en Returns all domains from the cookie store.
+     */
+    private getAllCookieDomains;
+    /**
+     * @ru Сохраняет cookies из заголовков Set-Cookie ответа в cookie jar.
+     * @en Stores cookies from response Set-Cookie headers into the cookie jar.
+     * @param requestUrl - The request URL for determining the default domain.
+     * @param headers - Response headers containing Set-Cookie values.
      */
-    private prepareHeaders;
+    private storeCookies;
     /**
-     * @ru Ожидает свободный слот в очереди concurrency.
-     * @en Waits for an available slot in the concurrency queue.
-     * @param signal - Optional abort signal.
+     * @ru Ожидает освобождения слота в очереди параллелизма.
+     * @en Waits for a slot to become available in the concurrency queue.
+     * @param signal - Optional abort signal to cancel waiting.
      * @returns Promise that resolves when a slot is available.
+     * @throws Error if the signal is aborted while waiting.
      */
     private waitForSlot;
     /**
-     * @ru Освобождает слот и уведомляет следующий запрос в очереди.
-     * @en Releases a slot and notifies the next request in the queue.
+     * @ru Освобождает слот и разблокирует следующий запрос в очереди.
+     * @en Releases a slot and unblocks the next request in the queue.
      */
     private releaseSlot;
     /**
-     * @ru Извлекает cookies для указанного домена из cookie jar.
-     * @en Retrieves cookies for the specified domain from the cookie jar.
-     * @param requestDomain - The domain to get cookies for.
-     * @returns The cookie string or empty string.
-     */
-    private getCookiesForDomain;
-    /**
-     * @ru Мягко закрывает транспорт, очищая очереди и cookies.
-     * @en Gracefully closes the transport, clearing queues and cookies.
-     * @returns Promise that resolves when the transport is closed.
+     * @ru Мягко закрывает транспорт, очищая очереди и cookie jar.
+     * @en Gracefully closes the transport, clearing queues and cookie jar.
+     * @returns Promise that resolves when cleanup is complete.
      */
     close(): Promise<void>;
     /**
-     * @ru Принудительно уничтожает транспорт и все активные соединения.
-     * @en Immediately destroys the transport and all active connections.
-     * @returns Promise that resolves when the transport is destroyed.
+     * @ru Принудительно уничтожает транспорт (алиас для close()).
+     * @en Forcefully destroys the transport (alias for close()).
+     * @returns Promise that resolves when cleanup is complete.
      */
     destroy(): Promise<void>;
 }

package/bun.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../src/bun.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EAElB,MAAM,iBAAiB,CAAC;AA4HzB;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,YAAa,YAAW,cAAc;IAC1C,MAAM,EAAE,kBAAkB,CAAC;IAElC,OAAO,CAAC,SAAS,CAA+D;IAChF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,WAAW,CAA+C;IAClE,OAAO,CAAC,eAAe,CAAK;IAE5B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,gBAAgB,CAAmD;IAC3E,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,SAAS,CAAK;IAEtB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,UAAU,CAAiC;IACnD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAgD;IAElE;;;;OAIG;gBACS,MAAM,EAAE,kBAAkB;IAKtC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IASxB;;;;;OAKG;IACU,OAAO,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAsEvE;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAgCtB;;;;;OAKG;YACW,WAAW;IAmBzB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAkBnB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAgC3B;;;;OAIG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAYnC;;;;OAIG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAGtC"}
+{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../src/bun.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EAIlB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAgI3D;;;;;GAKG;AACH,qBAAa,YAAa,YAAW,cAAc;IACjD;;;OAGG;IACI,MAAM,EAAE,kBAAkB,CAAC;IAElC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuC;IAEnE;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAuB;IAEzD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAkC;IAEjE;;;OAGG;IACH,OAAO,CAAC,cAAc,CAAK;IAE3B;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAAmD;IAE3E;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAK;IAEtB;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAK;IAEtB;;;OAGG;IACH,OAAO,CAAC,cAAc,CAAK;IAE3B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAK;IAErB;;;OAGG;IACH,OAAO,CAAC,UAAU,CAAS;IAE3B;;;OAGG;IACH,OAAO,CAAC,UAAU,CAAkE;IAEpF;;;;OAIG;IACH,YAAY,MAAM,EAAE,kBAAkB,EA6BrC;IAED;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;;;;;OAMG;IACU,OAAO,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAsItE;IAED;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAwB3B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IA8CpB;;;;;;OAMG;YACW,WAAW;IAmBzB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAkBnB;;;;OAIG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAQlC;IAED;;;;OAIG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAEpC;CACF"}