federails 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3463b1a877ca8224ade011016236c1fdbcbe41e31712b609347f41592d30531
-  data.tar.gz: 16ec7975b26bc5fbec1e243a4653c27d8b0239c7dbda42544150c9e5680d65f5
+  metadata.gz: '0538a0c2d7f7e3845a5d8ae304ac2b319b3cf1e76b10520645773f8f763c3431'
+  data.tar.gz: e97c559ecc5aba1b1c05c9be5f39b982a22e92cb8f73ae8c8a08741a3efb3d01
 SHA512:
-  metadata.gz: b54850967223bb1be7aadd54547f757a9e5fbe6ccc8d84249a4a2b340a494b275905c25e862c493b2d2b177a7cc5e12abf2d6e44c4f84b4bec76796a7b9cba5f
-  data.tar.gz: cc00b05153d4434eacc6409a4422575d5e851e07c332001a72fc818e5f64d1bf6f2cd35f6eaa5f4025b3150fe9009a370665a044d44f84a60399690186a8f5e8
+  metadata.gz: 560377c5b698b87274d1df302595c33467f010402096227583161087aaf124b0a9e2820f44234b2932c158e84b0ab8ccb79ea8501557840509a416c7b8205295
+  data.tar.gz: 6380fc79556446afbd4a81e3e5e2e6b49bdb5877576dd1038208c1c4471cd3986bb35bbfaae1a9f37e618ddf5ab14dcf6974f512f6a609c70c2de0b7c251803f

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,207 +23,37 @@ 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
+## Supported Ruby on Rails versions
 
-Add this line to your application's Gemfile:
+This gem is tested against non end-of-life versions of Ruby and Rails:
 
-```ruby
-gem "federails"
-```
+- Ruby versions 3.1 to 3.4
+- Rails 7.1 to 8.0.x.
 
-And then execute:
+Feel free to open an issue if we missed something
 
-```bash
-$ bundle
-```
+It _may_ work on other versions, but we won't provide support.
 
-### Configuration
+## Documentation
 
-Generate configuration files:
+- [Usage](docs/usage.md)
+- [Common questions](docs/faq.md)
+- [Contributing](CONTRIBUTING.md)
 
