@basmilius/apple-rtsp 0.9.19 → 0.10.1

package/dist/index.d.mts

@@ -1,54 +1,183 @@
 import { Connection, Context } from "@basmilius/apple-common";
 
 //#region src/encoding.d.ts
+/**
+* Supported RTSP/HTTP method verbs used in Apple protocol communication.
+*/
 type Method = "ANNOUNCE" | "FLUSH" | "GET" | "GET_PARAMETER" | "OPTIONS" | "POST" | "PUT" | "RECORD" | "SETUP" | "SET_PARAMETER" | "TEARDOWN";
+/**
+* Parsed RTSP request containing method, path, headers, body, and total byte length.
+*/
 type RtspRequest = {
-  readonly headers: Record<string, string>;
-  readonly method: Method;
-  readonly path: string;
-  readonly body: Buffer;
+  /** Parsed request headers with normalized (capitalized) names. */readonly headers: Record<string, string>; /** The RTSP/HTTP method verb. */
+  readonly method: Method; /** The request target path (e.g. `/info`, `/pair-setup`). */
+  readonly path: string; /** The request body as a raw buffer, empty if no body was present. */
+  readonly body: Buffer; /** Total number of bytes consumed from the input buffer for this request (headers + body). */
   readonly requestLength: number;
 };
+/**
+* Parsed RTSP response wrapping a standard `Response` object alongside the total byte length consumed.
+*/
 type RtspResponse = {
-  readonly response: Response;
+  /** The parsed response as a standard web `Response` object. */readonly response: Response; /** Total number of bytes consumed from the input buffer for this response (headers + body). */
   readonly responseLength: number;
 };
+/**
+* Options for building a serialized RTSP/HTTP response buffer.
+*/
 type BuildResponseOptions = {
-  readonly status: number;
-  readonly statusText: string;
-  readonly headers?: Record<string, string | number>;
-  readonly body?: Buffer;
+  /** HTTP status code (e.g. 200, 404). */readonly status: number; /** HTTP status reason phrase (e.g. "OK", "Not Found"). */
+  readonly statusText: string; /** Additional response headers. Content-Length is set automatically. */
+  readonly headers?: Record<string, string | number>; /** Optional response body. */
+  readonly body?: Buffer; /** Protocol version line prefix. Defaults to `'RTSP/1.0'`. */
   readonly protocol?: "RTSP/1.0" | "HTTP/1.1";
 };
+/**
+* Builds a serialized RTSP/HTTP response buffer from the given options.
+*
+* Automatically sets the `Content-Length` header based on the body size.
+* The resulting buffer is ready to be sent over a TCP socket.
+*
+* @param options - Response configuration including status, headers, and body.
+* @returns A buffer containing the fully formatted response.
+*/
 declare function buildResponse(options: BuildResponseOptions): Buffer;
+/**
+* Attempts to parse an RTSP/HTTP request from the given buffer.
+*
+* Returns `null` if the buffer does not yet contain a complete request
+* (i.e. headers are incomplete or the body has not fully arrived).
+* This allows incremental parsing as TCP data arrives in chunks.
+*
+* @param buffer - The raw input buffer to parse from.
+* @returns The parsed request, or `null` if the buffer is incomplete.
+* @throws Error if the request line is malformed.
+*/
 declare function parseRequest(buffer: Buffer): RtspRequest | null;
+/**
+* Attempts to parse an RTSP/HTTP response from the given buffer.
+*
+* Returns `null` if the buffer does not yet contain a complete response
+* (i.e. headers are incomplete or the body has not fully arrived).
+* This allows incremental parsing as TCP data arrives in chunks.
+*
+* @param buffer - The raw input buffer to parse from.
+* @returns The parsed response wrapped in an {@link RtspResponse}, or `null` if the buffer is incomplete.
+* @throws Error if the status line is malformed.
+*/
 declare function parseResponse(buffer: Buffer): RtspResponse | null;
 //#endregion
 //#region src/client.d.ts
