fix: handle non-ASCII filenames in export Content-Disposition headers (#7739)

Fixes #7730 - Exporting HTML/script/markdown fails with
`UnicodeEncodeError` when the filename contains non-ASCII characters
(Chinese, emojis, etc.).

Author: mscolnick

marimo/_server/api/endpoints/export.py

@@ -16,7 +16,10 @@
 from marimo._server.api.deps import AppState
 from marimo._server.api.utils import parse_request
 from marimo._server.export.exporter import AutoExporter, Exporter
-from marimo._server.export.utils import get_download_filename
+from marimo._server.export.utils import (
+    get_download_filename,
+    make_download_headers,
+)
 from marimo._server.models.export import (
     ExportAsHTMLRequest,
     ExportAsMarkdownRequest,
@@ -89,7 +92,7 @@ async def export_as_html(
     )
 
     if body.download:
-        headers = {"Content-Disposition": f"attachment; filename={filename}"}
+        headers = make_download_headers(filename)
     else:
         headers = {}
 
@@ -212,7 +215,7 @@ async def export_as_script(
     )
 
     if body.download:
-        headers = {"Content-Disposition": f"attachment; filename={filename}"}
+        headers = make_download_headers(filename)
     else:
         headers = {}
 
@@ -269,9 +272,7 @@ async def export_as_markdown(
         download_filename = get_download_filename(
             app_file_manager.filename, "md"
         )
-        headers = {
-            "Content-Disposition": f"attachment; filename={download_filename}"
-        }
+        headers = make_download_headers(download_filename)
     else:
         headers = {}
 

marimo/_server/export/utils.py

@@ -3,6 +3,7 @@
 
 import os
 from typing import Optional
+from urllib.parse import quote
 
 
 def get_filename(filename: Optional[str], default: str = "notebook.py") -> str:
@@ -17,3 +18,28 @@ def get_download_filename(filename: Optional[str], extension: str) -> str:
     if basename.endswith(f".{extension}"):
         return basename
     return f"{os.path.splitext(basename)[0]}.{extension}"
+
+
+def make_download_headers(filename: str) -> dict[str, str]:
+    """Create headers for file download with proper Content-Disposition encoding.
+
+    This function handles non-ASCII filenames using RFC 5987 encoding
+    (filename*=UTF-8''...) to avoid UnicodeEncodeError when the filename
+    contains characters outside the Latin-1 range.
+
+    Args:
+        filename: The filename for the download (may contain non-ASCII chars)
+
+    Returns:
+        A dict with the Content-Disposition header properly encoded
+    """
+    # URL-encode the filename for RFC 5987 (preserves safe chars like .)
+    encoded_filename = quote(filename, safe="")
+
+    # Use RFC 5987 encoding: filename*=UTF-8''<url-encoded-filename>
+    # Also provide a fallback ASCII filename for older clients
+    return {
+        "Content-Disposition": (
+            f"attachment; filename*=UTF-8''{encoded_filename}"
+        )
+    }

tests/_server/api/endpoints/test_export.py

@@ -23,7 +23,7 @@
     with_read_session,
     with_session,
 )
-from tests.mocks import snapshotter
+from tests.mocks import EDGE_CASE_FILENAMES, snapshotter
 
 if TYPE_CHECKING:
     from starlette.testclient import TestClient
@@ -579,3 +579,45 @@ def test_export_html_unnamed_file(client: TestClient) -> None:
     # Should return 400 Bad Request when file is unnamed
     assert response.status_code == 400
     assert "File must have a name before exporting" in response.text
+
+
+@with_session(SESSION_ID)
+def test_export_html_download_edge_case_filenames(client: TestClient) -> None:
+    """Test that HTML export with download=True works for non-ASCII filenames."""
+    for filename in EDGE_CASE_FILENAMES:
+        session = get_session_manager(client).get_session(SESSION_ID)
+        assert session
+        session.app_file_manager.filename = filename
+        response = client.post(
+            "/api/export/html",
+            headers=HEADERS,
+            json={
+                "download": True,
+                "files": [],
+                "includeCode": True,
+            },
+        )
+        assert response.status_code == 200, f"Failed for filename: {filename}"
+        assert "Content-Disposition" in response.headers
+        assert "attachment" in response.headers["Content-Disposition"]
+
+
+@with_session(SESSION_ID)
+def test_export_script_download_edge_case_filenames(
+    client: TestClient,
+) -> None:
+    """Test that script export with download=True works for non-ASCII filenames."""
+    for filename in EDGE_CASE_FILENAMES:
+        session = get_session_manager(client).get_session(SESSION_ID)
+        assert session
+        session.app_file_manager.filename = filename
+        response = client.post(
+            "/api/export/script",
+            headers=HEADERS,
+            json={
+                "download": True,
+            },
+        )
+        assert response.status_code == 200, f"Failed for filename: {filename}"
+        assert "Content-Disposition" in response.headers
+        assert "attachment" in response.headers["Content-Disposition"]