api

package
v1.9.3 Latest Latest
Warning

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

 Go to latest Published: Nov 21, 2024 License: MIT Imports: 34 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultListSectorIDsLimit = 10000

DefaultListSectorIDsLimit limits range of results for sectorIDs listing.

Variables

View Source 
var ErrBadMerkleProof = errors.New("host provided incorrect sector data or Merkle proof")

ErrBadMerkleProof is an error returned when MerkleProof verification fails.

It is returned by Client.DownloadAndVerify and by the reader returned by Client.DownloadBinaryAndVerify.

Functions

func GetRoutes 

func GetRoutes(ol HandlerHTTPapi) []api2.Route

GetRoutes return api routes.

Types

type API 

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

API represent host API.

func NewAPI 

func NewAPI(ts TokenStorage, hostSK crypto.SecretKey, host Host) *API

NewAPI return new host API.

func (*API) AttachSectors 

func (a *API) AttachSectors(ctx context.Context, req *AttachSectorsRequest) (*AttachSectorsResponse, error)

AttachSectors handler for /attach [POST] request.

func (*API) Close 

func (a *API) Close() error

Close stop API server.

func (*API) DownloadBinaryWithToken added in v1.9.3 

func (a *API) DownloadBinaryWithToken(ctx context.Context, req *DownloadBinaryWithTokenRequest) (*DownloadBinaryWithTokenResponse, error)

DownloadBinaryWithToken handler for /binary-download [POST] request.

func (*API) DownloadWithToken 

func (a *API) DownloadWithToken(ctx context.Context, req *DownloadWithTokenRequest) (*DownloadWithTokenResponse, error)

DownloadWithToken handler for /download [POST] request.

func (*API) Health 

func (a *API) Health(ctx context.Context, req *HealthRequest) (*HealthResponse, error)

Health is a handler for /health [GET] request.

func (*API) ListSectorIDs 

func (a *API) ListSectorIDs(ctx context.Context, req *ListSectorIDsRequest) (*ListSectorIDsResponse, error)

ListSectorIDs handler for /list-sector-ids [GET] request.

func (*API) RemoveSectors 

func (a *API) RemoveSectors(ctx context.Context, req *RemoveSectorsRequest) (*RemoveSectorsResponse, error)

RemoveSectors handler for /remove-sectors [POST] request.

func (*API) Start 

func (a *API) Start(ln net.Listener) (err error)

Start run API.

func (*API) TokenResources 

func (a *API) TokenResources(ctx context.Context, req *TokenResourcesRequest) (*TokenResourcesResponse, error)

TokenResources handler for /resources [GET] request.

func (*API) UploadBinaryWithToken added in v1.9.3 

func (a *API) UploadBinaryWithToken(ctx context.Context, req *UploadBinaryWithTokenRequest) (*UploadBinaryWithTokenResponse, error)

UploadBinaryWithToken handler for /binary-upload [POST] request.

func (*API) UploadWithToken 

func (a *API) UploadWithToken(ctx context.Context, req *UploadWithTokenRequest) (*UploadWithTokenResponse, error)

UploadWithToken handler for /upload [POST] request.

type AttachSectorsError 

type AttachSectorsError struct {
	IncorrectBlock   bool   `json:"incorrect_block,omitempty"`
	NotEnoughStorage bool   `json:"not_enough_storage,omitempty"`
	UnknownError     string `json:"unknown_error,omitempty"`
}

AttachSectorsError represent error message.

func (AttachSectorsError) Error 

func (e AttachSectorsError) Error() string

type AttachSectorsRequest 

type AttachSectorsRequest struct {
	ContractID      types.FileContractID       `json:"contract_id"`
	Sectors         []TokenAndSector           `json:"sectors"`
	Revision        types.FileContractRevision `json:"revision"`
	RenterSignature []byte                     `json:"renter_signature"`
	BlockHeight     types.BlockHeight          `json:"block_height"` // must be current or previous block
}

AttachSectorsRequest represent request data.

type AttachSectorsResponse 

type AttachSectorsResponse struct {
	HostSignature []byte `json:"host_signature"`
}

AttachSectorsResponse represent response data.

type Client 

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

func HostClientFromHttpClient 

func HostClientFromHttpClient(host, port string, client api2.HttpClient) (*Client, error)

HostClientFromHttpClient creates host API client initialized with provided http.Client.

func HostClientFromPk 

func HostClientFromPk(host, port string, hostPk types.SiaPublicKey) (*Client, error)

HostClientFromPk creates host API client using public key.

