api

package
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Dec 4, 2024 License: MIT Imports: 33 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewServer 

func NewServer(name string, hostKey types.PublicKey, cm ChainManager, s Syncer, am AccountManager, c ContractManager, vm VolumeManager, wm Wallet, mm MetricManager, sm Settings, im Index, opts ...ServerOption) http.Handler

NewServer initializes the API syncer chain accounts contracts volumes wallet metrics settings index

Types

type AccountManager 

type AccountManager interface {
	Accounts(limit, offset int) ([]accounts.Account, error)
	AccountFunding(accountID rhp3.Account) ([]accounts.FundingSource, error)
}

An AccountManager manages ephemeral accounts

type AddVolumeRequest 

type AddVolumeRequest struct {
	LocalPath  string `json:"localPath"`
	MaxSectors uint64 `json:"maxSectors"`
}

AddVolumeRequest is the request body for the [POST] /volume endpoint.

type AlertResp 

type AlertResp []alerts.Alert

AlertResp is the response body for the [GET] /alerts endpoint

func (AlertResp) PrometheusMetric 

func (a AlertResp) PrometheusMetric() (metrics []prometheus.Metric)

PrometheusMetric returns Prometheus samples for the hosts alerts.

type Alerts 

type Alerts interface {
	Active() []alerts.Alert
	Dismiss(...types.Hash256)
}

Alerts retrieves and dismisses notifications

type BackupRequest 

type BackupRequest struct {
	Path string `json:"path"`
}

A BackupRequest is the request body for the [POST] /system/backup endpoint.

type BuildState 

type BuildState struct {
	Version   string    `json:"version"`
	Commit    string    `json:"commit"`
	OS        string    `json:"os"`
	BuildTime time.Time `json:"buildTime"`
}

BuildState contains static information about the build.

type ChainManager 

type ChainManager interface {
	Tip() types.ChainIndex
	TipState() consensus.State

	RecommendedFee() types.Currency
	AddPoolTransactions(txns []types.Transaction) (known bool, err error)
	UnconfirmedParents(txn types.Transaction) []types.Transaction
	AddV2PoolTransactions(basis types.ChainIndex, txns []types.V2Transaction) (known bool, err error)
	V2TransactionSet(basis types.ChainIndex, txn types.V2Transaction) (types.ChainIndex, []types.V2Transaction, error)
}

A ChainManager retrieves the current blockchain state

type Client 

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

A Client is a client for the hostd API.

func NewClient 

func NewClient(baseURL, password string) *Client

NewClient creates a new hostd API client.

func (*Client) AddVolume 

func (c *Client) AddVolume(localPath string, sectors uint64) (vol storage.Volume, err error)

AddVolume adds a new volume to the host

func (*Client) Announce 

func (c *Client) Announce() error

Announce announces the host to the network. The announced address is determined by the host's current settings.

func (*Client) BackupSQLite3 

func (c *Client) BackupSQLite3(destPath string) error

BackupSQLite3 creates a backup of the SQLite3 database at the specified path on the local filesystem.

func (*Client) ConsensusNetwork 

func (c *Client) ConsensusNetwork() (network *consensus.Network, err error)

ConsensusNetwork returns the node's consensus network

func (*Client) ConsensusTip 

func (c *Client) ConsensusTip() (tip types.ChainIndex, err error)

ConsensusTip returns the current consensus tip

func (*Client) ConsensusTipState 

func (c *Client) ConsensusTipState() (state consensus.State, err error)

ConsensusTipState returns the current consensus tip state

func (*Client) Contract 

func (c *Client) Contract(id types.FileContractID) (contract contracts.Contract, err error)

Contract returns the contract with the specified ID.

func (*Client) Contracts 

func (c *Client) Contracts(filter contracts.ContractFilter) ([]contracts.Contract, int, error)

Contracts returns the contracts of the host matching the filter.

func (*Client) DeleteIntegrityCheck 

func (c *Client) DeleteIntegrityCheck(id types.FileContractID) error

DeleteIntegrityCheck deletes the integrity check for the specified contract.

func (*Client) DeleteSector 

