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;
}
}
}