@callback close(conn()) :: :ok

Closes the connection. Must be idempotent — calling close/1 on an already-closed handle returns :ok.

@callback command(
  conn(),
  request :: iodata(),
  deadline_ms :: non_neg_integer(),
  opts :: command_opts()
) :: {:ok, binary()} | {:error, Aerospike.Error.t()}

Sends a pre-encoded request and returns the full reply bytes.

The request is expected to be complete wire bytes (proto header + body) produced by the command encoder. The reply is the full response payload; framing/parsing is the caller's responsibility.

deadline_ms is a per-socket-read deadline in milliseconds applied to each :gen_tcp.recv/3 call (header and body are read separately on passive {:packet, :raw} sockets; see Aerospike.Transport.Tcp). It is deliberately separate from the caller's total-operation budget: a slow node can blow its read deadline without the caller having to track a monotonic deadline manually. The caller remains responsible for the overall operation budget — the transport does not enforce it.

opts is a keyword list documented by command_opts/0.

Single request, single response — streaming and multi-frame replies (scan, query) are out of scope for this behaviour.

@callback command_stream(
  conn(),
  request :: iodata(),
  deadline_ms :: non_neg_integer(),
  opts :: command_opts()
) :: {:ok, binary()} | {:error, Aerospike.Error.t()}

Sends a pre-encoded request and reads a multi-frame reply through the terminal marker, returning the concatenated reply frames or bodies appropriate for opts[:message_type].

This seam exists for batch-style requests that still complete as one bounded command but arrive as multiple protocol frames. Unary callers must continue using command/4; long-lived incremental consumers should use the stream callbacks.

@callback connect(host :: String.t(), port :: :inet.port_number(), opts :: connect_opts()) ::
  {:ok, conn()} | {:error, Aerospike.Error.t()}

Opens a connection to host:port.

On success, returns an opaque connection handle suitable for passing to the other callbacks. On failure, returns an Aerospike.Error tagged with a transport-appropriate code (e.g. :connection_error, :timeout).

@callback info(conn(), commands :: [String.t()]) ::
  {:ok, %{required(String.t()) => String.t()}} | {:error, Aerospike.Error.t()}

Issues one info request containing commands and returns the parsed key/value map from the server's reply.

The single-round-trip shape matches the Aerospike info protocol: all commands ship in one request, all results come back in one response.

@callback login(conn(), opts :: login_opts()) ::
  {:ok, login_reply()} | {:error, Aerospike.Error.t()}

Runs the admin-protocol login (or session-token authenticate) handshake on an already-connected socket and returns the parsed reply.

Optional — transports that do not support authentication raise UndefinedFunctionError; callers that use this callback must ensure the configured transport implements it.

Opts:

• :user — username (required when :session_token is absent).
• :password — cleartext password (required when :session_token is absent; the transport hashes it as the server requires).
• :auth_mode — :internal, :external, or :pki.
• :session_token — when present, runs AUTHENTICATE instead of a fresh LOGIN. :user is still required.
• :login_timeout_ms — read deadline applied to the login reply. Transport-specific default.

@callback stream_close(stream()) :: :ok

Closes an open stream handle. Must be idempotent.

@callback stream_open(
  conn(),
  request :: iodata(),
  deadline_ms :: non_neg_integer(),
  opts :: stream_opts()
) :: {:ok, stream()} | {:error, Aerospike.Error.t()}

Opens a streaming request and returns an opaque handle for reading frames.

The transport owns the long-lived socket state and delivery mechanics; the caller owns any parsing of returned frames. The request bytes are already encoded when they reach the transport.

@callback stream_read(stream(), deadline_ms :: non_neg_integer()) ::
  {:ok, binary()} | :done | {:error, Aerospike.Error.t()}

Reads the next frame from an open stream.

Returns {:ok, frame} for a delivered frame, :done when the stream has reached end-of-stream, or {:error, error} for a transport-class failure.