faymora 0.1

data/lib/faymora/link.rb

@@ -0,0 +1,55 @@
+module Faymora
+    module Link
+
+        BUFFER = []
+
+        def input( item )
+            item = Item.from_data( item )
+            item.passes ||= []
+
+            on_item item
+            nil
+        end
+
+        def output_to( other, propagate = true )
+            other   = Client.from_data( other )
+            @output = other
+            @output.input_from( self.client, false ){} if propagate
+            nil
+        end
+
+        def input_from( other, propagate = true )
+            other  = Client.from_data( other )
+            @input = other
+            @input.output_to( self.client, false ){} if propagate
+            nil
+        end
+
+        def has_output?
+            !!@output
+        end
+
+        def has_input?
+            !!@input
+        end
+
+        def forward( item )
+            return if !has_output?
+
+            item.passes << Item::Pass.new( path: self.class.to_s )
+
+            BUFFER << item
+            while !BUFFER.empty?
+                begin
+                    @output.input( BUFFER.pop ) {}
+                rescue => e
+                    ap e
+                    ap e.backtrace
+                    BUFFER << item if !BUFFER.include? item
+                end
+            end
+            nil
+        end
+    end
+
+end

data/lib/faymora/node.rb

@@ -0,0 +1,52 @@
+require 'gloox/node'
+
+module Faymora
+    class Node < GlooX::Node
+
+        class <<self
+
+            def when_ready( url, &block )
+                client = Faymora::Client.new(
+                  url: url,
+                  client_max_retries: 0,
+                  connection_pool_size: 1,
+                  handler: :node )
+
+                r = Raktr.new
+                r.run_in_thread
+                r.delay( 0.1 ) do |task|
+                    client.alive? do |r|
+                        if r.rpc_exception?
+                            r.delay( 0.1, &task )
+                            next
+                        end
+
+                        client.close
+                        block.call
+                    end
+                end
+            end
+
+            def connect( options = {} )
+                Faymora::Client.new(
+                  options.merge( handler: :node )
+                )
+            end
+
+            def boot( options = {} )
+                connect( url: start( options ).url )
+            end
+
+            def start( options = {} )
+                n = new( options )
+                n.start
+                n
+            end
+        end
+
+        def initialize( options = {} )
+            super( options.merge serializer: ::MessagePack )
+        end
+    end
+
+end

data/lib/faymora/provision.rb

@@ -0,0 +1,14 @@
+require 'slotz'
+
+module Faymora
+module Provision
+    include Slotz::Reservation
+
+    def self.included( other )
+        def other.provision( options = {} )
+            Slotz::Reservation.provision( self, options )
+        end
+    end
+
+end
+end

data/lib/faymora/rectifier.rb

@@ -0,0 +1,18 @@
+module Faymora
+    module Rectifier
+        # rectifies the bottleneck
+        def set_rectifier( rectifier )
+            @rectifier = rectifier
+            # use its output as input, keep the usual output for the process.
+        end
+
+        def rectifier
+            @rectifier ||= eXipno.spawn( :rectifier, self.client )
+        end
+
+        def rectify
+            rectifier.rectify
+        end
+    end
+
+end

data/lib/faymora/rpc.rb

@@ -0,0 +1,17 @@
+module Faymora
+    module RPC
+
+        def client
+            Client.new( url: self.url, handler: :instance )
+        end
+
+        def server
+            self
+        end
+
+        # @abstract
+        def node
+        end
+    end
+
+end

data/lib/faymora/service.rb

@@ -0,0 +1,59 @@
+module Faymora
+    module Service
+        include Link
+        include RPC
+        include Connection
+        include Throughput
+        # include Rectifier
+
+        # SHARE = Share.new( ARGUMENTS['peers'] )
+
+        def self.included( service )
+            def service.interested_in( &block )
+                @would_interest = block
+            end
+
+            def service.would_interest?( item )
+                return true if !@would_interest
+                @would_interest.call item
+            end
+
+            def service.upon( &block )
+                @upon = block
+            end
+
+            def service._upon
+                @upon
+            end
+        end
+
+        def join( &block )
+            block.call
+        end
+
+        def whereis?( name )
+            # find client for service by absolute path name. Ask Agent.
+        end
+
+        def process( item )
+            item = Item.from_data( item ) if !item.is_a?( Item )
+            return consume( item ) if interested?( item )
+            nil
+        end
+
+        # Interested in working on the item?
+        def interested?( item )
+            !!self.class.would_interest?( item )
+        end
+
+        def interested!( item )
+            item.interesting = true
+        end
+
+        def consume( item )
+            self.class._upon.call( item )
+        end
+
+    end
+
+end

data/lib/faymora/throughput.rb

