NET_WebResponse.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        NET_WebResponse.h
 *
 * COMMENTS:
 *
 */

#ifndef __NET_WEBRESPONSE_H__
#define __NET_WEBRESPONSE_H__

#include "NET_API.h"

#include "NET_HTTPDefines.h"
#include "NET_Time.h"
#include "NET_WebTypes.h"

#include <UT/UT_Array.h>
#include <UT/UT_ArrayStringMap.h>
#include <UT/UT_Assert.h>
#include <UT/UT_Debug.h>
#include <UT/UT_ErrorCode.h>
#include <UT/UT_Optional.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_Url.h>

#include <SYS/SYS_Types.h>

#include <time.h>

class NET_NetworkCookie;
class UT_WorkBuffer;

// NOTE: Not a full list of http status codes
enum NET_HTTPStatusCode
{
    // Curl uses zero to indicate no status code received
    NET_HTTPNone = 0,
    // Info Codes
    NET_HTTPContinue = 100,
    NET_HTTPSwitchProtocol = 101,
    // Success Codes
    NET_HTTPOk = 200,
    NET_HTTPCreated = 201,
    NET_HTTPAccepted = 202,
    NET_HTTPNonAuthoritativeInfo = 203,
    NET_HTTPNoContent = 204,
    NET_HTTPResetContent = 205,
    NET_HTTPPartialContent = 206,
    // Redirect Codes
    NET_HTTPMultipleChoice = 300,
    NET_HTTPMovedPerm = 301,
    NET_HTTPFound = 302,
    NET_HTTPSeeOther = 303,
    NET_HTTPNotModified = 304,
    NET_HTTPTempRedirect = 307,
    NET_HTTPPermRedirect = 308,
    // Client Error Codes
    NET_HTTPBadRequest = 400,
    NET_HTTPUnauthorized = 401,
    NET_HTTPPaymentRequired = 402,
    NET_HTTPForbidden = 403,
    NET_HTTPNotFound = 404,
    NET_HTTPMethodNotAllowed = 405,
    NET_HTTPNotAcceptable = 406,
    NET_HTTPProxyAuthRequired = 407,
    NET_HTTPRequestTimeout = 408,
    NET_HTTPConflict = 409,
    NET_HTTPGone = 410,
    NET_HTTPLengthRequired = 411,
    NET_HTTPPreconditionFailed = 412,
    NET_HTTPPayloadLarge = 413,
    NET_HTTPURITooLong = 414,
    NET_HTTPUnsupportedMedia = 415,
    NET_HTTPRangeNotSatisfiable = 416,
    NET_HTTPExpectationFailed = 417,
    NET_HTTPUnprocessableEntity = 422,
    NET_HTTPTooEarly = 425,
    NET_HTTPUpgradeRequired = 426,
    NET_HTTPPreconditionRequired = 428,
    NET_HTTPTooManyRequests = 429,
    NET_HTTPHeadersFieldsTooLarge = 431,
    NET_HTTPLegalReasons = 451,
    // Server Error Codes
    NET_HTTPInternalServerError = 500,
    NET_HTTPNotImplemented = 501,
    NET_HTTPBadGateway = 502,
    NET_HTTPServiceUnavailable = 503,
    NET_HTTPGatewayTimeout = 504,
    NET_HTTPVersionNotSupported = 505,
    NET_HTTPNetworkAuthRequired = 511,
    NET_HTTPLast
};

/// Holds all common information between a client response and an object holding
/// the servers response to a client.
class NET_API NET_BaseWebResponse
{
public:
    using HeaderMap = UT_ArrayStringMap<UT_StringHolder>;
    NET_BaseWebResponse();
    NET_BaseWebResponse(NET_HTTPStatusCode code);
    NET_BaseWebResponse(NET_HTTPStatusCode code, const UT_StringHolder &data);
    NET_BaseWebResponse(
            NET_HTTPStatusCode code,
            const HeaderMap &headers,
            const UT_StringHolder &data);
    NET_BaseWebResponse(NET_HTTPStatusCode code, const HeaderMap &headers);

