delegate_actor.go (11794B)
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 // DelegateActor contains the detailed interface an application must satisfy in 12 // order to implement the ActivityPub specification. 13 // 14 // Note that an implementation of this interface is implicitly provided in the 15 // calls to NewActor, NewSocialActor, and NewFederatingActor. 16 // 17 // Implementing the DelegateActor requires familiarity with the ActivityPub 18 // specification because it does not a strong enough abstraction for the client 19 // application to ignore the ActivityPub spec. It is very possible to implement 20 // this interface and build a foot-gun that trashes the fediverse without being 21 // ActivityPub compliant. Please use with due consideration. 22 // 23 // Alternatively, build an application that uses the parts of the pub library 24 // that do not require implementing a DelegateActor so that the ActivityPub 25 // implementation is completely provided out of the box. 26 type DelegateActor interface { 27 // Hook callback after parsing the request body for a federated request 28 // to the Actor's inbox. 29 // 30 // Can be used to set contextual information based on the Activity 31 // received. 32 // 33 // Only called if the Federated Protocol is enabled. 34 // 35 // Warning: Neither authentication nor authorization has taken place at 36 // this time. Doing anything beyond setting contextual information is 37 // strongly discouraged. 38 // 39 // If an error is returned, it is passed back to the caller of 40 // PostInbox. In this case, the DelegateActor implementation must not 41 // write a response to the ResponseWriter as is expected that the caller 42 // to PostInbox will do so when handling the error. 43 PostInboxRequestBodyHook(c context.Context, r *http.Request, activity Activity) (context.Context, error) 44 // Hook callback after parsing the request body for a client request 45 // to the Actor's outbox. 46 // 47 // Can be used to set contextual information based on the 48 // ActivityStreams object received. 49 // 50 // Only called if the Social API is enabled. 51 // 52 // Warning: Neither authentication nor authorization has taken place at 53 // this time. Doing anything beyond setting contextual information is 54 // strongly discouraged. 55 // 56 // If an error is returned, it is passed back to the caller of 57 // PostOutbox. In this case, the DelegateActor implementation must not 58 // write a response to the ResponseWriter as is expected that the caller 59 // to PostOutbox will do so when handling the error. 60 PostOutboxRequestBodyHook(c context.Context, r *http.Request, data vocab.Type) (context.Context, error) 61 // AuthenticatePostInbox delegates the authentication of a POST to an 62 // inbox. 63 // 64 // Only called if the Federated Protocol is enabled. 65 // 66 // If an error is returned, it is passed back to the caller of 67 // PostInbox. In this case, the implementation must not write a 68 // response to the ResponseWriter as is expected that the client will 69 // do so when handling the error. The 'authenticated' is ignored. 70 // 71 // If no error is returned, but authentication or authorization fails, 72 // then authenticated must be false and error nil. It is expected that 73 // the implementation handles writing to the ResponseWriter in this 74 // case. 75 // 76 // Finally, if the authentication and authorization succeeds, then 77 // authenticated must be true and error nil. The request will continue 78 // to be processed. 79 AuthenticatePostInbox(c context.Context, w http.ResponseWriter, r *http.Request) (out context.Context, authenticated bool, err error) 80 // AuthenticateGetInbox delegates the authentication of a GET to an 81 // inbox. 82 // 83 // Always called, regardless whether the Federated Protocol or Social 84 // API is enabled. 85 // 86 // If an error is returned, it is passed back to the caller of 87 // GetInbox. In this case, the implementation must not write a 88 // response to the ResponseWriter as is expected that the client will 89 // do so when handling the error. The 'authenticated' is ignored. 90 // 91 // If no error is returned, but authentication or authorization fails, 92 // then authenticated must be false and error nil. It is expected that 93 // the implementation handles writing to the ResponseWriter in this 94 // case. 95 // 96 // Finally, if the authentication and authorization succeeds, then 97 // authenticated must be true and error nil. The request will continue 98 // to be processed. 99 AuthenticateGetInbox(c context.Context, w http.ResponseWriter, r *http.Request) (out context.Context, authenticated bool, err error) 100 // AuthorizePostInbox delegates the authorization of an activity that 101 // has been sent by POST to an inbox. 102 // 103 // Only called if the Federated Protocol is enabled. 104 // 105 // If an error is returned, it is passed back to the caller of 106 // PostInbox. In this case, the implementation must not write a 107 // response to the ResponseWriter as is expected that the client will 108 // do so when handling the error. The 'authorized' is ignored. 109 // 110 // If no error is returned, but authorization fails, then authorized 111 // must be false and error nil. It is expected that the implementation 112 // handles writing to the ResponseWriter in this case. 113 // 114 // Finally, if the authentication and authorization succeeds, then 115 // authorized must be true and error nil. The request will continue 116 // to be processed. 117 AuthorizePostInbox(c context.Context, w http.ResponseWriter, activity Activity) (authorized bool, err error) 118 // PostInbox delegates the side effects of adding to the inbox and 119 // determining if it is a request that should be blocked. 120 // 121 // Only called if the Federated Protocol is enabled. 122 // 123 // As a side effect, PostInbox sets the federated data in the inbox, but 124 // not on its own in the database, as InboxForwarding (which is called 125 // later) must decide whether it has seen this activity before in order 126 // to determine whether to do the forwarding algorithm. 127 // 128 // If the error is ErrObjectRequired or ErrTargetRequired, then a Bad 129 // Request status is sent in the response. 130 PostInbox(c context.Context, inboxIRI *url.URL, activity Activity) error 131 // InboxForwarding delegates inbox forwarding logic when a POST request 132 // is received in the Actor's inbox. 133 // 134 // Only called if the Federated Protocol is enabled. 135 // 136 // The delegate is responsible for determining whether to do the inbox 137 // forwarding, as well as actually conducting it if it determines it 138 // needs to. 139 // 140 // As a side effect, InboxForwarding must set the federated data in the 141 // database, independently of the inbox, however it sees fit in order to 142 // determine whether it has seen the activity before. 143 // 144 // The provided url is the inbox of the recipient of the Activity. The 145 // Activity is examined for the information about who to inbox forward 146 // to. 147 // 148 // If an error is returned, it is returned to the caller of PostInbox. 149 InboxForwarding(c context.Context, inboxIRI *url.URL, activity Activity) error 150 // PostOutbox delegates the logic for side effects and adding to the 151 // outbox. 152 // 153 // Always called, regardless whether the Federated Protocol or Social 154 // API is enabled. In the case of the Social API being enabled, side 155 // effects of the Activity must occur. 156 // 157 // The delegate is responsible for adding the activity to the database's 158 // general storage for independent retrieval, and not just within the 159 // actor's outbox. 160 // 161 // If the error is ErrObjectRequired or ErrTargetRequired, then a Bad 162 // Request status is sent in the response. 163 // 164 // Note that 'rawJSON' is an unfortunate consequence where an 'Update' 165 // Activity is the only one that explicitly cares about 'null' values in 166 // JSON. Since go-fed does not differentiate between 'null' values and 167 // values that are simply not present, the 'rawJSON' map is ONLY needed 168 // for this narrow and specific use case. 169 PostOutbox(c context.Context, a Activity, outboxIRI *url.URL, rawJSON map[string]interface{}) (deliverable bool, e error) 170 // AddNewIDs sets new URL ids on the activity. It also does so for all 171 // 'object' properties if the Activity is a Create type. 172 // 173 // Only called if the Social API is enabled. 174 // 175 // If an error is returned, it is returned to the caller of PostOutbox. 176 AddNewIDs(c context.Context, a Activity) error 177 // Deliver sends a federated message. Called only if federation is 178 // enabled. 179 // 180 // Called if the Federated Protocol is enabled. 181 // 182 // The provided url is the outbox of the sender. The Activity contains 183 // the information about the intended recipients. 184 // 185 // If an error is returned, it is returned to the caller of PostOutbox. 186 Deliver(c context.Context, outbox *url.URL, activity Activity) error 187 // AuthenticatePostOutbox delegates the authentication and authorization 188 // of a POST to an outbox. 189 // 190 // Only called if the Social API is enabled. 191 // 192 // If an error is returned, it is passed back to the caller of 193 // PostOutbox. In this case, the implementation must not write a 194 // response to the ResponseWriter as is expected that the client will 195 // do so when handling the error. The 'authenticated' is ignored. 196 // 197 // If no error is returned, but authentication or authorization fails, 198 // then authenticated must be false and error nil. It is expected that 199 // the implementation handles writing to the ResponseWriter in this 200 // case. 201 // 202 // Finally, if the authentication and authorization succeeds, then 203 // authenticated must be true and error nil. The request will continue 204 // to be processed. 205 AuthenticatePostOutbox(c context.Context, w http.ResponseWriter, r *http.Request) (out context.Context, authenticated bool, err error) 206 // AuthenticateGetOutbox delegates the authentication of a GET to an 207 // outbox. 208 // 209 // Always called, regardless whether the Federated Protocol or Social 210 // API is enabled. 211 // 212 // If an error is returned, it is passed back to the caller of 213 // GetOutbox. In this case, the implementation must not write a 214 // response to the ResponseWriter as is expected that the client will 215 // do so when handling the error. The 'authenticated' is ignored. 216 // 217 // If no error is returned, but authentication or authorization fails, 218 // then authenticated must be false and error nil. It is expected that 219 // the implementation handles writing to the ResponseWriter in this 220 // case. 221 // 222 // Finally, if the authentication and authorization succeeds, then 223 // authenticated must be true and error nil. The request will continue 224 // to be processed. 225 AuthenticateGetOutbox(c context.Context, w http.ResponseWriter, r *http.Request) (out context.Context, authenticated bool, err error) 226 // WrapInCreate wraps the provided object in a Create ActivityStreams 227 // activity. The provided URL is the actor's outbox endpoint. 228 // 229 // Only called if the Social API is enabled. 230 WrapInCreate(c context.Context, value vocab.Type, outboxIRI *url.URL) (vocab.ActivityStreamsCreate, error) 231 // GetOutbox returns the OrderedCollection inbox of the actor for this 232 // context. It is up to the implementation to provide the correct 233 // collection for the kind of authorization given in the request. 234 // 235 // AuthenticateGetOutbox will be called prior to this. 236 // 237 // Always called, regardless whether the Federated Protocol or Social 238 // API is enabled. 239 GetOutbox(c context.Context, r *http.Request) (vocab.ActivityStreamsOrderedCollectionPage, error) 240 // GetInbox returns the OrderedCollection inbox of the actor for this 241 // context. It is up to the implementation to provide the correct 242 // collection for the kind of authorization given in the request. 243 // 244 // AuthenticateGetInbox will be called prior to this. 245 // 246 // Always called, regardless whether the Federated Protocol or Social 247 // API is enabled. 248 GetInbox(c context.Context, r *http.Request) (vocab.ActivityStreamsOrderedCollectionPage, error) 249 }