Surface the faixa a 404 now carriesHEADv0.2.0main

A CEP that fails is almost never a random number. It is someone who knows
the city and guessed the last digits, and the guess is usually the -000 that
957 municipalities never received. The API answers those 404s with a faixa
object naming the municipality that owns the band, which turns "not found"
from a dead end into something the caller can act on - and the caller cannot
reach it through this library, because the 404 path never looked at the body
at all.

cepis_error is where a 404 already reports itself, so faixa goes there, as
inline storage rather than a pointer: the struct is documented as owning
nothing and declared on the caller's stack, and that stays true. It costs
sizeof(cepis_error), 272 bytes to 384, so 0.2.0 needs a recompile.

The parser needed one new primitive. cepis__json_field could only pull
scalars out of a flat object; splitting it over cepis__json_find, which
returns a pointer to a value of any shape, reaches one level down without
building a document tree - the same depth cepis__geo_parse already needs for
geo. Absence is the case that matters: no faixa, an empty one, or one that
is not an object all leave the error byte-for-byte what it was before.

cep_ini and cep_fim are deliberately not presented as a range. They are the
lowest and highest CEP that exist, the band is sparse - Areal's 118 CEPs are
scattered over ~4900 numbers - and ceps is the only honest count.

1 files changed, 39 insertions, 4 deletions

diff --git a/tests/server.py b/tests/server.py
index c77d7f6..09410b2 100755
--- a/tests/server.py
+++ b/tests/server.py
@@ -64,10 +64,33 @@ for _n in range(600):
         "ibge": "3550308", "gia": "", "ddd": "11", "siafi": "7107",
     }
 
+# Bands the API knows about. A 404 for a CEP inside one carries the owning
+# municipality in "faixa"; a 404 outside every band omits the key entirely.
+# cep_ini/cep_fim inside the object are the extreme CEPs that exist, which is
+# why they differ from the band bounds: 25845000 is in the band, is the DNE's
+# own start for Areal, and does not exist.
+FAIXAS = [
+    ("25845000", "25849999", {
+        "localidade": "Areal", "uf": "RJ", "estado": "Rio de Janeiro",
+        "regiao": "Sudeste", "ibge": "3300225", "cep_ini": "25845001",
+        "cep_fim": "25849899", "ceps": 118,
+    }),
+]
+
 HITS = {}
 LOCK = threading.Lock()
 
 
+def not_found(cep=None):
+    body = {"erro": "cep_nao_encontrado",
+            "mensagem": "CEP não existe na base do DNE"}
+    for low, high, faixa in FAIXAS:
+        if cep is not None and low <= cep <= high:
+            body["faixa"] = faixa
+            break
+    return json.dumps(body, ensure_ascii=False)
+
+
 def bump(prefix):
     with LOCK:
         HITS[prefix] = HITS.get(prefix, 0) + 1
@@ -167,6 +190,20 @@ class Handler(BaseHTTPRequestHandler):
         if prefix == "escaped":
             self.send(200, json.dumps(DB["01001000"], ensure_ascii=True))
             return
+        if prefix == "faixavazia":
+            self.send(404, json.dumps({
+                "erro": "cep_nao_encontrado",
+                "mensagem": "CEP não existe na base do DNE",
+                "faixa": {},
+            }, ensure_ascii=False))
+            return
+        if prefix == "faixatexto":
+            self.send(404, json.dumps({
+                "erro": "cep_nao_encontrado",
+                "mensagem": "CEP não existe na base do DNE",
+                "faixa": "Areal",
+            }, ensure_ascii=False))
+            return
 
         if parts and parts[0] == "health":
             body = {"status": "ok", "dne": "26071", "ceps": 1596168,
@@ -194,8 +231,7 @@ class Handler(BaseHTTPRequestHandler):
             return
 
         if not parts:
-            self.send(404, '{"erro":"cep_nao_encontrado",'
-                           '"mensagem":"CEP não existe na base do DNE"}')
+            self.send(404, not_found())
             return
 
         cep = parts[0]
@@ -205,8 +241,7 @@ class Handler(BaseHTTPRequestHandler):
             return
         entry = DB.get(cep)
         if entry is None:
-            self.send(404, '{"erro":"cep_nao_encontrado",'
-                           '"mensagem":"CEP não existe na base do DNE"}')
+            self.send(404, not_found(cep))
             return
         self.send(200, json.dumps(entry, ensure_ascii=False))