@c9up/eon 0.1.0

package/src/EonProvider.ts

@@ -0,0 +1,222 @@
+/**
+ * EonProvider — Ream provider for the Eon time-series layer.
+ *
+ * On boot it opens the configured ws-first TDengine connection(s) via
+ * `connectWsEon` and registers them in the container (`eon` / `eon.connection`
+ * / `eon:<name>`), plus the module-level `services/connection` singleton. The
+ * transport-independent compiler is registered under `eon.compiler`. Shutdown
+ * closes every connection (fail-open) and releases the singletons.
+ *
+ * Agnostic leaf: consumes the host framework's app context STRUCTURALLY — it
+ * never imports `@c9up/ream`. Any context exposing `config.get(key)` and
+ * `container.singleton(token, factory)` satisfies the contract.
+ */
+
+import type { EonConfig, EonConnectionConfig } from "./connection/config.js";
+import type { EonConnection } from "./connection/EonConnection.js";
+import { connectWsEon } from "./connection/websocket.js";
+import {
+	type CompiledStatement,
+	compileStatementNative,
+	type EonDialect,
+} from "./query/native.js";
+
+/**
+ * Structural slice of the host framework's app context — only the surface
+ * EonProvider uses. Mirrors atlas `AtlasAppContext`. The `token` type mirrors
+ * ream's `ServiceToken` union so this can grow into Symbol/ctor tokens without
+ * re-coupling to `@c9up/ream`; EonProvider uses `string` tokens today.
+ */
+export interface EonAppContext {
+	container: {
+		singleton(
+			token: string | symbol | (new (...args: never[]) => unknown),
+			factory: () => unknown,
+		): void;
+	};
+	config: { get<T = unknown>(key: string): T | undefined };
+}
+
+/**
+ * The transport-independent compiler service registered under `eon.compiler`.
+ */
+export interface EonService {
+	compile(spec: object, dialect?: EonDialect): CompiledStatement;
+}
+
+/**
+ * How EonProvider opens a connection. Defaults to `connectWsEon`; tests inject a
+ * fake so the boot/shutdown wiring is exercised without a live TDengine server
+ * (eon has no in-process transport, unlike atlas's sqlite).
+ */
+export type EonConnector = (
+	config: EonConnectionConfig,
+) => Promise<EonConnection>;
+
+export class EonProvider {
+	readonly #app: EonAppContext;
+	readonly #connect: EonConnector;
+	/** connection name → open connection. Populated at boot. */
+	readonly #connections = new Map<string, EonConnection>();
+	/** Set once a full boot opened connections — guards against a leaking re-boot. */
+	#booted = false;
+
+	constructor(app: EonAppContext, connect: EonConnector = connectWsEon) {
+		this.#app = app;
+		this.#connect = connect;
+	}
+
+	register(): void {}
+
+	async boot(): Promise<void> {
+		if (this.#booted) {
+			throw new Error(
+				"EonProvider: boot() has already opened connections; a second boot would overwrite and leak them. Call shutdown() first, or construct a new provider.",
+			);
+		}
+		// The compiler is transport-independent — register it unconditionally.
+		const service: EonService = {
+			compile: (spec, dialect) => compileStatementNative(spec, dialect),
+		};
+		this.#app.container.singleton("eon.compiler", () => service);
+
+		const config =
+			this.#app.config.get<EonConfig>("timeseries") ??
+			this.#app.config.get<EonConfig>("eon");
+		if (!config) return;
+
+		const { connections, defaultName } = this.#resolveConnections(config);
+
+		// Open every connection in parallel. `allSettled` lets us distinguish
+		// successes from failures without leaking the already-opened ones: on any
+		// failure we close every success before rethrowing (no partial-boot leak).
+		const entries = Object.entries(connections);
+		const results = await Promise.allSettled(
+			entries.map(([, settings]) => this.#connect(settings)),
+		);
+		const failures: Array<{ name: string; error: unknown }> = [];
+		const successes: Array<{ name: string; conn: EonConnection }> = [];
+		results.forEach((result, i) => {
+			const entry = entries[i];
+			if (!entry) return; // unreachable — allSettled preserves length/order
+			const [name] = entry;
+			if (result.status === "fulfilled") {
+				successes.push({ name, conn: result.value });
+			} else {
+				failures.push({ name, error: result.reason });
+			}
+		});
+		const first = failures[0];
+		if (first) {
+			await Promise.allSettled(successes.map((s) => s.conn.close()));
+			const others = failures
+				.slice(1)
+				.map((f) => `${f.name}: ${String(f.error)}`)
+				.join("; ");
+			throw new Error(
+				`EonProvider: failed to open ${failures.length} connection(s) — ` +
+					`'${first.name}' failed: ${String(first.error)}` +
+					(others ? ` (also: ${others})` : ""),
+			);
+		}
+
+		for (const { name, conn } of successes) {
+			this.#connections.set(name, conn);
+		}
+
+		const defaultConn = this.#connections.get(defaultName);
+		if (!defaultConn) {
+			// Same rollback the connect-failure branch does above — close the
+			// already-opened sockets before throwing, else they leak (and #booted
+			// stays false, so a retry would open even more).
+			await Promise.allSettled(
+				[...this.#connections.values()].map((conn) => conn.close()),
+			);
+			this.#connections.clear();
+			throw new Error(
+				`EonProvider: default connection '${defaultName}' is not defined in config.timeseries.connections`,
+			);
+		}
+		// Register the container singletons only AFTER validation succeeds. The
+		// throw path above registers none, so a failed boot never leaves an
+		// `eon:<name>` factory resolving to a now-closed connection.
+		for (const { name, conn } of successes) {
+			this.#app.container.singleton(`eon:${name}`, () => conn);
+		}
+		this.#app.container.singleton("eon", () => defaultConn);
+		this.#app.container.singleton("eon.connection", () => defaultConn);
+
+		// Populate the `@c9up/eon/services/connection` singleton so apps can
+		// `import connection from '@c9up/eon/services/connection'` anywhere. Lazy
+		// import so a type-only discovery scan does not pull the module at
+		// construction time.
+		const { setConnection } = await import("./services/connection.js");
+		setConnection(defaultConn);
+		this.#booted = true;
+	}
+
+	async shutdown(): Promise<void> {
+		// Close every connection in parallel. `allSettled` (fail-open) so a single
+		// stuck close doesn't block the rest, but failures are aggregated and
+		// rethrown so supervisors see a non-zero shutdown signal. The map + module
+		// singleton are cleared unconditionally (never hand out closed handles).
+		const named = [...this.#connections.entries()];
+		const results = await Promise.allSettled(named.map(([, c]) => c.close()));
+		this.#connections.clear();
+		this.#booted = false; // allow a fresh boot() after a clean shutdown
+
+		const { clearConnection } = await import("./services/connection.js");
+		for (const [, conn] of named) clearConnection(conn);
+
+		const errors = results
+			.map((result, i) =>
+				result.status === "rejected"
+					? { name: named[i]?.[0] ?? "unknown", error: result.reason }
+					: null,
+			)
+			.filter((x): x is { name: string; error: unknown } => x !== null);
+		if (errors.length > 0) {
+			const summary = errors
+				.map((e) => `'${e.name}': ${String(e.error)}`)
+				.join("; ");
+			throw new AggregateError(
+				errors.map((e) => e.error),
+				`EonProvider: ${errors.length} connection(s) failed to close — ${summary}`,
+			);
+		}
+	}
+
+	/** Normalize the config into a `{ name → EonConnectionConfig }` map + default name. */
+	#resolveConnections(config: EonConfig): {
+		connections: Record<string, EonConnectionConfig>;
+		defaultName: string;
+	} {
+		if (config.connections && Object.keys(config.connections).length > 0) {
+			return {
+				connections: config.connections,
+				defaultName: config.default ?? "primary",
+			};
+		}
+		// Single-connection shape — promote to a one-entry map under "primary"
+		// (mirror atlas: copy the connection fields, drop `default`/`connections`).
+		return {
+			connections: {
+				primary: {
+					url: config.url,
+					user: config.user,
+					password: config.password,
+					database: config.database,
+					token: config.token,
+					timeoutMs: config.timeoutMs,
+					connectRetries: config.connectRetries,
+					connectBackoffMs: config.connectBackoffMs,
+				},
+			},
+			defaultName: "primary",
+		};
+	}
+}
+
+// ream's provider loader constructs `new mod.default(app)` (atlas parity:
+// `export default class AtlasProvider`). The named export stays for tests.
+export default EonProvider;

package/src/connection/EonConnection.ts

@@ -0,0 +1,146 @@
+/**
+ * `EonConnection` — the transport-agnostic seam every eon transport satisfies.
+ *
+ * The WebSocket implementation (`connectWsEon`) is ONE implementation. A
+ * deferred native `taos` implementation (`connectNativeEon`, opt-in, a later
+ * story — memory `project_eon_transport_decision`) satisfies this same
+ * interface, and the locked columnar bulk-ingest STMT method (spike 58-0 AC4)
+ * is added onto a live connection in story 58.4. Neither is built here, but the
+ * seam must not preclude them — keep `exec`/`query`/`ping`/`close`
+ * transport-neutral (no ws-specific type leaks through).
+ *
+ * `exec`/`query` take LITERAL SQL only. TDengine binds positional `?`
+ * placeholders exclusively through the STMT path (58.4 ingest), so the 58.1
+ * compiler's `params` array is NOT threaded through `exec`: a compiled
+ * param-free statement runs as literal SQL, a parameterised one waits for STMT.
+ */
+export interface EonConnection {
+	/**
+	 * Which transport backs this connection. A future native impl reports
+	 * `"native"`; the in-memory test double (`FakeEonConnection`, 58.6) reports
+	 * `"fake"`.
+	 */
+	readonly transport: "websocket" | "native" | "fake";
+	/** Run a literal DDL/DML statement (CREATE / USE / INSERT). */
+	exec(sql: string): Promise<{ rowsAffected: number }>;
+	/** Run a literal SELECT; rows are mapped to objects keyed by column name. */
+	query<T = Record<string, unknown>>(sql: string): Promise<T[]>;
+	/** Liveness probe — a cheap round-trip to the server. */
+	ping(): Promise<void>;
+	/**
+	 * Columnar STMT bulk ingest (story 58.4) — the default high-throughput write
+	 * path. Binds each child table's whole-column typed arrays once per batch
+	 * through the transport's STMT2 API, so no per-row object crosses the
+	 * boundary (the locked 58.0 columnar contract, kept even on the ws path).
+	 *
+	 * It lives on the connection — not as a free function — because only the
+	 * transport owns the live STMT handle; the `transport` discriminant is a
+	 * string, never the raw ws socket. A future native impl satisfies this same
+	 * agnostic contract, so ingest code never imports a ws-specific type.
+	 */
+	ingestColumnar(request: EonColumnarIngest): Promise<{ rowsAffected: number }>;
+	/**
+	 * Schemaless line-protocol ingest (InfluxDB / OpenTSDB). A documented ~8–10×
+	 * slower helper than STMT — NOT the default bulk path (AC4). Bypasses SQL
+	 * entirely; the transport maps the agnostic protocol/precision to its native
+	 * enums.
+	 */
+	schemaless(
+		lines: readonly string[],
+		options?: EonSchemalessOptions,
+	): Promise<void>;
+	/** Close THIS connection (never the process-global connector — D6). */
+	close(): Promise<void>;
+}
+
+/**
+ * How a bound column's values are typed for the STMT columnar bind path. Mirrors
+ * the compiler's `ColumnTypeKind` (camelCase) so ingest code carries the column
+ * metadata kind straight through; the transport maps each kind to its native
+ * columnar setter. No ws-specific type leaks into this seam.
+ */
+export type EonBindKind =
+	| "timestamp"
+	| "bool"
+	| "tinyInt"
+	| "smallInt"
+	| "int"
+	| "bigInt"
+	| "float"
+	| "double"
+	| "varchar"
+	| "nchar"
+	| "varbinary"
+	| "json"
+	| "decimal";
+
+/**
+ * One column's values in struct-of-arrays layout plus the kind that selects the
+ * transport's typed setter. `values` holds the WHOLE column (N rows) for metric
+ * columns, or a single-element array for a child's tag value.
+ */
+export interface EonBoundColumn {
+	readonly kind: EonBindKind;
+	readonly values: unknown[];
+}
+
+/** One child table's columnar batch: its name, tag values, and metric columns. */
+export interface EonChildBatch {
+	/** The (deterministic) child-table name bound via the STMT `?` table slot. */
+	readonly table: string;
+	/** Tag values (one single-element column per tag), bound before the columns. */
+	readonly tags: readonly EonBoundColumn[];
+	/** Value columns in prepared order (timestamp first); each holds the column. */
+	readonly columns: readonly EonBoundColumn[];
+}
+
+/**
+ * A columnar STMT bulk-ingest request: one prepared template reused across every
+ * child batch. `sql` is the compiler-produced STMT template
+ * (`INSERT INTO ? USING <stable> (…) TAGS (?) VALUES (?)`).
+ */
+export interface EonColumnarIngest {
+	readonly sql: string;
+	readonly children: readonly EonChildBatch[];
+}
+
+/** Line-protocol variants for the schemaless path. */
+export type EonLineProtocol = "influxdb" | "opentsdb-telnet" | "opentsdb-json";
+
+/** Timestamp precision for the schemaless path. */
+export type EonSchemalessPrecision =
+	| "hours"
+	| "minutes"
+	| "seconds"
+	| "milliseconds"
+	| "microseconds"
+	| "nanoseconds";
+
+/** Options for {@link EonConnection.schemaless}. */
+export interface EonSchemalessOptions {
+	/** Line-protocol variant. Default `"influxdb"`. */
+	readonly protocol?: EonLineProtocol;
+	/** Timestamp precision. Default `"milliseconds"`. */
+	readonly precision?: EonSchemalessPrecision;
+	/** Child-table TTL in days (0 = none). Default `0`. */
+	readonly ttl?: number;
+}
+
+/**
+ * Error thrown by an eon transport. When the failure originated in the TDengine
+ * connector, `code` carries the connector's numeric error code verbatim (never
+ * swallowed), so callers can branch on it.
+ */
+export class EonConnectionError 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 = "EonConnectionError";
+		this.code = options?.code;
+	}
+}

