feed

package
v0.0.0-...-aa5841e Latest Latest
Warning

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

Go to latest
Published: Nov 28, 2022 License: GPL-3.0 Imports: 20 Imported by: 0

Documentation

Overview

Package feeds defines Swarm Feeds.

Swarm Feeds allows a user to build an update feed about a particular topic without resorting to ENS on each update. The update scheme is built on swarm chunks with chunk keys following a predictable, versionable pattern.

A Feed is tied to a unique identifier that is deterministically generated out of the chosen topic.

A Feed is defined as the series of updates of a specific user about a particular topic

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:

updateAddr = H(Feed, Epoch ID) where H is the SHA3 hash function Feed is the combination of Topic and the user address Epoch ID is a time slot. See the lookup package for more information.

A user looking up a the latest update in a Feed only needs to know the Topic and the other user's address.

The Feed Update data is: updatedata = Feed|Epoch|data

The full update data that goes in the chunk payload is: updatedata|sign(updatedata)

Structure Summary:

Request: Feed Update with signature

Update: headers + data
	Header: Protocol version and reserved for future use placeholders
	ID: Information about how to locate a specific update
		Feed: Represents a user's series of publications about a specific Topic
			Topic: Item that the updates are about
			User: User who updates the Feed
		Epoch: time slot where the update is stored

Handler is the API for feeds It enables creating, updating, syncing and retrieving feed updates and their data

Index

Constants

View Source
const (
	ErrInit = iota
	ErrNotFound
	ErrIO
	ErrUnauthorized
	ErrInvalidValue
	ErrDataOverflow
	ErrNothingToReturn
	ErrCorruptData
	ErrInvalidSignature
	ErrNotSynced
	ErrPeriodDepth
	ErrCnt
)
View Source
const MaxUpdateDataLength = chunk.DefaultSize - signatureLength - idLength - headerLength

MaxUpdateDataLength indicates the maximum payload size for a feed update

View Source
const ProtocolVersion uint8 = 0

ProtocolVersion defines the current version of the protocol that will be included in each update message

View Source
const TopicLength = storage.AddressLength

TopicLength establishes the max length of a topic string

Variables

View Source
var ErrTopicTooLong = fmt.Errorf("Topic is too long. Max length is %d", TopicLength)

ErrTopicTooLong is returned when creating a topic with a name/related content too long

View Source
var TimestampProvider timestampProvider = NewDefaultTimestampProvider()

TimestampProvider sets the time source of the feeds package

Functions

func Hex

func Hex(bin binarySerializer) string

Hex serializes the structure and converts it to a hex string

func NewError

func NewError(code int, s string) error

NewError creates a new Swarm feeds Error object with the specified code and custom error message

func NewErrorf

func NewErrorf(code int, format string, args ...interface{}) error

NewErrorf is a convenience version of NewError that incorporates printf-style formatting

Types

type DefaultTimestampProvider

type DefaultTimestampProvider struct {
}

DefaultTimestampProvider is a TimestampProvider that uses system time as time source

func NewDefaultTimestampProvider

func NewDefaultTimestampProvider() *DefaultTimestampProvider

NewDefaultTimestampProvider creates a system clock based timestamp provider

func (*DefaultTimestampProvider) Now

Now returns the current time according to this provider

type Error

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

Error is a the typed error object used for Swarm feeds

func (*Error) Code

func (e *Error) Code() int

Code returns the error code Error codes are enumerated in the error.go file within the feeds package

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface

type Feed

type Feed struct {
	Topic Topic          `json:"topic"`
	User  common.Address `json:"user"`
}

Feed represents a particular user's stream of updates on a topic

func (*Feed) AppendValues

func (f *Feed) AppendValues(values Values)

AppendValues serializes this structure into the provided string key-value store useful to build query strings

func (*Feed) FromValues

func (f *Feed) FromValues(values Values) (err error)

FromValues deserializes this instance from a string key-value store useful to parse query strings

func (*Feed) Hex

func (f *Feed) Hex() string

Hex serializes the feed to a hex string

type GenericSigner

