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 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 ¶ added in v0.5.0
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 ¶ added in v0.2.0
IsChannel returns (the channel name, true) or (_, false) if the underlying type matches
func (AnyRef) IsFeed ¶ added in v0.2.0
IsFeed returns (the feed reference, true) or (_, false) if the underlying type matches
func (AnyRef) IsMessage ¶ added in v0.2.0
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 ¶ added in v0.5.0
MarshalText implements encoding.TextMarshaler
func (AnyRef) ShortSigil ¶ added in v0.5.0
ShortSigil returns a truncated version of Sigil()
func (AnyRef) Sigil ¶ added in v0.5.0
Sigil returns the classic way to encode a reference (starting with @, % or &, depending on the)
func (AnyRef) String ¶ added in v0.5.0
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 ¶ added in v0.3.0
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 ¶ added in v0.3.0
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 ¶ added in v0.5.0
ShortSigil returns a truncated version of Sigil()
func (BlobRef) Sigil ¶ added in v0.5.0
Sigil returns the BlobRef with the sigil &, it's base64 encoded hash and the used algo (currently only sha256)
func (BlobRef) String ¶ added in v0.5.0
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 ¶ added in v0.5.0
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 ¶ added in v0.5.0
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 ¶ added in v0.5.0
func (c CanonicalURI) Feed() (FeedRef, bool)
Feed returns the underlying feed reference and true, if the URI is indeed for a feed
func (CanonicalURI) Kind ¶ added in v0.5.0
func (c CanonicalURI) Kind() Kind
Kind implements refs.URI
func (CanonicalURI) Message ¶ added in v0.5.0
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 ¶ added in v0.5.0
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 ¶ added in v0.5.0
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 ¶ added in v0.5.0
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 ¶ added in v0.5.0
func (e *ExperimentalURI) Feed() (FeedRef, bool)
Feed returns the underlying feed reference and true, if the URI is indeed for a feed
func (*ExperimentalURI) Kind ¶ added in v0.5.0
func (e *ExperimentalURI) Kind() Kind
Kind implements refs.URI
func (*ExperimentalURI) Message ¶ added in v0.5.0
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 ¶ added in v0.5.0
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 ¶ added in v0.3.0
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 ¶ added in v0.5.0
ShortSigil returns a truncated version of Sigil()
func (FeedRef) Sigil ¶ added in v0.5.0
Sigil returns the FeedRef as a string with the sigil @, it's base64 encoded hash and the used algo
func (FeedRef) String ¶ added in v0.5.0
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 encodedTime.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 encodedTime.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 ¶ added in v0.5.0
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 ¶ added in v0.3.0
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 ¶ added in v0.3.0
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 ¶ added in v0.5.0
func (mr MessageRef) ShortSigil() string
ShortSigil prints a shortend version of Sigil()
func (MessageRef) Sigil ¶ added in v0.5.0
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 ¶ added in v0.5.0
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 ¶ added in v0.5.0
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 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 ¶ added in v0.3.0
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 ¶ added in v0.5.0
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 ¶ added in v0.5.0
type URIOption func(e *ExperimentalURI) error
URIOption allow to customaize an experimental ssb-uri
func RoomInvite ¶ added in v0.5.0
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 encodedTime.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.