GraphQL specification не определяет передачу binary-файлов. Если клиент отправляет multipart/form-data, он использует отдельную community convention, которую должны одинаково понимать client, gateway и server. Base64 внутри JSON тоже не решает задачу: payload увеличивается, файл буферизуется и хуже обрабатывается потоком. Устойчивый вариант — оставить в GraphQL только выдачу разрешения и привязку результата.
Сначала найдите этап отказа. Ответ 413 от proxy, GraphQL validation error, пустой Upload в resolver и объект в storage без записи в базе — четыре разные поломки. Не увеличивайте общий body limit до сотен мегабайт, пока не доказано, что binary действительно должен проходить через GraphQL service.
Статус ответа указывает на сломанный слой
| Симптом | Вероятная граница | Проверка |
|---|---|---|
| 413 до GraphQL error body | CDN, ingress или proxy body limit | Сравнить access logs и Content-Length |
| 415 или parser error | Content-Type и multipart middleware | Снять безопасные headers и operations/map |
| Validation failed до resolver | Schema или variable mapping | Проверить operation и одноразовое использование Upload |
| Resolver стартовал, stream пуст | Файл уже прочитан или закрыт | Проверить lifecycle stream |
| Storage object есть, запись отсутствует | Финальная mutation или transaction | Проверить upload state и idempotency |
Не логируйте binary, signed URL целиком или multipart body: URL обычно является временным credential. Для трассировки достаточно upload ID, размера, заявленного и определённого content type, этапа и request ID. Имена файлов поступают от пользователя и не должны становиться путём на сервере.
GraphQL становится диспетчером загрузки
mutation CreateUpload($input: CreateUploadInput!) {
createUpload(input: $input) {
uploadId
objectKey
method
signedUrl
requiredHeaders
expiresAt
}
}
# client uploads binary directly to signedUrl
mutation AttachUpload($uploadId: ID!, $ownerId: ID!) {
attachUpload(uploadId: $uploadId, ownerId: $ownerId) { id status }
}Названия условны. Первая mutation проверяет право создать файл для конкретного owner, разрешённый размер и тип, формирует непредсказуемый object key и короткое разрешение только на upload этого объекта. Вторая заново проверяет владельца, убеждается, что объект существует и соответствует ограничениям, затем идемпотентно связывает его с domain record.
Три шага имеют независимые критерии успеха
- Create: запись pending принадлежит principal и содержит ожидаемые size, type и expiry.
- Transfer: storage принимает только заданный method, key, срок и нужные headers.
- Verify: backend читает metadata из storage, а не доверяет словам клиента.
- Scan: файл проходит антивирусную и форматную проверку до публичного использования.
- Attach: mutation повторно проверяет owner и допускает безопасный повтор.
- Publish: приложение отдаёт файл через контролируемый URL и disposition.
- Cleanup: unattached и expired objects удаляются ограниченным фоновым процессом.
Клиентский ответ upload успешен ещё не означает, что файл допустим. MIME из браузера и расширение имени недоверенны; сервер определяет тип по содержимому и применяет проверки конкретного формата. Zip, PDF и изображения требуют собственных лимитов, потому что маленький compressed файл способен резко вырасти при обработке.
Signed URL ограничиваем сильнее сессии пользователя
- Короткий срок действия и только одна операция над одним object key.
- Максимальный размер, допустимый content type и обязательные headers, если storage это поддерживает.
- Непредсказуемый key, который не содержит исходное имя, email или tenant slug.
- Bucket не является публичным, а чтение выдаётся отдельным решением.
- Upload ID нельзя прикрепить к объекту другого tenant.
- Pending quota не позволяет запросить тысячи URL и заполнить storage.
GraphQL Foundation рекомендует signed URLs как более безопасный и масштабируемый путь: mutation выдаёт URL, client загружает напрямую, вторая mutation связывает файл. Неоконченные uploads удерживают коротко и затем удаляют, иначе атакующий сможет заполнить storage, выполняя только первые два шага.
Если multipart оставить, защита становится обязательной
Иногда прямой upload недоступен из-за legacy клиента. Тогда используйте поддерживаемую реализацию multipart convention, требуйте CSRF-защиту, ограничивайте body и число файлов, разрешайте каждую Upload variable ровно один раз, streaming направляйте в временное storage и закрывайте все streams при validation или authorization error. Любой неиспользованный multipart part отклоняется.
Gateway, WAF и GraphQL server должны согласовать allowed Content-Type и preflight policy. Нельзя отключать CSRF middleware только ради того, чтобы multipart снова заработал: form request способен пройти без CORS preflight. Отдельный upload endpoint или signed URL обычно проще защитить и наблюдать.
Контрольный набор проверяет не только happy path
valid small file -> uploaded, scanned, attached
expired signed URL -> rejected by storage
oversized body -> rejected before buffering
type mismatch -> quarantined or rejected
uploadId from other tenant -> forbidden
repeat attach mutation -> same result, no duplicate
created but not attached -> removed after retention windowПриёмка также включает отмену upload, разрыв сети, retry одного chunk или request, параллельное attach и отказ scanner. Для разбора подготовьте GraphQL server и gateway versions, безопасные request headers, лимиты каждого слоя, upload state timeline и storage metadata без signed URL. После перехода очистите legacy temporary files и отключите старый multipart route только после подтверждения клиентов.