standard-procedure-plumbing 0.5.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8071e0d012d60099bd30afaaabe7274fe4572a88686115e9b8db86fe880a0734
-  data.tar.gz: 212b5f27a5309d3cd638e354d8a41cbd77dcf0a5b9f22d5976e04403cea200a4
+  metadata.gz: 00d6b8a7e8165f292a6a6f130e7a03ca220bf64b1be9c926313aea61d90d6ce1
+  data.tar.gz: 2b445dda48df90ff053a0890ee027241ff7b82e460f82f06dd428b4e94601ff4
 SHA512:
-  metadata.gz: 82e7bf5617439df2e00886e7d95e9c4215e5f2e7dcf91a6a5de3673cd132bbc069c301fd0cdeb4cd315faff76981a4282898da66771be57ce19c7d9589fa7a30
-  data.tar.gz: c64ee286c7fec70b9025bd32ceaa39379751d26f7e7947934f07c5651f62f564407a87a4227fd2e4202c042b2d9db7df48008e67ba06aea9f15b269b7606cd15
+  metadata.gz: cacee68df443db89b5c6fe3bf5b7726419363502625138e8bf8c1241fdcecda17155effb464e8a6af303d0bf3fe996bec22893c5035e90817776c590849401f0
+  data.tar.gz: 74fdda077f25c6b2c1c9d4a10db03e070df7865105dea27685177193910d4714f0999efc7032f8e9a401358c9a8cfe3ebc8bfc215f142322b1883cd9b825f2c0

data/CHANGELOG.md

