rubyn-code 0.1.0

data/skills/rails/caching.md

@@ -0,0 +1,158 @@
+# Rails: Caching
+
+## Pattern
+
+Cache at the right layer for the right duration. Rails provides fragment caching (views), low-level caching (arbitrary data), Russian doll caching (nested fragments), and HTTP caching (ETags). Use the cheapest cache that satisfies the freshness requirement.
+
+### Low-Level Caching (Most Versatile)
+
+```ruby
+# Cache expensive queries or computations
+class DashboardService
+  def call(user)
+    {
+      order_count: cached_order_count(user),
+      revenue: cached_revenue(user),
+      top_products: cached_top_products(user)
+    }
+  end
+
+  private
+
+  def cached_order_count(user)
+    Rails.cache.fetch("dashboard:#{user.id}:order_count", expires_in: 15.minutes) do
+      user.orders.count
+    end
+  end
+
+  def cached_revenue(user)
+    Rails.cache.fetch("dashboard:#{user.id}:revenue", expires_in: 15.minutes) do
+      user.orders.shipped.sum(:total)
+    end
+  end
+
+  def cached_top_products(user)
+    Rails.cache.fetch("dashboard:#{user.id}:top_products", expires_in: 1.hour) do
+      user.orders
+        .joins(line_items: :product)
+        .group("products.name")
+        .order("count_all DESC")
+        .limit(5)
+        .count
+    end
+  end
+end
+```
+
+### Cache Key Design
+
+```ruby
+# Key-based expiration — cache auto-expires when the record changes
+class Order < ApplicationRecord
+  def cache_key_with_version
+    "orders/#{id}-#{updated_at.to_i}"
+  end
+end
+
+# Collection cache keys
+Rails.cache.fetch(["v1/orders", current_user.orders.cache_key_with_version]) do
+  current_user.orders.includes(:line_items).map(&:as_json)
+end
+
+# Manual invalidation when needed
+def invalidate_dashboard_cache(user)
+  Rails.cache.delete_matched("dashboard:#{user.id}:*")
+end
+```
+
+### Fragment Caching (Views)
+
+```erb
+<%# Russian doll caching — outer cache wraps inner caches %>
+<% cache @order do %>
+  <h2><%= @order.reference %></h2>
+  <p>Total: <%= number_to_currency(@order.total / 100.0) %></p>
+
+  <% @order.line_items.each do |item| %>
+    <%# Inner cache — only re-renders if item changes %>
+    <% cache item do %>
+      <div class="line-item">
+        <%= item.product.name %> x <%= item.quantity %>
+      </div>
+    <% end %>
+  <% end %>
+<% end %>
+```
+
+### HTTP Caching
+
+```ruby
+class Api::V1::ProductsController < Api::V1::BaseController
+  # ETag-based — returns 304 Not Modified if content hasn't changed
+  def show
+    product = Product.find(params[:id])
+
+    if stale?(product)
+      render json: ProductSerializer.new(product).as_json
+    end
+  end
+
+  # Time-based — client caches for the specified duration
+  def index
+    expires_in 5.minutes, public: true
+
+    products = Product.active.order(:name)
+    render json: products.map { |p| ProductSerializer.new(p).as_json }
+  end
+end
+```
+
+### Counter Caches (Database-Level Caching)
+
+```ruby
+# Migration
+add_column :users, :orders_count, :integer, default: 0, null: false
+
+# Model
+class Order < ApplicationRecord
+  belongs_to :user, counter_cache: true
+end
+
+# Now user.orders_count is a column read, not a COUNT(*) query
+# Updated automatically on Order create/destroy
+```
+
+## Why This Is Good
+
+- **`Rails.cache.fetch` is atomic.** If the cache misses, the block runs, and the result is stored. No race conditions between check and set.
+- **Key-based expiration is self-managing.** `"orders/#{id}-#{updated_at.to_i}"` automatically expires when the record is updated. No manual invalidation needed.
+- **Russian doll caching is granular.** When one line item changes, only that item's fragment re-renders. The order fragment and other items serve from cache.
+- **HTTP caching offloads the server.** ETags and `expires_in` let browsers and CDNs serve cached responses without hitting your app at all.
+- **Counter caches eliminate N+1 counts.** Displaying `user.orders_count` for 50 users is 0 queries instead of 50.
+
+## Anti-Pattern
+
+Caching without expiration or invalidation:
+
+```ruby
+# BAD: Cache forever with no expiration
+Rails.cache.write("all_products", Product.all.to_a)  # Never expires, grows stale
+
+# BAD: Over-caching mutable data
+Rails.cache.fetch("user:#{user.id}", expires_in: 24.hours) do
+  user.attributes  # User could change their email, name, plan in 24 hours
+end
+```
+
+## When To Apply
+
+- **Expensive queries displayed on every page load.** Dashboard counts, leaderboards, aggregate stats.
+- **Rarely-changing reference data.** Product catalogs, category trees, configuration.
+- **API responses that many clients request.** HTTP caching with CDNs.
+- **View fragments with complex rendering.** Partial renders that involve multiple queries or helpers.
+
+## When NOT To Apply
+
+- **Data that must be real-time.** Account balances, stock levels, live order status. Stale caches here cause user-visible bugs.
+- **Simple queries that are already fast.** Caching a `find_by(id:)` that takes 1ms adds complexity without meaningful speedup.
+- **In development.** Enable caching in development only when actively debugging cache behavior: `rails dev:cache`.

