httpapi.h

Go to the documentation of this file.

 
#pragma once
 
 
#include <promeki/config.h>
#if PROMEKI_ENABLE_HTTP
#include <functional>
#include <promeki/function.h>
#include <promeki/namespace.h>
#include <promeki/objectbase.h>
#include <promeki/error.h>
#include <promeki/result.h>
#include <promeki/string.h>
#include <promeki/stringlist.h>
#include <promeki/list.h>
#include <promeki/variant.h>
#include <promeki/variantspec.h>
#include <promeki/variantdatabase.h>
#include <promeki/variantlookup.h>
#include <promeki/json.h>
#include <promeki/httpmethod.h>
#include <promeki/httprequest.h>
#include <promeki/httpresponse.h>
#include <promeki/httphandler.h>
#include <promeki/httpserver.h>
 
PROMEKI_NAMESPACE_BEGIN
 
class HttpServer;
 
class HttpApi : public ObjectBase {
                PROMEKI_OBJECT(HttpApi, ObjectBase)
        public:
                static const String DefaultPrefix;
 
                static const String DefaultTitle;
 
                static const String DefaultVersion;
 
                // ============================================================
                // Endpoint descriptor types
                // ============================================================
 
                enum class ParamIn {
                        Path,   
                        Query,  
                        Header, 
                        Body,   
                };
 
                struct Param {
                                using List = ::promeki::List<Param>;
 
                                String      name;                
                                ParamIn     in = ParamIn::Query; 
                                bool        required = false;    
                                VariantSpec spec;                
                };
 
                struct ErrorResponse {
                                using List = ::promeki::List<ErrorResponse>;
 
                                int         status = 0;  
                                String      description; 
                                VariantSpec body;        
                };
 
                struct Endpoint {
                                using List = ::promeki::List<Endpoint>;
 
                                String      path;
                                HttpMethod  method;   
                                String      title;    
                                String      summary;  
                                StringList  tags;     
                                Param::List params;   
                                VariantSpec response; 
                                String responseContentType = "application/json"; 
                                ErrorResponse::List errors; 
                                bool                deprecated = false; 
 
                                // FIXME(auth): when an authentication/authorization
                                // story lands, add a `security` field here (list of
                                // required scope/scheme names) and a matching
                                // HttpApi::setSecurityScheme() / addSecurityScheme()
                                // accessor for the OpenAPI components.securitySchemes
                                // block.  The catalog and OpenAPI generators must
                                // surface the per-endpoint security[] array, and the
                                // route-installer must enforce it (returning 401/403
                                // before invoking the handler) — neither is done
                                // today.  Tracked so this isn't silently forgotten.
 
                                Endpoint &addParam(Param p) {
                                        params.pushToBack(std::move(p));
                                        return *this;
                                }
 
                                Endpoint &addTag(const String &t) {
                                        tags.pushToBack(t);
                                        return *this;
                                }
                };
 
                // ============================================================
                // RPC convenience
                // ============================================================
 
                using RpcCall = Function<Result<Variant>(const VariantMap &args)>;
 
                // ============================================================
                // Construction / lifetime
                // ============================================================
 
                explicit HttpApi(HttpServer &server, const String &prefix = DefaultPrefix,
                                 ObjectBase *parent = nullptr);
 
                ~HttpApi() override;
 
                HttpServer &server() { return _server; }
 
                const HttpServer &server() const { return _server; }
 
                const String &prefix() const { return _prefix; }
 
                String resolve(const String &relative) const;
 
                // ============================================================
                // OpenAPI metadata
                // ============================================================
 
                void setTitle(const String &title) { _title = title; }
 
                const String &title() const { return _title; }
 
                void setVersion(const String &version) { _version = version; }
 
                const String &version() const { return _version; }
 
                void setDescription(const String &desc) { _description = desc; }
 
                const String &description() const { return _description; }
 
                void addServer(const String &url, const String &description = String());
 
                void setDefaultErrors(ErrorResponse::List errors);
 
                // ============================================================
                // Endpoint registration
                // ============================================================
 
                Error route(Endpoint ep, HttpHandlerFunc handler);
 
                Error rpc(Endpoint ep, RpcCall call);
 
                template <CompiledString N>
                Error exposeDatabase(const String &mountPath, const String &title, VariantDatabase<N> &db,
                                     bool readOnly = false);
 
                template <typename T> Error exposeLookup(const String &mountPath, const String &title, T &target);
 
                // ============================================================
                // Bundled module installers
                // ============================================================
 
                Error installPromekiAPI();
 
                // ============================================================
                // Catalog / mount
                // ============================================================
 
                Endpoint::List endpoints() const;
 
                int endpointCount() const;
 
                Error mount();
 
                bool isMounted() const { return _mounted; }
 
                // ============================================================
                // Catalog / OpenAPI rendering (also used by the routes)
                // ============================================================
 
                JsonObject toCatalog() const;
 
                JsonObject toOpenApi() const;
 
                static JsonObject variantSpecToJsonSchema(const VariantSpec &spec, JsonObject *componentsOut = nullptr);
 
        private:
                struct ServerEntry {
                                using List = ::promeki::List<ServerEntry>;
                                String url;
                                String description;
                };
 
                // Internal: install a single endpoint into both the
                // catalog and the underlying HTTP server.  Returns
                // Error::Exists if (path, method) already exists.
                Error registerEndpoint(Endpoint ep, HttpHandler::Ptr handler);
 
                // Internal: render error responses, falling back to
                // _defaultErrors when the endpoint declares none.
                const ErrorResponse::List &errorsFor(const Endpoint &ep) const;
 
