mru

Documentation

Index

• Constants
• func NewBlockEstimator() *blockEstimator
• func NewError(code int, s string) error
• func ToSafeName(name string) (string, error)
• type Error
  • func (e *Error) Code() int
  • func (e *Error) Error() string
• type GenericSigner
  • func (self *GenericSigner) Sign(data common.Hash) (signature Signature, err error)
• type Handler
  • func NewHandler(params *HandlerParams) (*Handler, error)
  • func NewTestHandler(datadir string, params *HandlerParams) (*Handler, error)
  • func (h *Handler) BlockToPeriod(name string, blocknumber uint64) (uint32, error)
  • func (h *Handler) Close()
  • func (h *Handler) GetContent(name string) (storage.Address, []byte, error)
  • func (h *Handler) GetLastPeriod(nameHash string) (uint32, error)
  • func (h *Handler) GetVersion(nameHash string) (uint32, error)
  • func (h *Handler) IsValidated() bool
  • func (h *Handler) Load(addr storage.Address) (*resource, error)
  • func (h *Handler) LookupHistorical(ctx context.Context, nameHash common.Hash, period uint32, refresh bool, ...) (*resource, error)
  • func (h *Handler) LookupHistoricalByName(ctx context.Context, name string, period uint32, refresh bool, ...) (*resource, error)
  • func (h *Handler) LookupLatest(ctx context.Context, nameHash common.Hash, refresh bool, ...) (*resource, error)
  • func (h *Handler) LookupLatestByName(ctx context.Context, name string, refresh bool, maxLookup *LookupParams) (*resource, error)
  • func (h *Handler) LookupPrevious(ctx context.Context, nameHash common.Hash, maxLookup *LookupParams) (*resource, error)
  • func (h *Handler) LookupPreviousByName(ctx context.Context, name string, maxLookup *LookupParams) (*resource, error)
  • func (h *Handler) LookupVersion(ctx context.Context, nameHash common.Hash, period uint32, version uint32, ...) (*resource, error)
  • func (h *Handler) LookupVersionByName(ctx context.Context, name string, period uint32, version uint32, refresh bool, ...) (*resource, error)
  • func (h *Handler) New(ctx context.Context, name string, frequency uint64) (storage.Address, *resource, error)
  • func (h *Handler) PeriodToBlock(name string, period uint32) uint64
  • func (h *Handler) SetStore(store *storage.NetStore)
  • func (h *Handler) Update(ctx context.Context, name string, data []byte) (storage.Address, error)
  • func (h *Handler) UpdateMultihash(ctx context.Context, name string, data []byte) (storage.Address, error)
  • func (h *Handler) Validate(addr storage.Address, data []byte) bool
• type HandlerParams
• type LookupParams
• type Signature
• type Signer

Constants

const (
	ErrInit = iota
	ErrNotFound
	ErrIO
	ErrUnauthorized
	ErrInvalidValue
	ErrDataOverflow
	ErrNothingToReturn
	ErrCorruptData
	ErrInvalidSignature
	ErrNotSynced
	ErrPeriodDepth
	ErrCnt
)

const (
	DbDirName = "resource"
)

Functions

func NewBlockEstimator

func NewBlockEstimator() *blockEstimator

TODO: Average must be adjusted when blockchain connection is present and synced

func NewError

func NewError(code int, s string) error

func ToSafeName

func ToSafeName(name string) (string, error)

ToSafeName is a helper function to create an valid idna of a given resource update name

Types

type Error

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

func (*Error) Code

func (e *Error) Code() int

func (*Error) Error

func (e *Error) Error() string

type GenericSigner

type GenericSigner struct {
	PrivKey *ecdsa.PrivateKey
}

func (*GenericSigner) Sign

func (self *GenericSigner) Sign(data common.Hash) (signature Signature, err error)

type Handler

type Handler struct {
	HashSize int
	// contains filtered or unexported fields
}

Mutable resource is an entity which allows updates to a resource without resorting to ENS on each update. The update scheme is built on swarm chunks with chunk keys following a predictable, versionable pattern.

Updates are defined to be periodic in nature, where periods are expressed in terms of number of blocks.

The root entry of a mutable resource is tied to a unique identifier, typically - but not necessarily - an ens name. The identifier must be an valid IDNA string. It also contains the block number when the resource update was first registered, and the block frequency with which the resource will be updated, both of which are stored as little-endian uint64 values in the database (for a total of 16 bytes). It also contains the unique identifier. It is stored in a separate content-addressed chunk (call it the metadata chunk), with the following layout:

(0x0000|startblock|frequency|identifier)

(The two first zero-value bytes are used for disambiguation by the chunk validator, and update chunk will always have a value > 0 there.)

The root entry tells the requester from when the mutable resource was first added (block number) and in which block number to look for the actual updates. Thus, a resource update for identifier "føø.bar" starting at block 4200 with frequency 42 will have updates on block 4242, 4284, 4326 and so on.

Actual data updates are also made in the form of swarm chunks. The keys of the updates are the hash of a concatenation of properties as follows:

sha256(period|version|namehash)

The period is (currentblock - startblock) / frequency

Using our previous example, this means that a period 3 will have 4326 as the block number.

If more than one update is made to the same block number, incremental version numbers are used successively.

A lookup agent need only know the identifier name in order to get the versions

the resourcedata is: headerlength|period|version|identifier|data

if a validator is active, the chunk data is: resourcedata|sign(resourcedata) otherwise, the chunk data is the same as the resourcedata

headerlength is a 16 bit value containing the byte length of period|version|name

TODO: Include modtime in chunk data + signature

func NewHandler

