Module: OctaSpace

Defined in:
lib/octaspace.rb,
lib/octaspace/client.rb,
lib/octaspace/errors.rb,
lib/octaspace/railtie.rb,
lib/octaspace/version.rb,
lib/octaspace/response.rb,
lib/octaspace/types/node.rb,
lib/octaspace/configuration.rb,
lib/octaspace/types/account.rb,
lib/octaspace/types/balance.rb,
lib/octaspace/types/session.rb,
lib/octaspace/resources/apps.rb,
lib/octaspace/resources/base.rb,
lib/octaspace/transport/base.rb,
lib/octaspace/payload_helpers.rb,
lib/octaspace/resources/nodes.rb,
lib/octaspace/resources/network.rb,
lib/octaspace/resources/accounts.rb,
lib/octaspace/resources/services.rb,
lib/octaspace/resources/sessions.rb,
lib/octaspace/resources/idle_jobs.rb,
lib/octaspace/middleware/url_rotator.rb,
lib/octaspace/resources/services/vpn.rb,
lib/octaspace/resources/services/render.rb,
lib/octaspace/transport/faraday_transport.rb,
lib/octaspace/transport/persistent_transport.rb,
lib/octaspace/resources/services/session_proxy.rb,
lib/octaspace/resources/services/machine_rental.rb

Overview

OctaSpace Ruby SDK

Official Ruby client for the OctaSpace API. Supports standard and keep-alive (persistent) connection modes, automatic URL rotation/failover, retry with exponential backoff, and optional Rails integration.

Examples:

Quick start

OctaSpace.configure do |config|
  config.api_key = ENV["OCTA_API_KEY"]
end

client = OctaSpace.client
client.nodes.list
client.accounts.balance

See Also:

Defined Under Namespace

Modules: Middleware, PayloadHelpers, Resources, Transport, Types Classes: ApiError, AuthenticationError, BadGatewayError, Client, Configuration, ConfigurationError, ConnectionError, Error, GatewayTimeoutError, NetworkError, NotFoundError, PermissionError, ProvisionRejectedError, Railtie, RateLimitError, Response, ServerError, ServiceUnavailableError, TimeoutError, ValidationError

Constant Summary collapse

STATUS_ERRORS =

HTTP status code → exception class mapping

{
  401 => AuthenticationError,
  403 => PermissionError,
  404 => NotFoundError,
  422 => ValidationError,
  429 => RateLimitError,
  502 => BadGatewayError,
  503 => ServiceUnavailableError,
  504 => GatewayTimeoutError
}.freeze
VERSION = 
"0.2.0"

Class Method Summary collapse

Class Method Details

.client(api_key: nil, **opts) ⇒ OctaSpace::Client

Shared client lazily built from global configuration. Re-used across calls when no overrides are given — suitable for Rails controllers that call OctaSpace.client on every request. Passing api_key or any override creates a one-off client instead.

Parameters:

  • api_key (String, nil) (defaults to: nil) —

    override api_key for this call only

  • opts (Hash) —

    additional per-client configuration overrides

Returns:



77
78
79
80
81
82
83
 
# File 'lib/octaspace.rb', line 77

def client(api_key: nil, **opts)
  if api_key.nil? && opts.empty?
    @shared_client ||= Client.new(api_key: configuration.api_key)
  else
    Client.new(api_key: api_key || configuration.api_key, **opts)
  end
end

.configuration ⇒ OctaSpace::Configuration

Global configuration object

Returns:



46
47
48
 
# File 'lib/octaspace.rb', line 46

def configuration
  @configuration ||= Configuration.new
end

.configure {|OctaSpace::Configuration| ... } ⇒ Object

Configure the SDK globally

Examples:

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
end

Yields:



59
60
61
 
# File 'lib/octaspace.rb', line 59

def configure
  yield configuration
end

.error_for(response) ⇒ OctaSpace::ApiError

Build the appropriate error for a given Response

Parameters:

Returns:



96
97
98
99
100
101
 
# File 'lib/octaspace/errors.rb', line 96

def self.error_for(response)
  klass = STATUS_ERRORS.fetch(response.status) do
    response.server_error? ? ServerError : ApiError
  end
  klass.new(response: response)
end

.reset_configuration! ⇒ Object

Reset global configuration to defaults (useful in tests)



64
65
66
67
 
# File 'lib/octaspace.rb', line 64

def reset_configuration!
  @configuration = Configuration.new
  @shared_client = nil
end

.shutdown_shared_client! ⇒ Object

Gracefully shut down the shared client’s persistent connections. Called automatically by the Railtie at_exit hook when Rails stops.



87
88
89
90
 
# File 'lib/octaspace.rb', line 87

def shutdown_shared_client!
  @shared_client&.shutdown
  @shared_client = nil
end