Documentation
¶
Overview ¶
Package filbeam provides a client for FilBeam stats and retrieval APIs.
FilBeam is Filecoin's pay-per-byte infrastructure. This client exposes remaining egress quota for FWSS data sets: CDN cache-hit egress and cache-miss egress (retrieval from storage providers), plus CDN-backed piece downloads for a specific owner address.
Usage:
svc, err := filbeam.New(filbeam.Options{Chain: chain.Calibration})
if err != nil {
// handle error (e.g. unsupported chain)
}
stats, err := svc.GetDataSetStats(ctx, types.NewBigInt(12345))
Stability ¶
0.x phase: public API may change between minor releases.
Example ¶
Example demonstrates fetching dataset stats via filbeam.Service. In practice a Service is obtained from synapse.Client.FilBeam.
package main
import (
"context"
"fmt"
"log"
"github.com/strahe/synapse-go/filbeam"
"github.com/strahe/synapse-go/types"
)
func main() {
var svc *filbeam.Service // obtained from synapse.Client.FilBeam()
ctx := context.Background()
stats, err := svc.GetDataSetStats(ctx, types.NewBigInt(42))
if err != nil {
log.Fatal(err)
}
fmt.Println(stats.CDNEgressQuota)
}
Output:
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrClosed = lifecycle.ErrClosed
ErrClosed is returned when a method is called after the owning Client has been closed. It aliases the shared closed-client sentinel.
var ErrDataSetNotFound = errors.New("filbeam: data set not found")
ErrDataSetNotFound is returned by GetDataSetStats when the dataset does not exist on the FilBeam stats API (HTTP 404).
var ErrInvalidArgument = errors.New("filbeam: invalid argument")
ErrInvalidArgument is returned when a caller passes a zero or otherwise invalid argument to a Service method.
var ErrUninitialized = errors.New("filbeam: service not initialized; use filbeam.New")
ErrUninitialized is returned when a method is invoked on a zero-value Service (one that was not constructed via New).
Functions ¶
This section is empty.
Types ¶
type DataSetStats ¶
type DataSetStats struct {
// CDNEgressQuota is the remaining bytes that can be served from
// FilBeam's cache (fast, direct CDN delivery — cache hits).
CDNEgressQuota *big.Int
// CacheMissEgressQuota is the remaining bytes that can be retrieved
// from storage providers (triggers caching on first fetch).
CacheMissEgressQuota *big.Int
}
DataSetStats contains the remaining pay-per-byte egress quotas for a FilBeam data set. Values decrease as data is served and represent how many bytes can still be retrieved before adding more credits.
type Options ¶
type Options struct {
// Chain selects the FilBeam environment. Only chain.Mainnet and
// chain.Calibration are supported; any other value causes New to
// return an error wrapping chain.ErrUnknownChain.
// Zero value is chain.Mainnet.
Chain chain.Chain
// HTTPClient is the HTTP client used for API requests.
// If nil, http.DefaultClient is used.
HTTPClient *http.Client
// RetrievalDomain overrides the chain default FilBeam retrieval domain.
// Leave empty for the built-in Mainnet / Calibration defaults.
RetrievalDomain string
// Logger is the structured logger. If nil, logging is silent.
Logger *slog.Logger
// Lifecycle, when non-nil, ties this Service to the owning Client's
// close state. After the Lifecycle is closed, every method returns
// ErrClosed. Nil is allowed for standalone use.
Lifecycle *lifecycle.Lifecycle
}
Options configures a Service.
type Retriever ¶ added in v0.2.0
type Retriever struct {
// contains filtered or unexported fields
}
Retriever downloads pieces through FilBeam for one owner address. It is safe for concurrent use.
func (*Retriever) DownloadPiece ¶ added in v0.2.0
DownloadPiece downloads a PieceCID through FilBeam.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is a client for the FilBeam stats and retrieval APIs. It is safe for concurrent use.
func New ¶
New creates a Service for the given chain. Returns an error wrapping chain.ErrUnknownChain if opts.Chain is not a supported FilBeam network.
func (*Service) GetDataSetStats ¶
func (s *Service) GetDataSetStats(ctx context.Context, dataSetID types.BigInt) (*DataSetStats, error)
GetDataSetStats fetches remaining egress quotas for a FWSS data set. Returns ErrDataSetNotFound when the data set does not exist on FilBeam.
Transient failures (most transport errors and HTTP 5xx) are retried with jittered exponential backoff. Errors matching context.Canceled or context.DeadlineExceeded are returned immediately; non-transient statuses (4xx other than 404) and decode errors are also returned without retry.
Source Files