streams

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2023 License: Apache-2.0 Imports: 11 Imported by: 14

README

Hannibal / streams

This package implements the ActivityStreams 2.0 specifications in Hannibal. Specifically, it provides an overly simplistic view of JSON-LD documents, contexts, and the various types of ActivityStreams collections.

This is not a rigorous implementation of JSON-LD. Instead, it is an easy way to navigate well-formatted JSON-LD documents and to iterate over their contents, as well as loading additional documents from the web when necessary.

// Load a document directly from its URL
document, err := streams.Load("https://your.activitypub.server/@documentId")

document.ID() // returns a string value
document.Content() // returns the content property
document.Published() // returns a time value

// AttributedTo could be many things.. a single value, a link, or
// an array of values and links. Let's make all of that easier.
authors := document.AttributedTo() 

// You could just read the first author directly
authors.Name() // returns the 'Name' string
authors.ID() // returns the 'ID' string

// Or you can use it as an iterator
for authors := document.AttributedTo ; !authors.IsNil() ; authors = authors.Tail() {
	authors.Value() // returns the whole value from the array
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func UnmarshalItems

func UnmarshalItems(data any) ([]any, bool)

Types

type Client added in v0.4.0

type Client interface {

	// Load returns a Document representing the specified URI.
	Load(uri string, options ...any) (Document, error)
}

Client represents an HTTP client (or facades in front of one) that can load a JSON-LD document from a remote server. A Client is injected into each streams.Document record so that the Document can load additional linked data as needed.

func NewDefaultClient added in v0.4.0

func NewDefaultClient() Client

type Collection

type Collection struct {
	Context    Context `json:"@context,omitempty"    bson:"context,omitempty"`
	ID         string  `json:"id,omitempty"          bson:"id,omitempty"`
	Type       string  `json:"type,omitempty"        bson:"type,omitempty"`
	Summary    string  `json:"summary,omitempty"     bson:"summary,omitempty"`    // A natural language summarization of the object encoded as HTML. Multiple language tagged summaries may be provided.
	TotalItems int     `json:"totalItems,omitempty"  bson:"totalItems,omitempty"` // A non-negative integer specifying the total number of objects contained by the logical view of the collection. This number might not reflect the actual number of items serialized within the Collection object instance.
	Current    string  `json:"current,omitempty"     bson:"current,omitempty"`    // In a paged Collection, indicates the page that contains the most recently updated member items.
	First      string  `json:"first,omitempty"       bson:"first,omitempty"`      // In a paged Collection, indicates the furthest preceding page of items in the collection.
	Last       string  `json:"last,omitempty"        bson:"last,omitempty"`       // In a paged Collection, indicates the furthest proceeding page of the collection.
	Items      []any   `json:"items,omitempty"       bson:"items,omitempty"`      // Identifies the items contained in a collection. The items might be ordered or unordered.
}

Collection is a subtype of Object that represents ordered or unordered sets of Object or Link instances. https://www.w3.org/ns/activitystreams#Collection

func NewCollection added in v0.3.0

func NewCollection() Collection

func (*Collection) UnmarshalJSON

func (c *Collection) UnmarshalJSON(data []byte) error

func (*Collection) UnmarshalMap

func (c *Collection) UnmarshalMap(data mapof.Any) error

type CollectionPage

type CollectionPage struct {
	Context    Context `json:"@context,omitempty"    bson:"context,omitempty"`
	Type       string  `json:"type,omitempty"        bson:"type,omitempty"`
	Summary    string  `json:"summary,omitempty"     bson:"summary,omitempty"`    // A natural language summarization of the object encoded as HTML. Multiple language tagged summaries may be provided.
	TotalItems int     `json:"totalItems,omitempty"  bson:"totalItems,omitempty"` // A non-negative integer specifying the total number of objects contained by the logical view of the collection. This number might not reflect the actual number of items serialized within the Collection object instance.
	Current    string  `json:"current,omitempty"     bson:"current,omitempty"`    // In a paged Collection, indicates the page that contains the most recently updated member items.
	First      string  `json:"first,omitempty"       bson:"first,omitempty"`      // In a paged Collection, indicates the furthest preceding page of items in the collection.
	Last       string  `json:"last,omitempty"        bson:"last,omitempty"`       // In a paged Collection, indicates the furthest proceeding page of the collection.
	PartOf     string  `json:"partOf,omitempty"      bson:"partOf,omitempty"`     // dentifies the Collection to which a CollectionPage objects items belong.
	Prev       string  `json:"prev,omitempty"        bson:"prev,omitempty"`       // In a paged Collection, identifies the previous page of items.
	Next       string  `json:"next,omitempty"        bson:"next,omitempty"`       // In a paged Collection, indicates the next page of items.
	Items      []any   `json:"items,omitempty"       bson:"items,omitempty"`      // Identifies the items contained in a collection. The items might be ordered or unordered.
}

CollectionPage is used to represent distinct subsets of items from a Collection. Refer to the Activity Streams 2.0 Core for a complete description of the CollectionPage object. https://www.w3.org/ns/activitystreams#CollectionPage

func NewCollectionPage added in v0.3.0

func NewCollectionPage() CollectionPage

func (*CollectionPage) UnmarshalJSON

func (c *CollectionPage) UnmarshalJSON(data []byte) error

*****************************************

  • JSON Marshalling *****************************************

func (*CollectionPage) UnmarshalMap

func (c *CollectionPage) UnmarshalMap(data mapof.Any) error

type Context

type Context []ContextEntry

func DefaultContext

func DefaultContext() Context

DefaultContext represents the standard context defined by the W3C

func NewContext

func NewContext(args ...string) Context

func (*Context) Add

func (c *Context) Add(vocabulary string) *ContextEntry

Add puts a new ContextEntry into the list and returns a pointer to it so that additional properties can be set.

func (Context) Head

func (c Context) Head() *ContextEntry

func (Context) IsEmpty

func (c Context) IsEmpty() bool

func (Context) IsEmptyTail

func (c Context) IsEmptyTail() bool

func (Context) Length

func (c Context) Length() int

func (Context) MarshalJSON

func (c Context) MarshalJSON() ([]byte, error)

func (Context) Tail

func (c Context) Tail() Context

func (*Context) UnmarshalJSON

func (c *Context) UnmarshalJSON(data []byte) error

type ContextEntry

type ContextEntry struct {
	Vocabulary string            // The primary vocabulary represented by the context/document.
	Language   string            // The language
	Extensions map[string]string // a map of additional namespaces that are included in this context/document.
}

ContextEntry https://www.w3.org/TR/json-ld/#the-context

func NewContextEntry

func NewContextEntry(vocabulary string) ContextEntry

func (ContextEntry) HasExtensions

func (entry ContextEntry) HasExtensions() bool

func (ContextEntry) IsLanguageDefined

func (entry ContextEntry) IsLanguageDefined() bool

func (ContextEntry) IsVocabularyOnly

func (entry ContextEntry) IsVocabularyOnly() bool

func (ContextEntry) MarshalJSON

func (entry ContextEntry) MarshalJSON() ([]byte, error)

func (*ContextEntry) WithExtension

func (entry *ContextEntry) WithExtension(key string, value string) *ContextEntry

func (*ContextEntry) WithLanguage

func (entry *ContextEntry) WithLanguage(language string) *ContextEntry

type DefaultClient added in v0.4.0

type DefaultClient struct{}

func (DefaultClient) Load added in v0.4.0

func (client DefaultClient) Load(uri string, options ...any) (Document, error)

Load implements the hannibal.Client interface, which loads an ActivityStream document from a remote server. For the hannibal default client, this method simply loads the document from a remote server with no other processing.

type Document

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

Document represents a single ActivityStream document or document fragment. Due to the flexibility of ActivityStreams (and JSON-LD), this may be a data structure such as a `map[string]any`, `[]any`, or a primitive type, like a `string`, `float`, `int` or `bool`.

func NewDocument

func NewDocument(value any, options ...DocumentOption) Document

NewDocument creates a new Document object from a JSON-LD map[string]any

func NilDocument

func NilDocument(options ...DocumentOption) Document

NilDocument returns a new, empty Document.

func (Document) At added in v0.5.0

func (document Document) At(index int) Document

func (Document) Blocked added in v0.5.0

func (document Document) Blocked() Document

func (Document) Bool added in v0.4.0

func (document Document) Bool() bool

Bool returns the current object as a floating-point value

func (Document) Clone added in v0.7.0

func (document Document) Clone() Document

func (Document) Context

func (document Document) Context() Document

IMPORTANT: THIS IS NOT THE @context PROPERTY REQUIRED FOR EVERY JSON-LD DOCUMENT https://www.w3.org/TR/activitystreams-vocabulary/#dfn-context

func (Document) Duration

func (document Document) Duration() string

TODO: Implement Durations per https://www.w3.org/TR/activitystreams-vocabulary/#dfn-duration

func (Document) Endpoints added in v0.7.0

func (document Document) Endpoints() Document

https://www.w3.org/TR/activitypub/#endpoints

func (Document) Float added in v0.4.0

func (document Document) Float() float64

Float returns the current object as an integer value

func (Document) Followers added in v0.5.0

func (document Document) Followers() Document

func (Document) Following added in v0.5.0

func (document Document) Following() Document

func (Document) Get

func (document Document) Get(key string) Document

Get returns a sub-property of the current document

func (Document) HTTPHeader added in v0.7.0

func (document Document) HTTPHeader() http.Header

HTTPHeader returns the http.Header object associated with this document

func (Document) Head

func (document Document) Head() Document

Head returns the first object in a slice. For all other document types, it returns the current document.

func (Document) IconOrImage added in v0.4.2

func (document Document) IconOrImage() Image

IconOrImage is a hybrid accessor that returns the "icon" property (if not nil), otherwise it returns the "image" property. This is useful for working with different ActivityPub objects, which may use either property.

func (Document) Inbox added in v0.5.0

func (document Document) Inbox() Document

func (Document) Int added in v0.4.0

func (document Document) Int() int

Int returns the current object as an integer value

func (Document) IsArray

func (document Document) IsArray() bool

func (Document) IsBool

func (document Document) IsBool() bool

func (Document) IsEmptyTail

func (document Document) IsEmptyTail() bool

IsEmpty return TRUE if the current object is empty

func (Document) IsFloat

func (document Document) IsFloat() bool

func (Document) IsInt

func (document Document) IsInt() bool

func (Document) IsInt64

func (document Document) IsInt64() bool

func (Document) IsMap added in v0.4.2

func (document Document) IsMap() bool

func (Document) IsNil

func (document Document) IsNil() bool

func (Document) IsString

func (document Document) IsString() bool

func (Document) IsTypeActor added in v0.7.0

func (document Document) IsTypeActor() bool

IsTypeActor returns TRUE if this document represents any of the predefined actor types

func (Document) Items

func (document Document) Items() Document

Items returns the items collection for this Document. If the document contains an "orderedItems" collection, then it is returned instead.

func (Document) Len added in v0.5.0

func (document Document) Len() int

func (Document) Liked added in v0.5.0

func (document Document) Liked() Document

func (Document) Load added in v0.4.0

func (document Document) Load(options ...any) (Document, error)

Map retrieves a JSON-LD document from a remote server, parses is, and returns a Document object.

func (Document) Map added in v0.4.2

func (document Document) Map() map[string]any

func (Document) MarshalJSON

func (document Document) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaller interface, and provides a custom marshalling into JSON -- essentially just aiming the marshaller at the Document's value.

func (Document) NotNil added in v0.4.2

func (document Document) NotNil() bool

func (Document) NotTypeActor added in v0.7.0

func (document Document) NotTypeActor() bool

NotTypeActor returns TRUE if this document does NOT represent any of the predefined actor types

func (Document) Outbox added in v0.5.0

func (document Document) Outbox() Document

func (Document) PublicKey added in v0.2.2

func (document Document) PublicKey() Document

func (Document) PublicKeyPEM added in v0.2.2

func (document Document) PublicKeyPEM() string

func (Document) Rel

func (document Document) Rel() Document

https://www.w3.org/TR/activitystreams-vocabulary/#dfn-rel Rel is expected to be a string, but this function returns a document because it may contain multiple values (rel:["canonical", "preview"])

func (*Document) SetHTTPHeader added in v0.7.0

func (document *Document) SetHTTPHeader(httpHeader http.Header)

SetHTTPHeader sets the http.Header object associated with this document

func (*Document) SetProperty added in v0.7.0

func (document *Document) SetProperty(property string, value any)

func (*Document) SetValue added in v0.4.2

func (document *Document) SetValue(value any)

func (Document) Slice added in v0.4.2

func (document Document) Slice() []any

Array returns the array value of the current object

func (Document) SliceOfDocuments added in v0.4.2

func (document Document) SliceOfDocuments() sliceof.Object[Document]

SliceOfDocuments transforms the current object into a slice of separate Document objects, one for each value in the current document array.

func (Document) String added in v0.4.0

func (document Document) String() string

String returns the current object as a string value

func (Document) Summary

func (document Document) Summary() string

https://www.w3.org/TR/activitystreams-vocabulary/#dfn-summary TODO: Implement Language Maps

func (Document) Tail

func (document Document) Tail() Document

Tail returns all records after the first in a slice. For all other document types, it returns a nil document.

func (Document) Time added in v0.4.0

func (document Document) Time() time.Time

Time returns the current object as a time value

func (*Document) UnmarshalJSON

func (document *Document) UnmarshalJSON(bytes []byte) error

UnmarshalJSON implements the json.Unmarshaller interface, and provides a custom un-marshalling from JSON -- essentially just aiming the unmashaller at the Document's value

func (Document) Value

func (document Document) Value() any

Value returns the generic data stored in this Document

func (*Document) WithOptions added in v0.4.2

func (document *Document) WithOptions(options ...DocumentOption)

type DocumentOption added in v0.7.0

type DocumentOption func(*Document)

func WithClient added in v0.4.0

func WithClient(client Client) DocumentOption

WithClient option sets the HTTP client that can load remote documents if necessary

func WithHTTPHeader added in v0.7.0

func WithHTTPHeader(httpHeader http.Header) DocumentOption

WithHTTPHeader attaches an HTTP header to the document

type Image added in v0.4.2

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

https://www.w3.org/ns/activitystreams#Image

func NewImage added in v0.4.2

func NewImage(value any) Image

NewImage creates a new Image object from a JSON-LD value (string, map[string]any, or []any)

func (Image) HasDimensions added in v0.4.2

func (image Image) HasDimensions() bool

func (Image) HasHeight added in v0.4.2

func (image Image) HasHeight() bool

func (Image) HasWidth added in v0.4.2

func (image Image) HasWidth() bool

func (Image) Height added in v0.4.2

func (image Image) Height() int

https://www.w3.org/TR/activitystreams-vocabulary/#dfn-height

func (Image) IsNil added in v0.4.2

func (image Image) IsNil() bool

func (Image) MediaType added in v0.4.2

func (image Image) MediaType() string

https://www.w3.org/TR/activitystreams-vocabulary/#dfn-mediatype

func (Image) NotNil added in v0.4.2

func (image Image) NotNil() bool

func (Image) Summary added in v0.4.2

func (image Image) Summary() string

https://www.w3.org/TR/activitystreams-vocabulary/#dfn-summary

func (Image) URL added in v0.4.2

func (image Image) URL() string

https://www.w3.org/TR/activitystreams-vocabulary/#dfn-href

func (Image) Width added in v0.4.2

func (image Image) Width() int

https://www.w3.org/TR/activitystreams-vocabulary/#dfn-width

type Iterator added in v0.4.0

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

Iterator allows transparent iteration over a Collection, OrderedCollection, and their corresponding pages (if present).

func NewIterator added in v0.4.0

func NewIterator(uri Document) (Iterator, error)

NewIterator creates a new Iterator object from a Document or Document URI.

func (*Iterator) Error added in v0.4.0

func (it *Iterator) Error() error

Error returns any error that occurred during the iteration process.

func (*Iterator) HasNext added in v0.4.0

func (it *Iterator) HasNext() bool

HasNext verifies that there is at least one more item remaining in the collection.

func (*Iterator) Next added in v0.4.0

func (it *Iterator) Next() Document

Next returns the next Document in the Collection.

func (*Iterator) TotalItems added in v0.4.0

func (it *Iterator) TotalItems() int

TotalItems returns the total number of items in the collection.

type OrderedCollection

type OrderedCollection struct {
	Context      Context `json:"@context,omitempty"     bson:"@context,omitempty"`
	ID           string  `json:"id,omitempty"           bson:"id,omitempty"`
	Type         string  `json:"type,omitempty"         bson:"type,omitempty"`
	Summary      string  `json:"summary,omitempty"      bson:"summary,omitempty"`      // A natural language summarization of the object encoded as HTML. Multiple language tagged summaries may be provided.
	TotalItems   int     `json:"totalItems,omitempty"   bson:"totalItems,omitempty"`   // A non-negative integer specifying the total number of objects contained by the logical view of the collection. This number might not reflect the actual number of items serialized within the Collection object instance.
	OrderedItems []any   `json:"orderedItems,omitempty" bson:"orderedItems,omitempty"` // Identifies the items contained in a collection. The items might be ordered or unordered.
	Current      string  `json:"current,omitempty"      bson:"current,omitempty"`      // In a paged Collection, indicates the page that contains the most recently updated member items.
	First        string  `json:"first,omitempty"        bson:"first,omitempty"`        // In a paged Collection, indicates the furthest preceding page of items in the collection.
	Last         string  `json:"last,omitempty"         bson:"last,omitempty"`         // In a paged Collection, indicates the furthest proceeding page of the collection.
}

OrderedCollection is a subtype of Collection in which members of the logical collection are assumed to always be strictly ordered. https://www.w3.org/ns/activitystreams#OrderedCollection

func NewOrderedCollection added in v0.3.0

func NewOrderedCollection() OrderedCollection

func (*OrderedCollection) UnmarshalJSON

func (c *OrderedCollection) UnmarshalJSON(data []byte) error

func (*OrderedCollection) UnmarshalMap

func (c *OrderedCollection) UnmarshalMap(data mapof.Any) error

type OrderedCollectionPage

type OrderedCollectionPage struct {
	Context      Context `json:"@context,omitempty"     bson:"context,omitempty"`
	Type         string  `json:"type,omitempty"         bson:"type,omitempty"`
	Summary      string  `json:"summary,omitempty"      bson:"summary,omitempty"`      // A natural language summarization of the object encoded as HTML. Multiple language tagged summaries may be provided.
	TotalItems   int     `json:"totalItems,omitempty"   bson:"totalItems,omitempty"`   // A non-negative integer specifying the total number of objects contained by the logical view of the collection. This number might not reflect the actual number of items serialized within the Collection object instance.
	Current      string  `json:"current,omitempty"      bson:"current,omitempty"`      // In a paged Collection, indicates the page that contains the most recently updated member items.
	First        string  `json:"first,omitempty"        bson:"first,omitempty"`        // In a paged Collection, indicates the furthest preceding page of items in the collection.
	Last         string  `json:"last,omitempty"         bson:"last,omitempty"`         // In a paged Collection, indicates the furthest proceeding page of the collection.
	StartIndex   int     `json:"startIndex,omitempty"   bson:"startIndex,omitempty"`   // A non-negative integer value identifying the relative position within the logical view of a strictly ordered collection.
	PartOf       string  `json:"partOf,omitempty"       bson:"partOf,omitempty"`       // dentifies the Collection to which a CollectionPage objects items belong.
	Prev         string  `json:"prev,omitempty"         bson:"prev,omitempty"`         // In a paged Collection, identifies the previous page of items.
	Next         string  `json:"next,omitempty"         bson:"next,omitempty"`         // In a paged Collection, indicates the next page of items.
	OrderedItems []any   `json:"orderedItems,omitempty" bson:"orderedItems,omitempty"` // Identifies the items contained in a collection. The items might be ordered or unordered.
}

OrderedCollectionPage is used to represent ordered subsets of items from an OrderedCollection. Refer to the Activity Streams 2.0 Core for a complete description of the OrderedCollectionPage object. https://www.w3.org/ns/activitystreams#OrderedCollectionPage

func NewOrderedCollectionPage added in v0.3.0

func NewOrderedCollectionPage() OrderedCollectionPage

func (*OrderedCollectionPage) UnmarshalJSON

func (c *OrderedCollectionPage) UnmarshalJSON(data []byte) error

func (*OrderedCollectionPage) UnmarshalMap

func (c *OrderedCollectionPage) UnmarshalMap(data mapof.Any) error

Jump to

Keyboard shortcuts

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