Class: Turbopuffer::Client

Inherits:
Internal::Transport::BaseClient show all
Defined in:
lib/turbopuffer/client.rb

Constant Summary collapse

DEFAULT_MAX_RETRIES =

Default max number of retries to attempt after a failed retryable request.

4
DEFAULT_TIMEOUT_IN_SECONDS =

Default per-request timeout.

60.0
DEFAULT_INITIAL_RETRY_DELAY =

Default initial retry delay in seconds. Overall delay is calculated using exponential backoff + jitter.

0.3
DEFAULT_MAX_RETRY_DELAY =

Default max retry delay in seconds.

8.0

Constants inherited from Internal::Transport::BaseClient

Internal::Transport::BaseClient::MAX_REDIRECTS, Internal::Transport::BaseClient::PLATFORM_HEADERS

Instance Attribute Summary collapse

Attributes inherited from Internal::Transport::BaseClient

#base_url, #headers, #idempotency_header, #initial_retry_delay, #max_retries, #max_retry_delay, #requester, #timeout

Instance Method Summary collapse

Methods inherited from Internal::Transport::BaseClient

follow_redirect, #inspect, reap_connection!, #request, #send_request, should_retry?, validate!

Methods included from Internal::Util::SorbetRuntimeSupport

#const_missing, #define_sorbet_constant!, #sorbet_constant_defined?, #to_sorbet_type, to_sorbet_type

Constructor Details

#initialize(api_key: ENV["TURBOPUFFER_API_KEY"], region: ENV["TURBOPUFFER_REGION"], default_namespace: nil, base_url: ENV["TURBOPUFFER_BASE_URL"], max_retries: self.class::DEFAULT_MAX_RETRIES, timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS, initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY, max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY) ⇒ Client

Creates and returns a new client for interacting with the API.

‘“api.example.com/v2/”`. Defaults to `ENV`

Parameters:

  • api_key (String, nil) (defaults to: ENV["TURBOPUFFER_API_KEY"]) —

    API key used for authentication Defaults to ‘ENV`

  • region (String, nil) (defaults to: ENV["TURBOPUFFER_REGION"]) —

    The turbopuffer region to use. Defaults to ‘ENV`

  • default_namespace (String, nil) (defaults to: nil)
  • base_url (String, nil) (defaults to: ENV["TURBOPUFFER_BASE_URL"]) —

    Override the default base URL for the API, e.g.,

  • max_retries (Integer) (defaults to: self.class::DEFAULT_MAX_RETRIES) —

    Max number of retries to attempt after a failed retryable request.

  • timeout (Float) (defaults to: self.class::DEFAULT_TIMEOUT_IN_SECONDS)
  • initial_retry_delay (Float) (defaults to: self.class::DEFAULT_INITIAL_RETRY_DELAY)
  • max_retry_delay (Float) (defaults to: self.class::DEFAULT_MAX_RETRY_DELAY) 


92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/turbopuffer/client.rb', line 92

def initialize(
  api_key: ENV["TURBOPUFFER_API_KEY"],
  region: ENV["TURBOPUFFER_REGION"],
  default_namespace: nil,
  base_url: ENV["TURBOPUFFER_BASE_URL"],
  max_retries: self.class::DEFAULT_MAX_RETRIES,
  timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
  initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
  max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY
)
  base_url ||= "https://{region}.turbopuffer.com"

  if api_key.nil?
    raise ArgumentError.new("api_key is required, and can be set via environ: \"TURBOPUFFER_API_KEY\"")
  end

  if base_url.include?("{region}")
    if region.nil?
      raise ArgumentError.new("region is required when base_url contains {region} placeholder: #{base_url}")
    end
    base_url = base_url.gsub("{region}", region)
  elsif !region.nil?
    raise ArgumentError.new("region is set, but would be ignored (baseUrl does not contain {region} placeholder: #{base_url})")
  end

  @default_namespace = default_namespace&.to_s
  @api_key = api_key.to_s
  @region = region&.to_s

  super(
    base_url: base_url,
    timeout: timeout,
    max_retries: max_retries,
    initial_retry_delay: initial_retry_delay,
    max_retry_delay: max_retry_delay
  )
end

Instance Attribute Details

#api_key ⇒ String (readonly)

API key used for authentication

Returns:

  • (String) 


20
21
22
 
# File 'lib/turbopuffer/client.rb', line 20

def api_key
  @api_key
end

#default_namespace ⇒ String? (readonly)

Returns:

  • (String, nil) 


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

def default_namespace
  @default_namespace
end

#region ⇒ String? (readonly)

The turbopuffer region to use.

Returns:

  • (String, nil) 


24
25
26
 
# File 'lib/turbopuffer/client.rb', line 24

def region
  @region
end

Instance Method Details

#namespace(namespace) ⇒ Turbopuffer::Namespace

Creates a new namespace resource.

Parameters:

  • namespace (String) —

    The ID of the namespace.

Returns:



34
35
36
 
# File 'lib/turbopuffer/client.rb', line 34

def namespace(namespace)
  Turbopuffer::Namespace.new(self, namespace)
end

#namespaces(cursor: nil, page_size: nil, prefix: nil, request_options: {}) ⇒ Turbopuffer::Internal::NamespacePage<Turbopuffer::Models::NamespaceSummary>

List namespaces.

Parameters:

  • cursor (String) —

    Retrieve the next page of results.

  • page_size (Integer) —

    Limit the number of results per page.

  • prefix (String) —

    Retrieve only the namespaces that match the prefix.

  • request_options (Turbopuffer::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/turbopuffer/client.rb', line 53

def namespaces(params = {})
  parsed, options = Turbopuffer::ClientNamespacesParams.dump_request(params)
  request(
    method: :get,
    path: "v1/namespaces",
    query: parsed,
    page: Turbopuffer::Internal::NamespacePage,
    model: Turbopuffer::NamespaceSummary,
    options: options
  )
end