record_backend.hpp

/*
Author: Nels Frazier
Copyright (C) 2025 Lynker
------------------------------------------------------------------------
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
 
    http://www.apache.org/licenses/LICENSE-2.0
 
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
------------------------------------------------------------------------
Abstract record-storage interface.
 
`RecordBackend` is the engine-agnostic abstraction over "how
does this `Record` end up persisted and retrievable later."
Concrete backends implement the interface and choose their own
storage details; the abstract surface is silent on byte layout.
 
This file declares the abstract surface and per-method API
contracts. Cross-cutting design — sub-handle lifetime patterns,
error categorization, single-in-flight rule, durability,
identity, recommended call patterns — lives in this directory's
README.md; that's the discoverable reference for backend
implementers.
*/
#pragma once
 
#include "id_predicates.hpp"
#include "record.hpp"
 
#include <nonstd/expected.hpp>
 
#include <chrono>
#include <cstdint>
#include <memory>
#include <string>
#include <vector>
 
namespace ngen{ namespace serialization{
 
// Pull `expected` and `make_unexpected` into the library namespace
// so signatures below stay unqualified. Switching the underlying
// implementation (e.g. to std::expected when the codebase moves to
// C++23) is a one-line change here.
using nonstd::expected;
using nonstd::make_unexpected;
 
enum class Durability { relaxed, strict };
 
struct BackendError {
    enum class Kind { NotFound, Corrupted, IOError };
    Kind        kind;
    std::string message;
 
    BackendError() = default;
    BackendError(Kind k, std::string m)
        : kind(k), message(std::move(m)) {}
};
 
class RecordBackend {
public:
    class Writer {
    public:
        virtual ~Writer() = default;
 
        [[nodiscard]] virtual auto write(const RecordView& rv)
            -> expected<void, BackendError> = 0;
 
        [[nodiscard]] virtual auto commit()
            -> expected<void, BackendError> = 0;
    };
 
    class Reader {
    public:
        virtual ~Reader() = default;
 
        [[nodiscard]] virtual auto find_latest(const std::string& id)
            -> expected<Record, BackendError> = 0;
 
        [[nodiscard]] virtual auto find_at_step(const std::string& id,
                                                int64_t time_step)
            -> expected<Record, BackendError> = 0;
 
        [[nodiscard]] virtual auto
        find_at_simulation_timestamp(const std::string& id,
                                     int64_t simulation_timestamp)
            -> expected<Record, BackendError> = 0;
 
        [[nodiscard]] virtual auto close() -> expected<void, BackendError> {
            return {};
        }
    };
 
    virtual ~RecordBackend() = default;
 
    [[nodiscard]] virtual auto
    writer(std::chrono::system_clock::time_point epoch,
           Durability durability)
        -> expected<std::unique_ptr<Writer>, BackendError> = 0;
 
    [[nodiscard]] virtual auto reader(IdPredicate in_scope = {})
        -> expected<std::unique_ptr<Reader>, BackendError> = 0;
 
    [[nodiscard]] virtual auto finalize()
        -> expected<void, std::vector<BackendError>> = 0;
 
    // Scoped convenience wrappers — recommended call pattern.
    // Non-virtual; concrete backends do not override them. See
    // the README for why they exist and what they enforce.
 
    template <typename F>
    [[nodiscard]] auto with_writer(std::chrono::system_clock::time_point epoch,
                                   Durability durability, F&& fn)
        -> expected<void, BackendError>
    {
        auto wo = writer(epoch, durability);
        if (!wo) return make_unexpected(std::move(wo.error()));
        std::forward<F>(fn)(*wo.value());
        return wo.value()->commit();
    }
 
    template <typename F>
    [[nodiscard]] auto with_reader(IdPredicate in_scope, F&& fn)
        -> expected<void, BackendError>
    {
        auto ro = reader(std::move(in_scope));
        if (!ro) return make_unexpected(std::move(ro.error()));
        std::forward<F>(fn)(*ro.value());
        return ro.value()->close();
    }
};
 
}}  // namespace ngen::serialization