federails 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3463b1a877ca8224ade011016236c1fdbcbe41e31712b609347f41592d30531
-  data.tar.gz: 16ec7975b26bc5fbec1e243a4653c27d8b0239c7dbda42544150c9e5680d65f5
+  metadata.gz: 9e6d475999161590317e4a038b44829fdae2a44ccb007b03f24c240fccfa0771
+  data.tar.gz: b2266e7c4e9ac8c68177e2b17fc2e74afab52fc0e93607943716e06b39c10f6d
 SHA512:
-  metadata.gz: b54850967223bb1be7aadd54547f757a9e5fbe6ccc8d84249a4a2b340a494b275905c25e862c493b2d2b177a7cc5e12abf2d6e44c4f84b4bec76796a7b9cba5f
-  data.tar.gz: cc00b05153d4434eacc6409a4422575d5e851e07c332001a72fc818e5f64d1bf6f2cd35f6eaa5f4025b3150fe9009a370665a044d44f84a60399690186a8f5e8
+  metadata.gz: 14c482129bac20d5dfdaa2fa498070ab215819a0fe6af6499e268d631f40a7c15ee3341e999e6b0bfee5fd997b7a41f879c35537aeebbfbbdfc6182289d5edf4
+  data.tar.gz: 0c6fe55888c7b31f93958e258ad4b137aa305269056b2b512af2a137e2a15ac6de36a0a83f7fbec436c6657fca3c4ad9c18c08bb46a93e48601ef226c9a0011c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Experiments Labs / Experimentations
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -23,206 +23,11 @@ The general direction is to be able to:
 - 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
+## Documentation
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem "federails"
-```
-
-And then execute:
-
-```bash
-$ bundle
-```
-
-### Configuration
-
-Generate configuration files:
-
-```sh
-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:
-
-```rb
-# config/initializers/federails.rb
-Federails.configure do |config|
-  config.host = 'localhost'
-  # ...
-end
-```
-
-For now, refer to [the source code](lib/federails/configuration.rb) 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`):
-
-```rb
-# config/routes.rb
-mount Federails::Engine => '/'
-```
-
-With `routes_path = 'federation'`, routes will be:
-
-```txt
-/.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:
-
-```rb
-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.
-
-```rb
-Federails.configure do |config|
-  config.remote_follow_url_method = :new_follow_url
-end
-```
-
-### Migrations
-
-Copy the migrations:
-
-```sh
-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:
-
-```rb
-# 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:
-
-```rb
-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:
-
-```sh
-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](https://www.conventionalcommits.org/en/v1.0.0/) 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
-
-```sh
-bundle exec rspec
-```
-
-#### Rubocop
-
-Rubocop is a linter. Start it with
-
-```sh
-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:
-
-```sh
-bundle exec app:factory_bot:lint
-```
+- [Usage](docs/usage.md)
+- [Common questions](docs/faq.md)
+- [Contributing](docs/contributing.md)
 
 ## License
 

data/app/controllers/federails/server/published_controller.rb

@@ -0,0 +1,30 @@
+module Federails
+  module Server
+    # Controller to render ActivityPub representation of entities configured with Federails::DataEntity
+    class PublishedController < Federails::ServerController
+      def show
+        @publishable = type_scope.find_by!(url_param => params[:id])
+        authorize @publishable, policy_class: Federails::Server::PublishablePolicy
+      end
+
+      private
+
+      def publishable_config
+        return @publishable_config if instance_variable_defined? :@publishable_config
+
+        _, @publishable_config = Federails.configuration.data_types.find { |_, v| v[:route_path_segment].to_s == params[:publishable_type] }
+        raise ActiveRecord::RecordNotFound, "Invalid #{params[:publishable_type]} type" unless @publishable_config
+
+        @publishable_config
+      end
+
+      def url_param
+        publishable_config[:url_param]
+      end
+
+      def type_scope
+        publishable_config[:class].all
+      end
+    end
+  end
+end

data/app/models/concerns/federails/actor_entity.rb

@@ -1,51 +1,45 @@
 module Federails
+  # Concern to include in models that acts as actors.
+  #
+  # Actors can be anything; they authors content _via_ their _outbox_ and receive content in their _inbox_.
+  # Actors can follow and be followed by each other
+  #
+  # By default, when an entry is created on models using this concern, a _local_ `Federails::Actor` will be created.
+  #
+  # See also:
+  #  - https://www.w3.org/TR/activitypub/#actor-objects
+  #
+  # ## Usage
+  #
+  # Include the concern in an existing model:
+  #
+  # ```rb
+  # class User < ApplicationRecord
+  #   include Federails::ActorEntity
+  #   acts_as_federails_actor options
+  # end
+  # ```
   module ActorEntity
     extend ActiveSupport::Concern
 
