Update all the READMEs
このコミットが含まれているのは:
Cory Slep
コミット
e910e86bd6
48
README.md
48
README.md
@ -2,12 +2,14 @@
|
||||
|
||||
`go get github.com/go-fed/activity`
|
||||
|
||||
This repository supports `vgo` and is remotely verifiable.
|
||||
|
||||
This repository contains three libraries for use in your golang applications:
|
||||
|
||||
* An ActivityStreams Vocabulary library
|
||||
* A convenience library for the ActivityStreams Vocabulary
|
||||
* ActivityPub Social API (Client-to-Server) and Federation Protocol
|
||||
(Server-to-Server).
|
||||
* `vocab`: An ActivityStreams Vocabulary library
|
||||
* `streams`: A convenience library for the ActivityStreams Vocabulary
|
||||
* `pub`: ActivityPub SocialAPI (Client-to-Server) and FederateAPI
|
||||
(Server-to-Server)
|
||||
|
||||
This library is biased. It forgoes understanding JSON-LD in exchange for static
|
||||
typing. It provides a large amount of default behavior to let Social,
|
||||
@ -15,33 +17,43 @@ Federated, or both kinds of ActivityPub applications just work.
|
||||
|
||||
## Status
|
||||
|
||||
There is no stable version of this library (yet).
|
||||
Version 0.1.0 of this library is ready for use.
|
||||
|
||||
See each subdirectory for its own README for further elaboration.
|
||||
There is not an implementation report available... yet!
|
||||
|
||||
### Core ActivityPub Libraries
|
||||
See each subdirectory for its own README for further elaboration. The
|
||||
recommended reading order is `vocab`, `streams`, and then `pub`. Others are
|
||||
optional.
|
||||
|
||||
* `vocab` - ActivityStreams Vocabulary: Functional and tested
|
||||
* `streams` - ActivityStreams Convenience Library: Functional and tested
|
||||
* `pub` - ActivityPub: Under development and testing
|
||||
## How well tested are these libraries?
|
||||
|
||||
### Supplemental Libraries
|
||||
I took great care to add numerous tests using examples directly from
|
||||
specifications, official test repositories, and my own end-to-end tests.
|
||||
|
||||
## Who is using this library currently?
|
||||
|
||||
No one. Please let me know if you are using it!
|
||||
|
||||
## How do I use these libraries?
|
||||
|
||||
Please see each subdirectory for its own README for further elaboration. The
|
||||
recommended reading order is `vocab`, `streams`, and then `pub`. Others are
|
||||
optional.
|
||||
|
||||
Passing familiarity with ActivityStreams and ActivityPub is recommended.
|
||||
|
||||
## Other Libraries
|
||||
|
||||
* `tools` - Code generation wizardry and ActivityPub-spec-as-data.
|
||||
* `deliverer` - Provides an asynchronous `Deliverer` for use with the `pub` lib
|
||||
|
||||
## How To Use This Library
|
||||
|
||||
This section will be fleshed out once the library is approaching its first
|
||||
stable release.
|
||||
|
||||
## FAQ
|
||||
|
||||
*Why does compilation take so long?*
|
||||
|
||||
The `vocab` and `streams` packages are code generated on order of hundreds of
|
||||
thousands to a million lines long. Use `go install` or `go build -i` to cache
|
||||
the build artifacts and do incremental builds.
|
||||
thousands to a million lines long. If using Go 1.9 or before, use `go install`
|
||||
or `go build -i` to cache the build artifacts and do incremental builds.
|
||||
|
||||
## Useful References
|
||||
|
||||
|
||||
@ -1,8 +1,10 @@
|
||||
# deliverer
|
||||
|
||||
This library is completely optional, provided only for convenience.
|
||||
|
||||
An extra utility that provides a simple mechanism to asynchronously deliver
|
||||
federated messages from a `Pubber` available from the
|
||||
`github.com/go-fed/activity/pub` library.
|
||||
federated messages from a `pub.Pubber` available from the `go-fed/activity/pub`
|
||||
library.
|
||||
|
||||
It implements the `pub.Deliverer` interface.
|
||||
|
||||
|
||||
186
pub/README.md
ノーマルファイル
186
pub/README.md
ノーマルファイル
@ -0,0 +1,186 @@
|
||||
# pub
|
||||
|
||||
Implements both the SocialAPI and FederateAPI in the ActivityPub specification.
|
||||
|
||||
## Disclaimer
|
||||
|
||||
This library is designed with flexibility in mind. The cost of doing so is that
|
||||
writing an ActivityPub application requires a lot of careful considerations that
|
||||
are not trivial. ActivityPub is an Application transport layer that is also tied
|
||||
to a specific data model, making retrofits nontrivial as well.
|
||||
|
||||
## How To Use
|
||||
|
||||
There are two ActivityPub APIs: the SocialAPI between a user and your
|
||||
ActivityPub server, and the FederateAPI between your ActivityPub server and
|
||||
another server peer. This library lets you choose one or both.
|
||||
|
||||
*Lightning intro to ActivityPub: ActivityPub uses ActivityStreams as data. This
|
||||
lives in `go-fed/activity/vocab`. ActivityPub has a concept of `actors` who can
|
||||
send, receive, and read their messages. When sending and receiving messages from
|
||||
a client (such as on their phone) to an ActivityPub server, it is via the
|
||||
SocialAPI. When it is between two ActivityPub servers, it is via the
|
||||
FederateAPI.*
|
||||
|
||||
Next, there are two kinds of ActivityPub requests to handle:
|
||||
|
||||
1. Requests that `GET` or `POST` to stuff owned by an `actor` like their `inbox`
|
||||
or `outbox`.
|
||||
1. Requests that `GET` ActivityStream objects hosted on your server.
|
||||
|
||||
The first is the most complex, and requires the creation of a `Pubber`. It is
|
||||
created depending on which APIs are to be supported:
|
||||
|
||||
```
|
||||
// Only support SocialAPI
|
||||
s := pub.NewSocialPubber(...)
|
||||
// Only support FederateAPI
|
||||
f := pub.NewFederatingPubber(...)
|
||||
// Support both APIs
|
||||
sf := pub.NewPubber(...)
|
||||
```
|
||||
|
||||
Note that *only* the creation of the `Pubber` is affected by the decision of
|
||||
which API to support. Once created, the `Pubber` should be used in the same
|
||||
manner regardless of the API it is supporting. This allows your application
|
||||
to easily adopt one API first and migrate to both later by simply changing how
|
||||
the `Pubber` is created.
|
||||
|
||||
To use the `Pubber`, call its methods in the HTTP handlers responsible for an
|
||||
`actor`'s `inbox` and `outbox`:
|
||||
|
||||
```
|
||||
// Given:
|
||||
// var myPubber pub.Pubber
|
||||
var outboxHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request) {
|
||||
c := context.Background()
|
||||
// Populate c with application specific information
|
||||
if handled, err := myPubber.PostOutbox(c, w, r); err != nil {
|
||||
// Write to w
|
||||
} else if handled {
|
||||
return
|
||||
}
|
||||
if handled, err := myPubber.GetOutbox(c, w, r); err != nil {
|
||||
// Write to w
|
||||
} else if handled {
|
||||
return
|
||||
}
|
||||
// Handle non-ActivityPub request, such as responding with an HTML
|
||||
// representation with correct view permissions.
|
||||
}
|
||||
var inboxHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request) {
|
||||
c := context.Background()
|
||||
// Populate c with application specific information
|
||||
if handled, err := myPubber.PostIntox(c, w, r); err != nil {
|
||||
// Write to w
|
||||
} else if handled {
|
||||
return
|
||||
}
|
||||
if handled, err := myPubber.GetInbox(c, w, r); err != nil {
|
||||
// Write to w
|
||||
} else if handled {
|
||||
return
|
||||
}
|
||||
// Handle non-ActivityPub request, such as responding with an HTML
|
||||
// representation with correct view permissions.
|
||||
}
|
||||
```
|
||||
|
||||
Finally, to handle the second kind of request, use the `HandlerFunc` within HTTP
|
||||
handler functions in a similar way. There are two ways to create `HandlerFunc`,
|
||||
which depend on decisions we will address later:
|
||||
|
||||
```
|
||||
asHandler := pub.ServeActivityPubObject(...)
|
||||
var activityStreamHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request) {
|
||||
c := context.Background()
|
||||
// Populate c with application specific information
|
||||
if handled, err := asHandler(c, w, r); err != nil {
|
||||
// Write to w
|
||||
} else if handled {
|
||||
return
|
||||
}
|
||||
// Handle non-ActivityPub request, such as responding with an HTML
|
||||
// representation with correct view permissions.
|
||||
}
|
||||
```
|
||||
|
||||
That's all that's required.
|
||||
|
||||
## How To Create
|
||||
|
||||
You may have noticed that using the library is deceptively straightforward. This
|
||||
is because *creating* the `Pubber` and `HandlerFunc` types is not trivial and
|
||||
requires forethought.
|
||||
|
||||
There are a lot of interfaces that must be satisfied in order to have a complete
|
||||
working ActivityPub server.
|
||||
|
||||
Note that `context.Context` is passed everywhere possible, to allow your
|
||||
implementation to keep a request-specific context throughout the lifecycle of
|
||||
an ActivityPub request.
|
||||
|
||||
### Application Interface
|
||||
|
||||
Regardless of which of the SocialAPI and FederateAPI chosen, the `Application`
|
||||
interface contains the set of core methods fundamental to the functionality of
|
||||
this library. It contains a lot of the storage fetching and writing, all of
|
||||
which is keyed by `*url.URL`. To protect against race conditions, this library
|
||||
will inform whether it is fetching data to read-only or fetching or read-or-
|
||||
write.
|
||||
|
||||
Note that under some conditions, ActivityPub verifies the peer's request. It
|
||||
does so using HTTP Signatures. However, this requires knowing the other party's
|
||||
public key, and fetching this remotely is do-able. However, this library assumes
|
||||
this server already has it locally; it is up to implementations to remotely
|
||||
fetch it if needed at this time.
|
||||
|
||||
### SocialAPI and FederateAPI Interfaces
|
||||
|
||||
These interfaces capture additional behaviors required by the SocialAPI and the
|
||||
FederateAPI.
|
||||
|
||||
The SocialAPI can additionally provide a mechanism for client authentication and
|
||||
authorization using frameworks like Oauth 2.0. Such frameworks are not natively
|
||||
supported in this library and must be supplied.
|
||||
|
||||
### Callbacker Interface
|
||||
|
||||
One of these is needed per ActivityPub API supported. For example, if both the
|
||||
SocialAPI and FederateAPI are supported, then two of these are needed.
|
||||
|
||||
Upon receiving one of these activities from a `POST` to the inbox or outbox, the
|
||||
correct callbacker will be called to handle either a SocialAPI activity or a
|
||||
FederateAPI activity.
|
||||
|
||||
This is where the bulk of implementation-specific logic is expected to reside.
|
||||
|
||||
Do note that for some of these activities, default actions will already occur.
|
||||
For example, if receiving an `Accept` in response to a sent `Follow`, this
|
||||
library automatically handles adding the correct actor into the correct
|
||||
`following` collection. This means a lot of the social and federate
|
||||
functionality is provided out of the box.
|
||||
|
||||
### Deliverer Interface
|
||||
|
||||
This is an optional interface. Since this library needs to send HTTP requests,
|
||||
it would be unwise for it to provide no way of allowing implementations to
|
||||
rate limit, persist across downtime, back off, etc. This interface is satisfied
|
||||
by the `go-fed/activity/deliverer` package which has an implementation that can
|
||||
remember to send requests across downtime.
|
||||
|
||||
If an implementation does not care to have this level of control, a synchronous
|
||||
implementation is very straightforward to make.
|
||||
|
||||
### Other Interfaces
|
||||
|
||||
Other interfaces such as `Typer` and `PubObject` are meant to limit modification
|
||||
scope or require minimal ActivityStream compatibility to be used by this
|
||||
library. As long as the `go-fed/activity/vocab` or `go-fed/activity/streams`
|
||||
packages are being used, these interfaces will be natively supported.
|
||||
|
||||
## Other Considerations
|
||||
|
||||
This library does not have an implementation report generated... yet! Once it is
|
||||
available, it will be linked here. Furthermore, the test server will also be an
|
||||
excellent tutorial resource.
|
||||
@ -1,30 +1,13 @@
|
||||
# streams
|
||||
|
||||
The `streams` package provides static types for Core and Extended types to the
|
||||
[ActivityStream Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary).
|
||||
The library is battle-tested against the `vocabulary-ex*-jsonld.json`
|
||||
[test documents](https://github.com/w3c-social/activitystreams-test-documents)
|
||||
in addition to usual unit tests.
|
||||
Please read the `README.md` in the `go-fed/activity/vocab` package first. This
|
||||
library is a convenience layer on top of the `go-fed/activity/vocab` library, so
|
||||
this README builds off of that one.
|
||||
|
||||
Its mission is simple: Provide meaningful static types for the ActivityStream
|
||||
Vocabulary in golang. This library is a convenience layer on top of the
|
||||
`activity/vocab` library, which gives unfettered access to the data types.
|
||||
|
||||
This library is entirely code-generated by the `activity/tools/streams/gen`
|
||||
library and `activity/tools/streams` tool. Run `go generate` to refresh the
|
||||
library, which requires `$GOPATH/bin` to be on your `$PATH`.
|
||||
|
||||
**Consider using this library and falling back to `activity/vocab` only when
|
||||
necessary.**
|
||||
|
||||
## This library's API is huge!
|
||||
|
||||
**The W3C does not require client applications to support all of these
|
||||
use cases.** The W3C only requires that *"all implementations must at least be
|
||||
capable of serializing and deserializing the Extended properties in accordance
|
||||
with the Activity Streams 2.0 Core Syntax,"* which what this library and the
|
||||
`activity/vocab` libraries do for clients. This library's API is large to
|
||||
permit clients to use as much or as little as desired.
|
||||
This library is entirely code-generated by the
|
||||
`go-fed/activity/tools/streams/gen` library and `go-fed/activity/tools/streams`
|
||||
tool. Run `go generate` to refresh the library, which requires `$GOPATH/bin` to
|
||||
be on your `$PATH`.
|
||||
|
||||
## What it does
|
||||
|
||||
@ -147,53 +130,9 @@ The only caveat is that clients must set `"@context"` manually at this time.
|
||||
|
||||
## What it doesn't do
|
||||
|
||||
This library does not use the `reflect` package at all. It prioritizes
|
||||
minimizing dependencies and speed over binary size.
|
||||
|
||||
The ActivityStream specification is built on top of JSON-LD, which uses JSON.
|
||||
This library should be used with `encoding/json` in order to transform a raw
|
||||
string into a `map[string]interface{}` to static, semantically meaningful
|
||||
types.
|
||||
|
||||
This library does not set the `"@context"` property required when sending
|
||||
serialized data. Clients are in charge of setting it to
|
||||
`"https://www.w3.org/ns/activitystreams"`.
|
||||
|
||||
This implementation is heavily opinionated against understanding JSON-LD due to
|
||||
its sacrifice of semantic meaning, significant increase of complexity, even
|
||||
weaker typing, and increased exposure to partially-understood messages. These
|
||||
costs earn a degree of flexibility that is not needed for the ActivityStream
|
||||
Vocabulary.
|
||||
|
||||
This library is *not* a [JSON-LD](https://json-ld.org/) parser, and by design
|
||||
does not implement any further understanding of JSON-LD that may be outlined in
|
||||
the [W3C's JSON-LD](https://www.w3.org/TR/json-ld/) specification. Furthermore,
|
||||
it does *not* implement any of the JSON-LD
|
||||
[processing algorithms](https://www.w3.org/TR/json-ld-api/). If this
|
||||
functionality is strictly needed, or this library is not suitable, please see
|
||||
[piprate/json-gold/ld](https://github.com/piprate/json-gold) and its
|
||||
[documentation](https://godoc.org/github.com/piprate/json-gold/ld).
|
||||
Please see the same section in the `go-fed/activity/vocab` package.
|
||||
|
||||
## Other considerations
|
||||
|
||||
This library is entirely code-generated. Determined clients can add their own
|
||||
custom extended types to the `activity/tools/defs` library and generate a
|
||||
useful type. However, this process is purposefully painful to force clients to
|
||||
seriously consider whether they need their own
|
||||
[custom type](https://xkcd.com/927).
|
||||
|
||||
The code-generation aspect also allows the specification to be translated into
|
||||
declarative data, which permits certain kinds of validation and verification.
|
||||
This has led to giving the following feedback to the specification:
|
||||
|
||||
* [Inconsistencies between property domains and type properties](https://github.com/w3c/activitystreams/issues/436)
|
||||
* [Please clarify "items" and "orderedItems" properties](https://github.com/w3c/activitystreams/issues/437)
|
||||
* [Expectations around IRI resolution](https://github.com/w3c/activitystreams/issues/438)
|
||||
* [Examples Contradict Specification](https://github.com/w3c/activitystreams/issues/439)
|
||||
* [Tombstone "formerType" Property Range Needs Clarification](https://github.com/w3c/activitystreams/issues/440)
|
||||
* [Example 60 Missing `@context` Property](https://github.com/w3c/activitystreams/issues/441)
|
||||
* [Stylistic Consistency For Non-Functional Single-Value JSON in Examples](https://github.com/w3c/activitystreams/issues/442)
|
||||
* [Spec does not clarify non-functional natural language values when mapped](https://github.com/w3c/activitystreams/issues/443)
|
||||
* [Example 102: `url` property missing `type: "Link"`](https://github.com/w3c/activitystreams/issues/444)
|
||||
* [Example 146: Missing `Z` in startTime](https://github.com/w3c/activitystreams/issues/445)
|
||||
* [Example 150: Latitude/Longitude are not xsd:float](https://github.com/w3c/activitystreams/issues/446)
|
||||
This library is entirely code-generated. Please see the same section in the
|
||||
`go-fed/activity/vocab` package for more details.
|
||||
|
||||
@ -2,10 +2,16 @@
|
||||
|
||||
Contains the code-generation logic for aspects of this library:
|
||||
|
||||
* `defs` contains common utilities and definitions for the Vocabulary.
|
||||
* `vocab` is the tool used to generate the Vocabulary code.
|
||||
* `vocab/gen` is the library that does the heavy lifting of generating the
|
||||
Vocabulary code.
|
||||
* `stream` is the tool used to generate the ActivityStream convenience code.
|
||||
* `stream/gen` is the library that does the heavy lifting of generating the
|
||||
ActivityStream convenience code.
|
||||
* `go-fed/activity/tools/defs` contains common utilities and definitions for the
|
||||
Vocabulary.
|
||||
* `go-fed/activity/tools/vocab` is the tool used to generate the Vocabulary
|
||||
code.
|
||||
* `go-fed/activity/tools/vocab/gen` is the library that does the heavy lifting
|
||||
of generating the Vocabulary code.
|
||||
* `go-fed/activity/tools/stream` is the tool used to generate the ActivityStream
|
||||
convenience code.
|
||||
* `go-fed/activity/toolsstream/gen` is the library that does the heavy lifting
|
||||
of generating the ActivityStream convenience code.
|
||||
|
||||
Before you continue further; a fair warning. This code is in severe need of
|
||||
tender love and care.
|
||||
|
||||
@ -1,9 +1,10 @@
|
||||
# gen
|
||||
|
||||
This library is used to generate the `vocab` library implementation. Changes to
|
||||
this will fundamentally change the implementation of the `vocab` library. If
|
||||
custom ActivityStream types are required, no changes to this are required.
|
||||
Instead, the `tools/gen/vocab` library will need edits.
|
||||
This library is used to generate the `go-fed/activity/vocab` library
|
||||
implementation. Changes to this will fundamentally change the implementation of
|
||||
the `vocab` library. If custom ActivityStream types are required, no changes to
|
||||
this are required. Instead, the `go-fed/activity/tools/defs` library will need
|
||||
edits.
|
||||
|
||||
Creating a static type implementation from the specification is not
|
||||
straightforward due to the following considerations that stem from its roots in
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
The `vocab` package provides static types for Core and Extended types to the
|
||||
[ActivityStream Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary).
|
||||
The library is battle-tested against all 159 examples in the Vocabulary
|
||||
specification linked above in addition to usual unit tests.
|
||||
specification linked above in addition to unit tests.
|
||||
|
||||
Its mission is simple: Provide meaningful static types for the ActivityStream
|
||||
Vocabulary in golang.
|
||||
@ -12,8 +12,6 @@ This library is entirely code-generated by the `tools/vocab/gen` library
|
||||
and `tools/vocab` tool. Run `go generate` to refresh the library, which
|
||||
which requires `$GOPATH/bin` to be on your `$PATH`.
|
||||
|
||||
**Please consider using the `activity/streams` library instead.**
|
||||
|
||||
## This library's API is huge!
|
||||
|
||||
**The W3C does not require client applications to support all of these
|
||||
@ -57,7 +55,21 @@ conditions. Consider:
|
||||
* The `published` time conforms to RFC3339 with the exception that seconds may
|
||||
be omitted
|
||||
|
||||
All of these considerations are presented much more nicely by this library:
|
||||
Therefore, trying to statically determine this with typical JSON tagging does
|
||||
not work:
|
||||
|
||||
```
|
||||
type NaiveActivity struct {
|
||||
type string `json:"Type"` // Not OK, cannot handle array of strings
|
||||
name []string `json:"Name"` // Not OK, cannot handle single values
|
||||
// ...
|
||||
published time.Time `...` // Not OK, cannot handle when seconds are omitted
|
||||
}
|
||||
```
|
||||
|
||||
This is the motivation for this library.
|
||||
|
||||
All of these considerations are presented as:
|
||||
|
||||
```
|
||||
type Note struct { ... }
|
||||
@ -69,18 +81,7 @@ func (n *Note) GetNameString(index int) string { ... }
|
||||
```
|
||||
|
||||
Note that the resulting API and property type possibilities is *large*. This is
|
||||
a natural consequence of the specification being built on top of JSON-LD. It is
|
||||
recommended for applications to use the `activity/streams` convenience library
|
||||
instead, or create their own convenience types:
|
||||
|
||||
```
|
||||
type MyNote struct {
|
||||
note *vocab.Note
|
||||
}
|
||||
|
||||
func (n *Note) Name() (string, bool) { /* Use note.NameLen, etc. */ }
|
||||
// And so on
|
||||
```
|
||||
a natural consequence of the specification being built on top of JSON-LD.
|
||||
|
||||
## What it doesn't do
|
||||
|
||||
@ -119,19 +120,7 @@ consider whether they need their own [custom type](https://xkcd.com/927).
|
||||
|
||||
The code-generation aspect also allows the specification to be translated into
|
||||
declarative data, which permits certain kinds of validation and verification.
|
||||
This has led to giving the following feedback to the specification:
|
||||
|
||||
* [Inconsistencies between property domains and type properties](https://github.com/w3c/activitystreams/issues/436)
|
||||
* [Please clarify "items" and "orderedItems" properties](https://github.com/w3c/activitystreams/issues/437)
|
||||
* [Expectations around IRI resolution](https://github.com/w3c/activitystreams/issues/438)
|
||||
* [Examples Contradict Specification](https://github.com/w3c/activitystreams/issues/439)
|
||||
* [Tombstone "formerType" Property Range Needs Clarification](https://github.com/w3c/activitystreams/issues/440)
|
||||
* [Example 60 Missing `@context` Property](https://github.com/w3c/activitystreams/issues/441)
|
||||
* [Stylistic Consistency For Non-Functional Single-Value JSON in Examples](https://github.com/w3c/activitystreams/issues/442)
|
||||
* [Spec does not clarify non-functional natural language values when mapped](https://github.com/w3c/activitystreams/issues/443)
|
||||
* [Example 102: `url` property missing `type: "Link"`](https://github.com/w3c/activitystreams/issues/444)
|
||||
* [Example 146: Missing `Z` in startTime](https://github.com/w3c/activitystreams/issues/445)
|
||||
* [Example 150: Latitude/Longitude are not xsd:float](https://github.com/w3c/activitystreams/issues/446)
|
||||
This has resulted in feedback to the specification and the W3C working group.
|
||||
|
||||
## Thanks
|
||||
|
||||
|
||||
読み込み中…
新しいイシューから参照
ユーザーをブロックする