@spec build_error(map(), String.t() | integer() | nil) :: map()

Builds an error message map without encoding to JSON.

Examples

iex> Message.build_error(%{"code" => -32600, "message" => "Invalid Request"}, "req_123")
%{"jsonrpc" => "2.0", "error" => %{"code" => -32600, "message" => "Invalid Request"}, "id" => "req_123"}

@spec build_notification(String.t(), map()) :: map()

Builds a notification message map without encoding to JSON.

Examples

iex> Message.build_notification("notifications/message", %{"level" => "info", "data" => "test"})
%{"jsonrpc" => "2.0", "method" => "notifications/message", "params" => %{"level" => "info", "data" => "test"}}

@spec build_response(map(), String.t() | integer()) :: map()

Builds a response message map without encoding to JSON.

Examples

iex> Message.build_response(%{"value" => 42}, "req_123")
%{"jsonrpc" => "2.0", "result" => %{"value" => 42}, "id" => "req_123"}

Decodes raw data (possibly containing multiple messages) into JSON-RPC messages.

Messages are validated against the latest registered protocol version. Returns either:

• {:ok, messages} where messages is a list of parsed JSON-RPC messages
• {:error, reason} if parsing fails

Decodes raw data, validating each message against the given protocol version module.

Returns the same shapes as decode/1.

Encodes an elicitation response, validating the result against the latest registered protocol version.

Encodes an elicitation response, validating the result against the given protocol version module.

Encodes an error message to a JSON-RPC 2.0 compliant string.

Returns the encoded string with a newline character appended.

@spec encode_log_message(String.t(), term(), String.t() | nil) ::
  {:ok, String.t()} | {:error, term()}

Encodes a log message notification to be sent to the client.

Parameters

• level - The log level (debug, info, notice, warning, error, critical, alert, emergency)
• data - The data to be logged (any JSON-serializable value)
• logger - Optional name of the logger issuing the message

Returns the encoded notification string with a newline character appended.

Encodes a notification message to a JSON-RPC 2.0 compliant string.

The notification is validated against the latest registered protocol version. Returns the encoded string with a newline character appended.

Encodes a notification message using a custom schema.

Use notification_schema/1 to derive the schema for a negotiated protocol version module.

Parameters

• notification - The notification map containing method and params
• schema - The Peri schema to use for validation

Returns the encoded string with a newline character appended.

@spec encode_progress_notification(map(), term() | nil) ::
  {:ok, String.t()} | {:error, term()}

Encodes a progress notification message to a JSON-RPC 2.0 compliant string.

Parameters

• params - Map containing progress parameters:
  • "progressToken" - The token that was provided in the original request (string or integer)
  • "progress" - The current progress value (number)
  • "total" - Optional total value for the operation (number)
  • "message" - Optional descriptive message (string, for 2025-03-26)
• params_schema - Optional Peri schema for params validation (defaults to @progress_notif_params_schema)

Returns the encoded string with a newline character appended.

@spec encode_progress_notification(
  String.t() | integer(),
  number(),
  number() | nil
) :: {:ok, String.t()} | {:error, term()}

Legacy function for progress notifications with individual parameters.

Deprecated: Prefer using encode_progress_notification/2 with a params map.

This function will be removed in a future release. Update your code to use the newer function:

encode_progress_notification(%{
  "progressToken" => progress_token,
  "progress" => progress,
  "total" => total
})

Encodes a request message to a JSON-RPC 2.0 compliant string.

The request is validated against the latest registered protocol version. Returns the encoded string with a newline character appended.

Encodes a request message using a custom schema.

Use request_schema/1 to derive the schema for a negotiated protocol version module.

Parameters

• request - The request map containing method and params
• id - The request ID
• schema - The Peri schema to use for validation

Returns the encoded string with a newline character appended.

Encodes a response message to a JSON-RPC 2.0 compliant string.

Returns the encoded string with a newline character appended.

Encodes a response message using a custom schema.

Parameters

• response - The response map containing result
• id - The response ID
• schema - The Peri schema to use for validation

Returns the encoded string with a newline character appended.

Encodes a sampling response, validating the result against the latest registered protocol version.

Encodes a sampling response, validating the result against the given protocol version module.

@spec get_schema(atom()) :: term()

Returns the Peri schema registered under name.

Kept for backwards compatibility: these schemas used to be defined in this module and are now resolved from the latest registered protocol version.

Guard to determine if a JSON-RPC message is an error.

A message is considered an error if it contains both "error" and "id" fields.

Examples

iex> message = %{"jsonrpc" => "2.0", "error" => %{"code" => -32600}, "id" => 1}
iex> is_error(message)
true

Guard to check if a request is an initialize request.

Examples

iex> message = %{"jsonrpc" => "2.0", "method" => "initialize", "id" => 1, "params" => %{}}
iex> is_initialize(message)
true

Guard to check if a message is part of the initialization lifecycle.

This includes both the initialize request and the notifications/initialized notification.

Examples

iex> init_request = %{"jsonrpc" => "2.0", "method" => "initialize", "id" => 1, "params" => %{}}
iex> is_initialize_lifecycle(init_request)
true

iex> init_notification = %{"jsonrpc" => "2.0", "method" => "notifications/initialized"}
iex> is_initialize_lifecycle(init_notification)
true

iex> other_message = %{"jsonrpc" => "2.0", "method" => "tools/list", "id" => 2}
iex> is_initialize_lifecycle(other_message)
false

Guard to determine if a JSON-RPC message is a notification.

A message is considered a notification if it contains a "method" field but no "id" field.

Examples

iex> message = %{"jsonrpc" => "2.0", "method" => "notification"}
iex> is_notification(message)
true

iex> request = %{"jsonrpc" => "2.0", "method" => "ping", "id" => 1}
iex> is_notification(request)
false

Guard to check if a request is a ping request.

Examples

iex> message = %{"jsonrpc" => "2.0", "method" => "ping", "id" => 1}
iex> is_ping(message)
true

Guard to determine if a JSON-RPC message is a request.

A message is considered a request if it contains both "method" and "id" fields.

Examples

iex> message = %{"jsonrpc" => "2.0", "method" => "ping", "id" => 1}
iex> is_request(message)
true

iex> notification = %{"jsonrpc" => "2.0", "method" => "notification"}
iex> is_request(notification)
false

Guard to determine if a JSON-RPC message is a response.

A message is considered a response if it contains both "result" and "id" fields.

Examples

iex> message = %{"jsonrpc" => "2.0", "result" => %{}, "id" => 1}
iex> is_response(message)
true

@spec notification_schema() :: term()

Returns the full notification message schema for a protocol version module.

Defaults to the latest registered protocol version.

Returns the standard progress notification parameters schema for 2024-11-05.

Returns the progress notification parameters schema for 2025-03-26 (with message field).

@spec progress_params_schema_for(String.t()) :: {:ok, map()} | :error

Returns the progress notification parameters schema for a given protocol version.

Delegates to the version module via Anubis.Protocol.Registry.

Examples

iex> Message.progress_params_schema_for("2024-11-05")
%{"progressToken" => {:required, {:either, {:string, :integer}}}, ...}

iex> Message.progress_params_schema_for("2025-03-26")
%{"progressToken" => ..., "message" => :string}

@spec request_schema() :: term()

Returns the full request message schema for a protocol version module.

Defaults to the latest registered protocol version.

Examples

iex> {:multi, :method, branches} = Message.request_schema(Anubis.Protocol.V2025_11_25)
iex> Map.has_key?(branches, "tasks/get")
true

iex> {:multi, :method, branches} = Message.request_schema(Anubis.Protocol.V2025_03_26)
iex> Map.has_key?(branches, "elicitation/create")
false

Validates a decoded JSON message against the latest registered protocol version.

Validates a decoded JSON message against the given protocol version module.

A message whose method is not part of the version fails with {:error, :method_not_found}; malformed messages fail with {:error, :invalid_request}.