endpoint.h

Go to the documentation of this file.

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the Apache 2.0 License.
#pragma once
 
#include "ccf/ds/json.h"
#include "ccf/ds/openapi.h"
#include "ccf/endpoint_context.h"
#include "ccf/http_consts.h"
#include "ccf/rest_verb.h"
#include "ccf/service/map.h"
#include "ccf/service/operator_feature.h"
 
#include <string>
#include <utility>
 
namespace ccf::endpoints
{
  using URI = std::string;
 
  struct EndpointKey
  {
    URI uri_path;
    RESTVerb verb = HTTP_POST;
 
    [[nodiscard]] std::string to_str() const
    {
      return fmt::format("{} {}", verb.c_str(), uri_path);
    }
  };
}
 
namespace ccf::kv::serialisers
{
  template <>
  struct BlitSerialiser<ccf::endpoints::EndpointKey>
  {
    static SerialisedEntry to_serialised(
      const ccf::endpoints::EndpointKey& endpoint_key)
    {
      auto str =
        fmt::format("{} {}", endpoint_key.verb.c_str(), endpoint_key.uri_path);
      return {str.begin(), str.end()};
    }
 
    static ccf::endpoints::EndpointKey from_serialised(
      const SerialisedEntry& data)
    {
      std::string str{data.begin(), data.end()};
      auto i = str.find(' ');
      if (i == std::string::npos)
      {
        throw std::logic_error("invalid encoding of endpoint key");
      }
      auto verb = str.substr(0, i);
      auto uri_path = str.substr(i + 1);
      return {uri_path, verb};
    }
  };
}
 
namespace ccf::endpoints
{
  DECLARE_JSON_TYPE(EndpointKey);
  DECLARE_JSON_REQUIRED_FIELDS(EndpointKey, uri_path, verb);
 
  enum class ForwardingRequired : uint8_t
  {
    Sometimes,
 
    Always,
 
    Never
  };
 
  enum class RedirectionStrategy : uint8_t
  {
    None,
 
    ToPrimary,
 
    ToBackup,
  };
 
  enum class Mode : uint8_t
  {
    ReadWrite,
    ReadOnly,
    Historical
  };
 
  enum QueryParamPresence : uint8_t
  {
    RequiredParameter,
    OptionalParameter,
  };
 
  DECLARE_JSON_ENUM(
    ForwardingRequired,
    {{ForwardingRequired::Sometimes, "sometimes"},
     {ForwardingRequired::Always, "always"},
     {ForwardingRequired::Never, "never"}});
 
  DECLARE_JSON_ENUM(
    RedirectionStrategy,
    {{RedirectionStrategy::None, "none"},
     {RedirectionStrategy::ToPrimary, "to_primary"},
     {RedirectionStrategy::ToBackup, "to_backup"}});
 
  DECLARE_JSON_ENUM(
    Mode,
    {{Mode::ReadWrite, "readwrite"},
     {Mode::ReadOnly, "readonly"},
     {Mode::Historical, "historical"}});
 
  struct InterpreterReusePolicy
  {
    enum class Kind : uint8_t
    {
      KeyBased
    } kind = Kind::KeyBased;
 
    std::string key;
 
    bool operator==(const InterpreterReusePolicy&) const = default;
  };
 
  void to_json(nlohmann::json& j, const InterpreterReusePolicy& grp);
  void from_json(const nlohmann::json& j, InterpreterReusePolicy& grp);
  std::string schema_name(
    [[maybe_unused]] const InterpreterReusePolicy* policy);
  void fill_json_schema(
    nlohmann::json& schema,
    [[maybe_unused]] const InterpreterReusePolicy* policy);
 
  struct EndpointProperties
  {
    Mode mode = Mode::ReadWrite;
    ForwardingRequired forwarding_required = ForwardingRequired::Always;
    RedirectionStrategy redirection_strategy = RedirectionStrategy::ToPrimary;
    std::vector<nlohmann::json> authn_policies;
    nlohmann::json openapi;
    bool openapi_hidden = false;
    std::string js_module;
    std::string js_function;
    std::optional<InterpreterReusePolicy> interpreter_reuse = std::nullopt;
  };
 
  DECLARE_JSON_TYPE_WITH_OPTIONAL_FIELDS(EndpointProperties);
  DECLARE_JSON_REQUIRED_FIELDS(
    EndpointProperties, forwarding_required, authn_policies);
  DECLARE_JSON_OPTIONAL_FIELDS(
    EndpointProperties,
    openapi,
    openapi_hidden,
    mode,
    js_module,
    js_function,
    interpreter_reuse,
    redirection_strategy);
 
  struct EndpointDefinition
  {
    virtual ~EndpointDefinition() = default;
 
    EndpointKey dispatch;
 
    URI full_uri_path;
 
    EndpointProperties properties;
 
    AuthnPolicies authn_policies;
 
    std::set<OperatorFeature> required_operator_features;
  };
 
  using EndpointDefinitionPtr = std::shared_ptr<const EndpointDefinition>;
 
  using EndpointsMap = ccf::ServiceMap<EndpointKey, EndpointProperties>;
  namespace Tables
  {
    static constexpr auto ENDPOINTS = "public:ccf.gov.endpoints";
  }
 
  struct Endpoint : public EndpointDefinition
  {
    // Functor which is invoked to process requests for this Endpoint
    EndpointFunction func;
 
    // Functor which is invoked to modify the response after it is locally
    // committed (ie - assigned a transaction ID)
    LocallyCommittedEndpointFunction locally_committed_func;
 