-```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**
+## License
 
-  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.
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Contributing
 
-Contributions are welcome, may it be issues, ideas, code or whatever you want to share. Please note:
+See [CONTRIBUTING](CONTRIBUTING.md) to have an overview of the process and the tools we use.
 
-- 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
+### Contributors
 
-To contribute:
+- [echarp](https://gitlab.com/echarp)
+- [James Smith](https://gitlab.com/floppy.uk)
+- [Manuel Tancoigne](https://gitlab.com/mtancoigne)
 
-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
+### Indirect contributions
 
-### 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
-```
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+- Gitlab runners are graciously provided by [Coopaname](https://coopaname.coop), a French cooperative.

data/app/controllers/federails/client/actors_controller.rb

@@ -14,14 +14,16 @@ module Federails
 
       # GET /app/actors/1
       # GET /app/actors/1.json
-      def show; end
+      def show
+        render_show
+      end
 
-      # GET /app/explorer/lookup
-      # GET /app/explorer/lookup.json
+      # GET /app/actors/lookup
+      # GET /app/actors/lookup.json
       def lookup
         @actor = Federails::Actor.find_by_account account_param
         authorize @actor, policy_class: Federails::Client::ActorPolicy
-        render :show
+        render_show
       end
 
       private
@@ -35,6 +37,18 @@ module Federails
       def account_param
         params.require('account')
       end
+
+      def render_show
+        respond_to do |format|
+          if @actor.tombstoned?
+            format.html { render :gone, status: :gone }
+            format.json { render json: { error: I18n.t('controller.actors.gone') }, status: :gone }
+          else
+            format.html { render :show }
+            format.json { render :show }
+          end
+        end
+      end
     end
   end
 end

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

@@ -5,7 +5,10 @@ module Federails
 
       # GET /federation/actors/1
       # GET /federation/actors/1.json
-      def show; end
+      def show
+        status = @actor.tombstoned? ? :gone : :ok
+        render :show, status: status
+      end
 
       # GET /federation/actors/:id/followers
       # GET /federation/actors/:id/followers.json

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_untombstoned_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/controllers/federails/server/web_finger_controller.rb

@@ -9,11 +9,12 @@ module Federails
         resource = params.require(:resource)
         case resource
         when %r{^https?://.+}
-          @user = Federails::Actor.find_by_federation_url(resource)&.entity
+          @user = Federails::Actor.find_by_federation_url!(resource).entity # rubocop:disable Rails/DynamicFindBy
         when /^acct:.+/
-          Federails::Configuration.actor_types.each_value do |entity|
-            @user ||= entity[:class].find_by(entity[:username_field] => username)
-          end
+          actor = Federails::Actor.find_local_by_username(username)
+          raise Federails::Actor::TombstonedError if actor&.tombstoned?
+
+          @user = actor&.entity
         end
         raise ActiveRecord::RecordNotFound if @user.nil?
 
@@ -31,11 +32,13 @@ module Federails
       private
 
       def username
-        account = Fediverse::Webfinger.split_resource_account params.require(:resource)
+        return @username if instance_variable_defined? :@username
+
+        account = Fediverse::Webfinger.split_account params.require(:resource)
         # Fail early if user don't _seems_ local
         raise ActiveRecord::RecordNotFound unless account && Fediverse::Webfinger.local_user?(account)
 
-        account[:username]
+        @username = account[:username]
       end
     end
   end

data/app/controllers/federails/server_controller.rb

@@ -8,6 +8,9 @@ module Federails
     helper Federails::ServerHelper
 
     rescue_from ActiveRecord::RecordNotFound, with: :error_not_found
+    rescue_from Federails::Actor::TombstonedError,
+                Federails::DataEntity::TombstonedError,
+                with: :error_gone
 
     private
 
@@ -26,5 +29,9 @@ module Federails
     def error_not_found(exception = nil)
       error_fallback(exception, 'Resource not found', :not_found)
     end
+
+    def error_gone(exception = nil)
+      error_fallback(exception, 'Resource is gone', :gone)
+    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,104 @@ 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.
+      # The follow request will be passed as an argument to the method.
+      #
+      # @param method_name [Symbol] The name of the method to call, or a block that will be called directly
+      #
+      # @example
+      #   after_followed :accept_follow
+      def after_followed(method_name)
+        @after_followed = method_name
+      end
+
+      # Define a method that will be called after a follow request made by the entity is accepted
+      # The accepted follow request will be passed as an argument to the method.
+      #
+      # @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_follow_accepted :follow_accepted
+      def after_follow_accepted(method_name)
+        @after_follow_accepted = method_name
+      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_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
 
       private
 
-      def create_federails_actor
-        Federails::Actor.create! entity: self
+      def dispatch_callback(name, instance, *args)
+        case name
+        when :after_followed
+          instance.send(@after_followed, *args) if @after_followed
+        when :after_follow_accepted
+          instance.send(@after_follow_accepted, *args) if @after_follow_accepted
+        end
       end
     end
+
+    included do
+      # No "dependent: :xyz" as the "before_destroy" hook should have nullified the actor
+      has_one :federails_actor, class_name: 'Federails::Actor', as: :entity # rubocop:disable Rails/HasManyOrHasOneDependent
+
+      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]
+      }
+      before_destroy :tombstone_federails_actor!
+    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
+
+    # Result is used to determine if an actor related to this entity should be created as local actor or not
+    #
+    # Override it in your models if you need distant actors to be related to another entity.
+    def create_federails_actor_as_local?
+      true
+    end
+
+    def create_federails_actor
+      Federails::Actor.create_with(local: create_federails_actor_as_local?).find_or_create_by!(entity: self)
+    end
+
+    def tombstone_federails_actor!
+      federails_actor.tombstone!
+    end
   end
 end