plutonium 0.33.1 → 0.34.0

data/docs/guides/multi-tenancy.md

@@ -0,0 +1,302 @@
+# Multi-tenancy
+
+This guide covers isolating data by organization, account, or other entity.
+
+## Overview
+
+Multi-tenancy means each tenant (organization, company, account) sees only their own data. Plutonium supports this through:
+
+- **Entity Scoping** - Automatic query filtering via portal configuration
+- **Path or Custom Strategies** - Flexible entity resolution
+- **Policy Integration** - Authorization automatically respects tenancy
+
+## Setting Up Multi-tenancy
+
+### 1. Create the Entity Model
+
+```ruby
+# app/models/organization.rb
+class Organization < ApplicationRecord
+  include Plutonium::Resource::Record
+
+  has_many :users
+  has_many :posts
+end
+```
+
+### 2. Add Entity Reference to Resources
+
+Resources must have an association path to the entity:
+
+```ruby
+# Direct association (preferred)
+class Post < ResourceRecord
+  belongs_to :organization
+  belongs_to :user
+end
+
+# Through association
+class Comment < ResourceRecord
+  belongs_to :post
+  has_one :organization, through: :post
+end
+```
+
+### 3. Configure the Portal Engine
+
+```ruby
+# packages/customer_portal/lib/engine.rb
+module CustomerPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+
+    config.after_initialize do
+      # Path strategy - entity ID in URL
+      scope_to_entity Organization, strategy: :path
+    end
+  end
+end
+```
+
+Routes become: `/organizations/:organization_id/posts`
+
+## Scoping Strategies
+
+### Path Strategy (Default)
+
+Entity ID is included in the URL path:
+
+```ruby
+config.after_initialize do
+  scope_to_entity Organization, strategy: :path
+end
+```
+
+The user must have access to the organization (via `associated_with` scope).
+
+### Custom Strategy
+
+Define a method that returns the current entity:
+
+```ruby
+# packages/customer_portal/lib/engine.rb
+config.after_initialize do
+  scope_to_entity Organization, strategy: :current_organization
+end
+```
+
+```ruby
+# packages/customer_portal/app/controllers/customer_portal/concerns/controller.rb
+module CustomerPortal
+  module Concerns
+    module Controller
+      extend ActiveSupport::Concern
+      include Plutonium::Portal::Controller
+      include Plutonium::Auth::Rodauth(:user)
+
+      private
+
+      # Method name must match strategy
+      def current_organization
+        @current_organization ||= current_user.organization
+      end
+    end
+  end
+end
+```
+
+## How Entity Scoping Works
+
+### Automatic Query Filtering
+
+All resource queries are automatically scoped via `associated_with`:
+
+```ruby
+# In a scoped portal
+Post.all  # Returns only current entity's posts
+```
+
+### Helper Methods
+
+Inside controllers:
+
+```ruby
+current_scoped_entity  # The current Organization/Account/etc.
+scoped_to_entity?      # true if scoping is active
+scoped_entity_class    # Organization (the entity class)
+```
+
+### Model Requirements
+
+Models must have an association path to the scoped entity. Plutonium automatically resolves:
+
+1. **Direct belongs_to** - `Post belongs_to :organization`
+2. **Through association** - `Comment has_one :organization, through: :post`
+3. **Custom scope** - For complex cases, define a named scope:
+
+```ruby
+class AuditLog < ResourceRecord
+  # When automatic resolution fails, define this scope
+  scope :associated_with_organization, ->(org) {
+    joins(:user).where(users: { organization_id: org.id })
+  }
+end
+```
+
+## User Membership Patterns
+
+### Single Organization per User
+
+```ruby
+class User < ApplicationRecord
+  belongs_to :organization
+end
+
+# Custom strategy
+def current_organization
+  current_user.organization
+end
+```
+
+### Multiple Organizations per User
+
+```ruby
+class User < ApplicationRecord
+  has_many :memberships
+  has_many :organizations, through: :memberships
+end
+
+# Custom strategy with session storage
+def current_organization
+  @current_organization ||=
+    current_user.organizations.find_by(id: session[:organization_id]) ||
+    current_user.organizations.first
+end
+```
+
+### Organization Switcher
+
+```ruby
+class OrganizationSwitchController < ApplicationController
+  def update
+    org = current_user.organizations.find(params[:id])
+    session[:organization_id] = org.id
+    redirect_back(fallback_location: root_path)
+  end
+end
+```
+
+## Policy Integration
+
+Entity scoping is automatic. The base `Plutonium::Resource::Policy` includes:
+
+```ruby
+relation_scope do |relation|
+  next relation unless entity_scope
+
+  relation.associated_with(entity_scope)
+end
+```
+
+The `entity_scope` context is automatically set to `current_scoped_entity`.
+
+### Additional Filtering
+
+Add role-based filtering on top of entity scoping:
+
+```ruby
+class PostPolicy < ResourcePolicy
+  relation_scope do |relation|
+    relation = super(relation)  # Apply entity scoping first
+
+    if user.role == "viewer"
+      relation.where(published: true)
+    else
+      relation
+    end
+  end
+end
+```
+
+## Subdomain-Based Tenancy
+
+Route to different organizations by subdomain:
+
+### Routes
+
+```ruby
+# config/routes.rb
+constraints subdomain: /[a-z]+/ do
+  mount CustomerPortal::Engine, at: "/"
+end
+```
+
+### Custom Strategy
+
+```ruby
+# Engine configuration
+scope_to_entity Organization, strategy: :current_organization
+
+# Controller concern
+def current_organization
+  @current_organization ||=
+    Organization.find_by!(subdomain: request.subdomain)
+end
+```
+
+## Cross-Tenant Operations
+
+Sometimes admins need to see all data:
+
+### Super Admin Portal (No Scoping)
+
+```ruby
+# packages/super_admin_portal/lib/engine.rb
+module SuperAdminPortal
+  class Engine < Rails::Engine
+    include Plutonium::Portal::Engine
+    # No scope_to_entity = sees everything
+  end
+end
+```
+
+### Conditional Scoping
+
+```ruby
+# Custom strategy that returns nil for super admins
+def current_organization
+  return nil if current_user.super_admin?
+  current_user.organization
+end
+```
+
+When `current_scoped_entity` returns `nil`, scoping is bypassed.
+
+## Data Isolation Patterns
+
+### Shared Database, Scoped Queries (Recommended)
+
+All tenants share tables, queries filter by entity association:
+
+```ruby
+scope_to_entity Organization, strategy: :path
+```
+
+Pros:
+- Simple setup
+- Easy migrations
+- Efficient for many small tenants
+
+Cons:
+- Risk of data leakage if scoping fails
+- Complex queries for cross-tenant reports
+
+### Schema-Based Isolation
+
+Each tenant has separate database schema. This requires additional setup beyond Plutonium's built-in scoping.
+
+## Related
+
+- [Authorization](./authorization)
+- [Creating Packages](./creating-packages)
+- [Authentication](./authentication)

