diff --git a/src/activitypub/actors.go b/src/activitypub/actors.go index 52ad013..3982ebb 100644 --- a/src/activitypub/actors.go +++ b/src/activitypub/actors.go @@ -17,7 +17,10 @@ var validActorTypes = [...]ActivityVocabularyType{ ServiceType, } -// Endpoints +// Endpoints a json object which maps additional (typically server/domain-wide) +// endpoints which may be useful either for this actor or someone referencing this actor. +// This mapping may be nested inside the actor document as the value or may be a link to +// a JSON-LD document with these properties. type Endpoints struct { // Upload endpoint URI for this user for binary data. UploadMedia ObjectOrLink `jsonld:"uploadMedia,omitempty"` @@ -41,7 +44,10 @@ type Endpoints struct { SharedInbox ObjectOrLink `jsonld:"sharedInbox,omitempty"` } -// Actor types are apObject types that are capable of performing activities. +// Actor is generally one of the ActivityStreams Actor Types, but they don't have to be. +// For example, a Profile object might be used as an actor, or a type from an ActivityStreams extension. +// Actors are retrieved like any other Object in ActivityPub. +// Like other ActivityStreams objects, actors have an id, which is a URI. type Actor struct { *apObject // A reference to an [ActivityStreams] OrderedCollection comprised of all the messages received by the actor; diff --git a/src/activitypub/collections.go b/src/activitypub/collections.go index 04ced33..794df37 100644 --- a/src/activitypub/collections.go +++ b/src/activitypub/collections.go @@ -2,10 +2,10 @@ package activitypub var validCollectionTypes = [...]ActivityVocabularyType{CollectionType, OrderedCollectionType} -// Page +// Page represents a Web Page. type Page ObjectOrLink -// Collection +// Collection is a subtype of Object that represents ordered or unordered sets of Object or Link instances. type Collection struct { *apObject // A non-negative integer specifying the total number of objects contained by the logical view of the collection. @@ -15,7 +15,8 @@ type Collection struct { Items ItemCollection `jsonld:"items,omitempty"` } -// OrderedCollection +// OrderedCollection is a subtype of Collection in which members of the logical +// collection are assumed to always be strictly ordered. type OrderedCollection struct { *apObject // A non-negative integer specifying the total number of objects contained by the logical view of the collection. @@ -25,7 +26,9 @@ type OrderedCollection struct { OrderedItems ItemCollection `jsonld:"orderedItems,omitempty"` } -// CollectionPage +// CollectionPage is a Collection that contains a large number of items and when it becomes impractical +// for an implementation to serialize every item contained by a Collection using the items (or orderedItems) +// property alone. In such cases, the items within a Collection can be divided into distinct subsets or "pages". type CollectionPage struct { PartOf *Collection // In a paged Collection, indicates the page that contains the most recently updated member items. @@ -40,7 +43,10 @@ type CollectionPage struct { Prev Page `jsonld:"prev,omitempty"` } -// OrderedCollectionPage +// OrderedCollectionPage type extends from both CollectionPage and OrderedCollection. +// In addition to the properties inherited from each of those, the OrderedCollectionPage +// may contain an additional startIndex property whose value indicates the relative index position +// of the first item contained by the page within the OrderedCollection to which the page belongs. type OrderedCollectionPage struct { PartOf *OrderedCollection // In a paged Collection, indicates the page that contains the most recently updated member items. diff --git a/src/activitypub/following.go b/src/activitypub/following.go index 2e40c1c..623d7da 100644 --- a/src/activitypub/following.go +++ b/src/activitypub/following.go @@ -1,9 +1,11 @@ package activitypub type ( - // FollowingCollection + // FollowingCollection is a list of everybody that the actor has followed, added as a side effect. + // The following collection MUST be either an OrderedCollection or a Collection and MAY + // be filtered on privileges of an authenticated user or as appropriate when no authentication is given. FollowingCollection Following - // Following + // Following is a type alias for a simple Collection Following Collection ) diff --git a/src/activitypub/inbox.go b/src/activitypub/inbox.go index 6683222..dd71167 100644 --- a/src/activitypub/inbox.go +++ b/src/activitypub/inbox.go @@ -1,9 +1,13 @@ package activitypub type ( - // InboxStream + // InboxStream contains all activities received by the actor. + // The server SHOULD filter content according to the requester's permission. + // In general, the owner of an inbox is likely to be able to access all of their inbox contents. + // Depending on access control, some other content may be public, whereas other content may + // require authentication for non-owner users, if they can access the inbox at all. InboxStream Inbox - // Inbox + // Inbox is a type alias for an Ordered Collection Inbox OrderedCollection ) diff --git a/src/activitypub/liked.go b/src/activitypub/liked.go index 306103c..9a90f0b 100644 --- a/src/activitypub/liked.go +++ b/src/activitypub/liked.go @@ -1,9 +1,12 @@ package activitypub type ( - // LikedCollection + // LikedCollection is a list of every object from all of the actor's Like activities, + // added as a side effect. The liked collection MUST be either an OrderedCollection or + // a Collection and MAY be filtered on privileges of an authenticated user or as + // appropriate when no authentication is given. LikedCollection Liked - // Liked + // Liked is a type alias for an Ordered Collection Liked OrderedCollection ) diff --git a/src/activitypub/likes.go b/src/activitypub/likes.go index 947f319..5fb13f4 100644 --- a/src/activitypub/likes.go +++ b/src/activitypub/likes.go @@ -1,9 +1,12 @@ package activitypub type ( - // LikesCollection + // LikesCollection is a list of all Like activities with this object as the object property, + // added as a side effect. The likes collection MUST be either an OrderedCollection or a Collection + // and MAY be filtered on privileges of an authenticated user or as appropriate when + // no authentication is given. LikesCollection Likes - // Likes + // Likes is a type alias for an Ordered Collection Likes OrderedCollection ) diff --git a/src/activitypub/link.go b/src/activitypub/link.go index 175eb80..41e0745 100644 --- a/src/activitypub/link.go +++ b/src/activitypub/link.go @@ -40,7 +40,7 @@ type Link struct { HrefLang LangRef `jsonld:"hrefLang,omitempty"` } -// Mention +// Mention is a specialized Link that represents an @mention. type Mention Link // ValidLinkType validates a type against the valid link types diff --git a/src/activitypub/object.go b/src/activitypub/object.go index 06eefdf..705d8fe 100644 --- a/src/activitypub/object.go +++ b/src/activitypub/object.go @@ -5,13 +5,24 @@ import ( "time" ) -// ObjectID +// ObjectID designates an unique global identifier. +// All Objects in [ActivityStreams] should have unique global identifiers. +// ActivityPub extends this requirement; all objects distributed by the ActivityPub protocol MUST +// have unique global identifiers, unless they are intentionally transient +// (short lived activities that are not intended to be able to be looked up, +// such as some kinds of chat messages or game notifications). +// These identifiers must fall into one of the following groups: +// +// 1. Publicly dereferencable URIs, such as HTTPS URIs, with their authority belonging +// to that of their originating server. (Publicly facing content SHOULD use HTTPS URIs). +// 2. An ID explicitly specified as the JSON null object, which implies an anonymous object +// (a part of its parent context) type ObjectID string const ( // ActivityBaseURI the basic URI for the activity streams namespaces ActivityBaseURI URI = URI("https://www.w3.org/ns/activitystreams#") - ObjectType ActivityVocabularyType = "apObject" + ObjectType ActivityVocabularyType = "ActivityPubObject" LinkType ActivityVocabularyType = "Link" ActivityType ActivityVocabularyType = "Activity" IntransitiveActivityType ActivityVocabularyType = "IntransitiveActivity" @@ -19,7 +30,7 @@ const ( CollectionType ActivityVocabularyType = "Collection" OrderedCollectionType ActivityVocabularyType = "OrderedCollection" - // apObject Types + // Activity Pub Object Types ArticleType ActivityVocabularyType = "Article" AudioType ActivityVocabularyType = "Audio" DocumentType ActivityVocabularyType = "Document" @@ -33,7 +44,7 @@ const ( TombstoneType ActivityVocabularyType = "Tombstone" VideoType ActivityVocabularyType = "Video" - // Link Types + // MentionType is a link type for @mentions MentionType ActivityVocabularyType = "Mention" ) @@ -68,33 +79,35 @@ var validObjectTypes = [...]ActivityVocabularyType{ } type ( - // ActivityVocabularyType + // ActivityVocabularyType is the data type for an Activity type object ActivityVocabularyType string - // ActivityObject + // ActivityObject is a subtype of Object that describes some form of action that may happen, + // is currently happening, or has already happened ActivityObject interface{} - // ObjectOrLink + // ObjectOrLink describes an object of any kind. ObjectOrLink interface { IsLink() bool IsObject() bool } - // LinkOrUri + // LinkOrUri is an interface that Object and Link structs implement, and at the same time + // they are kept disjointed LinkOrUri interface{} - // ImageOrLink + // ImageOrLink is an interface that Image and Link structs implement ImageOrLink interface{} - // MimeType + // MimeType is the type for MIME types MimeType string - // LangRef + // LangRef is the type for a language reference, should be ISO 639-1 language specifier. LangRef string - // NaturalLanguageValue + // NaturalLanguageValue is a mapping for multiple language values NaturalLanguageValue map[LangRef]string ) -// IsLink validates if current apObject is a Link +// IsLink validates if current Activity Pub Object is a Link func (o apObject) IsLink() bool { return ValidLinkType(o.Type) } -// IsObject validates if current apObject is an Object +// IsObject validates if current Activity Pub Object is an Object func (o apObject) IsObject() bool { return ValidObjectType(o.Type) } @@ -193,10 +206,11 @@ type apObject struct { Duration time.Duration `jsonld:"duration,omitempty"` } -// ContentType +// ContentType represents the content type for a Source object type ContentType string -// Source +// Source is intended to convey some sort of source from which the content markup was derived, +// as a form of provenance, or to support future editing by clients. type Source struct { Content ContentType MediaType string diff --git a/src/activitypub/outbox.go b/src/activitypub/outbox.go index 392e15d..35a82ab 100644 --- a/src/activitypub/outbox.go +++ b/src/activitypub/outbox.go @@ -1,9 +1,11 @@ package activitypub type ( - // OutboxStream + // OutboxStream contains activities the user has published, + // subject to the ability of the requestor to retrieve the activity (that is, + // the contents of the outbox are filtered by the permissions of the person reading it). OutboxStream Outbox - // Outbox + // Outbox is a type alias for an Ordered Collection Outbox OrderedCollection ) diff --git a/src/activitypub/shares.go b/src/activitypub/shares.go index c39b345..e8d3f6c 100644 --- a/src/activitypub/shares.go +++ b/src/activitypub/shares.go @@ -1,9 +1,12 @@ package activitypub type ( - // SharesCollection + // SharesCollection is a list of all Announce activities with this object as the object property, + // added as a side effect. The shares collection MUST be either an OrderedCollection or a Collection + // and MAY be filtered on privileges of an authenticated user or as appropriate when no authentication + // is given. SharesCollection Shares - // Shares + // Shares is a type alias for an Ordered Collection Shares OrderedCollection ) diff --git a/src/activitypub/uri.go b/src/activitypub/uri.go index 3f4357a..ad0c388 100644 --- a/src/activitypub/uri.go +++ b/src/activitypub/uri.go @@ -1,9 +1,9 @@ package activitypub type ( - // IRI + // IRI is a Internationalized Resource Identifiers (IRIs) RFC3987 IRI URI - // URI + // URI is a Uniform Resource Identifier (URI) RFC3986 URI string ) diff --git a/src/jsonld/context.go b/src/jsonld/context.go index fbb117a..7ed6eed 100644 --- a/src/jsonld/context.go +++ b/src/jsonld/context.go @@ -17,6 +17,7 @@ type Context struct { Language activitypub.NaturalLanguageValue `jsonld:"@language,omitempty,collapsible"` } +// Collapsible is an interface used by the JSON-LD marshaller to collapse a struct to one single value type Collapsible interface { Collapse() []byte } @@ -26,6 +27,7 @@ func (c *Context) Ref() Ref { return Ref(c.URL) } +// Collapse returns the plain text collapsed value of the current Context object func (c *Context) Collapse() []byte { return []byte(c.URL) } diff --git a/tests/integration_test.go b/tests/integration_test.go index 1cc3ea8..de05ad9 100644 --- a/tests/integration_test.go +++ b/tests/integration_test.go @@ -42,9 +42,9 @@ func TestCreateActivityHTTPSerialization(t *testing.T) { obj := activitypub.AcceptNew(id, nil) obj.Name["en"] = "Accept New" - baseUri := string(activitypub.ActivityBaseURI) + baseURI := string(activitypub.ActivityBaseURI) ctx := jsonld.Context{ - URL: jsonld.Ref(baseUri + string(obj.Type)), + URL: jsonld.Ref(baseURI + string(obj.Type)), } data, err := jsonld.Marshal(obj, &ctx) if err != nil {