filestore

Documentation

Overview

Package filestore implements a Blockstore which is able to read certain blocks of data directly from its original location in the filesystem.

In a Filestore, object leaves are stored as FilestoreNodes. FilestoreNodes include a filesystem path and an offset, allowing a Blockstore dealing with such blocks to avoid storing the whole contents and reading them from their filesystem location instead.

Index

• Variables
• func IsURL(str string) bool
• func ListAll(fs *Filestore, fileOrder bool) (func() *ListRes, error)
• func VerifyAll(fs *Filestore, fileOrder bool) (func() *ListRes, error)
• type CorruptReferenceError
  • func (c CorruptReferenceError) Error() string
• type FileManager
  • func NewFileManager(ds ds.Batching, root string) *FileManager
  • func (f *FileManager) AllKeysChan(ctx context.Context) (<-chan cid.Cid, error)
  • func (f *FileManager) DeleteBlock(c cid.Cid) error
  • func (f *FileManager) Get(c cid.Cid) (blocks.Block, error)
  • func (f *FileManager) GetSize(c cid.Cid) (int, error)
  • func (f *FileManager) Has(c cid.Cid) (bool, error)
  • func (f *FileManager) Put(b *posinfo.FilestoreNode) error
  • func (f *FileManager) PutMany(bs []*posinfo.FilestoreNode) error
• type Filestore
  • func NewFilestore(bs blockstore.Blockstore, fm *FileManager) *Filestore
  • func (f *Filestore) AllKeysChan(ctx context.Context) (<-chan cid.Cid, error)
  • func (f *Filestore) DeleteBlock(c cid.Cid) error
  • func (f *Filestore) FileManager() *FileManager
  • func (f *Filestore) Get(c cid.Cid) (blocks.Block, error)
  • func (f *Filestore) GetSize(c cid.Cid) (int, error)
  • func (f *Filestore) Has(c cid.Cid) (bool, error)
  • func (f *Filestore) HashOnRead(enabled bool)
  • func (f *Filestore) MainBlockstore() blockstore.Blockstore
  • func (f *Filestore) Put(b blocks.Block) error
  • func (f *Filestore) PutMany(bs []blocks.Block) error
• type ListRes
  • func List(fs *Filestore, key cid.Cid) *ListRes
  • func Verify(fs *Filestore, key cid.Cid) *ListRes
  • func (r *ListRes) FormatLong(enc func(cid.Cid) string) string
• type Status
  • func (s Status) Format() string
  • func (s Status) String() string

Variables

var ErrFilestoreNotEnabled = errors.New("filestore is not enabled, see https://git.io/vNItf")

var ErrUrlstoreNotEnabled = errors.New("urlstore is not enabled")

var FilestorePrefix = ds.NewKey("filestore")

FilestorePrefix identifies the key prefix for FileManager blocks.

Functions

func IsURL

func IsURL(str string) bool

IsURL returns true if the string represents a valid URL that the urlstore can handle. More specifically it returns true if a string begins with 'http://' or 'https://'.

func ListAll

func ListAll(fs *Filestore, fileOrder bool) (func() *ListRes, error)

ListAll returns a function as an iterator which, once invoked, returns one by one each block in the Filestore's FileManager. ListAll does not verify that the references are valid or whether the raw data is accessible. See VerifyAll().

func VerifyAll

func VerifyAll(fs *Filestore, fileOrder bool) (func() *ListRes, error)

VerifyAll returns a function as an iterator which, once invoked, returns one by one each block in the Filestore's FileManager. VerifyAll checks that the reference is valid and that the block data can be read.

Types

type CorruptReferenceError

type CorruptReferenceError struct {
	Code Status
	Err  error
}

CorruptReferenceError implements the error interface. It is used to indicate that the block contents pointed by the referencing blocks cannot be retrieved (i.e. the file is not found, or the data changed as it was being read).

func (CorruptReferenceError) Error

func (c CorruptReferenceError) Error() string

Error() returns the error message in the CorruptReferenceError as a string.

type FileManager

type FileManager struct {
	AllowFiles bool
	AllowUrls  bool
	// contains filtered or unexported fields
}

FileManager is a blockstore implementation which stores special blocks FilestoreNode type. These nodes only contain a reference to the actual location of the block data in the filesystem (a path and an offset).

func NewFileManager

func NewFileManager(ds ds.Batching, root string) *FileManager

NewFileManager initializes a new file manager with the given datastore and root. All FilestoreNodes paths are relative to the root path given here, which is prepended for any operations.

func (*FileManager) AllKeysChan

func (f *FileManager) AllKeysChan(ctx context.Context) (<-chan cid.Cid, error)

AllKeysChan returns a channel from which to read the keys stored in the FileManager. If the given context is cancelled the channel will be closed.

func (*FileManager) DeleteBlock

func (f *FileManager) DeleteBlock(c cid.Cid) error

DeleteBlock deletes the reference-block from the underlying datastore. It does not touch the referenced data.

func (*FileManager) Get

