Struct Gateway 

pub struct Gateway { /* private fields */ }

Connectivity boundary for one or more procs.

Implementations

impl Gateway

pub fn new() -> Self

Create a fresh unserved gateway with dial-based forwarding.

pub fn isolated() -> Self

Create a fresh unserved local-only gateway.

pub fn global() -> &'static Self

Return the process-wide global gateway.

pub fn current() -> Self

Return the gateway for the current execution context.

This is the gateway attached to Proc::current().

pub fn uid(&self) -> &Uid

This gateway’s stable uid. Peers route messages back to procs attached here by addressing them as Location::Via(this_uid, inner).

pub fn default_location(&self) -> Location

The gateway’s default advertised location.

pub fn forwarder(&self) -> BoxedMailboxSender

The outbound forwarder. Inbound traffic for destinations that don’t match a bound proc, route, or via peer is handed off to this sender.

pub fn set_default_location(&self, location: Location)

Set the gateway’s fallback advertised location.

If any serves are active, the newest active normal serve or Gateway::serve_via session remains the advertised default. This location is used once all active serves stop.

pub fn attach_peer( &self, uid: Uid, sender: BoxedMailboxSender, ) -> Result<PeerAttachGuard, PeerAttachError>

Register a gateway peer that is reachable through sender. Messages whose destination location has an outermost Location::Via hop carrying uid are forwarded through sender after peeling the hop. The returned guard removes the entry on drop.

Used by [Gateway::attach] and the duplex accept loop in Gateway::serve_duplex. Hosts also use this for spawned child proc gateways.

Returns PeerAttachError if a peer with the same uid is already attached.

pub fn serve( &self, addr: ChannelAddr, ) -> Result<GatewayServeHandle, ChannelError>

Serve this gateway on the provided channel address.

When serving the first local ChannelAddr::any address, the gateway binds the local address that was reserved when the gateway was created. Local reservation is separate from local binding so a gateway can have a stable location before it has a runtime available to run a server. Later local any serves allocate fresh local ports, so the gateway can have multiple active local servers.

Serving updates the gateway’s default location to the newly served address. When that server stops, the default location falls back to the previous active normal serve or serve_via session, or to the reserved fallback location when no serve remains.

pub fn serve_duplex( &self, addr: ChannelAddr, ) -> Result<GatewayServeHandle, ChannelError>

Open a duplex endpoint that accepts both regular inbound envelope traffic and gateway-attach handshakes from peers.

On each connection the first message determines the branch:

• an [AttachRequest] control envelope enters the attach branch — this gateway records the peer’s uid in peers (so source routes addressed to Via(peer_uid, ...) flow back through the duplex), replies with [AttachAck::Accepted] carrying Via(peer_uid, default_location), and serves remaining traffic from the duplex into this gateway. If the peer cannot be registered, it replies with [AttachAck::Rejected] and closes the connection.
• a regular MessageEnvelope enters the inbound branch and is served straight through.

Returns a GatewayServeHandle of kind ServeDuplex. The accept loop respects .stop("reason").

Errors if addr’s transport cannot carry the duplex protocol (e.g. local transport). Callers that may be handed a non-duplex address should branch on ChannelTransport::supports_duplex and use [serve] instead.

pub fn serve_mux_with_listener( &self, addr: ChannelAddr, listener: Option<TcpListener>, ) -> Result<GatewayServeHandle, ChannelError>

Serve this gateway on addr (optionally with a pre-bound TCP listener) using a muxed listener: simplex clients (dialed via channel::dial) and duplex attach clients (dialed via channel::duplex::dial) share one address, demultiplexed at the link layer by channel::serve_mux.

Simplex traffic is served straight into this gateway; duplex connections run the same [AttachWire] accept path as serve_duplex — i.e. there is a single attach protocol regardless of whether a frontend is muxed or a plain duplex endpoint. Requires a net transport (serve_mux rejects non-net addresses).

Like serve_with_listener, this registers the bound address as an active serve location (so the gateway delivers frontend-addressed traffic in-process and adopts it as the default location).

pub fn serve_with_listener( &self, addr: ChannelAddr, listener: Option<TcpListener>, ) -> Result<GatewayServeHandle, ChannelError>

Serve this gateway on addr, optionally using an already-bound listener.

This chooses a duplex accept loop for duplex-capable transports and a simplex mailbox receiver otherwise. Serving updates the gateway’s advertised default location to the concrete bound address. Callers that need to construct procs using that address can call Gateway::default_location after this returns.

pub async fn serve_via(&self, addr: ChannelAddr) -> Result<GatewayServeHandle>

Connect this gateway to a peer gateway’s [serve_duplex] endpoint using the attach handshake.

Dials addr, sends this gateway’s uid as [AttachRequest], receives [AttachAck::Accepted] with the via location the peer assigned, sets that location as this gateway’s [default_location] (so every address handed out by this gateway carries the via prefix), installs the duplex sender as this gateway’s outbound forwarder, and serves inbound traffic from the duplex locally. If the peer returns [AttachAck::Rejected], the rejection reason is returned as an error.

Multiple serve_via sessions may be active. The newest active normal serve or serve_via session is this gateway’s advertised default location, while older active locations remain valid. The newest active serve_via supplies the outbound forwarder.

Trait Implementations

impl Clone for Gateway

fn clone(&self) -> Gateway

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Gateway

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

Formats the value using the given formatter.

impl MailboxSender for Gateway

fn post_unchecked( &self, envelope: MessageEnvelope, return_handle: PortHandle<Undeliverable<MessageEnvelope>>, )

Raw transport: no policy.

fn flush<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Wait until all messages previously posted through this sender have been delivered (wire-acked) or confirmed undeliverable. The default implementation is a no-op, appropriate for senders whose post is synchronous (e.g. local in-process delivery).

fn post( &self, envelope: MessageEnvelope, return_handle: PortHandle<Undeliverable<MessageEnvelope>>, )

Apply hop semantics (TTL decrement; undeliverable on 0), then delegate to transport.