-    included do # rubocop:todo Metrics/BlockLength
-      include ActiveSupport::Callbacks
-      define_callbacks :followed
-
-      # Define a method that will be called after the entity receives a follow request
-      # @param method [Symbol] The name of the method to call, or a block that will be called directly
-      # @example
-      #   after_followed :accept_follow
-      def self.after_followed(method)
-        set_callback :followed, :after, method
-      end
-
-      # Define a method that will be called after an activity has been received
-      # @param activity_type [String] The activity action to handle, e.g. 'Create'. If you specify '*', the handler will be called for any activity type.
-      # @param object_type [String] The object type to handle, e.g. 'Note'. If you specify '*', the handler will be called for any object type.
-      # @param method [Symbol] The name of the class method to call. The method will receive the complete activity payload as a parameter.
-      # @example
-      #   after_activity_received 'Create', 'Note', :create_note
-      def self.after_activity_received(activity_type, object_type, method)
-        Fediverse::Inbox.register_handler(activity_type, object_type, self, method)
-      end
-
-      has_one :federails_actor, class_name: 'Federails::Actor', as: :entity, dependent: :destroy
-
-      after_create :create_federails_actor, if: lambda {
-        raise("Entity not configured for #{self.class.name}. Did you use \"acts_as_federails_actor\"?") unless Federails.actor_entity? self
-
-        Federails.actor_entity(self)[:auto_create_actors]
-      }
-
+    # Class methods automatically included in the concern.
+    module ClassMethods
       # Configures the mapping between entity and actor
+      #
       # @param username_field [Symbol] The method or attribute name that returns the preferred username for ActivityPub
       # @param name_field [Symbol] The method or attribute name that returns the preferred name for ActivityPub
       # @param profile_url_method [Symbol] The route method name that will generate the profile URL for ActivityPub
       # @param actor_type [String] The ActivityStreams Actor type for this entity; defaults to 'Person'
       # @param user_count_method [Symbol] A class method to call to count active users. Leave unspecified to leave this
-      #  entity out of user counts. Method signature should accept a single parameter which will specify a date range
-      #  If parameter is nil, the total user count should be returned. If the parameter is specified, the number of users
-      #  active during the time period should be returned.
+      #   entity out of user counts. Method signature should accept a single parameter which will specify a date range
+      #   If parameter is nil, the total user count should be returned. If the parameter is specified, the number of users
+      #   active during the time period should be returned.
       # @param auto_create_actors [Boolean] Whether to automatically create an actor when the entity is created
+      #
       # @example
       #   acts_as_federails_actor username_field: :username, name_field: :display_name, profile_url_method: :url_for, actor_type: 'Person'
       # rubocop:disable Metrics/ParameterLists
