octaspace 0.1.0

data/lib/octaspace/errors.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  # Base error class for all OctaSpace SDK errors
+  class Error < StandardError
+    attr_reader :response, :status, :request_id
+
+    def initialize(message = nil, response: nil)
+      @response = response
+      @status = response&.status
+      @request_id = response&.request_id
+      super(message || "OctaSpace API error")
+    end
+  end
+
+  # Raised when SDK is misconfigured (e.g., missing required gems for persistent mode)
+  class ConfigurationError < Error; end
+
+  # Network-level errors (before HTTP response is received)
+  class NetworkError < Error; end
+  class ConnectionError < NetworkError; end
+  class TimeoutError < NetworkError; end
+
+  # API-level errors (HTTP response received, but indicates failure)
+  class ApiError < Error; end
+
+  # 401 Unauthorized
+  class AuthenticationError < ApiError; end
+
+  # 403 Forbidden
+  class PermissionError < ApiError; end
+
+  # 404 Not Found
+  class NotFoundError < ApiError; end
+
+  # 422 Unprocessable Entity
+  class ValidationError < ApiError; end
+
+  # 429 Too Many Requests — includes Retry-After header value
+  class RateLimitError < ApiError
+    attr_reader :retry_after
+
+    def initialize(message = nil, response: nil)
+      @retry_after = response&.retry_after
+      super
+    end
+  end
+
+  # 5xx Server Errors
+  class ServerError < ApiError; end
+  class BadGatewayError < ServerError; end # 502
+  class ServiceUnavailableError < ServerError; end # 503
+  class GatewayTimeoutError < ServerError; end # 504
+
+  # HTTP status code → exception class mapping
+  STATUS_ERRORS = {
+    401 => AuthenticationError,
+    403 => PermissionError,
+    404 => NotFoundError,
+    422 => ValidationError,
+    429 => RateLimitError,
+    502 => BadGatewayError,
+    503 => ServiceUnavailableError,
+    504 => GatewayTimeoutError
+  }.freeze
+
+  # Build the appropriate error for a given Response
+  # @param response [OctaSpace::Response]
+  # @return [OctaSpace::ApiError] subclass instance
+  def self.error_for(response)
+    klass = STATUS_ERRORS.fetch(response.status) do
+      response.server_error? ? ServerError : ApiError
+    end
+    klass.new(response: response)
+  end
+end

data/lib/octaspace/middleware/url_rotator.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  module Middleware
+    # Thread-safe round-robin URL rotator with automatic failover
+    #
+    # When multiple base_urls are configured, requests are distributed
+    # across all healthy URLs. Failed URLs enter a cooldown period before
+    # being re-admitted to the rotation.
+    #
+    # @example
+    #   rotator = OctaSpace::Middleware::UrlRotator.new([
+    #     "https://api.octa.space",
+    #     "https://api2.octa.space"
+    #   ])
+    #
+    #   url = rotator.next_url
+    #   rotator.mark_failed(url)
+    #   rotator.stats # => { total: 2, available: 1, failed: ["https://api.octa.space"] }
+    class UrlRotator
+      # Seconds a failed URL is excluded from rotation
+      FAILURE_COOLDOWN = 30
+
+      # @param urls [Array<String>] ordered list of API base URLs
+      def initialize(urls)
+        @urls = urls.dup.freeze
+        @counter = 0
+        @failed = {}   # url => Time failed_at
+        @mutex = Mutex.new
+      end
+
+      # @return [String] next available URL (round-robin), falls back to first if all failed
+      def next_url
+        available = available_urls
+        return @urls.first if available.empty?
+
+        @mutex.synchronize do
+          idx = @counter % available.size
+          @counter += 1
+          available[idx]
+        end
+      end
+
+      # Mark a URL as temporarily failed
+      # @param url [String]
+      def mark_failed(url)
+        @mutex.synchronize { @failed[url] = Time.now }
+      end
+
+      # Mark a URL as recovered (remove from failed list)
+      # @param url [String]
+      def mark_success(url)
+        @mutex.synchronize { @failed.delete(url) }
+      end
+
+      # @return [Array<String>] currently healthy URLs (excluding cooldown)
+      def available_urls
+        now = Time.now
+        @mutex.synchronize do
+          @urls.reject do |url|
+            failed_at = @failed[url]
+            next false unless failed_at
+
+            if now - failed_at < FAILURE_COOLDOWN
+              true
+            else
+              @failed.delete(url)
+              false
+            end
+          end
+        end
+      end
+
+      # @return [Hash] diagnostic stats
+      def stats
+        {
+          total: @urls.size,
+          available: available_urls.size,
+          failed: @mutex.synchronize { @failed.keys }
+        }
+      end
+
+      # Reset state — useful in tests
+      def reset!
+        @mutex.synchronize do
+          @counter = 0
+          @failed.clear
+        end
+      end
+    end
+  end
+end