package/src/connection/config.ts

@@ -0,0 +1,60 @@
+/**
+ * Eon connection configuration — mirrors atlas `ConnectionConfig` /
+ * `AtlasDatabaseConfig` (`AtlasProvider.ts`), adapted for the ws-first TDengine
+ * transport: pool sizing / pragmas / migrations / schema-verification are
+ * dropped (no pool — D7); URL + auth + a connect-retry knob remain.
+ *
+ * No env-var reading happens here: the host `config.get("timeseries")` supplies
+ * the resolved object (agnostic leaf — eon never touches `process.env`).
+ */
+
+/** One TDengine connection's settings. */
+export interface EonConnectionConfig {
+	/** taosAdapter WebSocket URL, e.g. `ws://localhost:6041`. */
+	url: string;
+	/** Auth user — supplied to the connector via a setter, never embedded in the URL. */
+	user?: string;
+	/** Auth password. */
+	password?: string;
+	/** Default database to `USE` on connect. */
+	database?: string;
+	/** Cloud / bearer token auth (taosAdapter) — alternative to user/password. */
+	token?: string;
+	/**
+	 * Per-request timeout in ms, passed to `WSConfig.setTimeOut`. Also used as the
+	 * overall connect deadline (a stalled WS handshake rejects instead of wedging
+	 * boot). Unset → no JS-side connect deadline.
+	 */
+	timeoutMs?: number;
+	/**
+	 * Retry the INITIAL connection if it fails — covers a server that starts a
+	 * moment after the app (docker-compose / k8s cold start). Extra attempts
+	 * beyond the first (default 0 — single attempt). Not a per-query reconnect
+	 * (D7: one long-lived connection, no pool).
+	 */
+	connectRetries?: number;
+	/** Base backoff in ms between connect attempts (exponential, capped 30s; default 200). */
+	connectBackoffMs?: number;
+}
+
+/**
+ * Full eon config — single-connection OR multi-connection (atlas parity).
+ *
+ * 58.2 ships single-connection end-to-end; the `default` / `connections` shape
+ * is structural (mirrors atlas) but not yet exercised — named connections /
+ * taosAdapter HA slot behind this same shape in a later story.
+ */
+export interface EonConfig extends EonConnectionConfig {
+	/** Name of the default connection when `connections` is set. Defaults to `"primary"`. */
+	default?: string;
+	/**
+	 * Named connections. When present, the top-level `url` is treated as
+	 * `connections[default].url`.
+	 */
+	connections?: Record<string, EonConnectionConfig>;
+}
+
+/** Identity helper for typed config authoring — mirrors atlas `defineConfig`. */
+export function defineConfig(config: EonConfig): EonConfig {
+	return config;
+}