func (c *Client) DeleteSector(root types.Hash256) error

DeleteSector deletes the sector with the specified root. This can cause contract failures if the sector is still in use.

func (*Client) DeleteVolume 

func (c *Client) DeleteVolume(id int) error

DeleteVolume deletes the volume with the specified ID.

func (*Client) DeleteWebHook 

func (c *Client) DeleteWebHook(id int64) error

DeleteWebHook deletes the Webhook with the specified ID.

func (*Client) Events 

func (c *Client) Events(limit, offset int) (transactions []wallet.Event, err error)

Events returns the transactions of the host's wallet.

func (*Client) IntegrityCheckProgress 

func (c *Client) IntegrityCheckProgress(id types.FileContractID) (IntegrityCheckResult, error)

IntegrityCheckProgress returns the progress of the integrity check for the specified contract.

func (*Client) LocalDir 

func (c *Client) LocalDir(path string) (resp SystemDirResponse, err error)

LocalDir returns the contents of the specified directory on the host.

func (*Client) Metrics 

func (c *Client) Metrics(at time.Time) (metrics metrics.Metrics, err error)

Metrics returns the metrics of the host at the specified time.

func (*Client) MkDir 

func (c *Client) MkDir(path string) error

MkDir creates a new directory on the host.

func (*Client) PendingEvents 

func (c *Client) PendingEvents() (events []wallet.Event, err error)

PendingEvents returns transactions that are not yet confirmed.

func (*Client) PeriodMetrics 

func (c *Client) PeriodMetrics(start time.Time, n int, interval metrics.Interval) (periods []metrics.Metrics, err error)

PeriodMetrics returns the metrics of the host for n periods starting at start.

func (*Client) RegisterWebHook 

func (c *Client) RegisterWebHook(callbackURL string, scopes []string) (hook webhooks.Webhook, err error)

RegisterWebHook registers a new Webhook.

func (*Client) ResizeVolume 

func (c *Client) ResizeVolume(id int, sectors uint64) error

ResizeVolume resizes the volume with the specified ID to a new size.

func (*Client) SendSiacoins 

func (c *Client) SendSiacoins(address types.Address, amount types.Currency, subtractFee bool) (id types.TransactionID, err error)

SendSiacoins sends siacoins to the specified address. If subtractFee is true, the miner fee is subtracted from the amount.

func (*Client) Settings 

func (c *Client) Settings() (settings settings.Settings, err error)

Settings returns the current settings of the host.

func (*Client) StartIntegrityCheck 

func (c *Client) StartIntegrityCheck(id types.FileContractID) error

StartIntegrityCheck scans the volume with the specified ID for consistency errors.

func (*Client) State 

func (c *Client) State() (resp State, err error)

State returns the current state of the host

func (*Client) SyncerAddress 

func (c *Client) SyncerAddress() (addr string, err error)

SyncerAddress returns the address of the syncer.

func (*Client) SyncerConnect 

func (c *Client) SyncerConnect(address string) error

SyncerConnect connects to a peer.

func (*Client) SyncerDisconnect 

func (c *Client) SyncerDisconnect(address string) error

SyncerDisconnect disconnects from a peer.

func (*Client) SyncerPeers 

func (c *Client) SyncerPeers() (peers []Peer, err error)

SyncerPeers returns the currently connected peers of the syncer.

func (*Client) TestDDNS 

func (c *Client) TestDDNS() error

TestDDNS tests the dynamic DNS settings of the host.

func (*Client) UpdateSettings 

func (c *Client) UpdateSettings(updated ...Setting) (settings settings.Settings, err error)

UpdateSettings updates the host's settings.

func (*Client) UpdateVolume 

func (c *Client) UpdateVolume(id int, req UpdateVolumeRequest) error

UpdateVolume updates the volume with the specified ID.

func (*Client) UpdateWebHook 

func (c *Client) UpdateWebHook(id int64, callbackURL string, scopes []string) (hook webhooks.Webhook, err error)

UpdateWebHook updates the Webhook with the specified ID.

func (*Client) Volume 

func (c *Client) Volume(id int) (volume VolumeMeta, err error)

Volume returns the volume with the specified ID.

