diff options
Diffstat (limited to 'lib/cepis')
| -rw-r--r-- | lib/cepis/client.rb | 41 | ||||
| -rw-r--r-- | lib/cepis/errors.rb | 20 | ||||
| -rw-r--r-- | lib/cepis/models.rb | 85 | ||||
| -rw-r--r-- | lib/cepis/version.rb | 2 |
4 files changed, 144 insertions, 4 deletions
diff --git a/lib/cepis/client.rb b/lib/cepis/client.rb index f451061..8480315 100644 --- a/lib/cepis/client.rb +++ b/lib/cepis/client.rb @@ -113,10 +113,15 @@ module Cepis # message: the format already passed local validation, so the server knows # something this client does not. # + # A 404 may carry {CEPNotFound#faixa}: the municipality that owns the band + # of numbers the CEP fell into. It is still a 404 and still an exception — + # the context does not make a nonexistent CEP into an address. See {Faixa}. + # # @param cep [String] masked or unmasked. # @return [Address] # @raise [InvalidCEP] the CEP is not 8 digits (no request is made). - # @raise [CEPNotFound] well-formed, but not in the database. + # @raise [CEPNotFound] well-formed, but not in the database. Carries + # {CEPNotFound#faixa} when the API named a municipality for the band. # @raise [RateLimited] 429 after every attempt. # @raise [ServerError] 5xx after every attempt. # @raise [NetworkError] the request never completed. @@ -125,7 +130,7 @@ module Cepis number = Cepis.normalize_cep(cep) status, body = request("/#{number}") - raise CEPNotFound, "CEP #{number} does not exist in the DNE database" if status == 404 + raise not_found(number, body) if status == 404 raise InvalidCEP, error_message(body, "CEP #{number} rejected") if status == 400 Address.from_json(parse_json(body)) @@ -219,6 +224,38 @@ module Cepis body.to_s.dup.force_encoding(Encoding::UTF_8).scrub end + # The {CEPNotFound} for a 404, with the band read off the body when it is + # there. + # + # Every step of reading it is allowed to fail into `nil`: an absent + # `faixa` is the ordinary case (the API omits it, it never sends null), + # and a body that is not JSON at all is a proxy's doing, not the caller's. + # Neither may promote a definitive, well-understood not-found into an + # {InvalidResponse} — the reason the lookup failed would be replaced by + # the reason the consolation prize failed to parse. + def not_found(number, body) + faixa = begin + data = JSON.parse(decode(body)) + data.is_a?(Hash) ? Faixa.from_json(data["faixa"]) : nil + rescue JSON::ParserError + nil + end + + CEPNotFound.new(not_found_message(number, faixa), faixa: faixa) + end + + # The message names the municipality when the API named one, because + # "does not exist" plus "the numbers around it are Areal/RJ" is what makes + # the log line diagnosable. The counts stay in the message too, so that + # nobody reads the two CEPs as the ends of a contiguous range. + def not_found_message(number, faixa) + base = "CEP #{number} does not exist in the DNE database" + return base if faixa.nil? + + "#{base} (it falls in the band of #{faixa.localidade}/#{faixa.uf}, which has " \ + "#{faixa.ceps} CEP(s) scattered between #{faixa.cep_ini} and #{faixa.cep_fim})" + end + def error_message(body, fallback) data = JSON.parse(decode(body)) data.is_a?(Hash) && data["mensagem"] ? String(data["mensagem"]) : fallback diff --git a/lib/cepis/errors.rb b/lib/cepis/errors.rb index 7a15841..71b8a29 100644 --- a/lib/cepis/errors.rb +++ b/lib/cepis/errors.rb @@ -27,7 +27,25 @@ module Cepis class InvalidCEP < Error; end # The CEP is well-formed but does not exist in the DNE database. - class CEPNotFound < Error; end + class CEPNotFound < Error + # The municipality that owns the band this CEP falls into, as a {Faixa}, + # or `nil` when no municipality owns it — or when the API did not say. + # + # It is context for the failure, not a fallback address: the CEP asked for + # does not exist, and this only names the neighbourhood of numbers it + # would have belonged to. Useful because a CEP that fails is usually a + # guess by someone who knows the city, so the municipality is the one + # thing about it that tends to be right. + # + # Read {Faixa} before showing `cep_ini`/`cep_fim` to anyone: the band is + # sparse, and the pair is not a range of valid CEPs. + attr_reader :faixa + + def initialize(message, faixa: nil) + super(message) + @faixa = faixa + end + end # The request never completed: DNS, refused connection, timeout, TLS. # diff --git a/lib/cepis/models.rb b/lib/cepis/models.rb index a0181ff..a80fe37 100644 --- a/lib/cepis/models.rb +++ b/lib/cepis/models.rb @@ -145,6 +145,91 @@ module Cepis end end + # The municipality that owns the band a **nonexistent** CEP falls into. + # + # It is context for an error, never an address: it arrives on the 404 of + # {Client#lookup}, hanging off {CEPNotFound#faixa}, and says "this CEP does + # not exist, but the numbers around it belong to Areal/RJ". The lookup still + # failed — nothing here turns it into a result. + # + # It is worth having because a CEP that fails is rarely a random number: it + # is usually someone who knows the city and guessed the digits. The classic + # guess is the `-000`, which 957 municipalities never received. + # + # **{#cep_ini} and {#cep_fim} are the smallest and the largest CEP that + # actually exist in the municipality, not the bounds the Correios publish.** + # The DNE's own start for Areal is `25845000` — exactly the CEP that just + # failed, which is why the published bounds would be useless here. + # + # **The band is sparse.** Areal's 118 CEPs are scattered across the ~4,900 + # numbers between `25845001` and `25849899`. {#ceps} is there to say so. Do + # not present the pair as a range of valid CEPs, and do not iterate it: all + # but a fiftieth of it does not exist. + class Faixa + attr_reader :localidade, :uf, :estado, :regiao, :ibge, :cep_ini, :cep_fim, :ceps + + def initialize(localidade:, uf:, estado:, regiao:, ibge:, cep_ini:, cep_fim:, ceps:) + @localidade = localidade + @uf = uf + @estado = estado + @regiao = regiao + @ibge = ibge + @cep_ini = cep_ini + @cep_fim = cep_fim + @ceps = ceps + freeze + end + + # Build from the hash the API returned, or `nil` when the block is + # missing, empty or malformed. + # + # The API **omits** `faixa` — it never sends null — for a CEP falling in a + # band no municipality owns, so absence is the ordinary case and not an + # anomaly. Anything unreadable is treated as absence too: this is a bonus + # on top of a failure that has already happened, and it must never be the + # reason a clean not-found becomes something else. + def self.from_json(data) + return nil unless data.is_a?(Hash) + + block = data.transform_keys(&:to_s) + localidade = String(block["localidade"] || "").strip + return nil if localidade.empty? + + new( + localidade: localidade, + uf: String(block["uf"] || ""), + estado: String(block["estado"] || ""), + regiao: String(block["regiao"] || ""), + ibge: String(block["ibge"] || ""), + cep_ini: String(block["cep_ini"] || ""), + cep_fim: String(block["cep_fim"] || ""), + ceps: Integer(block["ceps"] || 0, exception: false) || 0 + ) + rescue TypeError, ArgumentError + nil + end + + def to_h + { + localidade: @localidade, uf: @uf, estado: @estado, regiao: @regiao, + ibge: @ibge, cep_ini: @cep_ini, cep_fim: @cep_fim, ceps: @ceps + } + end + + def ==(other) + other.is_a?(Faixa) && to_h == other.to_h + end + alias eql? == + + def hash + to_h.hash + end + + def to_s + "#<Cepis::Faixa #{@localidade}/#{@uf} #{@cep_ini}-#{@cep_fim} #{@ceps} CEPs>" + end + end + # The response of `GET /health`. # # Good for two things: checking that the API answers, and knowing **which diff --git a/lib/cepis/version.rb b/lib/cepis/version.rb index cb88e06..ad38425 100644 --- a/lib/cepis/version.rb +++ b/lib/cepis/version.rb @@ -2,5 +2,5 @@ module Cepis # Version of this library, as reported in the default `User-Agent`. - VERSION = "0.1.0" + VERSION = "0.2.0" end |