@@ -0,0 +1,46 @@
+module Faymora
+    module Throughput
+        WARMED_UP_CLICKS = 50
+
+        def initialize(*)
+            super(*)
+            @clock_counter = 0
+        end
+
+        def throughput
+            return nil unless @click_counter && @click_counter >= WARMED_UP_CLICKS
+            return nil if @clock_counter.to_i <= 0
+
+            @click_counter.to_f / @clock_counter.to_f
+        end
+
+        def bottleneck?
+            return false unless has_input? && throughput
+
+            input_t = @input.throughput
+            return false unless input_t
+
+            input_t > throughput
+        end
+
+        def clock( item, &block )
+            @clock_item = Time.now
+            @clock_counter += 1
+
+            block.call item
+        ensure
+            click!( item )
+        end
+
+        def click!( item )
+            @clock_item = @clock_item.to_i
+            @click_counter ||= 0
+            @click_counter += 1
+
+            rectify if bottleneck?
+        ensure
+            GC.start
+        end
+    end
+
+end

data/lib/faymora/version.rb

@@ -0,0 +1,3 @@
+module Faymora
+    VERSION = '0.1'
+end

data/lib/faymora.rb

@@ -0,0 +1,17 @@
+require 'gloox'
+require 'msgpack'
+
+module Faymora
+    require_relative 'faymora/version'
+    require_relative 'faymora/provision'
+    require_relative 'faymora/item'
+    require_relative 'faymora/rpc'
+    require_relative 'faymora/connection'
+    require_relative 'faymora/rectifier'
+    require_relative 'faymora/instance'
+    require_relative 'faymora/client'
+    require_relative 'faymora/node'
+    require_relative 'faymora/link'
+    require_relative 'faymora/throughput'
+    require_relative 'faymora/service'
+end

data/spec/faymora/client_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+RSpec.describe Faymora::Client do
+  let(:options_string_keys) { { 'host' => 'example.org', 'port' => 5222, 'user' => 'alice' } }
+  let(:options) { { host: 'example.org', port: 5222, user: 'alice' } }
+
+  describe '#initialize' do
+    it 'inherits from GlooX::Client' do
+      expect(described_class < GlooX::Client).to be true
+      expect(described_class.new(options)).to be_a(GlooX::Client)
+    end
+
+    it 'symbolizes option keys and forces serializer to MessagePack' do
+      c = described_class.new(options_string_keys)
+      expect(c.opts).to include(options)
+      expect(c.opts[:serializer]).to be(MessagePack)
+    end
+
+    it 'overrides any provided serializer option' do
+      c = described_class.new(options.merge(serializer: :something_else))
+      expect(c.opts[:serializer]).to be(MessagePack)
+    end
+  end
+
+  describe '#to_data' do
+    it 'returns options without :serializer' do
+      c = described_class.new(options)
+      data = c.to_data
+      expect(data).to eq(options)
+      expect(data).not_to have_key(:serializer)
+    end
+  end
+
+  describe '#to_msgpack' do
+    it 'packs #to_data into MessagePack using a provided packer' do
+      c = described_class.new(options)
+      packer = MessagePack::Packer.new
+      c.to_msgpack(packer)
+      packed = packer.to_s
+      expect(MessagePack.unpack(packed).symbolize_keys).to eq(c.to_data)
+    end
+  end
+
+  describe '.from_data' do
+    it 'builds a client from Hash with string keys equivalent to symbolized options' do
+      c = described_class.from_data(options_string_keys)
+      expect(c).to be_a(described_class)
+      expect(c.to_data).to eq(options)
+    end
+
+    it 'builds a client from Hash with symbol keys as-is' do
+      c = described_class.from_data(options)
+      expect(c.to_data).to eq(options)
+    end
+  end
+end

data/spec/faymora/connection_spec.rb

