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
Functions
@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.
@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).
@spec set_initialized(OzMcp.Instance.t(), String.t()) :: :ok | error()
Marks the session as initialized.
@spec set_log_level(OzMcp.Instance.t(), String.t(), atom()) :: :ok | error()
Sets the log level of the session.
@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.
@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.
@spec subscribe(OzMcp.Instance.t(), String.t(), String.t(), [String.t()]) :: :ok | error()
@spec terminate(OzMcp.Instance.t(), String.t()) :: :ok | error()
Ends a session: its streams, its tasks and its requests.
@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.
@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.
@spec touch(OzMcp.Instance.t(), String.t(), [String.t()] | nil) :: :ok | error()
@spec unsubscribe(OzMcp.Instance.t(), String.t(), String.t()) :: :ok | error()
Removes the subscription of the session to a resource.