view mercurial/help/internals/censor.txt @ 37290:cc5a040fe150

wireproto: syntax for encoding CBOR into frames

We just vendored a library for encoding and decoding the CBOR
data format. While the intent of that vendor was to support state
files, CBOR is really a nice data format. It is extensible and
compact.

I've been feeling dirty inventing my own data formats for
frame payloads. While custom formats can always beat out a generic
format, there is a cost to be paid in terms of implementation,
comprehension, etc. CBOR is compact enough that I'm not too
worried about efficiency loss. I think the benefits of using
a standardized format outweigh rolling our own formats. So
I plan to make heavy use of CBOR in the wire protocol going
forward.

This commit introduces support for encoding CBOR data in frame
payloads to our function to make a frame from a human string.
We do need to employ some low-level Python code in order to
evaluate a string as a Python expression. But other than that,
this should hopefully be pretty straightforward.

Unit tests for this function have been added.

Differential Revision: https://phab.mercurial-scm.org/D2948

The censor system allows retroactively removing content from
files. Actually censoring a node requires using the censor extension,
but the functionality for handling censored nodes is partially in core.

Censored nodes in a filelog have the flag ``REVIDX_ISCENSORED`` set,
and the contents of the censored node are replaced with a censor
tombstone. For historical reasons, the tombstone is packed in the
filelog metadata field ``censored``. This allows censored nodes to be
(mostly) safely transmitted through old formats like changegroup
versions 1 and 2. When using changegroup formats older than 3, the
receiver is required to re-add the ``REVIDX_ISCENSORED`` flag when
storing the revision. This depends on the ``censored`` metadata key
never being used for anything other than censoring revisions, which is
true as of January 2017. Note that the revlog flag is the
authoritative marker of a censored node: the tombstone should only be
consulted when looking for a reason a node was censored or when revlog
flags are unavailable as mentioned above.

The tombstone data is a free-form string. It's expected that users of
censor will want to record the reason for censoring a node in the
tombstone. Censored nodes must be able to fit in the size of the
content being censored.