Crate veilid_core

Expand description

§The Veilid Framework

This is the core library used to create a Veilid node and operate it as part of an application.

veilid-core contains all of the core logic for Veilid and can be used in mobile applications as well as desktop and in-browser WebAssembly apps.

§Getting started

The public API is accessed by getting a VeilidAPI object via a call to api_startup, api_startup_json.

From there, a RoutingContext object can get you access to public and private routed operations.

§Cargo features

The default veilid-core configurations are:

default - Uses tokio as the async runtime.

If you use --no-default-features, you can switch to other runtimes:

default-async-std - Uses async-std as the async runtime.
default-wasm - When building for the wasm32 architecture, use this to enable wasm-bindgen-futures as the async runtime.

Re-exports§

pub use async_trait;
pub use tracing;
pub use tracing_subscriber;
pub use veilid_tools as tools;
pub use veilid_tools::bytes;

Modules§

as_human_base64: serde with-module for byte buffers: base64url-nopad string for human-readable formats, raw bytes otherwise.
as_human_opt_base64: serde with-module for Option<Vec<u8>>: base64url-nopad string for human-readable formats, raw bytes otherwise.
as_human_opt_string: serde with-module for Option<T> that uses Display/FromStr for human-readable formats and native serde otherwise.
as_human_string: serde with-module that uses a value’s Display/FromStr for human-readable formats and its native serde impl otherwise.
public_key_try_untyped_vld0: serde with-module accepting either a typed value or a bare VLD0 value.
serialize_arc: serde with-module that (de)serializes an Arc<T> transparently as its inner T.
serialize_hash_map_as_pairs: serde with-module that (de)serializes a HashMap<K, V> as a sequence of (key, value) pairs.
serialize_range_set_blaze: serde with-module that (de)serializes a RangeSetBlaze<T> as a sequence of inclusive (start, end) pairs.
signature_try_untyped_vld0: serde with-module accepting either a typed value or a bare VLD0 value.

Macros§

apibail_already_initialized: Return early with a VeilidAPIError::AlreadyInitialized error.
apibail_generic: Return early with a VeilidAPIError::Generic error carrying the given message.
apibail_internal: Return early with a VeilidAPIError::Internal error carrying the given message.
apibail_invalid_argument: Return early with a VeilidAPIError::InvalidArgument error naming the calling context, the argument, and its rejected value.
apibail_invalid_target: Return early with a VeilidAPIError::InvalidTarget error carrying the given message.
apibail_key_not_found: Return early with a VeilidAPIError::KeyNotFound error carrying the missing record key.
apibail_missing_argument: Return early with a VeilidAPIError::MissingArgument error naming the calling context and the missing argument.
apibail_no_connection: Return early with a VeilidAPIError::NoConnection error carrying the given message.
apibail_not_initialized: Return early with a VeilidAPIError::NotInitialized error.
apibail_parse_error: Return early with a VeilidAPIError::ParseError error carrying the given message and value.
apibail_timeout: Return early with a VeilidAPIError::Timeout error.
apibail_transaction_not_found: Return early with a VeilidAPIError::TransactionNotFound error carrying the given message.
apibail_try_again: Return early with a VeilidAPIError::TryAgain error carrying the given message.

Structs§