                // Internal: the three handler factories for mount().
                HttpHandlerFunc  makeCatalogHandler() const;
                HttpHandlerFunc  makeOpenApiHandler() const;
                HttpHandler::Ptr makeExplorerHandler() const;
 
                HttpServer         &_server;
                String              _prefix;
                bool                _mounted = false;
                String              _title;
                String              _version;
                String              _description;
                ServerEntry::List   _servers;
                ErrorResponse::List _defaultErrors;
                Endpoint::List      _endpoints;
 
                // Internal helpers used by exposeDatabase / exposeLookup.
                Error              addEndpointDescriptor(Endpoint ep);
                static VariantSpec keyParamSpec(const StringList &knownKeys);
};
 
// ============================================================
// Reflection adapter template definitions
// ============================================================
 
template <CompiledString N>
Error HttpApi::exposeDatabase(const String &mountPath, const String &title, VariantDatabase<N> &db, bool readOnly) {
        using DB = VariantDatabase<N>;
        using ID = typename DB::ID;
 
        // mountPath is relative to this api's prefix.  Resolve it
        // before handing it to HttpServer (which doesn't know about
        // the api's prefix) and to the catalog (which stores
        // absolute paths).
        const String absMount = resolve(mountPath);
 
        // Hand the actual route registration off to HttpServer; the
        // catalog publication is the only thing layered on top.
        _server.exposeDatabase(absMount, db, readOnly);
 
        // Collect declared keys for the {key} param description so the
        // explorer's free-form input has a hint of valid values.
        StringList knownKeys;
        const auto specs = DB::registeredSpecs();
        for (auto it = specs.cbegin(); it != specs.cend(); ++it) {
                knownKeys.pushToBack(ID::fromId(it->first).name());
        }
 
        // GET <absMount> — full snapshot.
        Endpoint epAll;
        epAll.path = absMount;
        epAll.method = HttpMethod::Get;
        epAll.title = title + ": snapshot";
        epAll.summary = String("Returns every key/value pair in ") + title + " as a single JSON object.";
        epAll.tags = {title};
        epAll.response = VariantSpec().setDescription("JSON object whose keys are the database IDs.");
        if (Error err = addEndpointDescriptor(epAll); err.isError()) return err;
 
        // GET <absMount>/_schema — registered specs.
        Endpoint epSchema;
        epSchema.path = absMount + "/_schema";
        epSchema.method = HttpMethod::Get;
        epSchema.title = title + ": schema";
        epSchema.summary = "Returns the registered VariantSpec for every "
                           "declared key (type, default, range, description).";
        epSchema.tags = {title};
        epSchema.response = VariantSpec().setDescription("JSON object keyed by ID name; each value carries the spec.");
        if (Error err = addEndpointDescriptor(epSchema); err.isError()) return err;
 
        // GET <absMount>/{key} — single value.
        Endpoint epGet;
        epGet.path = absMount + "/{key}";
        epGet.method = HttpMethod::Get;
        epGet.title = title + ": get key";
        epGet.summary = "Returns a single value plus its spec.";
        epGet.tags = {title};
        epGet.params = {Param{
                .name = "key",
                .in = ParamIn::Path,
                .required = true,
                .spec = keyParamSpec(knownKeys),
        }};
        epGet.response = VariantSpec().setDescription("JSON object with the value under its name and an "
                                                      "optional `_spec` companion.");
        if (Error err = addEndpointDescriptor(epGet); err.isError()) return err;
 
        if (readOnly) return Error::Ok;
 
        // PUT <absMount>/{key} — set.
        Endpoint epPut;
        epPut.path = absMount + "/{key}";
        epPut.method = HttpMethod::Put;
        epPut.title = title + ": set key";
        epPut.summary = "Updates a single value, validating it against the "
                        "registered spec.";
        epPut.tags = {title};
        epPut.params = {
                Param{
                        .name = "key",
                        .in = ParamIn::Path,
                        .required = true,
                        .spec = keyParamSpec(knownKeys),
                },
                Param{
                        .name = "value",
                        .in = ParamIn::Body,
                        .required = true,
                        .spec = VariantSpec().setDescription("New value for the key (shape depends on spec)."),
                },
        };
        epPut.response = VariantSpec().setDescription("JSON object with the stored value under its name.");
        if (Error err = addEndpointDescriptor(epPut); err.isError()) return err;
 
        // DELETE <absMount>/{key} — clear.
        Endpoint epDel;
        epDel.path = absMount + "/{key}";
        epDel.method = HttpMethod::Delete;
        epDel.title = title + ": delete key";
        epDel.summary = "Clears the entry for a single key.";
        epDel.tags = {title};
        epDel.params = {Param{
                .name = "key",
                .in = ParamIn::Path,
                .required = true,
                .spec = keyParamSpec(knownKeys),
        }};
        return addEndpointDescriptor(epDel);
}
 
template <typename T> Error HttpApi::exposeLookup(const String &mountPath, const String &title, T &target) {
        const String absMount = resolve(mountPath);
        _server.exposeLookup(absMount, target);
 
        Endpoint ep;
        ep.path = absMount + "/{path}";
        ep.method = HttpMethod::Get;
        ep.title = title;
        ep.summary = "Resolves a path-style key against the live object "
                     "tree (slashes mapped to dots; bare integer segments "
                     "to [N] index suffixes).";
        ep.tags = {title};
        ep.params = {Param{
                .name = "path",
                .in = ParamIn::Path,
                .required = true,
                .spec = VariantSpec().setType(DataTypeString).setDescription("Greedy lookup path."),
        }};
        ep.response = VariantSpec().setDescription("JSON object {\"value\": <variant>}.");
        return addEndpointDescriptor(ep);
}
 
PROMEKI_NAMESPACE_END
 
#endif // PROMEKI_ENABLE_HTTP