storage.h File Reference

UDIF file-based storage backend for MCEL integration. More...

#include "udifcommon.h"
#include "udif.h"
#include "fileutils.h"

Go to the source code of this file.

Data Structures
struct	udif_file_handle
	Cached file handle with metadata. More...
struct	udif_storage_context
	File-based storage context for MCEL integration. More...

Macros
#define	UDIF_STORAGE_MAX_PATH   512U
	Maximum file path length.
#define	UDIF_STORAGE_MAX_HANDLES   16U
	Maximum number of cached file handles.

Typedefs
typedef enum udif_ledger_type	udif_ledger_type
typedef struct udif_file_handle	udif_file_handle
typedef struct udif_storage_context	udif_storage_context

Enumerations
enum	udif_ledger_type { UDIF_LEDGER_MEMBERSHIP = 0U , UDIF_LEDGER_TRANSACTION = 1U , UDIF_LEDGER_REGISTRY = 2U }
	Ledger namespace identifiers. More...

Functions
UDIF_EXPORT_API udif_errors	udif_storage_initialize (udif_storage_context *ctx, const char *basepath)
	Initialize storage context.
UDIF_EXPORT_API void	udif_storage_set_ledger (udif_storage_context *ctx, udif_ledger_type ledgertype)
	Set active ledger namespace.
UDIF_EXPORT_API void	udif_storage_get_callbacks (udif_storage_context *ctx, void *callbacks)
	Get MCEL store callbacks for this context.
UDIF_EXPORT_API void	udif_storage_dispose (udif_storage_context *ctx)
	Dispose storage context.
UDIF_EXPORT_API bool	udif_storage_write (void *context, const uint8_t *loc, size_t loclen, const uint8_t *data, size_t datalen)
	Write complete object to storage.
UDIF_EXPORT_API bool	udif_storage_read (void *context, const uint8_t *loc, size_t loclen, uint8_t *data, size_t datalen, size_t *outread)
	Read complete object from storage.
UDIF_EXPORT_API bool	udif_storage_append (void *context, const uint8_t *loc, size_t loclen, const uint8_t *data, size_t datalen, uint64_t *outpos)
	Append data to append-only object.
UDIF_EXPORT_API bool	udif_storage_size (void *context, const uint8_t *loc, size_t loclen, uint64_t *outlen)
	Get object size.
UDIF_EXPORT_API bool	udif_storage_flush (void *context, const uint8_t *loc, size_t loclen)
	Flush buffered data.
bool	udif_storage_resolve_path (const udif_storage_context *ctx, const uint8_t *loc, size_t loclen, char *outpath, size_t outpathlen)
	Resolve logical location to file path.
bool	udif_storage_mkdir_recursive (const char *path)
	Create directory recursively.
bool	udif_storage_get_handle (udif_storage_context *ctx, const char *path, qsc_fileutils_mode mode, FILE **outfp)
	Get or open cached file handle.
void	udif_storage_evict_handle (udif_storage_context *ctx, const char *path)
	Close and evict a cached handle.
void	udif_storage_close_all_handles (udif_storage_context *ctx)
	Close all cached handles.

Detailed Description

UDIF file-based storage backend for MCEL integration.

This module implements the storage backend required by MCEL's mcel_store_callbacks interface. It provides file-based persistence for ledger records, blocks, checkpoints, and indexes.

The storage backend manages three separate ledger namespaces:

• Membership ledger (certificates, capabilities, treaties)
• Transaction ledger (object operations, queries)
• Registry ledger (object ownership records)

Storage Layout: <base_path>/ membership/ mcel/records - Append-only membership events mcel/blocks - Sealed membership blocks mcel/checkpoints - Signed membership checkpoints mcel/head - Current checkpoint head transaction/ mcel/records - Append-only transaction events mcel/blocks - Sealed transaction blocks mcel/checkpoints - Signed transaction checkpoints mcel/head - Current checkpoint head registry/ mcel/records - Append-only registry events mcel/blocks - Sealed registry blocks mcel/checkpoints - Signed registry checkpoints mcel/head - Current checkpoint head

Enumeration Type Documentation

udif_ledger_type

enum udif_ledger_type

Ledger namespace identifiers.

Enumerator
UDIF_LEDGER_MEMBERSHIP	Membership ledger namespace
UDIF_LEDGER_TRANSACTION	Transaction ledger namespace
UDIF_LEDGER_REGISTRY	Registry ledger namespace

Function Documentation

udif_storage_append()

UDIF_EXPORT_API bool udif_storage_append	(	void *	context,
		const uint8_t *	loc,
		size_t	loclen,
		const uint8_t *	data,
		size_t	datalen,
		uint64_t *	outpos )

Append data to append-only object.

Appends data to the end of an append-only file and returns the position. Creates the file if it doesn't exist.

Parameters

context	The storage context
loc	[const] The logical location identifier
loclen	The location identifier length
data	[const] The data to append
datalen	The data length
outpos	Pointer to receive append position (can be NULL)

