RestSchemaValidator.qm.dox.h

// -*- mode: c++; indent-tabs-mode: nil -*-
 
/*  RestSchemaValidator.qm Copyright (C) 2017 - 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.
*/
 
 
// make sure we have the required qore version
 
// requires the HttpServerUtil module
 
// need mime definitions
 
// supports using the DataProvider module to describe input and output records
 
// supports logging with the Logger module
 
 
 
 
 
namespace RestSchemaValidator {
    public hashdecl RestRequestClientInfo {
        string uri_path;
        string content;
 
        *list<string> response_content;
        *data body;
    };
 
    public hashdecl RestRequestServerInfo {
        string path;
        *hash<auto> query;
        *hash<auto> path_args;
        auto body;
        hash<auto> info;
    };
 
    public hashdecl RestResponseClientInfo {
        int code;
        auto body;
        hash<auto> hdr;
        hash<auto> info;
    };
 
    public hashdecl RestExampleRequestInfo {
        string request_uri;
        hash<auto> hdr;
        string body;
    };
 
    public hashdecl RestExampleResponseInfo {
        string response_uri;
        int code;
        hash<auto> hdr;
        string body;
    };
 
    public hashdecl RestQoreExampleCodeInfo {
        hash<string, string> hashdecls();
 
        string example;
    };
 
    class AbstractRestSchemaValidator {
 
public:
protected:
            *Logger::Logger logger;
 
public:
 
        constructor();
 
 
        constructor(Logger::Logger logger);
 
 
        setLogger(Logger::Logger logger);
 
 
 
        string getHash();
 
 
 
        string getTargetUrl();
 
 
 
        hash<RestRequestClientInfo> processRequest(string method, string path, auto body, *hash<auto> headers,
                *softlist<string> content_types) {
            return processRequestImpl(method, path, body, headers, content_types);
        }
 
 
        hash<RestRequestServerInfo> parseRequest(string method, string path, *data http_body,
                reference<hash<auto>> headers) {
            return parseRequestImpl(method, path, http_body, \headers);
        }
 
 
        hash<HttpResponseInfo> processResponse(string method, string path, int code, auto response_body,
                *hash<auto> headers, *softlist<string> content_types) {
            return processResponseImpl(method, path, code, response_body, headers, content_types);
        }
 
 
        hash<RestResponseClientInfo> parseResponse(string method, string path, int code, *data response_body,
                hash<auto> hdr) {
            // strip any query arguments from the path when validating
            path =~ s/\?.*//;
            return parseResponseImpl(method, path, code, response_body, hdr);
        }
 
 
        hash<RestQoreExampleCodeInfo> getQoreExampleRequest(string method, string path);
 
 
 
        hash<RestExampleRequestInfo> getExampleRequest(string method, string path, *softlist<string> content_types);
 
 
 
        hash<RestQoreExampleCodeInfo> getQoreExampleResponse(string method, string path, int code);
 
 
 
        hash<RestExampleResponseInfo> getExampleResponse(string method, string path, int code,
                *softlist<string> content_types) {
            hash<RestExampleResponseInfo> rv = getExampleResponseImpl(method, path, code, content_types);
            if (!rv.response_uri)
                rv.response_uri = sprintf("HTTP/1.1 %d %s", code, HttpCodes{code} ?? "Unknown");
            return rv;
        }
 
 
        hash<string, list<string>> getPathOperationHash();
 
 
 
        string getBasePath();
 
 
 
        setBasePath(string basePath);
 
 
 
        DataProvider::AbstractDataProvider getDataProvider(HTTPClient rest);
 
 
 
        bool managesUriPath();
 
 
 
        setTimeZoneLocale(*TimeZone tz);
 
 
 
