Struct VeilidAPI 

pub struct VeilidAPI { /* private fields */ }

The primary developer entrypoint into veilid-core functionality.

From VeilidAPI one can access various components:

• VeilidConfig - The Veilid configuration specified at startup time.
• Crypto - The available set of cryptosystems provided by Veilid.
• TableStore - The Veilid table-based encrypted persistent key-value store.
• ProtectedStore - The Veilid abstract of the device’s low-level ‘protected secret storage’.
• VeilidState - The current state of the Veilid node this API accesses.
• RoutingContext - Communication methods between Veilid nodes and private routes.
• Attach and detach from the network.
• Create and import private routes.
• Reply to AppCall RPCs.

Implementations

impl VeilidAPI

pub async fn shutdown(self)

Shut down Veilid and terminate the API.

Blocks until the core context has finished shutting down. Idempotent: a second call after the context is already taken is a no-op.

pub fn is_shutdown(&self) -> bool

Check to see if Veilid is already shut down.

pub fn config(&self) -> VeilidAPIResult<Arc<VeilidConfig>>

Access the configuration that Veilid was initialized with.

Errors with VeilidAPIError::NotInitialized if the API has been shut down.

pub fn crypto(&self) -> VeilidAPIResult<VeilidComponentGuard<'_, Crypto>>

Get the cryptosystem component.

Errors with VeilidAPIError::NotInitialized if the API has been shut down.

pub fn table_store( &self, ) -> VeilidAPIResult<VeilidComponentGuard<'_, TableStore>>

Get the TableStore component.

Errors with VeilidAPIError::NotInitialized if the API has been shut down.

pub fn protected_store( &self, ) -> VeilidAPIResult<VeilidComponentGuard<'_, ProtectedStore>>

Get the ProtectedStore component.

Errors with VeilidAPIError::NotInitialized if the API has been shut down.

pub async fn get_state(&self) -> VeilidAPIResult<VeilidState>

Get a full copy of the current state of Veilid.

Errors with VeilidAPIError::NotInitialized if the API has been shut down.

pub async fn attach(&self) -> VeilidAPIResult<()>

Connect to the network.

Sets the attachment to maintain peers; the network connect proceeds in the background tick loop. Returns an error if already attached.

Errors with VeilidAPIError::Generic if already attached, or VeilidAPIError::NotInitialized if the API has been shut down.

pub async fn detach(&self) -> VeilidAPIResult<()>

Disconnect from the network.

Clears the attachment’s maintain-peers flag; the network teardown proceeds in the background tick loop. Returns an error if already detached.

Errors with VeilidAPIError::Generic if already detached, or VeilidAPIError::NotInitialized if the API has been shut down.

pub fn routing_context(&self) -> VeilidAPIResult<RoutingContext>

Get a new RoutingContext object to use to send messages over the Veilid network with default safety, sequencing, and stability parameters.

Errors with VeilidAPIError::NotInitialized if the API has been shut down.

pub async fn get_dht_record_key( &self, schema: DHTSchema, owner_key: PublicKey, encryption_key: Option<SharedSecret>, ) -> VeilidAPIResult<RecordKey>

Deterministicly builds the record key for a given schema and owner public key. The crypto kind of the record key will be that of the owner public key

Local crypto computation only; despite being async it makes no network round-trip.

Errors with VeilidAPIError::InvalidArgument if schema is malformed, VeilidAPIError::Generic if owner_key or encryption_key names an unsupported crypto kind, or VeilidAPIError::NotInitialized if the API has been shut down.

pub fn generate_member_id( &self, writer_key: &PublicKey, ) -> VeilidAPIResult<MemberId>

Create a new MemberId for use with in creating DHTSchemas.

Errors with VeilidAPIError::Generic if writer_key names an unsupported crypto kind, or VeilidAPIError::NotInitialized if the API has been shut down.

pub async fn transact_dht_records( &self, record_keys: Vec<RecordKey>, options: Option<TransactDHTRecordsOptions>, ) -> VeilidAPIResult<DHTTransaction>

Start a transaction on a set of DHT records Record keys must have been opened via a routing context already when passed to this function The maximum number of records per transaction is currently 32. Options can be specified that supply a default signing keypair for records that are not opened for writing

Blocks on the network to begin the transaction across the record nodes (online-only). The returned DHTTransaction holds a network-side resource the caller must release by calling DHTTransaction::commit or DHTTransaction::rollback; dropping it without doing either logs a warning and tears the transaction down in the background.

Errors with VeilidAPIError::InvalidArgument if a record is not open or more than 32 records are passed, VeilidAPIError::MissingArgument if record_keys is empty or has duplicates, VeilidAPIError::Generic if a record key is malformed or its encryption key does not match the opened record, VeilidAPIError::TryAgain if the DHT is offline, the records are contended, or begin consensus was not reached (retry), VeilidAPIError::NotInitialized if the API has been shut down. Network failures surface as VeilidAPIError::Timeout or VeilidAPIError::NoConnection.

