path: root/includes/class-cepis-woo-lookup.php

<?php
/**
 * Server-side CEP lookups, cached.
 *
 * @package CepisWooCommerce
 */

declare(strict_types=1);

defined( 'ABSPATH' ) || exit;

/**
 * Resolves a CEP with the bundled `Cepis\Client` and remembers the answer in a
 * transient.
 *
 * Only the proxy mode goes through here. In the default direct mode the
 * browser talks to cep.is itself and no PHP runs at all.
 */
final class Cepis_Woo_Lookup {

	/**
	 * Prefix for the transient holding one CEP's answer.
	 */
	private const CACHE_PREFIX = 'cepis_woo_';

	/**
	 * How long a resolved address is kept.
	 *
	 * The DNE database behind the API is regenerated fortnightly, so a week is
	 * half a refresh cycle: an address can be at most one release behind, while
	 * a CEP a store sees repeatedly still costs one outbound request a week.
	 */
	private const HIT_TTL = WEEK_IN_SECONDS;

	/**
	 * How long a "this CEP does not exist" is kept.
	 *
	 * Much shorter than a hit, and for a different reason: a CEP absent today
	 * can appear in the next fortnightly base, and telling a shopper their
	 * brand-new street does not exist for two weeks is worse than making the
	 * request again tomorrow.
	 */
	private const MISS_TTL = DAY_IN_SECONDS;

	/**
	 * The fields of a 404's `faixa` object that are passed on.
	 *
	 * A whitelist rather than the whole object, so that a field the API grows
	 * later cannot reach the checkout unreviewed. None of these is ever written
	 * into a checkout field — see {@see Cepis_Woo_Lookup::faixa()}.
	 */
	private const FAIXA_FIELDS = array(
		'localidade',
		'uf',
		'estado',
		'regiao',
		'ibge',
		'cep_ini',
		'cep_fim',
		'ceps',
	);

	/**
	 * The transport the client speaks through, kept so that the body of a 404
	 * can be read back after the client has turned it into an exception.
	 *
	 * @var Cepis_Woo_Transport|null
	 */
	private static ?Cepis_Woo_Transport $transport = null;

	/**
	 * Look a CEP up, from cache when possible.
	 *
	 * Never throws: every outcome is described by the returned status and body,
	 * in exactly the shapes the public API uses, so the browser sees the same
	 * thing whichever mode the store is in.
	 *
	 * @param string $cep Eight digits, already validated by the caller.
	 *
	 * @return array{status:int, body:array<string, mixed>, retry_after:?int}
	 */
	public static function resolve( string $cep ): array {
		$cached = get_transient( self::CACHE_PREFIX . $cep );

		if ( is_array( $cached ) ) {
			if ( isset( $cached['miss'] ) ) {
				$remembered = isset( $cached['faixa'] ) && is_array( $cached['faixa'] ) ? $cached['faixa'] : null;

				return self::not_found( $remembered );
			}

			return array(
				'status'      => 200,
				'body'        => $cached,
				'retry_after' => null,
			);
		}

		try {
			$address = self::client()->lookup( $cep );
		} catch ( Cepis\CepNotFoundException ) {
			$faixa = self::faixa( self::transport()->last_body() );
			$miss  = array( 'miss' => true );

			if ( null !== $faixa ) {
				$miss['faixa'] = $faixa;
			}

			set_transient( self::CACHE_PREFIX . $cep, $miss, self::MISS_TTL );

			return self::not_found( $faixa );
		} catch ( Cepis\InvalidCepException ) {
			return array(
				'status'      => 400,
				'body'        => array(
					'erro'     => 'cep_invalido',
					'mensagem' => 'CEP deve ter 8 dígitos',
				),
				'retry_after' => null,
			);
		} catch ( Cepis\RateLimitedException $e ) {
			return array(
				'status'      => 429,
				'body'        => array(
					'erro'     => 'limite',
					'mensagem' => 'Muitas consultas em pouco tempo',
				),
				'retry_after' => null === $e->retryAfter ? null : (int) $e->retryAfter,
			);
		} catch ( Cepis\CepisException ) {
			return array(
				'status'      => 502,
				'body'        => array(
					'erro'     => 'interno',
					'mensagem' => 'falha interna',
				),
				'retry_after' => null,
			);
		}

		$body = $address->raw;
		set_transient( self::CACHE_PREFIX . $cep, $body, self::HIT_TTL );

		return array(
			'status'      => 200,
			'body'        => $body,
			'retry_after' => null,
		);
	}

