Exth.Transport (Exth v0.1.1)

View Source

Factory module for creating JSON-RPC transport implementations.

This module provides a unified interface for creating and managing different transport mechanisms (HTTP, WebSocket, IPC) for JSON-RPC communication with EVM nodes.

Features

  • Pluggable transport system via the Transportable protocol
  • Built-in HTTP transport with Tesla/Mint
  • Consistent interface across transport types
  • Automatic request/response encoding/decoding
  • Configurable timeout and retry mechanisms
  • Transport-specific option handling

Transport Types

Currently supported:

  • :http - HTTP/HTTPS transport using Tesla with Mint adapter
  • :custom - Custom transport implementations

Coming soon:

  • :ws - WebSocket transport
  • :ipc - Unix domain socket transport

Usage

# Create an HTTP transport
transport = Transport.new(:http,
  rpc_url: "https://mainnet.infura.io/v3/YOUR-PROJECT-ID",
  timeout: 30_000,
  headers: [{"authorization", "Bearer token"}]
)

# Make requests
{:ok, response} = Transport.call(transport, request)
{:ok, responses} = Transport.call(transport, [request1, request2])

Configuration

Common options for all transports:

  • :rpc_url - (Required) The endpoint URL
  • :encoder - (Required) Function to encode requests to JSON
  • :decoder - (Required) Function to decode JSON responses

HTTP-specific options:

  • :headers - Additional HTTP headers
  • :timeout - Request timeout in milliseconds (default: 30000)
  • :adapter - Tesla adapter to use (default: Tesla.Adapter.Mint)

Custom Transport Implementation

To implement a custom transport:

  1. Define your transport struct:

    defmodule MyTransport do
      defstruct [:config]
    end
  2. Implement the Transportable protocol:

    defimpl Exth.Transport.Transportable, for: MyTransport do
      def new(_transport, opts) do
        %MyTransport{config: opts}
      end
    
      def call(transport, request) do
        # Implement request handling
        {:ok, response}
      end
    end
  3. Use your transport:

    transport = Transport.new(:custom,
      module: MyTransport,
      rpc_url: "custom://endpoint",
      # other options...
    )

Error Handling

The module uses consistent error handling:

  • {:ok, response} - Successful request with decoded response
  • {:ok, responses} - Successful batch request with responses
  • {:error, reason} - Request failed with detailed reason

HTTP-specific errors:

  • {:error, {:http_error, status}} - HTTP error response
  • {:error, :timeout} - Request timeout
  • {:error, :network_error} - Network connectivity issues

Best Practices

  • Use appropriate timeouts for your use case
  • Implement retry logic for transient failures
  • Handle batch requests efficiently
  • Monitor transport health and metrics
  • Properly handle connection pooling
  • Use secure transport options in production

See Exth.Transport.Transportable for protocol details and Exth.Transport.Http for HTTP transport specifics.

Summary

Types

Transport configuration options.

Supported transport types

Functions

Makes a request using the configured transport.

Creates a new transport struct with the given type and options.

Types

error_reason()

@type error_reason() :: Exception.t() | String.t() | term()

options()

@type options() :: [
  rpc_url: String.t(),
  encoder: (term() -> String.t()),
  decoder: (String.t() -> term()),
  module: module() | nil
]

Transport configuration options.

type()

@type type() :: :custom | :http

Supported transport types:

  • :http - HTTP/HTTPS transport
  • :custom - Custom transport implementation

Functions

call(transportable, request)

Makes a request using the configured transport.

Parameters

  • transportable - The configured transport instance
  • request - The JSON-RPC request to send

Returns

  • {:ok, response} - Successful request with decoded response
  • {:error, reason} - Request failed with error reason

new(type, opts)

Creates a new transport struct with the given type and options.

Parameters

  • type - The type of transport to create (:http or :custom)
  • opts - Configuration options for the transport

Returns

  • A configured transport struct implementing the Transportable protocol

Raises