diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f2fd92..78c0b62 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,23 @@ ## Unreleased +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 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". 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 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..3054dc7 100644 --- a/docs/REALTIME.md +++ b/docs/REALTIME.md @@ -101,6 +101,45 @@ 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 + holds is left to that lane when the server offers it again. A lane holds a + 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. +- **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 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..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) { @@ -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 { @@ -103,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); @@ -114,6 +102,41 @@ 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 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) + { + if(options.IsInHand(job.JobId)) + { + 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); + 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 +181,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 +205,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 +221,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. + /// 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) { @@ -245,9 +275,10 @@ 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 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 32bb50d..54eb93c 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 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; } + + + /// 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/AgentRealtimeInHandTests.cs b/tests/Qqq.PrintAgent.Cli.Tests/AgentRealtimeInHandTests.cs new file mode 100644 index 0000000..e04d935 --- /dev/null +++ b/tests/Qqq.PrintAgent.Cli.Tests/AgentRealtimeInHandTests.cs @@ -0,0 +1,110 @@ +/* + * Copyright (c) 2026 James Maes + * SPDX-License-Identifier: MIT + */ + +using System.Text; +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 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. + /// + /// + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task JobOfferedAgainWhileALaneHoldsItIsLeftToThatLane(bool submitting) + { + 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.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, 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); + } + } +} 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..7e79b4e 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 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,6 +204,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.Equal(2, printer.Discoveries); } diff --git a/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs b/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs index 88c9736..c2d998a 100644 --- a/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs +++ b/tests/Qqq.PrintAgent.Core.Tests/PrintWorkerOutcomeTests.cs @@ -112,6 +112,199 @@ public sealed class PrintWorkerOutcomeTests + /// + /// 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("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"); + foreach(string state in recordedSoFar.Split(',')) + { + 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(); + 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 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, 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", "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 + { + 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", "SUBMITTING", outcome }, journal.StatesOf("job-1"), StringComparer.Ordinal); + Assert.Equal(reason, journal.Last("job-1").Message); + 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(submissions, printer.Submissions); + Assert.Equal(outcome, journal.GetState("job-1")); + } + + + + /// 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() + { + 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 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() + { + 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 @@ -243,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() 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()),