review/document client exceptions

[sechkova]

Description of issue or feature request:
Revise and implements client exceptions handling

Current behavior:
Not all thrown exceptions are documented or handled by the client.

Expected behavior:
Implement proper exception handling and document the API

Sync with #1131

[jku]

The major items here are probably:

• bundle (once it's in) should only raise RepositoryError (or anyway a single base error representing failures because remote provided metadata we can't cope with) and user errors like ValueError
• since we removed mirrors, we can longer hide behind NoWorkingMirror -- need to figure out a nice solution. This probably still involves at least one wrapper error as we may get random errors from whatever Fetcher is being used

[jku]

After doing the metadata bundle integration, I think our client exceptions should be grouped like this:

• RepositoryErrors (various): something is wrong with metadata. In some cases this can be handled within client (like in the case of local metadata being no longer signed by correct keys), but in many cases this is an external exception
• OSErrors (various): Failures to read or write local metadata
• RuntimeErrors/ValueErrors/etc: errors that mean API misuse (code should be fixed, exception should not be handled)
• some kind of generic download error: We should define an error that download functions return, wrapping whatever error the FetcherInterface implementation raises. This way the updater public API has a specific error for download failures

[jku]

My impression is that ngclient exceptions are in a pretty good state by now, but review would be good:

• see what exceptions are handled in code using ngclient (like tests)
• review ngclient/trustedmetadataset and see if exceptions seem to make sense

In addition to a review, we should document how ngclient uses exceptions: mostly that RepositoryError is used as a catch all for fatal update errors -- a metadata state that clients cannot recover from, but where a later update (after the remote updates metadata) might succeed.

[jku]

Updated title: I think we're mostly missing proper documentation:

• document our own exceptions
• document OSErrors where necessary (anytime we read or write files)