Logos Storage exposes a C binding that serves as a stable contract, making it straightforward to integrate Logos Storage into other languages such as Go.

The implementation was inspired by nim-library-template
and by the nwaku library.

The source code contains detailed comments to explain the threading and callback flow.
The diagram below summarizes the lifecycle: context creation, request execution, and shutdown.

sequenceDiagram
    autonumber
    actor App as App/User
    participant Go as Go Wrapper
    participant C as C API (libstorage.h)
    participant Ctx as StorageContext
    participant Thr as Worker Thread
    participant Eng as CodexServer

    App->>Go: Start
    Go->>C: storage_start_node
    C->>Ctx: enqueue request
    C->>Ctx: fire signal
    Ctx->>Thr: wake worker
    Thr->>Ctx: dequeue request
    Thr-->>Ctx: ACK
    Ctx-->>C: forward ACK
    C-->>Go: RET OK 
    Go->>App: Unblock
    Thr->>Eng: execute (async)
    Eng-->>Thr: result ready
    Thr-->>Ctx: callback
    Ctx-->>C: forward callback
    C-->>Go: forward callback
    Go-->>App: done

C API

C-exported interface for the Logos Storage shared library.

This API provides a C-compatible interface to the internal Nim implementation of Logos Storage.

Unless explicitly stated otherwise, all functions are asynchronous and execute their work on a separate thread, returning results via the provided callback. The int return value is the synchronous status of dispatch:

RET_OK: job dispatched to the worker thread
RET_ERR: immediate failure
RET_MISSING_CALLBACK: callback is missing

Some functions may emit progress updates via the callback using RET_PROGRESS, and finally complete with RET_OK or RET_ERR.
For upload/download streaming, msg contains a chunk of data and len the chunk length.

Types

`StorageCallback`

typedef void (*StorageCallback)(int callerRet, const char *msg, size_t len, void *userData);

Return codes

#define RET_OK 0
#define RET_ERR 1
#define RET_MISSING_CALLBACK 2
#define RET_PROGRESS 3

Context lifecycle

`storage_new`

Create a new instance of a Logos Storage node.

void *storage_new(
    const char *configJson,
    StorageCallback callback,
    void *userData
);

configJson: JSON string with configuration overwriting defaults
Returns an opaque context pointer used for subsequent calls

Typical usage:

storage_new(...)
storage_start(...)
storage_stop(...)
storage_destroy(...)

`storage_start`

Start the Logos Storage node (can be started/stopped multiple times).

int storage_start(void *ctx, StorageCallback callback, void *userData);

`storage_stop`

Stop the Logos Storage node (can be started/stopped multiple times).

int storage_stop(void *ctx, StorageCallback callback, void *userData);

`storage_close`

Close the node and release resources before destruction.

int storage_close(void *ctx, StorageCallback callback, void *userData);

`storage_destroy`

Destroy the node instance and free associated resources. Node must be stopped and closed.

int storage_destroy(void *ctx, StorageCallback callback, void *userData);

Version

`storage_version`

Get the Logos Storage version string. Does not require the node to be started and does not involve a thread call.

int storage_version(void *ctx, StorageCallback callback, void *userData);

`storage_revision`

Get the Logos Storage contracts revision. Does not require the node to be started and does not involve a thread call.

int storage_revision(void *ctx, StorageCallback callback, void *userData);

`storage_repo`

Get the repo (data-dir) used by the node.

int storage_repo(void *ctx, StorageCallback callback, void *userData);

Debug

`storage_debug`

Retrieve debug information (JSON).

int storage_debug(void *ctx, StorageCallback callback, void *userData);

`storage_spr`

Get the node's Signed Peer Record (SPR).

int storage_spr(void *ctx, StorageCallback callback, void *userData);

`storage_peer_id`

Get the node's peer ID (libp2p Peer Identity).

int storage_peer_id(void *ctx, StorageCallback callback, void *userData);

`storage_peer_debug`

Request debug information for a given peer ID. Only available if compiled with storage_enable_api_debug_peers.

int storage_peer_debug(void *ctx, const char *peerId, StorageCallback callback, void *userData);

Logging

`storage_log_level`

Set the log level at run time. logLevel can be: TRACE, DEBUG, INFO, NOTICE, WARN, ERROR, FATAL.

