Skip to content

fix: add RFC 5987 filename* encoding for special characters - #602

Open
abhu85 wants to merge 1 commit into
form-data:masterfrom
abhu85:fix/572-content-disposition-encoding
Open

abhu85 wants to merge 1 commit into
form-data:masterfrom
abhu85:fix/572-content-disposition-encoding

Conversation

@abhu85

@abhu85 abhu85 commented Mar 16, 2026

Copy link
Copy Markdown

Summary

  • Filenames with special characters (parentheses, spaces, etc.) now include RFC 5987 encoded filename* parameter
  • Normal filenames without special characters remain unchanged (backwards compatible)
  • Fixes compatibility with .NET servers that strictly validate Content-Disposition headers

Problem

When uploading files with parentheses in the filename (e.g., test(1).txt), .NET 8 servers reject the request with "Failed to read the request form. Form section has invalid Content-Disposition value".

Per RFC 2616 Section 2.2, parentheses are separators and should not appear unencoded in header parameter values. Per RFC 5987 Section 3.2.1, the attr-char set only includes:

ALPHA / DIGIT / "!" / "#" / "$" / "&" / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~"

Solution

When a filename contains characters outside the attr-char set, the fix now generates:

Content-Disposition: form-data; name="file"; filename="test(1).txt"; filename*=utf-8''test%281%29.txt

Per RFC 6266 Section 4.3, receivers should prefer filename* over filename, but including both ensures maximum compatibility.

For filenames without special characters, the output remains unchanged:

Content-Disposition: form-data; name="file"; filename="normal.txt"

Test Plan

  • All existing tests pass (28 test files)
  • Added 3 new test cases for RFC 5987 encoding
  • Linting passes (warnings only)
  • Coverage maintained at 98%+

Compatibility

  • No breaking changes for existing filenames
  • Backwards compatible - basic filename always included
  • Works with strict RFC-compliant servers (.NET, etc.)

Fixes #572

…a#572)

Filenames containing characters outside the RFC 5987 attr-char set
(e.g., parentheses, spaces, unicode) are now properly percent-encoded
in the Content-Disposition header using the filename* parameter.

Per RFC 2616 Section 2.2, parentheses are separators and must be encoded.
Per RFC 5987 Section 3.2.1, attr-char only includes:
  ALPHA / DIGIT / "!" / "#" / "$" / "&" / "+" / "-" / "." /
  "^" / "_" / "`" / "|" / "~"

The fix:
- Adds both filename="..." (for backwards compatibility) and
  filename*=utf-8''... (RFC 5987 encoded) when special chars are present
- Normal filenames without special chars only use filename="..."
- Per RFC 6266 Section 4.3, receivers should prefer filename* over filename

This fixes compatibility with .NET servers that strictly validate
Content-Disposition headers according to RFC 5987.

Fixes form-data#572

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@abhu85

abhu85 commented Apr 13, 2026

Copy link
Copy Markdown
Author

Hi @ljharb 👋

Friendly ping on this PR implementing RFC 5987 filename* encoding for special characters (fixes #572). The fix percent-encodes parentheses and other RFC 5987 separators in the filename* parameter.

Would appreciate a review when you have time. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Invalid Content-Disposition with FileName* containing parenthesis

1 participant