Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<Engine>.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;
Expand Down
2 changes: 1 addition & 1 deletion Directory.Build.props
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
</PropertyGroup>

<PropertyGroup>
<Version>0.1.0</Version>
<Version>0.1.1</Version>
<Authors>mahach666</Authors>
<Copyright>Copyright (c) 2026 mahach666</Copyright>
<Product>IOScene</Product>
Expand Down
4 changes: 3 additions & 1 deletion docs/contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 3 additions & 0 deletions src/IOScene/IOScene.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@
<IsPackable>true</IsPackable>
<PackageId>IOScene</PackageId>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<!-- dotnet pack compares the public API with the first release of the line: a patch release adds or fixes. -->
<EnablePackageValidation>true</EnablePackageValidation>
<PackageValidationBaselineVersion>0.1.0</PackageValidationBaselineVersion>
</PropertyGroup>

</Project>
42 changes: 31 additions & 11 deletions src/IOScene/SceneJson.cs
Original file line number Diff line number Diff line change
@@ -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;
Expand Down Expand Up @@ -43,12 +44,13 @@ public static class SceneJson
/// options add the rest: null members are omitted; an explicit <c>null</c> is read as a missing member for text
/// (except <see cref="SceneDocument.Kind"/>, which rejects it), lists, objects and nullable members, and makes the
/// serializer throw <see cref="JsonException"/> for a member of any other type, such as a number, an enum, a math
/// value or a date-time; a <c>null</c> inside a list of objects is rejected with
/// <see cref="InvalidDataException"/>; and text is escaped as <see cref="Write(SceneDocument, Stream)"/> escapes
/// it.
/// value or a date-time; a <c>null</c> inside a list of objects, and a scene of another kind or of a newer format,
/// are rejected with <see cref="InvalidDataException"/>, also on a runtime without dynamic code; and text is
/// escaped as <see cref="Write(SceneDocument, Stream)"/> escapes it.
/// </summary>
/// <remarks>
/// 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
/// <see cref="IJsonOnDeserialized.OnDeserialized"/> of a type that implements it runs after them. Two things that
/// <see cref="Write(SceneDocument, Stream)"/> 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.
/// </remarks>
Expand Down Expand Up @@ -150,11 +152,6 @@ private static SceneDocument Checked(Func<SceneDocument?> 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
Expand All @@ -167,22 +164,45 @@ private static void Harden(JsonTypeInfo info)
var lists = new List<JsonPropertyInfo>();
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<object?>).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)
{
if (list.Get!(target) is IEnumerable<object?> 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<object, object?> Unwrapped(Action<object, object?> 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)
{
Expand Down
54 changes: 53 additions & 1 deletion tests/IOScene.Tests/SceneJsonTests.cs
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace IOScene.Tests;

Expand Down Expand Up @@ -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<InvalidDataException>(() => JsonSerializer.Deserialize<SceneDocument>("{\"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<SceneDocument>("{\"Kind\":\"ioviewer\",\"Format\":1}"));
Assert.IsType<InvalidDataException>(rejected is System.Reflection.TargetInvocationException wrapped ? wrapped.InnerException : rejected);
}

private sealed class Holder
Expand Down Expand Up @@ -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<InvalidDataException>(() => JsonSerializer.Deserialize<Holder>("{\"Scene\":{\"Kind\":\"other\",\"Format\":1}}", options));
Assert.Contains("Kind is 'other'", kind.Message);
Assert.Throws<InvalidDataException>(() => JsonSerializer.Deserialize<Holder>("{\"Scene\":{\"Kind\":\"ioscene\",\"Format\":2}}", options));
}

private sealed class CallbackHolder : IJsonOnDeserialized
{
public List<string> 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<CallbackHolder>("{\"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<InvalidDataException>(() => JsonSerializer.Deserialize<CallbackHolder>("{\"Notes\":[null]}", options));
}

private sealed class RequiredHolder
{
[JsonRequired] public List<string> 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<RequiredHolder>("{\"Notes\":null}", options)!.Notes);
Assert.Throws<InvalidDataException>(() => JsonSerializer.Deserialize<RequiredHolder>("{\"Notes\":[\"a\",null]}", options));
Assert.Throws<JsonException>(() => JsonSerializer.Deserialize<RequiredHolder>("{}", options));
}

[Fact]
public void The_options_are_a_copy_that_the_caller_may_change()
{
Expand Down
Loading