Merge main into fix/radio-mirror-null-body

Resolve the CHANGELOG conflict by keeping every entry from main and
adding the radio entry on top; the previous main merge (cebd870)
had dropped 19 of main's entries.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

server/providers/local.js

@@ -83,6 +83,9 @@ export { LL2_CACHE_TTL_MS, launchLibraryRequestHeaders } from './space.js';
 export { googlePlacesContextProxy } from './places.js';
 export { googleServerApiKey } from './places.js';
 export { keylessGooglePlacesResponse } from './places.js';
+export { keylessGoogleGeocodeResponse } from './places.js';
+export { validateGeocodeAddress } from './places.js';
+export { geocodeBounds } from './places.js';
 export { adsbLolFallbackAnchor } from './aircraft/opensky.js';
 export { readResponseTextCapped } from './common/http.js';
 export { readResponseJsonCapped } from './common/http.js';

server/providers/places.js

@@ -1,8 +1,13 @@
 /** Place-search and route middleware for Node development servers. */
-export { googlePlacesContextProxy } from './places/google.js';
+export {
+  googlePlacesContextProxy,
+  validateGeocodeAddress,
+  geocodeBounds,
+} from './places/google.js';
 export {
   googleServerApiKey,
   keylessGooglePlacesResponse,
+  keylessGoogleGeocodeResponse,
 } from './places/google-key.js';
 export { installRouteMiddleware } from './places/routes.js';
 export {

server/providers/places/google-key.js

@@ -14,12 +14,34 @@ export function keylessGooglePlacesResponse(apiKey) {
 }
 
 /**
- * Google API key for the SERVER-SIDE calls (Places nearby/text search, the
- * CCTV Street View fallback). These never reach the browser, so this key can
- * be restricted by server IP and scoped to Places API + Street View Static
- * API — while GOOGLE_MAPS_API_KEY stays referrer-restricted to Map Tiles +
- * Geocoding for the browser (#33). Splitting them is opt-in: unset, this
- * falls back to the shared browser key and nothing changes.
+ * Geocoding speaks Google's own response shape rather than the `places: []`
+ * contract its two siblings use, because the browser adapters read `status`
+ * and `results` directly. The keyless capability reads the same way: a status
+ * that is not `OK` and no results, which the adapters already treat as "this
+ * provider did not answer" and pass to the next geocoder in the chain.
+ */
+export function keylessGoogleGeocodeResponse(apiKey) {
+  if (String(apiKey ?? '').trim()) return null;
+  return {
+    statusCode: 200,
+    payload: {
+      configured: false,
+      status: 'REQUEST_DENIED',
+      results: [],
+      error: null,
+    },
+  };
+}
+
+/**
+ * Google API key for the SERVER-SIDE calls (Places nearby/text search,
+ * geocoding, the CCTV Street View fallback). These never reach the browser, so
+ * this key can be restricted by server IP and scoped to Places API + Geocoding
+ * API + Street View Static API — while GOOGLE_MAPS_API_KEY stays
+ * referrer-restricted to Map Tiles + Maps JavaScript API for the browser
+ * (#33, #363). Splitting them is opt-in: unset, this falls back to the shared
+ * browser key, which then has to carry every API both sides use and cannot
+ * take a referrer restriction.
  */
 export function googleServerApiKey() {
   return resolveGoogleServerKey(process.env);

server/providers/places/google.js

@@ -1,9 +1,11 @@
 import {
   googleServerApiKey,
   keylessGooglePlacesResponse,
+  keylessGoogleGeocodeResponse,
 } from './google-key.js';
 import { makeCostRateLimiter, clientKey } from '../common/rate-limit.js';
 import { admitSameSite } from '../common/same-site.js';
+import { readResponseJsonCapped } from '../common/http.js';
 import {
   projectNearbyPlaces,
   projectTextSearchPlaces,
@@ -25,7 +27,7 @@ let _googleRateLimiter;
  */
 export const GOOGLE_DEFAULT_PER_MIN = 120;
 
-/** Google cost endpoints (nearby-places + text-search). Null only when set to 0. */
+/** Google cost endpoints (nearby-places, text-search, geocoding). Null only when set to 0. */
 function googleRateLimiter() {
   if (_googleRateLimiter === undefined)
     _googleRateLimiter = makeCostRateLimiter(
@@ -56,6 +58,51 @@ export function validatePlacesCoordinates(searchParams) {
   return { ok: true, latitude, longitude };
 }
 
+/** Longest accepted geocoder query. Real place names are far shorter. */
+const GEOCODE_MAX_QUERY = 200;
+
+/**
+ * Upstream deadline and body ceiling for the geocode routes. The deadline stays
+ * armed through body consumption, so a stalled upstream cannot hold a handler
+ * open, and the cap bounds a chunked or length-omitted reply. A geocode answer
+ * is a handful of results; 256 KiB is far above any honest one.
+ */
+const GEOCODE_UPSTREAM_TIMEOUT_MS = 10_000;
+
+const GEOCODE_MAX_RESPONSE_BYTES = 256 * 1024;
+
+/** Validate a free-text geocoder query before consuming request quota. */
+export function validateGeocodeAddress(searchParams) {
+  const address = String(searchParams.get('address') || '').trim();
+  if (!address) return { ok: false, error: 'address is required' };
+  if (address.length > GEOCODE_MAX_QUERY)
+    return { ok: false, error: 'address is too long' };
+  return { ok: true, address };
+}
+
+/**
+ * Validate the optional viewport bias, which Google reads as
+ * `sw_lat,sw_lng|ne_lat,ne_lng`. An unparsed value is dropped rather than
+ * refused: the bias only ranks results, so a malformed one costs relevance,
+ * not an answer.
+ */
+export function geocodeBounds(searchParams) {
+  const raw = String(searchParams.get('bounds') || '').trim();
+  if (!raw) return null;
+  const corners = raw.split('|');
+  if (corners.length !== 2) return null;
+  const parts = corners.flatMap((corner) => corner.split(','));
+  // A blank component must be refused before Number() turns it into 0 and a
+  // half-written corner like `30.4,` reads as the equator.
+  if (parts.length !== 4 || parts.some((part) => !part.trim())) return null;
+  const numbers = parts.map(Number);
+  if (!numbers.every(Number.isFinite)) return null;
+  const [swLat, swLon, neLat, neLon] = numbers;
+  if (Math.abs(swLat) > 90 || Math.abs(neLat) > 90) return null;
+  if (Math.abs(swLon) > 180 || Math.abs(neLon) > 180) return null;
+  return raw;
+}
+
 /** Nearby place labels and view-biased text search, with request-time key resolution. */
 export function googlePlacesContextProxy({
   resolveApiKey = googleServerApiKey,
@@ -293,6 +340,149 @@ export function googlePlacesContextProxy({
         );
       }
     });
+
+    /**
+     * Geocoding belongs on the server, not in the page. Google's Geocoding web
+     * service refuses referrer-restricted keys, so calling it from the browser
+     * forces GOOGLE_MAPS_API_KEY — which ships in the bundle by design — to be
+     * left unrestricted (#363). Here the request carries the server key, and
+     * the browser key no longer needs the Geocoding API at all.
+     *
+     * Unlike the two Places routes above, these answer in Google's own shape
+     * (`status` + `results`) rather than the `places: []` contract: the browser
+     * normalizers read that shape directly, and keeping it means the proxy adds
+     * a hop without adding a translation nobody asked for.
+     */
+    function installGeocodeRoute(path, readQuery) {
+      middlewares.use(path, async (req, res) => {
+        const refuse = (statusCode, error) => {
+          res.statusCode = statusCode;
+          res.setHeader('Content-Type', 'application/json');
+          res.end(
+            JSON.stringify({ status: 'REQUEST_DENIED', results: [], error }),
+          );
+        };
+
+        // Gate first, like the Places routes above: a cross-site caller learns
+        // nothing about this endpoint's method surface.
+        if (admitSameSite(req, res)) return;
+        if (req.method !== 'GET') {
+          refuse(405, 'Method not allowed');
+          return;
+        }
+
+        // A keyless geocode has no provider cost, so it resolves before the
+        // paid-endpoint limiter can consume or exhaust quota (mirrors the
+        // Places routes above).
+        const apiKey = resolveApiKey();
+        const keyless = keylessGoogleGeocodeResponse(apiKey);
+        if (keyless) {
+          res.statusCode = keyless.statusCode;
+          res.setHeader('Content-Type', 'application/json');
+          res.setHeader('Cache-Control', 'no-store');
+          res.end(JSON.stringify(keyless.payload));
+          return;
+        }
+
+        const requestUrl = new URL(req.url || '', 'http://localhost');
+        const query = readQuery(requestUrl.searchParams);
+        if (!query.ok) {
+          refuse(400, query.error);
+          return;
+        }
+
+        // Per-IP throttle (GEV_RATELIMIT_GOOGLE_PER_MIN), shared with the
+        // Places routes because both spend the same Google budget.
+        const _grl = googleRateLimiter();
+        if (_grl && !_grl(clientKey(req))) {
+          res.statusCode = 429;
+          res.setHeader('Content-Type', 'application/json');
+          res.setHeader('Retry-After', '5');
+          res.end(
+            JSON.stringify({
+              status: 'OVER_QUERY_LIMIT',
+              results: [],
+              error: 'Rate limit exceeded',
+            }),
+          );
+          return;
+        }
+
+        try {
+          const upstream = new URL(
+            endpoints.geocode ||
+              'https://maps.googleapis.com/maps/api/geocode/json',
+          );
+          for (const [name, value] of Object.entries(query.params))
+            upstream.searchParams.set(name, value);
+          upstream.searchParams.set('key', apiKey);
+          const deadline = AbortSignal.timeout(GEOCODE_UPSTREAM_TIMEOUT_MS);
+          const response = await fetchImpl(upstream.toString(), {
+            redirect: 'error',
+            signal: deadline,
+          });
+          // An unreadable, oversized or timed-out body is not an answer: it
+          // falls through to the same shaped failure as a refusal below.
+          const data = await readResponseJsonCapped(
+            response,
+            GEOCODE_MAX_RESPONSE_BYTES,
+            deadline,
+          ).catch(() => null);
+
+          // A body we could not read is an upstream failure, not an answer with
+          // a status of its own, so it does not borrow the upstream's code.
+          if (!data) {
+            res.statusCode = 502;
+            res.setHeader('Content-Type', 'application/json; charset=utf-8');
+            res.end(
+              JSON.stringify({
+                status: 'UNKNOWN_ERROR',
+                results: [],
+                error: 'Google Geocoding request failed',
+              }),
+            );
+            return;
+          }
+
+          res.statusCode = response.ok ? 200 : response.status;
+          res.setHeader('Content-Type', 'application/json; charset=utf-8');
+          res.setHeader('Cache-Control', 'private, max-age=300');
+          res.end(JSON.stringify(data));
+        } catch {
+          // Fixed public text: a transport, URL or runtime message would
+          // describe the server to the browser (SECURITY.md, sanitized errors).
+          res.statusCode = 502;
+          res.setHeader('Content-Type', 'application/json; charset=utf-8');
+          res.end(
+            JSON.stringify({
+              status: 'UNKNOWN_ERROR',
+              results: [],
+              error: 'Google Geocoding request failed',
+            }),
+          );
+        }
+      });
+    }
+
+    installGeocodeRoute('/api/google/geocode', (searchParams) => {
+      const address = validateGeocodeAddress(searchParams);
+      if (!address.ok) return address;
+      const bounds = geocodeBounds(searchParams);
+      return {
+        ok: true,
+        params: {
+          address: address.address,
+          ...(bounds ? { bounds } : {}),
+        },
+      };
+    });
+
+    installGeocodeRoute('/api/google/reverse-geocode', (searchParams) => {
+      const coordinates = validatePlacesCoordinates(searchParams);
+      if (!coordinates.ok) return coordinates;
+      const { latitude, longitude } = coordinates;
+      return { ok: true, params: { latlng: `${latitude},${longitude}` } };
+    });
   }
 
   return {