func NewClient 

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

func (*Client) AttachSectors 

func (c *Client) AttachSectors(ctx context.Context, req *AttachSectorsRequest) (res *AttachSectorsResponse, err error)

func (*Client) Close added in v1.6.2 

func (c *Client) Close() error

func (*Client) DownloadAndVerify 

func (c *Client) DownloadAndVerify(ctx context.Context, req *DownloadWithTokenRequest) (*DownloadWithTokenResponse, error)

DownloadAndVerify calls Client.DownloadWithToken() and verifies merkle proofs.

func (*Client) DownloadBinaryAndVerify added in v1.9.3 

func (c *Client) DownloadBinaryAndVerify(ctx context.Context, req *DownloadBinaryWithTokenRequest) (tokenRecord *TokenRecord, sectionReader io.Reader, err error)

DownloadBinaryAndVerify calls Client.DownloadBinaryWithToken() and verifies merkle proofs.

It returns tokenRecord and a reader producing requested data. If merkle proof verification was requested and proof fails, the reader will fail with ErrBadMerkleProof in one of reads. Note that the reader can return some data before it fails with this error. The caller must receive all the readers from the channels and read all of them to avoid goroutine leak.

func (*Client) DownloadBinaryWithToken added in v1.9.3 

func (c *Client) DownloadBinaryWithToken(ctx context.Context, req *DownloadBinaryWithTokenRequest) (res *DownloadBinaryWithTokenResponse, err error)

func (*Client) DownloadWithToken 

func (c *Client) DownloadWithToken(ctx context.Context, req *DownloadWithTokenRequest) (res *DownloadWithTokenResponse, err error)

func (*Client) Health 

func (c *Client) Health(ctx context.Context, req *HealthRequest) (res *HealthResponse, err error)

func (*Client) ListSectorIDs 

func (c *Client) ListSectorIDs(ctx context.Context, req *ListSectorIDsRequest) (res *ListSectorIDsResponse, err error)

func (*Client) RemoveSectors 

func (c *Client) RemoveSectors(ctx context.Context, req *RemoveSectorsRequest) (res *RemoveSectorsResponse, err error)

func (*Client) TokenResources 

func (c *Client) TokenResources(ctx context.Context, req *TokenResourcesRequest) (res *TokenResourcesResponse, err error)

func (*Client) UploadBinaryCompat added in v1.9.3 

func (c *Client) UploadBinaryCompat(ctx context.Context, req *UploadBinaryWithTokenRequest) (*UploadBinaryWithTokenResponse, error)

UploadBinaryCompat emulates new reader API using old JSON API of server.

func (*Client) UploadBinaryWithToken added in v1.9.3 

func (c *Client) UploadBinaryWithToken(ctx context.Context, req *UploadBinaryWithTokenRequest) (res *UploadBinaryWithTokenResponse, err error)

func (*Client) UploadWithToken 

func (c *Client) UploadWithToken(ctx context.Context, req *UploadWithTokenRequest) (res *UploadWithTokenResponse, err error)

type DownloadBinaryWithTokenRequest added in v1.9.3 

type DownloadBinaryWithTokenRequest struct {
	Authorization string `header:"Authorization"`
	Range         Range  `json:"range"`
}

DownloadBinaryWithTokenRequest requests one sector from a host.

It is more efficient than DownloadWithToken.

type DownloadBinaryWithTokenResponse added in v1.9.3 

type DownloadBinaryWithTokenResponse struct {
	// BinaryData streams the following data:
	//  - uint16 in little endian format (length of next field)
	//  - JSON with TokenRecord
	//  - uint16 in little endian format (length of next field)
	//  - JSON with Section, where Data is not set, but MerkleProof
	//    is set, if requested.
	//  - binary data of requested section
	BinaryData io.ReadCloser `use_as_body:"true" is_stream:"true"`
}

DownloadBinaryWithTokenResponse is response of DownloadBinaryWithTokenRequest.

type DownloadWithTokenError 

type DownloadWithTokenError struct {
	NotEnoughSectorAccesses bool         `json:"not_enough_sector_accesses,omitempty"`
	NotEnoughBytes          bool         `json:"not_enough_bytes,omitempty"`
	NoSuchSector            *crypto.Hash `json:"no_such_sector,omitempty"`
	UnknownError            string       `json:"unknown_error,omitempty"`
}

DownloadWithTokenError represent error message.

func (DownloadWithTokenError) Error 

func (e DownloadWithTokenError) Error() string

