plutonium 0.33.1 → 0.34.0

data/docs/guide/deep-dive/multitenancy.md

@@ -1,256 +0,0 @@
-# Deep Dive: Multitenancy
-
-Plutonium is designed to make building sophisticated, multi-tenant applications straightforward. Multitenancy allows you to serve distinct groups of users (like different companies or teams) from a single application instance, ensuring each group's data is kept private and isolated.
-
-This is achieved through a powerful feature called **Entity Scoping**, which automates data isolation, URL generation, and authorization with minimal setup.
-
-::: tip What You'll Learn
-- The core concept of Entity Scoping
-- A step-by-step guide to configuring multitenancy
-- The practical benefits of automatic data isolation and routing
-- Advanced patterns for complex multi-tenant scenarios
-- Best practices for security, testing, and performance
-:::
-
-## How Entity Scoping Works
-
-Entity Scoping is the heart of Plutonium's multitenancy. Instead of manually filtering data in every controller and model, you declare a **Scoping Entity** for a user-facing **Portal**. This entity is typically a model like `Organization`, `Account`, or `Workspace`.
-
-Once configured, Plutonium handles the rest automatically.
-
-::: code-group
-```ruby [Without Plutonium Scoping]
-# Manual filtering is required everywhere
-class PostsController < ApplicationController
-  def index
-    # Manually find the organization and scope posts
-    @organization = Organization.find(params[:organization_id])
-    @posts = @organization.posts
-  end
-
-  def create
-    # Manually associate new records with the organization
-    @organization = Organization.find(params[:organization_id])
-    @post = @organization.posts.build(post_params)
-    # ...
-  end
-end
-```
-
-```ruby [With Plutonium Scoping]
-# Scoping is automatic and declarative
-class PostsController < ResourceController
-  def index
-    # current_authorized_scope automatically returns posts scoped to the current organization
-    # When using path strategy: URL -> /organizations/123/posts
-    # When using subdomain strategy: URL -> /posts (on acme.yourapp.com)
-  end
-
-  def create
-    # resource_params automatically includes the current organization association
-    # Scoping works regardless of the strategy used
-  end
-end
-```
-:::
-
-## Setting Up Your Multi-Tenant Portal
-
-Configuring multitenancy involves three main steps: defining your strategy, implementing it, and ensuring your models are correctly associated.
-
-### 1. Configure Your Portal Engine
-
-First, you tell your portal which entity to scope to and which strategy to use. This is done in the portal's `engine.rb` file using `scope_to_entity`.
-
-A **Scoping Strategy** tells Plutonium how to identify the current tenant for each request.
-
-::: code-group
-```ruby [Path Strategy (Most Common)]
-# packages/admin_portal/lib/engine.rb
-# Tenant is identified by a URL parameter, e.g., /organizations/:organization_id
-scope_to_entity Organization, strategy: :path
-```
-
-```ruby [Custom Strategy (Subdomain)]
-# packages/customer_portal/lib/engine.rb
-# Tenant is identified by the a custom strategy that checks the subdomain, e.g., acme.yourapp.com
-scope_to_entity Organization, strategy: :current_organization
-```
-
-```ruby [Custom Parameter Key]
-# packages/client_portal/lib/engine.rb
-# Same as :path, but with a custom parameter name.
-scope_to_entity Client,
-  strategy: :path,
-  param_key: :client_slug # URL -> /clients/:client_slug
-```
-:::
-
-You can also use any custom name for your strategy method (the method name becomes the strategy).
-
-### 2. Implement the Strategy Method
-
-If you use any strategy other than `:path`, you must implement a controller method that returns the current tenant object. The method name must exactly match the strategy name.
-
-This logic typically lives in your portal's base controller concern.
-
-::: code-group
-```ruby [Subdomain Strategy]
-# packages/customer_portal/app/controllers/customer_portal/concerns/controller.rb
-private
-
-# Method name :current_organization matches the strategy
-def current_organization
-  @current_organization ||= Organization.find_by!(subdomain: request.subdomain)
-rescue ActiveRecord::RecordNotFound
-  redirect_to root_path, error: "Invalid organization subdomain"
-end
-```
-
-```ruby [Session-Based Strategy]
-# packages/internal_portal/app/controllers/internal_portal/concerns/controller.rb
-# In engine.rb: scope_to_entity Workspace, strategy: :current_workspace
-private
-
-def current_workspace
-  return @current_workspace if defined?(@current_workspace)
-
-  workspace_id = session[:workspace_id] || params[:workspace_id]
-  @current_workspace = current_user.workspaces.find(workspace_id)
-
-  session[:workspace_id] = @current_workspace.id # Remember for next request
-  @current_workspace
-rescue ActiveRecord::RecordNotFound
-  redirect_to workspace_selection_path, error: "Please select a workspace"
-end
-```
-:::
-
-### 3. Connect Your Models
-
-Plutonium needs to understand how your resources relate to the scoping entity. It automatically discovers these relationships in three ways:
-
-::: code-group
-```ruby [1. Direct Association (Preferred)]
-# The model belongs directly to the scoping entity.
-class Post < ApplicationRecord
-  belongs_to :organization # Direct link
-end
-```
-
-```ruby [2. Indirect Association]
-# The model belongs to another model that has the direct link.
-# Plutonium automatically follows the chain: Comment -> Post -> Organization
-class Comment < ApplicationRecord
-  belongs_to :post
-  has_one :organization, through: :post # Indirect link
-end
-```
-
-```ruby [3. Custom Scope (For Complex Cases)]
-# For complex relationships, you can define an explicit scope.
-# The scope name must be `associated_with_#{scoping_entity_name}`.
-class Invoice < ApplicationRecord
-  belongs_to :customer
-
-  scope :associated_with_organization, ->(organization) do
-    joins(customer: :organization_memberships)
-      .where(organization_memberships: { organization_id: organization.id })
-  end
-end
-```
-:::
-
-## The Benefits in Practice
-
-With this setup complete, you gain several powerful features across your portal.
-
-### Tenant-Aware Routing
-
-Your application's URLs are automatically transformed to include the tenant context, and Plutonium's URL helpers adapt accordingly.
-
-- **URL Transformation:** Routes like `/posts` and `/posts/123` become `/:organization_id/posts` and `/:organization_id/posts/123`.
-- **Automatic URL Generation:** The `resource_url_for` helper automatically includes the current tenant in all generated URLs, so links and forms work without any changes.
-
-```ruby
-# Both of these helpers are automatically aware of the current tenant.
-resource_url_for(Post) # => "/organizations/456/posts"
-form_with model: @post # action -> "/organizations/456/posts/123"
-```
-
-### Secure Data Scoping
-
-All data access is automatically and securely filtered to the current tenant.
-
-- **Query Scoping:** A query like `Post.all` is automatically converted to `current_scoped_entity.posts`. This prevents accidental data leaks.
-- **Record Scoping:** When fetching a single record (e.g., for `show` or `edit`), Plutonium ensures it belongs to the current tenant. If not, it raises an `ActiveRecord::RecordNotFound` error, just as if the record didn't exist.
-
-### Integrated Authorization
-
-The current `entity_scope` is seamlessly passed to your authorization policies, allowing for fine-grained, tenant-aware rules.
-
-```ruby
-class PostPolicy < Plutonium::Resource::Policy
-  # `entity_scope` is automatically available in all policy methods.
-  authorize :entity_scope, allow_nil: true
-
-  def update?
-    # A user can only update a post if it belongs to their current tenant
-    # AND they are the author of the post.
-    record.organization == entity_scope && record.author == user
-  end
-
-  relation_scope do |relation|
-    # `super` automatically applies the base entity scoping.
-    relation = super(relation)
-
-    # Add more logic: Admins can see all posts within their organization,
-    # but others can only see published posts.
-    user.admin? ? relation : relation.where(published: true)
-  end
-end
-```
-
-## Security Best Practices
-
-Securing a multi-tenant application is critical. While Plutonium provides strong defaults, you must ensure your implementation is secure.
-
-::: warning Always Validate Tenant Access
-A user might belong to multiple tenants. It's crucial to verify that the logged-in user has permission to access the tenant specified in the URL. Failure to do so could allow a user to see data from another organization they don't belong to.
-:::
-
-```ruby
-# ✅ Good: Proper tenant validation
-# In your custom strategy method or a before_action:
-private
-
-def current_organization
-  @current_organization ||= begin
-    # Find the organization from the URL
-    organization = Organization.find(params[:organization_id])
-
-    # CRITICAL: Verify the current user is a member of that organization
-    unless current_user.organizations.include?(organization)
-      raise ActionPolicy::Unauthorized, "Access denied to organization"
-    end
-
-    organization
-  end
-end
-
-# ❌ Dangerous: No access validation
-def current_organization
-  # This allows ANY authenticated user to access ANY organization's data
-  # simply by changing the ID in the URL.
-  Organization.find(params[:organization_id])
-end
-```
-
-## Advanced Patterns
-
-Plutonium's scoping is flexible enough to handle more complex scenarios.
-
-- **Multi-Level Tenancy:** For hierarchical tenancy (e.g., Company -> Department), you can apply the primary scope at the engine level and add secondary scoping logic inside your policies' `relation_scope`.
-- **Cross-Tenant Data Access:** For resources that can be shared, define a custom `associated_with_...` scope that includes both shared records and records belonging to the current tenant.
-- **Tenant Switching:** Build a controller that allows users to change their active tenant by updating a `session` key, then use a session-based scoping strategy to read it.
-- **API Multitenancy:** Create a custom scoping strategy (e.g., `:api_tenant`) that authenticates and identifies the tenant based on an API key or JWT from the request headers.

data/docs/guide/deep-dive/resources.md

@@ -1,390 +0,0 @@
-# Working with Resources
-
-::: tip What you'll learn
-- How to create and manage resources in Plutonium
-- Understanding resource definitions and configurations
-- Working with fields, associations, and nested resources
-- Implementing resource policies and scoping
-- Best practices for resource organization
-:::
-
-## Introduction
-
-Resources are the core building blocks of a Plutonium application. A resource represents a model in your application that can be managed through a consistent interface, complete with views, controllers, and policies.
-
-## Creating a Resource
-
-The fastest way to create a resource is using the scaffold generator:
-
-```bash
-rails generate pu:res:scaffold Blog user:belongs_to \
-  title:string content:text 'published_at:datetime?'
-```
-
-This generates several files, including:
-
-::: code-group
-```ruby [app/models/blog.rb]
-class Blog < ResourceRecord
-  belongs_to :user
-end
-```
-
-```ruby [app/policies/blog_policy.rb]
-class BlogPolicy < Plutonium::Resource::Policy
-  def create?
-    true
-  end
-
-  def read?
-    true
-  end
-
-  def permitted_attributes_for_create
-    %i[user title content published_at]
-  end
-
-  def permitted_attributes_for_read
-    %i[user title content published_at]
-  end
-end
-```
-
-```ruby [app/definitions/blog_definition.rb]
-class BlogDefinition < Plutonium::Resource::Definition
-end
-```
-:::
-
-## Resource Definitions
-
-Resource definitions customize how a resource behaves in your application. They define:
-- Fields and their types
-- Available actions
-- Search and filtering capabilities
-- Sorting options
-- Display configurations
-
-### Basic Field Configuration
-
-::: code-group
-```ruby [Simple Fields]
-class BlogDefinition < Plutonium::Resource::Definition
-  # Basic field definitions
-  field :content, as: :text
-
-  # Field with custom display options
-  field :published_at,
-        as: :datetime,
-        hint: "When this post should be published"
-end
-```
-
-```ruby [Custom Displays]
-class BlogDefinition < Plutonium::Resource::Definition
-  # Customize how fields are displayed
-  display :title, wrapper: {class: "col-span-full"}
-  display :content, wrapper: {class: "col-span-full"} do |f|
-    f.text_tag class: "format dark:format-invert"
-  end
-
-  # Custom column display in tables
-  column :published_at, align: :end
-end
-```
-:::
-
-<!--
-### Working with Associations
-
-Plutonium makes it easy to work with Rails associations:
-
-```ruby
-class BlogDefinition < Plutonium::Resource::Definition
-  # Define belongs_to association
-  field :user, as: :belongs_to
-
-  # Has-many association with inline creation
-  field :comments do |f|
-    f.has_many_tag nested: true
-  end
-
-  # Configure nested attributes
-  define_nested_input :comments,
-    inputs: %i[content user],
-    limit: 3 do |input|
-      input.define_field_input :content,
-        type: :text,
-        hint: "Keep it constructive"
-    end
-end
-```
--->
-
-### Adding Custom Actions
-
-Beyond CRUD, you can add custom actions to your resources:
-
-```ruby
-# app/interactions/blogs/publish.rb
-module Blogs
-  class Publish < Plutonium::Resource::Interaction
-    # Define what this interaction accepts
-    attribute :resource, class: Blog
-    attribute :publish_date, :date, default: -> { Time.current }
-
-    presents label: "Publish Blog",
-             icon: Phlex::TablerIcons::Send,
-             description: "Make this blog post public"
-
-    private
-
-    def execute
-      if resource.update(
-        published_at: publish_date
-      )
-        succeed(resource)
-          .with_message("Blog post published successfully")
-          .with_redirect_response(resource)
-      else
-        failed(resource.errors)
-      end
-    end
-  end
-end
-
-# app/definitions/blog_definition.rb
-class BlogDefinition < Plutonium::Resource::Definition
-  # Register the custom action
-  action :publish,
-    interaction: Blogs::Publish,
-    category: :primary
-end
-```
-
-### Search and Filtering
-
-Add search and filtering capabilities to your resources:
-
-```ruby
-class BlogDefinition < Plutonium::Resource::Definition
-  # Enable full-text search
-  search do |scope, query|
-    scope.where("title ILIKE ? OR content ILIKE ?",
-      "%#{query}%", "%#{query}%")
-  end
-
-  # Add filters
-  filter :published_at,
-    with: DateFilter,
-    predicate: :gteq
-
-  # Add scopes
-  scope :published do |scope|
-    scope.where.not(published_at: nil)
-  end
-  scope :draft do |scope|
-    scope.where(published_at: nil)
-  end
-
-  # Configure sorting
-  sort :title
-  sort :published_at
-  
-  # Configure default sorting (newest first)
-  default_sort :published_at, :desc
-end
-```
-
-## Resource Policies
-
-Policies control access to your resources:
-
-```ruby
-class BlogPolicy < Plutonium::Resource::Policy
-  def permitted_attributes_for_create
-    %i[title content state published_at user_id]
-  end
-
-  def permitted_associations
-    %i[comments]
-  end
-
-  def create?
-    # Allow logged in users to create blogs
-    user.present?
-  end
-
-  def update?
-    # Users can only edit their own blogs
-    record.user_id == user.id
-  end
-
-  def publish?
-    # Only editors can publish
-    user.editor? && record.draft?
-  end
-
-  # Scope visible records
-  relation_scope do |relation|
-    relation = super(relation)
-    next relation unless user.admin?
-
-    relation.with_deleted
-  end
-end
-```
-
-## Best Practices
-
-::: tip Resource Organization
-1. Keep resource definitions focused and cohesive
-2. Use packages to organize related resources
-3. Leverage policy scopes for authorization
-4. Extract complex logic into interactions
-5. Use presenters for view-specific logic
-:::
-
-::: warning Common Pitfalls
-- Avoid putting business logic in definitions
-- Don't bypass policy checks
-- Remember to scope resources appropriately
-- Test your interactions and policies
-:::
-
-# Deep Dive: Building a Resource
-
-In Plutonium, a **Resource** is the central concept for managing your application's data. It's more than just a model—it's a complete package that includes the model, controller, policy, views, and all the configuration that ties them together.
-
-This guide will walk you through building a complete `Post` resource from scratch, demonstrating how Plutonium's different modules work together to create a powerful and consistent user experience.
-
-## 1. Generating the Resource
-
-We'll start with the scaffold generator, which creates all the necessary files for our `Post` resource.
-
-```bash
-rails generate pu:res:scaffold Post user:belongs_to title:string content:text published_at:datetime
-```
-
-This command generates:
-- A `Post` model with the specified attributes and a `belongs_to :user` association.
-- A `PostsController`.
-- A `PostPolicy` with basic permissions.
-- A `PostDefinition` file, which will be the focus of this guide.
-
-## 2. Configuring Display & Forms (The Definition File)
-
-The **Definition** file (`app/definitions/post_definition.rb`) is where you declaratively configure how your resource is displayed and edited. Let's start by defining the fields for our table, detail page, and form.
-
-::: code-group
-```ruby [app/definitions/post_definition.rb]
-class PostDefinition < Plutonium::Resource::Definition
-  # Configure the table (index view)
-  column :user, label: "Author"
-  column :published_at, as: :datetime
-
-  # Configure the detail page (show view)
-  display :user, label: "Author"
-  display :published_at, as: :datetime
-  display :content, as: :rich_text
-
-  # Configure the form (new/edit views)
-  input :user, as: :select, label: "Author" # Explicitly use a select input
-  input :content, as: :rich_text
-end
-```
-```ruby [app/policies/post_policy.rb]
-# In the policy, we must permit these attributes to be read and written.
-class PostPolicy < Plutonium::Resource::Policy
-  # ...
-
-  def permitted_attributes_for_read
-    [:title, :user, :published_at, :content]
-  end
-
-  def permitted_attributes_for_create
-    [:title, :user_id, :content]
-  end
-
-  def permitted_attributes_for_update
-    permitted_attributes_for_create
-  end
-end
-```
-:::
-
-Here, we've used the `display` helper to control the `index` and `show` views, and the `input` helper for the forms. We've also specified `:rich_text` to get a WYSIWYG editor for our content. Notice that we also had to permit these attributes in the policy.
-
-## 3. Adding a Custom Action
-
-Standard CRUD is great, but most applications have custom business logic. Let's add a "Publish" action. This involves creating an **Interaction** for the logic and registering it in the definition.
-
-::: code-group
-```ruby [app/interactions/post_interactions/publish.rb]
-module PostInteractions
-  class Publish < Plutonium::Resource::Interaction
-    attribute :resource, class: "Post"
-
-    private
-
-    def execute
-      resource.update(published_at: Time.current)
-      succeed(resource).with_message("Post was successfully published.")
-    end
-  end
-end
-```
-```ruby [app/definitions/post_definition.rb]
-class PostDefinition < Plutonium::Resource::Definition
-  # ... (display and input helpers)
-
-  action :publish,
-    interaction: "PostInteractions::Publish",
-    category: :primary
-end
-```
-```ruby [app/policies/post_policy.rb]
-class PostPolicy < Plutonium::Resource::Policy
-  # ... (attribute permissions)
-
-  # An action is only visible if its policy returns true.
-  def publish?
-    # Only show the publish button if the post is not yet published.
-    update? && record.published_at.nil?
-  end
-end
-```
-:::
-
-We now have a "Publish" button on our `Post` detail page that only appears when appropriate, thanks to the combination of the Interaction, Definition, and Policy.
-
-## 4. Configuring Search, Filters, and Sorting
-
-To make our resource table more useful, let's add search, filtering, and sorting capabilities. This is all handled declaratively in the definition file.
-
-```ruby
-# app/definitions/post_definition.rb
-class PostDefinition < Plutonium::Resource::Definition
-  # ... (display, input, and action helpers)
-
-  # Enable full-text search across title and content
-  search do |scope, query|
-    scope.where("title ILIKE :q OR content ILIKE :q", q: "%#{query}%")
-  end
-
-  # Add filters to the sidebar
-  filter :published, with: ->(scope, value) { value ? scope.where.not(published_at: nil) : scope.where(published_at: nil) }, as: :boolean
-  filter :user, as: :select, choices: User.pluck(:name, :id)
-
-  # Define named scopes that appear as buttons
-  scope :all
-  scope :published, -> { where.not(published_at: nil) }
-  scope :drafts, -> { where(published_at: nil) }
-
-  # Configure which columns are sortable
-  sort :title
-  sort :published_at
-end
-```
-
-With just a few lines of code, we now have a powerful and interactive table view for our posts, complete with a search bar, filter sidebar, scope buttons, and sortable columns. This demonstrates how the **Resource** module integrates seamlessly with the **Query** module.