client

package
v0.38.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 9, 2026 License: Apache-2.0, MIT Imports: 33 Imported by: 12

Documentation

Overview

Package client implements an HTTP client for the Delegated Routing V1 API (IPIP-337).

The client supports finding content providers, peers, IPNS records, and closest DHT peers. Responses can be streamed as NDJSON or returned as plain JSON.

Basic Usage 

c, err := client.New("https://delegated-ipfs.dev")
if err != nil {
    // handle error
}

providers, err := c.FindProviders(ctx, cid)

Options

The client can be customized with functional options:

Index

Constants

This section is empty.

Variables

View Source 
var (
	ViewLatency = &view.View{
		Measure:     measureLatency,
		Aggregation: distMS,
		TagKeys:     []tag.Key{keyOperation, keyHost, keyStatusCode, keyError},
	}
	ViewLength = &view.View{
		Measure:     measureLength,
		Aggregation: distLength,
		TagKeys:     []tag.Key{keyOperation, keyHost},
	}
	// ViewRequests counts all requests (including errors)
	// Simple Grafana queries:
	//   - Total requests: routing_http_client_requests_total
	//   - Request rate: rate(routing_http_client_requests_total[5m])
	ViewRequests = &view.View{
		Measure:     measureRequests,
		Aggregation: view.Count(),
		TagKeys:     []tag.Key{keyOperation, keyHost},
	}
	// ViewPositiveResponses counts requests that returned at least 1 result
	// Simple Grafana queries:
	//   - Requests with results: routing_http_client_positive_responses_total
	//   - Success rate: positive_responses_total / requests_total
	//   - Empty/error rate: (requests_total - positive_responses_total) / requests_total
	ViewPositiveResponses = &view.View{
		Measure:     measurePositiveResponses,
		Aggregation: view.Count(),
		TagKeys:     []tag.Key{keyOperation, keyHost},
	}

	OpenCensusViews = []*view.View{
		ViewLatency,
		ViewLength,
		ViewRequests,
		ViewPositiveResponses,
	}
)
View Source 
var (
	DefaultProtocolFilter = []string{"unknown", "transport-bitswap"} // IPIP-484
)
View Source 
var ImportPath = importPath()

ImportPath is the canonical import path that allows us to identify official client builds vs modified forks, and use that info in User-Agent header.

Functions

This section is empty.

Types

type Client added in v0.14.0 

type Client struct {
	// contains filtered or unexported fields
}

func New 

func New(baseURL string, opts ...Option) (*Client, error)

New creates a content routing API client. The Provider and identity parameters are option. If they are nil, the client.ProvideBitswap method will not function.

func (*Client) FindPeers added in v0.14.0 

func (c *Client) FindPeers(ctx context.Context, pid peer.ID) (peers iter.ResultIter[*types.PeerRecord], err error)

FindPeers searches for information for the given peer.ID.

func (*Client) FindProviders added in v0.14.0 

func (c *Client) FindProviders(ctx context.Context, key cid.Cid) (providers iter.ResultIter[types.Record], err error)

FindProviders searches for providers that are able to provide the given cid.Cid. In a more generic way, it is also used as a mapping between CIDs and relevant metadata.

func (*Client) GetClosestPeers added in v0.36.0 

func (c *Client) GetClosestPeers(ctx context.Context, key cid.Cid) (peers iter.ResultIter[*types.PeerRecord], err error)

GetClosestPeers obtains the closest peers to the given key (CID or Peer ID).

func (*Client) GetIPNS added in v0.14.0 

func (c *Client) GetIPNS(ctx context.Context, name ipns.Name) (record *ipns.Record, err error)

GetIPNS tries to retrieve the ipns.Record for the given ipns.Name. The record is validated against the given name. If validation fails, an error is returned, but no record.

func (*Client) ProvideBitswap deprecated added in v0.14.0 

func (c *Client) ProvideBitswap(ctx context.Context, keys []cid.Cid, ttl time.Duration) (time.Duration, error)

Deprecated: historic API from IPIP-526, may be removed in a future version.

func (*Client) PutIPNS added in v0.14.0 

func (c *Client) PutIPNS(ctx context.Context, name ipns.Name, record *ipns.Record) (err error)

PutIPNS attempts at putting the given ipns.Record for the given ipns.Name.

type HTTPError 

type HTTPError struct {
	StatusCode int
	Body       string
}

func (*HTTPError) Error 

func (e *HTTPError) Error() string

type Option added in v0.9.0 

type Option func(*Client) error

func WithAddrFilter added in v0.24.0 

func WithAddrFilter(addrFilter []string) Option

WithAddrFilter adds an address filter to the client. The address filter is added to the request URL. The addresses are ordered alphabetically for cache key (url) consistency

func WithDisabledLocalFiltering added in v0.24.0 

func WithDisabledLocalFiltering(val bool) Option

WithDisabledLocalFiltering disables local filtering of the results. This should be used for delegated routing servers that already implement filtering

func WithHTTPClient 

func WithHTTPClient(h httpClient) Option

WithHTTPClient sets a custom HTTP Client to be used with Client.

func WithIdentity 

func WithIdentity(identity crypto.PrivKey) Option

func WithProtocolFilter added in v0.24.0 

func WithProtocolFilter(protocolFilter []string) Option

WithProtocolFilter adds a protocol filter to the client. The protocol filter is added to the request URL. The protocols are ordered alphabetically for cache key (url) consistency

func WithProviderInfo 

func WithProviderInfo(peerID peer.ID, addrs []multiaddr.Multiaddr) Option

WithProviderInfo sets the peer ID and static addresses used in provide requests. Mutually exclusive with WithProviderInfoFunc; if both are provided, WithProviderInfoFunc takes precedence.

func WithProviderInfoFunc added in v0.38.0 

func WithProviderInfoFunc(peerID peer.ID, addrsFunc func() []multiaddr.Multiaddr) Option

WithProviderInfoFunc is like WithProviderInfo but accepts a callback that is evaluated each time a provide request is made. Use this when addresses may change over the lifetime of the client (e.g., resolved from a libp2p host instead of static configuration). Mutually exclusive with WithProviderInfo; if both are provided, WithProviderInfoFunc takes precedence.

func WithStreamResultsRequired added in v0.9.0 

func WithStreamResultsRequired() Option

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent sets a custom user agent to use with the HTTP Client. This modifies the underlying http.Client. Therefore, you should not use the same HTTP Client with multiple routing clients.

This only works if using a http.Client with a ResponseBodyLimitedTransport set as its transport. Otherwise, an error will be returned.

type ResponseBodyLimitedTransport 

type ResponseBodyLimitedTransport struct {
	http.RoundTripper
	LimitBytes int64
	UserAgent  string
}

func (*ResponseBodyLimitedTransport) RoundTrip 

func (r *ResponseBodyLimitedTransport) RoundTrip(req *http.Request) (*http.Response, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.