Alpha

These pages are built from turborel-java’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Connections

NAME

Connect, Connection, Controls, the mechanisms, TlsConfig, Timeouts, Offer, KeyCache, Canceller: the low-level client's connections, as turborel-client gives them

SYNOPSIS

package com.turborel.jdbc.internal.session;

public final class Connect {
    public static final int PORT = 7422;
    public static Connection tcp(String host, int port, String user, Mechanism mechanism) throws TurborelException;
    public static Connection local(Path path, String user, Mechanism mechanism) throws TurborelException;
    public static Connection tls(String host, int port, String name, TlsConfig config, Login login)
            throws TurborelException;
    public static Connection to(Target target, String user, Mechanism mechanism, Timeouts timeouts, Offer offer)
            throws TurborelException;
}

public record Login(String user, Mechanism mechanism) {}

public final class Connection implements AutoCloseable {
    public static Connection open(Duplex duplex, String user, Mechanism mechanism, Offer offer)
            throws TurborelException;
    public String server();
    public String authorization();
    public boolean inTransaction();
    public Set<String> granted();
    public @Nullable String setting(String name);
    public Map<String, String> settings();
    public void setNoticeHandler(@Nullable Consumer<Reply.Notice> handler);
    public List<Reply.Notice> takeNotices();
    public void setReadTimeout(@Nullable Duration within) throws TurborelException;
    public @Nullable Duration readTimeout();
    public void setMaxBody(int bytes);
    public @Nullable Target target();
    public @Nullable Canceller canceller();
    public Statements statements();
    public Controls controls();
    public Told told();
    public void terminate() throws TurborelException;
    public boolean isLost();
    public void close();
}

public final class Controls {
    public void ping() throws TurborelException;
    public void reset() throws TurborelException;
    public void changeUser(String user, Mechanism mechanism) throws TurborelException;
}

public final class Canceller {
    public void cancel() throws TurborelException;
    public void cancelWithin(Duration limit) throws TurborelException;
}

public record Offer(List<String> capabilities, List<Attribute> attributes, int compressFrom) {
    public static final String APPLICATION = "application";
    public static Offer standard();
    public static Offer none();
    public Offer compressed();
    public Offer attribute(String name, String value);
}

package com.turborel.jdbc.internal.auth;

public final class Trust implements Mechanism {}
public final class Password implements Mechanism { public Password(String password); }
public final class Certificate implements Mechanism {}
public final class Scram implements Mechanism {
    public Scram(String password);
    public Scram inTheClear();
    public Scram channelBinding(ChannelBinding how);
    public Scram withCache(KeyCache keys);
}
public enum ChannelBinding { DISABLE, PREFER, REQUIRE }
public final class KeyCache {
    public static final int ENTRIES = 64;
    public KeyCache();
    public long[] lookups();
    public int size();
    public void clear();
}

package com.turborel.jdbc.internal.tls;

public final class TlsConfig {
    public static TlsConfig trusting(Path roots) throws TurborelException;
    public static TlsConfig presenting(Path roots, Path chain, Path key) throws TurborelException;
    public static TlsConfig of(KeyStore trusted, @Nullable Identity identity) throws TurborelException;
    public static TlsConfig of(TrustManager[] trust, @Nullable Identity identity, boolean checkName)
            throws TurborelException;
    public record Identity(List<X509Certificate> chain, PrivateKey key) {}
}
public final class Roots {
    public static KeyStore of(@Nullable Path file, boolean platform, UnaryOperator<@Nullable String> environment)
            throws TurborelException;
}

package com.turborel.jdbc.internal.transport;

public sealed interface Target {
    record Tcp(InetSocketAddress address) implements Target {}
    record Local(Path path) implements Target {}
    record Tls(InetSocketAddress address, String name, TlsConfig config) implements Target {}
}
public record Timeouts(@Nullable Duration connect, @Nullable Duration read) {
    public static final Duration CONNECT_WITHIN;   // 30 seconds
    public static final Duration TERMINATE_WITHIN; // 60 seconds
    public static final Duration CANCEL_WITHIN;    // 10 seconds
    public static final Timeouts DEFAULT;          // CONNECT_WITHIN, and no read timeout
}

These packages are not exported by the module (RULES.md D2): JDBC's classes rest on them, and a program reaches what the server told the session by unwrap(TurborelConnection.class) (Connection). A connection's statements() are told in Statements and Cursors, with what told() gives of a completion, and controls() several statements in one request and query attributes too.

DESCRIPTION

Connecting. Connect.tcp connects over TCP, trying each of the host's addresses in turn; Connect.local over the Unix socket at a path, or on Windows over a named pipe, as \\.\pipe\turborel; Connect.tls over TCP, then TLS on the same port, the server's certificate checked to be of name, which is sent as the server's name too. Each waits as Timeouts.DEFAULT says and asks for Offer.standard(). Connect.to connects to a Target, waiting as its timeouts say and asking for its offer. Connection.open logs in over a stream the program opened itself, which it bounds itself: its read timeout cannot be set, and it has no canceller. A program that opens a TLS stream of its own binds it before SCRAM-SHA-256-PLUS, by the mechanism's bind with Handshake.channel.

