@aletheia-ios/tools 0.2.0 → 0.2.2

package/dist/cli.js

@@ -1061,7 +1061,10 @@ const TRAVERSAL = /^(\.\.[/\\])+/;
 /** How long after the last change to wait before rebuilding, so an editor's save burst is one build. */
 const DEBOUNCE_MS = 300;
 const OK = 200;
+const NOT_MODIFIED = 304;
 const NOT_FOUND = 404;
+/** Base 16, so the validator stays short. */
+const HEX = 16;
 /**
 * Packs and indexes the whole repository, reporting failures instead of throwing.
 *
@@ -1103,7 +1106,27 @@ async function resolveFile(dist, url) {
 	if (!(existsSync(file) && (await stat(file)).isFile())) return null;
 	return file;
 }
-/** A static server over `dist/` that sends `cache-control: no-store` so the app never caches a dev build. */
+/**
+* A validator for the file as it is right now, from its size and modification time.
+*
+* Every rebuild rewrites the file, so the value changes and a conditional request gets the new
+* bytes. Between rebuilds it is stable, which is the only case that answers 304.
+*/
+function etagOf(size, mtimeMs) {
+	return `"${size.toString(HEX)}-${Math.trunc(mtimeMs).toString(HEX)}"`;
+}
+/** Whether the request already holds this version. A client may offer several. */
+function offers(header, etag) {
+	if (header === void 0) return false;
+	return header.split(",").some((candidate) => candidate.trim() === etag);
+}
+/**
+* A static server over `dist/`.
+*
+* Sends `cache-control: no-store` so nothing holds on to a dev build, alongside an `ETag` so a
+* client that asks can still be told nothing changed. The two are not in tension: `no-store`
+* governs whether a copy may be kept, the validator governs whether a fetch has to transfer.
+*/
 function fileServer(dist) {
 	return createServer(async (request, response) => {
 		const file = await resolveFile(dist, request.url ?? "/");
@@ -1111,9 +1134,20 @@ function fileServer(dist) {
 			response.writeHead(NOT_FOUND).end();
 			return;
 		}
+		const { size, mtimeMs } = await stat(file);
+		const etag = etagOf(size, mtimeMs);
+		if (offers(request.headers["if-none-match"], etag)) {
+			response.writeHead(NOT_MODIFIED, {
+				etag,
+				"cache-control": "no-store"
+			}).end();
+			return;
+		}
 		response.writeHead(OK, {
 			"content-type": TYPES[extname(file)] ?? "application/octet-stream",
-			"cache-control": "no-store"
+			"cache-control": "no-store",
+			"content-length": size,
+			etag
 		});
 		createReadStream(file).pipe(response);
 	});
@@ -1131,22 +1165,50 @@ function watchRepo(repo) {
 	return [watch(repo.packages, { recursive: true }, trigger), watch(repo.lists, { recursive: true }, trigger)];
 }
 /**
+* Binds the port and reports the one it got, since port 0 picks a free one.
+*
+* A busy port is the common way this fails and it arrives as an `error` event rather than a
+* rejection, so without this it surfaces as an unhandled event and a stack trace.
+*
+* @throws `CliError` naming the port when something already holds it.
+*/
+async function listen(server, port) {
+	try {
+		await new Promise((resolve, reject) => {
+			server.once("error", reject);
+			server.listen(port, "0.0.0.0", () => {
+				server.removeListener("error", reject);
+				resolve();
+			});
+		});
+	} catch (error) {
+		if (error.code === "EADDRINUSE") throw new CliError([`port ${port} is already in use - pass --port <n> to pick another`], { cause: error });
+		throw error;
+	}
+	const address = server.address();
+	return typeof address === "object" && address !== null ? address.port : port;
+}
+/**
 * The `serve` command: packs, indexes, serves `dist/` on the lan and rebuilds on change.
 *
 * Binds every interface and prints the lan URL of each list's `index.json`, which is what
 * the app's developer list points at. Port 0 binds a free port. Resolves once listening;
 * the returned `close` stops the watchers and the server.
 *
-* @throws `CliError` when there is no `lists/` directory, before any port is bound.
+* @throws `CliError` when there is no `lists/` directory, or when the port is taken.
 */
 async function serve(repo, port) {
 	const lists = await loadLists(repo);
 	await rebuild(repo);
 	const server = fileServer(repo.dist);
 	const watchers = watchRepo(repo);
-	await new Promise((resolve) => server.listen(port, "0.0.0.0", resolve));
-	const address = server.address();
-	const bound = typeof address === "object" && address !== null ? address.port : port;
+	let bound;
+	try {
+		bound = await listen(server, port);
+	} catch (error) {
+		for (const watcher of watchers) watcher.close();
+		throw error;
+	}
 	const url = `http://${lanAddress()}:${bound}/`;
 	info(`serving ${repo.dist} on ${url}`);
 	for (const list of lists) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aletheia-ios/tools",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "The aletheia CLI: build, check, pack, index and serve source packages",
   "license": "MIT",
   "repository": {