OzMcp.Sessions (OzMcp v0.9.0)

Copy Markdown View Source

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.

Summary

Functions

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

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.

Marks the session as initialized.

Sets the log level of the session.

Starts a session. Returns its id.

Subscribes the session to a resource.

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

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

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

Removes the subscription of the session to a resource.

Types

error()

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

principal_key()

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

Functions

list_principal(instance, principal)

@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(instance, session_id)

@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(instance, session_id)

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

Marks the session as initialized.

set_log_level(instance, session_id, level)

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

Sets the log level of the session.

start(instance, opts \\ [])

@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(instance, session_id, uri)

@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(instance, session_id, uri, required)

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

terminate(instance, session_id)

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

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

terminate_principal(instance, principal)

@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(instance, session_id)

@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(instance, session_id, granted)

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

unsubscribe(instance, session_id, uri)

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

Removes the subscription of the session to a resource.