Help us shape the future of Go! Take the 2026 Go Developer Survey

pdp

package
v0.7.1 Latest Latest
Warning

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

 Go to latest Published: Oct 25, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package pdp provides a Curio-compatible PDP provider HTTP client.

PDP endpoints are unauthenticated at the HTTP layer. Authorization for state-changing calls is carried inside the request body as caller-provided EIP-712 signed extraData.

Retry policy

Control-plane GET requests (getJSON and poll endpoints) retry on transient errors — HTTP 5xx (except 501), 429, connection resets, DNS temporaries, unexpected EOF, and request timeouts — with exponential backoff up to MaxRetries. Ping follows the same transient HTTP and transport retry policy, but succeeds only when a 2xx response body is at most 64 bytes and trims exactly to "curio-pdp". This identity response requires Curio v1.28.3 or later. Empty, oversized, or different complete successful bodies match ErrPingResponseMismatch and are not retried. Response-body read failures preserve their I/O and HTTP classifications and follow the transient retry policy.

Streaming GET and PUT requests have no total HTTP timeout by default and use the caller's context to limit their lifetime. WithHTTPClient applies a custom client's timeout to control and streaming requests; WithStreamingHTTPClient overrides only streaming requests. Piece downloads and streaming uploads do not go through the automatic retry loop. Non-success PDP HTTP responses surface *HTTPError. Use errors.AsType[*pdp.HTTPError] to inspect status code, response body, and Retry-After. Legacy providers reporting a full deletion queue additionally match ErrTooManyPiecesQueued; the wrapped *HTTPError remains available.

POST and DELETE requests are executed exactly once unless an endpoint documents server-side idempotency. The PullPieces POST is retried for transient failures because the provider de-duplicates by request body and returns the existing pull status for repeated calls. A full provider pull queue (HTTP 429) is not retried: PullPieces returns an error matching ErrPullQueueFull, and WaitForPullComplete waits for the provider's Retry-After before sending the request again. Other state-changing POST/DELETE endpoints are not retried: a client-side retry after a server-side partial success can cause duplicate work or inconsistent state.

Add-pieces limits

AddPieces, CreateDataSetAndAddPieces, and PullPieces reject requests whose encoded PDPVerifier.addPieces calldata exceeds MaxAddPiecesMessageSize (65,248 bytes). Metadata and signatures consume part of that budget. Existing legacy data sets also have an 80-piece limit, MaxLegacyAddPiecesBatchSize. Configure WithLegacyPieceStorageIDLimit with the chain's first compact data set ID; zero (the standalone default) skips the legacy count check. New and compact data sets have no fixed piece-count limit. MaxAddPiecesBatchSize is deprecated and no longer enforced. Use EstimateAddPiecesMessageSize when constructing a batch; these methods do not split oversized requests.

Deletion requests

SchedulePieceDeletions has no fixed piece-count limit. Contract, gas, and transaction-size limits still apply. Each request is sent once and is not split or retried. MaxDeletePiecesBatchSize is deprecated and unused by SDK validation. Piece IDs must be unique and within 0..math.MaxInt64; callers provide extraData signed for the complete ordered batch.

Status URLs

Transaction status URLs must be absolute HTTP(S) URLs with the same scheme, hostname, and effective port as the client's service URL, and their final path segment must be a nonzero transaction hash. Status responses must report the same hash. The origin check is applied to every redirect. This pins recovery handles to their provider origin and transaction; it does not block private addresses or DNS rebinding.

Response size cap

Control-plane JSON responses are capped at MaxControlResponseBytes (16 MiB). Anything larger is treated as a server bug or attack and fails the request. Streaming endpoints (piece download) are not subject to this cap.

Endpoints covered:

  • GET /piece/{pieceCid} (download bytes)
  • GET /pdp/ping (strict Curio identity)
  • POST /pdp/piece/uploads (create upload)
  • PUT /pdp/piece/uploads/{uploadUUID} (upload bytes)
  • POST /pdp/piece/uploads/{uploadUUID} (finalize upload)
  • GET /pdp/piece?pieceCid=... (find)
  • POST /pdp/piece/pull (pull pieces)
  • POST /pdp/data-sets (create)
  • GET /pdp/data-sets/created/{txHash} (poll create)
  • GET /pdp/data-sets/{id} (read)
  • POST /pdp/data-sets/{id}/pieces (add pieces)
  • GET /pdp/data-sets/{id}/pieces/added/{txHash} (poll add)
  • DELETE /pdp/data-sets/{id}/pieces/{pieceId} (schedule remove)

