ML-165: research and plan
This commit is contained in:
Claudio Ortolina
+168
@@ -0,0 +1,168 @@
|
||||
---
|
||||
id: doc-12
|
||||
title: 'Research: Mute and Resolve Production Errors Implementation Routes'
|
||||
type: specification
|
||||
created_date: '2026-05-05 11:24'
|
||||
---
|
||||
# Research: Mute and Resolve Production Errors Implementation Routes
|
||||
|
||||
**Task:** ML-165 — Mute and resolve production errors from pi
|
||||
**Date:** 2026-05-05
|
||||
|
||||
## Current State
|
||||
|
||||
### Backend (Elixir/Phoenix)
|
||||
|
||||
| Component | File | Status |
|
||||
|---|---|---|
|
||||
| Error schema | `deps/error_tracker/lib/error_tracker/schemas/error.ex` | Has `status` (:resolved/:unresolved) and `muted` (boolean) fields |
|
||||
| Error context | `lib/music_library/errors.ex` | Read-only: `list_errors/1`, `get_error/1` — no update functions |
|
||||
| Error controller | `lib/music_library_web/controllers/error_controller.ex` | `GET /api/v1/errors` (index), `GET /api/v1/errors/:id` (show) |
|
||||
| Error JSON views | `lib/music_library_web/controllers/error_json.ex` | Renders error/occurrence data |
|
||||
| Router | `lib/music_library_web/router.ex` | `/api/v1/errors` routes in API scope (Bearer token auth) |
|
||||
| Auth | `lib/music_library_web/auth.ex` | `require_api_token/2` plug — Bearer token comparison |
|
||||
|
||||
### Pi Extension (TypeScript)
|
||||
|
||||
| Component | File | Status |
|
||||
|---|---|---|
|
||||
| prod-errors extension | `.pi/extensions/prod-errors/index.ts` | Tools: `fetch_production_errors`, `fetch_production_error`; Command: `/prod-errors` (TUI browser) |
|
||||
| TUI ErrorBrowser | Same file, `ErrorBrowser` class | List view (no mute/resolve actions), Detail view (no mute/resolve actions) |
|
||||
|
||||
### Gap Analysis
|
||||
|
||||
1. **No mutation endpoints** — The API has no way to update an error's `muted` or `status` fields.
|
||||
2. **No context functions** — `MusicLibrary.Errors` has no `mute_error/1` or `resolve_error/1` (or generic `update_error/2`).
|
||||
3. **No pi tools** — No `mute_production_error` or `resolve_production_error` tool registered.
|
||||
4. **No TUI actions** — The `/prod-errors` ErrorBrowser TUI has no keybindings to mute or resolve errors.
|
||||
|
||||
## Implementation Routes
|
||||
|
||||
### Route A: Dedicated POST Endpoints Per Action (Recommended)
|
||||
|
||||
Add two new routes, each handling a single action:
|
||||
|
||||
```
|
||||
POST /api/v1/errors/:id/mute → sets muted = true
|
||||
POST /api/v1/errors/:id/resolve → sets status = :resolved
|
||||
```
|
||||
|
||||
**Elixir changes:**
|
||||
- `MusicLibrary.Errors`: Add `mute_error/1`, `resolve_error/1` (or a shared private helper)
|
||||
- `MusicLibraryWeb.ErrorController`: Add `mute/2` and `resolve/2` actions
|
||||
- `MusicLibraryWeb.ErrorJSON`: Add `mute/1`, `resolve/1` render functions
|
||||
- `MusicLibraryWeb.Router`: Add two POST routes in the API scope
|
||||
|
||||
**Pi extension changes:**
|
||||
- Register `mute_production_error` tool → POSTs to `/api/v1/errors/:id/mute`
|
||||
- Register `resolve_production_error` tool → POSTs to `/api/v1/errors/:id/resolve`
|
||||
- Add keybindings to `/prod-errors` TUI:
|
||||
- `M` (shift-m) in list view → mute selected error
|
||||
- `R` (shift-r) in detail view → resolve selected error
|
||||
- Or use single keys: `x` for mute, `d` for resolve (avoiding conflict with existing `m`/`r` filter toggles)
|
||||
|
||||
**Pros:**
|
||||
- Simplest approach — each endpoint does exactly one thing
|
||||
- RESTful resource/action pattern used elsewhere in the app (e.g., `/collection/latest`)
|
||||
- Easy to extend with unmute/unresolve later as additional endpoints
|
||||
- Clean tool-to-endpoint mapping in pi
|
||||
- Easy to test independently
|
||||
|
||||
**Cons:**
|
||||
- Two new routes instead of one
|
||||
- If many more error actions are added, route count could grow
|
||||
|
||||
### Route B: Single PATCH Endpoint
|
||||
|
||||
Add one generic mutation endpoint:
|
||||
|
||||
```
|
||||
PATCH /api/v1/errors/:id body: {"muted": true} or {"status": "resolved"}
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- Single route for all error mutations
|
||||
- Follows REST convention for partial updates
|
||||
- Easily extensible to other fields
|
||||
|
||||
**Cons:**
|
||||
- Parameter validation is more complex (must reject unknown fields, validate combinations)
|
||||
- Tool semantics are less clear — the pi tool would need to construct the PATCH body
|
||||
- PATCH semantics imply partial update; if both fields are sent, behavior must be defined
|
||||
- Less explicit — the URL doesn't convey the action being performed
|
||||
- Not aligned with existing project patterns (no other PATCH routes in the API)
|
||||
|
||||
### Route C: Single Action Endpoint
|
||||
|
||||
```
|
||||
POST /api/v1/errors/:id/actions body: {"action": "mute"} or {"action": "resolve"}
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- Single route for all actions
|
||||
- Easy to add new action types
|
||||
- Clean separation between action specification and execution
|
||||
- Tool semantics map cleanly (tool name = action)
|
||||
|
||||
**Cons:**
|
||||
- Less standard REST pattern
|
||||
- Requires action validation/dispatch layer
|
||||
- No existing precedent in the codebase
|
||||
|
||||
## Recommendation: Route A
|
||||
|
||||
Route A is the best fit for this project because:
|
||||
|
||||
1. **Convention alignment** — The project uses clear, descriptive route names for specific operations (e.g., `/collection/latest`, `/collection/random`, `/collection/on_this_day`). `POST /errors/:id/mute` and `POST /errors/:id/resolve` follow this pattern.
|
||||
|
||||
2. **Simplicity** — Each endpoint has a single responsibility. The controller actions, context functions, JSON views, and pi tools are all trivial to implement and test independently.
|
||||
|
||||
3. **Extensibility** — If unmute/unresolve are needed later, they can be added as `POST /errors/:id/unmute` and `POST /errors/:id/unresolve` without touching the existing endpoints.
|
||||
|
||||
4. **Pi tool mapping** — Each endpoint maps 1:1 to a pi tool (`mute_production_error` → `POST /errors/:id/mute`, `resolve_production_error` → `POST /errors/:id/resolve`). This makes the prompt guidelines simple and the tool behavior predictable.
|
||||
|
||||
5. **HTTP semantics** — POST is appropriate here because these are non-idempotent actions that change server state. POST on a sub-resource path is a well-established REST pattern.
|
||||
|
||||
## Architecture Impact
|
||||
|
||||
| Component | Impact |
|
||||
|---|---|
|
||||
| `MusicLibrary.Errors` | Add `mute_error/1`, `resolve_error/1` context functions |
|
||||
| `MusicLibraryWeb.ErrorController` | Add `mute/2`, `resolve/2` actions |
|
||||
| `MusicLibraryWeb.ErrorJSON` | Add render functions for success/error responses |
|
||||
| `MusicLibraryWeb.Router` | Add two POST routes |
|
||||
| `.pi/extensions/prod-errors/index.ts` | Add two tools, add TUI keybindings |
|
||||
| `test/music_library_web/controllers/error_controller_test.exs` | Add tests for new endpoints |
|
||||
| `test/music_library/errors_test.exs` | Add tests for new context functions (if separate test file exists) |
|
||||
| `docs/architecture.md` | Update Routes section if it lists API routes |
|
||||
|
||||
No changes needed to: supervision tree, PubSub, schemas, migrations, Oban workers, LiveViews, external APIs.
|
||||
|
||||
## Performance Profile
|
||||
|
||||
- **Database**: Single-row UPDATE by primary key — O(1). SQLite handles this efficiently.
|
||||
- **No N+1 risk**: These are simple UPDATE operations, no joins or preloads.
|
||||
- **HTTP latency**: Sub-millisecond for the DB update + minimal JSON encoding.
|
||||
- **Concurrency**: SQLite serializes writes — moot for low-frequency admin actions like mute/resolve.
|
||||
- **No paid API calls** — these are entirely local operations.
|
||||
|
||||
## Cost Profile
|
||||
|
||||
Zero incremental cost. No external API calls, no additional compute, no additional storage.
|
||||
|
||||
## Production Infrastructure Steps
|
||||
|
||||
No production infrastructure changes needed. The new endpoints are served by the existing Phoenix app. No new environment variables, no DNS changes, no firewall rules.
|
||||
|
||||
## Documentation Updates
|
||||
|
||||
| File | Change |
|
||||
|---|---|
|
||||
| `docs/architecture.md` | Update Routes section if API routes are enumerated there |
|
||||
| README (if applicable) | N/A — API is internal tooling |
|
||||
| `.pi/extensions/prod-errors/index.ts` | Self-documenting through tool descriptions and prompt snippets |
|
||||
|
||||
## Testing
|
||||
|
||||
- **Controller tests**: Test auth (401 without token), test mute sets muted=true, test resolve sets status=resolved, test 404 for non-existent error, test idempotency (calling mute on already-muted error returns success with no change).
|
||||
- **Context tests**: Test `mute_error/1` returns updated error, test `resolve_error/1` returns updated error, test error on non-existent ID.
|
||||
Reference in New Issue
Block a user