data/lib/octaspace/railtie.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  # Rails integration via Railtie
+  #
+  # Automatically loaded when Rails is present (see lib/octaspace.rb).
+  # Allows configuration via 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
+  class Railtie < ::Rails::Railtie
+    initializer "octaspace.configure" do
+      # No-op: users call OctaSpace.configure {} directly in their initializer.
+      # This hook exists for future extensions (e.g., auto-configure from credentials).
+    end
+
+    # Gracefully shut down the shared client's persistent connection pools
+    # when the Rails process stops. Only applies when keep_alive: true is used
+    # and the shared client (OctaSpace.client) has been accessed.
+    config.after_initialize do
+      at_exit { OctaSpace.shutdown_shared_client! }
+    end
+  end
+end

data/lib/octaspace/resources/accounts.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  module Resources
+    # Account-related API endpoints
+    #
+    # @example
+    #   client.accounts.profile
+    #   client.accounts.balance
+    class Accounts < Base
+      # Fetch the authenticated user's profile
+      # GET /accounts
+      # @return [OctaSpace::Response]
+      def profile
+        get("/accounts")
+      end
+
+      # Fetch the authenticated user's balance
+      # GET /accounts/balance
+      # @return [OctaSpace::Response]
+      def balance
+        get("/accounts/balance")
+      end
+
+      # Generate / create a new wallet for the authenticated user
+      # POST /accounts
+      # @return [OctaSpace::Response]
+      def generate_wallet
+        post("/accounts")
+      end
+    end
+  end
+end

data/lib/octaspace/resources/apps.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  module Resources
+    # Apps API endpoint
+    #
+    # @example
+    #   client.apps.list
+    class Apps < Base
+      # List available apps
+      # GET /apps
+      # @param params [Hash] optional filter params
+      # @return [OctaSpace::Response]
+      def list(**params)
+        get("/apps", params:)
+      end
+    end
+  end
+end

data/lib/octaspace/resources/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module OctaSpace
+  module Resources
+    # Base class for all API resource groups
+    #
+    # Delegates HTTP methods to the transport layer and provides
+    # a clean DSL for subclasses.
+    class Base
+      # @param transport [OctaSpace::Transport::Base]
+      def initialize(transport)
+        @transport = transport
+      end
+
+      private
+
+      attr_reader :transport
+
+      def get(path, **opts) = transport.get(path, **opts)
+      def post(path, **opts) = transport.post(path, **opts)
+      def put(path, **opts) = transport.put(path, **opts)
+      def patch(path, **opts) = transport.patch(path, **opts)
+      def delete(path, **opts) = transport.delete(path, **opts)
+
+      # Encode a single path segment to prevent path traversal
+      # @param segment [String, Integer]
+      # @return [String]
+      def encode(segment)
+        URI.encode_www_form_component(segment.to_s)
+      end
+    end
+  end
+end

data/lib/octaspace/resources/idle_jobs.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  module Resources
+    # Idle Jobs API endpoints
+    #
+    # Each idle job is identified by both a node ID and a job ID.
+    #
+    # @example
+    #   client.idle_jobs.find(node_id: 69, job_id: 42)
+    #   client.idle_jobs.logs(node_id: 69, job_id: 42)
+    class IdleJobs < Base
+      # Fetch a single idle job status
+      # GET /idle_jobs/:node_id/:job_id
+      # @param node_id [Integer, String]
+      # @param job_id [Integer, String]
+      # @return [OctaSpace::Response]
+      def find(node_id:, job_id:)
+        get("/idle_jobs/#{encode(node_id)}/#{encode(job_id)}")
+      end
+
+      # Fetch idle job logs
+      # GET /idle_jobs/:node_id/:job_id/logs
+      # @param node_id [Integer, String]
+      # @param job_id [Integer, String]
+      # @return [OctaSpace::Response]
+      def logs(node_id:, job_id:)
+        get("/idle_jobs/#{encode(node_id)}/#{encode(job_id)}/logs")
+      end
+    end
+  end
+end

data/lib/octaspace/resources/network.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  module Resources
+    # Network information endpoint
+    #
+    # @example
+    #   client.network.info
+    class Network < Base
+      # Fetch combined network information (blockchain, market, nodes, power, etc.)
+      # GET /network
+      # @return [OctaSpace::Response]
+      def info
+        get("/network")
+      end
+    end
+  end
+end