data/skills/rails/callbacks.md

@@ -0,0 +1,135 @@
+# Rails: ActiveRecord Callbacks
+
+## Pattern
+
+Use callbacks only for concerns that are intrinsic to data integrity — things that must always happen whenever the record changes, regardless of context. Everything else belongs in service objects.
+
+Safe callback use cases:
+
+```ruby
+class Order < ApplicationRecord
+  # GOOD: Normalizing data before save — this should always happen
+  before_validation :normalize_email
+  before_validation :generate_reference, on: :create
+
+  # GOOD: Maintaining data integrity
+  before_save :calculate_total, if: :line_items_changed?
+
+  # GOOD: Cleaning up owned resources
+  after_destroy :purge_attached_files
+
+  private
+
+  def normalize_email
+    self.email = email&.downcase&.strip
+  end
+
+  def generate_reference
+    self.reference ||= "ORD-#{SecureRandom.hex(6).upcase}"
+  end
+
+  def calculate_total
+    self.total = line_items.sum { |item| item.quantity * item.unit_price }
+  end
+
+  def purge_attached_files
+    receipt.purge_later if receipt.attached?
+  end
+end
+```
+
+## Why This Is Good
+
+- **Predictable.** Callbacks for data normalization and integrity are expected behavior. Every developer knows `before_validation` might downcase an email. Nobody expects `after_create` to charge a credit card.
+- **Context-independent.** Normalizing an email should happen whether the record is created via web form, API, console, seed file, or test factory. That's intrinsic to the data.
+- **No surprises in tests.** When a test creates an Order, it gets a reference number and a calculated total. It does NOT send emails, charge cards, or hit external APIs.
+- **Safe to call from anywhere.** `Order.create!(params)` works correctly from a controller, a Sidekiq job, a rake task, or the Rails console — because the callbacks only handle data integrity.
+
+## Anti-Pattern
+
+Using callbacks for business logic, side effects, and cross-model operations:
+
+```ruby
+class Order < ApplicationRecord
+  after_create :send_confirmation_email
+  after_create :notify_warehouse
+  after_create :update_product_inventory
+  after_create :award_loyalty_points
+  after_create :track_analytics_event
+
+  after_update :send_status_change_email, if: :saved_change_to_status?
+  after_update :refund_if_cancelled, if: -> { saved_change_to_status?(to: "cancelled") }
+
+  after_destroy :restore_inventory
+  after_destroy :send_cancellation_email
+
+  private
+
+  def send_confirmation_email
+    OrderMailer.confirmation(self).deliver_later
+  end
+
+  def notify_warehouse
+    WarehouseApi.new.notify(order_id: id, items: line_items.map(&:sku))
+  end
+
+  def update_product_inventory
+    line_items.each do |item|
+      item.product.decrement!(:stock, item.quantity)
+    end
+  end
+
+  def award_loyalty_points
+    user.increment!(:loyalty_points, (total / 10).floor)
+  end
+
+  def track_analytics_event
+    Analytics.track("order_created", order_id: id, total: total)
+  end
+end
+```
+
+## Why This Is Bad
+
+- **Hidden side effects.** A developer running `Order.create!(params)` in the console to fix a data issue accidentally sends a confirmation email, notifies a warehouse, decrements inventory, awards loyalty points, and fires an analytics event. None of this is visible from the call site.
+- **Tests become slow and fragile.** Every test that creates an order triggers the full callback chain. You need to stub mailers, mock external APIs, and create associated products with sufficient stock. Factory creation becomes a minefield.
+- **Ordering problems.** Callbacks run in declaration order. If `notify_warehouse` depends on `update_product_inventory` having run first, reordering the declarations breaks the app silently.
+- **Impossible to skip selectively.** You can't create an order without sending an email unless you add flags (`skip_email: true`) that pollute the model with callback control logic.
+- **Transaction danger.** `after_create` runs inside the transaction. If `notify_warehouse` raises an HTTP error, the entire order creation rolls back — even though the order itself was valid.
+- **Circular dependencies.** Callback A on Order updates Product stock. A callback on Product recalculates availability. That triggers a callback that touches Order again. Infinite loops are hard to debug.
+
+## When To Apply
+
+Use callbacks ONLY for these purposes:
+
+- **Data normalization** — downcasing emails, stripping whitespace, formatting phone numbers, generating slugs/tokens
+- **Default values** — setting a reference number, a UUID, a default status on creation
+- **Derived calculations** — computing a total from line items, a full name from first + last
+- **Cleanup of owned resources** — purging Active Storage attachments, removing associated cache entries
+- **Counter maintenance** — only when `counter_cache` on the association isn't sufficient
+
+The test: "If I create this record from the Rails console with no other context, should this behavior still happen?" If yes → callback. If no → service object.
+
+## When NOT To Apply
+
+Do NOT use callbacks for:
+
+- **Sending emails or notifications.** These are side effects that depend on context. An order created by an admin backfill should not trigger a customer email.
+- **Calling external APIs.** Webhooks, warehouse notifications, payment charges. These fail independently and should not roll back the record.
+- **Modifying other models.** Updating inventory, awarding points, creating audit records. These are business logic, not data integrity.
+- **Enqueuing background jobs.** Use service objects that explicitly enqueue after the primary operation succeeds.
+- **Anything with `if:` conditions based on business context.** If a callback needs `if: :registering?` or `if: :from_api?`, it's not intrinsic to the data — it's business logic wearing a callback costume.
+
+## Edge Cases
+
+**The team already has callbacks everywhere:**
+Don't rip them all out at once. When modifying a model, extract the business-logic callbacks into a service object one at a time. Leave the data-integrity callbacks in place.
+
+**`after_commit` vs `after_create`:**
+If you must trigger a side effect from a model (not recommended, but sometimes pragmatic), use `after_commit` instead of `after_create`. It runs after the transaction commits, so a failure won't roll back the record. But this is still a code smell — prefer service objects.
+
+**Gems that require callbacks (like `acts_as_paranoid`, `paper_trail`):**
+These are fine. They manage data integrity (soft deletes, audit trails) which is a legitimate callback concern. The gem handles the complexity.
+
+**Touch callbacks (`belongs_to :order, touch: true`):**
+These are fine — they maintain cache integrity and are intrinsic to the data relationship.

