odsl 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b972b04076091e4880481f3120c36fc38d233dae65c68ed62cfb5089b5064978
-  data.tar.gz: a974bbde6e1cc8e7c9fa9f6af823c0d7ded81e5f11ca0bbf2b69ac69adc17cc5
+  metadata.gz: a5247ca88b029a8621f55ca52a4cfc376c8c4f170059a2e62edd714d2ced6a1d
+  data.tar.gz: a68b985769287f222931e2c2ca290e875275cefddfce53070b8c71ba148a88b0
 SHA512:
-  metadata.gz: efd5eaaee6252374c7bdf82c44479770d211e570e1daedea948285aaa51a2e121020361c585480be3728ee49bb0a93e2301a49bacc48276fbeeeea5cc7dfe9fa
-  data.tar.gz: 63e3865d022968e0fae4e09c3c8fe5ccef63b7b0f1a46efcad11a18be34c50edd93d07edf55daf900cb0b1987017979f3f753d3b24b2f8c43a9a41fc22f505ab
+  metadata.gz: a9c50af3890a595878927066ef6bbceb44e20428b29e94b21624c0b57e1bd829ad31b5f3e5376f72b862fd20d3d4af27699341771113ef20207b10f9f9316ab5
+  data.tar.gz: 9d0d31d06e99681966c96099d970ae5d53181af59fe6606118b8645365e2e0146b578d14aa4d29110b05b412fbadd1f96cae201c9338579c8f84ca1d68ef9ad6

data/CHANGELOG.md

