octaspace 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9dd2b5c9ae96cbc0bef9e36fd492b2a1dbdcf53af596a82193986039ff8a4da9
+  data.tar.gz: b0f0a7a1a3301be4f3d1dbe33f60652fc5c9e4b36e709779076d374fb0e16ff4
+SHA512:
+  metadata.gz: 59cb1140ec7e34939b2535857d4d7afd395b8b25d45ac69df2c14c524bd1e14503f969704299fe6aa3d51021fa2491a8f00d0cf4dee3a3d848308a9aa9fb577d
+  data.tar.gz: 6b4353b1524bae1e594ef4109a93a371e539d48b157dcdd4e165a1283c60e4a86e719818f62276d3cac2628e4bf9cd419b651f5a4633302d391e3d5fc41f476d

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+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).
+
+## [0.1.0] - 2026-04-12
+
+### Added
+
+- Initial release of the official OctaSpace Ruby SDK.
+- Support for core resources: Accounts, Nodes, Sessions, Apps, Network, and Idle Jobs.
+- Resource-oriented client: `client.nodes.list`, `client.services.session(uuid).stop`.
+- Persistent HTTP connections (keep-alive mode) via `ConnectionPool`.
+- Automatic URL rotation and failover for high availability.
+- Retry with exponential backoff and jitter for transient errors.
+- Typed error hierarchy based on HTTP status codes.
+- Rails integration with automatic client sharing and graceful shutdown.
+- Interactive Playground app for manual testing and diagnostics.
+
+[0.1.0]: https://github.com/octaspace/ruby-sdk/compare/v0.1.0...HEAD

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2024-present OctaSpace
+
+MIT License
+
+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,336 @@
+# octaspace
+
+[![Gem Version](https://img.shields.io/gem/v/octaspace)](https://rubygems.org/gems/octaspace)
+[![CI](https://github.com/octaspace/ruby-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/octaspace/ruby-sdk/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](MIT-LICENSE)
+
+Official Ruby SDK for the [OctaSpace API](https://api.octa.space/api-docs).
+
+## Features
+
+- **Resource-oriented API** — `client.nodes.list`, `client.services.session(uuid).stop`
+- **Keep-alive mode** — persistent connections via `faraday-net_http_persistent` + `connection_pool`
+- **URL rotation / failover** — round-robin across multiple endpoints with per-URL cooldown
+- **Retry with exponential backoff + jitter** — configurable retries on transient failures
+- **Typed error hierarchy** — 12 exception classes mapped from HTTP status codes
+- **`on_request` / `on_response` hooks** — for logging, tracing, APM
+- **Rails integration** — Railtie, shared client, graceful shutdown at_exit
+- **Playground app** — `bin/playground` with live diagnostics page
+- **Ruby ≥ 3.2**, Rails 7.1 / 7.2 / 8.0
+
+## Installation
+
+```ruby
+# Gemfile
+gem "octaspace"
+
+# Optional — required for keep_alive: true
+gem "faraday-net_http_persistent"
+gem "connection_pool"
+```
+
+```ruby
+bundle install
+```
+
+## Quick Start
+
+```ruby
+require "octaspace"
+
+# Public endpoints (no API key required)
+client = OctaSpace::Client.new
+client.network.info                                    # GET /network
+
+# Authenticated endpoints
+client = OctaSpace::Client.new(api_key: ENV["OCTA_API_KEY"])
+
+# Accounts
+client.accounts.profile   # GET /accounts
+client.accounts.balance   # GET /accounts/balance
+
+# Nodes
+client.nodes.list                                      # GET /nodes
+client.nodes.find(123)                                 # GET /nodes/:id
+client.nodes.reboot(123)                               # GET /nodes/:id/reboot
+client.nodes.update_prices(123, gpu_hour: 0.5)         # PATCH /nodes/:id/prices
+
+# Sessions (list)
+client.sessions.list                                   # GET /sessions
+
+# Session proxy — operations on a specific session
+session = client.services.session("uuid-here")
+session.info                    # GET /services/:uuid/info
+session.logs                    # GET /services/:uuid/logs
+session.stop(score: 5)          # POST /services/:uuid/stop
+
+# Services
+client.services.mr.list                                # GET /services/mr
+client.services.mr.create(
+  node_id: 1,
+  disk_size: 10,
+  image: "ubuntu:24.04",
+  app: "249b4cb3-3db1-4c06-98a4-772ba88cd81c"
+)                                                     # POST /services/mr
+client.services.vpn.list                               # GET /services/vpn
+client.services.vpn.create(node_id: 1, subkind: "wg") # POST /services/vpn
+client.services.render.list                            # GET /services/render
+client.services.render.create(node_id: 1, disk_size: 100) # POST /services/render
+
+# Apps
+client.apps.list                                       # GET /apps
+
+# Network
+client.network.info                                    # GET /network
+
+# Idle Jobs
+client.idle_jobs.find(node_id: 69, job_id: 42)        # GET /idle_jobs/:node_id/:job_id
+client.idle_jobs.logs(node_id: 69, job_id: 42)        # GET /idle_jobs/:node_id/:job_id/logs
+```
+
+## Rails Integration
+
+### Initializer
+
+```ruby
+# config/initializers/octaspace.rb
+OctaSpace.configure do |config|
+  config.api_key    = ENV["OCTA_API_KEY"]
+  config.keep_alive = true
+  config.pool_size  = ENV.fetch("RAILS_MAX_THREADS", 5).to_i
+  config.logger     = Rails.logger
+end
+```
+
+### Shared client
+
+`OctaSpace.client` (called without arguments) returns a **lazily-initialized shared client** built from global configuration. It is safe to call it on every request:
+
+```ruby
+# app/controllers/application_controller.rb
+def octa_client
+  OctaSpace.client   # returns the same instance each time — no new connections
+end
+```
+
+Pass arguments to create a **one-off client** instead (e.g., for per-user API keys):
+
+```ruby
+OctaSpace.client(api_key: current_user.octa_api_key)   # new client, not cached
+```
+
+### Graceful shutdown
+
+The Railtie registers an `at_exit` hook that automatically shuts down the shared client's connection pool when the Rails process stops. No manual cleanup needed.
+
+## Configuration Reference
+
+| Option | Default | Description |
+|---|---|---|
+| `api_key` | `nil` | API key sent as `Authorization` header (optional for public endpoints) |
+| `base_url` | `https://api.octa.space` | Single API endpoint |
+| `base_urls` | `nil` | Multiple endpoints — enables URL rotation |
+| `keep_alive` | `false` | Persistent HTTP connections + pool |
+| `pool_size` | `5` | Connection pool size (keep-alive mode) |
+| `pool_timeout` | `5` | Seconds to wait for a pool slot |
+| `idle_timeout` | `60` | Seconds before an idle connection closes |
+| `open_timeout` | `10` | Seconds to open TCP connection |
+| `read_timeout` | `30` | Seconds to read response |
+| `write_timeout` | `30` | Seconds to write request body |
+| `max_retries` | `2` | Retry attempts on transient failures |
+| `retry_interval` | `0.5` | Base retry interval in seconds |
+| `backoff_factor` | `2.0` | Exponential backoff multiplier |
+| `ssl_verify` | `true` | Verify SSL certificates |
+| `on_request` | `nil` | `callable(req_hash)` — before each request |
+| `on_response` | `nil` | `callable(response)` — after each response |
+| `logger` | `nil` | Ruby `Logger` instance |
+| `log_level` | `:info` | Log level |
+| `user_agent` | auto | `User-Agent` header value |
+
+`persistent` is an alias for `keep_alive` for compatibility with Cube internals.
+
+## Keep-Alive Mode
+
+Requires `faraday-net_http_persistent` and `connection_pool` in your Gemfile.
+
+```ruby
+client = OctaSpace::Client.new(
+  api_key:      ENV["OCTA_API_KEY"],
+  keep_alive:   true,
+  pool_size:    ENV.fetch("RAILS_MAX_THREADS", 5).to_i,
+  idle_timeout: 120
+)
+
+# Diagnostics
+client.transport_stats
+# => { mode: :persistent, pools: { "https://api.octa.space" => { size: 5, available: 4 } } }
+
+# Explicit shutdown (optional — Railtie does this automatically in Rails)
+client.shutdown
+```
+
+## URL Rotation / Failover
+
+```ruby
+client = OctaSpace::Client.new(
+  api_key:   ENV["OCTA_API_KEY"],
+  base_urls: ["https://api.octa.space", "https://api2.octa.space"]
+)
+```
+
+- Requests are distributed round-robin across healthy endpoints.
+- If an endpoint raises a connection or timeout error, it enters a **30-second cooldown** and traffic shifts to the remaining endpoints.
+- After cooldown, the endpoint is re-admitted automatically.
+
+## Hooks
+
+```ruby
+OctaSpace.configure do |config|
+  config.on_request  = ->(req)  { Rails.logger.debug "→ #{req[:method].upcase} #{req[:path]}" }
+  config.on_response = ->(resp) { Rails.logger.debug "← #{resp.status} (#{resp.request_id})" }
+end
+```
+
+`on_request` receives `{ method:, path:, params: }`.
+`on_response` receives an `OctaSpace::Response` instance.
+
+## Error Handling
+
+```ruby
+begin
+  client.nodes.find(999_999)
+rescue OctaSpace::NotFoundError => e
+  puts "Not found — request_id: #{e.request_id}"
+rescue OctaSpace::AuthenticationError
+  puts "Invalid API key"
+rescue OctaSpace::RateLimitError => e
+  sleep e.retry_after
+  retry
+rescue OctaSpace::ConnectionError, OctaSpace::TimeoutError => e
+  puts "Network error: #{e.message}"
+rescue OctaSpace::Error => e
+  puts "API error #{e.status}: #{e.message}"
+end
+```
+
+### Error hierarchy
+
+```
+OctaSpace::Error
+├── ConfigurationError          — missing gems, invalid config
+├── NetworkError                — no HTTP response received
+│   ├── ConnectionError         — TCP connection refused / failed
+│   └── TimeoutError            — open/read timeout
+└── ApiError                    — HTTP response received with error status
+    ├── AuthenticationError     401
+    ├── PermissionError         403
+    ├── NotFoundError           404
+    ├── ValidationError         422
+    ├── RateLimitError          429  → #retry_after (seconds)
+    └── ServerError             5xx
+        ├── BadGatewayError     502
+        ├── ServiceUnavailableError  503
+        └── GatewayTimeoutError 504
+```
+
+All `ApiError` subclasses expose:
+
+- `#status` — HTTP status code
+- `#request_id` — value of `X-Request-Id` response header
+- `#response` — the raw `OctaSpace::Response` object
+
+## Types (Value Objects)
+
+The `OctaSpace::Types` namespace provides immutable `Data.define` value objects for domain entities. They are **not** returned by default — resources return raw `response.data` (Hash/Array). Use them explicitly when you want structured objects:
+
+```ruby
+response = client.nodes.find(123)
+node = OctaSpace::Types::Node.new(**response.data.transform_keys(&:to_sym))
+
+node.online?   # => true / false
+node.state     # => "online"
+node.id        # => 123
+```
+
+Available types: `Node`, `Account`, `Balance`, `Session`.
+
+## Playground App
+
+Interactive demo for manual testing against a real API key:
+
+```bash
+OCTA_API_KEY=your_key bin/playground
+# → http://localhost:3000
+```
+
+Pages:
+
+| Route | Content |
+|---|---|
+| `/playground/account` | Profile + balance |
+| `/playground/nodes` | Node list with state badges |
+| `/playground/sessions` | Active sessions |
+| `/playground/services` | Machine Rentals + VPN sessions |
+| `/playground/diagnostics` | Transport mode, pool stats, URL rotator state (auto-refresh every 5s) |
+
+## Development
+
+### Gem Development
+
+```bash
+bin/console            # IRB with gem loaded
+bundle exec standardrb  # lint (StandardRB)
+bundle exec rake test   # tests only
+```
+
+### Local Standalone Testing
+
+You can verify the gem in a clean Ruby environment without Rails:
+
+1. Build the gem: `gem build octaspace.gemspec`
+2. Install it locally: `gem install ./octaspace-0.1.0.gem`
+3. Test in IRB:
+
+```ruby
+irb
+> require 'octaspace'
+> client = OctaSpace::Client.new # Test public endpoints
+> client.network.info
+> client_auth = OctaSpace::Client.new(api_key: "token")  # Test authenticated client
+> client_auth.accounts.profile.data # Retrieving profile data (email, ID, etc.)
+```
+
+### Running tests against multiple Rails versions
+
+```bash
+bundle exec appraisal rails-7-1 rake test
+bundle exec appraisal rails-7-2 rake test
+bundle exec appraisal rails-8-0 rake test
+```
+
+### Dummy Application (Playground)
+
+The repository includes a Rails "Dummy" application for manual testing and UI prototyping. It is located in `test/dummy`.`.
+
+To run the dummy app:
+
+1. Ensure you have an API key: `export OCTA_API_KEY=your_key`
+2. Run the playground script: `bin/playground` (starts Puma on port 3000)
+3. Visit `http://localhost:3000/playground/diagnostics`
+
+You can also run it manually from the directory:
+
+```bash
+cd test/dummy
+bin/rails server
+```
+
+The dummy app is configured to use the local version of the gem. It is **not** included in the published gem package.
+
+## Packaging and Publishing
+
+See [PUBLISHING.md](PUBLISHING.md) for instructions on how to package and release new versions of the gem.
+
+## License
+
+[MIT](MIT-LICENSE) © OctaSpace Team

data/lib/octaspace/client.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  # Main entry point for the OctaSpace SDK
+  #
+  # Aggregates all resource groups and constructs the appropriate
+  # HTTP transport based on configuration.
+  #
+  # @example Standard mode (default)
+  #   client = OctaSpace::Client.new(api_key: ENV["OCTA_API_KEY"])
+  #   client.nodes.list
+  #   client.accounts.balance
+  #
+  # @example Keep-alive mode (persistent connections + pool)
+  #   client = OctaSpace::Client.new(
+  #     api_key:    ENV["OCTA_API_KEY"],
+  #     keep_alive: true,
+  #     pool_size:  ENV.fetch("RAILS_MAX_THREADS", 5).to_i
+  #   )
+  #
+  # @example Multiple API endpoints with failover
+  #   client = OctaSpace::Client.new(
+  #     api_key:   ENV["OCTA_API_KEY"],
+  #     base_urls: ["https://api.octa.space", "https://api2.octa.space"]
+  #   )
+  #
+  # @example Without API key (public endpoints only)
+  #   client = OctaSpace::Client.new
+  #   client.network.info
+  #
+  # @example With hooks
+  #   client = OctaSpace::Client.new(
+  #     api_key:     ENV["OCTA_API_KEY"],
+  #     on_request:  ->(req)  { puts "→ #{req[:method].upcase} #{req[:path]}" },
+  #     on_response: ->(resp) { puts "← #{resp.status}" }
+  #   )
+  class Client
+    attr_reader :accounts, :nodes, :sessions, :apps,
+      :network, :services, :idle_jobs
+
+    # @param api_key [String, nil] API key for authentication (optional for public endpoints)
+    # @param opts [Hash] Per-instance configuration overrides.
+    #   Any attribute from OctaSpace::Configuration can be passed here.
+    def initialize(api_key: nil, transport: nil, **opts)
+      @config = build_config(api_key, opts)
+      @transport = transport || build_transport
+      @accounts = Resources::Accounts.new(@transport)
+      @nodes = Resources::Nodes.new(@transport)
+      @sessions = Resources::Sessions.new(@transport)
+      @apps = Resources::Apps.new(@transport)
+      @network = Resources::Network.new(@transport)
+      @services = Resources::Services.new(@transport)
+      @idle_jobs = Resources::IdleJobs.new(@transport)
+    end
+
+    # Shut down persistent connections (only relevant in keep_alive mode)
+    def shutdown
+      @transport.respond_to?(:shutdown) && @transport.shutdown
+    end
+
+    # Transport diagnostics (pool stats when in keep_alive mode)
+    # @return [Hash]
+    def transport_stats
+      if @transport.respond_to?(:transport_stats)
+        @transport.transport_stats
+      elsif @transport.respond_to?(:pool_stats)
+        {mode: :persistent, pools: @transport.pool_stats}
+      elsif @config.urls.size > 1
+        {mode: :standard, rotator: @transport.instance_variable_get(:@rotator)&.stats}
+      else
+        {mode: :standard, url: @config.urls.first}
+      end
+    end
+
+    private
+
+    # Merge global config with per-instance overrides
+    def build_config(api_key, overrides)
+      cfg = OctaSpace.configuration.dup
+      cfg.api_key = api_key
+      overrides.each do |key, value|
+        cfg.public_send(:"#{key}=", value) if cfg.respond_to?(:"#{key}=")
+      end
+      cfg
+    end
+
+    def build_transport
+      if @config.keep_alive?
+        require_persistent_transport!
+        Transport::PersistentTransport.new(@config)
+      else
+        Transport::FaradayTransport.new(@config)
+      end
+    end
+
+    def require_persistent_transport!
+      require "faraday/net_http_persistent"
+      require "connection_pool"
+      require "octaspace/transport/persistent_transport"
+    rescue LoadError => e
+      raise ConfigurationError,
+        "keep_alive: true requires the following gems.\n" \
+        "Add to your Gemfile:\n" \
+        "  gem 'faraday-net_http_persistent'\n" \
+        "  gem 'connection_pool'\n\n" \
+        "Original error: #{e.message}"
+    end
+  end
+end

data/lib/octaspace/configuration.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  # Global and per-client configuration for the OctaSpace SDK
+  #
+  # @example Global configuration (Rails initializer)
+  #   OctaSpace.configure do |config|
+  #     config.api_key    = ENV["OCTA_API_KEY"]
+  #     config.keep_alive = true
+  #     config.pool_size  = ENV.fetch("RAILS_MAX_THREADS", 5).to_i
+  #     config.logger     = Rails.logger
+  #   end
+  class Configuration
+    # --- Authentication ---
+
+    # @return [String, nil] API key for Authorization header
+    attr_accessor :api_key
+
+    # --- Connection ---
+
+    # @return [String] Base URL for the API (single endpoint)
+    attr_accessor :base_url
+
+    # @return [Array<String>, nil] Multiple API endpoints — enables URL rotation/failover
+    attr_accessor :base_urls
+
+    # @return [Integer] Seconds to wait for connection to open
+    attr_accessor :open_timeout
+
+    # @return [Integer] Seconds to wait for a response
+    attr_accessor :read_timeout
+
+    # @return [Integer] Seconds to wait when writing request body
+    attr_accessor :write_timeout
+
+    # --- Keep-Alive / Persistent connections ---
+    # Requires: gem "faraday-net_http_persistent" and gem "connection_pool"
+
+    # @return [Boolean] Enable persistent HTTP connections with connection pooling
+    attr_accessor :keep_alive
+
+    # @return [Integer] Number of persistent connections in the pool
+    attr_accessor :pool_size
+
+    # @return [Integer] Seconds to wait for a connection from the pool
+    attr_accessor :pool_timeout
+
+    # @return [Integer] Seconds before an idle persistent connection is closed
+    attr_accessor :idle_timeout
+
+    # --- Retry ---
+
+    # @return [Integer] Maximum number of retries on transient failures
+    attr_accessor :max_retries
+
+    # @return [Float] Base interval in seconds between retries
+    attr_accessor :retry_interval
+
+    # @return [Float] Exponential backoff multiplier
+    attr_accessor :backoff_factor
+
+    # --- Hooks ---
+
+    # @return [#call, nil] Callable invoked before each request; receives request context hash
+    attr_accessor :on_request
+
+    # @return [#call, nil] Callable invoked after each response; receives OctaSpace::Response
+    attr_accessor :on_response
+
+    # --- Logging ---
+
+    # @return [Logger, nil] Ruby Logger instance (or any object responding to #debug/#info/#warn/#error)
+    attr_accessor :logger
+
+    # @return [Symbol] Log level (:debug, :info, :warn, :error)
+    attr_accessor :log_level
+
+    # --- SSL ---
+
+    # @return [Boolean] Verify SSL certificates (set false only in development/test)
+    attr_accessor :ssl_verify
+
+    # --- Identity ---
+
+    # @return [String] User-Agent header value
+    attr_accessor :user_agent
+
+    DEFAULTS = {
+      base_url: "https://api.octa.space",
+      open_timeout: 10,
+      read_timeout: 30,
+      write_timeout: 30,
+      keep_alive: false,
+      pool_size: 5,
+      pool_timeout: 5,
+      idle_timeout: 60,
+      max_retries: 2,
+      retry_interval: 0.5,
+      backoff_factor: 2.0,
+      ssl_verify: true,
+      log_level: :info
+    }.freeze
+
+    def initialize
+      DEFAULTS.each { |k, v| public_send(:"#{k}=", v) }
+      @user_agent = "octaspace-ruby/#{OctaSpace::VERSION} Ruby/#{RUBY_VERSION}"
+    end
+
+    # Alias: `persistent` is the Cube-internal term; `keep_alive` is the public SDK term
+    alias_method :persistent, :keep_alive
+    alias_method :persistent=, :keep_alive=
+
+    # @return [Boolean]
+    def keep_alive? = !!keep_alive
+
+    # Returns effective list of API URLs.
+    # base_urls takes priority over base_url; always returns an Array.
+    # @return [Array<String>]
+    def urls
+      candidates = Array(base_urls).map(&:to_s).reject(&:empty?)
+      candidates.empty? ? Array(base_url).map(&:to_s).reject(&:empty?) : candidates
+    end
+
+    # Deep-clone configuration for per-client overrides
+    # @return [Configuration]
+    def dup
+      copy = self.class.new
+      instance_variables.each do |var|
+        copy.instance_variable_set(var, instance_variable_get(var).dup)
+      rescue TypeError
+        copy.instance_variable_set(var, instance_variable_get(var))
+      end
+      copy
+    end
+  end
+end