Documentation
¶
Index ¶
- func IsDataSetServiceEnded(err error) bool
- func IsDataSetWriteBlocked(err error) bool
- func IsNoProviderCandidates(err error) bool
- func IsProviderUnavailable(err error) bool
- func IsTerminationBlocked(err error) bool
- func NewClient(ctx context.Context, cfg ClientConfig) (*sdk.Client, error)
- func NormalizeProviderOperationError(ctx context.Context, err error) error
- type AddPiecesStatusInput
- type ChainEpochReader
- type CleanupContext
- type ClientConfig
- type DataSetCreationStatusInput
- type DataSetServiceEndedError
- type DataSetTarget
- type NoProviderCandidatesError
- type PDPStatusChecker
- func (c *PDPStatusChecker) CheckAddPiecesStatus(ctx context.Context, input AddPiecesStatusInput) PDPStatusResult
- func (c *PDPStatusChecker) CheckDataSetCreationStatus(ctx context.Context, input DataSetCreationStatusInput) PDPStatusResult
- func (c *PDPStatusChecker) GetAddPiecesStatus(ctx context.Context, input AddPiecesStatusInput) (PDPStatusResult, error)
- type PDPStatusCheckerOptions
- type PDPStatusResult
- type PDPStatusState
- type PaymentAccountInfo
- type ProviderTarget
- type ProviderUnavailableError
- type ReadinessCheck
- type ReadinessChecker
- type ReadinessCheckerOption
- type ReadinessClient
- type ReadinessClientFactory
- type ReadinessConfig
- type ReadinessMode
- type ReadinessResult
- type ReadinessStatus
- type ServiceTerminator
- type StorageClient
- type StorageServiceAdapter
- func (s *StorageServiceAdapter) Download(ctx context.Context, pieceCID cid.Cid, opts *storage.DownloadOptions) (io.ReadCloser, error)
- func (s *StorageServiceAdapter) FindMatchingDataSet(ctx context.Context, providerID sdktypes.BigInt, metadata map[string]string, ...) (*storage.DataSetRef, error)
- func (s *StorageServiceAdapter) OpenCleanupContext(ctx context.Context, dataSetID sdktypes.BigInt, ...) (CleanupContext, error)
- func (s *StorageServiceAdapter) OpenDataSetTarget(ctx context.Context, dataSetID sdktypes.BigInt, ...) (DataSetTarget, error)
- func (s *StorageServiceAdapter) OpenProviderTarget(ctx context.Context, providerID sdktypes.BigInt, ...) (ProviderTarget, error)
- func (s *StorageServiceAdapter) PrepareUpload(ctx context.Context, dataSize uint64, targets []StorageTarget) (*storage.MultiContextCosts, error)
- func (s *StorageServiceAdapter) SelectUploadTargets(ctx context.Context, opts storage.SelectUploadContextsOptions) ([]StorageTarget, error)
- func (s *StorageServiceAdapter) TerminateService(ctx context.Context, dataSetID sdktypes.BigInt) (*TerminationResult, error)
- type StorageTarget
- type TerminationBlockedError
- type TerminationResult
- type WalletInfo
- type WalletOperator
- type WalletQuerier
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsDataSetServiceEnded ¶
func IsDataSetWriteBlocked ¶
IsDataSetWriteBlocked reports whether err means the data set can no longer accept writes because its PDP payment ended. The SDK raises it while validating the data set, before the provider is contacted, so a commit that fails this way never reached the provider.
func IsNoProviderCandidates ¶
func IsProviderUnavailable ¶
func IsTerminationBlocked ¶
IsTerminationBlocked reports whether termination needs operator action rather than another attempt.
Types ¶
type AddPiecesStatusInput ¶
type ChainEpochReader ¶
ChainEpochReader observes the chain head. Replacement uses it to decide when a terminated service has genuinely ended.
func NewChainEpochReader ¶
func NewChainEpochReader(source blockNumberSource) ChainEpochReader
NewChainEpochReader reads the epoch from the chain head.
The wall-clock estimate available elsewhere in the SDK derives an epoch from genesis time and can run ahead of the chain, which would let a replacement retire a source before its service has really ended. Retirement therefore only trusts an observed block number.
type CleanupContext ¶
type CleanupContext interface {
DeletePieceByID(context.Context, sdktypes.BigInt) (*sdktypes.WriteResult, error)
PieceStatus(context.Context, cid.Cid) (*storage.PieceStatus, error)
}
CleanupContext abstracts the SDK operations needed to remove PDP pieces.
type ClientConfig ¶
type ClientConfig struct {
PrivateKey string
RPCURL string
WithCDN bool
AllowPrivateNetworks bool
Logger *slog.Logger
}
ClientConfig contains SynapS3 runtime settings forwarded into synapse-go.
type DataSetServiceEndedError ¶
type DataSetServiceEndedError struct {
Cause error
}
DataSetServiceEndedError reports typed evidence that an established data set no longer represents a writable service.
func (*DataSetServiceEndedError) Error ¶
func (e *DataSetServiceEndedError) Error() string
func (*DataSetServiceEndedError) Unwrap ¶
func (e *DataSetServiceEndedError) Unwrap() error
type DataSetTarget ¶
type DataSetTarget interface {
StorageTarget
Store(context.Context, io.Reader, *storage.StoreOptions) (*storage.StoreResult, error)
PresignForCommit(context.Context, []storage.PieceInput) ([]byte, error)
Pull(context.Context, storage.PullRequest) (*storage.PullResult, error)
SubmitCommit(context.Context, storage.CommitRequest) (*storage.CommitSubmission, error)
GetCommitStatus(context.Context, storage.CommitSubmission) (*storage.CommitStatus, error)
PieceStatus(context.Context, cid.Cid) (*storage.PieceStatus, error)
}
DataSetTarget is an immutable existing data set used for piece operations.
type NoProviderCandidatesError ¶
type NoProviderCandidatesError struct {
Cause error
}
NoProviderCandidatesError reports that automatic selection cannot currently satisfy a newly authorized replica slot.
func (*NoProviderCandidatesError) Error ¶
func (e *NoProviderCandidatesError) Error() string
func (*NoProviderCandidatesError) Unwrap ¶
func (e *NoProviderCandidatesError) Unwrap() error
type PDPStatusChecker ¶
type PDPStatusChecker struct {
// contains filtered or unexported fields
}
func NewPDPStatusChecker ¶
func NewPDPStatusChecker(opts PDPStatusCheckerOptions) *PDPStatusChecker
func (*PDPStatusChecker) CheckAddPiecesStatus ¶
func (c *PDPStatusChecker) CheckAddPiecesStatus(ctx context.Context, input AddPiecesStatusInput) PDPStatusResult
func (*PDPStatusChecker) CheckDataSetCreationStatus ¶
func (c *PDPStatusChecker) CheckDataSetCreationStatus(ctx context.Context, input DataSetCreationStatusInput) PDPStatusResult
func (*PDPStatusChecker) GetAddPiecesStatus ¶
func (c *PDPStatusChecker) GetAddPiecesStatus(ctx context.Context, input AddPiecesStatusInput) (PDPStatusResult, error)
GetAddPiecesStatus performs one validated status request while preserving the underlying error for operational callers that must classify retries.
type PDPStatusCheckerOptions ¶
type PDPStatusResult ¶
type PDPStatusState ¶
type PDPStatusState string
const ( PDPStatusPending PDPStatusState = "pending" PDPStatusConfirmed PDPStatusState = "confirmed" PDPStatusRejected PDPStatusState = "rejected" PDPStatusMismatch PDPStatusState = "mismatch" PDPStatusUnknown PDPStatusState = "unknown" )
type PaymentAccountInfo ¶
type PaymentAccountInfo struct {
Funds *big.Int
AvailableFunds *big.Int
LockupCurrent *big.Int
LockupRate *big.Int
LockupLastSettledAt *big.Int
FundedUntilEpoch *big.Int
FundedUntilTime *time.Time
RunwaySeconds *int64
LockupRatePerDay *big.Int
LockupRatePerMonth *big.Int
NoActiveSpend bool
}
PaymentAccountInfo holds USDFC payment contract account state.
type ProviderTarget ¶
type ProviderTarget interface {
StorageTarget
CreateDataSet(context.Context, *storage.CreateDataSetOptions) (*storage.CreateDataSetResult, error)
WaitForDataSetCreated(context.Context, storage.CreateDataSetSubmission) (*storage.CreateDataSetResult, error)
}
ProviderTarget is an unbound provider used to create or resume creation of a data set. Creating a data set does not mutate the target into a bound one.
type ProviderUnavailableError ¶
type ProviderUnavailableError struct {
}
ProviderUnavailableError reports a recoverable provider or transport dependency failure.
func (*ProviderUnavailableError) Error ¶
func (e *ProviderUnavailableError) Error() string
func (*ProviderUnavailableError) Unwrap ¶
func (e *ProviderUnavailableError) Unwrap() error
type ReadinessCheck ¶
type ReadinessCheck struct {
ID string `json:"id"`
Status ReadinessStatus `json:"status"`
Message string `json:"message"`
Action string `json:"action,omitempty"`
RequiredUSDFC string `json:"required_usdfc,omitempty"`
}
type ReadinessChecker ¶
type ReadinessChecker struct {
// contains filtered or unexported fields
}
func NewReadinessChecker ¶
func NewReadinessChecker(cfg ReadinessConfig, runtime ReadinessClient, opts ...ReadinessCheckerOption) *ReadinessChecker
func (*ReadinessChecker) CheckDraft ¶
func (c *ReadinessChecker) CheckDraft(ctx context.Context, cfg ReadinessConfig) ReadinessResult
func (*ReadinessChecker) CheckRuntime ¶
func (c *ReadinessChecker) CheckRuntime(ctx context.Context) ReadinessResult
type ReadinessCheckerOption ¶
type ReadinessCheckerOption func(*ReadinessChecker)
func WithReadinessClientFactory ¶
func WithReadinessClientFactory(factory ReadinessClientFactory) ReadinessCheckerOption
func WithReadinessLogger ¶
func WithReadinessLogger(logger *slog.Logger) ReadinessCheckerOption
func WithReadinessTimeout ¶
func WithReadinessTimeout(timeout time.Duration) ReadinessCheckerOption
type ReadinessClient ¶
type ReadinessClient interface {
Address() common.Address
Chain() chain.Chain
ResolvedAddresses() sdk.ResolvedAddresses
Payments() readinessPayments
Storage() readinessStorage
Close() error
}
func AdaptReadinessClient ¶
func AdaptReadinessClient(client *sdk.Client) ReadinessClient
type ReadinessClientFactory ¶
type ReadinessClientFactory func(context.Context, ReadinessConfig) (ReadinessClient, error)
type ReadinessConfig ¶
type ReadinessConfig struct {
Network string
RPCURL string
PrivateKey string
WithCDN bool
AllowPrivateNetworks bool
DefaultCopies int
}
func ReadinessConfigFromFilecoinConfig ¶
func ReadinessConfigFromFilecoinConfig(cfg config.FilecoinConfig) ReadinessConfig
type ReadinessMode ¶
type ReadinessMode string
const ( ReadinessModeRuntime ReadinessMode = "runtime" ReadinessModeDraft ReadinessMode = "draft" )
type ReadinessResult ¶
type ReadinessResult struct {
Status ReadinessStatus `json:"status"`
Mode ReadinessMode `json:"mode"`
CheckedAt time.Time `json:"checked_at"`
Checks []ReadinessCheck `json:"checks"`
PartialErrors map[string]string `json:"partial_errors,omitempty"`
}
func (*ReadinessResult) Finish ¶
func (r *ReadinessResult) Finish()
Finish updates the aggregate readiness status from the contained checks.
type ReadinessStatus ¶
type ReadinessStatus string
const ( ReadinessStatusReady ReadinessStatus = "ready" ReadinessStatusWarning ReadinessStatus = "warning" ReadinessStatusBlocked ReadinessStatus = "blocked" ReadinessStatusUnknown ReadinessStatus = "unknown" )
type ServiceTerminator ¶
type ServiceTerminator interface {
TerminateService(ctx context.Context, dataSetID sdktypes.BigInt) (*TerminationResult, error)
}
ServiceTerminator is the destructive service-lifecycle boundary. It is used only after replacement cleanup authorization and the retirement safety gate have both passed.
type StorageClient ¶
type StorageClient interface {
Download(ctx context.Context, pieceCID cid.Cid, opts *storage.DownloadOptions) (io.ReadCloser, error)
PrepareUpload(ctx context.Context, dataSize uint64, targets []StorageTarget) (*storage.MultiContextCosts, error)
SelectUploadTargets(ctx context.Context, opts storage.SelectUploadContextsOptions) ([]StorageTarget, error)
OpenProviderTarget(ctx context.Context, providerID sdktypes.BigInt, opts storage.NewProviderContextOptions) (ProviderTarget, error)
OpenDataSetTarget(ctx context.Context, dataSetID sdktypes.BigInt, opts storage.NewDataSetContextOptions) (DataSetTarget, error)
FindMatchingDataSet(ctx context.Context, providerID sdktypes.BigInt, metadata map[string]string, withCDN bool) (*storage.DataSetRef, error)
OpenCleanupContext(ctx context.Context, dataSetID sdktypes.BigInt, opts storage.NewDataSetContextOptions) (CleanupContext, error)
}
StorageClient abstracts the synapse-go storage service for download plus staged provider operations.
type StorageServiceAdapter ¶
type StorageServiceAdapter struct {
// contains filtered or unexported fields
}
StorageServiceAdapter adapts synapse-go's concrete immutable storage contexts to SynapS3's testable staged storage interface.
func AdaptStorageService ¶
func AdaptStorageService(service *storage.Service) *StorageServiceAdapter
func (*StorageServiceAdapter) Download ¶
func (s *StorageServiceAdapter) Download(ctx context.Context, pieceCID cid.Cid, opts *storage.DownloadOptions) (io.ReadCloser, error)
func (*StorageServiceAdapter) FindMatchingDataSet ¶
func (*StorageServiceAdapter) OpenCleanupContext ¶
func (s *StorageServiceAdapter) OpenCleanupContext(ctx context.Context, dataSetID sdktypes.BigInt, opts storage.NewDataSetContextOptions) (CleanupContext, error)
func (*StorageServiceAdapter) OpenDataSetTarget ¶
func (s *StorageServiceAdapter) OpenDataSetTarget(ctx context.Context, dataSetID sdktypes.BigInt, opts storage.NewDataSetContextOptions) (DataSetTarget, error)
func (*StorageServiceAdapter) OpenProviderTarget ¶
func (s *StorageServiceAdapter) OpenProviderTarget(ctx context.Context, providerID sdktypes.BigInt, opts storage.NewProviderContextOptions) (ProviderTarget, error)
func (*StorageServiceAdapter) PrepareUpload ¶
func (s *StorageServiceAdapter) PrepareUpload(ctx context.Context, dataSize uint64, targets []StorageTarget) (*storage.MultiContextCosts, error)
func (*StorageServiceAdapter) SelectUploadTargets ¶
func (s *StorageServiceAdapter) SelectUploadTargets(ctx context.Context, opts storage.SelectUploadContextsOptions) ([]StorageTarget, error)
func (*StorageServiceAdapter) TerminateService ¶
func (s *StorageServiceAdapter) TerminateService(ctx context.Context, dataSetID sdktypes.BigInt) (*TerminationResult, error)
TerminateService ends the storage service for one data set. It is the destructive boundary of provider replacement and must only be called after the retirement safety gate passes.
Termination is relayed through the provider first. A provider-side failure falls back to the direct FWSS transaction path; a pending relay does not, because the provider has already accepted it. An already-terminated service reports its recorded end epoch rather than failing.
type StorageTarget ¶
type StorageTarget interface {
ProviderID() sdktypes.BigInt
DataSetRef() (storage.DataSetRef, bool)
GetProviderInfo() storage.Provider
CDNEnabled() bool
PieceURL(cid.Cid) string
ServiceURL() string
}
StorageTarget abstracts the immutable identity shared by provider and data set targets returned by synapse-go.
type TerminationBlockedError ¶
TerminationBlockedError means the service cannot be terminated until an operator resolves something the gateway must not decide on its own, such as settling outstanding payment debt. It is never retried automatically.
func (*TerminationBlockedError) Error ¶
func (e *TerminationBlockedError) Error() string
func (*TerminationBlockedError) Unwrap ¶
func (e *TerminationBlockedError) Unwrap() error
type TerminationResult ¶
TerminationResult records what the chain agreed to. EndEpoch is the epoch at which the service actually stops, which is why retirement waits for the chain to reach it rather than trusting the call returning.
type WalletInfo ¶
type WalletInfo struct {
Address string
Network string
ChainID int64
Nonce *uint64
CurrentEpoch *big.Int
EpochDurationSeconds int64
PaymentsAddress string
USDFCAddress string
USDFCDecimals uint8
FILGasBalance *big.Int
USDFCWalletBalance *big.Int
PaymentAccount *PaymentAccountInfo
Errors map[string]string
}
WalletInfo holds a snapshot of the wallet's on-chain state. Fields are nil when the corresponding RPC call failed; see Errors for details.
type WalletOperator ¶
type WalletOperator interface {
FundUSDFC(ctx context.Context, amount *big.Int) (string, error)
WithdrawUSDFC(ctx context.Context, amount *big.Int) (string, error)
ApproveFWSS(ctx context.Context) (string, error)
}
WalletOperator broadcasts wallet payment transactions.
func NewWalletOperator ¶
func NewWalletOperator(paySvc *payments.Service, usdfc common.Address) WalletOperator
type WalletQuerier ¶
type WalletQuerier interface {
GetWalletInfo(ctx context.Context) (*WalletInfo, error)
}
WalletQuerier provides on-chain wallet state for the admin dashboard.
func NewWalletQuerier ¶
func NewWalletQuerier(paySvc *payments.Service, address common.Address, c chain.Chain, addrs sdk.ResolvedAddresses) WalletQuerier
NewWalletQuerier creates a WalletQuerier backed by synapse-go payments.Service.