faymora 0.1

data/spec/faymora/node_spec.rb

@@ -0,0 +1,107 @@
+require 'spec_helper'
+
+RSpec.describe Faymora::Node do
+  describe '#initialize' do
+    it 'inherits from GlooX::Node and forces serializer to MessagePack' do
+      expect(described_class < GlooX::Node).to be true
+
+      n = described_class.new(url: 'u', serializer: :other, extra: 1)
+      expect(n).to be_a(GlooX::Node)
+      expect(n.opts[:serializer]).to be(MessagePack)
+      expect(n.opts[:url]).to eq('u')
+      expect(n.opts[:extra]).to eq(1)
+    end
+  end
+
+  describe '.connect' do
+    it 'builds a Faymora::Client with handler: :node merged into options' do
+      client = instance_double(Faymora::Client)
+      expect(Faymora::Client).to receive(:new)
+        .with(hash_including(host: 'h', handler: :node))
+        .and_return(client)
+
+      result = described_class.connect(host: 'h')
+      expect(result).to eq(client)
+    end
+  end
+
+  describe '.start' do
+    it 'instantiates a node, calls #start and returns the instance' do
+      instance = instance_double(described_class)
+      expect(described_class).to receive(:new).with(foo: 1).and_return(instance)
+      expect(instance).to receive(:start)
+
+      expect(described_class.start(foo: 1)).to eq(instance)
+    end
+  end
+
+  describe '.boot' do
+    it 'calls .start and then .connect using the started node url' do
+      started = instance_double(described_class, url: 'xmpp://example')
+      expect(described_class).to receive(:start).with(role: 'worker').and_return(started)
+
+      client = instance_double(Faymora::Client)
+      expect(Faymora::Client).to receive(:new)
+        .with(hash_including(url: 'xmpp://example', handler: :node))
+        .and_return(client)
+
+      expect(described_class.boot(role: 'worker')).to eq(client)
+    end
+  end
+
+  describe '.when_ready' do
+    # A tiny fake reactor to drive the polling loop deterministically
+    class FakeReactor
+      def initialize
+        @calls = 0
+      end
+
+      def run_in_thread; end
+
+      # Call the provided block immediately, passing the block itself as `task`
+      def delay(_seconds, &blk)
+        blk.call(blk)
+      end
+
+      # Expose a toggling state through the same instance
+      def rpc_exception?
+        @calls += 1
+        @calls == 1
+      end
+    end
+
+    it 'polls client.alive? until success, then closes client and yields' do
+      # Replace Raktr constant with our fake reactor
+      stub_const('Raktr', Class.new do
+        def initialize; end
+        def run_in_thread; end
+        def delay(_s)
+          # Provide a task proc to the block and let the block control rescheduling
+          yield(proc {})
+        end
+      end)
+
+      reactor = double('reactor', run_in_thread: true)
+      allow(Raktr).to receive(:new).and_return(reactor)
+
+      # The `alive?` callback receives an object responding to `rpc_exception?` and `delay`.
+      poller = FakeReactor.new
+
+      client = instance_double(Faymora::Client)
+      expect(Faymora::Client).to receive(:new)
+        .with(hash_including(url: 'xmpp://n', handler: :node, client_max_retries: 0, connection_pool_size: 1))
+        .and_return(client)
+
+      # Simulate two polls: first with exception, then success
+      expect(client).to receive(:alive?) do |&blk|
+        blk.call(poller)
+      end.twice
+
+      expect(client).to receive(:close)
+
+      yielded = false
+      described_class.when_ready('xmpp://n') { yielded = true }
+      expect(yielded).to be true
+    end
+  end
+end

data/spec/faymora/provision_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+RSpec.describe Faymora::Provision do
+  # Host class to include the module under test
+  class HostForProvision
+    include Faymora::Provision
+  end
+
+  describe 'inclusion' do
+    it 'adds a .provision class method to the host' do
+      expect(HostForProvision).to respond_to(:provision)
+    end
+  end
+
+  describe '.provision' do
+    it 'delegates to Slotz::Reservation.provision with the host class and options' do
+      options = { size: 3, region: 'eu' }
+      expect(Slotz::Reservation).to receive(:provision)
+        .with(HostForProvision, options)
+        .and_return(:token)
+
+      expect(HostForProvision.provision(options)).to eq(:token)
+    end
+
+    it 'passes an empty hash when options are omitted' do
+      expect(Slotz::Reservation).to receive(:provision)
+        .with(HostForProvision, {})
+        .and_return(:ok)
+
+      expect(HostForProvision.provision).to eq(:ok)
+    end
+  end
+end

