@c9up/eon 0.1.0 → 0.2.0

package/src/tmq/EonConsumer.ts

@@ -0,0 +1,111 @@
+/**
+ * Data subscription — TDengine's TMQ, as a transport-neutral seam.
+ *
+ * eon could write and read; it could not be TOLD when something arrived. TMQ is
+ * how TDengine streams changes to a consumer group, and without it an app that
+ * wants a live dashboard has to poll a `SELECT` on a timer.
+ *
+ * Mirrors {@link EonConnection}'s posture: this file declares the contract and
+ * leaks no ws type, so a native transport can implement the same seam later
+ * without any consumer changing.
+ */
+
+/** Where a consumer group starts when it has no committed offset. */
+export type EonOffsetReset = "earliest" | "latest" | "none";
+
+export interface EonConsumerConfig {
+	/** taosAdapter WebSocket endpoint, e.g. `ws://localhost:6041`. */
+	url: string;
+	/**
+	 * The consumer group.
+	 *
+	 * Two consumers sharing a group split the partitions between them; two with
+	 * DIFFERENT groups each receive everything. Getting this wrong is the
+	 * classic way to either duplicate every message or silently process half.
+	 */
+	groupId: string;
+	/** Identifies this consumer within its group, in server-side diagnostics. */
+	clientId?: string;
+	user?: string;
+	password?: string;
+	token?: string;
+	database?: string;
+	/** Where to start with no committed offset. Default: `latest`. */
+	offsetReset?: EonOffsetReset;
+	/**
+	 * Commit offsets on a timer.
+	 *
+	 * Default FALSE, which deviates from the driver: auto-commit acknowledges
+	 * messages the app may not have finished with, so a crash loses them with no
+	 * trace. Opt in once your handler is idempotent.
+	 */
+	autoCommit?: boolean;
+	/** Auto-commit period in ms. Ignored unless `autoCommit` is true. */
+	autoCommitIntervalMs?: number;
+	/** Include the source table name with each message. Default: true. */
+	withTableName?: boolean;
+}
+
+/** One topic's worth of a poll. */
+export interface EonMessage<T = Record<string, unknown>> {
+	topic: string;
+	rows: T[];
+}
+
+/** A position in one topic's virtual group. */
+export interface EonTopicPartition {
+	topic: string;
+	vgroupId: number;
+	offset?: bigint;
+	begin?: bigint;
+	end?: bigint;
+}
+
+/**
+ * A subscribed consumer.
+ *
+ * The lifecycle is `subscribe` → `poll` in a loop → `commit` → `close`.
+ */
+export interface EonConsumer {
+	/** Start receiving from these topics. Replaces any previous subscription. */
+	subscribe(topics: string[]): Promise<void>;
+	/** The topics currently subscribed to, as the server sees them. */
+	subscription(): Promise<string[]>;
+	/**
+	 * Wait up to `timeoutMs` for messages. Resolves to an empty array on timeout
+	 * — that is a normal quiet period, not an error.
+	 */
+	poll<T = Record<string, unknown>>(
+		timeoutMs: number,
+	): Promise<EonMessage<T>[]>;
+	/** Acknowledge everything polled so far. */
+	commit(): Promise<EonTopicPartition[]>;
+	/** The partitions assigned to this consumer. */
+	assignment(topics?: string[]): Promise<EonTopicPartition[]>;
+	/** Move one partition to an offset. */
+	seek(partition: EonTopicPartition): Promise<void>;
+	/** Stop receiving, without closing the connection. */
+	unsubscribe(): Promise<void>;
+	/** Release the consumer. Safe to call twice. */
+	close(): Promise<void>;
+}
+
+/**
+ * Raised by every consumer operation.
+ *
+ * Follows {@link EonConnectionError}'s shape — the connector's numeric code is
+ * carried verbatim rather than swallowed, so a caller can branch on it.
+ */
+export class EonConsumerError extends Error {
+	/** The underlying TDengine numeric error code, when the failure came from the connector. */
+	readonly code?: number;
+
+	constructor(message: string, options?: { cause?: unknown; code?: number }) {
+		super(
+			message,
+			options?.cause !== undefined ? { cause: options.cause } : undefined,
+		);
+		this.name = "EonConsumerError";
+		this.code = options?.code;
+	}
+}

