light-services 2.2.1 → 3.0.0

data/docs/pundit-authorization.md

@@ -0,0 +1,320 @@
+# Pundit Authorization
+
+[Pundit](https://github.com/varvet/pundit) is a simple, flexible authorization library for Ruby on Rails. This recipe shows how to integrate Pundit authorization into your Light Services.
+
+## Why Use Pundit with Services?
+
+- **Centralized authorization**: Keep authorization logic in policy classes
+- **Consistent patterns**: Same authorization approach across controllers and services
+- **Testable**: Policies are easy to unit test
+- **Reusable**: Services can be called from controllers, jobs, or other services with consistent authorization
+
+## Basic Setup
+
+### 1. Create an Authorization Concern
+
+```ruby
+# app/services/concerns/authorize_user.rb
+module AuthorizeUser
+  extend ActiveSupport::Concern
+
+  included do
+    arg :current_user, type: User, optional: true, context: true
+  end
+
+  # Authorize an action on a record or class
+  def auth(record, action)
+    policy = policy(record)
+    
+    unless policy.public_send(action)
+      errors.add(:authorization, "You are not authorized to perform this action")
+    end
+  end
+  alias_method :authorize!, :auth
+
+  # Get permitted attributes for an action
+  def permitted_attributes(record, action = nil)
+    policy = policy(record)
+    
+    method_name = if action
+      "permitted_attributes_for_#{action}"
+    else
+      "permitted_attributes"
+    end
+
+    if policy.respond_to?(method_name)
+      attributes = policy.public_send(method_name)
+      params.require(param_key(record)).permit(*attributes)
+    else
+      raise Pundit::NotDefinedError, "#{method_name} not defined in #{policy.class}"
+    end
+  end
+
+  private
+
+  def policy(record)
+    Pundit.policy!(current_user, record)
+  end
+
+  def param_key(record)
+    if record.is_a?(Class)
+      record.model_name.param_key
+    else
+      record.model_name.param_key
+    end
+  end
+end
+```
+
+### 2. Include in ApplicationService
+
+```ruby
+# app/services/application_service.rb
+class ApplicationService < Light::Services::Base
+  include AuthorizeUser
+end
+```
+
+## Usage Examples
+
+### Authorizing Actions
+
+```ruby
+class Post::Update < ApplicationService
+  arg :post, type: Post
+  arg :attributes, type: Hash
+
+  step :authorize
+  step :update_post
+
+  private
+
+  def authorize
+    auth(post, :update?)
+  end
+
+  def update_post
+    post.update!(attributes)
+  end
+end
+```
+
+### Authorizing on a Class (for Create actions)
+
+```ruby
+class Post::Create < ApplicationService
+  arg :attributes, type: Hash
+
+  step :authorize
+  step :create_post
+
+  output :post
+
+  private
+
+  def authorize
+    auth(Post, :create?)
+  end
+
+  def create_post
+    self.post = Post.create!(attributes)
+  end
+end
+```
+
+### Using Permitted Attributes
+
+```ruby
+class Post::Create < ApplicationService
+  step :authorize
+  step :create_post
+
+  output :post
+
+  private
+
+  def authorize
+    auth(Post, :create?)
+  end
+
+  def create_post
+    self.post = Post.create!(permitted_attributes(Post, :create))
+  end
+end
+```
+
+## Policy Example
+
+```ruby
+# app/policies/post_policy.rb
+class PostPolicy < ApplicationPolicy
+  def create?
+    !user.nil?
+  end
+
+  def update?
+    !user.nil? && (record.author == user || user.admin?)
+  end
+
+  def destroy?
+    !user.nil? && (record.author == user || user.admin?)
+  end
+
+  def permitted_attributes_for_create
+    [:title, :body, :category_id]
+  end
+
+  def permitted_attributes_for_update
+    attributes = [:title, :body]
+    attributes << :category_id if user.admin?
+    attributes
+  end
+end
+```
+
+## Integration with CRUD Services
+
+Combine Pundit with the [CRUD recipe](crud.md) for powerful, authorized services:
+
+```ruby
+# app/services/create_record_service.rb
+class CreateRecordService < ApplicationService
+  arg :record_class, type: Class
+  arg :attributes, type: Hash, default: {}
+
+  step :authorize
+  step :create_record
+
+  output :record
+
+  private
+
+  def authorize
+    auth(record_class, :create?)
+  end
+
+  def create_record
+    attrs = permitted_attributes(record_class, :create)
+              .to_h
+              .merge(attributes)
+    
+    self.record = record_class.create!(attrs)
+  rescue ActiveRecord::RecordInvalid => e
+    errors.copy_from(e.record)
+  end
+end
+```
+
+## Handling Authorization Failures
+
+### Option 1: Collect as Errors (Default)
+
+```ruby
+def authorize
+  auth(record, :update?)
+  # If unauthorized, an error is added and subsequent steps are skipped
+end
+```
+
+### Option 2: Raise Exceptions
+
+```ruby
+def authorize
+  unless policy(record).update?
+    raise Pundit::NotAuthorizedError, "not authorized to update this record"
+  end
+end
+```
+
+### Option 3: Custom Error Handling
+
+```ruby
+def authorize
+  return if policy(record).update?
+  
+  errors.add(:base, I18n.t("pundit.not_authorized"))
+end
+```
+
+## Testing Services with Authorization
+
+```ruby
+RSpec.describe Post::Update do
+  let(:author) { create(:user) }
+  let(:other_user) { create(:user) }
+  let(:post) { create(:post, author: author) }
+
+  context "when user is the author" do
+    it "updates the post" do
+      service = described_class.run(
+        current_user: author,
+        post: post,
+        attributes: { title: "New Title" }
+      )
+
+      expect(service).to be_success
+      expect(post.reload.title).to eq("New Title")
+    end
+  end
+
+  context "when user is not the author" do
+    it "returns authorization error" do
+      service = described_class.run(
+        current_user: other_user,
+        post: post,
+        attributes: { title: "New Title" }
+      )
+
+      expect(service).to be_failed
+      expect(service.errors[:authorization]).to be_present
+    end
+  end
+
+  context "when no user is provided" do
+    it "returns authorization error" do
+      service = described_class.run(
+        current_user: nil,
+        post: post,
+        attributes: { title: "New Title" }
+      )
+
+      expect(service).to be_failed
+    end
+  end
+end
+```
+
+## Skipping Authorization
+
+For system-level operations or background jobs where authorization isn't needed:
+
+```ruby
+class Post::SystemUpdate < UpdateRecordService
+  # Remove the authorize step for system operations
+  remove_step :authorize
+end
+```
+
+Or create a "system" flag:
+
+```ruby
+class ApplicationService < Light::Services::Base
+  arg :system, type: [TrueClass, FalseClass], default: false, context: true
+end
+
+class Post::Update < ApplicationService
+  step :authorize, unless: :system?
+  step :update_post
+  
+  # ...
+end
+
+# Usage in background job
+Post::Update.run(post: post, attributes: attrs, system: true)
+```
+
+## What's Next?
+
+Return to the recipes overview:
+
+[Back to Recipes](recipes.md)

data/docs/quickstart.md

@@ -0,0 +1,134 @@
+# Quickstart
+
+Light Services are framework-agnostic and can be used in any Ruby project.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "light-services", "~> 3.0"
+```
+
+Or you can install it yourself by running:
+
+```bash
+bundle add light-services --version "~> 3.0"
+```
+
+## Create `ApplicationService`
+
+{% hint style="info" %}
+This step is optional but recommended. Creating a base class for your services can help organize your code. This base class will act as the parent for all your services, where you can include common logic such as helpers, logging, error handling, etc.
+{% endhint %}
+
+### For Rails Applications
+
+If you're using Rails, you can use the install generator to set up Light Services automatically:
+
+```bash
+bin/rails generate light_services:install
+```
+
+This will create the `ApplicationService` base class, an initializer, and a spec file (if RSpec is detected). See [Rails Generators](generators.md) for more details.
+
+### For Non-Rails Applications
+
+First, create a folder for your services. The path will depend on the framework you are using. For Rails, you can create a folder in `app/services`.
+
+```bash
+mkdir app/services
+```
+
+Next, create your base class. You can name it as you wish, but we recommend `ApplicationService`.
+
+```ruby
+# app/services/application_service.rb
+class ApplicationService < Light::Services::Base
+  # Add common arguments, callbacks, or helpers shared across all services.
+  #
+  # Example: Add a context argument for the current user
+  # arg :current_user, type: User, optional: true, context: true
+end
+```
+
+## Create Your First Service
+
+Now let's create our first service. We'll make a simple service that returns a greeting message.
+
+{% hint style="info" %}
+**Rails users:** You can use the service generator to create services quickly:
+```bash
+bin/rails generate light_services:service GreetService --args=name --steps=greet --outputs=greeted
+```
+See [Rails Generators](generators.md) for more information.
+{% endhint %}
+
+```ruby
+# app/services/greet_service.rb
+class GreetService < ApplicationService
+  # Arguments
+  arg :name, type: String
+
+  # Steps
+  step :greet
+
+  # Outputs
+  output :greeted, default: false
+
+  private
+
+  def greet
+    puts "Hello, #{name}!"
+    self.greeted = true
+  end
+end
+```
+
+## Run the Service
+
+Now you can run your service from anywhere in your application.
+
+```ruby
+service = GreetService.run(name: "John")
+service.greeted # => true
+```
+
+### Check for Success or Failure
+
+```ruby
+service = GreetService.run(name: "John")
+
+if service.success?
+  puts "Greeting sent!"
+  puts service.greeted
+else
+  puts "Failed: #{service.errors.to_h}"
+end
+```
+
+### Raise on Error with `run!`
+
+Use `run!` when you want errors to raise exceptions instead of being collected:
+
+```ruby
+# This will raise Light::Services::Error if any errors are added
+service = GreetService.run!(name: "John")
+```
+
+This is equivalent to:
+
+```ruby
+service = GreetService.run({ name: "John" }, { raise_on_error: true })
+```
+
+{% hint style="info" %}
+Looks easy, right? But this is just the beginning. Light Services can do much more 🚀
+{% endhint %}
+
+## What's Next?
+
+Learn how to configure Light Services for your application:
+
+[Next: Configuration](configuration.md)
+

data/docs/readme.md

@@ -0,0 +1,100 @@
+# Light Services
+
+Light Services is a simple yet powerful way to organize business logic in Ruby applications. Build services that are easy to test, maintain, and understand.
+
+[Get started with Quickstart](quickstart.md)
+
+## Features
+
+- ✨ **Simple**: Define your service as a class with `arguments`, `steps`, and `outputs`
+- 📦 **No runtime dependencies**: Works stand-alone without requiring external gems at runtime
+- 🔄 **Transactions**: Automatically rollback database changes if any step fails
+- 🧬 **Inheritance**: Inherit from other services to reuse logic seamlessly
+- ⚠️ **Error Handling**: Collect errors from steps and handle them your way
+- 🔗 **Context**: Run multiple services sequentially within the same context
+- 🧪 **RSpec Matchers**: Built-in RSpec matchers for expressive service tests
+- 🌐 **Framework Agnostic**: Compatible with Rails, Hanami, or any Ruby framework
+- 🧩 **Modularity**: Isolate and test your services with ease
+- ✅ **100% Test Coverage**: Thoroughly tested and reliable
+- ⚔️ **Battle-Tested**: In production use since 2017
+
+## Simple Example
+
+```ruby
+class GreetService < Light::Services::Base
+  # Arguments
+  arg :name
+  arg :age
+
+  # Steps
+  step :build_message
+  step :send_message
+
+  # Outputs
+  output :message
+
+  private
+
+  def build_message
+    self.message = "Hello, #{name}! You are #{age} years old."
+  end
+
+  def send_message
+    # Send logic goes here
+  end
+end
+```
+
+## Advanced Example
+
+```ruby
+class User::ResetPassword < Light::Services::Base
+  # Arguments
+  arg :user, type: User, optional: true
+  arg :email, type: String, optional: true
+  arg :send_email, type: [TrueClass, FalseClass], default: true
+
+  # Steps
+  step :validate
+  step :find_user, unless: :user?
+  step :generate_reset_token
+  step :save_reset_token
+  step :send_reset_email, if: :send_email?
+
+  # Outputs
+  output :user, type: User
+  output :reset_token, type: String
+
+  private
+
+  def validate
+    errors.add(:base, "user or email is required") if !user? && !email?
+  end
+
+  def find_user
+    self.user = User.find_by("LOWER(email) = ?", email.downcase)
+    errors.add(:email, "not found") unless user
+  end
+
+  def generate_reset_token
+    self.reset_token = SecureRandom.hex(32)
+  end
+
+  def save_reset_token
+    user.update!(
+      reset_password_token: reset_token,
+      reset_password_sent_at: Time.current,
+    )
+  rescue ActiveRecord::RecordInvalid => e
+    errors.from_record(e.record)
+  end
+
+  def send_reset_email
+    Mailer::SendEmail
+      .with(self) # Call sub-service with the same context
+      .run(template: :reset_password, user:, reset_token:)
+  end
+end
+```
+
+[Get started with Light Services](quickstart.md)

data/docs/recipes.md

@@ -0,0 +1,14 @@
+# Recipes
+
+This section contains practical recipes for common patterns when using Light Services.
+
+- [CRUD](crud.md) - Implementing top-level services for CRUD operations
+- [Service Rendering](service-rendering.md) - Easy way to render service results and errors
+- [Pundit Authorization](pundit-authorization.md) - Integrating Pundit authorization with Light Services
+
+## Getting Started
+
+These recipes build upon each other. We recommend starting with CRUD services, then adding service rendering for cleaner controllers, and finally integrating Pundit for authorization.
+
+[Start with CRUD](crud.md)
+