func (*Client) Volumes 

func (c *Client) Volumes() (volumes []VolumeMeta, err error)

Volumes returns the volumes of the host.

func (*Client) Wallet 

func (c *Client) Wallet() (resp WalletResponse, err error)

Wallet returns the state of the host's wallet.

func (*Client) WebHooks 

func (c *Client) WebHooks() (hooks []webhooks.Webhook, err error)

WebHooks returns all registered WebHooks.

type ContractIntegrityResponse 

type ContractIntegrityResponse struct {
	BadSectors   []types.Hash256 `json:"badSectors"`
	TotalSectors uint64          `json:"totalSectors"`
}

ContractIntegrityResponse is the response body for the [POST] /contracts/:id/check endpoint.

type ContractManager 

type ContractManager interface {
	Contracts(filter contracts.ContractFilter) ([]contracts.Contract, int, error)
	Contract(id types.FileContractID) (contracts.Contract, error)

	// CheckIntegrity checks the integrity of a contract's sector roots on
	// disk. The result of each sector checked is sent on the returned
	// channel. Read errors are logged.
	CheckIntegrity(ctx context.Context, contractID types.FileContractID) (<-chan contracts.IntegrityResult, uint64, error)
}

A ContractManager manages the host's contracts

type ContractsResponse 

type ContractsResponse struct {
	Count     int                  `json:"count"`
	Contracts []contracts.Contract `json:"contracts"`
}

ContractsResponse is the response body for the [POST] /contracts endpoint.

type CreateDirRequest 

type CreateDirRequest struct {
	Path string `json:"path"`
}

A CreateDirRequest is the request body for the [POST] /system/dir endpoint.

type ExplorerState 

type ExplorerState struct {
	Enabled bool   `json:"enabled"`
	URL     string `json:"url"`
}

ExplorerState contains static information about explorer data sources.

type HostSettings 

type HostSettings settings.Settings

HostSettings is the response body for the [GET] /settings endpoint.

func (HostSettings) PrometheusMetric 

func (hs HostSettings) PrometheusMetric() []prometheus.Metric

PrometheusMetric returns Prometheus samples for the host settings.

type Index 

type Index interface {
	Tip() types.ChainIndex
}

An Index persists updates from the blockchain to a store

type IntegrityCheckResult 

