eaton 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42cf738c337ad3fae01953c5e78003e8ed0c789146ee7b71bacaf8f3162b98ae
-  data.tar.gz: 0ebf36ddf22c38dea0a216777f8b04fb5da841648cbc1ccc0e4a83a8f45427ff
+  metadata.gz: eb4213ff1de1459504fd9aef3ff717e711d4926dcc482af271a5ced054c4dd72
+  data.tar.gz: 5cb7bf81a8fc1cd3cba0d27407f352731bb49a07a22e210b87ddcd6fffe5eb9d
 SHA512:
-  metadata.gz: 5d342a6f0162da2fc073ccdb52f768a98daa7a6486b1c327c261b0a4b88e41c3d4d3763f55b02a14fb24e4393ff89d95f4d88f5c49ce728ad95c5fd78e98adbb
-  data.tar.gz: 26622a5ed0fcd33eb9249b25f92550b887f6844c528fd9641380782aabdbe3f4de5717020d6554d0212640b1aeffd6853963e6b3038c5757e3962e6245fbceed
+  metadata.gz: 5d64daf3ed46a838ee8e1b0b94501122af4b4124c1c9fe934fab670d504268ccf7809470690d69ce102d4ccfa5cde454e03b9f4585444d54b6ffbe1379d70a18
+  data.tar.gz: 8bb820f4d75d9149196d12da53af22e8b75dbd2521894c9b8cfa6d64d09976f0a72c1a35818553ce5a66203b9aa91d86596a486b915c2df9cd60de28c900a72a

data/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-09-10
+
+### Added
+- `Client#put` for settings writes; the client could only read, POST and DELETE
+- `Eaton::Network`, mixed into `Client`:
+  - `#ipv4` reports the address, mask, gateway and mode eth0 is running on
+  - `#set_ipv4(address:, subnet_mask:, gateway:)` switches eth0 to a static
+    address. All three are required and a blank one raises `ArgumentError`:
+    the PDU applies them together, and a wrong mask can leave it unreachable.
+
+### Improved
+- Enhanced authentication error handling for expired credentials
+- Added detailed password policy requirements in error messages
+- Improved user guidance for first-time login and password expiration scenarios
+- Error messages now include direct instructions for changing password via web interface
+
 ## [0.1.0] - 2025-01-20
 
 ### Added

data/README.md

@@ -176,29 +176,31 @@ client = Eaton::Client.new(
   verify_ssl: true
 )
 
-# Extend with power monitoring
-client.extend(Eaton::Power)
-
 # Get PDU info
-info = client.pdu_info
+info = client.info
 puts "#{info[:model]} - #{info[:serial_number]}"
 
 # Get overall power
-power = client.overall_power
+power = client.power
 puts "Current draw: #{power} watts"
 
 # Get active outlets
-outlets = client.outlet_power
+outlets = client.outlets
 outlets.select { |o| o[:watts] > 0 }.each do |outlet|
   puts "#{outlet[:name]}: #{outlet[:watts]}W"
 end
 
 # Get branch distribution
-branches = client.branch_power
+branches = client.branches
 branches.each do |branch|
   puts "#{branch[:name]}: #{branch[:current]}A @ #{branch[:voltage]}V"
 end
 
