GRPC::DeadlineExceeded error when querying Files API for large files via HEAD request

Summary

When making a HEAD or GET request to the Repository Files API for very large files, GitLab returns a 500 Internal Server Error due to a gRPC deadline being exceeded while streaming the file content from Gitaly.

Steps to reproduce

  1. Create a project with a very large file (e.g., large_file.bin > 1GB)
  2. Make a HEAD or GET request to the files API endpoint: HEAD /api/v4/projects/:id/repository/files/:file_path?ref=main
curl -I -H "PRIVATE-TOKEN: <TOKEN>" "https://gdk.test:3443/api/v4/projects/<project-path>/repository/files/large_file.bin?ref=main"
  1. Observe a 500 error with GRPC::DeadlineExceeded

What is the current bug behavior?

"4:Stream removed (Deadline Exceeded). debug_error_string:{DEADLINE_EXCEEDED:Stream removed (Deadline Exceeded)}"

The request times out after approximately 10 seconds (the default gitaly_timeout_fast value) because Gitaly takes too long to stream the large file content, even though HEAD requests only need metadata.

The content_sha method in lib/api/files.rb always calls @blob.load_all_data! to compute the SHA256 hash, which requires loading the entire file from Gitaly. For large files, this exceeds the gRPC deadline, causing the connection to be terminated and resulting in a 500 error.

What is the expected correct behavior?

The HEAD request should return quickly with file metadata (including size) without needing to load the entire file content from Gitaly.

Possible fixes

We can add a parameter skip_sha to skip the check when making a HEAD request. This keeps backwards compatibility, in case someone is currently using the sha from the HEAD request.

Edited by 🤖 GitLab Bot 🤖