sandbox-provider 0.1.1

data/lib/sandbox/provider/hetzner/client.rb

@@ -0,0 +1,58 @@
+require "net/http"
+
+# Thin JSON client for https://api.hetzner.cloud/v1. Raises Sandbox::Adapter::Provider::Error on non-2xx. Every body
+# comes back symbol-keyed.
+class Sandbox::Provider::Hetzner::Client
+  BASE = "https://api.hetzner.cloud/v1"
+
+  def initialize(token)
+    @token = token
+  end
+
+  def get(path, params = {}) = request(Net::HTTP::Get, path, params:)
+  def post(path, body = {}) = request(Net::HTTP::Post, path, body:)
+  def delete(path) = request(Net::HTTP::Delete, path)
+
+  # Lists filtered by name return an array; nil when nothing matches. `collection` is the symbol the list
+  # answers under (:servers, :volumes…).
+  def find(collection, name) = get("/#{collection}", name:)[collection].first
+
+  def wait(action)
+    return if action.nil?
+    60.times do
+      current = get("/actions/#{action[:id]}")[:action]
+      return current if current[:status] == "success"
+      if current[:status] == "error"
+        raise Sandbox::Adapter::Provider::Error,
+          "hetzner action #{current[:id]}: #{current.dig(:error, :message)}"
+      end
+      sleep 3
+    end
+    raise Sandbox::Adapter::Provider::Error, "hetzner action #{action[:id]} timed out"
+  end
+
+  private
+
+    def request(klass, path, params: {}, body: nil)
+      uri = URI("#{BASE}#{path}")
+      uri.query = URI.encode_www_form(params) if params.any?
+      req = klass.new(uri)
+      req["Authorization"] = "Bearer #{@token}"
+      req["Content-Type"] = "application/json"
+      req.body = body.to_json if body
+      res = Sandbox::Adapter::Provider.reaching("hetzner") do
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 30) do |http|
+          http.request(req)
+        end
+      end
+      json = res.body.to_s.empty? ? {} : JSON.parse(res.body, symbolize_names: true)
+      unless res.is_a?(Net::HTTPSuccess)
+        raise Sandbox::Adapter::Provider::Error,
+          "hetzner #{req.method} #{path} #{res.code}: #{json.dig(:error, :message)}"
+      end
+      json
+    rescue JSON::ParserError
+      raise Sandbox::Adapter::Provider::Error,
+        "hetzner #{req.method} #{path} #{res.code}: #{res.body.to_s[0, 200]}"
+    end
+end

data/lib/sandbox/provider/hetzner.rb

