Shanty/Main
1
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases Wiki Activity

Implement the Actix web backend for shanty-web #9

New Issue
Closed
opened 2026-03-17 16:24:56 -04:00 by connor · 0 comments
connor commented 2026-03-17 16:24:56 -04:00
Owner
Copy Link

The shanty-web crate is the Actix-web backend that ties all the other crates together and exposes a REST API for the Elm frontend. This is the "brain" of Shanty when used as a web application — it orchestrates indexing, tagging, downloading, and everything else through HTTP endpoints.

This issue covers the backend API. The frontend (Elm) is a separate issue.

  1. Core API endpoints:

    Library / Watchlist

    • GET /api/artists — list all artists in the library (with filter/pagination)
    • GET /api/artists/:id — get artist details including albums and watchlist status
    • POST /api/artists — add an artist to the watchlist
    • DELETE /api/artists/:id — remove an artist from the watchlist
    • GET /api/albums — list all albums (with filter/pagination)
    • GET /api/albums/:id — get album details including tracks
    • POST /api/albums — add an album to the watchlist
    • GET /api/tracks — list all tracks (with filter/pagination)
    • GET /api/tracks/:id — get track details

    Search

    • GET /api/search/artist?q=<query> — search for artists online
    • GET /api/search/album?q=<query>&artist=<artist> — search for albums online
    • GET /api/search/track?q=<query>&artist=<artist> — search for tracks online
    • GET /api/search/discography/:artist_id — get an artist's full discography

    Downloads

    • POST /api/downloads — trigger a download (by query or URL)
    • GET /api/downloads/queue — get the current download queue
    • POST /api/downloads/retry/:id — retry a failed download
    • DELETE /api/downloads/:id — cancel/remove a download

    System

    • GET /api/status — system status (DB stats, queue length, currently running tasks)
    • POST /api/index — trigger a library re-scan
    • POST /api/tag — trigger auto-tagging for untagged tracks
    • GET /api/config — get current configuration
    • PUT /api/config — update configuration

  2. Background task system — long-running operations (indexing, tagging, bulk downloads) should run as background tasks. The API should:

    • Return immediately with a task ID
    • Provide a GET /api/tasks/:id endpoint to check task progress
    • Support WebSocket or SSE for real-time progress updates to the frontend

  3. Configuration — the web app needs a configuration system:

    • Music library root directory
    • Database path
    • Download output directory
    • Organization format template
    • Auto-tagging settings
    • Port/bind address
    • Use a TOML or YAML config file, with environment variable overrides

  4. Static file serving — serve the compiled Elm frontend from a static directory

  5. Error handling — consistent JSON error responses with appropriate HTTP status codes

Design Considerations

  • Use actix-web as specified in the design doc.
  • Each crate's library API should be called directly — don't shell out to the CLI binaries.
  • Consider using actix-rt for spawning background tasks.
  • API responses should use consistent pagination (offset/limit or cursor-based).
  • Consider CORS configuration for development (Elm dev server on a different port).

Acceptance Criteria

  • Actix-web server starts and serves the API on a configurable port
  • All listed API endpoints are implemented and return appropriate JSON responses
  • Background tasks work for long-running operations (indexing, tagging)
  • Task progress can be queried
  • Configuration is loaded from a TOML file with env var overrides
  • Static file serving works for the frontend
  • Error responses are consistent JSON with proper status codes
  • Pagination works on list endpoints
  • CORS is configured for development
  • Integration tests exist for the key API endpoints
  • The server gracefully shuts down (completes in-progress tasks)

Dependencies

  • Issue #1 (workspace scaffolding)
  • Issue #2 (shared database schema)
  • Issue #3 (music indexing)
  • Issue #4 (music tagging)
  • Issue #6 (watchlist management)
  • Issue #7 (music downloading)
  • Issue #8 (music searching)
