EntropyEngine::Core::IO::PackageBackend

EntropyEngine::Core::IO::PackageBackend

Read-only VFS backend for EntropyPackage files. More…

#include <PackageBackend.h>

Inherits from EntropyEngine::Core::IO::IFileSystemBackend, EntropyEngine::Core::EntropyObject

Public Functions

	Name
	~PackageBackend() override
virtual FileOperationHandle	writeLine(const std::string & path, size_t lineNumber, std::string_view line) override Replaces a single line by index (0-based).
virtual FileOperationHandle	writeFile(const std::string & path, std::span< const uint8_t > data, WriteOptions options ={}) override Writes file contents.
virtual FileOperationHandle	removeDirectory(const std::string & path) override Removes a directory at the given path.
const PackageReader &	reader() const Get the underlying package reader.
virtual FileOperationHandle	readLine(const std::string & path, size_t lineNumber) override Reads a single line by index (0-based).
virtual FileOperationHandle	readFile(const std::string & path, ReadOptions options ={}) override Reads file contents.
virtual std::unique_ptr< FileStream >	openStream(const std::string & path, StreamOptions options ={}) override Opens a stream for the given path.
virtual FileOperationHandle	listDirectory(const std::string & path, ListDirectoryOptions options ={}) override Lists entries in the given directory.
bool	isEncrypted() const Check if the package is encrypted.
virtual FileOperationHandle	getMetadata(const std::string & path) override Retrieves metadata for a file.
virtual BackendCapabilities	getCapabilities() const override
virtual std::string	getBackendType() const override
virtual bool	exists(const std::string & path) override Checks existence of a path.
virtual FileOperationHandle	deleteFile(const std::string & path) override Deletes a file.
virtual FileOperationHandle	createFile(const std::string & path) override Creates an empty file.
virtual FileOperationHandle	createDirectory(const std::string & path) override Creates a directory at the given path.
PackageResult< std::shared_ptr< PackageBackend > >	create(const std::filesystem::path & path) Create backend for an unencrypted package.
PackageResult< std::shared_ptr< PackageBackend > >	create(const std::filesystem::path & path, std::span< const uint8_t, 32 > symmetricKey) Create backend for an encrypted package.

Additional inherited members

Public Classes inherited from EntropyEngine::Core::IO::IFileSystemBackend

	Name
struct	AcquireWriteScopeResult Backend-specific primitive for write serialization.
struct	AcquireScopeOptions

Public Functions inherited from EntropyEngine::Core::IO::IFileSystemBackend

	Name
	~IFileSystemBackend() override =default
void	setVirtualFileSystem(VirtualFileSystem * vfs)
virtual std::string	normalizeKey(const std::string & path) const
virtual FileOperationHandle	moveFile(const std::string & src, const std::string & dst, bool overwriteExisting =false)
virtual FileOperationHandle	getMetadataBatch(const BatchMetadataOptions & options)
virtual FileOperationHandle	copyFile(const std::string & src, const std::string & dst, const CopyOptions & options ={})
virtual const char *	className() const override Runtime class name for diagnostics and reflection.
virtual AcquireWriteScopeResult	acquireWriteScope(const std::string & path, AcquireScopeOptions options ={})

Protected Attributes inherited from EntropyEngine::Core::IO::IFileSystemBackend

	Name
VirtualFileSystem *	_vfs

Protected Classes inherited from EntropyEngine::Core::EntropyObject

	Name
struct	HandleCore Optional handle identity stamped by an owner/registry.

Public Functions inherited from EntropyEngine::Core::EntropyObject

	Name
virtual	~EntropyObject() =default
virtual const TypeSystem::TypeInfo *	typeInfo() const Optional richer type information; may be null.
bool	tryRetain() const Attempts to retain only if the object is still alive.
virtual std::string	toString() const Human-readable short string (class@ptr by default).
void	retain() const Increments the reference count.
void	release() const Decrements the reference count and deletes when it reaches zero.
uint32_t	refCount() const Current reference count (approximate under contention).
EntropyObject &	operator=(const EntropyObject & ) =delete
EntropyObject &	operator=(EntropyObject && ) =delete
bool	hasHandle() const
template <class OwnerT > OwnerT *	handleOwnerAs() const Returns the stamped owner pointer cast to the requested type.
const void *	handleOwner() const
uint32_t	handleIndex() const
uint64_t	handleId() const
uint32_t	handleGeneration() const
WeakControlBlock *	getWeakControlBlock() const Lazily retrieves or creates the weak control block.
virtual std::string	description() const Long-form description; defaults to toString().
virtual std::string	debugString() const Debug-oriented string including refcount and handle when present.
virtual const char *	className() const Runtime class name for diagnostics and reflection.
virtual uint64_t	classHash() const Stable type hash for cross-language identification.
	EntropyObject() =default
	EntropyObject(EntropyObject && ) =delete
	EntropyObject(const EntropyObject & ) =delete