    explicit operator bool() const { return isSuccess(); }

    bool isSuccess() const { return myStatus == NET_HTTPOk; }

    bool isRequestNotFound() const { return myStatus == NET_HTTPNotFound; }
    bool isBadRequest() const { return myStatus == NET_HTTPBadRequest; }
    bool hasTimedout() const { return myStatus == NET_HTTPRequestTimeout; }

    UT_StringHolder headersAsString() const;

    // Does this response object have a specific option specified.
    bool hasHeader(const UT_StringRef &header) const;

    void setDefault(const UT_StringHolder& name, const UT_StringHolder& value);

    const UT_StringHolder& getHeaderOrEmpty(const UT_StringRef& header) const
    {
        auto it = myHeaders.find(header);
        if (it == myHeaders.end())
            return UT_StringHolder::theEmptyString;
        return it->second;
    }
    UT_Optional<UT_StringHolder> getHeaderContentType();
    const UT_StringHolder& contentTypeOrEmpty() const
    {
        auto it = myHeaders.find(HTTP_CONTENT_TYPE);
        if (it == myHeaders.end())
            return UT_StringHolder::theEmptyString;
        return it->second;
    }
    UT_Optional<exint> getHeaderContentLength();

    bool hasContentType(const UT_StringRef &mime) const;

    NET_Time modTime() const;

    // Get the stock message based on the status code
    static void stockMsgFromCode(NET_HTTPStatusCode code, UT_WorkBuffer &msg);

    bool hasJSONBody() const;
    bool hasTextBody() const;
    static bool isJSONBody(const HeaderMap &headers);

    // The status of the response
    NET_HTTPStatusCode myStatus;
    // The headers of the response
    HeaderMap myHeaders;
    UT_StringArray myCookies;
    // The body of the response
    UT_StringHolder myData;
};

