CD: consistent handling of failed includes via errorStrategy and the shared error handler registry #213

When resolving includes fails, the Compound Documents plugin had no consistent behaviour. The possible failures are a non-2xx response from a service further down, a timeout, a connection error, a response that isn't JSON:API, or a type with no route. Under IGNORE, a partial included could be stored by shared caches for the full max-age. Under FAIL, errors were rendered by a plugin-specific writer instead of the registry every other API error goes through.

Changes:

• IGNORE: failures are isolated per filter[id] batch, and a type with no route is skipped and logged at ERROR. Any response with an incomplete included gets Cache-Control: no-store.
• FAIL: errors are rendered as JSON:API error documents: 504 GATEWAY_TIMEOUT, 502 BAD_GATEWAY, and 500 for a type with no route. No downstream URLs appear in the details, and each error gets a unique id.
• HTTP client: it always throws typed exceptions (DownstreamTimeoutException, ErrorJsonApiResponseException, DomainResolutionException), and it parses Cache-Control into CacheControlDirectives.
• Error-handling API: it moves from jsonapi4j-rest to jsonapi4j-base, in pro.api4.jsonapi4j.errorhandling.
  • Plugins contribute handlers through JsonApi4jPlugin#errorHandlerFactory(). These are added when JsonApi4j is built and never override mappings from the application or framework.
  • ErrorsDocResponseWriter is shared by the dispatcher servlet, the CD filter and OasServlet.
• DomainSettingsResolver.requireDomainSettings(type): a new default method that resolves a route or throws DomainResolutionException. SelfFallbackRouting passes a null from a custom resolver through, so the broken contract is reported clearly.
• Docs: the CD plugin page has a new "Error handling" section, and the error-handling page shows the new packages and how plugins contribute handlers.

Breaking: the error-handling classes have moved package, from pro.api4.jsonapi4j.servlet.response.errorhandling to pro.api4.jsonapi4j.errorhandling.