core.h

Go to the documentation of this file.

#ifndef FASTLY_CACHE_CORE_H
#define FASTLY_CACHE_CORE_H
 
#include <chrono>
#include <cstdint>
#include <fastly/expected.h>
#include <fastly/http/body.h>
#include <fastly/http/header.h>
#include <fastly/http/request.h>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <variant>
#include <vector>
 
namespace fastly::cache::core {

class CacheError {
public:
  enum Code {
    LimitExceeded,
    InvalidOperation,
    Unsupported,
    Unknown,
  };
  CacheError(Code code) : code_(code) {}
  Code code() const { return code_; }
 
private:
  Code code_;
};
 
namespace detail {
class CacheHandle {
public:
  explicit CacheHandle(std::uint32_t handle) : handle_(handle) {}
  std::uint32_t handle() const { return handle_; }
  ~CacheHandle();
 
private:
  std::uint32_t handle_;
};
 
class CacheReplaceHandle {
public:
  explicit CacheReplaceHandle(std::uint32_t handle) : handle_(handle) {}
  std::uint32_t handle() const { return handle_; }
  ~CacheReplaceHandle();
 
private:
  std::uint32_t handle_;
};
 
class CacheBusyHandle {
public:
  explicit CacheBusyHandle(std::uint32_t handle) : handle_(handle) {}
  std::uint32_t handle() const { return handle_; }
  ~CacheBusyHandle();
 
private:
  std::uint32_t handle_;
};
 
// TODO: this should really live somewhere else, but for now it's the only
// place that we need it, so we'll take an ad-hoc approach.
class RequestHandle {
public:
  static RequestHandle make();
  explicit RequestHandle(std::uint32_t handle) : handle_(handle) {}
  std::uint32_t handle() const { return handle_; }
  ~RequestHandle();
 
private:
  std::uint32_t handle_;
};
} // namespace detail

struct LookupOptions {
  std::optional<detail::RequestHandle> request_headers;
  std::optional<std::string> service;
  bool always_use_requested_range = false;
};

enum class ReplaceStrategy {
  Immediate,
  ImmediateForceMiss,
  Wait,
};

struct ReplaceOptions {
  std::optional<detail::RequestHandle> request_headers;
  ReplaceStrategy replace_strategy = ReplaceStrategy::Immediate;
  std::optional<std::string> service;
  bool always_use_requested_range = false;
};

struct WriteOptions {
  std::chrono::nanoseconds max_age;
  std::optional<detail::RequestHandle> request_headers;
  std::optional<std::string> vary_rule;
  std::optional<std::chrono::nanoseconds> initial_age;
  std::optional<std::chrono::nanoseconds> stale_while_revalidate;
  std::optional<std::string> surrogate_keys;
  std::optional<std::uint64_t> length;
  std::optional<std::vector<std::uint8_t>> user_metadata;
  bool sensitive_data = false;
  std::optional<std::chrono::nanoseconds> edge_max_age;
  std::optional<std::string> service;
  explicit WriteOptions(std::chrono::nanoseconds max_age) : max_age(max_age) {}
};

class TransactionUpdateBuilder {
public:
  TransactionUpdateBuilder vary_by(std::vector<std::string> headers) &&;

  TransactionUpdateBuilder age(std::chrono::nanoseconds age) &&;

  TransactionUpdateBuilder
  deliver_node_max_age(std::chrono::nanoseconds duration) &&;

  TransactionUpdateBuilder
  stale_while_revalidate(std::chrono::nanoseconds duration) &&;

  TransactionUpdateBuilder surrogate_keys(std::vector<std::string> keys) &&;

  TransactionUpdateBuilder user_metadata(std::vector<std::uint8_t> metadata) &&;

  TransactionUpdateBuilder on_behalf_of(std::string service) &&;

  tl::expected<void, CacheError> execute() &&;
 
private:
  TransactionUpdateBuilder(std::shared_ptr<detail::CacheHandle> handle,
                           WriteOptions options)
      : handle_(std::move(handle)), options_(std::move(options)) {}
 
  std::shared_ptr<detail::CacheHandle> handle_;
  WriteOptions options_;
  friend class Transaction;
};

class TransactionInsertBuilder {
public:
  TransactionInsertBuilder vary_by(std::vector<std::string> headers) &&;

  TransactionInsertBuilder initial_age(std::chrono::nanoseconds age) &&;

  TransactionInsertBuilder
  stale_while_revalidate(std::chrono::nanoseconds duration) &&;

  TransactionInsertBuilder surrogate_keys(std::vector<std::string> keys) &&;

  TransactionInsertBuilder known_length(std::uint64_t length) &&;

  TransactionInsertBuilder user_metadata(std::vector<std::uint8_t> metadata) &&;

