armor: Prevent serialization backwards compatibility problems using golden tests
Tests the serialization backwards compatibility of data types by storing serialized representations in .test files to be checked into your project's version control.
[Skip to Readme]
Downloads
- armor-0.2.tar.gz [browse] (Cabal source package)
- Package description (as included in the package)
Maintainer's Corner
For package maintainers and hackage trustees
Candidates
| Versions [RSS] | 0.1, 0.2, 0.2.0.1 |
|---|---|
| Change log | ChangeLog.md |
| Dependencies | base (>=4.6 && <4.16), bytestring (>=0.10 && <0.12), containers (>=0.5 && <0.7), directory (>=1.2 && <1.4), filepath (>=1.4 && <1.5), hashable (>=1.3 && <1.4), HUnit (>=1.5 && <1.7), lens (>=4.16 && <5.1) [details] |
| License | BSD-3-Clause |
| Copyright | Doug Beardsley, Formation Inc. |
| Author | Doug Beardsley |
| Maintainer | mightybyte@gmail.com |
| Category | Data, Testing |
| Home page | https://github.com/mightybyte/armor |
| Bug tracker | https://github.com/mightybyte/armor/issues |
| Source repo | head: git clone https://github.com/mightybyte/armor.git |
| Uploaded | by DougBeardsley at 2021-05-06T21:03:37Z |
| Distributions | |
| Reverse Dependencies | 1 direct, 0 indirect [details] |
| Downloads | 1153 total (14 in the last 30 days) |
| Rating | (no votes yet) [estimated by Bayesian average] |
| Your Rating | |
| Status | Docs available [build log] Last success reported on 2021-05-06 [all 1 reports] |
Readme for armor-0.2
[back to package description]Armor
Armor yourself against backwards-incompatible serializations once and for all.
See the ChangeLog for information about changes between versions.
Motivation
As almost everyone with significant experience managing production software systems knows, backwards compatibility is incredibly important for any data that is persisted by an application. If you make a change to a data structure that is not backwards compatible with the existing serialized formats, your app will break as soon as it encounters the existing format. Even if you have 100% test coverage, your tests still might not catch this problem because it's not a problem with your app at any single point in time, but a problem with how your app evolves over time.
More subtly, if you deploy a backwards incompatible migration, your app may persist some data in the new format before it crashes on the old format. This can leave your system in the horrible state where not only will it not work with the new code, but rolling back to the old code will also break because the old code doesn't support the new serialized format! You have two incomptable serializations active at the same time!
Proper migration systems can reduce the chances of this problem occurring, but
if your system has any kind of queueing system or message bus, your migrations
might not be applied to in-flight messages. Clearly we need something to help us
protect against this problem. Enter armor.
For an overview of how to use this package, check out the literate Haskell tutorial in the test suite.
Credits
Inspiration for this package came from Soostone's safecopy-hunit package.
Details were refined in production at Formation (previously Takt).