diff --git a/CHANGELOG.md b/CHANGELOG.md index 78c0b62..f14ae9d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -97,8 +97,10 @@ Core hardening for 2.0. No change to pairing, history or the wire protocol. - A job the server sends in a form the agent cannot use no longer blocks a device. The agent identifies the job and refuses it: history shows RECEIVED and then FAILED with a fixed reason ending "No bytes were submitted", nothing is downloaded or printed, and the next job is taken. This covers a missing or unusable member, a member - given twice in any letter case, and options nested deeper than 64 levels. Only a claim that names no job at all - still stops the device's queue until that job is cancelled on the server. + given twice in any letter case, options nested deeper than 64 levels, and text the agent cannot read (a + surrogate escape without its partner, or bytes that are not UTF-8) in a title, in another member it reads or in + a member name. Only a claim that names no job at all, or whose job identifier is itself unreadable, still stops + the device's queue until that job is cancelled on the server. - Extra fields in a job, including any a submitter adds to its options, are ignored. A job title may be 1,024 characters of any script, and a byte-order mark in front of a server response is accepted. - A job is never printed twice because the server offered it again. One that is still being submitted is left to diff --git a/docs/REALTIME.md b/docs/REALTIME.md index 3054dc7..0c64ea9 100644 --- a/docs/REALTIME.md +++ b/docs/REALTIME.md @@ -74,16 +74,20 @@ relays a submitter's options unchanged. The response itself is parsed to 1,024 levels, so that a job nested too deep to read can still be identified. - **Malformed job.** A job that breaks the contract (a missing or unusable - member, a member the client reads given twice in any letter case, or nesting - deeper than 64 levels) but still names itself with one usable job identifier - is refused, not skipped. The worker records RECEIVED and then FAILED with the - reason and "No bytes were submitted", delivers both events, never downloads - or submits the document, and the lane goes on to the next job. A malformed - replay of a job the journal already knows, in any state, changes nothing and - is logged. + member, a member the client reads given twice in any letter case, nesting + deeper than 64 levels, or text that cannot be read) but still names itself + with one usable job identifier is refused, not skipped. The worker records + RECEIVED and then FAILED with the reason and "No bytes were submitted", + delivers both events, never downloads or submits the document, and the lane + goes on to the next job. A malformed replay of a job the journal already + knows, in any state, changes nothing and is logged. Text that cannot be read + is a surrogate escape without its partner or bytes that are not UTF-8, both + of which the JSON parser accepts. It is refused in a text member the client + reads and in a member name beside the job, in the job, in its options or in + its media selection; inside a field the client does not read it is ignored. - **Claim that cannot be identified.** A claim response that names no single - job (not JSON, no usable identifier, the identifier given twice) cannot be - answered for: the lane stops with an error, the next wake-up claims again, + job (not JSON, no usable identifier, the identifier not readable text or + given twice) cannot be answered for: the lane stops with an error, the next wake-up claims again, and the server offers the same job until it is cancelled there. The one such response a submitter could in principle cause is a job nested deeper than the 1,024 levels the response is parsed to. That depth is derived from the diff --git a/docs/security/threat-model.md b/docs/security/threat-model.md index c2939b7..f000c8f 100644 --- a/docs/security/threat-model.md +++ b/docs/security/threat-model.md @@ -24,13 +24,13 @@ Successful cancellation means Windows accepted the request, not that printed pap A claimed job is untrusted input, and part of it is not even the server's. The options of a job are written by whoever submitted it and relayed by the server unchanged; the rest of the claim (identifiers, title, format, hash, length) is written by the server. The client therefore treats the whole claim as hostile and checks it before anything else handles it. -What is validated and bounded at the claim: the response is at most 2 MiB and is parsed to 1,024 levels of nesting; the job itself may nest to 64 levels counted from the response; job and printer identifiers are 1 to 200 ASCII letters, digits or `-`, `_`, `.`, `:`, so they are safe in a route and a log line (they are never used as file names, for which `:` would not be safe); the title is at most 1,024 code points; format and scale are tokens of at most 32 ASCII letters, digits or underscores; the content hash is 64 hexadecimal digits; the content length is 1 to 2,147,483,647; copies are 1 to 32,767; paper dimensions are complete, positive, at most 2,000 mm and never combined with a media profile. Creation time and status are only displayed and are blanked when missing or over-long. Fields the client does not read are ignored, as the contract requires of unknown fields. Whether a well-formed job may print (effective copies and size policy, the format the queue offers, the selected media still being current) is decided later by the worker, and the document is verified against the claimed length and SHA-256 while it streams. +What is validated and bounded at the claim: the response is at most 2 MiB and is parsed to 1,024 levels of nesting; the job itself may nest to 64 levels counted from the response; job and printer identifiers are 1 to 200 ASCII letters, digits or `-`, `_`, `.`, `:`, so they are safe in a route and a log line (they are never used as file names, for which `:` would not be safe); the title is at most 1,024 code points; format and scale are tokens of at most 32 ASCII letters, digits or underscores; the content hash is 64 hexadecimal digits; the content length is 1 to 2,147,483,647; copies are 1 to 32,767; paper dimensions are complete, positive, at most 2,000 mm and never combined with a media profile. Creation time and status are only displayed and are blanked when missing or over-long. Fields the client does not read are ignored, as the contract requires of unknown fields. Text the client cannot read at all also fails these checks. The JSON parser accepts, as valid JSON, a surrogate escape without its partner (`\ud800` alone, `\udc00` alone, or the two the wrong way round) and bytes that are not UTF-8, and neither can be turned into text. A claim is refused when such text is a text member the client reads, or a member name in any object the client reads members from: the response beside the job, the job, its options or its media selection. Inside a field the client does not read it is ignored with the rest of that field. Whether a well-formed job may print (effective copies and size policy, the format the queue offers, the selected media still being current) is decided later by the worker, and the document is verified against the claimed length and SHA-256 while it streams. -A job that fails these checks but still names itself with one usable identifier is refused, not skipped: the worker records RECEIVED and then FAILED, delivers both, never downloads or submits the document, and goes on to the next job. The reason is fixed text chosen by the client ("The claimed job has no print options. No bytes were submitted."); nothing the server or the submitter supplied is repeated in it, so the reason of a refusal cannot carry text into the journal, the server's history or the companion. The refused job itself is recorded like any other: its title, up to 1,024 code points and otherwise unchecked, is kept in the stand-in, stored in the journal and shown in the companion's history, and its identifiers, format and creation time are kept when they pass the checks above. A malformed replay of a job the journal already knows changes nothing. +A job that fails these checks but still names itself with one usable identifier is refused, not skipped: the worker records RECEIVED and then FAILED, delivers both, never downloads or submits the document, and goes on to the next job. The reason is fixed text chosen by the client ("The claimed job has no print options. No bytes were submitted."); nothing the server or the submitter supplied is repeated in it, so the reason of a refusal cannot carry text into the journal, the server's history or the companion. The refused job itself is recorded like any other: its title, up to 1,024 code points and otherwise unchecked, is kept in the stand-in, stored in the journal and shown in the companion's history, and its identifiers, format and creation time are kept when they pass the checks above. A title, printer identifier, format or creation time that cannot be read is left empty; nothing is substituted for it. A malformed replay of a job the journal already knows changes nothing. The client matches member names without regard to letter case. A job that gives a member the client reads twice (in the job, its options or its media selection, for example `copies` and `Copies`) could therefore make the client act on a value the server did not mean, so such a job is refused as above. Names the client does not read may repeat freely, because nothing is decided from them. -Residual risk: a claim that cannot be identified cannot be refused. A response that is not JSON, is nested beyond 1,024 levels, names no usable job identifier, gives the identifier twice in the contract's spelling, or holds two job members names no single job; the lane stops with a logged error, the server offers the same job again on the next claim, and that device prints nothing further until the job is cancelled on the server. Of these only the nesting depends on a submitter. The parse depth of 1,024 is derived from the server's cap of 2,000 characters on a job's options: the server's JSON library sets no depth limit, the cheapest nesting (an array in an array) costs two characters a level, so about 1,000 levels fit in the cap, and the response, the job and the options object add three. A response nested past 1,024 therefore cannot be produced through the server's options cap as it stands. This closure rests on that cap: if the server raises it, or relays another submitter-controlled member, the depth must be revisited. The cloud queue preview is display only: it requires each entry to name its job and printer once with usable identifiers, tolerates members that are unknown or repeated, and prints nothing. +Residual risk: a claim that cannot be identified cannot be refused. A response that is not JSON, is nested beyond 1,024 levels, names no usable job identifier (missing, malformed, or text that cannot be read), gives the identifier twice in the contract's spelling, or holds two job members names no single job; the lane stops with a logged error, the server offers the same job again on the next claim, and that device prints nothing further until the job is cancelled on the server. Of these only the nesting depends on a submitter. The parse depth of 1,024 is derived from the server's cap of 2,000 characters on a job's options: the server's JSON library sets no depth limit, the cheapest nesting (an array in an array) costs two characters a level, so about 1,000 levels fit in the cap, and the response, the job and the options object add three. A response nested past 1,024 therefore cannot be produced through the server's options cap as it stands. This closure rests on that cap: if the server raises it, or relays another submitter-controlled member, the depth must be revisited. The cloud queue preview is display only: it requires each entry to name its job and printer once with usable identifiers, tolerates members that are unknown or repeated, and prints nothing. ## Compatibility check diff --git a/src/Qqq.PrintAgent.Core/Printing/PrintJobContract.cs b/src/Qqq.PrintAgent.Core/Printing/PrintJobContract.cs index 6401ee4..a60823d 100644 --- a/src/Qqq.PrintAgent.Core/Printing/PrintJobContract.cs +++ b/src/Qqq.PrintAgent.Core/Printing/PrintJobContract.cs @@ -45,7 +45,11 @@ internal static class PrintJobContract /// usable identifier the failure carries a stand-in for it, so the worker can answer for the job instead of being /// offered it again forever; only a response that names no job the agent can answer for throws without one. A job /// nested deeper than is such an identified failure; a response nested - /// deeper than is not JSON to the parser and names nothing. + /// deeper than is not JSON to the parser and names nothing. Text the JSON + /// library cannot read (an unpaired surrogate escape, bytes that are not UTF-8) breaks the contract like any other + /// fault, and never stops the job from being identified: in a member name beside the job or where the agent reads + /// the job's members, and in a text member the agent reads, where the stand-in then leaves that member empty. A + /// response that offers no job is not looked through for such names; there is nothing in it to refuse. /// internal static PrintJob? ReadClaim(ReadOnlyMemory body) { @@ -64,6 +68,8 @@ internal static class PrintJobContract // them, so every refusal below can name the job it is about // ///////////////////////////////////////////////////////////////////////// PrintJob? named = StandIn(Text(element, "jobId"), Text(element, "printerId"), Text(element, "title"), Text(element, "format"), Text(element, "createdAt")); + if(ProtocolJson.HasUnreadableName(document.RootElement) || HasUnreadableName(element)) + { throw Violation("The claim has a member name that is not readable text.", named); } if(ProtocolJson.NestsDeeperThan(element, ProtocolJson.ReaderDepth - 1)) { throw Violation("The claimed job is nested deeper than the agent reads.", named); } if(RepeatsReadMember(element)) @@ -130,6 +136,24 @@ internal static class PrintJobContract + /// + /// True when a claimed job has a member whose name is not readable text where the agent reads members: in the job + /// itself, in its options or in its media selection. The JSON library skips some such names and fails on others, + /// so without this check whether the job printed would depend on how the name was spelled. Names deeper inside a + /// field the agent does not read are not looked at, like everything else in such a field. + /// + private static bool HasUnreadableName(JsonElement job) + { + if(ProtocolJson.HasUnreadableName(job)) + { return true; } + if(ProtocolJson.Members(job, "options") is not [{ ValueKind: JsonValueKind.Object } options]) + { return false; } + return ProtocolJson.HasUnreadableName(options) + || (ProtocolJson.Members(options, "mediaProfile") is [{ ValueKind: JsonValueKind.Object } media] && ProtocolJson.HasUnreadableName(media)); + } + + + /// /// Says what is wrong with a claimed job, or null when its shape is acceptable: safe identifiers, a bounded title, a /// format token, a SHA-256 hash, a positive length and usable options. @@ -214,9 +238,9 @@ internal static class PrintJobContract - /// Reads the text member the contract names, or null when it is missing, not text, or given more than once so that it is not clear which value is meant. + /// Reads the text member the contract names, or null when it is missing, not text, not readable text, or given more than once so that it is not clear which value is meant. private static string? Text(JsonElement element, string name) - => ProtocolJson.Members(element, name) is [{ ValueKind: JsonValueKind.String } member] ? member.GetString() : null; + => ProtocolJson.Members(element, name) is [{ ValueKind: JsonValueKind.String } member] ? ProtocolJson.Text(member) : null; diff --git a/src/Qqq.PrintAgent.Core/Printing/ProtocolJson.cs b/src/Qqq.PrintAgent.Core/Printing/ProtocolJson.cs index 67a8f6a..0f44ec7 100644 --- a/src/Qqq.PrintAgent.Core/Printing/ProtocolJson.cs +++ b/src/Qqq.PrintAgent.Core/Printing/ProtocolJson.cs @@ -108,14 +108,15 @@ internal static class ProtocolJson /// /// True when the object spells one of the given member names more than once. Names are compared ignoring case because /// that is how the deserializer matches them: "copies" and "Copies" are the same member to it, so a job carrying - /// both could print a different number of copies than the server meant. A name outside the list may repeat freely. + /// both could print a different number of copies than the server meant. A name outside the list may repeat freely, + /// and so may a name that is not readable text, which is none of the listed ones. /// internal static bool RepeatsMember(JsonElement value, IReadOnlyList names) { var seen = new HashSet(StringComparer.OrdinalIgnoreCase); foreach(JsonProperty property in value.EnumerateObject()) { - if(names.Contains(property.Name, StringComparer.OrdinalIgnoreCase) && !seen.Add(property.Name)) + if(Name(property) is { } name && names.Contains(name, StringComparer.OrdinalIgnoreCase) && !seen.Add(name)) { return true; } } return false; @@ -127,14 +128,61 @@ internal static class ProtocolJson /// Finds the candidates for the member the contract names: every member spelled exactly as the contract spells it, /// because that is the one the server itself reads, or, when there is none, every member that matches ignoring /// case, as the deserializer would take it. One candidate is the member, none means it is absent, and more than one - /// means the message does not say which value it means. + /// means the message does not say which value it means. A member whose name is not readable text is never a + /// candidate, and never stops the others from being found. /// internal static JsonElement[] Members(JsonElement value, string name) { - JsonElement[] exact = [.. value.EnumerateObject().Where(property => property.NameEquals(name)).Select(property => property.Value)]; + JsonElement[] exact = [.. value.EnumerateObject().Where(property => IsNamed(property, name)).Select(property => property.Value)]; return exact.Length != 0 ? exact - : [.. value.EnumerateObject().Where(property => string.Equals(property.Name, name, StringComparison.OrdinalIgnoreCase)).Select(property => property.Value)]; + : [.. value.EnumerateObject().Where(property => string.Equals(Name(property), name, StringComparison.OrdinalIgnoreCase)).Select(property => property.Value)]; + } + + + + /// True when the object has a member whose name is not readable text, as judges it. + internal static bool HasUnreadableName(JsonElement value) => value.EnumerateObject().Any(property => Name(property) is null); + + + + /// + /// The member's name, or null when it is not readable text. The parser accepts as valid JSON a name it cannot turn + /// into text: one with a surrogate escape that has no partner (a lone \ud800 or \udc00, or the two + /// the wrong way round) or with bytes that are not UTF-8. Asking for such a name throws, and not as a JSON failure. + /// The readers of a job ask here instead, because a job must be read far enough to learn which job it is before + /// it can be refused. The judgement is the JSON library's own; nothing here decides what readable means. A thrown + /// exception is the only way the library gives it, so each such name costs one each time it is asked for; the + /// 2 MiB limit on a response bounds how many there can be. + /// + internal static string? Name(JsonProperty property) + { + try + { return property.Name; } + catch(InvalidOperationException) + { return null; } + } + + + + /// The text of a JSON string, or null when it is not readable text, as describes. The caller has checked that the value is a string. + internal static string? Text(JsonElement value) + { + try + { return value.GetString(); } + catch(InvalidOperationException) + { return null; } + } + + + + /// True when the member is spelled exactly as given. A name that is not readable text is spelled as nothing. + private static bool IsNamed(JsonProperty property, string name) + { + try + { return property.NameEquals(name); } + catch(InvalidOperationException) + { return false; } } diff --git a/tests/Qqq.PrintAgent.Core.Tests/ClaimUnreadableTextTests.cs b/tests/Qqq.PrintAgent.Core.Tests/ClaimUnreadableTextTests.cs new file mode 100644 index 0000000..34ea843 --- /dev/null +++ b/tests/Qqq.PrintAgent.Core.Tests/ClaimUnreadableTextTests.cs @@ -0,0 +1,345 @@ +/* + * Copyright (c) 2026 James Maes + * SPDX-License-Identifier: MIT + */ + +using System.Text; +using System.Text.Json; +using Qqq.PrintAgent.Core.Printing; + +namespace Qqq.PrintAgent.Core.Tests; + +/// +/// The JSON parser accepts, as valid JSON, text it cannot afterwards read: a surrogate escape with no partner, and +/// bytes that are not UTF-8. A claim carrying such text where the agent reads used to end in a failure that named no +/// job, so the job was neither refused nor answered and the server offered it again forever. These tests put every +/// form of such text in every place a claim can carry it and require one of three outcomes and nothing else: the job +/// is refused and still identified, the text is in a field the agent does not read and the job is claimed as if it +/// were not there, or the job's own identifier is the unreadable text and the claim names no job. Then they run the +/// refusals through the worker, which must report the job once and go on to the job behind it. Every body is built +/// from bytes, because several of them are not text. +/// +public sealed class ClaimUnreadableTextTests +{ + private const string NameRefusal = "The claim has a member name that is not readable text."; + private const string FieldRefusal = "The claimed job does not have the expected fields."; + private const string Marker = ""; + private const string ValidClaim = """{"job":{MEMBERS,"options":{OPTIONS}}}"""; + private const string ValidMembers = """ + "jobId":"job-1","printerId":"printer1","title":"Synthetic","format":"ZPL","contentSha256":"HASH","contentLength":3,"createdAt":"2026-01-01T00:00:00Z","status":"CLAIMED" + """; + private const string ValidOptions = """ + "copies":1,"scale":"ACTUAL_SIZE" + """; + + private static readonly string Hash = new('a', 64); + private static readonly PrintJob Valid = new("job-1", "printer1", "Synthetic", "ZPL", Hash, 3, new PrintOptions(), "2026-01-01T00:00:00Z", "CLAIMED"); + private static readonly PrintJob StandIn = Valid with { ContentSha256 = "", ContentLength = 0 }; + + + + /// + /// Each form of text the parser accepts and cannot read, as the bytes that go into a claim. The first three are + /// surrogate escapes, six ASCII characters for each surrogate, beginning with a backslash; the last two are bytes + /// that are not UTF-8, the second of them a surrogate written directly as three bytes. + /// + private static readonly Dictionary Forms = new(StringComparer.Ordinal) + { + ["lone-high-surrogate"] = Encoding.ASCII.GetBytes("""\ud800"""), + ["lone-low-surrogate"] = Encoding.ASCII.GetBytes("""\udc00"""), + ["reversed-pair"] = Encoding.ASCII.GetBytes("""\udc00\ud800"""), + ["byte-that-is-not-utf-8"] = [0xFF], + ["surrogate-written-as-bytes"] = [0xED, 0xA0, 0x80], + }; + + + + /// + /// Each place where unreadable text makes the agent refuse the job: the claim, with the marker where the text goes, + /// the reason, and the stand-in the refusal must carry. In a body MEMBERS is the valid job's members without its + /// options, OPTIONS the valid options and HASH a well-formed SHA-256. + /// + private static readonly Dictionary Refused = new(StringComparer.Ordinal) + { + ["name-beside-the-job"] = ("""{"":1,"job":{MEMBERS,"options":{OPTIONS}}}""", NameRefusal, StandIn), + ["name-after-the-job"] = ("""{"job":{MEMBERS,"options":{OPTIONS}},"":1}""", NameRefusal, StandIn), + ["name-in-the-job"] = ("""{"job":{"":1,MEMBERS,"options":{OPTIONS}}}""", NameRefusal, StandIn), + ["name-in-the-options"] = ("""{"job":{MEMBERS,"options":{"":1,OPTIONS}}}""", NameRefusal, StandIn), + ["name-in-the-media-selection"] = ("""{"job":{MEMBERS,"options":{OPTIONS,"mediaProfile":{"":1,"id":"default","revision":"HASH"}}}}""", NameRefusal, StandIn), + ["title"] = (InPlaceOf("Synthetic"), FieldRefusal, StandIn with { Title = "" }), + ["printer-identifier"] = (InPlaceOf("printer1"), FieldRefusal, StandIn with { PrinterId = "" }), + ["format"] = (InPlaceOf("ZPL"), FieldRefusal, StandIn with { Format = "" }), + ["creation-time"] = (InPlaceOf("2026-01-01T00:00:00Z"), FieldRefusal, StandIn with { CreatedAt = "" }), + ["content-hash"] = (InPlaceOf("HASH"), FieldRefusal, StandIn), + ["status"] = (InPlaceOf("CLAIMED"), FieldRefusal, StandIn), + ["scale"] = (InPlaceOf("ACTUAL_SIZE"), FieldRefusal, StandIn), + ["media-identifier"] = ("""{"job":{MEMBERS,"options":{OPTIONS,"mediaProfile":{"id":"","revision":"HASH"}}}}""", FieldRefusal, StandIn), + ["media-revision"] = ("""{"job":{MEMBERS,"options":{OPTIONS,"mediaProfile":{"id":"default","revision":""}}}}""", FieldRefusal, StandIn), + }; + + + + /// Each place where unreadable text is in a field the agent does not read, so the job is claimed as if the field were not there. + private static readonly Dictionary Ignored = new(StringComparer.Ordinal) + { + ["value-beside-the-job"] = """{"note":"","job":{MEMBERS,"options":{OPTIONS}}}""", + ["value-of-an-unknown-job-member"] = """{"job":{"note":"",MEMBERS,"options":{OPTIONS}}}""", + ["value-of-an-unknown-option"] = """{"job":{MEMBERS,"options":{OPTIONS,"finishing":""}}}""", + ["name-inside-an-unknown-option"] = """{"job":{MEMBERS,"options":{OPTIONS,"finishing":{"":1}}}}""", + ["name-inside-an-unknown-job-member"] = """{"job":{"relayed":[{"":""}],MEMBERS,"options":{OPTIONS}}}""", + }; + + + + /// The cross product the refusal theories run: every place a refusal is expected in, with every form of unreadable text. + public static TheoryData RefusedPlacesAndForms() => Cross(Refused.Keys); + + + + /// The cross product the acceptance theory runs: every place the agent does not read, with every form of unreadable text. + public static TheoryData IgnoredPlacesAndForms() => Cross(Ignored.Keys); + + + + /// Every form of unreadable text, for a theory about one place. + public static TheoryData EveryForm() => [.. Forms.Keys]; + + + + /// + /// What the rest of this class stands on: each form is valid JSON to the parser, as a string and as a member name, + /// and asking for it as text fails, and not with the JSON failure the readers catch. If a later JSON library reads + /// such text leniently this fails first and says the rule needs another look. + /// + [Theory] + [MemberData(nameof(EveryForm))] + public void ParserAcceptsEachFormAndCannotReadIt(string form) + { + using var document = JsonDocument.Parse(Bytes("""{"":""}""", form)); + JsonProperty member = Assert.Single(document.RootElement.EnumerateObject()); + Assert.Equal(JsonValueKind.String, member.Value.ValueKind); + Assert.Throws(() => member.Name); + Assert.Throws(() => member.Value.GetString()); + Assert.Null(ProtocolJson.Name(member)); + Assert.Null(ProtocolJson.Text(member.Value)); + Assert.True(ProtocolJson.HasUnreadableName(document.RootElement)); + } + + + + /// + /// The escapes are the characters their names say, a backslash and all, so nothing that rewrites escapes on the way + /// into this file can turn a row into readable text without this failing. Text that can be read is still read: a + /// surrogate pair the right way round, written as escapes, is a name and a value like any other. + /// + [Fact] + public void SurrogateFormsAreEscapesAndAProperPairIsStillRead() + { + Assert.Equal(new byte[] { 0x5C, 0x75, 0x64, 0x38, 0x30, 0x30 }, Forms["lone-high-surrogate"]); + Assert.Equal(new byte[] { 0x5C, 0x75, 0x64, 0x63, 0x30, 0x30 }, Forms["lone-low-surrogate"]); + Assert.Equal(new byte[] { 0x5C, 0x75, 0x64, 0x63, 0x30, 0x30, 0x5C, 0x75, 0x64, 0x38, 0x30, 0x30 }, Forms["reversed-pair"]); + + byte[] pair = [.. Forms["lone-high-surrogate"], .. Forms["lone-low-surrogate"]]; + byte[] body = [.. "{\""u8, .. pair, .. "\":\""u8, .. pair, .. "\"}"u8]; + using var document = JsonDocument.Parse(body); + JsonProperty member = Assert.Single(document.RootElement.EnumerateObject()); + string expected = char.ConvertFromUtf32(0x10000); + Assert.Equal(expected, ProtocolJson.Name(member)); + Assert.Equal(expected, ProtocolJson.Text(member.Value)); + Assert.False(ProtocolJson.HasUnreadableName(document.RootElement)); + } + + + + /// + /// A claim that names its job and carries unreadable text where the agent reads is one protocol violation with a + /// fixed reason, and it carries the stand-in: the job's identifier, and every display fact that could be read. A + /// member name is refused by the agent's own rule, wherever the agent reads members (beside the job, in it, in its + /// options, in its media selection). A text member is refused because the job cannot be read into its fields, and + /// the stand-in leaves that one member empty; nothing unreadable is carried anywhere. + /// + [Theory] + [MemberData(nameof(RefusedPlacesAndForms))] + public async Task UnreadableTextWhereTheAgentReadsIsRefusedAndTheJobIsStillIdentified(string place, string form) + { + (string claim, string reason, PrintJob standIn) = Refused[place]; + using var server = new FakePrintServer(); + server.OfferBytes(Bytes(claim, form)); + using PrintApiClient api = FakeSessionClient.ApiOver(server); + PrintingProtocolException violation = await Assert.ThrowsAsync(() => api.ClaimAsync(CancellationToken.None)); + Assert.Equal(reason, violation.Message); + Assert.Equal(standIn, violation.RejectedJob); + } + + + + /// + /// The worker's side of every refusal above. The job is refused exactly once: received, then FAILED with the fixed + /// reason and the fact that nothing was submitted, both delivered, never downloaded and never handed to a printer. + /// The pass counts as work done, so the lane claims again and prints the job behind it, and the pass after that + /// finds the queue empty. Before the fix the first pass threw a failure that named no job and the lane stopped + /// there, with the job behind it never claimed. + /// + [Theory] + [MemberData(nameof(RefusedPlacesAndForms))] + public async Task WorkerRefusesTheJobOnceAndGoesOnToTheJobBehindIt(string place, string form) + { + (string claim, string reason, PrintJob standIn) = Refused[place]; + byte[] document = [1, 2, 3]; + await using var harness = new WorkerHarness(); + (FakePrintServer server, RecordingJournal journal, FakePrinterBackend printer) = (harness.Server, harness.Journal, harness.Printer); + server.OfferBytes(Bytes(claim, form)).Offer(FakePrintServer.Job(document, "job-2"), document); + + Assert.True(await harness.RunOnceAsync()); + Assert.Equal(new[] { "RECEIVED", "FAILED" }, journal.StatesOf("job-1"), StringComparer.Ordinal); + Assert.Equal(reason + " No bytes were submitted.", journal.Last("job-1").Message); + Assert.Equal(new[] { ("job-1", "RECEIVED"), ("job-1", "FAILED") }, server.Events.Select(entry => (entry.JobId, entry.Event.Status))); + Assert.Empty(journal.Pending()); + Assert.Equal(standIn, journal.Jobs["job-1"].Job); + Assert.Equal(0, server.Downloads); + Assert.Equal(0, printer.Submissions); + + Assert.True(await harness.RunOnceAsync()); + Assert.Equal("SPOOLED", journal.GetState("job-2")); + Assert.Equal(1, server.Downloads); + Assert.Equal(1, printer.Submissions); + Assert.False(await harness.RunOnceAsync()); + Assert.Equal(3, server.Claims); + Assert.Equal(new[] { "RECEIVED", "FAILED" }, journal.StatesOf("job-1"), StringComparer.Ordinal); + Assert.Equal(2, server.Events.Count(entry => string.Equals(entry.JobId, "job-1", StringComparison.Ordinal))); + Assert.Equal(new[] { "job-1: RECEIVED", "job-1: FAILED" }, harness.Log.Where(line => line.Contains("job-1", StringComparison.Ordinal)), StringComparer.Ordinal); + } + + + + /// + /// Unreadable text in a field the agent does not read changes nothing, like anything else in such a field: the + /// value of an unknown member beside the job, in the job or in its options, and names and values inside an unknown + /// member. The job is claimed exactly as the same claim without that field would be. + /// + [Theory] + [MemberData(nameof(IgnoredPlacesAndForms))] + public async Task UnreadableTextInAFieldTheAgentDoesNotReadIsIgnored(string place, string form) + { + using var server = new FakePrintServer(); + server.OfferBytes(Bytes(Ignored[place], form)); + using PrintApiClient api = FakeSessionClient.ApiOver(server); + Assert.Equal(Valid, await api.ClaimAsync(CancellationToken.None)); + } + + + + /// + /// A response that offers no job has nothing in it to refuse, so a member name that cannot be read beside a null + /// job, or in a response with no job member at all, is passed over and the claim is empty. It used to throw. + /// + [Theory] + [MemberData(nameof(EveryForm))] + public async Task UnreadableNameInAResponseThatOffersNoJobIsAnEmptyClaim(string form) + { + using var server = new FakePrintServer(); + server.OfferBytes(Bytes("""{"":1,"job":null}""", form)).OfferBytes(Bytes("""{"job":null,"":1}""", form)).OfferBytes(Bytes("""{"":1}""", form)); + using PrintApiClient api = FakeSessionClient.ApiOver(server); + Assert.Null(await api.ClaimAsync(CancellationToken.None)); + Assert.Null(await api.ClaimAsync(CancellationToken.None)); + Assert.Null(await api.ClaimAsync(CancellationToken.None)); + Assert.Equal(3, server.Claims); + } + + + + /// + /// The one case that stays unanswered, and it is the documented one: when the job's own identifier is the text that + /// cannot be read, the claim names no job. The violation carries no stand-in and reaches the caller, nothing is + /// recorded, reported, downloaded or printed, and the lane stops, as it does for any claim that names no job. It + /// is the protocol violation, not the JSON library's own failure. + /// + [Theory] + [MemberData(nameof(EveryForm))] + public async Task UnreadableJobIdentifierNamesNoJobAndTheViolationReachesTheCaller(string form) + { + await using var harness = new WorkerHarness(); + (FakePrintServer server, RecordingJournal journal, FakePrinterBackend printer) = (harness.Server, harness.Journal, harness.Printer); + server.OfferBytes(Bytes(InPlaceOf("job-1"), form)); + PrintingProtocolException violation = await Assert.ThrowsAsync(() => harness.RunOnceAsync()); + Assert.Equal(FieldRefusal, violation.Message); + Assert.Null(violation.RejectedJob); + Assert.Empty(journal.Jobs); + Assert.Empty(journal.Pending()); + Assert.Empty(server.Events); + Assert.Equal(0, server.Downloads); + Assert.Equal(0, printer.Submissions); + } + + + + /// + /// The queued-job list is only displayed, and it goes through the same member lookups, so they must not fail there + /// either. A member name that cannot be read beside the list is passed over and the list is shown. Inside an entry + /// the list keeps the behaviour it had: the JSON library skips a name that is not UTF-8, so the entry is shown, and + /// fails on an unpaired surrogate escape and on unreadable text in a member it reads, so the list is refused as a + /// protocol violation. None of these is the JSON library's own failure any more. + /// + [Theory] + [MemberData(nameof(EveryForm))] + public void QueuedListWithUnreadableTextIsShownOrRefusedAsAProtocolViolation(string form) + { + bool escape = Forms[form][0] == 0x5C; + Assert.Equal("queued-1", Assert.Single(PrintJobContract.ReadQueued(Bytes("""{"":1,"jobs":[{"jobId":"queued-1","printerId":"printer1"}]}""", form))).JobId); + Assert.Equal("queued-1", Assert.Single(PrintJobContract.ReadQueued(Bytes("""{"JOBS":[{"jobId":"queued-1","printerId":"printer1"}],"":1}""", form))).JobId); + byte[] nameInEntry = Bytes("""{"jobs":[{"":1,"jobId":"queued-1","printerId":"printer1"}]}""", form); + if(escape) + { Assert.Equal("The queued job does not have the expected fields.", Assert.Throws(() => PrintJobContract.ReadQueued(nameInEntry)).Message); } + else + { Assert.Equal("queued-1", Assert.Single(PrintJobContract.ReadQueued(nameInEntry)).JobId); } + byte[] title = Bytes("""{"jobs":[{"jobId":"queued-1","printerId":"printer1","title":""}]}""", form); + Assert.Equal("The queued job does not have the expected fields.", Assert.Throws(() => PrintJobContract.ReadQueued(title)).Message); + } + + + + /// The valid claim with the marker in place of one text value, which must occur in it exactly once, so the unreadable text becomes the whole of that member. + private static string InPlaceOf(string value) + { + string quoted = '"' + value + '"'; + string claim = Expand(ValidClaim); + Assert.Equal(2, claim.Split(quoted).Length); + return claim.Replace(quoted, '"' + Marker + '"', StringComparison.Ordinal); + } + + + + /// Fills a body with the valid job: MEMBERS is its members without its options, OPTIONS its options. HASH is left for . + private static string Expand(string body) + => body.Replace("MEMBERS", ValidMembers, StringComparison.Ordinal).Replace("OPTIONS", ValidOptions, StringComparison.Ordinal); + + + + /// The body as bytes: the text as UTF-8, filled with the valid job and a well-formed hash, with the form's bytes at every marker, of which there must be at least one. + private static byte[] Bytes(string body, string form) + { + string[] parts = Expand(body).Replace("HASH", Hash, StringComparison.Ordinal).Split(Marker); + Assert.True(parts.Length > 1, "The body has no place for the unreadable text."); + var bytes = new List(Encoding.UTF8.GetBytes(parts[0])); + foreach(string part in parts.Skip(1)) + { + bytes.AddRange(Forms[form]); + bytes.AddRange(Encoding.UTF8.GetBytes(part)); + } + return [.. bytes]; + } + + + + /// Every given place with every form. + private static TheoryData Cross(IEnumerable places) + { + var rows = new TheoryData(); + foreach(string place in places) + { + foreach(string form in Forms.Keys) + { rows.Add(place, form); } + } + return rows; + } +} diff --git a/tests/Qqq.PrintAgent.Core.Tests/WorkerFakes.cs b/tests/Qqq.PrintAgent.Core.Tests/WorkerFakes.cs index 1542772..f03ba26 100644 --- a/tests/Qqq.PrintAgent.Core.Tests/WorkerFakes.cs +++ b/tests/Qqq.PrintAgent.Core.Tests/WorkerFakes.cs @@ -4,6 +4,7 @@ */ using System.Net; +using System.Net.Http.Headers; using System.Security.Cryptography; using System.Text; using System.Text.Json; @@ -19,7 +20,7 @@ namespace Qqq.PrintAgent.Core.Tests; /// internal sealed class FakePrintServer : HttpMessageHandler { - private readonly Queue _claims = new(); + private readonly Queue _claims = new(); @@ -74,7 +75,12 @@ internal sealed class FakePrintServer : HttpMessageHandler /// Answers the next claim with exactly this body, for claims a well-behaved server would never send. - internal FakePrintServer OfferRaw(string body) + internal FakePrintServer OfferRaw(string body) => OfferBytes(Encoding.UTF8.GetBytes(body)); + + + + /// Answers the next claim with exactly these bytes, for a body that is not text at all: one holding bytes that are not UTF-8. + internal FakePrintServer OfferBytes(byte[] body) { _claims.Enqueue(body); return this; @@ -108,20 +114,25 @@ internal sealed class FakePrintServer : HttpMessageHandler { case "claim": Claims++; - return Json(_claims.Count > 0 ? _claims.Dequeue() : """{"job":null}"""); + return Json(_claims.Count > 0 ? _claims.Dequeue() : """{"job":null}"""u8.ToArray()); case "content": Downloads++; return new HttpResponseMessage(HttpStatusCode.OK) { Content = new ByteArrayContent(Document) }; default: Unexpected.Add(path); - return Json("{}"); + return Json("{}"u8.ToArray()); } } - /// A 200 JSON response. - private static HttpResponseMessage Json(string body) => new(HttpStatusCode.OK) { Content = new StringContent(body, Encoding.UTF8, "application/json") }; + /// A 200 JSON response with exactly these bytes as its body. + private static HttpResponseMessage Json(byte[] body) + { + var content = new ByteArrayContent(body); + content.Headers.ContentType = new MediaTypeHeaderValue("application/json") { CharSet = "utf-8" }; + return new HttpResponseMessage(HttpStatusCode.OK) { Content = content }; + } }