int storage_log_level(
    void *ctx,
    const char *logLevel,
    StorageCallback callback,
    void *userData
);

Networking

`storage_connect`

Connect to a peer by using peerAddresses if provided, otherwise use peerId.

Note that the peerId has to be advertised in the DHT for this to work.

int storage_connect(
    void *ctx,
    const char *peerId,
    const char **peerAddresses,
    size_t peerAddressesSize,
    StorageCallback callback,
    void *userData
);

Upload

`storage_upload_init`

Initialize an upload session for a file.

filepath: absolute path for file upload; for chunk uploads it's the file name. The metadata filename and mime type are derived from this value.
chunkSize: chunk size for upload (default: 1024 * 64 bytes)
Callback returns the sessionId

int storage_upload_init(
    void *ctx,
    const char *filepath,
    size_t chunkSize,
    StorageCallback callback,
    void *userData
);

`storage_upload_chunk`

Upload a chunk for the given sessionId.

int storage_upload_chunk(
    void *ctx,
    const char *sessionId,
    const uint8_t *chunk,
    size_t len,
    StorageCallback callback,
    void *userData
);

`storage_upload_finalize`

Finalize an upload session identified by sessionId. Callback returns the cid of the uploaded content.

int storage_upload_finalize(
    void *ctx,
    const char *sessionId,
    StorageCallback callback,
    void *userData
);

`storage_upload_cancel`

Cancel an ongoing upload session.

int storage_upload_cancel(
    void *ctx,
    const char *sessionId,
    StorageCallback callback,
    void *userData
);

`storage_upload_file`

Upload the file defined as filepath in the init method.

Callback may be called with RET_PROGRESS during upload (depending on chunk size constraints)
Callback returns the cid of the uploaded content

int storage_upload_file(
    void *ctx,
    const char *sessionId,
    StorageCallback callback,
    void *userData
);

Download API

`storage_download_init`

Initialize a download for cid.

chunkSize: chunk size for download (default: 1024 * 64 bytes)
local: attempt local store retrieval only

int storage_download_init(
    void *ctx,
    const char *cid,
    size_t chunkSize,
    bool local,
    StorageCallback callback,
    void *userData
);

`storage_download_stream`

Perform a streaming download for cid. Init must have been called prior.

If filepath is provided, content is written to that file.
Callback may be called with RET_PROGRESS updates during download.
local indicates whether to attempt local store retrieval only.

int storage_download_stream(
    void *ctx,
    const char *cid,
    size_t chunkSize,
    bool local,
    const char *filepath,
    StorageCallback callback,
    void *userData
);

`storage_download_chunk`

Download a chunk for the given cid. Init must have been called prior. Chunk returned via callback using RET_PROGRESS.

int storage_download_chunk(
    void *ctx,
    const char *cid,
    StorageCallback callback,
    void *userData
);

`storage_download_cancel`

Cancel an ongoing download for cid.

int storage_download_cancel(
    void *ctx,
    const char *cid,
    StorageCallback callback,
    void *userData
);

`storage_download_manifest`

Retrieve the manifest for the given cid (JSON).

int storage_download_manifest(
    void *ctx,
    const char *cid,
    StorageCallback callback,
    void *userData
);

Storage operations

`storage_list`

Retrieve the list of manifests stored in the node.

int storage_list(void *ctx, StorageCallback callback, void *userData);

`storage_space`

Retrieve storage space information (JSON).

int storage_space(void *ctx, StorageCallback callback, void *userData);

`storage_delete`

Delete the content identified by cid.

int storage_delete(void *ctx, const char *cid, StorageCallback callback, void *userData);

`storage_fetch`

Fetch content identified by cid from the network into local store in background. The callback will not receive progress updates.

int storage_fetch(void *ctx, const char *cid, StorageCallback callback, void *userData);

`storage_exists`

Check if content identified by cid exists in local store.

int storage_exists(void *ctx, const char *cid, StorageCallback callback, void *userData);

`storage_set_event_callback`

Not used currently. Reserved for future use to set an event callback.

void storage_set_event_callback(void *ctx, StorageCallback callback, void *userData);

Go wrapper

A Go wrapper is available here.

Rust Wrapper

A Rust wrapper is available here.