Requests the server sends to the client.
A callback (tool.call/2, resource.read/2, prompt.get/2, a task tool)
can ask the client something while it runs: ping/2 and the client
features built on request/4, which OzMcp.Client wraps (sampling,
elicitation, roots). The guide about the requests to the client
describes each method with an example.
request/4 sends one JSON-RPC request and blocks the calling process
until the client answers, the timeout elapses, or the session ends:
case OzMcp.Outbound.ping(ctx) do
{:ok, %{}} -> :alive
{:error, reason} -> {:unreachable, reason}
endResults
{:ok, result} when the client answered (a map). A failure gives one
of these errors: {:error, {:rpc_error, error}} (the client answered
with a JSON-RPC error), {:error, :timeout}, {:error, :session_terminated}, {:error, :session_not_found},
{:error, :capability_not_supported}, {:error, :unsupported_method},
{:error, :not_encodable}, {:error, :no_task}, {:error, :no_stream}
and {:error, :session_not_initialized}. request_task/4 adds
{:error, :client_tasks_disabled} (the runtime option client_tasks
is false, the default), {:error, {:client_task_cancelled, task_id}}
and {:error, {:invalid_response, result}}. The guide about the
requests to the client gives the meaning of each error and the option
:wait_for_stream of the :no_stream case.
Capabilities
Only a method whose capability the client declared is sent: ping
needs none, sampling/createMessage needs sampling,
elicitation/create needs elicitation, roots/list needs roots.
Some params need a member of the capability: a task key needs the
task capability of the method, the modes of elicitation/create need
elicitation.form or elicitation.url and sampling with tools,
toolChoice or includeContext needs sampling.tools or
sampling.context. The guide about the requests to the client gives
the table. The three tasks/* methods are internal to the flow of a
client task (see OzMcp.Client): a callback does not send them.
Where the request travels
The callback runs for a POST request, as a task, or outside a
request. A callback of a POST request writes the request on the
response of that POST, which becomes an event stream (see
OzMcp.PostStream). A callback that runs as a task
(ctx.task_id is set) writes the request on the tasks/result
streams of the task and the task is input_required while it waits.
In every other case the request travels on the GET stream of the
session and waits in the event log of the session until a stream
delivers it. The guide about the requests to the client describes each
way and the timeout of each method.
The client answers with a POST that carries a JSON-RPC response. The
router hands the answer to the waiting process with deliver/2: an
answer for a request of a task goes to the process of the task, by the
owner of the task. Any session of the owner can answer; an answer on a
session that does not own the task is ignored.
Pending requests
A pending request of a session lives in the process of the session:
the session gives each one its id, routes its messages and hands the
answer to the process that waits. The end of the session process ends
each wait and a callback that is cancelled, stopped at its deadline
or killed leaves no pending request: the client receives
notifications/cancelled for it. A late answer for an unknown request
id is ignored. The request id is generated by the server and is unique
in the session; a client can answer only the requests of its own
session.
Telemetry
Each call of request/4 gives one client_request span of the events
of :telemetry. The guide about the telemetry describes the events.
Summary
Functions
Hands the answer of the client to the process that waits for it.
Sends ping to the client. The client answers with an empty result.
Sends a request to the client and waits for its answer.
Sends a request as a task of the client and waits for the final result.
This feature is experimental and the runtime option client_tasks turns
it on (default false).
Types
@type ctx() :: OzMcp.Context.ctx() | OzMcp.Context.t()
@type error() :: {:rpc_error, map()} | :timeout | :session_terminated | :session_not_found | :no_stream | :session_not_initialized | :capability_not_supported | :unsupported_method | :not_encodable | :no_task | :client_tasks_disabled | {:client_task_cancelled, String.t()} | {:invalid_response, map()}
Functions
@spec deliver( OzMcp.Instance.t(), String.t(), String.t() | integer(), {:ok, map()} | {:error, map()} ) :: :ok
Hands the answer of the client to the process that waits for it.
answer is {:ok, result} or {:error, error} (the error object of the
response). Always returns :ok: an answer for a request that is not
pending (late, repeated, unknown, or of another session) is ignored.
This is the path to one session: the id must name a request that the
session holds. The router uses deliver/2, which sends the answer of a
request of a task to the task of its owner. An id of a request of a task
that reaches this function names no request of the session, so the
answer is ignored.
Sends ping to the client. The client answers with an empty result.
Sends a request to the client and waits for its answer.
Options:
:timeout— milliseconds, or:infinity. Defaults to the timeout runtime option of the method (see the moduledoc).:wait_for_stream—truesends a request that only theGETstream can carry even when the client has no stream open (defaultfalse, the call fails with:no_stream).
Sends a request as a task of the client and waits for the final result.
This feature is experimental and the runtime option client_tasks turns
it on (default false).
Same options as request/4 and:
:ttl— milliseconds that the client must keep the task. Defaults to the timeout of the method when it is an integer; withtimeout: :infinitythe request carries nottl.:poll_interval— milliseconds between twotasks/getcalls. ThepollIntervalof the client wins. Defaults to theclient_task_poll_interval_msruntime option.
The first request carries params.task. A task value that the params
already have is kept: the :ttl option applies only when the params have
no task. The client answers with a CreateTaskResult and the call
polls tasks/get until the task is terminal. A completed or failed
task is read with tasks/result; an input_required task calls
tasks/result at once; a cancelled task gives
{:error, {:client_task_cancelled, task_id}}.
The client must declare the task capability of the method
(tasks.requests.sampling.createMessage,
tasks.requests.elicitation.create), else the call gives
{:error, :capability_not_supported}.