Browse Source

Update all the READMEs

Cory Slep 10 months ago
parent
commit
e910e86bd6
7 changed files with 266 additions and 131 deletions
  1. 30 18
      README.md
  2. 4 2
      deliverer/README.md
  3. 186 0
      pub/README.md
  4. 10 71
      streams/README.md
  5. 13 7
      tools/README.md
  6. 5 4
      tools/vocab/gen/README.md
  7. 18 29
      vocab/README.md

+ 30 - 18
README.md

@@ -2,12 +2,14 @@
2 2
 
3 3
 `go get github.com/go-fed/activity`
4 4
 
5
+This repository supports `vgo` and is remotely verifiable.
6
+
5 7
 This repository contains three libraries for use in your golang applications:
6 8
 
7
-* An ActivityStreams Vocabulary library
8
-* A convenience library for the ActivityStreams Vocabulary
9
-* ActivityPub Social API (Client-to-Server) and Federation Protocol
10
-  (Server-to-Server).
9
+* `vocab`: An ActivityStreams Vocabulary library
10
+* `streams`: A convenience library for the ActivityStreams Vocabulary
11
+* `pub`: ActivityPub SocialAPI (Client-to-Server) and FederateAPI
12
+  (Server-to-Server)
11 13
 
12 14
 This library is biased. It forgoes understanding JSON-LD in exchange for static
13 15
 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.
15 17
 
16 18
 ## Status
17 19
 
18
-There is no stable version of this library (yet).
20
+Version 0.1.0 of this library is ready for use.
19 21
 
20
-See each subdirectory for its own README for further elaboration.
22
+There is not an implementation report available... yet!
21 23
 
22
-### Core ActivityPub Libraries
24
+See each subdirectory for its own README for further elaboration. The
25
+recommended reading order is `vocab`, `streams`, and then `pub`. Others are
26
+optional.
23 27
 
24
-* `vocab` - ActivityStreams Vocabulary: Functional and tested
25
-* `streams` - ActivityStreams Convenience Library: Functional and tested
26
-* `pub` - ActivityPub: Under development and testing
28
+## How well tested are these libraries?
27 29
 
28
-### Supplemental Libraries
30
+I took great care to add numerous tests using examples directly from
31
+specifications, official test repositories, and my own end-to-end tests.
29 32
 
30
-* `tools` - Code generation wizardry and ActivityPub-spec-as-data.
31
-* `deliverer` - Provides an asynchronous `Deliverer` for use with the `pub` lib
33
+## Who is using this library currently?
34
+
35
+No one. Please let me know if you are using it!
36
+
37
+## How do I use these libraries?
32 38
 
33
-## How To Use This Library
39
+Please see each subdirectory for its own README for further elaboration. The
40
+recommended reading order is `vocab`, `streams`, and then `pub`. Others are
41
+optional.
34 42
 
35
-This section will be fleshed out once the library is approaching its first
36
-stable release.
43
+Passing familiarity with ActivityStreams and ActivityPub is recommended.
44
+
45
+## Other Libraries
46
+
47
+* `tools` - Code generation wizardry and ActivityPub-spec-as-data.
48
+* `deliverer` - Provides an asynchronous `Deliverer` for use with the `pub` lib
37 49
 
38 50
 ## FAQ
39 51
 
40 52
 *Why does compilation take so long?*
41 53
 
42 54
 The `vocab` and `streams` packages are code generated on order of hundreds of
43
-thousands to a million lines long. Use `go install` or `go build -i` to cache
44
-the build artifacts and do incremental builds.
55
+thousands to a million lines long. If using Go 1.9 or before, use `go install`
56
+or `go build -i` to cache the build artifacts and do incremental builds.
45 57
 
46 58
 ## Useful References
47 59
 

+ 4 - 2
deliverer/README.md

@@ -1,8 +1,10 @@
1 1
 # deliverer
2 2
 
3
+This library is completely optional, provided only for convenience.
4
+
3 5
 An extra utility that provides a simple mechanism to asynchronously deliver
