# `OzMcp.Notify`
[🔗](https://github.com/oz-elixir/oz_mcp/blob/v0.9.0/lib/oz_mcp/notify.ex#L1)

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](guides/runtime/notifications.md).

# `broadcast_log`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

# `resource_updated`

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

# `task_progress`

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

# `task_status`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