  TransactionInsertBuilder sensitive_data(bool is_sensitive) &&;

  TransactionInsertBuilder
  deliver_node_max_age(std::chrono::nanoseconds duration) &&;

  TransactionInsertBuilder on_behalf_of(std::string service) &&;

  tl::expected<http::StreamingBody, CacheError> execute() &&;

  tl::expected<std::pair<http::StreamingBody, Found>, CacheError>
  execute_and_stream_back() &&;
 
private:
  TransactionInsertBuilder(std::shared_ptr<detail::CacheHandle> handle,
                           WriteOptions options)
      : handle_(std::move(handle)), options_(std::move(options)) {}
 
  std::shared_ptr<detail::CacheHandle> handle_;
  WriteOptions options_;
  friend class Transaction;
};
 
class Transaction;
class PendingTransaction;

class PendingTransaction {
public:
  tl::expected<bool, CacheError> pending() const;

  tl::expected<Transaction, CacheError> wait() &&;
 
private:
  explicit PendingTransaction(std::shared_ptr<detail::CacheBusyHandle> handle)
      : handle_(std::move(handle)) {}
 
  std::shared_ptr<detail::CacheBusyHandle> handle_;
  friend class TransactionLookupBuilder;
};

class TransactionLookupBuilder {
public:
  TransactionLookupBuilder
  header_values(std::string_view name,
                std::span<const http::HeaderValue> values) &&;


  TransactionLookupBuilder header(std::string_view name,
                                  const http::HeaderValue &value) &&;

  TransactionLookupBuilder on_behalf_of(std::string service) &&;

  TransactionLookupBuilder always_use_requested_range() &&;

  tl::expected<Transaction, CacheError> execute() &&;

  tl::expected<PendingTransaction, CacheError> execute_async() &&;
 
private:
  explicit TransactionLookupBuilder(std::vector<std::uint8_t> key) : key_(std::move(key)) {}
  std::vector<std::uint8_t> key_;
  LookupOptions options_;
  friend class Transaction;
};

class Found {
public:
  std::chrono::nanoseconds age() const;

  std::chrono::nanoseconds max_age() const;

  std::chrono::nanoseconds remaining_ttl() const;

  std::chrono::nanoseconds stale_while_revalidate() const;

  bool is_stale() const;

  bool is_usable() const;

  uint64_t hits() const;

  std::optional<uint64_t> known_length() const;

  std::vector<uint8_t> user_metadata() const;

  tl::expected<Body, CacheError> to_stream() const;

  tl::expected<Body, CacheError>
  to_stream_from_range(std::optional<uint64_t> from,
                       std::optional<uint64_t> to) const;
 
private:
  explicit Found(std::shared_ptr<detail::CacheHandle> handle)
      : handle_(std::move(handle)) {}
  explicit Found(std::shared_ptr<detail::CacheReplaceHandle> handle)
      : handle_(std::move(handle)) {}
 
  detail::CacheHandle *handle() const {
    auto ptr = std::get_if<std::shared_ptr<detail::CacheHandle>>(&handle_);
    return ptr ? ptr->get() : nullptr;
  }
  detail::CacheReplaceHandle *replace_handle() const {
    auto ptr =
        std::get_if<std::shared_ptr<detail::CacheReplaceHandle>>(&handle_);
    return ptr ? ptr->get() : nullptr;
  }
 
  std::variant<std::shared_ptr<detail::CacheHandle>,
               std::shared_ptr<detail::CacheReplaceHandle>>
      handle_;
  friend class Transaction;
  friend class LookupBuilder;
  friend class TransactionInsertBuilder;
  friend class ReplaceBuilder;
};

class Transaction {
public:
  static TransactionLookupBuilder lookup(std::span<const std::uint8_t> key);

  static TransactionLookupBuilder lookup(std::string_view key) {
    return lookup(std::span(reinterpret_cast<const std::uint8_t *>(key.data()),
                            key.size()));
  }

  std::optional<Found> found() const;

  bool must_insert() const;

  bool must_insert_or_update() const;

  tl::expected<void, CacheError> cancel_insert_or_update() const;

  TransactionUpdateBuilder update(std::chrono::nanoseconds max_age) &&;

  TransactionInsertBuilder insert(std::chrono::nanoseconds max_age) &&;
 
private:
  explicit Transaction(std::shared_ptr<detail::CacheHandle> handle)
      : handle_(std::move(handle)) {}
 
  std::shared_ptr<detail::CacheHandle> handle_;
  friend class TransactionLookupBuilder;
  friend class PendingTransaction;
};

class LookupBuilder {
public:
  LookupBuilder header_values(std::string_view name,
                              std::span<const http::HeaderValue> values) &&;


