legion-transport 1.2.2 → 1.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b44d9bbca572702bcfe3d8f37f5ff0330b9e2fd5626d3a094bf32219470fb457
-  data.tar.gz: 36521e18cfe03a26403538bc1001d5f6b0203219c50b466447eae5f00bfaeec4
+  metadata.gz: 5df8a97c0a9116b6e6882820661a69e91708c578511526752fa69aca081c688e
+  data.tar.gz: 3407435e75ef5ddae5a9dd5c68d8b3b755541b98345909edfb13dae0cfa6112f
 SHA512:
-  metadata.gz: 131abad2f93409e13ed874eedf04f0014f61b89fa0d953449ad8747076ae48841e9a8a30a37174086e4cfc37a08fd039410d88d9b74c16b4eb81b7dca865798d
-  data.tar.gz: cbead836289a7df9f8fdc44d9e157fc86874b63795b587f2c27ecf4dd2cdeab8b8b3820fb6905086ca9e80af5dded515df51b77eb7e675c5bc9b0c8779b12718
+  metadata.gz: a9869f1963d7c939cc2ecfa27a49b15f60c4fee20dce78818040e9813f4b81a31352704e99e152b390d8578e09ac462a0dd84903fba45599c3386e1707c2d7ff
+  data.tar.gz: 950098bfa689097417cad4ee2fb4395b0e2b6793127d3ac04a654254038f7ff9afc3cc91663d01b19f206ea29d6c751ea65843b35b7416bda881047378c40333

data/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Legion::Transport ChangeLog
 
-## [Unreleased]
+## [1.2.4] - 2026-03-20
+
+### Fixed
+- Add `logger` gem as runtime dependency for Ruby 4.0 compatibility (extracted from stdlib)
+- Disable DNS bootstrap in test environment to prevent `NameError` from legion-settings 1.3.5
+
+## [1.2.3] - 2026-03-19
+
+### Added
+- `Legion::Transport::Spool` JSONL disk buffer for offline message persistence when AMQP is unavailable
+- Automatic spool intercept on `Message#publish` Bunny connection errors with configurable limits
+- Spool drain reads oldest-first with file rotation and stale eviction (72hr TTL, 10MB/file, 500MB total, 100 files max)
 
 ## [1.2.2] - 2026-03-17
 

data/CLAUDE.md

@@ -8,6 +8,7 @@
 Ruby gem that manages the connection between LegionIO and its FIFO queue system (RabbitMQ over AMQP 0.9.1). Provides abstractions for exchanges, queues, messages, and consumers with thread-safe connection management.
 
 **GitHub**: https://github.com/LegionIO/legion-transport
+**Version**: 1.2.3
 **License**: Apache-2.0
 
 ## Architecture
@@ -20,13 +21,15 @@ Legion::Transport
 ├── Exchange            # Base exchange class (extends Bunny::Exchange)
 │   └── Exchanges/
 │       ├── Task        # Task routing exchange
-│       ├── Node        # Node communication exchange
+│       ├── Node        # Node communication exchange (infrastructure: swarms, services, heartbeats)
+│       ├── Agent       # Agent communication exchange (identity-bound: GAIA frames, preferences, proactive)
 │       ├── Crypt       # Encryption exchange
 │       ├── Extensions  # Extension exchange
 │       └── Lex         # LEX exchange (inherits Extensions)
 ├── Queue               # Base queue class (extends Bunny::Queue)
 │   └── Queues/
 │       ├── Node        # Node queue
+│       ├── Agent       # Per-agent queue (auto-delete, routing key: agent.<agent_id>)
 │       ├── NodeCrypt   # Node encryption queue
 │       ├── NodeStatus  # Node status queue
 │       ├── TaskLog     # Task logging queue
@@ -44,8 +47,9 @@ Legion::Transport
 ├── Consumer            # AMQP consumer with auto-generated tags
 ├── Common              # Shared utilities (channel mgmt, options merging, consumer tags)
 ├── Local               # In-memory pub/sub for local development mode (no RabbitMQ)
+├── Spool               # Disk-backed message buffer: persist messages when RabbitMQ unavailable, replay on reconnect
 ├── Settings            # Default configuration with env var overrides
