stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

save progress

Browse Source
This commit is contained in:
StellaOps Bot
2026-01-03 11:02:24 +02:00
parent ca578801fd
commit 83c37243e0
446 changed files with 22798 additions and 4031 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
src/__Libraries/StellaOps.Canonical.Json/CanonJson.cs
View File

@@ -20,7 +20,14 @@ namespace StellaOps.Canonical.Json;
/// </remarks>
public static class CanonJson
{
private static readonly JsonWriterOptions CanonWriterOptions = new()
private static readonly JsonSerializerOptions DefaultSerializerOptions = new()
{
WriteIndented = false,
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
};
private static readonly JsonWriterOptions DefaultWriterOptions = new()
{
Indented = false,
Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
@@ -62,16 +69,11 @@ public static class CanonJson
/// <returns>UTF-8 encoded canonical JSON bytes.</returns>
public static byte[] Canonicalize<T>(T obj)
{
var json = JsonSerializer.SerializeToUtf8Bytes(obj, new JsonSerializerOptions
{
WriteIndented = false,
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
});
var json = JsonSerializer.SerializeToUtf8Bytes(obj, DefaultSerializerOptions);
using var doc = JsonDocument.Parse(json);
using var ms = new MemoryStream();
using var writer = new Utf8JsonWriter(ms, CanonWriterOptions);
using var writer = new Utf8JsonWriter(ms, DefaultWriterOptions);
WriteElementSorted(doc.RootElement, writer);
writer.Flush();
@@ -92,7 +94,7 @@ public static class CanonJson
using var doc = JsonDocument.Parse(json);
using var ms = new MemoryStream();
using var writer = new Utf8JsonWriter(ms, CanonWriterOptions);
using var writer = new Utf8JsonWriter(ms, CreateWriterOptions(options));
WriteElementSorted(doc.RootElement, writer);
writer.Flush();
@@ -107,15 +109,50 @@ public static class CanonJson
/// <returns>UTF-8 encoded canonical JSON bytes.</returns>
public static byte[] CanonicalizeParsedJson(ReadOnlySpan<byte> jsonBytes)
{
using var doc = JsonDocument.Parse(jsonBytes.ToArray());
var reader = new Utf8JsonReader(jsonBytes, isFinalBlock: true, state: default);
using var doc = JsonDocument.ParseValue(ref reader);
using var ms = new MemoryStream();
using var writer = new Utf8JsonWriter(ms, CanonWriterOptions);
using var writer = new Utf8JsonWriter(ms, DefaultWriterOptions);
WriteElementSorted(doc.RootElement, writer);
writer.Flush();
return ms.ToArray();
}
/// <summary>
/// Canonicalizes raw JSON bytes using a custom encoder for output.
/// </summary>
/// <param name="jsonBytes">UTF-8 encoded JSON bytes.</param>
/// <param name="encoder">Encoder to use for output escaping.</param>
/// <returns>UTF-8 encoded canonical JSON bytes.</returns>
public static byte[] CanonicalizeParsedJson(ReadOnlySpan<byte> jsonBytes, JavaScriptEncoder encoder)
{
ArgumentNullException.ThrowIfNull(encoder);
var reader = new Utf8JsonReader(jsonBytes, isFinalBlock: true, state: default);
using var doc = JsonDocument.ParseValue(ref reader);
using var ms = new MemoryStream();
using var writer = new Utf8JsonWriter(ms, new JsonWriterOptions
{
Indented = false,
Encoder = encoder
});
WriteElementSorted(doc.RootElement, writer);
writer.Flush();
return ms.ToArray();
}
private static JsonWriterOptions CreateWriterOptions(JsonSerializerOptions? options)
{
var encoder = options?.Encoder ?? DefaultWriterOptions.Encoder;
return new JsonWriterOptions
{
Indented = false,
Encoder = encoder
};
}
private static void WriteElementSorted(JsonElement el, Utf8JsonWriter w)
{
switch (el.ValueKind)
@@ -198,16 +235,11 @@ public static class CanonJson
{
ArgumentException.ThrowIfNullOrWhiteSpace(version);
var json = JsonSerializer.SerializeToUtf8Bytes(obj, new JsonSerializerOptions
{
WriteIndented = false,
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
});
var json = JsonSerializer.SerializeToUtf8Bytes(obj, DefaultSerializerOptions);
using var doc = JsonDocument.Parse(json);
using var ms = new MemoryStream();
using var writer = new Utf8JsonWriter(ms, CanonWriterOptions);
using var writer = new Utf8JsonWriter(ms, DefaultWriterOptions);
WriteElementVersioned(doc.RootElement, writer, version);
writer.Flush();
@@ -230,7 +262,7 @@ public static class CanonJson
using var doc = JsonDocument.Parse(json);
using var ms = new MemoryStream();
using var writer = new Utf8JsonWriter(ms, CanonWriterOptions);
using var writer = new Utf8JsonWriter(ms, CreateWriterOptions(options));
WriteElementVersioned(doc.RootElement, writer, version);
writer.Flush();
@@ -249,6 +281,11 @@ public static class CanonJson
// Write remaining properties sorted
foreach (var prop in el.EnumerateObject().OrderBy(p => p.Name, StringComparer.Ordinal))
{
if (string.Equals(prop.Name, CanonVersion.VersionFieldName, StringComparison.Ordinal))
{
continue;
}
w.WritePropertyName(prop.Name);
WriteElementSorted(prop.Value, w);
}

12
src/__Libraries/StellaOps.Canonical.Json/README.md
View File

@@ -12,6 +12,7 @@ This library provides canonical JSON serialization that produces bit-identical o
- **No Whitespace**: Compact output with no formatting variations
- **Consistent Hashing**: SHA-256 hashes are always lowercase hex
- **Cross-Platform**: Same output across Windows, Linux, containers
- **Stable Defaults**: Default serialization uses camelCase naming and UnsafeRelaxed JSON escaping (override with custom options)
## Usage
@@ -51,6 +52,12 @@ byte[] canonical = CanonJson.CanonicalizeParsedJson(rawJson);
// Result: {"a":2,"z":1}
```
If you need stricter escaping rules for raw JSON, pass a custom encoder:
```csharp
byte[] canonical = CanonJson.CanonicalizeParsedJson(rawJson, JavaScriptEncoder.Default);
```
### Custom Serialization Options
```csharp
@@ -62,6 +69,10 @@ var options = new JsonSerializerOptions
byte[] canonical = CanonJson.Canonicalize(obj, options);
```
Notes:
- Default naming policy is `JsonNamingPolicy.CamelCase` for the object-to-JSON step.
- Default encoder is `JavaScriptEncoder.UnsafeRelaxedJsonEscaping` for canonical output.
## API Reference
| Method | Description |
@@ -69,6 +80,7 @@ byte[] canonical = CanonJson.Canonicalize(obj, options);
| `Canonicalize<T>(obj)` | Serialize and canonicalize an object |
| `Canonicalize<T>(obj, options)` | Serialize with custom options and canonicalize |
| `CanonicalizeParsedJson(bytes)` | Canonicalize existing JSON bytes |
| `CanonicalizeParsedJson(bytes, encoder)` | Canonicalize existing JSON with a custom encoder |
| `Sha256Hex(bytes)` | Compute SHA-256, return lowercase hex |
| `Sha256Prefixed(bytes)` | Compute SHA-256 with "sha256:" prefix |
| `Hash<T>(obj)` | Canonicalize and hash in one step |

1
src/__Libraries/StellaOps.Canonical.Json/StellaOps.Canonical.Json.csproj
View File

@@ -4,6 +4,7 @@
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
</Project>

2
src/__Libraries/StellaOps.Canonical.Json/TASKS.md
View File

@@ -7,4 +7,4 @@ Source of truth: `docs/implplan/SPRINT_20251229_049_BE_csproj_audit_maint_tests.
| --- | --- | --- |
| AUDIT-0130-M | DONE | Maintainability audit for StellaOps.Canonical.Json. |
| AUDIT-0130-T | DONE | Test coverage audit for StellaOps.Canonical.Json. |
| AUDIT-0130-A | TODO | Pending approval for changes. |
| AUDIT-0130-A | DONE | Applied canonicalization fixes and added tests. |