federails 0.4.0 → 0.6.0

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

@@ -0,0 +1,205 @@
+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
+  #
+  #   # This will be called when a Delete activity comes for the entry. As we don't know how you want to handle it,
+  #   # you'll have to implement the behavior yourself.
+  #   on_federails_delete_requested :do_something
+  # end
+  # ```
+  module DataEntity
+    class TombstonedError < StandardError; end
+
+    extend ActiveSupport::Concern
+    include Federails::HandlesDeleteRequests
+
+    # 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.
+      # @param soft_deleted_method [Symbol, nil] Method to soft-delete the object when receiving a Delete request. This
+      #   is not required by the spec but greatly encouraged as the app will return a 410 response with a Tombstone object
+      #   instead of an 404 error.
+      # @param soft_delete_date_method [Symbol, nil] Method to get the date of the soft-deletion
+      #
+      # @example
+      #   acts_as_federails_data handles: 'Note', with: :note_handler, route_path_segment: :articles, actor_entity_method: :user
+      # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
+      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?,
+        soft_deleted_method: nil,
+        soft_delete_date_method: nil
+      )
+        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,
+                                                    soft_deleted_method:     soft_deleted_method,
+                                                    soft_delete_date_method: soft_delete_date_method
+
+        # NOTE: Delete activities cannot be handled like this as we can't be sure to have the object's type
+        Fediverse::Inbox.register_handler 'Create', handles, self, with
+        Fediverse::Inbox.register_handler 'Update', handles, self, with
+      end
+      # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
+
+      # 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
+
+      def find_untombstoned_by!(**params)
+        configuration = Federails.data_entity_configuration(self)
+        entity = find_by!(**params)
+
+        raise Federails::DataEntity::TombstonedError if configuration[:soft_deleted_method] && entity.send(configuration[:soft_deleted_method])
+
+        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 'Create' }
+      after_update -> { create_federails_activity 'Update' }, :federails_tombstoned?
+      after_destroy -> { create_federails_activity 'Delete' }
+    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_tombstoned?
+      federails_data_configuration[:soft_deleted_method] ? send(federails_data_configuration[:soft_deleted_method]) : false
+    end
+
+    def federails_tombstoned_at
+      federails_data_configuration[:soft_delete_date_method] ? send(federails_data_configuration[:soft_delete_date_method]) : nil
+    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(action)
+      ensure_federails_configuration!
+      return unless local_federails_entity? && send(federails_data_configuration[:should_federate_method])
+
+      Activity.create! actor: federails_actor, action: action, 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/handles_delete_requests.rb

@@ -0,0 +1,31 @@
+module Federails
+  # Model concern providing hooks for on_federails_delete_requested callback
+  #
+  # ```rb
+  # # Example migration
+  # add_column :my_table, :uuid, :text, default: nil, index: { unique: true }
+  # ```
+  #
+  # Usage:
+  #
+  # ```rb
+  # class MyModel < ApplicationRecord
+  #   include Federails::HandlesDeleteRequests
+  #
+  #   on_federails_delete_requested -> { delete! }
+  # end
+  module HandlesDeleteRequests
+    extend ActiveSupport::Concern
+
+    # Class methods automatically included in the concern.
+    module ClassMethods
+      def on_federails_delete_requested(*args)
+        set_callback :on_federails_delete_requested, *args
+      end
+    end
+
+    included do
+      define_callbacks :on_federails_delete_requested
+    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,19 +24,33 @@ 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?
 
-      case entity_type
-      when 'Federails::Following'
-        [(action == 'Accept' ? entity.actor : entity.target_actor)]
+      case action
+      when 'Follow'
+        [entity]
+      when 'Undo'
+        [entity.entity]
+      when 'Accept'
+        [entity.actor]
       else
-        actor.followers
+        default_recipient_list
       end
     end
 
     private
 
+    def default_recipient_list
+      list = actor.followers
+      # If local actor is the subject, notify that actor's followers as well
+      list += entity.followers if entity.is_a?(Federails::Actor) && entity.local?
+      list.uniq
+    end
+
     def post_to_inboxes
       NotifyInboxJob.perform_later(self)
     end

data/app/models/federails/actor.rb

@@ -1,19 +1,31 @@
 require 'federails/utils/host'
+require 'federails/utils/actor'
 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
+    class TombstonedError < StandardError; end
 
-    validates :federated_url, presence: { unless: :entity }, uniqueness: { unless: :entity }
-    validates :username, presence: { unless: :entity }
-    validates :server, presence: { unless: :entity }
-    validates :inbox_url, presence: { unless: :entity }
-    validates :outbox_url, presence: { unless: :entity }
-    validates :followers_url, presence: { unless: :entity }
-    validates :followings_url, presence: { unless: :entity }
-    validates :profile_url, presence: { unless: :entity }
-    validates :entity_id, uniqueness: { scope: :entity_type }, if: :local?
+    include Federails::HasUuid
+    include Federails::HandlesDeleteRequests
+
+    validates :federated_url, presence: { unless: :entity }, uniqueness: { unless: :local? }
+    validates :username, presence: { unless: :local? }
+    validates :server, presence: { unless: :local? }
+    validates :inbox_url, presence: { unless: :local? }
+    validates :outbox_url, presence: { unless: :local? }
+    validates :followers_url, presence: { unless: :local? }
+    validates :followings_url, presence: { unless: :local? }
+    validates :profile_url, presence: { unless: :local? }
+    validates :actor_type, presence: { unless: :local? }
+    validates :entity_id, uniqueness: { scope: :entity_type }, if: :entity_type
+    validates :entity, presence: true, if: -> { local? && !tombstoned? }
 
     belongs_to :entity, polymorphic: true, optional: true
     # FIXME: Handle this with something like undelete
