lex-node 0.2.0 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7a24355435f4062840c1a3a93f98da788c51103665bde303fa3c2ad1649889a
-  data.tar.gz: 152bb8170bf5c0176f45e268db29dd257d43839c9c7ea44f06f1da3d9a875bf6
+  metadata.gz: d0260fcda3e0a5469d3bfc8d7065d4870addf415732a693da58d979746dcf97b
+  data.tar.gz: 67a9e3e080786935fea85006e9623cae1aff3a0995d9e507ba37eb723ffff48b
 SHA512:
-  metadata.gz: 14ee4014b1699b58d51e866b30080247815d776c063cbee5764a1a1ee392d2d3a0cd2e34e41d573c9d804d74b5e67342f8641107eba2e6df840703a57f24e15e
-  data.tar.gz: 215ed3d105bbfa0af16ed2b3bc897019d54dd544f5368643e2256aa7649619c3d2e2da0ac0be2ba3f2813ea801a59400022d966dc7d8fa6645c51d01496eadd2
+  metadata.gz: 27d58631dc278eceb7988cc6125382e55babcac167e2df4a68b386d0b2ac47c8ece02b76f8333732e9d342659d2fc0cc159241fae86a7194a5490ec90be6d504
+  data.tar.gz: 886335964005f1f868d644c0b084a1a2e82991a9714e00a25154551864c6cf6b55d4d2aaf2d66edd4c9b9313cc1650b07589345c20dbdcb71e95ee815b247384

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.rubocop.yml

@@ -1,20 +1,50 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
 Layout/LineLength:
-  Max: 120
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
 Metrics/MethodLength:
-  Max: 30
+  Max: 50
+
 Metrics/ClassLength:
   Max: 1500
+
+Metrics/ModuleLength:
+  Max: 1500
+
 Metrics/BlockLength:
-  Max: 50
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
 Style/Documentation:
   Enabled: false
-AllCops:
-  TargetRubyVersion: 2.5
-  NewCops: enable
-  SuggestExtensions: false
+
+Style/SymbolArray:
+  Enabled: true
+
 Style/FrozenStringLiteralComment:
-  Enabled: false
+  Enabled: true
+  EnforcedStyle: always
+
 Naming/FileName:
   Enabled: false
-Style/ClassAndModuleChildren:
-  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [0.2.3] - 2026-03-16
+
+### Added
+- Beat message now includes `version` (Legion::VERSION), `metrics` (memory RSS, extension count, uptime), and `hosted_worker_ids` (active digital worker IDs on this node)
+- Platform-aware resource metrics collection (macOS `ps` vs Linux `/proc`)
+
+## [0.2.2] - 2026-03-16
+
+### Added
+- `update_gem` runner function for remote gem installation and reload
+- `update_settings` runner function for remote settings propagation
+- `UpdateResult` message class for publishing operation results
+
+## [0.2.1] - 2026-03-13
+
+### Added
+- Initial release

data/CLAUDE.md

