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

The sessions of an instance: start, find, stop.

Each function takes the instance as its first argument. A call that
cannot get an answer gives `{:error, :unavailable}` (the instance is
not running, or the process of the call exited) or `{:error, :timeout}`
(no answer in time). A session that does not exist gives
`{:error, :no_session}`.

A session is a process (OzMcp.Session). It owns its lifecycle: the
initialization, the idle timer and the end. `lookup/2` reads the public
view of the session from the Registry of the instance, with no call.
`set_initialized/2`, `set_log_level/3`, `subscribe/3`, `unsubscribe/3`
and `terminate/2` call the session process and `touch/2` casts to it. A session that is gone
gives `{:error, :no_session}`: a request that arrives while the session
stops cannot see a half-ended session.

The readers of this module never start a session: only
`fetch_snapshot/2` and `start_restored/4` take a session out of the
snapshot store and only the restore stage of the request pipeline
calls them (see OzMcp.Validate). A message of the server (a
notification, a request to the client) never starts a session.

`list_principal/2` and `terminate_principal/2` read the `Principals`
Registry of the instance. They do not use the PubSub module, so they
work with a custom module. They are for an administrator, not for a
request.

The limit `max_sessions_per_principal` is checked before the start of
a session and a restore from a snapshot counts in it. Each open session
registers itself in the `Principals` Registry under the key of its
principal and the Registry removes the entry when the session process
ends. The count reads one key, so it does not scan the views. The check
and the start are two steps: two requests that arrive at the same time
for two different session ids can pass the check together. The limit
`max_sessions` is checked at the start itself, so it holds exactly.

The session process also owns the streams of the session (the GET
streams, the stdio stream and the POST streams), its event log and the
requests of the client that run right now. The transports call
OzMcp.Session for the streams and the requests. The functions with
`@doc false` are for the framework and the application does not call
them. A broadcast goes through the pubsub of the instance
(`OzMcp.PubSub`) to the sessions of a topic.

`terminate_principal/2` runs the full cascade of the end of a session:
the streams, the tasks and the requests of the client.

# `error`

```elixir
@type error() :: {:error, :no_session | :unavailable | :timeout | term()}
```

# `principal_key`

```elixir
@type principal_key() :: {String.t() | nil, String.t()}
```

# `list_principal`

```elixir
@spec list_principal(
  OzMcp.Instance.t(),
  OzMcp.Auth.Principal.t() | principal_key() | nil
) ::
  {:ok, [String.t()]} | error()
```

The ids of the open sessions of a principal. `nil` gives an empty list.

# `lookup`

```elixir
@spec lookup(OzMcp.Instance.t(), String.t()) ::
  {:ok, OzMcp.Session.View.t()} | error()
```

Reads the public view of a session from the Registry. No call. A
session whose process is dead is unknown, even while the Registry
still holds its entry.

`lookup/2` never calls the snapshot module and never starts a session:
a session that the Registry does not know is unknown, even when the
snapshot store of the instance holds it. Only the request pipeline
restores a session, through `fetch_snapshot/2` and `start_restored/4`
(see `OzMcp.Session.Snapshot`).

# `set_initialized`

```elixir
@spec set_initialized(OzMcp.Instance.t(), String.t()) :: :ok | error()
```

Marks the session as initialized.

# `set_log_level`

```elixir
@spec set_log_level(OzMcp.Instance.t(), String.t(), atom()) :: :ok | error()
```

Sets the log level of the session.

# `start`

```elixir
@spec start(OzMcp.Instance.t(), keyword()) :: {:ok, String.t()} | error()
```

Starts a session. Returns its id.

The options are `:protocol_version`, `:client_info`,
`:client_capabilities`, `:principal_key`, `:transport` (the transport
of the caller, for the telemetry of the session) and `:config` (the
config of the request, when the caller already read it: the start then
reads the Registry no time).

`{:error, :too_many_sessions}` tells that `max_sessions` or
`max_sessions_per_principal` is reached.

# `subscribe`

```elixir
@spec subscribe(OzMcp.Instance.t(), String.t(), String.t()) :: :ok | error()
```

Subscribes the session to a resource.

A repeat subscribe of a URI that is already in the set gives `:ok`. A
new URI over `max_subscriptions_per_session` gives
`{:error, :too_many_subscriptions}`.

`required` is the list of the scopes that the resource needs. The
session keeps it and a later touch that shows a principal without
those scopes ends the subscription.

# `subscribe`

```elixir
@spec subscribe(OzMcp.Instance.t(), String.t(), String.t(), [String.t()]) ::
  :ok | error()
```

# `terminate`

```elixir
@spec terminate(OzMcp.Instance.t(), String.t()) :: :ok | error()
```

Ends a session: its streams, its tasks and its requests.

# `terminate_principal`

```elixir
@spec terminate_principal(
  OzMcp.Instance.t(),
  OzMcp.Auth.Principal.t() | principal_key()
) ::
  {:ok, [String.t()]} | error()
```

Ends every session of a principal. Returns the ids of the sessions that
this call ended.

The principal is an `OzMcp.Auth.Principal` or its key
`{issuer, subject}`.

The cascade is the one of `terminate/2`: the open streams get a final
`retry:` event, the requests in flight are cancelled, the requests to
the client get `{:error, :session_terminated}` and the tasks are
removed. The removal of the tasks is asynchronous: it can end a short
time after this function returns.

# `touch`

```elixir
@spec touch(OzMcp.Instance.t(), String.t()) :: :ok | error()
```

Marks the session as active now: its idle timer starts again.

`granted` is the list of the scopes of the principal of the request, or
`nil` when there is nothing to check. A list ends the subscriptions of
the session whose required scopes the list does not cover.

# `touch`

```elixir
@spec touch(OzMcp.Instance.t(), String.t(), [String.t()] | nil) :: :ok | error()
```

# `unsubscribe`

```elixir
@spec unsubscribe(OzMcp.Instance.t(), String.t(), String.t()) :: :ok | error()
```

Removes the subscription of the session to a resource.

---

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