RestHandler.qm.dox.h

// -*- mode: c++; indent-tabs-mode: nil -*-
 
/* RestHandler.qm Copyright (C) 2013 - 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.
*/
 
// minimum qore version
 
// use new-style
 
// require type definitions everywhere
 
// enable all warnings
 
 
 
namespace RestHandler {
 
    class AbstractRestStreamRequestHandler {
 
public:
        
 
protected:
            hash<auto> cx;
 
            *hash<auto> ex;
 
            *hash<auto> ah;
 
            hash<auto> rhdr;
 
            *int timeout_ms;
 
public:
 
 
        constructor(hash<auto> n_cx, *hash<auto> n_ah);
 
 
 
        hash<HttpServer::HttpHandlerResponseInfo> getResponseHeaderMessage();
 
 
 
        nothing recv(hash<auto> v);
 
 
 
        auto send();
 
 
        *code getPersistentClosedNotification();
 
 
        bool isPersistent();
 
 
        setTimeout(timeout n_timeout_ms);
 
 
        *int getTimeout();
 
 
        streamError(hash<auto> n_ex);
 
 
 
        abstract hash<auto> getResponseHeaderMessageImpl();
 
 
        abstract nothing recvImpl(hash<auto> v);
 
 
        abstract auto sendImpl();
    };
 
class RestStreamRequest : public HttpServer::AbstractStreamRequest {
 
public:
protected:
            RestHandler::AbstractRestStreamRequestHandler stream;
            bool deserialized;
 
public:
 
        constructor(RestHandler::AbstractRestStreamRequestHandler n_stream,
                HttpServer::HttpListenerInterface listener, HttpServer::AbstractHttpRequestHandler handler, Socket s,
                hash<auto> cx, hash<auto> hdr, auto body)
                : HttpServer::AbstractStreamRequest(listener, handler, s,
                    cx + (exists body ? {'deserialized': True} : NOTHING), hdr, body);
 
 
        destructor();
 
 
        // callback method for the response header; this calls @ref RestHandler::AbstractRestStreamRequestHandler::getResponseHeaderMessage() and returns the result
protected:
         hash<HttpServer::HttpHandlerResponseInfo> getResponseHeaderMessageImpl();
public:
 
 
 
protected:
         nothing recvImpl(hash<auto> v);
public:
 
 
 
protected:
         auto sendImpl();
public:
 
    };
 
    class AbstractRestClass {
 
public:
            hash<string, AbstractRestClass> class_hash;
 
            const RestBasicMethodSet = map {$1: True}, RestHandler::Methods.iterator();
 
        constructor();
 
 
        abstract string name();
 
        addClass(AbstractRestClass cls);
 
 
 
        *AbstractRestClass subClass(string name, hash<auto> cx, *hash<auto> args);
 
 
 
        *AbstractRestClass subClassImpl(string name, hash<auto> cx, *hash<auto> args);
 
 
        hash<HttpServer::HttpHandlerResponseInfo> handleRequest(HttpListenerInterface listener, RestHandler rh,
                Socket s, *list<string> cl, string mn, hash<auto> cx, *hash<auto> args) {
            if (!args && cx.body.typeCode() == NT_HASH);
 
            cx.socketobject = s;
            if (cl);
 
 
            // try to mask passwords and sensitive data in args
            string astr = rh.maskData(sprintf("%y", args));
            rh.logDebug("REST DBG: class %y: dispatching method %y args: %s", name(), mn, astr);
            return dispatchStream(listener, rh, s, mn, args, cx);
        }
 
