dumpfile: Document escaping behavior relative to C composefs

The dumpfile format is flexible, e.g. it allows escaping
some things that technically don't need to be. While doing some
fuzzing it was discovered that there were some differences.

Let's note those here.

Assisted-by: OpenCode (Claude claude-opus-4-6)
Signed-off-by: Colin Walters <walters@verbum.org>

Author: cgwalters

crates/composefs/src/dumpfile.rs

@@ -31,29 +31,47 @@ fn write_empty(writer: &mut impl fmt::Write) -> fmt::Result {
     writer.write_str("-")
 }
 
+/// Escape a byte slice for a space-delimited dumpfile field.
+///
+/// This corresponds to `print_escaped_optional` in the C composefs
+/// `composefs-info.c`, combining `ESCAPE_STANDARD | ESCAPE_LONE_DASH`.
+/// Empty values map to `-` (the "none" sentinel), and a bare `-` is
+/// hex-escaped so it is not confused with the sentinel.
+///
+/// Not appropriate for xattr values — use [`write_escaped_raw`] instead.
 fn write_escaped(writer: &mut impl fmt::Write, bytes: &[u8]) -> fmt::Result {
     if bytes.is_empty() {
         return write_empty(writer);
     }
 
-    // A bare `-` must be escaped because the parser uses `-` as
-    // the sentinel for "empty/none" (cf. `optional_str` in the parser).
+    // Matches C ESCAPE_LONE_DASH: a bare `-` must be escaped because
+    // the parser uses `-` as the sentinel for "empty/none".
     if bytes == b"-" {
         return writer.write_str("\\x2d");
     }
 
     write_escaped_raw(writer, bytes)
 }
 
-/// Write escaped bytes without special handling for empty or bare `-`.
+/// Escape a byte slice without the `-` sentinel logic.
 ///
-/// Used for xattr values where the `-` sentinel is not applicable:
-/// xattr values are always present when the key=value pair exists,
-/// and a value of `-` or empty is perfectly valid.
+/// This corresponds to `print_escaped` with `ESCAPE_EQUAL` (but without
+/// `ESCAPE_LONE_DASH`) in the C composefs `composefs-info.c`.  Used for
+/// xattr values where `-` and empty are valid literal values, not
+/// sentinels.
+///
+/// Note: we unconditionally escape `=` in all fields, whereas the C code
+/// only uses `ESCAPE_EQUAL` for xattr keys and values.  This is harmless
+/// since `\x3d` round-trips correctly, but means our output for paths
+/// containing `=` is slightly more verbose than the C output.
 fn write_escaped_raw(writer: &mut impl fmt::Write, bytes: &[u8]) -> fmt::Result {
     for c in bytes {
         let c = *c;
 
+        // The set of hex-escaped characters matches C `!isgraph(c)` in the
+        // POSIX locale (i.e. outside 0x21..=0x7E), plus `=` and `\`.
+        // The C code uses named escapes for `\\`, `\n`, `\r`, `\t` while
+        // we hex-escape everything uniformly; both forms parse correctly.
         if c < b'!' || c == b'=' || c == b'\\' || c > b'~' {
             write!(writer, "\\x{c:02x}")?;
         } else {
@@ -234,6 +252,12 @@ pub fn write_leaf(
 ///
 /// Creates a special entry that links the given path to an existing target path
 /// that was already written to the dumpfile.
+///
+/// The C composefs writes the real metadata (mode, uid, etc.) from the
+/// target node; we write placeholder zeros since both parsers ignore all
+/// fields except the target path for hardlink entries.  The nlink/uid/gid/rdev
+/// fields must be valid integers (not `-`) because the parser reads them
+/// unconditionally before checking the `@` hardlink prefix.
 pub fn write_hardlink(writer: &mut impl fmt::Write, path: &Path, target: &OsStr) -> fmt::Result {
     write_escaped(writer, path.as_os_str().as_bytes())?;
     write!(writer, " 0 @120000 0 0 0 0 0.0 ")?;

crates/composefs/src/dumpfile_parse.rs

@@ -270,6 +270,15 @@ enum EscapeMode {
 }
 
 /// Escape a byte array according to the composefs dump file text format.
+///
+/// Note: this function unconditionally maps empty → `-` and escapes a
+/// bare `-`.  That matches C `ESCAPE_LONE_DASH` and is correct for
+/// space-delimited fields (path, payload, content), but the C code does
+/// NOT set `ESCAPE_LONE_DASH` for xattr values — there, `-` and empty
+/// are valid literals.  The `Entry` Display impl currently uses this for
+/// xattr values via `EscapeMode::Standard`, which diverges from C.
+/// The `write_dumpfile` writer in `dumpfile.rs` avoids this by using
+/// a separate `write_escaped_raw` for xattr values.
 fn escape<W: std::fmt::Write>(out: &mut W, s: &[u8], mode: EscapeMode) -> std::fmt::Result {
     // Empty content must be represented by `-`
     if s.is_empty() {
@@ -568,6 +577,12 @@ impl Display for Entry<'_> {
             f.write_char(' ')?;
             escape(f, xattr.key.as_bytes(), EscapeMode::XattrKey)?;
             f.write_char('=')?;
+            // NOTE: the C code uses ESCAPE_EQUAL (not ESCAPE_LONE_DASH)
+            // for xattr values, meaning it does not escape bare `-` or
+            // map empty to `-`.  Using `Standard` mode here is slightly
+            // inconsistent with C but harmless since `\x2d` parses back
+            // to `-`.  The `write_dumpfile` writer uses `write_escaped_raw`
+            // which matches C more closely.
             escape(f, &xattr.value, EscapeMode::Standard)?;
         }
         std::fmt::Result::Ok(())