pub async fn new_private_route(&self) -> VeilidAPIResult<RouteBlob>

Allocate a new private route set with default cryptography and network options. Default settings are for Stability::Reliable and Sequencing::PreferOrdered. Returns a route id and a publishable ‘blob’ with the route encrypted with each crypto kind. Those nodes importing the blob will have their choice of which crypto kind to use.

Returns a route id and ‘blob’ that can be published over some means (DHT or otherwise) to be imported by another Veilid node.

Blocks on the network to allocate and test the route. The returned route id holds an allocated route the caller must free with VeilidAPI::release_private_route.

Errors with VeilidAPIError::TryAgain if there is no valid PublicInternet network class yet, not enough nodes are known to build the route, or the route failed its reachability test (retry), or VeilidAPIError::NotInitialized if the API has been shut down.

pub async fn new_custom_private_route( &self, private_spec: PrivateSpec, ) -> VeilidAPIResult<RouteBlob>

Allocate a new private route and specify a specific cryptosystem, stability and sequencing preference. Faster connections may be possible with Stability::LowLatency, and Sequencing::PreferUnordered at the expense of some loss of messages. Returns a route id and a publishable ‘blob’ with the route encrypted with each crypto kind. Those nodes importing the blob will have their choice of which crypto kind to use.

Returns a route id and ‘blob’ that can be published over some means (DHT or otherwise) to be imported by another Veilid node.

Blocks on the network to allocate and test the route. The returned route id holds an allocated route the caller must free with VeilidAPI::release_private_route.

Errors with VeilidAPIError::Generic if private_spec names an invalid crypto kind, VeilidAPIError::InvalidArgument if the hop count exceeds the configured maximum, VeilidAPIError::TryAgain if there is no valid PublicInternet network class yet, not enough nodes are known to build the route, or the route failed its reachability test (retry), or VeilidAPIError::NotInitialized if the API has been shut down.

pub fn import_remote_private_route( &self, blob: Vec<u8>, ) -> VeilidAPIResult<RouteId>

Import a private route blob as a remote private route.

Returns a route id that can be used to send private messages to the node creating this route.

Local import, no network round-trip. The returned route id holds an imported route the caller must free with VeilidAPI::release_private_route.

Errors with VeilidAPIError::InvalidArgument if blob is empty or names too many crypto kinds, VeilidAPIError::ParseError if it is malformed, VeilidAPIError::Generic if the decoded route has no first hop, or VeilidAPIError::NotInitialized if the API has been shut down.

pub fn release_private_route(&self, route_id: RouteId) -> VeilidAPIResult<()>

Release either a locally allocated or remotely imported private route.

This will deactivate the route and free its resources and it can no longer be sent to or received from.

This is the release for VeilidAPI::new_private_route, VeilidAPI::new_custom_private_route, and VeilidAPI::import_remote_private_route. Local, no network round-trip. Releasing a route id that is unknown, already released, or malformed (unsupported crypto kind or bad length) returns VeilidAPIError::InvalidArgument; errors with VeilidAPIError::NotInitialized if the API has been shut down.

pub async fn app_call_reply( &self, call_id: OperationId, message: Vec<u8>, ) -> VeilidAPIResult<()>

Respond to an AppCall received over a VeilidUpdate::AppCall.

• call_id - specifies which call to reply to, and it comes from a VeilidUpdate::AppCall, specifically the VeilidAppCall::id() value.
• message - is an answer blob to be returned by the remote node’s RoutingContext::app_call() function, and may be up to 32768 bytes.

Completes the pending call locally and does not block on the network. Each call_id may be answered only once; replying to an unknown or already-answered call_id errors with VeilidAPIError::Generic. Errors with VeilidAPIError::TryAgain if the node is mid-shutdown, or VeilidAPIError::NotInitialized if the API has been shut down.

impl VeilidAPI

pub fn debug_help(&self) -> VeilidAPIResult<String>

Get the help text for ‘internal debug’ commands.

pub async fn debug_uptime(&self) -> VeilidAPIResult<String>

Get node uptime info.

pub async fn debug_die( &self, mode: Option<String>, message: Vec<String>, ) -> VeilidAPIResult<String>

Cause veilid-core to panic via various means

pub async fn debug(&self, args: String) -> VeilidAPIResult<String>

Execute an internal debug command. appmessage, appcall, and appreply preserve raw trailing payload text and parse payloads in command-specific logic. Buckets/config/purge/ route/record/table/punish/network command routing uses clap while semantic parsing remains delegated to existing helpers and downstream components.

Trait Implementations

impl Clone for VeilidAPI

fn clone(&self) -> VeilidAPI

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VeilidAPI

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.