Index

Constants

View Source 
const (
	// MaxAddPiecesBatchSize is the former temporary piece-count limit.
	//
	// Deprecated: use MaxLegacyAddPiecesBatchSize for legacy data sets and
	// MaxAddPiecesMessageSize for all requests.
	MaxAddPiecesBatchSize = 40
	// MaxLegacyAddPiecesBatchSize is the piece-count limit for legacy data sets.
	MaxLegacyAddPiecesBatchSize = 80
	// MaxAddPiecesMessageSize is the maximum encoded PDPVerifier.addPieces
	// calldata size accepted by the Filecoin message path.
	MaxAddPiecesMessageSize = 64*1024 - 288
	// MaxDeletePiecesBatchSize is the former deletion request count limit.
	//
	// Deprecated: deletion requests have no fixed count limit. Contract and
	// transaction limits still apply.
	MaxDeletePiecesBatchSize = 35
)
View Source 
const DefaultHTTPTimeout = 30 * time.Second

DefaultHTTPTimeout applies to control requests. Streaming requests have no total HTTP timeout by default and can be bounded by the caller's context.

View Source 
const DefaultMaxRetries = 3

DefaultMaxRetries is the number of retries attempted for transient failures (5xx, 429, network errors) when no explicit value is set.

View Source 
const DefaultUserAgent = "synapse-go/pdp"

DefaultUserAgent is set on every outgoing request unless overridden.

View Source 
const MaxControlResponseBytes = 16 << 20 // 16 MiB

MaxControlResponseBytes caps the size of control-plane JSON response bodies read fully into memory. PDP provider control-plane endpoints return small JSON documents (dataset status, piece IDs, etc.); anything larger indicates a buggy or hostile server and should not be allowed to exhaust client memory. Streaming endpoints (piece download) bypass this limit.

Variables

View Source 
var ErrAddPiecesMessageTooLarge = errors.New("pdp: add-pieces message too large")

ErrAddPiecesMessageTooLarge is matched when the encoded PDPVerifier.addPieces calldata exceeds MaxAddPiecesMessageSize.

View Source 
var ErrInvalidStatus = errors.New("pdp: invalid status response")

ErrInvalidStatus is returned when a provider status response is unknown, incomplete, or internally inconsistent.

View Source 
var ErrInvalidStatusURL = errors.New("pdp: invalid status URL")

ErrInvalidStatusURL is returned when a provider status URL is malformed or does not identify a transaction status resource.

View Source 
var ErrLocationHeader = errors.New("pdp: missing or invalid Location header")

ErrLocationHeader is returned when the server responds successfully but the expected Location header is missing or malformed.

View Source 
var ErrPieceNotFound = errors.New("pdp: piece not found")

ErrPieceNotFound is returned when GET /pdp/piece returns 404.

View Source 
var ErrPieceProcessing = errors.New("pdp: piece still processing")

ErrPieceProcessing is returned when GET /pdp/piece returns 202, meaning the piece is known but not yet parked and queryable.

View Source 
var ErrPingResponseMismatch = errors.New("pdp: ping response mismatch")

ErrPingResponseMismatch is returned when /pdp/ping responds successfully but its bounded response body is not the Curio PDP identity token.

View Source 
var ErrPullFailed = errors.New("pdp: pull failed")

ErrPullFailed is returned by WaitForPullComplete when the server reports that the overall pull status is "failed".

View Source 
var ErrPullQueueFull = errors.New("pdp: provider pull queue is full; retry later")

ErrPullQueueFull is returned when a provider declines a new pull because its pull queue is full. The provider records nothing, so the same request can be sent again later; the wrapped *HTTPError carries any Retry-After delay.

View Source 
var ErrStatusURLOrigin = errors.New("pdp: status URL origin mismatch")

ErrStatusURLOrigin is returned when a provider status URL does not use the same origin as the PDP client, or redirects to another origin.

