mythic-beasts 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3ce37ca163918f82d1612c56fc75ce81e8de315abf65500a90b98ff6ca586dd
-  data.tar.gz: 21885db9c87b16458429a26a886b5873437d29d4232d7b11833ce9a9c2016029
+  metadata.gz: b734cfcdd42c515ebf9d1c11d0ccc95067f0da9912fbbe62742de3865265f426
+  data.tar.gz: a53d53c0eaf241086e37cf25bad093156e5777edacabf90b291ffadfb43187d9
 SHA512:
-  metadata.gz: b4629b547c7aa646fdba1eedf30c51d9e524005f3e8c7de3c112abc1d38f305a1befa6f421cf2334520e9a8ba683450709b7398a7e29bdd2f8f1bb6ddf204e2a
-  data.tar.gz: 8e9e1879278b5b9fa898328835be2ceaa3bcb1a4d6dd809f58050374903e609869a5af216095e09fb46f8a72b7f0a92d0e4944c7ca85afbf7e44d98fa6f68586
+  metadata.gz: e464d4d61ac8a68ae5c2615c235e6a0357e1dcf4253a8f6bb961b690b0b97164f8dde32f486f637c29ce77893b6d83f3a0b6e314dd55a8e82a956d4567e5ebf0
+  data.tar.gz: 580d8c412f04e39a4a8a3f25604beed9d540655ab83ce7766f60df2dd05752655003105f399b8cd6b1b79c44ba7c9bf6bef1424a76032dd773f386a6f237622b

data/CHANGELOG.md

@@ -5,9 +5,64 @@ 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).
 
+## [Unreleased]
+
+## [0.2.0] - 2025-11-09
+
+### Added in 0.2.0
+
+- Interactive CLI tool `mythic-beasts-provision` with numbered menu navigation for VPS provisioning
+- Interactive VPS management tool `mythic-beasts-manage-vps` with DNS and proxy configuration
+- IPv4 to IPv6 Proxy API client (`MythicBeasts.client.proxy`) for managing proxy endpoints
+  - List, create, replace, and delete proxy configurations
+  - Support for all proxy sites (sov, ams, hex) or "all"
+  - Convenience method `create_simple` for quick proxy setup
+  - Full CRUD operations on proxy endpoints by domain/hostname/address
+- DNS record verification after proxy configuration
+- DNS management integration in manage-vps tool
+
+### Changed in 0.2.0
+
+- Replaced tty-prompt with simple numbered menus for better terminal compatibility (especially Ghostty)
+- Smart bandwidth display: shows GB for >= 1024MB, MB otherwise
+
+### Fixed in 0.2.0
+
+- Zones endpoint now uses correct `/beta/vps/zones` path
+- DNS verification now handles non-array responses correctly
+- DNS records method name corrected in provision-vps tool
+- VPS provisioning polling now waits for actual completion
+- Status polling output now uses newlines properly
+- IPv4 allocation during VPS provisioning
+- Bandwidth display showing MB correctly instead of 0GB
+
+## [0.1.3] - 2025-11-05
+
+### Fixed in 0.1.3
+
+- Bearer token authentication for VPS API endpoints - now sets Authorization header on each request
+- VPS API endpoints now use correct `/beta/vps/*` paths instead of `/vps/*`
+- Location header now captured from 202 Accepted responses for polling async operations
+- Improved error messages to show API response body for better debugging
+
+### Added to 0.1.3
+
+- `VPS#images` method to list available OS images from `/beta/vps/images`
+- `VPS#products` method to list available VPS products from `/beta/vps/products`
+- `VPS#disk_sizes` method to list available disk sizes from `/beta/vps/disk-sizes`
+- `VPS#zones` method to list available zones from `/beta/vps/zones`
+- Example script `list_vps_options.rb` to display all available VPS configuration options
+
+### Changed in 0.1.3
+
+- VPS creation now requires `product:` parameter (e.g., `VPSX16`) instead of `type:`
+- VPS creation now requires `ssh_keys:` parameter instead of `ssh_key:`
+- VPS creation now uses `zone:` parameter instead of `location:`
+- 404 errors now show the full URL and HTTP method that failed
+
 ## [0.1.2] - 2025-11-05
 
-### Added
+### Added in 0.1.2
 
 - VPS zones listing method (`MythicBeasts.client.vps.zones`) to query available datacenters
 - VPS types listing method (`MythicBeasts.client.vps.types`) to query available VPS plans
@@ -19,7 +74,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `ipv6_only_vps.rb` - IPv6-only VPS with proxy setup guide
 - Test coverage for IPv6-only VPS provisioning
 
