// Package rpc is the Kubo HTTP RPC backend implementation. // // It speaks to Kubo's /api/v0/* endpoints using a plain http.Client rather // than kubo's own Go SDK, which pulls in half of libp2p for features // anchorage doesn't need. The RPC protocol is stable and small — six // endpoints cover everything we use. package rpc import ( "context" "encoding/json" "fmt" "io" "net/http" "net/url" "strings" "time" "anchorage/internal/pkg/ipfs" ) // Client is a Kubo RPC client. type Client struct { base *url.URL hc *http.Client } // Options configures a Client. type Options struct { // Endpoint is the Kubo RPC base URL, e.g. http://localhost:5001. Endpoint string // Timeout applies to every RPC call. 0 picks a safe default. Timeout time.Duration } // New builds a Client pointed at the given endpoint. func New(opts Options) (*Client, error) { if opts.Endpoint == "" { return nil, fmt.Errorf("rpc: Endpoint is required") } u, err := url.Parse(opts.Endpoint) if err != nil { return nil, fmt.Errorf("rpc: parse endpoint: %w", err) } timeout := opts.Timeout if timeout <= 0 { timeout = 2 * time.Minute } return &Client{ base: u, hc: &http.Client{Timeout: timeout}, }, nil } // Pin implements ipfs.Backend. // // Kubo's pin/add is idempotent by design: pinning a CID that's already // pinned returns success. func (c *Client) Pin(ctx context.Context, cid string, origins []string) error { q := url.Values{"arg": []string{cid}} for _, o := range origins { q.Add("origin", o) } return c.callEmpty(ctx, "pin/add", q) } // Unpin implements ipfs.Backend. Kubo returns 500 if the CID isn't // pinned; we translate that into ErrNotFound. func (c *Client) Unpin(ctx context.Context, cid string) error { q := url.Values{"arg": []string{cid}} if err := c.callEmpty(ctx, "pin/rm", q); err != nil { if strings.Contains(err.Error(), "not pinned") { return ipfs.ErrNotFound } return err } return nil } // Status implements ipfs.Backend. func (c *Client) Status(ctx context.Context, cid string) (*ipfs.PinStatus, error) { q := url.Values{"arg": []string{cid}} var out struct { Keys map[string]struct { Type string `json:"Type"` } `json:"Keys"` } err := c.call(ctx, "pin/ls", q, &out) if err != nil { if strings.Contains(err.Error(), "is not pinned") { return &ipfs.PinStatus{CID: cid, Pinned: false}, nil } return nil, err } entry, ok := out.Keys[cid] if !ok { return &ipfs.PinStatus{CID: cid, Pinned: false}, nil } return &ipfs.PinStatus{CID: cid, Pinned: true, Type: entry.Type}, nil } // List implements ipfs.Backend. Returns only recursive pins so indirect // children aren't counted separately. func (c *Client) List(ctx context.Context) ([]string, error) { q := url.Values{"type": []string{"recursive"}} var out struct { Keys map[string]struct { Type string `json:"Type"` } `json:"Keys"` } if err := c.call(ctx, "pin/ls", q, &out); err != nil { return nil, err } cids := make([]string, 0, len(out.Keys)) for k := range out.Keys { cids = append(cids, k) } return cids, nil } // ID implements ipfs.Backend. func (c *Client) ID(ctx context.Context) (*ipfs.IDInfo, error) { var out struct { ID string `json:"ID"` Addresses []string `json:"Addresses"` } if err := c.call(ctx, "id", nil, &out); err != nil { return nil, err } return &ipfs.IDInfo{PeerID: out.ID, Addresses: out.Addresses}, nil } // call invokes /api/v0/ with the given query params and decodes // the JSON response into out. Kubo uses POST for every endpoint, even // pure reads, and returns newline-delimited JSON for streaming ops. func (c *Client) call(ctx context.Context, path string, q url.Values, out any) error { u := *c.base u.Path = "/api/v0/" + path if q != nil { u.RawQuery = q.Encode() } req, err := http.NewRequestWithContext(ctx, http.MethodPost, u.String(), nil) if err != nil { return err } resp, err := c.hc.Do(req) if err != nil { return fmt.Errorf("kubo %s: %w", path, err) } defer resp.Body.Close() body, err := io.ReadAll(resp.Body) if err != nil { return fmt.Errorf("read %s: %w", path, err) } if resp.StatusCode >= 400 { return fmt.Errorf("kubo %s: status %d: %s", path, resp.StatusCode, string(body)) } if out == nil { return nil } if err := json.Unmarshal(body, out); err != nil { return fmt.Errorf("decode %s: %w (body=%s)", path, err, string(body)) } return nil } func (c *Client) callEmpty(ctx context.Context, path string, q url.Values) error { return c.call(ctx, path, q, nil) }