Carry the band's municipality on a not-found CEPHEADv0.2.0main

A CEP that fails is almost never random: it is someone who knows the city
and guessed the number, usually the -000 that 957 municipalities never
received. The API now answers those 404s with a faixa block naming the
municipality that owns the band, so CepNotFoundException exposes it and
says it in its message.

It stays an error. The band is context, not an address, and its cep_ini
and cep_fim are the smallest and largest CEP that actually exist there —
not the bounds the Correios publish, and not a dense interval — so the
type documents both traps rather than inviting callers to walk the range.

Reading it is best effort: a missing, malformed or oddly shaped faixa is
dropped, because turning a definitive answer about the request into a
parse failure would hide the answer.

3 files changed, 110 insertions, 0 deletions

diff --git a/src/test/java/is/cep/cepis/HttpTest.java b/src/test/java/is/cep/cepis/HttpTest.java
index 42038d4..a6594a2 100644
--- a/src/test/java/is/cep/cepis/HttpTest.java
+++ b/src/test/java/is/cep/cepis/HttpTest.java
@@ -23,6 +23,16 @@ public abstract class HttpTest {
             "estado":"São Paulo","regiao":"Sudeste","ibge":"3550308","gia":"1004",\
             "ddd":"11","siafi":"7107"}""";
 
+    /**
+     * The 404 the API returns for 25845000, a CEP that does not exist in a
+     * band that Areal/RJ does own.
+     */
+    protected static final String NOT_FOUND_WITH_FAIXA = """
+            {"erro":"cep_nao_encontrado","mensagem":"CEP não existe na base do DNE",\
+            "faixa":{"localidade":"Areal","uf":"RJ","estado":"Rio de Janeiro",\
+            "regiao":"Sudeste","ibge":"3300225","cep_ini":"25845001",\
+            "cep_fim":"25849899","ceps":118}}""";
+
     /** The header row of the batch endpoint. */
     protected static final String CSV_HEADER =
             "cep,logradouro,complemento,unidade,bairro,localidade,uf,estado,regiao,"
diff --git a/src/test/java/is/cep/cepis/LookupTest.java b/src/test/java/is/cep/cepis/LookupTest.java
index 8934dca..46253e1 100644
--- a/src/test/java/is/cep/cepis/LookupTest.java
+++ b/src/test/java/is/cep/cepis/LookupTest.java
@@ -80,6 +80,79 @@ public final class LookupTest extends HttpTest {
         CepNotFoundException failure = assertThrows(CepNotFoundException.class,
                 () -> client.lookup("99999999"), "a missing CEP");
         assertContains(failure.getMessage(), "99999999", "the message names the CEP");
+        assertTrue(failure.faixa().isEmpty(), "no band was sent");
+    }
+
+    /** A 404 may name the municipality whose band the CEP fell in. */
+    public void testNotFoundCarriesTheBand() {
+        server.respond("/25845000", Reply.of(404, NOT_FOUND_WITH_FAIXA));
+        CepNotFoundException failure = assertThrows(CepNotFoundException.class,
+                () -> client.lookup("25845-000"), "a missing CEP in a known band");
+        Faixa faixa = failure.faixa().orElseThrow();
+        assertEquals("Areal", faixa.localidade(), "localidade");
+        assertEquals("RJ", faixa.uf(), "uf");
+        assertEquals("Rio de Janeiro", faixa.estado(), "estado");
+        assertEquals("Sudeste", faixa.regiao(), "regiao");
+        assertEquals("3300225", faixa.ibge(), "ibge");
+        assertEquals("25845001", faixa.cepIni(), "cep_ini is the first that exists");
+        assertEquals("25849899", faixa.cepFim(), "cep_fim is the last that exists");
+        assertEquals(118L, faixa.ceps(), "how many exist in between");
+        assertEquals("Areal/RJ", faixa.describe(), "describe");
+    }
+
+    /** The band is context for the failure, not a result. */
+    public void testTheBandDoesNotBecomeAnAddress() {
+        server.respond("/25845000", Reply.of(404, NOT_FOUND_WITH_FAIXA));
+        CepNotFoundException failure = assertThrows(CepNotFoundException.class,
+                () -> client.lookup("25845000"), "still a not-found");
+        assertContains(failure.getMessage(), "25845000", "the message names the CEP");
+        assertContains(failure.getMessage(), "Areal", "and the municipality");
+    }
+
+    /** A 404 without the band is the plain not-found it always was. */
+    public void testNotFoundWithoutTheBand() {
+        server.respond("/99999999", Reply.of(404,
+                "{\"erro\":\"cep_nao_encontrado\",\"mensagem\":\"CEP não existe\"}"));
+        CepNotFoundException failure = assertThrows(CepNotFoundException.class,
+                () -> client.lookup("99999999"), "a CEP no municipality owns");
+        assertTrue(failure.faixa().isEmpty(), "the field is absent, not null");
+        assertFalse(failure.getMessage().contains("band belongs to"),
+                "and the message says nothing about a municipality");
+    }
+
+    /** An explicit null band is absence too, not a parse failure. */
+    public void testNullBandIsAbsence() {
+        server.respond("/99999999",
+                Reply.of(404, "{\"erro\":\"cep_nao_encontrado\",\"faixa\":null}"));
+        CepNotFoundException failure = assertThrows(CepNotFoundException.class,
+                () -> client.lookup("99999999"), "a missing CEP");
+        assertTrue(failure.faixa().isEmpty(), "null is no band");
+    }
+
+    /** A malformed band costs the band, never the not-found. */
+    public void testMalformedBandStillNotFound() {
+        server.respond("/99999999", Reply.of(404,
+                "{\"erro\":\"cep_nao_encontrado\",\"faixa\":{\"uf\":\"RJ\",\"ceps\":\"many\"}}"));
+        CepNotFoundException failure = assertThrows(CepNotFoundException.class,
+                () -> client.lookup("99999999"), "a missing CEP");
+        assertTrue(failure.faixa().isEmpty(), "a band with no localidade is dropped");
+    }
+
+    /** A band that is not even an object is dropped just as quietly. */
+    public void testBandOfTheWrongShapeStillNotFound() {
+        server.respond("/99999999",
+                Reply.of(404, "{\"erro\":\"cep_nao_encontrado\",\"faixa\":\"Areal\"}"));
+        CepNotFoundException failure = assertThrows(CepNotFoundException.class,
+                () -> client.lookup("99999999"), "a missing CEP");
+        assertTrue(failure.faixa().isEmpty(), "a string is no band");
+    }
+
+    /** A 404 whose body is not JSON at all is still a clean not-found. */
+    public void testNotFoundWithAnUnreadableBody() {
+        server.respond("/99999999", Reply.of(404, "<html>gateway</html>"));
+        CepNotFoundException failure = assertThrows(CepNotFoundException.class,
+                () -> client.lookup("99999999"), "the status decides, not the body");
+        assertTrue(failure.faixa().isEmpty(), "nothing to read");
     }
 
     /** A 404 is definitive; retrying it only burns someone's quota. */
diff --git a/src/test/java/is/cep/cepis/ModelTest.java b/src/test/java/is/cep/cepis/ModelTest.java
index 26deb5a..c8a3269 100644
--- a/src/test/java/is/cep/cepis/ModelTest.java
+++ b/src/test/java/is/cep/cepis/ModelTest.java
@@ -3,6 +3,7 @@ package is.cep.cepis;
 import static is.cep.cepis.Assertions.assertEquals;
 import static is.cep.cepis.Assertions.assertFalse;
 import static is.cep.cepis.Assertions.assertNull;
+import static is.cep.cepis.Assertions.assertThrows;
 import static is.cep.cepis.Assertions.assertTrue;
 
 import java.util.LinkedHashMap;
@@ -68,6 +69,32 @@ public final class ModelTest {
         assertFalse(new Geo(-23.5, -46.6, 22000, "localidade").isPrecise(), "a municipality");
     }
 
+    /** A band block without a municipality is not a band. */
+    public void testFaixaNeedsALocalidade() {
+        assertThrows(IllegalArgumentException.class,
+                () -> Faixa.fromJson(Map.of("uf", "RJ", "ceps", 118)),
+                "the municipality is the whole point of the block");
+    }
+
+    /** A partial band keeps what it has instead of being dropped. */
+    public void testFaixaToleratesAPartialBlock() {
+        Faixa faixa = Faixa.fromJson(Map.of("localidade", "Areal"));
+        assertEquals("", faixa.uf(), "uf");
+        assertEquals("", faixa.cepIni(), "cepIni");
+        assertEquals(0L, faixa.ceps(), "ceps");
+        assertEquals("Areal", faixa.describe(), "describe without a state");
+    }
+
+    /** The bounds are strings, so a CEP starting in zero survives. */
+    public void testFaixaBoundsKeepTheirLeadingZeros() {
+        Faixa faixa = Faixa.fromJson(Map.of("localidade", "São Paulo", "uf", "SP",
+                "cep_ini", "01001001", "cep_fim", "05999999", "ceps", 3421));
+        assertEquals("01001001", faixa.cepIni(), "cepIni");
+        assertEquals("05999999", faixa.cepFim(), "cepFim");
+        assertEquals(3421L, faixa.ceps(), "the interval is sparse, and this is its census");
+        assertEquals("São Paulo/SP", faixa.describe(), "describe");
+    }
+
     /** Health tolerates a partial body rather than failing the check. */
     public void testHealthDefaults() {
         Health health = Health.fromJson(Map.of("status", "ok"));