fix(core): check the printer once per job, leave a job in hand to its lane, and always let go of a job #44

Merged
james.maes merged 8 commits from fix/2.0-worker-recheck-and-in-hand-20261110 into release/2.0 2026-11-11 02:36:59 +00:00
14 changed files with 497 additions and 36 deletions

No files matched your search

+17
View File
@@ -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
+39
View File
@@ -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
@@ -17,12 +17,17 @@ public sealed class ExposedPrinterBackend(IPrinterBackend inner, Func<IReadOnlyS
/// <summary>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.</summary>
/// <summary>
/// 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, <see cref="PrinterNotExposedException"/>, so the caller knows
/// that nothing was submitted.
/// </summary>
public Task<string> 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);
}
+60 -29
View File
@@ -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.
/// </summary>
public async Task<bool> RunOnceAsync(CancellationToken token)
{
@@ -61,10 +61,10 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ
/// <summary>
/// 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.
/// </summary>
private async Task<Claim> ClaimAndRegisterAsync(IReadOnlyList<PrinterInfo> 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
/// <summary>
/// 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.
/// </summary>
private bool IsReplay(PrintJob job, IReadOnlyList<PrinterInfo> 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;
}
/// <summary>
/// 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.
/// </summary>
private async Task SubmitJobAsync(PrintJob job, JobAttempt attempt, CancellationToken token)
{
@@ -245,9 +275,10 @@ public sealed class PrintWorker(PrintApiClient api, IPrinterBackend printers, IJ
/// <summary>
/// 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.
/// </summary>
private void RequireCurrentPrinter(PrintJob job)
{
@@ -48,6 +48,11 @@ public sealed record PrintWorkerOptions
/// <summary>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.</summary>
public required Func<string, bool> IsInHand { get; init; }
/// <summary>Says whether this lane may still claim; false once another lane found the queue empty.</summary>
public required Func<bool> CanClaim { get; init; }
@@ -0,0 +1,21 @@
/*
* Copyright (c) 2026 James Maes
* SPDX-License-Identifier: MIT
*/
namespace Qqq.PrintAgent.Core.Printing;
/// <summary>
/// The exposure filter's refusal: the job's printer is not shared with QQQ on this computer. Only
/// <see cref="ExposedPrinterBackend"/> 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.
/// </summary>
public sealed class PrinterNotExposedException : InvalidOperationException
{
/// <summary>Creates the refusal. Internal so that no backend outside this assembly can raise it after it has started to print.</summary>
internal PrinterNotExposedException(string message) : base(message)
{
}
}
@@ -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,
@@ -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;
/// <summary>
/// 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.
/// </summary>
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.";
/// <summary>
/// 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.
/// <para>
/// 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.
/// </para>
/// </summary>
[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);
}
/// <summary>True for a log line about a job that was offered again, whatever reason the line gives.</summary>
private static bool IsOffer(string line) => line.Contains("offered again", StringComparison.Ordinal);
/// <summary>True for a log line that says a lane stopped on an error, or that carries the duplicate-ticket error itself.</summary>
private static bool IsStoppedLane(string line) => line.Contains("Print lane stopped", StringComparison.Ordinal) || line.Contains("same key", StringComparison.OrdinalIgnoreCase);
/// <summary>True for an event of the test's one job with the given status.</summary>
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);
/// <summary>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.</summary>
private sealed class HeldDocument(byte[] bytes) : MemoryStream(bytes)
{
internal TaskCompletionSource Entered { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously);
internal TaskCompletionSource Release { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously);
/// <summary>Signals the first read, waits for release, then reads normally.</summary>
public override async ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken = default)
{
Entered.TrySetResult();
await Release.Task.WaitAsync(cancellationToken);
return await base.ReadAsync(buffer, cancellationToken);
}
}
}
@@ -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."),
@@ -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<InvalidOperationException>(() => backend.PrintFileAsync(job, Path.Combine(Path.GetTempPath(), "unused-exposure.document"), TimeSpan.FromSeconds(1), CancellationToken.None));
await Assert.ThrowsAsync<PrinterNotExposedException>(() => backend.PrintFileAsync(job, Path.Combine(Path.GetTempPath(), "unused-exposure.document"), TimeSpan.FromSeconds(1), CancellationToken.None));
Assert.False(printer.Printed);
}
@@ -178,7 +178,8 @@ public sealed class InjectedClockTests
/// <summary>
/// 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.
/// </summary>
[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);
}
@@ -112,6 +112,199 @@ public sealed class PrintWorkerOutcomeTests
/// <summary>
/// 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.
/// </summary>
[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<string>();
var active = new List<string?>();
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));
}
/// <summary>
/// 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.
/// </summary>
[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<string>();
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"));
}
/// <summary>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.</summary>
[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<string>();
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));
}
/// <summary>
/// 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.
/// </summary>
[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"));
}
/// <summary>
/// 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
/// <summary>
/// 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.
/// </summary>
[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<string?>();
harness.Options = harness.Options with { ActiveJobChanged = job => active.Add(job?.JobId) };
IOException failure = await Assert.ThrowsAsync<IOException>(() => 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);
}
/// <summary>A lane told that another lane already found the queue empty does not ask the server for work at all.</summary>
[Fact]
public async Task LaneThatMayNotClaimSendsNoClaim()
@@ -41,7 +41,7 @@ public sealed class PrintingSupportTests
/// <summary>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.</summary>
/// <summary>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.</summary>
[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<InvalidOperationException>(() => 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<PrinterNotExposedException>(() => 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);
}
@@ -47,6 +47,7 @@ internal sealed class WorkerHarness : IAsyncDisposable
EventGate = EventGate,
ClaimGate = ClaimGate,
ThrottleDownloadAsync = Unpaced,
IsInHand = _ => false,
CanClaim = () => true,
ReserveDocumentAsync = (_, _) => Task.FromResult<IAsyncDisposable>(new FreeLease()),
AcquireSubmissionAsync = (_, _) => Task.FromResult<IAsyncDisposable>(new FreeLease()),