@@ -24,50 +36,59 @@ module Federails
     has_many :followers, source: :actor, through: :following_followers
     has_many :follows, source: :target_actor, through: :following_follows
 
-    scope :local, -> { where.not(entity: nil) }
+    scope :local, -> { where(local: true) }
+    scope :distant, -> { where(local: false) }
+    scope :tombstoned, -> { where.not(tombstoned_at: nil) }
+    scope :not_tombstoned, -> { where(tombstoned_at: nil) }
 
-    def local?
-      entity.present?
+    on_federails_delete_requested -> { tombstone! }
+
+    def distant?
+      !local?
     end
 
     def federated_url
-      local? ? Federails::Engine.routes.url_helpers.server_actor_url(self) : attributes['federated_url'].presence
+      use_entity_attributes? ? Federails::Engine.routes.url_helpers.server_actor_url(self) : attributes['federated_url'].presence
     end
 
     def username
-      return attributes['username'] unless local?
+      return attributes['username'] unless use_entity_attributes?
 
       entity.send(entity_configuration[:username_field]).to_s
     end
 
     def name
-      value = (entity.send(entity_configuration[:name_field]).to_s if local?)
+      value = (entity.send(entity_configuration[:name_field]).to_s if use_entity_attributes?)
 
       value || attributes['name'] || username
     end
 
     def server
-      local? ? Utils::Host.localhost : attributes['server']
+      use_entity_attributes? ? Utils::Host.localhost : attributes['server']
+    end
+
+    def actor_type
+      use_entity_attributes? ? entity_configuration[:actor_type] : attributes['actor_type']
     end
 
     def inbox_url
-      local? ? Federails::Engine.routes.url_helpers.server_actor_inbox_url(self) : attributes['inbox_url']
+      use_entity_attributes? ? Federails::Engine.routes.url_helpers.server_actor_inbox_url(self) : attributes['inbox_url']
     end
 
     def outbox_url
-      local? ? Federails::Engine.routes.url_helpers.server_actor_outbox_url(self) : attributes['outbox_url']
+      use_entity_attributes? ? Federails::Engine.routes.url_helpers.server_actor_outbox_url(self) : attributes['outbox_url']
     end
 
     def followers_url
-      local? ? Federails::Engine.routes.url_helpers.followers_server_actor_url(self) : attributes['followers_url']
+      use_entity_attributes? ? Federails::Engine.routes.url_helpers.followers_server_actor_url(self) : attributes['followers_url']
     end
 
     def followings_url
-      local? ? Federails::Engine.routes.url_helpers.following_server_actor_url(self) : attributes['followings_url']
+      use_entity_attributes? ? Federails::Engine.routes.url_helpers.following_server_actor_url(self) : attributes['followings_url']
     end
 
     def profile_url
-      return attributes['profile_url'].presence unless local?
+      return attributes['profile_url'].presence unless use_entity_attributes?
 
       method = entity_configuration[:profile_url_method]
       return Federails::Engine.routes.url_helpers.server_actor_url self unless method
@@ -76,11 +97,15 @@ module Federails
     end
 
     def at_address
-      "#{username}@#{server}"
+      "@#{username}@#{server}"
     end
 
     def short_at_address
-      local? ? "@#{username}" : at_address
+      use_entity_attributes? ? "@#{username}" : at_address
+    end
+
+    def acct_uri
+      "acct:#{username}@#{server}"
     end
 
     def follows?(actor)
@@ -96,16 +121,24 @@ module Federails
       Federails.actor_entity entity_type
     end
 
+    def tombstoned?
+      tombstoned_at.present?
+    end
+
+    def tombstone!
+      Federails::Utils::Actor.tombstone! self
+    end
+
     class << self
-      def find_by_account(account) # rubocop:todo Metrics/AbcSize
+      # Searches for an actor from account URI
+      #
+      # @param account [String] Account URI (username@host)
+      # @return [Federails::Actor, nil]
+      def find_by_account(account)
         parts = Fediverse::Webfinger.split_account account
 
         if Fediverse::Webfinger.local_user? parts
-          actor = nil
-          Federails::Configuration.actor_types.each_value do |entity|
-            actor ||= entity[:class].find_by(entity[:username_field] => parts[:username])&.federails_actor
-          end
-          raise ActiveRecord::RecordNotFound if actor.nil?
+          actor = find_local_by_username! parts[:username]
         else
           actor = find_by username: parts[:username], server: parts[:domain]
           actor ||= Fediverse::Webfinger.fetch_actor(parts[:username], parts[:domain])
