Part 8: YAML & JSON Round-Tripping, with Schema Validation📋

public static class TraefikSerializer
{
    private static readonly IDeserializer Deserializer = new DeserializerBuilder()
        .WithNamingConvention(CamelCaseNamingConvention.Instance)
        .IgnoreUnmatchedProperties()
        .Build();

    private static readonly ISerializer Serializer = new SerializerBuilder()
        .WithNamingConvention(CamelCaseNamingConvention.Instance)
        .ConfigureDefaultValuesHandling(DefaultValuesHandling.OmitNull)
        .Build();

    private static readonly JsonSerializerOptions JsonOptions = new()
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
        WriteIndented = false,
    };

    private static readonly Lazy<JsonSchema?> StaticSchema = new(
        () => LoadEmbeddedSchema("traefik-v3-static.json"));

    private static readonly Lazy<JsonSchema?> DynamicSchema = new(
        () => LoadEmbeddedSchema("traefik-v3-file-provider.json"));
    // …
}

private static Result<T> TryDeserializeWithSchema<T>(string yaml, JsonSchema? schema) where T : notnull
{
    if (schema is null)
    {
        return Result<T>.Failure(new ValidationResult(
            "Embedded JSON schema could not be loaded."));
    }

    // Step 1: parse the YAML into a JsonNode tree that preserves the
    // *original* shape — including keys the typed deserializer would
    // silently drop because of IgnoreUnmatchedProperties. YamlToJson
    // honours YAML 1.2 core scalar resolution (true/false → bool,
    // 42 → int, 3.14 → float, etc.) so JsonSchema.Net sees real types.
    JsonNode? node;
    try
    {
        node = YamlToJson.Parse(yaml);
    }
    catch (Exception ex)
    {
        return Result<T>.Failure(new ValidationResult(
            $"YAML parse failure: {ex.Message}"));
    }

    if (node is null)
        return Result<T>.Failure(new ValidationResult("YAML document is empty."));

    // Step 2: schema-validate the original YAML shape. This catches
    // typo'd keys (`additionalProperties: false` in the schema) AND
    // type errors (string where bool expected, etc.).
    try
    {
        using var doc = JsonDocument.Parse(node.ToJsonString());
        var evaluation = schema.Evaluate(doc.RootElement, new EvaluationOptions
        {
            OutputFormat = OutputFormat.List,
        });
        if (!evaluation.IsValid)
            return Result<T>.Failure(BuildValidationResult(evaluation));
    }
    catch (Exception ex)
    {
        return Result<T>.Failure(new ValidationResult(
            $"Schema validation failed: {ex.Message}"));
    }

    // Step 3: only after the schema is happy, deserialize into the
    // typed POCO. The schema has already vetted the shape; this is
    // just the type projection.
    try
    {
        var typed = Deserializer.Deserialize<T>(yaml);
        return Result<T>.Success(typed);
    }
    catch (Exception ex)
    {
        return Result<T>.Failure(new ValidationResult(
            $"Typed deserialization failed after schema validation: {ex.Message}"));
    }
}

public static Task<ResultUnit> WriteDynamicToFileAsync(
    string path, TraefikDynamicConfig config, CancellationToken ct = default)
    => WriteToFileAsyncCore(path, config, DynamicSchema.Value, ct);

private static async Task<ResultUnit> WriteToFileAsyncCore<T>(
    string path, T config, JsonSchema? schema, CancellationToken ct) where T : notnull
{
    if (schema is null) return ResultUnit.Failure();

    // Validate the typed config against the embedded schema *before*
    // touching the disk. A serializer that produces an invalid Traefik
    // config is a bug; this surfaces it at write time rather than at
    // Traefik's startup.
    if (!TryValidateAgainstSchema(config, schema, out _))
        return ResultUnit.Failure();

    var yaml = Serializer.Serialize(config!);
    var tmpPath = path + ".tmp";

    try
    {
        // Write the temp file fully (and fsync via DisposeAsync) before
        // touching the destination, then atomically rename. File.Replace
        // exists on Windows + .NET; File.Move handles the no-target case.
        await File.WriteAllTextAsync(tmpPath, yaml, ct).ConfigureAwait(false);

        const int maxAttempts = 3;
        for (var attempt = 0; attempt < maxAttempts; attempt++)
        {
            ct.ThrowIfCancellationRequested();
            try
            {
                if (File.Exists(path))
                    File.Replace(tmpPath, path, destinationBackupFileName: null);
                else
                    File.Move(tmpPath, path);
                return ResultUnit.Success();
            }
            catch (IOException) when (attempt < maxAttempts - 1)
            {
                await Task.Delay(50, ct).ConfigureAwait(false);
            }
        }

        return ResultUnit.Failure();
    }
    catch (Exception)
    {
        try { if (File.Exists(tmpPath)) File.Delete(tmpPath); } catch { /* best effort */ }
        return ResultUnit.Failure();
    }
}

