inbox

README

Hannibal / inbox

The Inbox library gives you: 1) an ActivityPub inbox handler that parses and validates incoming ActivityPub messages, and 2) a router that identifies messages by their type and object, and routes them to the correct business logic in your application

// Set up handlers for different kinds of activities and documents
activityHandler := inbox.NewRouter[CustomContextType]()

// Here's a handler to accept Create/Note messages
activityHandler.Add(vocab.ActivityTypeCreate, vocab.ObjectTypeNote, func(context CustomContextType, activity streams.Document) error {
	// do something with the activity
})

// You can do wildcards too.  Here's a handler to accept 
// Follow/Any messages
activityHandler.Add(vocab.ActivityTypeFollow, vocab.Any, func(context CustomContextType, activity streams.Document) error {
	// do something with the follow request.
	// remember to send an "Accept" message back to the sender
})

// Here's a catch-all handler that receives any uncaught messages
activityHandler.Add(vocab.Any, vocab.Any, func(context CustomContextType, activity streams.Document) error {
	// do something with this activity
})

// Add routes to your web server
myAppRouter.POST("/my/inbox",func (r *http.Request, w *http.Response) {

	// Parse and validate the posted activity
	activity, err := pub.ReceiveRequest(r)
	
	// Handle errors however you like
	if err != nil {
		...
	}

	context := // create custom "Context" value for this request
	
	// Pass the activity to the activityHandler, that will figure
	// out what kind of activity/object we have and pass it to the 
	// previously registered handler function
	if err := activityHandler.Handle(context, actitity); err != nil {
		// do something with the error
	}
	
	// Success!
}

Documentation

Index

• func ReceiveRequest(request *http.Request, client streams.Client, options ...Option) (document streams.Document, err error)
• type Option
  • func WithValidators(validators ...Validator) Option
• type ReceiveConfig
  • func NewReceiveConfig(options ...Option) ReceiveConfig
• type RouteHandler
• type Router
  • func NewRouter[T any]() Router[T]
  • func (router *Router[T]) Add(activityType string, objectType string, routeHandler RouteHandler[T])
  • func (router *Router[T]) Handle(context T, activity streams.Document) error
• type Validator

Functions

func ReceiveRequest

func ReceiveRequest(request *http.Request, client streams.Client, options ...Option) (document streams.Document, err error)

ReceiveRequest reads an incoming HTTP request and returns a parsed and validated ActivityPub activity

Types

type Option

type Option func(*ReceiveConfig)

func WithValidators

func WithValidators(validators ...Validator) Option

type ReceiveConfig

type ReceiveConfig struct {
	Validators []Validator
}

ReceiveConfig is a configuration object for the `ReceiveRequest` function.

func NewReceiveConfig

func NewReceiveConfig(options ...Option) ReceiveConfig

NewReceiveConfig creates a new ReceiveConfig object with default settings, and applies any provided options to override the defaults.

type RouteHandler

type RouteHandler[T any] func(context T, activity streams.Document) error

RouteHandler is a function that handles a specific type of ActivityPub activity. RouteHandlers are registered with the Router object along with the names of the activity types that they correspond to.

type Router

type Router[T any] struct {
	// contains filtered or unexported fields
}

Router is a simple object that routes incoming ActivityPub activities to the appropriate handler

func NewRouter

func NewRouter[T any]() Router[T]

NewRouter creates a new Router object

func (*Router[T]) Add

func (router *Router[T]) Add(activityType string, objectType string, routeHandler RouteHandler[T])

Add puts a new route to the router. You can use "*" as a wildcard for either the activityType or objectType. The Handler method tries to match handlers from most specific to least specific. activity/object activity/* */object */*

For performance reasons, this function is not thread-safe. So, you should add all routes before starting the server, for instance, in your app's `init` functions.

func (*Router[T]) Handle

func (router *Router[T]) Handle(context T, activity streams.Document) error

Handle takes an ActivityPub activity and routes it to the appropriate handler

type Validator

type Validator interface {

	// Validate checks incoming HTTP requests for validity.  If a document is
	// valid, it returns `ResultValid`.  If the Validator cannot validate this
	// document, it returns `ResultUnknown`. If the Validator can say with
	// certainty that the document is invalid, it returns `ResultInvalid`.
	Validate(*http.Request, *streams.Document) validator.Result
}

Validator interface wraps the Validate method, which identifies whether a document received in an actor's inbox is valid or not. Multiple validators can be stacked to validate a document, so if one validator returns `false`, the document is not necessary invalid. It just can't be validated by this one validator.