Documentation ¶
Overview ¶
Package refs strives to offer a couple of types and corresponding encoding code to help other go-based ssb projects to talk about message, feed and blob references without pulling in all of go-ssb and it's network and database code.
Index ¶
- Variables
- func IsMessageUnusable(err error) bool
- func NewExperimentalURI(opts ...URIOption) (*url.URL, error)
- type About
- type AnyRef
- func (ar AnyRef) Algo() RefAlgo
- func (ar AnyRef) IsBlob() (BlobRef, bool)
- func (ar AnyRef) IsChannel() (string, bool)
- func (ar AnyRef) IsFeed() (FeedRef, bool)
- func (ar AnyRef) IsMessage() (MessageRef, bool)
- func (ar AnyRef) MarshalJSON() ([]byte, error)
- func (ar AnyRef) MarshalText() ([]byte, error)
- func (ar AnyRef) ShortSigil() string
- func (ar AnyRef) Sigil() string
- func (ar AnyRef) String() string
- func (ar AnyRef) URI() string
- func (ar *AnyRef) UnmarshalJSON(b []byte) error
- type BlobRef
- func (br BlobRef) Algo() RefAlgo
- func (br BlobRef) CopyHashTo(b []byte) error
- func (br BlobRef) Equal(other BlobRef) bool
- func (br BlobRef) IsValid() error
- func (br BlobRef) MarshalText() ([]byte, error)
- func (br BlobRef) ShortSigil() string
- func (br BlobRef) Sigil() string
- func (br BlobRef) String() string
- func (br BlobRef) URI() string
- func (br *BlobRef) UnmarshalText(text []byte) error
- type ByPrevious
- type CanonicalURI
- type Contact
- type ErrMalfromedMsg
- type ErrRefLen
- type ErrWrongType
- type ExperimentalURI
- type FeedRef
- func (fr FeedRef) Algo() RefAlgo
- func (fr FeedRef) Equal(b FeedRef) bool
- func (fr FeedRef) MarshalText() ([]byte, error)
- func (fr FeedRef) PubKey() ed25519.PublicKey
- func (fr FeedRef) ShortSigil() string
- func (fr FeedRef) Sigil() string
- func (fr FeedRef) String() string
- func (fr FeedRef) URI() string
- func (fr *FeedRef) UnmarshalText(input []byte) error
- type KeyValueAsMap
- type KeyValueRaw
- func (kvr KeyValueRaw) Author() FeedRef
- func (kvr KeyValueRaw) Claimed() time.Time
- func (kvr KeyValueRaw) ContentBytes() []byte
- func (kvr KeyValueRaw) Key() MessageRef
- func (kvr KeyValueRaw) Previous() *MessageRef
- func (kvr KeyValueRaw) Received() time.Time
- func (kvr KeyValueRaw) Seq() int64
- func (kvr KeyValueRaw) ValueContent() *Value
- func (kvr KeyValueRaw) ValueContentJSON() json.RawMessage
- type Kind
- type Mention
- type Message
- type MessageRef
- func (mr MessageRef) Algo() RefAlgo
- func (mr MessageRef) CopyHashTo(b []byte) error
- func (mr MessageRef) Equal(other MessageRef) bool
- func (mr MessageRef) MarshalText() ([]byte, error)
- func (mr MessageRef) ShortSigil() string
- func (mr MessageRef) Sigil() string
- func (mr MessageRef) String() string
- func (mr MessageRef) URI() string
- func (mr *MessageRef) UnmarshalText(input []byte) error
- type MessageRefs
- type Millisecs
- type OldAddress
- type OldPubMessage
- type Post
- type Ref
- type RefAlgo
- type TanglePoint
- type TangledPost
- type Tangles
- type Typed
- type URI
- type URIOption
- type Value
- type ValuePost
- type ValueVote
- type Vote
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidRef = errors.New("ssb: Invalid Ref") ErrInvalidRefType = errors.New("ssb: Invalid Ref Type") ErrInvalidRefAlgo = errors.New("ssb: Invalid Ref Algo") ErrInvalidSig = errors.New("ssb: Invalid Signature") ErrInvalidHash = errors.New("ssb: Invalid Hash") ErrUnuspportedFormat = errors.New("ssb: unsupported format") )
Common errors for invalid references
var ( ErrNotAnURI = errors.New("ssb: not a known URI scheme") ErrNotACanonicalURI = errors.New("ssb: not a caononical URI") )
Errors that might be returned by ParseURI
Functions ¶
func IsMessageUnusable ¶
IsMessageUnusable checks if an error is ErrWrongType, ErrMalfromedMsg or *json.SyntaxError
func NewExperimentalURI ¶
NewExperimentalURI constructs an experimental ssb uri from a slice of options
Example ¶
check := func(err error) { if err != nil { log.Fatal(err) } } fmt.Println() // emptyline so that Output: block looks nicer var testRef FeedRef copy(testRef.id[:], bytes.Repeat([]byte("A"), 32)) // msaddr msaddr, err := NewExperimentalURI( MSAddr("host:port", testRef.PubKey()), ) check(err) fmt.Println("simple multiserver address:") fmt.Println(msaddr.String()) // room invite roomInvite, err := NewExperimentalURI( MSAddr("host:port", testRef.PubKey()), RoomInvite("some-code"), ) check(err) fmt.Println("rooms2 invite:") fmt.Println(roomInvite.String()) // room alias roomAlias, err := NewExperimentalURI( MSAddr("host:port", testRef.PubKey()), RoomAlias("roomID", "userID", "alias", "sig"), ) check(err) fmt.Println("rooms2 alias:") fmt.Println(roomAlias.String())
Output: simple multiserver address: ssb:experimental?action=add-pub&msaddr=net%3Ahost%3Aport~shs%3AQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUE%3D rooms2 invite: ssb:experimental?action=join-room&invite=some-code&msaddr=net%3Ahost%3Aport~shs%3AQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUE%3D rooms2 alias: ssb:experimental?action=consume-alias&msaddr=net%3Ahost%3Aport~shs%3AQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUE%3D&roomID=roomID&userID=userID
Types ¶
type About ¶
type About struct { Type string `json:"type"` About FeedRef `json:"about"` Name string `json:"name,omitempty"` Description string `json:"description,omitempty"` Image *BlobRef `json:"image,omitempty"` }
About represents metadata updates about a feed like name, descriptin or image
func NewAboutImage ¶
NewAboutImage creats a new message to update one's image
func NewAboutName ¶
NewAboutName creats a new message to update one's name
func (*About) UnmarshalJSON ¶
UnmarshalJSON implements JSON deserialization of type:about
type AnyRef ¶
type AnyRef struct {
// contains filtered or unexported fields
}
AnyRef can hold any support reference type, as well as a channel name. Use the Is*() functions to get the underlying values.
func (AnyRef) IsBlob ¶
IsBlob returns (the blob reference, true) or (_, false) if the underlying type matches
func (AnyRef) IsChannel ¶
IsChannel returns (the channel name, true) or (_, false) if the underlying type matches
func (AnyRef) IsFeed ¶
IsFeed returns (the feed reference, true) or (_, false) if the underlying type matches
func (AnyRef) IsMessage ¶
func (ar AnyRef) IsMessage() (MessageRef, bool)
IsMessage returns (the message reference, true) or (_, false) if the underlying type matches
func (AnyRef) MarshalJSON ¶
MarshalJSON turns the underlying reference into a JSON string
func (AnyRef) MarshalText ¶
MarshalText implements encoding.TextMarshaler
func (AnyRef) ShortSigil ¶
ShortSigil returns a truncated version of Sigil()
func (AnyRef) Sigil ¶
Sigil returns the classic way to encode a reference (starting with @, % or &, depending on the)
func (AnyRef) String ¶
String implements the refs.Ref interface and returns a ssb-uri or sigil depending on the type
func (*AnyRef) UnmarshalJSON ¶
UnmarshalJSON implements JSON deserialization for any supported reference type, and #channel names as well
type BlobRef ¶
type BlobRef struct {
// contains filtered or unexported fields
}
BlobRef defines a static binary attachment reference, identified it's hash.
func NewBlobRefFromBytes ¶
NewBlobRefFromBytes allows to create a blob reference from raw bytes
func ParseBlobRef ¶
ParseBlobRef uses ParseRef and checks that it returns a *BlobRef
func (BlobRef) CopyHashTo ¶
CopyHashTo copies the internal hash data somewhere else the target needs to have enough space, otherwise an error is returned.
func (BlobRef) IsValid ¶
IsValid checks if the RefAlgo is known and the length of the data is as expected
func (BlobRef) MarshalText ¶
MarshalText encodes the BlobRef using String()
func (BlobRef) ShortSigil ¶
ShortSigil returns a truncated version of Sigil()
func (BlobRef) Sigil ¶
Sigil returns the BlobRef with the sigil &, it's base64 encoded hash and the used algo (currently only sha256)
func (BlobRef) String ¶
String implements the refs.Ref interface and returns a ssb-uri or sigil depending on the type
func (*BlobRef) UnmarshalText ¶
UnmarshalText uses ParseBlobRef
type ByPrevious ¶
type ByPrevious struct { TangleName string Items []TangledPost // contains filtered or unexported fields }
ByPrevious offers sorting messages by their previous cipherlinks relation. See https://github.com/ssbc/ssb-sort for more.
func (*ByPrevious) Heads ¶
func (by *ByPrevious) Heads() MessageRefs
Heads on a sorted slice of messages returns a slice of message refs which are not referenced by any other. Need to call FillLookup() before using this.
func (*ByPrevious) Len ¶
func (by *ByPrevious) Len() int
Len returns the number of messages, for sort.Sort.
func (*ByPrevious) Less ¶
func (by *ByPrevious) Less(i int, j int) bool
Less decides if message i is before j by looking up how many hops it takes from them to the root. TODO: tiebraker
func (*ByPrevious) Swap ¶
func (by *ByPrevious) Swap(i int, j int)
Swap switches the two items (for sort.Sort)
type CanonicalURI ¶
type CanonicalURI struct {
// contains filtered or unexported fields
}
CanonicalURI currently defines 3 different kinds of URIs for Messages, Feeds and Blobs See https://github.com/fraction/ssb-uri
func (CanonicalURI) Blob ¶
func (c CanonicalURI) Blob() (BlobRef, bool)
Blob returns the underlying blob reference and true, if the URI is indeed for a blob
func (CanonicalURI) Feed ¶
func (c CanonicalURI) Feed() (FeedRef, bool)
Feed returns the underlying feed reference and true, if the URI is indeed for a feed
func (CanonicalURI) Message ¶
func (c CanonicalURI) Message() (MessageRef, bool)
Message returns the underlying message reference and true, if the URI is indeed for a message
func (CanonicalURI) String ¶
func (c CanonicalURI) String() string
type Contact ¶
type Contact struct { Type string `json:"type"` Contact FeedRef `json:"contact"` Following bool `json:"following"` Blocking bool `json:"blocking"` }
Contact represents a (un)follow or (un)block message
func NewContactBlock ¶
NewContactBlock returns a initialzed block message
func NewContactFollow ¶
NewContactFollow returns a initialzed follow message
func (*Contact) UnmarshalJSON ¶
UnmarshalJSON implements JSON deserialization of type:contact
type ErrMalfromedMsg ¶
type ErrMalfromedMsg struct {
// contains filtered or unexported fields
}
ErrMalfromedMsg is returned if a message has invalid values
func (ErrMalfromedMsg) Error ¶
func (emm ErrMalfromedMsg) Error() string
type ErrRefLen ¶
type ErrRefLen struct {
// contains filtered or unexported fields
}
ErrRefLen is returned when a parsed reference was too short.
type ErrWrongType ¶
type ErrWrongType struct {
// contains filtered or unexported fields
}
ErrWrongType is returned if a certain type:value was expected on a message.
func (ErrWrongType) Error ¶
func (ewt ErrWrongType) Error() string
type ExperimentalURI ¶
type ExperimentalURI struct {
// contains filtered or unexported fields
}
ExperimentalURI define magnet-like URIs based on query parameters See https://github.com/ssb-ngi-pointer/ssb-uri-spec
func (*ExperimentalURI) Blob ¶
func (e *ExperimentalURI) Blob() (BlobRef, bool)
Blob returns the underlying blob reference and true, if the URI is indeed for a blob
func (*ExperimentalURI) Feed ¶
func (e *ExperimentalURI) Feed() (FeedRef, bool)
Feed returns the underlying feed reference and true, if the URI is indeed for a feed
func (*ExperimentalURI) Message ¶
func (e *ExperimentalURI) Message() (MessageRef, bool)
Message returns the underlying message reference and true, if the URI is indeed for a message
func (ExperimentalURI) String ¶
func (e ExperimentalURI) String() string
type FeedRef ¶
type FeedRef struct {
// contains filtered or unexported fields
}
FeedRef defines a publickey as ID with a specific algorithm (currently only ed25519)
func NewFeedRefFromBytes ¶
NewFeedRefFromBytes creats a feed reference directly from some bytes
func ParseFeedRef ¶
ParseFeedRef uses ParseRef and checks that it returns a *FeedRef
func (FeedRef) MarshalText ¶
MarshalText implements encoding.TextMarshaler
func (FeedRef) ShortSigil ¶
ShortSigil returns a truncated version of Sigil()
func (FeedRef) Sigil ¶
Sigil returns the FeedRef as a string with the sigil @, it's base64 encoded hash and the used algo
func (FeedRef) String ¶
String implements the refs.Ref interface and returns a ssb-uri or sigil depending on the type
func (*FeedRef) UnmarshalText ¶
UnmarshalText uses ParseFeedRef
type KeyValueAsMap ¶
type KeyValueAsMap struct { Key MessageRef `json:"key"` Value Value `json:"value"` Timestamp Millisecs `json:"timestamp"` }
KeyValueAsMap helps if there are no expectations about the content of a message
type KeyValueRaw ¶
type KeyValueRaw struct { Key_ MessageRef `json:"key"` // Key_ is using the underline here to not conflict with the refs.Message interface (for history ceasons) Value Value `json:"value"` Timestamp Millisecs `json:"timestamp"` }
KeyValueRaw uses json.RawMessage for the content portion, this helps of the content needs to be deserialzed manually or not at all
func (KeyValueRaw) Author ¶
func (kvr KeyValueRaw) Author() FeedRef
Author implements the refs.Message interface
func (KeyValueRaw) Claimed ¶
func (kvr KeyValueRaw) Claimed() time.Time
Claimed implements the refs.Message interface
func (KeyValueRaw) ContentBytes ¶
func (kvr KeyValueRaw) ContentBytes() []byte
ContentBytes implements the refs.Message interface
func (KeyValueRaw) Key ¶
func (kvr KeyValueRaw) Key() MessageRef
Key keyimplements the refs.Message interface
func (KeyValueRaw) Previous ¶
func (kvr KeyValueRaw) Previous() *MessageRef
Previous implements the refs.Message interface
func (KeyValueRaw) Received ¶
func (kvr KeyValueRaw) Received() time.Time
Received implements the refs.Message interface
func (KeyValueRaw) Seq ¶
func (kvr KeyValueRaw) Seq() int64
Seq implements the refs.Message interface
func (KeyValueRaw) ValueContent ¶
func (kvr KeyValueRaw) ValueContent() *Value
ValueContent implements the refs.Message interface
func (KeyValueRaw) ValueContentJSON ¶
func (kvr KeyValueRaw) ValueContentJSON() json.RawMessage
ValueContentJSON implements the refs.Message interface
type Kind ¶
type Kind uint
Kind represents the type of uri reference (as of writing, feed, message or blob)
constant definitions of the known kinds of uri references
type Mention ¶
Mention can link feeds/authors by name, channels or other messages.
func NewMention ¶
NewMention creates a mention:name field that should be added to a message, like a post.
type Message ¶
type Message interface { Key() MessageRef Previous() *MessageRef Seq() int64 Claimed() time.Time Received() time.Time Author() FeedRef ContentBytes() []byte ValueContent() *Value ValueContentJSON() json.RawMessage }
Message allows accessing message aspects without known the feed type
type MessageRef ¶
type MessageRef struct {
// contains filtered or unexported fields
}
MessageRef defines the content addressed version of a ssb message, identified it's hash.
func NewMessageRefFromBytes ¶
func NewMessageRefFromBytes(b []byte, algo RefAlgo) (MessageRef, error)
NewMessageRefFromBytes allows to create a message reference from raw bytes
func ParseMessageRef ¶
func ParseMessageRef(str string) (MessageRef, error)
ParseMessageRef returns a message ref from a string, if it's valid
func (MessageRef) CopyHashTo ¶
func (mr MessageRef) CopyHashTo(b []byte) error
CopyHashTo copies the internal hash data somewhere else the target needs to have enough space, otherwise an error is returned.
func (MessageRef) Equal ¶
func (mr MessageRef) Equal(other MessageRef) bool
Equal compares two references with each other
func (MessageRef) MarshalText ¶
func (mr MessageRef) MarshalText() ([]byte, error)
MarshalText implements encoding.TextMarshaler
func (MessageRef) ShortSigil ¶
func (mr MessageRef) ShortSigil() string
ShortSigil prints a shortend version of Sigil()
func (MessageRef) Sigil ¶
func (mr MessageRef) Sigil() string
Sigil returns the MessageRef with the sigil %, it's base64 encoded hash and the used algo (currently only sha256)
func (MessageRef) String ¶
func (mr MessageRef) String() string
String implements the refs.Ref interface and returns a ssb-uri or sigil depending on the type
func (MessageRef) URI ¶
func (mr MessageRef) URI() string
URI returns the reference in ssb-uri form, no matter it's type
func (*MessageRef) UnmarshalText ¶
func (mr *MessageRef) UnmarshalText(input []byte) error
UnmarshalText implements encoding.TextUnmarshaler
type MessageRefs ¶
type MessageRefs []MessageRef
MessageRefs holds a slice of multiple message references
func (*MessageRefs) String ¶
func (mr *MessageRefs) String() string
String turns a slice of references by String()ifiyng and joining them with a comma
func (*MessageRefs) UnmarshalJSON ¶
func (mr *MessageRefs) UnmarshalJSON(text []byte) error
UnmarshalJSON implements JSON deserialization for a list of message references. It also supports empty and `null` as well as a single refrence as a string ("%foo" and ["%foo"] are both returned as the right-hand case)
type Millisecs ¶
Millisecs is used to marshal and unmarshal time as a JSON number representing a timestamp in milliseconds.
func (Millisecs) MarshalJSON ¶
func (*Millisecs) UnmarshalJSON ¶
type OldAddress ¶
type OldAddress struct { Host string `json:"host"` Port int `json:"port"` Key FeedRef `json:"key"` }
OldAddress uses an ssb.FeedRef as a key this is not strictly necessary since secret-handshake only cares about the 32bytes of public key (and not the feed type) newer type:address uses multiserver and not this nested object
type OldPubMessage ¶
type OldPubMessage struct { Type string `json:"type"` Address OldAddress `json:"address"` }
OldPubMessage is posted after a legacy invite is used to advertise a pub to your followers
type Post ¶
type Post struct { Type string `json:"type"` Text string `json:"text"` Root *MessageRef `json:"root,omitempty"` Branch MessageRefs `json:"branch,omitempty"` Mentions []Mention `json:"mentions,omitempty"` Tangles Tangles `json:"tangles,omitempty"` // Recipients of a message Recps MessageRefs `json:"recps,omitempty"` }
Post represents a textual (markdown) message with some metadata.
type Ref ¶
type Ref interface { Algo() RefAlgo // Sigil returns the pre-URI string ala @foo=.ed25519, %msgkey=.sha256 or &blob=.sha256. Sigil() string // ShortSigil returns a truncated version of Sigil() ShortSigil() string // URI prints the reference as a ssb-uri, following https://github.com/ssb-ngi-pointer/ssb-uri-spec URI() string fmt.Stringer encoding.TextMarshaler }
Ref is the abstract interface all reference types should implement.
type RefAlgo ¶
type RefAlgo string
RefAlgo define a set of known/understood algorithms to reference feeds, messages or blobs
const ( RefAlgoFeedSSB1 RefAlgo = "ed25519" // ssb v1 (legacy, crappy encoding) RefAlgoMessageSSB1 RefAlgo = "sha256" // scuttlebutt happend anyway RefAlgoBlobSSB1 RefAlgo = RefAlgoMessageSSB1 RefAlgoFeedBamboo RefAlgo = "bamboo" RefAlgoMessageBamboo RefAlgo = RefAlgoFeedBamboo RefAlgoFeedBendyButt RefAlgo = "bendybutt-v1" RefAlgoMessageBendyButt RefAlgo = RefAlgoFeedBendyButt RefAlgoCloakedGroup RefAlgo = "cloaked" RefAlgoFeedGabby RefAlgo = "gabbygrove-v1" // cbor based chain RefAlgoMessageGabby RefAlgo = RefAlgoFeedGabby )
Some constant identifiers for the supported references
type TanglePoint ¶
type TanglePoint struct { Root *MessageRef `json:"root"` Previous MessageRefs `json:"previous"` }
TanglePoint represent a single reference point to a common message (root) and the _previous_ messages that were seen at the time in aggregate with other such messages this creates a _happend before_ relation betwee them.
type TangledPost ¶
type TangledPost interface { Key() MessageRef Tangle(name string) (root *MessageRef, prev MessageRefs) }
TangledPost is a utility type for ByPrevious' sorting functionality.
type Tangles ¶
type Tangles map[string]TanglePoint
Tangles represent a set of tangle information ala ssb-tangles v2 ( https://gitlab.com/tangle-js/tangle-graph ) for general information about tangles, you might want to read: https://github.com/cn-uofbasel/ssbdrv/blob/1f7e6b11373ef6f73415f0e9c62f1ade29739251/doc/tangle.md
type URI ¶
type URI interface { fmt.Stringer Feed() (FeedRef, bool) Message() (MessageRef, bool) Blob() (BlobRef, bool) // Type returns a known value of URIKind // URI values can also be interface-asserted to Canonical or Experimental URIs Kind() Kind }
URI is a SSB universal resource identifier. It can be a canonical link for a message, feed or blob.
type URIOption ¶
type URIOption func(e *ExperimentalURI) error
URIOption allow to customaize an experimental ssb-uri
func RoomInvite ¶
RoomInvite adds a rooms2 invite to an experimental URI
type Value ¶
type Value struct { Previous *MessageRef `json:"previous"` Author FeedRef `json:"author"` Sequence int64 `json:"sequence"` Timestamp Millisecs `json:"timestamp"` Hash string `json:"hash"` Content json.RawMessage `json:"content"` Signature string `json:"signature"` Meta map[string]interface{} `json:"meta,omitempty"` }
Value describes a signed entry on a classical ssb feed. The name 'value' comes from seeing them in (hashed) 'key' and 'value' pairs from database query results.