Struct MeshAdminAgent 

pub struct MeshAdminAgent { /* private fields */ }

Actor that serves a mesh-level admin HTTP endpoint.

MeshAdminAgent is the mesh-wide aggregation point for introspection: it holds hyperactor_reference::ActorRef<HostAgent> handles for each host, and answers admin queries by forwarding targeted requests to the appropriate host agent and assembling a uniform NodePayload response for the client.

The agent also exposes an HTTP server (spawned from init) and supports reference-based navigation (GET /v1/{reference}) by resolving opaque reference strings into typed NodeProperties plus child references.

Implementations

impl MeshAdminAgent

pub fn new( hosts: Vec<(String, ActorRef<HostAgent>)>, root_client_actor_id: Option<ActorId>, admin_addr: Option<SocketAddr>, ) -> Self

Construct a MeshAdminAgent from a list of (host_addr, host_agent_ref) pairs and an optional root client ActorId.

Builds both:

• hosts: the forward map used to route admin queries to the correct HostAgent, and
• host_agents_by_actor_id: a reverse index used during reference resolution to recognize host-agent ActorIds and resolve them as NodeProperties::Host rather than as generic actors.

When root_client_actor_id is Some, the root client appears as a first-class child of the root node in the introspection tree.

The HTTP listen address is initialized to None and populated during init() after the server socket is bound.

Trait Implementations

impl Actor for MeshAdminAgent

fn init<'life0, 'life1, 'async_trait>( &'life0 mut self, this: &'life1 Instance<Self>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

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

Initializes the mesh admin agent and its HTTP server.

1. Binds well-known message ports (proc.spawn() does not call bind() — unlike gspawn — so the actor must do it itself before becoming reachable).
2. Binds a TCP listener (ephemeral or fixed port).
3. Builds a TLS acceptor (explicit env vars, then Meta default paths). At Meta (fbcode_build), mTLS is mandatory and init fails if no certs are found. In OSS, falls back to plain HTTP.
4. Creates a dedicated Instance<()> client mailbox on system_proc for the HTTP bridge’s reply ports, keeping bridge traffic off the actor’s own mailbox.
5. Spawns the axum server in a background task (HTTPS with mTLS at Meta, HTTPS or HTTP in OSS depending on step 3).

