Class: Oz::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/oz/client.rb

Overview

HTTP client for the Oz API.

client = Oz::Client.new(api_key: ENV["WARP_API_KEY"])
run = client.agent.run(prompt: "Fix the bug in auth.rb")
puts run.run_id

The API key defaults to the WARP_API_KEY environment variable and the base URL to OZ_API_BASE_URL (falling back to app.warp.dev/api/v1). Transient failures (timeouts, connection errors, HTTP 408/409/429/5xx) are retried automatically with exponential backoff.

Constant Summary collapse

INITIAL_RETRY_DELAY =

Initial backoff before the first retry, in seconds.

0.5
MAX_RETRY_DELAY =

Maximum backoff between retries, in seconds.

8.0
RETRYABLE_STATUSES =

Statuses (besides 5xx) that trigger an automatic retry.

[408, 409, 429].freeze

Instance Attribute Summary collapse

Low-level HTTP verbs collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, base_url: nil, timeout: nil, max_retries: nil, default_headers: nil, logger: nil, adapter: nil) ⇒ Client

Returns a new instance of Client.

Parameters:

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

    Bearer token (defaults to WARP_API_KEY)

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

    API base URL (defaults to OZ_API_BASE_URL)

  • timeout (Integer, Float, nil) (defaults to: nil) —

    per-request timeout in seconds

  • max_retries (Integer, nil) (defaults to: nil) —

    retries for transient failures

  • default_headers (Hash, nil) (defaults to: nil) —

    extra headers for every request

  • logger (Logger, nil) (defaults to: nil) —

    enables Faraday request/response logging

  • adapter (Symbol, nil) (defaults to: nil) —

    Faraday adapter (defaults to net_http)



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/oz/client.rb', line 36

def initialize(api_key: nil, base_url: nil, timeout: nil, max_retries: nil,
               default_headers: nil, logger: nil, adapter: nil)
  config = Oz.configuration
  @api_key = api_key || ENV.fetch('WARP_API_KEY', nil) || config.api_key
  @base_url = normalize_base_url(base_url || ENV.fetch('OZ_API_BASE_URL', nil) || config.base_url)
  @timeout = timeout || config.timeout
  @max_retries = max_retries || config.max_retries
  @logger = logger || config.logger
  @adapter = adapter || config.adapter || Faraday.default_adapter
  @default_headers = build_default_headers(default_headers || config.default_headers)

  if @api_key.nil? || @api_key.to_s.empty?
    raise AuthenticationError,
          'The api_key client option must be set either by passing api_key to the client ' \
          'or by setting the WARP_API_KEY environment variable'
  end

  @connection = build_connection
end

Instance Attribute Details

#api_key ⇒ Object (readonly)

Returns the value of attribute api_key.



27
28
29
 
# File 'lib/oz/client.rb', line 27

def api_key
  @api_key
end

#base_url ⇒ Object (readonly)

Returns the value of attribute base_url.



27
28
29
 
# File 'lib/oz/client.rb', line 27

def base_url
  @base_url
end

#default_headers ⇒ Object (readonly)

Returns the value of attribute default_headers.



27
28
29
 
# File 'lib/oz/client.rb', line 27

def default_headers
  @default_headers
end

#max_retries ⇒ Object (readonly)

Returns the value of attribute max_retries.



27
28
29
 
# File 'lib/oz/client.rb', line 27

def max_retries
  @max_retries
end

#timeout ⇒ Object (readonly)

Returns the value of attribute timeout.



27
28
29
 
# File 'lib/oz/client.rb', line 27

def timeout
  @timeout
end

Instance Method Details

#agent ⇒ Oz::Resources::Agent

Returns the agent resource and its sub-resources.

Returns:



57
58
59
 
# File 'lib/oz/client.rb', line 57

def agent
  @agent ||= Resources::Agent.new(self)
end

#delete(path, query: nil, headers: nil) ⇒ Object 



75
76
77
 
# File 'lib/oz/client.rb', line 75

def delete(path, query: nil, headers: nil)
  request(:delete, path, query: query, headers: headers)
end

#get(path, query: nil, headers: nil) ⇒ Object 



63
64
65
 
# File 'lib/oz/client.rb', line 63

def get(path, query: nil, headers: nil)
  request(:get, path, query: query, headers: headers)
end

#inspect ⇒ Object Also known as: to_s 



106
107
108
 
# File 'lib/oz/client.rb', line 106

def inspect
  "#<Oz::Client base_url=#{@base_url.inspect} timeout=#{@timeout} max_retries=#{@max_retries}>"
end

#post(path, body: nil, query: nil, headers: nil) ⇒ Object 



67
68
69
 
# File 'lib/oz/client.rb', line 67

def post(path, body: nil, query: nil, headers: nil)
  request(:post, path, body: body, query: query, headers: headers)
end

#put(path, body: nil, query: nil, headers: nil) ⇒ Object 



71
72
73
 
# File 'lib/oz/client.rb', line 71

def put(path, body: nil, query: nil, headers: nil)
  request(:put, path, body: body, query: query, headers: headers)
end

#request(method, path, body: nil, query: nil, headers: nil) ⇒ Object

Performs an HTTP request with automatic retries and returns the decoded response body (a Hash, Array, String, or nil for empty/204 responses).

Raises:

  • (Oz::APIError) —

    on transport failures and non-2xx responses.



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/oz/client.rb', line 84

def request(method, path, body: nil, query: nil, headers: nil)
  attempt = 0
  loop do
    attempt += 1
    begin
      response = execute(method, path, body, query, headers)
    rescue APIConnectionError
      raise if attempt > @max_retries

      sleep(retry_delay(attempt, nil))
      next
    end

    if should_retry?(response.status) && attempt <= @max_retries
      sleep(retry_delay(attempt, response))
      next
    end

    return process_response(response)
  end
end