@corewire/core 0.0.0 → 1.0.0-next.2

package/dist/reporter-DfM6vPT0.mjs

@@ -0,0 +1,223 @@
+//#region src/reporter.ts
+const ALL_GROUPS = [
+	"debug",
+	"error",
+	"info",
+	"net",
+	"raw",
+	"warn"
+];
+/**
+* Logs under an identifier, usually a device id. The global {@link reporter} decides which groups
+* print.
+*/
+var Logger = class {
+	/** The identifier this logger is scoped to. */
+	get id() {
+		return this.#id;
+	}
+	/** ANSI-colored label prefix used in log output. */
+	get label() {
+		return this.#label;
+	}
+	#id;
+	#label;
+	#sink;
+	/**
+	* @param id - Prefix of every line, usually a device id.
+	* @param sink - Also receives every record of this logger, next to the global reporter.
+	*/
+	constructor(id, sink) {
+		this.#id = id;
+		this.#label = `\u001b[36m[${id}]\u001b[39m`;
+		this.#sink = sink;
+	}
+	/** Logs in the `debug` group, in cyan. */
+	debug(...data) {
+		this.#write("debug", data);
+	}
+	/** Logs in the `error` group, in red. */
+	error(...data) {
+		this.#write("error", data);
+	}
+	/** Logs in the `info` group, in green. */
+	info(...data) {
+		this.#write("info", data);
+	}
+	/** Logs in the `net` group, in yellow. */
+	net(...data) {
+		this.#write("net", data);
+	}
+	/** Logs in the `raw` group, in blue; meant for hex dumps and binary protocol data. */
+	raw(...data) {
+		this.#write("raw", data);
+	}
+	/** Logs in the `warn` group, in yellow. */
+	warn(...data) {
+		this.#write("warn", data);
+	}
+	/**
+	* Hands one protocol message to the traffic sink. Does nothing without a sink, so callers
+	* that have to build `decoded` first should check {@link Reporter.tapsTraffic}.
+	*
+	* @param direction - `out` for what we sent, `in` for what the device sent.
+	*/
+	traffic(protocol, direction, summary, decoded, bytes) {
+		reporter.reportTraffic({
+			deviceId: this.#id,
+			protocol,
+			direction,
+			summary,
+			decoded,
+			bytes,
+			timestamp: Date.now()
+		});
+	}
+	#write(group, data) {
+		write(group, this.#id, this.#label, data);
+		if (!this.#sink) return;
+		try {
+			this.#sink(group, data);
+		} catch {}
+	}
+};
+/**
+* Decides which log groups print, and where log records and traffic go. Every {@link Logger}
+* goes through the {@link reporter} singleton.
+*/
+var Reporter = class {
+	#enabled = [];
+	#sink = null;
+	#sinkGroups = ALL_GROUPS;
+	#silenceConsole = false;
+	#trafficSink = null;
+	/** Whether a traffic sink is installed. */
+	get tapsTraffic() {
+		return this.#trafficSink !== null;
+	}
+	/** Enables every group except the verbose `raw`. */
+	all() {
+		this.#enabled = [
+			"debug",
+			"error",
+			"info",
+			"net",
+			"warn"
+		];
+	}
+	/** Disables every group. */
+	none() {
+		this.#enabled = [];
+	}
+	disable(group) {
+		if (this.#enabled.includes(group)) this.#enabled.splice(this.#enabled.indexOf(group), 1);
+	}
+	enable(group) {
+		if (!this.#enabled.includes(group)) this.#enabled.push(group);
+	}
+	/** Whether a group reaches the console or the sink, so a caller can skip building an expensive message. */
+	accepts(group) {
+		return this.printsToConsole(group) || this.#sink !== null && this.#sinkGroups.includes(group);
+	}
+	isEnabled(group) {
+		return this.#enabled.includes(group);
+	}
+	/**
+	* Installs a sink that receives one record per logging call, whichever groups print. Replaces
+	* a sink that was already installed.
+	*/
+	setSink(sink, options = {}) {
+		this.#sink = sink;
+		this.#sinkGroups = options.groups ?? ALL_GROUPS;
+		this.#silenceConsole = options.silenceConsole === true;
+	}
+	/** Removes the installed sink and restores console output. */
+	clearSink() {
+		this.#sink = null;
+		this.#sinkGroups = ALL_GROUPS;
+		this.#silenceConsole = false;
+	}
+	/** Installs a sink that receives every tapped protocol message. Replaces a sink that was already installed. */
+	setTrafficSink(sink) {
+		this.#trafficSink = sink;
+	}
+	/** Removes the installed traffic sink. */
+	clearTrafficSink() {
+		this.#trafficSink = null;
+	}
+	/** Hands one entry to the traffic sink, swallowing a failing sink like {@link report} does. */
+	reportTraffic(entry) {
+		if (this.#trafficSink === null) return;
+		try {
+			this.#trafficSink(entry);
+		} catch {}
+	}
+	/** Whether a group still reaches the console. False while a sink silences the console. */
+	printsToConsole(group) {
+		return !this.#silenceConsole && this.#enabled.includes(group);
+	}
+	/**
+	* Hands one record to the installed sink. A throwing sink must never take the caller down
+	* with it, so this swallows the failure.
+	*
+	* @param deviceId - The logger identifier, or null when there is none.
+	*/
+	report(group, deviceId, args) {
+		if (this.#sink === null || !this.#sinkGroups.includes(group)) return;
+		try {
+			this.#sink({
+				group,
+				deviceId,
+				args,
+				timestamp: Date.now()
+			});
+		} catch {}
+	}
+};
+/** How each group prints: the console method and the ANSI color of its tag. */
+const CONSOLE = {
+	debug: {
+		method: "debug",
+		color: "36"
+	},
+	error: {
+		method: "error",
+		color: "31"
+	},
+	info: {
+		method: "info",
+		color: "32"
+	},
+	net: {
+		method: "info",
+		color: "33"
+	},
+	raw: {
+		method: "log",
+		color: "34"
+	},
+	warn: {
+		method: "warn",
+		color: "33"
+	}
+};
+/**
+* The one path every {@link Logger} method takes. The console prints only the enabled groups; the
+* sink sees every record, whether or not it printed.
+*
+* @param id - The logger identifier, or null when the record has no logger.
+* @param label - ANSI-colored prefix printed before the values.
+*/
+function write(group, id, label, data) {
+	reporter.report(group, id, data);
+	if (!reporter.printsToConsole(group)) return;
+	const { method, color } = CONSOLE[group];
+	const tag = `\u001b[${color}m[${group}]\u001b[39m`;
+	if (label === null) console[method](tag, ...data);
+	else console[method](tag, label, ...data);
+}
+/** The global {@link Reporter} that decides which log groups print. */
+const reporter = new Reporter();
+
+//#endregion
+export { reporter as n, Logger as t };

package/dist/reporter-Dn7n2TXN.d.mts

@@ -0,0 +1,112 @@
+//#region src/reporter.d.ts
+/** A log group. The global {@link reporter} turns each group on or off. */
+type DebugGroup = "debug" | "error" | "info" | "net" | "raw" | "warn";
+/** One log record, as a {@link ReporterSink} receives it. */
+type ReporterEntry = {
+  readonly group: DebugGroup; /** The {@link Logger} identifier, or `null` for output not tied to a logger. */
+  readonly deviceId: string | null; /** The values passed to the logging method, unformatted. */
+  readonly args: readonly unknown[]; /** Wall-clock milliseconds since the Unix epoch. */
+  readonly timestamp: number;
+};
+/** Receives every log record, whether or not its group prints to the console. */
+type ReporterSink = (entry: ReporterEntry) => void;
+/** Options for {@link Reporter.setSink}. */
+type ReporterSinkOptions = {
+  /** Stops console output entirely while the sink is installed. Default: false. */readonly silenceConsole?: boolean; /** Limits which groups reach the sink. Default: every group. */
+  readonly groups?: readonly DebugGroup[];
+};
+/** The label of the channel a tapped message crossed; each protocol package picks its own. */
+type TrafficProtocol = string;
+type TrafficDirection = "in" | "out";
+/** One protocol message as it crossed the wire, after decryption or before encryption. */
+type TrafficEntry = {
+  /** The {@link Logger} identifier of the device the message belongs to. */readonly deviceId: string | null;
+  readonly protocol: TrafficProtocol;
+  readonly direction: TrafficDirection; /** One line that identifies the message, for example `SETUP /stream cseq=4`. */
+  readonly summary: string; /** The decoded message, when the caller has one. */
+  readonly decoded?: unknown; /** The plaintext frame. */
+  readonly bytes?: Uint8Array; /** Wall-clock milliseconds since the Unix epoch. */
+  readonly timestamp: number;
+};
+type TrafficSink = (entry: TrafficEntry) => void;
+/** Receives every record of one {@link Logger}, whichever groups the global reporter prints. */
+type LogSink = (group: DebugGroup, args: readonly unknown[]) => void;
+/**
+* Logs under an identifier, usually a device id. The global {@link reporter} decides which groups
+* print.
+*/
+declare class Logger {
+  #private;
+  /** The identifier this logger is scoped to. */
+  get id(): string;
+  /** ANSI-colored label prefix used in log output. */
+  get label(): string;
+  /**
+  * @param id - Prefix of every line, usually a device id.
+  * @param sink - Also receives every record of this logger, next to the global reporter.
+  */
+  constructor(id: string, sink?: LogSink);
+  /** Logs in the `debug` group, in cyan. */
+  debug(...data: any[]): void;
+  /** Logs in the `error` group, in red. */
+  error(...data: any[]): void;
+  /** Logs in the `info` group, in green. */
+  info(...data: any[]): void;
+  /** Logs in the `net` group, in yellow. */
+  net(...data: any[]): void;
+  /** Logs in the `raw` group, in blue; meant for hex dumps and binary protocol data. */
+  raw(...data: any[]): void;
+  /** Logs in the `warn` group, in yellow. */
+  warn(...data: any[]): void;
+  /**
+  * Hands one protocol message to the traffic sink. Does nothing without a sink, so callers
+  * that have to build `decoded` first should check {@link Reporter.tapsTraffic}.
+  *
+  * @param direction - `out` for what we sent, `in` for what the device sent.
+  */
+  traffic(protocol: TrafficProtocol, direction: TrafficDirection, summary: string, decoded?: unknown, bytes?: Uint8Array): void;
+}
+/**
+* Decides which log groups print, and where log records and traffic go. Every {@link Logger}
+* goes through the {@link reporter} singleton.
+*/
+declare class Reporter {
+  #private;
+  /** Whether a traffic sink is installed. */
+  get tapsTraffic(): boolean;
+  /** Enables every group except the verbose `raw`. */
+  all(): void;
+  /** Disables every group. */
+  none(): void;
+  disable(group: DebugGroup): void;
+  enable(group: DebugGroup): void;
+  /** Whether a group reaches the console or the sink, so a caller can skip building an expensive message. */
+  accepts(group: DebugGroup): boolean;
+  isEnabled(group: DebugGroup): boolean;
+  /**
+  * Installs a sink that receives one record per logging call, whichever groups print. Replaces
+  * a sink that was already installed.
+  */
+  setSink(sink: ReporterSink, options?: ReporterSinkOptions): void;
+  /** Removes the installed sink and restores console output. */
+  clearSink(): void;
+  /** Installs a sink that receives every tapped protocol message. Replaces a sink that was already installed. */
+  setTrafficSink(sink: TrafficSink): void;
+  /** Removes the installed traffic sink. */
+  clearTrafficSink(): void;
+  /** Hands one entry to the traffic sink, swallowing a failing sink like {@link report} does. */
+  reportTraffic(entry: TrafficEntry): void;
+  /** Whether a group still reaches the console. False while a sink silences the console. */
+  printsToConsole(group: DebugGroup): boolean;
+  /**
+  * Hands one record to the installed sink. A throwing sink must never take the caller down
+  * with it, so this swallows the failure.
+  *
+  * @param deviceId - The logger identifier, or null when there is none.
+  */
+  report(group: DebugGroup, deviceId: string | null, args: readonly unknown[]): void;
+}
+/** The global {@link Reporter} that decides which log groups print. */
+declare const reporter: Reporter;
+//#endregion
+export { ReporterEntry as a, TrafficDirection as c, TrafficSink as d, reporter as f, Reporter as i, TrafficEntry as l, LogSink as n, ReporterSink as o, Logger as r, ReporterSinkOptions as s, DebugGroup as t, TrafficProtocol as u };

package/dist/transport-C4BMdD2J.mjs

@@ -0,0 +1,270 @@
+import { a as ConnectionError, i as ConnectionClosedError, o as ConnectionTimeoutError } from "./errors-DVv1n4fL.mjs";
+import { t as Logger } from "./reporter-DfM6vPT0.mjs";
+import { Socket } from "node:net";
+import { EventEmitter } from "node:events";
+
+//#region src/const.ts
+/** Timeout in milliseconds for TCP socket connections during initial connect. Matches Apple's 30s default. */
+const SOCKET_TIMEOUT = 3e4;
+
+//#endregion
+//#region src/transport/connection.ts
+/**
+* One TCP socket to a device, with keep-alive and no-delay. Subclasses extend the event map with
+* protocol events.
+*
+* A connection connects once and ends once. Every way it ends, `disconnect()` and `destroy()`
+* included, emits `closed` with the reason and aborts {@link signal}. Reconnecting takes a new
+* connection, because a fresh socket carries no pairing and no encryption keys. `error` reports
+* problems that do not end the connection by themselves, such as a write after the socket closed.
+*/
+var Connection = class extends EventEmitter {
+	get address() {
+		return this.#address;
+	}
+	get context() {
+		return this.#context;
+	}
+	get port() {
+		return this.#port;
+	}
+	get isConnected() {
+		return this.#state === "connected";
+	}
+	/** The local IP address of the socket, or `0.0.0.0` when it is not connected. */
+	get localAddress() {
+		return this.#socket?.localAddress ?? "0.0.0.0";
+	}
+	get state() {
+		return this.#state;
+	}
+	/** Aborts with a {@link ConnectionClosedError} when the connection ends. */
+	get signal() {
+		return this.#controller.signal;
+	}
+	#address;
+	#port;
+	#context;
+	#controller = new AbortController();
+	#connectPromise;
+	#debug = false;
+	#socket;
+	#state = "disconnected";
+	constructor(context, address, port) {
+		super();
+		this.#address = address;
+		this.#port = port;
+		this.#context = context;
+	}
+	/**
+	* Opens the socket. Returns at once when already connected.
+	*
+	* @throws {ConnectionTimeoutError} If the socket does not open within the socket timeout.
+	* @throws {ConnectionError} If the socket cannot open, or the connection is busy or has ended.
+	*/
+	async connect() {
+		if (this.#state === "connected") return;
+		if (this.signal.aborted) throw new ConnectionClosedError("This connection has ended, create a new one.");
+		if (this.#state !== "disconnected") throw new ConnectionError("A connection is already being established.");
+		this.#state = "connecting";
+		const connected = new Promise((resolve, reject) => {
+			this.#connectPromise = {
+				resolve,
+				reject
+			};
+		});
+		const socket = new Socket();
+		this.#socket = socket;
+		socket.setNoDelay(true);
+		socket.setTimeout(SOCKET_TIMEOUT);
+		socket.on("close", () => this.#onClose());
+		socket.on("connect", () => this.#onConnect());
+		socket.on("data", (data) => this.#onData(data));
+		socket.on("error", (error) => this.#onError(error));
+		socket.on("timeout", () => this.#onTimeout());
+		this.#context.logger.net(`Connecting to ${this.#address}:${this.#port}...`);
+		socket.connect({
+			host: this.#address,
+			port: this.#port
+		});
+		return connected;
+	}
+	/**
+	* Ends the connection right away without a graceful shutdown. Passing an error ends it with
+	* reason `error`, for a subclass that cannot continue after a broken frame.
+	*/
+	destroy(error) {
+		if (this.#state === "disconnected" && !this.#socket) return;
+		this.#end(error ? "error" : "local", error);
+	}
+	/** Ends the socket gracefully and resolves once it is closed. */
+	async disconnect() {
+		const socket = this.#socket;
+		if (!socket || this.signal.aborted) return;
+		if (socket.connecting || socket.destroyed) {
+			this.#end("local");
+			return;
+		}
+		const closed = new Promise((resolve) => this.signal.addEventListener("abort", () => resolve(), { once: true }));
+		if (this.#state !== "closing") {
+			this.#state = "closing";
+			socket.end();
+		}
+		await closed;
+	}
+	/** Toggles hex and ASCII dumps of incoming data. */
+	debug(enabled) {
+		this.#debug = enabled;
+		return this;
+	}
+	/** Writes to the socket, or emits `error` when the socket is not writable. */
+	write(data) {
+		if (!this.#socket || this.#state !== "connected" || !this.#socket.writable) {
+			this.#reportError(new ConnectionClosedError("Cannot write to a disconnected connection."));
+			return;
+		}
+		this.#socket.write(data, (error) => {
+			if (!error || this.signal.aborted) return;
+			this.#context.logger.error("Failed to write data to socket.");
+			this.#reportError(error);
+		});
+	}
+	/** Ends the connection, the one exit for every path. It closes the socket, settles a pending connect, aborts the signal and emits `closed`. */
+	#end(reason, error) {
+		if (this.signal.aborted) return;
+		const socket = this.#socket;
+		this.#socket = void 0;
+		this.#state = reason === "error" || reason === "timeout" ? "failed" : "disconnected";
+		if (socket) {
+			socket.removeAllListeners();
+			socket.on("error", () => {});
+			socket.destroy();
+		}
+		this.#context.logger.net(`Connection closed (${reason}${error ? `: ${error.message}` : ""}).`);
+		this.#controller.abort(new ConnectionClosedError(`Connection closed (${reason}).`));
+		if (this.#connectPromise) {
+			this.#connectPromise.reject(error ?? new ConnectionClosedError("Connection closed before it was established."));
+			this.#connectPromise = void 0;
+		}
+		this.#emitInternal("closed", reason, error);
+	}
+	#onClose() {
+		this.#end(this.#state === "closing" ? "local" : "remote");
+	}
+	#onConnect() {
+		this.#state = "connected";
+		this.#socket.setKeepAlive(true, 1e4);
+		this.#socket.setTimeout(0);
+		const pending = this.#connectPromise;
+		this.#connectPromise = void 0;
+		this.#emitInternal("connect");
+		pending?.resolve();
+	}
+	#onData(data) {
+		if (this.#debug) {
+			const cutoff = Math.min(data.byteLength, 64);
+			this.#context.logger.debug(`Received ${data.byteLength} bytes of data.`);
+			this.#context.logger.debug(`hex=${data.subarray(0, cutoff).toString("hex")}`);
+			this.#context.logger.debug(`ascii=${data.toString("ascii").replace(/[^\x20-\x7E]/g, ".").substring(0, cutoff)}`);
+		}
+		this.#emitInternal("data", data);
+	}
+	#onError(error) {
+		this.#context.logger.error(`Connection error: ${error.message}`);
+		if (this.#state === "connecting") {
+			this.#end("error", new ConnectionError(`Cannot connect to ${this.#address}:${this.#port}: ${error.message}`));
+			return;
+		}
+		this.#end("error", error);
+	}
+	/** Fires only while connecting, because the idle timeout goes off once the socket opens. */
+	#onTimeout() {
+		this.#context.logger.error("Connection timed out.");
+		this.#end("timeout", new ConnectionTimeoutError());
+	}
+	/** Emits `error` when someone listens, because an unhandled `error` event would throw. */
+	#reportError(error) {
+		if (this.listenerCount("error") > 0) this.#emitInternal("error", error);
+		else this.#context.logger.warn("No error handler registered.", this.constructor.name, error.message);
+	}
+	/** The merged event map makes the inherited emit signature too broad to call directly. */
+	#emitInternal(event, ...args) {
+		return this.emit(event, ...args);
+	}
+};
+
+//#endregion
+//#region src/transport/context.ts
+/** The name every protocol presents for this client when the identity has none. */
+const DEFAULT_CLIENT_NAME = "CoreWire";
+/**
+* Travels through every protocol layer of one device connection, so all layers log under the
+* same device id and present the same identity.
+*/
+var Context = class {
+	/** Identifies the target device, usually by its mDNS host name. */
+	get deviceId() {
+		return this.#deviceId;
+	}
+	/** The identity overrides this client presents; a protocol fills the rest with its defaults. */
+	get identity() {
+		return this.#identity;
+	}
+	/** Prefixes its output with the device id. */
+	get logger() {
+		return this.#logger;
+	}
+	#deviceId;
+	#identity;
+	#logger;
+	/**
+	* @param sink - Also receives every log record of this context.
+	*/
+	constructor(deviceId, identity = {}, sink) {
+		this.#deviceId = deviceId;
+		this.#identity = { ...identity };
+		this.#logger = new Logger(deviceId, sink);
+	}
+};
+
+//#endregion
+//#region src/transport/encryption.ts
+/** Builds the 12-byte ChaCha20-Poly1305 nonce for a message counter. */
+function buildNonce(counter, format) {
+	const nonce = Buffer.alloc(12);
+	nonce.writeBigUInt64LE(BigInt(counter), format === "counter-at-0" ? 0 : 4);
+	return nonce;
+}
+/**
+* Connection that can switch to ChaCha20-Poly1305 once pairing yields keys. Subclasses frame and
+* encrypt with the {@link EncryptionState}, because every protocol frames differently.
+*/
+var EncryptionAwareConnection = class extends Connection {
+	get isEncrypted() {
+		return !!this.#encryption;
+	}
+	/** Keys and counters once {@link enableEncryption} ran; for the subclass that frames the messages. */
+	get encryption() {
+		return this.#encryption;
+	}
+	#encryption;
+	enableEncryption(readKey, writeKey) {
+		this.#encryption = new EncryptionState(readKey, writeKey);
+	}
+};
+/** Keys and per-direction message counters of one encrypted connection. */
+var EncryptionState = class {
+	readKey;
+	readCount;
+	writeKey;
+	writeCount;
+	constructor(readKey, writeKey) {
+		this.readCount = 0;
+		this.readKey = readKey;
+		this.writeCount = 0;
+		this.writeKey = writeKey;
+	}
+};
+
+//#endregion
+export { DEFAULT_CLIENT_NAME as a, Context as i, EncryptionState as n, Connection as o, buildNonce as r, EncryptionAwareConnection as t };

