kamal-dev 0.3.0

data/lib/kamal/providers/base.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Providers
+    # Custom exception hierarchy for provider errors
+    class ProvisioningError < StandardError; end
+    class TimeoutError < ProvisioningError; end
+    class QuotaExceededError < ProvisioningError; end
+    class AuthenticationError < StandardError; end
+    class RateLimitError < StandardError; end
+
+    # Factory method to instantiate the appropriate provider
+    #
+    # @param config [Hash] Provider configuration including type and credentials
+    # @option config [String] "type" Provider type (e.g., "upcloud")
+    # @option config [String] "username" Provider API username (provider-specific)
+    # @option config [String] "password" Provider API password (provider-specific)
+    #
+    # @return [Kamal::Providers::Base] Provider instance
+    #
+    # @raise [Kamal::Dev::ConfigurationError] if provider type is unknown
+    #
+    # @example
+    #   provider = Kamal::Providers.for({
+    #     "type" => "upcloud",
+    #     "username" => ENV["UPCLOUD_USERNAME"],
+    #     "password" => ENV["UPCLOUD_PASSWORD"]
+    #   })
+    def self.for(config)
+      type = config["type"] || config[:type]
+
+      case type&.to_s&.downcase
+      when "upcloud"
+        require_relative "upcloud" unless defined?(Upcloud)
+        Upcloud.new(
+          username: config["username"] || config[:username],
+          password: config["password"] || config[:password]
+        )
+      else
+        raise Kamal::Dev::ConfigurationError, "Unknown provider type: #{type.inspect}"
+      end
+    end
+
+    # Abstract base class defining the provider adapter interface
+    # All cloud provider implementations must inherit from this class
+    # and implement the required methods.
+    #
+    # Example implementation:
+    #   class MyProvider < Kamal::Providers::Base
+    #     def provision_vm(config)
+    #       # Implementation here
+    #     end
+    #   end
+    class Base
+      # Provision a new VM
+      #
+      # @param config [Hash] VM configuration
+      #   @option config [String] :zone Cloud zone (e.g., "us-nyc1")
+      #   @option config [String] :plan VM plan/size (e.g., "1xCPU-2GB")
+      #   @option config [String] :ssh_key Public SSH key for access
+      #   @option config [String] :title VM name/title
+      #
+      # @return [Hash] VM details
+      #   @option return [String] :id VM identifier
+      #   @option return [String] :ip Public IP address
+      #   @option return [Symbol] :status VM status (:pending, :running, :failed)
+      #
+      # @raise [AuthenticationError] if credentials are invalid
+      #   @raise [QuotaExceededError] if provider quota is exceeded
+      #   @raise [TimeoutError] if VM doesn't start within timeout period
+      #   @raise [ProvisioningError] for other provisioning failures
+      def provision_vm(config)
+        raise NotImplementedError, "#{self.class}#provision_vm must be implemented"
+      end
+
+      # Query VM status
+      #
+      # @param vm_id [String] VM identifier
+      #
+      # @return [Symbol] VM status
+      #   - :pending - VM is being created
+      #   - :running - VM is running
+      #   - :failed - VM failed to start
+      #   - :stopped - VM is stopped
+      #
+      # @raise [AuthenticationError] if credentials are invalid
+      def query_status(vm_id)
+        raise NotImplementedError, "#{self.class}#query_status must be implemented"
+      end
+
+      # Destroy VM and cleanup all associated resources
+      #
+      # @param vm_id [String] VM identifier
+      #
+      # @return [Boolean] true if successful, false otherwise
+      #
+      # @raise [AuthenticationError] if credentials are invalid
+      def destroy_vm(vm_id)
+        raise NotImplementedError, "#{self.class}#destroy_vm must be implemented"
+      end
+
+      # Estimate monthly cost for VM configuration
+      #
+      # This provides generic cost guidance and pricing page link.
+      # Real-time pricing queries are not implemented in Phase 1.
+      #
+      # @param config [Hash] VM configuration
+      #   @option config [String] :zone Cloud zone
+      #   @option config [String] :plan VM plan/size
+      #
+      # @return [Hash] Cost estimate details
+      #   @option return [String] :warning User-friendly cost warning message
+      #   @option return [String] :plan VM plan being estimated
+      #   @option return [String] :zone Cloud zone
+      #   @option return [String] :pricing_url URL to provider's pricing page
+      def estimate_cost(config)
+        raise NotImplementedError, "#{self.class}#estimate_cost must be implemented"
+      end
+    end
+  end
+end