@@ -0,0 +1,188 @@
+## [1.0.0] - 2026-07-07 — v1 rewrite
+
+A ground-up rewrite. Plumbing is now a small, [`literal`](https://github.com/joeldrapper/literal)-based
+toolkit of composable concurrency primitives: pluggable-worker **Actors**, a
+**Provider** locator, a composable **Event / Pipeline** stream, an
+**Observable** mixin, and a state-machine **Operation** engine.
+
+**The only runtime dependency is `literal`.** `globalid` is dropped. The
+heavier worker dependencies (`async`, `rails`) are no longer in the core — the
+opt-in workers `require` their own and you add the gem to your app.
+
+### Breaking changes
+
+**RubberDuck removed — use `Object#as` with a literal interface:**
+
+```ruby
+obj.as(Plumbing::Callable)            # before — returned a narrowing proxy
+obj.as(Literal::Types._Callable)      # after  — validates and returns obj itself
+obj.as(Literal::Types._Interface(:observe, :remove, :remove_all))  # any literal interface works
+```
+
+**`Plumbing::Pipeline` is now the event stream (was `Plumbing::Pipe`).** The old
+sequential-operations `Pipeline` is removed; the old `Pipe` message bus is
+reborn as `Pipeline`, rebuilt around immutable `Plumbing::Event` values:
+
+```ruby
+# before (0.x Pipe) — observers got (event_name, data)
+pipe.add_observer { |event_name, data| ... }
+pipe.notify "something_happened", foo: 1
+
+# after (1.0 Pipeline) — events are Plumbing::Event value objects
+class SomethingHappened < Plumbing::Event
+  prop :foo, Integer
+end
+source = Plumbing::Pipeline::Source.new
+source.observe { |event| ... }
+source << SomethingHappened.new(foo: 1)
+
+# or via the registry, by type name:
+Plumbing::Pipeline.register(SomethingHappened)
+source.notify(event_type: "SomethingHappened", params: {foo: 1})
+```
+
+Compose with `Only` / `Except` (string names, trailing `*` wildcard), `Filter`
+(Regexp) and `Junction` (fan-in). Duplicate events are debounced.
+
+**New: `Plumbing::Observable` module** — mix into any object (actor or not) to
+give it its own event stream. It adds a public subscriber interface (`observe` /
+`remove` / `remove_all`) and a private emit interface (`push` / `notify`), backed
+by a lazily-created internal `Pipeline::Source`. `Operation` now uses it instead
+of hand-rolling a pipeline. (The old `Plumbing::Observable` interface *constant*,
+only ever an `Object#as` example, is removed — build interfaces inline with
+`Literal::Types._Interface(...)`.)
+
+**Actors rebuilt (composition, not proxies):**
+
+```ruby
+# before — Counter.start returned a proxy; methods were plain defs
+class Counter
+  include Plumbing::Actor
+  async :increment
+  def increment(by = 1) = @count += by
+end
+counter = Counter.start
+counter.increment
+
+# after — the async DSL carries typed params; resolve with await
+class Counter
+  include Plumbing::Actor
+  async :increment do
+    param :by, Integer, default: 1
+    returns { |by:| @count += by }
+  end
+end
+counter = Counter.new
+await { counter.increment(by: 2) }
+```
+
+- Worker selection moved from `Plumbing.config(mode: :async)` to
+  `Plumbing::Actor.uses :async` (after `require "plumbing/actor/async"`).
+- Workers: `inline` (default, zero-dependency), and opt-in `async`, `threaded`
+  (now core Ruby — no `concurrent-ruby`) and `rails`. Each delivers an actor's
+  messages **one at a time, in arrival order**.
+- Actors now track who called them: `current_sender` / `current_senders`.
+
+**New: `Provider` locator** — a path-based service locator, itself a
+`Plumbing::Actor`, with `register`/`provide` (aliases `singleton`/`factory`).
+`register`, `provide` and `get` are async messages taking keyword args; `[]` is
+the synchronous convenience (`get(path:).await`). Paths may carry `:params`
+passed to the block, and static routes win over dynamic ones on conflict.
+
+```ruby
+Plumbing.services.register(path: "config", value: AppConfig.load)  # eager singleton
+Plumbing.services.register(path: "db") { Database.connect }        # lazy singleton, cached
+Plumbing.services.provide(path: "clock") { Time.now }              # fresh every access
+Plumbing.services["db"]
+```
+
+Cached registrations accept an optional `expires_in:` (seconds) TTL — the value
+is evicted after that long and re-resolved on the next lookup (eviction is
+scheduled on the actor's worker, so it is a no-op under the `:inline` worker).
+
+A Provider can also be mounted under a wildcard tail path
+(`register(path: "prefix/*", value: nested_provider)`, or a block resolving to a
+Provider) — lookups beneath the prefix delegate the remaining path to the nested
+provider, like mounting a sub-router.
+
+## [0.5.2] - 2024-10-08
+
+ - Ensure preconditions are called in order
+
+## [0.5.1] - 2024-10-08
+
+ - Added exception handling for Pipeline preconditions
+
+## [0.5.0] - 2024-09-20
+
+ - Feature complete?
+
+## [0.4.5] - 2024-09-20
+
+ - Changed Plumbing::Pipeline into a module
+
+## [0.4.5] - 2024-09-20
+
+ - `become` matchers available to other gems
+ - `wait_for`
+
+## [0.4.4] - 2024-09-18
+
+ - Various bugfixes around the threading implementation
+
+## [0.4.1] - 2024-09-16
+
+ - Added `safely` to allow actors to run code within their own context
+
+## [0.4.0] - 2024-09-15
+
+ - Added #as_actor to allow actors to pass references to themselves
+
+## [0.3.3] - 2024-09-14
+
+ - Added :threaded and :rails modes
+ - RubberDuck now works with Module and Class
+
+## [0.3.2] - 2024-09-13
+
+ - URG - somehow I'd managed to exclude the lib folder from the gem contents
+
+## [0.3.1] - 2024-09-03
+
+ - Added `ignore_result` for queries on Plumbing::Valves
+
+## [0.3.0] - 2024-08-28
+
+ - Added Plumbing::Valve
+ - Reimplemented Plumbing::Pipe to use Plumbing::Valve
+
+## [0.2.2] - 2024-08-25
+
+ - Added Plumbing::RubberDuck
+
+## [0.2.1] - 2024-08-25
+
+ - Split the Pipe implementation between the Pipe and EventDispatcher
+ - Use different EventDispatchers to handle fibers or inline pipes
+ - Renamed Chain to Pipeline
+
+## [0.2.0] - 2024-08-14
+
+ - Added optional Dry::Validation support
+ - Use Async for fiber-based pipes
+
+## [0.1.2] - 2024-08-14
+
+ - Removed dependencies
+ - Removed Ractor-based concurrent pipe (as I don't trust it yet)
+
+## [0.1.1] - 2024-08-14
+
+- Tidied up the code
+- Added Plumbing::Chain
+
+## [0.1.0] - 2024-04-13
+
+- Initial release
+
+## [Unreleased]

data/README.md

@@ -1,63 +1,243 @@
 # Plumbing
 
-Actors, Observers and Data Pipelines.
+Small, fast building blocks for concurrent Ruby: **actors**, a **service
+locator**, a **composable event stream**, **observable** objects and a
+**state-machine engine** — built on
+[`literal`](https://github.com/joeldrapper/literal) and nothing else.
 
-## Usage
+> **v1 is a breaking rewrite** (`0.5.2 → 1.0.0`). See the
+> [CHANGELOG](CHANGELOG.md) for what changed.
 
-Start off by [configuring Plumbing](/docs/config.md) and selecting your `mode`.
+## Philosophy
 
-## Pipelines
+Plumbing gives you the few concurrency patterns an app actually needs without
+the surface area of the `dry-*` family. The core gem's **only runtime
+dependency is `literal`**. Anything heavier is opt-in — you `require` it and
+add the underlying gem yourself.
 
-[Data transformations](/docs/pipelines.md) similar to unix pipes.
+## Concepts
 
-## Actors
+### Actors
 
-[Asynchronous, thread-safe, objects](/docs/actors.md).
+Asynchronous, thread-safe objects. `include Plumbing::Actor`, declare typed
+async messages, and resolve results with `await`.
 
-## Pipes
+```ruby
+class Greeting
+  include Plumbing::Actor
+  def initialize(name:) = @name = name
+
+  async :say do
+    param :greeting, String, default: "Hello"
+    returns { |greeting:| "#{greeting} #{@name}" }  # validated params arrive as block kwargs
+  end
+end
+
+g = Greeting.new(name: "Alice")
+await { g.say(greeting: "Hi") }   # => "Hi Alice"
+```
 
-[Composable observers](/docs/pipes.md).
+Async messages forward **blocks** as well as params — declare `&block` in the
+`returns` signature and the caller's block arrives intact:
 
-## Rubber ducks
+```ruby
+class Speaker
+  include Plumbing::Actor
+  async :say_something do
+    returns { |&block| "I am speaking #{block.call}" }
+  end
+end
+
+await { Speaker.new.say_something { "in a block" } }   # => "I am speaking in a block"
+```
 
-[Type-safety the ruby way](/docs/rubber_ducks.md).
+Each actor owns a pluggable **worker**. `inline` (the default) ships with the
+core; `async`, `threaded` and `rails` are opt-in:
 
-## Installation
+```ruby
+require "plumbing/actor/async"   # also: add `async` to your Gemfile
+Plumbing::Actor.uses :async
+```
 
-Note: this gem is licensed under the [LGPL](/LICENCE).  This may or may not make it unsuitable for use by you or your company.
+Actors track who called them — `current_sender` (immediate) and
+`current_senders` (the full call-chain).
 
-Install the gem and add to the application's Gemfile by executing:
+### Providers
 
-```sh
-bundle add standard-procedure-plumbing
+A parameterised object locator. `Provider` is itself a **Plumbing actor**, so
+`register`, `provide` and `get` are async messages taking keyword arguments.
+Lookups via `[]` are the synchronous convenience — `provider[path]` is exactly
+`provider.get(path:).await`.
+
+- `register` - registers an object at a path - lookups on that path return the same object each time
+- `provide` - registers a factory at a path - lookups on that path return a new object each time
+
+```ruby
+# Every lookup returns the same object which is registered immediately
+Plumbing.services.register path: "app/config", value: AppConfig.load
+Plumbing.services["app/config"]
+
+# The first lookup calls the block and subsequent lookups are cached
+Plumbing.services.register(path: "db") { Database.connect }
+Plumbing.services["db"]
+
+# Each lookup calls the block
+Plumbing.services.provide(path: "system/clock") { Time.now }
+Plumbing.services["system/clock"]
 ```
 
-Then:
+The path can contain parameters which are then passed as keyword arguments to the provider block.  The arguments are always strings as they are extracted from the lookup query.  
 
 ```ruby
-require 'plumbing'
+# Every lookup calls `Person.find`
+Plumbing.services.provide(path: "people/:id") { |id:| Person.find(id) }
+Plumbing.services["/people/123"]
 
-# Set the mode for your Actors and Pipes
-Plumbing.config mode: :async
+# The first lookup calls `Person.find` and subsequent lookups are cached
+Plumbing.services.register(path: "people/:id") { |id:| Person.find(id) }
+Plumbing.services["/people/123"]
 ```
 
-## Development
+A cached registration can be given a **TTL** with `expires_in:` (seconds). After
+that long the cached value is evicted and the next lookup re-resolves through the
+block, restarting the clock — handy for singletons used in bursts that should
+release their memory once cold. Eviction is scheduled on the actor's worker, so
+it needs a worker that can defer: under the default `:inline` worker the TTL is a
+silent no-op and the value caches forever (much like a cache store with no expiry
+sweeper).
 
-### To Do
+```ruby
+# Re-fetched at most once every 60s; evicted in between so it can be reclaimed
+Plumbing.services.register(path: "exchange/rates", expires_in: 60) { RateApi.fetch }
+```
 
-- [ ] Add a debouncing filter for pipes
-- [ ] Pass the mode as a block parameter in `Plumbing::Spec.modes`
-- [ ] Move Plumbing::Actor::Transporter to Plumbing::Transporter ?? (planning to use it outside of Plumbing so would make sense not to imply it is tied to Actors)
-- [X] Ensure transporters deal with GlobalID models not being found / errors when unpacking
+Because `register` and `provide` are async, they return a message rather than
+raising inline. Registration errors (an ambiguous registration, a static value
+on a dynamic path) surface only when the message is awaited, so `await` if you
+need to catch them:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+provider.register(path: "locate/:object", value: "object").await   # => raises ArgumentError
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+If there is a conflict between a static path and a dynamic path, the one with the most static matches wins.  
 
-## Contributing
+```ruby
+@provider = Plumbing::Provider.new 
+
+@provider.register(path: "users/:id") { |id:| User.find(id) }
+@provider.register(path: "users/me") { Current.user }
+
+@provider["users/me"] # => Current.user 
+```
+
+```ruby
+@provider = Plumbing::Provider.new 
+
+# path has 2 static and 2 dynamic segments
+@provider.register(path: "users/:username/comments/:comment_id") { |username:, comment_id:| "user #{username} and comment #{comment_id}" }
+# path has 3 static and 1 dynamic segment
+@provider.register(path: "users/alice/comments/:comment_id") { |comment_id:|  "comment #{comment_id}" }
+
+# matches alice because the path has 3 static segments
+@provider["users/alice/comments/123"] # => comment 123
+@provider["users/bob/comments/123"] # => user bob and comment 123
+```
 
-Bug reports and pull requests are welcome on GitHub at <https://github.com/standard_procedure/plumbing>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/standard_procedure/plumbing/blob/main/CODE_OF_CONDUCT.md).
+**Nested providers.** Mount another Provider under a wildcard tail path
+(`"prefix/*"`) and lookups beneath that prefix are delegated to it — like
+mounting a sub-router. A lookup of the bare prefix returns the nested provider
+itself; a lookup with a tail forwards the remaining path. Only a Provider may be
+mounted under a wildcard (a static value is checked on registration; a block is
+checked when it resolves).
 
-## Code of Conduct
+```ruby
+users = Plumbing::Provider.new
+users.register(path: "me") { Current.user }
+
+app = Plumbing::Provider.new
+app.register path: "users/*", value: users
+
+app["users"]      # => the `users` provider itself
+app["users/me"]   # => Current.user  (delegates "me" to the nested provider)
+```
+
+Paths are automatically stripped of leading and trailing slashes.  
+
+Use the global `Plumbing.services`, or build and manage your own registry instances independently.
+
+### Pipeline + Event
+
+A composable, concurrency-safe event stream over immutable `Literal::Data`
+events.
+
+```ruby
+class SomethingHappened < Plumbing::Event
+  prop :id, String
+end
+
+errors = Pipeline::Only.new(
+  source: Pipeline::Junction.new(app_events, worker_events),
+  filters: ["Error*", "Critical*"],
+)
+errors.observe { |event| alert(event) }
+
+app_events << SomethingHappened.new(id: "123")
+```
+
+Compose with `Source`, `Only`, `Except`, `Filter` (regexp) and `Junction`
+(fan-in). Pushes are debounced and batched into a single notify pass.
+
+### Observable
+
+Mix `Plumbing::Observable` into any object — actor or not — to give it its own
+event stream. The host gains a public subscriber interface (`observe`, `remove`,
+`remove_all`) and a private emit interface (`push`, `notify`), backed by a
+lazily-created internal `Pipeline::Source`. Because the pipeline is the actor,
+these methods need not be async — they forward fire-and-forget.
+
+```ruby
+class Thermostat
+  include Plumbing::Observable
+
+  def temperature=(celsius)
+    @temperature = celsius
+    push TemperatureChanged.new(celsius: celsius)   # private — only the host emits
+  end
+end
+
+t = Thermostat.new
+t.observe { |event| puts "now #{event.celsius}°C" }
+t.temperature = 21   # => "now 21°C"
+```
+
+Observers subscribe from the outside; only the host emits. `Plumbing::Operation`
+is built on this — its lifecycle events (`Started`, `Transitioned`, …) are pushed
+through an `Observable` stream.
+
+## Installation
+
+```sh
+bundle add standard-procedure-plumbing
+```
+
+```ruby
+require "plumbing"
+```
+
+Note: this gem is licensed under the [LGPL](/LICENCE), which may or may not
+make it unsuitable for use by you or your company.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies, then
+`rake spec` to run the tests. `bin/console` gives you an interactive prompt.
+
+To install locally, run `bundle exec rake install`. To release, update the
+version in `lib/plumbing/version.rb` and run `bundle exec rake release`.
+
+## Contributing
 
-Everyone interacting in the Plumbing project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/standard_procedure/plumbing/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at
+<https://github.com/standard-procedure/plumbing>. This project follows a
+[code of conduct](https://github.com/standard-procedure/plumbing/blob/main/CODE_OF_CONDUCT.md).

data/lib/plumbing/actor/async.rb

@@ -1,52 +1,59 @@
+# frozen_string_literal: true
+
 require "async"
-require "async/semaphore"
-require "timeout"
+require_relative "worker"
+require_relative "message"
 
 module Plumbing
   module Actor
-    class Async
-      attr_reader :target
-
-      def initialize target
-        @target = target
-        @semaphore = ::Async::Semaphore.new(Plumbing.config.max_concurrency)
-      end
-
-      # Send the message to the target and wrap the result
-      def send_message(message_name, *args, **params, &block)
-        Plumbing.config.logger.debug { "-> #{@target.class}##{message_name}(#{args.inspect}, #{params.inspect})" }
-        task = @semaphore.async do
-          Plumbing.config.logger.debug { "---> #{@target.class}##{message_name}(#{args.inspect}, #{params.inspect})" }
-          @target.send(message_name, *args, **params, &block)
+    # Processes an actor's messages on the Async reactor, ONE AT A TIME, IN
+    # ARRIVAL ORDER — a single sequential consumer loop preserves the actor
+    # guarantee.
+    #
+    # NOTE: we deliberately do NOT use `Async::Queue#async`. That spawns a new
+    # task per item (bounded by a semaphore), so a single actor would deliver
+    # several messages concurrently and complete them out of order — which
+    # defeats the entire point of an actor. Concurrency belongs BETWEEN actors
+    # (each has its own worker/queue/consumer), never within one.
+    class Async < Worker
+      prop :queue, ::Async::Queue, default: -> { ::Async::Queue.new }
+
+      def call
+        Kernel.Async(transient: true) do
+          while (message = @queue.dequeue)
+            message.deliver
+          end
         end
-        sleep 0.01
-        Result.new(task)
       end
+      alias_method :start, :call
 
-      def safely(&)
-        Plumbing.config.logger.debug { "-> #{@target.class}#perform_safely" }
-        send_message(:perform_safely, &)
-        sleep 0.01
-        nil
-      end
+      def stop = @queue.close
 
-      def in_context? = true
+      def active? = !@queue.closed?
 
-      def stop = nil
+      def dispatch(message) = @queue.enqueue(message)
 
-      Result = Data.define(:task) do
-        def value
-          sleep 0.01
-          Timeout.timeout(Plumbing::Actor.timeout) do
-            task.wait
-          end
+      def after(delay, method:, sender: nil, params: {}, block: nil)
+        message = build_message(method: method, sender: sender, params: params, block: block)
+        deferral = Plumbing::Actor::Deferral.new
+        Kernel.Async(transient: true) do |task|
+          task.sleep delay
+          dispatch(message) unless deferral.cancelled?
         end
+        deferral
       end
-      private_constant :Result
-    end
 
-    def self.timeout
-      Plumbing.config.timeout
+      def message_class = Plumbing::Actor::Async::Message
+
+      class Message < Actor::Message
+        def _wait_until_ready
+          sleep 0.001 while @status == :waiting
+        end
+      end
     end
   end
 end
+
+# Opt-in worker: requiring this file registers it. Select with
+# `Plumbing::Actor.uses :async` (the app must also depend on the `async` gem).
+Plumbing::Actor.register(:async) { |actor| Plumbing::Actor::Async.new(actor: actor) }

data/lib/plumbing/actor/configuration.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Plumbing
+  module Actor
+    module Configuration
+      def worker_for actor
+        worker_types[selected_worker_type].call(actor)
+      end
+
+      def uses name
+        @selected_worker_type = name.to_sym
+      end
+
+      def selected_worker_type
+        @selected_worker_type ||= :inline
+      end
+
+      def workers = worker_types.keys
+
+      def register name, &builder
+        worker_types[name.to_sym] = builder
+      end
+
+      def worker_types
+        @worker_types ||= {inline: ->(actor) { Plumbing::Actor::Inline.new(actor: actor) }}
+      end
+    end
+  end
+end

data/lib/plumbing/actor/deferral.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Plumbing
+  module Actor
+    # An opaque handle for a scheduled (deferred) message. Cancelling sets a
+    # mutex-guarded flag that the worker's timer checks before dispatching. The
+    # flag itself is race-safe; a cancel landing in the tiny window after the
+    # check still lets one (benign, in-order) message through — the operation
+    # layer's generation token discards such a stale fire.
+    class Deferral
+      def initialize
+        @lock = Mutex.new
+        @cancelled = false
+      end
+
+      def cancel = @lock.synchronize { @cancelled = true }
+
+      def cancelled? = @lock.synchronize { @cancelled }
+    end
+  end
+end