data/spec/faymora/rpc_spec.rb

@@ -0,0 +1,43 @@
+require 'spec_helper'
+
+RSpec.describe Faymora::RPC do
+  # Minimal host including the module under test
+  class DummyRPC
+    include Faymora::RPC
+
+    def initialize(url)
+      @url = url
+    end
+
+    def url
+      @url
+    end
+  end
+
+  let(:url) { 'xmpp://example' }
+  let(:host) { DummyRPC.new(url) }
+
+  describe '#client' do
+    it 'builds a Faymora::Client with the instance url and handler: :instance' do
+      client = instance_double(Faymora::Client)
+      expect(Faymora::Client).to receive(:new)
+        .with(hash_including(url: url, handler: :instance))
+        .and_return(client)
+
+      expect(host.client).to be(client)
+    end
+  end
+
+  describe '#server' do
+    it 'returns self' do
+      expect(host.server).to be(host)
+    end
+  end
+
+  describe '#node' do
+    it 'is defined (abstract) and returns nil by default' do
+      expect(host).to respond_to(:node)
+      expect(host.node).to be_nil
+    end
+  end
+end

data/spec/faymora/service_spec.rb

@@ -0,0 +1,102 @@
+require 'spec_helper'
+
+RSpec.describe Faymora::Service do
+  # Dummy host including the module under test
+  class DummyService
+    include Faymora::Service
+
+    # Provide a minimal client to satisfy Link expectations if ever invoked
+    def client
+      :client
+    end
+  end
+
+  let(:service_class) { Class.new(DummyService) }
+  let(:service) { service_class.new }
+
+  describe 'class DSL' do
+    it 'defaults would_interest? to true when no predicate set' do
+      c = Class.new(DummyService)
+      expect(c.would_interest?(Faymora::Item.new(foo: 1))).to be true
+    end
+
+    it 'allows setting an interest predicate via .interested_in' do
+      service_class.interested_in { |item| item.respond_to?(:foo) && item.foo == 2 }
+
+      expect(service_class.would_interest?(Faymora::Item.new(foo: 2))).to be true
+      expect(service_class.would_interest?(Faymora::Item.new(foo: 1))).to be false
+    end
+
+    it 'stores a consumer via .upon and exposes it via ._upon' do
+      blk = proc { |i| [:handled, i] }
+      service_class.upon(&blk)
+
+      stored = service_class._upon
+      expect(stored).to be_a(Proc)
+      item = Faymora::Item.new
+      expect(stored.call(item)).to eq([:handled, item])
+    end
+
+    it 'toggles ignore state via .ignore! and .ignore?' do
+      expect(service_class.ignore?).to be false
+      service_class.ignore!
+      expect(service_class.ignore?).to be true
+    end
+  end
+
+  describe '#join' do
+    it 'yields to the provided block and returns its result' do
+      yielded = nil
+      result = service.join { yielded = :ok; 123 }
+      expect(yielded).to eq(:ok)
+      expect(result).to eq(123)
+    end
+  end
+
+  describe '#interested?' do
+    it 'delegates to the class-level would_interest? with the item' do
+      service_class.interested_in { |i| i.foo == 'y' }
+      yes = Faymora::Item.new(foo: 'y')
+      no  = Faymora::Item.new(foo: 'n')
+
+      expect(service.interested?(yes)).to be true
+      expect(service.interested?(no)).to be false
+    end
+  end
+
+  describe '#interested!' do
+    it 'marks the item as interesting' do
+      item = Faymora::Item.new
+      service.interested!(item)
+      expect(item.interesting).to be true
+    end
+  end
+
+  describe '#consume' do
+    it 'invokes the class-level consumer with the item and returns its result' do
+      service_class.upon { |i| i.processed = true; :done }
+      item = Faymora::Item.new
+      expect(service.consume(item)).to eq(:done)
+      expect(item.processed).to be true
+    end
+  end
+
+  describe '#process' do
+    it 'converts non-Item data via Item.from_data and consumes when interested' do
+      # Predicate always true
+      service_class.interested_in { |_i| true }
+      service_class.upon { |i| [i.class, i.foo] }
+
+      result = service.process({ foo: 5 })
+      expect(result).to eq([Faymora::Item, 5])
+    end
+
+    it 'returns nil and does not consume when not interested' do
+      service_class.interested_in { |_i| false }
+      expect(service_class).not_to receive(:_upon)
+
+      res = service.process(Faymora::Item.new(foo: 1))
+      expect(res).to be_nil
+    end
+  end
+end

