latitude-api 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ad7537135ba5a563aae3317a22e9ce2ec10d7b875ae0a2ffc1b812b9d20441cb
+  data.tar.gz: 9ec8e48ca3706b3d8c8ede062ae488479e292291b1ccc687a86df23d0fa70a5d
+SHA512:
+  metadata.gz: 5db971e47af3606101fd255f40ab3050cfad19336055366f2d4c76f91d48b729e329cd6ed85407bc6336ec114135ff01d2cdd90cc5df388f18f58d656035486d
+  data.tar.gz: 39389c048065f96391f13ebeca25997a8662d6a43feff75476177fd8321f5d245c521743e000d9122b13e1026d3e4280bdd58ac1dfe810ba66776d7359dc55a9

data/.yardopts

@@ -0,0 +1,10 @@
+--markup markdown
+--main README.md
+--title latitude-api
+--no-private
+--protected
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+LICENSE.txt

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Josh Brody
+
+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,283 @@
+# latitude-api
+
+A Ruby client for the [Latitude.sh](https://www.latitude.sh) REST API. Covers servers, projects, virtual machines, Kubernetes clusters, storage, networking, firewalls, elastic IPs, SSH keys, teams, and more. Ships with a client for the on-instance metadata service.
+
+Requires Ruby 3.0+. Fork it if you need lower support—should probably be fine.
+
+## Install
+
+```ruby
+gem "latitude-api"
+```
+
+```bash
+bundle add latitude-api
+```
+
+## Quickstart
+
+```ruby
+require "latitude"
+
+Latitude.api_key = ENV.fetch("LATITUDE_API_KEY")
+
+server = Latitude::Server.create(
+  project: "proj_abc",
+  plan: "c2-small-x86",
+  site: "ASH",
+  operating_system: "ubuntu_22_04_x64_lts",
+  hostname: "web-01",
+)
+
+server.id         # => "sv_..."
+server.hostname   # => "web-01"
+server.status     # => "off"
+server.plan.slug  # => "c2-small-x86"
+
+server.reboot
+server.lock
+server.delete
+```
+
+## Configuration
+
+```ruby
+Latitude.configure do |c|
+  c.api_key              = ENV.fetch("LATITUDE_API_KEY")
+  c.api_base             = "https://api.latitude.sh"      # default
+  c.api_version          = "2023-06-01"                   # optional, sent as API-Version header
+  c.open_timeout         = 30
+  c.read_timeout         = 80
+  c.max_network_retries  = 2                              # retries 429/500/502/503/504 with backoff
+  c.logger               = Logger.new($stdout)
+end
+```
+
+Per-request overrides live in the final hash argument of any call:
+
+```ruby
+Latitude::Server.create(params, {
+  api_key:         "lat_tenant_specific",
+  api_version:     "2023-06-01",
+  idempotency_key: "svr-create-123",
+  open_timeout:    5,
+})
+```
+
+So, for multi-tenant apps, use a client:
+
+```ruby
+client = Latitude::Client.new(api_key: "lat_tenant_A")
+client.servers.list
+client.projects.retrieve("proj_abc")
+```
+
+## Resources
+
+All resources are under `Latitude::`:
+
+| Resource | Class | Endpoint |
+|---|---|---|
+| Servers | `Latitude::Server` | `/servers` |
+| Projects | `Latitude::Project` | `/projects` |
+| Project SSH keys | `Latitude::Project::SSHKey` | `/projects/:project_id/ssh_keys` |
+| Project user data | `Latitude::Project::UserData` | `/projects/:project_id/user_data` |
+| SSH keys | `Latitude::SSHKey` | `/ssh_keys` |
+| User data | `Latitude::UserData` | `/user_data` |
+| Tags | `Latitude::Tag` | `/tags` |
+| Teams | `Latitude::Team` | `/team` |
+| Team members | `Latitude::Team::Member` | `/team/members` |
+| API keys | `Latitude::APIKey` | `/auth/api_keys` |
+| Elastic IPs | `Latitude::ElasticIP` | `/elastic_ips` |
+| VLANs | `Latitude::VirtualNetwork` | `/virtual_networks` |
+| VLAN assignments | `Latitude::VirtualNetwork::Assignment` | `/virtual_networks/assignments` |
+| Firewalls | `Latitude::Firewall` | `/firewalls` |
+| Firewall assignments | `Latitude::Firewall::Assignment` | `/firewalls/:firewall_id/assignments` |
+| VPN sessions | `Latitude::VPNSession` | `/vpn_sessions` |
+| Filesystems | `Latitude::Storage::Filesystem` | `/storage/filesystems` |
+| Volumes | `Latitude::Storage::Volume` | `/storage/volumes` |
+| Object storage | `Latitude::Storage::Object` | `/storage/objects` |
+| Virtual machines | `Latitude::VirtualMachine` | `/virtual_machines` |
+| Kubernetes clusters | `Latitude::KubernetesCluster` | `/kubernetes_clusters` |
+| Plans | `Latitude::Plan` (+ `OperatingSystem`, `Bandwidth`, `Storage`, `VirtualMachine`) | `/plans` |
+| Regions | `Latitude::Region` | `/regions` |
+| Roles | `Latitude::Role` | `/roles` |
+| Events | `Latitude::Event` | `/events` |
+| IPs | `Latitude::IP` | `/ips` |
+| Billing usage | `Latitude::BillingUsage` | `/billing/usage` |
+| Traffic | `Latitude::Traffic` (+ `#quota`) | `/traffic` |
+| User profile | `Latitude::User::Profile` | `/user/profile` |
+| User teams | `Latitude::User::Team` | `/user/teams` |
+
+Every full-CRUD resource supports a spooky-familiar operation surface:
+
+```ruby
+Latitude::Project.list(filter: { name: { match: "prod" } }, sort: "-created_at", page: { size: 50 })
+Latitude::Project.retrieve("proj_abc")
+Latitude::Project.create(name: "Payments", provisioning_type: "on_demand")
+Latitude::Project.update("proj_abc", name: "Payments 2.0")
+Latitude::Project.delete("proj_abc")
+
+project = Latitude::Project.retrieve("proj_abc")
+project.name = "renamed"
+project.save
+project.delete
+```
+
+### Filters, sort, pagination
+
+Follows the [Latitude API filter grammar](https://docs.latitude.sh):
+
+```ruby
+Latitude::Server.list(
+  filter: {
+    project:  "proj_abc",
+    hostname: { prefix: "web" },
+    ram:      { gte: 32 },
+    tags:     ["tag_prod", "tag_db"],
+  },
+  sort: "-created_at",
+  page: { size: 50, number: 1 },
+  extra_fields: { servers: "credentials" },
+)
+```
+
+Auto-paginate:
+
+```ruby
+Latitude::Server.list(filter: { project: "proj_abc" }).auto_paging_each do |server|
+  # ...
+end
+
+# or materialize the whole collection
+Latitude::Server.all(filter: { project: "proj_abc" })
+```
+
+### Server power and maintenance actions
+
+```ruby
+server = Latitude::Server.retrieve("sv_abc")
+
+server.reboot
+server.power_on
+server.power_off
+server.reset
+
+server.lock
+server.unlock
+
+server.rescue_mode
+server.exit_rescue_mode
+
+server.schedule_deletion(at: "2026-05-01T00:00:00Z", reason: "decommission")
+server.unschedule_deletion
+
+server.reinstall(
+  operating_system: "ubuntu_22_04_x64_lts",
+  hostname: "web-01",
+  ssh_keys: ["ssh_abc"],
+)
+
+server.deploy_config
+server.update_deploy_config(hostname: "web-02")
+
+server.create_out_of_band_connection(port: 22)
+server.list_out_of_band_connections
+```
+
+### Nested resources
+
+```ruby
+Latitude::Project::SSHKey.list(project_id: "proj_abc")
+Latitude::Project::SSHKey.create(project_id: "proj_abc", name: "bastion", public_key: "ssh-rsa ...")
+
+project = Latitude::Project.retrieve("proj_abc")
+project.ssh_keys.create(name: "bastion", public_key: "ssh-rsa ...")
+project.user_data.list
+```
+
+## Errors
+
+Every API failure raises a typed exception:
+
+```ruby
+begin
+  Latitude::Server.retrieve("sv_bogus")
+rescue Latitude::NotFoundError => e
+  e.http_status    # => 404
+  e.code           # => "not_found"
+  e.detail         # => "Specified Record Not Found"
+  e.request_id     # from response header
+  e.errors         # Array<APIError::Entry> with raw payloads
+end
+```
+
+Hierarchy is straightforward:
+
+- `Latitude::Error`
+  - `Latitude::ConfigurationError`
+  - `Latitude::ConnectionError`
+  - `Latitude::APIError`
+    - `Latitude::BadRequestError` (400)
+    - `Latitude::AuthenticationError` (401)
+    - `Latitude::PermissionError` (403) — `#feature_not_enabled?`, `#read_only_key?`
+    - `Latitude::NotFoundError` (404)
+    - `Latitude::ConflictError` (409)
+    - `Latitude::UnprocessableEntityError` (422)
+    - `Latitude::RateLimitError` (429) — `#retry_after` reads `meta.retry_after`
+    - `Latitude::ServerError` (5xx)
+
+## Rate limits
+
+The API rate limits per API key; these are handled in the gem but you should be mindful yourself:
+
+- Reads (GET): 60 requests/minute
+- Writes (POST/PUT/PATCH/DELETE): 20 requests/minute
+
+Set `max_network_retries` to auto-backoff across 429s; `RateLimitError#retry_after` is honored between retries.
+
+## Versioning
+
+As of this commit, only supports Latitude `2023-06-01`. You can override this if you want:
+
+```ruby
+Latitude.api_version = "2023-06-01"                       # global
+Latitude::Server.list({}, { api_version: "2022-07-18" })  # per call
+```
+
+## Instance metadata service
+
+One quirk I haven't decided to bake in because I don't need it (if you do, let me know and I'll do my best):
+
+_Only_ if your code runs on a Latitude.sh bare metal server, `Latitude::Metadata` reads the on-instance metadata service (`http://169.254.169.254/metadata/v1`) using IMDSv2-style tokens. Separate from the main API—different auth, same library.
+
+```ruby
+Latitude::Metadata.hostname       # "web-01"
+Latitude::Metadata.public_ipv4    # "203.0.113.10"
+Latitude::Metadata.region         # "SAO"
+Latitude::Metadata.tags           # [{key:, value:}, ...]
+Latitude::Metadata.userdata       # cloud-init string or nil
+Latitude::Metadata.all            # full metadata object
+
+meta = Latitude::Metadata.all
+meta.network.interfaces.first.addresses.first.address
+```
+
+Not reachable from outside a Latitude server. Outside that context, calls raise `Latitude::Metadata::Unavailable`.
+
+I've thought about making a protected HTTP server expose this but I don't imagine anyone needs it that can't do it themselves.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake test
+```
+
+## Contributing
+
+Bug reports and pull requests welcome at [github.com/joshmn/latitude-api](https://github.com/joshdotmn/latitude-api).
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
+task default: :test

data/lib/latitude/api/api_object.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    class APIObject
+      extend Attributes::ClassMethods
+      include Attributes::InstanceMethods
+
+      RESERVED = %i[attributes id type meta values].freeze
+
+      attr_reader :raw
+
+      def self.wrap(value)
+        case value
+        when Hash
+          new(value)
+        when Array
+          value.map { |v| wrap(v) }
+        else
+          value
+        end
+      end
+
+      def initialize(hash = {})
+        @raw = hash || {}
+        @values = {}
+        @raw.each { |k, v| @values[k.to_s] = wrap_attribute(k, v) }
+      end
+
+      def [](key)
+        @values[key.to_s]
+      end
+
+      def key?(key)
+        @values.key?(key.to_s)
+      end
+
+      def keys
+        @values.keys
+      end
+
+      def each(&blk)
+        @values.each(&blk)
+      end
+
+      def to_h
+        @values.each_with_object({}) do |(k, v), out|
+          out[k] = unwrap(v)
+        end
+      end
+
+      alias to_hash to_h
+
+      def as_json(*_)
+        to_h
+      end
+
+      def ==(other)
+        return false unless other.is_a?(self.class)
+
+        to_h == other.to_h
+      end
+
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      def inspect
+        "#<#{self.class.name} #{to_h.inspect}>"
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        key = normalize_method_name(name)
+        return true if @values.key?(key)
+        return true if key.end_with?("?") && @values.key?(key.chomp("?"))
+
+        super
+      end
+
+      def method_missing(name, *args, &blk)
+        key = normalize_method_name(name)
+        return @values[key] if @values.key?(key) && args.empty?
+        return !!@values[key.chomp("?")] if key.end_with?("?") && @values.key?(key.chomp("?")) && args.empty?
+
+        super
+      end
+
+      private
+
+      def normalize_method_name(name)
+        name.to_s
+      end
+
+      def unwrap(value)
+        case value
+        when APIObject then value.to_h
+        when Array     then value.map { |v| unwrap(v) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/latitude/api/api_resource.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+module Latitude
+  module API
+    class APIResource
+      extend Attributes::ClassMethods
+      include Attributes::InstanceMethods
+
+      class << self
+        def resource_type(value = nil)
+          @resource_type = value if value
+          @resource_type || raise(NotImplementedError, "#{name} must declare resource_type")
+        end
+
+        def resource_path(value = nil)
+          @resource_path = value if value
+          @resource_path || raise(NotImplementedError, "#{name} must declare resource_path")
+        end
+
+        def id_prefix(value = nil)
+          @id_prefix = value if value
+          @id_prefix
+        end
+
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@resource_type, @resource_type)
+          subclass.instance_variable_set(:@resource_path, @resource_path)
+          subclass.instance_variable_set(:@id_prefix, @id_prefix)
+        end
+
+        def class_url(path_params: {})
+          fill_path(resource_path, path_params)
+        end
+
+        def instance_url(id, path_params: {})
+          raise ArgumentError, "id is required" if id.nil? || id.to_s.empty?
+
+          "#{class_url(path_params: path_params)}/#{URI.encode_www_form_component(id)}"
+        end
+
+        def execute_request(method:, path:, query: nil, body: nil, opts: {}, headers: {})
+          options = RequestOptions.wrap(opts)
+          effective = options.apply_to(config_source)
+          RequestExecutor.new(effective).execute(
+            method: method,
+            path: path,
+            query: query,
+            body: body,
+            headers: headers,
+            idempotency_key: options.idempotency_key,
+            extra_headers: options.headers,
+          )
+        end
+
+        def construct_from(parsed, opts: {}, path_params: {})
+          data = parsed.is_a?(Hash) ? parsed["data"] : nil
+          raise APIError, "response missing data envelope" unless data.is_a?(Hash)
+
+          new(data, meta: parsed["meta"], path_params: path_params, opts: opts)
+        end
+
+        def config_source
+          Thread.current[:latitude_api_config] || Latitude.config
+        end
+
+        def with_config(config)
+          prev = Thread.current[:latitude_api_config]
+          Thread.current[:latitude_api_config] = config
+          yield
+        ensure
+          Thread.current[:latitude_api_config] = prev
+        end
+
+        def extract_path_params(params, keys)
+          extracted = {}
+          keys.each do |k|
+            v = params.delete(k) || params.delete(k.to_s)
+            extracted[k] = v if v
+          end
+          extracted
+        end
+
+        def path_param_keys
+          resource_path.scan(/:(\w+)/).flatten.map(&:to_sym)
+        end
+
+        private
+
+        def fill_path(template, path_params)
+          filled = template.dup
+          path_params.each do |k, v|
+            token = ":#{k}"
+            raise ArgumentError, "path param #{k} not in template #{template}" unless filled.include?(token)
+
+            filled = filled.gsub(token, URI.encode_www_form_component(v.to_s))
+          end
+          missing = filled.scan(/:(\w+)/).flatten
+          raise ArgumentError, "missing path params: #{missing.join(', ')}" unless missing.empty?
+
+          filled
+        end
+      end
+
+      attr_reader :id, :type, :meta, :path_params, :raw_data
+
+      def initialize(data, meta: nil, path_params: {}, opts: {})
+        @raw_data    = data
+        @id          = data["id"]
+        @type        = data["type"]
+        @meta        = data["meta"] || meta || {}
+        @path_params = path_params || {}
+        @opts        = opts || {}
+        @values      = {}
+        @unsaved     = []
+        Array(data["attributes"]).each do |k, v|
+          @values[k.to_s] = wrap_attribute(k, v)
+        end
+      end
+
+      def attributes
+        @values.each_with_object({}) { |(k, v), h| h[k] = unwrap(v) }
+      end
+
+      def to_h
+        out = {}
+        out["id"] = @id if @id
+        out["type"] = @type if @type
+        out["attributes"] = attributes
+        out["meta"] = @meta unless @meta.nil? || @meta.empty?
+        out
+      end
+
+      alias to_hash to_h
+
+      def as_json(*_)
+        to_h
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && other.id == @id
+      end
+
+      alias eql? ==
+
+      def hash
+        [@type, @id].hash
+      end
+
+      def inspect
+        "#<#{self.class.name} id=#{@id.inspect} #{attributes.map { |k, v| "#{k}=#{v.inspect}" }.join(' ')}>"
+      end
+
+      def [](key)
+        @values[key.to_s]
+      end
+
+      def []=(key, value)
+        key_s = key.to_s
+        @values[key_s] = wrap_attribute(key_s, value)
+        @unsaved << key_s unless @unsaved.include?(key_s)
+        value
+      end
+
+      def write_attribute(name, value)
+        self[name] = value
+      end
+
+      def unsaved_attributes
+        @unsaved.each_with_object({}) { |k, h| h[k] = unwrap(@values[k]) }
+      end
+
+      def changed?
+        !@unsaved.empty?
+      end
+
+      def refresh(opts = {})
+        parsed = self.class.execute_request(method: :get, path: resource_url, opts: opts)
+        update_from(parsed)
+        self
+      end
+
+      def save(opts = {})
+        return self unless changed?
+
+        payload = JSONAPI.encode(type: @type || self.class.resource_type, id: @id, attributes: unsaved_attributes)
+        parsed = self.class.execute_request(method: :patch, path: resource_url, body: payload, opts: opts)
+        update_from(parsed)
+        @unsaved.clear
+        self
+      end
+
+      def delete(opts = {})
+        self.class.execute_request(method: :delete, path: resource_url, opts: opts)
+        self
+      end
+
+      alias destroy delete
+
+      def resource_url
+        self.class.instance_url(@id, path_params: @path_params)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        return true if @values.key?(name.to_s)
+        return true if name.to_s.end_with?("=") && !read_only_attribute?(name.to_s.chomp("="))
+
+        super
+      end
+
+      def method_missing(name, *args)
+        name_s = name.to_s
+        if name_s.end_with?("=") && args.size == 1
+          attr_name = name_s.chomp("=")
+          if read_only_attribute?(attr_name)
+            raise NoMethodError, "cannot assign to read-only attribute #{attr_name}"
+          end
+
+          return self[attr_name] = args.first
+        end
+
+        return @values[name_s] if @values.key?(name_s) && args.empty?
+
+        super
+      end
+
+      READ_ONLY_ATTRIBUTES = %w[id type created_at updated_at].freeze
+
+      private
+
+      def read_only_attribute?(name)
+        return true if READ_ONLY_ATTRIBUTES.include?(name)
+
+        spec = attribute_spec(name)
+        spec ? spec.read_only : false
+      end
+
+      def update_from(parsed)
+        data = parsed.is_a?(Hash) ? parsed["data"] : nil
+        return unless data.is_a?(Hash)
+
+        @raw_data = data
+        @id   = data["id"] if data["id"]
+        @type = data["type"] if data["type"]
+        @meta = data["meta"] if data["meta"]
+        @values = {}
+        Array(data["attributes"]).each { |k, v| @values[k.to_s] = wrap_attribute(k, v) }
+        self
+      end
+
+      def unwrap(value)
+        case value
+        when APIObject then value.to_h
+        when Array     then value.map { |v| unwrap(v) }
+        else value
+        end
+      end
+    end
+  end
+end