diff --git a/src/Titano.Data/DatabaseOptions.cs b/src/Titano.Data/DatabaseOptions.cs new file mode 100644 index 00000000..6d857a27 --- /dev/null +++ b/src/Titano.Data/DatabaseOptions.cs @@ -0,0 +1,54 @@ +using Titano.Data.Postgres; +using Titano.Data.Sqlite; + +namespace Titano.Data; + +/// Which engine to open and how to reach it. +/// +/// SQLite: Data Source=<path>|:memory:;Pool Size=4. +/// PostgreSQL: Host=…;Port=5432;Database=…;Username=…;Password=…;SslMode=disable|prefer|require|verify-full +/// plus the optional keys listed on . +/// +public sealed record DatabaseOptions +{ + public required Dialect Dialect { get; init; } + + public required string ConnectionString { get; init; } + + public static DatabaseOptions Sqlite(string path) => new() + { + Dialect = Dialect.Sqlite, + ConnectionString = "Data Source='" + path.Replace("'", "''", StringComparison.Ordinal) + "'", + }; + + /// A private in-memory SQLite database that lives until the is disposed. + public static DatabaseOptions SqliteInMemory() => new() { Dialect = Dialect.Sqlite, ConnectionString = "Data Source=:memory:" }; + + public static DatabaseOptions Postgres(string connectionString) => new() { Dialect = Dialect.Postgres, ConnectionString = connectionString }; + + /// + /// Infers the dialect: a string with Host/Server is PostgreSQL; Data Source or a bare + /// path (no =) is SQLite. + /// + public static DatabaseOptions Parse(string connectionString) + { + ArgumentException.ThrowIfNullOrWhiteSpace(connectionString); + if (!connectionString.Contains('=', StringComparison.Ordinal)) return Sqlite(connectionString.Trim()); + var cs = new ConnectionString(connectionString); + if (cs.Contains("Host") || cs.Contains("Server")) return Postgres(connectionString); + if (cs.Contains("Data Source") || cs.Contains("Filename")) return new() { Dialect = Dialect.Sqlite, ConnectionString = connectionString }; + throw new FormatException("The connection string names neither a PostgreSQL host nor a SQLite data source."); + } +} + +/// Builds the implementation for a set of options. +public static class DatabaseFactory +{ + /// Creates the database object; SQLite opens the file now, PostgreSQL connects on the first session. + public static IDatabase Open(DatabaseOptions options) => options.Dialect switch + { + Dialect.Sqlite => SqliteDatabase.Open(SqliteSettings.Parse(options.ConnectionString)), + Dialect.Postgres => new PostgresDatabase(PostgresSettings.Parse(options.ConnectionString)), + _ => throw new ArgumentOutOfRangeException(nameof(options), options.Dialect, "Unknown dialect."), + }; +} diff --git a/src/Titano.Data/Postgres/PgAuthentication.cs b/src/Titano.Data/Postgres/PgAuthentication.cs new file mode 100644 index 00000000..f3933958 --- /dev/null +++ b/src/Titano.Data/Postgres/PgAuthentication.cs @@ -0,0 +1,137 @@ +using System.Globalization; +using System.Security.Authentication; +using System.Security.Cryptography; +using System.Text; + +namespace Titano.Data.Postgres; + +/// +/// Client side of SCRAM-SHA-256 (RFC 5802 / RFC 7677) as PostgreSQL uses it: no channel binding +/// (n,, GS2 header) and an empty user name, since the server takes the user from the startup packet. +/// +internal sealed class ScramSha256 +{ + private readonly string _password; + private readonly string _username; + private readonly string _clientNonce; + private string? _clientFirstBare; + private byte[]? _expectedServerSignature; + + public ScramSha256(string password, string username = "", string? clientNonce = null) + { + _password = password; + _username = username.Replace("=", "=3D", StringComparison.Ordinal).Replace(",", "=2C", StringComparison.Ordinal); + _clientNonce = clientNonce ?? Convert.ToBase64String(RandomNumberGenerator.GetBytes(18)); + } + + public const string Mechanism = "SCRAM-SHA-256"; + + public byte[] ClientFirstMessage() + { + _clientFirstBare = $"n={_username},r={_clientNonce}"; + return Encoding.UTF8.GetBytes("n,," + _clientFirstBare); + } + + /// Checks the server-first message and returns client-final with the proof. + public byte[] ClientFinalMessage(ReadOnlySpan serverFirst) + { + if (_clientFirstBare is null) throw new InvalidOperationException("ClientFirstMessage must be sent first."); + var serverFirstText = Encoding.UTF8.GetString(serverFirst); + string? nonce = null, salt = null, iterations = null; + foreach (var part in serverFirstText.Split(',')) + { + if (part.StartsWith("r=", StringComparison.Ordinal)) nonce = part[2..]; + else if (part.StartsWith("s=", StringComparison.Ordinal)) salt = part[2..]; + else if (part.StartsWith("i=", StringComparison.Ordinal)) iterations = part[2..]; + } + if (nonce is null || salt is null || iterations is null + || !nonce.StartsWith(_clientNonce, StringComparison.Ordinal) || nonce.Length == _clientNonce.Length + || !int.TryParse(iterations, NumberStyles.None, CultureInfo.InvariantCulture, out var count) || count < 1) + throw new AuthenticationException("Invalid SCRAM server-first message."); + + var saltedPassword = Rfc2898DeriveBytes.Pbkdf2( + Encoding.UTF8.GetBytes(SaslPrep(_password)), Convert.FromBase64String(salt), count, HashAlgorithmName.SHA256, 32); + var clientKey = HMACSHA256.HashData(saltedPassword, "Client Key"u8); + var storedKey = SHA256.HashData(clientKey); + var withoutProof = "c=biws,r=" + nonce; + var authMessage = Encoding.UTF8.GetBytes(_clientFirstBare + "," + serverFirstText + "," + withoutProof); + var proof = HMACSHA256.HashData(storedKey, authMessage); + for (var i = 0; i < proof.Length; i++) proof[i] ^= clientKey[i]; + _expectedServerSignature = HMACSHA256.HashData(HMACSHA256.HashData(saltedPassword, "Server Key"u8), authMessage); + return Encoding.UTF8.GetBytes(withoutProof + ",p=" + Convert.ToBase64String(proof)); + } + + /// Verifies the server signature, proving the server knows the password too. + public void VerifyServerFinal(ReadOnlySpan serverFinal) + { + var text = Encoding.UTF8.GetString(serverFinal); + if (text.StartsWith("e=", StringComparison.Ordinal)) throw new AuthenticationException("SCRAM authentication failed: " + text[2..]); + var end = text.IndexOf(',', StringComparison.Ordinal); + var value = text.StartsWith("v=", StringComparison.Ordinal) ? text[2..(end < 0 ? text.Length : end)] : null; + if (_expectedServerSignature is null || value is null + || !CryptographicOperations.FixedTimeEquals(Convert.FromBase64String(value), _expectedServerSignature)) + throw new AuthenticationException("The server's SCRAM signature is invalid."); + } + + /// + /// SASLprep (RFC 4013) as PostgreSQL applies it: non-ASCII spaces become U+0020, "mapped to nothing" + /// characters are dropped, then NFKC; a result with prohibited code points falls back to the raw password. + /// The unassigned-code-point and bidi checks are omitted. + /// + internal static string SaslPrep(string password) + { + var ascii = true; + foreach (var c in password) + { + if (c > 0x7F) + { + ascii = false; + break; + } + } + // Printable ASCII is unchanged by SASLprep; ASCII controls are prohibited, which also means "use raw". + if (ascii) return password; + + var mapped = new StringBuilder(password.Length); + foreach (var rune in password.EnumerateRunes()) + { + var v = rune.Value; + if (v is 0x00A0 or 0x1680 or (>= 0x2000 and <= 0x200B) or 0x202F or 0x205F or 0x3000) mapped.Append(' '); + else if (v is 0x00AD or 0x034F or 0x1806 or (>= 0x180B and <= 0x180D) or (>= 0x200C and <= 0x200D) or 0x2060 + or (>= 0xFE00 and <= 0xFE0F) or 0xFEFF) continue; + else mapped.Append(rune.ToString()); + } + var normalized = mapped.ToString().Normalize(NormalizationForm.FormKC); + foreach (var rune in normalized.EnumerateRunes()) + { + if (IsProhibited(rune.Value)) return password; + } + return normalized; + } + + private static bool IsProhibited(int v) => + v < 0x20 || v is >= 0x7F and <= 0x9F // C.2.1, C.2.2 controls + || v is 0x06DD or 0x070F or 0x180E or 0x2028 or 0x2029 or (>= 0x2060 and <= 0x2063) // C.2.2 + || v is >= 0x1D173 and <= 0x1D17A + || v is >= 0xE000 and <= 0xF8FF || v >= 0xF0000 // C.3 private use + || v is >= 0xFDD0 and <= 0xFDEF || (v & 0xFFFE) == 0xFFFE // C.4 non-characters + || v is >= 0xFFF9 and <= 0xFFFD // C.6 + || v is >= 0x2FF0 and <= 0x2FFB // C.7 + || v is 0x0340 or 0x0341 or 0x200E or 0x200F or (>= 0x202A and <= 0x202E) or (>= 0x206A and <= 0x206F) // C.8 + || v is 0xE0001 or (>= 0xE0020 and <= 0xE007F); // C.9 +} + +/// PostgreSQL's MD5 password response: "md5" + md5hex(md5hex(password + user) + salt). +internal static class PgMd5 +{ + public static string Response(string username, string password, ReadOnlySpan salt) + { + var inner = Hex(MD5.HashData(Encoding.UTF8.GetBytes(password + username))); + var buffer = new byte[inner.Length + salt.Length]; + Encoding.ASCII.GetBytes(inner, buffer); + salt.CopyTo(buffer.AsSpan(inner.Length)); + return "md5" + Hex(MD5.HashData(buffer)); + } + + private static string Hex(byte[] bytes) => Convert.ToHexStringLower(bytes); +} diff --git a/src/Titano.Data/Postgres/PgConnector.cs b/src/Titano.Data/Postgres/PgConnector.cs new file mode 100644 index 00000000..59c5f38d --- /dev/null +++ b/src/Titano.Data/Postgres/PgConnector.cs @@ -0,0 +1,1025 @@ +using System.Buffers.Binary; +using System.Globalization; +using System.Net.Security; +using System.Net.Sockets; +using System.Runtime.CompilerServices; +using System.Runtime.ExceptionServices; +using System.Security.Cryptography.X509Certificates; +using System.Text; +using Titano.Core.Diagnostics; + +namespace Titano.Data.Postgres; + +/// A NOTIFY delivered to a listening connection. +public sealed record PgNotification(int ProcessId, string Channel, string Payload); + +/// +/// One physical connection speaking protocol v3 (BRIEF §6.3): startup and authentication, simple and extended +/// query with a per-connection LRU of named prepared statements, COPY FROM STDIN, notices and notifications, +/// and cancellation through a CancelRequest on a second socket. Not thread-safe; the pool lends it to one +/// session at a time. +/// +internal sealed class PgConnector : IAsyncDisposable +{ + private const int ProtocolVersion3 = 196608; + private const int SslRequestCode = 80877103; + private const int CancelRequestCode = 80877102; + private const int CopyChunkBytes = 64 * 1024; + private const string LogCategory = "Data.Postgres"; + private static readonly TimeSpan CancelGracePeriod = TimeSpan.FromSeconds(5); + private static readonly DbColumns NoColumns = new([]); + + private readonly PostgresSettings _settings; + private readonly Socket _socket; + private readonly Stream _stream; + private readonly PgWriteBuffer _write = new(); + private readonly Dictionary> _statements = new(StringComparer.Ordinal); + private readonly LinkedList _statementLru = new(); + private readonly List _statementsToClose = []; + private readonly Dictionary _serverParameters = new(StringComparer.Ordinal); + private byte[] _read = new byte[16 * 1024]; + private int _readPos; + private int _readEnd; + private int _messageStart; + private int _messageLength; + private int _statementCounter; + private int _secretKey; + private long _idleSince; + private int _disposed; + private CancellationTokenSource _ioAbort = new(); + private Task _pendingCancel = Task.CompletedTask; + + private PgConnector(PostgresSettings settings, Socket socket, Stream stream) + { + _settings = settings; + _socket = socket; + _stream = stream; + } + + public int ProcessId { get; private set; } + + /// The connection failed or the server ended the session; it must be discarded. + public bool IsBroken { get; private set; } + + /// Last ReadyForQuery status: 'I' idle, 'T' in transaction, 'E' failed transaction. + public char TransactionStatus { get; private set; } = 'I'; + + public TimeSpan IdleTime => TimeSpan.FromMilliseconds(Environment.TickCount64 - _idleSince); + + public IReadOnlyDictionary ServerParameters => _serverParameters; + + /// Receives NotificationResponse messages (listener connections). + public Action? NotificationReceived { get; set; } + + private ReadOnlySpan Payload => _read.AsSpan(_messageStart, _messageLength); + + public static async Task OpenAsync(PostgresSettings settings, CancellationToken cancellationToken) + { + using var timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); + timeout.CancelAfter(settings.ConnectTimeout); + var socket = new Socket(SocketType.Stream, ProtocolType.Tcp) { NoDelay = true }; + Stream? stream = null; + try + { + await socket.ConnectAsync(settings.Host, settings.Port, timeout.Token).ConfigureAwait(false); + stream = new NetworkStream(socket, ownsSocket: false); + if (settings.SslMode != SslMode.Disable) + stream = await NegotiateTlsAsync(stream, settings, timeout.Token).ConfigureAwait(false); + var connector = new PgConnector(settings, socket, stream); + await connector.StartupAsync(timeout.Token).ConfigureAwait(false); + connector.MarkIdle(); + return connector; + } + catch (Exception ex) + { + if (stream is not null) await stream.DisposeAsync().ConfigureAwait(false); + socket.Dispose(); + if (ex is OperationCanceledException && !cancellationToken.IsCancellationRequested) + throw new DatabaseConnectionException($"Timed out connecting to {settings.Host}:{settings.Port}.", ex); + if (ex is SocketException or IOException) + throw new DatabaseConnectionException($"Cannot connect to {settings.Host}:{settings.Port}: {ex.Message}", ex); + throw; + } + } + + public void MarkIdle() => _idleSince = Environment.TickCount64; + + /// Runs one statement with the extended protocol and returns the rows it changed. + public async Task ExecuteAsync(string sql, DbParam[] parameters, CancellationToken cancellationToken) + { + var op = StartOperation(sql, parameters, decodeRows: false, cancellationToken); + try + { + await SendExtendedAsync(op).ConfigureAwait(false); + while (await ReadRowAsync(op).ConfigureAwait(false) is not null) + { + } + return op.Affected; + } + finally + { + await EndOperationAsync(op).ConfigureAwait(false); + } + } + + /// Streams the rows of one statement; abandoning the enumeration drains the rest of the response. + public async IAsyncEnumerable QueryAsync(string sql, DbParam[] parameters, [EnumeratorCancellation] CancellationToken cancellationToken) + { + var op = StartOperation(sql, parameters, decodeRows: true, cancellationToken); + try + { + await SendExtendedAsync(op).ConfigureAwait(false); + while (await ReadRowAsync(op).ConfigureAwait(false) is { } row) yield return row; + } + finally + { + await EndOperationAsync(op).ConfigureAwait(false); + } + } + + /// Runs a simple-protocol query (scripts, transaction control) and returns the last command tag. + public async Task SimpleQueryAsync(string sql, CancellationToken cancellationToken) + { + var op = StartOperation(sql, [], decodeRows: false, cancellationToken); + try + { + WriteQuery(sql); + await FlushAsync(op).ConfigureAwait(false); + await DrainAsync(op).ConfigureAwait(false); + return op.Tag; + } + finally + { + await EndOperationAsync(op).ConfigureAwait(false); + } + } + + /// True when SELECT 1 succeeds within the connect timeout; marks the connection broken otherwise. + public async Task PingAsync(CancellationToken cancellationToken) + { + using var timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); + timeout.CancelAfter(_settings.ConnectTimeout); + try + { + await SimpleQueryAsync("SELECT 1", timeout.Token).ConfigureAwait(false); + return true; + } + catch (Exception ex) when (ex is DatabaseException or OperationCanceledException && !cancellationToken.IsCancellationRequested) + { + IsBroken = true; + return false; + } + } + + /// + /// Streams rows through COPY … FROM STDIN in text format. A failing producer aborts the copy with + /// CopyFail, so the table is left untouched, and its exception is rethrown. + /// + public async Task CopyInAsync(string copySql, int columnCount, IAsyncEnumerable rows, CancellationToken cancellationToken) + { + var op = StartOperation(copySql, [], decodeRows: false, cancellationToken); + try + { + WriteQuery(copySql); + await FlushAsync(op).ConfigureAwait(false); + while (true) + { + var type = await NextMessageAsync(op).ConfigureAwait(false); + if (type == 'G') break; + if (type == 'E') OnError(op); + else if (type == 'Z') throw Complete(op) ?? ProtocolViolation(type); + } + + ExceptionDispatchInfo? failure = null; + try + { + _write.StartMessage('d'); + await foreach (var row in rows.WithCancellation(cancellationToken).ConfigureAwait(false)) + { + if (row.Length != columnCount) + throw new ArgumentException($"A row has {row.Length} values for {columnCount} columns.", nameof(rows)); + for (var i = 0; i < row.Length; i++) + { + if (i > 0) _write.WriteByte((byte)'\t'); + PgTypes.WriteCopyValue(row[i], _write); + } + _write.WriteByte((byte)'\n'); + if (_write.Length >= CopyChunkBytes) + { + _write.EndMessage(); + await FlushAsync(op).ConfigureAwait(false); + _write.StartMessage('d'); + } + } + _write.EndMessage(); + _write.StartMessage('c'); + _write.EndMessage(); + await FlushAsync(op).ConfigureAwait(false); + } + catch (Exception ex) when (!IsBroken) + { + failure = ExceptionDispatchInfo.Capture(ex); + _write.Clear(); + _write.StartMessage('f'); + _write.WriteCString(ex.Message); + _write.EndMessage(); + await FlushAsync(op).ConfigureAwait(false); + } + + try + { + await DrainAsync(op).ConfigureAwait(false); + } + catch (PostgresException) when (failure is not null) + { + // The server reports our CopyFail; the producer's exception is the real cause. + } + catch (OperationCanceledException) when (failure is not null) + { + } + failure?.Throw(); + return op.Affected; + } + finally + { + await EndOperationAsync(op).ConfigureAwait(false); + } + } + + /// Sends a simple query without reading the response (listener commands; the read loop completes them). + public async Task SendQueryAsync(string sql, CancellationToken cancellationToken) + { + WriteQuery(sql); + try + { + await _stream.WriteAsync(_write.Written, cancellationToken).ConfigureAwait(false); + await _stream.FlushAsync(cancellationToken).ConfigureAwait(false); + } + finally + { + _write.Clear(); + } + } + + /// + /// Listener read loop: notifications go to ; each ReadyForQuery reports the + /// error (or null) of the command it ends. Runs until or the connection fails. + /// + public async Task RunListenerAsync(Action commandCompleted, CancellationToken stop) + { + PostgresException? error = null; + while (true) + { + var type = await ReadMessageAsync(stop).ConfigureAwait(false); + if (type == 'E') + { + error = ParseError(); + if (error.IsFatal) + { + IsBroken = true; + throw error; + } + } + else if (type == 'Z') + { + TransactionStatus = (char)Payload[0]; + commandCompleted(error); + error = null; + } + } + } + + public async ValueTask DisposeAsync() + { + if (Interlocked.Exchange(ref _disposed, 1) != 0) return; + if (!IsBroken) + { + try + { + using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(1)); + _write.Clear(); + _write.StartMessage('X'); + _write.EndMessage(); + await _stream.WriteAsync(_write.Written, timeout.Token).ConfigureAwait(false); + } + catch (Exception ex) when (ex is IOException or SocketException or OperationCanceledException or ObjectDisposedException) + { + // Terminate is a courtesy; the socket closes either way. + } + } + IsBroken = true; + try + { + await _stream.DisposeAsync().ConfigureAwait(false); + } + catch (IOException) + { + } + _socket.Dispose(); + _ioAbort.Dispose(); + } + + private static async Task NegotiateTlsAsync(Stream stream, PostgresSettings settings, CancellationToken cancellationToken) + { + var request = new byte[8]; + BinaryPrimitives.WriteInt32BigEndian(request, 8); + BinaryPrimitives.WriteInt32BigEndian(request.AsSpan(4), SslRequestCode); + await stream.WriteAsync(request, cancellationToken).ConfigureAwait(false); + var answer = new byte[1]; + await stream.ReadExactlyAsync(answer, cancellationToken).ConfigureAwait(false); + if (answer[0] == 'N') + { + if (settings.SslMode == SslMode.Prefer) return stream; + throw new DatabaseConnectionException($"The server at {settings.Host}:{settings.Port} does not support TLS, which SslMode={settings.SslMode} requires."); + } + if (answer[0] != 'S') throw new DatabaseConnectionException("Unexpected answer to the TLS request."); + + var tls = new SslStream(stream, leaveInnerStreamOpen: false); + var options = new SslClientAuthenticationOptions + { + TargetHost = settings.Host, + RemoteCertificateValidationCallback = (_, certificate, chain, errors) => + settings.SslMode != SslMode.VerifyFull || IsTrusted(settings, certificate, chain, errors), + }; + await tls.AuthenticateAsClientAsync(options, cancellationToken).ConfigureAwait(false); + return tls; + } + + /// verify-full: the system trust store, or the configured root certificate, plus a host name match. + private static bool IsTrusted(PostgresSettings settings, X509Certificate? certificate, X509Chain? chain, SslPolicyErrors errors) + { + if (settings.RootCertificate is null) return errors == SslPolicyErrors.None; + if (certificate is null || (errors & (SslPolicyErrors.RemoteCertificateNotAvailable | SslPolicyErrors.RemoteCertificateNameMismatch)) != 0) + return false; + using var custom = new X509Chain(); + custom.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust; + custom.ChainPolicy.RevocationMode = X509RevocationMode.NoCheck; + custom.ChainPolicy.CustomTrustStore.ImportFromPemFile(settings.RootCertificate); + if (chain is not null) + { + foreach (var element in chain.ChainElements) custom.ChainPolicy.ExtraStore.Add(element.Certificate); + } + using var leaf = X509CertificateLoader.LoadCertificate(certificate.GetRawCertData()); + return custom.Build(leaf); + } + + private async Task StartupAsync(CancellationToken cancellationToken) + { + _write.StartUntypedMessage(); + _write.WriteInt32(ProtocolVersion3); + void Parameter(string name, string value) + { + _write.WriteCString(name); + _write.WriteCString(value); + } + Parameter("user", _settings.Username); + Parameter("database", _settings.Database); + Parameter("application_name", _settings.ApplicationName); + Parameter("client_encoding", "UTF8"); + Parameter("TimeZone", "UTC"); + Parameter("DateStyle", "ISO, MDY"); + Parameter("extra_float_digits", "3"); + if (_settings.SearchPath is { } searchPath) Parameter("search_path", searchPath); + _write.WriteByte(0); + _write.EndMessage(); + await WriteAndClearAsync(cancellationToken).ConfigureAwait(false); + + ScramSha256? scram = null; + while (true) + { + var type = await ReadMessageAsync(cancellationToken).ConfigureAwait(false); + switch (type) + { + case (byte)'R': + scram = Authenticate(scram); + if (_write.Length > 0) await WriteAndClearAsync(cancellationToken).ConfigureAwait(false); + break; + case (byte)'K': + ProcessId = BinaryPrimitives.ReadInt32BigEndian(Payload); + _secretKey = BinaryPrimitives.ReadInt32BigEndian(Payload[4..]); + break; + case (byte)'Z': + TransactionStatus = (char)Payload[0]; + return; + case (byte)'E': + throw ParseError(); + case (byte)'v': + break; // NegotiateProtocolVersion: we request no protocol extensions. + default: + throw ProtocolViolation(type); + } + } + } + + /// Answers one Authentication* message, queuing the response in the write buffer. + private ScramSha256? Authenticate(ScramSha256? scram) + { + var payload = Payload; + var code = BinaryPrimitives.ReadInt32BigEndian(payload); + switch (code) + { + case 0: + return scram; + case 3: + WritePassword(RequirePassword()); + return scram; + case 5: + WritePassword(PgMd5.Response(_settings.Username, RequirePassword(), payload.Slice(4, 4))); + return scram; + case 10: + { + var mechanisms = new List(); + var pos = 4; + while (pos < payload.Length && payload[pos] != 0) mechanisms.Add(ReadCString(payload, ref pos)); + if (!mechanisms.Contains(ScramSha256.Mechanism)) + throw new NotSupportedException($"The server offers SASL mechanisms {string.Join(", ", mechanisms)}; only {ScramSha256.Mechanism} is supported."); + scram = new ScramSha256(RequirePassword()); + var first = scram.ClientFirstMessage(); + _write.StartMessage('p'); + _write.WriteCString(ScramSha256.Mechanism); + _write.WriteInt32(first.Length); + _write.Write(first); + _write.EndMessage(); + return scram; + } + case 11: + var final = (scram ?? throw ProtocolViolation((byte)'R')).ClientFinalMessage(payload[4..]); + _write.StartMessage('p'); + _write.Write(final); + _write.EndMessage(); + return scram; + case 12: + (scram ?? throw ProtocolViolation((byte)'R')).VerifyServerFinal(payload[4..]); + return scram; + default: + throw new NotSupportedException($"PostgreSQL authentication method {code} is not supported (use scram-sha-256, md5, password or trust)."); + } + } + + private string RequirePassword() => + _settings.Password ?? throw new InvalidOperationException($"The server requires a password for user '{_settings.Username}'."); + + private void WritePassword(string password) + { + _write.StartMessage('p'); + _write.WriteCString(password); + _write.EndMessage(); + } + + private Operation StartOperation(string sql, DbParam[] parameters, bool decodeRows, CancellationToken cancellationToken) + { + if (IsBroken) throw new DatabaseConnectionException("The connection is broken."); + cancellationToken.ThrowIfCancellationRequested(); + var op = new Operation(this, sql, parameters, decodeRows, cancellationToken); + if (cancellationToken.CanBeCanceled) + op.Registration = cancellationToken.UnsafeRegister(static state => ((Operation)state!).Owner.RequestCancel((Operation)state!), op); + return op; + } + + private void RequestCancel(Operation op) + { + if (op.Completed) return; + op.CancelSent = true; + Volatile.Write(ref _pendingCancel, SendCancelRequestAsync()); + // If the server does not react, the socket is aborted so the caller is never stuck. + _ioAbort.CancelAfter(CancelGracePeriod); + } + + private async Task SendCancelRequestAsync() + { + try + { + using var timeout = new CancellationTokenSource(CancelGracePeriod); + using var socket = new Socket(SocketType.Stream, ProtocolType.Tcp) { NoDelay = true }; + await socket.ConnectAsync(_settings.Host, _settings.Port, timeout.Token).ConfigureAwait(false); + var packet = new byte[16]; + BinaryPrimitives.WriteInt32BigEndian(packet, 16); + BinaryPrimitives.WriteInt32BigEndian(packet.AsSpan(4), CancelRequestCode); + BinaryPrimitives.WriteInt32BigEndian(packet.AsSpan(8), ProcessId); + BinaryPrimitives.WriteInt32BigEndian(packet.AsSpan(12), _secretKey); + await socket.SendAsync(packet, SocketFlags.None, timeout.Token).ConfigureAwait(false); + // The postmaster closes the socket once it has signalled the backend. + await socket.ReceiveAsync(new byte[1], SocketFlags.None, timeout.Token).ConfigureAwait(false); + } + catch (Exception ex) when (ex is SocketException or OperationCanceledException or IOException) + { + Log.Warning(LogCategory, $"Cancel request to backend {ProcessId} failed: {ex.Message}"); + } + } + + /// Drains an abandoned response, then makes sure a late cancel request cannot hit the next command. + private async ValueTask EndOperationAsync(Operation op) + { + try + { + if (!op.Completed && !IsBroken) + { + try + { + await DrainAsync(op).ConfigureAwait(false); + } + catch (Exception ex) when (ex is PostgresException or OperationCanceledException) + { + // Errors after the consumer stopped reading are not its concern. + } + } + } + finally + { + op.Completed = true; + await op.Registration.DisposeAsync().ConfigureAwait(false); + if (op.CancelSent) + { + try + { + await Volatile.Read(ref _pendingCancel).WaitAsync(CancelGracePeriod).ConfigureAwait(false); + } + catch (TimeoutException) + { + IsBroken = true; + } + } + if (!_ioAbort.TryReset()) + { + IsBroken = true; + _ioAbort.Dispose(); + _ioAbort = new CancellationTokenSource(); + } + MarkIdle(); + } + } + + private async ValueTask SendExtendedAsync(Operation op) + { + var statement = Lookup(op.Sql, op.ParameterOids, out var hit); + op.Statement = statement; + op.CacheHit = hit; + try + { + foreach (var name in _statementsToClose) + { + _write.StartMessage('C'); + _write.WriteByte((byte)'S'); + _write.WriteCString(name); + _write.EndMessage(); + } + if (!hit) + { + _write.StartMessage('P'); + _write.WriteCString(statement.Name); + _write.WriteCString(op.Sql); + _write.WriteInt16(op.ParameterOids.Length); + foreach (var oid in op.ParameterOids) _write.WriteInt32((int)oid); + _write.EndMessage(); + _write.StartMessage('D'); + _write.WriteByte((byte)'S'); + _write.WriteCString(statement.Name); + _write.EndMessage(); + } + WriteBind(statement.Name, op.Parameters); + _write.StartMessage('E'); + _write.WriteCString(string.Empty); + _write.WriteInt32(0); + _write.EndMessage(); + _write.StartMessage('S'); + _write.EndMessage(); + } + catch + { + // Nothing was sent: forget the half-built batch so the connection stays usable. + _write.Clear(); + op.Completed = true; + throw; + } + _statementsToClose.Clear(); + await FlushAsync(op).ConfigureAwait(false); + } + + private void WriteBind(string statement, DbParam[] parameters) + { + _write.StartMessage('B'); + _write.WriteCString(string.Empty); + _write.WriteCString(statement); + _write.WriteInt16(parameters.Length); + foreach (var p in parameters) _write.WriteInt16(p.Type == DbValueType.Bytes ? 1 : 0); + _write.WriteInt16(parameters.Length); + foreach (var p in parameters) + { + switch (p.Value) + { + case null: + _write.WriteInt32(-1); + break; + case byte[] bytes: + _write.WriteInt32(bytes.Length); + _write.Write(bytes); + break; + case var value: + var span = _write.GetSpan(4 + PgTypes.MaxTextLength(value)); + var n = PgTypes.FormatText(value, span[4..]); + BinaryPrimitives.WriteInt32BigEndian(span, n); + _write.Advance(4 + n); + break; + } + } + _write.WriteInt16(1); + _write.WriteInt16(0); // every result column in text format + _write.EndMessage(); + } + + private void WriteQuery(string sql) + { + _write.StartMessage('Q'); + _write.WriteCString(sql); + _write.EndMessage(); + } + + /// Reads until the next DataRow (returned) or the end of the response (null), then throws any server error. + private async ValueTask ReadRowAsync(Operation op) + { + while (true) + { + var type = await NextMessageAsync(op).ConfigureAwait(false); + switch (type) + { + case (byte)'1': + Remember(op.Statement!); + break; + case (byte)'T': + op.Statement!.SetColumns(ParseRowDescription(out var oids), oids); + break; + case (byte)'n': + op.Statement!.SetColumns(NoColumns, []); + break; + case (byte)'D': + if (op.DecodeRows) return DecodeRow(op.Statement!); + break; + case (byte)'C': + op.Tag = ReadTag(); + op.Affected = AffectedRows(op.Tag); + break; + case (byte)'E': + OnError(op); + break; + case (byte)'Z': + // A cached statement invalidated by DDL is re-prepared once, if no transaction was aborted by it. + if (op.Error is { } stale && op.CacheHit && op.CanRetryStale && IsStale(stale) && Payload[0] == 'I') + { + TransactionStatus = 'I'; + op.Error = null; + op.CanRetryStale = false; + await SendExtendedAsync(op).ConfigureAwait(false); + break; + } + if (Complete(op) is { } error) throw error; + return null; + case (byte)'2' or (byte)'3' or (byte)'t' or (byte)'I' or (byte)'s': + break; + default: + throw ProtocolViolation(type); + } + } + } + + /// Reads to ReadyForQuery, keeping the command tag and the first error; answers stray COPY requests. + private async ValueTask DrainAsync(Operation op) + { + while (true) + { + var type = await NextMessageAsync(op).ConfigureAwait(false); + switch (type) + { + case (byte)'C': + op.Tag = ReadTag(); + op.Affected = AffectedRows(op.Tag); + break; + case (byte)'E': + OnError(op); + break; + case (byte)'G': + _write.StartMessage('f'); + _write.WriteCString("COPY FROM STDIN is only supported through BulkInsertAsync."); + _write.EndMessage(); + await FlushAsync(op).ConfigureAwait(false); + break; + case (byte)'Z': + if (Complete(op) is { } error) throw error; + return; + } + } + } + + /// Handles an ErrorResponse: keeps the first error, evicts a stale cached statement, and ends the operation on FATAL. + private void OnError(Operation op) + { + var error = ParseError(); + op.Error ??= error; + if (op.CacheHit && IsStale(error)) Evict(op.Statement!, close: error.SqlState != "26000"); + if (error.IsFatal) + { + // The server closes the session after FATAL; no ReadyForQuery follows. + IsBroken = true; + op.Completed = true; + throw error; + } + } + + /// Marks the operation finished at ReadyForQuery and returns the exception to raise, if any. + private Exception? Complete(Operation op) + { + TransactionStatus = (char)Payload[0]; + op.Completed = true; + return op.Error switch + { + null => null, + { SqlState: "57014" } e when op.Cancellation.IsCancellationRequested => new OperationCanceledException("The query was cancelled.", e, op.Cancellation), + var e => e, + }; + } + + private static bool IsStale(PostgresException e) => e.SqlState is "26000" or "0A000"; + + private PgStatement Lookup(string sql, uint[] oids, out bool hit) + { + if (_statements.TryGetValue(sql, out var node)) + { + if (node.Value.ParameterOids.AsSpan().SequenceEqual(oids)) + { + _statementLru.Remove(node); + _statementLru.AddFirst(node); + hit = true; + return node.Value; + } + Evict(node.Value, close: true); + } + hit = false; + var name = _settings.StatementCacheSize > 0 ? "titano_" + (++_statementCounter).ToString(CultureInfo.InvariantCulture) : string.Empty; + return new PgStatement(name, sql, oids); + } + + /// Caches a statement once the server confirmed its Parse; the least recently used one is closed when full. + private void Remember(PgStatement statement) + { + if (statement.Name.Length == 0 || _statements.ContainsKey(statement.Sql)) return; + _statements[statement.Sql] = _statementLru.AddFirst(statement); + while (_statementLru.Count > _settings.StatementCacheSize) Evict(_statementLru.Last!.Value, close: true); + } + + private void Evict(PgStatement statement, bool close) + { + if (_statements.Remove(statement.Sql, out var node)) _statementLru.Remove(node); + if (close && statement.Name.Length > 0) _statementsToClose.Add(statement.Name); + } + + private async ValueTask NextMessageAsync(Operation op) + { + try + { + return await ReadMessageAsync(_ioAbort.Token).ConfigureAwait(false); + } + catch (Exception ex) when (IsIoFailure(ex)) + { + throw ConnectionLost(ex, op); + } + } + + private async ValueTask FlushAsync(Operation op) + { + try + { + await WriteAndClearAsync(_ioAbort.Token).ConfigureAwait(false); + } + catch (Exception ex) when (IsIoFailure(ex)) + { + throw ConnectionLost(ex, op); + } + } + + private async ValueTask WriteAndClearAsync(CancellationToken cancellationToken) + { + try + { + await _stream.WriteAsync(_write.Written, cancellationToken).ConfigureAwait(false); + await _stream.FlushAsync(cancellationToken).ConfigureAwait(false); + } + finally + { + _write.Clear(); + } + } + + private static bool IsIoFailure(Exception ex) => + ex is IOException or SocketException or ObjectDisposedException or OperationCanceledException; + + private Exception ConnectionLost(Exception ex, Operation op) + { + IsBroken = true; + op.Completed = true; + return op.Cancellation.IsCancellationRequested + ? new OperationCanceledException("The query was cancelled and the connection closed.", ex, op.Cancellation) + : new DatabaseConnectionException($"The connection to {_settings.Host}:{_settings.Port} was lost: {ex.Message}", ex); + } + + private DatabaseConnectionException ProtocolViolation(byte type) + { + IsBroken = true; + return new DatabaseConnectionException($"Protocol violation: unexpected message '{(char)type}'."); + } + + /// Reads one message into the buffer, handling notices, parameter changes and notifications inline. + private async ValueTask ReadMessageAsync(CancellationToken cancellationToken) + { + while (true) + { + await EnsureAsync(5, cancellationToken).ConfigureAwait(false); + var type = _read[_readPos]; + var length = BinaryPrimitives.ReadInt32BigEndian(_read.AsSpan(_readPos + 1)); + if (length < 4) throw ProtocolViolation(type); + _readPos += 5; + await EnsureAsync(length - 4, cancellationToken).ConfigureAwait(false); + _messageStart = _readPos; + _messageLength = length - 4; + _readPos += _messageLength; + switch (type) + { + case (byte)'N': + LogNotice(); + continue; + case (byte)'S': + { + var pos = 0; + var name = ReadCString(Payload, ref pos); + _serverParameters[name] = ReadCString(Payload, ref pos); + continue; + } + case (byte)'A': + { + var pos = 4; + var channel = ReadCString(Payload, ref pos); + var payload = ReadCString(Payload, ref pos); + NotificationReceived?.Invoke(new PgNotification(BinaryPrimitives.ReadInt32BigEndian(Payload), channel, payload)); + continue; + } + default: + return type; + } + } + } + + private async ValueTask EnsureAsync(int count, CancellationToken cancellationToken) + { + if (_readEnd - _readPos >= count) return; + if (_readPos + count > _read.Length) + { + var target = count > _read.Length ? new byte[Math.Max(count, _read.Length * 2)] : _read; + Buffer.BlockCopy(_read, _readPos, target, 0, _readEnd - _readPos); + _read = target; + _readEnd -= _readPos; + _readPos = 0; + } + while (_readEnd - _readPos < count) + { + var n = await _stream.ReadAsync(_read.AsMemory(_readEnd), cancellationToken).ConfigureAwait(false); + if (n == 0) throw new EndOfStreamException("The server closed the connection."); + _readEnd += n; + } + } + + private DbColumns ParseRowDescription(out uint[] oids) + { + var payload = Payload; + var count = BinaryPrimitives.ReadInt16BigEndian(payload); + var names = new string[count]; + oids = new uint[count]; + var pos = 2; + for (var i = 0; i < count; i++) + { + names[i] = ReadCString(payload, ref pos); + oids[i] = BinaryPrimitives.ReadUInt32BigEndian(payload[(pos + 6)..]); + pos += 18; // table oid, column number, type oid, type size, type modifier, format + } + return new DbColumns(names); + } + + private DbRow DecodeRow(PgStatement statement) + { + var payload = Payload; + var oids = statement.ColumnOids ?? throw ProtocolViolation((byte)'D'); + var values = new object?[BinaryPrimitives.ReadInt16BigEndian(payload)]; + var pos = 2; + for (var i = 0; i < values.Length; i++) + { + var length = BinaryPrimitives.ReadInt32BigEndian(payload[pos..]); + pos += 4; + if (length < 0) continue; + values[i] = PgTypes.Decode(oids[i], payload.Slice(pos, length)); + pos += length; + } + return new DbRow(statement.Columns!, values); + } + + private string ReadTag() + { + var pos = 0; + return ReadCString(Payload, ref pos); + } + + /// Row count of an INSERT/UPDATE/DELETE/MERGE/COPY tag ("INSERT 0 5" → 5); 0 for other commands. + private static int AffectedRows(string tag) + { + var space = tag.LastIndexOf(' '); + if (space < 0) return 0; + var command = tag[..tag.IndexOf(' ', StringComparison.Ordinal)]; + if (command is not ("INSERT" or "UPDATE" or "DELETE" or "MERGE" or "COPY")) return 0; + return long.TryParse(tag.AsSpan(space + 1), NumberStyles.None, CultureInfo.InvariantCulture, out var n) ? (int)Math.Min(n, int.MaxValue) : 0; + } + + private PostgresException ParseError() + { + var fields = ParseFields(); + fields.TryGetValue('V', out var severity); + fields.TryGetValue('S', out var localized); + fields.TryGetValue('C', out var code); + fields.TryGetValue('M', out var message); + fields.TryGetValue('P', out var position); + return new PostgresException(severity ?? localized ?? "ERROR", code ?? "XX000", message ?? string.Empty) + { + Detail = fields.GetValueOrDefault('D'), + Hint = fields.GetValueOrDefault('H'), + Position = int.TryParse(position, NumberStyles.None, CultureInfo.InvariantCulture, out var p) ? p : null, + Where = fields.GetValueOrDefault('W'), + SchemaName = fields.GetValueOrDefault('s'), + TableName = fields.GetValueOrDefault('t'), + ColumnName = fields.GetValueOrDefault('c'), + ConstraintName = fields.GetValueOrDefault('n'), + }; + } + + private void LogNotice() + { + var fields = ParseFields(); + var severity = fields.GetValueOrDefault('V') ?? fields.GetValueOrDefault('S') ?? "NOTICE"; + var text = $"{severity} {fields.GetValueOrDefault('C')}: {fields.GetValueOrDefault('M')}"; + if (severity == "WARNING") Log.Warning(LogCategory, text); + else if (severity is "DEBUG" or "LOG") Log.Debug(LogCategory, text); + else Log.Info(LogCategory, text); + } + + private Dictionary ParseFields() + { + var payload = Payload; + var fields = new Dictionary(); + var pos = 0; + while (pos < payload.Length && payload[pos] != 0) + { + var field = (char)payload[pos++]; + fields[field] = ReadCString(payload, ref pos); + } + return fields; + } + + private static string ReadCString(ReadOnlySpan payload, ref int pos) + { + var end = payload[pos..].IndexOf((byte)0); + if (end < 0) throw new DatabaseConnectionException("Protocol violation: unterminated string."); + var value = Encoding.UTF8.GetString(payload.Slice(pos, end)); + pos += end + 1; + return value; + } + + /// State of one command: its statement, the first server error, and cancellation bookkeeping. + private sealed class Operation(PgConnector owner, string sql, DbParam[] parameters, bool decodeRows, CancellationToken cancellation) + { + public PgConnector Owner { get; } = owner; + public string Sql { get; } = sql; + public DbParam[] Parameters { get; } = parameters; + public uint[] ParameterOids { get; } = Array.ConvertAll(parameters, p => PgTypes.OidOf(p.Type)); + public bool DecodeRows { get; } = decodeRows; + public CancellationToken Cancellation { get; } = cancellation; + public CancellationTokenRegistration Registration { get; set; } + public PgStatement? Statement { get; set; } + public bool CacheHit { get; set; } + public bool CanRetryStale { get; set; } = true; + public PostgresException? Error { get; set; } + public string? Tag { get; set; } + public int Affected { get; set; } + public bool Completed { get; set; } + public bool CancelSent { get; set; } + } + + /// A server-side prepared statement and its result shape. + private sealed class PgStatement(string name, string sql, uint[] parameterOids) + { + public string Name { get; } = name; + public string Sql { get; } = sql; + public uint[] ParameterOids { get; } = parameterOids; + public DbColumns? Columns { get; private set; } + public uint[]? ColumnOids { get; private set; } + + public void SetColumns(DbColumns columns, uint[] oids) + { + Columns = columns; + ColumnOids = oids; + } + } +} diff --git a/src/Titano.Data/Postgres/PgListener.cs b/src/Titano.Data/Postgres/PgListener.cs new file mode 100644 index 00000000..dd5455c8 --- /dev/null +++ b/src/Titano.Data/Postgres/PgListener.cs @@ -0,0 +1,96 @@ +using Titano.Core.Diagnostics; + +namespace Titano.Data.Postgres; + +/// +/// LISTEN/NOTIFY on a dedicated connection (multi-instance job wake-ups). is raised on +/// a background thread; ends when the listener is disposed or faults if the connection +/// is lost, after which a new listener must be created. +/// +public sealed class PgListener : IAsyncDisposable +{ + private const string LogCategory = "Data.Postgres"; + private readonly PgConnector _connector; + private readonly SemaphoreSlim _commandLock = new(1, 1); + private readonly CancellationTokenSource _stop = new(); + private TaskCompletionSource? _pending; + + internal PgListener(PgConnector connector) + { + _connector = connector; + connector.NotificationReceived = Raise; + Completion = Task.Run(RunAsync); + } + + public event EventHandler? Notification; + + public Task Completion { get; } + + public Task ListenAsync(string channel, CancellationToken cancellationToken = default) => + CommandAsync("LISTEN " + SqlDialect.QuoteIdentifier(channel), cancellationToken); + + public Task UnlistenAsync(string channel, CancellationToken cancellationToken = default) => + CommandAsync("UNLISTEN " + SqlDialect.QuoteIdentifier(channel), cancellationToken); + + public async ValueTask DisposeAsync() + { + if (_stop.IsCancellationRequested) return; + await _stop.CancelAsync().ConfigureAwait(false); + await _connector.DisposeAsync().ConfigureAwait(false); + try + { + await Completion.ConfigureAwait(false); + } + catch (Exception ex) when (ex is DatabaseException or OperationCanceledException) + { + // The loop ends with whatever the closed socket raised. + } + _stop.Dispose(); + } + + private async Task CommandAsync(string sql, CancellationToken cancellationToken) + { + ObjectDisposedException.ThrowIf(_stop.IsCancellationRequested, this); + await _commandLock.WaitAsync(cancellationToken).ConfigureAwait(false); + try + { + if (Completion.IsCompleted) throw new DatabaseConnectionException("The listener connection is closed.", Completion.Exception?.InnerException); + var pending = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + Volatile.Write(ref _pending, pending); + await _connector.SendQueryAsync(sql, cancellationToken).ConfigureAwait(false); + if (await pending.Task.WaitAsync(cancellationToken).ConfigureAwait(false) is { } error) throw error; + } + finally + { + _commandLock.Release(); + } + } + + private async Task RunAsync() + { + try + { + await _connector.RunListenerAsync(error => Volatile.Read(ref _pending)?.TrySetResult(error), _stop.Token).ConfigureAwait(false); + } + catch (Exception) when (_stop.IsCancellationRequested) + { + } + finally + { + Volatile.Read(ref _pending)?.TrySetException(new DatabaseConnectionException("The listener connection is closed.")); + } + } + + private void Raise(PgNotification notification) + { + try + { + Notification?.Invoke(this, notification); + } + catch (Exception ex) + { + // A faulty handler must not stop delivery to the others. + Log.Error(LogCategory, $"Notification handler failed for channel '{notification.Channel}'.", ex); + } + } +} diff --git a/src/Titano.Data/Postgres/PgPool.cs b/src/Titano.Data/Postgres/PgPool.cs new file mode 100644 index 00000000..2e2002b6 --- /dev/null +++ b/src/Titano.Data/Postgres/PgPool.cs @@ -0,0 +1,128 @@ +using System.Net.Sockets; +using Titano.Core.Diagnostics; + +namespace Titano.Data.Postgres; + +/// +/// Connection pool: at most Maximum Pool Size connections, reused most-recent-first; a connection idle +/// longer than Health Check Interval is pinged with SELECT 1 before reuse; broken connections and +/// those left inside a transaction are discarded; idle ones beyond Minimum Pool Size are closed after +/// Connection Idle Lifetime. +/// +internal sealed class PgPool : IAsyncDisposable +{ + private const string LogCategory = "Data.Postgres"; + private static readonly TimeSpan PruneInterval = TimeSpan.FromSeconds(10); + + private readonly PostgresSettings _settings; + private readonly SemaphoreSlim _slots; + private readonly LinkedList _idle = new(); + private readonly Lock _gate = new(); + private readonly Timer _pruner; + private bool _disposed; + + public PgPool(PostgresSettings settings) + { + _settings = settings; + _slots = new SemaphoreSlim(settings.MaxPoolSize, settings.MaxPoolSize); + var interval = settings.IdleLifetime < PruneInterval ? settings.IdleLifetime : PruneInterval; + _pruner = new Timer(static state => ((PgPool)state!).Prune(), this, interval, interval); + } + + public async Task RentAsync(CancellationToken cancellationToken) + { + ObjectDisposedException.ThrowIf(_disposed, this); + if (!await _slots.WaitAsync(_settings.ConnectTimeout, cancellationToken).ConfigureAwait(false)) + throw new DatabaseConnectionException($"No pooled connection became free within {_settings.ConnectTimeout.TotalSeconds} s (Maximum Pool Size={_settings.MaxPoolSize})."); + try + { + while (TakeIdle() is { } connector) + { + if (!connector.IsBroken + && (connector.IdleTime < _settings.HealthCheckInterval || await connector.PingAsync(cancellationToken).ConfigureAwait(false))) + return connector; + await connector.DisposeAsync().ConfigureAwait(false); + } + return await OpenAsync(cancellationToken).ConfigureAwait(false); + } + catch + { + _slots.Release(); + throw; + } + } + + /// Takes a connection back; a broken one, or one not idle at transaction level, is closed instead. + public void Return(PgConnector connector) + { + PgConnector? discard = connector; + if (!connector.IsBroken && connector.TransactionStatus == 'I') + { + connector.MarkIdle(); + lock (_gate) + { + if (!_disposed) + { + _idle.AddFirst(connector); + discard = null; + } + } + } + if (discard is not null) _ = discard.DisposeAsync().AsTask(); + _slots.Release(); + } + + public async ValueTask DisposeAsync() + { + List idle; + lock (_gate) + { + if (_disposed) return; + _disposed = true; + idle = [.. _idle]; + _idle.Clear(); + } + await _pruner.DisposeAsync().ConfigureAwait(false); + foreach (var connector in idle) await connector.DisposeAsync().ConfigureAwait(false); + } + + /// Opens a connection, retrying once after a second when the server is starting up or refused it. + private async Task OpenAsync(CancellationToken cancellationToken) + { + try + { + return await PgConnector.OpenAsync(_settings, cancellationToken).ConfigureAwait(false); + } + catch (Exception ex) when (ex is PostgresException { IsConnectionFailure: true } or DatabaseConnectionException { InnerException: SocketException }) + { + Log.Warning(LogCategory, $"Connecting to {_settings.Host}:{_settings.Port} failed ({ex.Message}); retrying once."); + await Task.Delay(TimeSpan.FromSeconds(1), cancellationToken).ConfigureAwait(false); + return await PgConnector.OpenAsync(_settings, cancellationToken).ConfigureAwait(false); + } + } + + private PgConnector? TakeIdle() + { + lock (_gate) + { + if (_idle.First is not { } first) return null; + _idle.RemoveFirst(); + return first.Value; + } + } + + private void Prune() + { + List? expired = null; + lock (_gate) + { + while (_idle.Count > _settings.MinPoolSize && _idle.Last is { } last && last.Value.IdleTime >= _settings.IdleLifetime) + { + _idle.RemoveLast(); + (expired ??= []).Add(last.Value); + } + } + if (expired is null) return; + foreach (var connector in expired) _ = connector.DisposeAsync().AsTask(); + } +} diff --git a/src/Titano.Data/Postgres/PgTypes.cs b/src/Titano.Data/Postgres/PgTypes.cs new file mode 100644 index 00000000..0f8d3302 --- /dev/null +++ b/src/Titano.Data/Postgres/PgTypes.cs @@ -0,0 +1,219 @@ +using System.Buffers; +using System.Buffers.Text; +using System.Globalization; +using System.Text; + +namespace Titano.Data.Postgres; + +/// Type OIDs, text-format value encoding and result decoding (BRIEF §6.3 type mapping). +internal static class PgTypes +{ + public const uint Bool = 16; + public const uint Bytea = 17; + public const uint Char = 18; + public const uint Name = 19; + public const uint Int8 = 20; + public const uint Int2 = 21; + public const uint Int4 = 23; + public const uint Text = 25; + public const uint Oid = 26; + public const uint Json = 114; + public const uint Float4 = 700; + public const uint Float8 = 701; + public const uint Bpchar = 1042; + public const uint Varchar = 1043; + public const uint Date = 1082; + public const uint Timestamp = 1114; + public const uint TimestampTz = 1184; + public const uint Numeric = 1700; + public const uint Uuid = 2950; + public const uint Jsonb = 3802; + + private static readonly SearchValues CopySpecials = SearchValues.Create("\\\t\n\r"); + + /// Parameter type sent in Parse; 0 lets the server infer an untyped NULL. + public static uint OidOf(DbValueType type) => type switch + { + DbValueType.Text => Text, + DbValueType.Int32 => Int4, + DbValueType.Int64 => Int8, + DbValueType.Double => Float8, + DbValueType.Bool => Bool, + DbValueType.Uuid => Uuid, + DbValueType.Timestamp => TimestampTz, + DbValueType.LocalDateTime => Timestamp, + DbValueType.Bytes => Bytea, + DbValueType.Json => Jsonb, + _ => 0, + }; + + /// + /// Writes the text form of a canonical value (anything but byte[]) as UTF-8 and returns + /// the byte count. must hold bytes. + /// + public static int FormatText(object value, Span destination) + { + var inv = CultureInfo.InvariantCulture; + int written; + bool ok; + switch (value) + { + case string s: + return Encoding.UTF8.GetBytes(s, destination); + case bool b: + destination[0] = b ? (byte)'t' : (byte)'f'; + return 1; + case int i: + ok = i.TryFormat(destination, out written, default, inv); + break; + case long l: + ok = l.TryFormat(destination, out written, default, inv); + break; + case double d: + ok = d.TryFormat(destination, out written, "R", inv); + break; + case Guid g: + ok = g.TryFormat(destination, out written, "D"); + break; + case DateTimeOffset o: + ok = o.UtcDateTime.TryFormat(destination, out written, "yyyy-MM-dd'T'HH:mm:ss.ffffff'Z'", inv); + break; + case DateTime d: + ok = d.TryFormat(destination, out written, "yyyy-MM-dd'T'HH:mm:ss.ffffff", inv); + break; + default: + throw new NotSupportedException($"Cannot send {value.GetType().Name} as text."); + } + return ok ? written : throw new FormatException($"Cannot format {value}."); + } + + /// Upper bound of output for . + public static int MaxTextLength(object value) => value is string s ? Encoding.UTF8.GetMaxByteCount(s.Length) : 64; + + /// + /// Writes a value in COPY text format: \N for NULL, specials in strings backslash-escaped, bytea in + /// hex form (\\x…). Values of other CLR types go through normalisation. + /// + public static void WriteCopyValue(object? value, IBufferWriter writer) + { + switch (value) + { + case null: + writer.Write("\\N"u8); + return; + case string s: + WriteCopyEscaped(s, writer); + return; + case byte[] bytes: + { + var span = writer.GetSpan(3 + bytes.Length * 2); + "\\\\x"u8.CopyTo(span); + for (var i = 0; i < bytes.Length; i++) + { + span[3 + 2 * i] = HexDigits[bytes[i] >> 4]; + span[4 + 2 * i] = HexDigits[bytes[i] & 0xF]; + } + writer.Advance(3 + bytes.Length * 2); + return; + } + case int or long or double or bool or Guid or DateTimeOffset: + case DateTime { Kind: DateTimeKind.Unspecified }: + writer.Advance(FormatText(value, writer.GetSpan(64))); + return; + default: + var normalized = new DbParam(value); + WriteCopyValue(normalized.Value, writer); + return; + } + } + + private static void WriteCopyEscaped(string s, IBufferWriter writer) + { + var rest = s.AsSpan(); + while (!rest.IsEmpty) + { + var special = rest.IndexOfAny(CopySpecials); + var plain = special < 0 ? rest : rest[..special]; + if (!plain.IsEmpty) + { + var n = Encoding.UTF8.GetBytes(plain, writer.GetSpan(Encoding.UTF8.GetMaxByteCount(plain.Length))); + writer.Advance(n); + } + if (special < 0) return; + writer.Write(rest[special] switch + { + '\\' => "\\\\"u8, + '\t' => "\\t"u8, + '\n' => "\\n"u8, + _ => "\\r"u8, + }); + rest = rest[(special + 1)..]; + } + } + + /// Decodes a text-format result value by its type OID; unknown types stay strings. + public static object Decode(uint oid, ReadOnlySpan utf8) + { + var inv = CultureInfo.InvariantCulture; + switch (oid) + { + case Bool: + return utf8.Length > 0 && utf8[0] == (byte)'t'; + case Int2 or Int4: + return int.Parse(utf8, NumberStyles.AllowLeadingSign, inv); + case Int8 or Oid: + return long.Parse(utf8, NumberStyles.AllowLeadingSign, inv); + case Float4 or Float8: + return double.Parse(utf8, NumberStyles.Float, inv); + case Uuid: + return Utf8Parser.TryParse(utf8, out Guid guid, out var consumed) && consumed == utf8.Length + ? guid + : throw new FormatException("Malformed uuid."); + case Bytea: + return DecodeBytea(utf8); + case TimestampTz or Timestamp or Date when utf8.Length <= 64: + Span chars = stackalloc char[utf8.Length]; + Encoding.ASCII.GetChars(utf8, chars); + return oid switch + { + TimestampTz => TextValues.ParseTimestamp(chars), + Timestamp => TextValues.ParseLocal(chars), + _ => DateOnly.ParseExact(chars, "yyyy-MM-dd", inv), + }; + default: + return Encoding.UTF8.GetString(utf8); + } + } + + /// bytea output: hex (\x0a0b, the default since 9.0) or the legacy escape format. + private static byte[] DecodeBytea(ReadOnlySpan text) + { + if (text.Length >= 2 && text[0] == '\\' && text[1] == 'x') + return Convert.FromHexString(Encoding.ASCII.GetString(text[2..])); + var result = new List(text.Length); + for (var i = 0; i < text.Length; i++) + { + if (text[i] != '\\') + { + result.Add(text[i]); + } + else if (i + 1 < text.Length && text[i + 1] == '\\') + { + result.Add((byte)'\\'); + i++; + } + else if (i + 3 < text.Length) + { + result.Add((byte)(((text[i + 1] - '0') << 6) | ((text[i + 2] - '0') << 3) | (text[i + 3] - '0'))); + i += 3; + } + else + { + throw new FormatException("Malformed bytea escape sequence."); + } + } + return [.. result]; + } + + private static ReadOnlySpan HexDigits => "0123456789abcdef"u8; +} diff --git a/src/Titano.Data/Postgres/PgWriteBuffer.cs b/src/Titano.Data/Postgres/PgWriteBuffer.cs new file mode 100644 index 00000000..6c761553 --- /dev/null +++ b/src/Titano.Data/Postgres/PgWriteBuffer.cs @@ -0,0 +1,98 @@ +using System.Buffers; +using System.Buffers.Binary; +using System.Text; + +namespace Titano.Data.Postgres; + +/// Growable outgoing buffer that frames protocol messages (type byte + big-endian length). +internal sealed class PgWriteBuffer : IBufferWriter +{ + private byte[] _buffer = new byte[8192]; + private int _messageStart = -1; + + public int Length { get; private set; } + + public ReadOnlyMemory Written => _buffer.AsMemory(0, Length); + + /// Starts a message; its length is patched by . + public void StartMessage(char type) + { + GetSpan(1)[0] = (byte)type; + Advance(1); + StartUntypedMessage(); + } + + /// Starts a message without a type byte (startup, SSL and cancel requests). + public void StartUntypedMessage() + { + _messageStart = Length; + Advance(4); + } + + public void EndMessage() + { + BinaryPrimitives.WriteInt32BigEndian(_buffer.AsSpan(_messageStart), Length - _messageStart); + _messageStart = -1; + } + + public void WriteByte(byte value) + { + GetSpan(1)[0] = value; + Advance(1); + } + + public void WriteInt16(int value) + { + BinaryPrimitives.WriteInt16BigEndian(GetSpan(2), checked((short)value)); + Advance(2); + } + + public void WriteInt32(int value) + { + BinaryPrimitives.WriteInt32BigEndian(GetSpan(4), value); + Advance(4); + } + + public void Write(ReadOnlySpan bytes) + { + bytes.CopyTo(GetSpan(bytes.Length)); + Advance(bytes.Length); + } + + /// UTF-8 text followed by a NUL terminator. + public void WriteCString(string text) + { + var n = Encoding.UTF8.GetBytes(text, GetSpan(Encoding.UTF8.GetMaxByteCount(text.Length) + 1)); + _buffer[Length + n] = 0; + Advance(n + 1); + } + + /// Empties the buffer; an oversized one (a big bytea parameter) is released so pooled connections stay small. + public void Clear() + { + Length = 0; + _messageStart = -1; + if (_buffer.Length > 1 << 20) _buffer = new byte[8192]; + } + + public void Advance(int count) => Length += count; + + public Memory GetMemory(int sizeHint = 0) + { + Ensure(sizeHint); + return _buffer.AsMemory(Length); + } + + public Span GetSpan(int sizeHint = 0) + { + Ensure(sizeHint); + return _buffer.AsSpan(Length); + } + + private void Ensure(int sizeHint) + { + var needed = Length + Math.Max(sizeHint, 1); + if (needed <= _buffer.Length) return; + Array.Resize(ref _buffer, Math.Max(needed, _buffer.Length * 2)); + } +} diff --git a/src/Titano.Data/Postgres/PostgresDatabase.cs b/src/Titano.Data/Postgres/PostgresDatabase.cs new file mode 100644 index 00000000..81fc0417 --- /dev/null +++ b/src/Titano.Data/Postgres/PostgresDatabase.cs @@ -0,0 +1,216 @@ +using System.Runtime.CompilerServices; +using Titano.Core.Diagnostics; + +namespace Titano.Data.Postgres; + +/// A PostgreSQL server reached through the in-house protocol v3 client and its connection pool. +public sealed class PostgresDatabase(PostgresSettings settings) : IDatabase +{ + private readonly PgPool _pool = new(settings); + + public PostgresSettings Settings { get; } = settings; + + public Dialect Dialect => Dialect.Postgres; + + public async Task OpenAsync(CancellationToken cancellationToken) => + new PostgresSession(_pool, await _pool.RentAsync(cancellationToken).ConfigureAwait(false)); + + /// Opens a dedicated (unpooled) connection that raises an event for every NOTIFY on its channels. + public async Task CreateListenerAsync(CancellationToken cancellationToken = default) => + new(await PgConnector.OpenAsync(Settings, cancellationToken).ConfigureAwait(false)); + + public ValueTask DisposeAsync() => _pool.DisposeAsync(); +} + +/// +/// A pooled PostgreSQL connection. Reads (SELECT/VALUES/SHOW/TABLE) outside a transaction are retried once on a +/// fresh connection when the first attempt fails with a connection error before returning any row. +/// +internal sealed class PostgresSession(PgPool pool, PgConnector connector) : IDbSession +{ + private const string LogCategory = "Data.Postgres"; + private PgConnector? _connector = connector; + private PostgresTransaction? _transaction; + private bool _disposed; + + public Dialect Dialect => Dialect.Postgres; + + public bool InTransaction => _transaction is not null; + + private PgConnector Connector + { + get + { + ObjectDisposedException.ThrowIf(_disposed, this); + return _connector ?? throw new DatabaseConnectionException("The session lost its connection."); + } + } + + public Task ExecuteAsync(string sql, DbParam[] parameters, CancellationToken cancellationToken) => + Connector.ExecuteAsync(sql, parameters, cancellationToken); + + public async IAsyncEnumerable QueryAsync(string sql, DbParam[] parameters, [EnumeratorCancellation] CancellationToken cancellationToken) + { + var retry = _transaction is null && IsReadOnlyQuery(sql); + while (true) + { + var rows = Connector.QueryAsync(sql, parameters, cancellationToken).GetAsyncEnumerator(CancellationToken.None); + var yielded = false; + Exception? failure = null; + try + { + while (true) + { + bool more; + try + { + more = await rows.MoveNextAsync().ConfigureAwait(false); + } + catch (Exception ex) when (retry && !yielded && IsConnectionFailure(ex)) + { + failure = ex; + break; + } + if (!more) yield break; + yielded = true; + yield return rows.Current; + } + } + finally + { + await rows.DisposeAsync().ConfigureAwait(false); + } + Log.Warning(LogCategory, $"Retrying a read on a new connection after: {failure!.Message}"); + retry = false; + var broken = _connector!; + _connector = null; + pool.Return(broken); + _connector = await pool.RentAsync(cancellationToken).ConfigureAwait(false); + } + } + + public Task ExecuteScriptAsync(string script, CancellationToken cancellationToken) => + Connector.SimpleQueryAsync(script, cancellationToken); + + public async Task BeginAsync(CancellationToken cancellationToken) + { + if (_transaction is not null) throw new InvalidOperationException("A transaction is already active on this session."); + await Connector.SimpleQueryAsync("BEGIN", cancellationToken).ConfigureAwait(false); + return _transaction = new PostgresTransaction(this); + } + + public Task BulkInsertAsync(string table, IReadOnlyList columns, IAsyncEnumerable rows, CancellationToken cancellationToken) + { + if (columns.Count == 0) throw new ArgumentException("At least one column is required.", nameof(columns)); + var sql = $"COPY {SqlDialect.QuoteIdentifier(table)} ({string.Join(", ", columns.Select(SqlDialect.QuoteIdentifier))}) FROM STDIN"; + return Connector.CopyInAsync(sql, columns.Count, rows, cancellationToken); + } + + public async ValueTask DisposeAsync() + { + if (_disposed) return; + _disposed = true; + if (_connector is not { } connection) return; + _connector = null; + if (_transaction is not null && !connection.IsBroken) + { + try + { + await connection.SimpleQueryAsync("ROLLBACK", CancellationToken.None).ConfigureAwait(false); + } + catch (DatabaseException ex) + { + Log.Warning(LogCategory, "Rollback on session close failed; the connection is discarded.", ex); + } + } + _transaction = null; + pool.Return(connection); + } + + /// Ends if it is still active. COMMIT of an aborted transaction is reported, not silently rolled back. + internal async Task EndTransactionAsync(PostgresTransaction transaction, bool commit, CancellationToken cancellationToken) + { + if (_transaction != transaction) return; + try + { + if (!commit) + { + await Connector.SimpleQueryAsync("ROLLBACK", cancellationToken).ConfigureAwait(false); + } + else if (Connector.TransactionStatus == 'E') + { + await Connector.SimpleQueryAsync("ROLLBACK", cancellationToken).ConfigureAwait(false); + throw new InvalidOperationException("The transaction was aborted by an earlier error and has been rolled back."); + } + else if (await Connector.SimpleQueryAsync("COMMIT", cancellationToken).ConfigureAwait(false) == "ROLLBACK") + { + throw new InvalidOperationException("The server rolled the transaction back instead of committing it."); + } + } + finally + { + if (_connector is not { IsBroken: false, TransactionStatus: not 'I' }) _transaction = null; + } + } + + private static bool IsConnectionFailure(Exception ex) => + ex is DatabaseConnectionException or PostgresException { IsConnectionFailure: true }; + + /// True for statements that only read, so running them twice is harmless. + internal static bool IsReadOnlyQuery(string sql) + { + var s = sql.AsSpan(); + while (true) + { + s = s.TrimStart(); + if (s.StartsWith("--", StringComparison.Ordinal)) + { + var newline = s.IndexOf('\n'); + s = newline < 0 ? default : s[(newline + 1)..]; + } + else if (s.StartsWith("/*", StringComparison.Ordinal)) + { + var end = s.IndexOf("*/", StringComparison.Ordinal); + s = end < 0 ? default : s[(end + 2)..]; + } + else + { + break; + } + } + foreach (var keyword in (ReadOnlySpan)["SELECT", "VALUES", "SHOW", "TABLE"]) + { + if (s.StartsWith(keyword, StringComparison.OrdinalIgnoreCase) + && (s.Length == keyword.Length || !(char.IsLetterOrDigit(s[keyword.Length]) || s[keyword.Length] == '_'))) + return true; + } + return false; + } +} + +/// A BEGIN … COMMIT block on one session. +internal sealed class PostgresTransaction(PostgresSession session) : IDbTransaction +{ + private bool _completed; + + public async Task CommitAsync(CancellationToken cancellationToken = default) + { + ObjectDisposedException.ThrowIf(_completed, this); + _completed = true; + await session.EndTransactionAsync(this, commit: true, cancellationToken).ConfigureAwait(false); + } + + public async Task RollbackAsync(CancellationToken cancellationToken = default) + { + ObjectDisposedException.ThrowIf(_completed, this); + _completed = true; + await session.EndTransactionAsync(this, commit: false, cancellationToken).ConfigureAwait(false); + } + + public async ValueTask DisposeAsync() + { + if (_completed) return; + _completed = true; + await session.EndTransactionAsync(this, commit: false, CancellationToken.None).ConfigureAwait(false); + } +} diff --git a/src/Titano.Data/Postgres/PostgresException.cs b/src/Titano.Data/Postgres/PostgresException.cs new file mode 100644 index 00000000..92a1159c --- /dev/null +++ b/src/Titano.Data/Postgres/PostgresException.cs @@ -0,0 +1,47 @@ +namespace Titano.Data.Postgres; + +/// An ErrorResponse from the server, with the standard fields of the PostgreSQL protocol. +public sealed class PostgresException : DatabaseException +{ + internal PostgresException(string severity, string sqlState, string messageText) + : base($"{severity} {sqlState}: {messageText}") + { + Severity = severity; + SqlState = sqlState; + MessageText = messageText; + } + + /// ERROR, FATAL or PANIC (non-localised when the server sends it). + public string Severity { get; } + + /// Five-character SQLSTATE, e.g. 23505 (unique_violation). + public override string SqlState { get; } + + /// The primary human-readable message. + public string MessageText { get; } + + public string? Detail { get; internal init; } + public string? Hint { get; internal init; } + + /// 1-based character position of the error in the statement text. + public int? Position { get; internal init; } + + public string? Where { get; internal init; } + public string? SchemaName { get; internal init; } + public string? TableName { get; internal init; } + public string? ColumnName { get; internal init; } + public string? ConstraintName { get; internal init; } + + /// The server ends the session after FATAL/PANIC errors. + public bool IsFatal => Severity is "FATAL" or "PANIC"; + + /// Server shutdown/startup or connection failures (57P01, 57P02, 57P03, class 08): a new connection may succeed. + public bool IsConnectionFailure => SqlState is "57P01" or "57P02" or "57P03" || SqlState.StartsWith("08", StringComparison.Ordinal); + + /// Connection failures plus serialization failures and deadlocks. + public override bool IsTransient => IsConnectionFailure || SqlState is "40001" or "40P01"; + + public override bool IsUniqueViolation => SqlState == "23505"; + + public override bool IsForeignKeyViolation => SqlState == "23503"; +} diff --git a/src/Titano.Data/Postgres/PostgresSettings.cs b/src/Titano.Data/Postgres/PostgresSettings.cs new file mode 100644 index 00000000..76e003d6 --- /dev/null +++ b/src/Titano.Data/Postgres/PostgresSettings.cs @@ -0,0 +1,84 @@ +namespace Titano.Data.Postgres; + +/// TLS policy, with libpq's meaning. +public enum SslMode +{ + /// Plain TCP. + Disable, + + /// TLS when the server offers it, without certificate verification; plain TCP otherwise. + Prefer, + + /// TLS or fail; the certificate is not verified. + Require, + + /// TLS with a trusted chain whose certificate matches the host name. + VerifyFull, +} + +/// +/// PostgreSQL connection settings. Keys (case/space-insensitive): Host, Port (5432), Database +/// (defaults to the user), Username, Password, SslMode (prefer), Root Certificate +/// (PEM trusted by verify-full), Application Name (titano-server), Search Path, Timeout +/// (connect, 15 s), Minimum Pool Size (0), Maximum Pool Size (20), Connection Idle Lifetime +/// (300 s), Health Check Interval (30 s idle before a pooled connection is pinged), +/// Statement Cache Size (128 prepared statements per connection; 0 disables). +/// +public sealed record PostgresSettings +{ + public required string Host { get; init; } + public int Port { get; init; } = 5432; + public required string Database { get; init; } + public required string Username { get; init; } + public string? Password { get; init; } + public SslMode SslMode { get; init; } = SslMode.Prefer; + public string? RootCertificate { get; init; } + public string ApplicationName { get; init; } = "titano-server"; + public string? SearchPath { get; init; } + public TimeSpan ConnectTimeout { get; init; } = TimeSpan.FromSeconds(15); + public int MinPoolSize { get; init; } + public int MaxPoolSize { get; init; } = 20; + public TimeSpan IdleLifetime { get; init; } = TimeSpan.FromSeconds(300); + public TimeSpan HealthCheckInterval { get; init; } = TimeSpan.FromSeconds(30); + public int StatementCacheSize { get; init; } = 128; + + public static PostgresSettings Parse(string connectionString) + { + var cs = new ConnectionString(connectionString); + var host = cs.Get("Host", "Server") ?? throw new FormatException("A PostgreSQL connection string needs 'Host'."); + var user = cs.Get("Username", "User Id", "User", "UserName") ?? throw new FormatException("A PostgreSQL connection string needs 'Username'."); + var settings = new PostgresSettings + { + Host = host, + Port = cs.GetInt(5432, "Port"), + Username = user, + Database = cs.Get("Database", "DB") ?? user, + Password = cs.Get("Password", "Pwd"), + SslMode = ParseSslMode(cs.Get("SslMode", "Ssl Mode")), + RootCertificate = cs.Get("Root Certificate", "SslRootCert"), + ApplicationName = cs.Get("Application Name") ?? "titano-server", + SearchPath = cs.Get("Search Path"), + ConnectTimeout = TimeSpan.FromSeconds(cs.GetInt(15, "Timeout", "Connect Timeout")), + MinPoolSize = cs.GetInt(0, "Minimum Pool Size", "Min Pool Size"), + MaxPoolSize = cs.GetInt(20, "Maximum Pool Size", "Max Pool Size"), + IdleLifetime = TimeSpan.FromSeconds(cs.GetInt(300, "Connection Idle Lifetime")), + HealthCheckInterval = TimeSpan.FromSeconds(cs.GetInt(30, "Health Check Interval")), + StatementCacheSize = cs.GetInt(128, "Statement Cache Size", "Max Auto Prepare"), + }; + cs.ThrowOnUnknownKeys(); + if (settings.MaxPoolSize < 1 || settings.MinPoolSize < 0 || settings.MinPoolSize > settings.MaxPoolSize) + throw new FormatException("Pool sizes must satisfy 0 ≤ Minimum Pool Size ≤ Maximum Pool Size, Maximum ≥ 1."); + if (settings.StatementCacheSize < 0 || settings.ConnectTimeout <= TimeSpan.Zero) + throw new FormatException("'Statement Cache Size' must be ≥ 0 and 'Timeout' > 0."); + return settings; + } + + private static SslMode ParseSslMode(string? value) => value?.Trim().ToLowerInvariant() switch + { + null or "" or "prefer" => SslMode.Prefer, + "disable" => SslMode.Disable, + "require" => SslMode.Require, + "verify-full" or "verifyfull" => SslMode.VerifyFull, + _ => throw new FormatException($"Unsupported SslMode '{value}' (use disable, prefer, require or verify-full)."), + }; +}