package/dist/transport.d.mts

@@ -0,0 +1,2 @@
+import { a as Connection, c as Context, i as buildNonce, l as DEFAULT_CLIENT_NAME, n as EncryptionState, o as CloseReason, r as NonceFormat, s as ConnectionState, t as EncryptionAwareConnection, u as DeviceIdentity } from "./index-BJKNwUmq.mjs";
+export { type CloseReason, Connection, type ConnectionState, Context, DEFAULT_CLIENT_NAME, type DeviceIdentity, EncryptionAwareConnection, EncryptionState, type NonceFormat, buildNonce };

package/dist/transport.mjs

@@ -0,0 +1,3 @@
+import { a as DEFAULT_CLIENT_NAME, i as Context, n as EncryptionState, o as Connection, r as buildNonce, t as EncryptionAwareConnection } from "./transport-C4BMdD2J.mjs";
+
+export { Connection, Context, DEFAULT_CLIENT_NAME, EncryptionAwareConnection, EncryptionState, buildNonce };

package/dist/types-qzabRJJ9.d.mts

@@ -0,0 +1,5 @@
+//#region src/types.d.ts
+/** Generic event map type used as a constraint for typed EventEmitter subclasses. */
+type EventMap = Record<string, any>;
+//#endregion
+export { EventMap as t };

package/dist/utils-DY5OKUuy.mjs

@@ -0,0 +1,8 @@
+//#region src/utils.ts
+/** Resolves after `ms` milliseconds. */
+async function waitFor(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+//#endregion
+export { waitFor as t };