type DownloadWithTokenRequest 

type DownloadWithTokenRequest struct {
	Authorization string  `header:"Authorization"`
	Ranges        []Range `json:"ranges"`
}

DownloadWithTokenRequest represent request.

type DownloadWithTokenResponse 

type DownloadWithTokenResponse struct {
	Sections    []Section    `json:"sections"`
	TokenRecord *TokenRecord `json:"token_record,omitempty"`
}

DownloadWithTokenResponse represent response.

type HandlerHTTPapi 

type HandlerHTTPapi interface {
	Health(ctx context.Context, req *HealthRequest) (*HealthResponse, error)
	TokenResources(ctx context.Context, req *TokenResourcesRequest) (*TokenResourcesResponse, error)
	ListSectorIDs(ctx context.Context, req *ListSectorIDsRequest) (*ListSectorIDsResponse, error)
	RemoveSectors(ctx context.Context, req *RemoveSectorsRequest) (*RemoveSectorsResponse, error)
	DownloadWithToken(context.Context, *DownloadWithTokenRequest) (*DownloadWithTokenResponse, error)
	DownloadBinaryWithToken(context.Context, *DownloadBinaryWithTokenRequest) (*DownloadBinaryWithTokenResponse, error)
	UploadWithToken(context.Context, *UploadWithTokenRequest) (*UploadWithTokenResponse, error)
	UploadBinaryWithToken(context.Context, *UploadBinaryWithTokenRequest) (*UploadBinaryWithTokenResponse, error)
	AttachSectors(context.Context, *AttachSectorsRequest) (*AttachSectorsResponse, error)
}

HandlerHTTPapi api interface.

type HealthRequest 

type HealthRequest struct {
}

HealthRequest is a request for /health endpoint.

type HealthResponse 

type HealthResponse struct {
	Alive       bool              `json:"alive"`
	OS          string            `json:"os"`
	Arch        string            `json:"arch"`
	Commit      string            `json:"commit"`
	BuildTime   string            `json:"build_time"`
	BlockHeight types.BlockHeight `json:"block_height"`
}

HealthResponse is a response for /health endpoint.

type Host 

type Host interface {
	BlockHeight() types.BlockHeight
	AddSector(sectorRoot crypto.Hash, sectorData []byte) error
	RemoveSectorBatch(sectorRoots []crypto.Hash) error
	ReadSector(sectorRoot crypto.Hash) ([]byte, error)
	MoveTokenSectorsToStorageObligation(fcID types.FileContractID, newRev types.FileContractRevision, sectorsWithTokens []types.SectorWithToken, renterSig []byte) ([]byte, error)
}

Host represent host interface.

type HostClienter 

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

HostClienter stores and provides clients for host API.

func NewClienter 

func NewClienter(opts ...Option) *HostClienter

NewClienter creates HostClienter.

func (*HostClienter) Client 

func (hc *HostClienter) Client(host, port string, hostPk types.SiaPublicKey) (*Client, error)

Client returns client by public key.

type HostClienterConfig added in v1.6.2 

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

HostClienterConfig represents HostClienter settings.

func NewDefaultHostClienterConfig added in v1.6.2 

func NewDefaultHostClienterConfig() *HostClienterConfig

NewDefaultHostClienterConfig creates default HostClienterConfig.

type ListSectorIDsRequest 

type ListSectorIDsRequest struct {
	Authorization string `header:"Authorization"`
	PageID        string `json:"page_id"`
}

ListSectorIDsRequest represents request.

type ListSectorIDsResponse 

type ListSectorIDsResponse struct {
	SectorIDs  []crypto.Hash `json:"sector_ids"`
	NextPageID string        `json:"next_page_id"`
}

ListSectorIDsResponse represents response.

type Option added in v1.6.2 

type Option func(*HostClienterConfig)

Option is option callback for NewHostClienter.

func WithLRU added in v1.6.2 

func WithLRU(lruSize int) Option

WithLRU is an option for LRU.

type Range 

type Range struct {
	MerkleRoot  crypto.Hash `json:"merkle_root"`
	Offset      uint32      `json:"offset"`
	Length      uint32      `json:"length"`
	MerkleProof bool        `json:"merkle_proof"`
}

Range part of request.

type RemoveSectorsRequest 

type RemoveSectorsRequest struct {
	Authorization string `header:"Authorization"`
	SectorIDs     []crypto.Hash
}

RemoveSectorsRequest represents request.

type RemoveSectorsResponse 

type RemoveSectorsResponse struct{}

