docs(parsing): document why the nesting bound is necessary and sufficient

This commit is contained in:
Mihaela Mihaljevic 2026-06-23 11:08:30 +02:00
parent 64a171bff4
commit 16a47df118
2 changed files with 47 additions and 5 deletions

View File

@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
## [0.1.5] - 2026-06-23
### Documentation
- Document why `maxNestingDepth` is the necessary and sufficient safety bound
for deeply nested input: a `Model.Value` is a recursive tree whose every
operation (compose, emit, compare, hash, and especially deallocate) recurses
with nesting, and Swift cannot deallocate a recursive value type iteratively,
so bounding the tree's depth at parse time is the only complete protection.
Records the measured headroom, why the bound cannot be raised without an
iterative parser (and would be pointless past the ~5,000 `deinit` limit), and
the caveat that trees built by encoding a deep `Codable` value bypass it.
## [0.1.4] - 2026-06-23
### Fixed

View File

@ -9,11 +9,40 @@ extension PureYAML.Parsing {
/// with a diagnostic instead of overflowing the stack.
var depth = 0
/// Maximum node nesting the recursive-descent parser will follow.
/// Real-world specs nest well under this; the bound exists so a
/// pathologically nested document (e.g. hundreds of `[[[...]]]`)
/// throws ``ParseError/nestingTooDeep(line:column:)`` rather than
/// crashing the process.
/// Maximum node nesting the parser will follow before failing with
/// ``ParseError/nestingTooDeep(line:column:)``.
///
/// This bound is the single safety invariant for deeply nested input,
/// and it is *necessary*, not merely convenient. A ``Model/Value`` is a
/// recursive tree, so composing it, emitting it, comparing it, hashing
/// it, and -- crucially -- deallocating it all recurse with the nesting
/// depth. Swift tears down a recursive value type recursively, and that
/// teardown cannot be made iterative cheaply, so the only way to keep
/// every operation within the call stack is to bound the depth of the
/// tree where it is built: here, while parsing.
///
/// Because every parsing entry point routes through ``parseNode``, this
/// one bound caps the depth of any parsed tree, which transitively keeps
/// the parser, the event composers, the emitter, equality, hashing, and
/// deallocation all well inside their limits. Measured on the main
/// thread's 8 MB stack: the parser overflows near depth 225 and the
/// tree operations near depth 50,000, while real-world specs nest below
/// ~40. So 64 accepts every realistic document yet rejects pathological
/// input -- for example a 100 KB `[[[...]]]` -- cleanly and early.
///
/// The bound cannot simply be raised: above ~225 the recursive parser
/// itself overflows before the guard fires (lifting it would require an
/// iterative parser), and a tree past ~5,000 deep crashes on `deinit`
/// regardless, so a higher limit would trade a parse-time failure for an
/// un-fixable teardown crash. 64 is the largest value that is both safe
/// here and sufficient for real input.
///
/// Caveat: a tree built *without* the parser -- for example by encoding
/// a pathologically deep `Codable` value -- bypasses this bound, and
/// operations on such a tree are O(depth) in stack like any recursive
/// value type. Keeping those shallow is the caller's responsibility, the
/// same way the standard library cannot prevent unbounded recursion in
/// user code.
static let maxNestingDepth = 64
init(