openapi.h

#ifndef SOURCEMETA_CORE_OPENAPI_H_
#define SOURCEMETA_CORE_OPENAPI_H_
 
#ifndef SOURCEMETA_CORE_OPENAPI_EXPORT
#include <sourcemeta/core/openapi_export.h>
#endif
 
#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonpointer.h>
#include <sourcemeta/core/jsonschema.h>
 
// NOLINTBEGIN(misc-include-cleaner)
#include <sourcemeta/core/openapi_error.h>
// NOLINTEND(misc-include-cleaner)
 
#include <concepts>    // std::invocable, std::predicate
#include <cstddef>     // std::size_t
#include <cstdint>     // std::uint8_t, std::uint64_t
#include <functional>  // std::function, std::less
#include <limits>      // std::numeric_limits
#include <map>         // std::map
#include <memory>      // std::unique_ptr
#include <optional>    // std::optional, std::nullopt
#include <string_view> // std::string_view
#include <vector>      // std::vector

 
namespace sourcemeta::core {

enum class OpenAPIVersion : std::uint8_t {
  OPENAPI_3_1,
  OPENAPI_3_2
};

SOURCEMETA_CORE_OPENAPI_EXPORT
auto openapi_version(const JSON &document) -> std::optional<OpenAPIVersion>;

SOURCEMETA_CORE_OPENAPI_EXPORT
auto openapi_version_name(const OpenAPIVersion version) noexcept
    -> JSON::StringView;

struct OpenAPIContact {
  std::optional<JSON::StringView> name{std::nullopt};
  std::optional<JSON::StringView> url{std::nullopt};
  std::optional<JSON::StringView> email{std::nullopt};
};

struct OpenAPILicense {
  JSON::StringView name{};
  std::optional<JSON::StringView> identifier{std::nullopt};
  std::optional<JSON::StringView> url{std::nullopt};
};

struct OpenAPIInfo {
  JSON::StringView title{};
  JSON::StringView version{};
  std::optional<JSON::StringView> summary{std::nullopt};
  std::optional<JSON::StringView> description{std::nullopt};
  std::optional<JSON::StringView> terms_of_service{std::nullopt};
  std::optional<OpenAPIContact> contact{std::nullopt};
  std::optional<OpenAPILicense> license{std::nullopt};
};

class SOURCEMETA_CORE_OPENAPI_EXPORT OpenAPIFrame {
public:
  enum class ObjectKind : std::uint8_t {
    Document,
    // The eleven a reference may expect to find, the last of them only from 3.2
    // onwards, which is where a `content` map and the Components Object both
    // learn to hold a Reference Object in place of a Media Type Object
    PathItem,
    Parameter,
    RequestBody,
    Response,
    Example,
    Header,
    Link,
    Callbacks,
    SecurityScheme,
    MediaType,
    // The rest are never referenced, but every Object gets a location
    Info,
    Contact,
    License,
    Server,
    ServerVariable,
    Components,
    Paths,
    Operation,
    ExternalDocumentation,
    Encoding,
    Responses,
    Tag,
    Reference,
    Schema,
    OAuthFlows,
    OAuthFlow,
    SecurityRequirement
  };

  enum class OperationKind : std::uint8_t {
    Path,
    Webhook,
    Callback
  };

  struct Reference {
    JSON::String original;
    JSON::String destination;
    bool dangling{false};
    ObjectKind expected{ObjectKind::Document};
    Pointer origin;
  };

  struct Operation {
    OperationKind kind;
    JSON::String path;
    JSON::String method;
    JSON::String origin;
    JSON::String endpoint;
    std::optional<JSON::String> parent{std::nullopt};
    std::vector<JSON::String> servers;
    std::vector<JSON::String> security;
    std::vector<JSON::String> parameters;
    std::vector<std::optional<JSON::String>> tags;
  };

  struct Discriminator {
    Pointer origin;
    JSON::String destination;
    JSON::String scope;
    bool dangling{false};
  };

  struct Location {
    ObjectKind type;
    Pointer pointer;
    std::optional<JSON::StringView> parent{std::nullopt};
    JSON::String default_dialect;
    JSON::String base;
  };

  using Locations = std::map<JSON::String, Location, std::less<>>;

  using References = std::map<JSON::String, Reference, std::less<>>;

  OpenAPIFrame(
      const JSON &document, const SchemaWalker &walker,
      const SchemaResolver &resolver, std::string_view default_base = "",
      std::uint64_t max_locations = std::numeric_limits<std::uint64_t>::max());
 
  ~OpenAPIFrame();
 
  // We rely on internal caches that would be dangling otherwise
  OpenAPIFrame(const OpenAPIFrame &) = delete;
  auto operator=(const OpenAPIFrame &) -> OpenAPIFrame & = delete;
  OpenAPIFrame(OpenAPIFrame &&) = delete;
  auto operator=(OpenAPIFrame &&) -> OpenAPIFrame & = delete;

