ubicloud 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3f801ab2b4e1c51db702928710d8ad3620f24148f9a9ff010b56261f5b5d97a6
+  data.tar.gz: bab2944336ed68b238ea7e388c2a6b50615d48b94f9ea2c641bb776577f2df7f
+SHA512:
+  metadata.gz: 28a31228bd129ed12feaa7f318a60bf377c7798efc1419c1d7e898e5a13a2a723ed453c4b556d69d64687a08e35c56c512171b5b7db6656b407be9c9de6b43fc
+  data.tar.gz: 1a9a39683f664ae62b77505da081617ecc38a8a2864aade55c6617d1ae5812423521d272739d865a11ea4b23d1c5dd6ea5f0e4f2aa0d963e96ed45d0f340f3a2

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Ubicloud's Ruby SDK is released under the MIT license (the rest of Ubicloud
+is released under the AGPL license).
+
+Copyright (c) 2025 Ubicloud, Inc.
+
+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 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/lib/ubicloud/adapter/net_http.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "uri"
+require "net/http"
+
+module Ubicloud
+  # Ubicloud::Adapter::NetHttp is the recommended adapter for general use.
+  # It uses the net/http standard library to make requests to the Ubicloud API.
+  class Adapter::NetHttp < Adapter
+    # Set the token and project_id to use for requests.  The base_uri argument
+    # can be used to access a self-hosted Ubicloud instance (or other Ubicloud
+    # instance not hosted by Ubicloud).
+    def initialize(token:, project_id:, base_uri: "https://api.ubicloud.com/")
+      @base_uri = URI.join(URI(base_uri), "project/#{project_id}/")
+      @headers = {
+        "authorization" => "Bearer: #{token}",
+        "content-type" => "application/json",
+        "accept" => "text/plain",
+        "connection" => "close"
+      }.freeze
+      @get_headers = @headers.dup
+      @get_headers.delete("content-type")
+      @get_headers.freeze
+    end
+
+    METHOD_MAP = {
+      "GET" => :get,
+      "POST" => :post,
+      "DELETE" => :delete,
+      "PATCH" => :patch
+    }.freeze
+
+    private_constant :METHOD_MAP
+
+    private
+
+    # Use Net::HTTP to submit a request to the Ubicloud API.
+    def call(method, path, params: nil, missing: :raise)
+      Net::HTTP.start(@base_uri.hostname, @base_uri.port, use_ssl: @base_uri.scheme == "https") do |http|
+        path = URI.join(@base_uri, path).path
+
+        response = case method
+        when "GET"
+          http.get(path, @get_headers)
+        when "DELETE"
+          http.delete(path, @headers)
+        else
+          http.send(METHOD_MAP.fetch(method), path, params&.to_json, @headers)
+        end
+
+        handle_response(response.code.to_i, response.body, missing:)
+      end
+    end
+  end
+end

data/lib/ubicloud/adapter/rack.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Ubicloud
+  # Ubicloud::Adapter::Rack is designed for internal use of the
+  # Ruby SDK by Ubicloud itself.  It is used inside Ubicloud to
+  # issue internal requests when handling CLI commands.  A new
+  # instance of Ubicloud::Adapter::Rack is created for each
+  # CLI command.
+  class Adapter::Rack < Adapter
+    # Accept the rack application (Clover), request env of the CLI request,
+    # and related project id.
+    def initialize(app:, env:, project_id:)
+      @app = app
+      @env = env
+      @project_id = project_id
+    end
+
+    private
+
+    # Create a new rack request enviroment hash for the internal
+    # request, and call the rack application with it.
+    def call(method, path, params: nil, missing: :raise)
+      env = @env.merge(
+        "REQUEST_METHOD" => method,
+        "PATH_INFO" => "/project/#{@project_id}/#{path}",
+        "rack.request.form_input" => nil,
+        "rack.request.form_hash" => nil
+      )
+      params &&= params.to_json.force_encoding(Encoding::BINARY)
+      env["rack.input"] = StringIO.new(params || "".b)
+      env.delete("roda.json_params")
+
+      status, _, rack_body = @app.call(env)
+      body = +""
+      rack_body.each { body << _1 }
+      rack_body.close if rack_body.respond_to?(:close)
+
+      handle_response(status, body, missing:)
+    end
+  end
+end

