HttpServerUtil.qm.dox.h

// -*- mode: c++; indent-tabs-mode: nil -*-
 
/*  HttpServerUtil.qm Copyright (C) 2014 - 2023 Qore Technologies, s.r.o.
 
    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:
 
    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.
 
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
*/
 
 
 
 
 
namespace HttpServer {
const HttpServerVersion = "1.1";
 
const HttpServerString = sprintf("Qore-HTTP-Server/%s", HttpServerVersion);
 
const DefaultTimeout = 30s;  # recvs timeout after 30 seconds
 
const ReadTimeout = DefaultTimeout;
 
 
const MaxSslFileLen = 1024 * 1024;
 
const HttpCodes = {
    // 100s: Informational
    "100": "Continue",
    "101": "Switching Protocols",
 
    # RFC 2518: WebDAV
    "102": "Processing",
 
    # 200s: Success
    "200": "OK",
    "201": "Created",
    "202": "Accepted",
    "203": "Non-Authoritative Information",
    "204": "No Content",
    "205": "Reset Content",
    "206": "Partial Content",
 
    # RFC 4918: WebDAV: The message body that follows is an XML message and can contain a number of separate response
    #           codes, depending on how many sub-requests were made
    "207": "Multi-Status",
 
    # RFC 5842: WebDAV: The members of a DAV binding have already been enumerated in a previous reply to this request,
    #           and are not being included again
    "208": "Already Reported",
 
    # RFC 3229
    "226": "IM Used",
 
    # 300s: Redirection
    "300": "Multiple Choices",
    "301": "Moved Permanently",
    "302": "Found",
    "303": "See Other",
    "304": "Not Modified",
    "305": "Use Proxy",
    #"306": "(Reserved)",
    "307": "Temporary Redirect",
    "308": "Permanent Redirect",
 
    # 400s: Client Errors
    "400": "Bad Request",
    "401": "Unauthorized",
    "402": "Payment Required",
    "403": "Forbidden",
    "404": "Not Found",
    "405": "Method Not Allowed",
    "406": "Not Acceptable",
    "407": "Proxy Authentication Required",
    "408": "Request Timeout",
    "409": "Conflict",
    "410": "Gone",
    "411": "Length Required",
    "412": "Precondition Failed",
    "413": "Request Entity Too Large",
    "414": "Request-URI Too Long",
    "415": "Unsupported Media Type",
    "416": "Requested Range Not Satisfiable",
    "417": "Expectation Failed",
 
    # RFC 2324: http://tools.ietf.org/html/rfc2324
    "418": "I'm a teapot",
 
    # Returned by the Twitter Search and Trends API when the client is being rate limited
    "420": "Enhance Your Calm",
 
    # RFC 4918: WebDAV: The request was well-formed but was unable to be followed due to semantic errors
    "422": "Unprocessable Entity",
 
    # RFC 4918: WebDAV: The resource that is being accessed is locked
    "423": "Locked",
 
    # RFC 4918: WebDAV: The request failed due to failure of a previous request (e.g. a PROPPATCH)
    "424": "Failed Dependency",
 
    # Internet draft: Defined in drafts of "WebDAV Advanced Collections Protocol", but not present in "Web Distributed
    #                 Authoring and Versioning (WebDAV) Ordered Collections Protocol"
    "425": "Unordered Collection",
 
    # RFC 2817: The client should switch to a different protocol such as TLS/1.0
    "426": "Upgrade Required",
 
    # RFC 6585: The origin server requires the request to be conditional. Intended to prevent "the 'lost update'
    #           problem, where a client GETs a resource's state, modifies it, and PUTs it back to the server, when
    #           meanwhile a third party has modified the state on the server, leading to a conflict."
    "428": "Precondition Required",
 
    # RFC 6585: The user has sent too many requests in a given amount of time. Intended for use with rate limiting
    #           schemes
    "429": "Too Many Requests",
 
    # RFC 6585
    "431": "Request Header Fields Too Large",
 
    # 500s: Server Errors
    "500": "Internal Server Error",
    "501": "Not Implemented",
    "502": "Bad Gateway",
    "503": "Service Unavailable",
    "504": "Gateway Timeout",
    "505": "HTTP Version Not Supported",
    "509": "Bandwidth Limit Exceeded",
 
    # RFC 2774: Further extensions to the request are required for the server to fulfill it
    "510": "Not Extended",
 
    # RFC 6585: The client needs to authenticate to gain network access. Intended for use by intercepting proxies used
    #           to control access to the network (e.g. "captive portals" used to require agreement to Terms of Service
    #           before granting full Internet access via a Wi-Fi hotspot)
    "511": "Network Authentication Required",
};
 
const LP_LOGPARAMS = 1 << 16;
 
const LP_LEVELMASK = LP_LOGPARAMS - 1;
 
public hashdecl HttpResponseInfo {
    int code;
 
 
    *data body;
 
 
    *InputStream chunked_body;
 
    softbool close = False;
 
    *hash<auto> hdr;
 
    bool reply_sent = False;
 
    string log;
 
    string errlog;
 
    *hash<auto> user_state;
};
 
public hashdecl HttpHandlerResponseInfo {
    int code;
 
 
    auto body;
 
    softbool close = False;
 
 
    *hash<auto> hdr;
 
    bool reply_sent = False;
 
    string log;
 
    string errlog;
 
    *hash<auto> user_state;
};
 
// hashdecl for SSL info
public hashdecl HttpCertInfo {
 
    *string cert_loc;
 
 
    *string key_loc;
 
 
    *string key_password;
 
    *SSLCertificate cert;
    *SSLPrivateKey key;
};
 
public hashdecl HttpListenerOptionInfo {
    *string node;
 
    *softstring service;
 
    *string name;
 
 
    *string cert_loc;
 
 
    *string key_loc;
 
 
    *string key_password;
 
    *Qore::SSLCertificate cert;
 
    *Qore::SSLPrivateKey key;
 
    *hash<string, hash<HttpHandlerConfigInfo>> handler_info;
 
    *LoggerInterface logger;
 
    *code stopc;
 
    int family = AF_UNSPEC;
 
 
    bool get_remote_certs = False;
 
 
    int ssl_verify_flags = 0;
 
 
    bool ssl_accept_all_certs = True;
 
    hash<auto> ext_info;
};
 
public hashdecl HttpHandlerConfigInfo {
    string path = "/";
 
    bool isregex = False;
 
    softlist<softstring> content_types;
 
    AbstractHttpRequestHandler handler;
 
    softlist<softstring> headers;
};
 
 
 string http_get_url_from_bind(softstring bind, *string host);
 
 
 
