<?php

declare(strict_types=1);

namespace Cepis;

/**
 * How the client actually performs a GET.
 *
 * The default is {@see CurlTransport}, and most callers never touch this.
 * It exists because some hosts require their own HTTP layer: a WordPress
 * plugin is expected to go through the WP HTTP API (`wp_remote_get`) so that
 * site owners keep proxy support and the `http_request_args` filters they rely
 * on, and a library hardcoding curl cannot be a good citizen there.
 *
 * One method, no PSR-7, no framework types: an implementation over
 * `wp_remote_get` is about fifteen lines. See the README for that example.
 *
 * Implementations must be safe to reuse across calls; the client holds one for
 * its lifetime.
 */
interface Transport
{
    /**
     * Perform a GET and return the response, whatever its status.
     *
     * A non-2xx status is **not** an error here — return it and let the client
     * decide whether it is retriable. Throw {@see NetworkException} only when
     * the request did not complete at all: DNS failure, refused connection,
     * timeout, TLS error.
     *
     * Retries, backoff and `Retry-After` are the client's job. An
     * implementation should make exactly one request and should not retry.
     *
     * @param string                $url     Absolute URL, query string included.
     * @param array<string, string> $headers Request headers to send, as
     *     name => value.
     * @param float                 $timeout Seconds to allow for this single
     *     attempt. Implementations that distinguish connect from read timeouts
     *     should apply it to both.
     *
     * @throws NetworkException the request never completed.
     */
    public function get(string $url, array $headers, float $timeout): Response;
}