rails guide

guides/rails.md

@@ -0,0 +1,102 @@
+### Extending the `Person` Actor Type in a Rails App:
+
+1. **Create a Rails Model for `Person`:**
+
+   If you don't already have a User or Person model, create one:
+
+   ```bash
+   rails generate model Person name:string preferred_username:string inbox:string outbox:string
+   ```
+
+   Then run `rails db:migrate` to apply the changes to the database.
+
+2. **Extend the `ActivityPub::Actor::Person` in the Rails Model:**
+
+   We want the Rails `Person` model to have the same functionalities as the `ActivityPub::Actor::Person`.
+
+   ```ruby
+   class Person < ApplicationRecord
+     include ActivityPub::Actor::Person
+
+     # Any additional methods or scopes for the Rails model
+   end
+   ```
+
+3. **Override or Extend Methods as Necessary:**
+
+   For instance, if the `to_h` method from `ActivityPub::Actor::Person` does not cover all attributes or you want to add custom behavior:
+
+   ```ruby
+   def to_h
+     super.merge({
+       custom_attribute: self.custom_attribute,
+       another_custom_attribute: another_method
+     })
+   end
+   ```
+
+4. **Use Callbacks to Integrate ActivityPub Logic:**
+
+   Use ActiveRecord callbacks to add any necessary logic around ActivityPub actions. For instance:
+
+   ```ruby
+   after_create :broadcast_to_followers
+
+   private
+
+   def broadcast_to_followers
+     # Send a 'Create' activity to all followers when a new person is created.
+   end
+   ```
+
+5. **Extend Controller Logic:**
+
+   For processing ActivityPub requests, you may need to extend or create controllers to handle these:
+
+   ```ruby
+   class PersonsController < ApplicationController
+     def create
+       # Parse the incoming ActivityPub request, which is typically in JSON-LD format.
+       activity = ActivityPub::Activity.from_h(params.require(:activity).permit!)
+
+       # Handle the activity. For example, for a 'Follow' activity:
+       if activity.type == 'Follow'
+         # Handle the new follower logic
+       end
+
+       # Respond appropriately.
+       head :created
+     end
+   end
+   ```
+
+6. **Routes:**
+
+   Make sure your Rails app has the necessary routes set up to handle ActivityPub requests:
+
+   ```ruby
+   resources :persons, only: [:create]
+   ```
+
+7. **Views (if necessary):**
+
+   If you need views for the ActivityPub functionalities, create them. However, much of ActivityPub interactions are server-to-server, so views might not be required unless you're building user-facing features around it.
+
+8. **Add Necessary Gems:**
+
+   You might want to add certain gems to help with JSON-LD parsing, HTTP Signature verification, etc. Some examples include:
+
+   - `json-ld`
+   - `http-signature`
+
+### Tips:
+
+- **Separation of Concerns:** Keep the ActivityPub logic separate from the regular Rails app logic. This can help in maintaining the codebase as both your app and the ActivityPub protocol evolve.
+  
+- **Testing:** Ensure you have tests for the ActivityPub functionalities. Use libraries like `webmock` to stub out external requests and `rspec` or Rails' built-in testing for writing your tests.
+
+- **Logging:** Have proper logging in place. Since ActivityPub involves server-to-server communication, you'll want to log errors and other important events to help debug issues.
+
+- **Security:** Always validate and sanitize the incoming ActivityPub data. Verify HTTP Signatures and ensure you're communicating over HTTPS. 
+
+By following this guidance and the above steps, you should be able to integrate and extend the ActivityPub actor types within your Rails app effectively.