api.go

package api

// Files provides key-value storage with append-only values.
type Files interface {
	// Open return file descriptor of the given file name.
	// `existing=true` tells that the file is required to exist already.
	// `existing=false` tells that the file is required to not exist.
	// `write` and `read` tells if the file is being opened for read and for write.
	// `replication` describes replication requirements for the file.
	Open(name string, existing bool, write, read bool, replication string) (int64, error)

	// Close closes the opened file. A file can be closed by garbage collector
	// if it is not used for a certain time.
	Close(fd int64) error

	// SizeOf returns the size of the file in bytes.
	SizeOf(fd int64) (int64, error)

	// Append adds data to the end of the file.
	Append(fd int64, data []byte) error

	// ReadAt reads a part of the file.
	ReadAt(fd int64, offset int64, size int) ([]byte, error)

	// ReadAt returns the list of filenames.
	List() (map[string]int64, error)

	// Delete deletes the file.
	Delete(name string) error
}

// SectorManager gets data sectors and exchanges them with permanent identifiers.
type SectorManager interface {
	// ReadSector takes sector id and returns its content.
	// Data integrity is verified.
	ReadSector(i int64) ([]byte, error)

	// InsecureReadSectorAt takes sector id and coordinates and returns the slice.
	// Data integrity is NOT verified.
	InsecureReadSectorAt(i int64, offset, length int) ([]byte, error)

	// AllocateSector reserves new unique sector id and returns it.
	AllocateSector() (int64, error)

	// WriteSector fills a sector created by AllocateSector with data.
	// WriteSector can be called in the sector id at most once.
	// `replication` describes replication requirements for the sector.
	WriteSector(i int64, data []byte, replication string) error

	// Delete deletes a sector with the sector id.
	Delete(i int64) error
}

// HostIO reads and writes sectors to hosts.
// Integer sectorID must be unique for the encryption key,
// as it is used as nonce in encryption.
type HostIO interface {
	// Read reads the sector identified by sectorRoot from the contract.
	// Data integrity is verified.
	Read(contractID, sectorRoot string, sectorID int64) ([]byte, error)

	// InsecureRead reads a part of the sector.
	// Data integrity is NOT verified.
	InsecureRead(contractID, sectorRoot string, sectorID int64, offset, length int) ([]byte, error)

	// Write creates a sector on the contract with the given data.
	// It returns sectorRoot of the sector.
	Write(contractID string, data []byte, sectorID int64) (string, error)

	// Replace replaces the sector oldSectorRoot on the contract with the new data.
	// It returns new sectorRoot of the sector.
	Replace(contractID string, data []byte, sectorID int64, oldSectorRoot string) (string, error)
}

type Contractor interface {
	// Contracts returns the list of active contracts.
	Contracts() ([]string, error)

	// TODO: Data from hostdb. Important missibg piece of data: latencies.

	// ConcludeContract concludes a contract with the host for the given time.
	ConcludeContract(host string, duration int) (string, error)

	// RenewContract takes contractID and creates a new contract with the same data on the host.
	RenewContract(contractID string, duration int) (string, error)
}