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

extension = Extension("some name", __name__)

...

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

Running extensions

In order to test extensions, one might want to run these using a separate process. This can be achieved by running

python -m cattle_grid.extensions run your.extension.module

See below for further details on this command.

Warning

This only works for processing and API extensions. Transformation and lookup extensions are called by cattle_grid directly.

We note here that the configuration will be loaded through the same mechanism as cattle_grid does. This is in particular relevant for accessing the database and the RabbitMQ router.

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.

python -m cattle_grid.extensions

Tooling for managing extensions

Usage:

python -m cattle_grid.extensions [OPTIONS] COMMAND [ARGS]...

Options:

Name Type Description Default
--help boolean Show this message and exit. False

Subcommands

  • async-api: Generates the async api schema for the extension
  • load: Loads an extension
  • openapi: Generates the openapi schema for the extension
  • run: Runs the extension as an independent server process.

python -m cattle_grid.extensions async-api

Generates the async api schema for the extension

Usage:

python -m cattle_grid.extensions async-api [OPTIONS] MODULE

Options:

Name Type Description Default
--help boolean Show this message and exit. False

python -m cattle_grid.extensions load

Loads an extension

Usage:

python -m cattle_grid.extensions load [OPTIONS] MODULE

Options:

Name Type Description Default
--help boolean Show this message and exit. False

python -m cattle_grid.extensions openapi

Generates the openapi schema for the extension

Usage:

python -m cattle_grid.extensions openapi [OPTIONS] MODULE

Options:

Name Type Description Default
--filename text Filename to write to None
--help boolean Show this message and exit. False

python -m cattle_grid.extensions run

Runs the extension as an independent server process. The configuration is taken from the same files as cattle_grid. Thus these must be present.

Usage:

python -m cattle_grid.extensions run [OPTIONS] MODULE

Options:

Name Type Description Default
--host text Host to run on 0.0.0.0
--port integer Port to run on 80
--reload_dir text Reload on changes in directory None
--no_broker boolean Set to run without included broker False
--help boolean Show this message and exit. False