federails 0.4.0 → 0.6.0

data/app/views/federails/server/activities/_activity.activitypub.jbuilder

@@ -1,13 +1,18 @@
 context = true unless context == false
+addressing = true unless addressing == false
 json.set! '@context', 'https://www.w3.org/ns/activitystreams' if context
 
 json.id Federails::Engine.routes.url_helpers.server_actor_activity_url activity.actor, activity
 json.type activity.action
 json.actor activity.actor.federated_url
-json.to ['https://www.w3.org/ns/activitystreams#Public']
-json.cc [activity.actor.followers_url]
+if addressing
+  json.to ['https://www.w3.org/ns/activitystreams#Public']
+  json.cc [activity.actor.followers_url]
+end
 
-if activity.entity.respond_to? :to_activitypub_object
+if activity.entity.is_a? Federails::Activity
+  json.object { json.partial!('federails/server/activities/activity', activity: activity.entity, context: false, addressing: false) }
+elsif activity.entity.respond_to? :to_activitypub_object
   json.object activity.entity.to_activitypub_object
 elsif activity.entity.respond_to? :federated_url
   json.object activity.entity.federated_url

data/app/views/federails/server/actors/_actor.activitypub.jbuilder

@@ -1,4 +1,4 @@
-actor_data = actor.entity.to_activitypub_object
+actor_data = actor.entity&.to_activitypub_object || {}
 
 json.set! '@context', ([
   'https://www.w3.org/ns/activitystreams',
@@ -9,7 +9,7 @@ json.set! '@context', ([
 
 json.id actor.federated_url
 json.name actor.name
-json.type actor.entity_configuration[:actor_type]
+json.type actor.actor_type
 json.preferredUsername actor.username
 json.inbox actor.inbox_url
 json.outbox actor.outbox_url

data/app/views/federails/server/actors/_tombstone.activitypub.jbuilder

@@ -0,0 +1,9 @@
+json.set! '@context', [
+  'https://www.w3.org/ns/activitystreams',
+  'https://w3id.org/security/v1',
+]
+
+json.id actor.federated_url
+json.type 'Tombstone'
+json.deleted actor.tombstoned_at
+json.formerType actor.actor_type

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

@@ -1 +1,5 @@
-json.partial! 'federails/server/actors/actor', actor: @actor
+if @actor.tombstoned?
+  json.partial! 'federails/server/actors/tombstone', actor: @actor
+else
+  json.partial! 'federails/server/actors/actor', actor: @actor
+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/_tombstone.activitypub.jbuilder

@@ -0,0 +1,9 @@
+json.set! '@context', [
+  'https://www.w3.org/ns/activitystreams',
+  'https://w3id.org/security/v1',
+]
+
+json.id publishable.federated_url
+json.type 'Tombstone'
+json.deleted publishable.federails_tombstoned_at
+json.formerType publishable.federails_data_configuration[:handles]

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

@@ -0,0 +1,5 @@
+if @publishable.federails_tombstoned?
+  json.partial! 'federails/server/published/tombstone', publishable: @publishable
+else
+  json.partial! 'federails/server/published/publishable', publishable: @publishable
+end

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/db/migrate/20250122160618_add_extensions_to_federails_actors.rb

@@ -0,0 +1,5 @@
+class AddExtensionsToFederailsActors < ActiveRecord::Migration[7.1]
+  def change
+    add_column :federails_actors, :extensions, :json, default: nil, null: true
+  end
+end

data/db/migrate/20250301082500_add_local_to_actors.rb

@@ -0,0 +1,11 @@
+class AddLocalToActors < ActiveRecord::Migration[7.0]
+  def change
+    add_column :federails_actors, :local, :boolean, null: false, default: false
+
+    reversible do |dir|
+      dir.up do
+        exec_update 'UPDATE federails_actors SET local=true WHERE entity_type IS NOT NULL'
+      end
+    end
+  end
+end

data/db/migrate/20250329123939_add_actor_type_to_actors.rb

@@ -0,0 +1,5 @@
+class AddActorTypeToActors < ActiveRecord::Migration[7.2]
+  def change
+    add_column :federails_actors, :actor_type, :string, null: true
+  end
+end

data/db/migrate/20250329123940_add_tombstoned_at_to_actors.rb

@@ -0,0 +1,5 @@
+class AddTombstonedAtToActors < ActiveRecord::Migration[7.0]
+  def change
+    add_column :federails_actors, :tombstoned_at, :datetime, default: nil
+  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
@@ -26,8 +28,12 @@ module Federails
     @@enable_discovery = true
 
     # Does the site allow open registrations? (only used for nodeinfo reporting)
-    mattr_accessor :open_registrations
+    # Can either be a static boolean, or a Proc which will be called to get the state.
+    mattr_writer :open_registrations
     @@open_registrations = false
+    def self.open_registrations
+      @@open_registrations.is_a?(Proc) ? @@open_registrations.call : @@open_registrations
+    end
 
     # Application layout
     mattr_accessor :app_layout
@@ -45,7 +51,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 +81,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, #federated_url, #created_at, #updated_at] 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/maintenance/actors_updater.rb

@@ -0,0 +1,67 @@
+module Federails
+  module Maintenance
+    class ActorsUpdater
+      class << self
+        # Fetches all distant actors again and update their local copy
+        #
+        # A block can be passed with two arguments: the actor being updated and the update status
+        #
+        # @param actors [Integer, Federails::Actor, Array<Federails::Actor>, nil] Actor ID, Actor or list of actors to update.
+        #   If nothing is passed, all distant actors are processed
+        # @example
+        #   Update all distant actors
+        #     Federails::Maintenance::ActorUpdater.run
+        #   With an actor id:
+        #     Federails::Maintenance::ActorUpdater.run 1
+        #   With a federated URL:
+        #     Federails::Maintenance::ActorUpdater.run 'https://example.com/actor'
+        #   With a federated URL:
+        #     Federails::Maintenance::ActorUpdater.run ['https://example.com/actors/1', 'https://example.com/actors/1']
+        #   With actors:
+        #     Federails::Maintenance::ActorUpdater.run Federails::Actor.last(10)
+        #   Update all distant actors and puts status for each actor
+        #     Federails::Maintenance::ActorUpdater.run {|actor, status| puts "#{actor.federated_url}: #{status}"}
+        def run(actors = nil, &block)
+          actors_list(actors).each do |actor|
+            status = update(actor)
+
+            yield(actor, status) if block
+          end
+        end
+
+        private
+
+        # Make a list of actors to update from the passed attribute
+        def actors_list(param) # rubocop:disable Metrics/PerceivedComplexity, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/AbcSize
+          if param.nil?
+            Federails::Actor.distant
+          elsif param.is_a? String
+            [Federails::Actor.distant.find_by!(federated_url: param)]
+          elsif param.is_a? Integer
+            [Federails::Actor.distant.find(param)]
+          elsif param.is_a?(Federails::Actor)
+            [param]
+          elsif param.respond_to?(:pluck) && param.first.is_a?(Federails::Actor)
+            param
+          elsif param.is_a?(Array) && param.first.is_a?(String)
+            Federails::Actor.distant.where(federated_url: param)
+          else
+            raise "Cannot extract actors from #{param.class}"
+          end
+        end
+
+        # @param actor [Federails::Actor]
+        def update(actor)
+          return :ignored_local if actor.local?
+
+          response = Fediverse::Webfinger.fetch_actor_url(actor.federated_url)
+          new_attributes = response.attributes.except 'id', 'uuid', 'created_at', 'updated_at', 'local'
+
+          actor.update(new_attributes) ? :updated : :failed
+        rescue ActiveRecord::RecordNotFound
+          :not_found
+        end
+      end
+    end
+  end
+end

data/lib/federails/utils/actor.rb

@@ -0,0 +1,53 @@
+module Federails
+  module Utils
+    class Actor
+      # List of the attributes computed for local actors
+      COMPUTED_ATTRIBUTES = [
+        :federated_url,
+        :username,
+        :name,
+        :server,
+        :inbox_url,
+        :outbox_url,
+        :followers_url,
+        :followings_url,
+        :profile_url,
+      ].freeze
+
+      class << self
+        # @param actor [Federails::Actor]
+        # @return [Federails::Actor]
+        def tombstone!(actor)
+          if actor.local?
+            tombstone_local_actor actor
+          else
+            tombstone_distant_actor actor
+          end
+
+          actor
+        end
+
+        private
+
+        def tombstone_local_actor(actor)
+          Federails::Actor.transaction do
+            hash = {
+              tombstoned_at: Time.current,
+              entity:        nil,
+            }
+            # Hardcode attributes depending on the actor's entity
+            COMPUTED_ATTRIBUTES.each { |attribute| hash[attribute] = actor.send(attribute) }
+
+            actor.update! hash
+
+            Activity.create! actor: actor, action: 'Delete', entity: actor
+          end
+        end
+
+        def tombstone_distant_actor(actor)
+          actor.update! tombstoned_at: Time.current
+        end
+      end
+    end
+  end
+end

data/lib/federails/utils/object.rb

@@ -0,0 +1,131 @@
+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
+
+        # Search for a distant object in actors and configured data entities.
+        #
+        # This is useful to find something when the type is unknown, as an object from a Delete activity.
+        #
+        # @param federated_url [String] Object identifier
+        # @return [Federails::Actor, Federails::DataEntity, Federails::Following, nil]
+        def find_distant_object_in_all(federated_url)
+          # Search in actors
+          object = Federails::Actor.find_by federated_url: federated_url
+          return object if object.present?
+
+          # Search in followings
+          object = Federails::Following.find_by federated_url: federated_url
+          return object if object.present?
+
+          # Search in data entities
+          Federails.configuration.data_types.keys.sort.each do |klass|
+            object = klass.constantize.find_by federated_url: federated_url
+
+            break if object.present?
+          end
+
+          object
+        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.6.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,27 +4,51 @@ module Fediverse
   class Inbox
     @@handlers = {} # rubocop:todo Style/ClassVars
     class << self
+      # Registers a handler for incoming data
+      #
+      # Unless a specific type is not implemented in Federails, you should leave the 'Delete' activity to Federails:
+      # it will dispatch a `on_federails_delete_requested` event on the right objects.
+      #
+      # @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)
+        return dispatch_delete_request(payload) if payload['type'] == 'Delete'
+
+        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
 
       private
 
+      def dispatch_delete_request(payload)
+        payload['object'] = payload['object']['id'] unless payload['object'].is_a? String
+        object = Federails::Utils::Object.find_distant_object_in_all payload['object']
+        return if object.blank?
+
+        object.run_callbacks :on_federails_delete_requested
+      end
+
       def get_handlers(activity_type, object_type)
         {}.merge(@@handlers.dig(activity_type, object_type) || {})
           .merge(@@handlers.dig(activity_type, '*') || {})
@@ -39,8 +63,8 @@ module Fediverse
         Federails::Following.create! actor: actor, target_actor: target_actor, federated_url: activity['id']
       end
 
-      def handle_accept_request(activity)
-        original_activity = Request.get(activity['object'])
+      def handle_accept_follow_request(activity)
+        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']
@@ -50,7 +74,7 @@ module Fediverse
         follow.accept!
       end
 
-      def handle_undo_request(activity)
+      def handle_undo_follow_request(activity)
         original_activity = activity['object']
 
         actor        = Federails::Actor.find_or_create_by_object original_activity['actor']
@@ -59,10 +83,18 @@ module Fediverse
         follow = Federails::Following.find_by actor: actor, target_actor: target_actor
         follow&.destroy
       end
+
+      def handle_delete_request(activity)
+        object = Federails::Utils::Object.find_distant_object_in_all(activity['object'])
+        return if object.blank?
+
+        object.run_callbacks :on_federails_delete_requested
+      end
     end
 
     register_handler 'Follow', '*', self, :handle_create_follow_request
-    register_handler 'Accept', 'Follow', self, :handle_accept_request
-    register_handler 'Undo', 'Follow', self, :handle_undo_request
+    register_handler 'Accept', 'Follow', self, :handle_accept_follow_request
+    register_handler 'Undo', 'Follow', self, :handle_undo_follow_request
+    register_handler 'Delete', '*', self, :handle_delete_request
   end
 end

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?