docs(server): tighten compression comments and docs

src/tooling/liveProviders.test.mjs

@@ -615,8 +615,7 @@ test('the OpenSky snapshot is compressed for clients that ask, and an error body
     if (upstreamStatus !== 200)
       return new Response('{"error":"upstream"}', { status: upstreamStatus });
     const sourceSeconds = Math.floor((now - snapshotAgeMs) / 1000);
-    // A healthy credit budget, so the proxy keeps its 9 s base TTL and the
-    // clock advances below are unambiguously past it.
+    // Healthy credits keep the 9 s base TTL, so the clock jumps below clear it.
     return Response.json(
       {
         time: sourceSeconds,
@@ -634,8 +633,7 @@ test('the OpenSky snapshot is compressed for clients that ask, and an error body
     );
   });
 
-  // A module instance of its own: the snapshot cache, its frame and the
-  // adaptive TTL are module state, and this test reasons about all three.
+  // A fresh module: the snapshot cache, its frame and the TTL are module state.
   const isolated = await import(
     `../../server/providers/aircraft/opensky.js?compression=${now}`
   );
@@ -648,25 +646,25 @@ test('the OpenSky snapshot is compressed for clients that ask, and an error body
   assert.equal(compressed.headers.vary, 'Accept-Encoding');
   assert.ok(Buffer.isBuffer(compressed.body));
 
-  // Same snapshot from cache, this time to a client that offered nothing: the
-  // identity bytes, and the compressed frame above must decode to exactly them.
+  // Same cached snapshot, no Accept-Encoding: identity bytes, which the frame
+  // above must decode to.
   const identity = await states('/api/flights');
   assert.equal(identity.headers['x-opensky-cache'], 'HIT');
   assert.equal(identity.headers['content-encoding'], undefined);
   assert.equal(identity.headers.vary, 'Accept-Encoding');
   assert.equal(gunzipSync(compressed.body).toString(), identity.body);
 
-  // A client that names gzip and refuses it with q=0 is a non-gzip client.
+  // `gzip;q=0` refuses gzip.
   const refused = await states('/api/flights', '/', 'GET', {
     'accept-encoding': 'gzip;q=0',
   });
   assert.equal(refused.headers['content-encoding'], undefined);
   assert.equal(refused.body, identity.body);
 
-  // An upstream rejection is not cached, so it has no frame of its own. It must
-  // not be sent under the previous snapshot's Content-Encoding.
+  // An upstream rejection is not cached, so it must not carry the previous
+  // snapshot's Content-Encoding.
   upstreamStatus = 403;
-  now += 60000; // past the 9 s base TTL this fresh instance starts with
+  now += 60000; // past the 9 s base TTL
   const rejected = await states('/api/flights', '/', 'GET', {
     'accept-encoding': 'gzip',
   });
@@ -674,9 +672,8 @@ test('the OpenSky snapshot is compressed for clients that ask, and an error body
   assert.equal(rejected.headers['content-encoding'], undefined);
   assert.ok(JSON.parse(rejected.body).error, 'a readable error body');
 
-  // The regional fallback is a fifth body this route can answer with. It is
-  // cached the same way and so it negotiates the same way: a snapshot too old
-  // to serve hands the request to adsb.lol, compressed.
+  // A snapshot too old to serve falls back to adsb.lol, which negotiates the
+  // same way.
   upstreamStatus = 200;
   snapshotAgeMs = 3600000;
   now += 60000;

src/tooling/responseCompression.test.mjs

@@ -17,7 +17,7 @@ function request(acceptEncoding) {
   };
 }
 
-/** Repetitive JSON, the shape of an actual snapshot body. */
+/** Repetitive JSON shaped like a snapshot body. */
 function snapshotBody(states = 200) {
   return JSON.stringify({
     time: 1700000000,
@@ -33,10 +33,7 @@ function snapshotBody(states = 200) {
   });
 }
 
-/**
- * Deterministic high-entropy bytes. Random data would do, but a seeded sequence
- * keeps the "gzip made it bigger" assertion from depending on luck.
- */
+/** Seeded high-entropy bytes, so the "gzip made it bigger" check is stable. */
 function incompressibleBytes(length) {
   const bytes = Buffer.alloc(length);
   let state = 123456789;
@@ -61,16 +58,15 @@ test('accept-encoding is read the way clients actually write it', () => {
   assert.equal(acceptsGzip({}), false);
   assert.equal(acceptsGzip(undefined), false);
 
-  // A quality of zero names gzip and refuses it (RFC 9110 section 12.4.2).
+  // `q=0` names gzip and refuses it (RFC 9110 section 12.4.2).
   assert.equal(acceptsGzip(request('gzip;q=0')), false);
   assert.equal(acceptsGzip(request('gzip;q=0.000')), false);
   assert.equal(acceptsGzip(request('gzip;q=0.001')), true);
   assert.equal(acceptsGzip(request('gzip;q=1')), true);
   assert.equal(acceptsGzip(request('gzip;q=1.000')), true);
 
-  // A quality that is not a whole `qvalue` is unreadable, not a number with
-  // trailing noise: the grammar allows three decimals and a ceiling of 1, so
-  // these must not round into acceptance.
+  // A q that is not a whole `qvalue` is unreadable and must not round into
+  // acceptance.
   assert.equal(acceptsGzip(request('gzip;q=bogus')), false);
   assert.equal(acceptsGzip(request('gzip;q=1oops')), false);
   assert.equal(acceptsGzip(request('gzip;q=0.5abc')), false);
@@ -102,8 +98,7 @@ test('a body is only compressed when compression pays for itself', async () => {
   assert.ok(compressed.byteLength < Buffer.byteLength(identity));
   assert.equal(gunzipSync(compressed).toString(), identity);
 
-  // Buffers are accepted as-is, and data that gzip cannot shrink is refused
-  // rather than served as a larger response.
+  // Buffers are accepted as-is; data gzip cannot shrink stays uncompressed.
   assert.ok((await gzipBody(Buffer.from(identity))) !== null);
   assert.equal(await gzipBody(incompressibleBytes(4096)), null);
 });
@@ -118,8 +113,7 @@ test('the encoded body and the header that names it are chosen together', async
   assert.equal(negotiated.headers.Vary, 'Accept-Encoding');
   assert.equal(gunzipSync(negotiated.body).toString(), identity);
 
-  // Offered but not wanted: identity bytes, and no Content-Encoding to
-  // contradict them.
+  // Offered but refused: identity bytes and no Content-Encoding.
   const refused = encodedBody(request('br'), identity, compressed);
   assert.equal(refused.body, identity);
   assert.equal(refused.headers['Content-Encoding'], undefined);
@@ -130,8 +124,7 @@ test('the encoded body and the header that names it are chosen together', async
   assert.equal(unavailable.body, identity);
   assert.equal(unavailable.headers['Content-Encoding'], undefined);
 
-  // Vary is on both branches: without it a shared cache could hand a stored
-  // response to a client whose Accept-Encoding it was not selected for.
+  // Vary is on both branches, so a shared cache cannot serve the wrong encoding.
   assert.equal(unavailable.headers.Vary, 'Accept-Encoding');
   assert.equal(
     encodedBody(request(undefined), identity, compressed).headers.Vary,