data/spec/faymora/throughput_spec.rb

@@ -0,0 +1,125 @@
+require 'spec_helper'
+
+RSpec.describe Faymora::Throughput do
+  # Minimal host including the module under test
+  class DummyThroughput
+    include Faymora::Throughput
+
+    attr_accessor :input
+
+    def initialize
+      super
+      @clock_counter = 0
+    end
+
+    def has_input?
+      !!@input
+    end
+
+    # Expose counters for assertions in specs
+    def click_counter
+      @click_counter
+    end
+
+    def clock_counter
+      @clock_counter
+    end
+  end
+
+  let(:host) { DummyThroughput.new }
+
+  before do
+    # Avoid running real GC during specs
+    allow(GC).to receive(:start)
+  end
+
+  describe '#clock' do
+    it 'yields the item, appends a pass with class name, and always calls click!' do
+      item = Faymora::Item.new(passes: [])
+
+      # Verify it yields and records a pass
+      yielded = nil
+      expect(host).to receive(:click!).and_call_original
+
+      host.clock(item) { |i| yielded = i }
+
+      expect(yielded).to be(item)
+      expect(item.passes).not_to be_empty
+      last = item.passes.last
+      expect(last).to be_a(Faymora::Item::Pass)
+      expect(last.path).to eq(DummyThroughput.to_s)
+    end
+
+    it 'still calls click! when the block raises (ensure)' do
+      item = Faymora::Item.new(passes: [])
+      expect(host).to receive(:click!).and_call_original
+
+      expect do
+        host.clock(item) { raise 'boom' }
+      end.to raise_error(RuntimeError, 'boom')
+    end
+  end
+
+  describe '#click!' do
+    it 'increments the click counter and triggers GC' do
+      expect(host.click_counter).to eq 0
+      host.click!
+      expect(host.click_counter).to eq(1)
+      expect(GC).to have_received(:start)
+    end
+
+    it 'calls rectify when bottleneck? is true and not otherwise', focus: true do
+      allow(host).to receive(:bottleneck?).and_return(true)
+      expect(host).to receive(:rectify)
+      host.click!
+
+      allow(host).to receive(:bottleneck?).and_return(false)
+      expect(host).not_to receive(:rectify)
+      host.click!
+    end
+  end
+
+  describe '#throughput' do
+    it 'returns nil until warmed up, then clicks per clock_counter' do
+      # Not warmed up initially
+      expect(host.throughput).to be_nil
+
+      # Manually set counters to simulate warm state
+      host.instance_variable_set(:@clock_counter, 10)
+      host.instance_variable_set(:@click_counter, described_class::WARMED_UP_CLICKS)
+
+      t = host.throughput
+      expect(t).not_to be_nil
+      expect(t).to eq(described_class::WARMED_UP_CLICKS / 10.0)
+    end
+  end
+
+  describe '#bottleneck?' do
+    it 'is false when there is no input or throughput is nil' do
+      # No input
+      allow(host).to receive(:throughput).and_return(100.0)
+      expect(host.bottleneck?).to be false
+
+      # With input but no throughput
+      host.input = instance_double('Upstream', throughput: 200.0)
+      allow(host).to receive(:throughput).and_return(nil)
+      expect(host.bottleneck?).to be false
+    end
+
+    it 'returns true when input throughput is higher than own throughput' do
+      host.input = instance_double('Upstream', throughput: 10.0)
+      allow(host).to receive(:throughput).and_return(5.0)
+      expect(host.bottleneck?).to be true
+    end
+
+    it 'returns false when input throughput is lower or equal' do
+      host.input = instance_double('Upstream', throughput: 5.0)
+      allow(host).to receive(:throughput).and_return(10.0)
+      expect(host.bottleneck?).to be false
+
+      host.input = instance_double('Upstream', throughput: 10.0)
+      allow(host).to receive(:throughput).and_return(10.0)
+      expect(host.bottleneck?).to be false
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Ensure our support files (including a stub for `gloox`) are available to `require`.
+$LOAD_PATH.unshift File.expand_path('support', __dir__)
+
+# Provide a minimal `symbolize_keys` to match expectations in the library if it's not available.
+unless {}.respond_to?(:symbolize_keys)
+  class Hash
+    def symbolize_keys
+      each_with_object({}) do |(k, v), h|
+        h[(k.is_a?(String) ? k.to_sym : k)] = v
+      end
+    end
+  end
+end
+
+require 'rspec'
+require 'faymora'
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+end