data/lib/octaspace/resources/nodes.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  module Resources
+    # Node-related API endpoints
+    #
+    # @example
+    #   client.nodes.list
+    #   client.nodes.find(123)
+    #   client.nodes.reboot(123)
+    #   client.nodes.update_prices(123, gpu_hour: 0.5, cpu_hour: 0.1)
+    class Nodes < Base
+      # List all nodes
+      # GET /nodes
+      # @param params [Hash] optional filter/pagination params
+      # @return [OctaSpace::Response]
+      def list(**params)
+        get("/nodes", params:)
+      end
+
+      # Fetch a single node by ID
+      # GET /nodes/:id
+      # @param id [Integer, String]
+      # @return [OctaSpace::Response]
+      def find(id)
+        get("/nodes/#{encode(id)}")
+      end
+
+      # Download node identity file (binary response)
+      # GET /nodes/:id/ident
+      # @param id [Integer, String]
+      # @return [OctaSpace::Response]
+      def download_ident(id)
+        get("/nodes/#{encode(id)}/ident")
+      end
+
+      # Download node logs (binary response)
+      # GET /nodes/:id/logs
+      # @param id [Integer, String]
+      # @return [OctaSpace::Response]
+      def download_logs(id)
+        get("/nodes/#{encode(id)}/logs")
+      end
+
+      # Update node pricing
+      # PATCH /nodes/:id/prices
+      # @param id [Integer, String]
+      # @param prices [Hash] e.g. { gpu_hour: 0.5, cpu_hour: 0.1 }
+      # @return [OctaSpace::Response]
+      def update_prices(id, **prices)
+        patch("/nodes/#{encode(id)}/prices", body: prices)
+      end
+
+      # Reboot a node
+      # GET /nodes/:id/reboot
+      # @param id [Integer, String]
+      # @return [OctaSpace::Response]
+      def reboot(id)
+        get("/nodes/#{encode(id)}/reboot")
+      end
+    end
+  end
+end

data/lib/octaspace/resources/services/machine_rental.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  module Resources
+    class Services
+      # Machine Rental (MR) service endpoints
+      #
+      # @example
+      #   client.services.mr.list
+      #   client.services.mr.create(
+      #     node_id: 123,
+      #     disk_size: 10,
+      #     image: "ubuntu:24.04",
+      #     app: "249b4cb3-3db1-4c06-98a4-772ba88cd81c"
+      #   )
+      class MachineRental < Base
+        # List available / active machine rentals
+        # GET /services/mr
+        # @param params [Hash] optional filter params
+        # @return [OctaSpace::Response]
+        def list(**params)
+          get("/services/mr", params:)
+        end
+
+        # Create (start) a machine rental
+        # POST /services/mr
+        # @param attrs [Hash] rental parameters
+        # @return [OctaSpace::Response]
+        def create(**attrs)
+          item = {
+            id: 0,
+            node_id: attrs.fetch(:node_id),
+            disk_size: attrs.fetch(:disk_size),
+            image: attrs.fetch(:image),
+            app: attrs[:app].to_s,
+            envs: attrs[:envs] || {},
+            ports: attrs[:ports] || [],
+            http_ports: attrs[:http_ports] || [],
+            start_command: attrs[:start_command].to_s,
+            entrypoint: attrs[:entrypoint].to_s
+          }
+
+          post("/services/mr", body: [item])
+        end
+      end
+    end
+  end
+end

data/lib/octaspace/resources/services/render.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  module Resources
+    class Services
+      # Render service endpoints
+      #
+      # @example
+      #   client.services.render.list
+      #   client.services.render.create(node_id: 123, disk_size: 100)
+      class Render < Base
+        # List render jobs
+        # GET /services/render
+        # @param params [Hash] optional filter params
+        # @return [OctaSpace::Response]
+        def list(**params)
+          get("/services/render", params:)
+        end
+
+        # Create (start) a render job
+        # POST /services/render
+        # @param attrs [Hash] render job parameters
+        # @return [OctaSpace::Response]
+        def create(**attrs)
+          post("/services/render", body: attrs)
+        end
+      end
+    end
+  end
+end

