Package com.ultikits.ultitools.utils

Class AgentMessageRouter

java.lang.Object

com.ultikits.ultitools.utils.AgentMessageRouter

@Internal
public final class AgentMessageRouter
extends Object

Validates envelopes and dispatches framework handlers; internal, not for module use. Handlers validate their own payloads. Synchronous validation and runtime failures become correlated errors; diagnostics never include raw payload or exception text.

The capability predicate receives contract capability names such as commands and files:read, plus the literal fromPayload:module for module.request. Integration must return true for that sentinel so the module handler can validate the payload's module identifier and answer module_not_found when no responder is owned by that module. The module handler does not check the negotiated modules:<id>@<version> capabilities; whether a request for a module the gateway did not accept is filtered is decided in 22-21. The sentinel is never declared in hello or welcome. Likewise, accept power here; its handler applies the operator switch and answers power_disabled itself.

Since:

6.3.1

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static interface	AgentMessageRouter.SwitchRefusalListener	Hears every request the capability gate refused because the operator's switch (or the handshake) does not allow it, after its correlated capability_not_accepted reply was handed to the channel (22-23 fix): the place the remote action log records that refusal as one DENIED entry.

Field Summary

Fields

Modifier and Type	Field	Description
private final Predicate<String>	capabilityEnabled
private final LongSupplier	clock
private final Map<String,CloudRequestHandler>	handlers
private final Map<String,Long>	lastWarnings
private static final Logger	LOGGER
private final Function<String,String>	refusalForCapability
private ShutdownGate	shutdown
private AgentMessageRouter.SwitchRefusalListener	switchRefusals

Constructor Summary

Constructors

Constructor	Description
AgentMessageRouter(Predicate<String> capabilityEnabled, Function<String,String> refusalForCapability)	Creates a router using the system clock for warning throttling.
AgentMessageRouter(Predicate<String> capabilityEnabled, Function<String,String> refusalForCapability, LongSupplier clock)	Creates a router with an injectable clock.

Method Summary

Modifier and Type	Method	Description
private void	dispatch(Envelope envelope, CloudChannel channel)
void	dispatch(String text, CloudChannel channel)	Parses and dispatches one frame, applying the capability gate before the handler.
private void	dispatchAdmitted(Envelope envelope, CloudChannel channel)
private void	error(CloudChannel channel, String id, String code, String message, com.google.gson.JsonObject details)
private void	error(CloudChannel channel, String id, String code, String message, com.google.gson.JsonObject details, String diagnostic)
(package private) void	onShutdown(ShutdownGate gate)	Sets the shutdown gate (ShutdownGate): from the moment it refuses, every state-changing type it covers is answered with its shutting-down failure before the switch gate or a handler sees it; a request it lets in keeps the gate's permit for the whole switch check and handler call.
(package private) void	onSwitchRefusal(AgentMessageRouter.SwitchRefusalListener listener)	Sets the listener told of each refusal by the capability gate; null removes it.
private void	refuse(CloudChannel channel, String id, String capability, String message)
void	register(String type, CloudRequestHandler handler)	Registers or replaces the handler for one frozen-contract message type.
private void	warn(String code, String diagnostic)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

LOGGER

private static final Logger LOGGER

handlers

private final Map<String,CloudRequestHandler> handlers

lastWarnings

private final Map<String,Long> lastWarnings

capabilityEnabled

private final Predicate<String> capabilityEnabled

refusalForCapability

private final Function<String,String> refusalForCapability

clock

private final LongSupplier clock

switchRefusals

private volatile AgentMessageRouter.SwitchRefusalListener switchRefusals

shutdown

private volatile ShutdownGate shutdown

Constructor Details

AgentMessageRouter

public AgentMessageRouter(Predicate<String> capabilityEnabled,
 Function<String,String> refusalForCapability)

Creates a router using the system clock for warning throttling.

Parameters:

capabilityEnabled - the per-request capability gate

refusalForCapability - supplies safe refusal text naming the configuration key

AgentMessageRouter

public AgentMessageRouter(Predicate<String> capabilityEnabled,
 Function<String,String> refusalForCapability,
 LongSupplier clock)

Creates a router with an injectable clock. Warnings are limited to one per error code per minute; rejected requests still receive their own error reply.

Parameters:

capabilityEnabled - the per-request capability gate

refusalForCapability - supplies safe refusal text, never payload or exception text

clock - supplies epoch milliseconds for warning throttling

Method Details

onSwitchRefusal

void onSwitchRefusal(AgentMessageRouter.SwitchRefusalListener listener)

Sets the listener told of each refusal by the capability gate; null removes it. A listener that throws never costs the request its reply, which was sent before the listener runs.

Parameters:

listener - the listener, or null

onShutdown

void onShutdown(ShutdownGate gate)

Sets the shutdown gate (ShutdownGate): from the moment it refuses, every state-changing type it covers is answered with its shutting-down failure before the switch gate or a handler sees it; a request it lets in keeps the gate's permit for the whole switch check and handler call. null removes it.

Parameters:

gate - the gate, or null

register

public void register(String type,
 CloudRequestHandler handler)

Registers or replaces the handler for one frozen-contract message type.

Parameters:

type - the exact registered protocol type

handler - the non-null handler, invoked on the dispatching thread

Throws:

IllegalArgumentException - if the type is not in the contract

dispatch

public void dispatch(String text,
 CloudChannel channel)

Parses and dispatches one frame, applying the capability gate before the handler. Invalid frames without a usable id are discarded at FINE; otherwise failures receive a correlated protocol error. Unhandled error, ack and welcome are ignored.

Parameters:

text - the incoming JSON text, never included in diagnostics

channel - supplies current limits and receives replies

dispatch

private void dispatch(Envelope envelope,
 CloudChannel channel)

dispatchAdmitted

private void dispatchAdmitted(Envelope envelope,
 CloudChannel channel)

refuse

private void refuse(CloudChannel channel,
 String id,
 String capability,
 String message)

error

private void error(CloudChannel channel,
 String id,
 String code,
 String message,
 com.google.gson.JsonObject details)

error

private void error(CloudChannel channel,
 String id,
 String code,
 String message,
 com.google.gson.JsonObject details,
 String diagnostic)

warn

private void warn(String code,
 String diagnostic)