stealth-fetch 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 0XwX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# stealth-fetch
+
+HTTP/1.1 + HTTP/2 client for Cloudflare Workers built on `cloudflare:sockets`.
+It avoids automatic `cf-*` header injection by using raw TCP sockets.
+
+## Highlights
+
+- HTTP/1.1 + HTTP/2 with ALPN negotiation
+- WASM TLS (rustls) for TLS 1.2/1.3 + ALPN control
+- HTTP/2 connection pooling and protocol cache
+- NAT64 fallback for blocked outbound connections
+- Redirects, retries, and timeouts
+- Raw headers preserved (order + multi-value)
+
+## Install
+
+```bash
+pnpm add stealth-fetch
+```
+
+## Usage
+
+```typescript
+import { request } from "stealth-fetch";
+
+const response = await request("https://api.example.com/v1/data", {
+  method: "POST",
+  headers: {
+    Authorization: "Bearer sk-...",
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    model: "gpt-4",
+    messages: [{ role: "user", content: "Hello" }],
+  }),
+});
+
+const data = await response.json();
+console.log(data);
+```
+
+## Web Response Compatibility
+
+If you need a standard Web `Response` object (with `bodyUsed`, `clone`, `text`,
+`json`, etc.), convert with `toWebResponse()`:
+
+```typescript
+import { request, toWebResponse } from "stealth-fetch";
+
+const resp = await request("https://httpbin.org/headers", { protocol: "h2" });
+const webResp = toWebResponse(resp);
+const text = await webResp.text();
+```
+
+Note: don’t call `resp.text()/json()/arrayBuffer()` before converting, or the
+body stream will already be consumed.
+
+If you need a pre-cloned pair (using `ReadableStream.tee()`), pass
+`{ tee: true }`:
+
+```typescript
+const { response, clone } = toWebResponse(resp, { tee: true });
+```
+
+## API
+
+### `request(url, options?)`
+
+Returns `Promise<HttpResponse>`.
+
+**Options**
+
+| Option           | Type                                                         | Default    | Description                                                                                                            |
+| ---------------- | ------------------------------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `method`         | `string`                                                     | `'GET'`    | HTTP method                                                                                                            |
+| `headers`        | `Record<string, string>`                                     | `{}`       | Request headers                                                                                                        |
+| `body`           | `string \| Uint8Array \| ReadableStream<Uint8Array> \| null` | `null`     | Request body                                                                                                           |
+| `protocol`       | `'h2' \| 'http/1.1' \| 'auto'`                               | `'auto'`   | Protocol selection                                                                                                     |
+| `timeout`        | `number`                                                     | `30000`    | Overall timeout from call until response headers (includes retries/redirects)                                          |
+| `headersTimeout` | `number`                                                     | —          | Timeout waiting for response headers                                                                                   |
+| `bodyTimeout`    | `number`                                                     | —          | Idle timeout waiting for response body data                                                                            |
+| `signal`         | `AbortSignal`                                                | —          | Cancellation signal                                                                                                    |
+| `redirect`       | `'follow' \| 'manual'`                                       | `'follow'` | Redirect handling                                                                                                      |
+| `maxRedirects`   | `number`                                                     | `5`        | Max redirects to follow                                                                                                |
+| `decompress`     | `boolean`                                                    | `true`     | Auto-decompress gzip/deflate responses                                                                                 |
+| `compressBody`   | `boolean`                                                    | `false`    | Gzip-compress request body (Uint8Array > 1KB)                                                                          |
+| `strategy`       | `'compat' \| 'fast-h1'`                                      | `'compat'` | `compat`: ALPN + protocol cache (h2 supported); `fast-h1`: platform TLS for non-CF, WASM TLS h1 for CF (faster, no h2) |
+
+**Response**
+
+```typescript
+interface HttpResponse {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  rawHeaders: ReadonlyArray<[string, string]>;
+  protocol: "h2" | "http/1.1";
+  body: ReadableStream<Uint8Array>;
+
+  text(): Promise<string>;
+  json(): Promise<unknown>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  getSetCookie(): string[];
+}
+```
+
+### Advanced APIs
+
+```typescript
+import {
+  Http2Client,
+  Http2Connection,
+  http1Request,
+  clearPool,
+  preconnect,
+  createWasmTLSSocket,
+} from "stealth-fetch";
+```
+
+- `Http2Client` — HTTP/2 client with stream multiplexing
+- `Http2Connection` — Low-level HTTP/2 connection
+- `http1Request(socket, request)` — HTTP/1.1 over a raw socket
+- `clearPool()` — Clear the HTTP/2 connection pool
+- `preconnect(hostname, port?)` — Pre-establish an HTTP/2 connection
+- `createWasmTLSSocket(hostname, port, alpnList)` — WASM TLS socket with ALPN
+
+## Differences From `fetch`
+
+- `fetch` injects `cf-*` headers in Workers, this library does not.
+- `fetch` exposes standard `Request/Response` objects; this library returns a
+  custom `HttpResponse` (use `toWebResponse()` if you need a Web `Response`).
+- Protocol control (force `h1`/`h2`, ALPN, NAT64) is supported here.
+
+## NAT64 Fallback Notes
+
+NAT64 is a best-effort fallback. Public NAT64 gateways can be unstable or
+blocked depending on region and routing, so some connections may fail. If you
+rely on NAT64, plan for retries or fallback behavior in your application.
+
+## Requirements
+
+- Cloudflare Workers runtime
+- `nodejs_compat` compatibility flag
+
+## Example Worker
+
+The repo includes a minimal worker at `examples/worker.ts` with endpoints:
+
+- `/http1`
+- `/http2`
+- `/auto`
+- `/fetch`
+- `/single?url=&mode=auto|h1|h2|fetch`
+
+`wrangler.toml` points to `examples/worker.ts` as the entry.
+
+## Development
+
+```bash
+pnpm dev          # Local dev server (wrangler)
+pnpm test:run     # Run tests once
+pnpm test         # Run tests in watch mode
+pnpm type-check   # TypeScript type check
+pnpm build        # Build to dist/
+pnpm lint         # ESLint
+pnpm format       # Prettier
+```
+
+## Contributing
+
+See `CONTRIBUTING.md` for commit message rules and dev notes.
+
+## Building WASM TLS
+
+Requires Rust toolchain with `wasm-pack` and `wasm32-unknown-unknown` target:
+
+```bash
+pnpm build:wasm
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/client.d.ts

@@ -0,0 +1,99 @@
+interface RetryOptions {
+    /** Max retry attempts (default: 2) */
+    limit?: number;
+    /** HTTP methods to retry (default: GET, HEAD, OPTIONS, PUT, DELETE) */
+    methods?: string[];
+    /** HTTP status codes to retry on (default: [408, 413, 429, 500, 502, 503, 504]) */
+    statusCodes?: number[];
+    /** Max retry delay in ms (default: 30000) */
+    maxDelay?: number;
+    /** Base delay for exponential backoff in ms — delay = baseDelay * 2^attempt (default: 1000) */
+    baseDelay?: number;
+}
+interface RequestOptions {
+    method?: string;
+    headers?: Record<string, string> | Headers;
+    body?: Uint8Array | string | ReadableStream<Uint8Array> | null;
+    /** Protocol selection: 'h2', 'http/1.1', or 'auto' (default) */
+    protocol?: "h2" | "http/1.1" | "auto";
+    /** Request timeout in ms (default: 30000). Covers from call to response headers (includes retries/redirects). */
+    timeout?: number;
+    /** Timeout waiting for response headers in ms. */
+    headersTimeout?: number;
+    /** Timeout waiting for response body data in ms (idle). */
+    bodyTimeout?: number;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
+    /** Redirect handling: 'follow' (default) or 'manual' */
+    redirect?: "follow" | "manual";
+    /** Maximum number of redirects to follow (default: 5) */
+    maxRedirects?: number;
+    /** Retry configuration. Set to 0 or false to disable. Default: 0 (no retry). */
+    retry?: number | RetryOptions | false;
+    /** Auto-decompress gzip/deflate response body. Default: true */
+    decompress?: boolean;
+    /** Compress request body with gzip (Uint8Array > 1KB only). Default: false */
+    compressBody?: boolean;
+    /**
+     * Connection strategy: 'compat' (default) uses ALPN negotiation + protocol cache;
+     *  'fast-h1' uses platform TLS for non-CF, WASM TLS h1-only for CF (faster, no h2).
+     */
+    strategy?: "compat" | "fast-h1";
+}
+interface HttpResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    /** Raw headers preserving original order and multi-values */
+    rawHeaders: ReadonlyArray<[string, string]>;
+    protocol: "h2" | "http/1.1";
+    body: ReadableStream<Uint8Array>;
+    /** Read body as text */
+    text(): Promise<string>;
+    /** Read body as JSON */
+    json(): Promise<unknown>;
+    /** Read body as ArrayBuffer */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** Get all Set-Cookie header values as separate strings */
+    getSetCookie(): string[];
+}
+/**
+ * Pre-establish an HTTP/2 connection and place it in the pool.
+ * Subsequent requests to the same origin will reuse this connection,
+ * avoiding TCP + TLS + SETTINGS handshake latency (400-600ms).
+ *
+ * If the origin is behind CF CDN, automatically uses NAT64.
+ * H1-only servers are connected and immediately closed (no pool benefit).
+ */
+declare function preconnect(hostname: string, port?: number): Promise<void>;
+/**
+ * Send an HTTP request over a raw socket, bypassing Cloudflare's cf-* headers.
+ *
+ * If the direct connection is blocked by CF Workers' outbound restrictions,
+ * automatically falls back to NAT64 to reach the target.
+ * @example
+ * ```ts
+ * const response = await request('https://api.openai.com/v1/chat/completions', {
+ *   method: 'POST',
+ *   headers: { 'Authorization': 'Bearer sk-...' },
+ *   body: JSON.stringify({ model: 'gpt-4', messages: [...] })
+ * });
+ * const data = await response.json();
+ * ```
+ */
+declare function request(url: string, options?: RequestOptions): Promise<HttpResponse>;
+declare function normalizeHeaders(headers?: Record<string, string> | Headers): Record<string, string>;
+interface NormalizedRetry {
+    limit: number;
+    methods: Set<string>;
+    statusCodes: Set<number>;
+    maxDelay: number;
+    baseDelay: number;
+}
+declare function normalizeRetry(retry: number | RetryOptions | false | undefined): NormalizedRetry | null;
+declare function calculateRetryDelay(retryAfterHeader: string | undefined, attempt: number, config: {
+    baseDelay: number;
+    maxDelay: number;
+}): number;
+
+export { type HttpResponse, type RequestOptions, type RetryOptions, calculateRetryDelay, normalizeHeaders, normalizeRetry, preconnect, request };