gitea-mirror
/
go-fed-activity
mirror of https://gitea.com/gitea/go-fed-activity.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Minor fixes in the README

This commit is contained in:
Cory Slep 2019-02-24 16:45:54 +01:00
parent 4a8f7314a7
commit 19c351e729
2 changed files with 39 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
pub/README.md
View File

@ -49,12 +49,12 @@ var actor pub.Actor
var outboxHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request) {
c := context.Background()
// Populate c with request-specific information
if handled, err := myPubber.PostOutbox(c, w, r); err != nil {
if handled, err := actor.PostOutbox(c, w, r); err != nil {
// Write to w
return
} else if handled {
return
} else if handled, err := myPubber.GetOutbox(c, w, r); err != nil {
} else if handled, err = actor.GetOutbox(c, w, r); err != nil {
// Write to w
return
} else if handled {
@ -67,12 +67,12 @@ var outboxHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request
var inboxHandler http.HandlerFunc = func(w http.ResponseWriter, r *http.Request) {
c := context.Background()
// Populate c with request-specific information
if handled, err := myPubber.PostInbox(c, w, r); err != nil {
if handled, err := actor.PostInbox(c, w, r); err != nil {
// Write to w
return
} else if handled {
return
} else if handled, err := myPubber.GetInbox(c, w, r); err != nil {
} else if handled, err = actor.GetInbox(c, w, r); err != nil {
// Write to w
return
} else if handled {
@ -125,7 +125,7 @@ for ActivityPub. The interfaces to be satisfied are:
package.
* `Clock` - The server's internal clock.
* `Transport` - Responsible for the network that serves requests and deliveries
of ActivityStreams data.
of ActivityStreams data. A `HttpSigTransport` type is provided.
These implementations form the core of an application's behavior without
worrying about the particulars and pitfalls of the ActivityPub protocol.
@ -141,16 +141,18 @@ more than a bundle of default behaviors for types like `Create`, `Update`, and
so on.
Applications will want to focus on implementing their specific behaviors in the
callbacks, and has fine-grained control over customization:
callbacks, and have fine-grained control over customization:
```golang
// Implements the FederatingProtocol interface.
func (m *myAppsFederatingProtocol) Callbacks(c context.Context) (wrapped FederatingWrappedCallbacks, other []interface{}) {
//
// This illustration can also be applied for the Social Protocol.
func (m *myAppsFederatingProtocol) Callbacks(c context.Context) (wrapped pub.FederatingWrappedCallbacks, other []interface{}) {
// The context 'c' has request-specific logic and can be used to apply complex
// logic building the right behaviors, if desired.
//
// 'c' will later be passed through to the callbacks created below.
wrapped = &FederatingWrappedCallbacks{
wrapped = pub.FederatingWrappedCallbacks{
Create: func(ctx context.Context, create vocab.ActivityStreamsCreate) error {
// This function is wrapped by default behavior.
//
@ -158,18 +160,22 @@ func (m *myAppsFederatingProtocol) Callbacks(c context.Context) (wrapped Federat
//
// 'ctx' will have request-specific information from the HTTP handler. It
// is the same as the 'c' passed to the Callbacks method.
// 'create' has already triggered the recommended ActivityPub side effect
// behavior. The application can process it further as needed.
// 'create' has, at this point, already triggered the recommended
// ActivityPub side effect behavior. The application can process it
// further as needed.
return nil
},
}
// These must be compatible with streams.TypeResolver
// The 'other' must contain functions that satisfy the signature pattern
// required by streams.JSONResolver.
//
// If they are not, at runtime errors will be returned to indicate this.
other = []interface{}{
// The FederatingWrappedCallbacks has default behavior for an "Update" type,
// but since we are providing this behavior in "other" and not in the
// FederatingWrappedCallbacks.Update member, we will entirely replace the
// go-fed provided default behavior. Be careful that this still implements
// ActivityPub properly.
// default behavior provided by go-fed. Be careful that this still
// implements ActivityPub properly.
func(ctx context.Context, update vocab.ActivityStreamsUpdate) error {
// This function is NOT wrapped by default behavior.
//
@ -177,7 +183,7 @@ func (m *myAppsFederatingProtocol) Callbacks(c context.Context) (wrapped Federat
//
// 'ctx' will have request-specific information from the HTTP handler. It
// is the same as the 'c' passed to the Callbacks method.
// 'update' has NOT triggered the recommended ActivityPub side effect
// 'update' will NOT trigger the recommended ActivityPub side effect
// behavior. The application should do so in addition to any other custom
// side effects required.
return nil
@ -210,15 +216,20 @@ code generated types. As new ActivityStreams extensions are developed and their
code is generated, `pub` will automatically pick up support for these
extensions.
The steps to rapidly implement a new extension are:
The steps to rapidly implement a new extension in a `pub` application are:
1. Generate an OWL definition of the ActivityStreams extension.
1. Generate an OWL definition of the ActivityStreams extension. This definition
could be the same one defining the vocabulary at the `@context` IRI.
2. Run `astool` to autogenerate the golang types in the `streams` package.
3. Implement the application's callbacks in the `FederatingProtocol.Callbacks`
or `SocialProtocol.Callbacks` for the new behaviors needed.
4. Build `pub` against the application's code and the newly generated `streams`
4. Build the application, which builds `pub`, with the newly generated `streams`
code. No code changes in `pub` are required.
Whether an author of an ActivityStreams extension or an application developer,
these quick steps should reduce the barrier to adopion in a statically-typed
environment.
### DelegateActor
For those that need a near-complete custom ActivityPub solution, or want to have

19
streams/README.md
View File

@ -15,7 +15,7 @@ functions live in `github.com/go-fed/streams`.
To create a type and set properties:
```golang
var actorURL *url.URL
var actorURL *url.URL = // ...
// A new "Create" Activity.
create := streams.NewActivityStreamsCreate()
@ -32,8 +32,8 @@ To process properties on a type:
// Returns true if the "Update" has at least one "object" with an IRI value.
func hasObjectWithIRIValue(update vocab.ActivityStreamsUpdate) bool {
objectProperty := update.GetActivityStreamsObject()
// Any property may be nil if it was empty in the original JSON or simply not
// set after creation.
// Any property may be nil if it was either empty in the original JSON or
// never set on the golang type.
if objectProperty == nil {
return false
}
@ -42,7 +42,7 @@ func hasObjectWithIRIValue(update vocab.ActivityStreamsUpdate) bool {
// versus a non-functional one.
//
// While it may be easy to ignore multiple values in other languages
// (accidentally, or purposefully), go-fed is designed to make it hard to do
// (accidentally or purposefully), go-fed is designed to make it hard to do
// so.
for iter := objectProperty.Begin(); iter != objectProperty.End(); iter = iter.Next() {
// If this particular value is an IRI, return true.
@ -56,8 +56,9 @@ func hasObjectWithIRIValue(update vocab.ActivityStreamsUpdate) bool {
```
The ActivityStreams type hierarchy of "extends" and "disjoint" is not the same
as Object Oriented inheritance. Helper functions are provided to guarantee that
an application's logic is sound:
as the Object Oriented definition of inheritance. It is also not the same as
golang's interface duck-typing. Helper functions are provided to guarantee that
an application's logic can correctly apply the type hierarchy.
```golang
thing := // Pick a type from streams.NewActivityStreams<Type>()
@ -81,11 +82,13 @@ the interesting concrete type:
// func(context.Context, <TypeInterface>) error
createCallback := func(c context.Context, create vocab.ActivityStreamsCreate) error {
// Do something with 'create'
return error
fmt.Printf("createCallback called: %T\n", create)
return nil
}
updateCallback := func(c context.Context, update vocab.ActivityStreamsUpdate) error {
// Do something with 'update'
return error
fmt.Printf("updateCallback called: %T\n", update)
return nil
}
jsonResolver, err := streams.NewJSONResolver(createCallback, updateCallback)
if err != nil {