endojs
docs(marshal): expand smallcaps readability invariants
Closes: #XXXX Refs: https://github.com/endojs/endo/pull/2673 , https://github.com/endojs/endo/pull/2675
Description
For data that would round trip through JSON(*), I think people have not appreciated how close smallcaps is to JSON. For such data, if the encoding to JSON has no special strings, i.e., strings that begin with a character between ! and _, then smallcaps and JSON are essentially equivalent (modulo required hardening).
This PR only revises the smallcaps cheatsheet to make this clearer.
(*) without procedural interventions such as toJSON, replacers, or resolvers.
Security Considerations
To the extent we can start using smallcaps where we currently use JSON, we set our selves up for better security. Once we start using the non-trapping integrity trait shim (https://github.com/endojs/endo/pull/2673 and https://github.com/endojs/endo/pull/2675), then once we know a value is passable, we'll know that it can be marshaled without reentrancy vulnerabilities.
Scaling Considerations
smallcaps encoding builds on JSON encoding, and so will always be somewhat slower than the JSON it builds on. We won't know how much, or how to speed it up, until we measure.
Documentation Considerations
The point. This PR only expands the cheatsheet. We should have a more complete explanation with all the caveats somewhere else. Where?
Testing Considerations
This PR makes expanded claims about invariants. At some point, we should have fastcheck tests for testing all these invariants.
Compatibility Considerations
This PR itself is only a doc change, so in that sense, none.
If we start switching some JSON uses to smallcaps, non-passable values may cause throws rather than silent misbehavior.
Upgrade Considerations
This PR itself is only a doc change, so in that sense, none.
If we start switching some durable storage from JSON to smallcaps, we'll have an upgrade nightmare. For durably stored JSON encodings, we should not change those to smallcaps without deep carefulness. Not recommended.
@kriskowal , I only changed one *.md file and all my CI tests are red. And again on retry. Help!
@kriskowal , I only changed one *.md file and all my CI tests are red. And again on retry. Help!
Seems healed. Nevermind.