Struct Puncher 

pub struct Puncher { /* private fields */ }

One device’s boot subscription and one explicitly observed opening attempt.

Implementations

impl Puncher

pub fn rebind_broker(&mut self, broker: WireBroker) -> Result<(), PunchError>

A new open or recovery gets fresh admitted control streams after an outage.

Errors

The replacement broker did not admit the device’s own subscription.

pub fn prepare_open(&mut self) -> Result<(), PunchError>

A later open observes once on the retained socket; idle never calls this.

Errors

The echo or broker refused the new opening’s observation.

pub fn shared_carrier(&self) -> Result<Arc<UdpCarrier>, PunchError>

Shares the device’s one receive worker with its direct paths.

Errors

The device has not observed its socket.

pub fn lookup_addresses( &mut self, peer: MachineIdentity, ) -> Result<Vec<String>, PunchError>

Reads the configured peer’s registered wire addresses once.

Errors

Broker refusal or malformed lookup answer.

pub fn refresh( &mut self, peer: MachineIdentity, index: u32, ) -> Result<(), PunchError>

Reopens the mapping while retaining the keyed link and all message counters.

Errors

The broker or peer refused the refreshed mapping.

pub fn accept_refresh( &mut self, peer: MachineIdentity, index: u32, ) -> Result<(), PunchError>

Answers a mapping refresh without a second KK handshake.

Errors

Invalid broker word, probe failure, or unknown keyed link.

pub fn punch( &mut self, peer: MachineIdentity, index: u32, ) -> Result<PunchedLink, PunchError>

Opens the NAT mapping, requests the peer, then follows its return word.

Errors

Refuses unavailable observations, broker failures, invalid words or KK proof.

pub fn accept( &mut self, peer: MachineIdentity, index: u32, ) -> Result<PunchedLink, PunchError>

Answers the broker’s word after sending a mapping-opening probe.

Errors

Refuses unexpected words, broker failures or an unauthenticated KK peer.

pub fn carrier(&self) -> Result<&UdpCarrier, PunchError>

The shared carrier holding completed direct links.

Errors

Refuses use before a successful observation.

impl Puncher

pub fn fork_listener( &self, local: LocalMachine, broker: WireBroker, ) -> Result<Self, PunchError>

Shares the existing device socket while admitting a separate incoming subscription.

Errors

Subscription admission or socket setup failed.

pub fn next_instruction(&mut self) -> Result<Instruction, PunchError>

Parks on a broker instruction with no idle timer.

Errors

The broker ended or supplied an invalid instruction.

pub fn answer_instruction( &mut self, word: &Instruction, index: u32, refresh: bool, ) -> Result<(), PunchError>

Answers one recorded peer instruction using the existing socket and counters.

Errors

Broker refusal, probe failure, or the peer’s KK proof failed.

impl Puncher

pub fn boot( local: LocalMachine, socket: Arc<dyn PunchSocket>, broker: WireBroker, echo: SocketAddr, bound: Duration, ) -> Result<Self, PunchError>

Subscribes before registration or any request can publish a word.

Errors

Refuses invalid bounds/endpoints or an unadmitted subscription.

pub fn observe(&mut self) -> Result<SocketAddr, PunchError>

Sends one echo. A lost answer ends this attempt by name, without retry.

Errors

Refuses a repeated observation, an unanswered/invalid echo or socket failure.

pub fn register(&mut self) -> Result<(), PunchError>

Registers this attempt’s echo address, with no invented reachable address.

Errors

Refuses missing observation or a broker registration refusal.

pub fn request_punch( &mut self, peer: MachineIdentity, nonce: &str, ) -> Result<(), PunchError>

Publishes one instruction through the admitted broker control path.

Errors

Refuses self-punching, invalid keys/nonces, or a broker refusal.