Skip to content

https://arxiv.org/abs/2606.28344. The end of web parsing. The beginning of scalable pixel-native search. link: https://pixelrag.ai/

fix(serve): bound /reconstruct and stop unknown ids becoming 500s (#161)

Shubham Srivastava7a484cbc7ca9
diff --git a/serve/src/pixelrag_serve/api.py b/serve/src/pixelrag_serve/api.py
index d606a9e..7b7f003 100644
--- a/serve/src/pixelrag_serve/api.py
+++ b/serve/src/pixelrag_serve/api.py
@@ -639,8 +639,15 @@ async def departments():
}
+# Bound for the public /reconstruct endpoint: every id returns a full
+# `dimension`-length float list, which serializes to ~40 KB of JSON at dim 2048,
+# and the first call builds a direct map over the whole index. Real callers
+# debug a handful of vectors at a time.
+_MAX_RECONSTRUCT_IDS = 256
+
+
class ReconstructRequest(BaseModel):
- vector_ids: list[int | str]
+ vector_ids: list[int | str] = Field(max_length=_MAX_RECONSTRUCT_IDS)
@app.post("/reconstruct")
diff --git a/serve/src/pixelrag_serve/backends.py b/serve/src/pixelrag_serve/backends.py
index 1d60edd..388d453 100644
--- a/serve/src/pixelrag_serve/backends.py
+++ b/serve/src/pixelrag_serve/backends.py
@@ -163,7 +163,23 @@ class FaissBackend:
if not self._direct_map_built and hasattr(self.index, "make_direct_map"):
self.index.make_direct_map()
self._direct_map_built = True
- return [self.index.reconstruct(int(v)).tolist() for v in vids]
+ out = []
+ for v in vids:
+ # Vectors are added sequentially (index.add, no IDMap), so valid ids
+ # are 0..ntotal-1. An unknown or non-integer id yields None — the
+ # protocol's documented `list[float] | None`, and what QdrantBackend
+ # already does — instead of an uncaught ValueError/RuntimeError
+ # surfacing as a 500 on the public endpoint.
+ try:
+ i = int(v)
+ except (TypeError, ValueError):
+ out.append(None)
+ continue
+ if not 0 <= i < self.index.ntotal:
+ out.append(None)
+ continue
+ out.append(self.index.reconstruct(i).tolist())
+ return out
class QdrantBackend:
diff --git a/tests/test_serve_backends.py b/tests/test_serve_backends.py
index dac367e..f5ec04a 100644
--- a/tests/test_serve_backends.py
+++ b/tests/test_serve_backends.py
@@ -185,5 +185,16 @@ def test_reconstruct_round_trips(backend):
np.testing.assert_allclose(np.asarray(vecs[1]), VECTORS[5], atol=1e-6)
+def test_reconstruct_unknown_id_is_none(backend):
+ # Both backends report an id they don't hold as None rather than raising —
+ # /reconstruct is public, so an unknown id must not become a 500.
+ assert backend.reconstruct([1, 10**6])[1:] == [None]
+
+
+def test_reconstruct_non_integer_id_is_none(faiss_backend):
+ # FAISS ids are integers; a non-numeric id is a client mistake, not a crash.
+ assert faiss_backend.reconstruct(["not-an-id"]) == [None]
+
+
def test_k_zero_returns_empty(backend):
assert backend.raw_search(VECTORS[0:1], 0) == [[]]
diff --git a/tests/test_serve_reconstruct.py b/tests/test_serve_reconstruct.py
new file mode 100644
index 0000000..a8fe148
--- /dev/null
+++ b/tests/test_serve_reconstruct.py
@@ -0,0 +1,18 @@
+"""Input bound on the public /reconstruct endpoint (OOM/DoS hardening).
+
+Every id returns a full `dimension`-length float list (~40 KB of JSON at dim
+2048) and the first call builds a direct map over the index, so an unbounded
+`vector_ids` list is the same class of trivial OOM as the /search bounds.
+"""
+
+import pytest
+
+pytest.importorskip("fastapi", reason="serve extra not installed")
+from pixelrag_serve.api import _MAX_RECONSTRUCT_IDS, ReconstructRequest
+from pydantic import ValidationError
+
+
+def test_vector_ids_are_capped():
+ ReconstructRequest(vector_ids=list(range(_MAX_RECONSTRUCT_IDS)))
+ with pytest.raises(ValidationError):
+ ReconstructRequest(vector_ids=list(range(_MAX_RECONSTRUCT_IDS + 1)))