diff --git a/src/Qqq.PrintAgent.Core/Printing/PrintingRealtimeChannel.cs b/src/Qqq.PrintAgent.Core/Printing/PrintingRealtimeChannel.cs
index ee8382c..3ee8faa 100644
--- a/src/Qqq.PrintAgent.Core/Printing/PrintingRealtimeChannel.cs
+++ b/src/Qqq.PrintAgent.Core/Printing/PrintingRealtimeChannel.cs
@@ -5,6 +5,7 @@
using System.Collections.Concurrent;
using System.Net.WebSockets;
+using System.Runtime.ExceptionServices;
using System.Text.Json;
using System.Threading.Channels;
using Qqq.PrintAgent.Core.Transport;
@@ -56,6 +57,14 @@ public sealed class PrintingRealtimeChannel(WebSocket socket, RealtimeSettings l
/// cancellation while the caller's token is not cancelled ends the method as that cancellation, because it was not
/// the caller who asked to stop.
///
+ ///
+ /// A socket that is being ended refuses the next call on it, and a loop that is about to use the socket at that
+ /// moment fails on it instead of seeing the cancellation. The socket is ended twice over on a deliberate stop: the
+ /// platform socket aborts itself as soon as the token of a call in flight is cancelled, and this shutdown aborts it
+ /// again. A failure of that kind (the socket is disposed, or in an invalid state) is the stop itself and is not
+ /// reported when the caller had cancelled, or when the loop had not failed before this shutdown began. Any other
+ /// failure is reported whenever it arrives, even beside a cancellation.
+ ///
///
public async Task RunAsync(Action received, CancellationToken token)
{
@@ -65,15 +74,27 @@ public sealed class PrintingRealtimeChannel(WebSocket socket, RealtimeSettings l
Task ended = await Task.WhenAny(reader, writer).ConfigureAwait(false);
////////////////////////////////////////////////////////////////////////
- // read before the teardown below, so a channel that failed first and //
- // was disposed a moment later still reports its failure //
+ // read before the teardown below: whether the channel was disposed, //
+ // so one that failed first and was disposed a moment later still //
+ // reports its failure; and which loop had already failed while the //
+ // caller had not cancelled, because only such a failure can be told //
+ // from the socket refusing a call as it is being ended //
////////////////////////////////////////////////////////////////////////
bool disposed = Volatile.Read(ref _disposed) != 0;
+ bool callerCancelled = token.IsCancellationRequested;
+ bool readerFailedFirst = reader.IsFaulted && !callerCancelled;
+ bool writerFailedFirst = writer.IsFaulted && !callerCancelled;
Interlocked.Exchange(ref _closed, 1);
_outgoing.Writer.TryComplete();
await lifetime.CancelAsync().ConfigureAwait(false);
socket.Abort();
- Exception? cause = ended.Exception?.InnerException;
+
+ ///////////////////////////////////////////////////////////////////////
+ // a send still waiting for its acknowledgement is told why the //
+ // channel closed. a refusal the run takes to be the caller's stop //
+ // is not a cause, so the waiting send and the run say the same //
+ ///////////////////////////////////////////////////////////////////////
+ Exception? cause = FailureOf(ended, !callerCancelled);
foreach(TaskCompletionSource pending in _pending.Values)
{
pending.TrySetException(new RealtimeChannelClosedException("Realtime connection closed before acknowledgement; durable receipts will be replayed.", cause));
@@ -84,11 +105,32 @@ public sealed class PrintingRealtimeChannel(WebSocket socket, RealtimeSettings l
/////////////////////////////////////////////////////////////////////////
// ended on purpose: disposed (whatever the loops met on a socket that //
// was disposed under them is the dispose itself), or cancelled by the //
- // caller with neither loop having failed. anything else is rethrown: //
- // a failure, the reader's first, or a cancellation nobody asked for //
+ // caller with no failure but the socket refusing a call as it ended. //
+ // anything else is rethrown: a failure, the reader's first, or a //
+ // cancellation nobody asked for //
/////////////////////////////////////////////////////////////////////////
- if(!disposed && !(both.IsCanceled && token.IsCancellationRequested))
- { await both.ConfigureAwait(false); }
+ if(disposed)
+ { return; }
+ Exception? failure = FailureOf(reader, readerFailedFirst) ?? FailureOf(writer, writerFailedFirst);
+ if(failure is not null)
+ { ExceptionDispatchInfo.Throw(failure); }
+ if(!token.IsCancellationRequested)
+ { await (reader.IsCanceled ? reader : writer.IsCanceled ? writer : both).ConfigureAwait(false); }
+ }
+
+
+
+ ///
+ /// What a loop failed with, or null when it did not fail or its failure is only the stop. A socket that has been
+ /// aborted refuses a call in one of two ways: it is disposed, or it is in an invalid state. A loop that met that,
+ /// and is not known to have failed before the stop, was stopped by the abort and not by anything the server or the
+ /// network did. A connection the server dropped fails differently (closed prematurely) and is always reported.
+ ///
+ private static Exception? FailureOf(Task loop, bool failedBeforeStop)
+ {
+ Exception? failure = loop.Exception?.InnerException;
+ bool refusedByAnEndedSocket = failure is ObjectDisposedException || (failure is WebSocketException { WebSocketErrorCode: WebSocketError.InvalidState });
+ return failure is null || (!failedBeforeStop && refusedByAnEndedSocket) ? null : failure;
}
diff --git a/tests/Qqq.PrintAgent.Core.Tests/ApplicationTrafficTransportTests.cs b/tests/Qqq.PrintAgent.Core.Tests/ApplicationTrafficTransportTests.cs
index 5093642..f3d375c 100644
--- a/tests/Qqq.PrintAgent.Core.Tests/ApplicationTrafficTransportTests.cs
+++ b/tests/Qqq.PrintAgent.Core.Tests/ApplicationTrafficTransportTests.cs
@@ -119,9 +119,7 @@ public sealed class ApplicationTrafficTransportTests
finally
{
await timeout.CancelAsync();
- try
- { await run; }
- catch(Exception exception) when(exception is OperationCanceledException or WebSocketException) { }
+ await run;
}
}
diff --git a/tests/Qqq.PrintAgent.Core.Tests/RealtimeChannelEndingTests.cs b/tests/Qqq.PrintAgent.Core.Tests/RealtimeChannelEndingTests.cs
index 6006594..ba6f532 100644
--- a/tests/Qqq.PrintAgent.Core.Tests/RealtimeChannelEndingTests.cs
+++ b/tests/Qqq.PrintAgent.Core.Tests/RealtimeChannelEndingTests.cs
@@ -181,6 +181,144 @@ public sealed class RealtimeChannelEndingTests
+ ///
+ /// The caller's cancellation can overtake the reader: the reader has checked the token and is about to ask the socket
+ /// for a frame when the caller cancels and the shutdown aborts the socket, so the reader fails on the aborted socket
+ /// instead of seeing the cancellation. Nothing failed, so the run still returns. The hook holds the reader at exactly
+ /// that point until the socket has been aborted.
+ ///
+ [Fact]
+ public async Task CallerCancellationThatOvertakesTheReaderStillEndsTheRunNormally()
+ {
+ using var stop = new CancellationTokenSource();
+ using var socket = new ScriptedWebSocket();
+ int receives = 0;
+ socket.Receiving = () =>
+ {
+ if(Interlocked.Increment(ref receives) == 2)
+ {
+ stop.Cancel();
+ Assert.True(SpinWait.SpinUntil(() => socket.Aborts > 0, Patience));
+ }
+ };
+ using var channel = new PrintingRealtimeChannel(socket, new RealtimeSettings());
+ Task run = channel.RunAsync(_ => { }, stop.Token);
+ socket.Deliver("PONG", "pong-1", new { serverTime = "2026-01-01T00:00:00Z" });
+ await run.WaitAsync(Patience);
+ Assert.True(run.IsCompletedSuccessfully);
+ Assert.Equal(2, Volatile.Read(ref receives));
+ Assert.Equal(1, socket.Aborts);
+ }
+
+
+
+ ///
+ /// What a loop meets after the shutdown has aborted the socket decides whether the run fails. The writer is held in
+ /// its send until the caller has cancelled and the socket has been aborted, and then fails. A socket that refuses the
+ /// call because it has ended (disposed, or in an invalid state) is the stop itself, so the run returns. Anything
+ /// else is a failure and is reported although it arrived after the cancellation: an input or output error, and a
+ /// connection the server dropped, which the socket reports as closed prematurely.
+ ///
+ [Theory]
+ [InlineData("disposed", false)]
+ [InlineData("invalid-state", false)]
+ [InlineData("closed-prematurely", true)]
+ [InlineData("io", true)]
+ public async Task FailureMetAfterTheSocketWasAbortedIsReportedUnlessItIsTheSocketRefusingTheCall(string kind, bool reported)
+ {
+ Exception met = kind switch
+ {
+ "disposed" => new ObjectDisposedException("socket"),
+ "invalid-state" => new WebSocketException(WebSocketError.InvalidState),
+ "closed-prematurely" => new WebSocketException(WebSocketError.ConnectionClosedPrematurely),
+ _ => new IOException("Synthetic send failure."),
+ };
+ using var stop = new CancellationTokenSource();
+ using var socket = new ScriptedWebSocket();
+ socket.Sending = _ =>
+ {
+ stop.Cancel();
+ Assert.True(SpinWait.SpinUntil(() => socket.Aborts > 0, Patience));
+ throw met;
+ };
+ using var channel = new PrintingRealtimeChannel(socket, new RealtimeSettings());
+ Task run = channel.RunAsync(_ => { }, stop.Token);
+ await channel.SendAsync("HEARTBEAT", new { });
+ if(reported)
+ {
+ Assert.Same(met, await Assert.ThrowsAnyAsync(() => run.WaitAsync(Patience)));
+ }
+ else
+ {
+ await run.WaitAsync(Patience);
+ Assert.True(run.IsCompletedSuccessfully);
+ }
+ }
+
+
+
+ ///
+ /// The platform socket aborts itself as soon as the token of a call in flight is cancelled, before this channel's own
+ /// shutdown begins, and from then on refuses a new call as being in an invalid state. A writer that is about to send
+ /// at that moment therefore fails before the shutdown has looked at the loops. The reader is held in its callback
+ /// until the shutdown aborts the socket, which it does only after a loop has ended, so the writer is the loop that
+ /// ended first and had already failed when the shutdown looked. The caller had cancelled, so the refusal is still
+ /// the stop and the run returns.
+ ///
+ [Fact]
+ public async Task SocketRefusingACallBecauseTheCallerCancelledIsTheStopEvenBeforeTheShutdownBegins()
+ {
+ using var stop = new CancellationTokenSource();
+ using var socket = new ScriptedWebSocket();
+ socket.Sending = _ =>
+ {
+ stop.Cancel();
+ throw new WebSocketException(WebSocketError.InvalidState);
+ };
+ using var channel = new PrintingRealtimeChannel(socket, new RealtimeSettings());
+ Task run = channel.RunAsync(_ => Assert.True(SpinWait.SpinUntil(() => socket.Aborts > 0, Patience)), stop.Token);
+ socket.Deliver("PONG", "pong-1", new { serverTime = "2026-01-01T00:00:00Z" });
+ await channel.SendAsync("HEARTBEAT", new { });
+ await run.WaitAsync(Patience);
+ Assert.True(run.IsCompletedSuccessfully);
+ }
+
+
+
+ ///
+ /// Without a cancellation by the caller, a loop is taken to have been stopped by the shutdown only when it had not
+ /// failed before the shutdown began. Nobody cancels here: the callback gives up, as the service's does when a newer
+ /// connection has replaced this one, while the writer is inside a send. The shutdown then aborts the socket, and the
+ /// writer's send fails on it. That refusal came after the shutdown began, so it is the shutdown itself, and the run
+ /// ends as the cancellation the callback raised and not as the socket's refusal.
+ ///
+ [Fact]
+ public async Task RefusalMetAfterTheShutdownBeganIsNotReportedAlthoughNobodyCancelled()
+ {
+ using var never = new CancellationTokenSource();
+ using var socket = new ScriptedWebSocket();
+ using var sending = new ManualResetEventSlim();
+ socket.Sending = _ =>
+ {
+ sending.Set();
+ Assert.True(SpinWait.SpinUntil(() => socket.Aborts > 0, Patience));
+ return Task.CompletedTask;
+ };
+ using var channel = new PrintingRealtimeChannel(socket, new RealtimeSettings());
+ Task run = channel.RunAsync(_ =>
+ {
+ Assert.True(sending.Wait(Patience));
+ throw new OperationCanceledException("Replaced by a newer connection.");
+ }, never.Token);
+ await channel.SendAsync("HEARTBEAT", new { });
+ socket.Deliver("JOB_AVAILABLE", "wake-1", new { });
+ await Assert.ThrowsAnyAsync(() => run.WaitAsync(Patience));
+ Assert.True(run.IsCanceled);
+ Assert.False(never.IsCancellationRequested);
+ }
+
+
+
/// A failure is not hidden by a cancellation that arrives with it: when the socket refuses a frame just as the caller cancels, the run still ends with the failure.
[Fact]
public async Task FailureIsReportedEvenWhenTheCallerCancelsAtTheSameMoment()
diff --git a/tests/Qqq.PrintAgent.Core.Tests/ScriptedWebSocket.cs b/tests/Qqq.PrintAgent.Core.Tests/ScriptedWebSocket.cs
index a1c52ed..95c4b6e 100644
--- a/tests/Qqq.PrintAgent.Core.Tests/ScriptedWebSocket.cs
+++ b/tests/Qqq.PrintAgent.Core.Tests/ScriptedWebSocket.cs
@@ -29,6 +29,11 @@ internal sealed class ScriptedWebSocket : WebSocket
+ /// Called each time the channel asks for a frame, before the socket looks at its own state; a test uses it to act at the moment the reader is about to receive.
+ internal Action? Receiving { get; set; }
+
+
+
/// Called for every frame the channel sends, before it is recorded; a test uses it to stall or fail the send.
internal Func? Sending { get; set; }
@@ -166,6 +171,7 @@ internal sealed class ScriptedWebSocket : WebSocket
///
public override async Task ReceiveAsync(ArraySegment buffer, CancellationToken cancellationToken)
{
+ Receiving?.Invoke();
ThrowIfEnded();
if(!await _incoming.Reader.WaitToReadAsync(cancellationToken))
{ throw new WebSocketException(WebSocketError.ConnectionClosedPrematurely); }