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.Authentication; using System.Security.Cryptography.X509Certificates; using System.Text; using Chronos.Core.Diagnostics; namespace Chronos.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 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 Operation? _active; 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'; /// A command's response is still being read (an enumeration that was neither finished nor disposed). public bool IsBusy => _active is not null; public TimeSpan IdleTime => TimeSpan.FromMilliseconds(Environment.TickCount64 - _idleSince); /// 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"); Parameter("bytea_output", "hex"); // LIKE … ESCAPE '\' in the repositories needs backslashes to be literal in string constants. Parameter("standard_conforming_strings", "on"); 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: // A server that started SCRAM must finish it: only its final signature proves it knows the password. if (scram is { IsServerVerified: false }) throw new AuthenticationException("The server skipped the final SCRAM message."); 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."); if (IsBusy) throw new InvalidOperationException("A command is still running on this session; finish or dispose its enumeration first."); cancellationToken.ThrowIfCancellationRequested(); var op = new Operation(this, sql, parameters, decodeRows, cancellationToken); _active = op; 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(); } // A huge row (a large bytea) grew the buffer; do not keep it for the life of a pooled connection. if (_read.Length > 1 << 20 && _readPos == _readEnd) { _read = new byte[16 * 1024]; _readPos = _readEnd = 0; } _active = null; 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 ? "chronos_" + (++_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': // ParameterStatus: the settings the decoder relies on are pinned in the startup packet. 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; } } }