AlignedU64: 8-byte-aligned u64 newtype that serializes as a string for JSON safety.
AllowOffline: Whether a DHT write may be deferred for later when the node is offline. Defaults to true.
ApiTracingLayer: API Tracing layer for ‘tracing’ subscribers
AsyncCryptoSystemGuard: Async cryptosystem guard to help break up heavy blocking operations
AtomicOptionTimestamp: Atomic wrapper for optional timestamps used in structs so we can avoid locks for LRU and similar operations
AtomicTimestamp: Atomic wrapper for timestamps used in structs so we can avoid locks for LRU and similar operations
BareDecapsulationKey: Fixed-purpose byte array holding the raw bytes of a $name.
BareEncapsulationKey: Fixed-purpose byte array holding the raw bytes of a $name.
BareHashDigest: Fixed-purpose byte array holding the raw bytes of a $name.
BareKemKeyPair: Untyped KEM encapsulation/decapsulation key pair, carrying no cryptosystem kind.
BareKeyPair: Untyped public/secret key pair, carrying no cryptosystem kind.
BareMemberId: Fixed-purpose byte array holding the raw bytes of a $name.
BareNodeId: Fixed-purpose byte array holding the raw bytes of a $name.
BareOpaqueRecordKey: Fixed-purpose byte array holding the raw bytes of a $name.
BarePublicKey: Fixed-purpose byte array holding the raw bytes of a $name.
BareRecordKey: Untyped DHT record key: an opaque record key with an optional record encryption secret.
BareRouteId: Fixed-purpose byte array holding the raw bytes of a $name.
BareSecretKey: Fixed-purpose byte array holding the raw bytes of a $name.
BareSharedSecret: Fixed-purpose byte array holding the raw bytes of a $name.
BareSignature: Fixed-purpose byte array holding the raw bytes of a $name.
ByteCount: 8-byte-aligned u64 newtype that serializes as a string for JSON safety.
Crypto: Crypto factory implementation
CryptoKind: A four-character code
CryptoSystemGuard: Guard to access a particular cryptosystem
DHTRecordDescriptor: DHT Record Descriptor
DHTRecordReport: DHT Record Report
DHTSchemaDFLT: Default DHT Schema (DFLT)
DHTSchemaSMPL: Simple DHT Schema (SMPL)
DHTSchemaSMPLMember: Simple DHT Schema (SMPL) Member
DHTTransaction: DHT Transactions the way you perform multiple simulateous atomic operations over a set of DHT records.
DHTTransactionSetValueOptions: Options that override defaults for DHTTransaction::set
DecapsulationKey: A KEM secret key, opening blobs with CryptoSystem::hpke_open (DHKEM-X25519 under VLD0, ML-KEM at VLD1). Signing uses SecretKey; under VLD0 this key is derivable from one via CryptoSystem::decapsulation_key_from_signing_secret. A value tagged with the CryptoKind of the cryptosystem it belongs to.
DecapsulationKeyGroup: An ordered group of typed values holding at most one entry per CryptoKind.
EncapsulationKey: A KEM public key, sealed to with CryptoSystem::hpke_seal (DHKEM-X25519 under VLD0, ML-KEM at VLD1). Signing and identity use PublicKey; under VLD0 this key is derivable from one via CryptoSystem::encapsulation_key_from_signing_key. A value tagged with the CryptoKind of the cryptosystem it belongs to.
EncapsulationKeyGroup: An ordered group of typed values holding at most one entry per CryptoKind.
FmtStripVeilidFields: A filter for the fmt tracing layer that can be used to remove the Veilid-specific fields from the output Useful for getting the veilid-internal __VEILID_LOG_KEY fields gone from layers other than ApiTracingLayer tracing fields can not be removed by tracing filters. They can only enable and disable events and spans. To remove fields requires plugging in at the layer separately, and this struct is intended for that purpose to reduce the noise veilid-core’s logging facilities produce.
HashDigest: A value tagged with the CryptoKind of the cryptosystem it belongs to.
HashDigestGroup: An ordered group of typed values holding at most one entry per CryptoKind.
KemKeyPair: A KEM key pair for HPKE seal/open. Signing key pairs use KeyPair. A value tagged with the CryptoKind of the cryptosystem it belongs to.
KemKeyPairGroup: An ordered group of typed values holding at most one entry per CryptoKind.
KeyPair: A signing key pair. KEM key pairs use KemKeyPair. A value tagged with the CryptoKind of the cryptosystem it belongs to.
KeyPairGroup: An ordered group of typed values holding at most one entry per CryptoKind.
LatencyStats: Measurement of communications latency to this node over all RPC questions
LogOutput: A log output to be included in the log_outputs parameter of VeilidLog::try_init
MemberId: A value tagged with the CryptoKind of the cryptosystem it belongs to.
MemberIdGroup: An ordered group of typed values holding at most one entry per CryptoKind.
NodeCount: 8-byte-aligned u64 newtype that serializes as a string for JSON safety.
NodeId: A value tagged with the CryptoKind of the cryptosystem it belongs to.
NodeIdGroup: An ordered group of typed values holding at most one entry per CryptoKind.
Nonce: Fixed-purpose byte array holding the raw bytes of a $name.
OpaqueRecordKey: A value tagged with the CryptoKind of the cryptosystem it belongs to.
OpaqueRecordKeyGroup: An ordered group of typed values holding at most one entry per CryptoKind.
OperationId: 8-byte-aligned u64 newtype that serializes as a string for JSON safety.
PeerStats: API-visible statistics for a peer in the routing table
PeerTableData: Describe a recently accessed peer
PrivateSpec: Options for private routes (receiver privacy).
ProtectedStore: Secure key-value storage for user secrets, backed by the platform’s secure keyring when available and falling back to an on-disk insecure keyring when permitted by config.
ProtectedStoreInner: Mutable interior of the ProtectedStore, holding the open keyring backend.
PublicKey: A signing public key: verification, identity, and node ids (Ed25519 under VLD0, ML-DSA at VLD1). KEM encryption to a key uses EncapsulationKey. A value tagged with the CryptoKind of the cryptosystem it belongs to.
PublicKeyGroup: An ordered group of typed values holding at most one entry per CryptoKind.
RecordKey: A value tagged with the CryptoKind of the cryptosystem it belongs to.
RecordKeyGroup: An ordered group of typed values holding at most one entry per CryptoKind.
RouteBlob: An allocated route’s id paired with its encoded blob for import by another node.
RouteId: A value tagged with the CryptoKind of the cryptosystem it belongs to.
RouteIdGroup: An ordered group of typed values holding at most one entry per CryptoKind.
RoutingContext: Routing contexts are the way you specify the communication preferences for Veilid.
SafetySpec: Options for safety routes (sender privacy).
SecretKey: A signing secret key (Ed25519 under VLD0, ML-DSA at VLD1). KEM decryption uses DecapsulationKey. A value tagged with the CryptoKind of the cryptosystem it belongs to.
SecretKeyGroup: An ordered group of typed values holding at most one entry per CryptoKind.
SetDHTValueOptions: Options that override defaults for set_dht_value
SharedSecret: A value tagged with the CryptoKind of the cryptosystem it belongs to.
SharedSecretGroup: An ordered group of typed values holding at most one entry per CryptoKind.
Signature: A value tagged with the CryptoKind of the cryptosystem it belongs to.
SignatureGroup: An ordered group of typed values holding at most one entry per CryptoKind.
TableDB: A handle to an opened encrypted key-value table. Cheap to clone; clones share the same underlying database.
TableDBTransaction: A TableDB transaction Atomically commits a group of writes or deletes to the TableDB
TableStore: Veilid Table Storage. Database for storing key value pairs persistently and securely across runs.
Timestamp: 8-byte-aligned u64 newtype that serializes as a string for JSON safety.
TimestampDuration: 8-byte-aligned u64 newtype that serializes as a string for JSON safety.
TransactDHTRecordsOptions: Options for DHT record transactions
TransferStats: Measurement of how much data has transferred to or from this node over a time span
TransferStatsDownUp: Transfer statistics in both directions: from a node to us (down) and from us to the node (up).
ValueData: A DHT value and its metadata
ValueSeqNum: Value sequence number
ValueSubkeyRangeSet: A set of DHT subkeys stored as inclusive ranges of ValueSubkey
VeilidAPI: The primary developer entrypoint into veilid-core functionality.
VeilidAppCall: Direct question blob passed to hosting application for processing to send an eventual AppReply.
VeilidAppMessage: Direct statement blob passed to hosting application for processing.
VeilidCapability: A four-character code
VeilidComponentGuard: Borrow guard holding a shared reference to a registered component for the duration of 'a.
VeilidConfig: Top level of the Veilid configuration tree
VeilidConfigBlockStore: Block store configuration: content-addressed block storage.
VeilidConfigCapabilities: Capabilities advertised by this node.
VeilidConfigDHT: Configure the Distributed Hash Table (DHT). Defaults should be used here unless you are absolutely sure you know what you’re doing. If you change the count/fanout/timeout parameters, you may render your node inoperable for correct DHT operations.
VeilidConfigInternal: Internal “footgun” configuration tree, parallel to the main config.
VeilidConfigInternalDHT: Internal “footgun” DHT configuration. See VeilidConfigInternal. Changing the count/fanout/timeout parameters may render your node inoperable for correct DHT operations.
VeilidConfigInternalNetwork: Internal “footgun” network configuration. See VeilidConfigInternal.
VeilidConfigInternalProtocol: Internal “footgun” per-protocol configuration. See VeilidConfigInternal.
VeilidConfigInternalRPC: Internal “footgun” RPC configuration. See VeilidConfigInternal.
VeilidConfigInternalUDP: Internal “footgun” UDP configuration. See VeilidConfigInternal.
VeilidConfigNetwork: Network subsystem configuration: connections, routing table, RPC, DHT, transports, and privacy.
VeilidConfigPrivacy: Privacy preferences for routes.
VeilidConfigProtectedStore: Protected store configuration: where secrets such as the device encryption key are kept.
VeilidConfigProtocol: Configure Network Protocols.
VeilidConfigRPC: Configure RPC.
VeilidConfigRoutingTable: Configure the network routing table.
VeilidConfigTCP: Enable and configure TCP.
VeilidConfigTLS: Configure TLS.
VeilidConfigTableStore: Table store configuration: the encrypted key-value database backing node state.
VeilidConfigUDP: Enable and configure UDP.
VeilidConfigWS: Enable and configure Web Sockets.
VeilidLayerFilter: A tracing layer filter that gates events and spans by Veilid log facility, level, and log key. Its configuration can be changed at runtime.
VeilidLayerFilterConfig: How to initialize the list of filtered facilities
VeilidLog: A VeilidCore log message with optional backtrace.
VeilidLogDirective: Changes to the VeilidLayerFilter enabled facilities
VeilidRouteChange: Describe a private or safety route change that has happened
VeilidStartupOptions: The configuration built for each Veilid node during API startup
VeilidState: A queriable state of the internals of veilid-core.
VeilidStateAttachment: Describe the attachment state of the Veilid node
VeilidStateConfig: Describe changes to the Veilid node configuration Currently this is only ever emitted once, however we reserve the right to add the ability to change the configuration or have it changed by the Veilid node itself during runtime.
VeilidStateNetwork: Describe the current network state of the Veilid node
VeilidTracing: A simple high-level logging mechanism for Veilid applications
VeilidValueChange: Describe when DHT records have subkey values changed

