IntenseWebs/veilid
3
0
Fork 0
mirror of https://gitlab.com/veilid/veilid.git synced 2024-11-21 16:37:39 -06:00
Code Issues Packages Projects Releases Wiki Activity

Assorted comment typo and formatting fixes

Browse Source
This commit is contained in:
Sashanoraa 2024-05-01 20:37:06 -04:00
parent 439d2641f1
commit 5da287fae4
17 changed files with 159 additions and 158 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
veilid-core/src/attachment_manager.rs
View File

@ -120,7 +120,7 @@ impl AttachmentManager {
}
/// Update attachment and network readiness state
/// and possibly send a VeilidUpdate::Attachment
/// and possibly send a VeilidUpdate::Attachment.
fn update_attachment(&self) {
// update the routing table health
let routing_table = self.network_manager().routing_table();

32
veilid-core/src/core_context.rs
View File

@ -8,9 +8,9 @@ use crate::*;
pub type UpdateCallback = Arc<dyn Fn(VeilidUpdate) + Send + Sync>;
/// Internal services startup mechanism
/// Internal services startup mechanism.
/// Ensures that everything is started up, and shut down in the right order
/// and provides an atomic state for if the system is properly operational
/// and provides an atomic state for if the system is properly operational.
struct ServicesContext {
pub config: VeilidConfig,
pub update_callback: UpdateCallback,
@ -289,12 +289,12 @@ lazy_static::lazy_static! {
/// Initialize a Veilid node.
///
/// Must be called only once at the start of an application
/// Must be called only once at the start of an application.
///
/// * `update_callback` - called when internal state of the Veilid node changes, for example, when app-level messages are received, when private routes die and need to be reallocated, or when routing table states change
/// * `config_callback` - called at startup to supply a configuration object directly to Veilid
/// * `update_callback` - called when internal state of the Veilid node changes, for example, when app-level messages are received, when private routes die and need to be reallocated, or when routing table states change.
/// * `config_callback` - called at startup to supply a configuration object directly to Veilid.
///
/// Returns a [VeilidAPI] object that can be used to operate the node
/// Returns a [VeilidAPI] object that can be used to operate the node.
#[instrument(err, skip_all)]
pub async fn api_startup(
update_callback: UpdateCallback,
@ -318,14 +318,14 @@ pub async fn api_startup(
Ok(veilid_api)
}
/// Initialize a Veilid node, with the configuration in JSON format
/// Initialize a Veilid node, with the configuration in JSON format.
///
/// Must be called only once at the start of an application
/// Must be called only once at the start of an application.
///
/// * `update_callback` - called when internal state of the Veilid node changes, for example, when app-level messages are received, when private routes die and need to be reallocated, or when routing table states change
/// * `config_json` - called at startup to supply a JSON configuration object
/// * `update_callback` - called when internal state of the Veilid node changes, for example, when app-level messages are received, when private routes die and need to be reallocated, or when routing table states change.
/// * `config_json` - called at startup to supply a JSON configuration object.
///
/// Returns a [VeilidAPI] object that can be used to operate the node
/// Returns a [VeilidAPI] object that can be used to operate the node.
#[instrument(err, skip_all)]
pub async fn api_startup_json(
update_callback: UpdateCallback,
@ -348,14 +348,14 @@ pub async fn api_startup_json(
Ok(veilid_api)
}
/// Initialize a Veilid node, with the configuration object
/// Initialize a Veilid node, with the configuration object.
///
/// Must be called only once at the start of an application
/// Must be called only once at the start of an application.
///
/// * `update_callback` - called when internal state of the Veilid node changes, for example, when app-level messages are received, when private routes die and need to be reallocated, or when routing table states change
/// * `config` - called at startup to supply a configuration object
/// * `update_callback` - called when internal state of the Veilid node changes, for example, when app-level messages are received, when private routes die and need to be reallocated, or when routing table states change.
/// * `config` - called at startup to supply a configuration object.
///
/// Returns a [VeilidAPI] object that can be used to operate the node
/// Returns a [VeilidAPI] object that can be used to operate the node.
#[instrument(err, skip_all)]
pub async fn api_startup_config(
update_callback: UpdateCallback,

12
veilid-core/src/lib.rs
View File

@ -14,12 +14,12 @@
//!
//! The default `veilid-core` configurations are:
//!
//! * `default` - Uses `tokio` as the async runtime
//! * `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
//! * `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.
//!
#![deny(clippy::all)]
@ -67,7 +67,7 @@ pub use self::veilid_api::*;
pub use self::veilid_config::*;
pub use veilid_tools as tools;
/// The on-the-wire serialization format for Veilid RPC
/// The on-the-wire serialization format for Veilid RPC.
pub mod veilid_capnp {
include!("../proto/veilid_capnp.rs");
}
@ -75,12 +75,12 @@ pub mod veilid_capnp {
#[doc(hidden)]
pub mod tests;
/// Return the cargo package version of veilid-core in string format
/// Return the cargo package version of veilid-core in string format.
pub fn veilid_version_string() -> String {
env!("CARGO_PKG_VERSION").to_owned()
}
/// Return the cargo package version of veilid-core in tuple format
/// Return the cargo package version of veilid-core in tuple format.
pub fn veilid_version() -> (u32, u32, u32) {
(
u32::from_str(env!("CARGO_PKG_VERSION_MAJOR")).unwrap(),

6
veilid-core/src/table_store/mod.rs
View File

@ -26,8 +26,8 @@ struct TableStoreInner {
crypto: Option<Crypto>,
}
/// Veilid Table Storage
/// Database for storing key value pairs persistently and securely across runs
/// Veilid Table Storage.
/// Database for storing key value pairs persistently and securely across runs.
#[derive(Clone)]
pub struct TableStore {
config: VeilidConfig,
@ -444,7 +444,7 @@ impl TableStore {
}
/// Get or create a TableDB database table. If the column count is greater than an
/// existing TableDB's column count, the database will be upgraded to add the missing columns
/// existing TableDB's column count, the database will be upgraded to add the missing columns.
pub async fn open(&self, name: &str, column_count: u32) -> VeilidAPIResult<TableDB> {
let _async_guard = self.async_lock.lock().await;

14
veilid-core/src/table_store/table_db.rs
View File

@ -88,19 +88,19 @@ impl TableDB {
Arc::downgrade(&self.unlocked_inner)
}
/// Get the total number of columns in the TableDB
/// Not the number of columns that were opened, rather the total number that could be opened
/// Get the total number of columns in the TableDB.
/// Not the number of columns that were opened, rather the total number that could be opened.
pub fn get_column_count(&self) -> VeilidAPIResult<u32> {
let db = &self.unlocked_inner.database;
db.num_columns().map_err(VeilidAPIError::from)
}
/// Encrypt buffer using encrypt key and prepend nonce to output
/// Keyed nonces are unique because keys must be unique
/// Normally they must be sequential or random, but the critical
/// Encrypt buffer using encrypt key and prepend nonce to output.
/// Keyed nonces are unique because keys must be unique.
/// Normally they must be sequential or random, but the critical.
/// requirement is that they are different for each encryption
/// but if the contents are guaranteed to be unique, then a nonce
/// can be generated from the hash of the contents and the encryption key itself
/// can be generated from the hash of the contents and the encryption key itself.
fn maybe_encrypt(&self, data: &[u8], keyed_nonce: bool) -> Vec<u8> {
let data = compress_prepend_size(data);
if let Some(ei) = &self.unlocked_inner.encrypt_info {
@ -155,7 +155,7 @@ impl TableDB {
}
}
/// Get the list of keys in a column of the TableDAB
/// Get the list of keys in a column of the TableDB
pub async fn get_keys(&self, col: u32) -> VeilidAPIResult<Vec<Vec<u8>>> {
if col >= self.opened_column_count {
apibail_generic!(format!(

64
veilid-core/src/veilid_api/api.rs
View File

@ -20,19 +20,19 @@ impl Drop for VeilidAPIInner {
}
}
/// The primary developer entrypoint into `veilid-core` functionality
/// The primary developer entrypoint into `veilid-core` functionality.
///
/// From [VeilidAPI] one can access:
///
/// * [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
/// * [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.
#[derive(Clone, Debug)]
pub struct VeilidAPI {
inner: Arc<Mutex<VeilidAPIInner>>,
@ -50,7 +50,7 @@ impl VeilidAPI {
}
}
/// Shut down Veilid and terminate the API
/// Shut down Veilid and terminate the API.
#[instrument(target = "veilid_api", level = "debug", skip_all)]
pub async fn shutdown(self) {
event!(target: "veilid_api", Level::DEBUG,
@ -61,7 +61,7 @@ impl VeilidAPI {
}
}
/// Check to see if Veilid is already shut down
/// Check to see if Veilid is already shut down.
pub fn is_shutdown(&self) -> bool {
self.inner.lock().context.is_none()
}
@ -69,7 +69,7 @@ impl VeilidAPI {
////////////////////////////////////////////////////////////////
// Public Accessors
/// Access the configuration that Veilid was initialized with
/// Access the configuration that Veilid was initialized with.
pub fn config(&self) -> VeilidAPIResult<VeilidConfig> {
let inner = self.inner.lock();
if let Some(context) = &inner.context {
@ -78,7 +78,7 @@ impl VeilidAPI {
Err(VeilidAPIError::NotInitialized)
}
/// Get the cryptosystem manager
/// Get the cryptosystem manager.
pub fn crypto(&self) -> VeilidAPIResult<Crypto> {
let inner = self.inner.lock();
if let Some(context) = &inner.context {
@ -87,7 +87,7 @@ impl VeilidAPI {
Err(VeilidAPIError::NotInitialized)
}
/// Get the TableStore manager
/// Get the TableStore manager.
pub fn table_store(&self) -> VeilidAPIResult<TableStore> {
let inner = self.inner.lock();
if let Some(context) = &inner.context {
@ -96,7 +96,7 @@ impl VeilidAPI {
Err(VeilidAPIError::not_initialized())
}
/// Get the ProtectedStore manager
/// Get the ProtectedStore manager.
pub fn protected_store(&self) -> VeilidAPIResult<ProtectedStore> {
let inner = self.inner.lock();
if let Some(context) = &inner.context {
@ -154,7 +154,7 @@ impl VeilidAPI {
////////////////////////////////////////////////////////////////
// Attach/Detach
/// Get a full copy of the current state of Veilid
/// Get a full copy of the current state of Veilid.
pub async fn get_state(&self) -> VeilidAPIResult<VeilidState> {
let attachment_manager = self.attachment_manager()?;
let network_manager = attachment_manager.network_manager();
@ -171,7 +171,7 @@ impl VeilidAPI {
})
}
/// Connect to the network
/// Connect to the network.
#[instrument(target = "veilid_api", level = "debug", skip_all, ret, err)]
pub async fn attach(&self) -> VeilidAPIResult<()> {
event!(target: "veilid_api", Level::DEBUG,
@ -184,7 +184,7 @@ impl VeilidAPI {
Ok(())
}
/// Disconnect from the network
/// Disconnect from the network.
#[instrument(target = "veilid_api", level = "debug", skip_all, ret, err)]
pub async fn detach(&self) -> VeilidAPIResult<()> {
event!(target: "veilid_api", Level::DEBUG,
@ -209,13 +209,13 @@ impl VeilidAPI {
RoutingContext::try_new(self.clone())
}
/// Parse a string into a target object that can be used in a [RoutingContext]
/// Parse a string into a target object that can be used in a [RoutingContext].
///
/// Strings are in base64url format and can either be a remote route id or a node id.
/// Strings may have a [CryptoKind] [FourCC] prefix separated by a colon, such as:
/// `VLD0:XmnGyJrjMJBRC5ayJZRPXWTBspdX36-pbLb98H3UMeE` but if the prefix is left off
/// `XmnGyJrjMJBRC5ayJZRPXWTBspdX36-pbLb98H3UMeE` will be parsed with the 'best' cryptosystem
/// available (at the time of this writing this is `VLD0`)
/// available (at the time of this writing this is `VLD0`).
#[instrument(target = "veilid_api", level = "debug", skip(self), fields(s=s.to_string()), ret, err)]
pub fn parse_as_target<S: ToString>(&self, s: S) -> VeilidAPIResult<Target> {
let s = s.to_string();
@ -245,10 +245,10 @@ impl VeilidAPI {
////////////////////////////////////////////////////////////////
// Private route allocation
/// Allocate a new private route set with default cryptography and network options
/// Default settings are for Stability::Reliable and Sequencing::EnsureOrdered
/// 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
/// Allocate a new private route set with default cryptography and network options.
/// Default settings are for [Stability::Reliable] and [Sequencing::EnsureOrdered].
/// 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.
@ -262,11 +262,11 @@ impl VeilidAPI {
.await
}
/// Allocate a new private route and specify a specific cryptosystem, stability and sequencing preference
/// Faster connections may be possible with Stability::LowLatency, and Sequencing::NoPreference 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
/// Allocate a new private route and specify a specific cryptosystem, stability and sequencing preference.
/// Faster connections may be possible with [Stability::LowLatency], and [Sequencing::NoPreference] 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.
@ -332,7 +332,7 @@ impl VeilidAPI {
rss.import_remote_private_route_blob(blob)
}
/// Release either a locally allocated or remotely imported private route
/// 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.
@ -353,7 +353,7 @@ impl VeilidAPI {
/// 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
/// * `message` - is an answer blob to be returned by the remote node's [RoutingContext::app_call()] function, and may be up to 32768 bytes.
#[instrument(target = "veilid_api", level = "debug", skip(self), ret, err)]
pub async fn app_call_reply(
&self,

4
veilid-core/src/veilid_api/debug.rs
View File

@ -1924,7 +1924,7 @@ impl VeilidAPI {
}
}
/// Get the help text for 'internal debug' commands
/// Get the help text for 'internal debug' commands.
pub async fn debug_help(&self, _args: String) -> VeilidAPIResult<String> {
Ok(r#"buckets [dead|reliable]
dialinfo
@ -2002,7 +2002,7 @@ record list <local|remote|opened|offline>
.to_owned())
}
/// Execute an 'internal debug command'
/// Execute an 'internal debug command'.
pub async fn debug(&self, args: String) -> VeilidAPIResult<String> {
let res = {
let args = args.trim_start();

8
veilid-core/src/veilid_api/json_api/mod.rs
View File

@ -14,10 +14,10 @@ pub use process::*;
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct Request {
/// Operation Id (pairs with Response, or empty if unidirectional)
/// Operation Id (pairs with Response, or empty if unidirectional).
#[serde(default)]
pub id: u32,
/// The request operation variant
/// The request operation variant.
#[serde(flatten)]
pub op: RequestOp,
}
@ -31,10 +31,10 @@ pub enum RecvMessage {
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct Response {
/// Operation Id (pairs with Request, or empty if unidirectional)
/// Operation Id (pairs with Request, or empty if unidirectional).
#[serde(default)]
pub id: u32,
/// The response operation variant
/// The response operation variant.
#[serde(flatten)]
pub op: ResponseOp,
}

87
veilid-core/src/veilid_api/routing_context.rs
View File

@ -2,19 +2,19 @@ use super::*;
///////////////////////////////////////////////////////////////////////////////////////
/// Valid destinations for a message sent over a routing context
/// Valid destinations for a message sent over a routing context.
#[derive(Clone, Debug, Eq, PartialEq, Hash, Copy, PartialOrd, Ord)]
pub enum Target {
/// Node by its public key
/// Node by its public key.
NodeId(TypedKey),
/// Remote private route by its id
/// Remote private route by its id.
PrivateRoute(RouteId),
}
pub struct RoutingContextInner {}
pub struct RoutingContextUnlockedInner {
/// Safety routing requirements
/// Safety routing requirements.
safety_selection: SafetySelection,
}
@ -26,7 +26,7 @@ pub struct RoutingContextUnlockedInner {
///
#[derive(Clone)]
pub struct RoutingContext {
/// Veilid API handle
/// Veilid API handle.
api: VeilidAPI,
inner: Arc<Mutex<RoutingContextInner>>,
unlocked_inner: Arc<RoutingContextUnlockedInner>,
@ -69,7 +69,7 @@ impl RoutingContext {
///
/// * Hop count default is dependent on config, but is set to 1 extra hop.
/// * Stability default is to choose 'low latency' routes, preferring them over long-term reliability.
/// * Sequencing default is to prefer ordered before unordered message delivery
/// * Sequencing default is to prefer ordered before unordered message delivery.
///
/// To customize the safety selection in use, use [RoutingContext::with_safety()].
#[instrument(target = "veilid_api", level = "debug", ret, err)]
@ -88,7 +88,7 @@ impl RoutingContext {
}))
}
/// Use a custom [SafetySelection]. Can be used to disable safety via [SafetySelection::Unsafe]
/// Use a custom [SafetySelection]. Can be used to disable safety via [SafetySelection::Unsafe].
#[instrument(target = "veilid_api", level = "debug", ret, err)]
pub fn with_safety(self, safety_selection: SafetySelection) -> VeilidAPIResult<Self> {
event!(target: "veilid_api", Level::DEBUG,
@ -101,7 +101,7 @@ impl RoutingContext {
})
}
/// Use a specified [Sequencing] preference, with or without privacy
/// Use a specified [Sequencing] preference, with or without privacy.
#[instrument(target = "veilid_api", level = "debug", ret)]
pub fn with_sequencing(self, sequencing: Sequencing) -> Self {
event!(target: "veilid_api", Level::DEBUG,
@ -124,7 +124,7 @@ impl RoutingContext {
}
}
/// Get the safety selection in use on this routing context
/// Get the safety selection in use on this routing context.
pub fn safety(&self) -> SafetySelection {
self.unlocked_inner.safety_selection
}
@ -136,7 +136,7 @@ impl RoutingContext {
}
}
/// Get the [VeilidAPI] object that created this [RoutingContext]
/// Get the [VeilidAPI] object that created this [RoutingContext].
pub fn api(&self) -> VeilidAPI {
self.api.clone()
}
@ -160,10 +160,10 @@ impl RoutingContext {
///
/// Veilid apps may use this for arbitrary message passing.
///
/// * `target` - can be either a direct node id or a private route
/// * `message` - an arbitrary message blob of up to 32768 bytes
/// * `target` - can be either a direct node id or a private route.
/// * `message` - an arbitrary message blob of up to 32768 bytes.
///
/// Returns an answer blob of up to 32768 bytes
/// Returns an answer blob of up to 32768 bytes.
#[instrument(target = "veilid_api", level = "debug", ret, err)]
pub async fn app_call(&self, target: Target, message: Vec<u8>) -> VeilidAPIResult<Vec<u8>> {
event!(target: "veilid_api", Level::DEBUG,
@ -196,8 +196,8 @@ impl RoutingContext {
///
/// Veilid apps may use this for arbitrary message passing.
///
/// * `target` - can be either a direct node id or a private route
/// * `message` - an arbitrary message blob of up to 32768 bytes
/// * `target` - can be either a direct node id or a private route.
/// * `message` - an arbitrary message blob of up to 32768 bytes.
#[instrument(target = "veilid_api", level = "debug", ret, err)]
pub async fn app_message(&self, target: Target, message: Vec<u8>) -> VeilidAPIResult<()> {
event!(target: "veilid_api", Level::DEBUG,
@ -228,7 +228,7 @@ impl RoutingContext {
///////////////////////////////////
/// DHT Records
/// Creates a new DHT record a specified crypto kind and schema
/// Creates a new DHT record a specified crypto kind and schema.
///
/// The record is considered 'open' after the create operation succeeds.
///
@ -251,7 +251,7 @@ impl RoutingContext {
.await
}
/// Opens a DHT record at a specific key
/// Opens a DHT record at a specific key.
///
/// Associates a 'default_writer' secret if one is provided to provide writer capability. The
/// writer can be overridden if specified here via the set_dht_value writer.
@ -261,7 +261,7 @@ impl RoutingContext {
/// without first closing it, which will keep the active 'watches' on the record but change the default writer or
/// safety selection.
///
/// Returns the DHT record descriptor for the opened record if successful
/// Returns the DHT record descriptor for the opened record if successful.
#[instrument(target = "veilid_api", level = "debug", ret, err)]
pub async fn open_dht_record(
&self,
@ -280,7 +280,7 @@ impl RoutingContext {
/// Closes a DHT record at a specific key that was opened with create_dht_record or open_dht_record.
///
/// Closing a record allows you to re-open it with a different routing context
/// Closing a record allows you to re-open it with a different routing context.
#[instrument(target = "veilid_api", level = "debug", ret, err)]
pub async fn close_dht_record(&self, key: TypedKey) -> VeilidAPIResult<()> {
event!(target: "veilid_api", Level::DEBUG,
@ -291,7 +291,7 @@ impl RoutingContext {
storage_manager.close_record(key).await
}
/// Deletes a DHT record at a specific key
/// Deletes a DHT record at a specific key.
///
/// If the record is opened, it must be closed before it is deleted.
/// Deleting a record does not delete it from the network, but will remove the storage of the record
@ -306,12 +306,12 @@ impl RoutingContext {
storage_manager.delete_record(key).await
}
/// Gets the latest value of a subkey
/// Gets the latest value of a subkey.
///
/// May pull the latest value from the network, but by setting 'force_refresh' you can force a network data refresh
/// May pull the latest value from the network, but by setting 'force_refresh' you can force a network data refresh.
///
/// Returns `None` if the value subkey has not yet been set
/// Returns `Some(data)` if the value subkey has valid data
/// Returns `None` if the value subkey has not yet been set.
/// Returns `Some(data)` if the value subkey has valid data.
#[instrument(target = "veilid_api", level = "debug", ret, err)]
pub async fn get_dht_value(
&self,
@ -327,13 +327,13 @@ impl RoutingContext {
storage_manager.get_value(key, subkey, force_refresh).await
}
/// Pushes a changed subkey value to the network
/// Pushes a changed subkey value to the network.
/// The DHT record must first by opened via open_dht_record or create_dht_record.
///
/// The writer, if specified, will override the 'default_writer' specified when the record is opened.
///
/// Returns `None` if the value was successfully put
/// Returns `Some(data)` if the value put was older than the one available on the network
/// Returns `None` if the value was successfully put.
/// Returns `Some(data)` if the value put was older than the one available on the network.
#[instrument(target = "veilid_api", level = "debug", ret, err)]
pub async fn set_dht_value(
&self,
@ -366,8 +366,8 @@ impl RoutingContext {
/// If the returned timestamp is zero it indicates that the watch creation or update has failed. In the case of a faild update, the watch is considered cancelled.
///
/// DHT watches are accepted with the following conditions:
/// * First-come first-served basis for arbitrary unauthenticated readers, up to network.dht.public_watch_limit per record
/// * If a member (either the owner or a SMPL schema member) has opened the key for writing (even if no writing is performed) then the watch will be signed and guaranteed network.dht.member_watch_limit per writer
/// * First-come first-served basis for arbitrary unauthenticated readers, up to network.dht.public_watch_limit per record.
/// * If a member (either the owner or a SMPL schema member) has opened the key for writing (even if no writing is performed) then the watch will be signed and guaranteed network.dht.member_watch_limit per writer.
///
/// Members can be specified via the SMPL schema and do not need to allocate writable subkeys in order to offer a member watch capability.
#[instrument(target = "veilid_api", level = "debug", ret, err)]
@ -388,14 +388,15 @@ impl RoutingContext {
.await
}
/// Cancels a watch early
/// Cancels a watch early.
///
/// This is a convenience function that cancels watching all subkeys in a range. The subkeys specified here
/// are subtracted from the watched subkey range. If no range is specified, this is equivalent to cancelling the entire range of subkeys.
/// Only the subkey range is changed, the expiration and count remain the same.
/// If no subkeys remain, the watch is entirely cancelled and will receive no more updates.
/// Returns Ok(true) if there is any remaining watch for this record
/// Returns Ok(false) if the entire watch has been cancelled
///
/// Returns Ok(true) if there is any remaining watch for this record.
/// Returns Ok(false) if the entire watch has been cancelled.
#[instrument(target = "veilid_api", level = "debug", ret, err)]
pub async fn cancel_dht_watch(
&self,
@ -421,32 +422,32 @@ impl RoutingContext {
///
/// - DHTReportScope::Local
/// Results will be only for a locally stored record.
/// Useful for seeing what subkeys you have locally and which ones have not been retrieved
/// Useful for seeing what subkeys you have locally and which ones have not been retrieved.
///
/// - DHTReportScope::SyncGet
/// Return the local sequence numbers and the network sequence numbers with GetValue fanout parameters
/// Provides an independent view of both the local sequence numbers and the network sequence numbers for nodes that
/// Return the local sequence numbers and the network sequence numbers with GetValue fanout parameters.
/// Provides an independent view of both the local sequence numbers and the network sequence numbers for nodes that.
/// would be reached as if the local copy did not exist locally.
/// Useful for determining if the current local copy should be updated from the network.
///
/// - DHTReportScope::SyncSet
/// Return the local sequence numbers and the network sequence numbers with SetValue fanout parameters
/// Provides an independent view of both the local sequence numbers and the network sequence numbers for nodes that
/// Return the local sequence numbers and the network sequence numbers with SetValue fanout parameters.
/// Provides an independent view of both the local sequence numbers and the network sequence numbers for nodes that.
/// would be reached as if the local copy did not exist locally.
/// Useful for determining if the unchanged local copy should be pushed to the network.
///
/// - DHTReportScope::UpdateGet
/// Return the local sequence numbers and the network sequence numbers with GetValue fanout parameters
/// Provides an view of both the local sequence numbers and the network sequence numbers for nodes that
/// Return the local sequence numbers and the network sequence numbers with GetValue fanout parameters.
/// Provides an view of both the local sequence numbers and the network sequence numbers for nodes that.
/// would be reached as if a GetValue operation were being performed, including accepting newer values from the network.
/// Useful for determining which subkeys would change with a GetValue operation
/// Useful for determining which subkeys would change with a GetValue operation.
///
/// - DHTReportScope::UpdateSet
/// Return the local sequence numbers and the network sequence numbers with SetValue fanout parameters
/// Provides an view of both the local sequence numbers and the network sequence numbers for nodes that
/// Return the local sequence numbers and the network sequence numbers with SetValue fanout parameters.
/// Provides an view of both the local sequence numbers and the network sequence numbers for nodes that.
/// would be reached as if a SetValue operation were being performed, including accepting newer values from the network.
/// This simulates a SetValue with the initial sequence number incremented by 1, like a real SetValue would when updating.
/// Useful for determine which subkeys would change with an SetValue operation
/// Useful for determine which subkeys would change with an SetValue operation.
///
/// Returns a DHTRecordReport with the subkey ranges that were returned that overlapped the schema, and sequence numbers for each of the subkeys in the range.
#[instrument(target = "veilid_api", level = "debug", ret, err)]

8
veilid-core/src/veilid_api/types/aligned_u64.rs
View File

@ -1,9 +1,9 @@
use super::*;
/// Aligned u64
/// Required on 32-bit platforms for serialization because Rust aligns u64 on 4 byte boundaries
/// Some zero-copy serialization frameworks also want 8-byte alignment
/// Supports serializing to string for JSON as well, since JSON can't handle 64-bit numbers to Javascript
/// Aligned u64.
/// Required on 32-bit platforms for serialization because Rust aligns u64 on 4 byte boundaries.
/// Some zero-copy serialization frameworks also want 8-byte alignment.
/// Supports serializing to string for JSON as well, since JSON can't handle 64-bit numbers to Javascript.
#[derive(
Clone, Default, PartialEq, Eq, PartialOrd, Ord, Copy, Hash, Serialize, Deserialize, JsonSchema,

18
veilid-core/src/veilid_api/types/app_message_call.rs
View File

@ -1,6 +1,6 @@
use super::*;
/// Direct statement blob passed to hosting application for processing
/// Direct statement blob passed to hosting application for processing.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[cfg_attr(target_arch = "wasm32", derive(Tsify))]
pub struct VeilidAppMessage {
@ -33,23 +33,23 @@ impl VeilidAppMessage {
}
}
/// Some(sender) if the message was sent directly, None if received via a private/safety route
/// Some(sender) if the message was sent directly, None if received via a private/safety route.
pub fn sender(&self) -> Option<&TypedKey> {
self.sender.as_ref()
}
/// Some(route_id) if the message was received over a private route, None if received only a safety route or directly
/// Some(route_id) if the message was received over a private route, None if received only a safety route or directly.
pub fn route_id(&self) -> Option<&RouteId> {
self.route_id.as_ref()
}
/// The content of the message to deliver to the application
/// The content of the message to deliver to the application.
pub fn message(&self) -> &[u8] {
&self.message
}
}
/// Direct question blob passed to hosting application for processing to send an eventual AppReply
/// Direct question blob passed to hosting application for processing to send an eventual AppReply.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[cfg_attr(target_arch = "wasm32", derive(Tsify))]
pub struct VeilidAppCall {
@ -92,22 +92,22 @@ impl VeilidAppCall {
}
}
/// Some(sender) if the request was sent directly, None if received via a private/safety route
/// Some(sender) if the request was sent directly, None if received via a private/safety route.
pub fn sender(&self) -> Option<&TypedKey> {
self.sender.as_ref()
}
/// Some(route_id) if the request was received over a private route, None if received only a safety route or directly
/// Some(route_id) if the request was received over a private route, None if received only a safety route or directly.
pub fn route_id(&self) -> Option<&RouteId> {
self.route_id.as_ref()
}
/// The content of the request to deliver to the application
/// The content of the request to deliver to the application.
pub fn message(&self) -> &[u8] {
&self.message
}
/// The id to specify as `call_id` in the [VeilidAPI::app_call_reply] function
/// The id to specify as `call_id` in the [VeilidAPI::app_call_reply] function.
pub fn id(&self) -> OperationId {
self.call_id
}

2
veilid-core/src/veilid_api/types/fourcc.rs
View File

@ -1,6 +1,6 @@
use super::*;
/// FOURCC code
/// FOURCC code.
#[derive(
Copy, Default, Clone, Hash, PartialOrd, Ord, PartialEq, Eq, Serialize, Deserialize, JsonSchema,
)]

16
veilid-core/src/veilid_api/types/safety.rs
View File

@ -43,7 +43,7 @@ impl Default for Stability {
}
}
/// The choice of safety route to include in compiled routes
/// The choice of safety route to include in compiled routes.
#[derive(
Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema,
)]
@ -54,9 +54,9 @@ impl Default for Stability {
)]
pub enum SafetySelection {
/// Don't use a safety route, only specify the sequencing preference
/// Don't use a safety route, only specify the sequencing preference.
Unsafe(Sequencing),
/// Use a safety route and parameters specified by a SafetySpec
/// Use a safety route and parameters specified by a SafetySpec.
Safe(SafetySpec),
}
@ -75,20 +75,20 @@ impl Default for SafetySelection {
}
}
/// Options for safety routes (sender privacy)
/// Options for safety routes (sender privacy).
#[derive(
Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema,
)]
#[cfg_attr(target_arch = "wasm32", derive(Tsify))]
pub struct SafetySpec {
/// preferred safety route set id if it still exists
/// Preferred safety route set id if it still exists.
#[schemars(with = "Option<String>")]
#[cfg_attr(target_arch = "wasm32", tsify(optional, type = "string"))]
pub preferred_route: Option<RouteId>,
/// must be greater than 0
/// Must be greater than 0.
pub hop_count: usize,
/// prefer reliability over speed
/// Prefer reliability over speed.
pub stability: Stability,
/// prefer connection-oriented sequenced protocols
/// Prefer connection-oriented sequenced protocols.
pub sequencing: Sequencing,
}

2
veilid-core/src/veilid_api/types/tunnel.rs
View File

@ -1,7 +1,7 @@
#[cfg(feature = "unstable-tunnels")]
use super::*;
/// Tunnel identifier
/// Tunnel identifier.
#[cfg(feature = "unstable-tunnels")]
pub type TunnelId = AlignedU64;

4
veilid-core/src/veilid_api/types/veilid_log.rs
View File

@ -1,6 +1,6 @@
use super::*;
/// Log level for VeilidCore
/// Log level for VeilidCore.
#[derive(
Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Copy, Serialize, Deserialize, JsonSchema,
)]
@ -79,7 +79,7 @@ impl fmt::Display for VeilidLogLevel {
write!(f, "{}", text)
}
}
/// A VeilidCore log message with optional backtrace
/// A VeilidCore log message with optional backtrace.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[cfg_attr(target_arch = "wasm32", derive(Tsify))]
pub struct VeilidLog {

2
veilid-core/src/veilid_api/types/veilid_state.rs
View File

@ -1,6 +1,6 @@
use super::*;
/// Attachment abstraction for network 'signal strength'
/// Attachment abstraction for network 'signal strength'.
#[derive(Debug, PartialEq, Eq, Clone, Copy, Serialize, Deserialize, JsonSchema)]
#[cfg_attr(
target_arch = "wasm32",

36
veilid-core/src/veilid_config.rs
View File

@ -20,7 +20,7 @@ cfg_if::cfg_if! {
pub type ConfigCallbackReturn = VeilidAPIResult<Box<dyn core::any::Any + Send>>;
pub type ConfigCallback = Arc<dyn Fn(String) -> ConfigCallbackReturn + Send + Sync>;
/// Enable and configure HTTPS access to the Veilid node
/// Enable and configure HTTPS access to the Veilid node.
///
/// ```yaml
/// https:
@ -51,7 +51,7 @@ impl Default for VeilidConfigHTTPS {
}
}
/// Enable and configure HTTP access to the Veilid node
/// Enable and configure HTTP access to the Veilid node.
///
/// ```yaml
/// http:
@ -82,9 +82,9 @@ impl Default for VeilidConfigHTTP {
}
}
/// Application configuration
/// Application configuration.
///
/// Configure web access to the Progressive Web App (PWA)
/// Configure web access to the Progressive Web App (PWA).
///
/// To be implemented...
///
@ -95,7 +95,7 @@ pub struct VeilidConfigApplication {
pub http: VeilidConfigHTTP,
}
/// Enable and configure UDP
/// Enable and configure UDP.
///
/// ```yaml
/// udp:
@ -133,7 +133,7 @@ impl Default for VeilidConfigUDP {
}
}
/// Enable and configure TCP
/// Enable and configure TCP.
///
/// ```yaml
/// tcp:
@ -175,7 +175,7 @@ impl Default for VeilidConfigTCP {
}
}
/// Enable and configure Web Sockets
/// Enable and configure Web Sockets.
///
/// ```yaml
/// ws:
@ -221,7 +221,7 @@ impl Default for VeilidConfigWS {
}
}
/// Enable and configure Secure Web Sockets
/// Enable and configure Secure Web Sockets.
///
/// ```yaml
/// wss:
@ -258,7 +258,7 @@ impl Default for VeilidConfigWSS {
}
}
/// Configure Network Protocols
/// Configure Network Protocols.
///
/// Veilid can communicate over UDP, TCP, and Web Sockets.
///
@ -275,7 +275,7 @@ pub struct VeilidConfigProtocol {
pub wss: VeilidConfigWSS,
}
/// Configure TLS
/// Configure TLS.
///
/// ```yaml
/// tls:
@ -326,7 +326,7 @@ pub fn get_default_ssl_directory(sub_path: &str) -> String {
}
}
/// Configure the Distributed Hash Table (DHT)
/// Configure the Distributed Hash Table (DHT).
///
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[cfg_attr(target_arch = "wasm32", derive(Tsify))]
@ -410,7 +410,7 @@ impl Default for VeilidConfigDHT {
}
}
/// Configure RPC
/// Configure RPC.
///
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[cfg_attr(target_arch = "wasm32", derive(Tsify))]
@ -440,7 +440,7 @@ impl Default for VeilidConfigRPC {
}
}
/// Configure the network routing table
/// Configure the network routing table.
///
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[cfg_attr(target_arch = "wasm32", derive(Tsify))]
@ -721,9 +721,9 @@ pub struct VeilidConfigInner {
pub network: VeilidConfigNetwork,
}
/// The Veilid Configuration
/// The Veilid Configuration.
///
/// Veilid is configured
/// Veilid is configured.
#[derive(Clone)]
pub struct VeilidConfig {
update_cb: Option<UpdateCallback>,
@ -1223,8 +1223,8 @@ impl VeilidConfig {
Ok((node_id, node_id_secret))
}
/// Get the node id from config if one is specified
/// Must be done -after- protected store startup
/// Get the node id from config if one is specified.
/// Must be done -after- protected store startup.
#[cfg_attr(test, allow(unused_variables))]
pub async fn init_node_ids(
&self,
@ -1263,7 +1263,7 @@ impl VeilidConfig {
}
}
/// Return the default veilid config as a json object
/// Return the default veilid config as a json object.
pub fn default_veilid_config() -> String {
serialize_json(VeilidConfigInner::default())
}