Skip to content

Extensions

Warning

Still experimental

Types of extensions

cattle_grid supports different types of extensions:

  • Lookup extensions: Retrieves stuff
  • Transform extensions: Takes data and harmonizes the format / adds information
  • Processing extensions: When an activity is received or send, the extension does something
  • API extensions: Provide something accessible via HTTP

Combining these types of extension is possible.

Info

I might add a transform extension for outgoing messages. Similarly, a transform extension for messages just about to be send. This would allow one to do remote instance specific transformations.

Types of subscriptions

Extensions can define new topics, and then perform an action when a message is received. These actions should be either to change the state of the extension, e.g. update its database, or send new messages. These messages should be send to existing topics. Extensions should not send to incoming.# (as it is reserved for messages received form the Fediverse), not should they send to outgoing.#, instead they should send to send_message, which will ensure proper distribution to outgoing.#.

However, extensions should subscribe to outgoing.# and incoming.# to process messages.

Writing an extension

The basic implementation will be

from cattle_grid.extensions import Extension

def factory(config: dict) -> Extension:
    ...

By writing something as a cattle_grid extension, you can first through the lookup and transform method influence cattle_grid’s behavior to e.g.

  • serve archived activities (e.g. from a migrated account)
  • add information to activities, e.g. label them

Configuring extensions

Extensions are configured in cattle_grid.toml by adding an entry of the form

[[extensions]]

module_name = "your.extension"
config = { var = 1}

lookup_order = 2

The factory method in the python module your.extension will be called with the contents config as an argument.