@@ -0,0 +1,89 @@
+require 'spec_helper'
+
+RSpec.describe Faymora::Connection do
+  # Minimal harness including the module under test
+  class DummyConnection
+    include Faymora::Connection
+
+    attr_reader :forwarded, :clocked
+
+    def initialize
+      @forwarded = []
+      @clocked = []
+    end
+
+    def forward(item)
+      @forwarded << item
+      nil
+    end
+
+    # Simulate Throughput#clock without side effects; just yield the item
+    def clock(item)
+      @clocked << item
+      yield item if block_given?
+    end
+
+    # Allow tests to stub this
+    def process(item)
+      item
+    end
+  end
+
+  let(:conn) { DummyConnection.new }
+  let(:item) { Faymora::Item.new(foo: 'bar') }
+
+  describe '#on_item' do
+    context 'when passthrough? is true' do
+      it 'forwards the original item and returns nil' do
+        allow(conn).to receive(:passthrough?).with(item).and_return(true)
+
+        result = conn.on_item(item)
+
+        expect(conn.forwarded).to eq([item])
+        expect(result).to be_nil
+      end
+    end
+
+    context 'when passthrough? is false' do
+      before { allow(conn).to receive(:passthrough?).with(item).and_return(false) }
+
+      it 'calls clock with the item and processes it' do
+        expect(conn).to receive(:clock).with(item).and_call_original
+        expect(conn).to receive(:process).with(item).and_return(item)
+
+        conn.on_item(item)
+
+        expect(conn.clocked).to eq([item])
+      end
+
+      it 'forwards the result if process returns an Item' do
+        processed = Faymora::Item.new(baz: 1)
+        allow(conn).to receive(:process).and_return(processed)
+
+        result = conn.on_item(item)
+
+        expect(conn.forwarded).to eq([processed])
+        expect(result).to be_nil
+      end
+
+      it 'does not forward if process returns a non-Item' do
+        allow(conn).to receive(:process).and_return(:noop)
+
+        conn.on_item(item)
+
+        expect(conn.forwarded).to be_empty
+      end
+    end
+  end
+
+  describe '#on_error' do
+    it 'stores the error handler block' do
+      blk = proc { |e| :handled }
+      conn.on_error(&blk)
+
+      handler = conn.instance_variable_get(:@on_error)
+      expect(handler).to be_a(Proc)
+      expect(handler.call(StandardError.new)).to eq(:handled)
+    end
+  end
+end

data/spec/faymora/item_spec.rb

@@ -0,0 +1,80 @@
+require 'spec_helper'
+
+RSpec.describe Faymora::Item do
+  describe '.from_data' do
+    it 'converts passes (array of hashes) into Pass instances' do
+      data = { foo: 1, passes: [{ path: 'A' }, { path: 'B', extra: 2 }] }
+      item = described_class.from_data(data)
+
+      expect(item).to be_a(described_class)
+      expect(item.foo).to eq(1)
+      expect(item.passes).to all(be_a(Faymora::Item::Pass))
+      expect(item.passes.map(&:path)).to eq(%w[A B])
+      expect(item.passes.last.extra).to eq(2)
+    end
+
+    it 'handles missing passes key by creating an empty array' do
+      item = described_class.from_data(foo: 'bar')
+      expect(item.passes).to eq([])
+    end
+  end
+
+  describe '#to_msgpack' do
+    it 'packs all attributes including passes converted via Pass#to_msgpack' do
+      pass1 = Faymora::Item::Pass.new(path: 'X', n: 1)
+      pass2 = Faymora::Item::Pass.new(path: 'Y')
+      item = described_class.new(foo: 'bar', passes: [pass1, pass2])
+
+      packer = MessagePack::Packer.new
+      item.to_msgpack(packer)
+      packed = packer.to_s
+
+      unpacked = MessagePack.unpack(packed)
+      unpacked = unpacked.symbolize_keys if unpacked.respond_to?(:symbolize_keys)
+
+      expect(unpacked[:foo]).to eq('bar')
+      # Passes are stored as MessagePack-dumped strings
+      expect(unpacked[:passes]).to be_an(Array)
+      expect(unpacked[:passes].size).to eq(2)
+
+      # Validate the first pass payload decodes to the original hash
+      decoded_first = MessagePack.unpack(unpacked[:passes][0])
+      decoded_first = decoded_first.symbolize_keys if decoded_first.respond_to?(:symbolize_keys)
+      expect(decoded_first).to include(path: 'X', n: 1)
+
+      decoded_second = MessagePack.unpack(unpacked[:passes][1])
+      decoded_second = decoded_second.symbolize_keys if decoded_second.respond_to?(:symbolize_keys)
+      expect(decoded_second).to include(path: 'Y')
+    end
+
+    it 'works when passes is nil by treating it as empty' do
+      item = described_class.new(foo: 1, passes: nil)
+      packer = MessagePack::Packer.new
+      expect { item.to_msgpack(packer) }.not_to raise_error
+      unpacked = MessagePack.unpack(packer.to_s)
+      unpacked = unpacked.symbolize_keys if unpacked.respond_to?(:symbolize_keys)
+      expect(unpacked[:passes]).to eq([])
+    end
+  end
+
+  describe 'Pass' do
+    describe '.from_data' do
+      it 'builds a Pass from provided hash' do
+        pass = described_class::Pass.from_data(path: 'P', hop: 3)
+        expect(pass).to be_a(described_class::Pass)
+        expect(pass.path).to eq('P')
+        expect(pass.hop).to eq(3)
+      end
+    end
+
+    describe '#to_msgpack' do
+      it 'serializes the pass to MessagePack bytes' do
+        pass = described_class::Pass.new(path: 'Route', ok: true)
+        bytes = pass.to_msgpack
+        decoded = MessagePack.unpack(bytes)
+        decoded = decoded.symbolize_keys if decoded.respond_to?(:symbolize_keys)
+        expect(decoded).to eq({ path: 'Route', ok: true })
+      end
+    end
+  end
+end

