From 6ac485f850bd80da9b4f2bbac2748992be795691 Mon Sep 17 00:00:00 2001 From: James Maes Date: Tue, 10 Nov 2026 17:29:02 -0600 Subject: [PATCH 1/8] fix(core): check the printer again when its turn comes; leave a job in hand alone Two cases reached Windows-facing code that should have been settled before it. A printer was checked once, after the download, and then the job waited for the printer's turn. A printer unshared during that wait was refused only by the exposure filter, after SUBMITTING was recorded, and the job became OUTCOME_UNKNOWN although Windows was never asked. The worker now checks the printer again once the turn is held and before SUBMITTING: a printer no longer shared, a queue that is gone or a changed media default is FAILED. The filter keeps its own check for the instant in between, and its refusal is now PrinterNotExposedException, which only the filter can create and creates before it calls the backend behind it. The worker records that refusal as FAILED too, as it does the native layer's media mismatch, and its reason says no bytes were submitted. A replay of a job another lane holds was stopped only by the runtime's ticket registry refusing a duplicate key. PrintWorkerOptions gains a required IsInHand hook; a claimed job that is in hand is logged once, records nothing and ends the pass. The runtime answers from its tickets. The timing line's revalidate figure now covers both printer checks. Signed-off-by: James Maes Co-Authored-By: Claude Fable 5.2 --- .../Printing/ExposedPrinterBackend.cs | 9 +- .../Printing/PrintWorker.cs | 81 +++++--- .../Printing/PrintWorkerOptions.cs | 5 + .../Printing/PrinterNotExposedException.cs | 21 ++ .../AgentRuntime.Pipeline.cs | 5 + .../AgentStoreScaleTests.cs | 1 + .../PrinterExposureTests.cs | 2 +- .../InjectedClockTests.cs | 5 +- .../PrintWorkerOutcomeTests.cs | 179 ++++++++++++++++++ .../PrintingSupportTests.cs | 6 +- .../WorkerHarness.cs | 1 + 11 files changed, 281 insertions(+), 34 deletions(-) create mode 100644 src/Qqq.PrintAgent.Core/Printing/PrinterNotExposedException.cs diff --git a/src/Qqq.PrintAgent.Core/Printing/ExposedPrinterBackend.cs b/src/Qqq.PrintAgent.Core/Printing/ExposedPrinterBackend.cs index 64c5051..4f6a44c 100644 --- a/src/Qqq.PrintAgent.Core/Printing/ExposedPrinterBackend.cs +++ b/src/Qqq.PrintAgent.Core/Printing/ExposedPrinterBackend.cs @@ -17,12 +17,17 @@ public sealed class ExposedPrinterBackend(IPrinterBackend inner, FuncPrints a staged file only if the job's printer is still shared on this computer, rechecked at submission time because the operator may have unshared it since the job was claimed. + /// + /// Prints a staged file only if the job's printer is still shared on this computer, rechecked at submission time + /// because the operator may have unshared it since the job was claimed. The refusal is made before the backend + /// behind the filter is called and has its own type, , so the caller knows + /// that nothing was submitted. + /// public Task PrintFileAsync(PrintJob job, string path, TimeSpan submissionTimeout, CancellationToken cancellationToken) { if(!exposedIds().Contains(job.PrinterId)) { - throw new InvalidOperationException("The printer is not exposed to QQQ on this computer."); + throw new PrinterNotExposedException("The printer is not exposed to QQQ on this computer; no bytes were submitted."); } return inner.PrintFileAsync(job, path, submissionTimeout, cancellationToken); } diff --git a/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs b/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs index a8d6caf..29a5bc7 100644 --- a/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs +++ b/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs @@ -61,10 +61,10 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ /// /// Claims one job under the shared claim gate and registers it locally before anything else can happen to it. The /// server keeps replaying CLAIMED until RECEIVED commits, so admission is serialized through that acknowledgement; if - /// it is interrupted the job is recorded FAILED with no bytes submitted. A job the journal already holds in a final - /// state, or as submitting, is dropped here so a replayed claim can never print twice; the pass then ends, because - /// the server would only offer that job again. A claimed job that breaks the contract but names itself is refused - /// and reported instead of returned. + /// it is interrupted the job is recorded FAILED with no bytes submitted. A job this computer is already working on, + /// or that the journal holds in a final state or as submitting, is dropped here so a replayed claim can never print + /// twice; the pass then ends, because the server would only offer that job again. A claimed job that breaks the + /// contract but names itself is refused and reported instead of returned. /// private async Task ClaimAndRegisterAsync(IReadOnlyList inventory, CancellationToken token) { @@ -78,22 +78,8 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ { job = await api.ClaimAsync(token).ConfigureAwait(false); } catch(PrintingProtocolException violation) when(violation.RejectedJob is not null) { return new Claim(null, await RefuseAsync(violation.RejectedJob, violation.Message, inventory, token).ConfigureAwait(false)); } - if(job is null) + if(job is null || IsReplay(job, inventory)) { return default; } - Track(job, inventory); - if(journal.GetState(job.JobId) is { } state && (PrintJobState.IsFinal(state) || string.Equals(state, PrintJobState.Submitting, StringComparison.Ordinal))) - { - //////////////////////////////////////////////////////////////////////// - // a job recorded as submitting was handed to a printer once already // - // and has not concluded: another lane is submitting it now, or a run // - // stopped part-way and the runtime's recovery reports it as unknown. // - // claiming it again must never print it a second time, and it must // - // not pass silently, because the server should not be offering it // - //////////////////////////////////////////////////////////////////////// - if(!PrintJobState.IsFinal(state)) - { log($"{job.JobId}: offered again while recorded as {state}, so its submission has started and not concluded; it is not submitted a second time and this pass claims nothing more."); } - return default; - } options.ActiveJobChanged(job); try { @@ -114,6 +100,38 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ + /// + /// Says whether a claimed job is one this computer must not start on, because it already has, and says so in the + /// log when the server should not have offered it. A job that is in hand, held by a lane of this computer right + /// now, is left entirely to that lane: nothing is recorded for it here, not even its display facts. A job the + /// journal holds as submitting was handed to a printer once already and has not concluded, and one it holds in a + /// final state has; neither is ever submitted a second time. + /// + private bool IsReplay(PrintJob job, IReadOnlyList inventory) + { + if(options.IsInHand(job.JobId)) + { + log($"{job.JobId}: offered again while this computer is already working on it; it is left to the lane that holds it, nothing is recorded for it and this pass claims nothing more."); + return true; + } + Track(job, inventory); + if(journal.GetState(job.JobId) is not { } state || !(PrintJobState.IsFinal(state) || string.Equals(state, PrintJobState.Submitting, StringComparison.Ordinal))) + { return false; } + + //////////////////////////////////////////////////////////////////////// + // a job recorded as submitting was handed to a printer once already // + // and has not concluded: another lane is submitting it now, or a run // + // stopped part-way and the runtime's recovery reports it as unknown. // + // claiming it again must never print it a second time, and it must // + // not pass silently, because the server should not be offering it // + //////////////////////////////////////////////////////////////////////// + if(!PrintJobState.IsFinal(state)) + { log($"{job.JobId}: offered again while recorded as {state}, so its submission has started and not concluded; it is not submitted a second time and this pass claims nothing more."); } + return true; + } + + + /// /// Reports a claimed job the API client refused because it broke the contract. The server offers a claimed job again /// until the agent answers for it, so leaving it unanswered would block every job behind it; the job is therefore @@ -158,7 +176,10 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ /// disposal scope stays inside this method's try block, which keeps every failure, including one raised while /// releasing a reservation, inside the same decision: FAILED when Windows was never asked, OUTCOME_UNKNOWN when /// submission had begun, and nothing at all when the job is already recorded as SPOOLED, because a release that - /// fails after Windows accepted the document says nothing about the print and must not be written over it. One + /// fails after Windows accepted the document says nothing about the print and must not be written over it. Two + /// refusals that arrive after submission began are still FAILED, because each is known to have been made before + /// any bytes were sent: the native layer's media mismatch, and the exposure filter's refusal of a printer that is + /// no longer shared, which only the filter can raise and raises before it calls the backend behind it. One /// timing line per job is logged afterwards so a slow print can be attributed to a phase from the service's own log /// without any extra request, payload or printer access. Returns true when the job was processed, whatever its /// outcome; false only when something else had already recorded a final state for it, so nothing was done. @@ -179,7 +200,7 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ if(attempt.Spooled) { log($"{job.JobId}: spooled, and stays recorded as spooled; releasing what the job held failed afterwards: {exception.Message}"); } else - { Record(job, attempt.Submitting && exception is not PrinterMediaMismatchException ? PrintJobState.OutcomeUnknown : PrintJobState.Failed, exception.Message); } + { Record(job, attempt.Submitting && exception is not (PrinterMediaMismatchException or PrinterNotExposedException) ? PrintJobState.OutcomeUnknown : PrintJobState.Failed, exception.Message); } } log(attempt.TimingMessage(job.JobId)); if(!token.IsCancellationRequested) @@ -195,7 +216,10 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ /// caller can tell a refusal before any bytes from an uncertain submission. Between recording SUBMITTING and calling /// Windows nothing has been sent, so the two things that can stop the job there (delivery of the receipt not being /// confirmed, and cancellation) say in their own words that no bytes were submitted. Handing the verified staged - /// file to the backend is the only step after which an outcome is uncertain. + /// file to the backend is the only step after which an outcome is uncertain. The printer is checked twice before + /// that: after the download, and again once the printer's turn is held, because jobs can wait a long time behind a + /// print and the operator may stop sharing the printer, or its media may change, while they wait. The timing line + /// reports both checks together as the revalidation, and the wait for the turn with the receipt as the gate. /// private async Task SubmitJobAsync(PrintJob job, JobAttempt attempt, CancellationToken token) { @@ -211,6 +235,9 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ await using IAsyncDisposable submission = await options.AcquireSubmissionAsync(job, token).ConfigureAwait(false); RequireSubmitAllowed("Dispatch is paused before native submission."); + attempt.Gate = attempt.Lap(); + RequireCurrentPrinter(job); + attempt.Revalidate += attempt.Lap(); Record(job, PrintJobState.Submitting); try { await FlushAsync(token).ConfigureAwait(false); } @@ -227,7 +254,7 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ /////////////////////////////////////////////////////////////////////////// throw new IOException("Delivery of the submitting receipt could not be confirmed, so the document was not sent to the printer; no bytes were submitted.", exception); } - attempt.Gate = attempt.Lap(); + attempt.Gate += attempt.Lap(); RequireSubmitAllowed("Dispatch stopped before native submission; no bytes were submitted."); RealtimeSettings submissionSettings = EffectiveSettings; if(job.Options.Copies > submissionSettings.MaxCopies || job.ContentLength > submissionSettings.MaximumDocumentBytes(job.Format)) @@ -245,9 +272,11 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ /// - /// Discovers the printers again after the download and requires the assigned queue to still offer the job's format and - /// the selected media profile, so a queue or driver default that changed while the document streamed is refused before - /// any submission instead of printing on the wrong stock. + /// Discovers the printers again and requires the assigned queue to still be shared, to still offer the job's format + /// and to still have the selected media profile. It runs after the download and again when the printer's turn is + /// held, so a printer withdrawn, or a queue or driver default changed, while the document streamed or while the job + /// waited is refused before SUBMITTING is recorded, with Windows never asked, instead of printing on the wrong + /// stock or being refused when the outcome can no longer be called certain. /// private void RequireCurrentPrinter(PrintJob job) { diff --git a/src/Qqq.PrintAgent.Core/Printing/PrintWorkerOptions.cs b/src/Qqq.PrintAgent.Core/Printing/PrintWorkerOptions.cs index 32bb50d..3ab76ab 100644 --- a/src/Qqq.PrintAgent.Core/Printing/PrintWorkerOptions.cs +++ b/src/Qqq.PrintAgent.Core/Printing/PrintWorkerOptions.cs @@ -48,6 +48,11 @@ public sealed record PrintWorkerOptions + /// Says whether this computer is already working on the job with the given identifier, in any lane. A claim of such a job is a replay, and the worker leaves the job to the lane that holds it. + public required Func IsInHand { get; init; } + + + /// Says whether this lane may still claim; false once another lane found the queue empty. public required Func CanClaim { get; init; } diff --git a/src/Qqq.PrintAgent.Core/Printing/PrinterNotExposedException.cs b/src/Qqq.PrintAgent.Core/Printing/PrinterNotExposedException.cs new file mode 100644 index 0000000..75c5ff0 --- /dev/null +++ b/src/Qqq.PrintAgent.Core/Printing/PrinterNotExposedException.cs @@ -0,0 +1,21 @@ +/* + * Copyright (c) 2026 James Maes + * SPDX-License-Identifier: MIT + */ + +namespace Qqq.PrintAgent.Core.Printing; + +/// +/// The exposure filter's refusal: the job's printer is not shared with QQQ on this computer. Only +/// can create it, because the constructor is internal, and the filter creates it +/// only before it calls the backend behind it. Whoever catches it therefore knows that nothing was handed to a +/// printing platform and no document bytes were submitted, which is why the worker records such a job as FAILED and +/// not as an uncertain outcome. +/// +public sealed class PrinterNotExposedException : InvalidOperationException +{ + /// Creates the refusal. Internal so that no backend outside this assembly can raise it after it has started to print. + internal PrinterNotExposedException(string message) : base(message) + { + } +} diff --git a/src/Qqq.PrintAgent.Windows/AgentRuntime.Pipeline.cs b/src/Qqq.PrintAgent.Windows/AgentRuntime.Pipeline.cs index 0e225a4..5b2a371 100644 --- a/src/Qqq.PrintAgent.Windows/AgentRuntime.Pipeline.cs +++ b/src/Qqq.PrintAgent.Windows/AgentRuntime.Pipeline.cs @@ -158,6 +158,11 @@ public sealed partial class AgentRuntime EventGate = _eventDeliveryGate, ClaimGate = _claimGate, ThrottleDownloadAsync = ThrottleDownloadAsync, + IsInHand = jobId => + { + lock(_stateLock) + { return _jobTickets.ContainsKey(jobId); } + }, CanClaim = () => !wave.Drained, ReserveDocumentAsync = ReserveDocumentAsync, AcquireSubmissionAsync = AcquireSubmissionAsync, diff --git a/tests/Qqq.PrintAgent.Cli.Tests/AgentStoreScaleTests.cs b/tests/Qqq.PrintAgent.Cli.Tests/AgentStoreScaleTests.cs index 13d499d..090669a 100644 --- a/tests/Qqq.PrintAgent.Cli.Tests/AgentStoreScaleTests.cs +++ b/tests/Qqq.PrintAgent.Cli.Tests/AgentStoreScaleTests.cs @@ -125,6 +125,7 @@ public sealed class AgentStoreScaleTests(ITestOutputHelper output) EventGate = eventGate, ClaimGate = claimGate, ThrottleDownloadAsync = (_, _) => Task.CompletedTask, + IsInHand = _ => false, CanClaim = () => true, ReserveDocumentAsync = (_, _) => throw new InvalidOperationException("Scale tests must not print."), AcquireSubmissionAsync = (_, _) => throw new InvalidOperationException("Scale tests must not print."), diff --git a/tests/Qqq.PrintAgent.Cli.Tests/PrinterExposureTests.cs b/tests/Qqq.PrintAgent.Cli.Tests/PrinterExposureTests.cs index 1b2c201..2b52195 100644 --- a/tests/Qqq.PrintAgent.Cli.Tests/PrinterExposureTests.cs +++ b/tests/Qqq.PrintAgent.Cli.Tests/PrinterExposureTests.cs @@ -52,7 +52,7 @@ public sealed class PrinterExposureTests selected.Clear(); Assert.Empty(backend.Discover()); PrintJob job = new("j1", "p1", "Test", "PDF", "", 1, new PrintOptions(), "", "CLAIMED"); - await Assert.ThrowsAsync(() => backend.PrintFileAsync(job, Path.Combine(Path.GetTempPath(), "unused-exposure.document"), TimeSpan.FromSeconds(1), CancellationToken.None)); + await Assert.ThrowsAsync(() => backend.PrintFileAsync(job, Path.Combine(Path.GetTempPath(), "unused-exposure.document"), TimeSpan.FromSeconds(1), CancellationToken.None)); Assert.False(printer.Printed); } diff --git a/tests/Qqq.PrintAgent.Core.Tests/InjectedClockTests.cs b/tests/Qqq.PrintAgent.Core.Tests/InjectedClockTests.cs index 0b7bcf0..4d4401c 100644 --- a/tests/Qqq.PrintAgent.Core.Tests/InjectedClockTests.cs +++ b/tests/Qqq.PrintAgent.Core.Tests/InjectedClockTests.cs @@ -178,7 +178,8 @@ public sealed class InjectedClockTests /// /// The per-job timing line reports each phase as measured on the worker's clock: inventory, the claim with its receipt, - /// the download, the printer recheck, the submission gate with its receipt, and the native submission. + /// the download, the two printer rechecks (after the download and when the printer's turn is held) as one figure, + /// the submission gate with its receipt, and the native submission. /// [Fact] public async Task WorkerTimingLineReportsEachPhaseFromItsClock() @@ -202,7 +203,7 @@ public sealed class InjectedClockTests }; harness.Server.Offer(FakePrintServer.Job(document), document); Assert.True(await harness.RunOnceAsync()); - Assert.Contains("job-1: timing inventory=5ms claim=9ms download=11ms revalidate=5ms gate=2ms submit=13ms", harness.Log, StringComparer.Ordinal); + Assert.Contains("job-1: timing inventory=5ms claim=9ms download=11ms revalidate=10ms gate=2ms submit=13ms", harness.Log, StringComparer.Ordinal); } diff --git a/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs b/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs index 88c9736..0eeadda 100644 --- a/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs +++ b/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs @@ -112,6 +112,185 @@ public sealed class PrintWorkerOutcomeTests + /// + /// A replay of a job this computer is already working on in another lane is left entirely to the lane that holds + /// it, whatever that lane has recorded so far. Nothing is recorded or reported for it, its title and printer are not + /// rewritten, the runtime is not told a job became active, and it is neither downloaded nor printed. The log says so + /// once, in plain words, and the pass ends, because the server would only offer the same job again. + /// + [Theory] + [InlineData("RECEIVED")] + [InlineData("SUBMITTING")] + public async Task ClaimOfAJobInHandEndsThePassRecordsNothingAndLogsOneLine(string heldAt) + { + await using var harness = new WorkerHarness(); + (FakePrintServer server, RecordingJournal journal, FakePrinterBackend printer) = (harness.Server, harness.Journal, harness.Printer); + server.Offer(FakePrintServer.Job(Document) with { Title = "Replayed title" }, Document); + journal.TrackJob(FakePrintServer.Job(Document) with { Title = "Original title" }, "Original printer"); + journal.Record("job-1", new PrintEvent("received-by-the-other-lane", "RECEIVED")); + journal.Acknowledge("received-by-the-other-lane"); + if(string.Equals(heldAt, "SUBMITTING", StringComparison.Ordinal)) + { + journal.Record("job-1", new PrintEvent("submitting-by-the-other-lane", "SUBMITTING")); + journal.Acknowledge("submitting-by-the-other-lane"); + } + string[] recordedByTheOtherLane = journal.StatesOf("job-1"); + var asked = new List(); + var active = new List(); + harness.Options = harness.Options with + { + IsInHand = jobId => + { + asked.Add(jobId); + return true; + }, + ActiveJobChanged = job => active.Add(job?.JobId), + }; + + Assert.False(await harness.RunOnceAsync()); + Assert.Equal(new[] { "job-1" }, asked, StringComparer.Ordinal); + Assert.Equal(1, server.Claims); + Assert.Equal(recordedByTheOtherLane, journal.StatesOf("job-1"), StringComparer.Ordinal); + Assert.Empty(journal.Pending()); + Assert.Empty(server.Events); + Assert.Empty(active); + Assert.Equal("Original title", journal.Jobs["job-1"].Job.Title); + Assert.Equal("Original printer", journal.Jobs["job-1"].PrinterName); + Assert.Equal(0, server.Downloads); + Assert.Equal(0, printer.Submissions); + Assert.Equal("job-1: offered again while this computer is already working on it; it is left to the lane that holds it, nothing is recorded for it and this pass claims nothing more.", Assert.Single(harness.Log)); + } + + + + /// + /// Jobs can wait a long time for a printer's turn. What happened to the printer during the wait is found when the + /// turn is held, before SUBMITTING is recorded: a printer the operator stopped sharing, a queue that is gone, or a + /// selected media default that changed is FAILED with its reason and Windows is never asked. The receipts are + /// RECEIVED then FAILED, the backend is never called, the turn is released, nothing stays in the staging folder, + /// and the job is neither downloaded nor printed when the server offers it again. Without this check the first of + /// these was refused only by the exposure filter, after SUBMITTING, and recorded as an unknown outcome. + /// + [Theory] + [InlineData("unshared", "Assigned printer or document format is unavailable.")] + [InlineData("queue-gone", "Assigned printer or document format is unavailable.")] + [InlineData("media-changed", "The selected printer media profile changed or is unavailable. Refresh the printer and select its current default.")] + public async Task PrinterWithdrawnWhileWaitingForItsTurnIsFailedAndTheBackendIsNeverCalled(string change, string reason) + { + PrinterMediaProfile profile = new("default-id", new string('a', 64), "Default", 101600, 152400, 300, 300); + PrintJob job = FakePrintServer.Job(Document, options: new PrintOptions(MediaProfile: new(profile.Id, profile.Revision))); + await using var harness = new WorkerHarness(); + (FakePrintServer server, RecordingJournal journal, FakePrinterBackend printer) = (harness.Server, harness.Journal, harness.Printer); + printer.Printers[0] = printer.Printers[0] with { MediaProfiles = [profile] }; + server.Offer(job, Document).Offer(job, Document); + var steps = new List(); + harness.Options = harness.Options with + { + AcquireSubmissionAsync = (_, _) => + { + ////////////////////////////////////////////////////////////////////// + // the wait for the turn ends here; the change happened while the // + // job waited, after the check that follows the download had passed // + ////////////////////////////////////////////////////////////////////// + switch(change) + { + case "unshared": + harness.Exposed.Clear(); + break; + case "queue-gone": + printer.Printers.Clear(); + break; + default: + printer.Printers[0] = printer.Printers[0] with { MediaProfiles = [profile with { Revision = new string('b', 64) }] }; + break; + } + return Lease.TakeAsync(steps, "printer turn"); + }, + }; + + Assert.True(await harness.RunOnceAsync()); + Assert.Equal(new[] { "RECEIVED", "FAILED" }, journal.StatesOf("job-1"), StringComparer.Ordinal); + Assert.Equal(reason, journal.Last("job-1").Message); + Assert.Equal(new[] { "RECEIVED", "FAILED" }, server.States, StringComparer.Ordinal); + Assert.Equal(0, printer.Submissions); + Assert.Equal(new[] { "take printer turn", "release printer turn" }, steps, StringComparer.Ordinal); + Assert.Empty(Directory.EnumerateFileSystemEntries(harness.Staging.Path)); + + Assert.False(await harness.RunOnceAsync()); + Assert.Equal(2, server.Claims); + Assert.Equal(1, server.Downloads); + Assert.Equal(0, printer.Submissions); + Assert.Equal("FAILED", journal.GetState("job-1")); + } + + + + /// A printer withdrawn earlier, before the document is downloaded, is still caught by the check that follows the download: the job is FAILED with nothing submitted and never asks for the printer's turn. + [Fact] + public async Task PrinterWithdrawnBeforeTheDownloadIsStillFailedAndNeverTakesTheTurn() + { + await using var harness = new WorkerHarness(); + (FakePrintServer server, RecordingJournal journal, FakePrinterBackend printer) = (harness.Server, harness.Journal, harness.Printer); + server.Offer(FakePrintServer.Job(Document), Document); + var steps = new List(); + harness.Options = harness.Options with + { + ReserveDocumentAsync = (_, _) => + { + harness.Exposed.Clear(); + return Lease.TakeAsync(steps, "reservation"); + }, + AcquireSubmissionAsync = (_, _) => Lease.TakeAsync(steps, "printer turn"), + }; + + Assert.True(await harness.RunOnceAsync()); + Assert.Equal(new[] { "RECEIVED", "FAILED" }, journal.StatesOf("job-1"), StringComparer.Ordinal); + Assert.Equal("Assigned printer or document format is unavailable.", journal.Last("job-1").Message); + Assert.Equal(new[] { "RECEIVED", "FAILED" }, server.States, StringComparer.Ordinal); + Assert.Equal(1, server.Downloads); + Assert.Equal(0, printer.Submissions); + Assert.Equal(new[] { "take reservation", "release reservation" }, steps, StringComparer.Ordinal); + Assert.Empty(Directory.EnumerateFileSystemEntries(harness.Staging.Path)); + } + + + + /// + /// The exposure filter stays the last line of defense, because sharing can still change in the instant between the + /// worker's check and the call. A printer withdrawn after SUBMITTING was recorded is refused by the filter before + /// the backend behind it is called, with a refusal only the filter can raise. The worker therefore knows nothing + /// was sent: the job is FAILED, not unknown, its reason says that no bytes were submitted, the backend was never + /// called, and the job is not printed when the server offers it again. + /// + [Fact] + public async Task PrinterWithdrawnAfterTheSubmittingReceiptIsRefusedByTheFilterAndFailedWithNothingSent() + { + PrintJob job = FakePrintServer.Job(Document); + await using var harness = new WorkerHarness(); + (FakePrintServer server, RecordingJournal journal, FakePrinterBackend printer) = (harness.Server, harness.Journal, harness.Printer); + server.Offer(job, Document).Offer(job, Document); + journal.Recorded = (_, printEvent) => + { + if(string.Equals(printEvent.Status, "SUBMITTING", StringComparison.Ordinal)) + { harness.Exposed.Clear(); } + }; + + Assert.True(await harness.RunOnceAsync()); + Assert.Equal(new[] { "RECEIVED", "SUBMITTING", "FAILED" }, journal.StatesOf("job-1"), StringComparer.Ordinal); + Assert.Equal("The printer is not exposed to QQQ on this computer; no bytes were submitted.", journal.Last("job-1").Message); + Assert.Null(journal.Last("job-1").SpoolerJobId); + Assert.Equal(new[] { "RECEIVED", "SUBMITTING", "FAILED" }, server.States, StringComparer.Ordinal); + Assert.Equal(0, printer.Submissions); + Assert.Empty(Directory.EnumerateFileSystemEntries(harness.Staging.Path)); + + Assert.False(await harness.RunOnceAsync()); + Assert.Equal(1, server.Downloads); + Assert.Equal(0, printer.Submissions); + Assert.Equal("FAILED", journal.GetState("job-1")); + } + + + /// /// Every refusal the worker makes before native submission is a plain FAILED with its reason, never the uncertain /// state, and the printer is never called: copies over the policy (before any download), a policy tightened while the diff --git a/tests/Qqq.PrintAgent.Core.Tests/PrintingSupportTests.cs b/tests/Qqq.PrintAgent.Core.Tests/PrintingSupportTests.cs index 7fd7d1f..cdd4a20 100644 --- a/tests/Qqq.PrintAgent.Core.Tests/PrintingSupportTests.cs +++ b/tests/Qqq.PrintAgent.Core.Tests/PrintingSupportTests.cs @@ -41,7 +41,7 @@ public sealed class PrintingSupportTests - /// A job is submitted only while its printer is still shared: the check is made again at submission, the staged file and its submission limit reach the inner backend unchanged, and a refusal never reaches it. + /// A job is submitted only while its printer is still shared: the check is made again at submission, the staged file and its submission limit reach the inner backend unchanged, and a refusal never reaches it. The refusal has its own type and says that nothing was submitted, because it is made before the inner backend is called. [Fact] public async Task ExposureFilterRechecksSharingAtSubmission() { @@ -57,8 +57,8 @@ public sealed class PrintingSupportTests Assert.Equal(TimeSpan.FromSeconds(30), limit); shared.Clear(); - InvalidOperationException refused = await Assert.ThrowsAsync(() => backend.PrintFileAsync(Job, temp.File("staged.document"), TimeSpan.FromSeconds(30), CancellationToken.None)); - Assert.Equal("The printer is not exposed to QQQ on this computer.", refused.Message); + PrinterNotExposedException refused = await Assert.ThrowsAsync(() => backend.PrintFileAsync(Job, temp.File("staged.document"), TimeSpan.FromSeconds(30), CancellationToken.None)); + Assert.Equal("The printer is not exposed to QQQ on this computer; no bytes were submitted.", refused.Message); Assert.Equal(1, inner.Submissions); } diff --git a/tests/Qqq.PrintAgent.Core.Tests/WorkerHarness.cs b/tests/Qqq.PrintAgent.Core.Tests/WorkerHarness.cs index 18587fd..bdba06e 100644 --- a/tests/Qqq.PrintAgent.Core.Tests/WorkerHarness.cs +++ b/tests/Qqq.PrintAgent.Core.Tests/WorkerHarness.cs @@ -47,6 +47,7 @@ internal sealed class WorkerHarness : IAsyncDisposable EventGate = EventGate, ClaimGate = ClaimGate, ThrottleDownloadAsync = Unpaced, + IsInHand = _ => false, CanClaim = () => true, ReserveDocumentAsync = (_, _) => Task.FromResult(new FreeLease()), AcquireSubmissionAsync = (_, _) => Task.FromResult(new FreeLease()), -- 2.54.0 From d9fb2e0bc229fdfef44c617cdb9d7d7b336a8578 Mon Sep 17 00:00:00 2001 From: James Maes Date: Tue, 10 Nov 2026 17:29:03 -0600 Subject: [PATCH 2/8] docs: describe the second printer check, the filter's refusal and a job in hand REALTIME gains three entries under the claimed jobs the worker does not print, and the changelog says what an operator sees. Signed-off-by: James Maes Co-Authored-By: Claude Fable 5.2 --- CHANGELOG.md | 13 +++++++++++++ docs/REALTIME.md | 20 ++++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f2fd92..2e99cc5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,19 @@ ## Unreleased +Two cases the print worker now settles before Windows is asked (2.0). + +- A printer that stops being shared while jobs wait behind a print no longer leaves those jobs with an unknown + outcome. The worker checks the printer again when the job's turn comes, before SUBMITTING is recorded: a printer + that is no longer shared, a queue that is gone, or a selected media default that changed during the wait is + FAILED with its reason, and nothing is sent to Windows. If sharing changes in the instant after that check, the + job is still FAILED, with a reason ending "no bytes were submitted", because the refusal is known to come before + anything is sent. Each job costs one more printer discovery, and the log's timing line counts both checks under + `revalidate`. +- A job the server offers again while this computer is still working on it is left to the lane that holds it. The + log says so in plain words, nothing is recorded for the replay, and the lane ends its pass. Before, the replay was + stopped only by an internal duplicate check that logged "An item with the same key has already been added". + Branded Start menu shortcut (2.0). The installer step that creates, renames and removes the shortcut under **Start → Print Connectors** now records, by name, every shortcut it has put there and may still own, and a file that is not ours no longer fails an install or an uninstall. Nothing changes for an installation whose shortcut diff --git a/docs/REALTIME.md b/docs/REALTIME.md index 19a9674..3c5c896 100644 --- a/docs/REALTIME.md +++ b/docs/REALTIME.md @@ -101,6 +101,26 @@ levels, so that a job nested too deep to read can still be identified. released capacity starts a new wave. The outcome is reported by the lane that is submitting the job or, after a restart, by the runtime's recovery at start as OUTCOME_UNKNOWN. +- **Claimed job that is already in hand.** A job a lane of this computer is + working on right now is left to that lane when the server offers it again. + The worker asks the runtime whether the job is in hand before it does + anything else with the claim: nothing is recorded or reported, the job's + title and printer in history are not rewritten, the log says once that the + job was offered again while this computer is already working on it, and the + lane ends its pass as it does for a job that is submitting. +- **Printer withdrawn while the job waits.** The assigned printer is checked + twice before SUBMITTING is recorded: after the download, and again when the + printer's turn is held, because a job can wait a long time behind a print. + A printer the operator stopped sharing, a queue that is gone, or a selected + media default that changed during either wait is FAILED with its reason, + and Windows is never asked. The timing line reports both checks together as + `revalidate`. +- **Printer withdrawn after SUBMITTING.** Sharing can still change in the + instant between that check and the call, so the exposure filter in front of + the backend checks once more. Its refusal is made before the backend behind + it is called and has a type only the filter can raise, so the worker knows + nothing was sent: the job is FAILED, not OUTCOME_UNKNOWN, and its reason + ends "no bytes were submitted". - **Between SUBMITTING and Windows.** If delivery of the SUBMITTING receipt cannot be confirmed, or the worker is stopped after it was acknowledged and before the native call, Windows is never asked. The job is FAILED and its -- 2.54.0 From bdaeb6b89d58ea4bf5691e09ea1e49b06f681b88 Mon Sep 17 00:00:00 2001 From: James Maes Date: Tue, 10 Nov 2026 18:08:50 -0600 Subject: [PATCH 3/8] fix(core): check the printer once per job; word the in-hand line for a finished job Review of this branch asked for the second printer discovery, made when the printer's turn is held, to be removed. It started the print helper once more for every job while the job held the printer's turn and a print slot, and doubled the exposure to a slow or hung driver on an unrelated queue. The typed refusal of the exposure filter already gives a true FAILED when a printer is unshared while the job waits, and the native layer already fails a media change. The printer is discovered again once, after the download, as before this branch. The timing line's revalidate figure is one check again. What a change during the wait for the turn becomes: - no longer shared: refused by the exposure filter after SUBMITTING, FAILED, nothing sent (RECEIVED, SUBMITTING, FAILED) - selected media default changed: refused by the native layer before it prints, FAILED after SUBMITTING - queue removed from Windows: the native layer fails without a type the worker can rely on, so OUTCOME_UNKNOWN. An error code for a missing queue across the helper boundary would make this FAILED; it is not part of this change. The in-hand log line said the computer "is already working on" the job. A lane lets go of a job only after its final state was recorded and delivered, so the line can describe a job that has just finished. It now says a lane "still holds it, working on it or just finished with it", and the test has a row for a job in hand that is already SPOOLED. Signed-off-by: James Maes Co-Authored-By: Claude Fable 5.2 --- .../Printing/PrintWorker.cs | 29 ++++--- .../Printing/PrintWorkerOptions.cs | 2 +- .../InjectedClockTests.cs | 7 +- .../PrintWorkerOutcomeTests.cs | 80 +++++++++++-------- 4 files changed, 66 insertions(+), 52 deletions(-) diff --git a/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs b/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs index 29a5bc7..1172b3b 100644 --- a/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs +++ b/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs @@ -103,7 +103,9 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ /// /// Says whether a claimed job is one this computer must not start on, because it already has, and says so in the /// log when the server should not have offered it. A job that is in hand, held by a lane of this computer right - /// now, is left entirely to that lane: nothing is recorded for it here, not even its display facts. A job the + /// now, is left entirely to that lane: nothing is recorded for it here, not even its display facts. The lane lets + /// go of a job only after its final state was recorded and delivered, so a job in hand may be one that has just + /// finished, and the log line says "still holds" for that reason and does not claim work is under way. A job the /// journal holds as submitting was handed to a printer once already and has not concluded, and one it holds in a /// final state has; neither is ever submitted a second time. /// @@ -111,7 +113,7 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ { if(options.IsInHand(job.JobId)) { - log($"{job.JobId}: offered again while this computer is already working on it; it is left to the lane that holds it, nothing is recorded for it and this pass claims nothing more."); + log($"{job.JobId}: offered again while a lane of this computer still holds it, working on it or just finished with it; it is left to that lane, nothing is recorded for it and this pass claims nothing more."); return true; } Track(job, inventory); @@ -216,10 +218,11 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ /// caller can tell a refusal before any bytes from an uncertain submission. Between recording SUBMITTING and calling /// Windows nothing has been sent, so the two things that can stop the job there (delivery of the receipt not being /// confirmed, and cancellation) say in their own words that no bytes were submitted. Handing the verified staged - /// file to the backend is the only step after which an outcome is uncertain. The printer is checked twice before - /// that: after the download, and again once the printer's turn is held, because jobs can wait a long time behind a - /// print and the operator may stop sharing the printer, or its media may change, while they wait. The timing line - /// reports both checks together as the revalidation, and the wait for the turn with the receipt as the gate. + /// file to the backend is the only step after which an outcome is uncertain. The printer is discovered again once, + /// after the download, and not a second time when its turn is held: that would start the print helper once more + /// for every job, while the job holds the printer's turn and a print slot. What changes during the wait for the + /// turn is refused later by whoever can tell that nothing was sent: the exposure filter for a printer that is no + /// longer shared, and the native layer for media that changed. /// private async Task SubmitJobAsync(PrintJob job, JobAttempt attempt, CancellationToken token) { @@ -235,9 +238,6 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ await using IAsyncDisposable submission = await options.AcquireSubmissionAsync(job, token).ConfigureAwait(false); RequireSubmitAllowed("Dispatch is paused before native submission."); - attempt.Gate = attempt.Lap(); - RequireCurrentPrinter(job); - attempt.Revalidate += attempt.Lap(); Record(job, PrintJobState.Submitting); try { await FlushAsync(token).ConfigureAwait(false); } @@ -254,7 +254,7 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ /////////////////////////////////////////////////////////////////////////// throw new IOException("Delivery of the submitting receipt could not be confirmed, so the document was not sent to the printer; no bytes were submitted.", exception); } - attempt.Gate += attempt.Lap(); + attempt.Gate = attempt.Lap(); RequireSubmitAllowed("Dispatch stopped before native submission; no bytes were submitted."); RealtimeSettings submissionSettings = EffectiveSettings; if(job.Options.Copies > submissionSettings.MaxCopies || job.ContentLength > submissionSettings.MaximumDocumentBytes(job.Format)) @@ -272,11 +272,10 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ /// - /// Discovers the printers again and requires the assigned queue to still be shared, to still offer the job's format - /// and to still have the selected media profile. It runs after the download and again when the printer's turn is - /// held, so a printer withdrawn, or a queue or driver default changed, while the document streamed or while the job - /// waited is refused before SUBMITTING is recorded, with Windows never asked, instead of printing on the wrong - /// stock or being refused when the outcome can no longer be called certain. + /// Discovers the printers again after the download and requires the assigned queue to still be shared, to still + /// offer the job's format and to still have the selected media profile, so a printer withdrawn, or a queue or driver + /// default changed, while the document streamed is refused before SUBMITTING is recorded, with Windows never asked, + /// instead of printing on the wrong stock. /// private void RequireCurrentPrinter(PrintJob job) { diff --git a/src/Qqq.PrintAgent.Core/Printing/PrintWorkerOptions.cs b/src/Qqq.PrintAgent.Core/Printing/PrintWorkerOptions.cs index 3ab76ab..9199c7a 100644 --- a/src/Qqq.PrintAgent.Core/Printing/PrintWorkerOptions.cs +++ b/src/Qqq.PrintAgent.Core/Printing/PrintWorkerOptions.cs @@ -48,7 +48,7 @@ public sealed record PrintWorkerOptions - /// Says whether this computer is already working on the job with the given identifier, in any lane. A claim of such a job is a replay, and the worker leaves the job to the lane that holds it. + /// Says whether a lane of this computer holds the job with the given identifier: from the moment it was claimed until the lane lets go of it, which is after its final state was recorded and delivered. A claim of such a job is a replay, and the worker leaves the job to the lane that holds it. public required Func IsInHand { get; init; } diff --git a/tests/Qqq.PrintAgent.Core.Tests/InjectedClockTests.cs b/tests/Qqq.PrintAgent.Core.Tests/InjectedClockTests.cs index 4d4401c..7e79b4e 100644 --- a/tests/Qqq.PrintAgent.Core.Tests/InjectedClockTests.cs +++ b/tests/Qqq.PrintAgent.Core.Tests/InjectedClockTests.cs @@ -178,8 +178,8 @@ public sealed class InjectedClockTests /// /// The per-job timing line reports each phase as measured on the worker's clock: inventory, the claim with its receipt, - /// the download, the two printer rechecks (after the download and when the printer's turn is held) as one figure, - /// the submission gate with its receipt, and the native submission. + /// the download, the printer recheck, the submission gate with its receipt, and the native submission. The printer + /// is rechecked once, so the figure is one discovery. /// [Fact] public async Task WorkerTimingLineReportsEachPhaseFromItsClock() @@ -203,7 +203,8 @@ public sealed class InjectedClockTests }; harness.Server.Offer(FakePrintServer.Job(document), document); Assert.True(await harness.RunOnceAsync()); - Assert.Contains("job-1: timing inventory=5ms claim=9ms download=11ms revalidate=10ms gate=2ms submit=13ms", harness.Log, StringComparer.Ordinal); + Assert.Contains("job-1: timing inventory=5ms claim=9ms download=11ms revalidate=5ms gate=2ms submit=13ms", harness.Log, StringComparer.Ordinal); + Assert.Equal(2, printer.Discoveries); } diff --git a/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs b/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs index 0eeadda..2ab3184 100644 --- a/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs +++ b/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs @@ -113,26 +113,27 @@ public sealed class PrintWorkerOutcomeTests /// - /// A replay of a job this computer is already working on in another lane is left entirely to the lane that holds - /// it, whatever that lane has recorded so far. Nothing is recorded or reported for it, its title and printer are not - /// rewritten, the runtime is not told a job became active, and it is neither downloaded nor printed. The log says so - /// once, in plain words, and the pass ends, because the server would only offer the same job again. + /// A replay of a job another lane of this computer holds is left entirely to that lane, whatever it has recorded so + /// far. A lane lets go of a job only after its final state was recorded and delivered, so the job in hand may be + /// one that has just finished (the SPOOLED row); the log line is worded to be true then as well. Nothing is + /// recorded or reported for the replay, its title and printer are not rewritten, the runtime is not told a job + /// became active, and it is neither downloaded nor printed. The log says so once, in plain words, and the pass + /// ends, because the server would only offer the same job again. /// [Theory] [InlineData("RECEIVED")] - [InlineData("SUBMITTING")] - public async Task ClaimOfAJobInHandEndsThePassRecordsNothingAndLogsOneLine(string heldAt) + [InlineData("RECEIVED,SUBMITTING")] + [InlineData("RECEIVED,SUBMITTING,SPOOLED")] + public async Task ClaimOfAJobInHandEndsThePassRecordsNothingAndLogsOneLine(string recordedSoFar) { await using var harness = new WorkerHarness(); (FakePrintServer server, RecordingJournal journal, FakePrinterBackend printer) = (harness.Server, harness.Journal, harness.Printer); server.Offer(FakePrintServer.Job(Document) with { Title = "Replayed title" }, Document); journal.TrackJob(FakePrintServer.Job(Document) with { Title = "Original title" }, "Original printer"); - journal.Record("job-1", new PrintEvent("received-by-the-other-lane", "RECEIVED")); - journal.Acknowledge("received-by-the-other-lane"); - if(string.Equals(heldAt, "SUBMITTING", StringComparison.Ordinal)) + foreach(string state in recordedSoFar.Split(',')) { - journal.Record("job-1", new PrintEvent("submitting-by-the-other-lane", "SUBMITTING")); - journal.Acknowledge("submitting-by-the-other-lane"); + journal.Record("job-1", new PrintEvent(state + "-by-the-other-lane", state)); + journal.Acknowledge(state + "-by-the-other-lane"); } string[] recordedByTheOtherLane = journal.StatesOf("job-1"); var asked = new List(); @@ -158,30 +159,41 @@ public sealed class PrintWorkerOutcomeTests Assert.Equal("Original printer", journal.Jobs["job-1"].PrinterName); Assert.Equal(0, server.Downloads); Assert.Equal(0, printer.Submissions); - Assert.Equal("job-1: offered again while this computer is already working on it; it is left to the lane that holds it, nothing is recorded for it and this pass claims nothing more.", Assert.Single(harness.Log)); + Assert.Equal("job-1: offered again while a lane of this computer still holds it, working on it or just finished with it; it is left to that lane, nothing is recorded for it and this pass claims nothing more.", Assert.Single(harness.Log)); } /// - /// Jobs can wait a long time for a printer's turn. What happened to the printer during the wait is found when the - /// turn is held, before SUBMITTING is recorded: a printer the operator stopped sharing, a queue that is gone, or a - /// selected media default that changed is FAILED with its reason and Windows is never asked. The receipts are - /// RECEIVED then FAILED, the backend is never called, the turn is released, nothing stays in the staging folder, - /// and the job is neither downloaded nor printed when the server offers it again. Without this check the first of - /// these was refused only by the exposure filter, after SUBMITTING, and recorded as an unknown outcome. + /// Jobs can wait a long time for a printer's turn, and the worker does not discover the printers again when the + /// turn is held: that would start the print helper once more for every job, while the job holds the turn and a + /// print slot. What happened to the printer during the wait is therefore settled after SUBMITTING is recorded, by + /// whoever can tell whether anything was sent. A printer the operator stopped sharing is refused by the exposure + /// filter before the backend is called, and a selected media default that changed is refused by the native layer + /// before it prints: both are FAILED. A queue that is gone is found by the native layer as well, but its failure + /// carries no type the worker can rely on, so the job is OUTCOME_UNKNOWN like any other failure after the staged + /// file was handed over. The fake backend plays the native layer here: it finds the queue, then matches the job's + /// selected media against the queue's current default, and only then would print. In every case the printer is + /// discovered twice and no more (the inventory and the check after the download), the turn is released, nothing + /// stays in the staging folder, and the job is neither downloaded nor printed when the server offers it again. /// [Theory] - [InlineData("unshared", "Assigned printer or document format is unavailable.")] - [InlineData("queue-gone", "Assigned printer or document format is unavailable.")] - [InlineData("media-changed", "The selected printer media profile changed or is unavailable. Refresh the printer and select its current default.")] - public async Task PrinterWithdrawnWhileWaitingForItsTurnIsFailedAndTheBackendIsNeverCalled(string change, string reason) + [InlineData("unshared", "FAILED", "The printer is not exposed to QQQ on this computer; no bytes were submitted.", 0)] + [InlineData("media-changed", "FAILED", "The selected printer media profile changed or is unavailable. Refresh the printer and select its current default.", 1)] + [InlineData("queue-gone", "OUTCOME_UNKNOWN", "The assigned queue was not found.", 1)] + public async Task ChangeToThePrinterWhileWaitingForItsTurnIsSettledAfterSubmittingByWhoeverCanTell(string change, string outcome, string reason, int submissions) { PrinterMediaProfile profile = new("default-id", new string('a', 64), "Default", 101600, 152400, 300, 300); PrintJob job = FakePrintServer.Job(Document, options: new PrintOptions(MediaProfile: new(profile.Id, profile.Revision))); await using var harness = new WorkerHarness(); (FakePrintServer server, RecordingJournal journal, FakePrinterBackend printer) = (harness.Server, harness.Journal, harness.Printer); printer.Printers[0] = printer.Printers[0] with { MediaProfiles = [profile] }; + printer.Printing = (submitted, _, _) => + { + PrinterInfo queue = printer.Printers.FirstOrDefault(item => string.Equals(item.PrinterId, submitted.PrinterId, StringComparison.Ordinal)) ?? throw new InvalidOperationException("The assigned queue was not found."); + PrinterMediaProfile.RequireMatch(submitted.Options, queue.MediaProfiles); + return Task.FromResult("spool-1"); + }; server.Offer(job, Document).Offer(job, Document); var steps = new List(); harness.Options = harness.Options with @@ -209,23 +221,25 @@ public sealed class PrintWorkerOutcomeTests }; Assert.True(await harness.RunOnceAsync()); - Assert.Equal(new[] { "RECEIVED", "FAILED" }, journal.StatesOf("job-1"), StringComparer.Ordinal); + Assert.Equal(new[] { "RECEIVED", "SUBMITTING", outcome }, journal.StatesOf("job-1"), StringComparer.Ordinal); Assert.Equal(reason, journal.Last("job-1").Message); - Assert.Equal(new[] { "RECEIVED", "FAILED" }, server.States, StringComparer.Ordinal); - Assert.Equal(0, printer.Submissions); + Assert.Null(journal.Last("job-1").SpoolerJobId); + Assert.Equal(new[] { "RECEIVED", "SUBMITTING", outcome }, server.States, StringComparer.Ordinal); + Assert.Equal(submissions, printer.Submissions); + Assert.Equal(2, printer.Discoveries); Assert.Equal(new[] { "take printer turn", "release printer turn" }, steps, StringComparer.Ordinal); Assert.Empty(Directory.EnumerateFileSystemEntries(harness.Staging.Path)); Assert.False(await harness.RunOnceAsync()); Assert.Equal(2, server.Claims); Assert.Equal(1, server.Downloads); - Assert.Equal(0, printer.Submissions); - Assert.Equal("FAILED", journal.GetState("job-1")); + Assert.Equal(submissions, printer.Submissions); + Assert.Equal(outcome, journal.GetState("job-1")); } - /// A printer withdrawn earlier, before the document is downloaded, is still caught by the check that follows the download: the job is FAILED with nothing submitted and never asks for the printer's turn. + /// A printer withdrawn before the document has been downloaded is caught by the check that follows the download: the job is FAILED with nothing submitted and never asks for the printer's turn. [Fact] public async Task PrinterWithdrawnBeforeTheDownloadIsStillFailedAndNeverTakesTheTurn() { @@ -256,11 +270,11 @@ public sealed class PrintWorkerOutcomeTests /// - /// The exposure filter stays the last line of defense, because sharing can still change in the instant between the - /// worker's check and the call. A printer withdrawn after SUBMITTING was recorded is refused by the filter before - /// the backend behind it is called, with a refusal only the filter can raise. The worker therefore knows nothing - /// was sent: the job is FAILED, not unknown, its reason says that no bytes were submitted, the backend was never - /// called, and the job is not printed when the server offers it again. + /// The exposure filter is the check on sharing at the moment of submission, however late sharing changed: here in + /// the instant after SUBMITTING was recorded. The filter refuses before the backend behind it is called, with a + /// refusal only the filter can raise. The worker therefore knows nothing was sent: the job is FAILED, not unknown, + /// its reason says that no bytes were submitted, the backend was never called, and the job is not printed when the + /// server offers it again. /// [Fact] public async Task PrinterWithdrawnAfterTheSubmittingReceiptIsRefusedByTheFilterAndFailedWithNothingSent() -- 2.54.0 From 0d8fa244374d873fc8a29d871b8bc5a210fea8ea Mon Sep 17 00:00:00 2001 From: James Maes Date: Tue, 10 Nov 2026 18:08:51 -0600 Subject: [PATCH 4/8] test(runtime): a job offered again while its submission is held is left to its lane One runtime test for the in-hand function, on the realtime fixture's existing public members. One lane is inside the printer with a job; the server offers the same job to a second lane, whose claim is held at the server until then. The second lane logs the in-hand line once, records and reports nothing, does not register a second ticket (which stopped the lane with "An item with the same key has already been added") and does not print. The job is then SPOOLED and was printed once. Signed-off-by: James Maes Co-Authored-By: Claude Fable 5.2 --- .../AgentRealtimeInHandTests.cs | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 tests/Qqq.PrintAgent.Cli.Tests/AgentRealtimeInHandTests.cs diff --git a/tests/Qqq.PrintAgent.Cli.Tests/AgentRealtimeInHandTests.cs b/tests/Qqq.PrintAgent.Cli.Tests/AgentRealtimeInHandTests.cs new file mode 100644 index 0000000..88041ed --- /dev/null +++ b/tests/Qqq.PrintAgent.Cli.Tests/AgentRealtimeInHandTests.cs @@ -0,0 +1,75 @@ +/* + * Copyright (c) 2026 James Maes + * SPDX-License-Identifier: MIT + */ + +using Qqq.PrintAgent.Core.Printing; + +namespace Qqq.PrintAgent.Cli.Tests; + +/// +/// What the service does when the server offers a job that one of its own lanes still holds. The lane that holds the +/// job is the only one that may act on it, so the offer is logged in plain words and otherwise ignored. +/// +public sealed class AgentRealtimeInHandTests +{ + private const string InHandLine = "job: offered again while a lane of this computer still holds it, working on it or just finished with it; it is left to that lane, nothing is recorded for it and this pass claims nothing more."; + + + + /// + /// One lane has claimed a job and is inside the printer with it, so SUBMITTING is recorded and the lane holds the + /// job's ticket. The server then offers the same job to a second lane. The second lane says so once in the log, + /// records and reports nothing, and ends its pass. It does not register a second ticket for the job, which would + /// stop the lane with an error ("An item with the same key has already been added"), and it does not print. When + /// the printer lets the first submission finish, the job is SPOOLED and was printed once, with one RECEIVED, one + /// SUBMITTING and one SPOOLED reported. The second lane's claim is held at the server until the first submission is + /// inside the printer, so the offer arrives while the submission is held. + /// + [Fact] + public async Task JobOfferedAgainWhileItsSubmissionIsHeldIsLeftToTheLaneThatHoldsIt() + { + await using RealtimeRuntimeFixture fixture = new(downloads: 2); + fixture.Printer.BlockPrint = true; + var secondClaim = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + fixture.BeforeAcknowledgement = message => + { + //////////////////////////////////////////////////////////////////////// + // the next lane claims as soon as this RECEIVED is acknowledged, so // + // its claim is held from here until the first lane is in the printer // + //////////////////////////////////////////////////////////////////////// + if(IsEvent(message, "RECEIVED")) + { fixture.ClaimHold = secondClaim; } + return Task.CompletedTask; + }; + fixture.AddJob("job"); + await fixture.ConnectAsync(); + await fixture.WaitAsync(fixture.Printer.Entered.Task); + await fixture.WaitAsync(() => fixture.Claims == 2); + Assert.Equal("SUBMITTING", fixture.State("job")); + + fixture.AddJob("job"); + secondClaim.SetResult(); + await fixture.WaitAsync(() => fixture.Logs.Any(line => line.Contains("offered again", StringComparison.Ordinal))); + Assert.Contains(InHandLine, Assert.Single(fixture.Logs, line => line.Contains("offered again", StringComparison.Ordinal)), StringComparison.Ordinal); + Assert.Equal("SUBMITTING", fixture.State("job")); + Assert.Equal(1, fixture.Printer.Submissions); + + fixture.Printer.Release.SetResult(); + await fixture.WaitAsync(() => fixture.Messages.Any(message => IsEvent(message, "SPOOLED"))); + Assert.Equal("SPOOLED", fixture.State("job")); + Assert.Equal("job", Assert.Single(fixture.Printer.Order)); + Assert.Equal(1, fixture.Printer.Submissions); + Assert.Equal(new[] { "RECEIVED", "SUBMITTING", "SPOOLED" }, fixture.Messages.Where(message => message.Type is "JOB_EVENT").Select(message => message.Payload.GetProperty("event").GetProperty("status").GetString()), StringComparer.Ordinal); + Assert.Single(fixture.Logs, line => line.Contains("offered again", StringComparison.Ordinal)); + Assert.DoesNotContain(fixture.Logs, line => line.Contains("Print lane stopped", StringComparison.Ordinal) || line.Contains("same key", StringComparison.OrdinalIgnoreCase)); + Assert.Equal(0, fixture.ForbiddenPolls); + } + + + + /// True for an event of the test's one job with the given status. + private static bool IsEvent(RealtimeEnvelope message, string status) + => message.Type is "JOB_EVENT" && string.Equals(message.Payload.GetProperty("jobId").GetString(), "job", StringComparison.Ordinal) + && string.Equals(message.Payload.GetProperty("event").GetProperty("status").GetString(), status, StringComparison.Ordinal); +} -- 2.54.0 From 8a848282fc9a79e354df38dd807eaccd98a8a02d Mon Sep 17 00:00:00 2001 From: James Maes Date: Tue, 10 Nov 2026 18:08:51 -0600 Subject: [PATCH 5/8] docs: one printer check per job, and what a change during the wait becomes REALTIME no longer describes a second check when the printer's turn is held. It says what settles each change that happens while a job waits for its turn (the exposure filter, the print helper's media check, and the missing queue that is still OUTCOME_UNKNOWN), and that a job in hand may be one that has just finished. The changelog entry is rewritten to match. Signed-off-by: James Maes Co-Authored-By: Claude Fable 5.2 --- CHANGELOG.md | 22 ++++++++++--------- docs/REALTIME.md | 56 +++++++++++++++++++++++++++++++----------------- 2 files changed, 48 insertions(+), 30 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e99cc5..bbfcf9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,18 +2,20 @@ ## Unreleased -Two cases the print worker now settles before Windows is asked (2.0). +Two cases the print worker now settles with a known outcome (2.0). - A printer that stops being shared while jobs wait behind a print no longer leaves those jobs with an unknown - outcome. The worker checks the printer again when the job's turn comes, before SUBMITTING is recorded: a printer - that is no longer shared, a queue that is gone, or a selected media default that changed during the wait is - FAILED with its reason, and nothing is sent to Windows. If sharing changes in the instant after that check, the - job is still FAILED, with a reason ending "no bytes were submitted", because the refusal is known to come before - anything is sent. Each job costs one more printer discovery, and the log's timing line counts both checks under - `revalidate`. -- A job the server offers again while this computer is still working on it is left to the lane that holds it. The - log says so in plain words, nothing is recorded for the replay, and the lane ends its pass. Before, the replay was - stopped only by an internal duplicate check that logged "An item with the same key has already been added". + outcome. The filter that checks sharing at the moment of submission refuses before anything is handed to Windows, + and its refusal now has a type of its own, so the worker records the job as FAILED with a reason ending "no bytes + were submitted" where it used to record OUTCOME_UNKNOWN. History shows RECEIVED, SUBMITTING, FAILED. The printer + is still discovered once per job after the download, as before, and not a second time while the job holds the + printer's turn. A selected media default that changed during the wait is refused by the print helper before it + prints and is FAILED, as before. A queue that was removed from Windows during the wait is still + OUTCOME_UNKNOWN: the print helper finds it missing before it sends anything but cannot yet say so in a form the + worker can rely on. +- A job the server offers again while a lane of this computer still holds it is left to that lane. The log says so + in plain words, nothing is recorded for the replay, and the lane ends its pass. Before, the replay was stopped + only by an internal duplicate check that logged "An item with the same key has already been added". Branded Start menu shortcut (2.0). The installer step that creates, renames and removes the shortcut under **Start → Print Connectors** now records, by name, every shortcut it has put there and may still own, and a file diff --git a/docs/REALTIME.md b/docs/REALTIME.md index 3c5c896..23d2fc0 100644 --- a/docs/REALTIME.md +++ b/docs/REALTIME.md @@ -101,26 +101,42 @@ levels, so that a job nested too deep to read can still be identified. released capacity starts a new wave. The outcome is reported by the lane that is submitting the job or, after a restart, by the runtime's recovery at start as OUTCOME_UNKNOWN. -- **Claimed job that is already in hand.** A job a lane of this computer is - working on right now is left to that lane when the server offers it again. - The worker asks the runtime whether the job is in hand before it does - anything else with the claim: nothing is recorded or reported, the job's - title and printer in history are not rewritten, the log says once that the - job was offered again while this computer is already working on it, and the - lane ends its pass as it does for a job that is submitting. -- **Printer withdrawn while the job waits.** The assigned printer is checked - twice before SUBMITTING is recorded: after the download, and again when the - printer's turn is held, because a job can wait a long time behind a print. - A printer the operator stopped sharing, a queue that is gone, or a selected - media default that changed during either wait is FAILED with its reason, - and Windows is never asked. The timing line reports both checks together as - `revalidate`. -- **Printer withdrawn after SUBMITTING.** Sharing can still change in the - instant between that check and the call, so the exposure filter in front of - the backend checks once more. Its refusal is made before the backend behind - it is called and has a type only the filter can raise, so the worker knows - nothing was sent: the job is FAILED, not OUTCOME_UNKNOWN, and its reason - ends "no bytes were submitted". +- **Claimed job that is already in hand.** A job a lane of this computer + holds is left to that lane when the server offers it again. A lane holds a + job from its claim until it lets go, which is after the final state was + recorded and delivered, so a job in hand is being worked on or has just + finished. The worker asks the runtime whether the job is in hand before it + does anything else with the claim: nothing is recorded or reported, the + job's title and printer in history are not rewritten, the log says once + that the job was offered again while a lane of this computer still holds + it, and the lane ends its pass as it does for a job that is submitting. +- **Printer changed before the download finished.** The assigned printer is + discovered again once, after the download and before the job asks for the + printer's turn. A printer the operator stopped sharing, a queue that is + gone, or a selected media default that changed by then is FAILED with its + reason before SUBMITTING is recorded, and Windows is never asked. The + timing line reports this one check as `revalidate`. +- **Printer changed while the job waits for its turn.** A job can wait a + long time behind a print. The worker does not discover the printers again + when the turn is held: that would start the print helper once more for + every job, while the job holds the printer's turn and a print slot, and + would add a second wait on a slow driver of an unrelated queue. What + changed during the wait is settled after SUBMITTING is recorded, by + whoever can tell whether anything was sent: + - *No longer shared.* The exposure filter in front of the backend checks + sharing at the moment of submission. Its refusal is made before the + backend behind it is called and has a type only the filter can raise, so + the worker knows nothing was sent: the job is FAILED, not + OUTCOME_UNKNOWN, and its reason ends "no bytes were submitted". + - *Media default changed.* The print helper reads the queue's default + again before it starts the document and refuses a mismatch with its own + error code. The job is FAILED. + - *Queue removed from Windows.* The print helper finds no queue before it + sends anything, but reports that as an ordinary failure, which the worker + cannot tell from one that happened part-way. The job is OUTCOME_UNKNOWN + and needs an operator's review, although nothing was printed. An error + code for a missing queue would let the worker record FAILED; it is not + implemented. - **Between SUBMITTING and Windows.** If delivery of the SUBMITTING receipt cannot be confirmed, or the worker is stopped after it was acknowledged and before the native call, Windows is never asked. The job is FAILED and its -- 2.54.0 From 26249a27632d6647c193f0526b7107f4ed7e3871 Mon Sep 17 00:00:00 2001 From: James Maes Date: Tue, 10 Nov 2026 19:50:06 -0600 Subject: [PATCH 6/8] test(runtime): offer a job again while its lane is still downloading it The runtime test for a job in hand held the first lane inside the printer, where SUBMITTING is already recorded. A build without the in-hand check stops that offer through the journal, so only the wording assertion could fail there, and a check wired to the submitting set instead of the ticket registry passed the whole test. The test is now a theory with two rows. In the first the lane is held in its download, so the journal says RECEIVED and only the ticket shows the job is in hand; in the second it is inside the printer, as before. Both the in-hand line and the absence of a stopped lane discriminate in the first row: against release/2.0 without the check, and against the check wired to the submitting set. It is also deterministic now. One download is allowed at first, so no second lane can start a pass until the first lane is held; the test then puts the job back on the server's queue and has the server allow a second download. Before, the second lane could read the journal in the instant between the first lane's RECEIVED being recorded and acknowledged, end the wave, and leave the test waiting for a claim that never came. Signed-off-by: James Maes Co-Authored-By: Claude Fable 5.2 --- .../AgentRealtimeInHandTests.cs | 105 ++++++++++++------ 1 file changed, 70 insertions(+), 35 deletions(-) diff --git a/tests/Qqq.PrintAgent.Cli.Tests/AgentRealtimeInHandTests.cs b/tests/Qqq.PrintAgent.Cli.Tests/AgentRealtimeInHandTests.cs index 88041ed..e04d935 100644 --- a/tests/Qqq.PrintAgent.Cli.Tests/AgentRealtimeInHandTests.cs +++ b/tests/Qqq.PrintAgent.Cli.Tests/AgentRealtimeInHandTests.cs @@ -3,6 +3,7 @@ * SPDX-License-Identifier: MIT */ +using System.Text; using Qqq.PrintAgent.Core.Printing; namespace Qqq.PrintAgent.Cli.Tests; @@ -18,58 +19,92 @@ public sealed class AgentRealtimeInHandTests /// - /// One lane has claimed a job and is inside the printer with it, so SUBMITTING is recorded and the lane holds the - /// job's ticket. The server then offers the same job to a second lane. The second lane says so once in the log, - /// records and reports nothing, and ends its pass. It does not register a second ticket for the job, which would - /// stop the lane with an error ("An item with the same key has already been added"), and it does not print. When - /// the printer lets the first submission finish, the job is SPOOLED and was printed once, with one RECEIVED, one - /// SUBMITTING and one SPOOLED reported. The second lane's claim is held at the server until the first submission is - /// inside the printer, so the offer arrives while the submission is held. + /// One lane has claimed a job and holds its ticket, and the server then offers the same job to a second lane. In + /// the first row the first lane is still downloading the document, so the journal says RECEIVED and only the + /// ticket shows that the job is in hand; in the second it is inside the printer, so SUBMITTING is recorded as + /// well. Either way the second lane says so once in the log, in the words for a job in hand, records and reports + /// nothing, and ends its pass. It does not register a second ticket for the job, which would stop the lane with an + /// error ("An item with the same key has already been added"), and it does not print. When the first lane is let + /// go, the job is SPOOLED and was printed once, with one RECEIVED, one SUBMITTING and one SPOOLED reported. + /// + /// Only one download is allowed at first, so no second lane can start a pass, read the journal or claim until the + /// first lane is held where the row wants it. The test then puts the job back on the server's queue and has the + /// server allow a second download, which is what lets the second lane claim. The wait that follows ends when that + /// lane's pass has ended, in either of the two ways it can: with the line for an offer, or with a stopped lane. + /// /// - [Fact] - public async Task JobOfferedAgainWhileItsSubmissionIsHeldIsLeftToTheLaneThatHoldsIt() + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task JobOfferedAgainWhileALaneHoldsItIsLeftToThatLane(bool submitting) { - await using RealtimeRuntimeFixture fixture = new(downloads: 2); - fixture.Printer.BlockPrint = true; - var secondClaim = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); - fixture.BeforeAcknowledgement = message => - { - //////////////////////////////////////////////////////////////////////// - // the next lane claims as soon as this RECEIVED is acknowledged, so // - // its claim is held from here until the first lane is in the printer // - //////////////////////////////////////////////////////////////////////// - if(IsEvent(message, "RECEIVED")) - { fixture.ClaimHold = secondClaim; } - return Task.CompletedTask; - }; - fixture.AddJob("job"); - await fixture.ConnectAsync(); - await fixture.WaitAsync(fixture.Printer.Entered.Task); - await fixture.WaitAsync(() => fixture.Claims == 2); - Assert.Equal("SUBMITTING", fixture.State("job")); + await using RealtimeRuntimeFixture fixture = new(downloads: 1); + byte[] bytes = Encoding.ASCII.GetBytes("%PDF-synthetic-job"); + using var document = new HeldDocument(bytes); + fixture.Printer.BlockPrint = submitting; + if(submitting) + { document.Release.SetResult(); } + fixture.AddJob("job", () => document, length: bytes.Length); + Assert.True(fixture.Queue.TryPeek(out PrintJob? offer)); + ScriptedPrintServer.Connection connection = await fixture.ConnectAsync(); + await fixture.WaitAsync(submitting ? fixture.Printer.Entered.Task : document.Entered.Task); + string held = submitting ? "SUBMITTING" : "RECEIVED"; + Assert.Equal(held, fixture.State("job")); + Assert.Equal(1, fixture.Claims); - fixture.AddJob("job"); - secondClaim.SetResult(); - await fixture.WaitAsync(() => fixture.Logs.Any(line => line.Contains("offered again", StringComparison.Ordinal))); - Assert.Contains(InHandLine, Assert.Single(fixture.Logs, line => line.Contains("offered again", StringComparison.Ordinal)), StringComparison.Ordinal); - Assert.Equal("SUBMITTING", fixture.State("job")); - Assert.Equal(1, fixture.Printer.Submissions); + fixture.Queue.Enqueue(offer); + await connection.SendAsync("SETTINGS", fixture.Settings with { Revision = 2, MaxConcurrentDownloads = 2 }); + await fixture.WaitAsync(() => fixture.Logs.Any(line => IsOffer(line) || IsStoppedLane(line))); + Assert.Contains(InHandLine, Assert.Single(fixture.Logs, IsOffer), StringComparison.Ordinal); + Assert.Equal(2, fixture.Claims); + Assert.Equal(held, fixture.State("job")); + Assert.Equal(submitting ? 1 : 0, fixture.Printer.Submissions); + document.Release.TrySetResult(); fixture.Printer.Release.SetResult(); await fixture.WaitAsync(() => fixture.Messages.Any(message => IsEvent(message, "SPOOLED"))); Assert.Equal("SPOOLED", fixture.State("job")); Assert.Equal("job", Assert.Single(fixture.Printer.Order)); Assert.Equal(1, fixture.Printer.Submissions); Assert.Equal(new[] { "RECEIVED", "SUBMITTING", "SPOOLED" }, fixture.Messages.Where(message => message.Type is "JOB_EVENT").Select(message => message.Payload.GetProperty("event").GetProperty("status").GetString()), StringComparer.Ordinal); - Assert.Single(fixture.Logs, line => line.Contains("offered again", StringComparison.Ordinal)); - Assert.DoesNotContain(fixture.Logs, line => line.Contains("Print lane stopped", StringComparison.Ordinal) || line.Contains("same key", StringComparison.OrdinalIgnoreCase)); + Assert.Single(fixture.Logs, IsOffer); + Assert.DoesNotContain(fixture.Logs, IsStoppedLane); Assert.Equal(0, fixture.ForbiddenPolls); } + /// True for a log line about a job that was offered again, whatever reason the line gives. + private static bool IsOffer(string line) => line.Contains("offered again", StringComparison.Ordinal); + + + + /// True for a log line that says a lane stopped on an error, or that carries the duplicate-ticket error itself. + private static bool IsStoppedLane(string line) => line.Contains("Print lane stopped", StringComparison.Ordinal) || line.Contains("same key", StringComparison.OrdinalIgnoreCase); + + + /// True for an event of the test's one job with the given status. private static bool IsEvent(RealtimeEnvelope message, string status) => message.Type is "JOB_EVENT" && string.Equals(message.Payload.GetProperty("jobId").GetString(), "job", StringComparison.Ordinal) && string.Equals(message.Payload.GetProperty("event").GetProperty("status").GetString(), status, StringComparison.Ordinal); + + + + /// A document body that signals when the agent starts reading it and then withholds its bytes until the test releases it, which holds a lane in its download with the job in hand. + private sealed class HeldDocument(byte[] bytes) : MemoryStream(bytes) + { + internal TaskCompletionSource Entered { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously); + internal TaskCompletionSource Release { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously); + + + + /// Signals the first read, waits for release, then reads normally. + public override async ValueTask ReadAsync(Memory buffer, CancellationToken cancellationToken = default) + { + Entered.TrySetResult(); + await Release.Task.WaitAsync(cancellationToken); + return await base.ReadAsync(buffer, cancellationToken); + } + } } -- 2.54.0 From a9783f9cdbe08e716050f1c326cb2eeba3670da9 Mon Sep 17 00:00:00 2001 From: James Maes Date: Tue, 10 Nov 2026 19:51:31 -0600 Subject: [PATCH 7/8] fix(core): let go of a job even when recording its interrupted receipt fails When the receipt for a newly claimed job could not be delivered, the worker recorded FAILED and then told the runtime the job was no longer active. If the journal failed on that FAILED, the second step was skipped and the job's ticket stayed in the runtime's registry until the service restarted. Every later offer of that job was then logged as one a lane still holds, which was false. Before the in-hand check the same leak showed as "An item with the same key has already been added". The lane now lets go in a finally around the recording. Nothing changes in when RECEIVED or FAILED are recorded, or in which failure reaches the caller: the journal's, as before, when recording fails. The new test fails without the change: the runtime is told the job is active and never told it stopped. Signed-off-by: James Maes Co-Authored-By: Claude Fable 5.2 --- CHANGELOG.md | 4 ++- .../Printing/PrintWorker.cs | 6 ++-- .../PrintWorkerOutcomeTests.cs | 31 +++++++++++++++++++ 3 files changed, 38 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bbfcf9c..78c0b62 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,7 +15,9 @@ Two cases the print worker now settles with a known outcome (2.0). worker can rely on. - A job the server offers again while a lane of this computer still holds it is left to that lane. The log says so in plain words, nothing is recorded for the replay, and the lane ends its pass. Before, the replay was stopped - only by an internal duplicate check that logged "An item with the same key has already been added". + only by an internal duplicate check that logged "An item with the same key has already been added". A lane + also lets go of a job whose receipt was interrupted when the journal then fails to record that failure; before, + the job stayed marked as held until the service restarted, and every later offer of it was turned away. Branded Start menu shortcut (2.0). The installer step that creates, renames and removes the shortcut under **Start → Print Connectors** now records, by name, every shortcut it has put there and may still own, and a file diff --git a/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs b/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs index 1172b3b..d89ffba 100644 --- a/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs +++ b/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs @@ -89,8 +89,10 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ } catch { - Record(job, PrintJobState.Failed, "Receipt acknowledgement was interrupted before document submission; no bytes were submitted."); - options.ActiveJobChanged(null); + // The lane lets go of the job whatever the recording does: a ticket left behind would make every later offer of the job read as one a lane still holds. + try + { Record(job, PrintJobState.Failed, "Receipt acknowledgement was interrupted before document submission; no bytes were submitted."); } + finally { options.ActiveJobChanged(null); } throw; } return new Claim(job, false); diff --git a/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs b/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs index 2ab3184..c2d998a 100644 --- a/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs +++ b/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs @@ -436,6 +436,37 @@ public sealed class PrintWorkerOutcomeTests + /// + /// The lane lets go of a job whose receipt was interrupted even when the journal then fails to record FAILED for + /// it. The runtime is still told the job is no longer active, so no ticket is left behind to make a later offer of + /// the job read as one a lane still holds. The journal's failure is what reaches the caller, nothing was + /// downloaded or submitted, and both gates are released. + /// + [Fact] + public async Task InterruptedReceiptLetsGoOfTheJobEvenWhenRecordingItsFailureFails() + { + await using var harness = new WorkerHarness(); + (FakePrintServer server, RecordingJournal journal, FakePrinterBackend printer) = (harness.Server, harness.Journal, harness.Printer); + server.Arriving = (kind, _) => string.Equals(kind, "events", StringComparison.Ordinal) ? throw new HttpRequestException("Synthetic refusal.") : Task.CompletedTask; + journal.Recorded = (_, recorded) => + { + if(string.Equals(recorded.Status, "FAILED", StringComparison.Ordinal)) + { throw new IOException("Synthetic journal failure."); } + }; + server.Offer(FakePrintServer.Job(Document), Document); + var active = new List(); + harness.Options = harness.Options with { ActiveJobChanged = job => active.Add(job?.JobId) }; + IOException failure = await Assert.ThrowsAsync(() => harness.RunOnceAsync()); + Assert.Equal("Synthetic journal failure.", failure.Message); + Assert.Equal(new[] { "job-1", null }, active, StringComparer.Ordinal); + Assert.Equal(0, server.Downloads); + Assert.Equal(0, printer.Submissions); + Assert.Equal(1, harness.EventGate.CurrentCount); + Assert.Equal(1, harness.ClaimGate.CurrentCount); + } + + + /// A lane told that another lane already found the queue empty does not ask the server for work at all. [Fact] public async Task LaneThatMayNotClaimSendsNoClaim() -- 2.54.0 From 69ffc192f37f9fc987a82320f3837f3546cd970a Mon Sep 17 00:00:00 2001 From: James Maes Date: Tue, 10 Nov 2026 19:52:14 -0600 Subject: [PATCH 8/8] docs: when a lane lets go of a job, and a job in hand as a reason a pass ends The worker's comments, the option's summary and REALTIME.md said a lane lets go of a job "after its final state was recorded and delivered". That is the normal case, not a rule: delivery is skipped when the pass is cancelled and can fail, and the lane lets go all the same. They now say the lane holds a job until its pass for that job ends, and what normally comes before that. The summary of a pass also lists a job a lane already holds among the reasons it returns false. Comments and documentation only. Signed-off-by: James Maes Co-Authored-By: Claude Fable 5.2 --- docs/REALTIME.md | 11 +++++++---- src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs | 13 +++++++------ .../Printing/PrintWorkerOptions.cs | 2 +- 3 files changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/REALTIME.md b/docs/REALTIME.md index 23d2fc0..3054dc7 100644 --- a/docs/REALTIME.md +++ b/docs/REALTIME.md @@ -103,10 +103,13 @@ levels, so that a job nested too deep to read can still be identified. as OUTCOME_UNKNOWN. - **Claimed job that is already in hand.** A job a lane of this computer holds is left to that lane when the server offers it again. A lane holds a - job from its claim until it lets go, which is after the final state was - recorded and delivered, so a job in hand is being worked on or has just - finished. The worker asks the runtime whether the job is in hand before it - does anything else with the claim: nothing is recorded or reported, the + job from its claim until its pass for that job ends. Normally that is after + the final state was recorded and delivered; the delivery is skipped when + the pass is cancelled, as when the connection is replaced or the service + stops, and a delivery can fail, and the lane lets go all the same. So a job + in hand is being worked on or has just finished. The worker asks the + runtime whether the job is in hand before it does anything else with the + claim: nothing is recorded or reported, the job's title and printer in history are not rewritten, the log says once that the job was offered again while a lane of this computer still holds it, and the lane ends its pass as it does for a job that is submitting. diff --git a/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs b/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs index d89ffba..ce48e7d 100644 --- a/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs +++ b/src/Qqq.PrintAgent.Core/Printing/PrintWorker.cs @@ -21,8 +21,8 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ /// stay invisible. Only when nothing is pending, the connection is synchronized and dispatch is allowed does it /// discover printers and claim at most one job. Returns true whenever a claimed job was processed, whatever its /// outcome, and when a malformed job was refused and reported, so the lane keeps draining; false when idle, - /// paused, blocked, or the claimed job was one the journal already holds as final or as submitting, which ends the - /// lane's pass because the server would only offer that job again. + /// paused, blocked, or the claimed job was one a lane of this computer already holds, or one the journal already + /// holds as final or as submitting, which ends the lane's pass because the server would only offer that job again. /// public async Task RunOnceAsync(CancellationToken token) { @@ -106,10 +106,11 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ /// Says whether a claimed job is one this computer must not start on, because it already has, and says so in the /// log when the server should not have offered it. A job that is in hand, held by a lane of this computer right /// now, is left entirely to that lane: nothing is recorded for it here, not even its display facts. The lane lets - /// go of a job only after its final state was recorded and delivered, so a job in hand may be one that has just - /// finished, and the log line says "still holds" for that reason and does not claim work is under way. A job the - /// journal holds as submitting was handed to a printer once already and has not concluded, and one it holds in a - /// final state has; neither is ever submitted a second time. + /// go of a job when its pass for that job ends. Normally that is after the job's final state was recorded and + /// delivered; delivery is skipped when the pass is cancelled, and it can fail, and the lane lets go all the same. + /// So a job in hand may be one that has just finished, and the log line says "still holds" for that reason and + /// does not claim work is under way. A job the journal holds as submitting was handed to a printer once already + /// and has not concluded, and one it holds in a final state has; neither is ever submitted a second time. /// private bool IsReplay(PrintJob job, IReadOnlyList inventory) { diff --git a/src/Qqq.PrintAgent.Core/Printing/PrintWorkerOptions.cs b/src/Qqq.PrintAgent.Core/Printing/PrintWorkerOptions.cs index 9199c7a..54eb93c 100644 --- a/src/Qqq.PrintAgent.Core/Printing/PrintWorkerOptions.cs +++ b/src/Qqq.PrintAgent.Core/Printing/PrintWorkerOptions.cs @@ -48,7 +48,7 @@ public sealed record PrintWorkerOptions - /// Says whether a lane of this computer holds the job with the given identifier: from the moment it was claimed until the lane lets go of it, which is after its final state was recorded and delivered. A claim of such a job is a replay, and the worker leaves the job to the lane that holds it. + /// Says whether a lane of this computer holds the job with the given identifier: from the moment it was claimed until the lane lets go of it when its pass for that job ends, normally after the job's final state was recorded and delivered. A claim of such a job is a replay, and the worker leaves the job to the lane that holds it. public required Func IsInHand { get; init; } -- 2.54.0