 hash<Util::UriQueryInfo> parse_uri_query(string path);
 
 
 nothing http_set_reply_headers(Socket s, hash<auto> cx, reference<auto> rv, *string server_string);
 
 
 
 string http_mask_data(string msg);
 
 
 
 hash<HttpListenerOptionInfo> http_get_listener_options(*string node, *softstring service, *string cert_loc, *string key_loc, *string key_password);
 
 
 
 hash<HttpListenerOptionInfo> http_get_listener_options_from_bind(*softstring bind, *string cert_loc, *string key_loc, *string key_password);
 
 
 
 hash<HttpListenerOptionInfo> http_get_listener_options_from_bind(*softstring bind, hash<auto> listener_params, hash<HttpListenerOptionInfo> opts = <HttpListenerOptionInfo>{});
 
 
 
 hash<HttpCertInfo> http_get_ssl_objects(hash<auto> listener_params);
 
 
 
 hash<HttpCertInfo> http_get_ssl_objects(string cert_loc, *string key_loc, *string pwd);
 
 
class AbstractLogger {
 
public:
 
    abstract log(string fmt, ...);
 
 
    abstract logError(string fmt, ...);
 
 
    logArgs(*softlist<auto> args);
 
 
 
    logErrorArgs(*softlist<auto> args);
 
};
 
class HttpListenerInterface : public AbstractLogger {
 
public:
 
    abstract addUserThreadContext(hash<auto> uctx);
 
 
    abstract auto removeUserThreadContext(*string k);
 
 
    logResponse(hash<auto> cx, hash<auto> rv);
 
};
 
 
class AbstractAuthenticator {
 
public:
 
    bool requiresAuthentication();
 
 
 
    string getRealm();
 
 
 
    authenticate(string user, string pass = '');
 
 
 
    authenticateByIP(string ip, reference<string> user);
 
 
 
    hash<auto> getAuthHeader();
 
 
 
    hash<auto> getAuthHeader(hash<auto> cx);
 
 
 
    hash<HttpResponseInfo> do401(string msg = 'Authentication is required to access this server', *hash<auto> cx);
 
 
 
    *hash<HttpResponseInfo> authenticateRequest(HttpListenerInterface listener, hash<auto> hdr, reference<hash<auto>> cx);
 
};
 
class PermissiveAuthenticator : public AbstractAuthenticator {
 
public:
 
    *hash<HttpResponseInfo> authenticateRequest(HttpListenerInterface listener, hash<auto> hdr, reference<hash> cx);
 
};
 
 
class AbstractStreamRequest {
 
public:
    
 
protected:
        HttpListenerInterface listener;
        AbstractHttpRequestHandler handler;
        Socket s;
        hash<auto> cx;
        hash<auto> hdr;
        auto body;
        timeout timeout_ms = HttpServer::DefaultTimeout;
 
public:
 
 
    constructor(HttpListenerInterface listener, AbstractHttpRequestHandler handler, Socket s, hash<auto> cx, hash<auto> hdr, auto body);
 
 
    hash<HttpHandlerResponseInfo> handleRequest();
 
 
 
protected:
     hash<HttpHandlerResponseInfo> sendResponse();
public:
 
 
 
protected:
     hash<HttpHandlerResponseInfo> getResponseHeaderMessage();
public:
 
 
 
protected:
     nothing recv(hash<auto> v);
public:
 
 
 
protected:
     auto send();
public:
 
 
 
protected:
     logChunk(bool send, int size);
public:
 
 
 
protected:
     hash<HttpResponseInfo> getResponseHeaderMessageImpl();
public:
 
 
 
protected:
     nothing recvImpl(hash<auto> v);
public:
 
 
 
protected:
     auto sendImpl();
public:
 
};
 
 
class AbstractHttpRequestHandler {
 
public:
        *AbstractAuthenticator auth;
 