  LookupBuilder header(std::string_view name,
                       const http::HeaderValue &value) &&;

  LookupBuilder on_behalf_of(std::string service) &&;

  LookupBuilder always_use_requested_range() &&;

  tl::expected<std::optional<Found>, CacheError> execute() &&;
 
private:
  explicit LookupBuilder(std::vector<std::uint8_t> key) : key_(std::move(key)) {}
  std::vector<std::uint8_t> key_;
  LookupOptions options_;
  friend LookupBuilder lookup(std::span<const std::uint8_t> key);
};

LookupBuilder lookup(std::span<const std::uint8_t> key);

inline LookupBuilder lookup(std::string_view key) {
  return lookup(std::span(reinterpret_cast<const std::uint8_t *>(key.data()),
                          key.size()));
}

class InsertBuilder {
public:
  InsertBuilder header_values(std::string_view name,
                              std::span<const http::HeaderValue> values) &&;


  InsertBuilder header(std::string_view name,
                       const http::HeaderValue &value) &&;

  InsertBuilder vary_by(std::vector<std::string> headers) &&;

  InsertBuilder initial_age(std::chrono::nanoseconds age) &&;

  InsertBuilder stale_while_revalidate(std::chrono::nanoseconds duration) &&;

  InsertBuilder surrogate_keys(std::vector<std::string> keys) &&;

  InsertBuilder known_length(std::uint64_t length) &&;

  InsertBuilder user_metadata(std::vector<std::uint8_t> metadata) &&;

  InsertBuilder sensitive_data(bool is_sensitive) &&;

  InsertBuilder deliver_node_max_age(std::chrono::nanoseconds duration) &&;

  InsertBuilder on_behalf_of(std::string service) &&;

  tl::expected<http::StreamingBody, CacheError> execute() &&;
 
private:
  explicit InsertBuilder(std::vector<std::uint8_t> key, WriteOptions options)
      : key_(std::move(key)), options_(std::move(options)) {}
  std::vector<std::uint8_t> key_;
  WriteOptions options_;
  friend InsertBuilder insert(std::span<const std::uint8_t> key,
                              std::chrono::nanoseconds max_age);
};

InsertBuilder insert(std::span<const std::uint8_t> key,
                     std::chrono::nanoseconds max_age);

inline InsertBuilder insert(std::string_view key,
                            std::chrono::nanoseconds max_age) {
  return insert(std::span(reinterpret_cast<const std::uint8_t *>(key.data()),
                          key.size()),
                max_age);
}
 
class Replace;

class ReplaceBuilder {
public:
  tl::expected<Replace, CacheError> begin() &&;

  ReplaceBuilder replace_strategy(ReplaceStrategy strategy) &&;

  ReplaceBuilder always_use_requested_range() &&;
 
private:
  explicit ReplaceBuilder(std::vector<std::uint8_t> key) : key_(std::move(key)) {}
  std::vector<std::uint8_t> key_;
  ReplaceOptions options_;
  friend ReplaceBuilder replace(std::span<const std::uint8_t> key);
};

class Replace {
public:
  tl::expected<http::StreamingBody, CacheError>
  execute(std::chrono::nanoseconds max_age) &&;

  const std::optional<Found> &existing_object() const {
    return existing_object_;
  }

  Replace header_values(std::string_view name,
                        std::span<const http::HeaderValue> values) &&;


  Replace header(std::string_view name, const http::HeaderValue &value) &&;

  Replace vary_by(std::vector<std::string> headers) &&;

  Replace initial_age(std::chrono::nanoseconds age) &&;

  Replace stale_while_revalidate(std::chrono::nanoseconds duration) &&;

  Replace surrogate_keys(std::vector<std::string> keys) &&;

  Replace known_length(std::uint64_t length) &&;

  Replace user_metadata(std::vector<std::uint8_t> metadata) &&;

  Replace sensitive_data(bool is_sensitive) &&;

  Replace deliver_node_max_age(std::chrono::nanoseconds duration) &&;
 
private:
  Replace(std::shared_ptr<detail::CacheReplaceHandle> handle,
          std::optional<Found> existing_object)
      : handle_(std::move(handle)),
        existing_object_(std::move(existing_object)) {}
 
  std::shared_ptr<detail::CacheReplaceHandle> handle_;
  std::optional<Found> existing_object_;
  WriteOptions options_{std::chrono::nanoseconds(0)};
  friend class ReplaceBuilder;
};

ReplaceBuilder replace(std::span<const std::uint8_t> key);

inline ReplaceBuilder replace(std::string_view key) {
  return replace(std::span(reinterpret_cast<const std::uint8_t *>(key.data()),
                           key.size()));
}
 
} // namespace fastly::cache::core
 
#endif // FASTLY_CACHE_H