Urchin.Context (Urchin v0.2.0)

The request context handed to every server handler.

Besides carrying the negotiated session metadata and the user state from Urchin.Server.init/1, the context exposes the side-effecting capabilities a handler may use while processing a request:

progress and log notifications related to the in-flight request
server-initiated requests to the client: sampling, elicitation, roots
a best-effort cancellation check

Notifications and server-initiated requests are emitted on the stream that carries the originating request, as required by the transport spec.

Summary

Types

t()

Functions

assign(ctx, key, value)

Stores a value in the context assigns.

auth(context)

Returns the validated OAuth claims for the originating request, or nil.

cancelled?(context)

Returns true if the originating request has been cancelled by the client.

create_message(ctx, params, timeout \\ 30000)

Issues a sampling/createMessage request to the client and waits for the result.

elicit(ctx, params, timeout \\ 30000)

Issues an elicitation/create request to the client and waits for the result.

list_roots(ctx, timeout \\ 30000)

Issues a roots/list request to the client and waits for the result.

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

Sends a notifications/message log entry to the client.

notify(ctx, method, params \\ nil)

Sends an arbitrary JSON-RPC notification on the originating request stream.

progress(ctx, progress, opts)

Sends a progress notification for the originating request.

request(context, method, params, timeout)

Issues an arbitrary server-to-client request and blocks until the client responds.

state(context)

Returns the user state established by Urchin.Server.init/1.

Types

t()

@type t() :: %Urchin.Context{
  assigns: map(),
  auth: Urchin.Auth.Claims.t() | nil,
  cancelled_ref: reference() | nil,
  client_capabilities: map() | nil,
  client_info: map() | nil,
  min_log_level: String.t(),
  owner: pid() | nil,
  params: map(),
  progress_token: String.t() | number() | nil,
  protocol_version: String.t() | nil,
  request_id: Urchin.JSONRPC.id() | nil,
  session: pid() | nil,
  state: term(),
  uri: String.t() | nil
}

Functions

assign(ctx, key, value)

@spec assign(t(), atom(), term()) :: t()

Stores a value in the context assigns.

auth(context)

@spec auth(t()) :: Urchin.Auth.Claims.t() | nil

Returns the validated OAuth claims for the originating request, or nil.

Populated only when the transport is configured with :auth (or an upstream Urchin.Auth.Plug ran). Handlers use it for per-tool authorization:

if Urchin.Auth.Claims.has_scope?(Urchin.Context.auth(ctx), "files:write") do
  # ...
end

cancelled?(context)

@spec cancelled?(t()) :: boolean()

Returns true if the originating request has been cancelled by the client.

Cancellation also terminates the handler process, so this is a cooperative, best-effort check for long-running loops.

create_message(ctx, params, timeout \\ 30000)

@spec create_message(t(), map(), timeout()) ::
  {:ok, map()} | {:error, Urchin.Error.t()}

Issues a sampling/createMessage request to the client and waits for the result.

Returns {:ok, result_map} or {:error, Urchin.Error.t()}. Requires the client to have advertised the sampling capability.

elicit(ctx, params, timeout \\ 30000)

@spec elicit(t(), map(), timeout()) :: {:ok, map()} | {:error, Urchin.Error.t()}

Issues an elicitation/create request to the client and waits for the result.

Returns {:ok, result_map} or {:error, Urchin.Error.t()}.

list_roots(ctx, timeout \\ 30000)

@spec list_roots(t(), timeout()) :: {:ok, map()} | {:error, Urchin.Error.t()}

Issues a roots/list request to the client and waits for the result.

Returns {:ok, %{"roots" => [...]}} or {:error, Urchin.Error.t()}.

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

@spec log(t(), String.t(), term(), keyword()) :: :ok

Sends a notifications/message log entry to the client.

Messages below the level requested by the client via logging/setLevel are dropped. level is one of ["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"].

Options

:logger - optional logger name

notify(ctx, method, params \\ nil)

@spec notify(t(), String.t(), map() | nil) :: :ok

Sends an arbitrary JSON-RPC notification on the originating request stream.

progress(ctx, progress, opts)

@spec progress(t(), number(), keyword()) :: :ok

Sends a progress notification for the originating request.

No-op when the client did not supply a progressToken for the request.

Options

:total - total units of work, if known
:message - human-readable progress message

request(context, method, params, timeout)

@spec request(t(), String.t(), map() | nil, timeout()) ::
  {:ok, map()} | {:error, Urchin.Error.t()}

Issues an arbitrary server-to-client request and blocks until the client responds.

The request is written to the originating request's stream; the matching response, delivered on a later client POST, is correlated by the session.

state(context)

@spec state(t()) :: term()

Returns the user state established by Urchin.Server.init/1.