Mechanisms. Trust asks the server to trust the user as it names itself. Password sends the password whole. Certificate proves the user by the certificate TLS presents. Scram proves a password by SCRAM-SHA-256, the server proving it knows the user's verifier before the login ends; over TLS it is SCRAM-SHA-256-PLUS, bound by tls-exporter where the JDK exports keying material, else by the server's certificate, as channelBinding allows, PREFER by default. inTheClear lets it go over plain TCP; withCache gives it a key cache.

TLS. TlsConfig.trusting trusts the authorities of a PEM file; presenting also presents a certificate chain and key, the key as PKCS #8, PKCS #1 or SEC 1. TlsConfig.of takes a store of authorities, as Roots.of makes of a file's, the platform's, or both, and an identity or none. The platform's are those of the files SSL_CERT_FILE and SSL_CERT_DIR name, if either is set, SSL_CERT_DIR a list of directories apart by the platform's path separator, each that cannot be read passed over; else the JDK's own (RULES.md D13).

Timeouts. connect bounds connecting, TLS and each step of the login; read each read or write after. A named pipe is bounded only as it is opened. setReadTimeout changes a connection's read timeout; setMaxBody the longest reply it takes, 16 MiB at most.

What the server tells. server and authorization are as the server's Ready said. granted is the capabilities granted, those the offer asked for that the server serves. Granted status, setting and settings give the session's settings as the server last told them, with AUTHORIZATION, SCHEMA, READ_ONLY, SERVER_VERSION, SERVER_READ_ONLY, CATALOG and OWNER. Notices go to the handler set, or with none the last 64 are kept for takeNotices. inTransaction says whether a transaction is active, as the server last said.

The key cache. A KeyCache keeps the keys a SCRAM login derived, after a login the server proved, for a later login of the same salt and iterations. An entry is found by the salt, the iterations and a tag of the password under a random secret of the cache's own; it holds ENTRIES, 64, at most, the oldest dropped first, and drops an entry when a login that used it fails. lookups gives its hits and misses, in that order.

Controlling the session. Granted ping, ping asks whether the server and the connection are alive, with no statement run. Granted reset, reset puts the session back as it was at login: its transaction rolled back, told by notice 01T01, its prepared statements, cursors, temporary tables and settings gone, every setting told again, its user and cancel key kept. Granted change-user, changeUser authenticates the connection again as another user, answering each challenge as a login does, the session renewed as by a reset under a new cancel key, no transaction active after it.

Ending. terminate sends Terminate and waits for the server to close, at most the read timeout, else TERMINATE_WITHIN; the server ends the session as SESSION.COMMIT_AT_END says. close closes at once. canceller gives what cancels the statement running, over a connection of its own, carrying the session's cancel key, which it never shows; cancel gives up after CANCEL_WITHIN. A connection lost takes no more, isLost saying so.

ERRORS

SQLCODE SQLSTATE When
-919 28000 Password, or Scram not in the clear, over plain TCP, before connecting; the server refuses the user, the mechanism or the credentials, and closes
-919 08004 The server refuses the connection, as of a version it does not speak
-919 08006 The server cannot be reached; TLS's handshake fails; a wait runs out, the message saying the server did not answer in time; the server does not prove it knows the SCRAM verifier; a reply is longer than the connection takes; a file of certificates or a key cannot be read; the stream fails; setReadTimeout on a connection the program opened itself
-920 TB920 The statement a Canceller cancelled
-919 08006 ping, reset or changeUser of a capability not granted, refused before anything is sent, the connection kept
-919 28000 changeUser: the server refuses the user or the credentials, and the connection fails
-913 40002 terminate: the commit at the session's end fails, and the transaction is rolled back

EXAMPLES

Trust, over TCP:

Connection conn = Connect.tcp("127.0.0.1", 17434, "ann", new Trust());
System.out.println(conn.server() + ", as " + conn.authorization());
conn.terminate();
turborel 0.0.0 (alpha), as ANN

SCRAM-SHA-256-PLUS, over TLS:

TlsConfig config = TlsConfig.trusting(Path.of("certs/ca.pem"));
Connection conn = Connect.tls("127.0.0.1", 17434, "localhost", config, new Login("ann", new Scram("ann's")));
System.out.println(conn.authorization() + " over TLS");
conn.terminate();
ANN over TLS

The User's Guide's chapter Connecting has more: refusals, a certificate, timeouts and an offer, and the key cache.

STANDARD

[PROTOCOL The Native Protocol], [PROTOCOL Opening a connection], [PROTOCOL Mechanisms], [PROTOCOL Capabilities], [PROTOCOL Status 'T'], [PROTOCOL Cancel 'Z'], [PROTOCOL Terminate 'X'], [PROTOCOL Ping 'G'], [PROTOCOL Reset 'W'], [PROTOCOL ChangeUser 'U']; [CLIENT Connecting], [CLIENT Timeouts], [CLIENT What a connection asks for], [CLIENT What the server tells], [CLIENT Running statements], [CLIENT The SCRAM key cache], [CLIENT Controlling the session].

SEE ALSO

Connecting, Errors, Settings