        *TimeZone getTimeZoneLocale();
 
 
 
protected:
         DataProvider::AbstractDataProvider getDataProviderImpl(HTTPClient rest);
public:
 
 
 
protected:
         abstract string getHashImpl();
public:
 
 
protected:
         abstract string getTargetUrlImpl();
public:
 
 
        private abstract hash<RestRequestClientInfo> processRequestImpl(string method, string path, auto body,
                *hash<auto> headers, *softlist<string> content_types);
 
 
        private abstract hash<RestRequestServerInfo> parseRequestImpl(string method, string path, *data http_body,
                reference<hash> headers);
 
 
        private abstract hash<HttpResponseInfo> processResponseImpl(string method, string path, int code,
                auto response_body, *hash<auto> headers, *softlist<string> content_types);
 
 
        private abstract hash<RestResponseClientInfo> parseResponseImpl(string method, string path, int code,
                *data response_body, hash<auto> hdr);
 
 
protected:
         abstract hash<string, list<string>> getPathOperationHashImpl();
public:
 
 
protected:
         abstract string getBasePathImpl();
public:
 
 
protected:
         abstract setBasePathImpl(string basePath);
public:
 
 
protected:
         abstract hash<RestQoreExampleCodeInfo> getQoreExampleRequestImpl(string method, string path);
public:
 
 
        private abstract hash<RestExampleRequestInfo> getExampleRequestImpl(string method, string path,
                *softlist<string> content_types);
 
 
        private abstract hash<RestQoreExampleCodeInfo> getQoreExampleResponseImpl(string method, string path,
                int code);
 
 
        private abstract hash<RestExampleResponseInfo> getExampleResponseImpl(string method, string path, int code,
                *softlist<string> content_types);
 
 
protected:
         abstract setTimeZoneLocaleImpl(*TimeZone tz);
public:
 
 
protected:
         abstract *TimeZone getTimeZoneLocaleImpl();
public:
    };
 
class NullRestSchemaValidator : public AbstractRestSchemaValidator {
 
public:
            const DataSerializationSupport = {
%ifndef NoJson
                MimeTypeJson: \make_json(),
%endif
%ifndef NoYaml
                MimeTypeYamlRpc: \make_yaml(),
                MimeTypeYaml: \make_yaml(),
%endif
%ifndef NoXml
                MimeTypeXml: \make_xmlrpc_value(),
                MimeTypeXmlApp: string sub (auto v) {
                    switch (v.typeCode()) {
                        case NT_LIST: return make_xml(("list": ("element": v)));
                        case NT_HASH: return v.size() == 1 && v.firstValue().lsize() == 1 ? make_xml(v) : make_xml(("value": v));
                    }
                    return make_xml(("value": v));
                },
%endif
                MimeTypeFormUrlEncoded: string sub (auto v) {
                    if (v.typeCode() == NT_HASH)
                        return mime_get_form_urlencoded_string(v);
                    throw "FORMURLENCODING-ERROR", sprintf("form URL encoding can only encode hashes; type %y requested", v.type());
                },
                MimeTypeText: data sub (auto s) {
                    switch (s.typeCode()) {
                        case NT_STRING:
                        case NT_BINARY:
                            return s;
                        default:
                            // issue #3547: send as a YAML-serialized string if possible to catch unserializable data
%ifndef NoYaml
                            return make_yaml(s);
%else
                            throw "TEXT-SERIALIZATION-ERROR", sprintf("cannot serialize type %y without YAML support", s.type());
%endif
                    }
                },
                MimeTypeOctetStream: binary sub (auto s) {
                    switch (s.typeCode()) {
                        case NT_STRING:
                            return binary(s);
                        case NT_BINARY:
                            return s;
                        default:
                            # issue #3547: send as a YAML-serialized string if possible to catch unserializable data
%ifndef NoYaml
                            return binary(make_yaml(s));
%else
                            throw "BINARY-SERIALIZATION-ERROR", sprintf("cannot serialize type %y without YAML support", s.type());
%endif
                    }
                },
            };
 
            const DataSerializationSupportList = keys DataSerializationSupport;
 
