diff --git a/CHANGELOG b/CHANGELOG index bd5fe8b..3ee571c 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,4 +1,29 @@ -master 2019-02-24 +v1.0.0 2020-07-09 + +* Rename Callbacks to FederatingCallbacks in FederatingProtocol. +* Rename Callbacks to SocialCallbacks in SocialProtocol. +* Rename NewID to NewID on the Database interface. +* Added approx. 200 unit tests at ~70% LOC coverage. +* More fixes where nil pointers would be dereferenced. +* Modified programmatic delivery to be lenient instead of strict. +* Even more 'astool' bugfixes to handle multiple vocabulary code generation. +* Added request lifecycle hooks to allow implementations greater control when + using the 'context' standard library package and its 'Context'. +* Fixed bugs in programmatic delivery, handling rare forms of HTTP successes, + handling of JSON-LD's @context, race conditions. +* Provide a Mastodon-compliant http-signatures Transport implementation, when + using the github.com/go-fed/httpsig library. +* Support programmatic sending of Activities +* Added support for 3 vocabularies in addition to ActivityStreams: toot + (Mastodon), security v1, and ForgeFed. +* Modify 'astool' to address quirky logic and underspecification in various + vocabulary definitions. +* Fixed bugs in the 'astool' logic. +* Added more helpful functions to the code generated by 'astool'. +* Inbox forwarding bug fixes. +* Migrate to go modules. + +2019-02-24 * Removed 'tools'. * Removed 'vocab'. diff --git a/README.md b/README.md index 56c539f..0057937 100644 --- a/README.md +++ b/README.md @@ -10,35 +10,51 @@ ActivityStreams vocabulary. * `pub`: ActivityPub Social Protocol (Client-to-Server or C2S) and Federating Protocol (Server-to-Server or S2S) +Check out [go-fed.org](https://go-fed.org/) for tutorials and documentation. + ## Status -**Preview (unstable) 1.0.0** ([Semantic Versioning](https://semver.org/)) +**1.0.0** ([Semantic Versioning](https://semver.org/)) + +This library has been successfully used to +[federate since May 17, 2019](https://cjslep.com/c/blog/this-blog-is-federated). An [official implementation report](https://activitypub.rocks/implementation-report/) was last submitted for version **0.2.0** [here](https://github.com/w3c/activitypub/issues/318). - +Unfortunately, the official implementation report tool is no longer maintained. Previous unofficial implementation reports are available in [issue #46](https://github.com/go-fed/activity/issues/46). Please see CHANGELOG for changes between versions. ## Getting Started -See `astool`, `streams`, or `pub` for their own README. +Check out [go-fed.org](https://go-fed.org/) for tutorials and documentation. -## How can I get help, file issues, or contribute? +Also, see `astool`, `streams`, or `pub` for their own README. -Please see the CONTRIBUTING.md file! +## FAQ -## How well tested are these libraries? +### What vocabularies are supported? + +* [ActivityStreams](https://www.w3.org/TR/activitystreams-vocabulary). +* A subset of the [toot](https://github.com/tootsuite/mastodon/blob/master/app/lib/activitypub/adapter.rb) vocabulary. +* A subset of the [security](https://w3c-ccg.github.io/security-vocab/) vocabulary. +* [ForgeFed](https://forgefed.peers.community/vocabulary.html). + +### How well tested are these libraries? I took great care to add numerous tests using examples directly from specifications, official test repositories, and my own end-to-end tests. -**v1.0.0** still has a lot of unit tests to be written. Bug fixes and small -backwards-incompatible behavior is expected before it is blessed as being -released. +**v1.0.0** has around 200 unit tests. The **federation** or **S2S** portion of +the library is very well tested. The **social** or **C2S** portion could use +additional unit tests, but is far less popular than federation. About 70% of the +lines are covered by unit tests. -## Who is using this library currently? +### Who is using this library currently? + +Note: This list only includes those who have reached out to me to explicitly be +included. | Application | Description | Repository | Point Of Contact | Homepage | |:-----------:|:-------------------------------------------------:|:--------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------------------------------:|:------------------------------------:| @@ -47,15 +63,17 @@ released. | Read.as | Long-form reader built on open protocols | [https://github.com/writeas/Read.as](https://github.com/writeas/Read.as) | [@write_as@writing.exchange](https://writing.exchange/@write_as) or [hello@write.as](mailto:hello@write.as) | [https://read.as](https://read.as) | | go-fed/apcore | Generic ActivityPub server framework in Go | [https://github.com/go-fed/apcore](https://github.com/go-fed/apcore) | [@cj@mastodon.technology](https://mastodon.technology/@cj) or [cjslep@gmail.com](mailto:cjslep@gmail.com) | [https://go-fed.org](https://go-fed.org) | -## How do I use these libraries? +### How do I use these libraries? + +Check out [go-fed.org](https://go-fed.org/) for tutorials and documentation. Please see each subdirectory for its own README for further elaboration. -## FAQ +### How can I get help, file issues, or contribute? Please see the CONTRIBUTING.md file! -## Useful References +### Useful References * [ActivityPub Specification](https://www.w3.org/TR/activitypub) * [ActivityPub GitHub Repo](https://github.com/w3c/activitypub) diff --git a/astool/README.md b/astool/README.md index dca1ca8..e6efba8 100644 --- a/astool/README.md +++ b/astool/README.md @@ -52,9 +52,8 @@ tool is `activitystreams.jsonld` which contains the OWL2 definition of the ActivityStreams specification. To generate the code, in your `$GOPATH` do: ``` -mkdir tmp -cd tmp -astool -spec activitystreams.jsonld +cd $GOPATH/github.com/go-fed/activity/astool +go generate ``` This will automatically generate a number of files containing the functions, diff --git a/pub/README.md b/pub/README.md index d7233e8..dafe176 100644 --- a/pub/README.md +++ b/pub/README.md @@ -2,10 +2,10 @@ Implements the Social and Federating Protocols in the ActivityPub specification. -## Preview Release +## Reference & Tutorial -v1.0.0 still has a lot of unit tests that need to be written. Please run -`go test -v` to see the latest state of unit testing. +The [go-fed website](https://go-fed.org/) contains tutorials and reference +materials, in addition to the rest of this README. ## How To Use @@ -13,35 +13,57 @@ v1.0.0 still has a lot of unit tests that need to be written. Please run go get github.com/go-fed/activity ``` -The root of all ActivityPub behavior is the `Actor`: +The root of all ActivityPub behavior is the `Actor`, which requires you to +implement a few interfaces: ```golang -// Only support Social protocol +import ( + "github.com/go-fed/activity/pub" +) + +type myActivityPubApp struct { /* ... */ } +type myAppsDatabase struct { /* ... */ } +type myAppsClock struct { /* ... */ } + +var ( + // Your app will implement pub.CommonBehavior, and either + // pub.SocialProtocol, pub.FederatingProtocol, or both. + myApp = &myActivityPubApp{} + myCommonBehavior pub.CommonBehavior = myApp + mySocialProtocol pub.SocialProtocol = myApp + myFederatingProtocol pub.FederatingProtocol = myApp + // Your app's database implementation. + myDatabase pub.Database = &myAppsDatabase{} + // Your app's clock. + myClock pub.Clock = &myAppsClock{} +) + +// Only support the C2S Social protocol actor := pub.NewSocialActor( - myAppsCommonBehavior, - myAppsSocialProtocol, - myAppsDatabase, - myAppsClock) + myCommonBehavior, + mySocialProtocol, + myDatabase, + myClock) // OR // -// Only support Federating protocol +// Only support S2S Federating protocol actor = pub.NewFederatingActor( - myAppsCommonBehavior, - myAppsFederatingProtocol, - myAppsDatabase, - myAppsClock) + myCommonBehavior, + myFederatingProtocol, + myDatabase, + myClock) // OR // -// Support both Social and Federating protocol. +// Support both C2S Social and S2S Federating protocol. actor = pub.NewActor( - myAppsCommonBehavior, - myAppsSocialProtocol, - myAppsFederatingProtocol, - myAppsDatabase, - myAppsClock) + myCommonBehavior, + mySocialProtocol, + myFederatingProtocol, + myDatabase, + myClock) ``` -Next, hook the `Actor` into the HTTP server: +Next, hook the `Actor` into your web server: ```golang // The application's actor @@ -93,10 +115,7 @@ server.Handler = serveMux To serve ActivityStreams data: ```golang -myHander := pub.NewActivityStreamsHandler( - myAppsAuthenticateFunc, - myAppsDatabase, - myAppsClock) +myHander := pub.NewActivityStreamsHandler(myDatabase, myClock) var activityStreamsHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request) { c := context.Background() // Populate c with request-specific information @@ -239,7 +258,7 @@ interface can be used to obtain an `Actor`: ```golang // Use custom ActivityPub implementation actor = pub.NewCustomActor( - myAppsDelegateActor, + myDelegateActor, isSocialProtocolEnabled, isFederatedProtocolEnabled, myAppsClock) diff --git a/streams/README.md b/streams/README.md index 49f9ed4..00ae95d 100644 --- a/streams/README.md +++ b/streams/README.md @@ -2,6 +2,11 @@ ActivityStreams vocabularies automatically code-generated with `astool`. +## Reference & Tutorial + +The [go-fed website](https://go-fed.org/) contains tutorials and reference +materials, in addition to the rest of this README. + ## How To Use ```