Address review feedback

- Update the stale `_MAX_SEGMENT_BODY_BYTES` comment. It still claimed the cap
  was unenforced for chunked uploads, which stopped being true in d70a7a4 when
  `_body_iter` started counting cumulative bytes. Documented both enforcement
  points (Content-Length up front, streamed bytes as the real backstop).
- Document that a concurrency slot is deliberately held for the whole proxied
  call — launch plus inference — and why that differs from the conversion and
  Whitebox caps, which enqueue a background job and return immediately.
- Annotate the shared `calls` buffers on `_FakeHttpx` / `_ErrorHttpx` as
  `ClassVar[list]` so the intentional class-level sharing is explicit.
- Add the missing `-> Iterator[bytes]` return annotation to `_oversized_body`.

Author: giswqs

backend/geolibre_server/geolibre_server/app/ml.py

@@ -69,14 +69,21 @@
 
 # Cap concurrent segmentation proxy requests so a burst of large uploads cannot
 # exhaust sidecar memory or starve the event loop. Mirrors the conversion
-# engine's MAX_IN_FLIGHT_JOBS pattern.
+# engine's MAX_IN_FLIGHT_JOBS pattern, with one difference worth knowing: those
+# endpoints enqueue a background job and return immediately, whereas this is a
+# streaming proxy, so a slot is held for the whole call — the samgeo-api launch
+# (_HEALTH_TIMEOUT_SECS) plus inference (_PROXY_TIMEOUT_SECS). That is
+# deliberate: the resource being rationed is the held connection and the
+# in-flight upload, not a queue position.
 MAX_IN_FLIGHT_SEGMENT_REQUESTS = 4
 _segment_lock = threading.Lock()
 _segment_in_flight = 0
 
-# Reject uploads whose Content-Length exceeds this (100 MiB). When the header
-# is missing (chunked transfer) the limit is not enforced — the backend's own
-# size handling applies.
+# Reject uploads larger than this (100 MiB). Enforced twice: once up front on
+# Content-Length so an oversized upload is refused before any bytes are read,
+# and again on the cumulative bytes seen in ``_body_iter``, which is what
+# actually covers a client that omits the header (chunked transfer) or sends a
+# non-numeric one.
 _MAX_SEGMENT_BODY_BYTES = 100 * 1024 * 1024
 
 # Guards the launch-or-reuse decision for the child process.

backend/geolibre_server/tests/test_ml.py

@@ -10,6 +10,8 @@
 import asyncio
 import json
 import subprocess
+from collections.abc import Iterator
+from typing import ClassVar
 
 import pytest
 
@@ -62,7 +64,7 @@ class _FakeHTTPError(Exception):
 class _FakeHttpx:
     """Minimal stand-in for the httpx module used by ml.py."""
 
-    calls: list = []
+    calls: ClassVar[list] = []
     HTTPError = _FakeHTTPError
     AsyncClient = _FakeAsyncClient
 
@@ -290,7 +292,7 @@ def test_segment_releases_slot_after_upstream_failure(monkeypatch):
     from geolibre_server.app.main import app
 
     class _ErrorHttpx:
-        calls: list = []
+        calls: ClassVar[list] = []
         HTTPError = Exception
 
         class AsyncClient:
@@ -358,7 +360,7 @@ def test_segment_rejects_oversized_chunked_stream(monkeypatch):
     monkeypatch.setattr(ml, "_require_httpx", lambda: _FakeHttpx)
     monkeypatch.setattr(ml, "_ensure_server", lambda: "http://backend:9")
 
-    def _oversized_body():
+    def _oversized_body() -> Iterator[bytes]:
         yield b"x" * 50
 
     client = TestClient(app)