Evpack.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include "common/Identity.h"
#include "common/Result.h"
#include "common/SchemaVersion.h"
 
#include <array>
#include <cstddef>
#include <cstdint>
#include <span>
#include <memory>
#include <optional>
#include <string>
#include <vector>
 
namespace eve::asset {
 
enum class EvpackChunkKind : std::uint16_t {
    Definition = 1,
    Bulk       = 2,
    Stream     = 3,
    Shader     = 4,
    Dictionary = 5,
    DebugName  = 6,
};
 
enum class EvpackCodec : std::uint16_t {
    None = 0,
    Zstd = 1,
};
 
struct EvpackSignature {
    std::string algorithm;
    std::array<std::uint8_t, 32> keyId{};
    std::array<std::uint8_t, 64> bytes{};
};
 
class EvpackSigner {
public:
    virtual ~EvpackSigner() = default;
    [[nodiscard]] virtual Result<EvpackSignature> sign(
        std::span<const std::uint8_t, 32> digest) const = 0;
};
 
class EvpackSignatureVerifier {
public:
    virtual ~EvpackSignatureVerifier() = default;
    [[nodiscard]] virtual Result<void> verify(
        std::span<const std::uint8_t, 32> digest, const EvpackSignature& signature) const = 0;
};
 
enum class EvpackSignaturePolicy : std::uint8_t {
    AllowUnsignedDevelopment,
    RequireTrustedSignature,
};
 
struct EvpackTrust {
    EvpackSignaturePolicy policy = EvpackSignaturePolicy::AllowUnsignedDevelopment;
    std::shared_ptr<const EvpackSignatureVerifier> verifier;
};
 
struct EvpackVariant {
    std::string              os;
    std::string              arch;
    std::string              graphics;
    std::vector<std::string> textureFamilies;
    std::string              shaderFormat;
    std::string              quality;
    std::vector<std::string> features;
};
 
struct EvpackCapabilities {
    std::string              os;
    std::string              arch;
    std::string              graphics;
    std::vector<std::string> textureFamilies;
    std::vector<std::string> shaderFormats;
    std::vector<std::string> qualities;
    std::vector<std::string> features;
};
 
struct EvpackChunkInput {
    PersistentId                 assetId;
    std::string                  type;
    SchemaVersion               schemaVersion;
    std::uint32_t               variantIndex = 0;
    EvpackChunkKind              kind         = EvpackChunkKind::Definition;
    std::uint32_t               chunkId      = 0;
    EvpackCodec                  codec        = EvpackCodec::None;
    std::uint32_t               alignment    = 1;
    std::vector<PersistentId>    dependencies;
    std::vector<std::uint8_t>    bytes;
};
 
struct EvpackBuild {
    PersistentId                  packageId;
    PersistentId                  buildId;
    std::vector<EvpackVariant>    variants;
    std::vector<EvpackChunkInput> chunks;
    std::shared_ptr<const EvpackSigner> signer;
};
 
struct EvpackLimits {
    std::uint64_t maximumPackageBytes = 16ULL * 1024 * 1024 * 1024;
    std::uint64_t maximumChunkBytes   = 2ULL * 1024 * 1024 * 1024;
    std::uint64_t maximumDecodedBytes = 32ULL * 1024 * 1024 * 1024;
    std::uint64_t maximumMetadataBytes = 256ULL * 1024 * 1024;
    std::uint32_t maximumChunks       = 1000000;
    std::uint32_t maximumVariants     = 256;
    std::uint32_t maximumDependencies = 4096;
    std::uint32_t maximumStringBytes  = 4096;
};
 
struct EvpackChunk {
    PersistentId              assetId;
    std::string               type;
    SchemaVersion             schemaVersion;
    std::uint32_t             variantIndex = 0;
    EvpackChunkKind           kind         = EvpackChunkKind::Definition;
    std::uint32_t             chunkId      = 0;
    EvpackCodec               codec        = EvpackCodec::None;
    std::uint32_t             alignment    = 1;
    std::uint64_t             offset       = 0;
    std::uint64_t             storedSize   = 0;
    std::uint64_t             decodedSize  = 0;
    std::array<std::uint8_t, 32> contentHash{};
    std::vector<PersistentId> dependencies;
};
 
struct EvpackVariantSelection {
    std::uint32_t index = 0;
    bool          usedFallback = false;
};
 
class EVENGINE_API_FOUNDATION Evpack {
public:
    [[nodiscard]] const PersistentId& packageId() const noexcept { return packageId_; }
    [[nodiscard]] const PersistentId& buildId() const noexcept { return buildId_; }
    [[nodiscard]] const std::vector<EvpackVariant>& variants() const noexcept { return variants_; }
    [[nodiscard]] const std::vector<EvpackChunk>& chunks() const noexcept { return chunks_; }
    [[nodiscard]] const std::optional<EvpackSignature>& signature() const noexcept { return signature_; }
    [[nodiscard]] bool hasTrustedSignature() const noexcept { return trustedSignature_; }
 
    [[nodiscard]] Result<std::span<const std::uint8_t>> chunkBytes(std::size_t index) const;
 
    [[nodiscard]] Result<std::vector<std::uint8_t>> decodeChunk(
        std::size_t index, std::uint64_t maximumDecodedBytes) const;
 
private:
    friend EVENGINE_API_FOUNDATION Result<Evpack> parseEvpack(std::span<const std::uint8_t>, const EvpackLimits&,
                                                              const EvpackTrust&);
    friend Result<Evpack> parseEvpackMetadata(std::span<const std::uint8_t>, std::uint64_t,
                                              const EvpackLimits&, const EvpackTrust&);
    PersistentId                  packageId_;
    PersistentId                  buildId_;
    std::vector<EvpackVariant>    variants_;
    std::vector<EvpackChunk>      chunks_;
    std::vector<std::uint8_t>     bytes_;
    std::optional<EvpackSignature> signature_;
    bool                           trustedSignature_ = false;
};
 
[[nodiscard]] EVENGINE_API_FOUNDATION Result<std::vector<std::uint8_t>> buildEvpack(EvpackBuild         build,
                                                                                    const EvpackLimits& limits = {});
 
[[nodiscard]] EVENGINE_API_FOUNDATION Result<Evpack> parseEvpack(std::span<const std::uint8_t> bytes,
                                                                 const EvpackLimits&           limits = {},
                                                                 const EvpackTrust&            trust  = {});
 
[[nodiscard]] Result<Evpack> parseEvpackMetadata(
    std::span<const std::uint8_t> metadataPrefix, std::uint64_t packageSize,
    const EvpackLimits& limits = {}, const EvpackTrust& trust = {});
 
[[nodiscard]] EVENGINE_API_FOUNDATION Result<EvpackVariantSelection> selectEvpackVariant(
    const Evpack& pack, const EvpackCapabilities& capabilities);
 
}  // namespace eve::asset