Enums§

AttachmentState: Attachment abstraction for network ‘signal strength’.
DHTReportScope: DHT Record Report Scope
DHTSchema: Enum over all the supported DHT Schemas
ExpirationState: The state of a timestamp, either live (not expired) or dead (expired)
LogOutputKind: Where a LogOutput sends its formatted log events.
SafetySelection: The choice of safety route to include in compiled routes.
SequenceOrdering: Ordering of RPC message delivery over a route or for RPC messages sent to a target
Sequencing: Preferred ordering of RPC message delivery over a route or for RPC messages sent to a target
Stability: Choice of nodes to include in allocated routes
Target: Valid destinations for a message sent over a routing context.
VeilidAPIError: Error type returned by all fallible Veilid API operations.
VeilidConfigAddressType: An IP address family (IP version) the node may use.
VeilidConfigLogLevel: Logging level threshold (Off disables logging).
VeilidLogKeyFilterMode: Selects which log keys a VeilidLayerFilter accepts.
VeilidLogLevel: Log level for VeilidCore.
VeilidUpdate: An update from the veilid-core to the host application describing a change to the internal state of the Veilid node.

Constants§

CONNECTIVITY_CAPABILITIES: Capabilities that contribute to network connectivity, used when refreshing the routing table.
CRYPTO_KIND_VLD0: CryptoKind fourcc identifying the VLD0 cryptosystem.
CRYPTO_KIND_VLD0_FOURCC: The VLD0 fourcc as a big-endian u32.
DISTANCE_METRIC_CAPABILITIES: Capabilities that participate in the DHT distance metric, used when finding nodes close to a key.
LOCAL_NETWORK_CAPABILITIES: Capabilities advertised by this node in the LocalNetwork routing domain.
MAX_CAPABILITIES: Maximum number of capabilities a node may advertise.
MAX_CONNECTIONS_MAX: Maximum allowed total network.max_connections on native platforms.
MAX_CONNECTIONS_MIN: Minimum allowed total network.max_connections on native platforms.
MAX_CRYPTO_KINDS: Number of cryptosystem signatures to keep on structures if many are present beyond the ones we consider valid
MEMBER_ID_LENGTH: Fixed length of MemberId (DHT Schema member id) in bytes
PUBLIC_INTERNET_CAPABILITIES: Capabilities advertised by this node in the PublicInternet routing domain.
VALID_CRYPTO_KINDS: Crypto kinds in order of preference, best cryptosystem is the first one, worst is the last one
VEILID_CAPABILITY_APPMESSAGE: Node accepts application messages and calls.
VEILID_CAPABILITY_DHT: Node participates in the distributed hash table.
VEILID_CAPABILITY_RELAY: Node can act as an inbound relay for nodes that are not directly reachable.
VEILID_CAPABILITY_ROUTE: Node can relay private routes for other nodes.
VEILID_CAPABILITY_SIGNAL: Node can perform reverse-connect signalling to help nodes behind NAT make inbound connections.
VEILID_CAPABILITY_VALIDATE_DIAL_INFO: Node can validate another node’s claimed dial info by attempting to reach it.
VEILID_LOG_KEY_FIELD: The tracing log field used by veilid-core to indicate which instance of the VeilidAPI is doing the logging.
VLD0_DECAPSULATION_KEY_LENGTH: Length of a KEM decapsulation key in bytes (x25519 secret key)
VLD0_ENCAPSULATION_KEY_LENGTH: Length of a KEM encapsulation key in bytes (x25519 public key)
VLD0_HASH_DIGEST_LENGTH: Length of a hash digest in bytes
VLD0_HPKE_ENC_LENGTH: Length of the enc field of an HPKE sealed blob in bytes (DHKEM X25519 KEM ciphertext)
VLD0_NONCE_LENGTH: Length of a nonce in bytes
VLD0_PUBLIC_KEY_LENGTH: Length of a crypto key in bytes
VLD0_SECRET_KEY_LENGTH: Length of a secret key in bytes
VLD0_SHARED_SECRET_LENGTH: Length of a shared secret in bytes
VLD0_SIGNATURE_LENGTH: Length of a signature in bytes

