🥇 fix: asgi

[xinquiry]

变更内容

• 新功能
• 修复 Bug
• 增强重构
• 其他（请描述）

简要描述本次 PR 的主要变更内容。

相关 Issue

请关联相关 Issue（如有）：#编号

检查清单

默认已勾选，如不满足，请检查。

• 已在本地测试通过
• 已补充/更新相关文档
• 已添加测试用例
• 代码风格已经过 pre-commit 钩子检查

其他说明

如有特殊说明或注意事项，请补充。

Summary by Sourcery

Bug Fixes:

• 确保下载文件的响应包含符合 RFC 5987 的 Content-Disposition 头，以便正确处理包含非 ASCII 字符的文件名。

Original summary in English

Summary by Sourcery

Bug Fixes:

• Ensure downloaded file responses include RFC 5987-compliant Content-Disposition headers so filenames with non-ASCII characters are handled properly.

[sourcery-ai]

审阅者指南（在小型 PR 上默认折叠）

审阅者指南

为文件下载实现符合 RFC 5987 的 Content-Disposition 文件名处理，以在各浏览器中更好地支持非 ASCII 文件名。

文件级变更

变更	详情	文件
更新文件下载响应，使其使用同时包含 ASCII 和 UTF-8 文件名的、兼容 RFC 5987 的 Content-Disposition 头。	从原始文件名中派生仅包含 ASCII 的文件名变体，用于传统的 filename 参数。 对原始文件名的 UTF-8 版本进行 URL 编码，用于 filename* 参数。 设置 Content-Disposition 头，以在保留现有媒体类型和 Content-Length 处理的同时，包含 filename 和 filename* 两个值。	service/handler/api/v1/files.py

---

提示与命令

与 Sourcery 交互

• 触发新的审阅： 在 pull request 中评论 @sourcery-ai review。
• 继续讨论： 直接回复 Sourcery 的审阅评论。
• 从审阅评论生成 GitHub issue： 回复某条审阅评论，要求 Sourcery 从该评论创建一个 issue。你也可以在审阅评论下回复 @sourcery-ai issue 来从该评论创建 issue。
• 生成 pull request 标题： 在 pull request 标题的任意位置写上 @sourcery-ai，即可随时生成标题。你也可以在 pull request 中评论 @sourcery-ai title 来（重新）生成标题。
• 生成 pull request 摘要： 在 pull request 内容（body）的任意位置写上 @sourcery-ai summary，即可在你想要的位置生成 PR 摘要。你也可以在 pull request 中评论 @sourcery-ai summary 来随时（重新）生成摘要。
• 生成审阅者指南： 在 pull request 中评论 @sourcery-ai guide，即可随时（重新）生成审阅者指南。
• 解决所有 Sourcery 评论： 在 pull request 中评论 @sourcery-ai resolve，即可将所有 Sourcery 评论标记为已解决。如果你已经处理完所有评论且不想再看到它们，这会非常有用。
• 关闭所有 Sourcery 审阅： 在 pull request 中评论 @sourcery-ai dismiss，即可关闭所有现有的 Sourcery 审阅。特别适用于你想从一个全新的审阅开始时——别忘了随后评论 @sourcery-ai review 来触发新的审阅！

自定义你的体验

访问你的控制面板以：

• 启用或禁用审阅功能，例如 Sourcery 生成的 pull request 摘要、审阅者指南等。
• 更改审阅语言。
• 添加、移除或编辑自定义审阅说明。
• 调整其他审阅设置。

获取帮助

• 联系技术支持团队，提出问题或反馈意见。
• 访问我们的文档，获取详细指南和信息。
• 通过关注我们的 X/Twitter、LinkedIn 或 GitHub 与 Sourcery 团队保持联系。

Original review guide in English

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Implements RFC 5987-compliant Content-Disposition filename handling for file downloads to better support non-ASCII filenames across browsers.

File-Level Changes

Change	Details	Files
Update file download response to use RFC 5987-compatible Content-Disposition header with both ASCII and UTF-8 filenames.	Derive an ASCII-only filename variant from the original filename for the legacy filename parameter. URL-encode the UTF-8 version of the original filename for use in the filename* parameter. Set the Content-Disposition header to include both filename and filename* values while preserving existing media type and Content-Length handling.	service/handler/api/v1/files.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