data/lib/ubicloud/adapter.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ubicloud
+  # Ubicloud::Adapter is the base class for adapters used in Ubicloud's Ruby SDK.
+  # Ubicloud's Ruby SDK uses adapters to allow for separate ways to access
+  # Ubicloud's API.  Currently, the :net_http adapter is the recommended adapter.
+  #
+  # Ubicloud::Adapter subclasses must implement +call+ to handle sending the
+  # request.  They should call +handle_response+ to handle responses to the
+  # request.
+  class Adapter
+    ADAPTERS = {
+      net_http: :NetHttp,
+      rack: :Rack
+    }.freeze
+    private_constant :ADAPTERS
+
+    # Require the related adapter file, and return the related adapter.
+    def self.adapter_class(adapter_type)
+      require_relative "adapter/#{adapter_type}"
+      const_get(ADAPTERS.fetch(adapter_type))
+    end
+
+    # Issue a GET request to the API for the given path.
+    def get(path, missing: :raise)
+      call("GET", path, missing:)
+    end
+
+    # Issue a GET request to the API for the given path and parameters.
+    def post(path, params = nil)
+      call("POST", path, params:)
+    end
+
+    # Issue a DELETE request to the API for the given path.
+    def delete(path)
+      call("DELETE", path)
+    end
+
+    # Issue a PATCH request to the API for the given path and parameters.
+    def patch(path, params = nil)
+      call("PATCH", path, params:)
+    end
+
+    private
+
+    # Handle responses to the requests made the library.  Non-200/204
+    # are treated as errors and result in an Ubicloud::Error being raised.
+    def handle_response(code, body, missing: :raise)
+      case code
+      when 204
+        nil
+      when 200
+        JSON.parse(body, symbolize_names: true)
+      else
+        return if code == 404 && missing.nil?
+        raise Error.new("unsuccessful response", code:, body:)
+      end
+    end
+  end
+end

data/lib/ubicloud/context.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Ubicloud
+  # Ubicloud::Context instances are the root object used in Ubicloud's Ruby
+  # SDK.  They provide access to the models, using the configured adapter.
+  #
+  # The following instance methods are defined via metaprogramming.  All
+  # return instances of Ubicloud::ModelAdapter, for the related model.
+  #
+  # +firewall+ :: Ubicloud::Firewall
+  # +load_balancer+ :: Ubicloud::LoadBalancer
+  # +postgres+ :: Ubicloud::Postgres
+  # +private_subnet+ :: Ubicloud::PrivateSubnet
+  # +vm+ :: Ubicloud::Vm
+  class Context
+    def initialize(adapter)
+      @adapter = adapter
+      @models = {}
+    end
+
+    {
+      vm: Vm,
+      postgres: Postgres,
+      firewall: Firewall,
+      private_subnet: PrivateSubnet,
+      load_balancer: LoadBalancer
+    }.each do |meth, model|
+      define_method(meth) { @models[meth] ||= ModelAdapter.new(model, @adapter) }
+    end
+
+    MODEL_PREFIX_MAP = {
+      "vm" => Vm,
+      "pg" => Postgres,
+      "fw" => Firewall,
+      "ps" => PrivateSubnet,
+      "1b" => LoadBalancer
+    }.freeze
+
+    # Return a new model instance for the given id, assuming the id is properly
+    # formatted.  Returns nil if the id is not properly formatted.  Does not
+    # check with \Ubicloud to determine whether the object actually exists.
+    def new(id)
+      if id.is_a?(String) && (model = MODEL_PREFIX_MAP[id[0, 2]]) && model.id_regexp.match?(id)
+        model.new(@adapter, id)
+      end
+    end
+
+    # The same as #new, but checks that the object exists and you have access to it.
+    def [](id)
+      new(id)&.check_exists
+    end
+  end
+end