func NewHandler(params *HandlerParams) (*Handler, error)

Create or open resource update chunk store

func NewTestHandler

func NewTestHandler(datadir string, params *HandlerParams) (*Handler, error)

func (*Handler) BlockToPeriod

func (h *Handler) BlockToPeriod(name string, blocknumber uint64) (uint32, error)

Calculate the period index (aka major version number) from a given block number

func (*Handler) Close

func (h *Handler) Close()

Closes the datastore. Always call this at shutdown to avoid data corruption.

func (*Handler) GetContent

func (h *Handler) GetContent(name string) (storage.Address, []byte, error)

get data from current resource

func (*Handler) GetLastPeriod

func (h *Handler) GetLastPeriod(nameHash string) (uint32, error)

Gets the period of the current data loaded in the resource

func (*Handler) GetVersion

func (h *Handler) GetVersion(nameHash string) (uint32, error)

Gets the version of the current data loaded in the resource

func (*Handler) IsValidated

func (h *Handler) IsValidated() bool

If no ens client is supplied, resource updates are not validated

func (*Handler) Load

func (h *Handler) Load(addr storage.Address) (*resource, error)

Retrieves a resource metadata chunk and creates/updates the index entry for it with the resulting metadata

func (*Handler) LookupHistorical

func (h *Handler) LookupHistorical(ctx context.Context, nameHash common.Hash, period uint32, refresh bool, maxLookup *LookupParams) (*resource, error)

func (*Handler) LookupHistoricalByName

func (h *Handler) LookupHistoricalByName(ctx context.Context, name string, period uint32, refresh bool, maxLookup *LookupParams) (*resource, error)

Retrieves the latest version of the resource update identified by `name` at the specified block height

If an update is found, version numbers are iterated until failure, and the last successfully retrieved version is copied to the corresponding resources map entry and returned.

See also (*Handler).LookupVersion

func (*Handler) LookupLatest

func (h *Handler) LookupLatest(ctx context.Context, nameHash common.Hash, refresh bool, maxLookup *LookupParams) (*resource, error)

func (*Handler) LookupLatestByName

func (h *Handler) LookupLatestByName(ctx context.Context, name string, refresh bool, maxLookup *LookupParams) (*resource, error)

Retrieves the latest version of the resource update identified by `name` at the next update block height

It starts at the next period after the current block height, and upon failure tries the corresponding keys of each previous period until one is found (or startBlock is reached, in which case there are no updates).

Version iteration is done as in (*Handler).LookupHistorical

See also (*Handler).LookupHistorical

func (*Handler) LookupPrevious

func (h *Handler) LookupPrevious(ctx context.Context, nameHash common.Hash, maxLookup *LookupParams) (*resource, error)

func (*Handler) LookupPreviousByName

func (h *Handler) LookupPreviousByName(ctx context.Context, name string, maxLookup *LookupParams) (*resource, error)

Returns the resource before the one currently loaded in the resource index

This is useful where resource updates are used incrementally in contrast to merely replacing content.

Requires a synced resource object

func (*Handler) LookupVersion

func (h *Handler) LookupVersion(ctx context.Context, nameHash common.Hash, period uint32, version uint32, refresh bool, maxLookup *LookupParams) (*resource, error)

func (*Handler) LookupVersionByName

func (h *Handler) LookupVersionByName(ctx context.Context, name string, period uint32, version uint32, refresh bool, maxLookup *LookupParams) (*resource, error)

Searches and retrieves the specific version of the resource update identified by `name` at the specific block height

If refresh is set to true, the resource data will be reloaded from the resource update metadata chunk. It is the callers responsibility to make sure that this chunk exists (if the resource update root data was retrieved externally, it typically doesn't)

func (*Handler) New

func (h *Handler) New(ctx context.Context, name string, frequency uint64) (storage.Address, *resource, error)

Creates a new root entry for a mutable resource identified by `name` with the specified `frequency`.

The signature data should match the hash of the idna-converted name by the validator's namehash function, NOT the raw name bytes.

The start block of the resource update will be the actual current block height of the connected network.

func (*Handler) PeriodToBlock

func (h *Handler) PeriodToBlock(name string, period uint32) uint64

Calculate the block number from a given period index (aka major version number)

func (*Handler) SetStore

func (h *Handler) SetStore(store *storage.NetStore)

SetStore sets the store backend for resource updates

func (*Handler) Update

func (h *Handler) Update(ctx context.Context, name string, data []byte) (storage.Address, error)

func (*Handler) UpdateMultihash

func (h *Handler) UpdateMultihash(ctx context.Context, name string, data []byte) (storage.Address, error)

Adds an actual data update

Uses the data currently loaded in the resources map entry. It is the caller's responsibility to make sure that this data is not stale.

A resource update cannot span chunks, and thus has max length 4096

func (*Handler) Validate

func (h *Handler) Validate(addr storage.Address, data []byte) bool

Validate is a chunk validation method (matches ChunkValidatorFunc signature)

If resource update, owner is checked against ENS record of resource name inferred from chunk data If parsed signature is nil, validates automatically If not resource update, it validates are root chunk if length is metadataChunkOffsetSize and first two bytes are 0

type HandlerParams

type HandlerParams struct {
	QueryMaxPeriods *LookupParams
	Signer          Signer
	HeaderGetter    headerGetter
	OwnerValidator  ownerValidator
}

type LookupParams

type LookupParams struct {
	Limit bool
	Max   uint32
}

type Signature

type Signature [signatureLength]byte

type Signer

type Signer interface {
	Sign(common.Hash) (Signature, error)
}

Signs resource updates