ngclient `RequestsFetcher`: make timeout part of the public API

[woodruffw]

Description of issue or feature request:

TrustUpdater in the ngclient APIs can be given a RequestsFetcher to use or, if one is not supplied, will construct a default one.

RequestsFetcher in turn has a default socket timeout (via self.socket_timeout) of 4 seconds, per TUF's mitigations against "slow retrieval"-style attacks.

Unfortunately, this timeout might be too conservative for some real-world network scenarios: CI providers like GitHub Actions will occasionally de-prioritize network traffic, causing failures in tools like sigstore-python that use TUF to bootstrap their roots of trust.

We have a temporary workaround for this as part of sigstore/sigstore-python#432, where we plan to use a timeout of 30s (under the operating theory that this is more than acceptably permissive for GitHub Actions and other CI providers, but still short enough/a hard-failing error mode.) However, that patch requires us to import an _internal API and set an attribute directly, which isn't ideal 🙂

Current behavior:

RequestFetcher is a private API.

Expected behavior:

RequestFetcher becomes part of the ngclient public API surface, and (optionally) has a kwarg in its constructor for configuring the socket_timeout. The current approach of just modifying the attribute is also perfectly fine, given that it isn't currently marked as private.

[jku]

Yeah, original idea was that people who want to tweak things (maybe even use something other than requests) can just create their own Fetcher implementations... but this isn't the first request to just tweak downloading a little: I agree that we could make RequestsFetcher easier to configure. Exposing it in the API seems reasonable.

Implementation should be simple:

• move file from tuf/ngclient/_internal to tuf/ngclient/
• expose the class in tuf/ngclient/__init__.py
• fix any broken imports

[lukpueh]

(adding to implementation instructions)

• make sure it displays correctly on readthedocs

[jku]

Actually maybe we shouldn't just move the file -- that will break sigstore-python 1.0 as

• it's using the _internal module (understandably since there were no alternatives until now)
• it does not pin dependency versions

So I think I'll expose the class but keep the module in _internal and file an issue to move it "some time later"