diff --git a/CHANGELOG.md b/CHANGELOG.md index b6393b6..8f6dcc5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,14 @@ trace, study, receipt, API and database schema versions. ## [Unreleased] +### Changed + +- The API refuses request bodies larger than `AGENTLOOP_MAX_REQUEST_BYTES` + (default 16 MiB, `0` disables the limit) with `413`, before reading them into + memory. Bodies without a declared length are counted as they arrive. Earlier + versions accepted any size unless a proxy limited it. The cloud stack passes + the setting through so it can be raised together with the proxy limit. + ### Added - Trace labels are visible and searchable. Paginated trace listings include diff --git a/agentloop/request_limits.py b/agentloop/request_limits.py new file mode 100644 index 0000000..2519f01 --- /dev/null +++ b/agentloop/request_limits.py @@ -0,0 +1,102 @@ +"""Reject oversized API requests before they are buffered. + +Deployments without a reverse proxy (managed container platforms, a direct +``agentloop server``) would otherwise read request bodies of any size into +memory. The limit applies to the declared ``Content-Length`` and, for +streamed or chunked bodies, to the bytes actually received. +""" + +from __future__ import annotations + +import json +import os + +DEFAULT_MAX_REQUEST_BYTES = 16 * 1024 * 1024 +ENVIRONMENT_VARIABLE = "AGENTLOOP_MAX_REQUEST_BYTES" + + +def max_request_bytes(value: str | None = None) -> int | None: + """Parse the limit; ``0`` disables it. Invalid values fail at startup.""" + text = os.getenv(ENVIRONMENT_VARIABLE) if value is None else value + if text is None or not text.strip(): + return DEFAULT_MAX_REQUEST_BYTES + try: + limit = int(text.strip()) + except ValueError: + raise ValueError(f"{ENVIRONMENT_VARIABLE} must be a whole number of bytes") from None + if limit < 0: + raise ValueError(f"{ENVIRONMENT_VARIABLE} must be 0 (no limit) or a positive size") + return limit or None + + +class RequestSizeLimitMiddleware: + """ASGI middleware answering 413 for request bodies over ``limit`` bytes.""" + + def __init__(self, app, limit: int | None) -> None: + self.app = app + self.limit = limit + + async def __call__(self, scope, receive, send): + if scope["type"] != "http" or self.limit is None: + await self.app(scope, receive, send) + return + limit = self.limit + declared = None + for name, value in scope.get("headers", []): + if name == b"content-length": + try: + declared = int(value) + except ValueError: + declared = None + if declared is not None: + # The HTTP server already refuses bodies longer than their declared length. + if declared > limit: + await _reject(send, limit) + return + await self.app(scope, receive, send) + return + + # No declared length (for example chunked uploads): read up to the limit + # here, so the application never buffers more, then replay the body. + chunks: list[bytes] = [] + received = 0 + while True: + message = await receive() + if message["type"] != "http.request": + # The client disconnected; let the application see that. + replay = [message] + break + body = message.get("body", b"") + received += len(body) + if received > limit: + await _reject(send, limit) + return + chunks.append(body) + if not message.get("more_body", False): + replay = [{"type": "http.request", "body": b"".join(chunks), "more_body": False}] + break + + async def replay_receive(): + if replay: + return replay.pop(0) + return await receive() + + await self.app(scope, replay_receive, send) + + +async def _reject(send, limit: int) -> None: + body = json.dumps( + {"detail": f"request body exceeds the {limit}-byte limit ({ENVIRONMENT_VARIABLE})"} + ).encode("utf-8") + await send( + { + "type": "http.response.start", + "status": 413, + "headers": [ + (b"content-type", b"application/json"), + (b"content-length", str(len(body)).encode("ascii")), + (b"connection", b"close"), + ], + } + ) + await send({"type": "http.response.body", "body": body}) diff --git a/agentloop/server.py b/agentloop/server.py index 25f3f33..9fa5caa 100644 --- a/agentloop/server.py +++ b/agentloop/server.py @@ -19,6 +19,7 @@ from agentloop.optimizer import build_optimization_plan from agentloop.quality import QualityValidationError, build_quality_report from agentloop.ranking import RankingSort, sort_ranked +from agentloop.request_limits import RequestSizeLimitMiddleware, max_request_bytes from agentloop.schema import TraceValidationError, validate_elapsed_ms from agentloop.store import ( DEFAULT_PAGE_SIZE, @@ -45,6 +46,10 @@ versioned = APIRouter(tags=["API v1"]) legacy = APIRouter(deprecated=True, tags=["Deprecated aliases"]) +# Added first so it is the innermost layer around the routes; CORS still answers +# preflight requests and adds its headers to 413 responses. +app.add_middleware(RequestSizeLimitMiddleware, limit=max_request_bytes()) + _cors_origins = get_cors_origins() if _cors_origins: app.add_middleware( diff --git a/deploy/.env.example b/deploy/.env.example index b269f88..86569f5 100644 --- a/deploy/.env.example +++ b/deploy/.env.example @@ -28,3 +28,5 @@ AGENTLOOP_RETENTION_DAYS= # Largest trace upload the proxy accepts. AGENTLOOP_MAX_UPLOAD=16MB +# The API's own limit in bytes (default 16 MiB). Raise both together. +AGENTLOOP_MAX_REQUEST_BYTES=16777216 diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml index 1e6df1c..5ba812d 100644 --- a/deploy/docker-compose.yml +++ b/deploy/docker-compose.yml @@ -42,6 +42,7 @@ services: AGENTLOOP_REQUIRE_API_KEY: "true" AGENTLOOP_ADMIN_API_KEY: ${AGENTLOOP_ADMIN_API_KEY:?Set AGENTLOOP_ADMIN_API_KEY in deploy/.env} AGENTLOOP_CORS_ORIGINS: https://${AGENTLOOP_DASHBOARD_DOMAIN:?Set AGENTLOOP_DASHBOARD_DOMAIN in deploy/.env} + AGENTLOOP_MAX_REQUEST_BYTES: ${AGENTLOOP_MAX_REQUEST_BYTES:-16777216} depends_on: db: condition: service_healthy diff --git a/docs/CLOUD_DEPLOY.md b/docs/CLOUD_DEPLOY.md index ad05c4e..b511b22 100644 --- a/docs/CLOUD_DEPLOY.md +++ b/docs/CLOUD_DEPLOY.md @@ -224,8 +224,10 @@ These deployments are not exercised in CI. The same image and settings apply: keep it on a private network. Do not expose it publicly without one. Multiple API replicas can share one database; migrations are safe to run -concurrently. Set the platform's request size limit to match your largest -trace uploads. +concurrently. From 0.2.8 the API refuses request bodies over +`AGENTLOOP_MAX_REQUEST_BYTES` (16 MiB by default) with `413`, even without a +proxy in front; raise it, and any platform limit, to fit your largest trace +uploads. ## Kubernetes diff --git a/docs/PRODUCTION.md b/docs/PRODUCTION.md index 681c7a7..8d0be47 100644 --- a/docs/PRODUCTION.md +++ b/docs/PRODUCTION.md @@ -257,7 +257,10 @@ configured. From 0.2.7 it also publishes the container image to authenticated dashboard routes that users need. - Apply request-body limits, rate limits, timeouts, and access logging at the proxy. Trace payloads can be large and may contain sensitive prompts or tool - data. + data. From 0.2.8 the API also enforces `AGENTLOOP_MAX_REQUEST_BYTES` itself + (16 MiB by default, `0` for no limit): larger bodies get `413` before they are + read into memory, including chunked uploads without a declared length. An + invalid value stops the server at startup. - Restrict database network access to the API and dashboard workloads, require encrypted database connections in hosted environments, and test backups and restores. diff --git a/tests/test_request_limits.py b/tests/test_request_limits.py new file mode 100644 index 0000000..dd9bd5f --- /dev/null +++ b/tests/test_request_limits.py @@ -0,0 +1,91 @@ +from __future__ import annotations + +import pytest +from fastapi import FastAPI +from fastapi.testclient import TestClient +from pydantic import BaseModel + +from agentloop.request_limits import ( + DEFAULT_MAX_REQUEST_BYTES, + RequestSizeLimitMiddleware, + max_request_bytes, +) + + +class Payload(BaseModel): + text: str + + +def _client(limit): + app = FastAPI() + app.add_middleware(RequestSizeLimitMiddleware, limit=limit) + + @app.post("/echo") + def echo(payload: Payload) -> dict[str, int]: + return {"length": len(payload.text)} + + @app.get("/ping") + def ping() -> dict[str, str]: + return {"status": "ok"} + + return TestClient(app) + + +def test_requests_within_the_limit_pass(): + client = _client(100) + assert client.post("/echo", json={"text": "a" * 50}).json() == {"length": 50} + assert client.get("/ping").status_code == 200 + + +def test_a_declared_oversized_body_is_refused_before_reading(): + response = _client(100).post("/echo", json={"text": "a" * 200}) + assert response.status_code == 413 + assert "100-byte limit" in response.json()["detail"] + + +def test_a_streamed_body_without_a_length_is_counted(): + def chunks(): + yield b'{"text": "' + for _ in range(20): + yield b"a" * 10 + yield b'"}' + + response = _client(100).post( + "/echo", content=chunks(), headers={"content-type": "application/json"} + ) + assert response.status_code == 413 + + +def test_zero_disables_the_limit(): + assert _client(None).post("/echo", json={"text": "a" * 5000}).json() == {"length": 5000} + + +@pytest.mark.parametrize( + ("value", "expected"), + [ + (None, DEFAULT_MAX_REQUEST_BYTES), + ("", DEFAULT_MAX_REQUEST_BYTES), + ("0", None), + ("2048", 2048), + ], +) +def test_limit_setting(monkeypatch, value, expected): + if value is None: + monkeypatch.delenv("AGENTLOOP_MAX_REQUEST_BYTES", raising=False) + else: + monkeypatch.setenv("AGENTLOOP_MAX_REQUEST_BYTES", value) + assert max_request_bytes() == expected + + +@pytest.mark.parametrize("value", ["-1", "16MB", "1.5"]) +def test_invalid_limit_settings_fail_loudly(value): + with pytest.raises(ValueError, match="AGENTLOOP_MAX_REQUEST_BYTES"): + max_request_bytes(value) + + +def test_the_api_server_refuses_uploads_over_the_default_limit(): + from agentloop.server import app + + oversized = {"name": "x", "run_id": "too-big", "metadata": {"blob": "a" * (17 * 1024 * 1024)}} + response = TestClient(app).post("/v1/traces", json=oversized) + assert response.status_code == 413