client

Documentation

Overview

Package client provides thin HTTP clients for Heimdall's REST gateway and CometBFT JSON-RPC endpoint.

Neither client decodes response bodies. They return raw bytes and leave unmarshalling to the caller so subcommands can choose between typed decode (for rendered output) and direct JSON passthrough (for --json / --field).

Index

• func BuildCurl(req *http.Request, extra map[string]string) (string, error)
• func ExitCode(err error) int
• type CurlTransport
  • func (t *CurlTransport) Do(req *http.Request) ([]byte, int, error)
• type HTTPError
  • func (e *HTTPError) Error() string
  • func (e *HTTPError) NotFound() bool
• type HTTPTransport
  • func (t *HTTPTransport) Do(req *http.Request) ([]byte, int, error)
• type NetworkError
  • func (e *NetworkError) Error() string
  • func (e *NetworkError) Unwrap() error
• type RESTClient
  • func NewRESTClient(base string, timeout time.Duration, headers map[string]string, insecure bool) *RESTClient
  • func (c *RESTClient) Get(ctx context.Context, path string, query url.Values) ([]byte, int, error)
  • func (c *RESTClient) Post(ctx context.Context, path string, contentType string, body []byte) ([]byte, int, error)
• type RPCClient
  • func NewRPCClient(base string, timeout time.Duration, headers map[string]string, insecure bool) *RPCClient
  • func (c *RPCClient) Call(ctx context.Context, method string, params map[string]any) (json.RawMessage, error)
• type RPCError
  • func (e *RPCError) Error() string
• type RPCRequest
• type RPCResponse
• type Transport
• type UsageError
  • func (e *UsageError) Error() string

Functions

func BuildCurl

func BuildCurl(req *http.Request, extra map[string]string) (string, error)

BuildCurl renders a request as an equivalent curl invocation, including any headers merged from extra. Caller-side secrets are the caller's problem; nothing is redacted.

func ExitCode

func ExitCode(err error) int

ExitCode maps an error to a cast-style exit code. 0 -> success, 1 -> node error / not-found, 2 -> network error, 3 -> usage error, 4 -> signing error. The signing path lives in the tx builder and wraps errors as *SignError (declared elsewhere in W2).

Types

type CurlTransport

type CurlTransport struct {
	Out     io.Writer
	Headers map[string]string
	Last    string
}

CurlTransport replaces the HTTP call with an equivalent `curl` command dumped to Out. Last printed curl is also captured for tests.

func (*CurlTransport) Do

func (t *CurlTransport) Do(req *http.Request) ([]byte, int, error)

Do implements Transport by rendering the request as a curl one-liner and writing it to t.Out; the HTTP body is never sent. Returns an empty body with status 0 so callers know no real response is available.

type HTTPError

type HTTPError struct {
	Method     string
	URL        string
	StatusCode int
	Body       []byte
}

HTTPError is returned when the Heimdall node responds with a non-2xx status. Body is the raw response body; StatusCode is the HTTP code.

func (*HTTPError) Error

func (e *HTTPError) Error() string

Error implements error. Keeps the formatting terse but tries to surface enough context to debug from a log line alone.

func (*HTTPError) NotFound

func (e *HTTPError) NotFound() bool

NotFound reports whether the error represents a 404.

type HTTPTransport

type HTTPTransport struct {
	Client *http.Client
}

HTTPTransport is the default Transport: it forwards to an *http.Client.

func (*HTTPTransport) Do

func (t *HTTPTransport) Do(req *http.Request) ([]byte, int, error)

Do implements Transport.

type NetworkError

type NetworkError struct {
	Err error
}

NetworkError marks transport-level failures (DNS, TCP reset, TLS handshake, etc.).

func (*NetworkError) Error

func (e *NetworkError) Error() string

func (*NetworkError) Unwrap

func (e *NetworkError) Unwrap() error

type RESTClient

type RESTClient struct {
	BaseURL   string
	Headers   map[string]string
	Transport Transport
}

RESTClient wraps net/http for Heimdall's REST gateway.

func NewRESTClient

func NewRESTClient(base string, timeout time.Duration, headers map[string]string, insecure bool) *RESTClient

NewRESTClient returns a RESTClient configured from the resolved config.

func (*RESTClient) Get

func (c *RESTClient) Get(ctx context.Context, path string, query url.Values) ([]byte, int, error)

Get issues a GET against path (starting with '/') and returns the raw response body plus the HTTP status code. 2xx responses return (body, status, nil). 4xx/5xx responses return (body, status, *HTTPError).

func (*RESTClient) Post

func (c *RESTClient) Post(ctx context.Context, path string, contentType string, body []byte) ([]byte, int, error)

Post issues a POST with the given body and Content-Type.

type RPCClient

type RPCClient struct {
	BaseURL   string
	Headers   map[string]string
	Transport Transport
	// contains filtered or unexported fields
}

RPCClient is a CometBFT JSON-RPC client.

func NewRPCClient

func NewRPCClient(base string, timeout time.Duration, headers map[string]string, insecure bool) *RPCClient

NewRPCClient returns an RPCClient configured from the resolved config.

func (*RPCClient) Call

func (c *RPCClient) Call(ctx context.Context, method string, params map[string]any) (json.RawMessage, error)

Call issues a JSON-RPC call with the given method and params and returns the raw `result` field. Returns *RPCError on a JSON-RPC error, *HTTPError on HTTP 4xx/5xx, or *NetworkError on transport failures.

type RPCError

type RPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    string `json:"data,omitempty"`
}

RPCError represents a JSON-RPC error payload.

func (*RPCError) Error

func (e *RPCError) Error() string

Error implements error.

type RPCRequest

type RPCRequest struct {
	JSONRPC string         `json:"jsonrpc"`
	ID      uint64         `json:"id"`
	Method  string         `json:"method"`
	Params  map[string]any `json:"params,omitempty"`
}

RPCRequest is the JSON-RPC 2.0 envelope used by CometBFT.

type RPCResponse

type RPCResponse struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      uint64          `json:"id"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *RPCError       `json:"error,omitempty"`
}

RPCResponse is the JSON-RPC 2.0 response envelope.

type Transport

type Transport interface {
	// Do performs the request and returns the response body, status
	// code, and error. Implementations must honour req.Context().
	Do(req *http.Request) ([]byte, int, error)
}

Transport abstracts how a request is carried out so that --curl can short-circuit execution and emit the equivalent command instead.

type UsageError

type UsageError struct {
	Msg string
}

UsageError marks a caller-side mistake (bad flag, bad argument).

func (*UsageError) Error

func (e *UsageError) Error() string