@@ -0,0 +1,109 @@
+# lex-node: Node Identity and Cluster Management for LegionIO
+
+**Repository Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-core/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Core Legion Extension responsible for node identity within a LegionIO cluster. Handles heartbeat broadcasting, dynamic configuration distribution, cluster secret exchange, Vault token management, and RSA public key distribution between nodes.
+
+**GitHub**: https://github.com/LegionIO/lex-node
+**License**: MIT
+**Version**: 0.2.3
+
+## Architecture
+
+```
+Legion::Extensions::Node
+├── Actors/
+│   ├── Beat                # Periodic heartbeat broadcast
+│   ├── Crypt               # Cryptographic key exchange actor
+│   ├── PushKey             # Once actor: calls request_public_keys on startup
+│   ├── Vault               # Vault token lifecycle management
+│   └── VaultTokenRequest   # Once actor: calls 'request_token' on Vault runner (request_token delegates to request_vault_token)
+├── Runners/
+│   ├── Beat                # beat: publishes heartbeat message with node status
+│   ├── Crypt               # RSA key exchange: push_public_key, update_public_key,
+│   │                       #   delete_public_key, request_public_keys,
+│   │                       #   push_cluster_secret, request_cluster_secret,
+│   │                       #   receive_cluster_secret
+│   ├── Node                # Dynamic config and remote ops: message, update_settings,
+│   │                       #   update_gem, push_public_key, update_public_key,
+│   │                       #   push_cluster_secret, receive_cluster_secret,
+│   │                       #   receive_vault_token
+│   └── Vault               # Vault: request_token, request_vault_token,
+│                           #   receive_vault_token, push_vault_token
+├── Transport/
+│   ├── Exchanges/Node      # Node communication exchange
+│   ├── Queues/
+│   │   ├── Node            # node.<name> (exclusive, auto-delete, per-node)
+│   │   ├── Vault           # Vault token queue
+│   │   ├── Health          # Health check queue
+│   │   └── Crypt           # Encryption key exchange queue
+│   └── Messages/
+│       ├── Beat                  # Heartbeat message (routing_key: 'status', TTL 5s, includes metrics/worker_ids/version)
+│       ├── PublicKey             # Public key distribution
+│       ├── RequestPublicKeys     # Broadcast request for cluster public keys
+│       ├── PushClusterSecret     # Distribute encrypted cluster secret
+│       ├── RequestClusterSecret  # Request cluster secret from peer
+│       ├── RequestVaultToken     # Request Vault token from peer
+│       ├── PushVaultToken        # Distribute encrypted Vault token
+│       └── UpdateResult          # Operation result (update_gem / update_settings outcomes)
+└── DataTest/
+    └── Migrations/
+        ├── 001_nodes_table          # Core nodes table
+        ├── 002_node_history_table   # Node activity history
+        ├── 003_legion_version_colume # Legion version column (note: typo in filename)
+        └── 004_node_extensions      # Installed extensions per node
+```
+
+## Key Files
+
+| Path | Purpose |
+|------|---------|
+| `lib/legion/extensions/node.rb` | Entry point, extension registration |
+| `lib/legion/extensions/node/runners/beat.rb` | Heartbeat broadcasting |
+| `lib/legion/extensions/node/runners/crypt.rb` | RSA keypair and cluster secret exchange |
+| `lib/legion/extensions/node/runners/node.rb` | Dynamic config distribution, update_settings, update_gem, public key relay |
+| `lib/legion/extensions/node/runners/vault.rb` | Vault token request/receive/push lifecycle |
+| `lib/legion/extensions/node/transport/messages/beat.rb` | Heartbeat message (routing_key: 'status', TTL 5s) with resource metrics, hosted worker IDs, and Legion version |
+| `lib/legion/extensions/node/transport/messages/update_result.rb` | Operation result message for update_gem/update_settings |
+| `lib/legion/extensions/node/transport/messages/` | All node-to-node message types |
+| `lib/legion/extensions/node/transport/queues/node.rb` | Per-node queue (exclusive, auto-delete, classic type) |
+| `lib/legion/extensions/node/data_test/migrations/` | DB migrations |
+
+## Cluster Secret Exchange Flow
+
+1. Node starts, calls `request_public_keys` (broadcasts to all nodes)
+2. Nodes respond with `push_public_key` (RSA public key, base64-encoded)
+3. Node with cluster secret calls `push_cluster_secret`: encrypts secret with recipient's RSA public key, publishes to their queue
+4. Recipient calls `receive_cluster_secret`: decrypts with own private key, stores in settings
+
+## Vault Token Flow
+
+1. Node starts without Vault token; `VaultTokenRequest` (Once actor) calls `request_token`
+2. `request_token` checks `vault.enabled` and `vault.connected` before broadcasting `request_vault_token`
+3. Node with Vault token calls `push_vault_token`: encrypts token with recipient's RSA public key
+4. Recipient calls `receive_vault_token`: decrypts, stores token, calls `Legion::Crypt.connect_vault`
+
+## Remote Settings and Gem Updates
+
+`update_settings` and `update_gem` enable runtime cluster management without redeployment:
+
+- `update_settings(settings:, restart: false)` - Merges the provided hash into `Legion::Settings`. Nested hashes are merged key-by-key. Set `restart: true` to trigger `Legion.reload` after applying. Publishes `UpdateResult` with `action: 'update_settings'` and the merged key names.
+- `update_gem(extension:, version: nil, reload: true)` - Installs or upgrades a LEX gem (`lex-<name>`) via `Gem.install`. Set `reload: false` to skip `Legion.reload`. Publishes `UpdateResult` with `action: 'update_gem'` and the gem name/version.
+
+Both functions rescue `StandardError` and publish a failed `UpdateResult` on error. The `UpdateResult` message routes to `node.<name>.update_result` so callers can observe outcomes.
+
+## Testing
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Dockerfile

@@ -6,4 +6,4 @@ RUN apk update && apk add build-base tzdata gcc git
 
 COPY . ./
 RUN gem install lex-elastic_app_search --no-document --no-prerelease