-      def self.acts_as_federails_actor(
+      def acts_as_federails_actor(
         name_field:,
         username_field:,
         profile_url_method: nil,
@@ -65,34 +59,72 @@ module Federails
       end
       # rubocop:enable Metrics/ParameterLists
 
-      # Add custom data to actor responses.
-      # Override in your own model to add extra data, which will be merged into the actor response
-      # generated by Federails. You can include extra `@context` for activitypub extensions and it will
-      # be merged with the main response context.
+      # Define a method that will be called after the entity receives a follow request
+      #
+      # @param method_name [Symbol] The name of the method to call, or a block that will be called directly
+      #
       # @example
-      #   def to_activitypub_object
-      #     {
-      #       "@context": {
-      #         toot: "http://joinmastodon.org/ns#",
-      #         attributionDomains: {
-      #           "@id": "toot:attributionDomains",
-      #           "@type": "@id"
-      #         }
-      #       },
-      #       attributionDomains: [
-      #         "example.com"
-      #       ]
-      #     }
-      #   end
-      def to_activitypub_object
-        {}
+      #   after_followed :accept_follow
+      def after_followed(method_name)
+        set_callback :followed, :after, method_name
       end
 
-      private
-
-      def create_federails_actor
-        Federails::Actor.create! entity: self
+      # Define a method that will be called after an activity has been received
+      #
+      # @param activity_type [String] The activity action to handle, e.g. 'Create'. If you specify '*', the handler will be called for any activity type.
+      # @param object_type [String] The object type to handle, e.g. 'Note'. If you specify '*', the handler will be called for any object type.
+      # @param method_name [Symbol] The name of the class method to call. The method will receive the complete activity payload as a parameter.
+      #
+      # @example
+      #   after_activity_received 'Create', 'Note', :create_note
+      def after_activity_received(activity_type, object_type, method_name)
+        Fediverse::Inbox.register_handler(activity_type, object_type, self, method_name)
       end
     end
+
+    included do
+      include ActiveSupport::Callbacks
+
+      define_callbacks :followed
+
+      has_one :federails_actor, class_name: 'Federails::Actor', as: :entity, dependent: :destroy
+
+      after_create :create_federails_actor, if: lambda {
+        raise("Entity not configured for #{self.class.name}. Did you use \"acts_as_federails_actor\"?") unless Federails.actor_entity? self
+
+        Federails.actor_entity(self)[:auto_create_actors]
+      }
+    end
+
+    # Add custom data to actor responses.
+    #
+    # Override in your own model to add extra data, which will be merged into the actor response
+    # generated by Federails. You can include extra `@context` for activitypub extensions and it will
+    # be merged with the main response context.
+    #
+    # @example
+    #   def to_activitypub_object
+    #     {
+    #       "@context": {
+    #         toot: "http://joinmastodon.org/ns#",
+    #         attributionDomains: {
+    #           "@id": "toot:attributionDomains",
+    #           "@type": "@id"
+    #         }
+    #       },
+    #       attributionDomains: [
+    #         "example.com"
+    #       ]
+    #     }
+    #   end
+    def to_activitypub_object
+      {}
+    end
+
+    private
+
+    def create_federails_actor
+      Federails::Actor.create! entity: self
+    end
   end
 end

data/app/models/concerns/federails/data_entity.rb

@@ -0,0 +1,178 @@
+require 'fediverse/inbox'
+
+module Federails
+  # Model concern to include in models for which data is pushed to the Fediverse and comes from the Fediverse.
+  #
+  # Once included, an activity will automatically be created upon
+  #   - entity creation
+  #   - entity updates
+  #
+  # Also, when properly configured, a handler is registered to transform incoming objects and create/update entities
+  # accordingly.
+  #
+  # ## Pre-requisites
+  #
+  # Model must have a `federated_url` attribute:
+  # ```rb
+  # add_column :posts, :federated_url, :string, null: true, default: nil
+  # ```
+  #
+  # ## Usage
+  #
+  # Include the concern in an existing model:
+  #
+  # ```rb
+  # class Post < ApplicationRecord
+  #   include Federails::DataEntity
+  #   acts_as_federails_data options
+  # end
+  # ```
+  module DataEntity
+    extend ActiveSupport::Concern
+
+    # Class methods automatically included in the concern.
+    module ClassMethods
+      # Configures the mapping between entity and Fediverse
+      #
+      # Model should have the following methods:
+      # - `to_activitypub_object`, returning a valid ActivityPub object
+      #
+      # @param actor_entity_method [Symbol] Method returning an object responding to 'federails_actor', for local content
+      # @param url_param [Symbol] Column name of the object ID that should be used in URLs. Defaults to +:id+
+      # @param route_path_segment [Symbol] Segment used in Federails routes to display the ActivityPub representation.
+      #   Defaults to the pluralized, underscored class name
+      # @param handles [String] Type of ActivityPub object handled by this entity type
+      # @param with [Symbol] Self class method that will handle incoming objects. Defaults to +:handle_incoming_fediverse_data+
+      # @param filter_method [Symbol] Self class method that determines if an incoming object should be handled. Note
+      #   that the first model for which this method returns true will be used. If left empty, the model CAN be selected,
+      #   so define them if many models handle the same data type.
+      # @param should_federate_method [Symbol] method to determine if an object should be federated. If the method returns false,
+      #   no create/update activities will happen, and object will not be accessible at federated_url. Defaults to a method
+      #   that always returns true.
+      #
+      # @example
+      #   acts_as_federails_data handles: 'Note', with: :note_handler, route_path_segment: :articles, actor_entity_method: :user
+      # rubocop:disable Metrics/ParameterLists
+      def acts_as_federails_data(
+        handles:,
+        with: :handle_incoming_fediverse_data,
+        route_path_segment: nil,
+        actor_entity_method: nil,
+        url_param: :id,
+        filter_method: nil,
+        should_federate_method: :default_should_federate?
+      )
+        route_path_segment ||= name.pluralize.underscore
+
+        Federails::Configuration.register_data_type self,
+                                                    route_path_segment:     route_path_segment,
+                                                    actor_entity_method:    actor_entity_method,
+                                                    url_param:              url_param,
+                                                    handles:                handles,
+                                                    with:                   with,
+                                                    filter_method:          filter_method,
+                                                    should_federate_method: should_federate_method
+
+        Fediverse::Inbox.register_handler 'Create', handles, self, with
+        Fediverse::Inbox.register_handler 'Update', handles, self, with
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # Instantiates a new instance from an ActivityPub object
+      #
+      # @param activitypub_object [Hash]
+      #
+      # @return [self]
+      def new_from_activitypub_object(activitypub_object)
+        new from_activitypub_object(activitypub_object)
+      end
+
+      # Creates or updates entity based on the ActivityPub activity
+      #
+      # @param activity_hash_or_id [Hash, String] Dereferenced activity hash or ID
+      #
+      # @return [self]
+      def handle_incoming_fediverse_data(activity_hash_or_id)
+        activity = Fediverse::Request.dereference(activity_hash_or_id)
+        object = Fediverse::Request.dereference(activity['object'])
+
+        entity = Federails::Utils::Object.find_or_create!(object)
+
+        if activity['type'] == 'Update'
+          entity.assign_attributes from_activitypub_object(object)
+
+          # Use timestamps from attributes
+          entity.save! touch: false
+        end
+
+        entity
+      end
+    end
+
+    included do
+      belongs_to :federails_actor, class_name: 'Federails::Actor'
+
+      scope :local_federails_entities, -> { where federated_url: nil }
+      scope :distant_federails_entities, -> { where.not(federated_url: nil) }
+
+      before_validation :set_federails_actor
+      after_create :create_federails_activity
+      after_update :update_federails_activity
+    end
+
+    # Computed value for the federated URL
+    #
+    # @return [String]
+    def federated_url
+      return nil unless send(federails_data_configuration[:should_federate_method])
+      return attributes['federated_url'] if attributes['federated_url'].present?
+
+      path_segment = Federails.data_entity_configuration(self)[:route_path_segment]
+      url_param = Federails.data_entity_configuration(self)[:url_param]
+      Federails::Engine.routes.url_helpers.server_published_url(publishable_type: path_segment, id: send(url_param))
+    end
+
+    # Check whether the entity was created locally or comes from the Fediverse
+    #
+    # @return [Boolean]
+    def local_federails_entity?
+      attributes['federated_url'].blank?
+    end
+
+    def federails_data_configuration
+      Federails.data_entity_configuration(self)
+    end
+
+    private
+
+    def set_federails_actor
+      return federails_actor if federails_actor.present?
+
+      self.federails_actor = send(federails_data_configuration[:actor_entity_method])&.federails_actor if federails_data_configuration[:actor_entity_method]
+
+      raise 'Cannot determine actor from configuration' unless federails_actor
+    end
+
+    def create_federails_activity
+      ensure_federails_configuration!
+      return unless local_federails_entity? && send(federails_data_configuration[:should_federate_method])
+
+      Activity.create! actor: federails_actor, action: 'Create', entity: self
+    end
+
+    def update_federails_activity
+      ensure_federails_configuration!
+      return unless local_federails_entity? && send(federails_data_configuration[:should_federate_method])
+
+      Activity.create! actor: federails_actor, action: 'Update', entity: self
+    end
+
+    def ensure_federails_configuration!
+      raise("Entity not configured for #{self.class.name}. Did you use \"acts_as_federails_data\"?") unless Federails.data_entity? self
+    end
+
+    def default_should_federate?
+      true
+    end
+  end
+end

data/app/models/concerns/federails/has_uuid.rb

@@ -1,4 +1,28 @@
 module Federails
+  # Model concern providing UUIDs as model parameter (instead of IDs).
+  #
+  #
+  # A _required_, `uuid` field is required on the model's table for this concern to work:
+  #
+  # ```rb
+  # # Example migration
+  # add_column :my_table, :uuid, :text, default: nil, index: { unique: true }
+  # ```
+  #
+  # Usage:
+  #
+  # ```rb
+  # class MyModel < ApplicationRecord
+  #   include Federails::HasUuid
+  # end
+  #
+  # # And now:
+  # instance = MyModel.find_param 'aaaa_bbbb_cccc_dddd_....'
+  # instance.to_param
+  # # => 'aaaa_bbbb_cccc_dddd_....'
+  # ```
+  #
+  # It can be added on existing tables without data migration as the `uuid` accessor will generate the value when missing.
   module HasUuid
     extend ActiveSupport::Concern
 
@@ -11,12 +35,14 @@ module Federails
       end
     end
 
+    # @return [String] The UUID
     def to_param
       uuid
     end
 
-    # Override UUID accessor to provide lazy initialization of UUIDs for old data
+    # @return [String]
     def uuid
+      # Override UUID accessor to provide lazy initialization of UUIDs for old data
       if self[:uuid].blank?
         generate_uuid
         save!

data/app/models/federails/activity.rb

@@ -1,4 +1,13 @@
 module Federails
+  # Activities can be compared to a log of what happened in the Fediverse.
+  #
+  # Activities from local actors ends in the actors _outboxes_.
+  # Activities form distant actors comes from the actor's _inbox_.
+  # We try to only keep activities _from_ local actors, and external activities _targetting_ local actors.
+  #
+  # See also:
+  #   - https://www.w3.org/TR/activitypub/#outbox
+  #   - https://www.w3.org/TR/activitypub/#inbox
   class Activity < ApplicationRecord
     include Federails::HasUuid
 
@@ -15,6 +24,9 @@ module Federails
 
     after_create_commit :post_to_inboxes
 
+    # Determines the list of actors targeted by the activity
+    #
+    # @return [Array<Federails::Actor>]
     def recipients
       return [] unless actor.local?
 

data/app/models/federails/actor.rb

@@ -2,6 +2,12 @@ require 'federails/utils/host'
 require 'fediverse/webfinger'
 
 module Federails
+  # Model storing _distant_ actors and links to local ones.
+  #
+  # To make a model act as an actor, use the `Federails::ActorEntity` concern
+  #
+  # See also:
+  #  - https://www.w3.org/TR/activitypub/#actor-objects
   class Actor < ApplicationRecord # rubocop:disable Metrics/ClassLength
     include Federails::HasUuid
 
@@ -25,6 +31,7 @@ module Federails
     has_many :follows, source: :target_actor, through: :following_follows
 
     scope :local, -> { where.not(entity: nil) }
+    scope :distant, -> { where.not(federated_url: nil) }
 
     def local?
       entity.present?

data/app/models/federails/following.rb

@@ -1,4 +1,5 @@
 module Federails
+  # Stores following data between actors
   class Following < ApplicationRecord
     include Federails::HasUuid
 

data/app/policies/federails/server/publishable_policy.rb

@@ -0,0 +1,15 @@
+module Federails
+  module Server
+    class PublishablePolicy < Federails::FederailsPolicy
+      def show?
+        @record.send(@record.federails_data_configuration[:should_federate_method])
+      end
+
+      class Scope < Scope
+        def resolve
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/app/views/federails/server/published/_publishable.activitypub.jbuilder

@@ -0,0 +1,11 @@
+context = true unless context == false
+json.set! '@context', 'https://www.w3.org/ns/activitystreams' if context
+
+publishable.to_activitypub_object.each_pair do |key, value|
+  json.set! key, value
+end
+
+json.id publishable.federated_url
+json.actor publishable.federails_actor.federated_url
+json.to ['https://www.w3.org/ns/activitystreams#Public']
+json.cc [publishable.federails_actor.followers_url]

data/app/views/federails/server/published/show.activitypub.jbuilder

@@ -0,0 +1 @@
+json.partial! 'federails/server/published/publishable', publishable: @publishable

data/config/routes.rb

@@ -45,5 +45,9 @@ Federails::Engine.routes.draw do
       resources :activities, only: [:show]
       resources :followings, only: [:show]
     end
+
+    scope :published do
+      get ':publishable_type/:id', to: 'published#show', as: :published
+    end
   end
 end

data/lib/federails/configuration.rb

@@ -1,5 +1,7 @@
 module Federails
   # rubocop:disable Style/ClassVars
+
+  # Stores the Federails configuration in a _singleton_.
   module Configuration
     # Application name, used in well-known and nodeinfo endpoints
     mattr_accessor :app_name
@@ -45,7 +47,16 @@ module Federails
     mattr_accessor :base_client_controller
     @@base_client_controller = 'ActionController::Base'
 
+    # @!method self.remote_follow_url_method
+    #
     # Route method for remote-following requests
+
+    # @!method self.remote_follow_url_method=(value)
+    #
+    # Sets the route method for remote-following requests
+    # @param value [String] Route method name as used in links
+    # @example
+    #   remote_follow_url_method 'main_app.my_custom_route_helper'
     mattr_accessor :remote_follow_url_method
     @@remote_follow_url_method = 'federails.new_client_following_url'
 
@@ -66,6 +77,14 @@ module Federails
     def self.register_actor_class(klass, config = {})
       @@actor_types[klass.name] = config.merge(class: klass)
     end
+
+    # List of data types (classes using Federails::DataEntity)
+    mattr_reader :data_types
+    @@data_types = {}
+
+    def self.register_data_type(klass, config = {})
+      @@data_types[klass.name] = config.merge(class: klass)
+    end
   end
   # rubocop:enable Style/ClassVars
 end

data/lib/federails/data_transformer/note.rb

@@ -0,0 +1,31 @@
+module Federails
+  module DataTransformer
+    module Note
+      # Renders a Note. The entity is used to determine actor and generic fields data
+      #
+      # @param entity [#federail_actor] A model instance
+      # @param content [String] Note content
+      # @param name [String, nil] Optional name/title
+      # @param custom [Hash] Optional additional keys (e.g.: attachment, icon, ...). Defaults will override these.
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   Federails::DataTransformer::Note.to_federation(comment, content: comment.content, custom: { 'inReplyTo' => comment.parent.federated_url })
+      #
+      # See:
+      #   - https://www.w3.org/TR/activitystreams-vocabulary/#dfn-object
+      #   - https://www.w3.org/TR/activitystreams-vocabulary/#dfn-note
+      def self.to_federation(entity, content:, name: nil, custom: {})
+        custom.merge '@context'     => 'https://www.w3.org/ns/activitystreams',
+                     'id'           => entity.federated_url,
+                     'type'         => 'Note',
+                     'name'         => name,
+                     'content'      => content,
+                     'attributedTo' => entity.federails_actor.federated_url,
+                     'published'    => entity.created_at,
+                     'updated'      => entity.updated_at
+      end
+    end
+  end
+end

data/lib/federails/utils/object.rb

@@ -0,0 +1,106 @@
+module Federails
+  module Utils
+    # Methods to manipulate incoming objects
+    class Object
+      class << self
+        # Finds data from an object or its ID.
+        #
+        # When data exists locally, the entity is returned.
+        # For distant data, a new instance is returned unless the target does not exist.
+        #
+        # @param object_or_id [String, Hash] String identifier or incoming object
+        #
+        # @return [ApplicationRecord, nil] Entity or nil when invalid/not found
+        def find_or_initialize(object_or_id)
+          federated_url = object_or_id.is_a?(Hash) ? object_or_id['id'] : object_or_id
+
+          route = local_route(federated_url)
+          return from_local_route(route) if route
+
+          from_distant_server(object_or_id)
+        end
+
+        # Finds or initializes an entity from an ActivityPub object or id
+        #
+        # @see .find_or_initialize
+        #
+        # @param object_or_id [String, Hash] String identifier or incoming object
+        #
+        # @return [ApplicationRecord, nil] Entity or nil when invalid/not found
+        def find_or_initialize!(object_or_id)
+          entity = find_or_initialize object_or_id
+          raise ActiveRecord::RecordNotFound unless entity
+
+          entity
+        end
+
+        # Finds or create an entity from an ActivityPub object or id
+        #
+        # Note that the data transformer MUST return timestamps from the ActivityPub object if used on the model,
+        # as they won't be set automatically.
+        #
+        # @see .find_or_initialize!
+        #
+        # @param object_or_id [String, Hash] String identifier or incoming object
+        #
+        # @return [ApplicationRecord, nil] Entity or nil when invalid/not found
+        def find_or_create!(object_or_id)
+          entity = find_or_initialize! object_or_id
+          return entity if entity.persisted?
+
+          entity.save!(touch: false)
+          entity
+        end
+
+        # Returns the timestamps to use from an ActivityPub object
+        #
+        # @param hash [Hash] ActivityPub object
+        #
+        # @return [Hash] Hash with timestamps
+        def timestamp_attributes(hash)
+          {
+            created_at: hash['published'] ||= Time.current,
+            updated_at: hash['updated'].presence || hash['published'],
+          }
+        end
+
+        private
+
+        def local_route(url)
+          route = Utils::Host.local_route(url)
+
+          return nil unless route && route[:controller] == 'federails/server/published' && route[:action] == 'show'
+
+          route
+        end
+
+        def from_local_route(route)
+          config = Federails.data_entity_handled_on route[:publishable_type]
+          return unless config
+
+          config[:class]&.find_by(config[:url_param] => route[:id])
+        rescue ActiveRecord::RecordNotFound
+          nil
+        end
+
+        def from_distant_server(federated_url)
+          hash = Fediverse::Request.dereference(federated_url)
+          return unless hash
+
+          handler = Federails.data_entity_handler_for hash
+          return unless handler
+
+          entity = handler[:class].find_by federated_url: hash['id']
+          return entity if entity
+
+          entity = handler[:class].new_from_activitypub_object(hash)
+          return unless entity
+
+          entity.federails_actor = Federails::Actor.find_or_create_by_object hash['attributedTo'] if entity && !entity.federails_actor
+
+          entity
+        end
+      end
+    end
+  end
+end

data/lib/federails/version.rb

@@ -1,3 +1,3 @@
 module Federails
-  VERSION = '0.4.0'.freeze
+  VERSION = '0.5.0'.freeze
 end

data/lib/federails.rb

@@ -1,9 +1,14 @@
 require 'federails/version'
 require 'federails/engine'
 require 'federails/configuration'
+require 'federails/utils/object'
 
 # rubocop:disable Style/ClassVars
+
+# This module includes classes and methods related to Ruby on Rails: engine configuration, models, controllers, etc.
 module Federails
+  DEFAULT_DATA_FILTER_METHOD = :handle_federated_object?
+
   mattr_reader :configuration
   @@configuration = Configuration
 
@@ -49,6 +54,55 @@ module Federails
       Configuration.actor_types[klass]
     end
 
+    # @return [Boolean] True if the given model is a possible data entity
+    def data_entity?(class_or_instance)
+      Configuration.data_types.key? class_or_instance_name(class_or_instance)
+    end
+
+    # Finds configured data types from ActivityPub type
+    #
+    # @param type [String] ActivityPub object type, as configured with `:handles`
+    # @return [Array] List of data entity configurations
+    #
+    # @example
+    #   data_entity_handlers_for 'Note'
+    def data_entity_handlers_for(type)
+      Federails::Configuration.data_types.select { |_, v| v[:handles] == type }.map(&:last)
+    end
+
+    # Finds the configured handler for a given ActivityPub object
+    #
+    # @param hash [Hash] ActivityPub object hash
+    #
+    # @return [Hash, nil] Data entity configuration
+    def data_entity_handler_for(hash)
+      data_entity_handlers_for(hash['type']).find do |handler|
+        return true if !handler[:filter_method] && !handler[:class].respond_to?(DEFAULT_DATA_FILTER_METHOD)
+
+        handler[:class].send(handler[:filter_method] || DEFAULT_DATA_FILTER_METHOD, hash)
+      end
+    end
+
+    # Finds configured data type from route path segment
+    #
+    # @param route_path_segment [Symbol, String] Route path segment, as configured with `:route_path_segment`
+    # @return [Hash, nil] Entity configuration
+    #
+    # @example
+    #   data_entity_handled_on :articles
+    def data_entity_handled_on(route_path_segment)
+      route_path_segment = route_path_segment.to_sym
+      Federails::Configuration.data_types.find { |_, v| v[:route_path_segment] == route_path_segment }&.last
+    end
+
+    # @return [Hash] The configuration for the given data entity
+    def data_entity_configuration(class_or_instance)
+      klass = class_or_instance_name(class_or_instance)
+      raise "#{klass} is not a configured data entity" unless Configuration.data_types.key?(klass)
+
+      Configuration.data_types[klass]
+    end
+
     private
 
     # @return [String] Class name of the provided class or instance

data/lib/fediverse/inbox.rb

@@ -4,21 +4,32 @@ module Fediverse
   class Inbox
     @@handlers = {} # rubocop:todo Style/ClassVars
     class << self
+      # Registers a handler for incoming data
+      #
+      # @param activity_type [String] Target activity type ('Create', 'Follow', 'Like', ...)
+      #   See https://www.w3.org/TR/activitystreams-vocabulary/#activity-types for a list of common ones
+      # @param object_type [String] Type of the related object ('Article', 'Note', ...)
+      #   See https://www.w3.org/TR/activitystreams-vocabulary/#object-types for a list of common object types
+      # @param klass [String] Class handling the incoming object
+      # @param method [Symbol] Method in the class that will handle the object
       def register_handler(activity_type, object_type, klass, method)
         @@handlers[activity_type] ||= {}
         @@handlers[activity_type][object_type] ||= {}
         @@handlers[activity_type][object_type][klass] = method
       end
 
+      # Executes the registered handler for an incoming object
+      #
+      # @param payload [Hash] Dereferenced activity
       def dispatch_request(payload)
-        handlers = get_handlers(payload['type'], payload['object'].is_a?(Hash) ? payload.dig('object', 'type') : nil)
+        payload['object'] = Fediverse::Request.dereference(payload['object']) if payload.key? 'object'
+
+        handlers = get_handlers(payload['type'], payload.dig('object', 'type'))
         handlers.each_pair do |klass, method|
           klass.send method, payload
         end
         return true unless handlers.empty?
 
-        # FIXME: Fails silently
-        # raise NotImplementedError
         Rails.logger.debug { "Unhandled activity type: #{payload['type']}" }
         false
       end
@@ -40,7 +51,7 @@ module Fediverse
       end
 
       def handle_accept_request(activity)
-        original_activity = Request.get(activity['object'])
+        original_activity = Request.dereference(activity['object'])
 
         actor        = Federails::Actor.find_or_create_by_object original_activity['actor']
         target_actor = Federails::Actor.find_or_create_by_object original_activity['object']

data/lib/fediverse/notifier.rb

@@ -3,6 +3,9 @@ require 'fediverse/signature'
 module Fediverse
   class Notifier
     class << self
+      # Posts an activity to its recipients
+      #
+      # @param activity [Federails::Activity]
       def post_to_inboxes(activity)
         actors = activity.recipients
         Rails.logger.debug('Nobody to notice') && return if actors.count.zero?

data/lib/fediverse/request.rb

@@ -11,6 +11,7 @@ module Fediverse
       @id = id
     end
 
+    # FIXME: Replace by `Webfinger.get_json` (move other method here as class method)
     def get
       Rails.logger.debug { "GET #{@id}" }
       @response = Faraday.get(@id, nil, BASE_HEADERS)
@@ -21,6 +22,18 @@ module Fediverse
       def get(id)
         new(id).get
       end
+
+      # Dereferences a value
+      #
+      # @param value [String, Hash]
+      #
+      # @return [Hash, nil]
+      def dereference(value)
+        return value if value.is_a? Hash
+        return get(value) if value.is_a? String
+
+        raise "Unhandled object type #{value.class}"
+      end
     end
 
     private

data/lib/fediverse/webfinger.rb

@@ -4,31 +4,63 @@ require 'faraday/follow_redirects'
 require 'federails/utils/host'
 
 module Fediverse
+  # Methods related to Webfinger: find accounts, fetch actors,...
   class Webfinger
     class << self
       ACCOUNT_REGEX = /(?<username>[a-z0-9\-_.]+)(?:@(?<domain>.*))?/
 
+      # Extracts username and domain from a "acct:username@domain" string
+      #
+      # @param account [String] Account string
+      #
+      # @return [MatchData, nil] Matches with +:username+ and +:domain+ or +nil+
       def split_resource_account(account)
         /\Aacct:#{ACCOUNT_REGEX}\z/io.match account
       end
 
+      # Extracts username and domain from a "username@domain" string
+      #
+      # @param account [String] Account string
+      #
+      # @return [MatchData, nil] Matches with +:username+ and +:domain+ or +nil+
       def split_account(account)
         /\A#{ACCOUNT_REGEX}\z/io.match account
       end
 
-      def local_user?(account)
-        account[:username] && (account[:domain].nil? || (account[:domain] == Federails::Utils::Host.localhost))
+      # Determines if a given account string should be a local account (same host as configured one)
+      #
+      # @param hash [Hash, MatchData] Object with +:username+ and +:domain+ keys
+      #
+      # @return [Boolean]
+      def local_user?(hash)
+        hash[:username] && (hash[:domain].nil? || (hash[:domain] == Federails::Utils::Host.localhost))
       end
 
+      # Fetches a distant actor
+      #
+      # @param username [String]
+      # @param domain [String]
+      #
+      # @return [Federails::Actor, nil] Federails actor or nothing when not found
       def fetch_actor(username, domain)
         fetch_actor_url webfinger(username, domain)
       end
 
+      # Fetches an actor given its URL
+      #
+      # @param url [String] Actor's federation URL
+      #
+      # @return [Federails::Actor, nil] Federails actor or nothing when not found
       def fetch_actor_url(url)
         webfinger_to_actor get_json url
       end
 
-      # Returns actor id
+      # Gets the real actor's federation URL from its username and domain
+      #
+      # @param username [String]
+      # @param domain [String]
+      #
+      # @return [String, nil] Federation URL if found
       def webfinger(username, domain)
         json = webfinger_response(username, domain)
         link = json['links'].find { |l| l['type'] == 'application/activity+json' }
@@ -37,6 +69,12 @@ module Fediverse
       end
 
       # Returns remote follow link template, or complete link if actor_url is provided
+      #
+      # @param username [String]
+      # @param domain [String]
+      # @param actor_url [String] Optional Federation URL to provide when known
+      #
+      # @return [String] The URL to use as follow URL
       def remote_follow_url(username, domain, actor_url: nil)
         json = webfinger_response(username, domain)
         link = json['links'].find { |l| l['rel'] == 'http://ostatus.org/schema/1.0/subscribe' }
@@ -51,13 +89,17 @@ module Fediverse
 
       private
 
+      # Makes a webfinger request for a given username/domain
+      # @return [Hash] Webfinger response's content
       def webfinger_response(username, domain)
         scheme = Federails.configuration.force_ssl ? 'https' : 'http'
         get_json "#{scheme}://#{domain}/.well-known/webfinger", resource: "acct:#{username}@#{domain}"
       end
 
-      def server_and_port(id)
-        uri = URI.parse id
+      # Extracts the server and port from a string, omitting common ports
+      # @return [String] Server and port
+      def server_and_port(string)
+        uri = URI.parse string
         if uri.port && [80, 443].exclude?(uri.port)
           "#{uri.host}:#{uri.port}"
         else
@@ -65,6 +107,9 @@ module Fediverse
         end
       end
 
+      # Builds a +Federails::Actor+ from a Webfinger response
+      # @param data [Hash] Webfinger response
+      # @return [Federails::Actor]
       def webfinger_to_actor(data)
         Federails::Actor.new federated_url:  data['id'],
                              username:       data['preferredUsername'],
@@ -78,6 +123,9 @@ module Fediverse
                              public_key:     data.dig('publicKey', 'publicKeyPem')
       end
 
+      # Makes a simple GET request and returns a +Hash+ from the parsed body
+      # @return [Hash]
+      # @raise [ActiveRecord::RecordNotFound] when the response is invalid
       def get_json(url, payload = {})
         response = get(url, payload: payload, headers: { accept: 'application/json' })
 
@@ -93,10 +141,12 @@ module Fediverse
         raise ActiveRecord::RecordNotFound
       end
 
-      # Only perform a GET request and throws an ActiveRecord::RecordNotFound
-      # on error.
-      # That's "ok-ish"; when an actor is unavailable, whatever the reason is, it's
-      # not found...
+      # Only perform a GET request and throws an ActiveRecord::RecordNotFound on error.
+      #
+      # That's "ok-ish"; when an actor is unavailable, whatever the reason is, it's not found...
+      #
+      # @return [Faraday::Response]
+      # @raise [ActiveRecord::RecordNotFound] when the response is invalid
       def get(url, payload: {}, headers: {})
         connection = Faraday.new url: url, params: payload, headers: headers do |faraday|
           faraday.response :follow_redirects # use Faraday::FollowRedirects::Middleware

data/lib/fediverse.rb

@@ -0,0 +1,3 @@
+# This module includes classes and helpers to interact with the Fediverse.
+module Fediverse
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: federails
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Manuel Tancoigne
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-02 00:00:00.000000000 Z
+date: 2025-01-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -115,6 +115,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - README.md
 - Rakefile
 - app/assets/config/federails_manifest.js
@@ -127,6 +128,7 @@ files:
 - app/controllers/federails/server/actors_controller.rb
 - app/controllers/federails/server/followings_controller.rb
 - app/controllers/federails/server/nodeinfo_controller.rb
+- app/controllers/federails/server/published_controller.rb
 - app/controllers/federails/server/web_finger_controller.rb
 - app/controllers/federails/server_controller.rb
 - app/helpers/federails/server_helper.rb
@@ -134,6 +136,7 @@ files:
 - app/jobs/federails/notify_inbox_job.rb
 - app/mailers/federails/application_mailer.rb
 - app/models/concerns/federails/actor_entity.rb
+- app/models/concerns/federails/data_entity.rb
 - app/models/concerns/federails/has_uuid.rb
 - app/models/federails/activity.rb
 - app/models/federails/actor.rb
@@ -146,6 +149,7 @@ files:
 - app/policies/federails/server/activity_policy.rb
 - app/policies/federails/server/actor_policy.rb
 - app/policies/federails/server/following_policy.rb
+- app/policies/federails/server/publishable_policy.rb
 - app/views/federails/client/activities/_activity.html.erb
 - app/views/federails/client/activities/_activity.json.jbuilder
 - app/views/federails/client/activities/_index.json.jbuilder
@@ -180,6 +184,8 @@ files:
 - app/views/federails/server/followings/show.activitypub.jbuilder
 - app/views/federails/server/nodeinfo/index.nodeinfo.jbuilder
 - app/views/federails/server/nodeinfo/show.nodeinfo.jbuilder
+- app/views/federails/server/published/_publishable.activitypub.jbuilder
+- app/views/federails/server/published/show.activitypub.jbuilder
 - app/views/federails/server/web_finger/find.jrd.jbuilder
 - app/views/federails/server/web_finger/host_meta.xrd.erb
 - config/initializers/mime_types.rb
@@ -191,9 +197,12 @@ files:
 - db/migrate/20241002094501_add_keypair_to_actors.rb
 - lib/federails.rb
 - lib/federails/configuration.rb
+- lib/federails/data_transformer/note.rb
 - lib/federails/engine.rb
 - lib/federails/utils/host.rb
+- lib/federails/utils/object.rb
 - lib/federails/version.rb
+- lib/fediverse.rb
 - lib/fediverse/inbox.rb
 - lib/fediverse/notifier.rb
 - lib/fediverse/request.rb
@@ -230,7 +239,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.5.23
 signing_key:
 specification_version: 4
 summary: An ActivityPub engine for Ruby on Rails