@@ -1,5 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
-## [0.1.0] - 2023-07-03
+## [0.3.0] - 2026-10-10
+
+### Added
+- Pluggable background adapters: `:thread` (default) and `:active_job`
+- `run_in_background(:method)` and `run_in_parallel(*methods)` on service instances
+- `Odsl::Configuration` with `background_adapter`, `audit_ttl`, `lock_redis_url`, `lock_ttl`
+- `Odsl.configure {}` and `Odsl.config` with thread-safe access
+- Step-level audit system: `Odsl::Audit::ExecutionContext` and `Odsl::Audit::StepRecord`
+- Idempotent runs via `run(:method, key: "...")` — no-op if already completed
+- `resume(key:)` class method — restarts a failed run from the first incomplete step
+- TTL support for audit records via `audit_ttl` config option
+- `Odsl.cleanup_expired!` and `rake odsl:cleanup` for pruning expired records
+- Distributed locking via `lock(*vars)` DSL method (backed by [Redlock](https://github.com/leandromoreira/redlock-rb))
+- `Odsl::LockError`, `Odsl::AlreadyRunningError`, `Odsl::ContextNotFoundError`
+- Rails generator: `rails generate odsl:install` (migration + initializer)
+- `Odsl::Railtie` for automatic Rake task registration in Rails apps
+- `Odsl::Audit::Serializer` for JSON-safe step result persistence
+- GitHub Actions CI across Ruby 3.1, 3.2, 3.3
+
+### Fixed
+- Thread-safe configuration access via `CONFIG_MUTEX`
+- `lib/odsl/error.rb` replaced with `lib/odsl/errors.rb` (syntax fix, plural naming)
+
+### Changed
+- Minimum Ruby version remains `>= 3.1.0`
+- Version bumped to `0.3.0`
+
+## [0.2.0] - 2024-01-01
+
+### Added
+- `inmutable` mode
+- `run_in_background` / `run_in_parallel`
+- `subscribe` / `dispatch` event bus
+- `finish_with` / `value_return` aliases
+- `set` / `link` aliases for `make` / `call`
+
+## [0.1.0] - 2023-01-01
+
+### Added
+- Initial DSL: `build`, `with`, `make`, `call`, `get`, `use`, `instantiate`, `finish_with`
+- `Odsl::Dsl` base class
+- `inmutable` class-level flag
+- Minitest test suite
 
-- Initial release
+[Unreleased]: https://github.com/aleguro/ODSL/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/aleguro/ODSL/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/aleguro/ODSL/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/aleguro/ODSL/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to Odsl
+
+Thanks for taking the time to contribute!
+
+## Setup
+
+```bash
+git clone https://github.com/aleguro/ODSL.git
+cd ODSL
+bundle install
+```
+
+## Running Tests
+
+```bash
+bundle exec rake test
+```
+
+The test suite uses an in-memory SQLite database — no external services required.
+
+## Adding a Feature
+
+1. Fork the repo and create a branch: `git checkout -b feat/your-feature`
+2. Write a failing test first
+3. Implement the feature
+4. Run `bundle exec rake test` — all tests must pass
+5. Update `README.md` if the public API changed
+6. Add an entry to `CHANGELOG.md` under `[Unreleased]`
+7. Open a PR against `master`
+
+## Code Style
+
+- No unnecessary comments — let well-named identifiers speak
+- No added error handling for scenarios that can't happen
+- Prefer editing existing files over creating new ones
+- Keep files focused; one clear responsibility per file
+
+## Reporting a Bug
+
+Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include a minimal reproducible example.

data/README.md

@@ -1,109 +1,362 @@
-# Object DSL
+# Odsl
 
-This is a prototype oriented to use OOP and a functional programming approach by providing a DSL to decouple code logic from coding itself while enforcing good practices and providing:
+[![Gem Version](https://badge.fury.io/rb/odsl.svg)](https://badge.fury.io/rb/odsl)
+[![CI](https://github.com/aleguro/ODSL/actions/workflows/ci.yml/badge.svg)](https://github.com/aleguro/ODSL/actions/workflows/ci.yml)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
+[![Maintainability](https://img.shields.io/badge/maintainability-A-brightgreen)](https://github.com/aleguro/ODSL)
+[![RubyGems MFA](https://img.shields.io/badge/rubygems%20MFA-enabled-green)](https://guides.rubygems.org/mfa-requirement-opt-in/)
 
-    - Design patterns
-    - Inmutability
-    - Dry off
-    - Decouple aspects from code ( background, paralelization )
+> **O**bject **D**SL — a fluent, chainable framework for writing service objects in Ruby that are easy to read, test, and extend.
 
-# Your code
+Odsl lets you express complex business workflows as a sequence of named steps — composing objects, calling methods, and storing intermediate results — without the sprawling `def call` anti-pattern. Every service is immutable by default, background-capable, audit-ready, and optionally protected by distributed locking.
 
+---
+
+## Why Odsl?
+
+Most Ruby service objects end up as a `call` method with a hundred lines of code, private helpers tangled with side effects, and zero insight into which step failed when something goes wrong.
+
+Odsl solves this by making each step **named**, **recorded**, and **resumable**:
+
+```ruby
+def create_order
+  build(Inventory, Pricing)       # compose a scoped object
+    .get(:catalog)                 # store it as @catalog
+
+  with(:catalog, :items, :user)
+    .make(:calculate_total)        # call your private method
+    .get(:order_total)             # store the result
+
+  with(:user, :order_total)
+    .instantiate(Order)            # build an AR model
+    .get(:order)
+
+  with(:order)
+    .make(:charge_customer)
+    .get(:payment)
+
+  finish_with(:order, :payment)    # declare what to return
+end
 ```
-class ScoreBoard
 
-  def initialize(game_object)
-    @game, @player = game_object.game, game_object.player
-  end
+Each `.get(:var)` is a named checkpoint — recorded to the audit log, replayable on resume, and crystal clear in stack traces.
+
+---
+
+## Installation
 
-  def publish
-    STDOUT.puts "Player: @player.name is playing: #{@game.game_type}"
+```ruby
+# Gemfile
+gem "odsl"
+
+# Optional: background jobs
+gem "activejob"
+
+# Optional: distributed locking
+gem "redlock"
+```
+
+For audit tables (Rails):
+
+```bash
+rails generate odsl:install
+rails db:migrate
+```
+
+---
+
+## Quick Start
+
+```ruby
+# Define your modules (plain Ruby — no inheritance required)
+module Player
+  attr_reader :player
+
+  def with_player(player)
+    @player = Struct.new(:name).new(player)
+    self
   end
 end
 
 module Game
+  attr_reader :game
+
   def start(game_type)
-    @game = Struct.new(game_type: game_type, player: @player.name)
+    @game = Struct.new(:game_type, :player).new(game_type, @player.name)
     self
   end
 end
 
-module Player
-  def with_player(player)
-    @player = Struct.new(name: player)
-    self
+# Define your service
+class GameService < Odsl::Dsl
+  include GameCrud
+  inmutable true
+
+  subscribe 'start_game', to: :create
+end
+
+module GameCrud
+  def create
+    build(Game, Player)
+      .get(:game_object)
+
+    with(:player, :game, :game_object)
+      .make(:new_game)
+      .get(:game_instance)
+
+    with(:game_instance)
+      .instantiate(ScoreBoard)
+      .get(:score_board)
+
+    finish_with(:game_instance, :score_board)
+  end
+
+  private
+
+  def new_game(player, game, game_object)
+    game_object
+      .with_player(player[:name])
+      .start(game)
   end
 end
 
-module Game
-  module Crud     
-    def create    
-      build(Game, Players)
-        .get(:game_object)
+# Run it
+game, board = GameService.new(player: { name: "alejandro" }, game: "chess").run(:create)
+game.game.game_type   # => "chess"
+game.game.player      # => "alejandro"
 
-      with(:args, :game_object)
-        .set(:new_game)
-        .get(:game_instance)
+# Or via event dispatch
+game, board = GameService.dispatch('start_game', player: { name: "alejandro" }, game: "chess")
+```
 
-      with(:game_object)
-        .instanciate(ScoreBoard)
-        .get(:score_board_object)
+---
 
-      with(:score_board_object)
-        .call(:publish)
+## DSL Reference
 
-      finish_with(:game_instance) 
-    end
+### Chaining Methods
 
-    def delete(id)
-    end
+| Method | Alias(es) | Description |
+|--------|-----------|-------------|
+| `build(*modules)` | — | Composes a new object by mixing modules into an anonymous class |
+| `with(*attrs)` | — | Sets the arguments passed to the next `make`/`call`/`instantiate` |
+| `make(:method)` | `set`, `link` | Calls a private method with the current `with` attrs |
+| `call(:method)` | — | Calls a method on the currently delegated object |
+| `get(*vars)` | `to` | Stores last result(s) into named instance variables |
+| `use(:object)` | — | Points delegation to the object in `@object` |
+| `instantiate(Class)` | — | Instantiates a class using the current `with` attrs |
+| `finish_with(*vars)` | `value_return` | Declares the return value(s) of `run` |
 
-    private
+### Running
 
-    def new_game(args, game_object)
+| Method | Description |
+|--------|-------------|
+| `instance.run(:method)` | Executes a method, returns `finish_with` values |
+| `instance.execute(:method)` | Alias for `run` |
+| `MyService.resume(key:)` | Resumes a failed run from the first incomplete step |
 
-      game_object
-        .with_player(args[:player])
-        .start(args[:game_name])  
-    end    
-  end
+### Class-Level DSL
+
+| Method | Description |
+|--------|-------------|
+| `inmutable true` | Each `run` operates on a fresh dup — no shared state |
+| `subscribe 'event', to: :method` | Maps a string event name to a method |
+| `dispatch('event', **kwargs)` | Finds the subscription and runs it |
+
+---
+
+## Features
+
+### Immutability
+
+```ruby
+class ReportService < Odsl::Dsl
+  inmutable true
 end
-  
-module Game
-  class Service < Odsl:Dsl
-    include Crud
 
-    inmutable true 
-  end
+service = ReportService.new(year: 2024)
+result1 = service.run(:generate)
+result2 = service.run(:generate)  # identical — original service is untouched
+```
+
+When `inmutable true` is set, every `run` works on a `dup` of the instance — your kwargs and context are never mutated.
+
+---
+
+### Background Jobs
+
+```ruby
+# Fire and forget (returns a Thread by default)
+thread = service.run_in_background(:process)
+result = thread.value  # wait for it
+
+# Run multiple steps in parallel
+game1, game2 = service.run_in_parallel(:create, :create)
+```
+
+Switch adapters as your stack grows:
+
+```ruby
+Odsl.configure do |config|
+  config.background_adapter = :active_job  # delegates to your configured queue backend
 end
 ```
 
-# How to use call it.
+With `:active_job`, Odsl enqueues an `Odsl::OdslJob` that reconstructs the service from its kwargs and calls the method. Works with Sidekiq, Solid Queue, Good Job, and any other ActiveJob backend.
 
+---
+
+### Audit & Idempotency
+
+Every `run` can be made idempotent by passing a `key:`. Odsl records an `ExecutionContext` and a `StepRecord` per `.get(:var)` checkpoint.
+
+```ruby
+# Won't re-run if already completed with this key
+service.run(:process_order, key: "order-#{order.id}")
+
+# A second call with the same key returns nil immediately
+service.run(:process_order, key: "order-#{order.id}")  # => nil
 ```
-Games::Service
-  .new(player: { name: 'alejandro' } , game: 'chez')
-  .run(:create)
+
+**Step-level audit** means you can see exactly which steps completed and what their results were:
+
+```ruby
+ctx = Odsl::Audit::ExecutionContext.find_by(idempotency_key: "order-42")
+ctx.status          # => "completed"
+ctx.step_records    # => [#<StepRecord name="catalog">, #<StepRecord name="order_total">, ...]
 ```
 
-# Future development
+**Resume a failed run** from the first step that wasn't recorded:
 
- - Run in background mode
+```ruby
+# Process died after step 2 of 5 — resume picks up from step 3
+result = OrderService.resume(key: "order-42")
+```
 
- ```.run_in_background(:method)``` 
- 
- - Run sevreral methods in paralell 
+Completed steps are loaded from the database (no side effects re-run). Non-serializable results (complex objects) are re-executed.
 
- ```.run_in_parallel(:method_a, :method_b)```
+**TTL & cleanup:**
 
- - Make service objects subscribe to messaages
+```ruby
+Odsl.configure do |config|
+  config.audit_ttl = 7 * 24 * 3600  # expire records after 1 week
+end
 
- module Game
-  class Service < Odsl:Dsl
-    include Crud
+# Remove expired records
+Odsl.cleanup_expired!
 
-    subscribe 'start_game', to: :create
-    subscribe 'end_game', to: end_game
-  end
+# Or with Rake
+rake odsl:cleanup
+```
+
+**Rails setup:**
+
+```bash
+rails generate odsl:install
+rails db:migrate
+```
+
+Generates `config/initializers/odsl.rb` and a migration for `odsl_execution_contexts` + `odsl_step_records`.
+
+---
+
+### Distributed Locking
+
+Prevent double-execution when users submit the same action from two browser tabs simultaneously.
+
+```ruby
+# Gemfile
+gem "redlock"
+```
+
+```ruby
+Odsl.configure do |config|
+  config.lock_redis_url = ENV["REDIS_URL"]
+  config.lock_ttl       = 10_000  # ms — how long to hold the lock
+end
+```
+
+Call `lock` at the top of any business method:
+
+```ruby
+def process_order
+  lock(:order_id)  # key = "OrderService:42"
+
+  with(:order_id)
+    .make(:fetch_order)
+    .get(:order)
+
+  # ...
+  finish_with(:order)
 end
-```
+```
+
+`lock` builds the key from the service class name + the string values of the given instance variables. If the lock is already held, `Odsl::LockError` is raised immediately (fail-fast — no waiting). The lock is released automatically in the `ensure` block.
+
+`lock` is a **no-op** when `lock_redis_url` is not configured, so the same code works in development without Redis.
+
+---
+
+### Event Bus
+
+```ruby
+class GameService < Odsl::Dsl
+  include Crud
+
+  subscribe 'game.start',  to: :create
+  subscribe 'game.finish', to: :end_game
+end
+
+# Dispatch by event name
+result = GameService.dispatch('game.start', player: { name: 'alejandro' }, game: 'chess')
+```
+
+Useful for decoupling event producers from the service implementation — the event string is the contract, not the method name.
+
+---
+
+## Configuration Reference
+
+```ruby
+Odsl.configure do |config|
+  # :thread (default) or :active_job
+  config.background_adapter = :thread
+
+  # Seconds to keep audit records. nil = never expire.
+  config.audit_ttl = nil
+
+  # Redis URL for Redlock. nil = locking disabled (no-op).
+  config.lock_redis_url = nil
+
+  # Distributed lock TTL in milliseconds.
+  config.lock_ttl = 10_000
+end
+```
+
+---
+
+## Error Reference
+
+| Error | When raised |
+|-------|-------------|
+| `Odsl::LockError` | Distributed lock couldn't be acquired |
+| `Odsl::AlreadyRunningError` | Idempotency key is currently in a `running` state |
+| `Odsl::ContextNotFoundError` | `resume(key:)` called for an unknown key |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, code style, and the PR checklist.
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a full history of releases.
+
+---
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).