-spec activate(conn()) -> ok | {error, error()}.

Ask for the next bytes to arrive as a message instead of a read.

{active, once} on the socket, so exactly one message arrives and the owner asks again. That is the arrangement a process which has to wait for the server without a query outstanding needs - LISTEN is the only one there is - because next/1 blocks, and a process blocked in a read answers nothing else.

The connection is unusable for next/1 until the messages stop coming, and the two must not be mixed on one connection.

-spec age(conn()) -> non_neg_integer().

How long this connection has been open, in milliseconds.

For a pool deciding whether to keep lending it. A connection to PostgreSQL itself can live for months; one that goes through a proxy, a load balancer or a NAT is on a clock somebody else set, and finding out where that clock ran out by having a query fail is the expensive way.

-spec backend_key(conn()) -> key() | undefined.

The key cancel/1 needs, for a caller that wants to cancel from elsewhere.

-spec cancel(conn()) -> ok | {error, error()}.

Ask the server to cancel whatever this connection is running.

Opens a second connection to the same server, sends CancelRequest and closes it. No answer is defined by the protocol: the server either cancels the query or does not, and this connection finds out by reading what its query returned.

-spec channel_binding(conn()) -> binary() | undefined.

The tls-server-end-point binding data for this connection, or undefined.

The hash of the server's certificate, taken with the hash the certificate was signed with, which is what RFC 5929 defines and what PostgreSQL computes on its side. SHA-1 and MD5 signatures are hashed with SHA-256 instead, because the binding must not be weaker than the mechanism it is bound to.

There is nothing to bind to on a plain socket, so it is undefined there.

-spec claim(conn()) -> {binary() | undefined, conn()}.

Take the next statement name this connection has room for, or undefined.

Names never repeat, even after forget/2, because the statement a forgotten name refers to may still be parsed on the server, and parsing a second one under the same name is an error rather than a replacement.

-spec close(conn()) -> ok.

Close a connection.

Terminate is sent first so the server tears the backend down rather than discovering a closed socket, and a failure to send it is not reported: the socket is being closed either way.

-spec connect(opts()) -> {ok, conn()} | {error, error()}.

Open a connection and complete the opening exchange.

Answers once the server has sent ReadyForQuery, so a connection that is returned is one that can be used, not merely one that is open.

Raises error({minato_auth, _}) for a server that asks for something it cannot be answered with, and error({minato_scram, _}) for a server that fails to prove itself. The socket is closed before either is re-raised.

{ok, Conn} = minato_conn:connect(#{user => ~"minato", password => ~"minato",
                                   database => ~"minato_test"}).

-spec deactivate(conn()) -> {ok, conn()} | {error, error()}.

Go back to reading, after activate/1.

{active, false} on the socket, and then whatever the socket already delivered to the mailbox is taken back into the buffer, because those bytes have left the socket and next/1 would otherwise wait for bytes it already has. A connection that has been switched back can be read with next/1 as usual.

-spec deadline(conn(), timeout()) -> conn().

Give the statement that runs next this long, then cancel it.

A read timeout on its own can only end the wait, not the statement: the server carries on running the query, and the connection is left with an answer coming that nobody is reading, which makes it fit for closing and nothing else. A deadline sends CancelRequest when it expires and then goes on reading, so what arrives is the server's own 57014 and the ReadyForQuery after it. A cancelled statement therefore comes back as an ordinary failed statement with the connection still usable, which is the difference between a slow query costing one query and costing a connection.

The cancelled statement gets cancel_timeout to acknowledge it. A server that does not answer even that has stopped talking, and the connection really is finished: {error, {socket, timeout}}, with no connection handed back.

It lasts until it is cleared with infinity, which the query layer does before handing a connection back, so a deadline belongs to one call rather than to the connection. It covers everything that call does, including the Describe round trip a first-time statement needs, because a caller asking for 300 milliseconds means the answer, not one leg of it.

-spec decoding(conn(), minato_protocol:decoder() | undefined) -> conn().

Decode data rows as they are framed, with Decoder, or stop doing so.