  [[nodiscard]] auto version() const noexcept -> OpenAPIVersion;

  [[nodiscard]] auto info() const noexcept -> const OpenAPIInfo &;

  [[nodiscard]] auto base() const noexcept -> JSON::StringView;

  [[nodiscard]] auto standalone() const noexcept -> bool;

  [[nodiscard]] auto schemas() const noexcept -> const SchemaFrame &;

  [[nodiscard]] auto locations() const noexcept -> const Locations &;

  [[nodiscard]] auto references() const noexcept -> const References &;

  [[nodiscard]] auto security_references() const noexcept -> const References &;

  [[nodiscard]] auto operations() const noexcept
      -> const std::vector<Operation> &;

  [[nodiscard]] auto discriminators() const noexcept
      -> const std::vector<Discriminator> &;

  template <std::invocable<const JSON::String &, const Location &> F>
  auto for_each_object(const F &callback) const -> void {
    for (const auto &entry : this->locations()) {
      callback(entry.first, entry.second);
    }
  }

  template <std::predicate<const JSON::String &, const Location &> F>
  [[nodiscard]] auto any_object(const F &predicate) const -> bool {
    for (const auto &entry : this->locations()) {
      if (predicate(entry.first, entry.second)) {
        return true;
      }
    }
 
    return false;
  }

  template <std::invocable<const JSON::String &, const Reference &> F>
  auto for_each_reference(const F &callback) const -> void {
    for (const auto &entry : this->references()) {
      callback(entry.first, entry.second);
    }
  }

  template <std::invocable<const JSON::String &, const Reference &> F>
  auto for_each_security_reference(const F &callback) const -> void {
    for (const auto &entry : this->security_references()) {
      callback(entry.first, entry.second);
    }
  }

  template <std::invocable<const Operation &> F>
  auto for_each_operation(const F &callback) const -> void {
    for (const auto &operation : this->operations()) {
      callback(operation);
    }
  }

  template <std::invocable<const Discriminator &> F>
  auto for_each_discriminator(const F &callback) const -> void {
    for (const auto &discriminator : this->discriminators()) {
      callback(discriminator);
    }
  }

  [[nodiscard]] auto traverse(const JSON::StringView uri) const
      -> const Location *;

  [[nodiscard]] auto uri(const Pointer &pointer) const -> JSON::String;

  [[nodiscard]] auto object_count() const noexcept -> std::size_t;

  [[nodiscard]] auto reference_count() const noexcept -> std::size_t;

  [[nodiscard]] auto to_json(
      const std::optional<PointerPositionTracker> &tracker = std::nullopt) const
      -> JSON;
 
private:
// Exporting symbols that depends on the standard C++ library is considered
// safe.
// https://learn.microsoft.com/en-us/cpp/error-messages/compiler-warnings/compiler-warning-level-2-c4275?view=msvc-170&redirectedfrom=MSDN
#if defined(_MSC_VER)
#pragma warning(push)
#pragma warning(disable : 4251)
#endif
  struct Internal;
  std::unique_ptr<Internal> internal_;
#if defined(_MSC_VER)
#pragma warning(pop)
#endif
};

SOURCEMETA_CORE_OPENAPI_EXPORT
auto openapi_kind_name(const OpenAPIFrame::ObjectKind kind) noexcept
    -> JSON::StringView;

SOURCEMETA_CORE_OPENAPI_EXPORT
auto openapi_operation_kind_name(
    const OpenAPIFrame::OperationKind kind) noexcept -> JSON::StringView;

using OpenAPIResolverResult = OwnedOrReference<JSON>;

using OpenAPIResolver = std::function<OpenAPIResolverResult(std::string_view)>;

SOURCEMETA_CORE_OPENAPI_EXPORT
auto openapi_format(JSON &document, const OpenAPIFrame &frame) -> void;

struct OpenAPIBundleOptions {
  using Callback =
      std::function<void(JSON::StringView, const sourcemeta::core::Pointer &)>;

  using Namer = std::function<JSON::String(JSON::StringView, JSON::StringView)>;

  std::string_view default_base{};
  std::uint64_t max_locations{std::numeric_limits<std::uint64_t>::max()};
  Callback callback{};
  Namer namer{};
};

SOURCEMETA_CORE_OPENAPI_EXPORT
auto openapi_bundle(JSON &document, const SchemaWalker &walker,
                    const SchemaResolver &schema_resolver,
                    const OpenAPIResolver &resolver,
                    const OpenAPIBundleOptions &options = {}) -> void;

SOURCEMETA_CORE_OPENAPI_EXPORT
auto openapi_bundle(const JSON &document, const SchemaWalker &walker,
                    const SchemaResolver &schema_resolver,
                    const OpenAPIResolver &resolver,
                    const OpenAPIBundleOptions &options = {}) -> JSON;
 
} // namespace sourcemeta::core
 
#endif