feed

package
v1.0.0-alpha Latest Latest
Warning

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

 Go to latest Published: Dec 29, 2018 License: GPL-3.0 Imports: 21 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 

func (dtp *DefaultTimestampProvider) Now() Timestamp

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(chunkAddr storage.Address, data []byte) 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

Source Files

View all Source files

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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.