table_core.hpp

Go to the documentation of this file.

#pragma once

 
#include <cstddef>
#include <cstdint>
#include <optional>
#include <span>
#include <string_view>
#include <vector>
 
#include <welder/vocabulary.hpp>
 
#include <wowlib/core/buffer.hpp>
#include <wowlib/core/error.hpp>
#include <wowlib/core/file_key.hpp>
#include <wowlib/db/codec.hpp>
#include <wowlib/db/record_bridge.hpp>
#include <wowlib/formats/common/string_block.hpp>
#include <wowlib/formats/common/validation.hpp>
 
namespace wowlib::fs {
  class FileSystem;
}
 
namespace wowlib::db {
  class TableCore {
  public:
    void wire(void* recordsVec, const detail::RecordOps* ops, TableInfo info) {
      _vec = recordsVec;
      _ops = ops;
      _info = info;
    }

    void wire(RecordSink* sink, const RecordSource* source, TableInfo info) {
      _extSink = sink;
      _extSource = source;
      _info = info;
    }

    void rewire(void* recordsVec) { _vec = recordsVec; }

    void rewire(RecordSink* sink, const RecordSource* source) {
      _extSink = sink;
      _extSource = source;
    }
 
    Result<void> read(std::span<const std::byte> data);
    Result<void> read(fs::FileSystem& fs, const FileKey& key);
    Result<FileBuffer> write(EncryptedPolicy policy) const;
    Result<void> write(fs::FileSystem& fs, const FileKey& key, EncryptedPolicy policy) const;
 
    const formats::StringBlock& strings() const { return _state.strings; }
 
    const std::vector<EncryptedSection>& encryptedSections() const {
      return _state.encrypted;
    }
 
    bool fullyDecoded() const { return _state.encrypted.empty(); }
    formats::ValidationReport validate() const;
    Result<void> ensureValid() const { return validate().toResult(); }

    const TableInfo& info() const { return _info; }

    void* recordsVec() const { return _vec; }
    const detail::RecordOps* ops() const { return _ops; }
 
  private:
    Result<void> _requireWired() const;
    std::uint32_t _db2MagicForVersion() const;
    Result<std::uint32_t> _freshMagic(std::optional<std::string_view> path) const;
    Result<FileBuffer> _writeAs(std::uint32_t magic, EncryptedPolicy policy) const;
 
    void* _vec = nullptr;
    const detail::RecordOps* _ops = nullptr;
    RecordSink* _extSink = nullptr; 
    const RecordSource* _extSource = nullptr; 
    TableInfo _info{};
    TableState _state;
  };

  class [[
      =welder::weld,
      =welder::doc("The common surface of every client-database table: decode "
        "(read), encode (write), validation, and the preserved decode "
        "state. Concrete tables add their typed records.")]] TableBase {
  public:
    [[=welder::doc("Decode a table file image."),
      =welder::returns(
        "nothing; raises on malformed input or a schema mismatch")]]
    Result<void> read(std::span<const std::byte> data [[=welder::doc("the whole file content")]]) {
      return _core.read(data);
    }
 
    [[=welder::doc("Load the table from a client filesystem."),
      =welder::returns("nothing; raises when loading fails")]]
    Result<void> read(fs::FileSystem& fs [[=welder::doc("the filesystem gateway")]],
                      const FileKey& key [[=welder::doc("the file to read")]]) {
      return _core.read(fs, key);
    }
 
    [[=welder::doc(
        "Serialize the table to a file image; a loaded table re-emits "
        "the format it was read from. `policy` decides how keyless "
        "encrypted sections are handled."),
      =welder::returns("the file bytes")]]
    Result<FileBuffer> write(EncryptedPolicy policy
      [[=welder::doc("keyless-section handling (WDC only)")]]
      = EncryptedPolicy::Preserve) const {
      return _core.write(policy);
    }
 
    [[=welder::doc("Serialize the table into a client filesystem (project "
        "overlay); the target path's extension picks .dbc/.db2 in "
        "the mixed eras."),
      =welder::returns("nothing; raises when saving fails")]]
    Result<void> write(fs::FileSystem& fs [[=welder::doc("the filesystem gateway")]],
                       const FileKey& key [[=welder::doc("the file to write")]],
                       EncryptedPolicy policy
        [[=welder::doc("keyless-section handling (WDC only)")]]
                         = EncryptedPolicy::Preserve) const {
      return _core.write(fs, key, policy);
    }
 
    [[=welder::getter,
      =welder::doc(
        "The preserved string block the record string fields were decoded "
        "from; offsets never move, write() appends new strings past its "
        "end.")]]
    const formats::StringBlock& strings() const { return _core.strings(); }
 
    [[=welder::getter,
      =welder::doc(
        "The encrypted sections skipped on read: their records are not "
        "in records, but the file re-writes them verbatim.")]]
    const std::vector<EncryptedSection>& encryptedSections() const {
      return _core.encryptedSections();
    }
 
    [[=welder::getter,
      =welder::doc(
        "Whether the whole table decoded — false when encrypted sections "
        "were skipped.")]]
    bool fullyDecoded() const { return _core.fullyDecoded(); }
 
    [[nodiscard]]
    [[=welder::doc(R"(
        Check the logical integrity contracts the records must satisfy to
        survive a write and load in the client: the primary key stays unique,
        and no string holds an embedded NUL the string block would truncate.
        write() never runs this.)"),
      =welder::returns("every violated contract, in record order")]]
    formats::ValidationReport validate() const { return _core.validate(); }
 
    [[nodiscard]]
    [[=welder::doc("Validate and raise on the first error instead of returning "
        "a report — the assert-style face of validate()."),
      =welder::returns("nothing; raises when validate() finds any error")]]
    Result<void> ensureValid() const { return _core.ensureValid(); }

    [[=welder::mark::exclude]]
    const TableCore& core() const { return _core; }
 
  protected:
    TableCore _core;
  };
}