data/lib/ubicloud/model/firewall.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Ubicloud
+  class Firewall < Model
+    set_prefix "fw"
+
+    set_fragment "firewall"
+
+    set_columns :id, :name, :description, :location, :firewall_rules, :path, :private_subnets
+
+    set_associations do
+      {private_subnets: PrivateSubnet}
+    end
+
+    # Allow the given cidr (ip address range) access to the given port range.
+    #
+    # * If +start_port+ and +end_port+ are both given, they specify the port range.
+    # * If only +start_port+ is given, only that single port is allowed.
+    # * If only +end_port+ is given, all ports up to that end port are allowed.
+    # * If neither +start_port+ and +end_port+ are given, all ports are allowed.
+    #
+    # Returns a hash for the firewall rule.
+    def add_rule(cidr, start_port: nil, end_port: nil)
+      rule = adapter.post(_path("/firewall-rule"), cidr:, port_range: "#{start_port || 0}..#{end_port || start_port || 65535}")
+
+      self[:firewall_rules]&.<<(rule)
+
+      rule
+    end
+
+    # Delete the firewall rule with the given id.  Returns nil.
+    def delete_rule(rule_id)
+      check_no_slash(rule_id, "invalid rule id format")
+      adapter.delete(_path("/firewall-rule/#{rule_id}"))
+
+      self[:firewall_rules]&.delete_if { _1[:id] == rule_id }
+
+      nil
+    end
+
+    # Attach the given private subnet to the firewall. Accepts either a PrivateSubnet instance
+    # or a private subnet id string.  Returns a PrivateSubnet instance.
+    def attach_subnet(subnet)
+      subnet_action(subnet, "/attach-subnet")
+    end
+
+    # Detach the given private subnet from the firewall. Accepts either a PrivateSubnet instance
+    # or a private subnet id string.  Returns a PrivateSubnet instance.
+    def detach_subnet(subnet)
+      subnet_action(subnet, "/detach-subnet")
+    end
+
+    private
+
+    # Internals of attach_subnet/detach_subnet.
+    def subnet_action(subnet, action)
+      PrivateSubnet.new(adapter, adapter.post(_path(action), private_subnet_id: to_id(subnet)))
+    end
+  end
+end

data/lib/ubicloud/model/load_balancer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Ubicloud
+  class LoadBalancer < Model
+    set_prefix "1b"
+
+    set_fragment "load-balancer"
+
+    set_columns :id, :name, :location, :hostname, :algorithm, :stack, :health_check_endpoint, :health_check_protocol, :src_port, :dst_port, :subnet, :vms
+
+    set_associations do
+      {
+        subnet: PrivateSubnet,
+        vms: Vm
+      }
+    end
+
+    set_create_param_defaults do |params|
+      params[:algorithm] ||= "round_robin"
+      params[:stack] ||= "dual"
+      params[:health_check_protocol] ||= "http"
+    end
+
+    # Update the receiver with new parameters. Returns self.
+    #
+    # The +vms+ argument should be an array of virtual machines attached to the load
+    # balancer.  The method will attach and detach virtual machines to the load
+    # balancer as needed so that the list of attached virtual machines matches the
+    # array given.
+    def update(algorithm:, src_port:, dst_port:, health_check_endpoint:, vms:)
+      merge_into_values(adapter.patch(_path, algorithm:, src_port:, dst_port:, health_check_endpoint:, vms:))
+    end
+
+    # Attach the given virtual machine to the firewall. Accepts either a Vm instance
+    # or a virtual machine id string.  Returns a Vm instance.
+    def attach_vm(vm)
+      vm_action(vm, "/attach-vm")
+    end
+
+    # Detach the given virtual machine from the firewall. Accepts either a Vm instance
+    # or a virtual machine id string.  Returns a Vm instance.
+    def detach_vm(vm)
+      vm_action(vm, "/detach-vm")
+    end
+
+    private
+
+    # Internals of attach_vm/detach_vm
+    def vm_action(vm, action)
+      Vm.new(adapter, adapter.post(_path(action), vm_id: to_id(vm)))
+    end
+  end
+end

