From 4014037e505876ed8c4df229ace3a65092e64ca8 Mon Sep 17 00:00:00 2001
From: Murilo Ijanc <murilo@ijanc.org>
Date: Mon, 27 Jul 2026 20:39:38 -0300
Subject: Expose the faixa a missing CEP would have belonged to

A CEP that fails is rarely a random number: it is someone who knows the
city and guessed the digits, and the classic guess is the -000 that 957
municipalities never received. The API now attaches that municipality to
the 404, and a caller left with nothing but "does not exist" cannot tell
a typo in a real city from a CEP that was never plausible.

It goes in CEPIS-STATUS, not CEPIS-ADDRESS. The call has still failed
and the address is still empty; putting a localidade where the address
lives would let a caller that forgets to test the status read Areal as
the answer to a CEP that does not exist.

Parsing is best effort throughout. faixa is omitted rather than sent as
null for a band no municipality owns, so its absence is the normal case
and there is a flag instead of a marker value; a block that is missing,
is not an object, or is short of localidade, uf, cep_ini, cep_fim and
ceps is dropped and the not-found comes back clean. Failing a 404 the
caller already understands over a decoration on it would be a poor
trade.

cep_ini and cep_fim are the CEPs that exist, not the bounds the Correios
publish, and the span between them is mostly empty -- hence ceps beside
them, so the pair is not read as a list.
---
 tests/server.py | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

(limited to 'tests/server.py')

diff --git a/tests/server.py b/tests/server.py
index 46185a0..57fa120 100644
--- a/tests/server.py
+++ b/tests/server.py
@@ -76,6 +76,22 @@ SYNTHETIC = [
 
 DROPPED_CEP = "00000099"
 
+# The municipality a missing CEP would have belonged to, attached to the
+# 404 for /25845000 below. The numbers are Areal/RJ's real ones: cep_ini is
+# 25845001, one past the 25845000 the DNE publishes as the start of the
+# range and that the route refuses, and the 118 CEPs are scattered over the
+# ~4900 numbers up to cep_fim rather than filling them.
+AREAL = {
+    "localidade": "Areal",
+    "uf": "RJ",
+    "estado": "Rio de Janeiro",
+    "regiao": "Sudeste",
+    "ibge": "3300225",
+    "cep_ini": "25845001",
+    "cep_fim": "25849899",
+    "ceps": 118,
+}
+
 LONG_STREET = "Avenida " + ("Muito Comprida " * 20)
 
 COUNTS = {}
@@ -166,6 +182,32 @@ def route(path, query, hits):
         return 404, json_body(
             {"erro": "cep_nao_encontrado", "mensagem": "gone"}
         ), {}
+    if path == "/25845000":
+        return 404, json_body(
+            {
+                "erro": "cep_nao_encontrado",
+                "mensagem": "CEP não existe na base do DNE",
+                "faixa": AREAL,
+            }
+        ), {}
+    if path == "/25849900":
+        return 404, json_body(
+            {
+                "erro": "cep_nao_encontrado",
+                "mensagem": "CEP não existe na base do DNE",
+            }
+        ), {}
+    if path == "/25845002":
+        broken = dict(AREAL)
+        broken["cep_fim"] = "nope"
+        broken["ceps"] = "many"
+        return 404, json_body(
+            {"erro": "cep_nao_encontrado", "faixa": broken}
+        ), {}
+    if path == "/25845003":
+        return 404, json_body(
+            {"erro": "cep_nao_encontrado", "faixa": "Areal"}
+        ), {}
     if path == "/00000000":
         return 400, json_body(
             {"erro": "cep_invalido", "mensagem": "rejected by the API"}
-- 
cgit v1.3