View Source 
var ErrTooManyPieces = errors.New("pdp: too many pieces")

ErrTooManyPieces is returned when a piece batch exceeds the corresponding add or delete request limit.

View Source 
var ErrTooManyPiecesQueued = errors.New("pdp: piece deletion queue is full; retry after the next proving period")

ErrTooManyPiecesQueued is returned when a provider cannot schedule more piece deletions until its on-chain removal queue has been processed.

View Source 
var ErrTxRejected = errors.New("pdp: transaction rejected")

ErrTxRejected is returned when an on-chain operation posted by the SP was rejected, failed, or removed from the canonical chain by a reorganization.

Functions

func EstimateAddPiecesMessageSize added in v0.6.0 

func EstimateAddPiecesMessageSize(pieces []AddPieceInput, extraData []byte) (int, error)

EstimateAddPiecesMessageSize returns the encoded PDPVerifier.addPieces calldata size in bytes, including the four-byte method selector. It does not enforce the provider's piece-count or message-size limits.

Types

type AddPieceInput 

type AddPieceInput struct {
	PieceCID cid.Cid
}

AddPieceInput mirrors one entry of the pieces array for POST /pdp/data-sets/{id}/pieces. The wire format uses the piece CID as its own single sub-piece. PieceCID must be a PieceCIDv2 whose raw size is between chain.MinUploadSize and chain.MaxUploadSize.

type AddPiecesMessageTooLargeError added in v0.6.0 

type AddPiecesMessageTooLargeError struct {
	Size int
	Max  int
}

AddPiecesMessageTooLargeError reports the encoded calldata size and limit.

func (*AddPiecesMessageTooLargeError) Error added in v0.6.0 

func (e *AddPiecesMessageTooLargeError) Error() string

func (*AddPiecesMessageTooLargeError) Is added in v0.6.0 

func (e *AddPiecesMessageTooLargeError) Is(target error) bool

Is makes AddPiecesMessageTooLargeError match ErrAddPiecesMessageTooLarge.

type AddPiecesResult 

type AddPiecesResult struct {
	TxHash    common.Hash
	StatusURL string
}

AddPiecesResult is what the client gets back from a successful POST.

type AddPiecesStatus 

type AddPiecesStatus struct {
	TxHash          common.Hash  `json:"-"`
	ConfirmedTxHash common.Hash  `json:"-"`
	TxStatus        string       `json:"txStatus"`
	DataSetID       types.BigInt `json:"-"`
	// PieceCount may be zero while processing is pending or after rejection. A
	// successful response reports the full number of add entries.
	PieceCount        int            `json:"pieceCount"`
	AddMessageOK      *bool          `json:"addMessageOk"`
	PiecesAdded       bool           `json:"piecesAdded"`
	ConfirmedPieceIDs []types.BigInt `json:"-"`
}

AddPiecesStatus mirrors GET /pdp/data-sets/{id}/pieces/added/{txHash}. TxStatus reports the provider's wire status. Callers should use the error returned by GetAddPiecesStatus instead of interpreting it directly. Providers report pending, confirmed, failed, or reorged; rejected is also accepted for compatibility.

type Client 

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

Client is a thin HTTP client for a single PDP provider service URL. Safe for concurrent use.

func New 

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

