gotosocial/vendor/github.com/superseriousbusiness/activity/pub/delegate_actor.go
2021-11-13 17:29:43 +01:00

250 lines
12 KiB
Go

package pub
import (
"context"
"net/http"
"net/url"
"github.com/superseriousbusiness/activity/streams/vocab"
)
// DelegateActor contains the detailed interface an application must satisfy in
// order to implement the ActivityPub specification.
//
// Note that an implementation of this interface is implicitly provided in the
// calls to NewActor, NewSocialActor, and NewFederatingActor.
//
// Implementing the DelegateActor requires familiarity with the ActivityPub
// specification because it does not a strong enough abstraction for the client
// application to ignore the ActivityPub spec. It is very possible to implement
// this interface and build a foot-gun that trashes the fediverse without being
// ActivityPub compliant. Please use with due consideration.
//
// Alternatively, build an application that uses the parts of the pub library
// that do not require implementing a DelegateActor so that the ActivityPub
// implementation is completely provided out of the box.
type DelegateActor interface {
// Hook callback after parsing the request body for a federated request
// to the Actor's inbox.
//
// Can be used to set contextual information based on the Activity
// received.
//
// Only called if the Federated Protocol is enabled.
//
// Warning: Neither authentication nor authorization has taken place at
// this time. Doing anything beyond setting contextual information is
// strongly discouraged.
//
// If an error is returned, it is passed back to the caller of
// PostInbox. In this case, the DelegateActor implementation must not
// write a response to the ResponseWriter as is expected that the caller
// to PostInbox will do so when handling the error.
PostInboxRequestBodyHook(c context.Context, r *http.Request, activity Activity) (context.Context, error)
// Hook callback after parsing the request body for a client request
// to the Actor's outbox.
//
// Can be used to set contextual information based on the
// ActivityStreams object received.
//
// Only called if the Social API is enabled.
//
// Warning: Neither authentication nor authorization has taken place at
// this time. Doing anything beyond setting contextual information is
// strongly discouraged.
//
// If an error is returned, it is passed back to the caller of
// PostOutbox. In this case, the DelegateActor implementation must not
// write a response to the ResponseWriter as is expected that the caller
// to PostOutbox will do so when handling the error.
PostOutboxRequestBodyHook(c context.Context, r *http.Request, data vocab.Type) (context.Context, error)
// AuthenticatePostInbox delegates the authentication of a POST to an
// inbox.
//
// Only called if the Federated Protocol is enabled.
//
// If an error is returned, it is passed back to the caller of
// PostInbox. In this case, the implementation must not write a
// response to the ResponseWriter as is expected that the client will
// do so when handling the error. The 'authenticated' is ignored.
//
// If no error is returned, but authentication or authorization fails,
// then authenticated must be false and error nil. It is expected that
// the implementation handles writing to the ResponseWriter in this
// case.
//
// Finally, if the authentication and authorization succeeds, then
// authenticated must be true and error nil. The request will continue
// to be processed.
AuthenticatePostInbox(c context.Context, w http.ResponseWriter, r *http.Request) (out context.Context, authenticated bool, err error)
// AuthenticateGetInbox delegates the authentication of a GET to an
// inbox.
//
// Always called, regardless whether the Federated Protocol or Social
// API is enabled.
//
// If an error is returned, it is passed back to the caller of
// GetInbox. In this case, the implementation must not write a
// response to the ResponseWriter as is expected that the client will
// do so when handling the error. The 'authenticated' is ignored.
//
// If no error is returned, but authentication or authorization fails,
// then authenticated must be false and error nil. It is expected that
// the implementation handles writing to the ResponseWriter in this
// case.
//
// Finally, if the authentication and authorization succeeds, then
// authenticated must be true and error nil. The request will continue
// to be processed.
AuthenticateGetInbox(c context.Context, w http.ResponseWriter, r *http.Request) (out context.Context, authenticated bool, err error)
// AuthorizePostInbox delegates the authorization of an activity that
// has been sent by POST to an inbox.
//
// Only called if the Federated Protocol is enabled.
//
// If an error is returned, it is passed back to the caller of
// PostInbox. In this case, the implementation must not write a
// response to the ResponseWriter as is expected that the client will
// do so when handling the error. The 'authorized' is ignored.
//
// If no error is returned, but authorization fails, then authorized
// must be false and error nil. It is expected that the implementation
// handles writing to the ResponseWriter in this case.
//
// Finally, if the authentication and authorization succeeds, then
// authorized must be true and error nil. The request will continue
// to be processed.
AuthorizePostInbox(c context.Context, w http.ResponseWriter, activity Activity) (authorized bool, err error)
// PostInbox delegates the side effects of adding to the inbox and
// determining if it is a request that should be blocked.
//
// Only called if the Federated Protocol is enabled.
//
// As a side effect, PostInbox sets the federated data in the inbox, but
// not on its own in the database, as InboxForwarding (which is called
// later) must decide whether it has seen this activity before in order
// to determine whether to do the forwarding algorithm.
//
// If the error is ErrObjectRequired or ErrTargetRequired, then a Bad
// Request status is sent in the response.
PostInbox(c context.Context, inboxIRI *url.URL, activity Activity) error
// InboxForwarding delegates inbox forwarding logic when a POST request
// is received in the Actor's inbox.
//
// Only called if the Federated Protocol is enabled.
//
// The delegate is responsible for determining whether to do the inbox
// forwarding, as well as actually conducting it if it determines it
// needs to.
//
// As a side effect, InboxForwarding must set the federated data in the
// database, independently of the inbox, however it sees fit in order to
// determine whether it has seen the activity before.
//
// The provided url is the inbox of the recipient of the Activity. The
// Activity is examined for the information about who to inbox forward
// to.
//
// If an error is returned, it is returned to the caller of PostInbox.
InboxForwarding(c context.Context, inboxIRI *url.URL, activity Activity) error
// PostOutbox delegates the logic for side effects and adding to the
// outbox.
//
// Always called, regardless whether the Federated Protocol or Social
// API is enabled. In the case of the Social API being enabled, side
// effects of the Activity must occur.
//
// The delegate is responsible for adding the activity to the database's
// general storage for independent retrieval, and not just within the
// actor's outbox.
//
// If the error is ErrObjectRequired or ErrTargetRequired, then a Bad
// Request status is sent in the response.
//
// Note that 'rawJSON' is an unfortunate consequence where an 'Update'
// Activity is the only one that explicitly cares about 'null' values in
// JSON. Since go-fed does not differentiate between 'null' values and
// values that are simply not present, the 'rawJSON' map is ONLY needed
// for this narrow and specific use case.
PostOutbox(c context.Context, a Activity, outboxIRI *url.URL, rawJSON map[string]interface{}) (deliverable bool, e error)
// AddNewIDs sets new URL ids on the activity. It also does so for all
// 'object' properties if the Activity is a Create type.
//
// Only called if the Social API is enabled.
//
// If an error is returned, it is returned to the caller of PostOutbox.
AddNewIDs(c context.Context, a Activity) error
// Deliver sends a federated message. Called only if federation is
// enabled.
//
// Called if the Federated Protocol is enabled.
//
// The provided url is the outbox of the sender. The Activity contains
// the information about the intended recipients.
//
// If an error is returned, it is returned to the caller of PostOutbox.
Deliver(c context.Context, outbox *url.URL, activity Activity) error
// AuthenticatePostOutbox delegates the authentication and authorization
// of a POST to an outbox.
//
// Only called if the Social API is enabled.
//
// If an error is returned, it is passed back to the caller of
// PostOutbox. In this case, the implementation must not write a
// response to the ResponseWriter as is expected that the client will
// do so when handling the error. The 'authenticated' is ignored.
//
// If no error is returned, but authentication or authorization fails,
// then authenticated must be false and error nil. It is expected that
// the implementation handles writing to the ResponseWriter in this
// case.
//
// Finally, if the authentication and authorization succeeds, then
// authenticated must be true and error nil. The request will continue
// to be processed.
AuthenticatePostOutbox(c context.Context, w http.ResponseWriter, r *http.Request) (out context.Context, authenticated bool, err error)
// AuthenticateGetOutbox delegates the authentication of a GET to an
// outbox.
//
// Always called, regardless whether the Federated Protocol or Social
// API is enabled.
//
// If an error is returned, it is passed back to the caller of
// GetOutbox. In this case, the implementation must not write a
// response to the ResponseWriter as is expected that the client will
// do so when handling the error. The 'authenticated' is ignored.
//
// If no error is returned, but authentication or authorization fails,
// then authenticated must be false and error nil. It is expected that
// the implementation handles writing to the ResponseWriter in this
// case.
//
// Finally, if the authentication and authorization succeeds, then
// authenticated must be true and error nil. The request will continue
// to be processed.
AuthenticateGetOutbox(c context.Context, w http.ResponseWriter, r *http.Request) (out context.Context, authenticated bool, err error)
// WrapInCreate wraps the provided object in a Create ActivityStreams
// activity. The provided URL is the actor's outbox endpoint.
//
// Only called if the Social API is enabled.
WrapInCreate(c context.Context, value vocab.Type, outboxIRI *url.URL) (vocab.ActivityStreamsCreate, error)
// GetOutbox returns the OrderedCollection inbox of the actor for this
// context. It is up to the implementation to provide the correct
// collection for the kind of authorization given in the request.
//
// AuthenticateGetOutbox will be called prior to this.
//
// Always called, regardless whether the Federated Protocol or Social
// API is enabled.
GetOutbox(c context.Context, r *http.Request) (vocab.ActivityStreamsOrderedCollectionPage, error)
// GetInbox returns the OrderedCollection inbox of the actor for this
// context. It is up to the implementation to provide the correct
// collection for the kind of authorization given in the request.
//
// AuthenticateGetInbox will be called prior to this.
//
// Always called, regardless whether the Federated Protocol or Social
// API is enabled.
GetInbox(c context.Context, r *http.Request) (vocab.ActivityStreamsOrderedCollectionPage, error)
}