4
-federated messages from a `Pubber` available from the
5
-`github.com/go-fed/activity/pub` library.
6
+federated messages from a `pub.Pubber` available from the `go-fed/activity/pub`
7
+library.
6 8
 
7 9
 It implements the `pub.Deliverer` interface.
8 10
 

+ 186 - 0
pub/README.md

@@ -0,0 +1,186 @@
1
+# pub
2
+
3
+Implements both the SocialAPI and FederateAPI in the ActivityPub specification.
4
+
5
+## Disclaimer
6
+
7
+This library is designed with flexibility in mind. The cost of doing so is that
8
+writing an ActivityPub application requires a lot of careful considerations that
9
+are not trivial. ActivityPub is an Application transport layer that is also tied
10
+to a specific data model, making retrofits nontrivial as well.
11
+
12
+## How To Use
13
+
14
+There are two ActivityPub APIs: the SocialAPI between a user and your
15
+ActivityPub server, and the FederateAPI between your ActivityPub server and
16
+another server peer. This library lets you choose one or both.
17
+
18
+*Lightning intro to ActivityPub: ActivityPub uses ActivityStreams as data. This
19
+lives in `go-fed/activity/vocab`. ActivityPub has a concept of `actors` who can
20
+send, receive, and read their messages. When sending and receiving messages from
21
+a client (such as on their phone) to an ActivityPub server, it is via the
22
+SocialAPI. When it is between two ActivityPub servers, it is via the
23
+FederateAPI.*
24
+
25
+Next, there are two kinds of ActivityPub requests to handle:
26
+
27
+1. Requests that `GET` or `POST` to stuff owned by an `actor` like their `inbox`
28
+ or `outbox`.
29
+1. Requests that `GET` ActivityStream objects hosted on your server.
30
+
31
+The first is the most complex, and requires the creation of a `Pubber`. It is
32
+created depending on which APIs are to be supported:
33
+
34
+```
35
+// Only support SocialAPI
36
+s := pub.NewSocialPubber(...)
37
+// Only support FederateAPI
38
+f := pub.NewFederatingPubber(...)
39
+// Support both APIs
40
+sf := pub.NewPubber(...)
41
+```
42
+
43
+Note that *only* the creation of the `Pubber` is affected by the decision of
44
+which API to support. Once created, the `Pubber` should be used in the same
45
+manner regardless of the API it is supporting. This allows your application
46
+to easily adopt one API first and migrate to both later by simply changing how
47
+the `Pubber` is created.
48
+
49
+To use the `Pubber`, call its methods in the HTTP handlers responsible for an
50
+`actor`'s `inbox` and `outbox`:
51
+
52
+```
53
+// Given:
54
+//     var myPubber pub.Pubber
55
+var outboxHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request) {
56
+  c := context.Background()
57
+  // Populate c with application specific information
58
+  if handled, err := myPubber.PostOutbox(c, w, r); err != nil {
59
+    // Write to w
60
+  } else if handled {
61
+    return
62
+  }
63
+  if handled, err := myPubber.GetOutbox(c, w, r); err != nil {
64
+    // Write to w
65
+  } else if handled {
66
+    return
67
+  }
68
+  // Handle non-ActivityPub request, such as responding with an HTML
69
+  // representation with correct view permissions.
70
+}
71
+var inboxHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request) {
72
+  c := context.Background()
73
+  // Populate c with application specific information
74
+  if handled, err := myPubber.PostIntox(c, w, r); err != nil {
75
+    // Write to w
76
+  } else if handled {
77
+    return
78
+  }
79
+  if handled, err := myPubber.GetInbox(c, w, r); err != nil {
80
+    // Write to w
81
+  } else if handled {
82
+    return
83
+  }
84
+  // Handle non-ActivityPub request, such as responding with an HTML
85
+  // representation with correct view permissions.
86
+}
87
+```
88
+
89
+Finally, to handle the second kind of request, use the `HandlerFunc` within HTTP
90
+handler functions in a similar way. There are two ways to create `HandlerFunc`,
91
+which depend on decisions we will address later:
92
+
93
+```
94
+asHandler := pub.ServeActivityPubObject(...)
95
+var activityStreamHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request) {
96
+  c := context.Background()
97
+  // Populate c with application specific information
98
+  if handled, err := asHandler(c, w, r); err != nil {
99
+    // Write to w
100
+  } else if handled {
101
+    return
102
+  }
103
+  // Handle non-ActivityPub request, such as responding with an HTML
104
+  // representation with correct view permissions.
105
+}
106
+```
107
+
108
+That's all that's required.
109
+
110
+## How To Create
111
+
112
+You may have noticed that using the library is deceptively straightforward. This
113
+is because *creating* the `Pubber` and `HandlerFunc` types is not trivial and
114
+requires forethought.
115
+
116
+There are a lot of interfaces that must be satisfied in order to have a complete
117
+working ActivityPub server.
118
+
119
+Note that `context.Context` is passed everywhere possible, to allow your
120
+implementation to keep a request-specific context throughout the lifecycle of
121
+an ActivityPub request.
122
+
123
+### Application Interface
124
+
125
+Regardless of which of the SocialAPI and FederateAPI chosen, the `Application`
126
+interface contains the set of core methods fundamental to the functionality of
127
+this library. It contains a lot of the storage fetching and writing, all of
128
+which is keyed by `*url.URL`. To protect against race conditions, this library
129
+will inform whether it is fetching data to read-only or fetching or read-or-
130
+write.
131
+
132
+Note that under some conditions, ActivityPub verifies the peer's request. It
133
+does so using HTTP Signatures. However, this requires knowing the other party's
134
+public key, and fetching this remotely is do-able. However, this library assumes
135
+this server already has it locally; it is up to implementations to remotely
136
+fetch it if needed at this time.
137
+
138
+### SocialAPI and FederateAPI Interfaces
139
+
140
+These interfaces capture additional behaviors required by the SocialAPI and the
141
+FederateAPI.
142
+
143
+The SocialAPI can additionally provide a mechanism for client authentication and
144
+authorization using frameworks like Oauth 2.0. Such frameworks are not natively
145
+supported in this library and must be supplied.
146
+
147
+### Callbacker Interface
148
+
149
+One of these is needed per ActivityPub API supported. For example, if both the
150
+SocialAPI and FederateAPI are supported, then two of these are needed.
151
+
152
+Upon receiving one of these activities from a `POST` to the inbox or outbox, the
153
+correct callbacker will be called to handle either a SocialAPI activity or a
154
+FederateAPI activity.
155
+
156
+This is where the bulk of implementation-specific logic is expected to reside.
157
+
158
+Do note that for some of these activities, default actions will already occur.
159
+For example, if receiving an `Accept` in response to a sent `Follow`, this
160
+library automatically handles adding the correct actor into the correct
161
+`following` collection. This means a lot of the social and federate
162
+functionality is provided out of the box.
163
+
164
+### Deliverer Interface
165
+
166
+This is an optional interface. Since this library needs to send HTTP requests,
167
+it would be unwise for it to provide no way of allowing implementations to
168
+rate limit, persist across downtime, back off, etc. This interface is satisfied
169
+by the `go-fed/activity/deliverer` package which has an implementation that can
170
+remember to send requests across downtime.
171
+
172
+If an implementation does not care to have this level of control, a synchronous
173
+implementation is very straightforward to make.
174
+
175
+### Other Interfaces
176
+
177
+Other interfaces such as `Typer` and `PubObject` are meant to limit modification
178
+scope or require minimal ActivityStream compatibility to be used by this
179
+library. As long as the `go-fed/activity/vocab` or `go-fed/activity/streams`
180
+packages are being used, these interfaces will be natively supported.
181
+
182
+## Other Considerations
183
+
184
+This library does not have an implementation report generated... yet! Once it is
185
+available, it will be linked here. Furthermore, the test server will also be an
186
+excellent tutorial resource.

