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
- Variables
- func Hex(bin binarySerializer) string
- func NewError(code int, s string) error
- func NewErrorf(code int, format string, args ...interface{}) error
- type DefaultTimestampProvider
- type Error
- type Feed
- type GenericSigner
- type Handler
- func (h *Handler) GetContent(feed *Feed) (storage.Address, []byte, error)
- func (h *Handler) Lookup(ctx context.Context, query *Query) (*cacheEntry, error)
- func (h *Handler) NewRequest(ctx context.Context, feed *Feed) (request *Request, err error)
- func (h *Handler) SetStore(store *storage.NetStore)
- func (h *Handler) Update(ctx context.Context, r *Request) (updateAddr storage.Address, err error)
- func (h *Handler) Validate(chunkAddr storage.Address, data []byte) bool
- type HandlerParams
- type Header
- type ID
- type Query
- type Request
- func (r *Request) AppendValues(values Values) []byte
- func (r *Request) FromValues(values Values, data []byte) error
- func (r *Request) GetDigest() (result common.Hash, err error)
- func (r *Request) IsUpdate() bool
- func (r *Request) MarshalJSON() (rawData []byte, err error)
- func (r *Request) SetData(data []byte)
- func (r *Request) Sign(signer Signer) error
- func (r *Request) UnmarshalJSON(rawData []byte) error
- func (r *Request) Verify() (err error)
- type Signature
- type Signer
- type TestHandler
- type Timestamp
- type Topic
- type Update
- type Values
Constants ¶
const ( ErrInit = iota ErrNotFound ErrIO ErrInvalidValue ErrDataOverflow ErrNothingToReturn ErrCorruptData ErrInvalidSignature ErrNotSynced ErrPeriodDepth ErrCnt )
const MaxUpdateDataLength = chunk.DefaultSize - signatureLength - idLength - headerLength
MaxUpdateDataLength indicates the maximum payload size for a feed update
const ProtocolVersion uint8 = 0
ProtocolVersion defines the current version of the protocol that will be included in each update message
const TopicLength = storage.AddressLength
TopicLength establishes the max length of a topic string
Variables ¶
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
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
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
type Feed ¶
Feed represents a particular user's stream of updates on a topic
func (*Feed) AppendValues ¶
AppendValues serializes this structure into the provided string key-value store useful to build query strings
func (*Feed) FromValues ¶
FromValues deserializes this instance from a string key-value store useful to parse query strings
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
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 ¶
GetContent retrieves the data payload of the last synced update of the feed
func (*Handler) Lookup ¶
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 ¶
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) Update ¶
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.
type HandlerParams ¶
type HandlerParams struct {
}
HandlerParams pass parameters to the Handler constructor NewHandler Signer and TimestampProvider are mandatory parameters
type Header ¶
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 ¶
ID uniquely identifies an update on the network.
func (*ID) AppendValues ¶
AppendValues serializes this structure into the provided string key-value store useful to build query strings
func (*ID) FromValues ¶
FromValues deserializes this instance from a string key-value store useful to parse query strings
type Query ¶
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 ¶
NewQuery constructs an Query structure to find updates on or before `time` if time == 0, the latest update will be looked up
func NewQueryLatest ¶
NewQueryLatest generates lookup parameters that look for the latest update to a feed
func (*Query) AppendValues ¶
AppendValues serializes this structure into the provided string key-value store useful to build query strings
func (*Query) FromValues ¶
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 ¶
NewFirstRequest returns a ready to sign request to publish a first feed update
func (*Request) AppendValues ¶
AppendValues serializes this structure into the provided string key-value store useful to build query strings
func (*Request) FromValues ¶
FromValues deserializes this instance from a string key-value store useful to parse query strings
func (*Request) GetDigest ¶
GetDigest creates the feed update digest used in signatures the serialized payload is cached in .binaryData
func (*Request) IsUpdate ¶
IsUpdate returns true if this request models a signed update or otherwise it is a signature request
func (*Request) MarshalJSON ¶
MarshalJSON takes an update request and encodes it as a JSON structure into a byte array Implements json.Marshaler interface
func (*Request) UnmarshalJSON ¶
UnmarshalJSON takes a JSON structure stored in a byte array and populates the Request object Implements json.Unmarshaler interface
type Signature ¶
type Signature [signatureLength]byte
Signature is an alias for a static byte array with the size of a signature
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 ¶
MarshalJSON implements the json.Marshaller interface
func (*Timestamp) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaller interface
type Topic ¶
type Topic [TopicLength]byte
Topic represents what a feed is about
func NewTopic ¶
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) MarshalJSON ¶
MarshalJSON implements the json.Marshaller interface
func (*Topic) UnmarshalJSON ¶
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 ¶
AppendValues serializes this structure into the provided string key-value store useful to build query strings
Source Files
Directories