59 lines
1.5 KiB
Markdown
59 lines
1.5 KiB
Markdown
|
# 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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
```
|