The notifications that a server sends to its clients.
Scope
Each function sends to a fixed set of sessions:
| Function | Sessions |
|---|---|
log/4 | the session of the request of the ctx (the stream of the request); for the ctx of a task, the owner of the task |
log_session/5 | one session |
broadcast_log/4 | every session of the server (every tenant), or the sessions of one principal with :principal |
progress/3 | the session of the request of the ctx; for the ctx of a task, the owner of the task |
task_status/3, task_progress/7, elicitation_complete/3 | one session (elicitation_complete/3 with the id of a task: the owner of the task) |
resource_updated/3 | the sessions that subscribed to the URI |
The owner of a task is the principal that created it, or its session
when the server has no authorization. A message of a task goes to the
attached tasks/result streams of the task, else to every session of
the owner. A task that a session owns sends only to its session: no
other session can read the task.
Do not put the data of one client in a message that goes to many sessions.
Data
The application data of a notification (the data of a log, a _meta
map, the message of a progress notification) must hold JSON terms:
strings, numbers, booleans, nil, lists and maps with atom or string
keys. A pid, a tuple, a reference, a function or a port is not a JSON
term.
The log functions check the data before the send. They return
{:error, :not_encodable} and send nothing when the data holds a term
that is not a JSON term. A struct is not a JSON term: convert it first.
The sender encodes each notification one time, before it sends it. A
notification that holds a term that JSON cannot encode is not sent and
the function returns {:error, :not_encodable}. The process that writes
a stream never encodes a term of an application.
The guide about the notifications shows each function with an example: Notifications.
Summary
Functions
Sends notifications/message to many sessions of the server.
Tells the client that an elicitation in URL mode is done (the user finished the interaction on the web page).
Sends notifications/message to the client of the request that the
callback runs for.
Sends notifications/message to one session, on its GET stream.
Reports the progress of the request the callback runs for.
Functions
@spec broadcast_log(module(), OzMcp.LogLevel.t(), term(), keyword()) :: :ok | {:error, :not_encodable | :unavailable}
Sends notifications/message to many sessions of the server.
WARNING: without the :principal option, the message goes to every
initialized session of the server, thus to every tenant. Do not put the
data of one client in a broadcast. For a message about a request, use
log/4 with the ctx of the request. For one session, use
log_session/5.
Options:
:logger- the name of the logger (a string).:principal- anOzMcp.Auth.Principalor a key{issuer, subject}. The message goes only to the sessions of that principal.
Each session gets the message only when its level (logging/setLevel)
accepts the level of the message. A message over the option
max_log_rate of the instance is dropped by the session: the return
stays :ok. Returns {:error, :not_encodable}
when the data holds a term that is not a JSON term: nothing is sent.
Returns {:error, :unavailable} when the instance does not run.
@spec elicitation_complete(module(), String.t(), String.t(), String.t() | nil) :: :ok | {:error, :capability_not_supported | :no_session}
Tells the client that an elicitation in URL mode is done (the user finished the interaction on the web page).
elicitation_id is the id of OzMcp.Client.elicit/3 (it is part of its
result). The notification goes out only if the client declared the url
mode of elicitation; otherwise {:error, :capability_not_supported}
is returned and nothing is sent. Returns {:error, :no_session} for
an unknown session.
The notification is delivered on the GET stream of the session. A
client ignores an id it does not know.
The task_id is the id of the task that asked the elicitation (the
task_id of its ctx, or nil). The notification then carries the
related-task _meta. For a task that runs, the capability check reads
the capabilities that the request which created the task declared and
the notification goes to the owner of the task (each attached
tasks/result stream, else every session of the owner). A task that
does not run keeps the session of the caller.
@spec log( OzMcp.Context.ctx() | OzMcp.Context.t(), OzMcp.LogLevel.t(), term(), keyword() ) :: :ok | {:error, :not_encodable}
Sends notifications/message to the client of the request that the
callback runs for.
ctx is the context handed to the callback. The message goes on the
response stream of the POST request (see OzMcp.PostStream), so it
reaches the client even when no GET stream is open. A request that has
no stream falls back to the GET stream of its session.
For the ctx of a task, the message goes to the owner of the task: each
attached tasks/result stream of the task, else every session of the
owner (each session applies its own level). The message carries the
related-task _meta (see OzMcp.Tasks.RelatedTask).
The message is sent only when the level of the session (set by the
client with logging/setLevel) accepts level. Before
logging/setLevel, nothing is sent.
Options: :logger (a string).
Returns :ok, also when the level refuses the message or when the
session drops the message over max_log_rate. Returns
{:error, :not_encodable} when data holds a term that is not a JSON
term: nothing is sent.
@spec log_session(module(), String.t(), OzMcp.LogLevel.t(), term(), keyword()) :: :ok | {:error, :no_session | :unavailable | :not_encodable}
Sends notifications/message to one session, on its GET stream.
Use it in a process that has no ctx (for example a GenServer of the
application). For a message about a request, use log/4 with the ctx of
the request: the message then goes on the stream of the request.
The message is sent only when the level of the session (set by the
client with logging/setLevel) accepts level. Before
logging/setLevel, nothing is sent.
Options: :logger (a string).
Returns :ok (also when the level refuses the message, or when the
session drops the message over max_log_rate),
{:error, :no_session} for an unknown session,
{:error, :unavailable} when the instance does not run, or
{:error, :not_encodable} when data holds a term that is not a JSON
term.
@spec progress(OzMcp.Context.ctx() | OzMcp.Context.t(), number(), keyword()) :: :ok | {:error, :not_encodable | :unavailable}
Reports the progress of the request the callback runs for.
ctx is the context handed to the callback. The notification carries the
progressToken of the request (nothing is sent when the request had
none) and is written on the response stream of that POST request, so it
reaches the client even when no GET stream is open (see
OzMcp.PostStream). The response becomes an event stream, as for a
request to the client. A request that has no stream (a process of the
application) falls back to the GET stream of the session, like
progress/5.
When the ctx belongs to a task (ctx.task_id is set), this call and
OzMcp.Tasks.Context.progress/4 are the same: both call
OzMcp.Tasks.progress/5, which checks the values before the send. The
task sends the notification to the owner of the task like the log and
it carries the io.modelcontextprotocol/related-task _meta; the raw
progress/5 takes no ctx and never adds it.
Options: :total and :message.
The progress value must increase with each call for the same token.
A value that is equal to or smaller than the last one is dropped: the
function returns :ok and the client gets nothing. A debug line is
written. The first value can be any number. A value that is not a
number is not checked.
Progress is only meaningful while the request runs: do not call it after the callback returned.
Returns {:error, :not_encodable} when a value holds a term that
JSON cannot encode (for example a pid in the :message option): nothing
is sent and the request goes on. For the ctx of a task it can also give
{:error, :unavailable} when the instance does not run.
@spec resource_updated(module(), String.t(), keyword()) :: :ok | OzMcp.Sessions.error() | {:error, :invalid_meta | :not_encodable}
@spec task_status(module(), String.t(), OzMcp.Structs.Task.t()) :: :ok | OzMcp.Sessions.error() | {:error, :not_encodable}