Initial importv0.1.0

1 files changed, 45 insertions, 0 deletions

diff --git a/src/Transport.php b/src/Transport.php
new file mode 100644
index 0000000..811ac69
--- /dev/null
+++ b/src/Transport.php
@@ -0,0 +1,45 @@
+<?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;
+}