ventiws 1.0.0-alpha.16 → 1.0.0-beta.1

package/README.md

@@ -12,8 +12,8 @@ observable behaviour rather than its source. ventiws is not affiliated with the
 as the pinned contract, credited in
 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
 
-**ventiws is at `1.0.0-alpha.16`.** The surface may change between alpha
-releases. What "alpha" means here is bounded: the `ws` compatibility
+**ventiws is at `1.0.0-beta.1`.** The surface may change between beta
+releases. What "beta" means here is bounded: the `ws` compatibility
 contract is tracked row by row in
 [COMPATIBILITY.md](COMPATIBILITY.md), and the four places ventiws knowingly
 differs from `ws` are listed in [CHANGELOG.md](CHANGELOG.md) under "Known
@@ -94,6 +94,22 @@ Both halves run against a real `ws` peer in this repository's suites, and the
 constructors are plain functions returning state records: no `class`, no `this`,
 no prototype.
 
+### Dev logger
+
+ventiws prints lifecycle records as they happen: the splash when a server starts
+listening, then open, close, and error records for every connection, with no
+callbacks to subscribe. It is a zero-dependency ANSI module outside the `ws`
+surface, on by default, and silenced with one switch.
+
+```ts
+import { setLoggerEnabled } from "ventiws/logging";
+
+setLoggerEnabled(false); // VENTIWS_LOG=0 does the same at load
+```
+
+The record format, every recorded moment, and the manual API are in
+[docs/logging.md](docs/logging.md).
+
 ## Status
 
 Option defaults match `ws`: `maxPayload` 100 MiB, `maxFragments` 16384, and
@@ -152,6 +168,7 @@ pnpm format:check
 - [CODEBASE.md](CODEBASE.md): repository layout, the two routes, the boundary, and the compiled capacities.
 - [CODING_CONVENTION.md](CODING_CONVENTION.md): TypeScript and Zig style, the anti-OOP rules, and the module budget.
 - [docs/migrating.md](docs/migrating.md): moving an existing `ws` application over.
+- [docs/logging.md](docs/logging.md): the opt-in dev logger and startup splash.
 - [CONTRIBUTE.md](CONTRIBUTE.md): environment setup, the script contract, and how to release.
 
 MIT. See [LICENSE](LICENSE). `ws` is copyright Einar Otto Stangvik, Arnout

package/dist/index.cjs

@@ -2,6 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
+const require_logging = require("./logging.cjs");
 let node_http = require("node:http");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
@@ -383,10 +384,42 @@ function trackClient(state, socket) {
 	});
 }
 //#endregion