data/lib/ubicloud/model/postgres.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Ubicloud
+  class Postgres < Model
+    set_prefix "pg"
+
+    set_fragment "postgres"
+
+    set_columns :id, :name, :state, :location, :vm_size, :storage_size_gib, :version, :ha_type, :flavor, :ca_certificates, :connection_string, :primary, :firewall_rules, :metric_destinations
+
+    set_create_param_defaults do |params|
+      params[:size] ||= "standard-2"
+    end
+
+    # Schedule a restart of the PostgreSQL server. Returns self.
+    def restart
+      merge_into_values(adapter.post(_path("/restart")))
+    end
+
+    # Allow the given cidr (ip address range) access to the PostgreSQL database port (5432)
+    # for this database. Returns a hash for the firewall rule.
+    def add_firewall_rule(cidr)
+      rule = adapter.post(_path("/firewall-rule"), cidr:)
+
+      self[:firewall_rules]&.<<(rule)
+
+      rule
+    end
+
+    # Delete the firewall rule with the given id.  Returns nil.
+    def delete_firewall_rule(rule_id)
+      check_no_slash(rule_id, "invalid rule id format")
+      adapter.delete(_path("/firewall-rule/#{rule_id}"))
+
+      self[:firewall_rules]&.delete_if { _1[:id] == rule_id }
+
+      nil
+    end
+
+    # Add a metric destination for this database with the given username, password,
+    # and URL. Returns a hash for the metric destination.
+    def add_metric_destination(username:, password:, url:)
+      md = adapter.post(_path("/metric-destination"), username:, password:, url:)
+
+      self[:metric_destinations]&.<<(md)
+
+      md
+    end
+
+    # Delete the metric destination with the given id.  Returns nil.
+    def delete_metric_destination(md_id)
+      check_no_slash(md_id, "invalid metric destination id format")
+      adapter.delete(_path("/metric-destination/#{md_id}"))
+
+      self[:metric_destinations]&.delete_if { _1[:id] == md_id }
+
+      nil
+    end
+
+    # Schedule a password reset for the database superuser (postgres) for the database.
+    # Returns self.
+    def reset_superuser_password(password)
+      merge_into_values(adapter.post(_path("/reset-superuser-password"), password:))
+    end
+
+    # Schedule a restore of the database at the given restore_target time, to a new
+    # database with the given name.  Returns a Postgres instance for the restored
+    # database.
+    def restore(name:, restore_target:)
+      Postgres.new(adapter, adapter.post(_path("/restore"), name:, restore_target:))
+    end
+  end
+end

data/lib/ubicloud/model/private_subnet.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ubicloud
+  class PrivateSubnet < Model
+    set_prefix "ps"
+
+    set_fragment "private-subnet"
+
+    set_columns :id, :name, :state, :location, :net4, :net6, :firewalls, :nics
+
+    set_associations do
+      {firewalls: Firewall}
+    end
+
+    # Connect the given private subnet to the receiver. Accepts either a PrivateSubnet instance
+    # or a private subnet id string. Returns self.
+    def connect(subnet)
+      merge_into_values(adapter.post(_path("/connect"), "connected-subnet-ubid": to_id(subnet)))
+    end
+
+    # Disconnect the given private subnet from the receiver. Accepts either a PrivateSubnet instance
+    # or a private subnet id string. Returns self.
+    def disconnect(subnet)
+      subnet = to_id(subnet)
+      check_no_slash(subnet, "invalid private subnet id format")
+      merge_into_values(adapter.post(_path("/disconnect/#{subnet}")))
+    end
+  end
+end

data/lib/ubicloud/model/vm.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Ubicloud
+  class Vm < Model
+    set_prefix "vm"
+
+    set_fragment "vm"
+
+    set_columns :id, :name, :state, :location, :size, :unix_user, :storage_size_gib, :ip6, :ip4_enabled, :ip4, :firewalls, :private_ipv4, :private_ipv6, :subnet
+
+    set_associations do
+      {
+        firewalls: Firewall,
+        subnet: PrivateSubnet
+      }
+    end
+
+    set_create_param_defaults do |params|
+      params[:public_key] = params[:public_key]&.gsub(/(?<!\r)\n/, "\r\n")
+    end
+
+    # Schedule a restart of the virtual machine. Returns self.
+    def restart
+      merge_into_values(adapter.post(_path("/restart")))
+    end
+  end
+end

