OzMcp.Notify (OzMcp v0.9.0)

Copy Markdown View Source

The notifications that a server sends to its clients.

Scope

Each function sends to a fixed set of sessions:

FunctionSessions
log/4the 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/5one session
broadcast_log/4every session of the server (every tenant), or the sessions of one principal with :principal
progress/3the 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/3one session (elicitation_complete/3 with the id of a task: the owner of the task)
resource_updated/3the 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

broadcast_log(instance, level, data, opts \\ [])

@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 - an OzMcp.Auth.Principal or 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.

elicitation_complete(instance, session_id, elicitation_id, task_id \\ nil)

@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.

log(ctx_or_server, level, data, opts \\ [])

@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.

log_session(instance, session_id, level, data, opts \\ [])

@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.

progress(ctx, progress, opts \\ [])

@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.

progress(instance, session_id, token, progress, opts \\ [])

@spec progress(module(), String.t(), term(), number(), keyword()) ::
  :ok | {:error, :unavailable}

resource_updated(instance, uri, opts \\ [])

@spec resource_updated(module(), String.t(), keyword()) ::
  :ok | OzMcp.Sessions.error() | {:error, :invalid_meta | :not_encodable}

task_progress(instance, session_id, task_id, progress_token, progress, total, message)

@spec task_progress(
  module(),
  String.t(),
  String.t(),
  term(),
  number(),
  number() | nil,
  term()
) ::
  :ok | OzMcp.Sessions.error() | {:error, :not_encodable}

task_status(instance, session_id, task)

@spec task_status(module(), String.t(), OzMcp.Structs.Task.t()) ::
  :ok | OzMcp.Sessions.error() | {:error, :not_encodable}