data/docs/guides/nested-resources.md

@@ -0,0 +1,411 @@
+# Nested Resources
+
+This guide covers setting up parent/child resource relationships.
+
+## Overview
+
+Nested resources create URLs like `/posts/1/comments` where comments belong to a specific post. Plutonium automatically handles:
+
+- Scoping queries to the parent
+- Assigning parent to new records
+- Hiding parent field in forms
+- URL generation with parent context
+- Breadcrumb navigation
+
+## Setting Up Nested Resources
+
+### 1. Define the Association
+
+```ruby
+# Parent model
+class Post < ResourceRecord
+  has_many :comments, dependent: :destroy
+end
+
+# Child model
+class Comment < ResourceRecord
+  belongs_to :post
+end
+```
+
+### 2. Register Both Resources
+
+```ruby
+# packages/admin_portal/config/routes.rb
+AdminPortal::Engine.routes.draw do
+  register_resource ::Post
+  register_resource ::Comment
+end
+```
+
+Plutonium automatically creates nested routes based on the `belongs_to` association:
+- `GET /posts/:post_id/comments`
+- `GET /posts/:post_id/comments/new`
+- `GET /posts/:post_id/comments/:id`
+- etc.
+
+### 3. Enable Association Panel
+
+Show comments on the post detail page:
+
+```ruby
+class PostPolicy < ResourcePolicy
+  def permitted_associations
+    %i[comments]
+  end
+end
+```
+
+## How It Works
+
+### Automatic Scoping
+
+When accessing `/posts/1/comments`, queries are scoped to the parent:
+
+```ruby
+# Internally uses: Comment.associated_with(post)
+# Which resolves to: Comment.where(post: post)
+```
+
+### Automatic Parent Assignment
+
+When creating a comment under a post, the parent is injected into params:
+
+```ruby
+# POST /posts/1/comments
+# resource_params automatically includes { post: <Post:1>, post_id: 1 }
+```
+
+### Automatic Field Hiding
+
+The parent field (`post`) is automatically hidden in forms since it's determined by the URL.
+
+## Controller Helpers
+
+### current_parent
+
+Returns the parent record resolved from the URL:
+
+```ruby
+# URL: /posts/123/comments
+current_parent  # => Post.find(123)
+```
+
+### parent_route_param
+
+The URL parameter containing the parent ID:
+
+```ruby
+parent_route_param  # => :post_id
+```
+
+### parent_input_param
+
+The association name on the child model:
+
+```ruby
+parent_input_param  # => :post
+```
+
+## URL Generation
+
+Use `resource_url_for` with the `parent:` option:
+
+```ruby
+# Child collection
+resource_url_for(Comment, parent: @post)
+# => /posts/123/comments
+
+# Child record
+resource_url_for(@comment, parent: @post)
+# => /posts/123/comments/456
+
+# New child form
+resource_url_for(Comment, action: :new, parent: @post)
+# => /posts/123/comments/new
+
+# Edit child
+resource_url_for(@comment, action: :edit, parent: @post)
+# => /posts/123/comments/456/edit
+```
+
+Within a nested context, `parent:` defaults to `current_parent`:
+
+```ruby
+# In CommentsController under /posts/:post_id/comments
+resource_url_for(@comment)  # parent: current_parent is automatic
+```
+
+## Presentation Hooks
+
+Control whether the parent field appears:
+
+```ruby
+class CommentsController < ResourceController
+  private
+
+  # Show parent in displays (default: false when nested)
+  def present_parent?
+    current_parent.nil?  # Only show when accessed standalone
+  end
+
+  # Allow changing parent in forms (default: same as present_parent?)
+  def submit_parent?
+    false
+  end
+end
+```
+
+## Policy Integration
+
+### Parent Authorization
+
+The parent is authorized for `:read?` before being returned:
+
+```ruby
+# Inside current_parent
+authorize! parent, to: :read?
+```
+
+### Entity Scope Context
+
+The parent is passed to child policies as `entity_scope`:
+
+```ruby
+class CommentPolicy < ResourcePolicy
+  def create?
+    # entity_scope is the parent post
+    entity_scope.present? && user.can_comment_on?(entity_scope)
+  end
+
+  def update?
+    record.user_id == user.id
+  end
+
+  def destroy?
+    record.user_id == user.id || entity_scope&.user_id == user.id
+  end
+end
+```
+
+### Additional Scoping
+
+Add role-based filtering on top of parent scoping:
+
+```ruby
+class CommentPolicy < ResourcePolicy
+  relation_scope do |relation|
+    relation = super(relation)  # Applies associated_with(entity_scope)
+
+    if user.moderator?
+      relation
+    else
+      relation.where(approved: true).or(relation.where(user: user))
+    end
+  end
+end
+```
+
+## Association Panels
+
+Associations listed in `permitted_associations` appear on the parent's show page:
+
+```ruby
+class PostPolicy < ResourcePolicy
+  def permitted_associations
+    %i[comments tags]  # Shows panels for these
+  end
+end
+```
+
+Each panel displays:
+- List of child records
+- "Add" button linking to nested new action
+- Edit/Delete actions per record
+
+## Nested Forms
+
+Edit child records inline within the parent form:
+
+### 1. Enable Nested Attributes
+
+```ruby
+class Post < ResourceRecord
+  has_many :comments
+
+  accepts_nested_attributes_for :comments,
+                                allow_destroy: true,
+                                reject_if: :all_blank
+end
+```
+
+### 2. Configure as Nested Input
+
+```ruby
+class PostDefinition < ResourceDefinition
+  input :comments, as: :nested
+end
+```
+
+### 3. Permit in Policy
+
+```ruby
+class PostPolicy < ResourcePolicy
+  def permitted_attributes_for_create
+    [:title, :content, comments_attributes: [:id, :body, :_destroy]]
+  end
+end
+```
+
+## Nesting Depth
+
+Plutonium supports **one level of nesting**:
+
+- `/posts/:post_id/comments` (parent → child)
+- `/comments/:comment_id/replies` (parent → child)
+
+Not supported:
+- `/posts/:post_id/comments/:comment_id/replies` (grandparent → parent → child)
+
+### Working with Deep Hierarchies
+
+Use through associations for data access:
+
+```ruby
+class Post < ResourceRecord
+  has_many :comments
+  has_many :replies, through: :comments
+end
+```
+
+## Custom Routes on Nested Resources
+
+Add member/collection routes:
+
+```ruby
+register_resource ::Comment do
+  member do
+    post :approve
+    post :flag
+  end
+  collection do
+    get :pending
+  end
+end
+```
+
+Generates nested routes:
+- `POST /posts/:post_id/comments/:id/approve`
+- `POST /posts/:post_id/comments/:id/flag`
+- `GET /posts/:post_id/comments/pending`
+
+## Breadcrumbs
+
+Nested resources automatically include parent in breadcrumbs:
+
+```
+Dashboard > Posts > My First Post > Comments > Comment #1
+```
+
+## Scoped Uniqueness
+
+Validate uniqueness within parent:
+
+```ruby
+class Comment < ResourceRecord
+  belongs_to :post
+  validates :position, uniqueness: { scope: :post_id }
+end
+```
+
+## Example: Blog with Comments
+
+### Models
+
+```ruby
+class Post < ResourceRecord
+  belongs_to :user
+  has_many :comments, dependent: :destroy
+
+  validates :title, :body, presence: true
+end
+
+class Comment < ResourceRecord
+  belongs_to :post
+  belongs_to :user
+
+  validates :body, presence: true
+end
+```
+
+### Policies
+
+```ruby
+class PostPolicy < ResourcePolicy
+  def create?
+    user.present?
+  end
+
+  def read?
+    true
+  end
+
+  def permitted_attributes_for_create
+    %i[title body]
+  end
+
+  def permitted_attributes_for_read
+    %i[title body user created_at]
+  end
+
+  def permitted_associations
+    %i[comments]
+  end
+end
+
+class CommentPolicy < ResourcePolicy
+  def create?
+    user.present? && entity_scope.present?
+  end
+
+  def read?
+    true
+  end
+
+  def update?
+    record.user_id == user.id
+  end
+
+  def destroy?
+    record.user_id == user.id || entity_scope&.user_id == user.id
+  end
+
+  def permitted_attributes_for_create
+    %i[body]
+  end
+
+  def permitted_attributes_for_read
+    %i[body user created_at]
+  end
+end
+```
+
+### Controller (if customization needed)
+
+```ruby
+class CommentsController < ResourceController
+  private
+
+  def build_resource
+    super.tap do |comment|
+      comment.user = current_user
+    end
+  end
+end
+```
+
+## Related
+
+- [Adding Resources](./adding-resources)
+- [Authorization](./authorization)
+- [Creating Packages](./creating-packages)