data/lib/octaspace/resources/services/session_proxy.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module OctaSpace
+  module Resources
+    class Services
+      # Proxy object for operations on a specific service session
+      #
+      # Obtained via: client.services.session("uuid")
+      #
+      # @example
+      #   session = client.services.session("abc-123")
+      #   session.info
+      #   session.logs
+      #   session.stop(score: 5)
+      class SessionProxy
+        # @param transport [OctaSpace::Transport::Base]
+        # @param uuid [String] session UUID
+        def initialize(transport, uuid)
+          @transport = transport
+          @uuid = URI.encode_www_form_component(uuid.to_s)
+        end
+
+        # Fetch session details
+        # GET /services/:uuid/info
+        # @return [OctaSpace::Response]
+        def info
+          @transport.get("/services/#{@uuid}/info")
+        end
+
+        # Fetch session logs
+        # GET /services/:uuid/logs
+        # @return [OctaSpace::Response]
+        def logs
+          @transport.get("/services/#{@uuid}/logs")
+        end
+
+        # Stop the session
+        # POST /services/:uuid/stop
+        # @param params [Hash] e.g. { score: 5 }
+        # @return [OctaSpace::Response]
+        def stop(**params)
+          @transport.post("/services/#{@uuid}/stop", body: params.empty? ? nil : params)
+        end
+      end
+    end
+  end
+end

data/lib/octaspace/resources/services/vpn.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  module Resources
+    class Services
+      # VPN service endpoints
+      #
+      # @example
+      #   client.services.vpn.list
+      #   client.services.vpn.create(node_id: 123)
+      class Vpn < Base
+        # List active VPN sessions
+        # GET /services/vpn
+        # @param params [Hash] optional filter params
+        # @return [OctaSpace::Response]
+        def list(**params)
+          get("/services/vpn", params:)
+        end
+
+        # Create (start) a VPN session
+        # POST /services/vpn
+        # @param attrs [Hash] VPN parameters
+        # @return [OctaSpace::Response]
+        def create(**attrs)
+          post("/services/vpn", body: attrs)
+        end
+      end
+    end
+  end
+end

data/lib/octaspace/resources/services.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  module Resources
+    # Services namespace — aggregates MR, VPN, Render subresources
+    # and provides the session proxy pattern
+    #
+    # @example
+    #   client.services.mr.list
+    #   client.services.vpn.create(node_id: 123)
+    #   client.services.render.create(node_id: 456, disk_size: 100)
+    #
+    #   # Session proxy pattern
+    #   client.services.session("uuid-123").info
+    #   client.services.session("uuid-123").stop(score: 5)
+    class Services < Base
+      attr_reader :mr, :vpn, :render
+
+      def initialize(transport)
+        super
+        @mr = Services::MachineRental.new(transport)
+        @vpn = Services::Vpn.new(transport)
+        @render = Services::Render.new(transport)
+      end
+
+      # Return a proxy object for operations on a specific session
+      # @param uuid [String] session UUID
+      # @return [OctaSpace::Resources::Services::SessionProxy]
+      def session(uuid)
+        Services::SessionProxy.new(transport, uuid)
+      end
+    end
+  end
+end
+
+require_relative "services/session_proxy"
+require_relative "services/machine_rental"
+require_relative "services/vpn"
+require_relative "services/render"

data/lib/octaspace/resources/sessions.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  module Resources
+    # Session listing endpoint
+    #
+    # For operations on a specific session (info/logs/stop),
+    # use the proxy pattern: client.services.session("uuid")
+    #
+    # @example
+    #   client.sessions.list
+    #   client.sessions.list(recent: true)
+    class Sessions < Base
+      # List all sessions
+      # GET /sessions
+      # @param params [Hash] optional filter params
+      # @return [OctaSpace::Response]
+      def list(**params)
+        get("/sessions", params:)
+      end
+    end
+  end
+end

data/lib/octaspace/response.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module OctaSpace
+  # Wraps a raw Faraday response, providing a stable SDK interface
+  class Response
+    attr_reader :status, :headers, :body, :data
+
+    # @param faraday_response [Faraday::Response]
+    def initialize(faraday_response)
+      @status = faraday_response.status
+      @headers = faraday_response.headers
+      @body = faraday_response.body
+      # Faraday :json middleware parses JSON body into a Hash/Array automatically
+      @data = faraday_response.body
+    end
+
+    # @return [Boolean] true for 2xx status codes
+    def success? = (200..299).cover?(status)
+
+    # @return [Boolean] true for 4xx status codes
+    def client_error? = (400..499).cover?(status)
+
+    # @return [Boolean] true for 5xx status codes
+    def server_error? = (500..599).cover?(status)
+
+    # @return [Boolean] true for any non-2xx error
+    def error? = client_error? || server_error?
+
+    # @return [String, nil] X-Request-Id header value
+    def request_id = headers["x-request-id"]
+
+    # @return [Integer, nil] Retry-After header value in seconds
+    def retry_after = headers["retry-after"]&.to_i
+
+    def to_s
+      "#<OctaSpace::Response status=#{status}>"
+    end
+    alias_method :inspect, :to_s
+  end
+end