+//#region package.json
+var version = "1.0.0-beta.1";
+//#endregion
+//#region src/logging/lifecycle.ts
+const CONTROL = /\p{Cc}/gu;
+function sideOf(state) {
+	return state.isServer ? "connection" : "client";
+}
+function logServerListening(port) {
+	require_logging.ready(version, Math.round(performance.now()), port);
+}
+function logServerPath(path) {
+	require_logging.info("server", `listening on ${path}`);
+}
+function logServerClosed() {
+	require_logging.info("server", "closed");
+}
+function logServerError(error) {
+	require_logging.fatal("server", error.message);
+}
+function logSocketOpen(state) {
+	require_logging.info(sideOf(state), "open");
+}
+function logSocketClose(state, code, reason) {
+	const text = reason.length === 0 ? "" : ` ${reason.toString("utf8").replace(CONTROL, "?")}`;
+	require_logging.warn(sideOf(state), `closed ${code}${text}`);
+}
+function logSocketError(state, error) {
+	require_logging.fatal(sideOf(state), error.message);
+}
+//#endregion
 //#region src/compat/server/close.ts
 function emitClose(state) {
 	if (state.lifecycle === "closed") return;
 	state.lifecycle = "closed";
+	logServerClosed();
 	emitEvent(state, "close");
 }
 function emitCloseAgain(state) {
@@ -1121,6 +1154,7 @@ function finishConnection(state, code, reason) {
 	state.closeCode = code;
 	state.closeReason = reason;
 	state.pendingInput = [];
+	logSocketClose(state, code, reason);
 	emitEvent(state, "close", code, reason);
 }
 function failConnection(state, error) {
@@ -1128,6 +1162,7 @@ function failConnection(state, error) {
 	if (!state.errorEmitted) {
 		state.errorEmitted = true;
 		state.readyState = 2;
+		logSocketError(state, error);
 		try {
 			emitEvent(state, "error", error);
 		} finally {
@@ -1141,6 +1176,7 @@ function reportWithoutClosing(state, error) {
 	if (state.errorEmitted) return;
 	if (state.readyState === 3) return;
 	state.errorEmitted = true;
+	logSocketError(state, error);
 	emitEvent(state, "error", error);
 }
 function closeConnection(state, code, reason) {
@@ -1199,7 +1235,9 @@ function refuseFramed(state, refusal) {
 	try {
 		if (!state.errorEmitted) {
 			state.errorEmitted = true;
-			emitEvent(state, "error", createError(refusal.code, refusal.message, refusal.ctor));
+			const error = createError(refusal.code, refusal.message, refusal.ctor);
+			logSocketError(state, error);
+			emitEvent(state, "error", error);
 		}
 	} finally {
 		finishConnection(state, refusal.closeCode, Buffer.from(refusal.reason, "utf8"));
@@ -1487,6 +1525,7 @@ const EMPTY = Buffer.alloc(0);
 function failTransport(state, error) {
 	if (state.readyState === 3) return;
 	state.readyState = 2;
+	logSocketError(state, error);
 	emitEvent(state, "error", error);
 }
 function terminateConnection(state) {
@@ -1538,6 +1577,7 @@ function attachSocket(socket, transport, role, pending) {
 function openSocket(state) {
 	if (state.readyState === 1) return;
 	state.readyState = 1;
+	logSocketOpen(state);
 	emitEvent(state, "open");
 }
 function asCodedError(error) {
@@ -1925,9 +1965,13 @@ function wireServer(state) {
 	if (httpServer === null) return;
 	const handlers = {
 		onListening: () => {
+			const address = state.server?.address();
+			if (typeof address === "string") logServerPath(address);
+			else logServerListening(typeof address === "object" && address !== null ? address.port : 0);
 			emitEvent(state, "listening");
 		},
 		onError: (error) => {
+			logServerError(error);
 			emitEvent(state, "error", error);
 		},
 		onUpgrade: (request, socket, head) => {

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { fatal, info, ready, warn } from "./logging.mjs";
 import { createRequire } from "node:module";
 import { STATUS_CODES, createServer, request } from "node:http";
 import { existsSync, readFileSync } from "node:fs";
@@ -379,10 +380,42 @@ function trackClient(state, socket) {
 	});
 }
 //#endregion
+//#region package.json
+var version = "1.0.0-beta.1";
+//#endregion
+//#region src/logging/lifecycle.ts
+const CONTROL = /\p{Cc}/gu;
+function sideOf(state) {
+	return state.isServer ? "connection" : "client";
+}
+function logServerListening(port) {
+	ready(version, Math.round(performance.now()), port);
+}
+function logServerPath(path) {
+	info("server", `listening on ${path}`);
+}
+function logServerClosed() {
+	info("server", "closed");
+}
+function logServerError(error) {
+	fatal("server", error.message);
+}
+function logSocketOpen(state) {
+	info(sideOf(state), "open");
+}
+function logSocketClose(state, code, reason) {
+	const text = reason.length === 0 ? "" : ` ${reason.toString("utf8").replace(CONTROL, "?")}`;
+	warn(sideOf(state), `closed ${code}${text}`);
+}
+function logSocketError(state, error) {
+	fatal(sideOf(state), error.message);
+}
+//#endregion
 //#region src/compat/server/close.ts
 function emitClose(state) {
 	if (state.lifecycle === "closed") return;
 	state.lifecycle = "closed";
+	logServerClosed();
 	emitEvent(state, "close");
 }
 function emitCloseAgain(state) {
@@ -1117,6 +1150,7 @@ function finishConnection(state, code, reason) {
 	state.closeCode = code;
 	state.closeReason = reason;
 	state.pendingInput = [];
+	logSocketClose(state, code, reason);
 	emitEvent(state, "close", code, reason);
 }
 function failConnection(state, error) {
@@ -1124,6 +1158,7 @@ function failConnection(state, error) {
 	if (!state.errorEmitted) {
 		state.errorEmitted = true;
 		state.readyState = 2;
+		logSocketError(state, error);
 		try {
 			emitEvent(state, "error", error);
 		} finally {
@@ -1137,6 +1172,7 @@ function reportWithoutClosing(state, error) {
 	if (state.errorEmitted) return;
 	if (state.readyState === 3) return;
 	state.errorEmitted = true;
+	logSocketError(state, error);
 	emitEvent(state, "error", error);
 }
 function closeConnection(state, code, reason) {
@@ -1195,7 +1231,9 @@ function refuseFramed(state, refusal) {
 	try {
 		if (!state.errorEmitted) {
 			state.errorEmitted = true;
-			emitEvent(state, "error", createError(refusal.code, refusal.message, refusal.ctor));
+			const error = createError(refusal.code, refusal.message, refusal.ctor);
+			logSocketError(state, error);
+			emitEvent(state, "error", error);
 		}
 	} finally {
 		finishConnection(state, refusal.closeCode, Buffer.from(refusal.reason, "utf8"));
@@ -1483,6 +1521,7 @@ const EMPTY = Buffer.alloc(0);
 function failTransport(state, error) {
 	if (state.readyState === 3) return;
 	state.readyState = 2;
+	logSocketError(state, error);
 	emitEvent(state, "error", error);
 }
 function terminateConnection(state) {
@@ -1534,6 +1573,7 @@ function attachSocket(socket, transport, role, pending) {
 function openSocket(state) {
 	if (state.readyState === 1) return;
 	state.readyState = 1;
+	logSocketOpen(state);
 	emitEvent(state, "open");
 }
 function asCodedError(error) {
@@ -1921,9 +1961,13 @@ function wireServer(state) {
 	if (httpServer === null) return;
 	const handlers = {
 		onListening: () => {
+			const address = state.server?.address();
+			if (typeof address === "string") logServerPath(address);
+			else logServerListening(typeof address === "object" && address !== null ? address.port : 0);
 			emitEvent(state, "listening");
 		},
 		onError: (error) => {
+			logServerError(error);
 			emitEvent(state, "error", error);
 		},
 		onUpgrade: (request, socket, head) => {

package/dist/logging.cjs

@@ -0,0 +1,57 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/logging/logger.ts
+const RESET = "\x1B[0m";
+const BOLD = "\x1B[1m";
+const DIM = "\x1B[2m";
+const RED = "\x1B[31m";
+const GREEN = "\x1B[32m";
+const YELLOW = "\x1B[33m";
+const CYAN = "\x1B[36m";
+const SPLASH = `██╗   ██╗███████╗███╗   ██╗████████╗██╗██╗    ██╗███████╗
+██║   ██║██╔════╝████╗  ██║╚══██╔══╝██║██║    ██║██╔════╝
+██║   ██║█████╗  ██╔██╗ ██║   ██║   ██║██║ █╗ ██║███████╗
+╚██╗ ██╔╝██╔══╝  ██║╚██╗██║   ██║   ██║██║███╗██║╚════██║
+ ╚████╔╝ ███████╗██║ ╚████║   ██║   ██║╚███╔███╔╝███████║
+  ╚═══╝  ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝ ╚══╝╚══╝ ╚══════╝`;
+let isEnabled = process.env["VENTIWS_LOG"] !== "0";
+function setLoggerEnabled(enabled) {
+	isEnabled = enabled;
+}
+function time() {
+	return (/* @__PURE__ */ new Date()).toTimeString().slice(0, 8);
+}
+function emit(line) {
+	process.stdout.write(`${line}\n`);
+}
+function record(color, command, status) {
+	emit(`${DIM}${time()}${RESET} | ${color}${command}${RESET} : ${status}`);
+}
+function info(command, status) {
+	if (!isEnabled) return;
+	record(CYAN, command, status);
+}
+function warn(command, status) {
+	if (!isEnabled) return;
+	record(YELLOW, command, status);
+}
+function fatal(command, status) {
+	if (!isEnabled) return;
+	record(RED, command, status);
+}
+function ready(version, timeMs, port) {
+	if (!isEnabled) return;
+	emit(`${CYAN}${SPLASH}${RESET}`);
+	emit("");
+	emit(`ventiws ${BOLD}${version}${RESET} ready in ${timeMs}`);
+	emit("");
+	emit(`${GREEN}\u279C${RESET}  Local: localhost:${port}/`);
+	emit("");
+}
+//#endregion
+exports.fatal = fatal;
+exports.info = info;
+exports.ready = ready;
+exports.setLoggerEnabled = setLoggerEnabled;
+exports.warn = warn;
+
+module.exports = Object.assign(module.exports.default ?? module.exports, module.exports);

package/dist/logging.d.cts

@@ -0,0 +1,7 @@
+//#region src/logging/logger.d.ts
+export declare function setLoggerEnabled(enabled: boolean): void;
+export declare function info(command: string, status: string): void;
+export declare function warn(command: string, status: string): void;
+export declare function fatal(command: string, status: string): void;
+export declare function ready(version: string, timeMs: number, port: number): void;
+//#endregion

package/dist/logging.d.mts

@@ -0,0 +1,7 @@
+//#region src/logging/logger.d.ts
+export declare function setLoggerEnabled(enabled: boolean): void;
+export declare function info(command: string, status: string): void;
+export declare function warn(command: string, status: string): void;
+export declare function fatal(command: string, status: string): void;
+export declare function ready(version: string, timeMs: number, port: number): void;
+//#endregion

package/dist/logging.mjs

@@ -0,0 +1,51 @@
+//#region src/logging/logger.ts
+const RESET = "\x1B[0m";
+const BOLD = "\x1B[1m";
+const DIM = "\x1B[2m";
+const RED = "\x1B[31m";
+const GREEN = "\x1B[32m";
+const YELLOW = "\x1B[33m";
+const CYAN = "\x1B[36m";
+const SPLASH = `██╗   ██╗███████╗███╗   ██╗████████╗██╗██╗    ██╗███████╗
+██║   ██║██╔════╝████╗  ██║╚══██╔══╝██║██║    ██║██╔════╝
+██║   ██║█████╗  ██╔██╗ ██║   ██║   ██║██║ █╗ ██║███████╗
+╚██╗ ██╔╝██╔══╝  ██║╚██╗██║   ██║   ██║██║███╗██║╚════██║
+ ╚████╔╝ ███████╗██║ ╚████║   ██║   ██║╚███╔███╔╝███████║
+  ╚═══╝  ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝ ╚══╝╚══╝ ╚══════╝`;
+let isEnabled = process.env["VENTIWS_LOG"] !== "0";
+function setLoggerEnabled(enabled) {
+	isEnabled = enabled;
+}
+function time() {
+	return (/* @__PURE__ */ new Date()).toTimeString().slice(0, 8);
+}
+function emit(line) {
+	process.stdout.write(`${line}\n`);
+}
+function record(color, command, status) {
+	emit(`${DIM}${time()}${RESET} | ${color}${command}${RESET} : ${status}`);
+}
+function info(command, status) {
+	if (!isEnabled) return;
+	record(CYAN, command, status);
+}
+function warn(command, status) {
+	if (!isEnabled) return;
+	record(YELLOW, command, status);
+}
+function fatal(command, status) {
+	if (!isEnabled) return;
+	record(RED, command, status);
+}
+function ready(version, timeMs, port) {
+	if (!isEnabled) return;
+	emit(`${CYAN}${SPLASH}${RESET}`);
+	emit("");
+	emit(`ventiws ${BOLD}${version}${RESET} ready in ${timeMs}`);
+	emit("");
+	emit(`${GREEN}\u279C${RESET}  Local: localhost:${port}/`);
+	emit("");
+}
+//#endregion
+export { fatal, info, ready, setLoggerEnabled, warn };
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ventiws",
-  "version": "1.0.0-alpha.16",
+  "version": "1.0.0-beta.1",
   "description": "A drop-in replacement for ws for Node.js, built on the first-party µWebZockets Zig engine via napi-zig.",
   "homepage": "https://github.com/farbenbuilds/ventiws#readme",
   "bugs": {
@@ -24,16 +24,20 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
+    "./logging": {
+      "import": "./dist/logging.mjs",
+      "require": "./dist/logging.cjs"
+    },
     "./package.json": "./package.json"
   },
   "engines": {
     "node": ">=22.12.0"
   },
   "optionalDependencies": {
-    "@ventiws/binding-darwin-arm64": "1.0.0-alpha.16",
-    "@ventiws/binding-darwin-x64": "1.0.0-alpha.16",
-    "@ventiws/binding-linux-arm64-gnu": "1.0.0-alpha.16",
-    "@ventiws/binding-linux-x64-gnu": "1.0.0-alpha.16",
-    "@ventiws/binding-linux-x64-musl": "1.0.0-alpha.16"
+    "@ventiws/binding-darwin-arm64": "1.0.0-beta.1",
+    "@ventiws/binding-darwin-x64": "1.0.0-beta.1",
+    "@ventiws/binding-linux-arm64-gnu": "1.0.0-beta.1",
+    "@ventiws/binding-linux-x64-gnu": "1.0.0-beta.1",
+    "@ventiws/binding-linux-x64-musl": "1.0.0-beta.1"
   }
 }