namespace NET
{
enum class CurlError
{
    INTERNAL_ERROR = -1,
    OK = 0,
    UNSUPPORTED_PROTOCOL,
    FAILED_INIT,
    URL_MALFORMAT,
    NOT_BUILT_IN,
    COULDNT_RESOLVE_PROXY,
    COULDNT_RESOLVE_HOST,
    COULDNT_CONNECT,
    WEIRD_SERVER_REPLY,
    REMOTE_ACCESS_DENIED,
    FTP_ACCEPT_FAILED,
    FTP_WEIRD_PASS_REPLY,
    FTP_ACCEPT_TIMEOUT,
    FTP_WEIRD_PASV_REPLY,
    FTP_WEIRD_227_FORMAT,
    FTP_CANT_GET_HOST,
    HTTP2_PROBLEM,
    FTP_COULDNT_SET_TYPE,
    PARTIAL_FILE,
    FTP_COULDNT_RETR_FILE,
    QUOTE_ERROR,
    HTTP_RETURNED_ERROR,
    WRITE_ERROR,
    UPLOAD_FAILED,
    READ_ERROR,
    OUT_OF_MEMORY,
    OPERATION_TIMEDOUT,
    FTP_PORT_FAILED,
    FTP_COULDNT_USE_REST,
    RANGE_ERROR,
    HTTP_POST_ERROR,
    SSL_CONNECT_ERROR,
    BAD_DOWNLOAD_RESUME,
    FILE_COULDNT_READ_FILE,
    LDAP_CANNOT_BIND,
    LDAP_SEARCH_FAILED,
    FUNCTION_NOT_FOUND,
    ABORTED_BY_CALLBACK,
    BAD_FUNCTION_ARGUMENT,
    INTERFACE_FAILED,
    TOO_MANY_REDIRECTS,
    UNKNOWN_OPTION,
    SETOPT_OPTION_SYNTAX,
    TELNET_OPTION_SYNTAX,
    GOT_NOTHING,
    SSL_ENGINE_NOTFOUND,
    SSL_ENGINE_SETFAILED,
    SEND_ERROR,
    RECV_ERROR,
    SSL_CERTPROBLEM,
    SSL_CIPHER,
    PEER_FAILED_VERIFICATION,
    BAD_CONTENT_ENCODING,
    LDAP_INVALID_URL,
    FILESIZE_EXCEEDED,
    USE_SSL_FAILED,
    SEND_FAIL_REWIND,
    SSL_ENGINE_INITFAILED,
    LOGIN_DENIED,
    TFTP_NOTFOUND,
    REMOTE_DISK_FULL,
    TFTP_ILLEGAL,
    TFTP_UNKNOWNID,
    REMOTE_FILE_EXISTS,
    TFTP_NOSUCHUSER,
    CONV_FAILED,
    CONV_REQD,
    SSL_CACERT_BADFILE,
    REMOTE_FILE_NOT_FOUND,
    SSH_ERROR,
    SSL_SHUTDOWN_FAILED,
    AGAIN_ERROR,
    SSL_CRL_BADFILE,
    SSL_ISSUER_ERROR,
    FTP_PRET_FAILED,
    RTSP_CSEQ_ERROR,
    RTSP_SESSION_ERROR,
    FTP_BAD_FILE_LIST,
    CHUNK_FAILED,
    NO_CONNECTION_AVAILABLE,
    SSL_PINNEDPUBKEYNOMATCH,
    SSL_INVALIDCERTSTATUS,
    HTTP2_STREAM,
    RECURSIVE_API_CALL,
    AUTH_ERROR,
    HTTP3_ERROR,
    QUIC_CONNECT_ERROR,
    PROXY_ERROR,
    SSL_CLIENTCERT,
    TFTP_PERM,
    LAST
};

NET_API const UT_ErrorCategory &GetCurlErrorCategory();

inline UT_ErrorCode
make_error_code(NET::CurlError e)
{
    return UT_ErrorCode{static_cast<int>(e), GetCurlErrorCategory()};
}
} // namespace NET

namespace std
{
    template <> struct is_error_code_enum<NET::CurlError> : true_type
    {
    };
}

/// Contains extra information that might be useful. Note this only contains
/// extra details for the NET::CurlError
NET_API UT_StringHolder NETextraDetails(const UT_ErrorCode& ec);

/// Response object used by a client from a response by a server.
class NET_API NET_HTTPResponse : public NET_BaseWebResponse
{
public:
    struct NET_API Error
    {
        UT_StringHolder buildErrorMessage(const UT_Url& effective_url) const;
        static UT_ErrorCode translateErrorToCode(int err);

        UT_ErrorCode myErrorCode = NET::CurlError::OK;
        // Explenation of the error
        UT_StringHolder myErrorMsg;
        bool myMaxRetriesHit = false;
        // Total number of attempts made when myMaxRetriesHit is set, so error
        // messages can report how many times we tried before giving up.
        int myAttempts = 0;

    private:
        friend class NET_HTTPResponse;
    };

    NET_HTTPResponse();
    NET_HTTPResponse(NET_HTTPStatusCode code);
    NET_HTTPResponse(NET_HTTPStatusCode code, const UT_StringHolder &data);
    NET_HTTPResponse(
            NET_HTTPStatusCode code,
            const HeaderMap &headers,
            const UT_StringHolder &data);
    NET_HTTPResponse(NET_HTTPStatusCode code, const HeaderMap &headers);

    void parseCookies(UT_Array<NET_NetworkCookie> &cookies) const;
    bool errorReceivedNothing() const
    {
        return myError.myErrorCode
               == make_error_code(NET::CurlError::GOT_NOTHING);
    }
    void clear();
    UT_StringHolder errorMessage() const
    {
        return myError.buildErrorMessage(myEffectiveURL);
    }

    Error myError;