New constructs a Client pointing at the given service URL (e.g. https://pdp.example.com).

func (*Client) AddPieces 

func (c *Client) AddPieces(ctx context.Context, dataSetID types.BigInt, pieces []AddPieceInput, extraData []byte) (*AddPiecesResult, error)

AddPieces calls POST /pdp/data-sets/{dataSetId}/pieces. extraData must be caller-provided EIP-712 signed data encoded as the PDP provider expects. Piece CIDs must be unique within one request after PieceCIDv2-to-v1 normalization; the same CID may be used again in a later request. Requests exceeding MaxAddPiecesMessageSize are rejected before submission. When the configured cutoff identifies a legacy data set, MaxLegacyAddPiecesBatchSize also applies.

func (*Client) BaseURL 

func (c *Client) BaseURL() *url.URL

BaseURL returns a copy of the configured base URL.

func (*Client) CreateDataSet 

func (c *Client) CreateDataSet(ctx context.Context, recordKeeper common.Address, extraData []byte) (*CreateDataSetResult, error)

CreateDataSet calls POST /pdp/data-sets. extraData must be an EIP-712 signed blob encoded as the PDP provider expects.

func (*Client) CreateDataSetAndAddPieces 

func (c *Client) CreateDataSetAndAddPieces(
	ctx context.Context,
	recordKeeper common.Address,
	pieces []AddPieceInput,
	extraData []byte,
) (*CreateDataSetResult, error)

CreateDataSetAndAddPieces calls POST /pdp/data-sets/create-and-add.

The provider creates a dataset and immediately submits the add-pieces transaction using the caller-provided EIP-712 signed extraData for the combined create+add flow. Piece CIDs must be unique within the request after PieceCIDv2-to-v1 normalization. Requests exceeding MaxAddPiecesMessageSize are rejected before submission; there is no fixed piece-count limit.

func (*Client) DownloadPiece 

func (c *Client) DownloadPiece(ctx context.Context, pieceCID cid.Cid) (io.ReadCloser, int64, error)

DownloadPiece calls GET /piece/{pieceCid} and returns a streaming io.ReadCloser plus the Content-Length (-1 when unknown). The caller must close the reader when done.

Downloads have no total HTTP timeout by default. A custom streaming client's Timeout and the caller's context both bound the download lifetime.

func (*Client) FindPiece 

func (c *Client) FindPiece(ctx context.Context, pieceCID cid.Cid) (*FindPieceResult, error)

FindPiece calls GET /pdp/piece?pieceCid=.... It returns ErrPieceNotFound for HTTP 404 and ErrPieceProcessing for HTTP 202 while the SP is still parking the piece.

func (*Client) GetAddPiecesStatus 

func (c *Client) GetAddPiecesStatus(ctx context.Context, statusURL string) (*AddPiecesStatus, error)

GetAddPiecesStatus polls the status URL once. Providers may return either HTTP 200 or 202 with the same JSON body shape.

func (*Client) GetCreateDataSetAndAddPiecesStatus added in v0.5.0 

func (c *Client) GetCreateDataSetAndAddPiecesStatus(
	ctx context.Context,
	statusURL string,
) (*CreateAndAddPiecesStatus, error)

GetCreateDataSetAndAddPiecesStatus checks a combined create-and-add submission once. It does not wait for either stage to advance.

func (*Client) GetDataSet 

func (c *Client) GetDataSet(ctx context.Context, dataSetID types.BigInt) (*DataSet, error)

GetDataSet calls GET /pdp/data-sets/{dataSetId}.

func (*Client) GetDataSetCreationStatus 

func (c *Client) GetDataSetCreationStatus(ctx context.Context, statusURL string) (*CreateDataSetStatus, error)

GetDataSetCreationStatus polls the status URL once. Providers may return either HTTP 200 or 202 with the same JSON body shape.

func (*Client) GetTerminateServiceStatus added in v0.4.0 

func (c *Client) GetTerminateServiceStatus(ctx context.Context, dataSetID types.BigInt) (*TerminateServiceStatus, error)

GetTerminateServiceStatus reads the provider termination status once.

func (*Client) Ping 

func (c *Client) Ping(ctx context.Context) error

Ping issues GET /pdp/ping and accepts only a 2xx response whose trimmed body is exactly "curio-pdp". Responses larger than 64 bytes are rejected. The identity response is supported by Curio v1.28.3 and later.

func (*Client) PullPieces 

func (c *Client) PullPieces(ctx context.Context, req PullRequest) (*PullResult, error)

PullPieces calls POST /pdp/piece/pull to request that this SP pull the given pieces from the source URLs.

The endpoint is idempotent: calling again with the same extraData returns the status of the existing pull request rather than creating a duplicate. This makes it safe to poll for status using repeated calls. Transient failures are retried. When the provider's pull queue is full, the error matches ErrPullQueueFull and is returned without retrying; send the same request again after the wrapped *HTTPError's RetryAfter. Requests exceeding MaxAddPiecesMessageSize are rejected before submission. Existing legacy data sets also have a MaxLegacyAddPiecesBatchSize count limit when WithLegacyPieceStorageIDLimit configures their deployment's cutoff.

func (*Client) SchedulePieceDeletions added in v0.5.1 

func (c *Client) SchedulePieceDeletions(ctx context.Context, dataSetID types.BigInt, pieceIDs []types.BigInt, extraData []byte) (common.Hash, error)

SchedulePieceDeletions issues DELETE /pdp/data-sets/{id}/pieces/{pieceId} with the provided EIP-712 signed extraData. pieceIDs must be unique and in the same order used to construct extraData.

func (*Client) TerminateService added in v0.4.0 

func (c *Client) TerminateService(ctx context.Context, req TerminateServiceRequest) (*TerminateServiceResult, error)

TerminateService requests provider-relayed service termination.

func (*Client) TerminateServiceStatusURL added in v0.4.0 

func (c *Client) TerminateServiceStatusURL(dataSetID types.BigInt) (string, error)

TerminateServiceStatusURL returns the provider status URL for a data set.

func (*Client) UploadPieceStreaming 

func (c *Client) UploadPieceStreaming(
	ctx context.Context,
	data io.Reader,
	opts UploadPieceStreamingOptions,
) (*UploadStreamingResult, error)

UploadPieceStreaming uploads a piece using the CommP-last 3-step streaming protocol. This is the preferred upload path: data is streamed to the server in a single pass while the PieceCID is computed inline (either by the client via TeeReader or by the caller in advance).

Protocol:

  1. POST /pdp/piece/uploads — create upload session, get UUID
  2. PUT /pdp/piece/uploads/{uuid} — stream body; commP is computed in this pass (unless opts.PieceCID is pre-filled)
  3. POST /pdp/piece/uploads/{uuid} — finalize with the PieceCID; server validates that the uploaded bytes hash to the same value

The default streaming HTTP client has no total timeout. A context deadline or a custom HTTP client's Timeout can bound the PUT. Session creation and finalization use the control HTTP client.

func (*Client) WaitForCreateDataSetAndAddPieces 

func (c *Client) WaitForCreateDataSetAndAddPieces(
	ctx context.Context,
	statusURL string,
	pollInterval time.Duration,
) (*AddPiecesStatus, error)

WaitForCreateDataSetAndAddPieces polls the one-shot combined status check until both stages are confirmed or the transaction is rejected.

func (*Client) WaitForDataSetCreated 

func (c *Client) WaitForDataSetCreated(ctx context.Context, statusURL string, pollInterval time.Duration) (*CreateDataSetStatus, error)

WaitForDataSetCreated polls until the server reports txStatus=confirmed with dataSetCreated=true (success) or a rejected transaction (ErrTxRejected). pollInterval defaults to 4 seconds.

func (*Client) WaitForPieceParked 

func (c *Client) WaitForPieceParked(ctx context.Context, pieceCID cid.Cid, pollInterval time.Duration) error

WaitForPieceParked polls FindPiece until the piece is found or the context is cancelled / timeout is reached. A zero pollInterval defaults to one second.

func (*Client) WaitForPiecesAdded 

func (c *Client) WaitForPiecesAdded(ctx context.Context, statusURL string, pollInterval time.Duration) (*AddPiecesStatus, error)

WaitForPiecesAdded polls until the add-pieces tx is confirmed with piecesAdded=true or rejected. pollInterval defaults to 4s.

func (*Client) WaitForPullComplete 

func (c *Client) WaitForPullComplete(
	ctx context.Context,
	req PullRequest,
	pollInterval time.Duration,
	onStatus func(*PullResult),
) (*PullResult, error)

WaitForPullComplete polls PullPieces until the overall pull status is "complete" or "failed". On failure it returns (result, ErrPullFailed) so callers can inspect the per-piece statuses. When the provider's pull queue is full, it waits for the provider's Retry-After (one minute when absent or under a second, at most five minutes) and sends the request again until ctx ends. An overall "complete" result can contain failed pieces when another piece completed; callers requiring every piece must inspect the per-piece statuses.

onStatus is invoked after each poll (may be nil). A zero pollInterval defaults to 4 seconds.

func (*Client) WaitForTerminateService added in v0.4.0 

func (c *Client) WaitForTerminateService(
	ctx context.Context,
	dataSetID types.BigInt,
	pollInterval time.Duration,
	onHash func(common.Hash),
	opts ...WaitForTerminateServiceOption,
) (*TerminateServiceStatus, error)

WaitForTerminateService polls termination status until FWSS termination is confirmed. Waiting errors return the last successfully read status.

onHash runs synchronously at most once for an original hash newly observed during this wait. A hash supplied by WithKnownTerminationTxHash is not notified. Callback panics propagate to the caller.

type CreateAndAddPiecesStatus added in v0.5.0 

type CreateAndAddPiecesStatus struct {
	Create *CreateDataSetStatus
	Add    *AddPiecesStatus
}

CreateAndAddPiecesStatus contains the available status snapshots for a combined create-and-add submission. Add is nil until data-set creation has completed and the add-pieces endpoint can be queried.

type CreateDataSetRequest 

type CreateDataSetRequest struct {
	RecordKeeper common.Address `json:"recordKeeper"`
	ExtraData    string         `json:"extraData"` // 0x-prefixed hex
}

CreateDataSetRequest is the body of POST /pdp/data-sets.

type CreateDataSetResult 

type CreateDataSetResult struct {
	TxHash    common.Hash
	StatusURL string
}

CreateDataSetResult carries what the server returns from POST /pdp/data-sets: the transaction hash (parsed out of the Location header) and the absolute status URL the caller can poll.

type CreateDataSetStatus 

type CreateDataSetStatus struct {
	CreateMessageHash common.Hash   `json:"createMessageHash"`
	ConfirmedTxHash   common.Hash   `json:"-"`
	Service           string        `json:"service"`
	TxStatus          string        `json:"txStatus"`
	DataSetCreated    bool          `json:"dataSetCreated"`
	OK                *bool         `json:"ok"`
	DataSetID         *types.BigInt `json:"-"`
}

CreateDataSetStatus mirrors GET /pdp/data-sets/created/{txHash}. TxStatus reports the provider's wire status. Callers should use the error returned by GetDataSetCreationStatus instead of interpreting it directly. Providers report pending, confirmed, failed, or reorged; rejected is also accepted for compatibility.

type DataSet 

type DataSet struct {
	ID                 types.BigInt   `json:"-"`
	NextChallengeEpoch int64          `json:"nextChallengeEpoch"`
	Pieces             []DataSetPiece `json:"pieces"`
}

DataSet mirrors the JSON returned by GET /pdp/data-sets/{id}.

func (DataSet) MarshalJSON 

func (d DataSet) MarshalJSON() ([]byte, error)

func (*DataSet) UnmarshalJSON 

func (d *DataSet) UnmarshalJSON(data []byte) error

type DataSetPiece 

type DataSetPiece struct {
	PieceCID       string       `json:"pieceCid"`
	PieceID        types.BigInt `json:"-"`
	SubPieceCID    string       `json:"subPieceCid"`
	SubPieceOffset uint64       `json:"subPieceOffset"`
}

DataSetPiece mirrors a piece entry returned by GET /pdp/data-sets/{id}.

func (DataSetPiece) MarshalJSON 

func (p DataSetPiece) MarshalJSON() ([]byte, error)

func (*DataSetPiece) UnmarshalJSON 

func (p *DataSetPiece) UnmarshalJSON(data []byte) error

type FindPieceResult 

type FindPieceResult struct {
	PieceCID string `json:"pieceCid"`
}

FindPieceResult mirrors the JSON body of GET /pdp/piece?pieceCid=...

type HTTPError 

type HTTPError struct {
	Method     string
	URL        string
	StatusCode int
	Body       string
	// RetryAfter is the server-requested wait duration from the Retry-After
	// header. Non-zero on HTTP 429 (Too Many Requests) and 503 (Service
	// Unavailable) responses when the server provides the header. Delays too
	// long for time.Duration are clamped to the longest whole-second duration.
	RetryAfter time.Duration
}

HTTPError wraps a non-success response from the PDP provider API. Use errors.AsType[*pdp.HTTPError] to read StatusCode, Body, and RetryAfter from wrapped errors. Body retains the response text with surrounding whitespace removed. Error displays at most its first 4 KiB, with control characters escaped.

The URL field is always pre-redacted: userinfo is stripped and the values of sensitive query parameters such as token, signature, or api_key are masked as "***". This removes the footgun where a caller logs `%+v` or JSON marshals the struct and leaks credentials. The pre-redacted form is sufficient for debugging — path, scheme, host and non-sensitive query values are preserved.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

Error implements the error interface using the pre-redacted URL.

func (*HTTPError) RedactedURL 

func (e *HTTPError) RedactedURL() string

RedactedURL returns the log-safe URL stored in e.URL. Retained for backwards compatibility; new code can simply read e.URL directly as it is always pre-redacted.

type Option 

type Option func(*Client)

Option configures a Client. Nil options are ignored.

func WithHTTPClient 

func WithHTTPClient(h *http.Client) Option

WithHTTPClient supplies the client for control and streaming requests. Its Timeout applies to the entire request, including reading the response body. A later WithStreamingHTTPClient option can override only streaming requests. A nil client is ignored.

func WithLegacyPieceStorageIDLimit added in v0.6.1 

func WithLegacyPieceStorageIDLimit(limit uint64) Option

WithLegacyPieceStorageIDLimit sets the first compact data set ID for this deployment. Zero (the default) skips the legacy piece-count check.

func WithLogger 

func WithLogger(l *slog.Logger) Option

WithLogger attaches a structured logger. A nil logger disables logging.

func WithMaxRetries 

func WithMaxRetries(n int) Option

WithMaxRetries sets the maximum number of retry attempts for transient failures (5xx, 429, network errors). A value of 0 disables retries. Negative values are treated as 0. Defaults to DefaultMaxRetries (3).

func WithStreamingHTTPClient added in v0.7.0 

func WithStreamingHTTPClient(h *http.Client) Option

WithStreamingHTTPClient supplies the client for streaming GET and PUT requests. Its Timeout and the caller's context both bound the request lifetime. A nil client is ignored.

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header on every request.

type PullPieceInput 

type PullPieceInput struct {
	// PieceCID is the piece to pull: a PieceCIDv2 whose raw size is between
	// chain.MinUploadSize and chain.MaxUploadSize.
	PieceCID cid.Cid
	// SourceURL is an HTTPS URL ending in /piece/{pieceCid} on the source SP.
	SourceURL string
}

PullPieceInput is one entry in a pull request.

type PullPieceStatus 

type PullPieceStatus struct {
	PieceCID string     `json:"pieceCid"`
	Status   PullStatus `json:"status"`
}

PullPieceStatus is the per-piece status returned by POST /pdp/piece/pull.

type PullRequest 

type PullRequest struct {
	// RecordKeeper is the record-keeper contract address (e.g. FWSS). The
	// pull request body always carries it, even when reusing an existing dataset.
	RecordKeeper common.Address
	// ExtraData is caller-provided EIP-712 signed data encoded as the provider expects.
	ExtraData []byte
	// DataSetID is the target dataset. Nil means create a new dataset.
	DataSetID *types.BigInt
	// Pieces are the pieces to pull with their source URLs.
	Pieces []PullPieceInput
}

PullRequest carries all parameters for POST /pdp/piece/pull.

type PullResult 

type PullResult struct {
	Status PullStatus        `json:"status"`
	Pieces []PullPieceStatus `json:"pieces"`
}

PullResult is what the server returns from POST /pdp/piece/pull.

type PullStatus 

type PullStatus string

PullStatus mirrors the status values used by the PDP pull endpoint. 

const (
	PullStatusPending    PullStatus = "pending"
	PullStatusInProgress PullStatus = "inProgress"
	PullStatusRetrying   PullStatus = "retrying"
	PullStatusComplete   PullStatus = "complete"
	PullStatusFailed     PullStatus = "failed"
)

type ServiceAlreadyTerminatedError added in v0.4.0 

type ServiceAlreadyTerminatedError struct {
	ServiceTerminationEpoch types.Epoch
	Message                 string
}

ServiceAlreadyTerminatedError is returned when the provider reports the service is already terminated on chain.

func (*ServiceAlreadyTerminatedError) Error added in v0.4.0 

func (e *ServiceAlreadyTerminatedError) Error() string

type TerminateServiceNotSupportedError added in v0.4.0 

type TerminateServiceNotSupportedError struct {
	Body string
}

TerminateServiceNotSupportedError is returned when the provider does not support provider-relayed termination.

func (*TerminateServiceNotSupportedError) Error added in v0.4.0 

func (e *TerminateServiceNotSupportedError) Error() string

type TerminateServicePendingError added in v0.4.0 

type TerminateServicePendingError struct {
	Message string
}

TerminateServicePendingError is returned when a termination request is already queued.

func (*TerminateServicePendingError) Error added in v0.4.0 

func (e *TerminateServicePendingError) Error() string

type TerminateServiceRequest added in v0.4.0 

type TerminateServiceRequest struct {
	DataSetID types.BigInt
	ExtraData []byte
}

TerminateServiceRequest requests provider-relayed FWSS service termination.

type TerminateServiceResult added in v0.4.0 

type TerminateServiceResult struct {
	StatusURL string
}

TerminateServiceResult contains the provider status URL to poll.

type TerminateServiceStatus added in v0.4.0 

type TerminateServiceStatus struct {
	// TerminationTxHash is the provider's original submission hash.
	TerminationTxHash *common.Hash
	// ConfirmedTxHash is the hash included on chain after any replacement.
	ConfirmedTxHash         *common.Hash
	FWSSTerminated          bool
	ServiceTerminationEpoch types.Epoch
}

TerminateServiceStatus is the provider's termination status.

type UploadPieceStreamingOptions 

type UploadPieceStreamingOptions struct {
	// Size is the payload byte count. When > 0 it is used to set the
	// Content-Length request header. When 0 the request is sent with
	// Transfer-Encoding: chunked.
	Size int64
	// PieceCID, when defined, is a pre-computed PieceCIDv2 of the payload.
	// If set, the client skips incremental commP calculation during the
	// streaming PUT. The server still verifies the uploaded bytes against
	// this value during finalize; a mismatch yields an HTTP error.
	PieceCID cid.Cid
	// OnProgress is invoked after each non-empty Read from the data reader,
	// with the cumulative byte count sent so far. It may be nil. It can run on
	// the HTTP transport goroutine; a panic aborts the upload and is re-raised
	// with the same value on the calling goroutine, after logging the original
	// stack at Error level when a logger is configured.
	OnProgress func(bytesUploaded int64)
}

UploadPieceStreamingOptions configures a single streaming upload.

type UploadStreamingResult 

type UploadStreamingResult struct {
	// PieceCID is the PieceCIDv2 of the uploaded piece — either the caller-
	// provided value (when opts.PieceCID was set) or the value computed
	// client-side during the streaming PUT.
	PieceCID cid.Cid
	// Size is the total byte count consumed from the data reader.
	Size int64
}

UploadStreamingResult is returned by UploadPieceStreaming on success.

type WaitForTerminateServiceNotFoundError added in v0.4.0 

type WaitForTerminateServiceNotFoundError struct{}

WaitForTerminateServiceNotFoundError is returned when no provider termination request is visible before a tx hash is observed.

func (*WaitForTerminateServiceNotFoundError) Error added in v0.4.0 

func (e *WaitForTerminateServiceNotFoundError) Error() string

type WaitForTerminateServiceOption added in v0.7.1 

type WaitForTerminateServiceOption func(*terminateServiceWaitConfig)

WaitForTerminateServiceOption configures termination status polling.

func WithKnownTerminationTxHash added in v0.7.1 

func WithKnownTerminationTxHash(hash common.Hash) WaitForTerminateServiceOption

WithKnownTerminationTxHash supplies a previously observed transaction hash, so a missing status reports WaitForTerminateServiceRejectedError. It does not establish provider acceptance or trigger the hash callback. A zero hash means no known hash.

type WaitForTerminateServiceRejectedError added in v0.4.0 

type WaitForTerminateServiceRejectedError struct {
	TxHash common.Hash
}

WaitForTerminateServiceRejectedError is returned when a provider tx hash was observed and the status later disappears.

func (*WaitForTerminateServiceRejectedError) Error added in v0.4.0 

func (e *WaitForTerminateServiceRejectedError) Error() string

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.