+ 10 - 71
streams/README.md

@@ -1,30 +1,13 @@
1 1
 # streams
2 2
 
3
-The `streams` package provides static types for Core and Extended types to the
4
-[ActivityStream Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary).
5
-The library is battle-tested against the `vocabulary-ex*-jsonld.json`
6
-[test documents](https://github.com/w3c-social/activitystreams-test-documents)
7
-in addition to usual unit tests.
3
+Please read the `README.md` in the `go-fed/activity/vocab` package first. This
4
+library is a convenience layer on top of the `go-fed/activity/vocab` library, so
5
+this README builds off of that one.
8 6
 
9
-Its mission is simple: Provide meaningful static types for the ActivityStream
10
-Vocabulary in golang. This library is a convenience layer on top of the
11
-`activity/vocab` library, which gives unfettered access to the data types.
12
-
13
-This library is entirely code-generated by the `activity/tools/streams/gen`
14
-library and `activity/tools/streams` tool. Run `go generate` to refresh the
15
-library, which requires `$GOPATH/bin` to be on your `$PATH`.
16
-
17
-**Consider using this library and falling back to `activity/vocab` only when
18
-necessary.**
19
-
20
-## This library's API is huge!
21
-
22
-**The W3C does not require client applications to support all of these
23
-use cases.** The W3C only requires that *"all implementations must at least be
24
-capable of serializing and deserializing the Extended properties in accordance
25
-with the Activity Streams 2.0 Core Syntax,"* which what this library and the
26
-`activity/vocab` libraries do for clients. This library's API is large to
27
-permit clients to use as much or as little as desired.
7
+This library is entirely code-generated by the
8
+`go-fed/activity/tools/streams/gen` library and `go-fed/activity/tools/streams`
9
+tool. Run `go generate` to refresh the library, which requires `$GOPATH/bin` to
10
+be on your `$PATH`.
28 11
 
29 12
 ## What it does
30 13
 
@@ -147,53 +130,9 @@ The only caveat is that clients must set `"@context"` manually at this time.
147 130
 
148 131
 ## What it doesn't do
149 132
 
150
-This library does not use the `reflect` package at all. It prioritizes
151
-minimizing dependencies and speed over binary size.
152
-
153
-The ActivityStream specification is built on top of JSON-LD, which uses JSON.
154
-This library should be used with `encoding/json` in order to transform a raw
155
-string into a `map[string]interface{}` to static, semantically meaningful
156
-types.
157
-
158
-This library does not set the `"@context"` property required when sending
159
-serialized data. Clients are in charge of setting it to
160
-`"https://www.w3.org/ns/activitystreams"`.
161
-
162
-This implementation is heavily opinionated against understanding JSON-LD due to
163
-its sacrifice of semantic meaning, significant increase of complexity, even
164
-weaker typing, and increased exposure to partially-understood messages. These
165
-costs earn a degree of flexibility that is not needed for the ActivityStream
166
-Vocabulary.
167
-
168
-This library is *not* a [JSON-LD](https://json-ld.org/) parser, and by design
169
-does not implement any further understanding of JSON-LD that may be outlined in
170
-the [W3C's JSON-LD](https://www.w3.org/TR/json-ld/) specification. Furthermore,
171
-it does *not* implement any of the JSON-LD
172
-[processing algorithms](https://www.w3.org/TR/json-ld-api/). If this
173
-functionality is strictly needed, or this library is not suitable, please see 
174
-[piprate/json-gold/ld](https://github.com/piprate/json-gold) and its
175
-[documentation](https://godoc.org/github.com/piprate/json-gold/ld).
133
+Please see the same section in the `go-fed/activity/vocab` package.
176 134
 
177 135
 ## Other considerations
178 136
 
179
-This library is entirely code-generated. Determined clients can add their own
180
-custom extended types to the `activity/tools/defs` library and generate a
181
-useful type. However, this process is purposefully painful to force clients to
182
-seriously consider whether they need their own
183
-[custom type](https://xkcd.com/927).
184
-
185
-The code-generation aspect also allows the specification to be translated into
186
-declarative data, which permits certain kinds of validation and verification.
187
-This has led to giving the following feedback to the specification:
188
-
189
-* [Inconsistencies between property domains and type properties](https://github.com/w3c/activitystreams/issues/436)
190
-* [Please clarify "items" and "orderedItems" properties](https://github.com/w3c/activitystreams/issues/437)
191
-* [Expectations around IRI resolution](https://github.com/w3c/activitystreams/issues/438)
192
-* [Examples Contradict Specification](https://github.com/w3c/activitystreams/issues/439)
193
-* [Tombstone "formerType" Property Range Needs Clarification](https://github.com/w3c/activitystreams/issues/440)
194
-* [Example 60 Missing `@context` Property](https://github.com/w3c/activitystreams/issues/441)
195
-* [Stylistic Consistency For Non-Functional Single-Value JSON in Examples](https://github.com/w3c/activitystreams/issues/442)
196
-* [Spec does not clarify non-functional natural language values when mapped](https://github.com/w3c/activitystreams/issues/443)
197
-* [Example 102: `url` property missing `type: "Link"`](https://github.com/w3c/activitystreams/issues/444)
198
-* [Example 146: Missing `Z` in startTime](https://github.com/w3c/activitystreams/issues/445)
199
-* [Example 150: Latitude/Longitude are not xsd:float](https://github.com/w3c/activitystreams/issues/446)
137
+This library is entirely code-generated. Please see the same section in the
138
+`go-fed/activity/vocab` package for more details.

+ 13 - 7
tools/README.md

@@ -2,10 +2,16 @@
2 2
 
3 3
 Contains the code-generation logic for aspects of this library:
4 4
 
5
-* `defs` contains common utilities and definitions for the Vocabulary.
6
-* `vocab` is the tool used to generate the Vocabulary code.
7
-* `vocab/gen` is the library that does the heavy lifting of generating the
8
-  Vocabulary code.
9
-* `stream` is the tool used to generate the ActivityStream convenience code.
10
-* `stream/gen` is the library that does the heavy lifting of generating the
11
-  ActivityStream convenience code.
5
+* `go-fed/activity/tools/defs` contains common utilities and definitions for the
6
+  Vocabulary.
7
+* `go-fed/activity/tools/vocab` is the tool used to generate the Vocabulary
8
+  code.
9
+* `go-fed/activity/tools/vocab/gen` is the library that does the heavy lifting
10
+  of generating the Vocabulary code.
11
+* `go-fed/activity/tools/stream` is the tool used to generate the ActivityStream
12
+  convenience code.
13
+* `go-fed/activity/toolsstream/gen` is the library that does the heavy lifting
14
+  of generating the ActivityStream convenience code.
15
+
16
+Before you continue further; a fair warning. This code is in severe need of
17
+tender love and care.

+ 5 - 4
tools/vocab/gen/README.md

@@ -1,9 +1,10 @@
1 1
 # gen
2 2
 
3
-This library is used to generate the `vocab` library implementation. Changes to
4
-this will fundamentally change the implementation of the `vocab` library. If
5
-custom ActivityStream types are required, no changes to this are required.
6
-Instead, the `tools/gen/vocab` library will need edits.
3
+This library is used to generate the `go-fed/activity/vocab` library
4
+implementation. Changes to this will fundamentally change the implementation of
5
+the `vocab` library. If custom ActivityStream types are required, no changes to
6
+this are required. Instead, the `go-fed/activity/tools/defs` library will need
7
+edits.
7 8
 
8 9
 Creating a static type implementation from the specification is not
9 10
 straightforward due to the following considerations that stem from its roots in

+ 18 - 29
vocab/README.md

@@ -3,7 +3,7 @@
3 3
 The `vocab` package provides static types for Core and Extended types to the
4 4
 [ActivityStream Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary).
5 5
 The library is battle-tested against all 159 examples in the Vocabulary
6
-specification linked above in addition to usual unit tests.
6
+specification linked above in addition to unit tests.
7 7
 
8 8
 Its mission is simple: Provide meaningful static types for the ActivityStream
9 9
 Vocabulary in golang.
@@ -12,8 +12,6 @@ This library is entirely code-generated by the `tools/vocab/gen` library
12 12
 and `tools/vocab` tool. Run `go generate` to refresh the library, which
13 13
 which requires `$GOPATH/bin` to be on your `$PATH`.
14 14
 
15
-**Please consider using the `activity/streams` library instead.**
16
-
17 15
 ## This library's API is huge!
18 16
 
19 17
 **The W3C does not require client applications to support all of these
@@ -57,7 +55,21 @@ conditions. Consider:
57 55
 * The `published` time conforms to RFC3339 with the exception that seconds may
58 56
   be omitted
59 57
 
60
-All of these considerations are presented much more nicely by this library:
58
+Therefore, trying to statically determine this with typical JSON tagging does
59
+not work:
60
+
61
+```
62
+type NaiveActivity struct {
63
+  type string `json:"Type"`   // Not OK, cannot handle array of strings
64
+  name []string `json:"Name"` // Not OK, cannot handle single values
65
+  // ...
66
+  published time.Time `...`   // Not OK, cannot handle when seconds are omitted
67
+}
68
+```
69
+
70
+This is the motivation for this library.
71
+
72
+All of these considerations are presented as:
61 73
 
62 74
 ```
63 75
 type Note struct { ... }
@@ -69,18 +81,7 @@ func (n *Note) GetNameString(index int) string { ... }
69 81
 ```
70 82
 
71 83
 Note that the resulting API and property type possibilities is *large*. This is
72
-a natural consequence of the specification being built on top of JSON-LD. It is
73
-recommended for applications to use the `activity/streams` convenience library
74
-instead, or create their own convenience types:
75
-
76
-```
77
-type MyNote struct {
78
-  note *vocab.Note
79
-}
80
-
81
-func (n *Note) Name() (string, bool) { /* Use note.NameLen, etc. */ }
82
-// And so on
83
-```
84
+a natural consequence of the specification being built on top of JSON-LD.
84 85
 
85 86
 ## What it doesn't do
86 87
 
@@ -119,19 +120,7 @@ consider whether they need their own [custom type](https://xkcd.com/927).
119 120
 
120 121
 The code-generation aspect also allows the specification to be translated into
121 122
 declarative data, which permits certain kinds of validation and verification.
122
-This has led to giving the following feedback to the specification:
123
-
124
-* [Inconsistencies between property domains and type properties](https://github.com/w3c/activitystreams/issues/436)
125
-* [Please clarify "items" and "orderedItems" properties](https://github.com/w3c/activitystreams/issues/437)
126
-* [Expectations around IRI resolution](https://github.com/w3c/activitystreams/issues/438)
127
-* [Examples Contradict Specification](https://github.com/w3c/activitystreams/issues/439)
128
-* [Tombstone "formerType" Property Range Needs Clarification](https://github.com/w3c/activitystreams/issues/440)
129
-* [Example 60 Missing `@context` Property](https://github.com/w3c/activitystreams/issues/441)
130
-* [Stylistic Consistency For Non-Functional Single-Value JSON in Examples](https://github.com/w3c/activitystreams/issues/442)
131
-* [Spec does not clarify non-functional natural language values when mapped](https://github.com/w3c/activitystreams/issues/443)
132
-* [Example 102: `url` property missing `type: "Link"`](https://github.com/w3c/activitystreams/issues/444)
133
-* [Example 146: Missing `Z` in startTime](https://github.com/w3c/activitystreams/issues/445)
134
-* [Example 150: Latitude/Longitude are not xsd:float](https://github.com/w3c/activitystreams/issues/446)
123
+This has resulted in feedback to the specification and the W3C working group.
135 124
 
136 125
 ## Thanks
137 126