Add Access-Control-Max-Age header on CORS preflight and improve external logging (v0.6.4)

- Add cors_max_age parameter to make_wsgi_app() (default 7200s / 2 hours)
- New _CorsMaxAgeMiddleware sets Access-Control-Max-Age on OPTIONS responses
- Fix external.py SHA-256 docstring (pre-compression, not post-compression)
- Improve externalize logging to show both raw and uploaded byte sizes

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rustyconover

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-rpc"
-version = "0.6.3"
+version = "0.6.4"
 description = "Vector Gateway Interface - RPC framework based on Apache Arrow"
 readme = "README.md"
 requires-python = ">=3.13"

tests/test_http.py

@@ -1133,6 +1133,38 @@ def test_no_cors_by_default(self) -> None:
         resp = tc.simulate_options("/add", headers={"Origin": "http://example.com"})
         assert "access-control-allow-origin" not in resp.headers
 
+    def test_cors_max_age_default(self) -> None:
+        """OPTIONS responses include Access-Control-Max-Age: 7200 by default."""
+        server = RpcServer(RpcFixtureService, RpcFixtureServiceImpl())
+        app = make_wsgi_app(server, signing_key=b"test", cors_origins="*")
+        tc = falcon.testing.TestClient(app)
+        resp = tc.simulate_options("/add", headers={"Origin": "http://example.com"})
+        assert resp.headers.get("access-control-max-age") == "7200"
+
+    def test_cors_max_age_custom(self) -> None:
+        """cors_max_age overrides the default value."""
+        server = RpcServer(RpcFixtureService, RpcFixtureServiceImpl())
+        app = make_wsgi_app(server, signing_key=b"test", cors_origins="*", cors_max_age=3600)
+        tc = falcon.testing.TestClient(app)
+        resp = tc.simulate_options("/add", headers={"Origin": "http://example.com"})
+        assert resp.headers.get("access-control-max-age") == "3600"
+
+    def test_cors_max_age_none_omits_header(self) -> None:
+        """cors_max_age=None omits the Access-Control-Max-Age header."""
+        server = RpcServer(RpcFixtureService, RpcFixtureServiceImpl())
+        app = make_wsgi_app(server, signing_key=b"test", cors_origins="*", cors_max_age=None)
+        tc = falcon.testing.TestClient(app)
+        resp = tc.simulate_options("/add", headers={"Origin": "http://example.com"})
+        assert "access-control-max-age" not in resp.headers
+
+    def test_cors_max_age_not_on_post(self) -> None:
+        """Access-Control-Max-Age is only set on OPTIONS, not regular requests."""
+        server = RpcServer(RpcFixtureService, RpcFixtureServiceImpl())
+        app = make_wsgi_app(server, signing_key=b"test", cors_origins="*")
+        tc = falcon.testing.TestClient(app)
+        resp = tc.simulate_get("/", headers={"Origin": "http://example.com"})
+        assert "access-control-max-age" not in resp.headers
+
 
 # ---------------------------------------------------------------------------
 # Tests: Max request bytes header

vgi_rpc/external.py