data/spec/support/gloox/node.rb

@@ -0,0 +1,21 @@
+# Minimal stub for `require 'gloox/node'` used by Faymora::Node
+module GlooX
+  class Node
+    attr_reader :opts
+
+    def initialize(options = {})
+      # Mirror the `@opts` behavior used across the library
+      @opts = options.dup
+    end
+
+    # Provide a no-op start to satisfy Faymora::Node.start
+    def start
+      self
+    end
+
+    # Provide a basic url accessor used by .boot in specs (when not stubbed)
+    def url
+      @opts[:url]
+    end
+  end
+end

data/spec/support/gloox.rb

@@ -0,0 +1,12 @@
+# Minimal stub for the external `gloox` gem used by the library during specs.
+module GlooX
+  class Client
+    attr_reader :opts
+
+    def initialize(options = {})
+      # Store a dup so mutation outside won’t affect internals, and keep the
+      # exact semantics the library relies on: the ivar name is `@opts`.
+      @opts = options.dup
+    end
+  end
+end

data/spec/support/slotz.rb

@@ -0,0 +1,10 @@
+# Minimal stub for the external `slotz` gem used by the Provision module in specs.
+module Slotz
+  module Reservation
+    # Placeholder to be stubbed in specs. Keeping a default no-op implementation
+    # to avoid unexpected NameErrors when not explicitly stubbed.
+    def self.provision(_klass, _options = {})
+      :ok
+    end
+  end
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: faymora
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Tasos Laskos
+bindir: bin
+cert_chain: []
+date: 2026-01-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gloox
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ''
+email: tasos.laskos@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.md
+- README.md
+files:
+- Gemfile
+- LICENSE.md
+- README.md
+- faymora.gemspec
+- lib/faymora.rb
+- lib/faymora/client.rb
+- lib/faymora/connection.rb
+- lib/faymora/instance.rb
+- lib/faymora/item.rb
+- lib/faymora/link.rb
+- lib/faymora/node.rb
+- lib/faymora/provision.rb
+- lib/faymora/rectifier.rb
+- lib/faymora/rpc.rb
+- lib/faymora/service.rb
+- lib/faymora/throughput.rb
+- lib/faymora/version.rb
+- spec/faymora/client_spec.rb
+- spec/faymora/connection_spec.rb
+- spec/faymora/item_spec.rb
+- spec/faymora/link_spec.rb
+- spec/faymora/node_spec.rb
+- spec/faymora/provision_spec.rb
+- spec/faymora/rpc_spec.rb
+- spec/faymora/service_spec.rb
+- spec/faymora/throughput_spec.rb
+- spec/spec_helper.rb
+- spec/support/gloox.rb
+- spec/support/gloox/node.rb
+- spec/support/slotz.rb
+homepage: https://github.com/faymora/faymora
+licenses:
+- MPL v2
+metadata: {}
+rdoc_options:
+- "--charset=UTF-8"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: ''
+test_files:
+- spec/faymora/client_spec.rb
+- spec/faymora/connection_spec.rb
+- spec/faymora/item_spec.rb
+- spec/faymora/link_spec.rb
+- spec/faymora/node_spec.rb
+- spec/faymora/provision_spec.rb
+- spec/faymora/rpc_spec.rb
+- spec/faymora/service_spec.rb
+- spec/faymora/throughput_spec.rb
+- spec/spec_helper.rb
+- spec/support/gloox.rb
+- spec/support/gloox/node.rb
+- spec/support/slotz.rb