data/lib/ubicloud/model.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module Ubicloud
+  # Ubicloud::Model is the abstract base class for model classes.  There is a
+  # separate model class for each primary object type in Ubicloud's API.
+  class Model
+    class << self
+      # A hash of associations for the model.  This is used by instances
+      # to automatically wrap returned objects in model instances.
+      attr_reader :associations
+
+      # The path fragment for this model in the Ubicloud API.
+      attr_reader :fragment
+
+      # A regexp for valid id format for instances of this model.
+      attr_reader :id_regexp
+
+      # Return a new model instance for the given values, tied to the
+      # related adapter, if the model instance exists and is accessible.
+      # Return nil if the model instance does not exist or is not
+      # accessible.  +values+ can be:
+      #
+      # * a string in a valid id format for the model
+      # * a string in location/name format
+      # * a hash of values (must contain either :id key or :location and :name keys)
+      def [](adapter, values)
+        new(adapter, values).check_exists
+      end
+
+      # Create a new model object in Ubicloud with the given location, name, and params.
+      def create(adapter, location:, name:, **params)
+        new(adapter, adapter.post("location/#{location}/#{fragment}/#{name}", _create_params(params)))
+      end
+
+      # Return an array of all model instances you have access to in Ubicloud. If the
+      # +location+ keyword argument is given, only return model instances for that location.
+      def list(adapter, location: nil)
+        path = if location
+          raise Error, "invalid location: #{location.inspect}" if location.include?("/")
+          "location/#{location}/#{fragment}"
+        else
+          fragment
+        end
+
+        adapter.get(path)[:items].map { new(adapter, _1) }
+      end
+
+      # Resolve associations.  This is called after all models have been loaded.
+      # This approach is taken to avoid the need for autoload or const_get.
+      def resolve_associations # :nodoc:
+        @associations = @association_block&.call || {}
+      end
+
+      private
+
+      # Used by models to set defaults for parameters.  Overrides the _create_params
+      # method using the given block.  The block should mutate the parameter hash.
+      def set_create_param_defaults
+        singleton_class.send(:private, define_singleton_method(:_create_params) do |params|
+          params = params.dup || {}
+          yield params
+          params
+        end)
+      end
+
+      # The parameters to use when creating an object.  Uses only the given parameters
+      # by default.
+      def _create_params(params)
+        params
+      end
+
+      # Register the assocation block that will be used for resolving associations.
+      def set_associations(&block)
+        @association_block = block
+      end
+
+      # Create methods for each of the model's columns (unless the method is already defined).
+      # These methods will fully populate the object if the related key is not already present
+      # in the model.
+      def set_columns(*columns)
+        columns.each do |column|
+          next if method_defined?(column)
+          define_method(column) do
+            info unless @values.has_key?(column)
+            @values[column]
+          end
+        end
+      end
+
+      # Use the given regexp to set the valid id_regexp format for the model.
+      def set_prefix(prefix)
+        @id_regexp = %r{\A#{prefix}[a-tv-z0-9]{24}\z}
+      end
+
+      # Set the path fragment that this model uses in the Ubicloud API.
+      def set_fragment(fragment)
+        @fragment = fragment
+      end
+    end
+
+    # Return the adapter used for this model instance.  Each model instance is tied to a
+    # specific adapter, and requests to the Ubicloud API are made through the adapter.
+    attr_reader :adapter
+
+    # A hash of values for the model instance.
+    attr_reader :values
+
+    # Create a new model instance, which should represent an object that already exists
+    # in Ubicloud. +values+ can be:
+    #
+    # * a string in a valid id format for the model
+    # * a string in location/name format
+    # * a hash with symbol keys (must contain either :id key or :location and :name keys)
+    def initialize(adapter, values)
+      @adapter = adapter
+
+      case values
+      when String
+        @values = if self.class.id_regexp.match?(values)
+          {id: values}
+        else
+          location, name, extra = values.split("/", 3)
+          raise Error, "invalid #{self.class.fragment} location/name: #{values.inspect}" if extra || !name
+          {location:, name:}
+        end
+      when Hash
+        if !values[:id] && !(values[:location] && values[:name])
+          raise Error, "hash must have :id key or :location and :name keys"
+        end
+        @values = {}
+        merge_into_values(values)
+      else
+        raise Error, "unsupported value initializing #{self.class}: #{values.inspect}"
+      end
+    end
+
+    # Return hash of data for this model instance.
+    def to_h
+      @values
+    end
+
+    # Return the value of a specific key for the model instance.
+    def [](key)
+      @values[key]
+    end
+
+    # Destroy the given model instance in Ubicloud.  It is not possible to restore
+    # objects that have been destroyed, so only use this if you are sure you want
+    # to destroy the object.
+    def destroy
+      adapter.delete(_path)
+    end
+
+    # The model's id, which will be a 26 character string.  This will load the
+    # id from Ubicloud if the model instance doesn't currently store the id
+    # (such as when it was initialized with a location and name).
+    def id
+      unless (id = @values[:id])
+        info
+        id = @values[:id]
+      end
+
+      id
+    end
+
+    # The model's location, as a string.  This will load the location from Ubicloud
+    # if the model instance does not currently store it (such as when it was
+    # initialized with an id).
+    def location
+      unless (location = @values[:location])
+        load_object_info_from_id
+        location = @values[:location]
+      end
+
+      location
+    end
+
+    # The model's name.  This will load the name from Ubicloud if the model instance
+    # does not currently store it (such as when it was initialized with an id).
+    def name
+      unless (name = @values[:name])
+        load_object_info_from_id
+        name = @values[:name]
+      end
+
+      name
+    end
+
+    # Fully populate the model instance by making a request to the Ubicloud API.
+    # This can also be used to refresh an already populated instance.
+    def info
+      _info
+    end
+
+    # Show the class name and values hash.
+    def inspect
+      "#<#{self.class.name} #{@values.inspect}>"
+    end
+
+    # Check whether the current instance exists in Ubicloud.  Returns nil if the
+    # object does not exist.
+    def check_exists
+      @values[:name] ? _info(missing: nil) : load_object_info_from_id(missing: nil)
+    end
+
+    private
+
+    def _info(missing: :raise)
+      if (hash = adapter.get(_path, missing:))
+        merge_into_values(hash)
+      end
+    end
+
+    # Raise an error if the given string contains a slash.  This is used for strings
+    # used as path fragments when making requests, to raise an error before issuing
+    # an HTTP request in the case where you know the path would not be valid.
+    def check_no_slash(string, error_message)
+      raise Error, error_message if string.include?("/")
+    end
+
+    # If the given id is not already a string, call id on it to get a string.
+    # This is used in methods that can accept either a model instance or an id.
+    def to_id(id)
+      (String === id) ? id : id.id
+    end
+
+    # For each of the model's associations, convert the related entry in the values
+    # hash to an associated object.
+    def check_associations
+      values = @values
+
+      self.class.associations.each do |key, klass|
+        next unless (value = values[key])
+
+        values[key] = if value.is_a?(Array)
+          value.map do
+            convert_to_association(_1, klass)
+          end
+        else
+          convert_to_association(value, klass)
+        end
+      end
+    end
+
+    # Convert the given value to an instance of the given klass.
+    def convert_to_association(value, klass)
+      case value
+      when Hash, klass.id_regexp
+        klass.new(adapter, value)
+      when String
+        # The object is given by name and not by id, assume that
+        # it must be in the same location as the receiver.
+        klass.new(adapter, "#{location}/#{value}")
+      else
+        value
+      end
+    end
+
+    # Given only the object's id, find the location and name of the object
+    # and merge them into the values hash.
+    def load_object_info_from_id(missing: :raise)
+      if (hash = adapter.get("object-info/#{values[:id]}", missing:))
+        hash.delete("type")
+        merge_into_values(hash)
+      end
+    end
+
+    # Merge the given values into the values hash, and convert any entries in
+    # the values hash to associated objects.
+    def merge_into_values(values)
+      @values.merge!(values)
+      check_associations
+      self
+    end
+
+    # The path to use for requests for the model instance.  If +rest+ is given,
+    # it is appended to the path.
+    def _path(rest = "")
+      "location/#{location}/#{self.class.fragment}/#{name}#{rest}"
+    end
+  end
+end
+
+# Require each model subclass, and then resolve associations after
+# all subclasses have been loaded.
+Dir.open(File.join(__dir__, "model")) do |dir|
+  dir.each_child do |file|
+    if file.end_with?(".rb")
+      require_relative "model/#{file}"
+    end
+  end
+end
+Ubicloud::Model.subclasses.each(&:resolve_associations)

data/lib/ubicloud/model_adapter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ubicloud
+  # Ubicloud::ModelAdapter instances represents a model class
+  # that is tied to a adapter.  Methods called on instances
+  # of this class are forwarded to the related model, with
+  # the adapter as the first argument.
+  class ModelAdapter
+    def initialize(model, adapter)
+      @model = model
+      @adapter = adapter
+    end
+
+    # Forward methods to the model class, but include the
+    # adapter as the first argument.
+    def method_missing(meth, ...)
+      @model.public_send(meth, @adapter, ...)
+    end
+
+    # Respond to the method if the model class responds to it.
+    def respond_to_missing?(...)
+      @model.respond_to?(...)
+    end
+  end
+end

data/lib/ubicloud.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "ubicloud/adapter"
+require_relative "ubicloud/model"
+require_relative "ubicloud/model_adapter"
+require_relative "ubicloud/context"
+
+# The Ubicloud module is the namespace for Ubicloud's Ruby SDK,
+# and also the primary entry point.  Even though it is a module,
+# users are expected to call +Ubicloud.new+ to return an appropriate
+# context (Ubicloud::Context) that is used to make requests to
+# Ubicloud's API.
+module Ubicloud
+  # Error class used for errors raised by Ubicloud's Ruby SDK.
+  class Error < StandardError
+    # The integer HTTP status code related to the error.  Can be
+    # nil if the Error is not related to an HTTP request.
+    attr_reader :code
+
+    # Accept the code and body keyword arguments for metadata
+    # related to this error.
+    def initialize(message, code: nil, body: nil)
+      super(message)
+      @code = code
+      @body = body
+    end
+
+    # A hash of parameters.  This is the parsed JSON response body
+    # for the request that resulted in an error.  If an invalid
+    # body is given, or the error is not related to an HTTP request,
+    # returns an empty hash.
+    def params
+      @body ? JSON.parse(@body) : {}
+    rescue
+      {}
+    end
+  end
+
+  # Create a new Ubicloud::Context for the given adapter type
+  # and parameters.  This is the main entry point to the library.
+  # In general, users of the SDK will want to use the :net_http
+  # adapter type:
+  #
+  #   Ubicloud.new(:net_http, token: "YOUR_API_TOKEN", project_id: "pj...")
+  def self.new(adapter_type, **params)
+    Context.new(Adapter.adapter_class(adapter_type).new(**params))
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: ubicloud
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ubicloud, Inc.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-03-31 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- ruby-gem-owner@ubicloud.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- MIT-LICENSE
+files:
+- MIT-LICENSE
+- lib/ubicloud.rb
+- lib/ubicloud/adapter.rb
+- lib/ubicloud/adapter/net_http.rb
+- lib/ubicloud/adapter/rack.rb
+- lib/ubicloud/context.rb
+- lib/ubicloud/model.rb
+- lib/ubicloud/model/firewall.rb
+- lib/ubicloud/model/load_balancer.rb
+- lib/ubicloud/model/postgres.rb
+- lib/ubicloud/model/private_subnet.rb
+- lib/ubicloud/model/vm.rb
+- lib/ubicloud/model_adapter.rb
+homepage: https://github.com/ubicloud/ubicloud/tree/main/sdk/ruby
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/ubicloud/ubicloud/issues
+  mailing_list_uri: https://github.com/ubicloud/ubicloud/discussions/new?category=q-a
+  source_code_uri: https://github.com/ubicloud/ubicloud/tree/main/sdk/ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ubicloud Ruby SDK
+test_files: []