HttpServerUtil.qm.dox.h

// -*- mode: c++; indent-tabs-mode: nil -*-
 
/*  HttpServerUtil.qm Copyright (C) 2014 - 2024 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.2";
 
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 = ...;
 
 
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:
 
    logResponse(hash<auto> cx, hash<auto> rv);
 
 
    removeExternalDedicatedSocket(softstring id);
 
 
 
    abstract addUserThreadContext(hash<auto> uctx);
 
 
    abstract auto removeUserThreadContext(*string k);
};
 
// for backwared compatibility, calls to deprecated methods are made below
 
 
class AbstractAuthenticator {
 
public:
 
    bool requiresAuthentication();
 
 
 
    string getRealm();
 
 
 
    authenticate(reference<hash<auto>> cx, string user, string pass = '');
 
 
 
    authenticateByIP(reference<hash<auto>> cx, string ip, reference<bool> authenticated);
 
 
 
      deprecated authenticate(string user, string pass = '');
 
 
      deprecated 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);
 
 
 
protected:
     *hash<HttpResponseInfo> authenticateRequestIntern(HttpListenerInterface listener, hash<auto> hdr, reference<hash<auto>> cx, reference<bool> authenticated);
public:
 
 
protected:
     *hash<HttpResponseInfo> processBasicAuthorizationHeader(HttpListenerInterface listener, hash<auto> hdr, reference<hash<auto>> cx, reference<bool> authenticated);
public:
 
 
protected:
     *hash<HttpResponseInfo> processDigestAuthorizationHeader(HttpListenerInterface listener, hash<auto> hdr, reference<hash<auto>> cx, reference<bool> authenticated);
public:
 
 
protected:
     *hash<HttpResponseInfo> processBearerAuthorizationHeader(HttpListenerInterface listener, hash<auto> hdr, reference<hash<auto>> cx, reference<bool> authenticated);
public:
 
 
protected:
     *hash<HttpResponseInfo> processCookieHeader(HttpListenerInterface listener, hash<auto> hdr, reference<hash<auto>> cx, reference<bool> authenticated);
public:
 
 
 
    endRequest();
 
};
 
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);
 
 
 
    *hash<HttpResponseInfo> preprocessRequest(HttpListenerInterface listener, reference<hash<auto>> hdr, reference<hash<auto>> cx);
 
 
 
    *hash<HttpResponseInfo> authenticateRequest(HttpListenerInterface listener, hash<auto> hdr, reference<hash<auto>> cx);
 
 
 
    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 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:
 
    code setExternallyManaged(softstring lid, hash<auto> cx, Socket s);
 
 
 
    bool start(softstring lid, hash<auto> cx, hash<auto> hdr, Socket s);
 
 
 
    stop(softstring lid);
 
 
 
    stop();
 
 
protected:
     handlerStopped(softstring lid);
public:
 
 
 
protected:
     abstract bool 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) ;
 
};
};