Name the municipality behind a CEP that does not existHEADv0.2.0main

A CEP that fails at the checkout is almost never a random number. It is
a shopper who knows perfectly well which town they live in and got a
digit wrong, most often by reaching for the -000 that 957 municipalities
never received. The API now names the municipality such a number would
have belonged to, in the body of its own 404, so the message can say
"that would be in Areal/RJ, which has CEPs from 25845-001 to 25849-899"
instead of leaving the shopper at a dead end with nothing to act on.

It stays an error. Nothing from it is written into a checkout field, on
either checkout and in either lookup mode: a CEP that does not exist has
no address, and filling one in from the municipality behind it means a
parcel delivered to the wrong town and a chargeback behind that. The one
module that reads the 404 body hands its callers a finished sentence and
never the data itself, so there is no shape in which it could leak into
a field later. The two CEPs quoted are the lowest and the highest that
really exist there, never a list and never a suggestion, because the
range is sparse enough that a number out of the middle of it would most
likely not exist either.

The widget correctly throws its 404 away without reading it, so the body
is fetched once more, on the miss path only and once per CEP. In proxy
mode PHP passes the municipality through with the 404 and caches it with
the miss, which is what keeps the two modes indistinguishable from the
browser. Anything missing or misshapen falls back to the message the
plugin has always shown.

1 files changed, 29 insertions, 1 deletions

diff --git a/includes/class-cepis-woo-transport.php b/includes/class-cepis-woo-transport.php
index 888be54..b89a81c 100644
--- a/includes/class-cepis-woo-transport.php
+++ b/includes/class-cepis-woo-transport.php
@@ -24,6 +24,31 @@ defined( 'ABSPATH' ) || exit;
 final class Cepis_Woo_Transport implements Cepis\Transport {
 
 	/**
+	 * Body of the response to the most recent completed request.
+	 *
+	 * The client turns a 404 into a {@see Cepis\CepNotFoundException} and drops
+	 * the body with it, which is the right shape for a library: a CEP that does
+	 * not exist is an error, not a payload. The API nonetheless puts something
+	 * useful in that body — the municipality the number would have belonged to —
+	 * and this is the only place in the plugin that still has it.
+	 *
+	 * Kept here rather than handed to the client so that nothing downstream can
+	 * mistake it for an address. {@see Cepis_Woo_Lookup} reads it, keeps the few
+	 * fields that name a municipality, and passes them on inside the 404.
+	 *
+	 * @var string
+	 */
+	private string $last_body = '';
+
+	/**
+	 * The body of the last response, or an empty string when the last request
+	 * never completed.
+	 */
+	public function last_body(): string {
+		return $this->last_body;
+	}
+
+	/**
 	 * Perform a single GET.
 	 *
 	 * @param string                $url     Absolute URL, query string included.
@@ -33,6 +58,8 @@ final class Cepis_Woo_Transport implements Cepis\Transport {
 	 * @throws Cepis\NetworkException The request never completed.
 	 */
 	public function get( string $url, array $headers, float $timeout ): Cepis\Response {
+		$this->last_body = '';
+
 		$response = wp_remote_get(
 			$url,
 			array(
@@ -48,11 +75,12 @@ final class Cepis_Woo_Transport implements Cepis\Transport {
 		}
 
 		$response_headers = wp_remote_retrieve_headers( $response );
+		$this->last_body  = (string) wp_remote_retrieve_body( $response );
 
 		return new Cepis\Response(
 			(int) wp_remote_retrieve_response_code( $response ),
 			is_object( $response_headers ) ? $response_headers->getAll() : (array) $response_headers,
-			(string) wp_remote_retrieve_body( $response )
+			$this->last_body
 		);
 	}
 }