fair_machines 0.1.5-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c3c4faee52a632fb98e06653ec81b1c60b779479aeadc28bf6dde0fa8622762e
+  data.tar.gz: cea172d1a0cb2679bbd9ef3db6defbc2d62983082c282c5c688a4bcefc3fca34
+SHA512:
+  metadata.gz: 58e781a081e6f3afe3a874cd07224a52cfd8be2ec1cb3cf8598c3d9910e7aa9581ca7c14dc0fc68ce019d2a4e3bc641b14933bcf9cf2944772620a1e2f4264e7
+  data.tar.gz: 797826760ab020f80c912e2cdfebcc255de233dd5df05e8643811eb718568e3c8b15f8d15f9018683bd355944b622a1569da6d54d4ad5a537d7f6d6f34fd85ec

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [0.1.5](https://github.com/seuros/fair_machines/compare/fair_machines/v0.1.4...fair_machines/v0.1.5) (2026-11-07)
+
+
+### Features
+
+* add KeyedFair hashed-lane budgets ([33d8f62](https://github.com/seuros/fair_machines/commit/33d8f62d6c8f8e8ad8a9bc759dffbdfa8b7a2706))
+
+## [0.1.4](https://github.com/seuros/fair_machines/compare/fair_machines/v0.1.3...fair_machines/v0.1.4) (2026-11-06)
+
+
+### Bug Fixes
+
+* share positive count parsing in tenants ffi ([85f970b](https://github.com/seuros/fair_machines/commit/85f970b7e7002248032c25fc36ad03b1b96ca56c))
+
+## [0.1.3](https://github.com/seuros/fair_machines/compare/fair_machines/v0.1.2...fair_machines/v0.1.3) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([c9e496f](https://github.com/seuros/fair_machines/commit/c9e496fca380c51529e965ce4c8158f5210ed258))
+
+## [0.1.2](https://github.com/seuros/fair_machines/compare/fair_machines/v0.1.1...fair_machines/v0.1.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([58a408b](https://github.com/seuros/fair_machines/commit/58a408ba6727d04d8517a6b76c47b90e381203e3))
+
+## [0.1.1](https://github.com/seuros/fair_machines/compare/fair_machines-v0.1.0...fair_machines/v0.1.1) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([3c25da7](https://github.com/seuros/fair_machines/commit/3c25da7ef06236f290cef43e29ce5519cbf69aff))

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+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,216 @@
+# FairMachines
+
+> One tenant with ten thousand jobs should not make every other tenant wait ten thousand jobs. ⚖️
+
+Cost-aware fair scheduling for Ruby. You give each tenant a budget for how much work it may have queued and a share of each dispatch round. `TenantFair` tells you whose job goes next, charges the tenant for its cost, and refuses to admit work past the budget. The loud tenant still gets served. It just doesn't get served *instead of* everyone else.
+
+## Quick Start
+
+```bash
+gem 'fair_machines'
+```
+
+```ruby
+# Two tenants. Each may have 100 units of work queued; each gets 2 units per round.
+fair = FairMachines::TenantFair.new(capacities: [100, 100], quanta: [2, 2])
+
+# Enterprise tenant enqueues ten PDF exports at cost 5. Small tenant queues five emails at cost 1.
+10.times { fair.admit(tenant: 0, cost: 5) }
+5.times  { fair.admit(tenant: 1, cost: 1) }
+
+# Each round, tell the scheduler the cost at the head of every tenant's queue.
+# It answers with the tenant whose head runs now. You pop that job and run it.
+fair.select([5, 1])   # => 1   the email goes first
+fair.select([5, 1])   # => 1
+fair.select([5, 1])   # => 1
+fair.select([5, 1])   # => 1
+fair.select([5, 1])   # => 0   the PDF has saved up enough share
+```
+
+Tenants are indices into the arrays you passed in. Heads are the cost of each tenant's next job, or `nil` when that tenant has nothing waiting.
+
+## A Message to the Resistance
+
+So you built the job queue. Priorities, retries, a dashboard. Then your biggest customer clicked "export everything" and ten thousand PDF jobs landed in the queue at once, and for the next forty minutes nobody else's password reset email went out.
+
+You added a second queue for the big customer. Then a third for the next big customer. Then a priority flag that every customer's jobs somehow ended up setting. None of it fixes the actual problem, which is that the queue has no idea what a tenant is, let alone how much of the worker pool that tenant has already consumed.
+
+Fairness is two numbers per tenant. How much work may this tenant have waiting at once, and how big a slice of each round does it get. With those, a ten-thousand-job export gets a fixed share of the workers and the password reset goes out in seconds, because the small tenant's slice is sitting there unused.
+
+This gem keeps those two numbers honest. You keep the queues.
+
+## Chapter 1: Stardate 2025.186, the AMS Shreedhar
+
+> **AMS Shreedhar**, NCC-4207, *Shreedhar*-class convoy escort.
+> The flagship does not get to spend every tenant's fuel allowance.
+
+The escort doesn't fly the convoy. It holds the fuel ledger: how much each ship may have on request at once, and how much is pumped to each per cycle. A ship with a loud captain and a long manifest still draws from its own allowance, charged by the actual mass of what it asked for. A dinghy asking for one pallet gets its pallet on the next cycle.
+
+Somewhere on the bridge, a junior officer suggests:
+
+```ruby
+def next_job
+  queue.shift   # it's a queue, first come first served, that's fair, right?
+end
+```
+
+"That," says the convoy master, "is how a dinghy starves behind a freighter."
+
+## The Flight Plan
+
+Each tenant is either idle or has cost queued. Admission moves cost in, dispatch and cancellation move it out, and a full budget turns new work away.
+
+```mermaid
+stateDiagram-v2
+    [*] --> idle
+    idle --> queued: admit within budget
+    queued --> queued: admit within budget
+    queued --> queued: admit over budget, refused
+    queued --> queued: select, head cost charged
+    queued --> idle: last head dispatched or cancelled
+    queued --> queued: cancel, cost returned
+    idle --> [*]
+```
+
+And the afternoon the enterprise tenant clicked "export everything":
+
+```mermaid
+sequenceDiagram
+    participant E as Enterprise (tenant 0)
+    participant F as TenantFair
+    participant S as Small shop (tenant 1)
+    participant W as Workers
+
+    E->>F: admit cost 5, ten times
+    F-->>E: true, true, true...
+    S->>F: admit cost 1
+    F-->>S: true
+
+    W->>F: select([5, 1])
+    F-->>W: tenant 1
+    Note over W: password reset goes out
+
+    W->>F: select([5, nil])
+    F-->>W: tenant 0
+    Note over W: first PDF renders
+
+    S->>F: admit cost 1
+    W->>F: select([5, 1])
+    F-->>W: tenant 1
+    Note over S: still seconds, not forty minutes
+```
+
+## How the Ledger Works
+
+### Admit
+
+Before a job is enqueued, ask whether the tenant has room for its cost. The answer is a plain boolean, and `false` means the job doesn't go on the queue.
+
+```ruby
+fair = FairMachines::TenantFair.new(capacities: [10, 5], quanta: [3, 1])
+
+fair.admit(tenant: 1, cost: 5)   # => true   budget 5, now full
+fair.admit(tenant: 1, cost: 1)   # => false  over budget
+fair.admit(tenant: 2, cost: 1)   # => false  no such tenant
+fair.tenant_count                # => 2
+```
+
+Over-budget is a refusal, not an error. Decide what to do with the job: reject it, hold it, tell the tenant.
+
+### Select
+
+Each round, pass the head cost of every tenant's queue. You get back the tenant whose head runs now, or `nil` when nobody is eligible. The chosen tenant is charged that cost against its budget, so the room comes back as the work drains.
+
+```ruby
+fair = FairMachines::TenantFair.new(capacities: [10, 5], quanta: [3, 1])
+fair.admit(tenant: 0, cost: 4)
+fair.admit(tenant: 1, cost: 1)
+
+fair.select([4, 1])     # => 1
+fair.select([4, nil])   # => 0
+fair.select([4, nil])   # => nil   tenant 0 has nothing left queued
+fair.admit(tenant: 0, cost: 7)   # => true   the dispatched 4 freed its room
+```
+
+Heads have to be truthful. A head that costs more than the tenant has admitted is not eligible and `select` returns `nil` for it.
+
+### Share is by cost, not by count
+
+Quanta are how much cost each tenant may dispatch per round, with leftover carried to the next round. A tenant whose head is expensive waits until it has saved up. A tenant with cheap jobs runs one every round.
+
+```ruby
+fair = FairMachines::TenantFair.new(capacities: [50, 50], quanta: [2, 2])
+fair.admit(tenant: 0, cost: 40)   # heavy jobs at cost 4
+fair.admit(tenant: 1, cost: 10)   # light jobs at cost 1
+
+Array.new(10) { fair.select([4, 1]) }
+# => [1, 1, 0, 1, 1, 1, 1, 0, 1, 1]
+```
+
+Same quanta, same share of the pool, and the light tenant still dispatches four jobs for every one heavy job, because the heavy job costs four times as much.
+
+Give one tenant a bigger quantum and it gets a bigger share of the pool outright:
+
+```ruby
+fair = FairMachines::TenantFair.new(capacities: [20, 20], quanta: [3, 1])
+fair.admit(tenant: 0, cost: 20)
+fair.admit(tenant: 1, cost: 20)
+
+Array.new(8) { fair.select([1, 1]) }
+# => [0, 0, 0, 1, 0, 0, 0, 1]
+```
+
+### Cancel
+
+A job that leaves the queue without being dispatched has to give its cost back, or the tenant's budget leaks until nothing is admitted.
+
+```ruby
+fair = FairMachines::TenantFair.new(capacities: [10, 5], quanta: [3, 1])
+fair.admit(tenant: 0, cost: 4)
+
+fair.cancel(tenant: 0, cost: 4)   # => true
+fair.cancel(tenant: 0, cost: 1)   # => false  nothing left to cancel
+fair.select([4, nil])             # => nil    the queue is empty, and so is the ledger
+```
+
+Cancelling more than was admitted is refused, and the ledger is untouched.
+
+### Too many tenants to name: `KeyedFair`
+
+Sixteen tenant slots is a crew roster. Orgs, API keys and IP prefixes are a starfield. `KeyedFair` hashes each key onto a fixed set of lanes, every lane with its own budget and no queue. A loud org fills its lane and gets `nil`; the other lanes don't notice. Keys that hash to the same lane share its budget, so pick enough lanes that a collision is rare.
+
+```ruby
+fair = FairMachines::KeyedFair.new(lanes: 64, capacity: 8)
+
+lane = fair.admit(hash: org_id.hash, cost: 1)   # => 17, or nil when that lane is full
+# ... do the work ...
+fair.release(lane:, cost: 1)                    # => true
+```
+
+`lanes:` is a power of two from 1 to 256. Any Integer works as `hash:`, negatives included, so `key.hash` goes straight in.
+
+## The Rules of the Escort
+
+- **1 to 16 tenants**, set by the length of `capacities:`. `quanta:` must be the same length. Empty, longer, or mismatched arrays raise `ArgumentError`.
+- **Capacities, quanta, and costs are positive Integers** below `2**32`. Zero is `ArgumentError`, negative or too large is `RangeError`, floats and strings are `TypeError`. Nothing is rounded for you.
+- **Heads are exactly `tenant_count` entries**, each a positive Integer or `nil`. The wrong length or a zero raises `ArgumentError`, and a float raises `TypeError`, before anything changes.
+- **Bad tenant indices don't raise.** `admit` and `cancel` with an unknown tenant return `false`.
+- **Frozen means frozen.** `freeze` the scheduler and `admit`, `cancel`, and `select` raise `FrozenError`. `tenant_count` still answers.
+- **A tenant that drains to empty loses its saved-up share.** Leftover quantum doesn't accumulate for a tenant with nothing queued.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "Round robin between tenants. Everybody gets a turn."
+### Reality: A turn is not a share. One tenant's turn is a thumbnail, another's is a 40-page PDF.
+
+Taking turns by job count hands the pool to whoever submits the heaviest jobs. Fairness has to be measured in what a job costs, which is why every call here carries a cost and why the scheduler charges it before it hands out the next turn.
+
+## What's Yours
+
+The scheduler is a ledger, not a queue. You keep a queue per tenant, call `admit` before you push, hand `select` the cost at the head of each queue, and pop the job from the tenant it names. Your cost estimates have to be honest, because the ledger believes them. And when a job dies on the floor without running, call `cancel`, or the tenant pays for it forever.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+**Remember: The export job will finish. The question is whether the password reset has to wait for it.**

data/ext/fair_machines_native/core/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.3.0](https://github.com/seuros/fair_machines/compare/fair-machines-v0.2.2...fair-machines-v0.3.0) (2026-11-07)
+
+
+### Features
+
+* add KeyedFair hashed-lane budgets ([33d8f62](https://github.com/seuros/fair_machines/commit/33d8f62d6c8f8e8ad8a9bc759dffbdfa8b7a2706))
+
+## [0.2.2](https://github.com/seuros/fair_machines/compare/fair-machines-v0.2.1...fair-machines-v0.2.2) (2026-11-06)
+
+
+### Bug Fixes
+
+* crates.io keywords and categories for the core ([c9e496f](https://github.com/seuros/fair_machines/commit/c9e496fca380c51529e965ce4c8158f5210ed258))
+
+## [0.2.1](https://github.com/seuros/fair_machines/compare/fair-machines-v0.2.0...fair-machines-v0.2.1) (2026-11-06)
+
+
+### Bug Fixes
+
+* keep test sources out of the packaged gem and crate ([58a408b](https://github.com/seuros/fair_machines/commit/58a408ba6727d04d8517a6b76c47b90e381203e3))
+
+## [0.2.0](https://github.com/seuros/fair_machines/compare/fair-machines-v0.1.0...fair-machines-v0.2.0) (2026-11-06)
+
+
+### Features
+
+* initial extraction ([3c25da7](https://github.com/seuros/fair_machines/commit/3c25da7ef06236f290cef43e29ce5519cbf69aff))

data/ext/fair_machines_native/core/README.md

@@ -0,0 +1,21 @@
+# fair-machines
+
+> **AMS Shreedhar**, NCC-4207, *Shreedhar*-class convoy escort.
+
+Engine-room flight manual: share departure capacity without starving smaller crews.
+
+Allocation-free `no_std` tenant isolation: independent cost-credit budgets for
+admission, with DRR selection delegated to `priority-machines`. This is not a
+second implementation of DRR. Admission accounts queued cost; selection returns
+that cost to the tenant budget. Running work after selection is not bounded here.
+
+Adapters own queues, present truthful head costs, and serialize admission,
+selection, and cancellation. Aggregate credits do not identify individual jobs.
+`cancel` returns admitted cost; when a tenant drains its DRR visit is reset.
+Fairness assumes continuously backlogged tenants and meaningful cost estimates.
+`KeyedFair<LANES>` covers an open tenant set: caller-hashed keys map onto fixed
+lanes with independent credit budgets and no scheduler. Keys sharing a lane share
+its budget.
+
+Tenant hierarchies, per-flow WFQ, runtime preemption, and strict latency/starvation
+bounds are not implemented.

data/ext/fair_machines_native/extconf.rb

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

data/lib/fair_machines/version.rb

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

data/lib/fair_machines.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'fair_machines/version'
+require 'fair_machines_native/fair_machines_native'

data/sig/fair_machines.rbs

@@ -0,0 +1,18 @@
+module FairMachines
+  VERSION: String
+  class TenantFair
+    def self.new: (capacities: Array[Integer], quanta: Array[Integer]) -> instance
+    def admit: (tenant: Integer, cost: Integer) -> bool
+    def cancel: (tenant: Integer, cost: Integer) -> bool
+    def select: (Array[Integer?] heads) -> Integer?
+    def tenant_count: () -> Integer
+  end
+  class KeyedFair
+    def self.new: (lanes: Integer, capacity: Integer) -> instance
+    def admit: (hash: Integer, cost: Integer) -> Integer?
+    def release: (lane: Integer, cost: Integer) -> bool
+    def in_flight: (Integer lane) -> Integer
+    def lane: (Integer hash) -> Integer
+    def lane_count: () -> Integer
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: fair_machines
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: x86_64-linux
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-07 00:00:00.000000000 Z
+dependencies: []
+description: Initial unstable Ruby adapter to the no_std fair-machines Rust core.
+  Local source builds require unpublished path-only flow and priority siblings.
+email:
+- oss@seuros.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/fair_machines_native/core/CHANGELOG.md
+- ext/fair_machines_native/core/README.md
+- ext/fair_machines_native/extconf.rb
+- lib/fair_machines.rb
+- lib/fair_machines/version.rb
+- lib/fair_machines_native/fair_machines_native.so
+- sig/fair_machines.rbs
+homepage: https://github.com/seuros/fair_machines
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seuros/fair_machines
+  bug_tracker_uri: https://github.com/seuros/fair_machines/issues
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: fair_machines_native
+  cargo_manifest_path: ext/fair_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: Native per-tenant admission budgets and deficit fairness
+test_files: []