data/skills/rails/concerns_controllers.md

@@ -0,0 +1,218 @@
+# Rails: Controller Concerns
+
+## Pattern
+
+Use controller concerns for cross-cutting HTTP behavior shared across multiple controllers — authentication helpers, pagination, error handling, and response formatting. Keep concerns focused on one capability.
+
+```ruby
+# app/controllers/concerns/authenticatable.rb
+module Authenticatable
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :authenticate_user!
+    helper_method :current_user
+  end
+
+  private
+
+  def current_user
+    @current_user ||= User.find_by(id: session[:user_id])
+  end
+
+  def authenticate_user!
+    redirect_to login_path, alert: "Please log in" unless current_user
+  end
+end
+```
+
+```ruby
+# app/controllers/concerns/paginatable.rb
+module Paginatable
+  extend ActiveSupport::Concern
+
+  private
+
+  def paginate(scope, per_page: 25)
+    scope.page(params[:page]).per(per_page)
+  end
+
+  def pagination_meta(collection)
+    {
+      current_page: collection.current_page,
+      total_pages: collection.total_pages,
+      total_count: collection.total_count,
+      per_page: collection.limit_value
+    }
+  end
+end
+```
+
+```ruby
+# app/controllers/concerns/api_error_handling.rb
+module ApiErrorHandling
+  extend ActiveSupport::Concern
+
+  included do
+    rescue_from ActiveRecord::RecordNotFound, with: :not_found
+    rescue_from ActiveRecord::RecordInvalid, with: :unprocessable
+    rescue_from ActionController::ParameterMissing, with: :bad_request
+  end
+
+  private
+
+  def not_found(exception)
+    render json: { error: "Not found", detail: exception.message }, status: :not_found
+  end
+
+  def unprocessable(exception)
+    render json: { error: "Validation failed", details: exception.record.errors.full_messages }, status: :unprocessable_entity
+  end
+
+  def bad_request(exception)
+    render json: { error: "Bad request", detail: exception.message }, status: :bad_request
+  end
+end
+```
+
+Usage — compose focused concerns:
+
+```ruby
+class Api::V1::BaseController < ActionController::API
+  include Authenticatable
+  include Paginatable
+  include ApiErrorHandling
+end
+
+class Api::V1::OrdersController < Api::V1::BaseController
+  def index
+    orders = paginate(current_user.orders.recent)
+    render json: { orders: orders, meta: pagination_meta(orders) }
+  end
+end
+```
+
+## Why This Is Good
+
+- **Single responsibility per concern.** `Authenticatable` handles auth. `Paginatable` handles pagination. `ApiErrorHandling` handles errors. Each is independently understandable and testable.
+- **Composable.** A controller includes the concerns it needs. An API controller includes `ApiErrorHandling`. A web controller includes `WebErrorHandling` instead. No monolithic base class.
+- **DRY across controllers.** Pagination logic is identical across every index action. Writing it once in a concern prevents copy-paste and ensures consistency.
+- **`rescue_from` in a concern centralizes error handling.** Every API controller inheriting from `BaseController` gets consistent error responses for common exceptions without any per-controller code.
+
+## Anti-Pattern
+
+Concerns with business logic, controller-specific behavior, or too many responsibilities:
+
+```ruby
+# BAD: Business logic in a controller concern
+module OrderProcessing
+  extend ActiveSupport::Concern
+
+  private
+
+  def process_order(order)
+    validate_inventory(order)
+    calculate_total(order)
+    apply_discount(order)
+    charge_payment(order)
+    send_confirmation(order)
+    notify_warehouse(order)
+  end
+
+  def validate_inventory(order)
+    order.line_items.each do |item|
+      raise "Out of stock" if item.product.stock < item.quantity
+    end
+  end
+
+  def calculate_total(order)
+    order.total = order.line_items.sum { |li| li.quantity * li.price }
+  end
+
+  # ... 50 more lines of business logic
+end
+```
+
+```ruby
+# BAD: Concern used by only one controller
+module OrdersControllerHelpers
+  extend ActiveSupport::Concern
+
+  private
+
+  def set_order
+    @order = current_user.orders.find(params[:id])
+  end
+
+  def order_params
+    params.require(:order).permit(:address, :notes)
+  end
+end
+```
+
+## Why This Is Bad
+
+- **Business logic in a controller concern is still business logic in a controller.** Moving `process_order` from the controller to a concern doesn't fix the architecture — it just moves the problem to a different file. This belongs in a service object.
+- **Single-use concerns add indirection.** `OrdersControllerHelpers` is included in one controller. Opening the controller, you see `include OrdersControllerHelpers` and have to navigate to another file to find `set_order`. Just define `set_order` in the controller directly.
+- **Fat concerns replace fat controllers.** If the concern is 100 lines of business logic, the controller's responsibilities haven't shrunk — they've been scattered.
+
+## When To Apply
+
+- **Cross-cutting HTTP concerns** used by 3+ controllers: authentication, authorization, pagination, error handling, logging, CORS, request throttling.
+- **Response formatting** shared across API controllers: consistent JSON error shapes, pagination metadata, HATEOAS links.
+- **`before_action` chains** that are identical across controllers: `authenticate_user!`, `set_locale`, `verify_csrf_token`.
+
+## When NOT To Apply
+
+- **Business logic.** Inventory validation, payment processing, email sending — these belong in service objects, not controller concerns.
+- **Behavior for one controller.** If only `OrdersController` uses it, keep it in `OrdersController`. A concern for one consumer is just indirection.
+- **Model-level logic.** If the concern accesses `ActiveRecord` methods or database queries, it probably belongs on the model or in a query object, not in a controller concern.
+
+## Edge Cases
+
+**Concern needs configuration per controller:**
+Use class methods or class attributes:
+
+```ruby
+module RateLimitable
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :rate_limit_per_minute, default: 60
+    before_action :check_rate_limit
+  end
+
+  private
+
+  def check_rate_limit
+    key = "rate_limit:#{current_user.id}:#{controller_name}"
+    count = Rails.cache.increment(key, 1, expires_in: 1.minute)
+    head :too_many_requests if count > self.class.rate_limit_per_minute
+  end
+end
+
+class Api::V1::AiController < Api::V1::BaseController
+  include RateLimitable
+  self.rate_limit_per_minute = 20  # Stricter limit for AI endpoints
+end
+```
+
+**Testing concerns in isolation:**
+Create an anonymous controller in the spec:
+
+```ruby
+RSpec.describe Authenticatable, type: :controller do
+  controller(ApplicationController) do
+    include Authenticatable
+
+    def index
+      render json: { user: current_user.email }
+    end
+  end
+
+  it "redirects unauthenticated users" do
+    get :index
+    expect(response).to redirect_to(login_path)
+  end
+end
+```