-### Changed
+### Changed in 0.1.2
 
 - Updated README with new VPS methods and examples
 - Improved VPS create documentation with optional parameters

data/README.md

@@ -86,14 +86,37 @@ MythicBeasts.client.dns.dynamic_update('home.example.com')
 
 ### VPS Management
 
+#### Interactive CLI Tool (Recommended)
+
+The gem includes an interactive CLI for easy VPS provisioning with numbered menus:
+
+```bash
+# With 1Password
+op run --env-file=.env.1password -- mythic-beasts-provision
+
+# Or with environment variables
+export MYTHIC_BEASTS_API_KEY="your_key"
+export MYTHIC_BEASTS_API_SECRET="your_secret"
+mythic-beasts-provision
+```
+
+The CLI will guide you through selecting options by number:
+
+- Selecting product (VPS size)
+- Choosing datacenter/zone
+- Picking OS image
+- Setting disk size
+- Network configuration (IPv4/IPv6)
+- Server naming
+
+#### Programmatic API
+
 ```ruby
-# List available zones/datacenters
+# List available options
 zones = MythicBeasts.client.vps.zones
-# => ["london", "cambridge", "amsterdam", "fremont"]
-
-# List available VPS types/plans
-types = MythicBeasts.client.vps.types
-# => ["VPS-1", "VPS-2", "VPS-3", ...]
+products = MythicBeasts.client.vps.products
+images = MythicBeasts.client.vps.images
+disk_sizes = MythicBeasts.client.vps.disk_sizes
 
 # List all VPS servers
 servers = MythicBeasts.client.vps.list
@@ -103,13 +126,14 @@ server = MythicBeasts.client.vps.get('my-server')
 
 # Create a new VPS
 MythicBeasts.client.vps.create(
-  name: 'my-new-server',
-  type: 'VPS-2',
-  ssh_key: 'ssh-rsa AAAAB3...',
-  location: 'london',  # Optional: specify datacenter
-  service: 'my-service',  # Optional: service/project name
-  description: 'My test server',  # Optional: server description
-  notes: 'Any additional notes'  # Optional: special requests
+  product: 'VPSX16',  # Required: product code (e.g., VPSX16 = 2 cores, 4GB RAM)
+  name: 'my-new-server',  # Optional: friendly name
+  hostname: 'my-server',  # Optional: server hostname
+  ssh_keys: 'ssh-rsa AAAAB3...',  # Optional: SSH public key(s)
+  zone: 'cam',  # Optional: datacenter code (e.g., 'cam' for Cambridge)
+  image: 'cloudinit-debian-bookworm.raw.gz',  # Optional: OS image
+  disk_size: 20480,  # Required: disk size in MB
+  ipv4: false  # Optional: false for IPv6-only (cheaper)
 )
 
 # Control servers
@@ -124,16 +148,16 @@ console = MythicBeasts.client.vps.console('my-server')
 MythicBeasts.client.vps.delete('my-server')
 ```
 