# Realistic Traefik dynamic configuration sample.
# Exercises multiple middlewares (auth, prefix, headers, retry), TLS options,
# weighted load balancing, and a TCP router. Used by RealisticRoundTripTests
# to flush out edge cases the synthetic minimal fixtures don't reach.
http:
  routers:
    api-router:
      rule: "Host(`api.example.com`) && PathPrefix(`/v1`)"
      entryPoints:
        - websecure
      service: api-backend
      middlewares:
        - api-auth
        - api-strip-prefix
        - api-rate-limit
      tls:
        certResolver: letsencrypt
    web-router:
      rule: "Host(`www.example.com`)"
      entryPoints:
        - web
        - websecure
      service: web-frontend
      middlewares:
        - secure-headers
      priority: 100

  services:
    api-backend:
      loadBalancer:
        servers:
          - url: "http://api-1.internal:8080"
          - url: "http://api-2.internal:8080"
        passHostHeader: true
        responseForwarding:
          flushInterval: "100ms"
        healthCheck:
          path: "/healthz"
          interval: "30s"
          timeout: "5s"
    web-frontend:
      loadBalancer:
        servers:
          - url: "http://web-1.internal:3000"

  middlewares:
    api-auth:
      basicAuth:
        users:
          - "admin:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
        realm: "API"
    api-strip-prefix:
      stripPrefix:
        prefixes:
          - "/v1"
    api-rate-limit:
      rateLimit:
        average: 100
        burst: 50
    secure-headers:
      headers:
        frameDeny: true
        sslRedirect: true
        stsSeconds: 31536000
        customResponseHeaders:
          X-Frame-Options: "DENY"
          X-Content-Type-Options: "nosniff"

tcp:
  routers:
    postgres-router:
      rule: "HostSNI(`db.example.com`)"
      entryPoints:
        - postgres
      service: postgres-backend
      tls:
        passthrough: true
  services:
    postgres-backend:
      loadBalancer:
        servers:
          - address: "postgres-1.internal:5432"

[Fact]
public void DeserializeDynamic_RealisticSample_PreservesDiscriminatedMiddlewareBranches()
{
    var yaml = File.ReadAllText("Samples/realistic-dynamic.yaml");
    var config = TraefikSerializer.DeserializeDynamic(yaml);

    var auth = config.Http!.Middlewares!["api-auth"];
    auth.BasicAuth.ShouldNotBeNull();
    auth.StripPrefix.ShouldBeNull();

    var stripPrefix = config.Http.Middlewares["api-strip-prefix"];
    stripPrefix.StripPrefix.ShouldNotBeNull();
    stripPrefix.BasicAuth.ShouldBeNull();
}

[Fact]
public void RoundTrip_RealisticSample_StableShape()
{
    var yaml = File.ReadAllText("Samples/realistic-dynamic.yaml");
    var first = TraefikSerializer.DeserializeDynamic(yaml);
    var serialized = TraefikSerializer.Serialize(first);
    var second = TraefikSerializer.DeserializeDynamic(serialized);

    second.Http!.Routers!.Keys.ShouldBe(first.Http!.Routers!.Keys, ignoreOrder: true);
    second.Http.Services!.Keys.ShouldBe(first.Http.Services!.Keys, ignoreOrder: true);
    second.Http.Middlewares!.Keys.ShouldBe(first.Http.Middlewares!.Keys, ignoreOrder: true);
    second.Tcp!.Routers!.Keys.ShouldBe(first.Tcp!.Routers!.Keys, ignoreOrder: true);
}