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 bodyCDN, ingress или proxy body limitСравнить access logs и Content-Length
415 или parser errorContent-Type и multipart middlewareСнять безопасные headers и operations/map
Validation failed до resolverSchema или 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.

Три шага имеют независимые критерии успеха

  1. Create: запись pending принадлежит principal и содержит ожидаемые size, type и expiry.
  2. Transfer: storage принимает только заданный method, key, срок и нужные headers.
  3. Verify: backend читает metadata из storage, а не доверяет словам клиента.
  4. Scan: файл проходит антивирусную и форматную проверку до публичного использования.
  5. Attach: mutation повторно проверяет owner и допускает безопасный повтор.
  6. Publish: приложение отдаёт файл через контролируемый URL и disposition.
  7. 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 только после подтверждения клиентов.

Проверенные источники