-CMD ruby --jit $(which legionio)
+CMD ruby --yjit $(which legionio)

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 gemspec
 

data/Gemfile.lock

@@ -0,0 +1,87 @@
+PATH
+  remote: .
+  specs:
+    lex-node (0.2.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rspec_junit_formatter (0.6.0)
+      rspec-core (>= 2, < 4, != 2.12.0)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  lex-node!
+  rake
+  rspec
+  rspec_junit_formatter
+  rubocop
+  simplecov
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -1,9 +1,14 @@
-# Legion::Extensions::Node
+# lex-node
 
+Node identity and cluster management for [LegionIO](https://github.com/LegionIO/LegionIO). Handles heartbeat broadcasting, dynamic configuration distribution, cluster secret exchange, Vault token management, and RSA public key distribution between nodes.
+
+**Version**: 0.2.2
+
+This is a core LEX installed by default with LegionIO.
 
 ## Installation
 
-This LEX is installed into LegionIO by default. You can disable it with the following setting
+Installed automatically as a dependency of `legionio`. To disable:
 
 ```json
 {
@@ -15,10 +20,65 @@ This LEX is installed into LegionIO by default. You can disable it with the foll
 }
 ```
 
-## Usage
+## Runners
+
+### Beat
+
+Periodic heartbeat broadcast to the cluster.
+
+- `beat(status:)` - Publishes a heartbeat message with the node hostname, PID, timestamp, and status. Interval is controlled by the `beat_interval` setting.
+
+### Crypt
+
+RSA keypair and cluster secret exchange.
+
+- `push_public_key` - Broadcasts this node's RSA public key to all peers
+- `update_public_key(name:, public_key:)` - Stores a received public key in cluster settings
+- `delete_public_key(name:)` - Removes a stored public key from cluster settings
+- `request_public_keys` - Broadcasts a request for all nodes to send their public keys
+- `push_cluster_secret(public_key:, queue_name:)` - Encrypts the cluster secret with a peer's RSA public key and delivers it to their queue
+- `request_cluster_secret` - Requests the cluster secret from peers
+- `receive_cluster_secret(message:)` - Decrypts and stores the cluster secret received from a peer
+
+### Node
+
+Dynamic configuration distribution and node management.
+
+- `message(**hash)` - Merges arbitrary key/value pairs into `Legion::Settings` at runtime
+- `update_settings(settings:, restart: false)` - Merges a settings hash into `Legion::Settings`; optionally restarts Legion. Publishes an `UpdateResult` message on completion.
+- `update_gem(extension:, version: nil, reload: true)` - Installs or upgrades a LEX gem via `Gem.install`, then reloads Legion. Publishes an `UpdateResult` message on completion.
+- `push_public_key` - Broadcasts this node's RSA public key (raw string form)
+- `update_public_key(name:, public_key:)` - Stores a received public key in cluster settings
+- `push_cluster_secret(public_key:, queue_name:)` - Encrypts and delivers the cluster secret to a peer
+- `receive_cluster_secret(message:)` - Decrypts and stores the received cluster secret
+- `receive_vault_token(message:, routing_key:, public_key:)` - Delegates to the Vault runner
+
+### Vault
+
+Vault token lifecycle management.
+
+- `request_token` - Checks if Vault is enabled but not connected, then calls `request_vault_token`
+- `request_vault_token` - Broadcasts a request for a Vault token from peers
+- `receive_vault_token(message:)` - Decrypts the received Vault token, stores it, and calls `Legion::Crypt.connect_vault`
+- `push_vault_token(public_key:, node_name:)` - Encrypts the local Vault token with a peer's RSA public key and delivers it to their queue
+
+## How It Works
+
+Each node periodically calls `beat` to broadcast its presence. On startup, nodes exchange RSA public keys, then use them to securely distribute the cluster shared secret (AES encryption key) and Vault tokens - all encrypted peer-to-peer so no secrets traverse the bus in plaintext.
+
+Dynamic config changes (`update_settings`) and gem upgrades (`update_gem`) can be pushed to individual nodes or broadcast to all nodes at runtime. Both operations publish an `UpdateResult` message to `node.<name>.update_result` so the outcome can be observed cluster-wide.
+
+## Transport
+
+- **Exchange**: `node` (topic exchange)
+- **Queues**: `node.<name>` (node-specific, exclusive, auto-delete), `crypt`, `vault`, `health`
+- **Messages**: Beat, PublicKey, RequestPublicKeys, PushClusterSecret, RequestClusterSecret, RequestVaultToken, PushVaultToken, UpdateResult
+
+## Requirements
 
-This is used by default and you shouldn't have to do anything special to use it
+- Ruby >= 3.4
+- [LegionIO](https://github.com/LegionIO/LegionIO) framework
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT

data/docker_deploy.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 name = 'node'
 require "./lib/legion/extensions/#{name}/version"

data/lex-node.gemspec

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'lib/legion/extensions/node/version'
 
 Gem::Specification.new do |spec|
@@ -10,13 +12,14 @@ Gem::Specification.new do |spec|
   spec.description   = 'This lex is responsible for sending heartbeats, allowing for dynamic config, cluster secret, etc'
   spec.homepage      = 'https://github.com/LegionIO/lex-node'
   spec.license       = 'MIT'
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.5.0')
+  spec.required_ruby_version = '>= 3.4'
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/LegionIO/lex-node'
   spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-node'
   spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-node'
   spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-node/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }

data/lib/legion/extensions/node/actors/beat.rb

@@ -1,27 +1,35 @@
-module Legion::Extensions::Node::Actor
-  class Beat < Legion::Extensions::Actors::Every
-    def runner_function
-      'beat'
-    end
+# frozen_string_literal: true
 
-    def use_runner?
-      false
-    end
+module Legion
+  module Extensions
+    module Node
+      module Actor
+        class Beat < Legion::Extensions::Actors::Every
+          def runner_function
+            'beat'
+          end
 
-    def check_subtask?
-      false
-    end
+          def use_runner?
+            false
+          end
 
-    def generate_task?
-      false
-    end
+          def check_subtask?
+            false
+          end
 
-    def run_now?
-      true
-    end
+          def generate_task?
+            false
+          end
+
+          def run_now?
+            true
+          end
 
-    def time
-      settings['beat_interval']
+          def time
+            settings['beat_interval']
+          end
+        end
+      end
     end
   end
 end

data/lib/legion/extensions/node/actors/crypt.rb

@@ -1,7 +1,15 @@
-module Legion::Extensions::Node::Actor
-  class Crypt < Legion::Extensions::Actors::Subscription
-    def delay_start
-      2
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Node
+      module Actor
+        class Crypt < Legion::Extensions::Actors::Subscription
+          def delay_start
+            2
+          end
+        end
+      end
     end
   end
 end

data/lib/legion/extensions/node/actors/push_key.rb

@@ -1,27 +1,35 @@
-module Legion::Extensions::Node::Actor
-  class PushKey < Legion::Extensions::Actors::Once
-    def function
-      'request_public_keys'
-    end
+# frozen_string_literal: true
 
-    def runner_class
-      Legion::Extensions::Node::Runners::Crypt
-    end
+module Legion
+  module Extensions
+    module Node
+      module Actor
+        class PushKey < Legion::Extensions::Actors::Once
+          def function
+            'request_public_keys'
+          end
 
-    def disabled?
-      false
-    end
+          def runner_class
+            Legion::Extensions::Node::Runners::Crypt
+          end
 
-    def use_runner?
-      true
-    end
+          def disabled?
+            false
+          end
 
-    def check_subtask?
-      false
-    end
+          def use_runner?
+            true
+          end
+
+          def check_subtask?
+            false
+          end
 
-    def generate_task?
-      false
+          def generate_task?
+            false
+          end
+        end
+      end
     end
   end
 end

data/lib/legion/extensions/node/actors/vault.rb

@@ -1,27 +1,35 @@
-module Legion::Extensions::Node::Actor
-  class Vault < Legion::Extensions::Actors::Subscription
-    # def delay_start
-    #   2
-    # end
+# frozen_string_literal: true
 
-    def runner_class
-      Legion::Extensions::Node::Runners::Vault
-    end
+module Legion
+  module Extensions
+    module Node
+      module Actor
+        class Vault < Legion::Extensions::Actors::Subscription
+          # def delay_start
+          #   2
+          # end
 
-    def disabled?
-      false
-    end
+          def runner_class
+            Legion::Extensions::Node::Runners::Vault
+          end
 
-    def use_runner?
-      true
-    end
+          def disabled?
+            false
+          end
 
-    def check_subtask?
-      false
-    end
+          def use_runner?
+            true
+          end
+
+          def check_subtask?
+            false
+          end
 
-    def generate_task?
-      false
+          def generate_task?
+            false
+          end
+        end
+      end
     end
   end
 end