API Reference#

class StorageModuleImpl : public LogosModuleContext#

Logos Storage Module API.

Wraps a libstorage node and exposes upload, download, and data-management operations. Synchronous methods return immediately; asynchronous methods report completion through the typed events in the Asynchronous-completion events section.

Asynchronous-completion events

Each event delivers a single JSON-encoded string payload, described with the event below.

void storageStop(const std::string &payload)#

Emitted when stop() has finished stopping the node.

{
  "success": bool,
  "message": string
}

void storageConnect(const std::string &payload)#

Emitted when connect() has finished connecting to the peer.

{
  "success": bool,
  "message": string
}

void storageUploadProgress(const std::string &payload)#

Emitted as uploadUrl() or uploadChunk() upload data.

{
  "success":   bool,
  "sessionId": string,
  "bytes":     number,       // present on success
  "total":     number,       // file size in bytes
  "error":     string        // present on failure
}

void storageUploadDone(const std::string &payload)#

Emitted when uploadUrl() finishes.

{
  "success":   bool,
  "sessionId": string,
  "cid":       string,       // present on success
  "error":     string        // present on failure
}

void storageDownloadProgress(const std::string &payload)#

Emitted as downloadToUrl() or downloadChunks() receive data.

{
  "success":   true,
  "sessionId": string,
  "bytes":     number,       // file download (downloadToUrl)
  "total":     number,       // file download; dataset size in bytes
  "chunk":     string        // base64 chunk, stream download (downloadChunks)
}

void storageDownloadDone(const std::string &payload)#

Emitted when downloadToUrl() or downloadChunks() finishes.

{
  "success":   bool,
  "sessionId": string,
  "error":     string        // present on failure
}

void storageDownloadManifestDone(const std::string &payload)#

Emitted when downloadManifest() finishes.

{
  "success": bool,
  "cid":     string,
  "manifest": {              // present on success
    "manifestVersion": number,
    "treeCid":     string,
    "datasetSize": number,
    "blockSize":   number,
    "filename":    string,
    "mimetype":    string
  },
  "error":   string          // present on failure
}

void storageRemoveDone(const std::string &payload)#

Emitted when remove() finishes.

{
  "success": bool,
  "cid":     string,
  "error":   string          // present on failure
}

Public Functions

StdLogosResult loadConfigOrDefault()#

Load the configuration saved by the last successful init().

The configuration is read from ~/.logos_storage/config.json and migrated to this module version using its config-version. Depending on the updates of logos-storage-nim, some options can be removed or replaced with new ones. The data-dir and the Mix configuration are then filled in as init() does.

When the file does not exist, returns a suitable default configuration. This call does not write anything to disk.

Returns StdLogosResult::value as a JSON string.

bool init(const std::string &cfg)#

Create a new storage node instance and configure it.

cfg is a JSON string with the configuration overwriting defaults.

Example of JSON config:

{
    "log-level": "info",
    "log-format": "auto",
    "metrics": false,
    "metrics-address": "127.0.0.1",
    "metrics-port": 8008,
    "data-dir": ".cache/storage",
    "listen-ip": "0.0.0.0",
    "listen-port": 0,
    "nat": "auto",
    "net-privkey": "key",
    "bootstrap-node": [],
    "no-bootstrap-node": false,
    "network": "logos.test",
    "dht-mix-proxy": [],
    "mix-enabled": false,
    "mix-pool": "",
    "mix-pool-json": "",
    "max-peers": 160,
    "num-threads": 0,
    "agent-string": "Logos Storage",
    "repo-kind": "fs",
    "storage-quota": 21474836480,
    "block-ttl": "30d",
    "block-mi": "10m",
    "block-mn": 1000,
    "block-retries": 300,
    "log-file": "/tmp/storage-log-624036264.log",
    "nat-schedule-interval": "2m",
    "nat-num-peers-to-ask": 3,
    "nat-max-queue-size": 3,
    "nat-min-confidence": 0.6,
    "nat-observed-addr-min-count": 1,
    "nat-max-relays": 2,
    "nat-port-mapping-discover-timeout": 500,
    "nat-port-mapping-timeout": 500,
    "nat-port-mapping-recheck-period": 300000
}

cfg is taken as a configuration suitable for this version of the module - older configuration strings are not migrated automatically (see loadConfigOrDefault). The data-dir is set if it is not provided. With mix-enabled true and no custom bootstrap settings, the Mix configuration of the network is filled in.

Do not call init() more than once per instance.

On success, cfg is saved in ~/.logos_storage/config.json, where loadConfigOrDefault() reads it back. A cfg without config-version is saved with the current version.

Returns true on success. The method is synchronous.

bool start()#

Start the storage node.

If the node is already running, the call succeeds and emits storageStart immediately. If the node is starting or stopping, the call fails.

storageStart is emitted once the node is up.

Returns true if the start command was accepted by libstorage. Actual completion is signalled asynchronously via the storageStart event.

The method is asynchronous.

StdLogosResult stop()#

Stop the storage node.

If the node is starting or stopping, the call fails.

The node can be started and stopped multiple times. Returns a StdLogosResult indicating whether the stop command was sent; actual completion is signalled via the storageStop event.

The method is asynchronous.

StdLogosResult destroy()#

Destroy the storage context and free all resources.

Internally calls storage_close then storage_destroy. The node should be stopped before calling destroy(). Not stopping first can lead to undefined behaviour (e.g. data loss or crashes).

Fails while the node is starting or stopping.

Returns StdLogosResult::success = true on success. The method is synchronous.

bool isRunning()#

Check whether the storage node is running.

Returns true after a successful start, and false after a successful stop or a destroy().

The method is synchronous.

StdLogosResult libstorageVersion()#

Get the libstorage version string.

Named for what it returns: this is the version of the underlying libstorage (Nim) library, NOT of this module. version() cannot be used for it — that name is reserved for module identity and must be version() -> tstr, which the generator injects from metadata.json.

Does not require the node to be started.