RemoveSectorsResponse represents response.

type Section 

type Section struct {
	Data        []byte        `json:"data"`
	MerkleProof []crypto.Hash `json:"merkle_proof"`
}

Section part of response.

type TokenAndSector 

type TokenAndSector struct {
	Authorization string      `json:"Authorization"`
	SectorID      crypto.Hash `json:"sector_id"`
}

TokenAndSector include information about token and sectors.

type TokenRecord 

type TokenRecord struct {
	DownloadBytes  int64            `json:"download_bytes"`
	UploadBytes    int64            `json:"upload_bytes"`
	SectorAccesses int64            `json:"sector_accesses"`
	TokenInfo      TokenStorageInfo `json:"token_info"`
}

TokenRecord include information about token record.

type TokenResourcesRequest 

type TokenResourcesRequest struct {
	Authorization string `header:"Authorization"`
}

TokenResourcesRequest represents request.

type TokenResourcesResponse 

type TokenResourcesResponse struct {
	UploadBytes    int64     `json:"upload_bytes,omitempty"`
	DownloadBytes  int64     `json:"download_bytes,omitempty"`
	SectorAccesses int64     `json:"sector_accesses,omitempty"`
	Storage        int64     `json:"storage,omitempty"`
	LastChangeTime time.Time `json:"last_change_time,omitempty"`
}

TokenResourcesResponse represents response.

type TokenStorage 

type TokenStorage interface {
	TokenRecord(id types.TokenID) (tokenstorage.TokenRecord, error)
	RecordDownload(id types.TokenID, downloadBytes, sectorAccesses int64, time time.Time) (tokenstorage.TokenRecord, error)
	AddSectors(id types.TokenID, sectorsIDs []crypto.Hash, time time.Time) (tokenstorage.TokenRecord, error)
	ListSectorIDs(id types.TokenID, pageID string, limit int) (sectorIDs []crypto.Hash, nextPageID string, err error)
	RemoveSpecificSectors(id types.TokenID, sectorsIDs []crypto.Hash, time time.Time) error
	AttachSectors(tokensSectors map[types.TokenID][]crypto.Hash, time time.Time) error
	EnoughStorageResource(id types.TokenID, sectorsNum int64, now time.Time) (bool, error)
}

TokenStorage represent communication between api and token storage.

type TokenStorageInfo 

type TokenStorageInfo struct {
	Storage        int64     `json:"storage"` // sectors * second.
	SectorsNum     uint64    `json:"sectors_num"`
	LastChangeTime time.Time `json:"last_change_time"`
}

TokenStorageInfo represent info about token storage resource.

type UploadBinaryWithTokenRequest added in v1.9.3 

type UploadBinaryWithTokenRequest struct {
	Authorization string        `header:"Authorization"`
	Sector        io.ReadCloser `use_as_body:"true" is_stream:"true"`
}

UploadBinaryWithTokenRequest sends one sector as raw binary data.

This is more efficient than UploadWithToken, which sends over JSON in base64 form, causing more bandwidth and encoding. Another benefit is streaming, which provides reading from disk using less memory.

type UploadBinaryWithTokenResponse added in v1.9.3 

type UploadBinaryWithTokenResponse struct {
	TokenRecord *TokenRecord `json:"token_record,omitempty"`
}

UploadBinaryWithTokenResponse is response for UploadBinaryWithTokenRequest.

type UploadWithTokenError 

type UploadWithTokenError struct {
	DataLengthIsZero    bool         `json:"data_length_is_zero,omitempty"`
	IncorrectSectorSize bool         `json:"incorrect_sector_size,omitempty"`
	NotEnoughBytes      bool         `json:"not_enough_bytes,omitempty"`
	NotEnoughStorage    bool         `json:"not_enough_storage,omitempty"`
	UnknownError        string       `json:"unknown_error,omitempty"`
	TokenRecord         *TokenRecord `json:"token_record,omitempty"`
}

UploadWithTokenError represent error message.

func (UploadWithTokenError) Error 

func (e UploadWithTokenError) Error() string

type UploadWithTokenRequest 

type UploadWithTokenRequest struct {
	Authorization string   `header:"Authorization"`
	Sectors       [][]byte `json:"sectors"`
}

UploadWithTokenRequest represent request data.

type UploadWithTokenResponse 

type UploadWithTokenResponse struct {
	TokenRecord *TokenRecord `json:"token_record,omitempty"`
}

UploadWithTokenResponse represent response data.

Source Files

View all Source files

Directories

Path Synopsis

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.