        bool decompress = True;
 
 
        bool decompress_to_string = True;
 
        bool stream;
 
        timeout timeout_ms = HttpServer::DefaultTimeout;
 
        const NotificationThreadKey = "_AHRH_pc";
 
        const PersistenceThreadKey = "_AHRH_p";
 
 
    constructor(*AbstractAuthenticator n_auth, softbool n_stream = False);
 
 
    bool isPersistent();
 
 
    setPersistent(bool p = True);
 
 
    notifyClosed(*code c);
 
 
 
    string maskData(string msg);
 
 
      static staticNotificationCleanup();
 
      static staticPersistenceCleanup();
 
    nothing persistentClosed();
 
 
protected:
     nothing checkPersistent(hash<auto> cx, hash<auto> hdr);
public:
 
 
 
    hash<HttpResponseInfo> handleExpectHeader(hash<auto> cx, hash<auto> hdr);
 
 
 
    hash<HttpResponseInfo> handleRequest(hash<auto> cx, hash<auto> hdr, *data body);
 
 
    hash<HttpResponseInfo> handleRequest(HttpListenerInterface listener, Socket s, hash<auto> cx, hash<auto> hdr, *data body);
 
 
protected:
     AbstractStreamRequest getStreamRequestImpl(HttpListenerInterface listener, Socket s, hash<auto> cx, hash<auto> hdr, *data body);
public:
 
 
      static data decodeBody(string content_encoding, binary body, *string string_encoding);
 
      static binary encodeBody(string content_encoding, data body);
 
    *data getMessageBody(Socket s, hash<auto> hdr, *data body, bool decode = True);
 
 
 
      static *string getLogMessage(hash<auto> cx, hash api, reference params, *reference<string> args);
 
 
    *hash<auto> saveThreadLocalData();
 
 
 
    restoreThreadLocalData(*hash<auto> data);
 
 
      static hash<HttpResponseInfo> makeResponse(int code, string fmt, ...);
 
      static hash<HttpResponseInfo> makeResponse(hash<auto> hdr, int code, string fmt, ...);
 
      static hash<HttpResponseInfo> makeResponse(int code, binary body);
 
      static hash<HttpResponseInfo> makeResponse(hash<auto> hdr, int code, binary body);
 
      static hash<HttpResponseInfo> makeResponse(int code, *data body, *hash<auto> hdr);
 
 
      static hash<HttpResponseInfo> makeResponse(int code, *InputStream chunked_body, *hash<auto> hdr);
 
      static hash<HttpResponseInfo> make200(string fmt, ...);
 
      static hash<HttpResponseInfo> make200(hash<auto> hdr, string fmt, ...);
 
      static hash<HttpResponseInfo> make200(hash<auto> hdr, InputStream chunked_body);
 
      static hash<HttpResponseInfo> make200(InputStream chunked_body);
 
      static hash<HttpResponseInfo> make400(string fmt, ...);
 
      static hash<HttpResponseInfo> make400(hash<auto> hdr, string fmt, ...);
 
      static hash<HttpResponseInfo> make500(string fmt, ...);
 
      static hash<HttpResponseInfo> make500(hash<auto> hdr, string fmt, ...);
 
      static hash<HttpResponseInfo> make501(string fmt, ...);
 
      static hash<HttpResponseInfo> make501(hash<auto> hdr, string fmt, ...);
 
      static hash<HttpResponseInfo> redirect(hash<auto> cx, hash<auto> request_hdr, string path, int status_code = 301, *hash<auto> response_hdr);
};
 
class AbstractUrlHandler : public HttpServer::AbstractHttpRequestHandler {
 
public:
        string url_root;
 
 
    constructor(string n_url_root, *AbstractAuthenticator auth) ;
 
 
 
    string getRelativePath(string path);
 
};
 
 
class AbstractHttpSocketHandlerInterface {
 
public:
protected:
        bool stop = False;
 
        hash<string, int> lh;
 
        hash<string, bool> lsh;
 
        Mutex m();
 
public:
 
 
    start(softstring lid, hash<auto> cx, hash<auto> hdr, Socket s);
 
 
 
    stop(softstring lid);
 
 
 
    stop();
 
 
 
protected:
     abstract startImpl(softstring lid, hash<auto> cx, hash<auto> hdr, Socket s);
public:
 
 
protected:
     stopImpl(string lid);
public:
 
 
 
protected:
     stopImpl();
public:
 
};
 
 
class AbstractHttpSocketHandler : public AbstractHttpRequestHandler, public AbstractHttpSocketHandlerInterface {
 
public:
 
    constructor(*AbstractAuthenticator auth) ;
 
};
};