-└── Version             # 1.2.1
+└── Version             # 1.2.3
 ```
 
 ## Key Design Patterns
@@ -106,13 +110,33 @@ Vault integration: If `Legion::Settings[:crypt][:vault][:connected]` is true, cr
 | `lib/legion/transport/connection/vault.rb` | Vault PKI integration (stub) |
 | `lib/legion/transport/common.rb` | Shared module (channel access, deep_merge, consumer tags) |
 | `lib/legion/transport/exchange.rb` | Base Exchange class |
+| `lib/legion/transport/exchanges/agent.rb` | Agent exchange for identity-bound communication |
 | `lib/legion/transport/queue.rb` | Base Queue class |
+| `lib/legion/transport/queues/agent.rb` | Per-agent queue (auto-delete, keyed by agent_id) |
 | `lib/legion/transport/message.rb` | Base Message class with publish/encode/encrypt |
 | `lib/legion/transport/consumer.rb` | AMQP consumer wrapper |
+| `lib/legion/transport/spool.rb` | Disk-backed message buffer (~/.legionio/spool, 10MB/file, 500MB total, 3-day TTL) |
 | `lib/legion/transport/settings.rb` | Default config, env var loading, Vault cred fetch |
 | `lib/legion/transport/version.rb` | Version constant |
 | `spec/` | RSpec test suite |
 
+## Node vs Agent Exchange
+
+Two identity-scoped exchanges separate infrastructure traffic from agent-bound traffic:
+
+| Exchange | Routing Key Pattern | Use Case |
+|----------|-------------------|----------|
+| `node` | `node.<fqdn/nodename>` | Infrastructure: swarm coordination, service heartbeats, non-identity traffic |
+| `agent` | `agent.<agent_id>` | Identity-bound: GAIA cognitive frames, preference queries, proactive messages |
+
+**Agent queue defaults** differ from standard queues:
+- `durable: false` — agent queues are ephemeral (recreated on connect)
+- `auto_delete: true` — cleaned up when the agent disconnects
+- Dead letter exchange: `agent.dlx`
+- Agent ID defaults to `Legion::Settings['client']['name']` if not provided
+
+The `agent` exchange is used by `legion-gaia` for inbound cognitive frames (replacing the former `gaia` exchange routing) and by `lex-mesh` for async preference queries via `reply_to` + `correlation_id` RPC.
+
 ## Queue Defaults
 
 All queues are created with:
@@ -137,7 +161,7 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
-Spec count: 144 examples
+Spec count: 166 examples
 
 ---
 

data/README.md

@@ -2,6 +2,8 @@
 
 Legion::Transport is the Ruby gem responsible for connecting LegionIO to its FIFO queue system (RabbitMQ over AMQP 0.9.1). It provides thread-safe connection management, exchange/queue abstractions, message publishing with optional encryption, and consumer wrappers.
 
+**Version**: 1.2.3
+
 ## Features
 
 - Thread-safe connection management using `concurrent-ruby`
@@ -11,6 +13,7 @@ Legion::Transport is the Ruby gem responsible for connecting LegionIO to its FIF
 - Dynamic credential retrieval from HashiCorp Vault
 - Auto-recovery on connection loss
 - Dead letter exchange support
+- Spool buffer for disk-backed message persistence when RabbitMQ is unavailable
 
 ## Supported Ruby Versions
 
@@ -182,12 +185,6 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
-## Authors
-
-- [Matthew Iverson](https://github.com/Esity) - current maintainer
-
 ## License
 
-This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
-
-Copyright 2021 Esity
+Apache-2.0

data/legion-transport.gemspec

@@ -30,4 +30,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'concurrent-ruby', '>= 1.2'
   spec.add_dependency 'legion-json'
   spec.add_dependency 'legion-settings'
+  spec.add_dependency 'logger'
 end

data/lib/legion/transport/message.rb

@@ -27,6 +27,9 @@ module Legion
                               correlation_id:   correlation_id,
                               app_id:           app_id,
                               timestamp:        timestamp)
+      rescue Bunny::ConnectionClosedError, Bunny::ChannelAlreadyClosed, Bunny::ChannelError,
+             Bunny::NetworkErrorWrapper, IOError => e
+        spool_message(e)
       end
 
       def app_id
@@ -165,6 +168,28 @@ module Legion
       def channel
         Legion::Transport::Connection.channel
       end
+
+      private
+
+      def spool_message(error)
+        return unless defined?(Legion::Transport::Spool)
+
+        Legion::Transport::Spool.write(
+          exchange:    exchange_name_for_spool,
+          routing_key: routing_key || '',
+          payload:     message
+        )
+        Legion::Logging.debug { "Message spooled due to: #{error.message}" } if defined?(Legion::Logging)
+      rescue StandardError => e
+        Legion::Logging.warn { "Spool write failed: #{e.message}" } if defined?(Legion::Logging)
+      end
+
+      def exchange_name_for_spool
+        ex = exchange
+        ex.respond_to?(:name) ? ex.name : ex.to_s
+      rescue StandardError
+        self.class.name
+      end
     end
   end
 end

data/lib/legion/transport/spool.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'securerandom'
+
+module Legion
+  module Transport
+    module Spool
+      class << self
+        def setup(directory: nil, max_file_bytes: 10_485_760, max_total_bytes: 524_288_000,
+                  max_files: 100, max_age_seconds: 259_200)
+          @directory = directory || File.expand_path('~/.legionio/spool')
+          @max_file_bytes = max_file_bytes
+          @max_total_bytes = max_total_bytes
+          @max_files = max_files
+          @max_age_seconds = max_age_seconds
+          @current_file = nil
+          @mutex = Mutex.new
+
+          FileUtils.mkdir_p(@directory)
+        end
+
+        def write(exchange:, routing_key:, payload:)
+          setup unless @directory
+
+          @mutex.synchronize do
+            evict_oldest if over_limits?
+
+            line = Legion::JSON.dump({
+                                       exchange:    exchange,
+                                       routing_key: routing_key,
+                                       payload:     payload,
+                                       spooled_at:  Time.now.iso8601
+                                     })
+
+            file = current_file
+            File.open(file, 'a') { |f| f.puts(line) }
+
+            rotate_if_needed
+          end
+        rescue StandardError => e
+          Legion::Logging.warn { "Spool write failed: #{e.message}" } if defined?(Legion::Logging)
+        end
+
+        def drain
+          setup unless @directory
+
+          sorted_files.each do |file|
+            lines = File.readlines(file).map(&:strip).reject(&:empty?)
+            lines.each do |line|
+              msg = Legion::JSON.load(line)
+              yield(msg)
+            end
+            File.delete(file)
+          rescue StandardError => e
+            Legion::Logging.warn { "Spool drain error on #{file}: #{e.message}" } if defined?(Legion::Logging)
+            break
+          end
+        end
+
+        def count
+          setup unless @directory
+
+          sorted_files.sum do |file|
+            File.readlines(file).count { |l| !l.strip.empty? }
+          rescue StandardError
+            0
+          end
+        end
+
+        def evict_stale
+          setup unless @directory
+
+          cutoff = Time.now - @max_age_seconds
+          sorted_files.each do |file|
+            File.delete(file) if File.mtime(file) < cutoff
+          rescue StandardError
+            nil
+          end
+        end
+
+        def reset!
+          @directory = nil
+          @current_file = nil
+          @mutex = nil
+          @max_file_bytes = nil
+          @max_total_bytes = nil
+          @max_files = nil
+          @max_age_seconds = nil
+        end
+
+        attr_reader :max_file_bytes
+
+        private
+
+        def sorted_files
+          Dir.glob(File.join(@directory, '*.jsonl'))
+        end
+
+        def current_file
+          @current_file ||= new_file_path
+          @current_file = new_file_path unless File.exist?(@current_file)
+          @current_file
+        end
+
+        def new_file_path
+          File.join(@directory, "spool-#{Time.now.strftime('%Y%m%d%H%M%S')}-#{SecureRandom.hex(4)}.jsonl")
+        end
+
+        def rotate_if_needed
+          return unless File.exist?(@current_file) && File.size(@current_file) >= @max_file_bytes
+
+          @current_file = nil
+        end
+
+        def over_limits?
+          files = sorted_files
+          return true if files.size >= @max_files
+
+          total = files.sum do |f|
+            File.size(f)
+          rescue StandardError
+            0
+          end
+          total >= @max_total_bytes
+        end
+
+        def evict_oldest
+          files = sorted_files
+          while files.size >= @max_files
+            begin
+              File.delete(files.shift)
+            rescue StandardError
+              break
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/transport/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Transport
-    VERSION = '1.2.2'
+    VERSION = '1.2.4'
   end
 end

data/lib/legion/transport.rb

@@ -43,4 +43,5 @@ module Legion
   require_relative 'transport/queue'
   require_relative 'transport/exchange'
   require_relative 'transport/message'
+  require_relative 'transport/spool'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-transport
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.2.4
 platform: ruby
 authors:
 - Esity
@@ -65,6 +65,20 @@ dependencies:
     - - ">="
       - !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: The Gem to connect LegionIO and it's extensions to the transport tier
 email:
 - matthewdiverson@gmail.com
@@ -115,6 +129,7 @@ files:
 - lib/legion/transport/queues/task_log.rb
 - lib/legion/transport/queues/task_update.rb
 - lib/legion/transport/settings.rb
+- lib/legion/transport/spool.rb
 - lib/legion/transport/version.rb
 - sonar-project.properties
 homepage: https://github.com/LegionIO/legion-transport