HttpServerUtil.qm.dox.h

// -*- mode: c++; indent-tabs-mode: nil -*-
// @file HttpServerUtil.qm HTTP server base code

/*  HttpServerUtil.qm Copyright (C) 2014 - 2016 David Nichols

    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.
*/

// need mime definitions




namespace HttpServer {
    const HttpServerVersion = "0.3.11";

    const HttpServerString = sprintf("Qore-HTTP-Server/%s", HttpServerVersion);

    const DefaultTimeout = 30s;  // recvs timeout after 30 seconds

    const ReadTimeout = DefaultTimeout;

    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",

        // 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 Yextern 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;


     string http_get_url_from_bind(softstring bind, *string host);



     hash parse_uri_query(string path);


     nothing http_set_reply_headers(Socket s, hash cx, reference rv, *string server_string);

};

class HttpServer::AbstractLogger {

public:

    abstract log(string fmt);


    abstract logError(string fmt);


    logArgs(*softlist args);



    logErrorArgs(*softlist args);

};

class HttpServer::HttpListenerInterface : public HttpServer::AbstractLogger {

public:

    abstract addUserThreadContext(hash uctx);


    abstract any removeUserThreadContext(*string k);
};


class HttpServer::AbstractAuthenticator {

public:

    bool requiresAuthentication();



    string getRealm();



    authenticate(string user, string pass = "");



    authenticateByIP(string ip, reference user);


    private hash getAuthHeader();


    private hash do401(string msg = "Authentication is required to access this server");



    *hash authenticateRequest(HttpListenerInterface listener, hash hdr, reference cx);

};

class HttpServer::PermissiveAuthenticator : public HttpServer::AbstractAuthenticator {

public:

    *hash authenticateRequest(HttpListenerInterface listener, hash hdr, reference cx);

};


class HttpServer::AbstractStreamRequest {

public:
private:

public:

    private :
        HttpListenerInterface listener;
        AbstractHttpRequestHandler handler;
        Socket s;
        hash cx;
        hash hdr;
        any body;
        timeout timeout_ms = HttpServer::DefaultTimeout;

public:


    constructor(HttpListenerInterface n_listener, AbstractHttpRequestHandler n_handler, Socket n_s, hash n_cx, hash n_hdr, any n_body);


    hash handleRequest();



    private hash sendResponse();



    private hash getResponseHeaderMessage();



    private nothing recv(hash v);


    private any send();


    private logChunk(bool send, int size);



    private hash getResponseHeaderMessageImpl();



    private nothing recvImpl(hash v);



    private any sendImpl();

};


class HttpServer::AbstractHttpRequestHandler {

public:
    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";

public:


    constructor(*AbstractAuthenticator n_auth, softbool n_stream = False);


    bool isPersistent();


    setPersistent(bool p = True);


    notifyClosed(*code c);


      static staticNotificationCleanup();

      static staticPersistenceCleanup();

    nothing persistentClosed();


    private nothing checkPersistent(hash cx, hash hdr);



    hash handleRequest(hash cx, hash hdr, *data body);


    hash handleRequest(HttpListenerInterface listener, Socket s, hash cx, hash hdr, *data body);


    private AbstractStreamRequest getStreamRequestImpl(HttpListenerInterface listener, Socket s, hash cx, hash hdr, *data body);


      static data decodeBody(string ce, binary body, *string enc);

      static binary encodeBody(string ce, data body);

    *data getMessageBody(Socket s, hash hdr, *data body, bool decode = True);



      static *string getLogMessage(hash cx, hash api, reference params, *reference args);


    *hash saveThreadLocalData();



    restoreThreadLocalData(*hash data);


      static hash makeResponse(int code, string fmt);

      static hash makeResponse(hash hdr, int code, string fmt);

      static hash makeResponse(int code, *data body, *hash hdr);

      static hash make400(string fmt);

      static hash make400(hash hdr, string fmt);

      static hash make501(string fmt);

      static hash make501(hash hdr, string fmt);

      static hash redirect(hash cx, hash hdr, string path);
};

class HttpServer::AbstractUrlHandler : public HttpServer::AbstractHttpRequestHandler {

public:
    public :
        string url_root;

public:


    constructor(string n_url_root, *AbstractAuthenticator auth) ;


    string getRelativePath(string path);

};


class HttpServer::AbstractHttpSocketHandler : public HttpServer::AbstractHttpRequestHandler {

public:
    private :
        bool stop = False;

        hash lh;

        hash lsh;

        Mutex m();

public:


    constructor(*AbstractAuthenticator auth) ;



    start(softstring lid, hash cx, hash hdr, Socket s);



    stop(softstring lid);



    stop();



    abstract hash handleRequest(hash cx, hash hdr, *data b);


    private abstract startImpl(softstring lid, hash cx, hash hdr, Socket s);


    private stopImpl(string lid);


    private stopImpl();

};