#moon-content-disposition

#Highlights

• Strict, deterministic parser. Implements the RFC 6266 Section 4.2 grammar with a stable, structured error model: every failure is a DispositionError carrying a processing stage, a concrete kind, a UTF-8 byte offset and a bounded context excerpt.
• RFC 8187 international filenames. filename* extended values are parsed and serialised for the two charsets that matter in practice (UTF-8 and ISO-8859-1), with strict percent-decoding, RFC 5646 language tags, and the RFC 6266 Section 4.3 precedence rule (filename* wins; filename is the fallback).
• Safe filename policy. resolve_filename selects the download name; sanitize_filename turns it into a single safe path component under one of three profiles (Portable / Windows-like / Posix-like). Every transformation is recorded as a stable issue key; a non-empty name never fails.
• Security audit. audit_header reports path separators, control characters, missing filename*, risky extensions, Windows reserved names, trailing dots, duplicate parameters and more — each with a severity, before anything is written to disk.
• Deterministic serialisation. Parsed values re-serialise byte-stably; canonicalize_content_disposition produces a canonical form that is idempotent.
• CR/LF injection defence. The generator rejects CR, LF, NUL and other control bytes outright rather than emitting them.
• Bounded resource use. Seven independent Limits (input bytes, parameter count, value bytes, …) guarantee that no parse can exhaust memory, loop forever, or silently truncate.
• Portable. The same code builds and passes 327 tests on the native, js and wasm-gc targets. Includes a JSON-emitting CLI (disposition-tool) and six runnable examples.

#Quick start

let header = "attachment; filename=\"café.txt\"; filename*=UTF-8'en'caf%C3%A9.txt"

match @cd.parse_content_disposition(header) {
  Err(e) => println("parse failed: \{e.to_display()}")
  Ok(cd) => {
    match @cd.resolve_filename(cd) {
      Err(e) => println("resolve failed: \{e.to_display()}")
      Ok(sel) => {
        // sel.selected() == "café.txt", sel.source() == FilenameStar
        match @cd.sanitize_portable_filename(sel.selected()) {
          Err(e) => println("sanitize failed: \{e.to_display()}")
          Ok(result) => println("safe download name: \{result.safe()}")
        }
      }
    }
  }
}

let value = @cd.generate_attachment("café report.pdf")
// "attachment; filename=\"café report.pdf\"; filename*=UTF-8''caf%C3%A9%20report.pdf"

let canonical = @cd.canonicalize_content_disposition(
  "ATTACHMENT; FILE=fallback.txt; FILE*=UTF-8''caf%C3%A9.pdf",
)
// "attachment; filename=fallback.txt; filename*=UTF-8''caf%C3%A9.pdf"

match @cd.audit_header("attachment; filename=\"../../install.exe\"") {
  Err(e) => println("audit failed: \{e.to_display()}")
  Ok(report) =>
    for issue in report.issues() {
      println("[ \{issue.severity().to_string()} ] \{issue.kind().to_string()}: \{issue.message()}")
    }
}

#The pipeline

parse → resolve → sanitize
  │         │        └─ FilenamePolicy (Portable / WindowsLike / PosixLike)
  │         └─ RFC 6266 §4.3 precedence, advisory warnings
  └─ ContentDisposition model
       ├─ serialize / canonicalize
       ├─ generate (the inverse of parse)
       └─ audit (advisory, never mutates)

#Documentation

• API reference
• Usage guide
• CLI reference
• Security model
• Strict vs. compatible parsing
• International filenames (RFC 8187)
• Testing
• Architecture and design

#Command-line toolkit

parse <value>            serialize <value>          canonicalize <value>
resolve <value>          sanitize <name> [profile]  generate <type> <name>
audit <value>            limits [preset]            profiles
version                  help

#Examples

moon run examples/parse
moon run examples/resolve -- "attachment; filename=fallback.txt; filename*=UTF-8'en'caf%C3%A9.txt"
moon run examples/sanitize
moon run examples/generate -- "café report.pdf"
moon run examples/canonicalize
moon run examples/audit

#Building and testing

moon build                     # library
moon build cmd/disposition-tool --target wasm-gc
moon test                      # native (default)
moon test --target js
moon test --target wasm-gc
scripts/verify_all.ps1         # end-to-end verification (three targets)
scripts/count_code.py          # source-line report

#Requirements

• MoonBit toolchain 0.1.20260713 or newer. The build is verified on the native, js and wasm-gc targets.
• Python 3 for scripts/count_code.py; Windows PowerShell for scripts/verify_all.ps1 (the script also works under pwsh on other platforms).

#Versioning

#License