flow_machines 0.1.4-x86_64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d03519b4f84f989fb2a3619debbddff9a0c1e090203952433028748a6a5b4abc
+  data.tar.gz: '08a6e7b9686aaa4de3377d746a4fa9a007e97699f408a21bc36e769ddada0f9c'
+SHA512:
+  metadata.gz: c7bf3cfe5d2fda1c0080e8b1ee229821a91cde688c7dbb251f941446648d31d487102aaf21aec7e53dc337486ad58ae7b5f3b07841c592dfaa6d843408173ad1
+  data.tar.gz: 74e28bf464ffc363484a012af5d299e918b790d5c2bac6b63db3fbd1c920576e67218ee336ef8514b674d673ff408bd84a77285f86e04f2393631d37badf2388

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.1.4](https://github.com/seuros/flow_machines/compare/flow_machines/v0.1.3...flow_machines/v0.1.4) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([14830b5](https://github.com/seuros/flow_machines/commit/14830b52d44337c74302591f4c73ebcbe8bac3e4))
+
+## [0.1.3](https://github.com/seuros/flow_machines/compare/flow_machines/v0.1.2...flow_machines/v0.1.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([3c9e544](https://github.com/seuros/flow_machines/commit/3c9e544f3b2140a179455b34236fd0f2ab9747a7))
+
+## [0.1.2](https://github.com/seuros/flow_machines/compare/flow_machines/v0.1.1...flow_machines/v0.1.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* cross builds no longer compile for the host ([5a0009f](https://github.com/seuros/flow_machines/commit/5a0009fdef9267dc83ca7704b1e9f0f6373d3a5a))
+
+## [0.1.1](https://github.com/seuros/flow_machines/compare/flow_machines-v0.1.0...flow_machines/v0.1.1) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([e087042](https://github.com/seuros/flow_machines/commit/e0870427dde8239fc30fc2fa10e6e204ebab9289))

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,230 @@
+# FlowMachines
+
+> Your producer has a bigger engine than your consumer. Somebody has to say "hold." 🌊
+
+Backpressure for Ruby, in two small parts. A `CreditWindow` counts how much work is allowed in flight and refuses anything past the line. A `Watermarks` controller watches a queue's occupancy and tells you when to pause the producer and when it's safe to resume, without flapping between the two every time the count twitches.
+
+## Quick Start
+
+```bash
+gem 'flow_machines'
+```
+
+```ruby
+window  = FlowMachines::CreditWindow.new(capacity: 100)
+control = FlowMachines::Watermarks.new(low: 20, high: 80)
+
+# Producer side: ask before you enqueue.
+def enqueue(job)
+  return false unless window.try_acquire(1)
+  queue << job
+  producer.pause if control.observe(queue.length) == :pause
+  true
+end
+
+# Consumer side: give the credit back when the work is done.
+def finish(job)
+  queue.delete(job)
+  window.release(1)
+  producer.resume if control.observe(queue.length) == :resume
+end
+```
+
+The window stops the queue from growing past 100. The watermarks tell the producer to stop at 80 and start again at 20. Everything in between is your queue and your producer. The gem only decides.
+
+## A Message to the Resistance
+
+So the ingest service got faster. Good news, until the worker pool behind it started falling over every evening at seven.
+
+You know the shape of this one. The producer runs at whatever speed the producer runs at. The consumer runs slower. The gap goes into a queue, and the queue goes into memory, and memory is finite, and at seven the OOM killer arrives like a bailiff. Nobody wrote a bug. Everything did its job. The system just never had a word for "enough."
+
+The first fix everyone reaches for is a hard cap: drop the job when the queue is full. That's load shedding, and sometimes it's right. But if the jobs matter, dropping them just moves the outage to wherever those jobs were supposed to land.
+
+The second fix is to tell the producer to slow down. That's backpressure, and it needs two things: a count that actually limits what's in flight, and a signal that says "pause" at one level and "resume" at a lower one, so the producer isn't toggled on and off a thousand times a second as the count hovers around the line.
+
+Those two things are this gem.
+
+## Chapter 1: Stardate 2025.186, the AMS Cerf
+
+> **AMS Cerf**, NCC-4209, *Cerf*-class traffic escort.
+> Count the berths before inviting the next freighter through the gate.
+
+The escort doesn't fly the freighters and doesn't own the dock. It keeps the count of berths, issues a credit for each one, and raises the hold signal when the approach lane fills up. Captains who ignore the signal still crash. Captains who obey it never do.
+
+Somewhere in the approach lane, a freshly commissioned lieutenant files a flight plan:
+
+```ruby
+loop do
+  job = upstream.next
+  queue.push(job)   # "Ruby arrays grow automatically, it's fine"
+end
+```
+
+"That," says the dock master, "is how a lane becomes a debris field."
+
+## The Flight Plan
+
+The watermarks controller has two states and moves between them only at the edges.
+
+```mermaid
+stateDiagram-v2
+    [*] --> running
+    running --> running: observe(n) with n below high, unchanged
+    running --> paused: observe(n) with n at or above high, pause
+    paused --> paused: observe(n) with n above low, unchanged
+    paused --> running: observe(n) with n at or below low, resume
+```
+
+And an evening at the dock, with a window of 3 and watermarks at 1 and 3:
+
+```mermaid
+sequenceDiagram
+    participant P as Producer
+    participant W as CreditWindow(3)
+    participant M as Watermarks(1, 3)
+    participant C as Consumer
+
+    P->>W: try_acquire(1)
+    W-->>P: true (1 in flight)
+    P->>M: observe(1)
+    M-->>P: unchanged
+
+    P->>W: try_acquire(1)
+    W-->>P: true (2 in flight)
+    P->>M: observe(2)
+    M-->>P: unchanged
+
+    P->>W: try_acquire(1)
+    W-->>P: true (3 in flight)
+    P->>M: observe(3)
+    M-->>P: pause
+    Note over P: stops producing
+
+    P->>W: try_acquire(1)
+    W-->>P: false (window full)
+
+    C->>W: release(1)
+    W-->>C: true (2 in flight)
+    C->>M: observe(2)
+    M-->>C: unchanged
+    Note over P: still paused, no flapping
+
+    C->>W: release(1)
+    W-->>C: true (1 in flight)
+    C->>M: observe(1)
+    M-->>C: resume
+    Note over P: starts producing again
+```
+
+## The Credit Window
+
+A window has a capacity. Acquiring takes units out of it, releasing puts them back. Both are all-or-nothing.
+
+```ruby
+window = FlowMachines::CreditWindow.new(capacity: 3)
+window.capacity    # => 3
+window.in_flight   # => 0
+window.available   # => 3
+
+window.try_acquire(2)   # => true
+window.try_acquire(2)   # => false, only 1 left and we asked for 2
+window.in_flight        # => 2
+window.available        # => 1
+```
+
+A refused acquire takes nothing. There is no partial grant, so you never have to figure out how much you actually got.
+
+Release is the same deal in reverse:
+
+```ruby
+window.release(3)   # => false, only 2 are out
+window.release(2)   # => true
+window.release(1)   # => false, nothing is out
+window.available    # => 3
+```
+
+The window is a count, not a ledger. It doesn't know who acquired what. If your code acquires on enqueue and forgets to release on a cancelled job, the window will slowly fill with ghosts. Release every unit you acquire exactly once, including on the error path.
+
+## The Watermarks
+
+A watermarks controller starts running. Feed it the current occupancy after every change and it answers with one of three words.
+
+```ruby
+control = FlowMachines::Watermarks.new(low: 2, high: 5)
+control.state        # => :running
+
+control.observe(4)   # => :unchanged
+control.observe(5)   # => :pause
+control.paused?      # => true
+control.observe(5)   # => :unchanged, already paused
+control.observe(3)   # => :unchanged, above low, stay paused
+control.observe(2)   # => :resume
+control.observe(0)   # => :unchanged
+```
+
+The gap between `low` and `high` is the whole point. A controller that paused at 5 and resumed at 4 would flap every time one job finished. This one pauses at 5 and won't resume until the queue drains to 2. That's hysteresis, and it's why your producer doesn't get whiplash.
+
+`:pause` and `:resume` are edges. You get each one once per crossing. If a producer connects late and missed the edge, ask `state` or `paused?` instead of waiting for a signal that already went by.
+
+Occupancy is whatever you want to measure. Queue length is the obvious choice. Bytes buffered, open connections, or outstanding requests all work just as well, as long as you measure the same thing every time.
+
+## Putting Them Together
+
+The window and the controller don't know about each other. You wire them around your queue. Here's a cancellation path, the one everyone forgets:
+
+```ruby
+window  = FlowMachines::CreditWindow.new(capacity: 4)
+control = FlowMachines::Watermarks.new(low: 1, high: 3)
+queue   = []
+
+3.times do |id|
+  window.try_acquire(1)
+  queue << id
+  control.observe(queue.length)   # :unchanged, :unchanged, :pause
+end
+control.paused?                   # => true
+
+# A job is cancelled before it ever ran. Still a release.
+queue.pop
+window.release(1)                 # => true
+control.observe(queue.length)     # => :unchanged, 2 is above low
+
+# One finishes normally.
+queue.shift
+window.release(1)                 # => true
+control.observe(queue.length)     # => :resume
+window.in_flight                  # => 1, same as queue.length
+```
+
+If the cancelled job hadn't released its credit, `in_flight` would read 2 while the queue held 1, and the window would be one berth short forever.
+
+## The Rules of the Escort
+
+- **Counts are Integers** in `0..4_294_967_295`. Capacity, acquire, and release units must be at least 1. Floats and strings raise `TypeError`, zero raises `ArgumentError`, negatives and anything past the range raise `RangeError`.
+- **Thresholds obey `0 <= low < high`.** Equal thresholds or a reversed pair raise `ArgumentError`. A `low` of zero is fine: resume only when fully drained.
+- **Keywords only.** `CreditWindow.new(3)` and `Watermarks.new(1, 2)` raise `ArgumentError`. So does an unknown keyword.
+- **A rejected observation changes nothing.** Pass the controller a float and it raises, but its state is exactly what it was before.
+- **No copies.** `dup` and `clone` raise `TypeError`. Live accounting isn't something you want two of.
+- **Frozen means frozen.** `freeze` either object and every mutation raises `FrozenError`.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "I'll cap the queue and drop what doesn't fit."
+### Reality: You've moved the outage downstream and called it resilience.
+
+Dropping is a fine answer when the work is disposable. When it isn't, every dropped job is a retry somewhere else, a reconciliation report, or a customer email. Backpressure keeps the work and slows the source. Pick the one that matches what the jobs are worth.
+
+### You Think: "Pause at 80, resume at 79, nice and responsive."
+### Reality: Your producer now has a 79-to-80 oscillation you can hear from the next room.
+
+One finished job resumes the producer. One enqueued job pauses it. Repeat a few thousand times a second. The gap between `low` and `high` is not slack. It's the thing that makes the signal mean something.
+
+## What's Yours
+
+The gem decides. It doesn't enqueue, dequeue, block, sleep, spawn threads, or talk to another process. Your queue is yours, your producer is yours, and so is making the producer actually stop when it hears `:pause`. If the window and the queue are touched from more than one thread, wrap the acquire-and-push and the pop-and-release in your own lock so the count and the queue never disagree.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+**Remember: A queue that can grow forever is just an outage with a delay on it.**

data/ext/flow_machines_native/core/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.2.2](https://github.com/seuros/flow_machines/compare/flow-machines-v0.2.1...flow-machines-v0.2.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([14830b5](https://github.com/seuros/flow_machines/commit/14830b52d44337c74302591f4c73ebcbe8bac3e4))
+
+## [0.2.1](https://github.com/seuros/flow_machines/compare/flow-machines-v0.2.0...flow-machines-v0.2.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([3c9e544](https://github.com/seuros/flow_machines/commit/3c9e544f3b2140a179455b34236fd0f2ab9747a7))
+
+## [0.2.0](https://github.com/seuros/flow_machines/compare/flow-machines-v0.1.0...flow-machines-v0.2.0) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([e087042](https://github.com/seuros/flow_machines/commit/e0870427dde8239fc30fc2fa10e6e204ebab9289))

data/ext/flow_machines_native/core/README.md

@@ -0,0 +1,59 @@
+# flow-machines
+
+> **AMS Cerf**, NCC-4209, *Cerf*-class traffic escort.
+
+Engine-room flight manual: count docking credits before admitting more traffic.
+
+Decision-only flow control with no runtime, I/O, allocator, or dependencies.
+
+## Capacity Credits
+
+```rust
+use core::num::NonZeroU32;
+use flow_machines::CreditWindow;
+
+# fn example() -> Option<()> {
+let mut window = CreditWindow::new(NonZeroU32::new(2)?);
+assert!(window.try_acquire(NonZeroU32::MIN));
+assert!(window.try_acquire(NonZeroU32::MIN));
+assert!(!window.try_acquire(NonZeroU32::MIN));
+assert!(window.release(NonZeroU32::MIN));
+assert_eq!(window.available(), 1);
+# Some(())
+# }
+# assert_eq!(example(), Some(()));
+```
+
+Acquisition and release are all-or-nothing. Failed operations leave state
+unchanged; capacity never overflows. Units can be requests, messages, or bytes,
+but must be consistent within a window.
+
+This is **aggregate accounting**, not an owned-permit API. The adapter must return
+each acquired credit exactly once, including on cancellation and failure.
+A release larger than the outstanding balance is rejected, but repeated releases
+cannot always be distinguished from legitimate completions. Credits are local
+state, not authenticated distributed permissions.
+
+## High/Low Watermarks
+
+```rust
+use core::num::NonZeroU32;
+use flow_machines::{Signal, Watermarks};
+
+# fn example() -> Option<()> {
+let mut control = Watermarks::new(2, NonZeroU32::new(5)?)?;
+assert_eq!(control.observe(5), Signal::Pause);
+assert_eq!(control.observe(4), Signal::Unchanged);
+assert_eq!(control.observe(2), Signal::Resume);
+# Some(())
+# }
+# assert_eq!(example(), Some(()));
+```
+
+`low < high` is required. A running producer pauses at `occupancy >= high`;
+a paused producer resumes at `occupancy <= low`. The gap prevents oscillation.
+Signals are edges: repeated observations in the same state return `Unchanged`.
+Newly attached producers should inspect `state()` as well as future signals.
+
+Watermarks do not enforce capacity. Combine them with credits: producers should
+honor the signals, while credit acquisition remains the hard admission boundary.

data/ext/flow_machines_native/extconf.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ffi/extconf'

data/lib/flow_machines/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FlowMachines
+  VERSION = '0.1.4'
+end

data/lib/flow_machines.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'flow_machines/version'
+
+# One implementation: Ruby delegates every policy decision to the Rust core.
+# A missing extension is an installation error, not a request for a fallback.
+require 'flow_machines_native/flow_machines_native'

data/sig/flow_machines.rbs

@@ -0,0 +1,27 @@
+# Native policy decisions only. The caller owns queues and enforces the results.
+module FlowMachines
+  VERSION: String
+
+  type signal = :pause | :resume | :unchanged
+  type state = :running | :paused
+
+  # Aggregate accounting, not a semaphore or a per-work-item permit ledger.
+  class CreditWindow
+    def self.new: (capacity: Integer) -> instance
+    def try_acquire: (Integer units) -> bool
+    def release: (Integer units) -> bool
+    def capacity: () -> Integer
+    def in_flight: () -> Integer
+    def available: () -> Integer
+    def inspect: () -> String
+  end
+
+  # Starts running; pauses at occupancy >= high and resumes at occupancy <= low.
+  class Watermarks
+    def self.new: (low: Integer, high: Integer) -> instance
+    def observe: (Integer occupancy) -> signal
+    def state: () -> state
+    def paused?: () -> bool
+    def inspect: () -> String
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: flow_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.4
+platform: x86_64-darwin
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-06 00:00:00.000000000 Z
+dependencies: []
+description: A native binding to the allocation-free flow-machines Rust core. Tracks
+  aggregate capacity and high/low-watermark producer signals; the caller owns queues,
+  credit ownership, and enforcement.
+email:
+- oss@seuros.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/flow_machines_native/core/CHANGELOG.md
+- ext/flow_machines_native/core/README.md
+- ext/flow_machines_native/extconf.rb
+- lib/flow_machines.rb
+- lib/flow_machines/version.rb
+- lib/flow_machines_native/flow_machines_native.bundle
+- sig/flow_machines.rbs
+homepage: https://github.com/seuros/flow_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/flow_machines
+  bug_tracker_uri: https://github.com/seuros/flow_machines/issues
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: flow_machines_native
+  cargo_manifest_path: ext/flow_machines_native/ffi/Cargo.toml
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Capacity credits and backpressure decisions for Ruby
+test_files: []