cabal-club / cable

A lightweight peer-to-peer chat protocol.
https://cabal.chat
74 stars 4 forks source link

after v1 review: create test vectors to facilitate interoperating implementations #13

Open cblgh opened 1 year ago

cblgh commented 1 year ago

when i was helping out on the ssb ngi project that was developing partial replication, we had a concept called testvectors (example) that i think could be really helpful as a resource to have for cable.

given that we're going through a spec review, this should come at the earliest after the v1 has been reviewed, RFCs process is done, and a final version decided on and landed in the spec repo.

so onto what a testvector is: a piece of documentation x example x testbed that gives pairs of [plaintext input, binary output] together with a description of what use case is being demonstrated by the pair.

so, a test vector for a cable hash response would:

we can also provide test vectors that do not work. e.g faulty input that should not result in a cablegram

the end result is that implementors have, in addition to the spec, a set of clear language-independent test cases they can try their implementation against. they can input the inputs and compare it against the generated buffer, as well as take the buffer and decode it to hopefully arrive at the given inputs.

i don't care so much about the format in particular, the example above is just one format we could choose. i would personally be happy with having a markdown document for test vectors, where each vector is listed as a description, the inputs, as well as the base16 encoded bytes representing the cablegram.