nlcurl 0.1.0 → 0.2.0

package/dist/http/h2/client.d.ts

@@ -1,14 +1,16 @@
-/**
- * HTTP/2 client.
- *
- * Multiplexed HTTP/2 client that runs over a TLS Duplex stream.
- * Sends the connection preface with browser-profile-matched SETTINGS
- * and WINDOW_UPDATE for Akamai HTTP/2 fingerprint control.
- */
 import type { Duplex } from 'node:stream';
 import type { NLcURLRequest, RequestTimings } from '../../core/request.js';
 import { NLcURLResponse } from '../../core/response.js';
 import type { H2Profile } from '../../fingerprints/types.js';
+/**
+ * Multiplexed HTTP/2 client that operates over an existing duplex stream.
+ * Handles all aspects of the HTTP/2 connection lifecycle: connection preface,
+ * settings negotiation, flow control (both stream-level and connection-level),
+ * HPACK header compression, and stream multiplexing.
+ *
+ * Create one `H2Client` per underlying TCP/TLS connection; each call to
+ * {@link H2Client.request} or {@link H2Client.streamRequest} opens a new HTTP/2 stream.
+ */
 export declare class H2Client {
     private readonly stream;
     private readonly encoder;
@@ -19,30 +21,95 @@ export declare class H2Client {
     private streams;
     private readBuffer;
     private prefaceSent;
-    private closed;
+    private _closed;
+    private connectionRecvWindow;
+    private initialStreamRecvWindow;
+    private streamRecvWindows;
+    private serverMaxConcurrentStreams;
+    private serverMaxFrameSize;
+    private connectionSendWindow;
+    private initialStreamSendWindow;
+    private streamSendWindows;
+    private pendingSendData;
+    private pendingHeaderStreamId;
+    private pendingHeaderBlock;
+    private pendingHeaderFlags;
+    /**
+     * Optional callback invoked when the underlying connection closes, regardless
+     * of the reason (graceful GOAWAY, remote reset, or network error).
+     *
+     * @type {(() => void) | undefined}
+     */
+    onClose?: () => void;
+    /**
+     * Creates a new H2Client and begins listening for frames on `stream`.
+     *
+     * @param {Duplex}                   stream         - Connected transport stream (TLS or plain TCP).
+     * @param {H2Profile}                [h2Profile]    - Browser HTTP/2 fingerprint settings (SETTINGS frame values,
+     *   window update sizes, and priority frames). Defaults to Chrome-like settings when omitted.
+     * @param {Array<[string, string]>}  [defaultHeaders=[]] - Profile-level request headers prepended to every request.
+     */
     constructor(stream: Duplex, h2Profile?: H2Profile, defaultHeaders?: Array<[string, string]>);
     /**
-     * Send the HTTP/2 connection preface.
+     * Returns `true` if the connection has been closed or destroyed and is no
+     * longer usable.
      *
-     * Must be called before sending any requests.
+     * @returns {boolean} Whether the connection is closed.
+     */
+    get isClosed(): boolean;
+    /**
+     * Sends the HTTP/2 client connection preface (magic PRI bytes) and the
+     * initial SETTINGS frame derived from the browser profile. Idempotent —
+     * calling more than once has no effect.
      */
     sendPreface(): void;
     /**
-     * Send an HTTP/2 request and return the response.
+     * Sends an HTTP/2 request and buffers the entire response body before
+     * resolving. This is the standard (non-streaming) request path.
+     *
+     * @param {NLcURLRequest}             req      - Request descriptor.
+     * @param {Partial<RequestTimings>}   [timings={}] - Partial timings object populated with `firstByte`.
+     * @returns {Promise<NLcURLResponse>} Resolves with the fully received, decompressed response.
+     * @throws {ProtocolError}  If the connection is already closed or stream IDs are exhausted.
+     * @throws {TimeoutError}   If the per-request timeout elapses before a response is received.
      */
     request(req: NLcURLRequest, timings?: Partial<RequestTimings>): Promise<NLcURLResponse>;
     /**
-     * Gracefully close the HTTP/2 connection.
+     * Sends an HTTP/2 request and returns a streaming response. The returned
+     * `NLcURLResponse` resolves once the status and headers are received;
+     * the response body is exposed as a `PassThrough` readable stream via
+     * `response.body`.
+     *
+     * @param {NLcURLRequest}             req      - Request descriptor.
+     * @param {Partial<RequestTimings>}   [timings={}] - Partial timings object populated with `firstByte`.
+     * @returns {Promise<NLcURLResponse>} Resolves once headers are received; body is streamed via `response.body`.
+     * @throws {ProtocolError}  If the connection is already closed or stream IDs are exhausted.
+     * @throws {TimeoutError}   If the per-request timeout elapses before the stream begins.
+     */
+    streamRequest(req: NLcURLRequest, timings?: Partial<RequestTimings>): Promise<NLcURLResponse>;
+    /**
+     * Initiates a graceful shutdown by sending a GOAWAY frame and ending the
+     * underlying stream. In-flight requests will fail with `ProtocolError`.
      */
     close(): void;
+    /**
+     * Immediately destroys the underlying transport stream, aborting all
+     * pending requests with a `ProtocolError`.
+     */
     destroy(): void;
     private buildRequestHeaders;
     private write;
     private onData;
     private processFrames;
     private handleFrame;
+    private processDecodedHeaders;
+    private resolveStreamingResponse;
     private finalizeStream;
-    private onError;
-    private onClose;
+    private applyServerSettings;
+    private consumeRecvWindow;
+    private handleError;
+    private handleClose;
+    private sendDataWithFlowControl;
+    private flushPendingSendData;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/http/h2/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/http/h2/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAmC7D,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;IAEzD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAS;gBAGrB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,SAAS,EACrB,cAAc,GAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM;IAa9C;;;;OAIG;IACH,WAAW,IAAI,IAAI;IA4CnB;;OAEG;IACG,OAAO,CACX,GAAG,EAAE,aAAa,EAClB,OAAO,GAAE,OAAO,CAAC,cAAc,CAAM,GACpC,OAAO,CAAC,cAAc,CAAC;IA8D1B;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb,OAAO,IAAI,IAAI;IAYf,OAAO,CAAC,mBAAmB;IAsD3B,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,WAAW;YAiFL,cAAc;IA8C5B,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,OAAO;CAQhB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/http/h2/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAqC7D;;;;;;;;GAQG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;IAEzD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAS;IAExB,OAAO,CAAC,oBAAoB,CAA+B;IAC3D,OAAO,CAAC,uBAAuB,CAA+B;IAC9D,OAAO,CAAC,iBAAiB,CAA6B;IAEtD,OAAO,CAAC,0BAA0B,CAAY;IAC9C,OAAO,CAAC,kBAAkB,CAAS;IAEnC,OAAO,CAAC,oBAAoB,CAA+B;IAC3D,OAAO,CAAC,uBAAuB,CAA+B;IAC9D,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,eAAe,CAAkF;IAEzG,OAAO,CAAC,qBAAqB,CAAuB;IACpD,OAAO,CAAC,kBAAkB,CAAuB;IACjD,OAAO,CAAC,kBAAkB,CAAa;IAEvC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB;;;;;;;OAOG;gBAED,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,SAAS,EACrB,cAAc,GAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM;IAa9C;;;;;OAKG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;OAIG;IACH,WAAW,IAAI,IAAI;IA8CnB;;;;;;;;;OASG;IACG,OAAO,CACX,GAAG,EAAE,aAAa,EAClB,OAAO,GAAE,OAAO,CAAC,cAAc,CAAM,GACpC,OAAO,CAAC,cAAc,CAAC;IA4D1B;;;;;;;;;;;OAWG;IACG,aAAa,CACjB,GAAG,EAAE,aAAa,EAClB,OAAO,GAAE,OAAO,CAAC,cAAc,CAAM,GACpC,OAAO,CAAC,cAAc,CAAC;IAoE1B;;;OAGG;IACH,KAAK,IAAI,IAAI;IAQb;;;OAGG;IACH,OAAO,IAAI,IAAI;IAcf,OAAO,CAAC,mBAAmB;IAkD3B,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,WAAW;IA4LnB,OAAO,CAAC,qBAAqB;IAuB7B,OAAO,CAAC,wBAAwB;YAuClB,cAAc;IAoD5B,OAAO,CAAC,mBAAmB;IA6B3B,OAAO,CAAC,iBAAiB;IA0BzB,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,uBAAuB;IA0B/B,OAAO,CAAC,oBAAoB;CAuC7B"}