type GenericSigner struct {
	PrivKey *ecdsa.PrivateKey
	// contains filtered or unexported fields
}

GenericSigner implements the Signer interface It is the vanilla signer that probably should be used in most cases

func NewGenericSigner

func NewGenericSigner(privKey *ecdsa.PrivateKey) *GenericSigner

NewGenericSigner builds a signer that will sign everything with the provided private key

func (*GenericSigner) Address

func (s *GenericSigner) Address() common.Address

Address returns the public key of the signer's private key

func (*GenericSigner) Sign

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

Sign signs the supplied data It wraps the ethereum crypto.Sign() method

type Handler

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

func NewHandler

func NewHandler(params *HandlerParams) *Handler

NewHandler creates a new Swarm feeds API

func (*Handler) GetContent

func (h *Handler) GetContent(feed *Feed) (storage.Address, []byte, error)

GetContent retrieves the data payload of the last synced update of the feed

func (*Handler) Lookup

func (h *Handler) Lookup(ctx context.Context, query *Query) (*cacheEntry, error)

Lookup retrieves a specific or latest feed update Lookup works differently depending on the configuration of `query` See the `query` documentation and helper functions: `NewQueryLatest` and `NewQuery`

func (*Handler) NewRequest

func (h *Handler) NewRequest(ctx context.Context, feed *Feed) (request *Request, err error)

NewRequest prepares a Request structure with all the necessary information to just add the desired data and sign it. The resulting structure can then be signed and passed to Handler.Update to be verified and sent

func (*Handler) SetStore

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

SetStore sets the store backend for the Swarm feeds API

func (*Handler) Update

func (h *Handler) Update(ctx context.Context, r *Request) (updateAddr storage.Address, err error)

Update publishes a feed update Note that a feed update cannot span chunks, and thus has a MAX NET LENGTH 4096, INCLUDING update header data and signature. This results in a max payload of `maxUpdateDataLength` (check update.go for more details) An error will be returned if the total length of the chunk payload will exceed this limit. Update can only check if the caller is trying to overwrite the very last known version, otherwise it just puts the update on the network.

func (*Handler) Validate

func (h *Handler) Validate(chunk storage.Chunk) bool

Validate is a chunk validation method If it looks like a feed update, the chunk address is checked against the userAddr of the update's signature It implements the storage.ChunkValidator interface

type HandlerParams

type HandlerParams struct {
}

HandlerParams pass parameters to the Handler constructor NewHandler Signer and TimestampProvider are mandatory parameters

type Header struct {
	Version uint8                   // Protocol version
	Padding [headerLength - 1]uint8 // reserved for future use
}

Header defines a update message header including a protocol version byte

type ID

type ID struct {
	Feed         `json:"feed"`
	lookup.Epoch `json:"epoch"`
}

ID uniquely identifies an update on the network.

func (*ID) Addr

func (u *ID) Addr() (updateAddr storage.Address)

Addr calculates the feed update chunk address corresponding to this ID

func (*ID) AppendValues

func (u *ID) AppendValues(values Values)

AppendValues serializes this structure into the provided string key-value store useful to build query strings

func (*ID) FromValues

func (u *ID) FromValues(values Values) error

FromValues deserializes this instance from a string key-value store useful to parse query strings

type Query

type Query struct {
	Feed
	Hint      lookup.Epoch
	TimeLimit uint64
}

Query is used to specify constraints when performing an update lookup TimeLimit indicates an upper bound for the search. Set to 0 for "now"

func NewQuery

func NewQuery(feed *Feed, time uint64, hint lookup.Epoch) *Query

NewQuery constructs an Query structure to find updates on or before `time` if time == 0, the latest update will be looked up

func NewQueryLatest

func NewQueryLatest(feed *Feed, hint lookup.Epoch) *Query

NewQueryLatest generates lookup parameters that look for the latest update to a feed

func (*Query) AppendValues

func (q *Query) AppendValues(values Values)

AppendValues serializes this structure into the provided string key-value store useful to build query strings

func (*Query) FromValues

func (q *Query) FromValues(values Values) error

FromValues deserializes this instance from a string key-value store useful to parse query strings

type Request