@@ -387,8 +387,8 @@ def make_external_location_batch(
     Args:
         schema: The schema the pointer batch should conform to.
         url: The URL where the actual data resides.
-        sha256: Optional hex-encoded SHA-256 of the stored bytes
-            (post-compression).  Included as ``vgi_rpc.location.sha256``
+        sha256: Optional hex-encoded SHA-256 of the raw IPC bytes
+            (pre-compression).  Included as ``vgi_rpc.location.sha256``
             metadata so consumers can verify data integrity on fetch.
 
     Returns:
@@ -651,16 +651,23 @@ def maybe_externalize_collector(
         ipc_bytes = zstandard.ZstdCompressor(level=config.compression.level).compress(ipc_bytes)
         content_encoding = config.compression.algorithm
 
+    raw_size = original_bytes if original_bytes is not None else len(ipc_bytes)
     url = _traced_upload(
         ipc_bytes, out.output_schema, config.storage, content_encoding=content_encoding, original_bytes=original_bytes
     )
     _logger.debug(
-        "Batch externalized: %s (%d bytes, compressed=%s, sha256=%s)",
+        "Batch externalized: %s (%d bytes raw, %d bytes uploaded, compressed=%s, sha256=%s)",
         url,
+        raw_size,
         len(ipc_bytes),
         content_encoding is not None,
         data_sha256,
-        extra={"url": url, "size_bytes": len(ipc_bytes), "compressed": content_encoding is not None},
+        extra={
+            "url": url,
+            "raw_size_bytes": raw_size,
+            "uploaded_size_bytes": len(ipc_bytes),
+            "compressed": content_encoding is not None,
+        },
     )
 
     pointer_batch, pointer_cm = make_external_location_batch(out.output_schema, url, sha256=data_sha256)
@@ -724,16 +731,23 @@ def maybe_externalize_batch(
         ipc_bytes = zstandard.ZstdCompressor(level=config.compression.level).compress(ipc_bytes)
         content_encoding = config.compression.algorithm
 
+    raw_size = original_bytes if original_bytes is not None else len(ipc_bytes)
     url = _traced_upload(
         ipc_bytes, batch.schema, config.storage, content_encoding=content_encoding, original_bytes=original_bytes
     )
     _logger.debug(
-        "Batch externalized: %s (%d bytes, compressed=%s, sha256=%s)",
+        "Batch externalized: %s (%d bytes raw, %d bytes uploaded, compressed=%s, sha256=%s)",
         url,
+        raw_size,
         len(ipc_bytes),
         content_encoding is not None,
         data_sha256,
-        extra={"url": url, "size_bytes": len(ipc_bytes), "compressed": content_encoding is not None},
+        extra={
+            "url": url,
+            "raw_size_bytes": raw_size,
+            "uploaded_size_bytes": len(ipc_bytes),
+            "compressed": content_encoding is not None,
+        },
     )
 
     return make_external_location_batch(batch.schema, url, sha256=data_sha256)

vgi_rpc/http/_server.py

@@ -1958,6 +1958,26 @@ def process_response(
             resp.set_header("Content-Encoding", "zstd")
 
 
+class _CorsMaxAgeMiddleware:
+    """Falcon middleware that sets ``Access-Control-Max-Age`` on OPTIONS responses."""
+
+    __slots__ = ("_max_age",)
+
+    def __init__(self, max_age: int) -> None:
+        self._max_age = str(max_age)
+
+    def process_response(
+        self,
+        req: falcon.Request,
+        resp: falcon.Response,
+        resource: object,
+        req_succeeded: bool,
+    ) -> None:
+        """Set Access-Control-Max-Age on preflight OPTIONS responses."""
+        if req.method == "OPTIONS":
+            resp.set_header("Access-Control-Max-Age", self._max_age)
+
+
 class _CapabilitiesMiddleware:
     """Falcon middleware that sets capability headers on every response."""
 
@@ -1988,6 +2008,7 @@ def make_wsgi_app(
     max_request_bytes: int | None = None,
     authenticate: Callable[[falcon.Request], AuthContext] | None = None,
     cors_origins: str | Iterable[str] | None = None,
+    cors_max_age: int | None = 7200,
     upload_url_provider: UploadUrlProvider | None = None,
     max_upload_bytes: int | None = None,
     otel_config: object | None = None,
@@ -2040,6 +2061,10 @@ def make_wsgi_app(
             disables CORS headers.  Uses Falcon's built-in
             ``CORSMiddleware`` which also handles preflight OPTIONS
             requests automatically.
+        cors_max_age: Value for the ``Access-Control-Max-Age`` header on
+            preflight OPTIONS responses, in seconds.  ``7200`` (2 hours)
+            by default.  ``None`` omits the header.  Only effective when
+            ``cors_origins`` is set.
         upload_url_provider: Optional provider for generating pre-signed
             upload URLs.  When set, the ``__upload_url__/init`` endpoint
             is enabled and ``VGI-Upload-URL-Support: true`` is advertised
@@ -2169,6 +2194,8 @@ def make_wsgi_app(
             "expose_headers": cors_expose,
         }
         middleware.append(falcon.CORSMiddleware(**cors_kwargs))
+        if cors_max_age is not None:
+            middleware.append(_CorsMaxAgeMiddleware(cors_max_age))
     if authenticate is not None:
         on_auth_failure: Callable[[str | None, str], None] | None = None
         if otel_config is not None: