Draft: Limit content_sha256 computation for large files in Files API

What does this MR do and why?

Problem

Computing content_sha256 loads the full blob through Gitaly GetBlob, which always uses the fast timeout, regardless of the HTTP method. For large files, Files API metadata, raw, and blame requests can exceed that timeout and return a 500 error (GRPC::DeadlineExceeded), even though these endpoints don't need the full file content.

Solution

  • For files up to 10 MB (CONTENT_SHA_MAX_SIZE), compute content_sha256 as before.
  • For larger files, return the SHA from the cache if it exists. Otherwise, omit the X-Gitlab-Content-Sha256 header.
  • Apply this to:
    • HEAD /projects/:id/repository/files/:file_path
    • GET and HEAD /projects/:id/repository/files/:file_path/blame
    • GET and HEAD /projects/:id/repository/files/:file_path/raw
  • Keep GET /projects/:id/repository/files/:file_path unchanged. This endpoint already loads the full content, so it always returns the SHA.
  • Keep the order of keys in the response unchanged.
  • Document that the header can be missing for large files, and recommend X-Gitlab-Blob-Id instead.

Behavior change

  • Files larger than 10 MB that return X-Gitlab-Content-Sha256 today no longer return it, unless the SHA is cached. Cache entries expire after 8 hours by default.
  • Files that fail with a 500 error today now return a successful response without the header.

Because this changes REST API v4 behavior, it needs approval from an API maintainer.

References

Closes #604992

Screenshots or screen recordings

Not applicable. This change has no visual impact.

How to set up and validate locally

Not applicable.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist.

Edited by Vasilii Iakliushin

Merge request reports

Loading
Loading