Add error handling strategy and shared error types #12

New Issue

connor · 2026-03-17T16:30:12-04:00

connor commented

2026-03-17 16:30:12 -04:00

As a multi-crate workspace, Shanty needs a consistent error handling strategy. Each crate will have its own error conditions, but they need to compose cleanly — especially when the web backend calls into library crates and needs to translate errors into HTTP responses.

This issue covers:

Shared error types — create an error module (in shanty-db or a new shanty-core crate) that defines:
- A base error enum that other crates can extend or wrap
- Common error variants: DatabaseError, IoError, NetworkError, ConfigError, NotFoundError, ExternalToolError (for yt-dlp, etc.)
- Implement std::error::Error, Display, and From conversions for common types
- Consider using thiserror for ergonomic error type derivation
Per-crate errors — each crate should define its own error type that wraps the shared errors plus crate-specific variants. For example, shanty-tag might have TagError::NoMatchFound, TagError::ApiRateLimited, etc.
Web error mapping — in shanty-web, implement actix_web::ResponseError for the error types so they automatically convert to appropriate HTTP responses (404 for NotFound, 500 for internal errors, 429 for rate limits, etc.)
Result type alias — define a Result<T> = std::result::Result<T, ShantyError> alias for convenience

Acceptance Criteria

Shared error types exist and are usable by all crates
thiserror (or equivalent) is used for clean error type definitions
Each crate has its own error type wrapping the shared base
Web errors map to correct HTTP status codes
Error messages are user-friendly (not raw debug output)
From implementations allow easy error propagation with ?
No unwrap/expect calls in library code (only in tests and CLI main)

Dependencies

Issue #1 (workspace scaffolding)

As a multi-crate workspace, Shanty needs a consistent error handling strategy. Each crate will have its own error conditions, but they need to compose cleanly — especially when the web backend calls into library crates and needs to translate errors into HTTP responses. This issue covers: 1. **Shared error types** — create an error module (in `shanty-db` or a new `shanty-core` crate) that defines: - A base error enum that other crates can extend or wrap - Common error variants: `DatabaseError`, `IoError`, `NetworkError`, `ConfigError`, `NotFoundError`, `ExternalToolError` (for yt-dlp, etc.) - Implement `std::error::Error`, `Display`, and `From` conversions for common types - Consider using `thiserror` for ergonomic error type derivation 2. **Per-crate errors** — each crate should define its own error type that wraps the shared errors plus crate-specific variants. For example, `shanty-tag` might have `TagError::NoMatchFound`, `TagError::ApiRateLimited`, etc. 3. **Web error mapping** — in `shanty-web`, implement `actix_web::ResponseError` for the error types so they automatically convert to appropriate HTTP responses (404 for NotFound, 500 for internal errors, 429 for rate limits, etc.) 4. **Result type alias** — define a `Result<T> = std::result::Result<T, ShantyError>` alias for convenience ### Acceptance Criteria - [ ] Shared error types exist and are usable by all crates - [ ] `thiserror` (or equivalent) is used for clean error type definitions - [ ] Each crate has its own error type wrapping the shared base - [ ] Web errors map to correct HTTP status codes - [ ] Error messages are user-friendly (not raw debug output) - [ ] `From` implementations allow easy error propagation with `?` - [ ] No unwrap/expect calls in library code (only in tests and CLI `main`) ### Dependencies - Issue #1 (workspace scaffolding)

connor added the MVP HighPriority labels 2026-03-17 16:30:12 -04:00

connor removed the HighPriority label 2026-03-17 16:32:14 -04:00

connor started working 2026-03-18 15:15:38 -04:00

connor closed this issue

2026-03-18 15:21:16 -04:00

connor worked for 5 minutes

2026-03-18 15:21:16 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Total Time Spent: 5 minutes

connor

5 minutes

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Shanty/Main#12