@@ -0,0 +1,238 @@
+# Hetzner Cloud: the server in the workspace's network behind a firewall that opens SSH to everyone and the
+# preview port to Cloudflare alone, where the preview worker's requests come from. ensure_* calls are
+# find-or-create by name and safe to repeat.
+class Sandbox::Provider::Hetzner < Sandbox::Adapter::Vm
+  IMAGE = "ubuntu-24.04"
+  IP_RANGE = "10.0.0.0/16"
+  ANYONE = [ "0.0.0.0/0", "::/0" ].freeze
+  SSH_RULE = { direction: "in", protocol: "tcp", port: "22", source_ips: ANYONE }.freeze
+  FIREWALL_RULES = [ SSH_RULE ].freeze
+
+  # The ranges Cloudflare publishes; a Worker's fetch leaves from them. Fetched once per process, with the
+  # list as of 2026 behind it so a network blip does not close every preview.
+  CLOUDFLARE_LISTS = %w[https://www.cloudflare.com/ips-v4 https://www.cloudflare.com/ips-v6].freeze
+  CLOUDFLARE_IPS = %w[
+    173.245.48.0/20 103.21.244.0/22 103.22.200.0/22 103.31.4.0/22 141.101.64.0/18
+    108.162.192.0/18 190.93.240.0/20 188.114.96.0/20 197.234.240.0/22 198.41.128.0/17
+    162.158.0.0/15 104.16.0.0/13 104.24.0.0/14 172.64.0.0/13 131.0.72.0/22
+    2400:cb00::/32 2606:4700::/32 2803:f800::/32 2405:b500::/32 2405:8100::/32 2a06:98c0::/29
+    2c0f:f248::/32
+  ].freeze
+
+  # A list this box cannot reach leaves the built-in copy, reported so the staleness is visible. Only the
+  # reaching is caught: anything else here is a bug, not an unreachable Cloudflare.
+  def self.cloudflare_ips
+    @cloudflare_ips ||= CLOUDFLARE_LISTS.flat_map { Net::HTTP.get(URI(_1)).split }.presence ||
+                        CLOUDFLARE_IPS
+  rescue SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, SocketError => e
+    Sandbox::Adapter.reporter.report(e, handled: true)
+    CLOUDFLARE_IPS
+  end
+
+  # SSH for everyone, the preview port for Cloudflare only.
+  def self.rules
+    preview = { direction: "in", protocol: "tcp", port: Sandbox::Adapter::Vm::PREVIEW_PORT.to_s,
+                source_ips: cloudflare_ips }
+    [ SSH_RULE, preview ]
+  end
+  # The one size offered until the production catalog reads /server_types: cx23 at hel1, from the table.
+  # held is the volume, EUR per GB-month turned into USD cents per hour.
+  SIZE = { key: "2x4", type: "cx23", location: "hel1", cpu: 2, memory: 4, disk: 40 }.freeze
+  VOLUME_EUR_GB_MONTH = 0.0572
+  HOURS_MONTH = 730
+  # The label a deploy puts on everything it makes here, and the one thing #list can ask for.
+  LABEL = "nvoi-worktree".freeze
+
+  # Hetzner bills in EUR; every rate kept for it is USD cents. The rate comes from the bank that issues
+  # the euro, which publishes one reference rate a day and asks for no key. It publishes on business days
+  # only, so the newest is up to three days old, which is closer than a number typed in once.
+  #
+  # The constant is what the last look gave and what answers when the bank cannot be reached, so a box is
+  # still priced; it was read on the day the hetzner rates in Sandbox::Adapter::Prices were.
+  EUR_USD = 1.17
+  ECB = "https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml".freeze
+
+  # Dollars to the euro, as the ECB published it. Held for the process: a rate that moves once a day is
+  # not worth a request per price.
+  def self.eur_usd
+    @eur_usd ||= Net::HTTP.get(URI(ECB))[/currency=['"]USD['"]\s+rate=['"]([\d.]+)['"]/, 1]&.to_f ||
+                 EUR_USD
+  rescue SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, SocketError => e
+    Sandbox::Adapter.reporter.report(e, handled: true)
+    EUR_USD
+  end
+
+  def shapes
+    gb_hour = (VOLUME_EUR_GB_MONTH * 100 * self.class.eur_usd / HOURS_MONTH)
+    volume = (gb_hour * layout.volume_size).round(6)
+    key = "#{SIZE[:type]}:#{SIZE[:location]}"
+    { SIZE[:key] => Sandbox::Adapter.shape(cpu: SIZE[:cpu], memory: SIZE[:memory], disk: SIZE[:disk],
+                                  type: SIZE[:type], rate: price_table.cents("hetzner", key),
+                                  held: volume, source: :table,
+                                  as_of: price_table.as_of("hetzner")) }
+  end
+
+  # The server types priced: the AX node and the production sizes to come.
+  PRICED = %w[cx23 cx33 cx43].freeze
+
+  # Their price API, EUR net per hour per type and location, into USD cents.
+  def prices
+    types = @client.get("/pricing").dig(:pricing, :server_types)
+    rates = types.select { PRICED.include?(_1[:name]) }.flat_map do |type|
+      type[:prices].map do |price|
+        [ "#{type[:name]}:#{price[:location]}",
+(price.dig(:price_hourly, :net).to_f * 100 * self.class.eur_usd).round(6) ]
+      end
+    end.to_h
+    { source: "api", rates: }
+  end
+
+  # By the status string the API answers.
+  STATES = {
+    "running" => :running,
+    "off" => :stopped,
+    "initializing" => :starting,
+    "starting" => :starting,
+    "stopping" => :starting,
+    "migrating" => :starting,
+    "rebuilding" => :starting,
+    "deleting" => :starting
+  }.freeze
+
+  def initialize(token, client: Client.new(token), **)
+    super(token, **)
+    @client = client
+  end
+
+  # Network and firewall for the workspace, a volume and a server for the worktree; the volume's device path
+  # rides along in the machine's data.
+  # The size names the server type; the location is the one size's.
+  def create(name, labels: {}, shape: default_shape, disk: default_disk(shape), workspace:,
+user_data:)
+    server_type = shapes.fetch(shape)[:type]
+    location = SIZE[:location]
+    network = ensure_network(workspace)
+    firewall = ensure_firewall(workspace, rules: self.class.rules)
+    volume = ensure_volume(name, size: layout.volume_size, location:, labels:)
+    server = @client.find(:servers, name) || @client.post(
+      "/servers",
+      name:,
+      server_type:,
+      location:,
+      image: IMAGE,
+      user_data:,
+      labels:,
+      networks: [ network[:id] ],
+      firewalls: [ { firewall: firewall[:id] } ],
+      volumes: [ volume[:id] ]
+    ).then do |body|
+      @client.wait(body[:action])
+      body[:next_actions].each { |a| @client.wait(a) }
+      @client.get("/servers/#{body.dig(:server, :id)}")[:server]
+    end
+    machine(server, volume)
+  end
+
+  def find(name)
+    server = @client.find(:servers, name) or return nil
+    machine(server, @client.find(:volumes, name))
+  end
+
+  # Every server of ours at this project, by the label a deploy puts on one. Without it nothing could see
+  # a server whose row this app has lost, which is a server that bills until somebody notices by hand.
+  # The volume each one carries is fetched by the same name.
+  def list
+    volumes = @client.get("/volumes", label_selector: LABEL)[:volumes]
+    @client.get("/servers", label_selector: LABEL)[:servers].map do |server|
+      machine(server, volumes.find { _1[:name] == server[:name] })
+    end
+  end
+
+  def wake(m)
+    server = @client.find(:servers, m.name) or raise Error, "server #{m.name} is gone"
+    if server[:status] == "off"
+      @client.wait(@client.post("/servers/#{server[:id]}/actions/poweron")[:action])
+      server = @client.get("/servers/#{server[:id]}")[:server]
+    end
+    machine(server, @client.find(:volumes, m.name))
+  end
+
+  # The server is shut down cleanly, so the volume's filesystem is consistent, then goes; the volume stays for
+  # the next create.
+  def halt(m)
+    found = @client.find(:servers, m.name)
+    return false if found.nil?
+    if found[:status] == "running"
+      @client.wait(@client.post("/servers/#{found[:id]}/actions/shutdown")[:action])
+      30.times do
+        break if @client.get("/servers/#{found[:id]}").dig(:server, :status) == "off"
+        sleep 2
+      end
+    end
+    @client.wait(@client.delete("/servers/#{found[:id]}")[:action])
+    false
+  end
+
+  def destroy(m)
+    halt(m)
+    found = @client.find(:volumes, m.name)
+    return if found.nil?
+    if found[:server]
+      @client.wait(@client.post("/volumes/#{found[:id]}/actions/detach")[:action])
+    end
+    @client.delete("/volumes/#{found[:id]}")
+  end
+
+  def destroy_network(workspace)
+    found = @client.find(:firewalls, workspace)
+    @client.delete("/firewalls/#{found[:id]}") if found
+    found = @client.find(:networks, workspace)
+    @client.delete("/networks/#{found[:id]}") if found
+  end
+
+  private
+
+    def ensure_network(name)
+      @client.find(:networks, name) || @client.post(
+        "/networks",
+        name:,
+        ip_range: IP_RANGE,
+        subnets: [ { type: "cloud", ip_range: IP_RANGE, network_zone: "eu-central" } ]
+      )[:network]
+    end
+
+    def ensure_firewall(name, rules: FIREWALL_RULES)
+      found = @client.find(:firewalls, name)
+      return @client.post("/firewalls", name:, rules:)[:firewall] if found.nil?
+
+      if found[:rules].map { |r| r[:port] }.sort != rules.map { |r| r[:port] }.sort
+        @client.post("/firewalls/#{found[:id]}/actions/set_rules", rules:)[:actions].each do |a|
+          @client.wait(a)
+        end
+      end
+      found
+    end
+
+    # Labelled like the server it belongs to: a volume outlives its server, and one nothing can list is
+    # one that bills on quietly.
+    def ensure_volume(name, size:, location:, labels:)
+      @client.find(:volumes, name) || begin
+        body = @client.post("/volumes", name:, size:, location:, format: "ext4", labels:)
+        @client.wait(body[:action])
+        body[:volume]
+      end
+    end
+
+    def machine(server, volume)
+      Sandbox::Adapter::Machine.new(
+        id: server[:id].to_s,
+        name: server[:name],
+        state: STATES.fetch(server[:status], :broken),
+        data: {
+          address: server.dig(:public_net, :ipv4, :ip),
+          hostname: server.dig(:public_net, :ipv4, :dns_ptr),
+          device: volume&.dig(:linux_device)
+        }
+      )
+    end
+end

data/lib/sandbox/provider/version.rb

@@ -0,0 +1,5 @@
+module Sandbox
+  module Provider
+    VERSION = "0.1.1"
+  end
+end

data/lib/sandbox-provider.rb

@@ -0,0 +1,20 @@
+# The vendors a box can be bought from: a server of its own (Hetzner) and the sandboxes that fork from a
+# seed (Daytona, E2B, boat.dev). Each answers the Sandbox::Adapter::Provider contract and nothing else.
+#
+# A provider is required before the classes nested in it, which name it as they are defined.
+require "sandbox-adapter"
+
+module Sandbox::Provider; end
+require_relative "sandbox/provider/version"
+
+require_relative "sandbox/provider/cloud_init"
+require_relative "sandbox/provider/hetzner"
+require_relative "sandbox/provider/hetzner/client"
+require_relative "sandbox/provider/daytona"
+require_relative "sandbox/provider/daytona/client"
+require_relative "sandbox/provider/e2b"
+require_relative "sandbox/provider/e2b/client"
+require_relative "sandbox/provider/e2b/envd"
+require_relative "sandbox/provider/boat_dev"
+require_relative "sandbox/provider/boat_dev/client"
+require_relative "sandbox/provider/boat_dev/key"

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: sandbox-provider
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- nvoi
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sandbox-adapter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+- !ruby/object:Gem::Dependency
+  name: ed25519
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+email:
+- admin@nvoi.to
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/sandbox-provider.rb
+- lib/sandbox/provider/boat_dev.rb
+- lib/sandbox/provider/boat_dev/client.rb
+- lib/sandbox/provider/boat_dev/key.rb
+- lib/sandbox/provider/cloud_init.rb
+- lib/sandbox/provider/daytona.rb
+- lib/sandbox/provider/daytona/client.rb
+- lib/sandbox/provider/e2b.rb
+- lib/sandbox/provider/e2b/client.rb
+- lib/sandbox/provider/e2b/envd.rb
+- lib/sandbox/provider/hetzner.rb
+- lib/sandbox/provider/hetzner/client.rb
+- lib/sandbox/provider/version.rb
+homepage: https://rubygems.org/gems/sandbox-provider
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: 'Sandbox providers for sandbox-adapter: Daytona, E2B, boat.dev and Hetzner.'
+test_files: []