Protected Functions inherited from EntropyEngine::Core::EntropyObject

	Name
void	_setHandleIdentity(void * owner, uint32_t index, uint32_t generation)
void	_clearHandleIdentity()

Protected Attributes inherited from EntropyEngine::Core::EntropyObject

	Name
std::atomic< WeakControlBlock * >	_weakBlock Lazily allocated control block for weak refs.
std::atomic< uint32_t >	_refCount Thread-safe retain/release counter.
struct EntropyEngine::Core::EntropyObject::HandleCore	_handle

Friends inherited from EntropyEngine::Core::EntropyObject

	Name
struct	HandleAccess

Detailed Description

class EntropyEngine::Core::IO::PackageBackend;

Read-only VFS backend for EntropyPackage files.

Mounts a .epak package as a virtual filesystem. Supports reading files, listing directories, and querying metadata. All write operations are rejected.

Usage:

auto result = PackageBackend::create("content.epak");
if (result.failed()) {
    // Handle error
}
auto backend = std::move(result.value);

// Use via VFS mount
vfs.mount("/content", backend);

// Or directly
auto op = backend->readFile("meshes/character.mesh");
op.wait();
auto data = op.contentsBytes();

Public Functions Documentation

function ~PackageBackend

~PackageBackend() override

function writeLine

virtual FileOperationHandle writeLine(
    const std::string & path,
    size_t lineNumber,
    std::string_view line
) override

Replaces a single line by index (0-based).

Parameters:

• path Target file
• lineNumber Line index
• line New content without newline

Return: Handle representing the write

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::writeLine

function writeFile

virtual FileOperationHandle writeFile(
    const std::string & path,
    std::span< const uint8_t > data,
    WriteOptions options ={}
) override

Writes file contents.

Parameters:

• path Target path
• data Bytes to write
• options WriteOptions (append/offset/truncate, parent dirs, final newline, fsync)

Return: Handle representing the async write

Note:

• Symlink behavior: Writes follow symlinks and modify the target file.
• Dangling symlinks cause FileError::FileNotFound.
• Special files (FIFO, device, socket) are rejected with FileError::InvalidPath on Unix.
• Set options.fsync=true for durability guarantee (Unix/POSIX only; forces data to disk).

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::writeFile

function removeDirectory

virtual FileOperationHandle removeDirectory(
    const std::string & path
) override

Removes a directory at the given path.

Parameters:

• path Directory to remove

Return: A FileOperationHandle; status() will be Pending for default impl

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::removeDirectory

Backend-specific semantics:

• LocalFileSystemBackend: Removes directory and all contents recursively (like rm -rf). Succeeds even if directory doesn’t exist (idempotent).
• S3Backend (future): Deletes all objects with this prefix. Warning: Potentially expensive for deep hierarchies. May require pagination and multiple requests.
• AzureBlobBackend (future): Similar to S3. Deletes all blobs matching prefix. With HNS, can delete directory object itself if empty.
• WebDAVBackend (future): Issues HTTP DELETE on collection. May fail if collection is non-empty depending on server implementation (RFC 4918 allows but doesn’t require recursive delete).
• HTTPBackend (non-WebDAV): Not supported. Returns empty handle.

function reader

const PackageReader & reader() const

Get the underlying package reader.

function readLine

virtual FileOperationHandle readLine(
    const std::string & path,
    size_t lineNumber
) override

Reads a single line by index (0-based).

Parameters:

• path Target file
• lineNumber Line index

Return: Handle with contentsBytes/Text containing the line

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::readLine

function readFile

virtual FileOperationHandle readFile(
    const std::string & path,
    ReadOptions options ={}
) override

Reads file contents.

Parameters:

• path Path to read
• options ReadOptions (offset/length, binary)

Return: Handle whose contents are available after wait()

Note:

• Symlink behavior: File operations follow symlinks by default on Unix systems.
• Dangling symlinks cause FileError::FileNotFound.
• Use getMetadata() with FileMetadata::isSymlink to detect symlinks before operations.
• Special files (FIFO, device, socket) are rejected with FileError::InvalidPath on Unix.

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::readFile

function openStream

virtual std::unique_ptr< FileStream > openStream(
    const std::string & path,
    StreamOptions options ={}
) override

Opens a stream for the given path.

Parameters:

• path Target path
• options StreamOptions (mode, buffering)

Return: Unique pointer to FileStream, or null on failure

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::openStream

function listDirectory

virtual FileOperationHandle listDirectory(
    const std::string & path,
    ListDirectoryOptions options ={}
) override

Lists entries in the given directory.

Parameters:

• path Directory to list
• options Listing options (recursion, filters, sorting, pagination)

Return: A FileOperationHandle; status() will be Pending for default impl

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::listDirectory

Backend-specific semantics:

• LocalFileSystemBackend: Native filesystem iteration using std::filesystem::directory_iterator. Supports recursion, glob patterns, hidden file filtering, sorting, and pagination.
• S3Backend (future): Uses ListObjectsV2 with delimiter=”/” to simulate directory listing. Recursion requires multiple requests. Pagination is native (continuation tokens).
• AzureBlobBackend (future): Uses List Blobs API with delimiter=”/”. Similar to S3. With HNS enabled, can use true hierarchical listing APIs.
• WebDAVBackend (future): Issues HTTP PROPFIND request with Depth: 1 header for non-recursive, Depth: infinity for recursive. Parses XML response (RFC 4918 multistatus).
• HTTPBackend (non-WebDAV): Not supported. Returns empty handle.

function isEncrypted

bool isEncrypted() const

Check if the package is encrypted.

function getMetadata

virtual FileOperationHandle getMetadata(
    const std::string & path
) override

Retrieves metadata for a file.

Parameters:

• path Target path

Return: Handle whose metadata() is populated after wait()

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::getMetadata

function getCapabilities

virtual BackendCapabilities getCapabilities() const override

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::getCapabilities

function getBackendType

virtual std::string getBackendType() const override

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::getBackendType

function exists

virtual bool exists(
    const std::string & path
) override

Checks existence of a path.

Parameters:

• path Target path

Return: true if path exists, false otherwise

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::exists

function deleteFile

virtual FileOperationHandle deleteFile(
    const std::string & path
) override

Deletes a file.

Parameters:

• path Target path

Return: Handle representing the delete operation

Note: Symlink behavior: Deletes the symlink itself, not the target.

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::deleteFile

function createFile

virtual FileOperationHandle createFile(
    const std::string & path
) override

Creates an empty file.

Parameters:

• path Target path

Return: Handle representing the create operation

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::createFile

function createDirectory

virtual FileOperationHandle createDirectory(
    const std::string & path
) override

Creates a directory at the given path.

Parameters:

• path Directory to create

Return: A FileOperationHandle; status() will be Pending for default impl

Reimplements: EntropyEngine::Core::IO::IFileSystemBackend::createDirectory

Backend-specific semantics:

• LocalFileSystemBackend: Creates all parent directories (like mkdir -p). Always succeeds if directory already exists.
• S3Backend (future): Creates a 0-byte marker object with ”/” suffix for compatibility with tools expecting directory markers. This is optional; S3 has no native directory concept.
• AzureBlobBackend (future): With hierarchical namespace (HNS) enabled, creates a true directory object. Without HNS, creates a 0-byte blob with ”/” suffix (like S3).
• WebDAVBackend (future): Issues HTTP MKCOL request to create collection (directory).
• HTTPBackend (non-WebDAV): Not supported. Returns empty handle.

function create

static PackageResult< std::shared_ptr< PackageBackend > > create(
    const std::filesystem::path & path
)

Create backend for an unencrypted package.

Parameters:

• path Path to .epak file

Return: Result containing backend or error

function create

static PackageResult< std::shared_ptr< PackageBackend > > create(
    const std::filesystem::path & path,
    std::span< const uint8_t, 32 > symmetricKey
)

Create backend for an encrypted package.

Parameters:

• path Path to .epak file
• symmetricKey 32-byte AES-256 key

Return: Result containing backend or error

---

Updated on 2026-01-26 at 17:14:35 -0500