        private hash<HttpServer::HttpHandlerResponseInfo> dispatchStream(HttpListenerInterface listener,
                RestHandler rh, Socket s, string mn, *hash<auto> ah, hash<auto> cx) {
            string sn = "stream" + mn[0].upr() + mn.substr(1);
            AbstractRestStreamRequestHandler rsh;
            try {
                rsh = call_object_method_args(self, sn, (cx, ah));
            } catch (hash<ExceptionInfo> ex) {
                if (ex.err == "METHOD-DOES-NOT-EXIST" && ex.desc.find(sn) != -1) {
                    if (cx.hdr."transfer-encoding" == "chunked")
                        cx.body = rh.getMessageBody(s, cx.hdr, NOTHING);
 
                    return cast<hash<HttpHandlerResponseInfo>>(dispatch(rh, mn, ah, cx));
                }
                string desc = !cx.debug
                    ? sprintf("%s: %s: %s", get_ex_pos(ex), ex.err, ex.desc)
                    : get_exception_string(ex);
                rh.logDebug("REST DBG: class %y: stream method %y: %s", name(), sn, desc);
                rethrow;
            }
            try {
                RestStreamRequest req(rsh, listener, rh, s, cx, cx.hdr, cx.hdr."content-length" ? cx.body : NOTHING);
                return req.handleRequest();
            } catch (hash<ExceptionInfo> ex) {
                // make sure the error is registered with the stream handler
                if (rsh) {
                    # issue #4291: handle errors here correctly
                    try {
                        rsh.streamError(ex);
                    } catch (hash<ExceptionInfo> ex1) {
                        rh.logError("cannot register error %s: %s with stream handler: %s: %s", ex.err, ex.desc,
                            ex1.err, ex1.desc);
                    }
                }
                string desc = !cx.debug
                    ? sprintf("%s: %s: %s", get_ex_pos(ex), ex.err, ex.desc)
                    : get_exception_string(ex);
                rh.logDebug("REST DBG: class %y: stream method %y: %s", name(), sn, desc);
                rethrow;
            }
        }
 
 
        private hash<HttpServer::HttpHandlerResponseInfo> dispatch(RestHandler rh, string mn, *hash<auto> ah,
                hash<auto> cx) {
            try {
                return cast<hash<HttpHandlerResponseInfo>>(call_object_method_args(self, mn, (cx, ah)));
            } catch (hash<ExceptionInfo> ex) {
                if (ex.err == "METHOD-DOES-NOT-EXIST") {
                    // try to mask passwords in args
                    string astr = rh.maskData(sprintf("%y", ah));
                    rh.logError("DISPATCH-ERROR: cannot dispatch to unimplemented method %y: class %y, args: %s", mn,
                        name(), astr);
                    # see if alternate methods would work
                    list hl = ();
                    # break flag
                    bool brk;
                    foreach hash<auto> mh in (RestHandler::Methods.pairIterator()) {
                        string nmn = mh.value + cx.rest_method;
                        if (self.hasCallableMethod(nmn)) {
                            if (mh.key == cx.hdr.method) {
                                brk = True;
                                break;
                            }
                            hl += mh.key;
                        }
                    }
                    if (!brk) {
                        if (!hl)
                            return cast<hash<HttpHandlerResponseInfo>>(RestHandler::make501("REST class %y (%s) does "
                                "not implement method %y", name(), self.className(),
                                cx.orig_method ? cx.orig_method : mn));
 
                        string ml = foldl $1 + "," + $2, hl;
                        string desc = sprintf("HTTP method %s is unimplemented in REST class %y (%s)", cx.hdr.method,
                            name(), self.className());
                        if (cx.orig_method)
                            desc += sprintf(" REST method %y", cx.orig_method);
                        desc += sprintf(", available methods: %s", ml);
                        return cast<hash<HttpHandlerResponseInfo>>(
                            HttpServer::AbstractHttpRequestHandler::makeResponse(("Allow": ml), 405, desc)
                        );
                    }
                }
                string desc = !cx.debug
                    ? sprintf("%s: %s: %s", get_ex_pos(ex), ex.err, ex.desc)
                    : get_exception_string(ex);
                rh.logDebug("REST DBG: class %y: method %y: %s", name(), mn, desc);
                rethrow;
            }
        }
 
 
protected:
         hash<HttpServer::HttpHandlerResponseInfo> unknownSubClassError(string cls_name, hash<auto> cx, *hash<auto> ah);
public:
 
 
 
protected:
         *hash<string, bool> doGetPossibleSubClasses(hash<auto> cx, *hash<auto> ah);
public:
 
    };
 
 
class RestHandler : public HttpServer::AbstractHttpRequestHandler,public  AbstractRestClass {
 
public:
            const Err501 = new hash<HttpResponseInfo>({
                "code": 501,
                "body": "not implemented",
            });
 
