Urchin.Context (Urchin v0.1.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.

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(),
  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.

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.