-#### IPv6-Only Servers (Cost Savings)
+#### IPv6-Only Servers
 
 Provision cheaper IPv6-only servers without IPv4 addresses. Perfect for services accessible via Mythic Beasts' IPv4-to-IPv6 proxy:
 
 ```ruby
-# Create an IPv6-only VPS (cheaper!)
+# Create an IPv6-only VPS
 MythicBeasts.client.vps.create(
   name: 'my-ipv6-server',
   type: 'VPS-2',
-  ipv4: false,  # No IPv4 address = lower cost
+  ipv4: false,
   ssh_key: 'ssh-rsa AAAAB3...',
   location: 'london'
 )
@@ -242,7 +266,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/tastyb
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-Copyright (c) 2025 Otaina Limited
+Copyright © 2025, Otaina Limited
 
 ## Resources
 

data/lib/mythic_beasts/auth.rb

@@ -36,6 +36,9 @@ module MythicBeasts
       @token = data["access_token"]
       # Expire token 30 seconds before actual expiry to be safe
       @token_expires_at = Time.now + (data["expires_in"].to_i - 30)
+    rescue Faraday::UnauthorizedError => e
+      response_body = e.response&.dig(:body)
+      raise AuthenticationError, "Failed to authenticate with Mythic Beasts API. Check your API key and secret. Response: #{response_body}"
     rescue Faraday::Error => e
       raise AuthenticationError, "Failed to authenticate: #{e.message}"
     end

data/lib/mythic_beasts/client.rb

@@ -2,12 +2,13 @@ module MythicBeasts
   class Client
     API_BASE_URL = "https://api.mythic-beasts.com"
 
-    attr_reader :auth, :dns, :vps
+    attr_reader :auth, :dns, :vps, :proxy
 
     def initialize(api_key:, api_secret:)
       @auth = Auth.new(api_key: api_key, api_secret: api_secret)
       @dns = DNS.new(self)
       @vps = VPS.new(self)
+      @proxy = Proxy.new(self)
     end
 
     def get(path, params: {})
@@ -22,6 +23,10 @@ module MythicBeasts
       request(:put, path, body: body, params: params)
     end
 
+    def patch(path, body: {}, params: {})
+      request(:patch, path, body: body, params: params)
+    end
+
     def delete(path, params: {})
       request(:delete, path, params: params)
     end
@@ -31,22 +36,34 @@ module MythicBeasts
     def request(method, path, body: {}, params: {})
       response = connection.send(method) do |req|
         req.url path
+        req.headers["Authorization"] = "Bearer #{auth.token}"
         req.params = params if params.any?
         req.body = body.to_json if body.any?
       end
 
-      JSON.parse(response.body) if response.body && !response.body.empty?
+      result = JSON.parse(response.body) if response.body && !response.body.empty?
+
+      # For 202 Accepted responses, include Location header for polling
+      if response.status == 202 && response.headers["location"]
+        result ||= {}
+        result["location"] = response.headers["location"]
+      end
+
+      result
     rescue Faraday::UnauthorizedError, Faraday::ClientError => e
+      response_body = e.response&.dig(:body)
       if e.response&.dig(:status) == 401
-        raise AuthenticationError, "Invalid credentials"
+        raise AuthenticationError, "Invalid credentials - #{response_body}"
       elsif e.response&.dig(:status) == 404
-        raise NotFoundError, e.message
+        raise NotFoundError, "the server responded with status 404 for #{method.to_s.upcase} #{API_BASE_URL}#{path}"
       elsif e.response&.dig(:status) == 400
-        raise ValidationError, e.message
+        raise ValidationError, "#{e.message} - #{response_body}"
+      elsif e.response&.dig(:status) == 409
+        raise ConflictError, "#{e.message} - #{response_body}"
       elsif e.response&.dig(:status) == 429
         raise RateLimitError, e.message
       else
-        raise Error, e.message
+        raise Error, "#{e.message} - #{response_body}"
       end
     rescue Faraday::ServerError => e
       raise ServerError, e.message
@@ -54,7 +71,6 @@ module MythicBeasts
 
     def connection
       @connection ||= Faraday.new(url: API_BASE_URL) do |conn|
-        conn.request :authorization, :bearer, -> { auth.token }
         conn.request :json
         conn.request :retry, {
           max: 3,

data/lib/mythic_beasts/errors.rb

@@ -3,6 +3,7 @@ module MythicBeasts
   class AuthenticationError < Error; end
   class NotFoundError < Error; end
   class ValidationError < Error; end
+  class ConflictError < Error; end
   class RateLimitError < Error; end
   class ServerError < Error; end
 end

data/lib/mythic_beasts/proxy.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module MythicBeasts
+  # IPv4 to IPv6 Proxy API
+  #
+  # Manages IPv4-to-IPv6 proxy endpoints for making IPv6-only servers
+  # accessible via IPv4. Useful for cost-effective IPv6-only VPS deployments.
+  #
+  # @see https://www.mythic-beasts.com/support/api/proxy
+  class Proxy
+    # @param client [MythicBeasts::Client] the API client
+    def initialize(client)
+      @client = client
+    end
+
+    # List all proxy endpoints accessible to the authenticated user
+    #
+    # @return [Array<Hash>] array of endpoint configurations
+    # @example
+    #   endpoints = client.proxy.list
+    #   # => [{"domain" => "example.com", "hostname" => "www", "address" => "2a00:...", "site" => "all"}]
+    def list
+      response = @client.get("/proxy/endpoints")
+      response["endpoints"] || response[:endpoints] || []
+    end
+
+    # List proxy endpoints for a specific domain
+    #
+    # @param domain [String] the domain name
+    # @return [Array<Hash>] array of endpoint configurations for the domain
+    # @example
+    #   endpoints = client.proxy.list_for_domain("example.com")
+    def list_for_domain(domain)
+      response = @client.get("/proxy/endpoints/#{domain}")
+      response["endpoints"] || response[:endpoints] || []
+    end
+
+    # List proxy endpoints for a specific hostname
+    #
+    # @param domain [String] the domain name
+    # @param hostname [String] the hostname (use "@" for the domain itself)
+    # @return [Array<Hash>] array of endpoint configurations
+    # @example
+    #   endpoints = client.proxy.list_for_hostname("example.com", "www")
+    def list_for_hostname(domain, hostname)
+      response = @client.get("/proxy/endpoints/#{domain}/#{hostname}")
+      response["endpoints"] || response[:endpoints] || []
+    end
+
+    # Create or replace proxy endpoints for a hostname
+    #
+    # This replaces ALL existing endpoints for the hostname.
+    #
+    # @param domain [String] the domain name
+    # @param hostname [String] the hostname (use "@" for the domain itself)
+    # @param endpoints [Array<Hash>] array of endpoint configurations
+    # @option endpoints [String] :address IPv6 address
+    # @option endpoints [String] :site proxy server location or "all"
+    # @option endpoints [Boolean] :proxy_protocol enable PROXY protocol (optional)
+    # @return [Hash] API response
+    # @example
+    #   client.proxy.replace(
+    #     "example.com",
+    #     "www",
+    #     [{address: "2a00:1098:4c4::1", site: "all"}]
+    #   )
+    def replace(domain, hostname, endpoints)
+      @client.put("/proxy/endpoints/#{domain}/#{hostname}", body: {endpoints: endpoints})
+    end
+
+    # Add proxy endpoints for a hostname without replacing existing ones
+    #
+    # @param domain [String] the domain name
+    # @param hostname [String] the hostname (use "@" for the domain itself)
+    # @param endpoints [Array<Hash>] array of endpoint configurations
+    # @option endpoints [String] :address IPv6 address
+    # @option endpoints [String] :site proxy server location or "all"
+    # @option endpoints [Boolean] :proxy_protocol enable PROXY protocol (optional)
+    # @return [Hash] API response
+    # @example
+    #   client.proxy.add(
+    #     "example.com",
+    #     "www",
+    #     [{address: "2a00:1098:4c4::1", site: "all"}]
+    #   )
+    def add(domain, hostname, endpoints)
+      @client.post("/proxy/endpoints/#{domain}/#{hostname}", body: {endpoints: endpoints})
+    end
+
+    # Delete all proxy endpoints for a hostname
+    #
+    # @param domain [String] the domain name
+    # @param hostname [String] the hostname
+    # @return [Hash] API response
+    # @example
+    #   client.proxy.delete("example.com", "www")
+    def delete(domain, hostname)
+      @client.delete("/proxy/endpoints/#{domain}/#{hostname}")
+    end
+
+    # Delete a specific proxy endpoint
+    #
+    # @param domain [String] the domain name
+    # @param hostname [String] the hostname
+    # @param address [String] the IPv6 address
+    # @param site [String] the proxy site (optional, defaults to "all")
+    # @return [Hash] API response
+    # @example
+    #   client.proxy.delete_endpoint("example.com", "www", "2a00:1098:4c4::1")
+    def delete_endpoint(domain, hostname, address, site = nil)
+      path = "/proxy/endpoints/#{domain}/#{hostname}/#{address}"
+      path += "/#{site}" if site
+      @client.delete(path)
+    end
+
+    # List available proxy server locations
+    #
+    # @return [Array<String>] array of site codes (e.g., ["sov", "ams", "hex"])
+    # @example
+    #   sites = client.proxy.sites
+    #   # => ["sov", "ams", "hex"]
+    def sites
+      response = @client.get("/proxy/sites")
+      response["sites"] || response[:sites] || []
+    end
+
+    # Convenience method: Create a simple proxy endpoint for a server
+    #
+    # @param domain [String] the domain name
+    # @param hostname [String] the hostname (use "@" for root domain)
+    # @param ipv6_address [String] the IPv6 address of your server
+    # @param proxy_protocol [Boolean] enable PROXY protocol (default: false)
+    # @return [Hash] API response
+    # @example
+    #   # Make staging.example.com point to IPv6-only server
+    #   client.proxy.create_simple(
+    #     "example.com",
+    #     "staging",
+    #     "2a00:1098:4c4::1"
+    #   )
+    def create_simple(domain, hostname, ipv6_address, proxy_protocol: false)
+      endpoint = {
+        address: ipv6_address,
+        site: "all"
+      }
+      endpoint[:proxy_protocol] = true if proxy_protocol
+
+      add(domain, hostname, [endpoint])
+    end
+  end
+end

data/lib/mythic_beasts/version.rb

@@ -1,3 +1,3 @@
 module MythicBeasts
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/mythic_beasts/vps.rb

@@ -11,26 +11,55 @@ module MythicBeasts
       client.get("/api/vps")
     end
 
+    # List all VPS servers (newer endpoint)
+    def servers
+      client.get("/vps/servers")
+    end
+
     # Get details of a specific VPS
     def get(server_name)
       client.get("/api/vps/#{server_name}")
     end
 
+    # Get details of a specific VPS by identifier (newer endpoint)
+    def server(identifier)
+      client.get("/vps/servers/#{identifier}")
+    end
+
     # Create a new VPS
     # Options:
-    #   - name: Server name
-    #   - type: Server type (e.g., 'VPS-1', 'VPS-2')
-    #   - disk: Disk size in GB
-    #   - ssh_key: SSH public key for access
-    def create(name:, type:, ssh_key: nil, **options)
+    #   - product: Server product (e.g., 'VPS-1', 'VPS-2') - REQUIRED
+    #   - name: Friendly name for the server
+    #   - hostname: Hostname for the server
+    #   - ssh_keys: SSH public key(s) for access
+    #   - zone: Datacentre code (e.g., 'london', 'cambridge')
+    #   - ipv4: Boolean - allocate IPv4 address (default true)
+    #   - image: Operating system image name
+    #   - disk_size: Disk size in MB
+    #   And other optional parameters...
+    def create(product:, name: nil, ssh_keys: nil, **options)
+      body = {
+        product: product,
+        **options
+      }
+      body[:name] = name if name
+      body[:ssh_keys] = ssh_keys if ssh_keys
+
+      client.post("/beta/vps/servers", body: body)
+    end
+
+    # Create a new VPS with a custom identifier
+    # Returns 409 Conflict if identifier already exists
+    # Options are same as create method
+    def create_with_identifier(identifier, product:, name: nil, ssh_keys: nil, **options)
       body = {
-        name: name,
-        type: type,
+        product: product,
         **options
       }
-      body[:ssh_key] = ssh_key if ssh_key
+      body[:name] = name if name
+      body[:ssh_keys] = ssh_keys if ssh_keys
 
-      client.post("/api/vps", body: body)
+      client.post("/beta/vps/servers/#{identifier}", body: body)
     end
 
     # Start a VPS
@@ -48,24 +77,58 @@ module MythicBeasts
       client.post("/api/vps/#{server_name}/restart")
     end
 
+    # Reboot a VPS by identifier (newer endpoint)
+    def reboot(identifier)
+      client.post("/vps/servers/#{identifier}/reboot")
+    end
+
+    # Update a VPS (e.g., mount ISO image)
+    # Options:
+    #   - iso_image: ISO image name to mount
+    def update(identifier, **options)
+      client.patch("/vps/servers/#{identifier}", body: options)
+    end
+
     # Delete a VPS
     def delete(server_name)
       client.delete("/api/vps/#{server_name}")
     end
 
+    # Unprovision (permanently delete) a VPS by identifier (newer endpoint)
+    def unprovision(identifier)
+      client.delete("/beta/vps/servers/#{identifier}")
+    end
+
     # Get VPS console access
     def console(server_name)
       client.get("/api/vps/#{server_name}/console")
     end
 
-    # List available zones/locations for VPS provisioning
+    # List available ISO images for a specific server
+    # These can be mounted to the server for manual OS installation
+    def iso_images(server_identifier)
+      client.get("/beta/vps/servers/#{server_identifier}/iso-images")
+    end
+
+    # List available zones/datacenters for VPS provisioning
     def zones
-      client.get("/api/vps/zones")
+      client.get("/beta/vps/zones")
+    end
+
+    # List available OS images for VPS provisioning
+    def images
+      client.get("/beta/vps/images")
+    end
+
+    # List available disk sizes
+    # Returns hash with 'ssd' and 'hdd' keys containing arrays of sizes in MB
+    def disk_sizes
+      client.get("/beta/vps/disk-sizes")
     end
 
-    # List available VPS types/plans
-    def types
-      client.get("/api/vps/types")
+    # List available products
+    def products
+      client.get("/beta/vps/products")
     end
   end
 end

data/lib/mythic_beasts.rb

@@ -7,6 +7,7 @@ require_relative "mythic_beasts/client"
 require_relative "mythic_beasts/auth"
 require_relative "mythic_beasts/dns"
 require_relative "mythic_beasts/vps"
+require_relative "mythic_beasts/proxy"
 require_relative "mythic_beasts/errors"
 
 module MythicBeasts

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mythic-beasts
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - James Inman
@@ -165,6 +165,7 @@ files:
 - lib/mythic_beasts/client.rb
 - lib/mythic_beasts/dns.rb
 - lib/mythic_beasts/errors.rb
+- lib/mythic_beasts/proxy.rb
 - lib/mythic_beasts/version.rb
 - lib/mythic_beasts/vps.rb
 homepage: https://github.com/tastybamboo/mythic-beasts