type Request struct {
	Update    // actual content that will be put on the chunk, less signature
	Signature *Signature
	// contains filtered or unexported fields
}

Request represents a request to sign or signed feed update message

func NewFirstRequest

func NewFirstRequest(topic Topic) *Request

NewFirstRequest returns a ready to sign request to publish a first feed update

func (*Request) AppendValues

func (r *Request) AppendValues(values Values) []byte

AppendValues serializes this structure into the provided string key-value store useful to build query strings

func (*Request) FromValues

func (r *Request) FromValues(values Values, data []byte) error

FromValues deserializes this instance from a string key-value store useful to parse query strings

func (*Request) GetDigest

func (r *Request) GetDigest() (result common.Hash, err error)

GetDigest creates the feed update digest used in signatures the serialized payload is cached in .binaryData

func (*Request) IsUpdate

func (r *Request) IsUpdate() bool

IsUpdate returns true if this request models a signed update or otherwise it is a signature request

func (*Request) MarshalJSON

func (r *Request) MarshalJSON() (rawData []byte, err error)

MarshalJSON takes an update request and encodes it as a JSON structure into a byte array Implements json.Marshaler interface

func (*Request) SetData

func (r *Request) SetData(data []byte)

SetData stores the payload data the feed update will be updated with

func (*Request) Sign

func (r *Request) Sign(signer Signer) error

Sign executes the signature to validate the update message

func (*Request) UnmarshalJSON

func (r *Request) UnmarshalJSON(rawData []byte) error

UnmarshalJSON takes a JSON structure stored in a byte array and populates the Request object Implements json.Unmarshaler interface

func (*Request) Verify

func (r *Request) Verify() (err error)

Verify checks that signatures are valid

type Signature

type Signature [signatureLength]byte

Signature is an alias for a static byte array with the size of a signature

type Signer

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

Signer signs feed update payloads

type TestHandler

type TestHandler struct {
	*Handler
}

func NewTestHandler

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

NewTestHandler creates Handler object to be used for testing purposes.

func (*TestHandler) Close

func (t *TestHandler) Close()

type Timestamp

type Timestamp struct {
	Time uint64 `json:"time"` // Unix epoch timestamp, in seconds
}

Timestamp encodes a point in time as a Unix epoch

func (*Timestamp) MarshalJSON

func (t *Timestamp) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaller interface

func (*Timestamp) UnmarshalJSON

func (t *Timestamp) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaller interface

type Topic

type Topic [TopicLength]byte

Topic represents what a feed is about

func NewTopic

func NewTopic(name string, relatedContent []byte) (topic Topic, err error)

NewTopic creates a new topic from a provided name and "related content" byte array, merging the two together. If relatedContent or name are longer than TopicLength, they will be truncated and an error returned name can be an empty string relatedContent can be nil

func (*Topic) FromHex

func (t *Topic) FromHex(hex string) error

FromHex will parse a hex string into this Topic instance

func (*Topic) Hex

func (t *Topic) Hex() string

Hex will return the topic encoded as an hex string

func (*Topic) MarshalJSON

func (t *Topic) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaller interface

func (*Topic) Name

func (t *Topic) Name(relatedContent []byte) string

Name will try to extract the topic name out of the Topic

func (*Topic) UnmarshalJSON

func (t *Topic) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaller interface

type Update

type Update struct {
	Header Header //
	ID            // Feed Update identifying information
	// contains filtered or unexported fields
}

Update encapsulates the information sent as part of a feed update

func (*Update) AppendValues

func (r *Update) AppendValues(values Values) []byte

AppendValues serializes this structure into the provided string key-value store useful to build query strings

func (*Update) FromValues

func (r *Update) FromValues(values Values, data []byte) error

FromValues deserializes this instance from a string key-value store useful to parse query strings

type Values

type Values interface {
	Get(key string) string
	Set(key, value string)
}

Values interface represents a string key-value store useful for building query strings

Directories

Path Synopsis
Package lookup defines feed lookup algorithms and provides tools to place updates so they can be found
Package lookup defines feed lookup algorithms and provides tools to place updates so they can be found

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL