federating_protocol.go (5832B)
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 // FederatingProtocol contains behaviors an application needs to satisfy for the 12 // full ActivityPub S2S implementation to be supported by this library. 13 // 14 // It is only required if the client application wants to support the server-to- 15 // server, or federating, protocol. 16 // 17 // It is passed to the library as a dependency injection from the client 18 // application. 19 type FederatingProtocol interface { 20 // Hook callback after parsing the request body for a federated request 21 // to the Actor's inbox. 22 // 23 // Can be used to set contextual information based on the Activity 24 // received. 25 // 26 // Only called if the Federated Protocol is enabled. 27 // 28 // Warning: Neither authentication nor authorization has taken place at 29 // this time. Doing anything beyond setting contextual information is 30 // strongly discouraged. 31 // 32 // If an error is returned, it is passed back to the caller of 33 // PostInbox. In this case, the DelegateActor implementation must not 34 // write a response to the ResponseWriter as is expected that the caller 35 // to PostInbox will do so when handling the error. 36 PostInboxRequestBodyHook(c context.Context, r *http.Request, activity Activity) (context.Context, error) 37 // AuthenticatePostInbox delegates the authentication of a POST to an 38 // inbox. 39 // 40 // If an error is returned, it is passed back to the caller of 41 // PostInbox. In this case, the implementation must not write a 42 // response to the ResponseWriter as is expected that the client will 43 // do so when handling the error. The 'authenticated' is ignored. 44 // 45 // If no error is returned, but authentication or authorization fails, 46 // then authenticated must be false and error nil. It is expected that 47 // the implementation handles writing to the ResponseWriter in this 48 // case. 49 // 50 // Finally, if the authentication and authorization succeeds, then 51 // authenticated must be true and error nil. The request will continue 52 // to be processed. 53 AuthenticatePostInbox(c context.Context, w http.ResponseWriter, r *http.Request) (out context.Context, authenticated bool, err error) 54 // Blocked should determine whether to permit a set of actors given by 55 // their ids are able to interact with this particular end user due to 56 // being blocked or other application-specific logic. 57 // 58 // If an error is returned, it is passed back to the caller of 59 // PostInbox. 60 // 61 // If no error is returned, but authentication or authorization fails, 62 // then blocked must be true and error nil. An http.StatusForbidden 63 // will be written in the wresponse. 64 // 65 // Finally, if the authentication and authorization succeeds, then 66 // blocked must be false and error nil. The request will continue 67 // to be processed. 68 Blocked(c context.Context, actorIRIs []*url.URL) (blocked bool, err error) 69 // FederatingCallbacks returns the application logic that handles 70 // ActivityStreams received from federating peers. 71 // 72 // Note that certain types of callbacks will be 'wrapped' with default 73 // behaviors supported natively by the library. Other callbacks 74 // compatible with streams.TypeResolver can be specified by 'other'. 75 // 76 // For example, setting the 'Create' field in the 77 // FederatingWrappedCallbacks lets an application dependency inject 78 // additional behaviors they want to take place, including the default 79 // behavior supplied by this library. This is guaranteed to be compliant 80 // with the ActivityPub Social protocol. 81 // 82 // To override the default behavior, instead supply the function in 83 // 'other', which does not guarantee the application will be compliant 84 // with the ActivityPub Social Protocol. 85 // 86 // Applications are not expected to handle every single ActivityStreams 87 // type and extension. The unhandled ones are passed to DefaultCallback. 88 FederatingCallbacks(c context.Context) (wrapped FederatingWrappedCallbacks, other []interface{}, err error) 89 // DefaultCallback is called for types that go-fed can deserialize but 90 // are not handled by the application's callbacks returned in the 91 // Callbacks method. 92 // 93 // Applications are not expected to handle every single ActivityStreams 94 // type and extension, so the unhandled ones are passed to 95 // DefaultCallback. 96 DefaultCallback(c context.Context, activity Activity) error 97 // MaxInboxForwardingRecursionDepth determines how deep to search within 98 // an activity to determine if inbox forwarding needs to occur. 99 // 100 // Zero or negative numbers indicate infinite recursion. 101 MaxInboxForwardingRecursionDepth(c context.Context) int 102 // MaxDeliveryRecursionDepth determines how deep to search within 103 // collections owned by peers when they are targeted to receive a 104 // delivery. 105 // 106 // Zero or negative numbers indicate infinite recursion. 107 MaxDeliveryRecursionDepth(c context.Context) int 108 // FilterForwarding allows the implementation to apply business logic 109 // such as blocks, spam filtering, and so on to a list of potential 110 // Collections and OrderedCollections of recipients when inbox 111 // forwarding has been triggered. 112 // 113 // The activity is provided as a reference for more intelligent 114 // logic to be used, but the implementation must not modify it. 115 FilterForwarding(c context.Context, potentialRecipients []*url.URL, a Activity) (filteredRecipients []*url.URL, err error) 116 // GetInbox returns the OrderedCollection inbox of the actor for this 117 // context. It is up to the implementation to provide the correct 118 // collection for the kind of authorization given in the request. 119 // 120 // AuthenticateGetInbox will be called prior to this. 121 // 122 // Always called, regardless whether the Federated Protocol or Social 123 // API is enabled. 124 GetInbox(c context.Context, r *http.Request) (vocab.ActivityStreamsOrderedCollectionPage, error) 125 }