diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 726f999..216e116 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -31,3 +31,6 @@ jobs: name: packages-${{ matrix.os }} path: artifacts/*.nupkg if-no-files-found: error + # System.Text.Json calls setters through reflection on a runtime without dynamic code. + - name: Test without dynamic code + run: dotnet test IOScene.slnx -c Release -p:DynamicCodeSupport=false diff --git a/CHANGELOG.md b/CHANGELOG.md index 389cc5f..75b285f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,13 +6,30 @@ and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.htm ## [Unreleased] +## [0.1.1] - 2026-11-13 + ### Fixed +- `SceneJson.CreateOptions()`: a scene of another kind or of a newer format inside a document read with these options + is rejected with `InvalidDataException` also on a runtime without dynamic code; before, it came as a + `TargetInvocationException` around it. `SceneJson.Read` and `SceneJson.Load` threw `InvalidDataException` there + already; it is now the setter's exception itself, as with dynamic code, without the `TargetInvocationException` as + its inner exception. +- `SceneJson.CreateOptions()`: a type read with these options that implements `IJsonOnDeserialized` and has a member + that is a list of objects or strings gets its `OnDeserialized` call again, after the check for null entries; the + options replaced it before. +- `SceneJson.CreateOptions()`: a member that a holder marks required (`[JsonRequired]` or `required`) follows the + rules of the options like any other member, as the documentation of the method says: an explicit `null` is read as + a missing member, and a `null` entry of its list is rejected. 0.1.0 left such members alone. - README and `docs/contract.md`: a package that depends on IOScene references `[0.N.0, 0.N+1.0-0.0)` instead of `[0.N.0, 0.N+1.0-0)`. nuget.org refuses a package whose dependency bound is `0.2.0-0`, because a prerelease label of one part must start with a letter there; `0.2.0-0.0` has two parts and keeps out every preview of 0.2.0 except `0.2.0-0`, which IOScene does not publish. - `docs/keys.md`: the `ifc:` formats are fixed from `IfcIO.Scene` 0.11.1, its first release; nuget.org refused 0.11.0. +### Changed +- `dotnet pack` compares the public API with 0.1.0 (package validation) and fails on a removed or changed member. CI + also runs the tests as a runtime without dynamic code does (`-p:DynamicCodeSupport=false`). + ## [0.1.0] - 2026-11-13 First stable release. The API, the file format (kind `ioscene`, format 1) and the validation codes are those of diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2c1a0ed..de887b3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,6 +68,10 @@ handled before. If ignoring it gives wrong output, it is a break. **Breaking changes** (a 0.N+1 minor release; never after 1.0 without 2.0): rename, retype or remove a member; change units, defaults or the meaning of an existing member; reorder enum values; change a positional record signature. +`dotnet pack` compares the public API with the first release of the line (`PackageValidationBaselineVersion` in +`src/IOScene/IOScene.csproj`, 0.1.0 for the 0.1 line) and fails on a removed or changed member. The commit that +starts a breaking minor removes the baseline; the first release of the new line becomes the next baseline. + **Break procedure.** A breaking minor is tagged only when the pull request of every package that depends on IOScene (the `.Scene` packages and the consumers) is ready against the same preview on a local feed. Then all tags go out in one session, in release order: IOScene, each engine, the consumers. Previews iterate on the local feed; diff --git a/Directory.Build.props b/Directory.Build.props index 164e734..95974cf 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -14,7 +14,7 @@ - 0.1.0 + 0.1.1 mahach666 Copyright (c) 2026 mahach666 IOScene diff --git a/docs/contract.md b/docs/contract.md index f7754c7..86c7cf8 100644 --- a/docs/contract.md +++ b/docs/contract.md @@ -275,7 +275,9 @@ line (nuget.org refuses the shorter bound `-0` in a dependency). From 1.0 the ra a saving, not a cure: text doubles dominate. The cure for size is a new encoding (item 4 of section 5), which is why `Format` is not tied to a breaking package version. - The converters of the math values are attached to the types, so any `System.Text.Json` serialisation of a scene - writes them as arrays, and `Kind` and `Format` are checked whoever reads the scene. The other rules of this section + writes them as arrays, and `Kind` and `Format` are checked whoever reads the scene. With the options of `SceneJson` + a wrong value is an `InvalidDataException` on any runtime; without them, a runtime without dynamic code wraps it in + a `TargetInvocationException`. The other rules of this section (null members omitted, the reader rules, the escaping) belong to `SceneJson`. A document of another kind that holds a scene as a member gets them from `SceneJson.CreateOptions()`, which returns serializer options for the whole document. Such a document lists the elements in the order of the list, not parents first. diff --git a/src/IOScene/IOScene.csproj b/src/IOScene/IOScene.csproj index c122010..edd8bb5 100644 --- a/src/IOScene/IOScene.csproj +++ b/src/IOScene/IOScene.csproj @@ -4,6 +4,9 @@ true IOScene true + + true + 0.1.0 diff --git a/src/IOScene/SceneJson.cs b/src/IOScene/SceneJson.cs index 01243c2..0afba45 100644 --- a/src/IOScene/SceneJson.cs +++ b/src/IOScene/SceneJson.cs @@ -1,4 +1,5 @@ using System.Reflection; +using System.Runtime.ExceptionServices; using System.Text.Encodings.Web; using System.Text.Json; using System.Text.Json.Serialization; @@ -43,12 +44,13 @@ public static class SceneJson /// options add the rest: null members are omitted; an explicit null is read as a missing member for text /// (except , which rejects it), lists, objects and nullable members, and makes the /// serializer throw for a member of any other type, such as a number, an enum, a math - /// value or a date-time; a null inside a list of objects is rejected with - /// ; and text is escaped as escapes - /// it. + /// value or a date-time; a null inside a list of objects, and a scene of another kind or of a newer format, + /// are rejected with , also on a runtime without dynamic code; and text is + /// escaped as escapes it. /// /// - /// The rules apply to every type that is read or written with the options, the holder included. Two things that + /// The rules apply to every type that is read or written with the options, the holder included; the + /// of a type that implements it runs after them. Two things that /// does are not part of them: the elements are written in the order /// of the list, not parents first, and the size of a geometry is not checked. /// @@ -150,11 +152,6 @@ private static SceneDocument Checked(Func read) { throw new InvalidDataException($"Not a readable IOScene document: Kind or Format is missing, or the JSON is damaged. {e.Message}", e); } - catch (TargetInvocationException e) when (e.InnerException is InvalidDataException rejected) - { - // Without dynamic code the serialiser calls the setters of Kind and Format through reflection. - throw new InvalidDataException(rejected.Message, e); - } } // Reading treats an explicit null for a member of a reference type like a missing member, so no member typed as @@ -167,12 +164,20 @@ private static void Harden(JsonTypeInfo info) var lists = new List(); foreach (var property in info.Properties) { - // Required members (Kind, Format) are left alone: their setters reject a wrong value, null included. - if (property.PropertyType.IsValueType || property.IsRequired) continue; + // Kind and Format keep their values, null included: their setters reject a wrong one. A member that a + // holder marks required follows the rules below like any other. + if (info.Type == typeof(SceneDocument) && property.IsRequired) + { + if (property.Set is { } required) property.Set = Unwrapped(required); + continue; + } + if (property.PropertyType.IsValueType) continue; if (property.Set is { } set) property.Set = (target, value) => { if (value is not null) set(target, value); }; if (property.Get is not null && typeof(IEnumerable).IsAssignableFrom(property.PropertyType)) lists.Add(property); } if (lists.Count == 0) return; + // The callback of a type that implements IJsonOnDeserialized, which must still run after the check. + var own = info.OnDeserialized; info.OnDeserialized = target => { foreach (var list in lists) @@ -180,9 +185,24 @@ private static void Harden(JsonTypeInfo info) if (list.Get!(target) is IEnumerable items && items.Contains(null)) throw new InvalidDataException($"Not a readable IOScene document: {list.Name} of {info.Type.Name} holds a null entry."); } + own?.Invoke(target); }; } + // Without dynamic code the serialiser calls a setter through reflection, which wraps the InvalidDataException of + // Kind and Format in a TargetInvocationException; the caller gets the rejection itself. + private static Action Unwrapped(Action set) => (target, value) => + { + try + { + set(target, value); + } + catch (TargetInvocationException e) when (e.InnerException is InvalidDataException rejected) + { + ExceptionDispatchInfo.Capture(rejected).Throw(); + } + }; + // What the writer serialises: the document, checked for the size the reader can take back, with its elements in file order. private static SceneDocument Prepared(SceneDocument document) { diff --git a/tests/IOScene.Tests/SceneJsonTests.cs b/tests/IOScene.Tests/SceneJsonTests.cs index 874e5d2..7608c09 100644 --- a/tests/IOScene.Tests/SceneJsonTests.cs +++ b/tests/IOScene.Tests/SceneJsonTests.cs @@ -1,5 +1,6 @@ using System.Text; using System.Text.Json; +using System.Text.Json.Serialization; namespace IOScene.Tests; @@ -376,7 +377,9 @@ public void Math_values_are_number_arrays_in_any_System_Text_Json_serialisation( string json = JsonSerializer.Serialize(new { Scene = GoldenScenes.NoProperties() }); Assert.StartsWith("{\"Scene\":{\"Kind\":\"ioscene\",\"Format\":1,", json); Assert.Contains("\"Vertices\":[0,0,0,1,0,0,1,1,0,0,1,0]", json); - Assert.Throws(() => JsonSerializer.Deserialize("{\"Kind\":\"ioviewer\",\"Format\":1}")); + // Without the options of SceneJson and without dynamic code, the runtime's reflection call wraps the rejection. + var rejected = Record.Exception(() => JsonSerializer.Deserialize("{\"Kind\":\"ioviewer\",\"Format\":1}")); + Assert.IsType(rejected is System.Reflection.TargetInvocationException wrapped ? wrapped.InnerException : rejected); } private sealed class Holder @@ -419,6 +422,55 @@ public void A_scene_inside_another_document_follows_the_scene_rules_with_the_opt Assert.Equal(SceneJson.Write(holder.Scene), SceneJson.Write(back.Scene)); } + [Fact] + public void A_holder_read_with_the_options_of_SceneJson_gets_InvalidDataException_for_another_kind_or_format() + { + // Without dynamic code the serializer calls the setters of Kind and Format through reflection, which wraps + // their exception; CI runs this test that way too (-p:DynamicCodeSupport=false). + var options = SceneJson.CreateOptions(); + var kind = Assert.Throws(() => JsonSerializer.Deserialize("{\"Scene\":{\"Kind\":\"other\",\"Format\":1}}", options)); + Assert.Contains("Kind is 'other'", kind.Message); + Assert.Throws(() => JsonSerializer.Deserialize("{\"Scene\":{\"Kind\":\"ioscene\",\"Format\":2}}", options)); + } + + private sealed class CallbackHolder : IJsonOnDeserialized + { + public List Notes { get; set; } = []; + public SceneDocument Scene { get; set; } = new(); + [JsonIgnore] public int Calls { get; private set; } + + // Throws another type when it runs before the options have checked the lists for null entries. + public void OnDeserialized() + { + if (Notes.Contains(null!)) throw new InvalidOperationException("OnDeserialized ran before the check for null entries."); + Calls++; + } + } + + [Fact] + public void The_holders_own_IJsonOnDeserialized_still_runs_with_the_options_of_SceneJson() + { + var options = SceneJson.CreateOptions(); + var holder = JsonSerializer.Deserialize("{\"Notes\":[\"a\"],\"Scene\":{\"Kind\":\"ioscene\",\"Format\":1}}", options)!; + Assert.Equal(1, holder.Calls); + // The options still reject a null entry in a list of the holder, before the callback runs. + Assert.Throws(() => JsonSerializer.Deserialize("{\"Notes\":[null]}", options)); + } + + private sealed class RequiredHolder + { + [JsonRequired] public List Notes { get; set; } = ["kept"]; + } + + [Fact] + public void A_member_the_holder_marks_required_follows_the_rules_of_the_options() + { + var options = SceneJson.CreateOptions(); + Assert.Equal(new[] { "kept" }, JsonSerializer.Deserialize("{\"Notes\":null}", options)!.Notes); + Assert.Throws(() => JsonSerializer.Deserialize("{\"Notes\":[\"a\",null]}", options)); + Assert.Throws(() => JsonSerializer.Deserialize("{}", options)); + } + [Fact] public void The_options_are_a_copy_that_the_caller_may_change() {