+# Get detailed metrics
+detailed = client.detailed
+puts "Power Factor: #{detailed[:overall][:power_factor]}"
+puts "Frequency: #{detailed[:overall][:frequency]} Hz"
+
 # Clean up
 client.logout
 ```

data/TODO.md

@@ -0,0 +1,81 @@
+# TODO
+
+## Future Enhancements
+
+### Programmatic Password Change (Issue #1)
+
+**Priority**: Medium
+**Context**: First-time login and password expiration handling
+
+**Problem**:
+Eaton PDUs enforce password expiration policies. When credentials expire, users currently must:
+1. Navigate to the PDU web interface
+2. Manually change the password
+3. Update credentials in their application
+
+This creates friction, especially for:
+- First-time setup (initial default password change)
+- Automated systems that need to handle password rotation
+- Multiple PDU management scenarios
+
+**Proposed Solution**:
+Add programmatic password change capability to the client:
+
+```ruby
+# Ruby API
+client = Eaton::Client.new(
+  host: 'pdu.example.com',
+  username: 'admin',
+  password: 'current_password'
+)
+
+client.change_password(new_password: 'NewSecurePass123!')
+
+# CLI
+eaton change-password \
+  --host pdu.example.com \
+  --username admin \
+  --current-password old_pass \
+  --new-password new_pass
+```
+
+**Implementation Requirements**:
+1. Research Eaton PDU API endpoint for password changes
+2. Implement `change_password` method in `Eaton::Client`
+3. Add password policy validation before attempting change
+4. Create CLI command `eaton change-password`
+5. Handle special case: changing expired credentials
+6. Add comprehensive error handling
+7. Update documentation with password management guide
+8. Add tests for password change functionality
+
+**API Research Needed**:
+- Identify correct REST endpoint (likely `/users/{id}` or `/accounts/{id}`)
+- Determine if special authentication is needed for expired credentials
+- Understand session requirements during password change
+- Check if password history/reuse policies are enforced
+
+**Security Considerations**:
+- Never log passwords
+- Clear old password from memory after use
+- Validate new password against policy before submitting
+- Handle authentication state correctly during transition
+- Consider secure input methods (no command-line password echo)
+
+**Testing Approach**:
+- Mock API responses for password change
+- Test policy validation
+- Test error scenarios (wrong current password, policy violations)
+- Integration test with real PDU (manual, not CI)
+
+**Documentation Updates**:
+- Add password management section to README
+- Include examples for both API and CLI
+- Document password policy requirements
+- Add troubleshooting guide for common scenarios
+
+**Related Files**:
+- `lib/eaton/client.rb` - Add change_password method
+- `lib/eaton/cli.rb` - Add CLI command
+- `spec/*` - Add test coverage
+- `README.md` - Update documentation

data/lib/eaton/cli.rb

@@ -16,7 +16,7 @@ module Eaton
     desc "power", "Get overall power consumption in watts"
     def power
       with_client do |client|
-        power = client.overall_power
+        power = client.power
         output_result("Overall Power", { watts: power })
       end
     end
@@ -24,7 +24,7 @@ module Eaton
     desc "outlets", "Get per-outlet power consumption"
     def outlets
       with_client do |client|
-        outlets = client.outlet_power
+        outlets = client.outlets
         # Filter out zero-power outlets in text mode
         if options[:format] == "text"
           outlets = outlets.select { |o| o[:watts] && o[:watts] > 0 }
@@ -36,7 +36,7 @@ module Eaton
     desc "detailed", "Get detailed power information"
     def detailed
       with_client do |client|
-        info = client.detailed_power_info
+        info = client.detailed
         # Filter outlets in text mode
         if options[:format] == "text" && info[:outlets]
           info[:outlets] = info[:outlets].select { |o| o[:watts] && o[:watts] > 0 }
@@ -48,7 +48,7 @@ module Eaton
     desc "branches", "Get power consumption per branch"
     def branches
       with_client do |client|
-        branches = client.branch_power
+        branches = client.branches
         # Filter out zero-current branches in text mode
         if options[:format] == "text"
           branches = branches.select { |b| b[:current] && b[:current] > 0 }
@@ -60,7 +60,7 @@ module Eaton
     desc "info", "Display PDU device information"
     def info
       with_client do |client|
-        info = client.pdu_info
+        info = client.info
         output_result("PDU Device Information", info)
       end
     end
@@ -88,9 +88,6 @@ module Eaton
           host_header: options[:host_header]
         )
 
-        # Mix in the Power module to add power monitoring methods
-        client.extend(Power)
-
         yield client
       rescue Client::AuthenticationError => e
         error("Authentication failed: #{e.message}")

data/lib/eaton/client.rb

@@ -10,6 +10,9 @@ module Eaton
     class AuthenticationError < StandardError; end
     class APIError < StandardError; end
 
+    include Power
+    include Network
+
     attr_reader :host, :username, :base_url
 
     def initialize(host:, username:, password:, port: 443, verify_ssl: false, host_header: nil)
@@ -37,7 +40,7 @@ module Eaton
         @session = data["session"]
         @token
       else
-        raise AuthenticationError, "Authentication failed: #{response.body}"
+        handle_auth_error(response)
       end
     rescue JSON::ParserError => e
       raise AuthenticationError, "Invalid response from server: #{e.message}"
@@ -66,6 +69,16 @@ module Eaton
       handle_response(execute_request(request))
     end
 
+    def put(path, data = {})
+      authenticate! unless authenticated?
+
+      request = Net::HTTP::Put.new("#{@base_path}#{path}")
+      add_auth_headers(request)
+      request.body = data.to_json
+
+      handle_response(execute_request(request))
+    end
+
     def logout
       return unless authenticated?
 
@@ -81,6 +94,65 @@ module Eaton
 
     private
 
+    def handle_auth_error(response)
+      begin
+        error_data = JSON.parse(response.body)
+
+        # Check for expired credentials error
+        if error_data["code"] == 112 && error_data["description"] =~ /expired/i
+          policy = parse_password_policy(error_data["args"])
+          message = build_expired_credentials_message(policy)
+          raise AuthenticationError, message
+        end
+      rescue JSON::ParserError
+        # Fall through to generic error
+      end
+
+      # Generic authentication error
+      raise AuthenticationError, "Authentication failed: #{response.body}"
+    end
+
+    def parse_password_policy(args)
+      return nil unless args && args.is_a?(Array) && args.length >= 7
+
+      {
+        min_length: args[0],
+        max_length: args[1],
+        require_uppercase: args[2] == 1,
+        require_lowercase: args[3] == 1,
+        require_numbers: args[4] == 1,
+        require_special: args[5] == 1,
+        special_chars: args[6]
+      }
+    end
+
+    def build_expired_credentials_message(policy)
+      message = "Credentials are expired. Please change the password via the PDU web interface.\n\n"
+
+      if policy
+        message += "Password requirements:\n"
+        message += "  - Length: #{policy[:min_length]}-#{policy[:max_length]} characters\n"
+
+        requirements = []
+        requirements << "uppercase letters" if policy[:require_uppercase]
+        requirements << "lowercase letters" if policy[:require_lowercase]
+        requirements << "numbers" if policy[:require_numbers]
+        requirements << "special characters" if policy[:require_special]
+
+        message += "  - Must include: #{requirements.join(', ')}\n" if requirements.any?
+        message += "  - Allowed special characters: #{policy[:special_chars]}\n" if policy[:special_chars]
+        message += "\n"
+      end
+
+      message += "To change password:\n"
+      message += "  1. Navigate to https://#{@host}#{@port == 443 ? '' : ":#{@port}"}\n"
+      message += "  2. Log in with current credentials\n"
+      message += "  3. Follow prompts to change password\n"
+      message += "\nNote: First-time login may require password change before API access is granted."
+
+      message
+    end
+
     def http_connection
       @http_connection ||= begin
         http = Net::HTTP.new(@host, @port)

data/lib/eaton/network.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Eaton
+  # eth0 addressing on the PDU's network management card.
+  module Network
+    ETH0_PATH = "/managers/1/networkService/networkInterfaces/eth0"
+
+    # Current eth0 addressing. :mode is "dhcp client" or "manual"; the address,
+    # subnet_mask and gateway are what the interface is running on right now,
+    # which is what DHCP handed it when the mode is dhcp.
+    def ipv4
+      data = get(ETH0_PATH)
+
+      {
+        mode: data.dig("ipv4", "settings", "mode"),
+        address: data.dig("ipv4", "status", "address"),
+        subnet_mask: data.dig("ipv4", "status", "subnetMask"),
+        gateway: data.dig("ipv4", "status", "gateway")
+      }
+    end
+
+    # Switch eth0 to a static address. All three values are required: the PDU
+    # applies them together, and a wrong mask strands it on the wrong subnet.
+    def set_ipv4(address:, subnet_mask:, gateway:)
+      raise ArgumentError, "address, subnet_mask and gateway are all required" if
+        [address, subnet_mask, gateway].any? { |v| v.to_s.strip.empty? }
+
+      put(ETH0_PATH, ipv4: {
+        settings: {
+          enabled: true,
+          mode: "manual",
+          manual: { address: address, subnetMask: subnet_mask, gateway: gateway }
+        }
+      })
+    end
+  end
+end

data/lib/eaton/power.rb

@@ -4,14 +4,14 @@ module Eaton
   module Power
     # Get overall power consumption for the PDU
     # Returns power in watts
-    def overall_power
+    def power
       data = get("/powerDistributions/1/inputs/1")
       data.dig("measures", "activePower")
     end
 
     # Get per-outlet power consumption
     # Returns an array of hashes with outlet info and power in watts
-    def outlet_power
+    def outlets
       # Get list of outlets
       outlets_list = get("/powerDistributions/1/outlets")
       member_count = outlets_list["members@count"] || 0
@@ -41,7 +41,7 @@ module Eaton
     end
 
     # Get detailed power information including voltage, current, and power factor
-    def detailed_power_info
+    def detailed
       input_data = get("/powerDistributions/1/inputs/1")
 
       {
@@ -55,13 +55,13 @@ module Eaton
           cumulated_energy: input_data.dig("measures", "cumulatedEnergy"),
           partial_energy: input_data.dig("measures", "partialEnergy")
         },
-        outlets: outlet_power
+        outlets: outlets
       }
     end
 
     # Get branch power information
     # Returns an array of branch power data
-    def branch_power
+    def branches
       branches_list = get("/powerDistributions/1/branches")
       member_count = branches_list["members@count"] || 0
 
@@ -87,7 +87,7 @@ module Eaton
     end
 
     # Get PDU information
-    def pdu_info
+    def info
       data = get("/powerDistributions/1")
 
       {

data/lib/eaton/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Eaton
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/eaton.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 require_relative "eaton/version"
-require_relative "eaton/client"
 require_relative "eaton/power"
+require_relative "eaton/network"
+require_relative "eaton/client"
 require_relative "eaton/cli"
 
 module Eaton

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: eaton
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jonathan Siegel
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-19 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -29,7 +28,7 @@ description: Comprehensive power monitoring and management for Eaton Rack PDU G4
   detailed metrics (voltage, current, power factor), OAuth2 authentication, and SSH
   tunneling support.
 email:
-- jonathan@example.com
+- "<248302+usiegj00@users.noreply.github.com>"
 executables:
 - eaton
 extensions: []
@@ -39,10 +38,12 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- TODO.md
 - exe/eaton
 - lib/eaton.rb
 - lib/eaton/cli.rb
 - lib/eaton/client.rb
+- lib/eaton/network.rb
 - lib/eaton/power.rb
 - lib/eaton/version.rb
 - sig/pdu_manager.rbs
@@ -55,7 +56,6 @@ metadata:
   bug_tracker_uri: https://github.com/usiegj00/eaton/issues
   changelog_uri: https://github.com/usiegj00/eaton/blob/main/CHANGELOG.md
   documentation_uri: https://github.com/usiegj00/eaton
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -70,8 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby gem and CLI for managing Eaton Rack PDU G4 devices via REST API
 test_files: []