rns_net/common/

callbacks.rs

//! Application callback trait for driver events.

use crate::{DestHash, IdentityHash, InterfaceId, LinkId, PacketHash, TeardownReason};

/// Names a packet queued with `RnsNode::send_packet_deferred` until
/// [`Callbacks::on_packet_sent`] reports its hash.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct SendTicket(pub u64);

pub trait Callbacks: Send {
    fn on_announce(&mut self, announced: crate::common::destination::AnnouncedIdentity);

    fn on_path_updated(&mut self, dest_hash: DestHash, hops: u8);

    fn on_local_delivery(&mut self, dest_hash: DestHash, raw: Vec<u8>, packet_hash: PacketHash);

    /// Called when an interface comes online.
    fn on_interface_up(&mut self, _id: InterfaceId) {}

    /// Called when an interface goes offline.
    fn on_interface_down(&mut self, _id: InterfaceId) {}

    /// Called when a link is fully established.
    fn on_link_established(
        &mut self,
        _link_id: LinkId,
        _dest_hash: DestHash,
        _rtt: f64,
        _is_initiator: bool,
    ) {
    }

    /// Called when a link is closed.
    fn on_link_closed(&mut self, _link_id: LinkId, _reason: Option<TeardownReason>) {}

    /// Called when a remote peer identifies on a link.
    fn on_remote_identified(
        &mut self,
        _link_id: LinkId,
        _identity_hash: IdentityHash,
        _public_key: [u8; 64],
    ) {
    }

    /// Called when a resource transfer delivers data.
    fn on_resource_received(
        &mut self,
        _link_id: LinkId,
        _data: Vec<u8>,
        _metadata: Option<Vec<u8>>,
    ) {
    }

    /// Called when a resource transfer delivers data, with the application
    /// flag the sender set in the advertisement. The default ignores the flag
    /// and forwards to [`Callbacks::on_resource_received`].
    fn on_resource_received_with_app_flag(
        &mut self,
        link_id: LinkId,
        data: Vec<u8>,
        metadata: Option<Vec<u8>>,
        _app_flag: bool,
    ) {
        self.on_resource_received(link_id, data, metadata);
    }

    /// Called when a resource transfer completes (sender-side proof validated).
    fn on_resource_completed(&mut self, _link_id: LinkId) {}

    /// Called when a resource transfer fails.
    fn on_resource_failed(&mut self, _link_id: LinkId, _error: String) {}

    /// Called with resource transfer progress updates.
    fn on_resource_progress(&mut self, _link_id: LinkId, _received: usize, _total: usize) {}

    /// Called when a streaming Resource completes on the sender side.
    fn on_resource_stream_completed(
        &mut self,
        _link_id: LinkId,
        _transfer_id: crate::resource::ResourceTransferId,
    ) {
    }

    /// Called when a streaming Resource fails.
    fn on_resource_stream_failed(
        &mut self,
        _link_id: LinkId,
        _transfer_id: crate::resource::ResourceTransferId,
        _error: crate::resource::ResourceTransferError,
    ) {
    }

    /// Called with logical-byte progress for a streaming Resource.
    fn on_resource_stream_progress(
        &mut self,
        _link_id: LinkId,
        _transfer_id: crate::resource::ResourceTransferId,
        _transferred: u64,
        _total: u64,
    ) {
    }

    /// Called with each verified segment of an incoming Resource received
    /// in [`ResourceReceiveMode::Stream`](crate::resource::ResourceReceiveMode::Stream),
    /// in order: `offset` is where `data` starts in the Resource.
    fn on_resource_segment(
        &mut self,
        _link_id: LinkId,
        _original_hash: [u8; 32],
        _offset: u64,
        _data: Vec<u8>,
    ) {
    }

    /// Called when an incoming Resource received in
    /// [`ResourceReceiveMode::Stream`](crate::resource::ResourceReceiveMode::Stream)
    /// has been delivered in full.
    fn on_resource_stream_received(
        &mut self,
        _link_id: LinkId,
        _resource: crate::resource::ReceivedResourceStream,
    ) {
    }

