eryph-compute 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b325ab23bab7159f9739f2ca245c2c9610643d5cd80aeba5471b0a9ddda30596
+  data.tar.gz: 532c3c97b205016b2135d539950e74b2889ee8cd5b6dd1e362a7ef77cc26b036
+SHA512:
+  metadata.gz: 631697c5902ab1f3c954b31d9b3ee9c12615b63b0373e54386b3236d018fdbebc08d28c2ee2e36058a250f858c6b9eb6f67ccc8ce60082126dd857dbf8e721ea
+  data.tar.gz: 04e0985c3d88904066af5a635338bc40a2a3405b6f9ed9e73b03457000a4566c8456a5beab01396ed03b7fe9436afbc26bf4be1ebcddbebf6526f5d0487c965e

data/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to the Eryph Ruby client libraries 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).
+
+## [Unreleased]
+
+### Added
+- Initial release of Eryph Ruby compute client
+- OAuth2 authentication with JWT support
+- **Automatic credential discovery** - Tries multiple configurations (default → zero → local) without requiring explicit config name
+- **Client ID-based discovery** - Find specific client across all configurations
+- **Enhanced Client constructor** - Support for `client_id` parameter and automatic discovery
+- System client credential detection for eryph-zero
+- Complete Compute API coverage via OpenAPI generation
+- Configuration-based endpoint management
+- SSL/TLS configuration support
+- Comprehensive error handling and logging
+- **Cross-platform admin privilege detection** - Windows Administrator and Linux root support
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [0.1.0] - 2025-01-24
+
+### Added
+- Initial release of `eryph-clientruntime` gem with authentication and configuration management
+- Initial release of `eryph-compute` gem with complete Compute API coverage
+- Support for Windows DPAPI credential decryption
+- Automatic endpoint discovery from running eryph-zero instances
+- Generated API client with proper authentication
+- Monorepo structure with separate versioning for runtime and compute client using changesets
+- Examples and documentation for common usage patterns
+- Integration with @changesets/cli for version management
+- Automated version synchronization between NPM packages and Ruby gems
+
+[Unreleased]: https://github.com/eryph-org/ruby-client/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/eryph-org/ruby-client/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Eryph Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,144 @@
+# Eryph Ruby Client Libraries
+
+[![Gem Version](https://badge.fury.io/rb/eryph-compute.svg)](https://badge.fury.io/rb/eryph-compute)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Ruby client libraries for Eryph APIs with seamless OAuth2 authentication, automatic configuration discovery, and cross-platform support.
+
+## 🚀 Quick Start
+
+```ruby
+require 'eryph'
+
+# Automatic credential discovery - tries multiple configs in priority order  
+client = Eryph.compute_client  # Auto-discovers: default → zero → local
+
+# Or specify configuration/client explicitly
+# client = Eryph.compute_client('production')           # Specific config
+# client = Eryph.compute_client(client_id: 'my-app')    # Find client across all configs
+# client = Eryph.compute_client('zero', client_id: 'admin')  # Specific client in config
+
+# List your catlets
+catlets = client.catlets.catlets_list
+puts "Found #{catlets.value.length} catlets"
+
+# Validate a configuration  
+config = { name: 'my-app', parent: 'dbosoft/ubuntu-22.04/starter' }
+result = client.validate_catlet_config(config)
+puts result.is_valid ? '✅ Valid' : '❌ Invalid'
+```
+
+## 📦 Installation
+
+Add to your Gemfile:
+```ruby
+gem 'eryph-compute'
+```
+
+Or install directly:
+```bash
+gem install eryph-compute
+```
+
+## ✨ Features
+
+- **🔐 Zero-Config Authentication** - Automatic credential discovery from multiple sources
+- **🎯 eryph-zero Integration** - Auto-detects local development environments  
+- **🌍 Cross-Platform** - Windows, Linux, and macOS support
+- **🔄 Operation Tracking** - Real-time monitoring of long-running operations
+
+## 🏗️ Architecture 
+
+This is a **monorepo** containing multiple Ruby client libraries:
+
+| Gem | Description | Use Case |
+|-----|-------------|----------|
+| **`eryph-compute`** | Compute API client | Managing catlets, projects, resources |
+| **`eryph-clientruntime`** | Shared authentication runtime | Used by all Eryph clients |
+| **`eryph-identity`** | *Coming Soon* | User and role management |
+
+## 📚 Documentation
+
+### Getting Started
+- **[Installation & Setup](docs/guides/getting-started.md)** - Complete installation guide
+- **[Authentication](docs/guides/authentication.md)** - OAuth2 setup and configuration  
+- **[Configuration](docs/guides/configuration.md)** - Managing multiple environments
+
+### API Reference  
+- **[Ruby API Reference](docs/ruby-api/)** - High-level Ruby client documentation
+- **[REST API Reference](docs/api/)** - Complete OpenAPI specification
+- **[Code Examples](docs/examples/)** - Common usage patterns
+
+For detailed API endpoint documentation, see **[API Reference](docs/api/)** - complete REST API documentation with all endpoints, models, and examples.
+
+## 🔧 Configuration
+
+The client uses a hierarchical configuration system with automatic discovery:
+
+```bash
+# Priority order (highest to lowest):
+1. ./.eryph/{config}.config          # Project directory
+2. ~/.config/.eryph/{config}.config  # User directory (Unix)
+   %APPDATA%\.eryph\{config}.config  # User directory (Windows)  
+3. /etc/.eryph/{config}.config       # System directory (Unix)
+   %PROGRAMDATA%\.eryph\{config}.config # System directory (Windows)
+```
+
+**Configuration file example** (`.eryph/default.config`):
+```json
+{
+  "endpoints": {
+    "identity": "https://identity.mycompany.com",
+    "compute": "https://compute.mycompany.com"
+  },
+  "clients": [{
+    "id": "my-app-client",
+    "name": "My Application"
+  }],
+  "defaultClient": "my-app-client"
+}
+```
+
+## 🎯 Multiple Environments & Discovery
+
+```ruby
+# Automatic discovery (recommended - tries multiple configs)
+client = Eryph.compute_client  # Auto-discovers best available credentials
+
+# Specific configurations  
+prod_client = Eryph.compute_client('production')  # Production environment
+dev_client = Eryph.compute_client('zero')         # Local eryph-zero instance  
+
+# Client ID-based discovery (searches across all configurations)
+admin_client = Eryph.compute_client(client_id: 'admin-client')
+app_client = Eryph.compute_client(client_id: 'my-app-client')
+
+# Combined - specific client in specific config
+specific_client = Eryph.compute_client('production', client_id: 'backup-service')
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
+
+- Development setup with changeset management
+- Code style and testing requirements  
+- Pull request process
+- Release workflow
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support & Community
+
+- **[📖 Documentation](https://https://www.eryph.io/docs)** - Complete guides and API reference
+- **[🐛 Issue Tracker](https://github.com/eryph-org/ruby-client/issues)** - Bug reports and feature requests
+- **[💬 Discussions](https://github.com/eryph-org/eryph/discussions)** - Community support and questions  
+- **[🌐 Website](https://eryph.io)** - Learn more about Eryph
+
+---
+
+<div align="center">
+  <strong>Built with ❤️ by the Eryph Team</strong>
+</div>

data/eryph-clientruntime.gemspec

@@ -0,0 +1,42 @@
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+require 'eryph/clientruntime/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'eryph-clientruntime'
+  s.version     = Eryph::ClientRuntime::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Eryph Team']
+  s.email       = ['support@eryph.io']
+  s.homepage    = 'https://github.com/eryph-org/ruby-client'
+  s.summary     = 'Eryph Client Runtime for Ruby'
+  s.description = 'Authentication, configuration, and credential lookup runtime for Eryph Ruby client libraries'
+  s.license     = 'MIT'
+  s.required_ruby_version = '>= 2.7'
+
+  s.metadata = {
+    'bug_tracker_uri' => 'https://github.com/eryph-org/ruby-client/issues',
+    'changelog_uri' => 'https://github.com/eryph-org/ruby-client/blob/main/CHANGELOG.md',
+    'source_code_uri' => 'https://github.com/eryph-org/ruby-client',
+    'homepage_uri' => 'https://eryph.io',
+    'documentation_uri' => 'https://www.eryph.io/docs',
+    'rubygems_mfa_required' => 'true',
+  }
+
+  # Runtime dependencies
+  s.add_dependency 'jwt', '>= 2.0', '< 4.0'
+
+  # Development dependencies moved to Gemfile for better version management
+
+  # Specify files to include (only clientruntime files)
+  s.files = Dir[
+    'lib/eryph/clientruntime.rb',
+    'lib/eryph/clientruntime/**/*',
+    'README.md',
+    'CHANGELOG.md',
+    'LICENSE',
+    '*.gemspec'
+  ].select { |f| File.file?(f) }
+
+  s.executables = []
+  s.require_paths = ['lib']
+end

data/eryph-compute.gemspec

@@ -0,0 +1,44 @@
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+require 'eryph/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'eryph-compute'
+  s.version     = Eryph::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Eryph Team']
+  s.email       = ['support@eryph.io']
+  s.homepage    = 'https://github.com/eryph-org/ruby-client'
+  s.summary     = 'Ruby client for Eryph Compute API'
+  s.description = 'Official Ruby client library for the Eryph Compute API with OAuth2 authentication support'
+  s.license     = 'MIT'
+  s.required_ruby_version = '>= 2.7'
+
+  s.metadata = {
+    'bug_tracker_uri' => 'https://github.com/eryph-org/ruby-client/issues',
+    'changelog_uri' => 'https://github.com/eryph-org/ruby-client/blob/main/CHANGELOG.md',
+    'source_code_uri' => 'https://github.com/eryph-org/ruby-client',
+    'homepage_uri' => 'https://eryph.io',
+    'documentation_uri' => 'https://www.eryph.io/docs',
+    'rubygems_mfa_required' => 'true',
+  }
+
+  # Runtime dependencies
+  s.add_dependency 'eryph-clientruntime', '~> 0.1'
+  s.add_dependency 'faraday', '>= 1.0.1', '< 3.0'
+  s.add_dependency 'faraday-multipart', '~> 1.0'
+  s.add_dependency 'marcel', '~> 1.0'
+
+  # Development dependencies moved to Gemfile for better version management
+
+  # Specify files to include
+  s.files = Dir[
+    'lib/**/*',
+    'README.md',
+    'CHANGELOG.md',
+    'LICENSE',
+    '*.gemspec'
+  ].select { |f| File.file?(f) }
+
+  s.executables = []
+  s.require_paths = ['lib']
+end

data/lib/eryph/clientruntime/client_credentials_lookup.rb

@@ -0,0 +1,295 @@
+require 'openssl'
+require 'logger'
+
+module Eryph
+  module ClientRuntime
+    # Client credentials structure
+    # Holds the information needed for OAuth2 client credentials flow
+    class ClientCredentials
+      # @return [String] OAuth client ID
+      attr_reader :client_id
+
+      # @return [String] client name
+      attr_reader :client_name
+
+      # @return [OpenSSL::PKey::RSA] RSA private key for JWT signing
+      attr_reader :private_key
+
+      # @return [String] OAuth token endpoint URL
+      attr_reader :token_endpoint
+
+      # @return [String, nil] configuration name this client belongs to
+      attr_reader :configuration
+
+      # Initialize client credentials
+      # @param client_id [String] OAuth client ID
+      # @param client_name [String] client name
+      # @param private_key [OpenSSL::PKey::RSA, String] RSA private key
+      # @param token_endpoint [String] OAuth token endpoint URL
+      # @param configuration [String, nil] configuration name
+      def initialize(client_id:, client_name:, private_key:, token_endpoint:, configuration: nil)
+        raise ArgumentError, 'client_id cannot be nil or empty' if client_id.nil? || client_id.empty?
+        raise ArgumentError, 'token_endpoint cannot be nil or empty' if token_endpoint.nil? || token_endpoint.empty?
+
+        @client_id = client_id
+        @client_name = client_name
+        @private_key = parse_private_key(private_key)
+        @token_endpoint = token_endpoint
+        @configuration = configuration
+      end
+
+      private
+
+      def parse_private_key(key)
+        raise ArgumentError, 'private_key cannot be nil' if key.nil?
+
+        case key
+        when OpenSSL::PKey::RSA
+          key
+        when String
+          raise ArgumentError, 'private_key cannot be empty' if key.empty?
+
+          OpenSSL::PKey::RSA.new(key)
+        else
+          raise ArgumentError, 'private_key must be an RSA key or PEM string'
+        end
+      rescue OpenSSL::PKey::RSAError => e
+        raise ArgumentError, "Invalid RSA private key: #{e.message}"
+      end
+    end
+
+    # Looks up client credentials from configuration stores
+    # Supports automatic discovery across multiple configurations like .NET implementation
+    class ClientCredentialsLookup
+      # @return [ConfigStoresReader] configuration stores reader
+      attr_reader :reader
+
+      # @return [String, nil] configuration name for specific lookups
+      attr_reader :config_name
+
+      # @return [Logger] logger instance
+      attr_reader :logger
+
+      # Initialize the credentials lookup
+      # @param reader [ConfigStoresReader] configuration stores reader
+      # @param config_name [String, nil] configuration name for specific lookup, nil for automatic discovery
+      # @param logger [Logger, nil] logger instance
+      def initialize(reader, config_name = nil, logger: nil)
+        @reader = reader
+        @config_name = config_name
+        @logger = logger || Logger.new($stdout).tap { |l| l.level = Logger::WARN }
+      end
+
+      # Find and return client credentials
+      # Uses automatic discovery if no config_name specified, otherwise looks in specific config
+      # @return [ClientCredentials] the discovered credentials
+      # @raise [CredentialsNotFoundError, NoUserCredentialsError] if credentials cannot be found
+      def find_credentials
+        @logger.debug("find_credentials: config=#{@config_name || 'auto'}")
+
+        if @config_name
+          # Find default client in specific config
+          creds = get_default_credentials(@config_name)
+          @logger.debug("find_credentials: default_client=#{creds ? 'found' : 'nil'}")
+
+          # For zero/local config, try system client as fallback
+          if !creds && %w[zero local].include?(@config_name)
+            @logger.debug('find_credentials: trying system_client fallback')
+            creds = get_system_client_credentials(@config_name)
+            @logger.debug("find_credentials: system_client=#{creds ? 'found' : 'nil'}")
+          end
+
+          @logger.debug("find_credentials: result=#{creds ? creds.client_id : 'nil'}")
+          raise CredentialsNotFoundError, "No default client found in configuration '#{@config_name}'" unless creds
+
+          creds
+        else
+          # Automatic discovery across multiple configs
+          configs = @reader.environment.windows? ? %w[default zero local] : %w[default local]
+          @logger.debug("find_credentials: auto_discovery configs=#{configs.join(',')}")
+          find_credentials_in_configs(*configs)
+        end
+      end
+
+      # Try multiple configurations in order
+      # @param config_names [Array<String>] configuration names to try
+      # @return [ClientCredentials] first credentials found
+      # @raise [NoUserCredentialsError] if no credentials found in any config
+      def find_credentials_in_configs(*config_names)
+        @logger.debug("find_credentials_in_configs: trying #{config_names.join(',')}")
+
+        config_names.each do |config_name|
+          @logger.debug("find_credentials_in_configs: checking config=#{config_name}")
+
+          # Try default client first
+          creds = get_default_credentials(config_name)
+          if creds
+            @logger.debug("find_credentials_in_configs: found default in #{config_name}")
+            return creds
+          end
+
+          # Try system client for zero/local configs
+          next unless %w[zero local].include?(config_name)
+
+          @logger.debug("find_credentials_in_configs: trying system client for #{config_name}")
+          creds = get_system_client_credentials(config_name)
+          if creds
+            @logger.debug("find_credentials_in_configs: found system client in #{config_name}")
+            return creds
+          end
+        end
+
+        @logger.debug('find_credentials_in_configs: no credentials found in any config')
+        raise NoUserCredentialsError, 'No credentials found. Please configure an eryph client.'
+      end
+
+      # Get default client credentials from specific configuration
+      # @param config_name [String] configuration name
+      # @return [ClientCredentials, nil] credentials if found, nil otherwise
+      def get_default_credentials(config_name)
+        @logger.debug("get_default_credentials: config=#{config_name}")
+
+        client = @reader.get_default_client(config_name)
+        @logger.debug("get_default_credentials: client=#{client ? client['id'] : 'nil'}")
+        return nil unless client
+
+        creds = build_credentials(client, config_name)
+        @logger.debug("get_default_credentials: build_result=#{creds ? 'success' : 'failed'}")
+        creds
+      end
+
+      # Get credentials by client ID from specific configuration
+      # @param client_id [String] client ID to find
+      # @param config_name [String] configuration name to search in
+      # @return [ClientCredentials, nil] credentials if found, nil otherwise
+      def get_credentials_by_client_id(client_id, config_name = 'default')
+        # Handle system-client specially
+        if client_id == 'system-client'
+          return get_system_client_credentials(config_name)
+        end
+
+        client = @reader.get_client(config_name, client_id)
+        return nil unless client
+
+        build_credentials(client, config_name)
+      end
+
+      # Get credentials by client name from specific configuration
+      # @param client_name [String] client name to find
+      # @param config_name [String] configuration name to search in
+      # @return [ClientCredentials, nil] credentials if found, nil otherwise
+      def get_credentials_by_client_name(client_name, config_name = 'default')
+        # Search through all clients to find by name
+        all_clients = @reader.get_all_clients(config_name)
+        client = all_clients.find { |c| c['name'] == client_name }
+        return nil unless client
+
+        build_credentials(client, config_name)
+      end
+
+      # Get system client credentials for zero/local configurations
+      # @param config_name [String] configuration name ('zero' or 'local')
+      # @return [ClientCredentials, nil] system credentials if available, nil otherwise
+      # @raise [NoUserCredentialsError] if system client available but requires admin privileges
+      def get_system_client_credentials(config_name = 'local')
+        @logger.debug("get_system_client_credentials: config=#{config_name}")
+
+        unless %w[zero local].include?(config_name)
+          @logger.debug('get_system_client_credentials: invalid config')
+          return nil
+        end
+
+        unless @reader.environment.windows? || @reader.environment.linux?
+          @logger.debug('get_system_client_credentials: unsupported platform')
+          return nil
+        end
+
+        # Zero config only supported on Windows
+        if config_name == 'zero' && !@reader.environment.windows?
+          @logger.debug('get_system_client_credentials: zero config not supported on non-Windows')
+          return nil
+        end
+
+        # Check admin privileges on Windows
+        if @reader.environment.windows? && !@reader.environment.admin_user?
+          @logger.debug('get_system_client_credentials: Windows admin required')
+          raise NoUserCredentialsError,
+                'No user credentials found. System client is available but requires Administrator privileges. ' \
+                'Please run as Administrator (Windows) or root (Linux) to use system client.'
+        end
+
+        # Check root privileges on Linux
+        if @reader.environment.linux? && !@reader.environment.admin_user?
+          @logger.debug('get_system_client_credentials: Linux root required')
+          raise NoUserCredentialsError,
+                'No user credentials found. System client is available but requires root privileges. ' \
+                'Please run as root to use system client.'
+        end
+
+        provider_info = LocalIdentityProviderInfo.new(@reader.environment, config_name, logger: @logger)
+        provider_running = provider_info.running?
+        @logger.debug("get_system_client_credentials: provider_running=#{provider_running}")
+
+        return nil unless provider_running
+
+        system_creds = provider_info.system_client_credentials
+        @logger.debug("get_system_client_credentials: system_creds=#{system_creds ? 'found' : 'nil'}")
+        return nil unless system_creds
+
+        @logger.debug("get_system_client_credentials: creating credentials for #{system_creds['id']}")
+
+        ClientCredentials.new(
+          client_id: system_creds['id'],
+          client_name: 'system-client',
+          private_key: system_creds['private_key'],
+          token_endpoint: "#{system_creds['identity_endpoint']}/connect/token",
+          configuration: config_name
+        )
+      end
+
+      # Test if credentials are available
+      # @return [Boolean] true if credentials can be found
+      def credentials_available?
+        find_credentials
+        true
+      rescue CredentialsNotFoundError, NoUserCredentialsError
+        false
+      end
+
+      private
+
+      # Build credentials object from client data and config
+      # @param client [Hash] client data from configuration
+      # @param config_name [String] configuration name
+      # @return [ClientCredentials, nil] built credentials or nil if invalid
+      def build_credentials(client, config_name)
+        private_key = @reader.get_client_private_key(client)
+        return nil unless private_key
+
+        token_endpoint = get_token_endpoint(config_name)
+        return nil unless token_endpoint
+
+        ClientCredentials.new(
+          client_id: client['id'],
+          client_name: client['name'] || client['id'],
+          private_key: private_key,
+          token_endpoint: token_endpoint,
+          configuration: config_name
+        )
+      rescue ArgumentError
+        nil
+      end
+
+      # Get token endpoint for configuration
+      # @param config_name [String] configuration name
+      # @return [String, nil] token endpoint URL or nil if not found
+      def get_token_endpoint(config_name)
+        endpoint_lookup = EndpointLookup.new(@reader, config_name, logger: @logger)
+        identity_url = endpoint_lookup.endpoint('identity')
+        return nil unless identity_url
+
+        "#{identity_url.chomp('/')}/connect/token"
+      end
+    end
+  end
+end