refactored many events to use wails bindings, reducing boilerplate
This commit is contained in:
@@ -0,0 +1,283 @@
|
||||
# Plan: #12 — Move queue frontend→backend communication to Wails bindings
|
||||
|
||||
## Goal
|
||||
|
||||
Replace the 15 `Request*` events (frontend→backend) with direct Wails bindings while keeping the 4 backend→frontend push events (`QueueChanged`, `QueueIndexChanged`, `QueueModeChanged`, `QueueTracksModified`) intact. This eliminates ~420 lines of handler boilerplate in Go and aligns the queue's communication pattern with playlists.
|
||||
|
||||
## Rationale
|
||||
|
||||
**Why bindings for frontend→backend (replacing events):**
|
||||
- Eliminates 420 lines of hand-written type-assertion boilerplate in `handlers.go`
|
||||
- Provides compile-time type safety — Wails auto-generates typed TypeScript bindings from Go method signatures, so `float64`→`int` casting, `[]interface{}`→`[]string` conversion, and `len(data)` validation all disappear
|
||||
- Adding a new queue operation becomes a 1-file change (add Go method) vs the current 4-file change (Go event constant, TS event constant, Go handler, TS store method)
|
||||
- Aligns with the playlist pattern, reducing cognitive overhead
|
||||
|
||||
**Why keep events for backend→frontend (not replacing with invalidate-and-refetch):**
|
||||
- The queue's delta system (`QueueTracksModified` with add/insert/remove/move actions) is genuinely good architecture for a data structure that changes frequently during playback
|
||||
- Avoids unnecessary round-trips — the backend pushes only what changed
|
||||
- The playlist's invalidate-and-refetch pattern works for playlists (infrequent mutations) but would be wasteful for a queue (changes on every track advance)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The queue must be created in `NewYellowJacketApp()` (before `wails.Run()`) rather than in `OnStartup()`, because Wails v2 consumes the `Bind` slice eagerly at startup via reflection. The struct pointer must be non-nil and fully constructed at `Bind` time.
|
||||
|
||||
This is safe because `queue.NewQueue()` only needs `logger` and `db` (both already available in `NewYellowJacketApp`). The player dependency and context are set later via `SetPlayer()` and `SetContext()` during `OnStartup`, which is the existing two-phase initialization pattern used by all other bound services.
|
||||
|
||||
## Detailed Steps
|
||||
|
||||
### Step 1: Move queue construction to `NewYellowJacketApp` and add to `FEBindings`
|
||||
|
||||
**File:** `backend/app.go`
|
||||
|
||||
In `NewYellowJacketApp()`, after the playlist service is created (~line 104), add:
|
||||
|
||||
```go
|
||||
yjApp.queue = queue.NewQueue(yjApp.logger, yjApp.database)
|
||||
```
|
||||
|
||||
Add the queue to `FEBindings`:
|
||||
|
||||
```go
|
||||
yjApp.FEBindings = []any{
|
||||
yjApp.FrontendUtil,
|
||||
yjApp.appConfig,
|
||||
yjApp.library,
|
||||
yjApp.playlist,
|
||||
yjApp.queue,
|
||||
}
|
||||
```
|
||||
|
||||
In `OnStartup()`, remove `queue.NewQueue(...)` and keep only the deferred initialization:
|
||||
|
||||
```go
|
||||
yj.queue.SetContext(ctx)
|
||||
yj.queue.SetPlayer(yj.player)
|
||||
yj.queue.RestoreState()
|
||||
```
|
||||
|
||||
### Step 2: Remove `registerEventHandlers()` and all handler boilerplate
|
||||
|
||||
**File:** `backend/queue/handlers.go`
|
||||
|
||||
Remove:
|
||||
- `registerEventHandlers()` — all 16 `runtime.EventsOn` registrations (lines 41-172)
|
||||
- All 10 `handle*` functions (lines 201-461): `handleSetQueue`, `handleAddToQueue`, `handlePlayNext`, `handleRemoveFromQueue`, `handleRemoveTracksFromQueue`, `handleAddTracksToQueue`, `handleInsertTracksAtIndex`, `handleMoveQueueTracks`, `handlePlayQueueIndex`, `handlePlayTracksNext`
|
||||
- The two helper functions `toStringSlice` and `toIntSlice` (lines 175-199)
|
||||
|
||||
Keep:
|
||||
- `OnPlaybackFinished()` (lines 11-38) — this is domain logic, not event boilerplate
|
||||
|
||||
**File:** `backend/queue/queue.go`
|
||||
|
||||
In `SetContext()`, remove the call to `q.registerEventHandlers()`. The method becomes:
|
||||
|
||||
```go
|
||||
func (q *Queue) SetContext(ctx context.Context) {
|
||||
q.ctx = ctx
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Remove the 15 `Request*` queue event constants
|
||||
|
||||
**File:** `backend/events/events.go`
|
||||
|
||||
Remove from the "Queue events" const block (lines 38-52):
|
||||
- `RequestNext`
|
||||
- `RequestPrevious`
|
||||
- `RequestSetQueue`
|
||||
- `RequestAddToQueue`
|
||||
- `RequestPlayNext`
|
||||
- `RequestRemoveFromQueue`
|
||||
- `RequestToggleShuffle`
|
||||
- `RequestCycleRepeat`
|
||||
- `RequestAddTracksToQueue`
|
||||
- `RequestPlayTracksNext`
|
||||
- `RequestPlayQueueIndex`
|
||||
- `RequestRemoveTracksFromQueue`
|
||||
- `RequestInsertTracksAtIndex`
|
||||
- `RequestMoveQueueTracks`
|
||||
- `RequestClearQueue`
|
||||
|
||||
Keep `RequestPlay` — it's in the "Playback control events" block and is used by the queue's event handler. Since we're removing `registerEventHandlers`, also remove `RequestPlay` from the queue's event handler. But check if `RequestPlay` is still used by the player package first.
|
||||
|
||||
> **Note:** `RequestPlay` is currently handled by the queue (in `handlers.go:48`), not the player. After this refactor, the queue's `Play()` method will be callable directly via bindings, so the `RequestPlay` event handler in the queue is no longer needed. However, `RequestPlay` may still be emitted by the frontend for player-related actions — audit all `RequestPlay` usages before removing the constant.
|
||||
|
||||
**File:** `frontend/src/events.ts`
|
||||
|
||||
Remove the corresponding 15 `Request*` constants from lines 28-42. Keep the 4 backend→frontend queue events (lines 24-27).
|
||||
|
||||
### Step 4: Rewrite the queue store to use Wails bindings
|
||||
|
||||
**File:** `frontend/src/store/queue-store.ts`
|
||||
|
||||
Replace the 14 action methods that call `EventsEmit(Events.Request*)` with direct calls to the auto-generated Wails bindings.
|
||||
|
||||
**Before** (example):
|
||||
```typescript
|
||||
import { EventsOn, EventsEmit } from '@runtime/runtime';
|
||||
import { Events } from '../events';
|
||||
|
||||
// ...
|
||||
next(): void {
|
||||
EventsEmit(Events.RequestNext);
|
||||
}
|
||||
|
||||
setQueue(filePaths: string[], startIndex: number, shuffleStart = false): void {
|
||||
EventsEmit(Events.RequestSetQueue, filePaths, startIndex, shuffleStart);
|
||||
}
|
||||
```
|
||||
|
||||
**After** (example):
|
||||
```typescript
|
||||
import { EventsOn } from '@runtime/runtime';
|
||||
import { Events } from '../events';
|
||||
import * as QueueService from '@go/queue/Queue';
|
||||
|
||||
// ...
|
||||
next(): void {
|
||||
QueueService.Next();
|
||||
}
|
||||
|
||||
setQueue(filePaths: string[], startIndex: number, shuffleStart = false): void {
|
||||
QueueService.SetQueue(filePaths, startIndex, shuffleStart);
|
||||
}
|
||||
```
|
||||
|
||||
Keep the entire `initializeEventListeners()` method unchanged — the 4 backend→frontend event subscriptions (`QueueChanged`, `QueueIndexChanged`, `QueueModeChanged`, `QueueTracksModified`) and the `applyTracksDelta()` logic remain as-is.
|
||||
|
||||
Remove the `EventsEmit` import if no longer needed after removing all `Request*` emissions.
|
||||
|
||||
**Complete action method mapping** (queue store method → Wails binding):
|
||||
|
||||
| Store method | Current event | Wails binding call |
|
||||
|---|---|---|
|
||||
| `next()` | `RequestNext` | `QueueService.Next()` |
|
||||
| `previous()` | `RequestPrevious` | `QueueService.Previous()` |
|
||||
| `setQueue(filePaths, startIndex, shuffleStart)` | `RequestSetQueue` | `QueueService.SetQueue(filePaths, startIndex, shuffleStart)` |
|
||||
| `addToQueue(filePath)` | `RequestAddToQueue` | `QueueService.AddTrack(filePath)` |
|
||||
| `playNext(filePath)` | `RequestPlayNext` | `QueueService.InsertNext(filePath)` |
|
||||
| `removeFromQueue(position)` | `RequestRemoveFromQueue` | `QueueService.RemoveTrack(position)` |
|
||||
| `removeTracksFromQueue(positions)` | `RequestRemoveTracksFromQueue` | `QueueService.RemoveTracks(positions)` |
|
||||
| `addTracksToQueue(filePaths)` | `RequestAddTracksToQueue` | `QueueService.AddTracks(filePaths)` |
|
||||
| `playTracksNext(filePaths)` | `RequestPlayTracksNext` | `QueueService.InsertNextTracks(filePaths)` |
|
||||
| `toggleShuffle()` | `RequestToggleShuffle` | `QueueService.ToggleShuffle()` |
|
||||
| `cycleRepeat()` | `RequestCycleRepeat` | `QueueService.CycleRepeat()` |
|
||||
| `playAtIndex(index)` | `RequestPlayQueueIndex` | `QueueService.PlayIndex(index)` |
|
||||
| `insertTracksAtIndex(filePaths, index)` | `RequestInsertTracksAtIndex` | `QueueService.InsertTracksAt(filePaths, index)` |
|
||||
| `moveTracksInQueue(fromIndices, toIndex)` | `RequestMoveQueueTracks` | `QueueService.MoveQueueTracks(fromIndices, toIndex)` |
|
||||
| `clearQueue()` | `RequestClearQueue` | `QueueService.Clear()` |
|
||||
|
||||
> **Note:** Some store method names don't match Go method names (e.g., `addToQueue` → `AddTrack`, `playNext` → `InsertNext`). The store method names can remain unchanged for API stability — only the implementation changes.
|
||||
|
||||
### Step 5: Handle `Play()` specifically
|
||||
|
||||
The queue's `Play()` method is currently triggered by the `RequestPlay` event, which is in the "Playback control events" group and is also emitted by `player-controls.ts`. After this refactor:
|
||||
|
||||
- The `RequestPlay` event handler in `handlers.go:48` is removed along with all other handlers
|
||||
- The frontend should call `QueueService.Play()` directly instead of `EventsEmit(Events.RequestPlay)`
|
||||
|
||||
Audit all places that emit `RequestPlay`:
|
||||
- `frontend/src/components/audio-player/controls/player-controls.ts` — the play button emits `RequestPlay`. This should be changed to call `QueueService.Play()` (or more likely, the queue store should expose a `play()` method that delegates to the binding)
|
||||
|
||||
If `RequestPlay` has no other consumers after this change, remove the event constant from both `events.go` and `events.ts`.
|
||||
|
||||
### Step 6: Regenerate Wails bindings
|
||||
|
||||
Run `wails generate module` (or `make dev` which triggers binding generation) to produce the auto-generated files:
|
||||
|
||||
- `frontend/wailsjs/go/queue/Queue.js` — JavaScript bridge calling `window['go']['queue']['Queue'][method](...)`
|
||||
- `frontend/wailsjs/go/queue/Queue.d.ts` — TypeScript declarations with proper types
|
||||
- `frontend/wailsjs/go/models.ts` — Updated with `queue.Track`, `queue.State`, `queue.RepeatMode`, etc.
|
||||
|
||||
> **Important:** The auto-generated TypeScript types will mirror the Go struct JSON tags, so the frontend types already defined in `queue-store.ts` (`QueueTrack`, `QueueState`, `IndexChanged`, `ModeChanged`, `TracksModified`) will have matching auto-generated equivalents in `models.ts`. We should keep the manually-defined types in the store (they're used by the event listeners which still need them) but could optionally import the model types where convenient.
|
||||
|
||||
### Step 7: Handle `SetContext` visibility
|
||||
|
||||
When a struct is added to Wails `FEBindings`, **all exported methods** become callable from JavaScript. `SetContext(ctx context.Context)` and `SetPlayer(player TrackLoader)` would be exposed, which is undesirable — they're internal lifecycle methods, not frontend API.
|
||||
|
||||
Options:
|
||||
1. **Unexport them** — rename to `setContext`/`setPlayer`. This requires updating `app.go` to call `q.setContext(ctx)` etc. But unexported methods on structs in other packages aren't accessible, so this won't work without making them package-internal.
|
||||
2. **Create a thin facade struct** — a `Service` (or `API`) struct that embeds or wraps `*Queue` and only exposes the methods the frontend should call. This is the playlist pattern (`playlist.Service`).
|
||||
3. **Accept the exposure** — Wails will generate bindings for `SetContext` and `SetPlayer`, but the frontend simply won't call them. They'll be inert in the generated JS. This is what happens with `playlist.Service.SetContext` — it's in the generated `Service.js` but never imported by the frontend.
|
||||
|
||||
**Recommendation:** Option 3 — accept it. The playlist already has `SetContext` exposed in its generated bindings (`frontend/wailsjs/go/playlist/Service.js:69`) and it's not a problem. Wails bindings are not a security boundary (the frontend and backend are in the same process). The generated bindings are auto-generated artifacts, not a public API. No one will accidentally call `SetContext` from the frontend.
|
||||
|
||||
If `SetPlayer` is a concern because `TrackLoader` is an interface type that Wails can't serialize, Wails may skip it or error during binding generation. If so, either unexport `SetPlayer` only, or have `app.go` set it via an unexported package-level function. This needs testing during step 6.
|
||||
|
||||
### Step 8: Update `queue-controller.ts` (no changes needed)
|
||||
|
||||
The `QueueController` (`frontend/src/store/controllers/queue-controller.ts`) proxies all actions through `queueStore.*()`. Since we're only changing the store's internal implementation (from `EventsEmit` to binding calls), the controller needs zero changes. All 14 action proxy methods remain identical.
|
||||
|
||||
### Step 9: Update components that call `queueStore` directly (no changes needed)
|
||||
|
||||
These 6 components import `queueStore` and call its action methods:
|
||||
- `player-controls.ts` — `queueStore.next()`, `.previous()`, `.toggleShuffle()`, `.cycleRepeat()`
|
||||
- `track-list.ts` — `queueStore.setQueue()`, `.addTracksToQueue()`, `.playTracksNext()`
|
||||
- `cover-grid.ts` — `queueStore.setQueue()`, `.addTracksToQueue()`, `.playTracksNext()`
|
||||
- `genres-view.ts` — `queueStore.setQueue()`, `.addTracksToQueue()`, `.playTracksNext()`
|
||||
- `artists-view.ts` — `queueStore.setQueue()`, `.addTracksToQueue()`, `.playTracksNext()`
|
||||
- `playlist-view.ts` — `queueStore.setQueue()`, `.addTracksToQueue()`, `.playTracksNext()`
|
||||
|
||||
Since the store's public API (method signatures) is unchanged, none of these components need modifications.
|
||||
|
||||
**Exception:** `player-controls.ts` currently emits `Events.RequestPlay` directly for the play/pause button (not through the queue store). This specific call site needs to be updated to either:
|
||||
- Call `queueStore.play()` (add a `play()` method to the store), or
|
||||
- Call `QueueService.Play()` directly
|
||||
|
||||
### Step 10: Run tests, lint, and build
|
||||
|
||||
```bash
|
||||
make test # Verify Go tests pass (especially queue tests)
|
||||
make lint # Verify linting passes
|
||||
cd frontend && pnpm exec tsc --noEmit # Verify TypeScript types
|
||||
make build-dev # Full build to verify Wails binding generation works
|
||||
```
|
||||
|
||||
## Files Modified
|
||||
|
||||
| File | Action | Description |
|
||||
|---|---|---|
|
||||
| `backend/app.go` | Edit | Move queue construction; add to `FEBindings` |
|
||||
| `backend/queue/handlers.go` | Major edit | Remove all `handle*` functions, `registerEventHandlers`, `toStringSlice`, `toIntSlice`. Keep only `OnPlaybackFinished` |
|
||||
| `backend/queue/queue.go` | Edit | Remove `registerEventHandlers()` call from `SetContext` |
|
||||
| `backend/events/events.go` | Edit | Remove 15 `Request*` queue constants |
|
||||
| `frontend/src/events.ts` | Edit | Remove 15 `Request*` queue constants |
|
||||
| `frontend/src/store/queue-store.ts` | Edit | Replace `EventsEmit` action methods with Wails binding calls |
|
||||
| `frontend/src/components/audio-player/controls/player-controls.ts` | Edit | Replace `RequestPlay` event emission with binding call |
|
||||
| `frontend/wailsjs/go/queue/Queue.js` | Auto-generated | New file from `wails generate` |
|
||||
| `frontend/wailsjs/go/queue/Queue.d.ts` | Auto-generated | New file from `wails generate` |
|
||||
| `frontend/wailsjs/go/models.ts` | Auto-generated | Updated with queue types |
|
||||
|
||||
## Files NOT Modified
|
||||
|
||||
| File | Reason |
|
||||
|---|---|
|
||||
| `backend/queue/emit.go` | Backend→frontend push events are kept as-is |
|
||||
| `frontend/src/store/controllers/queue-controller.ts` | Proxies through store; no API change |
|
||||
| `frontend/src/components/queue-panel/queue-panel.ts` | Uses controller; no API change |
|
||||
| `frontend/src/components/track-list/track-list.ts` | Calls store methods; no API change |
|
||||
| `frontend/src/components/cover-grid/cover-grid.ts` | Calls store methods; no API change |
|
||||
| `frontend/src/components/genres-view/genres-view.ts` | Calls store methods; no API change |
|
||||
| `frontend/src/components/artists-view/artists-view.ts` | Calls store methods; no API change |
|
||||
| `frontend/src/components/playlist-view/playlist-view.ts` | Calls store methods; no API change |
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
**Low risk:**
|
||||
- The queue's public Go methods are already well-tested and have clear type signatures
|
||||
- The store's public API doesn't change, so no component-level regressions
|
||||
- The backend→frontend event system is untouched
|
||||
- The pattern is proven by the playlist package
|
||||
|
||||
**Medium risk:**
|
||||
- `SetPlayer(TrackLoader)` exposure in Wails bindings — Wails may not handle the interface parameter. If binding generation fails, we'll need to unexport `SetPlayer` and wire it via a package-level function or an exported setter that takes concrete types
|
||||
- `RequestPlay` event has cross-cutting usage in `player-controls.ts` — needs careful auditing to avoid breaking play/pause
|
||||
|
||||
## Net Effect
|
||||
|
||||
- **~420 lines removed** from `handlers.go` (boilerplate)
|
||||
- **~20 lines removed** from `events.go` and `events.ts` (15 event constants each)
|
||||
- **~30 lines changed** in `queue-store.ts` (swap `EventsEmit` for binding calls)
|
||||
- **~10 lines changed** in `app.go` (move construction, add to bindings)
|
||||
- **~3 auto-generated files** created/updated by Wails
|
||||
- Adding a new queue operation goes from a 4-file change to a 1-2 file change
|
||||
@@ -0,0 +1,286 @@
|
||||
# Plan: Move player frontend→backend communication to Wails bindings
|
||||
|
||||
## Goal
|
||||
|
||||
Replace the 4 remaining `EventsEmit` calls (frontend→backend) in `player-store.ts` with direct Wails bindings, eliminating ~90 lines of handler boilerplate in Go. This completes the pattern established by the queue refactoring (#12) — after this change, **all** frontend→backend communication uses Wails bindings.
|
||||
|
||||
## Rationale
|
||||
|
||||
Same benefits as the queue refactor:
|
||||
- Eliminates untyped `data[0].(float64)` casting boilerplate
|
||||
- Provides compile-time type safety via auto-generated TypeScript declarations
|
||||
- Adding a new player operation becomes a 1-file change (Go method) instead of 4 files
|
||||
- Completes the architectural consistency — every frontend→backend call uses bindings, every backend→frontend push uses events
|
||||
|
||||
## Key Challenge: `speaker.Init()` in constructor
|
||||
|
||||
The player is currently created in `OnStartup` (after `wails.Run()`) because `NewPlayer` calls `speaker.Init()` to initialize audio hardware. Wails bindings must be registered before `wails.Run()`, so we need to split the constructor.
|
||||
|
||||
**Solution:** Extract `speaker.Init()` into a separate `InitSpeaker()` method. `NewPlayer` creates the struct with all fields initialized (logger, db, state, default format) but does NOT touch audio hardware. `InitSpeaker()` is called during `OnStartup` when hardware is available.
|
||||
|
||||
This is safe because:
|
||||
- `NewPlayer` already initializes all struct fields before `speaker.Init()` runs
|
||||
- `speaker.Init()` doesn't depend on any struct state — it only uses the sample rate constant
|
||||
- The player's methods that touch the speaker (`Play`, `Pause`, `Seek`, `LoadFile`) are only called after `OnStartup` completes, so the speaker will always be initialized before any method is invoked via binding
|
||||
|
||||
## Detailed Steps
|
||||
|
||||
### Step 1: Split `NewPlayer` — extract `InitSpeaker`
|
||||
|
||||
**File:** `backend/player/player.go`
|
||||
|
||||
Change `NewPlayer` to accept only `logger` and `db` (remove the `ctx` parameter — context is set later via `SetContext`). Remove `speaker.Init()` from the constructor.
|
||||
|
||||
Add a new `InitSpeaker() error` method that does the `speaker.Init()` call.
|
||||
|
||||
**Before:**
|
||||
```go
|
||||
func NewPlayer(ctx context.Context, logger *slog.Logger, db *database.DB) (*Player, error) {
|
||||
player := &Player{ctx: ctx, logger: logger, db: db, state: Stopped, ...}
|
||||
err := speaker.Init(...)
|
||||
if err != nil { return nil, ... }
|
||||
return player, nil
|
||||
}
|
||||
```
|
||||
|
||||
**After:**
|
||||
```go
|
||||
func NewPlayer(logger *slog.Logger, db *database.DB) *Player {
|
||||
return &Player{logger: logger, db: db, state: Stopped, ...}
|
||||
}
|
||||
|
||||
func (p *Player) InitSpeaker() error {
|
||||
err := speaker.Init(p.format.SampleRate, p.format.SampleRate.N(time.Second/10))
|
||||
if err != nil { return fmt.Errorf("failed to initialize speaker: %w", err) }
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
Note: `NewPlayer` no longer returns an error (struct creation can't fail) and no longer takes `ctx` (set via `SetContext`).
|
||||
|
||||
### Step 2: Remove `registerEventHandlers` from player
|
||||
|
||||
**File:** `backend/player/player.go`
|
||||
|
||||
Delete the entire `registerEventHandlers()` method (lines 154-272) — all 4 `runtime.EventsOn` registrations and their handler closures.
|
||||
|
||||
Update `SetContext` to remove the `registerEventHandlers()` call. Keep only the context assignment and state restoration:
|
||||
|
||||
```go
|
||||
func (p *Player) SetContext(ctx context.Context) {
|
||||
p.mu.Lock()
|
||||
p.ctx = ctx
|
||||
p.mu.Unlock()
|
||||
|
||||
p.mu.Lock()
|
||||
p.restoreStateLocked()
|
||||
p.mu.Unlock()
|
||||
}
|
||||
```
|
||||
|
||||
Remove the `"fmt"` import if it becomes unused (it was used by `fmt.Sprintf("%T", data[0])` in the handlers). Check if `fmt` is still used elsewhere in the file — yes, it's used in `loadFileLocked`, `seekLocked`, etc. Keep it.
|
||||
|
||||
Remove the `"yellowjacket/backend/events"` import — check first. It's used by:
|
||||
- `registerEventHandlers` (being removed) — uses `events.RequestPause`, `events.RequestLoadFile`, `events.Seek`, `events.RequestSetVolume`
|
||||
- `emitPlaybackStateChanged` — uses `events.PlaybackStateChanged`
|
||||
- `emitPlaybackFinished` — uses `events.PlaybackFinished`
|
||||
- `emitVolumeChanged` — uses `events.VolumeChanged`
|
||||
- `emitTrackChanged` — uses `events.TrackChanged`
|
||||
- `seekLocked` — uses `events.SeekFailed`
|
||||
- `UnloadTrack` — uses `events.TrackChanged`
|
||||
|
||||
So `events` import stays (it's still used by the emit helpers).
|
||||
|
||||
The `runtime` import also stays (used by emit helpers and `UnloadTrack`).
|
||||
|
||||
### Step 3: Update `SetVolume` to include side effects
|
||||
|
||||
**File:** `backend/player/player.go`
|
||||
|
||||
The current `SetVolume` only calls `setVolumeLocked()`. The event handler also called `emitVolumeChanged()` and `saveState()`. Update `SetVolume` to match what the event handler did:
|
||||
|
||||
**Before:**
|
||||
```go
|
||||
func (p *Player) SetVolume(desiredVolume UserVolume) error {
|
||||
p.mu.Lock()
|
||||
defer p.mu.Unlock()
|
||||
p.setVolumeLocked(desiredVolume)
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
**After:**
|
||||
```go
|
||||
func (p *Player) SetVolume(desiredVolume UserVolume) {
|
||||
p.mu.Lock()
|
||||
defer p.mu.Unlock()
|
||||
p.setVolumeLocked(desiredVolume)
|
||||
p.emitVolumeChanged()
|
||||
p.saveState()
|
||||
}
|
||||
```
|
||||
|
||||
Note: changed return type from `error` to void — `setVolumeLocked` never fails, and this avoids Wails generating a Promise rejection for a method that can't error. Check if any Go code calls `SetVolume` and checks the error — no callers exist (confirmed above).
|
||||
|
||||
### Step 4: Update `app.go` — create player early, add to `FEBindings`
|
||||
|
||||
**File:** `backend/app.go`
|
||||
|
||||
In `NewYellowJacketApp`, create the player early (after db is available):
|
||||
|
||||
```go
|
||||
yjApp.player = player.NewPlayer(yjApp.logger.WithGroup("player"), yjApp.database)
|
||||
```
|
||||
|
||||
Add to `FEBindings`:
|
||||
|
||||
```go
|
||||
yjApp.FEBindings = []any{
|
||||
yjApp.FrontendUtil,
|
||||
yjApp.appConfig,
|
||||
yjApp.library,
|
||||
yjApp.playlist,
|
||||
yjApp.queue,
|
||||
yjApp.player,
|
||||
}
|
||||
```
|
||||
|
||||
In `OnStartup`, replace player creation with deferred initialization:
|
||||
|
||||
```go
|
||||
if err := yj.player.InitSpeaker(); err != nil {
|
||||
startupErr = errors.Join(startupErr, fmt.Errorf("could not initialize speaker: %w", err))
|
||||
}
|
||||
yj.player.SetContext(ctx)
|
||||
```
|
||||
|
||||
### Step 5: Update player test
|
||||
|
||||
**File:** `backend/player/player_test.go`
|
||||
|
||||
Update the test to match the new two-phase constructor:
|
||||
|
||||
**Before:**
|
||||
```go
|
||||
p, err := NewPlayer(context.Background(), slog.Default(), nil)
|
||||
if err != nil { t.Fatalf(...) }
|
||||
p.SetContext(t.Context())
|
||||
```
|
||||
|
||||
**After:**
|
||||
```go
|
||||
p := NewPlayer(slog.Default(), nil)
|
||||
if err := p.InitSpeaker(); err != nil { t.Fatalf(...) }
|
||||
p.SetContext(t.Context())
|
||||
```
|
||||
|
||||
### Step 6: Remove player `Request*` event constants from Go and TS
|
||||
|
||||
**File:** `backend/events/events.go`
|
||||
|
||||
Remove from "Playback control events" block:
|
||||
- `RequestPause`
|
||||
- `RequestLoadFile`
|
||||
|
||||
Remove the entire "Seek events" block — `Seek` was only used as a frontend→backend event. Keep `SeekFailed` by moving it elsewhere (e.g., into a "Playback control events" block or its own group).
|
||||
|
||||
Remove from "Volume events" block:
|
||||
- `RequestSetVolume`
|
||||
|
||||
**File:** `frontend/src/events.ts`
|
||||
|
||||
Remove:
|
||||
- `RequestPause`
|
||||
- `RequestLoadFile`
|
||||
- `Seek`
|
||||
- `RequestSetVolume`
|
||||
|
||||
Keep:
|
||||
- `PlaybackStateChanged`, `PlaybackFinished` (backend→frontend push)
|
||||
- `SeekFailed` (backend→frontend push, even though unused — separate issue #15)
|
||||
- `TrackChanged` (backend→frontend push)
|
||||
- `VolumeChanged` (backend→frontend push)
|
||||
|
||||
### Step 7: Regenerate Wails bindings
|
||||
|
||||
Run `wails generate module` to produce:
|
||||
- `frontend/wailsjs/go/player/Player.js`
|
||||
- `frontend/wailsjs/go/player/Player.d.ts`
|
||||
- Updated `frontend/wailsjs/go/models.ts` with `player.TrackInfo`, `player.UserVolume`, etc.
|
||||
|
||||
Expected generated bindings for the methods we need:
|
||||
- `Pause(): Promise<void>` (from `func (p *Player) Pause() error`)
|
||||
- `LoadFile(arg1: string): Promise<void>` (from `func (p *Player) LoadFile(filePath string) error`)
|
||||
- `Seek(arg1: number): Promise<void>` (from `func (p *Player) Seek(targetSeconds int) error`)
|
||||
- `SetVolume(arg1: number): Promise<void>` (from `func (p *Player) SetVolume(desiredVolume UserVolume)`)
|
||||
|
||||
Note: `UserVolume` is `type UserVolume int`, so Wails will serialize it as a plain number. The generated TS type will be `number` (or `player.UserVolume` which maps to `number`).
|
||||
|
||||
### Step 8: Rewrite `player-store.ts` actions to use Wails bindings
|
||||
|
||||
**File:** `frontend/src/store/player-store.ts`
|
||||
|
||||
Replace `EventsEmit` action methods with Wails binding calls:
|
||||
|
||||
| Store method | Current | After |
|
||||
|---|---|---|
|
||||
| `pause()` | `EventsEmit(Events.RequestPause)` | `Player.Pause()` |
|
||||
| `loadTrack(filePath)` | `EventsEmit(Events.RequestLoadFile, filePath)` | `Player.LoadFile(filePath)` |
|
||||
| `seek(seconds)` | `EventsEmit(Events.Seek, seconds)` | `Player.Seek(seconds)` |
|
||||
| `setVolume(level)` | `EventsEmit(Events.RequestSetVolume, level)` | `Player.SetVolume(level)` |
|
||||
|
||||
Remove the `EventsEmit` import (only `EventsOn` will be needed).
|
||||
|
||||
Add import: `import * as Player from '@go/player/Player';`
|
||||
|
||||
The 4 backend→frontend event subscriptions (`PlaybackStateChanged`, `TrackChanged`, `PlaybackFinished`, `VolumeChanged`) remain unchanged.
|
||||
|
||||
### Step 9: Run tests, lint, and TypeScript type check
|
||||
|
||||
```bash
|
||||
make test
|
||||
make lint
|
||||
cd frontend && pnpm exec tsc --noEmit
|
||||
cd frontend && pnpm build
|
||||
```
|
||||
|
||||
## Files Modified
|
||||
|
||||
| File | Action | Description |
|
||||
|---|---|---|
|
||||
| `backend/player/player.go` | Edit | Split `NewPlayer`, add `InitSpeaker`, remove `registerEventHandlers`, update `SetVolume` |
|
||||
| `backend/app.go` | Edit | Move player creation early, add to `FEBindings`, call `InitSpeaker` in `OnStartup` |
|
||||
| `backend/player/player_test.go` | Edit | Update test to use new constructor + `InitSpeaker` |
|
||||
| `backend/events/events.go` | Edit | Remove `RequestPause`, `RequestLoadFile`, `Seek`, `RequestSetVolume` |
|
||||
| `frontend/src/events.ts` | Edit | Remove same 4 constants |
|
||||
| `frontend/src/store/player-store.ts` | Edit | Replace `EventsEmit` with Wails binding calls |
|
||||
| `frontend/wailsjs/go/player/Player.js` | Auto-generated | New |
|
||||
| `frontend/wailsjs/go/player/Player.d.ts` | Auto-generated | New |
|
||||
| `frontend/wailsjs/go/models.ts` | Auto-generated | Updated with player types |
|
||||
|
||||
## Files NOT Modified
|
||||
|
||||
| File | Reason |
|
||||
|---|---|
|
||||
| `frontend/src/store/controllers/player-controller.ts` | Proxies through store; no API change |
|
||||
| `frontend/src/components/audio-player/` | Uses controller/store; no API change |
|
||||
| All other component files | No direct player store interaction for these actions |
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
**Low risk:**
|
||||
- The player's public methods (`Pause`, `LoadFile`, `Seek`) already have the correct behavior — the event handlers were just thin wrappers
|
||||
- `SetVolume` is the only method that needs side effects added, and it has zero existing callers
|
||||
- The test is an integration test that skips by default
|
||||
|
||||
**Medium risk:**
|
||||
- `InitSpeaker()` splitting — if any code path calls a player method that touches the speaker before `InitSpeaker()` runs, it will panic. This is safe because all player method calls happen after `OnStartup` completes, but worth being aware of.
|
||||
- Wails may expose lifecycle methods (`SetContext`, `SetPlaybackFinishedHandler`, `InitSpeaker`) as callable bindings. Same non-issue as queue — these are harmless in generated JS.
|
||||
|
||||
## Net Effect
|
||||
|
||||
- **~120 lines removed** from `player.go` (event handlers + boilerplate)
|
||||
- **~8 lines removed** from event constants (Go + TS)
|
||||
- **~8 lines changed** in `player-store.ts` (swap `EventsEmit` for binding calls)
|
||||
- **~10 lines changed** in `app.go` (move construction)
|
||||
- After this change, **zero** `EventsEmit` calls remain in the frontend for backend requests — all frontend→backend communication uses Wails bindings
|
||||
@@ -30,8 +30,6 @@ Prioritized list of architectural improvements identified during a full codebase
|
||||
|
||||
### ~~6. Extract `SizedFilename` to a shared utility package~~ — solved
|
||||
|
||||
Created `backend/coverart/` package with `SizedFilename`, a `ResolveURLs` helper (encapsulates the repeated pattern of resolving filesystem paths to all size-variant URL paths), a `URLs` struct, and a `PathPrefix` constant. Removed `SizedFilename` from `library/coverart.go`. Updated all four callers (`library/query.go`, `player/player.go`, `playlist/playlist.go`, `app.go`) to use `coverart.ResolveURLs`, eliminating the `player` -> `library` and `playlist` -> `library` coupling. Added tests for the new package.
|
||||
|
||||
---
|
||||
|
||||
### 7. ~~Consolidate `LibraryScanComplete` handling~~ — solved
|
||||
@@ -48,14 +46,10 @@ Created `backend/coverart/` package with `SizedFilename`, a `ResolveURLs` helper
|
||||
|
||||
### ~~10. Move `FullRescan` orchestration from library to app~~ — solved
|
||||
|
||||
Replaced `queueClearer`/`playlistRestorer` interfaces and `SetQueue`/`SetPlaylistRestorer` setters with a single `RescanHooks` struct containing `PreClear`/`PostScan` function callbacks. The app wires `queue.Clear` and `playlist.RestoreAllPlaylists` as hooks, so the library no longer has any knowledge of or dependency on those packages.
|
||||
|
||||
---
|
||||
|
||||
### ~~11. Fix double `LibraryScanStarted` event during FullRescan~~ — solved
|
||||
|
||||
Removed the `LibraryScanStarted` emission from `FullRescan` (resolved as part of item #10). The event is now only emitted from `Scan()`, giving exactly one emission per rescan.
|
||||
|
||||
---
|
||||
|
||||
### 12. Inconsistent communication patterns: queue (events) vs playlist (bindings)
|
||||
@@ -83,8 +77,6 @@ Removed the `LibraryScanStarted` emission from `FullRescan` (resolved as part of
|
||||
|
||||
### 14. ~~Unused queue sentinels: `ErrEmptyQueue`, `ErrNoPlayer`~~ — solved
|
||||
|
||||
Removed during the queue.go split/rewrite (item #3).
|
||||
|
||||
---
|
||||
|
||||
### 15. `SeekFailed` event emitted but never listened to
|
||||
|
||||
Reference in New Issue
Block a user