Строка `Отчёт + 10%.pdf` проходит минимум через форму, приложение, SDK, подпись URL, объектное хранилище и HTTP-ответ браузеру. Если один слой декодирует её второй раз, `%` станет началом escape-последовательности, `+` превратится в пробел или кириллица распадётся. Лечить это заменой символов в конце слишком поздно.
В S3 object key — Unicode-последовательность в UTF-8 размером до 1024 байт. Слеш является частью key и создаёт видимость папок, хотя модель хранилища плоская. Пользовательское имя файла не обязано становиться key: чаще безопаснее генерировать UUID/key, а исходную строку хранить отдельно.
Три значения не смешиваются
| Значение | Пример | Назначение |
|---|---|---|
| object key | tenant/42/01J….bin | стабильный адрес объекта |
| original filename | Отчёт + 10%.pdf | отображение и аудит |
| download filename | очищенная версия | Content-Disposition браузеру |
| URL-encoded key | tenant/42/01J%E2%80%A6.bin | путь HTTP/подпись |
Не восстанавливайте имя из последнего сегмента key, если оно важно бизнесу. Храните его в своей БД рядом с MIME type, размером и владельцем; пользовательские metadata объекта могут быть дополнительной копией, но не единственным индексом.
Загрузка фиксирует исходную Unicode-строку
- Принять имя как Unicode и ограничить длину в байтах и символах.
- Удалить NUL, управляющие символы и разделители путей для download name.
- Не доверять расширению при определении MIME и безопасности файла.
- При необходимости выбрать одну форму нормализации Unicode и записать её явно.
- Создать независимый object key, не раскрывающий tenant или персональные данные.
NFC и NFD могут выглядеть одинаково, но состоять из разных code points. Это особенно заметно после загрузки с разных ОС. Не нормализуйте молча уже существующие keys: в S3 это разные объекты. Нормализацию лучше ввести на границе новой загрузки и сохранить исходное значение для отображения.
Key кодируется ровно один раз
raw key: tenant/42/Фото #1+.jpg
path segments: [tenant, 42, Фото #1+.jpg]
encode each segment as UTF-8 percent-encoding
keep intentional '/' separators
never encode the already encoded URL againSDK обычно сам формирует канонический запрос и подпись. Если передать ему уже percent-encoded key вместо исходной строки, знак `%` может закодироваться как `%25`, и запрос уйдёт к другому объекту. Зафиксируйте контракт функции: она принимает raw key или URL, но не угадывает по наличию процента.
Браузеру имя задаёт Content-Disposition
RFC 6266 разрешает одновременно передать совместимый ASCII `filename` и расширенный UTF-8 `filename*`; получатель, который понимает оба, должен предпочесть `filename*`. ASCII fallback не обязан побайтно повторять кириллицу — он нужен старым клиентам и должен оставаться безопасным.
Content-Disposition: attachment;
filename="report-10-percent.pdf";
filename*=UTF-8''%D0%9E%D1%82%D1%87%D1%91%D1%82%20%2B%2010%25.pdfЭкранируйте каждый параметр по его синтаксису, а не общей HTML-функцией. Уберите CR/LF, кавычки обрабатывайте корректно, разделители пути не допускайте. Не позволяйте имени изменить заголовки ответа или сохранить файл за пределами выбранной пользователем папки.
Presigned URL подписывает итоговый заголовок
S3 GetObject позволяет переопределить `Content-Disposition` через query-параметр `response-content-disposition`. Для presigned URL этот параметр добавляют до вычисления подписи и кодируют так, как ожидает SDK. Если изменить его после подписания, canonical request уже не совпадёт и хранилище отклонит запрос.
- Взять raw object key из БД.
- Сформировать безопасные filename и filename* из original filename.
- Передать response-content-disposition в параметры SDK GetObject.
- Получить presigned URL с коротким сроком.
- Проверить заголовок фактического ответа и имя в браузере.
Матрица символов находит первый сломанный слой
| Имя | Что проверяет | Частая ошибка |
|---|---|---|
| Фото 1.jpg | UTF-8 и пробел | пробел стал + |
| a+b.txt | literal plus | + превратился в пробел |
| 10%.pdf | literal percent | ошибка decode |
| a#b?.txt | fragment/query | key обрезан в URL |
| ё/ё.txt | NFD/NFC и slash | разные keys/путь |
| "name".csv | quoted filename | сломанный заголовок |
Для каждого случая сравните исходную строку, UTF-8 bytes, key в SDK, canonical request при необходимости, сохранённый key из list/head, заголовок ответа и имя на диске. Не ограничивайтесь тем, что объект «открылся»: неверное имя может проявиться только при скачивании.
Миграция не переименовывает objects вслепую
Переименование в объектном хранилище обычно означает copy в новый key и удаление старого. До массовой операции составьте таблицу old key → new key, проверьте ссылки и версии, сохраните rollback и исключите коллизии Unicode. Если проблема только в download filename, менять object key вообще не нужно.
Для разбора подготовьте один raw key, original filename в JSON-escaped виде, итоговый URL без подписи/секретных параметров, Content-Disposition ответа, используемый SDK и результат матрицы символов. Access key и полный presigned URL передавать нельзя.