docs(parsing): document why the nesting bound is necessary and sufficient
This commit is contained in:
parent
64a171bff4
commit
16a47df118
13
CHANGELOG.md
13
CHANGELOG.md
@ -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
|
||||
|
||||
@ -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(
|
||||
|
||||
Loading…
Reference in New Issue
Block a user