Skip to content

ref(service): Classify service errors by kind#493

Open
lcian wants to merge 20 commits into
mainfrom
lcian/feat/proper-errors-v3
Open

ref(service): Classify service errors by kind#493
lcian wants to merge 20 commits into
mainfrom
lcian/feat/proper-errors-v3

Conversation

@lcian

@lcian lcian commented Jun 8, 2026

Copy link
Copy Markdown
Member

This is a different take on giving us more control over HTTP status codes when erroring out from the service layer that doesn't make callers more verbose, but actually less so in some cases.

  1. ServiceError variants gain a kind that's used to determine log level and HTTP status code when converting to ApiErrorResponse. The kind is implemented via https://crates.io/crates/derive-error-kind which lets us do it concisely via a error_kind attribute on each variant. This is a very simple proc macro that we could also vendor in.

  2. Existing constructors for specific Error variants remain, and map to ErrorKind::Internal.

  3. For errors that could map to different kinds depending on the context, we also introduce additional intermediate wrapper types (needed to support different kinds) and constructors on ServiceError.
    Namely: reqwest_transparent (alternative to the existing reqwest helper), serde_client (alternative to the existing serde helper), and the metadata/metadata_client pair.

  4. As a special case, we implement From<std::io::Error> for Error so that callers can keep using ? to propagate io errors. That's because so far we always want io::Error to map to ErrorKind::internal, so there's no reason to make callers more verbose in this case.
    This has the added benefit that the impl can encapsulate the unpack_client_error logic, to avoid repeating it in every caller.

  5. Also renames ClientError to ClientStreamError as that's a less confusing name.

Refs FS-358

@codecov

This comment has been minimized.

@lcian lcian changed the title ref(service): Classify service errors by kind ref(service): Refactor Error Jun 8, 2026
@lcian lcian changed the title ref(service): Refactor Error feat(service): Refactor Error Jun 8, 2026
@lcian lcian force-pushed the lcian/feat/proper-errors-v3 branch from 9ca4473 to 2953792 Compare June 8, 2026 11:56
@lcian lcian changed the title feat(service): Refactor Error ref(service): Classify service errors by kind Jun 8, 2026
Add service-level error kinds so API handlers can map failures without matching every backend-specific variant. Keep client metadata errors distinct from internal metadata failures and classify transient backend failures as retryable/service-unavailable paths.

Co-Authored-By: OpenAI Codex <noreply@openai.com>
@lcian lcian force-pushed the lcian/feat/proper-errors-v3 branch from 2953792 to 445c724 Compare June 8, 2026 12:13
lcian and others added 9 commits June 8, 2026 14:30
Remove private wrapper constructor helpers that only duplicated the public Error helpers. Keep classification policy in the public constructors so call sites have fewer names to reason about.

Co-Authored-By: OpenAI Codex <noreply@openai.com>
Remove the service Error conversion from objectstore metadata errors. Map metadata parsing and serialization failures at each backend call site so the context and classification stay visible.

Co-Authored-By: OpenAI Codex <noreply@openai.com>
Update stream documentation links after the client stream error rename. This keeps rustdoc clean under CI's denied warnings.

Co-Authored-By: OpenAI Codex <noreply@openai.com>
Move reqwest retryability out of the shared error wrapper and back next to the GCS retry loop. Let ReqwestError handle only construction and service-level classification.

Co-Authored-By: OpenAI Codex <noreply@openai.com>
@linear-code

linear-code Bot commented Jun 8, 2026

Copy link
Copy Markdown

FS-358

let metadata_headers = metadata.to_headers("").map_err(ServiceError::from)?;
let metadata_headers = metadata
.to_headers("")
.map_err(|cause| ServiceError::metadata("failed to serialize object metadata", cause))?;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Improvement: here we have a valid Metadata, it's therefore our fault if we fail to serialize it, and now we can correctly map this to an internal error as opposed to always blaming the client.

@lcian lcian marked this pull request as ready for review June 8, 2026 14:23
@lcian lcian requested a review from a team as a code owner June 8, 2026 14:23
@lcian lcian requested a review from matt-codecov June 8, 2026 14:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant