ExMCP.Transport.Error (ex_mcp v0.9.2)

Standardized error handling for MCP transports.

This module provides consistent error patterns and error handling functions for all MCP transport implementations. It ensures that all transports return errors in the same format for better client compatibility.

Standard Error Types

:connection_error - Connection establishment or maintenance failures
:transport_error - Transport-level communication failures
:security_violation - Security policy violations
:validation_error - Message or parameter validation failures
:timeout_error - Operation timeout failures
:protocol_error - Protocol-level violations or incompatibilities

Usage

# In transport implementations
case some_operation() do
  {:ok, result} -> {:ok, result}
  {:error, reason} -> Error.transport_error(reason)
end

# Connection failures
Error.connection_error(:server_not_available)

# Security violations  
Error.security_violation("Invalid origin")

Summary

Types

error_reason()

error_type()

Functions

connection_error(reason)

Creates a standardized connection error.

error_type?(arg1, expected_type)

Checks if an error is of a specific type.

get_error_reason(error)

Extracts the error reason from a standardized error tuple.

get_error_type(arg1)

Extracts the error type from a standardized error tuple.

normalize_error(other)

Normalizes an error tuple to the standard format.

protocol_error(reason)

Creates a standardized protocol error.

security_violation(reason)

Creates a standardized security violation error.

timeout_error(reason)

Creates a standardized timeout error.

transport_error(reason)

Creates a standardized transport error.

validate_connection(state, connected_check_fn)

Validates connection state before performing transport operations.

validate_connection_with_module(state, transport_module)

Validates connection state using the transport's connected?/1 function.

validation_error(reason)

Creates a standardized validation error.

wrap_error(type, reason)

Wraps an arbitrary error in the standard transport error format.

Types

error_reason()

@type error_reason() :: atom() | String.t() | map()

error_type()

@type error_type() ::
  :connection_error
  | :transport_error
  | :security_violation
  | :validation_error
  | :timeout_error
  | :protocol_error

Functions

connection_error(reason)

@spec connection_error(error_reason()) :: {:error, {error_type(), error_reason()}}

Creates a standardized connection error.

Used when transport connection establishment or maintenance fails.

error_type?(arg1, expected_type)

@spec error_type?(
  {:error, {error_type(), any()}},
  error_type()
) :: boolean()

Checks if an error is of a specific type.

Examples

error = Error.connection_error(:timeout)
Error.error_type?(error, :connection_error)  #=> true
Error.error_type?(error, :transport_error)   #=> false

get_error_reason(error)

@spec get_error_reason({:error, {error_type(), any()}} | any()) :: any()

Extracts the error reason from a standardized error tuple.

Returns the original error for non-standard formats.

get_error_type(arg1)

@spec get_error_type({:error, {error_type(), any()}} | any()) ::
  error_type() | :unknown

Extracts the error type from a standardized error tuple.

Returns :unknown for non-standard error formats.

normalize_error(other)

@spec normalize_error(any()) :: {:error, {error_type(), any()}}

Normalizes an error tuple to the standard format.

Converts various error formats into the standardized transport error format.

protocol_error(reason)

@spec protocol_error(error_reason()) :: {:error, {error_type(), error_reason()}}

Creates a standardized protocol error.

Used when protocol-level violations or incompatibilities occur.

security_violation(reason)

@spec security_violation(error_reason()) :: {:error, {error_type(), error_reason()}}

Creates a standardized security violation error.

Used when security policies are violated.

timeout_error(reason)

@spec timeout_error(error_reason()) :: {:error, {error_type(), error_reason()}}

Creates a standardized timeout error.

Used when operations exceed their timeout limits.

transport_error(reason)

@spec transport_error(error_reason()) :: {:error, {error_type(), error_reason()}}

Creates a standardized transport error.

Used for transport-level communication failures.

validate_connection(state, connected_check_fn)

@spec validate_connection(any(), (any() -> boolean())) ::
  :ok | {:error, {error_type(), any()}}

Validates connection state before performing transport operations.

This helper provides consistent connection validation across all transports. It should be called before send_message and receive_message operations.

Examples

case Error.validate_connection(state, &MyTransport.connected?/1) do
  :ok -> 
    # Proceed with operation
  {:error, reason} -> 
    # Handle disconnected state
end

validate_connection_with_module(state, transport_module)

@spec validate_connection_with_module(any(), module()) ::
  :ok | {:error, {error_type(), any()}}

Validates connection state using the transport's connected?/1 function.

This is a convenience function for transports that implement the standard connected?/1 callback.

validation_error(reason)

@spec validation_error(error_reason()) :: {:error, {error_type(), error_reason()}}

Creates a standardized validation error.

Used when message or parameter validation fails.

wrap_error(type, reason)

@spec wrap_error(error_type(), any()) :: {:error, {error_type(), any()}}

Wraps an arbitrary error in the standard transport error format.

This is useful for converting legacy error formats or third-party library errors into the standard format.