Implement real-time collection updates when books are added/removed:
Backend Changes:
- Added connManager to CollectionHandler struct
- Updated constructor to accept ConnectionManager
- Updated all NewCollectionHandler() calls in ebook.go and main.go
- Added WebSocket broadcasts in AddBooks() handler
- Added WebSocket broadcasts in BulkRemoveBooks() handler
- Broadcasts collection_updated events with:
- collection_id: Which collection changed
- action: books_added or books_removed
- book_ids: Array of affected book IDs
- count: Number of books changed
Frontend Changes:
- Added WebSocket connection in collections UI
- connectWebSocket() establishes connection to /ws/sync
- Listens for collection_updated events
- Shows toast notification on collection change
- Auto-reloads page after 1 second to show updated book list
- Auto-reconnect on disconnect (5s delay)
- Error handling for WebSocket failures
WebSocket Event Format:
{
"type": "collection_updated",
"timestamp": "2026-02-01T12:00:00Z",
"data": {
"collection_id": "uuid",
"action": "books_added",
"book_ids": ["uuid1", "uuid2"],
"count": 2
}
}
User Experience:
- When another user adds books to a collection, all connected clients see:
1. Toast notification: "Collection updated: books_added (2 books)"
2. Page auto-refreshes after 1 second
3. Updated book list displays
- Same for book removal
- Works across multiple browser tabs/devices
- No manual refresh needed
Technical Notes:
- Broadcasts to ALL connected WebSocket clients
- Client-side filtering by collection_id
- Existing progress/conflict broadcasts continue to work
- Connection manager handles broadcast distribution
Resolves Limitation #4: Real-time Collection Updates
Add SSR routes for collections, progress, and devices pages:
Progress Page (/api/progress):
- Fetches all user progress with device sync sources
- Maps device types to icons (Kobo, KOReader, Web, Mobile)
- Server-renders progress visualization with real data
Collections Pages (/api/collections):
- GET /collections: List all user collections with SSR
- GET /collections/🆔 Collection detail page with books SSR
- Fetches collection metadata and book listings
- Converts database models to template data structures
Helper Functions:
- getTemplateUserWithTheme: Fetches user with theme preference
- Proper error handling for missing data
All routes use JWT authentication and fetch data server-side
for better SEO and initial page load performance. Client-side
enhancements can be added via HTMX for interactive features.
These routes support the Phase 9 frontend implementation with
proper SSR rendering for improved performance and accessibility.
- Update conflicts.templ to accept pre-rendered data
- Update queue.templ to accept pre-rendered data
- Update /conflicts and /queue routes in main.go for SSR
- Update stats rendering to use server-side values
- Add server-side conflict list rendering
- Add server-side queue list rendering
- Update conflicts.js to use location.reload() after operations
- Update queue.js to use location.reload() after operations
- Remove initial load calls from JavaScript files
Preserves all API endpoints and backward compatibility
- Add /devices route for device management interface
- Add /conflicts route for sync conflict resolution
- Add /queue route for sync queue management
- Add comprehensive tests for device cap management
- Add test suite for queue management
- Test successful updates (5, 10, 50, 100 devices)
- Test validation failures (0, -1, 101, 1000 devices)
- Test authentication requirements (no token, non-admin)
- Test non-existent user ID
- Test missing user ID in URL
- Test max_devices field in user list response
- Add 20+ test cases across 7 test functions
- Helper functions for admin user creation and login
Implement conflict detection for concurrent reading progress updates from different devices. Adds conflict management endpoints for listing, viewing, and resolving conflicts.
- Add ConflictHandler with CRUD endpoints for conflict management
- Implement automatic conflict detection in KOReader progress updates
- Add WebSocket broadcast for real-time conflict notifications
- Add database query for listing user conflicts by status
- Add integration tests and Bruno API test collection
- Test login returns both access_token and refresh_token
- Test refresh endpoint accepts UUID token and returns new access_token
- Verifies end-to-end refresh token flow works correctly
- Add Kobo sync handler with markup, bookmark, analytics, and initialization endpoints
- Add Kobo integration tests and Bruno API test collection
- Move device approve/reject routes from public to protected routes
- Enhance test infrastructure with DATABASE_URL support and helper functions
- Fix device GetDevice handler nil pointer handling
- Clean up test reports and session files
Add WebSocket infrastructure to main server:
- Import sync package for ConnectionManager
- Create and start ConnectionManager with cleanup task
- Initialize WSHandler with auth dependencies
- Add /ws/sync WebSocket endpoint
- Update handler initialization to pass ConnectionManager
The WebSocket endpoint at /ws/sync enables real-time progress
updates across all connected clients (web, mobile, devices).
- Add KOReader sync endpoints to main application router
- Create Bruno API collection for testing KOReader endpoints
- Add integration tests for KOReader functionality
- Include comprehensive README with setup instructions
- Test coverage for progress, metadata, library, and bookmarks sync
- Part of Phase 3 KOReader Integration implementation
- Add POST /api/libraries/:id/scan endpoint for admin library scanning
- Add GET /api/libraries/:id/media-items endpoint for library media items
- Move /api/libraries/types to public endpoint (no auth required)
- Update ScanEbooks handler to support library_id parameter
- Remove manual device ID generation, use database-generated IDs
- Add comprehensive test helpers (setupTestServer, loginTestUser, getTestUserID)
- Add cleanup step for existing test users in integration tests
- Fix UUID parsing from database responses
Test Files Added:
- integration_test.sh: Automated integration test script
* Tests full user flow: register, login, library creation, scanning
* Tests device registration and management
* Color-coded output with pass/fail tracking
* Generates detailed test results report
- cmd/server/tests/device_test.go: Unit tests for device endpoints
* TestDeviceRegistrationFlow: Full registration flow test
* TestListDevices: Device listing functionality
* TestUpdateDevice: Device settings updates
* TestDeleteDevice: Device removal
* TestDeviceAuthentication: Device auth middleware test
- cmd/server/tests/phase1_integration_test.go: Phase 1 integration tests
* Tests universal progress tracking
* Tests format group detection
* Tests progress conversion
Test Coverage:
- Device registration with web-based approval flow
- Device management (list, update, delete)
- Device authentication and token validation
- User authentication and authorization
- Library creation and management
- Scanner integration
- Media items listing
Notes:
- Tests designed to run against live server on localhost:8765
- Integration test script uses bash/curl for endpoint testing
- Device tests require helper functions to be implemented
- Remove ebook-specific test files (ebook_test.go, integration_test.go, notes_highlights_test.go)
- Update search_test.go for media-items API paths
- Regenerate templates (bookshelf_templ.go, header_templ.go)
- Add ISBN normalization utility function
- Clean up test suite to focus on media-items functionality
Aligns tests and templates with unified media-items architecture
Major changes:
- Rename testEbooks() function to testMediaItems()
- Remove all old ebook test cases
- Update all /api/ebooks paths to /api/media-items
- Update TestContext: remove EbookID, add MediaItemID field
- Add admin media-items tests (Create, Update, Delete)
- Fix compilation errors and missing imports
Tests updated to use new API structure while maintaining test coverage.
Breaking change: /api/ebooks endpoints removed (use /api/media-items instead)
- Add integration tests for sorting (sorting_test.go)
- Test sort by title, author, page_count, copyright_year, genre
- Test pagination with sorting
- Test invalid sort parameter defaults
- Cover no user, user, and admin contexts
- Add integration tests for filtering (filtering_test.go)
- Test filter by genre, language, year range, has_cover
- Test combining multiple filters
- Test filtering with pagination and sorting
- Cover no user, user, and admin contexts
- Add Bruno API test for sorting
- Add Bruno API test for filtering
- Add explicit status code check (require.Equal 201)
- Remove conditional success/failure branching
- Provide clear error message with actual vs expected status
Now if CreateLibrary returns 500, test will clearly show:
"Failed to create library: expected 201, got 500"
Instead of vague "Library ID is empty" message that hid the 500 error.
- Add comprehensive search integration tests (search_test.go)
- Test no user, user, and admin contexts
- Test partial matching, fuzzy fallback, special characters
- Add Bruno API test for search endpoint
- Fix missing closing parenthesis in test structure
- Added direct /bookshelf route that works with both Authorization header and cookie token
- Imported missing strings package
- Users can now access /bookshelf directly instead of /api/bookshelf
- Add /bookshelf route as default page for logged-in users
- Update login and register handlers to redirect to /bookshelf
- Update homepage to auto-redirect to /bookshelf when logged in
- Preserve /dashboard route for backward compatibility
- Update test redirects to use /bookshelf
Changes:
- main.go: Add /bookshelf protected route
- auth.go: Change login/register redirects from /api/dashboard to /bookshelf (2 locations)
- edge_cases_test.go: Update test redirect to /bookshelf
- Maintains backward compatibility with existing /dashboard route
This makes the beautiful bookshelf the default landing page
for all authenticated users while keeping the old dashboard accessible.
- Add fallback to login when user registration returns 409 Conflict
- Prevents empty user token error when test user already exists
- Allows integration tests to run reliably across multiple executions
- Test now attempts to log in with existing credentials if registration fails
This fixes the issue where the test would fail if the user
'integrationuser@test.com' already existed from a previous test run.
- Fix scheduler.go log.Printf calls to convert pgtype.UUID to string before formatting
- Fix ebook.go fmt.Printf calls to convert pgtype.UUID to string before formatting
- Add missing Enabled field to rate limiter config in security test
- Prevents format string errors when logging library IDs
This resolves compilation errors where pgtype.UUID was being formatted
with %s which expects a string, not a UUID struct.
- Fix SetLibraryVisibility request format (library_ids -> library_id)
- Fix UpdateReadingProgress HTTP method (POST -> PUT)
- Fix DeleteMediaNote expected status (200 -> 204)
- Add cleanupTestData() helper for better test cleanup
- Improve Setup_CreateDuplicateTestUsers to handle existing data
- Add graceful handling of 409 and 429 responses
- Update password test to create/delete temporary user
- Add test requirements comment at top of file
These changes improve test reliability and reduce flakiness.
- Add TestMode, RateLimitEnabled, RequestsPerMinute to Config
- Add getEnvBool() and getEnvInt() helper functions
- Update rate limiter to support enabled/disabled state
- Pass test environment variables through docker-compose
- Configure rate limiter dynamically in main.go
This allows disabling rate limiting for integration testing while
maintaining security in production environments.
- Increase ISBN column from VARCHAR(13) to VARCHAR(17) to support ISBN-13 with hyphens
- Add normalize_isbn() database function to automatically remove hyphens and spaces
- Create trigger to auto-normalize ISBNs on INSERT/UPDATE operations
- Update all Ebook and MediaItem queries to use ISBN normalization
- Add GetEbookLibraryID query to check for existing ebook libraries
- Add graceful error handling when no ebook library exists
- Return helpful error message: 'no ebook library found. Please create an ebook library first'
- Create comprehensive tests for ISBN normalization and library selection
- Add Bruno test files for various ISBN formats and error scenarios
- Update documentation with ISBN normalization details
- Update scan endpoint test to expect HTTP 202 with job ID
- Add tests for new scan job status endpoint
- Add tests for watch mode start/stop/status endpoints
- Update all scanner tests to reflect async behavior
- All tests passing
- Add RequestTracingMiddleware to middleware chain
- Auto-start scheduler for auto-scanning on server boot
- Auto-start watch mode for all libraries with 2-second delay
- Update SetupRoutes to return handler for service management
- Test password complexity requirements
- Test account lockout mechanism
- Test rate limiting functionality
- Test JWT expiration (1 hour)
- Test refresh token expiration (7 days)
- Test password requirements list
- Verify transaction manager and error handler types
- All tests passing
- Add rate limiter middleware (10 requests/minute per IP)
- Apply rate limiting to POST /api/auth/register and /api/auth/login
- Prevents brute force attacks and registration spam
- Automatic cleanup of old request records
Closes security issue: No rate limiting on auth endpoints
This major update implements a complete user annotation system:
## 🎯 New Features
- User notes with position tracking for media items
- Text highlighting with customizable colors
- Highlight-note associations for detailed annotations
- Full CRUD API for both notes and highlights
- Backward compatibility with existing ebook endpoints
## 📊 Database Changes
- Add media_notes table (id, media_item_id, user_id, content, position, timestamps)
- Add media_highlights table (id, media_item_id, user_id, selection_text, start/end_position, color, optional note_id)
- Add foreign key relationships with CASCADE deletes
- Add proper indexes for performance
- Add database schema views for ebook backward compatibility
## 🔧 API Implementation
- Complete REST API endpoints for notes and highlights
- JWT authentication with proper middleware bypass
- Request validation with meaningful error responses
- UUID validation and type safety
- Support for hex color codes in highlights
## 🧪 Testing & Documentation
- Comprehensive test suite covering authentication scenarios
- Bruno API collection for manual testing
- Detailed testing guide with troubleshooting
- Updated documentation in README and TESTING.md
## 📁 Backward Compatibility
- Existing ebook endpoints continue working
- Database views maintain API contracts
- No breaking changes for existing integrations
The annotation system is now fully functional and ready for production use.
- Fix undefined variable 'resp' errors in library_test.go (should be 'req')
- Fix authentication test expectations to match unauthorized response
- Fix TestUserVisibleLibraries to properly simulate user visibility filtering
- Remove hidden library from mock user response to test visibility correctly
- All tests now pass successfully
- Add complete test suite for media notes API with validation
- Add complete test suite for media highlights API with color validation
- Add backward compatibility tests for ebook endpoints
- Test authentication scenarios (unauthorized access)
- Test request validation and error handling
- Fix existing test import issues and syntax errors
- Add test cases for highlight-note associations
- Add authentication middleware tests for JWT validation
- Add library creation tests for admin authorization
- Add library visibility control tests
- Add user management and error handling tests
- Add JSON validation and security tests
- Add tests for both success and failure scenarios
- Test edge cases like missing tokens, invalid data, unauthorized access
- Use httptest for isolated API testing without needing running server
- Include comprehensive test coverage for security and functionality
Tests verify application security and multi-library system works correctly before deployment.
- Update JWT middleware to set complete user object in context
- Parse UUID correctly and convert to pgtype.UUID format
- Add missing imports for uuid and pgx/v5/pgtype
- Fix type conversion from UUID string to byte array
- Ensure compatibility with database.Users struct
Resolves authentication issues for library and user endpoints
- Add library routes to main router configuration
- Implement media items API endpoints for library content
- Update existing ebook handlers to use new schema
- Add media rating and progress tracking
- Maintain backward compatibility with existing endpoints
- Support library-specific media item queries
Updates application to support new multi-library architecture
- Add AdminMiddleware for protecting sensitive operations
- Update JWT generation to include user role and details
- Modify login/registration to use enhanced JWT claims
- Update main.go to set admin-protected routes
- Add user role to JWT context for downstream handlers
- Add tailwind.config.js with theme color configuration
- Add package.json with build scripts and dependencies
- Add Dockerfile Node.js setup for CSS building
- Add input.css for Tailwind processing
- Update all templates to use local CSS and JS instead of CDN
- Add static file serving in main.go
- Download htmx during build process
- Enable CSS minification for production builds
john-okeefe