            const DeserializeYaml = ...;
 
            const DeserializeXml = ...;
 
 
            const DataDeserializationSupport = {
                MimeTypeFormUrlEncoded: (
                    "code": "url",
                    "in": \mime_parse_form_urlencoded_string(),
                ),
%ifndef NoJson
                MimeTypeJson: (
                    "code": "json",
                    "in": \parse_json(),
                ),
%endif
%ifndef NoYaml
                MimeTypeYamlRpc: DeserializeYaml,
                MimeTypeYaml: DeserializeYaml,
%endif
%ifndef NoXml
                MimeTypeXml: DeserializeXml,
                MimeTypeXmlApp: DeserializeXml,
%endif
                MimeTypeText: (
                    "code": "text",
                    "in": data sub (data s) { return s; },
                ),
 
                MimeTypeOctetStream: {
                    "code": "bin",
                    "in": binary sub (data s) {
                        return s.typeCode() == NT_BINARY ? s : binary(s);
                    },
                },
            };
 
 
            const NullSchemaHashStr = "<null rest schema>";
 
 
        bool managesUriPath();
 
 
 
protected:
         string getHashImpl();
public:
 
 
 
protected:
         string getTargetUrlImpl();
public:
 
 
 
protected:
         hash<RestRequestClientInfo> processRequestImpl(string method, string path, auto body, *hash<auto> headers, *softlist<string> content_types);
public:
 
 
 
protected:
         hash<RestRequestServerInfo> parseRequestImpl(string method, string path, *data http_body, reference<hash> headers);
public:
 
 
 
        private hash<HttpResponseInfo> processResponseImpl(string method, string path, int code, auto response_body,
                *hash<auto> headers, *softlist<string> content_types) {
            hash<HttpResponseInfo> rv((
                "code": code,
                "hdr": headers,
            ));
 
            if (exists response_body);
 
 
            rv.body = response_body;
            rv.hdr = headers;
            return rv;
        }
 
 
        private hash<RestResponseClientInfo> parseResponseImpl(string method, string path, int code,
                *data response_body, hash<auto> hdr) {
            hash<RestResponseClientInfo> rv((
                "code": code,
                "hdr": hdr,
            ));
 
            if (response_body.val());
 
 
            return rv;
        }
 
 
        private:internal bool checkResponseContentTypeHeader(reference<hash<HttpResponseInfo>> resp, auto body,
                *hash<auto> headers, *softlist<string> content_types) {
            // quickly return if body is not in data format
            if (body.typeCode() != NT_BINARY && body.typeCode() != NT_STRING)
                return False;
 
            // try to find \c Content-Type header
            *list ct = map $1, keys headers, $1 ==1i;
 
            // if found and it is accepted, use it and don't serialize the body
            if (ct && ct.size() == 1);
 
            return False;
        }
 
 
protected:
         hash<string, list<string>> getPathOperationHashImpl();
public:
 
 
 
protected:
         string getBasePathImpl();
public:
 
 
 
protected:
         setBasePathImpl(string basePath);
public:
 
 
 
protected:
         hash<RestQoreExampleCodeInfo> getQoreExampleRequestImpl(string method, string path);
public:
 
 
 
        private hash<RestExampleRequestInfo> getExampleRequestImpl(string method, string path,
                *softlist<string> content_types) {
            return new hash<RestExampleRequestInfo>();
        }
 
 
protected:
         hash<RestQoreExampleCodeInfo> getQoreExampleResponseImpl(string method, string path, int code);
public:
 
 
 
        private hash<RestExampleResponseInfo> getExampleResponseImpl(string method, string path, int code,
                *softlist<string> content_types) {
            return new hash<RestExampleResponseInfo>();
        }
 
 
protected:
         setTimeZoneLocaleImpl(*TimeZone tz);
public:
 
 
 
protected:
         *TimeZone getTimeZoneLocaleImpl();
public:
 
    };
};