你好，我已经查看了你的修改，这里有一些反馈：

• 在构造 ASCII 回退文件名时，建议处理“原始文件名完全为非 ASCII（例如纯中文文件名）”的情况，以避免 ascii_filename 变成空字符串。可以在这种情况下回退到一个安全的默认值或原始文件名。
• 确保 utf8_filename 的转义符合 RFC 5987：检查 quote 的用法（例如 safe 参数），并对 ascii_filename 中的双引号、反斜杠等潜在问题字符进行清理或转义，以避免生成不合法的 Content-Disposition 头。

给 AI Agent 的提示

Please address the comments from this code review:

## Overall Comments
- When constructing the ASCII fallback filename, consider handling the case where the original filename is entirely non-ASCII (e.g., Chinese-only names) so that `ascii_filename` doesn’t become empty, for example by falling back to a safe default or the original name.
- Ensure the `utf8_filename` quoting is RFC 5987–compliant by verifying the `quote` usage (e.g., `safe` parameter) and sanitizing or escaping problematic characters like double quotes or backslashes in `ascii_filename` to avoid malformed `Content-Disposition` headers.

## Individual Comments

### Comment 1
<location> `service/handler/api/v1/files.py:277` </location>
<code_context>

+        # Encode filename for Content-Disposition header (RFC 5987)
+        # Support both ASCII and UTF-8 filenames for better browser compatibility
+        ascii_filename = file_record.original_filename.encode("ascii", "ignore").decode("ascii")
+        utf8_filename = quote(file_record.original_filename.encode("utf-8"))
+
</code_context>

<issue_to_address>
**suggestion:** Dropping all non-ASCII characters may yield an empty or misleading `filename` value.

Because `.encode("ascii", "ignore")` drops non-ASCII characters, a fully non-ASCII `original_filename` will produce an empty `ascii_filename`, which some older user agents may display instead of `filename*`. It would be safer to map non-ASCII characters to a placeholder (e.g. `_` or `?`) and/or fall back to a generic filename if the ASCII result ends up empty.

Suggested implementation:

```python
from io import BytesIO
import os
from urllib.parse import quote
from uuid import UUID

```

```python
        # Encode filename for Content-Disposition header (RFC 5987)
        # Support both ASCII and UTF-8 filenames for better browser compatibility
        original_filename = file_record.original_filename or "download"
        # Replace non-ASCII (or otherwise unsafe) characters with a placeholder
        ascii_filename = "".join(
            ch if ch.isascii() and ch not in ['"', "\\"] else "_"
            for ch in original_filename
        ).strip()
        # Fall back to a generic ASCII filename if everything was replaced
        if not ascii_filename:
            base, ext = os.path.splitext(original_filename)
            ascii_filename = f"download{ext}" if ext else "download"
        utf8_filename = quote(file_record.original_filename.encode("utf-8"))

```
</issue_to_address>

---

Sourcery 对开源项目是免费的——如果你觉得我们的评审有帮助，欢迎分享 ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{帮我变得更有用！请在每条评论上点击 👍 或 👎，我会根据你的反馈改进后续的评审。}

Original comment in English

Hey there - I've reviewed your changes - here's some feedback:

• When constructing the ASCII fallback filename, consider handling the case where the original filename is entirely non-ASCII (e.g., Chinese-only names) so that ascii_filename doesn’t become empty, for example by falling back to a safe default or the original name.
• Ensure the utf8_filename quoting is RFC 5987–compliant by verifying the quote usage (e.g., safe parameter) and sanitizing or escaping problematic characters like double quotes or backslashes in ascii_filename to avoid malformed Content-Disposition headers.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- When constructing the ASCII fallback filename, consider handling the case where the original filename is entirely non-ASCII (e.g., Chinese-only names) so that `ascii_filename` doesn’t become empty, for example by falling back to a safe default or the original name.
- Ensure the `utf8_filename` quoting is RFC 5987–compliant by verifying the `quote` usage (e.g., `safe` parameter) and sanitizing or escaping problematic characters like double quotes or backslashes in `ascii_filename` to avoid malformed `Content-Disposition` headers.

## Individual Comments

### Comment 1
<location> `service/handler/api/v1/files.py:277` </location>
<code_context>

