package pub import ( "context" "net/http" "net/url" "github.com/superseriousbusiness/activity/streams/vocab" ) // 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. // // 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). // // 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. // // If the Actor was constructed with the Federated Protocol enabled, // side effects will occur. // // If the Federated Protocol is not enabled, writes the // http.StatusMethodNotAllowed status code in the response. No side // effects occur. // // The request and data of your application will be interpreted as // having an HTTPS protocol scheme. PostInbox(c context.Context, w http.ResponseWriter, r *http.Request) (bool, error) // PostInboxScheme is similar to PostInbox, except clients are able to // specify which protocol scheme to handle the incoming request and the // data stored within the application (HTTP, HTTPS, etc). PostInboxScheme(c context.Context, w http.ResponseWriter, r *http.Request, scheme string) (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. // // 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. // // The request will be interpreted as having an HTTPS scheme. PostOutbox(c context.Context, w http.ResponseWriter, r *http.Request) (bool, error) // PostOutboxScheme is similar to PostOutbox, except clients are able to // specify which protocol scheme to handle the incoming request and the // data stored within the application (HTTP, HTTPS, etc). PostOutboxScheme(c context.Context, w http.ResponseWriter, r *http.Request, scheme string) (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) } // FederatingActor is an Actor that allows programmatically delivering an // Activity to a federating peer. type FederatingActor interface { Actor // Send a federated activity. // // 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. // - A new ID is generated for the activity. // - The activity is added to the specified outbox. // - The activity is prepared and delivered to recipients. // // Note that this function will only behave as expected if the // 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) }