HttpClient.h

// Copyright (c) Stefano Cristiano
// SPDX-License-Identifier: MIT
#pragma once
 
#include "../Common/CompilerMacrosExport.h"
#include "../Common/CompilerMacrosType.h"
#ifndef SC_EXPORT_LIBRARY_HTTP_CLIENT
#define SC_EXPORT_LIBRARY_HTTP_CLIENT 0
#endif
#define SC_HTTP_CLIENT_EXPORT SC_COMPILER_LIBRARY_EXPORT(SC_EXPORT_LIBRARY_HTTP_CLIENT)
 
#include "../Common/Result.h"
#include "../Common/Span.h"
#include "../Common/StringSpan.h"
#include "HttpClientError.h"
#include "Internal/HttpClientThreading.h"
 
namespace SC
{
 
struct SC_HTTP_CLIENT_EXPORT HttpClientRequestBodyProvider;
struct SC_HTTP_CLIENT_EXPORT HttpClientRequestOptions;
 
struct SC_HTTP_CLIENT_EXPORT HttpClientHeader
{
    StringSpan name;
    StringSpan value;
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientResponseHeaderIterator
{
    size_t offset = 0;
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientContentCoding
{
    enum Type : uint8_t
    {
        Unknown,
        Identity,
        GZip,
        Deflate,
        Compress,
        Brotli,
    };
 
    Type       type = Unknown;
    StringSpan name;
 
    [[nodiscard]] bool               isIdentity() const { return type == Identity; }
    [[nodiscard]] static Type        parseName(StringSpan name);
    [[nodiscard]] static const char* getName(Type type);
    [[nodiscard]] static Result writeAcceptEncoding(Span<const Type> types, Span<char> destination, StringSpan& value);
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientContentCodingIterator
{
    HttpClientResponseHeaderIterator headerIterator;
    StringSpan                       headerValue;
    size_t                           valueOffset    = 0;
    bool                             hasHeaderValue = false;
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientTransferCoding
{
    enum Type : uint8_t
    {
        Unknown,
        Chunked,
        Compress,
        Deflate,
        GZip,
    };
 
    Type       type = Unknown;
    StringSpan name;
 
    [[nodiscard]] bool               isChunked() const { return type == Chunked; }
    [[nodiscard]] static Type        parseName(StringSpan name);
    [[nodiscard]] static const char* getName(Type type);
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientTransferCodingIterator
{
    HttpClientResponseHeaderIterator headerIterator;
    StringSpan                       headerValue;
    size_t                           valueOffset    = 0;
    bool                             hasHeaderValue = false;
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientCapabilities
{
    enum Backend : uint8_t
    {
        Unsupported,
        AppleURLSession,
        LibCurl,
        WinHttp,
    };
 
    enum Feature : uint8_t
    {
        MultipleOperationsPerClient,
        FixedRequestBody,
        SizedStreamRequestBody,
        ChunkedStreamRequestBody,
        RedirectPolicy,
        ProtocolHttp11Only,
        ProtocolHttp2Preferred,
        ProtocolHttp2Required,
        TlsDisablePeerVerification,
        TlsCustomCaPath,
        ProxyNoProxy,
        ProxyHttp,
        ProxyAuthorization,
        ProxyBypassList,
        ContentCodingPolicy,
    };
 
    Backend backend = Unsupported;
 
    bool multipleOperationsPerClient = false;
    bool fixedRequestBody            = false;
    bool sizedStreamRequestBody      = false;
    bool chunkedStreamRequestBody    = false;
    bool redirectPolicy              = false;
    bool protocolHttp11Only          = false;
    bool protocolHttp2Preferred      = false;
    bool protocolHttp2Required       = false;
    bool tlsDisablePeerVerification  = false;
    bool tlsCustomCaPath             = false;
    bool proxyNoProxy                = false;
    bool proxyHttp                   = false;
    bool proxyAuthorization          = false;
    bool proxyBypassList             = false;
    bool contentCodingPolicy         = false;
 
    [[nodiscard]] bool               hasBackend(Backend requiredBackend) const;
    [[nodiscard]] bool               supports(Feature feature) const;
    [[nodiscard]] bool               supportsRequestOptions(const HttpClientRequestOptions& options) const;
    [[nodiscard]] bool               supportsAll(Span<const Feature> features) const;
    [[nodiscard]] Result             requireBackend(Backend requiredBackend) const;
    [[nodiscard]] Result             requireFeatures(Span<const Feature> features) const;
    [[nodiscard]] Result             requireRequestOptions(const HttpClientRequestOptions& options) const;
    [[nodiscard]] const char*        getBackendName() const;
    [[nodiscard]] static const char* getBackendName(Backend backend);
    [[nodiscard]] static const char* getFeatureName(Feature feature);
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientRequestBody
{
    enum Framing : uint8_t
    {
        FixedSize,
        SizedStream,
        ChunkedStream,
    };
 
    Span<const char>               bytes;
    HttpClientRequestBodyProvider* provider = nullptr;
 
    uint64_t sizeInBytes = 0; 
    bool     canReplay   = false;
 
    Framing framing = FixedSize;
 
    [[nodiscard]] bool               isStreamed() const { return framing == SizedStream or framing == ChunkedStream; }
    [[nodiscard]] bool               isChunkedStream() const { return framing == ChunkedStream; }
    [[nodiscard]] const char*        getFramingName() const { return getFramingName(framing); }
    [[nodiscard]] static const char* getFramingName(Framing framing);
    [[nodiscard]] uint64_t           getDeclaredSizeInBytes() const
    {
        if (framing == FixedSize)
        {
            return static_cast<uint64_t>(bytes.sizeInBytes());
        }
        return framing == SizedStream ? sizeInBytes : 0;
    }
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientRequestRedirectOptions
{
    enum Mode : uint8_t
    {
        NoRedirects,
        FollowGetHead,
        FollowAll,
    };
 
    Mode    mode         = NoRedirects;
    uint8_t maxRedirects = 10;
 
    [[nodiscard]] const char*        getModeName() const { return getModeName(mode); }
    [[nodiscard]] static const char* getModeName(Mode mode);
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientRequestTimeoutOptions
{
    uint32_t requestTimeoutMs = 30000; 
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientRequestTlsOptions
{
    bool       verifyPeer = true;
    StringSpan caCertificatesPath;
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientRequestProtocolOptions
{
    enum Preference : uint8_t
    {
        Default,
        Http11Only,
        Http2Preferred,
        Http2Required,
    };
 
    Preference preference = Default;
 
    [[nodiscard]] const char*        getPreferenceName() const { return getPreferenceName(preference); }
    [[nodiscard]] static const char* getPreferenceName(Preference preference);
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientRequestProxyOptions
{
    enum Mode : uint8_t
    {
        Default, 
        NoProxy, 
        Http,    
    };
 
    Mode       mode = Default;
    StringSpan url;           
    StringSpan authorization; 
    StringSpan bypassList;    
 
    [[nodiscard]] const char*        getModeName() const { return getModeName(mode); }
    [[nodiscard]] static const char* getModeName(Mode mode);
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientRequestOptions
{
    HttpClientRequestRedirectOptions redirect;
    HttpClientRequestTimeoutOptions  timeouts;
    HttpClientRequestTlsOptions      tls;
    HttpClientRequestProtocolOptions protocol;
    HttpClientRequestProxyOptions    proxy;
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientRequest
{
    enum Method : uint8_t
    {
        HttpGET,
        HttpPOST,
        HttpPUT,
        HttpHEAD,
        HttpDELETE,
        HttpPATCH,
        HttpOPTIONS,
    };
 
    Method method = HttpGET;
 
    StringSpan url; 
 
    Span<const HttpClientHeader> headers;
    HttpClientRequestBody        body;
    HttpClientRequestOptions     options;
 
    [[nodiscard]] const char*        getMethodName() const { return getMethodName(method); }
    [[nodiscard]] static const char* getMethodName(Method method);
    [[nodiscard]] Result             validate() const;
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientResponse
{
    enum class Protocol : uint8_t
    {
        Unknown,
        Http11,
        Http2,
    };
 
    int statusCode = 0; 
 
    Span<const char> headers;
 
    size_t     headersLength      = 0;
    Protocol   negotiatedProtocol = Protocol::Unknown;
    StringSpan effectiveUrl;
    uint32_t   redirectCount = 0;
 
    [[nodiscard]] bool        getHeader(StringSpan name, StringSpan& value) const;
    [[nodiscard]] bool        hasHeader(StringSpan name) const;
    [[nodiscard]] bool        findNextHeader(StringSpan name, HttpClientResponseHeaderIterator& iterator,
                                             StringSpan& value) const;
    [[nodiscard]] bool        getNextHeader(HttpClientResponseHeaderIterator& iterator, HttpClientHeader& header) const;
    [[nodiscard]] bool        getContentLength(uint64_t& value) const;
    [[nodiscard]] bool        getContentType(StringSpan& value) const;
    [[nodiscard]] bool        getContentEncoding(StringSpan& value) const;
    [[nodiscard]] bool        getTransferEncoding(StringSpan& value) const;
    [[nodiscard]] bool        getLocation(StringSpan& value) const;
    [[nodiscard]] bool        getWwwAuthenticate(StringSpan& value) const;
    [[nodiscard]] bool        getProxyAuthenticate(StringSpan& value) const;
    [[nodiscard]] bool        getNextContentCoding(HttpClientContentCodingIterator& iterator,
                                                   HttpClientContentCoding&         contentCoding) const;
    [[nodiscard]] bool        getNextTransferCoding(HttpClientTransferCodingIterator& iterator,
                                                    HttpClientTransferCoding&         transferCoding) const;
    [[nodiscard]] bool        hasContentCoding(HttpClientContentCoding::Type type) const;
    [[nodiscard]] bool        hasTransferCoding(HttpClientTransferCoding::Type type) const;
    [[nodiscard]] bool        isHttp11() const { return negotiatedProtocol == Protocol::Http11; }
    [[nodiscard]] bool        isHttp2() const { return negotiatedProtocol == Protocol::Http2; }
    [[nodiscard]] bool        isInformationalStatus() const { return statusCode >= 100 and statusCode < 200; }
    [[nodiscard]] bool        isSuccessfulStatus() const { return statusCode >= 200 and statusCode < 300; }
    [[nodiscard]] bool        isRedirectStatus() const { return statusCode >= 300 and statusCode < 400; }
    [[nodiscard]] bool        isClientErrorStatus() const { return statusCode >= 400 and statusCode < 500; }
    [[nodiscard]] bool        isServerErrorStatus() const { return statusCode >= 500 and statusCode < 600; }
    [[nodiscard]] bool        isErrorStatus() const { return statusCode >= 400; }
    [[nodiscard]] const char* getProtocolName() const { return getProtocolName(negotiatedProtocol); }
    [[nodiscard]] static const char* getProtocolName(Protocol protocol);
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientRequestBodyProvider
{
    virtual ~HttpClientRequestBodyProvider() {}
 
    virtual Result pullRequestBody(Span<char> dest, size_t& bytesWritten, bool& endReached) = 0;
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientOperationListener
{
    virtual ~HttpClientOperationListener() {}
 
    virtual void onResponseHead(HttpClientResponse& response) { (void)(response); }
 
    virtual void onResponseBody(Span<const char> data) { (void)(data); }
 
    virtual void onResponseComplete() {}
 
    virtual void onError(Result error) { (void)(error); }
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientOperation;
 
struct SC_HTTP_CLIENT_EXPORT HttpClientOperationNotifier
{
    virtual ~HttpClientOperationNotifier() {}
 
    virtual void notifyHttpClientOperation(HttpClientOperation& operation) = 0;
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientResponseBuffer
{
    Span<char> data;
 
  private:
    friend struct HttpClientOperation;
    bool inUse = false;
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientOperationEvent
{
    enum class Type : uint8_t
    {
        ResponseHead,
        ResponseData,
        ResponseComplete,
        Error,
    };
 
    Type   type        = Type::ResponseHead;
    size_t size        = 0;
    size_t bufferIndex = 0;
    Result error       = Result(true);
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientOperationMemory
{
    Span<HttpClientResponseBuffer> responseBuffers;
    Span<HttpClientOperationEvent> eventQueue;
 
    Span<char> responseBufferMemory; 
    Span<char> responseHeaders;
    Span<char> responseMetadata;
    Span<char> backendScratch;
};
 
#if SC_COMPILER_MSVC
#pragma warning(push)
#pragma warning(disable : 4324)
#endif
struct SC_HTTP_CLIENT_EXPORT HttpClient
{
    HttpClient();
    ~HttpClient();
 
    HttpClient(const HttpClient&)            = delete;
    HttpClient(HttpClient&&)                 = delete;
    HttpClient& operator=(const HttpClient&) = delete;
    HttpClient& operator=(HttpClient&&)      = delete;
 
    [[nodiscard]] Result init();
    [[nodiscard]] Result init(HttpClientCapabilities::Backend requiredBackend);
    [[nodiscard]] Result init(Span<const HttpClientCapabilities::Feature> requiredFeatures);
    [[nodiscard]] Result init(HttpClientCapabilities::Backend             requiredBackend,
                              Span<const HttpClientCapabilities::Feature> requiredFeatures);
    [[nodiscard]] Result close();
 
    [[nodiscard]] static HttpClientCapabilities getCapabilities();
    [[nodiscard]] bool                          isInitialized() const { return initialized; }
 
    [[nodiscard]] static Result executeBlocking(const HttpClientRequest& request, HttpClientResponse& response,
                                                Span<char> bodyBuffer, size_t& bodyLength,
                                                const HttpClientOperationMemory& memory);
 
    friend struct HttpClientOperation;
 
  private:
    friend struct Internal;
    friend struct HttpClientLinuxCallbacks;
    struct Internal;
 
    Result platformInit();
    Result platformClose();
 
    bool initialized = false;
 
#if SC_PLATFORM_APPLE
    alignas(uint64_t) char storage[128];
#elif SC_PLATFORM_WINDOWS
    alignas(uint64_t) char storage[128];
#elif SC_PLATFORM_LINUX
    alignas(uint64_t) char storage[512];
#else
    alignas(uint64_t) char storage[8];
#endif
};
 
struct SC_HTTP_CLIENT_EXPORT HttpClientOperation
{
    HttpClientOperation();
    ~HttpClientOperation();
 
    HttpClientOperation(const HttpClientOperation&)            = delete;
    HttpClientOperation(HttpClientOperation&&)                 = delete;
    HttpClientOperation& operator=(const HttpClientOperation&) = delete;
    HttpClientOperation& operator=(HttpClientOperation&&)      = delete;
 
    [[nodiscard]] Result init(HttpClient& client, const HttpClientOperationMemory& memory);
    [[nodiscard]] Result close();
    [[nodiscard]] Result cancel();
 
    [[nodiscard]] Result start(const HttpClientRequest& request, HttpClientResponse& response,
                               HttpClientOperationListener* listener = nullptr);
 
    [[nodiscard]] Result poll(uint32_t timeoutMilliseconds = 0);
 
    void setNotifier(HttpClientOperationNotifier* notifierValue) { notifier = notifierValue; }
 
    [[nodiscard]] bool isInitialized() const { return initialized; }
    [[nodiscard]] bool isRequestInFlight() const { return requestInFlight; }
 
    friend struct Internal;
    struct Internal;
 
  private:
    friend struct HttpClientTest; // Exercise the request-body callback contract without a native backend.
    friend struct HttpClientAppleCallbacks;
    friend struct HttpClientLinuxCallbacks;
    friend struct HttpClientWindowsCallbacks;
 
    Result platformInit();
    Result platformClose();
    Result platformStart();
    Result platformCancel();
 
    Result enqueueEvent(const HttpClientOperationEvent& event);
    bool   dequeueEvent(HttpClientOperationEvent& event);
 
    Result allocateResponseBuffer(size_t minimumSizeInBytes, size_t& bufferIndex, Span<char>& data);
    void   releaseResponseBuffer(size_t bufferIndex);
    Result enqueueResponseDataCopy(Span<const char> data);
 
    void enqueueResponseHead();
    void enqueueResponseBuffer(size_t bufferIndex, size_t size);
    void enqueueResponseComplete();
    void enqueueError(Result error);
 
    void   resetResponseState(HttpClientResponse& response);
    void   resetRequestBodyState();
    bool   isAutomaticRedirectEnabled() const;
    bool   canAutomaticRedirectRequestReplay() const;
    Result copyResponseEffectiveUrl(StringSpan url);
 
    size_t readRequestBodyChunk(Span<char> dest, Result& outError, bool& outEnd);
    bool   hasPendingEvents() const;
    Result processPendingEvents();
 
    HttpClient*                  client          = nullptr;
    HttpClientResponse*          currentResponse = nullptr;
    HttpClientOperationListener* currentListener = nullptr;
    HttpClientOperationNotifier* notifier        = nullptr;
    HttpClientRequest            currentRequest;
 
    Span<HttpClientResponseBuffer> responseBuffers;
    Span<HttpClientOperationEvent> eventQueue;
 
    Span<char> responseHeaders;
    Span<char> responseMetadata;
    Span<char> backendScratch;
 
    mutable HttpClientLocalMutex     eventMutex;
    HttpClientLocalConditionVariable eventCV;
    HttpClientOperationEvent         dequeuedEvent;
 
    size_t   eventHead            = 0;
    size_t   eventTail            = 0;
    size_t   eventCount           = 0;
    bool     requestBodyFinished  = false;
    Result   requestBodyError     = Result(true);
    uint64_t requestBodyBytesRead = 0;
    bool     initialized          = false;
    bool     requestInFlight      = false;
 
#if SC_PLATFORM_APPLE
    alignas(uint64_t) char storage[512];
#elif SC_PLATFORM_WINDOWS
    alignas(uint64_t) char storage[256];
#elif SC_PLATFORM_LINUX
    alignas(uint64_t) char storage[512];
#else
    alignas(uint64_t) char storage[8];
#endif
};
#if SC_COMPILER_MSVC
#pragma warning(pop)
#endif
 
} // namespace SC