data/lib/kamal/providers/upcloud.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require_relative "base"
+
+module Kamal
+  module Providers
+    # UpCloud API v1.3 provider implementation
+    #
+    # Implements VM provisioning, status querying, and cleanup via UpCloud's REST API.
+    # Uses Faraday with retry middleware for robust HTTP communication.
+    #
+    # @example Initialize provider
+    #   provider = Kamal::Providers::Upcloud.new(
+    #     username: ENV['UPCLOUD_USERNAME'],
+    #     password: ENV['UPCLOUD_PASSWORD']
+    #   )
+    #
+    # @example Provision a VM
+    #   vm = provider.provision_vm(
+    #     zone: 'us-nyc1',
+    #     plan: '1xCPU-2GB',
+    #     title: 'my-dev-vm',
+    #     ssh_key: File.read('~/.ssh/id_rsa.pub')
+    #   )
+    #   # => { id: 'uuid', ip: '1.2.3.4', status: :running }
+    class Upcloud < Base
+      API_BASE_URL = "https://api.upcloud.com"
+      API_VERSION = "1.3"
+      POLLING_INTERVAL = 5 # seconds
+      POLLING_TIMEOUT = 120 # seconds
+
+      # UpCloud storage template for Ubuntu 24.04 LTS (latest LTS)
+      # Using template UUID (universal across all UpCloud zones)
+      # Template type: cloud-init
+      # See: https://developers.upcloud.com/1.3/7-templates/
+      #
+      # Available Ubuntu templates:
+      #   - Ubuntu 24.04 LTS (Noble Numbat) - UUID: 01000000-0000-4000-8000-000030240200
+      #   - Ubuntu 22.04 LTS (Jammy Jellyfish) - UUID: 01000000-0000-4000-8000-000030220200
+      #
+      # Note: UUIDs verified from UpCloud API (2025-11-18)
+      DEFAULT_UBUNTU_TEMPLATE = "01000000-0000-4000-8000-000030240200"
+
+      # Initialize UpCloud provider with credentials
+      #
+      # @param username [String] UpCloud API username
+      # @param password [String] UpCloud API password
+      def initialize(username:, password:)
+        @conn = build_connection(username, password)
+      end
+
+      # Provision a new VM on UpCloud
+      #
+      # @param config [Hash] VM configuration
+      # @option config [String] :zone Cloud zone (e.g., "us-nyc1")
+      # @option config [String] :plan VM plan (e.g., "1xCPU-2GB")
+      # @option config [String] :title VM name/title
+      # @option config [String] :ssh_key Public SSH key for access
+      #
+      # @return [Hash] VM details
+      # @option return [String] :id VM identifier (UUID)
+      # @option return [String] :ip Public IP address
+      # @option return [Symbol] :status VM status (:running)
+      #
+      # @raise [AuthenticationError] if credentials are invalid
+      # @raise [QuotaExceededError] if provider quota is exceeded
+      # @raise [TimeoutError] if VM doesn't start within timeout
+      # @raise [ProvisioningError] for other failures
+      def provision_vm(config)
+        response = @conn.post("/#{API_VERSION}/server") do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.body = build_server_spec(config).to_json
+        end
+
+        server_data = parse_response(response)
+        vm_id = server_data["uuid"]
+        vm_ip = extract_ip_address(server_data)
+
+        # If already started, return immediately
+        return {id: vm_id, ip: vm_ip, status: :running} if server_data["state"] == "started"
+
+        # Otherwise poll until running
+        poll_until_running(vm_id)
+
+        {id: vm_id, ip: vm_ip, status: :running}
+      rescue Faraday::UnauthorizedError
+        raise AuthenticationError, "Invalid UpCloud credentials"
+      rescue Faraday::ForbiddenError => e
+        handle_forbidden_error(e)
+      rescue Faraday::ClientError => e
+        raise ProvisioningError, "UpCloud API error: #{e.response[:body]}"
+      rescue Faraday::ServerError
+        raise ProvisioningError, "UpCloud service unavailable"
+      end
+
+      # Query VM status
+      #
+      # @param vm_id [String] VM identifier (UUID)
+      #
+      # @return [Symbol] VM status
+      #   - :pending - VM is being created or in maintenance
+      #   - :running - VM is running
+      #   - :failed - VM failed to start
+      #   - :stopped - VM is stopped
+      #
+      # @raise [AuthenticationError] if credentials are invalid
+      def query_status(vm_id)
+        response = @conn.get("/#{API_VERSION}/server/#{vm_id}")
+        server_data = response.body["server"]
+
+        map_state_to_status(server_data["state"])
+      rescue Faraday::UnauthorizedError
+        raise AuthenticationError, "Invalid UpCloud credentials"
+      end
+
+      # Destroy VM and cleanup all associated resources
+      #
+      # @param vm_id [String] VM identifier (UUID)
+      #
+      # @return [Boolean] true if successful (idempotent)
+      #
+      # @raise [AuthenticationError] if credentials are invalid
+      def destroy_vm(vm_id)
+        @conn.delete("/#{API_VERSION}/server/#{vm_id}") do |req|
+          req.params["storages"] = "1" # Delete attached storages
+        end
+
+        true
+      rescue Faraday::ResourceNotFound
+        # Already deleted - idempotent
+        true
+      rescue Faraday::UnauthorizedError
+        raise AuthenticationError, "Invalid UpCloud credentials"
+      end
+
+      # Estimate monthly cost for VM configuration
+      #
+      # Provides generic cost guidance and pricing page link.
+      # Real-time pricing queries not implemented in Phase 1.
+      #
+      # @param config [Hash] VM configuration
+      # @option config [String] "zone" Cloud zone (string key)
+      # @option config [String] "plan" VM plan (string key)
+      #
+      # @return [Hash] Cost estimate details
+      # @option return [String] :warning User-friendly cost warning
+      # @option return [String] :plan VM plan
+      # @option return [String] :zone Cloud zone
+      # @option return [String] :pricing_url UpCloud pricing page
+      def estimate_cost(config)
+        plan = config["plan"] || config[:plan]
+        zone = config["zone"] || config[:zone]
+
+        {
+          warning: "Deploying VMs with plan #{plan} in zone #{zone}. " \
+                   "Check pricing for accurate costs.",
+          plan: plan,
+          zone: zone,
+          pricing_url: "https://upcloud.com/pricing"
+        }
+      end
+
+      private
+
+      # Build Faraday connection with middleware
+      def build_connection(username, password)
+        Faraday.new(url: API_BASE_URL) do |f|
+          # Request middleware (order matters!)
+          f.request :authorization, :basic, username, password
+          f.request :json # Auto-encode request bodies as JSON
+
+          # Retry middleware with exponential backoff
+          f.request :retry,
+            max: 3,
+            interval: 0.5,
+            interval_randomness: 0.5,
+            backoff_factor: 2,
+            retry_statuses: [429, 500, 502, 503, 504],
+            methods: [:get, :post, :delete]
+
+          # Response middleware
+          f.response :json, content_type: /\bjson$/ # Auto-parse JSON responses
+          f.response :raise_error # Raise on 4xx/5xx responses
+
+          # Adapter (must be last)
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      # Build UpCloud server specification from config
+      def build_server_spec(config)
+        # Determine storage template UUID
+        # Priority: 1) config override, 2) default Ubuntu 24.04 template
+        # Template UUIDs are universal (same across all UpCloud zones)
+        storage_template = config[:storage_template] || DEFAULT_UBUNTU_TEMPLATE
+
+        {
+          server: {
+            zone: config[:zone],
+            title: config[:title] || "kamal-dev-vm",
+            hostname: "#{config[:title] || "kamal-dev-vm"}.local",
+            plan: config[:plan],
+            metadata: "yes", # Required for cloud-init templates
+            storage_devices: {
+              storage_device: [
+                {
+                  action: "clone",
+                  storage: storage_template,
+                  title: "#{config[:title]}-disk",
+                  size: config[:disk_size] || 25 # GB
+                }
+              ]
+            },
+            login_user: {
+              username: "root",
+              ssh_keys: {
+                ssh_key: [config[:ssh_key]]
+              }
+            }
+          }
+        }
+      end
+
+      # Parse JSON response
+      def parse_response(response)
+        response.body["server"] || response.body
+      end
+
+      # Extract public IPv4 address from server data
+      # Prefers IPv4 over IPv6 for broader network compatibility
+      def extract_ip_address(server_data)
+        ip_addresses = server_data.dig("ip_addresses", "ip_address") || []
+
+        # Priority 1: Public IPv4 address
+        ipv4_public = ip_addresses.find { |ip| ip["access"] == "public" && ip["family"] == "IPv4" }
+        return ipv4_public["address"] if ipv4_public
+
+        # Priority 2: Any IPv4 address
+        ipv4_any = ip_addresses.find { |ip| ip["family"] == "IPv4" }
+        return ipv4_any["address"] if ipv4_any
+
+        # Priority 3: Public IPv6 address (fallback)
+        ipv6_public = ip_addresses.find { |ip| ip["access"] == "public" && ip["family"] == "IPv6" }
+        return ipv6_public["address"] if ipv6_public
+
+        # Priority 4: Any IP address (last resort)
+        ip_addresses.first&.fetch("address")
+      end
+
+      # Poll VM status until running or timeout
+      def poll_until_running(vm_id)
+        start_time = Time.now
+
+        loop do
+          status = query_status(vm_id)
+
+          return if status == :running
+
+          raise ProvisioningError, "VM failed to start" if status == :failed
+          raise TimeoutError, "VM provision timeout after #{POLLING_TIMEOUT}s" if Time.now - start_time > POLLING_TIMEOUT
+
+          sleep POLLING_INTERVAL
+        end
+      end
+
+      # Map UpCloud state to standard status symbol
+      def map_state_to_status(state)
+        case state
+        when "started"
+          :running
+        when "stopped"
+          :stopped
+        when "error"
+          :failed
+        when "maintenance", "pending"
+          :pending
+        else
+          :pending
+        end
+      end
+
+      # Handle 403 Forbidden errors (quota, credits, etc.)
+      def handle_forbidden_error(error)
+        body = error.response[:body].to_s
+
+        if body.include?("quota")
+          raise QuotaExceededError, "UpCloud quota exceeded"
+        elsif body.include?("credit")
+          raise ProvisioningError, "Insufficient UpCloud credits"
+        else
+          raise ProvisioningError, "Access forbidden: #{body}"
+        end
+      end
+    end
+  end
+end