data/spec/faymora/link_spec.rb

@@ -0,0 +1,140 @@
+require 'spec_helper'
+
+RSpec.describe Faymora::Link do
+  # A simple host class including the module under test
+  class DummyLink
+    include Faymora::Link
+
+    attr_reader :handled
+
+    def initialize(client)
+      @client_obj = client
+      @handled = []
+    end
+
+    def on_item(item)
+      @handled << item
+    end
+
+    def client
+      @client_obj
+    end
+  end
+
+  let(:self_client) { instance_double(Faymora::Client) }
+  let(:dummy) { DummyLink.new(self_client) }
+
+  before do
+    # Ensure the shared buffer does not bleed across examples
+    Faymora::Link::BUFFER.clear
+  end
+
+  describe '#input' do
+    it 'converts data to Item via Item.from_data, calls on_item, and returns nil' do
+      raw = { foo: 1 }
+      expect(Faymora::Item).to receive(:from_data).with(raw).and_call_original
+
+      result = dummy.input(raw)
+
+      expect(result).to be_nil
+      expect(dummy.handled.size).to eq(1)
+      expect(dummy.handled.first).to be_a(Faymora::Item)
+      expect(dummy.handled.first.foo).to eq(1)
+    end
+  end
+
+  describe '#output_to' do
+    let(:other_opts) { { host: 'h', port: 1 } }
+
+    it 'sets @output from Client.from_data and propagates to input_from by default' do
+      output_client = instance_double(Faymora::Link)
+      expect(Faymora::Client).to receive(:from_data).with(other_opts).and_return(output_client)
+      expect(output_client).to receive(:input_from).with(self_client, false)
+
+      expect(dummy.output_to(other_opts)).to be_nil
+      expect(dummy.has_output?).to be true
+    end
+
+    it 'does not propagate when propagate=false' do
+      output_client = instance_double(Faymora::Link)
+      expect(Faymora::Client).to receive(:from_data).with(other_opts).and_return(output_client)
+      expect(output_client).not_to receive(:input_from)
+
+      expect(dummy.output_to(other_opts, false)).to be_nil
+      expect(dummy.has_output?).to be true
+    end
+  end
+
+  describe '#input_from' do
+    let(:other_opts) { { host: 'h2', port: 2 } }
+
+    it 'sets @input from Client.from_data and propagates to output_to by default' do
+      input_client = instance_double(Faymora::Link)
+      expect(Faymora::Client).to receive(:from_data).with(other_opts).and_return(input_client)
+      expect(input_client).to receive(:output_to).with(self_client, false)
+
+      expect(dummy.input_from(other_opts)).to be_nil
+      expect(dummy.has_input?).to be true
+    end
+
+    it 'does not propagate when propagate=false' do
+      input_client = instance_double(Faymora::Link)
+      expect(Faymora::Client).to receive(:from_data).with(other_opts).and_return(input_client)
+      expect(input_client).not_to receive(:output_to)
+
+      expect(dummy.input_from(other_opts, false)).to be_nil
+      expect(dummy.has_input?).to be true
+    end
+  end
+
+  describe '#forward' do
+    let(:item) { Faymora::Item.new(data: 123) }
+
+    it 'is a no-op when there is no output' do
+      expect(dummy.has_output?).to be false
+      # Nothing should be enqueued after forward is attempted
+      dummy.forward(item)
+      expect(Faymora::Link::BUFFER).to be_empty
+    end
+
+    it 'sends item to @output.input and drains the buffer' do
+      output_client = instance_double(Faymora::Link)
+      allow(Faymora::Client).to receive(:from_data).and_return(output_client)
+      allow(output_client).to receive(:input_from)
+      dummy.output_to(host: 'h', port: 1)
+
+      expect(output_client).to receive(:input) do |arg, &blk|
+        expect(arg).to eq(item)
+        blk&.call # block is accepted but unused here
+      end
+
+      dummy.forward(item)
+      expect(Faymora::Link::BUFFER).to be_empty
+    end
+
+    it 'retries when @output.input raises once' do
+      # Provide Kernel.ap to avoid NameError from logging in rescue
+      unless Kernel.method_defined?(:ap)
+        module Kernel
+          def ap(*)
+          end
+        end
+      end
+
+      output_client = instance_double(Faymora::Link)
+      allow(Faymora::Client).to receive(:from_data).and_return(output_client)
+      allow(output_client).to receive(:input_from)
+      dummy.output_to(host: 'h', port: 1)
+
+      calls = 0
+      allow(output_client).to receive(:input) do |_arg|
+        calls += 1
+        raise 'boom' if calls == 1
+      end
+
+      dummy.forward(item)
+      expect(calls).to eq(2)
+      expect(Faymora::Link::BUFFER).to be_empty
+    end
+  end
+end