The `shanty-web` crate is the Actix-web backend that ties all the other crates together and exposes a REST API for the Elm frontend. This is the "brain" of Shanty when used as a web application — it orchestrates indexing, tagging, downloading, and everything else through HTTP endpoints. This issue covers the backend API. The frontend (Elm) is a separate issue. 1. **Core API endpoints:** **Library / Watchlist** - `GET /api/artists` — list all artists in the library (with filter/pagination) - `GET /api/artists/:id` — get artist details including albums and watchlist status - `POST /api/artists` — add an artist to the watchlist - `DELETE /api/artists/:id` — remove an artist from the watchlist - `GET /api/albums` — list all albums (with filter/pagination) - `GET /api/albums/:id` — get album details including tracks - `POST /api/albums` — add an album to the watchlist - `GET /api/tracks` — list all tracks (with filter/pagination) - `GET /api/tracks/:id` — get track details **Search** - `GET /api/search/artist?q=<query>` — search for artists online - `GET /api/search/album?q=<query>&artist=<artist>` — search for albums online - `GET /api/search/track?q=<query>&artist=<artist>` — search for tracks online - `GET /api/search/discography/:artist_id` — get an artist's full discography **Downloads** - `POST /api/downloads` — trigger a download (by query or URL) - `GET /api/downloads/queue` — get the current download queue - `POST /api/downloads/retry/:id` — retry a failed download - `DELETE /api/downloads/:id` — cancel/remove a download **System** - `GET /api/status` — system status (DB stats, queue length, currently running tasks) - `POST /api/index` — trigger a library re-scan - `POST /api/tag` — trigger auto-tagging for untagged tracks - `GET /api/config` — get current configuration - `PUT /api/config` — update configuration 2. **Background task system** — long-running operations (indexing, tagging, bulk downloads) should run as background tasks. The API should: - Return immediately with a task ID - Provide a `GET /api/tasks/:id` endpoint to check task progress - Support WebSocket or SSE for real-time progress updates to the frontend 3. **Configuration** — the web app needs a configuration system: - Music library root directory - Database path - Download output directory - Organization format template - Auto-tagging settings - Port/bind address - Use a TOML or YAML config file, with environment variable overrides 4. **Static file serving** — serve the compiled Elm frontend from a static directory 5. **Error handling** — consistent JSON error responses with appropriate HTTP status codes ### Design Considerations - Use `actix-web` as specified in the design doc. - Each crate's library API should be called directly — don't shell out to the CLI binaries. - Consider using `actix-rt` for spawning background tasks. - API responses should use consistent pagination (offset/limit or cursor-based). - Consider CORS configuration for development (Elm dev server on a different port). ### Acceptance Criteria - [ ] Actix-web server starts and serves the API on a configurable port - [ ] All listed API endpoints are implemented and return appropriate JSON responses - [ ] Background tasks work for long-running operations (indexing, tagging) - [ ] Task progress can be queried - [ ] Configuration is loaded from a TOML file with env var overrides - [ ] Static file serving works for the frontend - [ ] Error responses are consistent JSON with proper status codes - [ ] Pagination works on list endpoints - [ ] CORS is configured for development - [ ] Integration tests exist for the key API endpoints - [ ] The server gracefully shuts down (completes in-progress tasks) ### Dependencies - Issue #1 (workspace scaffolding) - Issue #2 (shared database schema) - Issue #3 (music indexing) - Issue #4 (music tagging) - Issue #6 (watchlist management) - Issue #7 (music downloading) - Issue #8 (music searching)
connor added the HighPriorityMVP labels 2026-03-17 16:25:02 -04:00
connor started working 2026-03-17 21:41:44 -04:00
connor worked for 18 minutes 2026-03-17 21:59:52 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
LowPriority
MediumPriority
HighPriority
MVP
No Label HighPriority MVP
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
connor
No Assignees
1 Participants
Notifications
Total Time Spent: 18 minutes
connor
18 minutes
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Shanty/Main#9
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?