    /// Called when a disk-backed incoming Resource is ready.
    fn on_resource_file_received(
        &mut self,
        _link_id: LinkId,
        _resource: crate::resource::ReceivedResourceFile,
    ) {
    }

    /// Called to ask whether to accept an incoming resource (for AcceptApp strategy).
    /// Return true to accept, false to reject.
    fn on_resource_accept_query(
        &mut self,
        _link_id: LinkId,
        _resource_hash: Vec<u8>,
        _transfer_size: u64,
        _has_metadata: bool,
    ) -> bool {
        false
    }

    /// Called to ask whether to accept an incoming resource (for AcceptApp
    /// strategy), with the application flag set in its advertisement
    /// (Python `ResourceAdvertisement.app_flag_set()`). The default ignores
    /// the flag and forwards to [`Callbacks::on_resource_accept_query`].
    fn on_resource_accept_query_with_app_flag(
        &mut self,
        link_id: LinkId,
        resource_hash: Vec<u8>,
        transfer_size: u64,
        has_metadata: bool,
        _app_flag: bool,
    ) -> bool {
        self.on_resource_accept_query(link_id, resource_hash, transfer_size, has_metadata)
    }

    /// Called when a channel message is received on a link.
    fn on_channel_message(&mut self, _link_id: LinkId, _msgtype: u16, _payload: Vec<u8>) {}

    /// Called when generic link data is received.
    fn on_link_data(&mut self, _link_id: LinkId, _context: u8, _data: Vec<u8>) {}

    /// Called when a response is received on a link.
    fn on_response(&mut self, _link_id: LinkId, _request_id: [u8; 16], _data: Vec<u8>) {}

    /// Called when a response is received on a link, including resource metadata when present.
    fn on_response_with_metadata(
        &mut self,
        link_id: LinkId,
        request_id: [u8; 16],
        data: Vec<u8>,
        _metadata: Option<Vec<u8>>,
    ) {
        self.on_response(link_id, request_id, data);
    }

    /// Called when a request response is rejected.
    fn on_request_failed(
        &mut self,
        _link_id: LinkId,
        _request_id: [u8; 16],
        _reason: crate::link_manager::RequestFailure,
    ) {
    }

    /// Called for a packet queued with `RnsNode::send_packet_deferred` once it
    /// is encrypted, before it is sent: its hash, which a proof of it will
    /// carry, or `None` when it could not be encrypted or the node is
    /// shutting down, and it was not sent.
    fn on_packet_sent(&mut self, _ticket: SendTicket, _packet_hash: Option<PacketHash>) {}

    /// Called with the plaintext of a single packet for a destination that
    /// delivers decrypted (`RnsNode::deliver_decrypted`), in place of
    /// [`on_local_delivery`](Self::on_local_delivery). Packets that do not
    /// decrypt are dropped, and not proved. Decrypted on several threads,
    /// packets may be reported out of arrival order.
    fn on_packet_received(
        &mut self,
        _dest_hash: DestHash,
        _data: Vec<u8>,
        _packet_hash: PacketHash,
    ) {
    }

    /// Called when a delivery proof is received for a packet we sent.
    /// `rtt` is the round-trip time in seconds.
    fn on_proof(&mut self, _dest_hash: DestHash, _packet_hash: PacketHash, _rtt: f64) {}

    /// Called for ProveApp strategy: should we prove this incoming packet?
    /// Return true to generate and send a proof, false to skip.
    fn on_proof_requested(&mut self, _dest_hash: DestHash, _packet_hash: PacketHash) -> bool {
        true
    }

    /// Called when a direct connection is proposed by a peer (for AskApp policy).
    /// Return true to accept, false to reject.
    fn on_direct_connect_proposed(
        &mut self,
        _link_id: LinkId,
        _peer_identity: Option<IdentityHash>,
    ) -> bool {
        false
    }

    /// Called when a direct P2P connection is established via hole punching.
    fn on_direct_connect_established(&mut self, _link_id: LinkId, _interface_id: InterfaceId) {}

    /// Called when a direct connection attempt fails.
    fn on_direct_connect_failed(&mut self, _link_id: LinkId, _reason: u8) {}
}