# Client

Create and configure the client, and read the metadata of every API response.

A `Synthient::Client` holds a pool of keep-alive connections and is safe to share between threads. Create one, reuse it for every request, and call `close` on shutdown. In a forking server, connections inherited from the parent process are never reused.

## new

`Synthient::Client.new` returns a client.

```ruby
def initialize: (?api_key: String?, ?base_url: String, ?max_retries: Integer, ?timeout: Numeric,
                 ?open_timeout: Numeric, ?user_agent: String?, ?response_hook: _ResponseHook?) -> void
```

```ruby
client = Synthient::Client.new(
  api_key: ENV.fetch("SYNTHIENT_API_KEY"),
  max_retries: 4,
  user_agent: "my-app/1.0"
)
at_exit { client.close }
```

- **Input:** A missing or blank API key, a key or `user_agent` that contains a line break, or an invalid option raises `ArgumentError`. An `api_key` that is not a `String`, or a `response_hook` that does not respond to `call`, raises `TypeError`.
- **Network:** It makes no network requests.

## Options

- `api_key` `String?` — The API key. The default is the `SYNTHIENT_API_KEY` environment variable. Surrounding whitespace is trimmed.
- `base_url` `String` — The API base URL, including the version path. The default is `Synthient::DEFAULT_BASE_URL`. It must be an `http` or `https` URL with a host and no query, fragment, or user info. A trailing slash is removed.
- `max_retries` `Integer` — How many times a failed request is retried after the first attempt. The default is `2`, and `0` disables retries. See [Retries and timeouts](https://docs.synthient.com/sdks/ruby/errors#retries-and-timeouts).
- `timeout` `Numeric` — Seconds to wait for each read or write. The default is `60`. It must be a positive, finite number.
- `open_timeout` `Numeric` — Seconds to wait for a connection. The default is `10`. It must be a positive, finite number.
- `user_agent` `String?` — Appended, such as `"my-app/1.2"`, to the `User-Agent` header, which starts with `synthient-ruby/` followed by the SDK version.
- `response_hook` `_ResponseHook?` — Any object with a `call` method, such as a lambda, which receives a `ResponseMetadata` for every API response. See [Response metadata](#response-metadata).

## close

Closes idle connections.

```ruby
def close: () -> nil
```

- **Idempotence:** It is idempotent.
- **Errors:** Requests made after `close` raise `IOError`.

## Constants

- `Synthient::DEFAULT_BASE_URL` `String` — `"https://api.synthient.com/api/v4"`, the base URL of the Synthient HTTP API.
- `Synthient::VERSION` `String` — The SDK version, such as `"1.0.0"`. It is sent in the `User-Agent` header.
- `Synthient::Client::MAX_BATCH_SIZE` `Integer` — `1000`, the most addresses `lookup_ips` accepts.

## Response metadata

The `response_hook:` option is called with a `ResponseMetadata` for every API response, before its body is read.

```ruby
interface _ResponseHook
  def call: (ResponseMetadata metadata) -> untyped
end
```

```ruby
hook = lambda do |meta|
  rate_limit = meta.rate_limit
  puts "#{meta.status} #{meta.request_id} #{rate_limit.remaining}/#{rate_limit.limit}" if rate_limit
end
client = Synthient::Client.new(response_hook: hook)
client.account
```

- **Coverage:** The hook sees retried attempts, export pages, stream handshakes, and responses that later fail to decode. Export downloads from storage are not reported.
- **Concurrency:** The hook runs on the thread that sent the request, so a hook on a shared client must be thread-safe.
- **Errors:** Exceptions the hook raises propagate to the caller.

### ResponseMetadata

- `status` `Integer` — The HTTP status code of the response.
- `request_id` `String?` — The `X-Request-Id` header.
- `rate_limit` `RateLimit?` — The rate limit that applies to the operation, or `nil` unless all three `RateLimit-*` headers are present and valid.
- `headers` `Hash[String, String]` — A frozen copy of the response headers with lowercase names. Headers can contain sensitive data, such as presigned download URLs.

### RateLimit

The state of an operation's rate limit, from the `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers. Limits are shared by every key of a team. See [Rate Limits](https://docs.synthient.com/rate-limits).

- `limit` `Integer` — The bucket size, which is the burst the operation allows.
- `remaining` `Integer` — The number of requests left in the bucket.
- `reset` `Integer` — The number of seconds until the window resets.