A result set arrives as a run of DataRow messages, and framing them into a list only for the layer above to walk that list again costs an allocation and a traversal per row. With a decoder set, a contiguous run comes back as one {rows, Rows} message with the rows already decoded.

The decoder belongs to one statement's result, so it must be cleared before the connection is used for anything else. A decoder left behind would be applied to the next statement's rows, which is wrong data rather than an error.

-spec forget(conn(), binary()) -> conn().

Drop what was kept under this SQL.

For a statement the server has stopped accepting, which is what a schema change under a cached plan looks like.

-spec give_away(conn(), pid()) -> ok | {error, error()}.

Hand the socket to another process.

The connection term is data and can be sent anywhere; the socket underneath it cannot. It belongs to one process, and a process that is handed a connection without being handed the socket gets {error, {socket, einval}} on its first read. A pool checking a connection out has to call this, and so does the borrower checking it back in.

-spec handle_message(conn(), term()) ->
                        {messages, [minato_protocol:backend()], conn()} | {closed, term()} | ignore.

Turn a socket message into the protocol messages it carried.

For a connection under activate/1. Anything that is not this connection's socket answers ignore, so an owner with other messages of its own can pass everything through.

{closed, Reason} is the socket going away, and there is no connection in it: the socket is gone, and what is left of the buffer belongs to a message that will never finish arriving.

-spec next(conn()) -> {ok, minato_protocol:backend(), conn()} | {error, error()}.

next/2 with the connection's own timeout.

-spec next(conn(), timeout()) -> {ok, minato_protocol:backend(), conn()} | {error, error()}.

Read the next message the server sent.

Reads from the socket only when no already decoded message is waiting, so a result set of five thousand rows costs as many reads as the network chose to split it into rather than one per row.

ParameterStatus is not handled here even though the server may send it at any time. It is a message like any other and the layer above decides what to do with it, because a connection that quietly swallowed SET TIME ZONE taking effect would be hiding the one thing the message exists to announce.

-spec parameter(conn(), binary()) -> binary() | undefined.

One reported parameter, or undefined.

server_version, client_encoding and integer_datetimes are always among them; which others a server volunteers is the server's choice.

-spec parameters(conn()) -> #{binary() => binary()}.

Every parameter the server has reported, by name.

-spec recall(conn(), binary()) -> dynamic().

What this connection has parsed on the server under this SQL, or undefined.

The value is whatever the query layer put there, which is why it is untyped here: the connection keeps statements without knowing what a statement is.

The cache belongs to the connection because the statement does: a name is meaningful only to the session that parsed it, so a cache anywhere else would hand out names another session does not have.

-spec remember(conn(), binary(), term()) -> conn().

Keep a parsed statement under its SQL, if there is room.

Room is claim/1's to give: a connection that has handed out every name it is allowed answers undefined there, and the caller runs the statement unnamed. An unbounded workload therefore gets the uncached path rather than an unbounded pile of parsed statements in the backend.

-spec send(conn(), minato_protocol:frontend() | [minato_protocol:frontend()]) -> ok | {error, error()}.

Write one frontend message, or a list of them in order.

A list is written as a single send, which is what the extended query protocol wants: Parse, Bind, Execute and Sync in one write is one round trip rather than four.

-spec statements(conn()) -> {non_neg_integer(), non_neg_integer()}.

How many statements this connection is keeping, and how many names it may claim.

-spec timeout(conn()) -> timeout().

The per read timeout this connection was opened with.

-spec transaction_status(conn()) -> minato_protocol:transaction_status().

What the server last said about the transaction on this connection.

Taken from the status byte of every ReadyForQuery as it is read, so it is only as current as the last message the caller read. failed is a transaction in which a statement has already errored, and everything further is rejected until it is rolled back.

-spec with_timeout(conn(), timeout()) -> conn().

The same connection with a different read timeout.

For work that should be given less time than the connection's own budget - a health check that has to answer inside a probe interval - or more, for a query that is known to be slow. The change lasts as long as the connection term the caller keeps.