    struct Installer
    {
      virtual void install(Endpoint&) = 0;
      virtual ~Installer() = default;
    };
    Installer* installer = nullptr;
 
    using SchemaBuilderFn =
      std::function<void(nlohmann::json&, const Endpoint&)>;
    std::vector<SchemaBuilderFn> schema_builders;
 
    bool openapi_hidden = false;
 
    http_status success_status = HTTP_STATUS_OK;
    nlohmann::json params_schema = nullptr;
    nlohmann::json result_schema = nullptr;
 
    std::optional<std::string> openapi_summary = std::nullopt;
    std::optional<std::string> openapi_description = std::nullopt;
    std::optional<bool> openapi_deprecated = std::nullopt;
 
    Endpoint& set_openapi_description(const std::string& description);
 
    Endpoint& set_openapi_summary(const std::string& summary);
 
    Endpoint& set_openapi_deprecated(bool is_deprecated);
 
    Endpoint& set_openapi_deprecated_replaced(
      const std::string& deprecation_version, const std::string& replacement);
 
    Endpoint& set_openapi_hidden(bool hidden);
 
    Endpoint& require_operator_feature(OperatorFeature feature);
 
    Endpoint& set_params_schema(const nlohmann::json& j);
 
    Endpoint& set_result_schema(
      const nlohmann::json& j,
      std::optional<http_status> status = std::nullopt);
 
    // NOLINTNEXTLINE(misc-confusable-identifiers)
    template <typename In, typename Out>
    Endpoint& set_auto_schema(std::optional<http_status> status = std::nullopt)
    {
      if constexpr (!std::is_same_v<In, void>)
      {
        params_schema = ds::json::build_schema<In>();
 
        schema_builders.push_back(
          [](nlohmann::json& document, const Endpoint& endpoint) {
            const auto http_verb = endpoint.dispatch.verb.get_http_method();
            if (!http_verb.has_value())
            {
              // Non-HTTP endpoints are not documented
              return;
            }
 
            ds::openapi::add_request_body_schema<In>(
              document, endpoint.full_uri_path, http_verb.value());
          });
      }
      else
      {
        params_schema = nullptr;
      }
 
      if constexpr (!std::is_same_v<Out, void>)
      {
        success_status = status.value_or(HTTP_STATUS_OK);
 
        result_schema = ds::json::build_schema<Out>();
 
        schema_builders.push_back(
          [](nlohmann::json& document, const Endpoint& endpoint) {
            const auto http_verb = endpoint.dispatch.verb.get_http_method();
            if (!http_verb.has_value())
            {
              return;
            }
 
            ds::openapi::add_response_schema<Out>(
              document,
              endpoint.full_uri_path,
              http_verb.value(),
              endpoint.success_status);
          });
      }
      else
      {
        success_status = status.value_or(HTTP_STATUS_NO_CONTENT);
        result_schema = nullptr;
      }
 
      return *this;
    }
 
    template <typename T>
    Endpoint& set_auto_schema(std::optional<http_status> status = std::nullopt)
    {
      return set_auto_schema<typename T::In, typename T::Out>(status);
    }
 
    template <typename T>
    Endpoint& add_query_parameter(
      const std::string& param_name,
      QueryParamPresence presence = QueryParamPresence::RequiredParameter)
    {
      schema_builders.push_back(
        [param_name,
         presence](nlohmann::json& document, const Endpoint& endpoint) {
          const auto http_verb = endpoint.dispatch.verb.get_http_method();
          if (!http_verb.has_value())
          {
            // Non-HTTP endpoints are not documented
            return;
          }
 
          const auto schema_name = ds::json::schema_name<T>();
          const auto query_schema = ds::json::build_schema<T>();
 
          auto parameter = nlohmann::json::object();
          parameter["name"] = param_name;
          parameter["in"] = "query";
          parameter["required"] =
            presence == QueryParamPresence::RequiredParameter;
          parameter["schema"] = ds::openapi::add_schema_to_components(
            document, schema_name, query_schema);
          ds::openapi::add_request_parameter_schema(
            document, endpoint.full_uri_path, http_verb.value(), parameter);
        });
 
      return *this;
    }
 
    Endpoint& set_forwarding_required(ForwardingRequired fr);
 
    Endpoint& set_redirection_strategy(RedirectionStrategy rs);
 
    Endpoint& set_locally_committed_function(
      const LocallyCommittedEndpointFunction& lcf);
 
    void install();
  };
 
  using EndpointPtr = std::shared_ptr<const Endpoint>;
}
 
FMT_BEGIN_NAMESPACE
template <>
struct formatter<ccf::endpoints::ForwardingRequired>
{
  template <typename ParseContext>
  constexpr auto parse(ParseContext& ctx)
  {
    return ctx.begin();
  }
 
  template <typename FormatContext>
  auto format(
    const ccf::endpoints::ForwardingRequired& v, FormatContext& ctx) const
  {
    switch (v)
    {
      case ccf::endpoints::ForwardingRequired::Sometimes:
      {
        return format_to(ctx.out(), "sometimes");
      }
      case ccf::endpoints::ForwardingRequired::Always:
      {
        return format_to(ctx.out(), "always");
      }
      case ccf::endpoints::ForwardingRequired::Never:
      {
        return format_to(ctx.out(), "never");
      }
      default:
      {
        throw std::logic_error(fmt::format(
          "Unhandled value for ForwardingRequired: {}",
          static_cast<uint8_t>(v)));
      }
    }
  }
};
FMT_END_NAMESPACE