Struct 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 reliable routes, preferring them over low latency.
• 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 sequencing(&self) -> Sequencing

Get the sequencing used by 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 - a private route id
• 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 - a private route.
• message - an arbitrary message blob of up to 32768 bytes.

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

Creates a new DHT record

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

• ‘kind’ - specify a cryptosystem kind to use
• ‘schema’ - the schema to use when creating the DHT record
• ‘owner’ - optionally specify an owner keypair to use. If you leave this as None then a random one will be generated. If specified, the crypto kind of the owner must match that of the kind parameter

Returns the newly allocated DHT record’s key if successful. Note: if you pass in an owner keypair this call is a deterministic! This means that if you try to create a new record for a given owner and schema that already exists it will fail.

pub async fn open_dht_record( &self, record_key: RecordKey, 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, record_key: RecordKey, ) -> 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, record_key: RecordKey, ) -> 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, record_key: RecordKey, 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. Can only be used on opened records.

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, record_key: RecordKey, subkey: ValueSubkey, data: Vec<u8>, options: Option<SetDHTValueOptions>, ) -> 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 set. Returns Some(data) if the value set was older than the one available on the network.

pub async fn watch_dht_values( &self, record_key: RecordKey, subkeys: Option<ValueSubkeyRangeSet>, expiration: Option<Timestamp>, count: Option<u32>, ) -> VeilidAPIResult<bool>

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. Can only be used on opened records.

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:
  • None: specifies watching the entire range of subkeys.
  • Some(range): 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:
  • None: specifies a watch with no expiration
  • Some(timestamp): 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:
  • None: specifies a watch count of u32::MAX
  • Some(count): is the number of times the watch will be sent, maximum. A zero value here is equivalent to a cancellation.

Returns Ok(true) if a watch is active for this record. Returns Ok(false) if the entire watch has been 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, record_key: RecordKey, subkeys: Option<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 currently-watched subkey range. Can only be used on opened records.

• subkeys:
  • None: specifies watching the entire range of subkeys.
  • Some(range): 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.

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 a watch is active for this record. Returns Ok(false) if the entire watch has been cancelled.

pub async fn inspect_dht_record( &self, record_key: RecordKey, subkeys: Option<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. Can only be used on opened records.

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

• subkeys:

  • None: specifies inspecting the entire range of subkeys.
  • Some(range): 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 watching the entire range of subkeys.

• 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 Ok(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 duplicate 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.