Statics§

KNOWN_PROTECTED_STORE_KEYS: Protected store keys that Veilid creates and manages, removed together by delete_all.

Traits§

Buffer: In-place encryption/decryption byte buffers.
CryptoSystem: The set of cryptographic primitives a single cryptosystem provides: key generation, signing and verification, AEAD and unauthenticated encryption, Diffie-Hellman key exchange and shared secret derivation, hashing, password hashing, and random byte generation.
OkVeilidAPIResult: Extension methods for turning recoverable VeilidAPIError outcomes into Ok(None).
TimestampDurationTimeoutFutureExt: Future extension trait that mirrors TimestampDuration::timeout for ergonomic chaining. Named timeout_duration to avoid conflict with futures_time::FutureExt::timeout.
ToVeilidAPIErrorArgument: Trait for types that can be directly converted into parameters for VeilidAPIError

Functions§

api_startup: Initialize a Veilid node, with the configuration object.
api_startup_json: Initialize a Veilid node, with the configuration in JSON format.
common_crypto_kinds: Intersection of crypto kind vectors
compare_crypto_kind: Sort best crypto kinds first Better crypto kinds are ‘less’, ordered toward the front of a list
default_veilid_config: Return the default veilid config as a json object.
deserialize_json: Deserializes T from a JSON string, mapping parse failures to VeilidAPIError::ParseError.
deserialize_json_bytes: Deserializes T from JSON bytes, mapping parse failures to VeilidAPIError::ParseError.
deserialize_json_lenient: Lenient JSON deserialization for command-line / set_config ergonomics.
deserialize_opt_json: Deserializes T from an optional JSON string, returning a ParseError when the argument is None.
deserialize_opt_json_bytes: Deserializes T from optional JSON bytes, returning a ParseError when the argument is None.
get_default_ssl_directory: Default directory for TLS certificates and keys, given the program identity and a relative sub-path.
serialize_json: Serializes val to a JSON string, panicking if serialization fails.
serialize_json_bytes: Serializes val to JSON bytes, panicking if serialization fails.
serialize_json_pretty: Serializes val to a pretty-printed JSON string, panicking if serialization fails.
veilid_features: Return the features that were enabled when veilid-core was built.
veilid_version: Return the cargo package version of veilid-core in tuple format.
veilid_version_string: Return the cargo package version of veilid-core in string format.

Type Aliases§

SequenceOrderingSet: A set of SequenceOrdering values.
UpdateCallback: Callback the application registers to receive VeilidUpdate events from a running node.
ValueSubkey: Value subkey
VeilidAPIResult: Result type for public Veilid API errors
VeilidLayerLogKeyFilter: The type of a filtering closure accepted by VeilidLayerFilter. The filter is passed a log key to filter on and returns true if the log key matches the desired log key of the application. This is an advanced filter for when a basic string comparison against a VeilidLogKey is insufficient, for example defining a logging layer that aggregates the logs of several VeilidAPI instances
VeilidLogKey: A log filtering key that is a combination of the ‘program name’ and ‘namespace’ of the VeilidAPI instance This has a static lifetime because it is used in the veilid_log!() macros

Attribute Macros§

async_trait: Re-exported from async-trait crate

Crate veilid_core

Crate veilid_core Copy item path

§The Veilid Framework

§Getting started

§Cargo features

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Statics§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate veilid_core