Giocci.Inspect
(giocci v0.6.4)
Copy Markdown
Read-only inspection of this client and Giocci relays and engines.
Inspection does not register clients, save modules, or execute application
functions. The client application and its Zenoh session must be running, but
remote queries do not require a prior Giocci.register_client/1 call.
Module queries use this configured client name; it is not access control.
Results are snapshots and registration lists do not guarantee reachability.
Remote operations accept timeout: milliseconds (default: 5_000).
A responsive relay with no matching records returns {:ok, []}; a
communication failure does not. Remote queries require a compatible
relay or engine. Module queries describe saved relay BEAMs, not engine
distribution or execution. Multiple responses to the same inspection key
are reported as an error rather than selecting one responder.
relay_info/2 and engine_info/2 return :name, :giocci_version,
:elixir_version, :otp_release, :system_architecture, :uptime_ms
(since the target application started), and :schedulers_online (BEAM
schedulers, not allocated vCPUs). Engine information and ping query the
engine directly, without a relay name. Relay information and ping work
without registered engines. Ping measures Giocci Query/Reply round-trip
time using the client's monotonic clock; it includes waiting and response
processing, not ICMP timing.
Summary
Functions
Returns this client's name and key prefix, its Zenoh ID, and the router and peer IDs known to its own session. It does not query a relay or describe the entire network; zero connected routers can be normal in a peer setup.
Queries an engine's runtime information by engine name.
Returns the sorted, distinct engine names recorded at the specified relay.
Returns {:ok, []} if none are registered. Use ping_engine/2 to check
whether an engine responds.
Returns the saved BEAM's public callable functions as sorted
{name, arity} tuples with string names (for example, {"hello", 0}).
The module can be specified as an atom or a name returned by
list_modules/2. Default-argument arities and public callbacks are
included; private functions, macros, module_info/0,1,
__info__/1, and __struct__/0,1 are excluded. Other __-prefixed
public functions are not excluded just because of their names.
Returns the sorted, distinct module names as strings (for example,
"Elixir.MyModule") saved at a relay under this configured client name,
or {:ok, []} if none are saved.
Compares relays this client has successfully registered with each relay's current record for this client's name. The result is sorted by relay name.
Returns %{module: name, beam_sha256: hash, beam_size_bytes: size, saved_at: date_time} for this client's BEAM saved at the relay.
:module is a string even when the module argument is an atom; the
argument can also be a name returned by list_modules/2.
Queries an engine by name and returns {:ok, %{rtt_ms: milliseconds}}
when it responds.
Queries a relay directly and returns {:ok, %{rtt_ms: milliseconds}}
when it responds.
Queries the specified relay's runtime information.
Functions
Returns this client's name and key prefix, its Zenoh ID, and the router and peer IDs known to its own session. It does not query a relay or describe the entire network; zero connected routers can be normal in a peer setup.
Returns {:ok, %{client_name: name, key_prefix: prefix, zenoh_id: id, router_ids: routers, peer_ids: peers}} or {:error, reason}.
Queries an engine's runtime information by engine name.
Returns the sorted, distinct engine names recorded at the specified relay.
Returns {:ok, []} if none are registered. Use ping_engine/2 to check
whether an engine responds.
Returns the saved BEAM's public callable functions as sorted
{name, arity} tuples with string names (for example, {"hello", 0}).
The module can be specified as an atom or a name returned by
list_modules/2. Default-argument arities and public callbacks are
included; private functions, macros, module_info/0,1,
__info__/1, and __struct__/0,1 are excluded. Other __-prefixed
public functions are not excluded just because of their names.
The relay analyzes the stored BEAM without loading or running the module.
Returns {:error, "module_not_found"} for a missing saved module or
{:error, "invalid_beam"} if its BEAM cannot be analyzed.
Returns the sorted, distinct module names as strings (for example,
"Elixir.MyModule") saved at a relay under this configured client name,
or {:ok, []} if none are saved.
The list is based on the relay's stored BEAMs, not the client's loaded
code. Names can be passed directly to list_functions/3 or
module_info/3. Other connections using the same client name share
the stored namespace.
Compares relays this client has successfully registered with each relay's current record for this client's name. The result is sorted by relay name.
Returns {:ok, []} if there is no local history, {:ok, confirmed_relays}
if all candidates agree, {:warn, confirmed_relays, issues} if some
agree, or {:error, issues} if none can be confirmed. Each issue has
%{relay: name, reason: reason}; a relay that responds without this
client's registration reports "client_not_registered", while a relay
without a response reports its timeout or connection error.
:timeout applies separately to each candidate relay (default: 5_000 ms).
Returns %{module: name, beam_sha256: hash, beam_size_bytes: size, saved_at: date_time} for this client's BEAM saved at the relay.
:module is a string even when the module argument is an atom; the
argument can also be a name returned by list_modules/2.
beam_sha256 is the lowercase hexadecimal SHA-256 of the entire BEAM,
beam_size_bytes is its size in bytes, and saved_at is a UTC
DateTime from the relay's clock. It records the last successful relay
save, including identical re-saves; inspection and distribution to a
later-registered engine do not update it. Engine distribution failures
do not undo a successful relay save. Functions are available separately
via list_functions/3.
Returns {:error, "module_not_found"} if the module is not saved under
this client name, or {:error, "invalid_beam"} for an invalid saved BEAM.
Queries an engine by name and returns {:ok, %{rtt_ms: milliseconds}}
when it responds.
Queries a relay directly and returns {:ok, %{rtt_ms: milliseconds}}
when it responds.
Queries the specified relay's runtime information.