aion/query
Typed query handler registration and replies.
Values
pub fn dispatch(
name: String,
value_codec: codec.Codec(value),
) -> Result(value, error.QueryError)Dispatch a typed query through the in-engine/client-side binding.
This helper exists for callers already inside the engine boundary and for the
pure Gleam test harness. It asks AT’s query service for the named handler,
then decodes the encoded reply with the supplied codec. An unregistered name
returns Error(UnknownQuery(name)); malformed replies return
Error(QueryDecodeFailed(_)). Query dispatch records no workflow event.
pub fn handler(
name: String,
value_codec: codec.Codec(value),
reply: fn() -> value,
) -> Result(Nil, error.QueryError)Register a typed read-only query handler with AT’s query service.
The handler’s return type is fixed by the Codec(a) supplied at
registration. When the engine dispatches a query with this name, the SDK
invokes reply, encodes the returned value with the codec, and replies on the
engine-provided one-shot reply channel. Query return values never cross the
FFI boundary without a codec.
Registration stores the encoding handler in the workflow process
dictionary (the engine-contract location the yield-point query pump reads
from) and then registers the name with the engine. Register before the
first yield point — workflow.sleep, workflow.receive, workflow.run
— that should answer the query; awaits reached earlier cannot service it.
Because workflow code re-executes from the top on replay, re-registration
after recovery is automatic: a recovered workflow answers queries without
any extra author code.
Queries bind to AT’s read-only query service: they append no workflow Event,
are answered at engine yield points, and never block workflow progress. By
type this callback only returns a value; by workflow-author convention it must
not call activity-dispatch primitives such as workflow.run or otherwise
mutate workflow state — the engine refuses recording calls made while a
query is being serviced, surfacing them as a typed handler failure.
pub fn recorded_observations() -> Result(Int, error.QueryError)Return the test/engine observation count reported by the backing query service.
Production engines may expose this as diagnostic data; the shipped test double uses it to assert that query dispatch does not append recorded observations or history events.