Struct veilid_core::RoutingContext

pub struct RoutingContext { /* private fields */ }

Routing contexts are the way you specify the communication preferences for Veilid.

By default routing contexts have ‘safety routing’ enabled which offers sender privacy. privacy. To disable this and send RPC operations straight from the node use RoutingContext::with_safety() with a SafetySelection::Unsafe parameter. To enable receiver privacy, you should send to a private route RouteId that you have imported, rather than directly to a NodeId.

Implementations

impl RoutingContext

pub fn with_default_safety(self) -> VeilidAPIResult<Self>

Turn on sender privacy, enabling the use of safety routes. This is the default and calling this function is only necessary if you have previously disable safety or used other parameters.

Default values for hop count, stability and sequencing preferences are used.

• 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

To customize the safety selection in use, use RoutingContext::with_safety().

pub fn with_safety( self, safety_selection: SafetySelection ) -> VeilidAPIResult<Self>

Use a custom SafetySelection. Can be used to disable safety via SafetySelection::Unsafe

pub fn with_sequencing(self, sequencing: Sequencing) -> Self

Use a specified Sequencing preference, with or without privacy

pub fn safety(&self) -> SafetySelection

Get the safety selection in use on this routing context

pub fn api(&self) -> VeilidAPI

Get the VeilidAPI object that created this RoutingContext

pub async fn app_call( &self, target: Target, message: Vec<u8> ) -> VeilidAPIResult<Vec<u8>>

App-level bidirectional call that expects a response to be returned.

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

Returns an answer blob of up to 32768 bytes

pub async fn app_message( &self, target: Target, message: Vec<u8> ) -> VeilidAPIResult<()>

App-level unidirectional message that does not expect any value to be returned.

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

pub async fn create_dht_record( &self, schema: DHTSchema, kind: Option<CryptoKind> ) -> VeilidAPIResult<DHTRecordDescriptor>

DHT Records Creates a new DHT record a specified crypto kind and schema

The record is considered ‘open’ after the create operation succeeds.

Returns the newly allocated DHT record’s key if successful.

pub async fn open_dht_record( &self, key: TypedKey, default_writer: Option<KeyPair> ) -> VeilidAPIResult<DHTRecordDescriptor>

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.

Records may only be opened or created. If a record is re-opened it will use the new writer and routing context ignoring the settings of the last time it was opened. This allows one to open a record a second time 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

pub async fn close_dht_record(&self, key: TypedKey) -> VeilidAPIResult<()>

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

pub async fn delete_dht_record(&self, key: TypedKey) -> VeilidAPIResult<()>

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 locally, and will prevent its value from being refreshed on the network by this node.

pub async fn get_dht_value( &self, key: TypedKey, subkey: ValueSubkey, force_refresh: bool ) -> VeilidAPIResult<Option<ValueData>>

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

Returns None if the value subkey has not yet been set Returns Some(data) if the value subkey has valid data

pub async fn set_dht_value( &self, key: TypedKey, subkey: ValueSubkey, data: Vec<u8>, writer: Option<KeyPair> ) -> VeilidAPIResult<Option<ValueData>>

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

pub async fn watch_dht_values( &self, key: TypedKey, subkeys: ValueSubkeyRangeSet, expiration: Timestamp, count: u32 ) -> VeilidAPIResult<Timestamp>

Add or update a watch to a DHT value that informs the user via an VeilidUpdate::ValueChange callback when the record has subkeys change. One remote node will be selected to perform the watch and it will offer an expiration time based on a suggestion, and make an attempt to continue to report changes via the callback. Nodes that agree to doing watches will be put on our ‘ping’ list to ensure they are still around otherwise the watch will be cancelled and will have to be re-watched.

There is only one watch permitted per record. If a change to a watch is desired, the previous one will be overwritten.

• key is the record key to watch. it must first be opened for reading or writing.
• subkeys is the the range of subkeys to watch. The range must not exceed 512 discrete non-overlapping or adjacent subranges. If no range is specified, this is equivalent to watching the entire range of subkeys.
• expiration is the desired timestamp of when to automatically terminate the watch, in microseconds. If this value is less than network.rpc.timeout_ms milliseconds in the future, this function will return an error immediately.
• count is the number of times the watch will be sent, maximum. A zero value here is equivalent to a cancellation.

Returns a timestamp of when the watch will expire. All watches are guaranteed to expire at some point in the future, and the returned timestamp will be no later than the requested expiration, but -may- be before the requested expiration. 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

Members can be specified via the SMPL schema and do not need to allocate writable subkeys in order to offer a member watch capability.

pub async fn cancel_dht_watch( &self, key: TypedKey, subkeys: ValueSubkeyRangeSet ) -> VeilidAPIResult<bool>

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

pub async fn inspect_dht_record( &self, key: TypedKey, subkeys: ValueSubkeyRangeSet, scope: DHTReportScope ) -> VeilidAPIResult<DHTRecordReport>

Inspects a DHT record for subkey state. This is useful for checking if you should push new subkeys to the network, or retrieve the current state of a record from the network to see what needs updating locally.

• key is the record key to watch. it must first be opened for reading or writing.

• subkeys is the the range of subkeys to inspect. The range must not exceed 512 discrete non-overlapping or adjacent subranges. If no range is specified, this is equivalent to inspecting the entire range of subkeys. In total, the list of subkeys returned will be truncated at 512 elements.

• scope is what kind of range the inspection has:

  • 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

  • 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 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 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 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

  • 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 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

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.

Trait Implementations

impl Clone for RoutingContext

fn clone(&self) -> RoutingContext

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for RoutingContext

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

Formats the value using the given formatter.