data/lib/kamal-dev.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Bundler auto-requires "kamal-dev" based on the gem name
+# This file redirects to the actual implementation at kamal/dev.rb
+require_relative "kamal/dev"

data/sig/kamal/dev.rbs

@@ -0,0 +1,6 @@
+module Kamal
+  module Dev
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

data/test_installer.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# Test script for kamal-dev-install executable
+
+set -e
+
+echo "🧪 Testing kamal-dev-install..."
+echo
+
+# Store current directory (the gem root)
+GEM_ROOT=$(pwd)
+
+# Create a temporary test directory
+TEST_DIR=$(mktemp -d)
+echo "📁 Created test directory: $TEST_DIR"
+
+cd "$TEST_DIR"
+
+# Create a minimal Gemfile
+cat > Gemfile <<EOF
+source 'https://rubygems.org'
+
+gem 'kamal', '~> 2.0'
+gem 'kamal-dev', path: '$GEM_ROOT'
+EOF
+
+echo "✓ Created test Gemfile"
+
+# Run bundle install
+echo "📦 Running bundle install..."
+bundle install --quiet
+
+# Run the installer
+echo "🔧 Running plugin-kamal-dev..."
+bundle exec plugin-kamal-dev
+
+# Verify bin/kamal exists
+if [ ! -f "bin/kamal" ]; then
+  echo "❌ FAILED: bin/kamal not created"
+  exit 1
+fi
+
+echo "✓ bin/kamal exists"
+
+# Verify it contains the require
+if ! grep -q 'require "kamal-dev"' bin/kamal; then
+  echo "❌ FAILED: bin/kamal does not contain kamal-dev require"
+  exit 1
+fi
+
+echo "✓ bin/kamal contains kamal-dev require"
+
+# Run installer again to test idempotency
+echo "🔧 Running installer again (testing idempotency)..."
+bundle exec plugin-kamal-dev
+
+# Verify still only one require line
+REQUIRE_COUNT=$(grep -c 'require "kamal-dev"' bin/kamal || true)
+if [ "$REQUIRE_COUNT" -ne 1 ]; then
+  echo "❌ FAILED: Expected 1 require line, found $REQUIRE_COUNT"
+  exit 1
+fi
+
+echo "✓ Installer is idempotent"
+
+# Cleanup
+cd -
+rm -rf "$TEST_DIR"
+echo "🧹 Cleaned up test directory"
+
+echo
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "✅ All installer tests passed!"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: kamal-dev
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Lauri Jutila
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: kamal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: A Ruby gem that helps to deploy development containers using Kamal.
+email:
+- ljuti@nmux.dev
+executables:
+- kamal-dev
+- plugin-kamal-dev
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/kamal-dev
+- exe/plugin-kamal-dev
+- lib/kamal-dev.rb
+- lib/kamal/cli/dev.rb
+- lib/kamal/dev.rb
+- lib/kamal/dev/builder.rb
+- lib/kamal/dev/compose_parser.rb
+- lib/kamal/dev/config.rb
+- lib/kamal/dev/devcontainer.rb
+- lib/kamal/dev/devcontainer_parser.rb
+- lib/kamal/dev/registry.rb
+- lib/kamal/dev/secrets_loader.rb
+- lib/kamal/dev/state_manager.rb
+- lib/kamal/dev/templates/dev-entrypoint.sh
+- lib/kamal/dev/templates/dev.yml
+- lib/kamal/dev/version.rb
+- lib/kamal/providers/base.rb
+- lib/kamal/providers/upcloud.rb
+- sig/kamal/dev.rbs
+- test_installer.sh
+homepage: https://github.com/hyperengineering/kamal-dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hyperengineering/kamal-dev
+  source_code_uri: https://github.com/hyperengineering/kamal-dev
+  changelog_uri: https://github.com/hyperengineering/kamal-dev/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Deploy devcontainers with Kamal
+test_files: []