    fpreal64 myConnectTime = 0.0f;
    fpreal64 myTotalTime = 0.0f;

    UT_Url myEffectiveURL;
    UT_StringHolder myEffectiveMethod;

    UT_StringHolder myFileName;
};

/// Response object used for responding to request in the server.
class NET_API NET_WebResponse : protected NET_BaseWebResponse
{
public:
    using HeaderMap = NET_BaseWebResponse::HeaderMap;

    NET_WebResponse()
        : NET_BaseWebResponse()
    {
        _init(NET_HTTPInternalServerError);
    }
    NET_WebResponse(NET_HTTPStatusCode code)
        : NET_BaseWebResponse()
    {
        _init(code);
    }
    NET_WebResponse(NET_HTTPStatusCode code, const UT_StringHolder &data)
        : NET_BaseWebResponse()
    {
        _init(code);
        setBody(data);
    }
    NET_WebResponse(
            NET_HTTPStatusCode code,
            const HeaderMap &headers,
            const UT_StringHolder &data)
        : NET_BaseWebResponse()
    {
        _init(code);
        setHeaders(headers);
        setBody(data);
    }
    NET_WebResponse(NET_HTTPStatusCode code, const HeaderMap &headers) :
        NET_BaseWebResponse()
    {
        _init(code);
        setHeaders(headers);
    }

    NET_WebResponse(const NET_WebResponse &resp) = default;
    NET_WebResponse &operator=(const NET_WebResponse &resp) = default;
    NET_WebResponse(NET_WebResponse &&resp) = default;
    NET_WebResponse &operator=(NET_WebResponse &&resp) = default;

    // Convience operators to forward a client response as a server response
    NET_WebResponse(const NET_HTTPResponse &resp)
        : NET_BaseWebResponse()
    {
        _init(resp.myStatus);
        setHeaders(resp.myHeaders);
        setBody(resp.myData);
    }
    NET_WebResponse &operator=(const NET_HTTPResponse &resp)
    {
        _init();
        setHeaders(resp.myHeaders);
        setBody(resp.myData);
        return *this;
    }

    void clear();

    bool isFile() const { return myFile.isstring(); }

    bool isChunked() const
    {
        return myChunked;
    }
    bool hasHeader(const UT_StringRef& header) const
    {
        return NET_BaseWebResponse::hasHeader(header);
    }
    const UT_StringHolder& getHeaderOrEmpty(const UT_StringRef& header) const
    {
        return NET_BaseWebResponse::getHeaderOrEmpty(header);
    }

    void setDefault(const UT_StringHolder& name, const UT_StringHolder& value)
    {
        return NET_BaseWebResponse::setDefault(name, value);
    }

    void setStatus(NET_HTTPStatusCode code)
    {
        myStatus = code;

        if (myStatus == NET_HTTPNoContent ||
                myStatus == NET_HTTPNotModified)
        {
            myChunked = true;
        }
    }
    NET_HTTPStatusCode status() const { return myStatus; }

    // Set a header entry. An empty header value means to remove the entry.
    void setHeader(const UT_StringRef& name, const UT_StringRef& value);
    void setHeaders(const HeaderMap& headers)
    {
        for (auto&& header : headers)
        {
            setHeader(header.first, header.second);
        }
    }
    // Used whenever a header can have a list of values attached to it
    // (i.e. Vary)
    void patchHeader(const UT_StringHolder& name, const UT_StringHolder& value);

