5 - API (feat): Improved Errors

[RobertRosca]

PR no. 5 of the big refactor.

This PR expands on the DWError exception, creating a few explicit Errors based on that which should be used throughout the application code whenever an error/failure needs to be raised to be shown to the client, and adds in code to handle the errors at the request 'edge' (rest, graphql) so that the right response is sent to the client.

Details

Previously the API used builtin/re-raised exceptions, which makes it hard to tell if an error is 'expected' (missing proposal, upstream service, permission denial, etc...) or not (random bug in our code/a dependency, divide by zero, unexpected None, etc...), which makes it harder to dispatch to the right handler.

ADR-001 explains this in more detail and says that there should be an easy way to figure out what error response to send to a client, and decides to do this by having some distinct error classes where this happens, with anything else mapped to generic 500 error. To keep things from going very out of control, mapping to a response should be done in one clear place (transport edge/handler).

Error Classes

Errors are in shared/errors.py. The errors are meant to be framework-agnostic/generic-ish, so they aren't subclasses of some specific FastAPI/Starlette/Strawberry/whatever class.

Instead all errors are based on the main error class, DWError, which has fields:

• code: defaults to 500, so it's always defined
• message
• details
• request_id - captured from structlog contextvars at raise time

Currently the following errors are defined:

• InvalidInputError (400)
• UnauthenticatedError (401)
• ForbiddenError (403)
• NotFoundError (404)
  • ProposalNotFoundError
• UpstreamServiceError (502), e.g. MyMdC/Keycloak not available
• DataUnavailableError (503), e.g. issue reading data files (runs.sqlite, hdf5)

Mapping

REST maps a DWError to {"message", "details", "request_id"} with exc.code via a FastAPI exception handler.

According to the ADR, GraphQL maps DWErrors as GraphQL errors with extensions: {code, request_id} so the frontend branches on code rather than message text.

This is a partial lie since that's not in this PR/branch and is included in a later branch in the stack that changes the resolvers, but that's the design.

Tests

test_errors.py covers:

• code attributes
• ProposalNotFoundError -> NotFoundError inheritance
• details/request_id capture (including the unbound-contextvars case)
• FastAPI handler mapping a raised DWError to the right status code and body

[CammilleCC]

Comment aside, LGTM. Error codes and exception names make sense.

[CammilleCC]

LGTM after CI and the rename