            const Methods = {
                "GET": "get",
                "POST": "post",
                "PUT": "put",
                "DELETE": "del",
                "OPTIONS": "options",
                "PATCH": "patch",
            };
 
protected:
            Logger::Logger logger;
 
            RestSchemaValidator::AbstractRestSchemaValidator validator;
 
public:
 
 
        constructor(*HttpServer::AbstractAuthenticator auth,
                RestSchemaValidator::AbstractRestSchemaValidator validator = new NullRestSchemaValidator())
 ;
 
 
 
        constructor(Logger::Logger logger, *HttpServer::AbstractAuthenticator auth,
                RestSchemaValidator::AbstractRestSchemaValidator validator = new NullRestSchemaValidator(logger))
 ;
 
 
        string name();
 
 
        setLogger(Logger::Logger logger);
 
 
 
        auto handleExternalRequest(string method, string path, *hash<auto> body, hash<auto> cx = {});
 
 
 
        hash<HttpResponseInfo> handleRequest(HttpListenerInterface listener, Socket s, hash<auto> cx, hash<auto> hdr,
                *data b) {
            //logDebug("REST DBG: cx: %N", cx);
            //logDebug("REST DBG: hdr: %N", hdr);
 
            auto body = b;
 
            // get rest class name
            string path = cx.url.path ?? "";
 
            removeRootPath(\path);
 
            hash<RestRequestServerInfo> req;
            try {
                if (b) {
                    string bstr = maskData(b.typeCode() == NT_STRING ? trim(b) : sprintf("%y", b));
                    logDebug("REST DBG: body: %s", bstr);
                }
 
                req = validator.parseRequest(hdr.method, path, body, \hdr);
            } catch (hash<ExceptionInfo> ex) {
                logDebug("REST DBG: %s", get_exception_string(ex));
                // return a 400 Bad Request response to encoding, serialization, or validation errors
                if (ex.err == "INVALID-ENCODING"
                    || ex.err == "ENCODING-CONVERSION-ERROR"
                    || ex.err == "DESERIALIZATION-ERROR"
                    || ex.err == "SCHEMA-VALIDATION-ERROR")
                    return AbstractHttpRequestHandler::makeResponse(400, sprintf("%s: %s", ex.err, ex.desc),
                        errorResponseHeaders(cx));
                if (ex.err == "INVALID-METHOD") {
                    string ml = (foldl $1 + "," + $2, ex.arg) ?? "";
                    return AbstractHttpRequestHandler::makeResponse(405, sprintf("HTTP method %y is not supported "
                        "with URI path %y; supported methods: %s", hdr.method, path, ml ?* "<none>"),
                        errorResponseHeaders(cx) + {"Allow": ml});
                }
                rethrow;
            }
 
            // get object and args
            hash<auto> ah = path ? {
                "method": req.path,
                "params": req.query,
            } : {};
            //path ? parse_uri_query(path) : {};
 
            *hash<auto> args;
            if (ah.params);
 
 
            // add path args, if any
            if (req.path_args);
 
 
            if (exists body);
 else {
                body = args;
            }
 
            // reflect body in arguments if body is a hash
            if (body.typeCode() == NT_HASH);
 
 
            if (!Methods.(hdr.method))
                return AbstractHttpRequestHandler::make400("unsupported HTTP method %y given in REST call %y",
                    hdr.method, path);
 
            // make method name
            string mn;
            if (args.action);
 else if (body.action);
 else {
                mn = Methods.(hdr.method);
            }
 
            cx.rest_action_method = mn;
 
            // remove leading slash from method name
            if (ah.method ==1)
                splice ah.method, 0, 1;
 
            // get class chain
            *list<string> cl;
            if (ah.method);
 
 
            // make a hash of "accept" values
            *string astr = hdr.accept;
            hash<auto> aih;
            if (astr);
 else {
                // http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html: If no Accept header field is present, then
                # it is assumed that the client accepts all media types
                aih."*/*" = True;
            }
 
            //logDebug("REST DBG: aih: %y", aih);
 
            // set up context hash
            cx += {"hdr": hdr, "body": body, "aih": aih};
 
            // handle call with class
            hash<HttpHandlerResponseInfo> rv;
 
            try {
                rv = dispatchRequest(listener, s, cl, mn, path, cx, args);
            } catch (hash<ExceptionInfo> ex) {
                string desc = !cx.debug
                    ? sprintf("%s: %s: %s", get_ex_pos(ex), ex.err, ex.desc)
                    : get_exception_string(ex);
 
                logError(desc);
                rv = returnRestException(ex);
            }
 
            if (!rv.reply_sent);
 
 
            //logDebug("REST DBG: rv: %N", rv);
 
            return cast<hash<HttpResponseInfo>>(rv);
        }
 
 
protected:
         *hash<auto> errorResponseHeaders(hash<auto> cx);
public:
 
 
        private hash<HttpHandlerResponseInfo> dispatchRequest(HttpListenerInterface listener, Socket s,
                *list<string> class_list, string method_name, string path, hash<auto> cx, *hash<auto> args) {
            AbstractRestClass rcls;
 
            // get initial class
            *string cls = shift class_list;
 
            if (!cls);
 else {
                *AbstractRestClass c = subClass(cls, cx, args);
                if (!c) {
                    // issue #2994: if we are on the last class and there is no "action" argument; see if we can f
                    # ind an action method instead
                    if (!class_list && !args.action) {
                        string mname = sprintf("%s%s%s", method_name, cls[0].upr(), cls[1..]);
                        if (self.hasCallableMethod(mname)) {
                            rcls = self;
                            method_name = mname;
                        }
                    }
 
                    if (!rcls) {
                        return unknownSubClassError(cls, cx, args);
                    }
                } else {
                    rcls = c;
                }
            }
 
            return rcls.handleRequest(listener, self, s, class_list, method_name, cx, args);
        }
 
 
protected:
         hash<HttpHandlerResponseInfo> returnRestException(hash<ExceptionInfo> ex);
public:
 
 
protected:
         checkExceptionSerializable(reference<hash<ExceptionInfo>> ex);
public:
 
 
        hash<auto> get(hash<auto> cx, *hash<auto> ah);
 
 
        removeRootPath(reference<string> path);
 
 
        requestDeserializationError(hash<auto> hdr, hash<auto> cx, string body);
 
 
        responseSerializationError(hash<auto> cx, *hash<auto> aih, hash<auto> rv);
 
 
 