    // Set the response as an in memory response
    void setBody(const UT_StringHolder& body, const UT_StringRef& content_type = "")
    {
        clearFile();

        myData = body;
        if (!content_type.isEmpty())
            myContentType = content_type;
        else if (myContentType.isEmpty())
            myContentType = "text/plain";
        myContentLength = myData.length();
    }
    // Set the next chunk to send. This only updates the body and if there is
    // more data to be processed. The chunked header MUST be set prior to
    // calling this function.
    void setBodyChunk(const UT_StringHolder& body, bool has_more = false)
    {
        UT_ASSERT(myChunked);

        myHasMoreData = has_more;
        myData = body;
    }
    // Helper method to set a text body
    void setText(const UT_StringHolder& body)
    {
        setBody(body, "text/plain");
    }
    void setJSON(const UT_StringHolder& body)
    {
        setBody(body, "application/json");
    }
    // Set the response as a file response.
    void setFile(const UT_StringHolder& file, bool delete_file);
    void clearBody()
    {
        myData.clear();
    }
    void clearFile()
    {
        myFile.clear();
        myDeleteFile = false;
        myHeaders.erase(HTTP_LAST_MODIFIED);
    }
    // Set the ranges for our response.
    void setRanges(const NET_RequestRangeList& ranges)
    {
        myRanges = ranges;
        // Create a boundary if we have multiple ranges
        //
        // NB: we dont set/change the content type as we will just set the
        // content type when sending so that the body can send the proper
        // content type when its time to send this information.
        if (ranges.entries() > 1)
            myBoundary.format("-----{}", time(nullptr) ^ (uint64)(this));
        else
            myBoundary.clear();

        setHeader(HTTP_ACCEPT_RANGES, "bytes");
    }

    void clearRanges()
    {
        myRanges.clear();
        myBoundary.clear();
        myHeaders.erase(HTTP_ACCEPT_RANGES);
    }

    bool shouldClose() const
    {
        if (!myKeepAlive)
            return true;

        if (myUpgrade)
            return false;

        if (myStatus > 499)
            return true;

        return false;
    }
    const UT_StringHolder& data() const
    {
        return myData;
    }
    exint contentLength() const { return myContentLength; }
    const UT_StringHolder& contentType() const { return myContentType; }
    const HeaderMap& headers() const { return myHeaders; }
    bool isUpgrade() const { return myUpgrade; }
    void setErrors(const UT_StringHolder& errors)
    {
        myErrors = errors;
    }
    const NET_RequestRangeList& ranges() const { return myRanges; }
    const UT_StringHolder& boundary() const { return myBoundary; }
    bool isTempFile() const { return myDeleteFile; }
    const UT_StringHolder& file() const { return myFile; }
    // True if there is more data that needs to be sent. This only has meaning
    // if the response is chunked.
    bool hasMoreData() const { return myHasMoreData; }
    bool keepAlive() const { return myKeepAlive; }
    void setKeepAlive(bool keep_alive) { myKeepAlive = keep_alive; }

    void addCookie(const NET_NetworkCookie& cookie);
    void deleteCookie(const UT_StringRef& name);
    bool hasCookie(const UT_StringRef& name) const;
    bool getCookie(const UT_StringRef& name, NET_NetworkCookie& cookie) const;
private:
    void _init(NET_HTTPStatusCode code = NET_HTTPInternalServerError)
    {
        myChunked = false;

        setStatus(code);

        myHeaders.clear();
        myCookies.clear();

        myContentType.clear();
        myBoundary.clear();
        myContentLength = 0;

        myFile.clear();
        myDeleteFile = false;

        myRanges.clear();

        myData.clear();

        myUpgrade = false;

        myHasMoreData = false;
        myKeepAlive = true;

        myErrors.clear();
    }

private:
    friend class NET_HttpIO;

    NET_RequestRangeList myRanges;
    
    UT_StringHolder myContentType;
    UT_StringHolder myBoundary;
    exint myContentLength;

    UT_StringHolder myFile;
    unsigned myDeleteFile : 1;
    unsigned myUpgrade : 1;
    unsigned myChunked : 1;
    unsigned myHasMoreData : 1;
    unsigned myKeepAlive : 1;
    // Error that you might want hidden
    UT_StringHolder myErrors;
};

using NET_WebResponseSPtr = UT_SharedPtr<NET_WebResponse>;

#endif // __NET_WEBRESPONSE_H__