feat: Add asynchronous SBOM support

[tunztunztunz]

Adds GenerateSBOM and FetchSBOM to generate and retrieve SBOMs asynchronously.

• Rate limits: Fetching uses the core allowance, so exhausting the SBOM allowance does not block polling. Confirmed through x-ratelimit-resource on live requests.
• Response shape: Downloads contain the SPDX document without the legacy endpoint’s sbom wrapper. I compared both responses from one repository and found the same fields, so FetchSBOM wraps the download to return the existing SBOM type.
• Authentication: The download client must omit authentication because signed URLs reject tokens. GitHub checks repository access before redirecting.

Testing

Tests cover generation, polling, redirects, downloads, errors, and rate-limit selection. Manually tested generation and download with a scratch program against large public repositories and private repositories.

Questions

• Should download errors redact signed URLs? Transport errors can include the full URL, potentially exposing access to the report until the link expires.
• Is SBOMGeneration.UUID() worth keeping? Generation and fetching are usually called together, so I figured this would save callers the trouble of extracting the UUID themselves.
• Should FetchSBOM return the existing SBOM type for consistency with GetSBOM, or return SBOMInfo directly to match the unwrapped download?

AI disclosure: assisted with implementation, tests, and this PR body.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.57%. Comparing base (9905978) to head (102b574).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #4543   +/-   ##
=======================================
  Coverage   98.57%   98.57%           
=======================================
  Files         197      197           
  Lines       18252    18291   +39     
=======================================
+ Hits        17991    18030   +39     
  Misses        261      261           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gmlewis]

Questions

• Should download errors redact signed URLs? Transport errors can include the full URL, potentially exposing access to the report until the link expires.

No, in general we do not attempt to anticipate what users of these methods wish to do with the responses.
So I recommended that we pass back the response and let the user decide what to do after that.

• Is SBOMGeneration.UUID() worth keeping? Generation and fetching are usually called together, so I figured this would save callers the trouble of extracting the UUID themselves.

No, for the same reason stated above.

• Should FetchSBOM return the existing SBOM type for consistency with GetSBOM, or return SBOMInfo directly to match the unwrapped download?

I find having a // GetSBOM fetches the software bill of materials for a repository. AND a FetchSBOM to be very confusing from a user's standpoint. "Should I GetSBOM which fetches, or should I FetchSBOM instead?"

I'm thinking that either we don't need both or we need better names for both and maybe much clearer documentation as to WHEN to use one method over another.

[tunztunztunz]

I find having a // GetSBOM fetches the software bill of materials for a repository. AND a FetchSBOM to be very confusing from a user's standpoint. "Should I GetSBOM which fetches, or should I FetchSBOM instead?"

I agree. I was a little worried about submitting a PR that removes existing functionality 😅

On November 13 GitHub plans to replace the synchronous workflow used by GetSBOM with the asynchronous workflow this PR is adding. Is it reasonable to remove it altogether in this PR or would you prefer deprecating it now with a comment and looping back on the November 13 to fully remove it after the endpoint is retired?

I'm now wondering if it would be clearer to split FetchSBOM into two explicitly named methods, like DownloadSBOM which downloads and returns the report, andGetSBOMDownloadURL, which only return the temporary download URL. The current implementation follows the pattern established by RepositoriesService.DownloadReleaseAsset, where supplying a client controls whether the redirect is followed.

[gmlewis]

I find having a // GetSBOM fetches the software bill of materials for a repository. AND a FetchSBOM to be very confusing from a user's standpoint. "Should I GetSBOM which fetches, or should I FetchSBOM instead?"

I agree. I was a little worried about submitting a PR that removes existing functionality 😅

On November 13 GitHub plans to replace the synchronous workflow used by GetSBOM with the asynchronous workflow this PR is adding. Is it reasonable to remove it altogether in this PR or would you prefer deprecating it now with a comment and looping back on the November 13 to fully remove it after the endpoint is retired?

OK, so yes, I think it makes sense to officially deprecate the existing GetSBOM endpoint and since the official API endpoint says "fetch software bill of materials" in it, I think your FetchSBOM name is appropriate and reasonable.
Thank you for the extra context.

I'm now wondering if it would be clearer to split FetchSBOM into two explicitly named methods, like DownloadSBOM which downloads and returns the report, andGetSBOMDownloadURL, which only return the temporary download URL. The current implementation follows the pattern established by RepositoriesService.DownloadReleaseAsset, where supplying a client controls whether the redirect is followed.

Honestly, I'm fine either way, @Not-Dhananjay-Mishra might have some opinions about this.

Please go ahead and address the earlier comments and add the deprecation comment and then I think we can continue with this PR.

[Not-Dhananjay-Mishra]

I think both designs are reasonable. But I am more inclined toward keeping only FetchSBOM, mainly because GitHub API titled it as "Fetch a software bill of materials (SBOM) for a repository." Also, as you mentioned that,

The current implementation follows the pattern established by RepositoriesService.DownloadReleaseAsset, where supplying a client controls whether the redirect is followed.

[tunztunztunz]

@gmlewis Okay. I believe I addressed your comments.

• Removed the UUID helper function and adjusted the comments to explain that callers need to grab the UUID from the returned URL.
• Added a deprecation comment to the GetSBOM.
• Per @Not-Dhananjay-Mishra's comment, I kept the current design of FetchSBOM as is.
• Codecov pointed out a missing line of coverage, so I added TestDependencyGraphService_fetchSBOMFromURL_unparsableURL to test fetchSBOMFromURL directly with an unparsable URL.
• Left download errors as-is.

[gmlewis]

Thank you, @tunztunztunz!
LGTM.

cc: @Not-Dhananjay-Mishra