-spec alpn_opts(list()) -> list().

Generate ALPN options for SSL connection. Returns a list containing alpn_advertised_protocols option based on the protocols specified in Options.

Options: - protocols: list of atoms [http3, http2, http1] (default: [http2, http1]) Order matters - first protocol is preferred Note: http3 is only used for informational purposes here - HTTP/3 uses QUIC which has its own ALPN negotiation handled by hackney_http3.

Example:

  alpn_opts([{protocols, [http2, http1]}]) ->
      [{alpn_advertised_protocols, [<<"h2">>, <<"http/1.1">>]}]

-spec close(ssl:sslsocket()) -> ok.

Close a TCP socket.

See also: ssl:close/1.

-spec controlling_process(ssl:sslsocket(), pid()) -> ok | {error, closed | not_owner | atom()}.

Assign a new controlling process Pid to Socket.

See also: ssl:controlling_process/2.

-spec effective_opts(string(), list(), list()) -> list().

Build the exact options handed to ssl:connect/2 for an SSL upgrade. SslOpts is the caller's ssl_options, with an optional {protocols, P} entry prepended when the request carries one. ConnectOpts is only used as the ALPN fallback when SslOpts yields no ALPN protocols. Computing the final list once, caller-side, lets options_key/1 hash the same term the handshake uses.

Requests on hackney's default TLS config (no user ssl_options) also get {session_tickets, auto} for TLS 1.3 session resumption, unless the tls_session_resumption application env is set to false or the node pins the ssl app to versions without 'tlsv1.3'. Custom ssl_options deliberately never get resumption: OTP's automatic ticket store is global per node and keyed by SNI, not by trust options, and a PSK-resumed handshake skips certificate validation. Restricting it to the default config means every participant in the store has identical trust, so trust configs cannot cross by construction.

-spec effective_opts_and_key(string(), list(), list()) -> {list(), binary()}.

Like effective_opts/3 but also return options_key/1 of the result, memoized in a bounded ETS cache. Building the options is cheap; hashing them is not (sha256 over the full term, dominated by the certifi CA bundle), so only the hash is cached. The memo key is the small pre-merge inputs plus env_fingerprint/0, so a runtime env flip yields a fresh key instead of hashing connections into wrong pool buckets.

-spec get_negotiated_protocol(ssl:sslsocket()) -> http2 | http1.

Get the negotiated protocol after SSL handshake. Returns http2 if HTTP/2 was negotiated, http1 otherwise. Note: HTTP/3 is not returned here as it uses QUIC, not TLS.

See also: ssl:negotiated_protocol/1.

-spec h3_options_key(list(), list()) -> binary().

Hash the QUIC trust projection of an HTTP/3 connection into a pool key component. Includes exactly what decides server trust on the QUIC handshake, mirroring hackney_conn's h3_tls_opts/2: the verify mode derived from the insecure flag (read from ConnectOpts first, then SslOpts) and the CA source from SslOpts (the cacerts list, else the cacertfile path, else the default trust store). The cacertfile path is hashed as given, without reading the file. Deliberately excluded: session_ticket (injected per resumption, so the conn-side store key must not depend on it), and family and happy_eyeballs (connectivity options that do not affect trust). A user-supplied server_name_indication is included so requests to one host:port with different SNI do not share a QUIC connection; the default SNI is the host itself, already part of the outer pool key.

-spec init_key_cache() -> ok.

Create the TLS key memo table used by effective_opts_and_key/3. Idempotent; called from hackney_sup:init/1.

Atoms used to identify messages in {active, once | true} mode.

-spec options_key(list()) -> binary().

Hash the effective TLS options into a pool key component. 2-tuples are ukeysorted (first occurrence wins, preserving proplists lookup semantics) so option order does not change the key, while conflicting duplicates such as [{verify,A},{verify,B}] and its reverse still hash differently.

-spec peercert(ssl:sslsocket()) -> {ok, binary()} | {error, atom()}.

Return the peer certificate of an SSL connection.

See also: ssl:peercert/1.

-spec peername(ssl:sslsocket()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}.

Return the address and port for the other end of a connection.

See also: ssl:peername/1.

-spec recv(ssl:sslsocket(), non_neg_integer(), timeout()) -> {ok, any()} | {error, closed | atom()}.

Receive a packet from a socket in passive mode.

See also: ssl:recv/3.

-spec send(ssl:sslsocket(), iolist()) -> ok | {error, atom()}.

Send a packet on a socket.

See also: ssl:send/2.

-spec setopts(ssl:sslsocket(), list()) -> ok | {error, atom()}.

Set one or more options for a socket.

See also: ssl:setopts/2.

-spec shutdown(ssl:sslsocket(), read | write | read_write) -> ok | {error, any()}.

Immediately close a socket in one or two directions.

See also: ssl:shutdown/2.

-spec sockname(ssl:sslsocket()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}.

Get the local address and port of a socket

See also: ssl:sockname/1.

Build SSL options for a connection. Used by proxy modules for SSL upgrade after tunnel establishment.