common_behavior.go (3918B)
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 // Common contains functions required for both the Social API and Federating 12 // Protocol. 13 // 14 // It is passed to the library as a dependency injection from the client 15 // application. 16 type CommonBehavior interface { 17 // AuthenticateGetInbox delegates the authentication of a GET to an 18 // inbox. 19 // 20 // Always called, regardless whether the Federated Protocol or Social 21 // API is enabled. 22 // 23 // If an error is returned, it is passed back to the caller of 24 // GetInbox. In this case, the implementation must not write a 25 // response to the ResponseWriter as is expected that the client will 26 // do so when handling the error. The 'authenticated' is ignored. 27 // 28 // If no error is returned, but authentication or authorization fails, 29 // then authenticated must be false and error nil. It is expected that 30 // the implementation handles writing to the ResponseWriter in this 31 // case. 32 // 33 // Finally, if the authentication and authorization succeeds, then 34 // authenticated must be true and error nil. The request will continue 35 // to be processed. 36 AuthenticateGetInbox(c context.Context, w http.ResponseWriter, r *http.Request) (out context.Context, authenticated bool, err error) 37 // AuthenticateGetOutbox delegates the authentication of a GET to an 38 // outbox. 39 // 40 // Always called, regardless whether the Federated Protocol or Social 41 // API is enabled. 42 // 43 // If an error is returned, it is passed back to the caller of 44 // GetOutbox. In this case, the implementation must not write a 45 // response to the ResponseWriter as is expected that the client will 46 // do so when handling the error. The 'authenticated' is ignored. 47 // 48 // If no error is returned, but authentication or authorization fails, 49 // then authenticated must be false and error nil. It is expected that 50 // the implementation handles writing to the ResponseWriter in this 51 // case. 52 // 53 // Finally, if the authentication and authorization succeeds, then 54 // authenticated must be true and error nil. The request will continue 55 // to be processed. 56 AuthenticateGetOutbox(c context.Context, w http.ResponseWriter, r *http.Request) (out context.Context, authenticated bool, err error) 57 // GetOutbox returns the OrderedCollection inbox of the actor for this 58 // context. It is up to the implementation to provide the correct 59 // collection for the kind of authorization given in the request. 60 // 61 // AuthenticateGetOutbox will be called prior to this. 62 // 63 // Always called, regardless whether the Federated Protocol or Social 64 // API is enabled. 65 GetOutbox(c context.Context, r *http.Request) (vocab.ActivityStreamsOrderedCollectionPage, error) 66 // NewTransport returns a new Transport on behalf of a specific actor. 67 // 68 // The actorBoxIRI will be either the inbox or outbox of an actor who is 69 // attempting to do the dereferencing or delivery. Any authentication 70 // scheme applied on the request must be based on this actor. The 71 // request must contain some sort of credential of the user, such as a 72 // HTTP Signature. 73 // 74 // The gofedAgent passed in should be used by the Transport 75 // implementation in the User-Agent, as well as the application-specific 76 // user agent string. The gofedAgent will indicate this library's use as 77 // well as the library's version number. 78 // 79 // Any server-wide rate-limiting that needs to occur should happen in a 80 // Transport implementation. This factory function allows this to be 81 // created, so peer servers are not DOS'd. 82 // 83 // Any retry logic should also be handled by the Transport 84 // implementation. 85 // 86 // Note that the library will not maintain a long-lived pointer to the 87 // returned Transport so that any private credentials are able to be 88 // garbage collected. 89 NewTransport(c context.Context, actorBoxIRI *url.URL, gofedAgent string) (t Transport, err error) 90 }