87 lines
4.4 KiB
Go
87 lines
4.4 KiB
Go
|
// Package pana can be used to process [ActivityStreams] messages.
|
||
|
|
//
|
||
|
|
// This library is meant to help with implementing fediverse ([ActivityPub])
|
||
|
|
// clients and servers.
|
||
|
|
//
|
||
|
|
// # Usage
|
||
|
|
//
|
||
|
|
// An application starts with creating a [Processor] using [NewProcessor]. This
|
||
|
|
// processor should exist for the lifetime of the application, and not a single
|
||
|
|
// request.
|
||
|
|
//
|
||
|
|
// Incoming messages can then be processed by calling [Processor.Unmarshal].
|
||
|
|
// This will return an [Activity] that you can inspect and drill into.
|
||
|
|
//
|
||
|
|
// Call [Activity.GetType] to figure out what type of activity it is. With that
|
||
|
|
// information you can then cast the activity to a more specific type which will
|
||
|
|
// add new getters and setters for the properties that are set on that activity.
|
||
|
|
// You can use [Properties] to get a set of all properties set on the activity.
|
||
|
|
// This lets you handle any property you're interested in.
|
||
|
|
//
|
||
|
|
// If an activity has an [Object], you can do the same thing. Use
|
||
|
|
// [Activity.GetObject] to get the object. An object may be a reference, or a
|
||
|
|
// full object. You can check this with [Object.IsReference]. Once you have a
|
||
|
|
// full object, you can use [Object.GetType] to determine the type and cast it
|
||
|
|
// to a more specific type. And you can use [Properties] to determine the
|
||
|
|
// properties set on the object.
|
||
|
|
//
|
||
|
|
// Once you've created an [Object] you wrap it in an [Activity] and call
|
||
|
|
// [Processor.Marshal]. You can then exchange the resulting JSON using the
|
||
|
|
// client-to-server or server-to-server APIs.
|
||
|
|
//
|
||
|
|
// If you're going to store ActivityStreams messages, ensure you always store
|
||
|
|
// the original you received. Should an implementation bug in Unmarshal result
|
||
|
|
// in a problem, you can then always reprocess messages after that's been fixed.
|
||
|
|
// But if you store a potentially incorrectly unmarshalled document you may not
|
||
|
|
// be able to return to its original form even if you retain the context.
|
||
|
|
//
|
||
|
|
// # JSON-LD
|
||
|
|
//
|
||
|
|
// ActivityStreams uses JSON-LD for its JSON serialisatoin format. Pana doesn't
|
||
|
|
// hide this from you, but aims to provide an API that makes working with this
|
||
|
|
// simple enough so that you don't have to think about it.
|
||
|
|
//
|
||
|
|
// Pana's Unmarshal converts a document to JSON-LD Expanded Document Form. The
|
||
|
|
// Marshal method does the opposite, converting to JSON-LD Compacted Document
|
||
|
|
// Form.
|
||
|
|
//
|
||
|
|
// In JSON-LD all properties, with the exception of 'id' / '@id', are arrays.
|
||
|
|
// But if an array only has a single etnry it's typically reduced to its member.
|
||
|
|
// This distinction is removed in expanded document form, but it makes the
|
||
|
|
// resulting [Object] a bit verbose to handle.
|
||
|
|
//
|
||
|
|
// # API
|
||
|
|
//
|
||
|
|
// The API Pana exposes is meant to do the right thing for you in 99.9% of
|
||
|
|
// cases. Its API is based on what properties are used in practice across the
|
||
|
|
// fediverse, and what their values are. This is a more restrictive subset of
|
||
|
|
// what the ActivityStreams specification allows for. Pana does this on purpose
|
||
|
|
// to guide you towards maximal interoperability with other, potentially JSON-LD
|
||
|
|
// unaware, implementations.
|
||
|
|
//
|
||
|
|
// For any proprety, you'll either have:
|
||
|
|
// - GetXXX and SetXXX for single-valued properties. These will accept and
|
||
|
|
// return strings or [encoding/json.RawMessage].
|
||
|
|
// - GetXXX and AddXXX for multi-valued properties. Get will return an
|
||
|
|
// [iter.Seq], and Add will be variadic. Add appends so can be called
|
||
|
|
// multiple times too.
|
||
|
|
//
|
||
|
|
// Most value properties return [encoding/json.RawMessage]. You can look at the
|
||
|
|
// JSON-LD context definition to determine what the type of the value should be.
|
||
|
|
// This will also be part of the vocabulary documentation for the property
|
||
|
|
// you're retrieving. However, remember that this is not enforced, so even if a
|
||
|
|
// property is defined as a number it can hold a boolean.
|
||
|
|
//
|
||
|
|
// All types in Pana are a [sourcery.dny.nu/longdistance.Node]. This struct type
|
||
|
|
// has exported fields for every JSON-LD keyword, as well as a catch-all
|
||
|
|
// Properties field for all other properties. You can directly manipulate any of
|
||
|
|
// these, but at that point you're responsible for ensuring you create valid
|
||
|
|
// JSON-LD nodes that will compact to a representation non-JSON-LD aware
|
||
|
|
// processors will understand. In order to Get, Add or Set properties you need
|
||
|
|
// to use the IRI a property maps to. This is part of what the JSON-LD context
|
||
|
|
// defines. The [sourcery.dny.nu/pana/vocab] packages provide the necessary consts.
|
||
|
|
//
|
||
|
|
// [ActivityStreams]: https://www.w3.org/TR/activitystreams-core/
|
||
|
|
// [ActivityPub]: https://www.w3.org/TR/activitypub/
|
||
|
|
package pana
|