nix-playgraound/notes/030-haskell-aeson-roundtrip.md

Haskell Aeson Round Trips

This note covers 27-haskell-aeson-roundtrip/, which defines explicit JSON instances for deployment manifests and checks that encoding followed by decoding preserves the manifest value.

---

1. Why the Instances Are Explicit

The example could have used generic deriving, but that would hide the JSON shape.

Instead, it defines instances by hand for:

• Environment,
• RolloutStrategy, and
• DeploymentManifest.

That makes the wire format obvious, especially for the nested strategy object.

---

2. What the Round Trip Proves

The main test checks this flow:

1. start with a manifest value,
2. encode it to JSON,
3. decode the JSON back, and
4. compare the result with the original value.

That does not prove every possible JSON input is valid, but it does prove that the encoder and decoder agree on the example's own format.

---

3. Why the Strategy Shape Is Interesting

RolloutStrategy is not encoded as a bare string. It becomes an object with a type field and, for canary rollouts, a percentage field.

That is a more realistic format for APIs because it leaves room for strategy-specific data while keeping a stable top-level manifest shape.

---

4. Commands to Try

cd 27-haskell-aeson-roundtrip

nix develop
cabal run
cabal run -- api production 3 platform,security canary:10
cabal test

nix build
./result/bin/mini-manifest api production 3 platform,security canary:10

nix run . -- api production 3 platform,security canary:10
nix flake check