Returns

Returns true on success

udif_storage_close_all_handles()

void udif_storage_close_all_handles

(

udif_storage_context *

ctx

)

Close all cached handles.

Closes all cached file handles (used during dispose).

Parameters

ctx	The storage context

udif_storage_dispose()

UDIF_EXPORT_API void udif_storage_dispose

(

udif_storage_context *

ctx

)

Dispose storage context.

Closes all cached file handles and frees resources.

Parameters

ctx	The storage context to dispose

udif_storage_evict_handle()

void udif_storage_evict_handle	(	udif_storage_context *	ctx,
		const char *	path )

Close and evict a cached handle.

Closes a file handle and removes it from the cache.

Parameters

ctx	The storage context
path	[const] The file path to evict

udif_storage_flush()

UDIF_EXPORT_API bool udif_storage_flush	(	void *	context,
		const uint8_t *	loc,
		size_t	loclen )

Flush buffered data.

Forces all buffered data for a logical location to be written to disk.

Parameters

context	The storage context
loc	[const] The logical location identifier
loclen	The location identifier length

Returns

Returns true on success

udif_storage_get_callbacks()

UDIF_EXPORT_API void udif_storage_get_callbacks	(	udif_storage_context *	ctx,
		void *	callbacks )

Get MCEL store callbacks for this context.

Returns a populated mcel_store_callbacks structure that can be passed to MCEL initialization functions.

Parameters

ctx	The storage context
callbacks	The output callbacks structure

udif_storage_get_handle()

bool udif_storage_get_handle	(	udif_storage_context *	ctx,
		const char *	path,
		qsc_fileutils_mode	mode,
		FILE **	outfp )

Get or open cached file handle.

Returns a cached file handle for a path, opening it if necessary. Uses LRU eviction if cache is full.

Parameters

ctx	The storage context
path	[const] The file path
mode	[const] The open mode string
outfp	Pointer to receive FILE*

Returns

Returns true on success

udif_storage_initialize()

UDIF_EXPORT_API udif_errors udif_storage_initialize	(	udif_storage_context *	ctx,
		const char *	basepath )

Initialize storage context.

Creates the base directory structure and initializes the storage context. This must be called before any storage operations.

Parameters

ctx	The storage context to initialize
basepath	[const] The base directory path (e.g., "/var/udif/ledgers/entity_serial")

Returns

Returns udif_error_none on success

udif_storage_mkdir_recursive()

bool udif_storage_mkdir_recursive

(

const char *

path

)

Create directory recursively.

Creates all parent directories needed for a path.

Parameters

path	[const] The directory path

Returns

Returns true on success

udif_storage_read()

UDIF_EXPORT_API bool udif_storage_read	(	void *	context,
		const uint8_t *	loc,
		size_t	loclen,
		uint8_t *	data,
		size_t	datalen,
		size_t *	outread )

Read complete object from storage.

Reads the entire content at a logical location into a buffer.

Parameters

context	The storage context
loc	[const] The logical location identifier
loclen	The location identifier length
data	The output buffer
datalen	The output buffer length
outread	Pointer to receive bytes read

Returns

Returns true on success

udif_storage_resolve_path()

bool udif_storage_resolve_path	(	const udif_storage_context *	ctx,
		const uint8_t *	loc,
		size_t	loclen,
		char *	outpath,
		size_t	outpathlen )

Resolve logical location to file path.

Converts an MCEL logical location to a full file system path based on the current ledger namespace.

Parameters

ctx	[const] The storage context
loc	[const] The logical location
loclen	The location length
outpath	The output path buffer
outpathlen	The output path buffer length

Returns

Returns true on success

udif_storage_set_ledger()

UDIF_EXPORT_API void udif_storage_set_ledger	(	udif_storage_context *	ctx,
		udif_ledger_type	ledgertype )

Set active ledger namespace.

Switches the storage context to operate on a specific ledger namespace. All subsequent storage operations will use this namespace until changed.

Parameters

ctx	The storage context
ledgertype	The ledger namespace to activate

udif_storage_size()

UDIF_EXPORT_API bool udif_storage_size	(	void *	context,
		const uint8_t *	loc,
		size_t	loclen,
		uint64_t *	outlen )

Get object size.

Returns the size in bytes of an object at a logical location.

Parameters

context	The storage context
loc	[const] The logical location identifier
loclen	The location identifier length
outlen	Pointer to receive size in bytes

Returns

Returns true on success

udif_storage_write()

UDIF_EXPORT_API bool udif_storage_write	(	void *	context,
		const uint8_t *	loc,
		size_t	loclen,
		const uint8_t *	data,
		size_t	datalen )

Write complete object to storage.

Overwrites the entire content at a logical location. Creates parent directories if necessary.

Parameters

context	The storage context
loc	[const] The logical location identifier
loclen	The location identifier length
data	[const] The data to write
datalen	The data length

Returns

Returns true on success