@@ -124,6 +157,13 @@ module Federails
         Fediverse::Webfinger.fetch_actor_url(federated_url)
       end
 
+      def find_by_federation_url!(federated_url)
+        find_by_federation_url(federated_url).tap do |actor|
+          raise Federails::Actor::TombstonedError if actor.tombstoned?
+          raise ActiveRecord::RecordNotFound if actor.nil?
+        end
+      end
+
       def find_or_create_by_account(account)
         actor = find_by_account account
         # Create/update distant actors
@@ -151,6 +191,25 @@ module Federails
           raise "Unsupported object type for actor (#{object.class})"
         end
       end
+
+      def find_local_by_username(username)
+        actor = nil
+        Federails::Configuration.actor_types.each_value do |entity|
+          break if actor.present?
+
+          actor = entity[:class].find_by(entity[:username_field] => username)&.federails_actor
+        end
+        return actor if actor
+
+        # Last hope: Search for tombstoned actors
+        Federails::Actor.local.tombstoned.find_by username: username
+      end
+
+      def find_local_by_username!(username)
+        find_local_by_username(username).tap do |actor|
+          raise ActiveRecord::RecordNotFound if actor.nil?
+        end
+      end
     end
 
     def public_key
@@ -187,5 +246,9 @@ module Federails
         public_key:  rsa_key.public_key.to_pem,
       }
     end
+
+    def use_entity_attributes?
+      local? && !tombstoned?
+    end
   end
 end

data/app/models/federails/following.rb

@@ -1,4 +1,5 @@
 module Federails
+  # Stores following data between actors
   class Following < ApplicationRecord
     include Federails::HasUuid
 
@@ -8,17 +9,21 @@ module Federails
 
     belongs_to :actor
     belongs_to :target_actor, class_name: 'Federails::Actor'
-    # FIXME: Handle this with something like undelete
     has_many :activities, as: :entity, dependent: :destroy
 
     after_create :after_follow
-    after_create :create_activity
-    after_destroy :destroy_activity
+    after_create :create_activity, if: :locally_instigated?
+    after_update :after_follow_accepted
+    after_destroy :destroy_activity, if: :locally_instigated?
+
+    define_callbacks :on_federails_delete_requested
+
+    set_callback :on_federails_delete_requested, -> { destroy! unless locally_instigated? }
 
     scope :with_actor, ->(actor) { where(actor_id: actor.id).or(where(target_actor_id: actor.id)) }
 
     def federated_url
-      attributes['federated_url'].presence || Federails::Engine.routes.url_helpers.server_actor_following_url(actor_id: actor_id, id: id)
+      attributes['federated_url'].presence || Federails::Engine.routes.url_helpers.server_actor_following_url(actor_id: actor.to_param, id: to_param)
     end
 
     def accept!
@@ -26,6 +31,10 @@ module Federails
       Activity.create! actor: target_actor, action: 'Accept', entity: self
     end
 
+    def follow_activity
+      Activity.find_by actor: actor, action: 'Follow', entity: target_actor
+    end
+
     class << self
       def new_from_account(account, actor:)
         target_actor = Actor.find_or_create_by_account account
@@ -35,18 +44,29 @@ module Federails
 
     private
 
+    def locally_instigated?
+      actor.local?
+    end
+
     def after_follow
-      target_actor&.entity&.run_callbacks :followed, :after do
-        self
-      end
+      return unless target_actor&.entity
+
+      target_actor.entity.class.send(:dispatch_callback, :after_followed, target_actor.entity, self)
+    end
+
+    def after_follow_accepted
+      return unless status_previously_changed? && status == 'accepted'
+      return unless actor&.entity
+
+      actor.entity.class.send(:dispatch_callback, :after_follow_accepted, actor.entity, self)
     end
 
     def create_activity
-      Activity.create! actor: actor, action: 'Create', entity: self
+      Activity.create! actor: actor, action: 'Follow', entity: target_actor
     end
 
     def destroy_activity
-      Activity.create! actor: actor, action: 'Undo', entity: self
+      Activity.create! actor: actor, action: 'Undo', entity: follow_activity
     end
   end
 end

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/client/actors/_actor.json.jbuilder

@@ -9,6 +9,9 @@ json.extract! actor,
               :followings_url,
               :profile_url,
               :at_address,
-              :user_id,
+              :local,
+              :entity_id,
+              :entity_type,
+              :tombstoned_at,
               :created_at,
               :updated_at

data/app/views/federails/client/actors/gone.html.erb

@@ -0,0 +1 @@
+<%= t('.gone') %>

data/app/views/federails/client/actors/index.html.erb

@@ -27,7 +27,13 @@
   <% end %>
   <% @actors.each do |actor| %>
     <tr>
-      <td><%= actor.name %></td>
+      <td>
+        <% if actor.tombstoned? %>
+          <del><%= actor.name %></del>
+        <% else %>
+          <%= actor.name %>
+        <% end %>
+      </td>
       <td><%= actor.username %></td>
       <td><%= actor.at_address %></td>
       <td><%= actor.local? %></td>