The hostname-based listen address is stored in admin_host so it can be returned via GetAdminAddr. The scheme (https:// or http://) is included so clients know which protocol to use.

fn handle_undeliverable_message<'life0, 'life1, 'async_trait>( &'life0 mut self, _cx: &'life1 Instance<Self>, __arg2: Undeliverable<MessageEnvelope>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

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

Swallow undeliverable message bounces instead of crashing.

The admin agent sends IntrospectMessage to actors that may not have the introspection port bound (e.g. actors spawned via cx.spawn() whose #[export] list does not include it). When the message cannot be delivered, the routing layer bounces an Undeliverable back to the sender. The default Actor::handle_undeliverable_message calls bail!(), which would kill this admin agent and — via supervision cascade — take down the entire admin process with exit(1).

Since the admin agent is best-effort infrastructure, an undeliverable introspection probe is not a fatal error.

fn cleanup<'life0, 'life1, 'life2, 'async_trait>( &'life0 mut self, _this: &'life1 Instance<Self>, _err: Option<&'life2 ActorError>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Cleanup things used by this actor before shutting down. Notably this function is async and allows more complex cleanup. Simpler cleanup can be handled by the impl Drop for this Actor. If err is not None, it is the error that this actor is failing with. Any errors returned by this function will be logged and ignored. If err is None, any errors returned by this function will be propagated as an ActorError. This function is not called if there is a panic in the actor, as the actor may be in an indeterminate state. It is also not called if the process is killed, there is no atexit handler or signal handler.

fn spawn(self, cx: &impl Actor) -> Result<ActorHandle<Self>, Error>

Spawn a child actor, given a spawning capability (usually given by Instance). The spawned actor will be supervised by the parent (spawning) actor.

fn spawn_with_name( self, cx: &impl Actor, name: &str, ) -> Result<ActorHandle<Self>, Error>

Spawn a named child actor. Same supervision semantics as spawn, but the child gets name in its ActorId.

fn spawn_detached(self) -> Result<ActorHandle<Self>, Error>

Spawns this actor in a detached state, handling its messages in a background task. The returned handle is used to control the actor’s lifecycle and to interact with it.

fn spawn_server_task<F>(future: F) -> JoinHandle<<F as Future>::Output>

where F: Future + Send + 'static, <F as Future>::Output: Send + 'static,

This method is used by the runtime to spawn the actor server. It can be used by actors that require customized runtime setups (e.g., dedicated actor threads), or want to use a custom tokio runtime.

fn handle_supervision_event<'life0, 'life1, 'life2, 'async_trait>( &'life0 mut self, _this: &'life1 Instance<Self>, _event: &'life2 ActorSupervisionEvent, ) -> Pin<Box<dyn Future<Output = Result<bool, Error>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Handle actor supervision event. Return `Ok(true)`` if the event is handled here.

fn display_name(&self) -> Option<String>

If overridden, we will use this name in place of the ActorId for talking about this actor in supervision error messages.

impl Binds<MeshAdminAgent> for MeshAdminAgent

fn bind(ports: &Ports<Self>)

Bind ports in this actor.

impl Debug for MeshAdminAgent

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

Formats the value using the given formatter.

impl Handler<MeshAdminMessage> for MeshAdminAgent

Manual Handler impl — swallows reply.send() failures so the admin agent stays alive when the HTTP caller disconnects.

fn handle<'life0, 'life1, 'async_trait>( &'life0 mut self, cx: &'life1 Context<'_, Self>, msg: MeshAdminMessage, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

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

Dispatches MeshAdminMessage variants.

Reply-send failures are swallowed because a dropped receiver (e.g. the HTTP bridge timed out) is not an error — the caller simply went away. Propagating the failure would crash the admin agent and take down the entire process.

impl Handler<ResolveReferenceMessage> for MeshAdminAgent

Manual Handler impl — swallows reply.send() failures so the admin agent stays alive when the HTTP caller disconnects.

fn handle<'life0, 'life1, 'async_trait>( &'life0 mut self, cx: &'life1 Context<'_, Self>, msg: ResolveReferenceMessage, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

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

Dispatches ResolveReferenceMessage variants.

The inner resolve_reference call never returns Err to the handler — failures are captured in the response payload. Reply-send failures are swallowed for the same reason as MeshAdminMessage: a dropped receiver means the caller (HTTP bridge) went away, which must not crash the admin agent.

impl Named for MeshAdminAgent

fn typename() -> &'static str

The globally unique type name for the type. This should typically be the fully qualified Rust name of the type.

fn typehash() -> u64

A globally unique hash for this type. TODO: actually enforce perfect hashing

fn typeid() -> TypeId

The TypeId for this type. TypeIds are unique only within a binary, and should not be used for global identification.

fn port() -> u64

The globally unique port for this type. Typed ports are in the range of 1<<63..1<<64-1.

fn arm(&self) -> Option<&'static str>

If the named type is an enum, this returns the name of the arm of the value self.

unsafe fn arm_unchecked(self_: *const ()) -> Option<&'static str>

An unsafe version of ‘arm’, accepting a pointer to the value, for use in type-erased settings.

impl Accepts<IntrospectMessage> for MeshAdminAgent

impl Accepts<MeshAdminMessage> for MeshAdminAgent

impl Accepts<ResolveReferenceMessage> for MeshAdminAgent

impl Accepts<Signal> for MeshAdminAgent

impl Referable for MeshAdminAgent

impl RemoteHandles<IntrospectMessage> for MeshAdminAgent

impl RemoteHandles<MeshAdminMessage> for MeshAdminAgent

impl RemoteHandles<ResolveReferenceMessage> for MeshAdminAgent

impl RemoteHandles<Signal> for MeshAdminAgent