aigroup-workflow 2.1.1 → 2.2.0

package/skills/ruby/rails-expert/references/api-development.md

@@ -0,0 +1,401 @@
+# API Development
+
+## API-Only Rails Application
+
+```ruby
+# Generate API-only app
+rails new myapp --api
+
+# config/application.rb
+module MyApp
+  class Application < Rails::Application
+    config.api_only = true
+    config.load_defaults 7.1
+  end
+end
+
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::API
+  include ActionController::HttpAuthentication::Token::ControllerMethods
+
+  before_action :authenticate
+
+  rescue_from ActiveRecord::RecordNotFound, with: :not_found
+  rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
+
+  private
+
+  def authenticate
+    authenticate_token || render_unauthorized
+  end
+
+  def authenticate_token
+    authenticate_with_http_token do |token, options|
+      @current_user = User.find_by(api_token: token)
+    end
+  end
+
+  def render_unauthorized
+    render json: { error: 'Unauthorized' }, status: :unauthorized
+  end
+
+  def not_found
+    render json: { error: 'Not found' }, status: :not_found
+  end
+
+  def unprocessable_entity(exception)
+    render json: { errors: exception.record.errors }, status: :unprocessable_entity
+  end
+end
+```
+
+## RESTful API Controller
+
+```ruby
+# app/controllers/api/v1/posts_controller.rb
+module Api
+  module V1
+    class PostsController < ApplicationController
+      before_action :set_post, only: [:show, :update, :destroy]
+
+      # GET /api/v1/posts
+      def index
+        @posts = Post.includes(:user)
+                    .page(params[:page])
+                    .per(params[:per_page] || 20)
+
+        render json: @posts, meta: pagination_meta(@posts)
+      end
+
+      # GET /api/v1/posts/:id
+      def show
+        render json: @post, include: [:user, :comments]
+      end
+
+      # POST /api/v1/posts
+      def create
+        @post = current_user.posts.build(post_params)
+
+        if @post.save
+          render json: @post, status: :created, location: api_v1_post_url(@post)
+        else
+          render json: { errors: @post.errors }, status: :unprocessable_entity
+        end
+      end
+
+      # PATCH/PUT /api/v1/posts/:id
+      def update
+        if @post.update(post_params)
+          render json: @post
+        else
+          render json: { errors: @post.errors }, status: :unprocessable_entity
+        end
+      end
+
+      # DELETE /api/v1/posts/:id
+      def destroy
+        @post.destroy
+        head :no_content
+      end
+
+      private
+
+      def set_post
+        @post = Post.find(params[:id])
+      end
+
+      def post_params
+        params.require(:post).permit(:title, :body, :published)
+      end
+
+      def pagination_meta(collection)
+        {
+          current_page: collection.current_page,
+          total_pages: collection.total_pages,
+          total_count: collection.total_count
+        }
+      end
+    end
+  end
+end
+```
+
+## Serialization with ActiveModel::Serializers
+
+```ruby
+# Gemfile
+gem 'active_model_serializers'
+
+# app/serializers/post_serializer.rb
+class PostSerializer < ActiveModel::Serializer
+  attributes :id, :title, :body, :published, :created_at
+
+  belongs_to :user
+  has_many :comments
+
+  # Conditional attributes
+  attribute :draft_content, if: :current_user_is_author?
+
+  # Custom attributes
+  def published_date
+    object.created_at.strftime("%Y-%m-%d")
+  end
+
+  private
+
+  def current_user_is_author?
+    current_user == object.user
+  end
+end
+
+# app/serializers/user_serializer.rb
+class UserSerializer < ActiveModel::Serializer
+  attributes :id, :username, :email
+
+  # Exclude sensitive data
+  def email
+    return nil unless current_user&.admin?
+    object.email
+  end
+end
+```
+
+## JWT Authentication
+
+```ruby
+# Gemfile
+gem 'jwt'
+
+# app/lib/json_web_token.rb
+class JsonWebToken
+  SECRET_KEY = Rails.application.credentials.secret_key_base
+
+  def self.encode(payload, exp = 24.hours.from_now)
+    payload[:exp] = exp.to_i
+    JWT.encode(payload, SECRET_KEY)
+  end
+
+  def self.decode(token)
+    decoded = JWT.decode(token, SECRET_KEY)[0]
+    HashWithIndifferentAccess.new(decoded)
+  rescue JWT::DecodeError
+    nil
+  end
+end
+
+# app/controllers/api/v1/authentication_controller.rb
+module Api
+  module V1
+    class AuthenticationController < ApplicationController
+      skip_before_action :authenticate, only: [:create]
+
+      # POST /api/v1/auth/login
+      def create
+        user = User.find_by(email: params[:email])
+
+        if user&.authenticate(params[:password])
+          token = JsonWebToken.encode(user_id: user.id)
+          render json: { token: token, user: UserSerializer.new(user) }
+        else
+          render json: { error: 'Invalid credentials' }, status: :unauthorized
+        end
+      end
+    end
+  end
+end
+
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::API
+  before_action :authenticate_request
+
+  attr_reader :current_user
+
+  private
+
+  def authenticate_request
+    header = request.headers['Authorization']
+    token = header.split(' ').last if header
+
+    decoded = JsonWebToken.decode(token)
+    @current_user = User.find(decoded[:user_id]) if decoded
+
+    render json: { error: 'Unauthorized' }, status: :unauthorized unless @current_user
+  rescue ActiveRecord::RecordNotFound
+    render json: { error: 'Unauthorized' }, status: :unauthorized
+  end
+end
+```
+
+## API Versioning
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  namespace :api do
+    namespace :v1 do
+      resources :posts
+      resources :users
+
+      post '/auth/login', to: 'authentication#create'
+    end
+
+    namespace :v2 do
+      resources :posts
+    end
+  end
+end
+
+# app/controllers/api/v1/base_controller.rb
+module Api
+  module V1
+    class BaseController < ApplicationController
+      # V1 specific logic
+    end
+  end
+end
+```
+
+## Rate Limiting
+
+```ruby
+# Gemfile
+gem 'rack-attack'
+
+# config/initializers/rack_attack.rb
+class Rack::Attack
+  # Throttle all requests by IP
+  throttle('req/ip', limit: 300, period: 5.minutes) do |req|
+    req.ip
+  end
+
+  # Throttle login attempts by email
+  throttle('logins/email', limit: 5, period: 20.seconds) do |req|
+    if req.path == '/api/v1/auth/login' && req.post?
+      req.params['email'].to_s.downcase.gsub(/\s+/, "")
+    end
+  end
+
+  # Block suspicious requests
+  blocklist('block bad IPs') do |req|
+    # Requests are blocked if the return value is truthy
+    BadIpList.include?(req.ip)
+  end
+end
+
+# config/application.rb
+config.middleware.use Rack::Attack
+```
+
+## CORS Configuration
+
+```ruby
+# Gemfile
+gem 'rack-cors'
+
+# config/initializers/cors.rb
+Rails.application.config.middleware.insert_before 0, Rack::Cors do
+  allow do
+    origins 'localhost:3000', 'example.com'
+
+    resource '*',
+      headers: :any,
+      methods: [:get, :post, :put, :patch, :delete, :options, :head],
+      credentials: true
+  end
+end
+```
+
+## API Documentation with RSwag
+
+```ruby
+# Gemfile
+gem 'rswag'
+
+# spec/requests/api/v1/posts_spec.rb
+require 'swagger_helper'
+
+RSpec.describe 'Posts API', type: :request do
+  path '/api/v1/posts' do
+    get 'Retrieves posts' do
+      tags 'Posts'
+      produces 'application/json'
+      parameter name: :page, in: :query, type: :integer, required: false
+
+      response '200', 'posts found' do
+        schema type: :array,
+          items: {
+            type: :object,
+            properties: {
+              id: { type: :integer },
+              title: { type: :string },
+              body: { type: :string }
+            }
+          }
+
+        run_test!
+      end
+    end
+
+    post 'Creates a post' do
+      tags 'Posts'
+      consumes 'application/json'
+      parameter name: :post, in: :body, schema: {
+        type: :object,
+        properties: {
+          title: { type: :string },
+          body: { type: :string }
+        },
+        required: ['title', 'body']
+      }
+
+      response '201', 'post created' do
+        let(:post) { { title: 'Test', body: 'Content' } }
+        run_test!
+      end
+    end
+  end
+end
+```
+
+## Error Handling
+
+```ruby
+# app/controllers/concerns/error_handler.rb
+module ErrorHandler
+  extend ActiveSupport::Concern
+
+  included do
+    rescue_from ActiveRecord::RecordNotFound, with: :not_found
+    rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
+    rescue_from ActionController::ParameterMissing, with: :bad_request
+  end
+
+  private
+
+  def not_found(exception)
+    render json: { error: exception.message }, status: :not_found
+  end
+
+  def unprocessable_entity(exception)
+    render json: { errors: exception.record.errors.full_messages },
+           status: :unprocessable_entity
+  end
+
+  def bad_request(exception)
+    render json: { error: exception.message }, status: :bad_request
+  end
+end
+```
+
+## Best Practices
+
+- Use semantic versioning for API versions
+- Return proper HTTP status codes
+- Include pagination for list endpoints
+- Use JSON:API or similar standard format
+- Document API with OpenAPI/Swagger
+- Implement rate limiting and throttling
+- Use HTTPS in production
+- Validate and sanitize all inputs
+- Include API versioning in URL or headers
+- Provide helpful error messages

package/skills/ruby/rails-expert/references/background-jobs.md

@@ -0,0 +1,272 @@
+# Background Jobs with Sidekiq
+
+## Sidekiq Setup
+
+```ruby
+# Gemfile
+gem 'sidekiq'
+gem 'sidekiq-cron' # Optional: scheduled jobs
+
+# config/initializers/sidekiq.rb
+Sidekiq.configure_server do |config|
+  config.redis = { url: ENV['REDIS_URL'] || 'redis://localhost:6379/0' }
+end
+
+Sidekiq.configure_client do |config|
+  config.redis = { url: ENV['REDIS_URL'] || 'redis://localhost:6379/0' }
+end
+
+# config/sidekiq.yml
+:concurrency: 5
+:queues:
+  - critical
+  - default
+  - low
+```
+
+## Basic Job Design
+
+```ruby
+# app/jobs/email_sender_job.rb
+class EmailSenderJob < ApplicationJob
+  queue_as :default
+
+  def perform(user_id, email_type)
+    user = User.find(user_id)
+    UserMailer.send(email_type, user).deliver_now
+  end
+end
+
+# Usage
+EmailSenderJob.perform_later(user.id, :welcome)
+
+# Perform at specific time
+EmailSenderJob.set(wait: 1.hour).perform_later(user.id, :reminder)
+EmailSenderJob.set(wait_until: Date.tomorrow.noon).perform_later(user.id, :digest)
+```
+
+## Queue Priority
+
+```ruby
+class CriticalJob < ApplicationJob
+  queue_as :critical
+
+  def perform
+    # High priority work
+  end
+end
+
+class ReportGenerationJob < ApplicationJob
+  queue_as :low
+
+  def perform
+    # Can wait
+  end
+end
+```
+
+## Retry Strategy
+
+```ruby
+class ImportJob < ApplicationJob
+  # Retry up to 5 times with exponential backoff
+  sidekiq_options retry: 5
+
+  # Custom retry logic
+  sidekiq_retry_in do |count, exception|
+    case exception
+    when NetworkError
+      10 * (count + 1) # 10, 20, 30 seconds
+    when RateLimitError
+      1.hour
+    else
+      :default # Use Sidekiq's default exponential backoff
+    end
+  end
+
+  def perform(data_url)
+    # Import logic
+  end
+end
+```
+
+## Error Handling
+
+```ruby
+class ProcessPaymentJob < ApplicationJob
+  sidekiq_options retry: 3
+
+  # Called when job fails after all retries
+  sidekiq_retries_exhausted do |msg, exception|
+    Rails.logger.error("Payment job failed: #{msg}")
+
+    # Notify admin
+    AdminMailer.job_failed(msg, exception).deliver_now
+
+    # Store failure record
+    FailedPayment.create(
+      user_id: msg['args'][0],
+      error: exception.message
+    )
+  end
+
+  def perform(user_id, amount)
+    user = User.find(user_id)
+    PaymentProcessor.charge(user, amount)
+  rescue PaymentError => e
+    # Log and re-raise to trigger retry
+    Rails.logger.warn("Payment failed: #{e.message}")
+    raise
+  end
+end
+```
+
+## Batch Processing
+
+```ruby
+class BulkEmailJob < ApplicationJob
+  def perform(user_ids)
+    # Process in batches to avoid memory issues
+    user_ids.in_groups_of(100, false) do |batch|
+      batch.each do |user_id|
+        user = User.find(user_id)
+        UserMailer.newsletter(user).deliver_now
+      end
+    end
+  end
+end
+
+# Better: Use Sidekiq::Batch (requires sidekiq-pro)
+class ParentJob < ApplicationJob
+  def perform(user_ids)
+    batch = Sidekiq::Batch.new
+    batch.on(:success, self.class, 'user_ids' => user_ids)
+
+    batch.jobs do
+      user_ids.each do |user_id|
+        ChildJob.perform_later(user_id)
+      end
+    end
+  end
+
+  def on_success(status, options)
+    # All child jobs completed
+    Rails.logger.info("Processed #{options['user_ids'].length} users")
+  end
+end
+```
+
+## Scheduled Jobs
+
+```ruby
+# Using sidekiq-cron
+# config/initializers/sidekiq.rb
+schedule_file = "config/schedule.yml"
+
+if File.exist?(schedule_file) && Sidekiq.server?
+  Sidekiq::Cron::Job.load_from_hash YAML.load_file(schedule_file)
+end
+
+# config/schedule.yml
+daily_report:
+  cron: "0 6 * * *"
+  class: "DailyReportJob"
+  queue: default
+
+cleanup_old_records:
+  cron: "0 2 * * 0" # Sunday at 2am
+  class: "CleanupJob"
+  queue: low
+```
+
+## Job Patterns
+
+Idempotent jobs:
+
+```ruby
+class ProcessOrderJob < ApplicationJob
+  def perform(order_id)
+    order = Order.find(order_id)
+
+    # Check if already processed
+    return if order.processed?
+
+    # Process order
+    order.process!
+  end
+end
+```
+
+Unique jobs (requires sidekiq-unique-jobs gem):
+
+```ruby
+class GenerateReportJob < ApplicationJob
+  sidekiq_options lock: :until_executed,
+                   on_conflict: :log
+
+  def perform(user_id, report_type)
+    # Only one instance of this job per user+report_type
+  end
+end
+```
+
+## Testing
+
+```ruby
+# spec/jobs/email_sender_job_spec.rb
+require 'rails_helper'
+
+RSpec.describe EmailSenderJob, type: :job do
+  let(:user) { create(:user) }
+
+  describe "#perform" do
+    it "sends welcome email" do
+      expect {
+        described_class.perform_now(user.id, :welcome)
+      }.to change { ActionMailer::Base.deliveries.count }.by(1)
+    end
+
+    it "enqueues job" do
+      expect {
+        described_class.perform_later(user.id, :welcome)
+      }.to have_enqueued_job(described_class)
+        .with(user.id, :welcome)
+        .on_queue("default")
+    end
+  end
+end
+
+# Test inline in development
+# config/environments/test.rb
+config.active_job.queue_adapter = :inline
+```
+
+## Monitoring
+
+```ruby
+# Check queue size
+Sidekiq::Queue.new("default").size
+
+# Check scheduled jobs
+Sidekiq::ScheduledSet.new.size
+
+# Check retry set
+Sidekiq::RetrySet.new.size
+
+# Check dead jobs
+Sidekiq::DeadSet.new.size
+
+# Clear queues (use with caution)
+Sidekiq::Queue.new("default").clear
+```
+
+## Performance Tips
+
+- Keep jobs small and focused
+- Pass IDs, not objects (serialize/deserialize issue)
+- Use appropriate queue priorities
+- Set realistic retry limits
+- Monitor queue depth and latency
+- Scale workers based on load
+- Use Redis persistence for job durability
+- Consider job uniqueness to prevent duplicates