feat(rpc): JSON-RPC 2.0 client transport and response types
Co-Authored-By: Charon <charon@lethean.io> Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Claude
parent
1fdd8d47d7
commit
03c11b3bbd
3 changed files with 395 additions and 0 deletions
153
rpc/client.go
Normal file
153
rpc/client.go
Normal file
|
|
@ -0,0 +1,153 @@
|
||||||
|
// Copyright (c) 2017-2026 Lethean (https://lt.hn)
|
||||||
|
//
|
||||||
|
// Licensed under the European Union Public Licence (EUPL) version 1.2.
|
||||||
|
// SPDX-License-Identifier: EUPL-1.2
|
||||||
|
|
||||||
|
// Package rpc provides a typed client for the Lethean daemon JSON-RPC API.
|
||||||
|
package rpc
|
||||||
|
|
||||||
|
import (
|
||||||
|
"bytes"
|
||||||
|
"encoding/json"
|
||||||
|
"fmt"
|
||||||
|
"io"
|
||||||
|
"net/http"
|
||||||
|
"net/url"
|
||||||
|
"time"
|
||||||
|
)
|
||||||
|
|
||||||
|
// Client is a Lethean daemon RPC client.
|
||||||
|
type Client struct {
|
||||||
|
url string // Base URL with /json_rpc path for JSON-RPC calls.
|
||||||
|
baseURL string // Base URL without path for legacy calls.
|
||||||
|
httpClient *http.Client
|
||||||
|
}
|
||||||
|
|
||||||
|
// NewClient creates a client for the daemon at the given URL.
|
||||||
|
// If the URL has no path, "/json_rpc" is appended automatically.
|
||||||
|
func NewClient(daemonURL string) *Client {
|
||||||
|
return NewClientWithHTTP(daemonURL, &http.Client{Timeout: 30 * time.Second})
|
||||||
|
}
|
||||||
|
|
||||||
|
// NewClientWithHTTP creates a client with a custom http.Client.
|
||||||
|
func NewClientWithHTTP(daemonURL string, httpClient *http.Client) *Client {
|
||||||
|
u, err := url.Parse(daemonURL)
|
||||||
|
if err != nil {
|
||||||
|
// Fall through with raw URL.
|
||||||
|
return &Client{url: daemonURL + "/json_rpc", baseURL: daemonURL, httpClient: httpClient}
|
||||||
|
}
|
||||||
|
baseURL := fmt.Sprintf("%s://%s", u.Scheme, u.Host)
|
||||||
|
if u.Path == "" || u.Path == "/" {
|
||||||
|
u.Path = "/json_rpc"
|
||||||
|
}
|
||||||
|
return &Client{
|
||||||
|
url: u.String(),
|
||||||
|
baseURL: baseURL,
|
||||||
|
httpClient: httpClient,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// RPCError represents a JSON-RPC error returned by the daemon.
|
||||||
|
type RPCError struct {
|
||||||
|
Code int `json:"code"`
|
||||||
|
Message string `json:"message"`
|
||||||
|
}
|
||||||
|
|
||||||
|
func (e *RPCError) Error() string {
|
||||||
|
return fmt.Sprintf("rpc error %d: %s", e.Code, e.Message)
|
||||||
|
}
|
||||||
|
|
||||||
|
// JSON-RPC 2.0 envelope types.
|
||||||
|
type jsonRPCRequest struct {
|
||||||
|
JSONRPC string `json:"jsonrpc"`
|
||||||
|
ID string `json:"id"`
|
||||||
|
Method string `json:"method"`
|
||||||
|
Params any `json:"params"`
|
||||||
|
}
|
||||||
|
|
||||||
|
type jsonRPCResponse struct {
|
||||||
|
JSONRPC string `json:"jsonrpc"`
|
||||||
|
ID json.RawMessage `json:"id"`
|
||||||
|
Result json.RawMessage `json:"result"`
|
||||||
|
Error *jsonRPCError `json:"error,omitempty"`
|
||||||
|
}
|
||||||
|
|
||||||
|
type jsonRPCError struct {
|
||||||
|
Code int `json:"code"`
|
||||||
|
Message string `json:"message"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// call makes a JSON-RPC 2.0 call to /json_rpc.
|
||||||
|
func (c *Client) call(method string, params any, result any) error {
|
||||||
|
reqBody, err := json.Marshal(jsonRPCRequest{
|
||||||
|
JSONRPC: "2.0",
|
||||||
|
ID: "0",
|
||||||
|
Method: method,
|
||||||
|
Params: params,
|
||||||
|
})
|
||||||
|
if err != nil {
|
||||||
|
return fmt.Errorf("marshal request: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
resp, err := c.httpClient.Post(c.url, "application/json", bytes.NewReader(reqBody))
|
||||||
|
if err != nil {
|
||||||
|
return fmt.Errorf("post %s: %w", method, err)
|
||||||
|
}
|
||||||
|
defer resp.Body.Close()
|
||||||
|
|
||||||
|
if resp.StatusCode != http.StatusOK {
|
||||||
|
return fmt.Errorf("http %d from %s", resp.StatusCode, method)
|
||||||
|
}
|
||||||
|
|
||||||
|
body, err := io.ReadAll(resp.Body)
|
||||||
|
if err != nil {
|
||||||
|
return fmt.Errorf("read response: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
var rpcResp jsonRPCResponse
|
||||||
|
if err := json.Unmarshal(body, &rpcResp); err != nil {
|
||||||
|
return fmt.Errorf("unmarshal response: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
if rpcResp.Error != nil {
|
||||||
|
return &RPCError{Code: rpcResp.Error.Code, Message: rpcResp.Error.Message}
|
||||||
|
}
|
||||||
|
|
||||||
|
if result != nil && len(rpcResp.Result) > 0 {
|
||||||
|
if err := json.Unmarshal(rpcResp.Result, result); err != nil {
|
||||||
|
return fmt.Errorf("unmarshal result: %w", err)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
|
||||||
|
// legacyCall makes a plain JSON POST to a legacy URI path (e.g. /getheight).
|
||||||
|
func (c *Client) legacyCall(path string, params any, result any) error {
|
||||||
|
reqBody, err := json.Marshal(params)
|
||||||
|
if err != nil {
|
||||||
|
return fmt.Errorf("marshal request: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
url := c.baseURL + path
|
||||||
|
resp, err := c.httpClient.Post(url, "application/json", bytes.NewReader(reqBody))
|
||||||
|
if err != nil {
|
||||||
|
return fmt.Errorf("post %s: %w", path, err)
|
||||||
|
}
|
||||||
|
defer resp.Body.Close()
|
||||||
|
|
||||||
|
if resp.StatusCode != http.StatusOK {
|
||||||
|
return fmt.Errorf("http %d from %s", resp.StatusCode, path)
|
||||||
|
}
|
||||||
|
|
||||||
|
body, err := io.ReadAll(resp.Body)
|
||||||
|
if err != nil {
|
||||||
|
return fmt.Errorf("read response: %w", err)
|
||||||
|
}
|
||||||
|
|
||||||
|
if result != nil {
|
||||||
|
if err := json.Unmarshal(body, result); err != nil {
|
||||||
|
return fmt.Errorf("unmarshal response: %w", err)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return nil
|
||||||
|
}
|
||||||
164
rpc/client_test.go
Normal file
164
rpc/client_test.go
Normal file
|
|
@ -0,0 +1,164 @@
|
||||||
|
// Copyright (c) 2017-2026 Lethean (https://lt.hn)
|
||||||
|
//
|
||||||
|
// Licensed under the European Union Public Licence (EUPL) version 1.2.
|
||||||
|
// SPDX-License-Identifier: EUPL-1.2
|
||||||
|
|
||||||
|
package rpc
|
||||||
|
|
||||||
|
import (
|
||||||
|
"encoding/json"
|
||||||
|
"io"
|
||||||
|
"net/http"
|
||||||
|
"net/http/httptest"
|
||||||
|
"testing"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestClient_Good_JSONRPCCall(t *testing.T) {
|
||||||
|
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||||
|
// Verify request format.
|
||||||
|
if r.Method != http.MethodPost {
|
||||||
|
t.Errorf("method: got %s, want POST", r.Method)
|
||||||
|
}
|
||||||
|
if r.URL.Path != "/json_rpc" {
|
||||||
|
t.Errorf("path: got %s, want /json_rpc", r.URL.Path)
|
||||||
|
}
|
||||||
|
body, _ := io.ReadAll(r.Body)
|
||||||
|
var req jsonRPCRequest
|
||||||
|
json.Unmarshal(body, &req)
|
||||||
|
if req.JSONRPC != "2.0" {
|
||||||
|
t.Errorf("jsonrpc: got %q, want %q", req.JSONRPC, "2.0")
|
||||||
|
}
|
||||||
|
if req.Method != "getblockcount" {
|
||||||
|
t.Errorf("method: got %q, want %q", req.Method, "getblockcount")
|
||||||
|
}
|
||||||
|
|
||||||
|
// Return a valid response.
|
||||||
|
w.Header().Set("Content-Type", "application/json")
|
||||||
|
json.NewEncoder(w).Encode(jsonRPCResponse{
|
||||||
|
JSONRPC: "2.0",
|
||||||
|
ID: json.RawMessage(`"0"`),
|
||||||
|
Result: json.RawMessage(`{"count":6300,"status":"OK"}`),
|
||||||
|
})
|
||||||
|
}))
|
||||||
|
defer srv.Close()
|
||||||
|
|
||||||
|
c := NewClient(srv.URL)
|
||||||
|
var result struct {
|
||||||
|
Count uint64 `json:"count"`
|
||||||
|
Status string `json:"status"`
|
||||||
|
}
|
||||||
|
err := c.call("getblockcount", struct{}{}, &result)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("call: %v", err)
|
||||||
|
}
|
||||||
|
if result.Count != 6300 {
|
||||||
|
t.Errorf("count: got %d, want 6300", result.Count)
|
||||||
|
}
|
||||||
|
if result.Status != "OK" {
|
||||||
|
t.Errorf("status: got %q, want %q", result.Status, "OK")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestClient_Good_LegacyCall(t *testing.T) {
|
||||||
|
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||||
|
if r.URL.Path != "/getheight" {
|
||||||
|
t.Errorf("path: got %s, want /getheight", r.URL.Path)
|
||||||
|
}
|
||||||
|
w.Header().Set("Content-Type", "application/json")
|
||||||
|
w.Write([]byte(`{"height":6300,"status":"OK"}`))
|
||||||
|
}))
|
||||||
|
defer srv.Close()
|
||||||
|
|
||||||
|
c := NewClient(srv.URL)
|
||||||
|
var result struct {
|
||||||
|
Height uint64 `json:"height"`
|
||||||
|
Status string `json:"status"`
|
||||||
|
}
|
||||||
|
err := c.legacyCall("/getheight", struct{}{}, &result)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("legacyCall: %v", err)
|
||||||
|
}
|
||||||
|
if result.Height != 6300 {
|
||||||
|
t.Errorf("height: got %d, want 6300", result.Height)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestClient_Bad_RPCError(t *testing.T) {
|
||||||
|
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||||
|
w.Header().Set("Content-Type", "application/json")
|
||||||
|
json.NewEncoder(w).Encode(jsonRPCResponse{
|
||||||
|
JSONRPC: "2.0",
|
||||||
|
ID: json.RawMessage(`"0"`),
|
||||||
|
Error: &jsonRPCError{
|
||||||
|
Code: -2,
|
||||||
|
Message: "TOO_BIG_HEIGHT",
|
||||||
|
},
|
||||||
|
})
|
||||||
|
}))
|
||||||
|
defer srv.Close()
|
||||||
|
|
||||||
|
c := NewClient(srv.URL)
|
||||||
|
var result struct{}
|
||||||
|
err := c.call("getblockheaderbyheight", struct{ Height uint64 }{999999999}, &result)
|
||||||
|
if err == nil {
|
||||||
|
t.Fatal("expected error")
|
||||||
|
}
|
||||||
|
rpcErr, ok := err.(*RPCError)
|
||||||
|
if !ok {
|
||||||
|
t.Fatalf("expected *RPCError, got %T: %v", err, err)
|
||||||
|
}
|
||||||
|
if rpcErr.Code != -2 {
|
||||||
|
t.Errorf("code: got %d, want -2", rpcErr.Code)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestClient_Bad_ConnectionRefused(t *testing.T) {
|
||||||
|
c := NewClient("http://127.0.0.1:1") // Unlikely to be listening
|
||||||
|
var result struct{}
|
||||||
|
err := c.call("getblockcount", struct{}{}, &result)
|
||||||
|
if err == nil {
|
||||||
|
t.Fatal("expected connection error")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestClient_Good_URLAppendPath(t *testing.T) {
|
||||||
|
// NewClient should append /json_rpc if path is empty.
|
||||||
|
c := NewClient("http://localhost:46941")
|
||||||
|
if c.url != "http://localhost:46941/json_rpc" {
|
||||||
|
t.Errorf("url: got %q, want %q", c.url, "http://localhost:46941/json_rpc")
|
||||||
|
}
|
||||||
|
|
||||||
|
// If path already present, leave it alone.
|
||||||
|
c2 := NewClient("http://localhost:46941/json_rpc")
|
||||||
|
if c2.url != "http://localhost:46941/json_rpc" {
|
||||||
|
t.Errorf("url: got %q, want %q", c2.url, "http://localhost:46941/json_rpc")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestClient_Bad_InvalidJSON(t *testing.T) {
|
||||||
|
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||||
|
w.Write([]byte(`not json`))
|
||||||
|
}))
|
||||||
|
defer srv.Close()
|
||||||
|
|
||||||
|
c := NewClient(srv.URL)
|
||||||
|
var result struct{}
|
||||||
|
err := c.call("getblockcount", struct{}{}, &result)
|
||||||
|
if err == nil {
|
||||||
|
t.Fatal("expected error for invalid JSON")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestClient_Bad_HTTP500(t *testing.T) {
|
||||||
|
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||||
|
w.WriteHeader(http.StatusInternalServerError)
|
||||||
|
}))
|
||||||
|
defer srv.Close()
|
||||||
|
|
||||||
|
c := NewClient(srv.URL)
|
||||||
|
var result struct{}
|
||||||
|
err := c.call("getblockcount", struct{}{}, &result)
|
||||||
|
if err == nil {
|
||||||
|
t.Fatal("expected error for HTTP 500")
|
||||||
|
}
|
||||||
|
}
|
||||||
78
rpc/types.go
Normal file
78
rpc/types.go
Normal file
|
|
@ -0,0 +1,78 @@
|
||||||
|
// Copyright (c) 2017-2026 Lethean (https://lt.hn)
|
||||||
|
//
|
||||||
|
// Licensed under the European Union Public Licence (EUPL) version 1.2.
|
||||||
|
// SPDX-License-Identifier: EUPL-1.2
|
||||||
|
|
||||||
|
package rpc
|
||||||
|
|
||||||
|
// BlockHeader is a block header as returned by daemon RPC.
|
||||||
|
// Returned by getlastblockheader, getblockheaderbyheight, getblockheaderbyhash.
|
||||||
|
type BlockHeader struct {
|
||||||
|
MajorVersion uint8 `json:"major_version"`
|
||||||
|
MinorVersion uint8 `json:"minor_version"`
|
||||||
|
Timestamp uint64 `json:"timestamp"`
|
||||||
|
PrevHash string `json:"prev_hash"`
|
||||||
|
Nonce uint64 `json:"nonce"`
|
||||||
|
OrphanStatus bool `json:"orphan_status"`
|
||||||
|
Height uint64 `json:"height"`
|
||||||
|
Depth uint64 `json:"depth"`
|
||||||
|
Hash string `json:"hash"`
|
||||||
|
Difficulty string `json:"difficulty"`
|
||||||
|
Reward uint64 `json:"reward"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// DaemonInfo is the daemon status as returned by getinfo.
|
||||||
|
type DaemonInfo struct {
|
||||||
|
Height uint64 `json:"height"`
|
||||||
|
TxCount uint64 `json:"tx_count"`
|
||||||
|
TxPoolSize uint64 `json:"tx_pool_size"`
|
||||||
|
AltBlocksCount uint64 `json:"alt_blocks_count"`
|
||||||
|
OutgoingConnectionsCount uint64 `json:"outgoing_connections_count"`
|
||||||
|
IncomingConnectionsCount uint64 `json:"incoming_connections_count"`
|
||||||
|
SynchronizedConnectionsCount uint64 `json:"synchronized_connections_count"`
|
||||||
|
DaemonNetworkState uint64 `json:"daemon_network_state"`
|
||||||
|
SynchronizationStartHeight uint64 `json:"synchronization_start_height"`
|
||||||
|
MaxNetSeenHeight uint64 `json:"max_net_seen_height"`
|
||||||
|
PowDifficulty uint64 `json:"pow_difficulty"`
|
||||||
|
PosDifficulty string `json:"pos_difficulty"`
|
||||||
|
BlockReward uint64 `json:"block_reward"`
|
||||||
|
DefaultFee uint64 `json:"default_fee"`
|
||||||
|
MinimumFee uint64 `json:"minimum_fee"`
|
||||||
|
LastBlockTimestamp uint64 `json:"last_block_timestamp"`
|
||||||
|
LastBlockHash string `json:"last_block_hash"`
|
||||||
|
AliasCount uint64 `json:"alias_count"`
|
||||||
|
TotalCoins string `json:"total_coins"`
|
||||||
|
PosAllowed bool `json:"pos_allowed"`
|
||||||
|
CurrentMaxAllowedBlockSize uint64 `json:"current_max_allowed_block_size"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// BlockDetails is a full block with metadata as returned by get_blocks_details.
|
||||||
|
type BlockDetails struct {
|
||||||
|
Height uint64 `json:"height"`
|
||||||
|
Timestamp uint64 `json:"timestamp"`
|
||||||
|
ActualTimestamp uint64 `json:"actual_timestamp"`
|
||||||
|
BaseReward uint64 `json:"base_reward"`
|
||||||
|
SummaryReward uint64 `json:"summary_reward"`
|
||||||
|
TotalFee uint64 `json:"total_fee"`
|
||||||
|
ID string `json:"id"`
|
||||||
|
PrevID string `json:"prev_id"`
|
||||||
|
Difficulty string `json:"difficulty"`
|
||||||
|
Type uint64 `json:"type"`
|
||||||
|
IsOrphan bool `json:"is_orphan"`
|
||||||
|
CumulativeSize uint64 `json:"block_cumulative_size"`
|
||||||
|
Blob string `json:"blob"`
|
||||||
|
ObjectInJSON string `json:"object_in_json"`
|
||||||
|
Transactions []TxInfo `json:"transactions_details"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// TxInfo is transaction metadata as returned by get_tx_details.
|
||||||
|
type TxInfo struct {
|
||||||
|
ID string `json:"id"`
|
||||||
|
BlobSize uint64 `json:"blob_size"`
|
||||||
|
Fee uint64 `json:"fee"`
|
||||||
|
Amount uint64 `json:"amount"`
|
||||||
|
Timestamp uint64 `json:"timestamp"`
|
||||||
|
KeeperBlock int64 `json:"keeper_block"`
|
||||||
|
Blob string `json:"blob"`
|
||||||
|
ObjectInJSON string `json:"object_in_json"`
|
||||||
|
}
|
||||||
Loading…
Add table
Reference in a new issue