actor.go (6033B)
1 package pub 2 3 import ( 4 "context" 5 "net/http" 6 "net/url" 7 8 "github.com/superseriousbusiness/activity/streams/vocab" 9 ) 10 11 // Actor represents ActivityPub's actor concept. It conceptually has an inbox 12 // and outbox that receives either a POST or GET request, which triggers side 13 // effects in the federating application. 14 // 15 // An Actor within an application may federate server-to-server (Federation 16 // Protocol), client-to-server (Social API), or both. The Actor represents the 17 // server in either use case. 18 // 19 // An actor can be created by calling NewSocialActor (only the Social Protocol 20 // is supported), NewFederatingActor (only the Federating Protocol is 21 // supported), NewActor (both are supported), or NewCustomActor (neither are). 22 // 23 // Not all Actors have the same behaviors depending on the constructor used to 24 // create them. Refer to the constructor's documentation to determine the exact 25 // behavior of the Actor on an application. 26 // 27 // The behaviors documented here are common to all Actors returned by any 28 // constructor. 29 type Actor interface { 30 // PostInbox returns true if the request was handled as an ActivityPub 31 // POST to an actor's inbox. If false, the request was not an 32 // ActivityPub request and may still be handled by the caller in 33 // another way, such as serving a web page. 34 // 35 // If the error is nil, then the ResponseWriter's headers and response 36 // has already been written. If a non-nil error is returned, then no 37 // response has been written. 38 // 39 // If the Actor was constructed with the Federated Protocol enabled, 40 // side effects will occur. 41 // 42 // If the Federated Protocol is not enabled, writes the 43 // http.StatusMethodNotAllowed status code in the response. No side 44 // effects occur. 45 // 46 // The request and data of your application will be interpreted as 47 // having an HTTPS protocol scheme. 48 PostInbox(c context.Context, w http.ResponseWriter, r *http.Request) (bool, error) 49 // PostInboxScheme is similar to PostInbox, except clients are able to 50 // specify which protocol scheme to handle the incoming request and the 51 // data stored within the application (HTTP, HTTPS, etc). 52 PostInboxScheme(c context.Context, w http.ResponseWriter, r *http.Request, scheme string) (bool, error) 53 // GetInbox returns true if the request was handled as an ActivityPub 54 // GET to an actor's inbox. If false, the request was not an ActivityPub 55 // request and may still be handled by the caller in another way, such 56 // as serving a web page. 57 // 58 // If the error is nil, then the ResponseWriter's headers and response 59 // has already been written. If a non-nil error is returned, then no 60 // response has been written. 61 // 62 // If the request is an ActivityPub request, the Actor will defer to the 63 // application to determine the correct authorization of the request and 64 // the resulting OrderedCollection to respond with. The Actor handles 65 // serializing this OrderedCollection and responding with the correct 66 // headers and http.StatusOK. 67 GetInbox(c context.Context, w http.ResponseWriter, r *http.Request) (bool, error) 68 // PostOutbox returns true if the request was handled as an ActivityPub 69 // POST to an actor's outbox. If false, the request was not an 70 // ActivityPub request and may still be handled by the caller in another 71 // way, such as serving a web page. 72 // 73 // If the error is nil, then the ResponseWriter's headers and response 74 // has already been written. If a non-nil error is returned, then no 75 // response has been written. 76 // 77 // If the Actor was constructed with the Social Protocol enabled, side 78 // effects will occur. 79 // 80 // If the Social Protocol is not enabled, writes the 81 // http.StatusMethodNotAllowed status code in the response. No side 82 // effects occur. 83 // 84 // If the Social and Federated Protocol are both enabled, it will handle 85 // the side effects of receiving an ActivityStream Activity, and then 86 // federate the Activity to peers. 87 // 88 // The request will be interpreted as having an HTTPS scheme. 89 PostOutbox(c context.Context, w http.ResponseWriter, r *http.Request) (bool, error) 90 // PostOutboxScheme is similar to PostOutbox, except clients are able to 91 // specify which protocol scheme to handle the incoming request and the 92 // data stored within the application (HTTP, HTTPS, etc). 93 PostOutboxScheme(c context.Context, w http.ResponseWriter, r *http.Request, scheme string) (bool, error) 94 // GetOutbox returns true if the request was handled as an ActivityPub 95 // GET to an actor's outbox. If false, the request was not an 96 // ActivityPub request. 97 // 98 // If the error is nil, then the ResponseWriter's headers and response 99 // has already been written. If a non-nil error is returned, then no 100 // response has been written. 101 // 102 // If the request is an ActivityPub request, the Actor will defer to the 103 // application to determine the correct authorization of the request and 104 // the resulting OrderedCollection to respond with. The Actor handles 105 // serializing this OrderedCollection and responding with the correct 106 // headers and http.StatusOK. 107 GetOutbox(c context.Context, w http.ResponseWriter, r *http.Request) (bool, error) 108 } 109 110 // FederatingActor is an Actor that allows programmatically delivering an 111 // Activity to a federating peer. 112 type FederatingActor interface { 113 Actor 114 // Send a federated activity. 115 // 116 // The provided url must be the outbox of the sender. All processing of 117 // the activity occurs similarly to the C2S flow: 118 // - If t is not an Activity, it is wrapped in a Create activity. 119 // - A new ID is generated for the activity. 120 // - The activity is added to the specified outbox. 121 // - The activity is prepared and delivered to recipients. 122 // 123 // Note that this function will only behave as expected if the 124 // implementation has been constructed to support federation. This 125 // method will guaranteed work for non-custom Actors. For custom actors, 126 // care should be used to not call this method if only C2S is supported. 127 Send(c context.Context, outbox *url.URL, t vocab.Type) (Activity, error) 128 }