record.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.
------------------------------------------------------------------------
The value-type contract shared between record producers and
record-storage backends.
 
A `Record` (in the `ngen::serialization` namespace) is the
engine-agnostic interchange unit between code that *produces* a
piece of saved state (e.g. a BMI adapter capturing a model's
bytes) and code that *stores* that state (e.g. a file backend
that lays it out on disk, an HDF5 backend that stores it as a
dataset + attributes, or any future storage).
 
This header defines only the value type and a small parse helper.
It does NOT prescribe a wire format — backends are free to encode
the fields however suits their storage.
*/
#pragma once
 
#include <boost/core/span.hpp>
 
#include <cctype>
#include <cstdint>
#include <ctime>
#include <exception>
#include <limits>
#include <string>
#include <vector>
 
namespace ngen{ namespace serialization{
constexpr const char* TIMESTAMP_STRPTIME_FORMAT = "%Y-%m-%d %T";
 
constexpr int64_t UNPARSEABLE_TIMESTAMP_SENTINEL
    = (std::numeric_limits<int64_t>::min)();
 
inline int64_t parse_epoch_string(const std::string& s) {
    try {
        std::size_t     consumed = 0;
        const long long v        = std::stoll(s, &consumed);
        while (consumed < s.size()
               && std::isspace(static_cast<unsigned char>(s[consumed]))) {
            ++consumed;
        }
        if (consumed == s.size()) {
            return static_cast<int64_t>(v);
        }
    } catch (const std::exception&) {
        // std::out_of_range / std::invalid_argument — fall through
        // to the sentinel.
    }
    return UNPARSEABLE_TIMESTAMP_SENTINEL;
}
 
inline int64_t parse_formatted_time(const std::string& s) {
    std::tm     tm  = {};
    const char* end = ::strptime(s.c_str(), TIMESTAMP_STRPTIME_FORMAT, &tm);
    if (end != nullptr) {
        while (*end != '\0' && std::isspace(static_cast<unsigned char>(*end))) {
            ++end;
        }
        if (*end == '\0') {
            return static_cast<int64_t>(::timegm(&tm));
        }
    }
    return UNPARSEABLE_TIMESTAMP_SENTINEL;
}
 
inline int64_t parse_timestamp(const std::string& s) {
    if (s.empty()) return UNPARSEABLE_TIMESTAMP_SENTINEL;
    const int64_t epoch = parse_epoch_string(s);
    if (epoch != UNPARSEABLE_TIMESTAMP_SENTINEL) return epoch;
    return parse_formatted_time(s);
}
 
namespace detail {
 
// Shared field set for the two public checkpoint-record types
// (`Record` and `RecordView`, below). Implementation alignment
// mechanism only — adding or changing a metadata field touches
// one definition and both aliases inherit the change.
template <typename PayloadT>
struct RecordT {
    std::string       id;
    int64_t           time_step            = 0;
    int64_t           simulation_timestamp = 0;
    int64_t           checkpoint_epoch     = 0;
    PayloadT          payload{};
 
    RecordT() = default;
    RecordT(std::string id_,
                        int64_t time_step_,
                        int64_t simulation_timestamp_,
                        PayloadT payload_,
                        int64_t checkpoint_epoch_ = 0)
        : id(std::move(id_))
        , time_step(time_step_)
        , simulation_timestamp(simulation_timestamp_)
        , checkpoint_epoch(checkpoint_epoch_)
        , payload(std::move(payload_)) {}
};
 
} // namespace detail
 
using Record     = detail::RecordT<std::vector<char>>;
 
using RecordView = detail::RecordT<boost::span<const char>>;
 
}}  // namespace ngen::serialization