2019-02-12 08:16:33 +09:00
|
|
|
package pub
|
|
|
|
|
|
|
|
import (
|
|
|
|
"context"
|
2019-04-04 06:35:57 +09:00
|
|
|
"github.com/go-fed/activity/streams/vocab"
|
2019-02-12 08:16:33 +09:00
|
|
|
"net/http"
|
2019-03-25 01:18:22 +09:00
|
|
|
"net/url"
|
2019-02-12 08:16:33 +09:00
|
|
|
)
|
|
|
|
|
|
|
|
// Actor represents ActivityPub's actor concept. It conceptually has an inbox
|
|
|
|
// and outbox that receives either a POST or GET request, which triggers side
|
|
|
|
// effects in the federating application.
|
|
|
|
//
|
|
|
|
// An Actor within an application may federate server-to-server (Federation
|
|
|
|
// Protocol), client-to-server (Social API), or both. The Actor represents the
|
|
|
|
// server in either use case.
|
|
|
|
//
|
2019-02-16 05:03:43 +09:00
|
|
|
// An actor can be created by calling NewSocialActor (only the Social Protocol
|
|
|
|
// is supported), NewFederatingActor (only the Federating Protocol is
|
|
|
|
// supported), NewActor (both are supported), or NewCustomActor (neither are).
|
|
|
|
//
|
2019-02-12 08:16:33 +09:00
|
|
|
// Not all Actors have the same behaviors depending on the constructor used to
|
|
|
|
// create them. Refer to the constructor's documentation to determine the exact
|
|
|
|
// behavior of the Actor on an application.
|
|
|
|
//
|
|
|
|
// The behaviors documented here are common to all Actors returned by any
|
|
|
|
// constructor.
|
|
|
|
type Actor interface {
|
|
|
|
// PostInbox returns true if the request was handled as an ActivityPub
|
|
|
|
// POST to an actor's inbox. If false, the request was not an
|
|
|
|
// ActivityPub request and may still be handled by the caller in
|
|
|
|
// another way, such as serving a web page.
|
|
|
|
//
|
|
|
|
// If the error is nil, then the ResponseWriter's headers and response
|
|
|
|
// has already been written. If a non-nil error is returned, then no
|
|
|
|
// response has been written.
|
|
|
|
//
|
2019-02-16 02:34:58 +09:00
|
|
|
// If the Actor was constructed with the Federated Protocol enabled,
|
|
|
|
// side effects will occur.
|
|
|
|
//
|
2019-02-12 08:16:33 +09:00
|
|
|
// If the Federated Protocol is not enabled, writes the
|
|
|
|
// http.StatusMethodNotAllowed status code in the response. No side
|
|
|
|
// effects occur.
|
|
|
|
PostInbox(c context.Context, w http.ResponseWriter, r *http.Request) (bool, error)
|
|
|
|
// GetInbox returns true if the request was handled as an ActivityPub
|
|
|
|
// GET to an actor's inbox. If false, the request was not an ActivityPub
|
|
|
|
// request and may still be handled by the caller in another way, such
|
|
|
|
// as serving a web page.
|
|
|
|
//
|
|
|
|
// If the error is nil, then the ResponseWriter's headers and response
|
|
|
|
// has already been written. If a non-nil error is returned, then no
|
|
|
|
// response has been written.
|
|
|
|
//
|
|
|
|
// If the request is an ActivityPub request, the Actor will defer to the
|
|
|
|
// application to determine the correct authorization of the request and
|
|
|
|
// the resulting OrderedCollection to respond with. The Actor handles
|
|
|
|
// serializing this OrderedCollection and responding with the correct
|
|
|
|
// headers and http.StatusOK.
|
|
|
|
GetInbox(c context.Context, w http.ResponseWriter, r *http.Request) (bool, error)
|
|
|
|
// PostOutbox returns true if the request was handled as an ActivityPub
|
|
|
|
// POST to an actor's outbox. If false, the request was not an
|
|
|
|
// ActivityPub request and may still be handled by the caller in another
|
|
|
|
// way, such as serving a web page.
|
|
|
|
//
|
|
|
|
// If the error is nil, then the ResponseWriter's headers and response
|
|
|
|
// has already been written. If a non-nil error is returned, then no
|
|
|
|
// response has been written.
|
2019-02-16 02:34:58 +09:00
|
|
|
//
|
|
|
|
// If the Actor was constructed with the Social Protocol enabled, side
|
|
|
|
// effects will occur.
|
|
|
|
//
|
|
|
|
// If the Social Protocol is not enabled, writes the
|
|
|
|
// http.StatusMethodNotAllowed status code in the response. No side
|
|
|
|
// effects occur.
|
|
|
|
//
|
|
|
|
// If the Social and Federated Protocol are both enabled, it will handle
|
|
|
|
// the side effects of receiving an ActivityStream Activity, and then
|
|
|
|
// federate the Activity to peers.
|
2019-02-12 08:16:33 +09:00
|
|
|
PostOutbox(c context.Context, w http.ResponseWriter, r *http.Request) (bool, error)
|
|
|
|
// GetOutbox returns true if the request was handled as an ActivityPub
|
|
|
|
// GET to an actor's outbox. If false, the request was not an
|
|
|
|
// ActivityPub request.
|
|
|
|
//
|
|
|
|
// If the error is nil, then the ResponseWriter's headers and response
|
|
|
|
// has already been written. If a non-nil error is returned, then no
|
|
|
|
// response has been written.
|
|
|
|
//
|
|
|
|
// If the request is an ActivityPub request, the Actor will defer to the
|
|
|
|
// application to determine the correct authorization of the request and
|
|
|
|
// the resulting OrderedCollection to respond with. The Actor handles
|
|
|
|
// serializing this OrderedCollection and responding with the correct
|
|
|
|
// headers and http.StatusOK.
|
|
|
|
GetOutbox(c context.Context, w http.ResponseWriter, r *http.Request) (bool, error)
|
|
|
|
}
|
2019-03-25 01:18:22 +09:00
|
|
|
|
|
|
|
// FederatingActor is an Actor that allows programmatically delivering an
|
|
|
|
// Activity to a federating peer.
|
|
|
|
type FederatingActor interface {
|
|
|
|
Actor
|
2019-03-27 06:00:55 +09:00
|
|
|
// Send a federated activity.
|
2019-03-25 01:18:22 +09:00
|
|
|
//
|
2019-03-27 06:00:55 +09:00
|
|
|
// The provided url must be the outbox of the sender. All processing of
|
|
|
|
// the activity occurs similarly to the C2S flow:
|
|
|
|
// - If t is not an Activity, it is wrapped in a Create activity.
|
2019-04-04 06:35:57 +09:00
|
|
|
// - A new ID is generated for the activity.
|
|
|
|
// - The activity is added to the specified outbox.
|
|
|
|
// - The activity is prepared and delivered to recipients.
|
2019-03-25 01:18:22 +09:00
|
|
|
//
|
|
|
|
// Note that this function will only behave as expected if the
|
2019-03-27 06:00:55 +09:00
|
|
|
// implementation has been constructed to support federation. This
|
|
|
|
// method will guaranteed work for non-custom Actors. For custom actors,
|
|
|
|
// care should be used to not call this method if only C2S is supported.
|
|
|
|
Send(c context.Context, outbox *url.URL, t vocab.Type) (Activity, error)
|
2019-03-25 01:18:22 +09:00
|
|
|
}
|