func (f *FileManager) Get(c cid.Cid) (blocks.Block, error)

Get reads a block from the datastore. Reading a block is done in two steps: the first step retrieves the reference block from the datastore. The second step uses the stored path and offsets to read the raw block data directly from disk.

func (*FileManager) GetSize

func (f *FileManager) GetSize(c cid.Cid) (int, error)

GetSize gets the size of the block from the datastore.

This method may successfully return the size even if returning the block would fail because the associated file is no longer available.

func (*FileManager) Has

func (f *FileManager) Has(c cid.Cid) (bool, error)

Has returns if the FileManager is storing a block reference. It does not validate the data, nor checks if the reference is valid.

func (*FileManager) Put

func (f *FileManager) Put(b *posinfo.FilestoreNode) error

Put adds a new reference block to the FileManager. It does not check that the reference is valid.

func (*FileManager) PutMany

func (f *FileManager) PutMany(bs []*posinfo.FilestoreNode) error

PutMany is like Put() but takes a slice of blocks instead, allowing it to create a batch transaction.

type Filestore

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

Filestore implements a Blockstore by combining a standard Blockstore to store regular blocks and a special Blockstore called FileManager to store blocks which data exists in an external file.

func NewFilestore

func NewFilestore(bs blockstore.Blockstore, fm *FileManager) *Filestore

NewFilestore creates one using the given Blockstore and FileManager.

func (*Filestore) AllKeysChan

func (f *Filestore) AllKeysChan(ctx context.Context) (<-chan cid.Cid, error)

AllKeysChan returns a channel from which to read the keys stored in the blockstore. If the given context is cancelled the channel will be closed.

func (*Filestore) DeleteBlock

func (f *Filestore) DeleteBlock(c cid.Cid) error

DeleteBlock deletes the block with the given key from the blockstore. As expected, in the case of FileManager blocks, only the reference is deleted, not its contents. It may return ErrNotFound when the block is not stored.

func (*Filestore) FileManager

func (f *Filestore) FileManager() *FileManager

FileManager returns the FileManager in Filestore.

func (*Filestore) Get

func (f *Filestore) Get(c cid.Cid) (blocks.Block, error)

Get retrieves the block with the given Cid. It may return ErrNotFound when the block is not stored.

func (*Filestore) GetSize

func (f *Filestore) GetSize(c cid.Cid) (int, error)

GetSize returns the size of the requested block. It may return ErrNotFound when the block is not stored.

func (*Filestore) Has

func (f *Filestore) Has(c cid.Cid) (bool, error)

Has returns true if the block with the given Cid is stored in the Filestore.

func (*Filestore) HashOnRead

func (f *Filestore) HashOnRead(enabled bool)

HashOnRead calls blockstore.HashOnRead.

func (*Filestore) MainBlockstore

func (f *Filestore) MainBlockstore() blockstore.Blockstore

MainBlockstore returns the standard Blockstore in the Filestore.

func (*Filestore) Put

func (f *Filestore) Put(b blocks.Block) error

Put stores a block in the Filestore. For blocks of underlying type FilestoreNode, the operation is delegated to the FileManager, while the rest of blocks are handled by the regular blockstore.

func (*Filestore) PutMany

func (f *Filestore) PutMany(bs []blocks.Block) error

PutMany is like Put(), but takes a slice of blocks, allowing the underlying blockstore to perform batch transactions.

type ListRes

type ListRes struct {
	Status   Status
	ErrorMsg string
	Key      cid.Cid
	FilePath string
	Offset   uint64
	Size     uint64
}

ListRes wraps the response of the List*() functions, which allows to obtain and verify blocks stored by the FileManager of a Filestore. It includes information about the referenced block.

func List

func List(fs *Filestore, key cid.Cid) *ListRes

List fetches the block with the given key from the Filemanager of the given Filestore and returns a ListRes object with the information. List does not verify that the reference is valid or whether the raw data is accesible. See Verify().

func Verify

func Verify(fs *Filestore, key cid.Cid) *ListRes

Verify fetches the block with the given key from the Filemanager of the given Filestore and returns a ListRes object with the information. Verify makes sure that the reference is valid and the block data can be read.

func (*ListRes) FormatLong

func (r *ListRes) FormatLong(enc func(cid.Cid) string) string

FormatLong returns a human readable string for a ListRes object

type Status

type Status int32

Status is used to identify the state of the block data referenced by a FilestoreNode. Among other places, it is used by CorruptReferenceError.

const (
	StatusOk           Status = 0
	StatusFileError    Status = 10 // Backing File Error
	StatusFileNotFound Status = 11 // Backing File Not Found
	StatusFileChanged  Status = 12 // Contents of the file changed
	StatusOtherError   Status = 20 // Internal Error, likely corrupt entry
	StatusKeyNotFound  Status = 30
)

These are the supported Status codes.

func (Status) Format

func (s Status) Format() string

Format returns the status formatted as a string with leading 0s.

func (Status) String

func (s Status) String() string

String provides a human-readable representation for Status codes.