type IntegrityCheckResult struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`

	CheckedSectors uint64                      `json:"checkedSectors"`
	TotalSectors   uint64                      `json:"totalSectors"`
	BadSectors     []contracts.IntegrityResult `json:"badSectors"`
}

IntegrityCheckResult tracks the result of an integrity check.

type JSONErrors 

type JSONErrors []error

JSONErrors is a slice of errors that can be marshaled to and unmarshaled from JSON.

func (JSONErrors) MarshalJSON 

func (je JSONErrors) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler

func (*JSONErrors) UnmarshalJSON 

func (je *JSONErrors) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler

type MetricManager 

type MetricManager interface {
	// PeriodMetrics returns metrics for n periods starting at start.
	PeriodMetrics(start time.Time, periods int, interval metrics.Interval) (period []metrics.Metrics, err error)
	// Metrics returns aggregated metrics for the host as of the timestamp.
	Metrics(time.Time) (m metrics.Metrics, err error)
}

A MetricManager retrieves metrics related to the host

type Metrics 

type Metrics metrics.Metrics

Metrics is the response body for the [GET] /metrics endpoint.

func (Metrics) PrometheusMetric 

func (m Metrics) PrometheusMetric() []prometheus.Metric

PrometheusMetric returns Prometheus samples for the host metrics.

type Peer 

type Peer struct {
	Address string `json:"address"`
	Inbound bool   `json:"inbound"`
	Version string `json:"version"`

	FirstSeen      time.Time     `json:"firstSeen,omitempty"`
	ConnectedSince time.Time     `json:"connectedSince,omitempty"`
	SyncedBlocks   uint64        `json:"syncedBlocks,omitempty"`
	SyncDuration   time.Duration `json:"syncDuration,omitempty"`
}

A Peer is a currently-connected peer.

type PeerResp 

type PeerResp []Peer

PeerResp is the response body for the [GET] /syncer/address endpoint

func (PeerResp) PrometheusMetric 

func (p PeerResp) PrometheusMetric() (metrics []prometheus.Metric)

PrometheusMetric returns Prometheus samples for the hosts syncer peers.

type PinnedSettings 

type PinnedSettings interface {
	Update(context.Context, pin.PinnedSettings) error
	Pinned(context.Context) pin.PinnedSettings
}

PinnedSettings updates and retrieves the host's pinned settings

type RegisterWebHookRequest 

type RegisterWebHookRequest struct {
	CallbackURL string   `json:"callbackURL"`
	Scopes      []string `json:"scopes"`
}

RegisterWebHookRequest is the request body for the [POST] /webhooks endpoint.

type ResizeVolumeRequest 

type ResizeVolumeRequest struct {
	MaxSectors uint64 `json:"maxSectors"`
}

ResizeVolumeRequest is the request body for the [PUT] /volume/:id/resize endpoint.

type SQLite3Store 

type SQLite3Store interface {
	Backup(ctx context.Context, destPath string) error
}

The SQLite3Store provides an interface for backing up a SQLite3 database

type ServerOption 

type ServerOption func(*api)

ServerOption is a functional option to configure an API server.

func WithAlerts 

func WithAlerts(al Alerts) ServerOption

WithAlerts sets the alerts manager for the API server.

func WithExplorer 

func WithExplorer(explorer *explorer.Explorer) ServerOption

WithExplorer sets the explorer for the API server.

func WithLogger 

func WithLogger(log *zap.Logger) ServerOption

WithLogger sets the logger for the API server.

func WithPinnedSettings 

func WithPinnedSettings(p PinnedSettings) ServerOption

WithPinnedSettings sets the pinned settings for the API server.

func WithSQLite3Store 

func WithSQLite3Store(s SQLite3Store) ServerOption

WithSQLite3Store sets the SQLite3 store for the API server.

This option is not required since it is only used for backups and there may be other stores in the future.

func WithWebhooks 

func WithWebhooks(w Webhooks) ServerOption

WithWebhooks sets the webhooks manager for the API server.

type Setting 

type Setting func(map[string]any)

A Setting updates a single setting on the host. It can be combined with other settings to update multiple settings at once.

func SetAcceptingContracts 

func SetAcceptingContracts(value bool) Setting

SetAcceptingContracts sets the AcceptingContracts field of the request

func SetAccountExpiry 

func SetAccountExpiry(value time.Duration) Setting

SetAccountExpiry sets the AccountExpiry field of the request

func SetBaseRPCPrice 

func SetBaseRPCPrice(price types.Currency) Setting

SetBaseRPCPrice sets the BaseRPCPrice field of the request

func SetCollateral 

func SetCollateral(collateral types.Currency) Setting

SetCollateral sets the Collateral field of the request

func SetContractPrice 

func SetContractPrice(price types.Currency) Setting

SetContractPrice sets the ContractPrice field of the request

func SetEgressLimit 

func SetEgressLimit(limit uint64) Setting

SetEgressLimit sets the EgressLimit in bytes per second

func SetIngressLimit 

func SetIngressLimit(limit uint64) Setting

SetIngressLimit sets the IngressLimit in bytes per second

func SetMaxAccountBalance 

func SetMaxAccountBalance(value types.Currency) Setting

SetMaxAccountBalance sets the MaxAccountBalance

func SetMaxCollateral 

func SetMaxCollateral(collateral types.Currency) Setting

SetMaxCollateral sets the MaxCollateral

func SetMaxContractDuration 

func SetMaxContractDuration(duration uint64) Setting

SetMaxContractDuration sets the MaxContractDuration field of the request

func SetMaxRegistryEntries 

func SetMaxRegistryEntries(value uint64) Setting

SetMaxRegistryEntries sets the MaxRegistryEntries field of the request

func SetMinEgressPrice 

func SetMinEgressPrice(price types.Currency) Setting

SetMinEgressPrice sets the MinEgressPrice in bytes

func SetMinIngressPrice 

func SetMinIngressPrice(price types.Currency) Setting

SetMinIngressPrice sets the MinIngressPrice in bytes

func SetMinStoragePrice 

func SetMinStoragePrice(price types.Currency) Setting

SetMinStoragePrice sets the MinStoragePrice in bytes/block

func SetNetAddress 

func SetNetAddress(addr string) Setting

SetNetAddress sets the NetAddress field of the request

func SetPriceTableValidity 

func SetPriceTableValidity(value time.Duration) Setting

SetPriceTableValidity sets the PriceTableValidity field of the request

func SetSectorAccessPrice 

func SetSectorAccessPrice(price types.Currency) Setting

SetSectorAccessPrice sets the SectorAccessPrice field of the request

type Settings 

type Settings interface {
	Announce() error

	UpdateSettings(s settings.Settings) error
	Settings() settings.Settings
	LastAnnouncement() (settings.Announcement, error)

	UpdateDDNS(force bool) error
}

Settings updates and retrieves the host's settings

type State 

type State struct {
	Name             string                `json:"name,omitempty"`
	PublicKey        types.PublicKey       `json:"publicKey"`
	LastAnnouncement settings.Announcement `json:"lastAnnouncement"`
	StartTime        time.Time             `json:"startTime"`
	Explorer         ExplorerState         `json:"explorer"`
	BuildState
}

State is the response body for the [GET] /state endpoint.

func (State) PrometheusMetric 

func (s State) PrometheusMetric() []prometheus.Metric

PrometheusMetric returns a Prometheus metric for the host state.

type Syncer 

type Syncer interface {
	Addr() string
	Peers() []*syncer.Peer
	PeerInfo(string) (syncer.PeerInfo, error)
	Connect(ctx context.Context, addr string) (*syncer.Peer, error)

	BroadcastTransactionSet(txns []types.Transaction)
	BroadcastV2TransactionSet(index types.ChainIndex, txns []types.V2Transaction)
}

A Syncer can connect to other peers and synchronize the blockchain.

type SyncerAddrResp 

type SyncerAddrResp string

SyncerAddrResp is the response body for the [GET] /syncer/peers endpoint

func (SyncerAddrResp) PrometheusMetric 

func (s SyncerAddrResp) PrometheusMetric() (metrics []prometheus.Metric)

PrometheusMetric returns Prometheus samples for the hosts syncer address.

type SyncerConnectRequest 

type SyncerConnectRequest struct {
	Address string `json:"address"`
}

SyncerConnectRequest is the request body for the [PUT] /syncer/peers endpoint.

type SystemDirResponse 

type SystemDirResponse struct {
	Path        string   `json:"path"`
	TotalBytes  uint64   `json:"totalBytes"`
	FreeBytes   uint64   `json:"freeBytes"`
	Directories []string `json:"directories"`
}

SystemDirResponse is the response body for the [GET] /system/dir endpoint.

type TPoolResp 

type TPoolResp types.Currency

TPoolResp is the response body for the [GET] /tpool/fee endpoint

func (TPoolResp) MarshalText 

func (tr TPoolResp) MarshalText() ([]byte, error)

MarshalText implements test.Marshaler

func (TPoolResp) PrometheusMetric 

func (t TPoolResp) PrometheusMetric() (metrics []prometheus.Metric)

PrometheusMetric returns Prometheus samples for the hosts tpool fee.

func (*TPoolResp) UnmarshalText 

func (tr *TPoolResp) UnmarshalText(b []byte) error

UnmarshalText implements test.Unmarshaler

type UpdateVolumeRequest 

type UpdateVolumeRequest struct {
	ReadOnly bool `json:"readOnly"`
}

UpdateVolumeRequest is the request body for the [PUT] /volume/:id endpoint.

type VerifySectorResponse 

type VerifySectorResponse struct {
	storage.SectorReference
	Error string `json:"error,omitempty"`
}

VerifySectorResponse is the response body for the [GET] /sectors/:root/verify endpoint.

type VolumeManager 

type VolumeManager interface {
	Usage() (usedSectors uint64, totalSectors uint64, err error)
	Volumes() ([]storage.VolumeMeta, error)
	Volume(id int64) (storage.VolumeMeta, error)
	AddVolume(ctx context.Context, localPath string, maxSectors uint64, result chan<- error) (storage.Volume, error)
	RemoveVolume(ctx context.Context, id int64, force bool, result chan<- error) error
	ResizeVolume(ctx context.Context, id int64, maxSectors uint64, result chan<- error) error
	SetReadOnly(id int64, readOnly bool) error
	RemoveSector(root types.Hash256) error
	ResizeCache(size uint32)
	Read(types.Hash256) (*[rhp2.SectorSize]byte, error)

	// SectorReferences returns the references to a sector
	SectorReferences(root types.Hash256) (storage.SectorReference, error)
}

A VolumeManager manages the host's storage volumes

type VolumeMeta 

type VolumeMeta struct {
	storage.VolumeMeta
	Errors JSONErrors `json:"errors"`
}

VolumeMeta is a volume with its metadata. It overrides the marshalling of the storage.VolumeMeta type to handle error messages.

type VolumeResp 

type VolumeResp []VolumeMeta

VolumeResp is the response body for the [GET] /volumes endpoint

func (VolumeResp) PrometheusMetric 

func (v VolumeResp) PrometheusMetric() (metrics []prometheus.Metric)

PrometheusMetric returns Prometheus samples for the hosts volumes.

type Wallet 

type Wallet interface {
	Address() types.Address
	Balance() (balance wallet.Balance, err error)
	UnconfirmedEvents() ([]wallet.Event, error)
	Events(offset, limit int) ([]wallet.Event, error)

	ReleaseInputs(txns []types.Transaction, v2txns []types.V2Transaction)

	// v1
	FundTransaction(txn *types.Transaction, amount types.Currency, useUnconfirmed bool) ([]types.Hash256, error)
	SignTransaction(txn *types.Transaction, toSign []types.Hash256, cf types.CoveredFields)

	// v2
	FundV2Transaction(txn *types.V2Transaction, amount types.Currency, useUnconfirmed bool) (types.ChainIndex, []int, error)
	SignV2Inputs(txn *types.V2Transaction, toSign []int)
}

A Wallet manages Siacoins and funds transactions

type WalletPendingResp 

type WalletPendingResp []wallet.Event

WalletPendingResp is the response body for the [GET] /wallet/pending endpoint

func (WalletPendingResp) PrometheusMetric 

func (w WalletPendingResp) PrometheusMetric() (metrics []prometheus.Metric)

PrometheusMetric returns Prometheus samples for the host pending transactions.

type WalletResponse 

type WalletResponse struct {
	wallet.Balance

	Address types.Address `json:"address"`
}

WalletResponse is the response body for the [GET] /wallet endpoint.

func (WalletResponse) PrometheusMetric 

func (wr WalletResponse) PrometheusMetric() []prometheus.Metric

PrometheusMetric returns Prometheus samples for the host wallet.

type WalletSendSiacoinsRequest 

type WalletSendSiacoinsRequest struct {
	Address          types.Address  `json:"address"`
	Amount           types.Currency `json:"amount"`
	SubtractMinerFee bool           `json:"subtractMinerFee"`
}

WalletSendSiacoinsRequest is the request body for the [POST] /wallet/send endpoint.

type WalletTransactionsResp 

type WalletTransactionsResp []wallet.Event

WalletTransactionsResp is the response body for the [GET] /wallet/transactions endpoint

func (WalletTransactionsResp) PrometheusMetric 

func (w WalletTransactionsResp) PrometheusMetric() (metrics []prometheus.Metric)

PrometheusMetric returns Prometheus samples for the hosts transactions.

type Webhooks 

type Webhooks interface {
	Webhooks() ([]webhooks.Webhook, error)
	RegisterWebhook(callbackURL string, scopes []string) (webhooks.Webhook, error)
	UpdateWebhook(id int64, callbackURL string, scopes []string) (webhooks.Webhook, error)
	RemoveWebhook(id int64) error
	BroadcastToWebhook(id int64, event, scope string, data interface{}) error
}

Webhooks manages webhooks

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.