        logInfo(string fmt);
 
 
 
        logError(string fmt);
 
 
 
        logDebug(string fmt);
 
 
          static hash<HttpHandlerResponseInfo> make200(string fmt);
 
          static hash<HttpHandlerResponseInfo> make200(hash<auto> hdr, string fmt);
 
          static hash<HttpHandlerResponseInfo> make400(string fmt);
 
          static hash<HttpHandlerResponseInfo> make400(hash<auto> hdr, string fmt);
 
          static hash<HttpHandlerResponseInfo> makeResponse(int code, auto body, *hash<auto> hdr);
 
          static hash<HttpHandlerResponseInfo> make500(string fmt);
 
          static hash<HttpHandlerResponseInfo> make500(hash<auto> hdr, string fmt);
 
          static hash<HttpHandlerResponseInfo> make501(string fmt);
 
          static hash<HttpHandlerResponseInfo> make501(hash<auto> hdr, string fmt);
    };
};
 
// private, unexported namespace
namespace Priv {
    // dumHttpListenerInterface class
class DummyListenerInterface : public HttpListenerInterface {
 
public:
        addUserThreadContext(hash<auto> uctx);
 
 
        auto removeUserThreadContext(*string k);
 
 
        log(string fmt);
 
 
        logError(string fmt);
 
    };
};