package/src/tmq/index.ts

@@ -0,0 +1,10 @@
+/** `@c9up/eon/tmq` — data subscription, without the rest of the barrel. */
+export {
+	type EonConsumer,
+	type EonConsumerConfig,
+	EonConsumerError,
+	type EonMessage,
+	type EonOffsetReset,
+	type EonTopicPartition,
+} from "./EonConsumer.js";
+export { connectWsConsumer } from "./websocket.js";

package/src/tmq/websocket.ts

@@ -0,0 +1,217 @@
+/**
+ * WebSocket implementation of {@link EonConsumer}, over `@tdengine/websocket`'s
+ * `WsConsumer` (ws-only via taosAdapter, like the SQL connection).
+ *
+ * Thin by design: the driver already speaks TMQ. What this adds is the seam
+ * (no ws type leaks out), decoded rows instead of a `TaosResult`, one error
+ * type, and two defaults chosen for safety rather than convenience — see
+ * `autoCommit` and `offsetReset`.
+ */
+import {
+	type TaosResult,
+	TDWebSocketClientError,
+	TMQConstants,
+	WsConsumer,
+} from "@tdengine/websocket";
+import {
+	type EonConsumer,
+	type EonConsumerConfig,
+	EonConsumerError,
+	type EonMessage,
+	type EonTopicPartition,
+} from "./EonConsumer.js";
+
+function wrapError(cause: unknown, message: string): EonConsumerError {
+	if (cause instanceof TDWebSocketClientError) {
+		return new EonConsumerError(`${message}: ${cause.message}`, {
+			cause,
+			code: cause.code,
+		});
+	}
+	return new EonConsumerError(message, { cause });
+}
+
+/** Zip a poll result's column metadata with its rows. */
+function decode<T>(result: TaosResult): T[] {
+	const meta = result.getMeta() ?? [];
+	const data = result.getData() ?? [];
+	if (data.length > 0 && meta.length === 0) {
+		// The same trap the query decoder guards: rows with no column metadata
+		// would each decode to `{}` — silent data loss. Fail loud.
+		throw new EonConsumerError(
+			`[E_EON_DECODE] poll returned rows but no column metadata for topic '${result.getTopic()}'; cannot decode`,
+		);
+	}
+	return data.map((row: unknown[]) => {
+		const record: Record<string, unknown> = {};
+		meta.forEach((column, index) => {
+			record[column.name] = row[index];
+		});
+		return record as T;
+	});
+}
+
+function toPartition(p: {
+	topic: string;
+	vgroup_id: number;
+	offset?: bigint;
+	begin?: bigint;
+	end?: bigint;
+}): EonTopicPartition {
+	return {
+		topic: p.topic,
+		vgroupId: p.vgroup_id,
+		offset: p.offset,
+		begin: p.begin,
+		end: p.end,
+	};
+}
+
+/**
+ * Open a consumer against a taosAdapter WebSocket endpoint.
+ *
+ * `autoCommit` defaults to FALSE, where the driver defaults it on. Auto-commit
+ * acknowledges messages the handler may not have finished with, so a crash
+ * drops them silently; a subscription that loses data without saying so is
+ * worse than one that redelivers.
+ */
+export async function connectWsConsumer(
+	config: EonConsumerConfig,
+): Promise<EonConsumer> {
+	const options = new Map<string, string>([
+		[TMQConstants.WS_URL, config.url],
+		[TMQConstants.GROUP_ID, config.groupId],
+		[TMQConstants.AUTO_OFFSET_RESET, config.offsetReset ?? "latest"],
+		[
+			TMQConstants.ENABLE_AUTO_COMMIT,
+			config.autoCommit === true ? "true" : "false",
+		],
+		[
+			TMQConstants.MSG_WITH_TABLE_NAME,
+			config.withTableName === false ? "false" : "true",
+		],
+	]);
+	if (config.clientId) options.set(TMQConstants.CLIENT_ID, config.clientId);
+	if (config.user) options.set(TMQConstants.CONNECT_USER, config.user);
+	if (config.password) options.set(TMQConstants.CONNECT_PASS, config.password);
+	if (config.token) options.set(TMQConstants.CONNECT_TOKEN, config.token);
+	if (config.autoCommit === true && config.autoCommitIntervalMs !== undefined) {
+		options.set(
+			TMQConstants.AUTO_COMMIT_INTERVAL_MS,
+			String(config.autoCommitIntervalMs),
+		);
+	}
+
+	let consumer: WsConsumer;
+	try {
+		consumer = await WsConsumer.newConsumer(options);
+	} catch (error) {
+		throw wrapError(error, `eon: failed to open a consumer on '${config.url}'`);
+	}
+
+	let closed = false;
+	function ensureOpen(): void {
+		if (closed) {
+			throw new EonConsumerError("eon: consumer is closed");
+		}
+	}
+
+	return {
+		async subscribe(topics: string[]): Promise<void> {
+			ensureOpen();
+			if (topics.length === 0) {
+				// An empty subscribe is accepted by the server and then delivers
+				// nothing forever — a silent no-op is the worst possible answer.
+				throw new EonConsumerError("eon: subscribe() needs at least one topic");
+			}
+			try {
+				await consumer.subscribe(topics);
+			} catch (error) {
+				throw wrapError(
+					error,
+					`eon: subscribe failed for [${topics.join(", ")}]`,
+				);
+			}
+		},
+
+		async subscription(): Promise<string[]> {
+			ensureOpen();
+			try {
+				return await consumer.subscription();
+			} catch (error) {
+				throw wrapError(error, "eon: reading the subscription failed");
+			}
+		},
+
+		async poll<T = Record<string, unknown>>(
+			timeoutMs: number,
+		): Promise<EonMessage<T>[]> {
+			ensureOpen();
+			let polled: Map<string, TaosResult>;
+			try {
+				polled = await consumer.poll(timeoutMs);
+			} catch (error) {
+				throw wrapError(error, "eon: poll failed");
+			}
+			const out: EonMessage<T>[] = [];
+			for (const [topic, result] of polled) {
+				out.push({ topic, rows: decode<T>(result) });
+			}
+			return out;
+		},
+
+		async commit(): Promise<EonTopicPartition[]> {
+			ensureOpen();
+			try {
+				return (await consumer.commit()).map(toPartition);
+			} catch (error) {
+				throw wrapError(error, "eon: commit failed");
+			}
+		},
+
+		async assignment(topics?: string[]): Promise<EonTopicPartition[]> {
+			ensureOpen();
+			try {
+				return (await consumer.assignment(topics)).map(toPartition);
+			} catch (error) {
+				throw wrapError(error, "eon: reading the assignment failed");
+			}
+		},
+
+		async seek(partition: EonTopicPartition): Promise<void> {
+			ensureOpen();
+			if (partition.offset === undefined) {
+				throw new EonConsumerError("eon: seek() needs an offset");
+			}
+			try {
+				await consumer.seek({
+					topic: partition.topic,
+					vgroup_id: partition.vgroupId,
+					offset: partition.offset,
+				} as Parameters<WsConsumer["seek"]>[0]);
+			} catch (error) {
+				throw wrapError(error, `eon: seek failed on '${partition.topic}'`);
+			}
+		},
+
+		async unsubscribe(): Promise<void> {
+			ensureOpen();
+			try {
+				await consumer.unsubscribe();
+			} catch (error) {
+				throw wrapError(error, "eon: unsubscribe failed");
+			}
+		},
+
+		async close(): Promise<void> {
+			// Idempotent: a `finally` that closes twice must not throw.
+			if (closed) return;
+			closed = true;
+			try {
+				await consumer.close();
+			} catch (error) {
+				throw wrapError(error, "eon: closing the consumer failed");
+			}
+		},
+	};
+}