+/**
+* Options for configuring an RTSP/HTTP request-response exchange.
+*/
 type ExchangeOptions = {
-  contentType?: string;
-  headers?: Record<string, string>;
-  body?: Buffer | string | Record<string, unknown>;
-  allowError?: boolean;
-  protocol?: "RTSP/1.0" | "HTTP/1.1";
+  /** Explicit Content-Type header. Automatically set to `application/x-apple-binary-plist` when body is a plain object. */contentType?: string; /** Additional headers to include in the request. Merged after default headers. */
+  headers?: Record<string, string>; /** Request body. Plain objects are serialized as binary plist; strings and buffers are sent as-is. */
+  body?: Buffer | string | Record<string, unknown>; /** When `true`, non-OK responses resolve instead of rejecting with {@link InvalidResponseError}. */
+  allowError?: boolean; /** Protocol version for the request line. Defaults to `'RTSP/1.0'`. */
+  protocol?: "RTSP/1.0" | "HTTP/1.1"; /** Response timeout in milliseconds. Defaults to `HTTP_TIMEOUT`. */
   timeout?: number;
 };
+/**
+* RTSP client for Apple protocol communication over TCP.
+*
+* Extends {@link Connection} with RTSP-specific request/response handling, including
+* CSeq-based request tracking, automatic body serialization (binary plist for objects),
+* and support for encryption via overridable transform hooks. Maintains separate buffers
+* for encrypted and decrypted data to prevent corruption during partial TCP delivery.
+*
+* Subclasses should override {@link transformIncoming} and {@link transformOutgoing} to
+* add encryption/decryption, and {@link getDefaultHeaders} to inject per-request headers.
+*/
 declare class RtspClient extends Connection<{}> {
   #private;
+  /**
+  * Creates a new RTSP client and binds internal event handlers.
+  *
+  * @param context - Device context providing logger and configuration.
+  * @param address - The target host address to connect to.
+  * @param port - The target TCP port to connect to.
+  */
   constructor(context: Context, address: string, port: number);
   /**
-  * Override to provide default headers for every request.
+  * Returns default headers that are included in every outgoing request.
+  *
+  * Override in subclasses to inject session-specific headers (e.g. DACP-ID,
+  * Active-Remote). These headers are placed after CSeq but before any
+  * per-request headers from {@link ExchangeOptions.headers}.
+  *
+  * @returns A record of header name-value pairs.
   */
   protected getDefaultHeaders(): Record<string, string | number>;
   /**
-  * Override to transform incoming data before RTSP parsing (e.g. decryption).
+  * Transforms incoming raw TCP data before RTSP response parsing.
+  *
+  * Override in subclasses to perform decryption. Return `false` if the buffer
+  * does not yet contain enough data for a complete decryption block, signaling
+  * that more data should be accumulated before retrying.
+  *
+  * @param data - The raw (potentially encrypted) incoming data buffer.
+  * @returns The transformed (decrypted) buffer, or `false` if more data is needed.
   */
   protected transformIncoming(data: Buffer): Buffer | false;
   /**
-  * Override to transform outgoing data after RTSP formatting (e.g. encryption).
+  * Transforms outgoing data after RTSP request formatting.
+  *
+  * Override in subclasses to perform encryption on the fully formatted
+  * request buffer before it is written to the socket.
+  *
+  * @param data - The fully formatted RTSP request buffer (headers + body).
+  * @returns The transformed (encrypted) buffer ready for transmission.
   */
   protected transformOutgoing(data: Buffer): Buffer;
+  /**
+  * Sends an RTSP/HTTP request and waits for the matching response.
+  *
+  * Automatically assigns a CSeq header, serializes the body (plain objects become
+  * binary plist), applies outgoing transformation (e.g. encryption), and tracks
+  * the pending response via a timeout-guarded promise.
+  *
+  * @param method - The RTSP/HTTP method verb.
+  * @param path - The request target path.
+  * @param options - Additional request configuration.
+  * @returns The response from the remote device.
+  * @throws TimeoutError if no response is received within the configured timeout.
+  * @throws InvalidResponseError if the response has a non-OK status and `allowError` is not set.
+  */
   protected exchange(method: Method, path: string, options?: ExchangeOptions): Promise<Response>;
+  /**
+  * Handles TCP connection close events.
+  *
+  * Resets both internal buffers and rejects all pending requests with a
+  * {@link ConnectionClosedError}.
+  */
+  onRtspClose(): void;
+  /**
+  * Handles incoming TCP data by accumulating, transforming, and parsing RTSP responses.
+  *
+  * Raw data is first appended to the encrypted buffer, then passed through
+  * {@link transformIncoming} for decryption. The resulting plaintext is appended
+  * to the parse buffer and consumed as complete RTSP responses. Each response is
+  * matched to its pending request via the CSeq header.
+  *
+  * If the buffer exceeds {@link MAX_BUFFER_SIZE}, all buffers are reset and
+  * pending requests are rejected to prevent memory exhaustion.
+  *
+  * @param data - Raw TCP data received from the socket.
+  */
+  onRtspData(data: Buffer): void;
+  /**
+  * Handles socket error events by rejecting all pending requests with the error.
+  *
+  * @param err - The error that occurred on the socket.
+  */
+  onRtspError(err: Error): void;
+  /**
+  * Handles socket timeout events by rejecting all pending requests with a
+  * {@link ConnectionTimeoutError}.
+  */
+  onRtspTimeout(): void;
 }
 //#endregion
 export { type BuildResponseOptions, type ExchangeOptions, type Method, RtspClient, type RtspRequest, type RtspResponse, buildResponse, parseRequest, parseResponse };