+        # Encode filename for Content-Disposition header (RFC 5987)
+        # Support both ASCII and UTF-8 filenames for better browser compatibility
+        ascii_filename = file_record.original_filename.encode("ascii", "ignore").decode("ascii")
+        utf8_filename = quote(file_record.original_filename.encode("utf-8"))
+
</code_context>

<issue_to_address>
**suggestion:** Dropping all non-ASCII characters may yield an empty or misleading `filename` value.

Because `.encode("ascii", "ignore")` drops non-ASCII characters, a fully non-ASCII `original_filename` will produce an empty `ascii_filename`, which some older user agents may display instead of `filename*`. It would be safer to map non-ASCII characters to a placeholder (e.g. `_` or `?`) and/or fall back to a generic filename if the ASCII result ends up empty.

Suggested implementation:

```python
from io import BytesIO
import os
from urllib.parse import quote
from uuid import UUID

```

```python
        # Encode filename for Content-Disposition header (RFC 5987)
        # Support both ASCII and UTF-8 filenames for better browser compatibility
        original_filename = file_record.original_filename or "download"
        # Replace non-ASCII (or otherwise unsafe) characters with a placeholder
        ascii_filename = "".join(
            ch if ch.isascii() and ch not in ['"', "\\"] else "_"
            for ch in original_filename
        ).strip()
        # Fall back to a generic ASCII filename if everything was replaced
        if not ascii_filename:
            base, ext = os.path.splitext(original_filename)
            ascii_filename = f"download{ext}" if ext else "download"
        utf8_filename = quote(file_record.original_filename.encode("utf-8"))

```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

suggestion: 丢弃所有非 ASCII 字符可能会导致 filename 为空或产生误导性的值。

由于 .encode("ascii", "ignore") 会丢弃非 ASCII 字符，如果 original_filename 完全由非 ASCII 字符组成，那么生成的 ascii_filename 将会是空字符串，而某些老旧的用户代理可能会显示这个值，而不是 filename*。更安全的做法是把非 ASCII 字符映射为占位符（例如 _ 或 ?），并且在 ASCII 结果为空时回退到一个通用的文件名。

建议的实现方式：

from io import BytesIO
import os
from urllib.parse import quote
from uuid import UUID

        # Encode filename for Content-Disposition header (RFC 5987)
        # Support both ASCII and UTF-8 filenames for better browser compatibility
        original_filename = file_record.original_filename or "download"
        # Replace non-ASCII (or otherwise unsafe) characters with a placeholder
        ascii_filename = "".join(
            ch if ch.isascii() and ch not in ['"', "\\"] else "_"
            for ch in original_filename
        ).strip()
        # Fall back to a generic ASCII filename if everything was replaced
        if not ascii_filename:
            base, ext = os.path.splitext(original_filename)
            ascii_filename = f"download{ext}" if ext else "download"
        utf8_filename = quote(file_record.original_filename.encode("utf-8"))

Original comment in English

suggestion: Dropping all non-ASCII characters may yield an empty or misleading filename value.

Because .encode("ascii", "ignore") drops non-ASCII characters, a fully non-ASCII original_filename will produce an empty ascii_filename, which some older user agents may display instead of filename*. It would be safer to map non-ASCII characters to a placeholder (e.g. _ or ?) and/or fall back to a generic filename if the ASCII result ends up empty.

Suggested implementation:

from io import BytesIO
import os
from urllib.parse import quote
from uuid import UUID

        # Encode filename for Content-Disposition header (RFC 5987)
        # Support both ASCII and UTF-8 filenames for better browser compatibility
        original_filename = file_record.original_filename or "download"
        # Replace non-ASCII (or otherwise unsafe) characters with a placeholder
        ascii_filename = "".join(
            ch if ch.isascii() and ch not in ['"', "\\"] else "_"
            for ch in original_filename
        ).strip()
        # Fall back to a generic ASCII filename if everything was replaced
        if not ascii_filename:
            base, ext = os.path.splitext(original_filename)
            ascii_filename = f"download{ext}" if ext else "download"
        utf8_filename = quote(file_record.original_filename.encode("utf-8"))

[codecov]

Codecov Report

❌ Patch coverage is 33.33333% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
service/handler/api/v1/files.py	33.33%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!