federails

Federails

Federails is an engine that brings ActivityPub to Ruby on Rails application.

Community

You can join the matrix chat room to chat with humans.

Open issues or feature requests on the issue tracker

Features

This engine is meant to be used in Rails applications to add the ability to act as an ActivityPub server.

As the project is in an early stage of development we're unable to provide a clean list of what works and what is missing.

The general direction is to be able to:

• publish and subscribe to any type of content
• have a discovery endpoint (webfinger)
• have a following/followers system
• implement all the parts of the (RFC) labelled with MUST and MUST NOT
• implement some or all the parts of the RFC labelled with SHOULD and SHOULD NOT
• maybe implement the parts of the RFC labelled with MAY

Installation

Add this line to your application's Gemfile:

gem "federails"

And then execute:

$ bundle

Configuration

Generate configuration files:

bundle exec rails generate federails:install

It creates an initializer and a configuration file:

• config/initializers/federails.rb
• config/federails.yml

By default, Federails is configured using config_from method, that loads the appropriate YAML file, but you may want to configure it differently:

# config/initializers/federails.rb
Federails.configure do |config|
  config.host = 'localhost'
  # ...
end

For now, refer to the source code for the full list of options.

Routes

Mount the engine on /: routes to /.well-known/* and /nodeinfo/* must be at the root of the site. Federails routes are then available under the configured path (routes_path):

# config/routes.rb
mount Federails::Engine => '/'

With routes_path = 'federation', routes will be:

/.well-known/webfinger(.:format)
/.well-known/host-meta(.:format)
/.well-known/nodeinfo(.:format)
/nodeinfo/2.0(.:format)
/federation/actors/:id/followers(.:format)
/federation/actors/:id/following(.:format)
/federation/actors/:actor_id/outbox(.:format)
/federation/actors/:actor_id/inbox(.:format)
/federation/actors/:actor_id/activities/:id(.:format)
/federation/actors/:actor_id/followings/:id(.:format)
/federation/actors/:actor_id/notes/:id(.:format)
/federation/actors/:id(.:format)
...

Some routes can be disabled in configuration if you don't want to expose particular features:

Federails.configure do |config|
  # Disable routing for .well-known and nodeinfo
  config.enable_discovery = false

  # Disable web client UI routes
  config.client_routes_path = nil
end

Remote following

By default, remote follow requests (where you press a follow button on another server and get redirected home to complete the follow) will use the built-in client paths. If you're not using the client, or want to provide your own user interface, you can set the path like this, assuming that new_follow_url is a valid route in your app. A uri query parameter template will be automatically appended, you don't need to specify that.

Federails.configure do |config|
  config.remote_follow_url_method = :new_follow_url
end

Migrations

Copy the migrations:

bundle exec rails federails:install:migrations

User model

In the ActivityPub world, we refer to actors to represent the thing that publishes or subscribe to other actors.

Federails provides a concern to include in your "user" model or whatever will publish data:

# app/models/user.rb

class User < ApplicationRecord
  # Include the concern here:
  include Federails::ActorEntity

  # Configure field names
  acts_as_federails_actor username_field: :username, name_field: :name, profile_url_method: :user_url
end

This concern automatically create a Federails::Actor after a user creation, as well as the actor reference. When adding it to an existing model with existing data, you will need to generate the corresponding actors yourself in a migration.

Usage example:

actor = User.find(1).federails_actor

actor.inbox
actor.outbox
actor.followers
actor.following
#...

Using the Federails client

Federails comes with a client, enabled by default, that provides basic views to display and interact with Federails data, accessible on /app by default (changeable with the configuration option client_routes_path)

If it's a good starting point, it might be disabled once you made your own integration by setting client_routes_path to a nil value.

If you want to override the client's views, copy them in your application:

rails generate federails:copy_client_views

Common questions

• I override the base controller and the links breaks in my layout

  Use main_app.<url_helper> for links to your application; federails.<federails_url_helper> for links to the Federails client.

• I specified a custom layout and the links breaks in it

  Use main_app.<url_helper> for links to your application; federails.<federails_url_helper> for links to the Federails client.

• I specified a custom layout and my helpers are not available

  You will have better results if you specify a base_controller from your application as Federails base controller is isolated from the main app and does not have access to its helpers.

Contributing

Contributions are welcome, may it be issues, ideas, code or whatever you want to share. Please note:

• This project is fast forward only: we don't do merge commits
• We adhere to semantic versioning. Please update the changelog in your commits
• We try to adhere to conventional commits principles
• We may rename your commits before merging them
• We may split your commits before merging them

To contribute:

1. Fork this repository
2. Create small commits
3. Ideally create small pull requests. Don't hesitate to open them early so we all can follow how it's going
4. Get congratulated

Tooling

RSpec

RSpec is the test suite. Start it with

bundle exec rspec

Rubocop

Rubocop is a linter. Start it with

bundle exec rubocop

FactoryBot

FactoryBot is a factory generator used in tests and development. A rake task checks the replayability of the factories and traits:

bundle exec app:factory_bot:lint

License

The gem is available as open source under the terms of the MIT License.