package/dist/index.mjs

@@ -2,6 +2,15 @@ import { Connection, ConnectionClosedError, ConnectionTimeoutError, HTTP_TIMEOUT
 import { Plist } from "@basmilius/apple-encoding";
 
 //#region src/encoding.ts
+/**
+* Builds a serialized RTSP/HTTP response buffer from the given options.
+*
+* Automatically sets the `Content-Length` header based on the body size.
+* The resulting buffer is ready to be sent over a TCP socket.
+*
+* @param options - Response configuration including status, headers, and body.
+* @returns A buffer containing the fully formatted response.
+*/
 function buildResponse(options) {
 	const { status, statusText, headers: extraHeaders = {}, body, protocol = "RTSP/1.0" } = options;
 	const headers = {
@@ -17,6 +26,17 @@ function buildResponse(options) {
 	if (body && body.byteLength > 0) return Buffer.concat([Buffer.from(headerLines), body]);
 	return Buffer.from(headerLines);
 }
+/**
+* Attempts to parse an RTSP/HTTP request from the given buffer.
+*
+* Returns `null` if the buffer does not yet contain a complete request
+* (i.e. headers are incomplete or the body has not fully arrived).
+* This allows incremental parsing as TCP data arrives in chunks.
+*
+* @param buffer - The raw input buffer to parse from.
+* @returns The parsed request, or `null` if the buffer is incomplete.
+* @throws Error if the request line is malformed.
+*/
 function parseRequest(buffer) {
 	const headerLength = buffer.indexOf("\r\n\r\n");
 	if (headerLength === -1) return null;
@@ -33,6 +53,17 @@ function parseRequest(buffer) {
 		requestLength
 	};
 }
+/**
+* Attempts to parse an RTSP/HTTP response from the given buffer.
+*
+* Returns `null` if the buffer does not yet contain a complete response
+* (i.e. headers are incomplete or the body has not fully arrived).
+* This allows incremental parsing as TCP data arrives in chunks.
+*
+* @param buffer - The raw input buffer to parse from.
+* @returns The parsed response wrapped in an {@link RtspResponse}, or `null` if the buffer is incomplete.
+* @throws Error if the status line is malformed.
+*/
 function parseResponse(buffer) {
 	const headerLength = buffer.indexOf("\r\n\r\n");
 	if (headerLength === -1) return null;
@@ -51,20 +82,40 @@ function parseResponse(buffer) {
 		responseLength
 	};
 }
+/**
+* Parses raw header lines into a key-value record.
+*
+* Header names are normalized to capitalized form (e.g. `content-length` becomes
+* `Content-Length`) so that lookups work regardless of the sender's casing.
+* Lines without a valid colon separator are silently skipped.
+*
+* @param lines - Individual header lines (without the request/status line).
+* @returns A record mapping normalized header names to their values.
+*/
 function parseHeaders(lines) {
 	const headers = {};
 	for (let i = 0; i < lines.length; i++) {
 		const colon = lines[i].indexOf(":");
 		if (colon <= 0) continue;
-		const name = lines[i].substring(0, colon).trim();
+		const name = lines[i].substring(0, colon).trim().replace(/(^|-)(\w)/g, (_, prefix, char) => prefix + char.toUpperCase());
 		headers[name] = lines[i].substring(colon + 1).trim();
 	}
 	return headers;
 }
+/**
+* Parses the header section of an RTSP/HTTP request buffer into structured components.
+*
+* Extracts the method, path, and headers from the raw header bytes. The first line
+* is expected to match the format `METHOD /path RTSP/1.0` or `METHOD /path HTTP/1.1`.
+*
+* @param buffer - The raw header bytes (up to but not including the `\r\n\r\n` delimiter).
+* @returns An object containing the parsed headers, method, and path.
+* @throws Error if the request line does not match the expected format.
+*/
 function parseRequestHeaders(buffer) {
 	const lines = buffer.toString("utf8").split("\r\n");
-	const rawRequest = lines[0].match(/^(\S+)\s+(\S+)\s+RTSP\/1\.0$/);
-	if (!rawRequest) throw new Error(`Invalid RTSP request line: ${lines[0]}`);
+	const rawRequest = lines[0].match(/^(\S+)\s+(\S+)\s+(?:RTSP|HTTP)\/[\d.]+$/);
+	if (!rawRequest) throw new Error(`Invalid RTSP/HTTP request line: ${lines[0]}`);
 	const method = rawRequest[1];
 	const path = rawRequest[2];
 	return {
@@ -73,6 +124,16 @@ function parseRequestHeaders(buffer) {
 		path
 	};
 }
+/**
+* Parses the header section of an RTSP/HTTP response buffer into structured components.
+*
+* Extracts the status code, status text, and headers from the raw header bytes. The first
+* line is expected to match the format `RTSP/1.0 200 OK` or `HTTP/1.1 200 OK`.
+*
+* @param buffer - The raw header bytes (up to but not including the `\r\n\r\n` delimiter).
+* @returns An object containing the parsed headers, status code, and status text.
+* @throws Error if the status line does not match the expected format.
+*/
 function parseResponseHeaders(buffer) {
 	const lines = buffer.toString("utf8").split("\r\n");
 	const rawStatus = lines[0].match(/(HTTP|RTSP)\/[\d.]+\s+(\d+)\s+(.+)/);
@@ -88,36 +149,97 @@ function parseResponseHeaders(buffer) {
 
 //#endregion
 //#region src/client.ts
+/** Maximum allowed buffer size (2 MB) before resetting to prevent memory exhaustion. */
 const MAX_BUFFER_SIZE = 2 * 1024 * 1024;
+/**
+* RTSP client for Apple protocol communication over TCP.
+*
+* Extends {@link Connection} with RTSP-specific request/response handling, including
+* CSeq-based request tracking, automatic body serialization (binary plist for objects),
+* and support for encryption via overridable transform hooks. Maintains separate buffers
+* for encrypted and decrypted data to prevent corruption during partial TCP delivery.
+*
+* Subclasses should override {@link transformIncoming} and {@link transformOutgoing} to
+* add encryption/decryption, and {@link getDefaultHeaders} to inject per-request headers.
+*/
 var RtspClient = class extends Connection {
+	/** Accumulates decrypted plaintext data waiting to be parsed as RTSP responses. */
 	#buffer = Buffer.alloc(0);
+	/** Accumulates raw encrypted TCP data before transformation/decryption. */
+	#encryptedBuffer = Buffer.alloc(0);
+	/** Monotonically increasing RTSP CSeq counter for request tracking. */
 	#cseq = 0;
+	/** Map of in-flight requests keyed by CSeq, awaiting their matching response. */
 	#requests = /* @__PURE__ */ new Map();
+	/**
+	* Creates a new RTSP client and binds internal event handlers.
+	*
+	* @param context - Device context providing logger and configuration.
+	* @param address - The target host address to connect to.
+	* @param port - The target TCP port to connect to.
+	*/
 	constructor(context, address, port) {
 		super(context, address, port);
-		this.on("close", this.#onClose.bind(this));
-		this.on("data", this.#onData.bind(this));
-		this.on("error", this.#onError.bind(this));
-		this.on("timeout", this.#onTimeout.bind(this));
+		this.onRtspClose = this.onRtspClose.bind(this);
+		this.onRtspData = this.onRtspData.bind(this);
+		this.onRtspError = this.onRtspError.bind(this);
+		this.onRtspTimeout = this.onRtspTimeout.bind(this);
+		this.on("close", this.onRtspClose);
+		this.on("data", this.onRtspData);
+		this.on("error", this.onRtspError);
+		this.on("timeout", this.onRtspTimeout);
 	}
 	/**
-	* Override to provide default headers for every request.
+	* Returns default headers that are included in every outgoing request.
+	*
+	* Override in subclasses to inject session-specific headers (e.g. DACP-ID,
+	* Active-Remote). These headers are placed after CSeq but before any
+	* per-request headers from {@link ExchangeOptions.headers}.
+	*
+	* @returns A record of header name-value pairs.
 	*/
 	getDefaultHeaders() {
 		return {};
 	}
 	/**
-	* Override to transform incoming data before RTSP parsing (e.g. decryption).
+	* Transforms incoming raw TCP data before RTSP response parsing.
+	*
+	* Override in subclasses to perform decryption. Return `false` if the buffer
+	* does not yet contain enough data for a complete decryption block, signaling
+	* that more data should be accumulated before retrying.
+	*
+	* @param data - The raw (potentially encrypted) incoming data buffer.
+	* @returns The transformed (decrypted) buffer, or `false` if more data is needed.
 	*/
 	transformIncoming(data) {
 		return data;
 	}
 	/**
-	* Override to transform outgoing data after RTSP formatting (e.g. encryption).
+	* Transforms outgoing data after RTSP request formatting.
+	*
+	* Override in subclasses to perform encryption on the fully formatted
+	* request buffer before it is written to the socket.
+	*
+	* @param data - The fully formatted RTSP request buffer (headers + body).
+	* @returns The transformed (encrypted) buffer ready for transmission.
 	*/
 	transformOutgoing(data) {
 		return data;
 	}
+	/**
+	* Sends an RTSP/HTTP request and waits for the matching response.
+	*
+	* Automatically assigns a CSeq header, serializes the body (plain objects become
+	* binary plist), applies outgoing transformation (e.g. encryption), and tracks
+	* the pending response via a timeout-guarded promise.
+	*
+	* @param method - The RTSP/HTTP method verb.
+	* @param path - The request target path.
+	* @param options - Additional request configuration.
+	* @returns The response from the remote device.
+	* @throws TimeoutError if no response is received within the configured timeout.
+	* @throws InvalidResponseError if the response has a non-OK status and `allowError` is not set.
+	*/
 	async exchange(method, path, options = {}) {
 		const { contentType, headers: extraHeaders = {}, allowError = false, protocol = "RTSP/1.0", timeout = HTTP_TIMEOUT } = options;
 		let { body } = options;
@@ -165,19 +287,40 @@ var RtspClient = class extends Connection {
 			this.write(data);
 		});
 	}
-	#onClose() {
+	/**
+	* Handles TCP connection close events.
+	*
+	* Resets both internal buffers and rejects all pending requests with a
+	* {@link ConnectionClosedError}.
+	*/
+	onRtspClose() {
 		this.#buffer = Buffer.alloc(0);
+		this.#encryptedBuffer = Buffer.alloc(0);
 		for (const [cseq, { reject }] of this.#requests) {
 			reject(new ConnectionClosedError("Connection closed."));
 			this.#requests.delete(cseq);
 		}
-		this.context.logger.net("[rtsp]", "#onClose()");
+		this.context.logger.net("[rtsp]", "onRtspClose()");
 	}
-	#onData(data) {
+	/**
+	* Handles incoming TCP data by accumulating, transforming, and parsing RTSP responses.
+	*
+	* Raw data is first appended to the encrypted buffer, then passed through
+	* {@link transformIncoming} for decryption. The resulting plaintext is appended
+	* to the parse buffer and consumed as complete RTSP responses. Each response is
+	* matched to its pending request via the CSeq header.
+	*
+	* If the buffer exceeds {@link MAX_BUFFER_SIZE}, all buffers are reset and
+	* pending requests are rejected to prevent memory exhaustion.
+	*
+	* @param data - Raw TCP data received from the socket.
+	*/
+	onRtspData(data) {
 		try {
-			this.#buffer = Buffer.concat([this.#buffer, data]);
-			if (this.#buffer.byteLength > MAX_BUFFER_SIZE) {
-				this.context.logger.error("[rtsp]", `Buffer exceeded max size (${this.#buffer.byteLength} bytes), resetting.`);
+			this.#encryptedBuffer = Buffer.concat([this.#encryptedBuffer, data]);
+			if (this.#encryptedBuffer.byteLength > MAX_BUFFER_SIZE) {
+				this.context.logger.error("[rtsp]", `Buffer exceeded max size (${this.#encryptedBuffer.byteLength} bytes), resetting.`);
+				this.#encryptedBuffer = Buffer.alloc(0);
 				this.#buffer = Buffer.alloc(0);
 				const err = /* @__PURE__ */ new Error("Buffer overflow: exceeded maximum buffer size");
 				for (const [cseq, { reject }] of this.#requests) {
@@ -187,9 +330,10 @@ var RtspClient = class extends Connection {
 				this.emit("error", err);
 				return;
 			}
-			const transformed = this.transformIncoming(this.#buffer);
+			const transformed = this.transformIncoming(this.#encryptedBuffer);
 			if (transformed === false) return;
-			this.#buffer = transformed;
+			this.#encryptedBuffer = Buffer.alloc(0);
+			this.#buffer = Buffer.concat([this.#buffer, transformed]);
 			while (this.#buffer.byteLength > 0) {
 				const result = parseResponse(this.#buffer);
 				if (result === null) return;
@@ -203,24 +347,33 @@ var RtspClient = class extends Connection {
 				} else this.context.logger.warn("[rtsp]", `Unexpected response for CSeq ${cseq}`);
 			}
 		} catch (err) {
-			this.context.logger.error("[rtsp]", "#onData()", err);
+			this.context.logger.error("[rtsp]", "onRtspData()", err);
 			this.emit("error", err);
 		}
 	}
-	#onError(err) {
+	/**
+	* Handles socket error events by rejecting all pending requests with the error.
+	*
+	* @param err - The error that occurred on the socket.
+	*/
+	onRtspError(err) {
 		for (const [cseq, { reject }] of this.#requests) {
 			reject(err);
 			this.#requests.delete(cseq);
 		}
-		this.context.logger.error("[rtsp]", "#onError()", err);
+		this.context.logger.error("[rtsp]", "onRtspError()", err);
 	}
-	#onTimeout() {
+	/**
+	* Handles socket timeout events by rejecting all pending requests with a
+	* {@link ConnectionTimeoutError}.
+	*/
+	onRtspTimeout() {
 		const err = new ConnectionTimeoutError();
 		for (const [cseq, { reject }] of this.#requests) {
 			reject(err);
 			this.#requests.delete(cseq);
 		}
-		this.context.logger.net("[rtsp]", "#onTimeout()");
+		this.context.logger.net("[rtsp]", "onRtspTimeout()");
 	}
 };
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@basmilius/apple-rtsp",
     "description": "RTSP protocol implementation for Apple Protocols.",
-    "version": "0.9.19",
+    "version": "0.10.1",
     "type": "module",
     "license": "MIT",
     "author": {
@@ -42,8 +42,8 @@
         }
     },
     "dependencies": {
-        "@basmilius/apple-common": "0.9.19",
-        "@basmilius/apple-encoding": "0.9.19"
+        "@basmilius/apple-common": "0.10.1",
+        "@basmilius/apple-encoding": "0.10.1"
     },
     "devDependencies": {
         "@types/bun": "^1.3.11",