	/**
	 * Drop every cached answer.
	 *
	 * Used by the settings screen when the API root changes, since answers from
	 * one instance say nothing about another.
	 */
	public static function flush(): void {
		global $wpdb;

		$like = $wpdb->esc_like( '_transient_' . self::CACHE_PREFIX ) . '%';

		$names = $wpdb->get_col(
			$wpdb->prepare( "SELECT option_name FROM {$wpdb->options} WHERE option_name LIKE %s", $like )
		);

		foreach ( (array) $names as $name ) {
			delete_transient( substr( (string) $name, strlen( '_transient_' ) ) );
		}
	}

	/**
	 * The client, built once per request.
	 */
	private static function client(): Cepis\Client {
		static $client = null;

		if ( null === $client ) {
			$client = new Cepis\Client(
				baseUrl: Cepis_Woo_Options::base_url(),
				timeout: 5.0,
				maxAttempts: 2,
				totalTimeout: 8.0,
				userAgent: 'cepis-woocommerce/' . CEPIS_WOO_VERSION . ' (+https://cep.is)',
				transport: self::transport(),
			);
		}

		return $client;
	}

	/**
	 * The transport, built once per request.
	 */
	private static function transport(): Cepis_Woo_Transport {
		if ( null === self::$transport ) {
			self::$transport = new Cepis_Woo_Transport();
		}

		return self::$transport;
	}

	/**
	 * The municipality a missing CEP would have belonged to, out of the API's
	 * 404 body.
	 *
	 * **This is context, not an address.** A CEP that does not exist has no
	 * address, and nothing here may ever reach a checkout field: a shipping
	 * address filled from a CEP the Correios do not have is a parcel delivered
	 * somewhere else. It exists only so the shopper can be told what they most
	 * likely mistyped — the classic case being the `-000` that 957
	 * municipalities never received.
	 *
	 * Returns `null` for anything unexpected, so a body that changed shape, or
	 * is not JSON at all, produces exactly the message this plugin has always
	 * shown.
	 *
	 * @param string $body The response body, as it arrived.
	 *
	 * @return array<string, int|string>|null The named fields, or null.
	 */
	private static function faixa( string $body ): ?array {
		if ( '' === $body ) {
			return null;
		}

		$data = json_decode( $body, true );

		if ( ! is_array( $data ) || ! isset( $data['faixa'] ) || ! is_array( $data['faixa'] ) ) {
			return null;
		}

		$faixa = array();

		foreach ( self::FAIXA_FIELDS as $name ) {
			if ( ! isset( $data['faixa'][ $name ] ) || ! is_scalar( $data['faixa'][ $name ] ) ) {
				continue;
			}

			$value = $data['faixa'][ $name ];

			$faixa[ $name ] = is_int( $value ) ? $value : sanitize_text_field( (string) $value );
		}

		return array() === $faixa ? null : $faixa;
	}

	/**
	 * The API's own 404 body, reproduced so the browser cannot tell the two
	 * modes apart.
	 *
	 * `faixa` is **omitted** when there is none, never sent as null, which is
	 * what the API does and what the browser is written to expect.
	 *
	 * @param array<string, int|string>|null $faixa The municipality the CEP
	 *     would have belonged to, when the API named one.
	 *
	 * @return array{status:int, body:array<string, mixed>, retry_after:?int}
	 */
	private static function not_found( ?array $faixa = null ): array {
		$body = array(
			'erro'     => 'cep_nao_encontrado',
			'mensagem' => 'CEP não existe na base do DNE',
		);

		if ( null !== $faixa ) {
			$body['faixa'] = $faixa;
		}

		return array(
			'status'      => 404,
			'body'        => $body,
			'retry_after' => null,
		);
	}
}