Critical fixes to prevent goroutine leaks during application shutdown:
1. Sync Queue Processor:
- Changed StartCleanupTask() to return context.CancelFunc
- Modified to accept and watch cancellable context
- Added queue context/cancel to Handler struct
- Created StartBackgroundTasks() method for main handler instance
- Cancel queue processor during shutdown in StopScheduler()
2. Connection Manager:
- Modified StartCleanupTask() to use cancellable context
- Returns cancel function that can be called during shutdown
- Goroutine now properly exits when context is cancelled
3. Handler Lifecycle:
- Added StartBackgroundTasks() to Handler
- Only main handler instance starts background goroutines
- Temporary handler instances (library/sync routes) don't start tasks
- StopScheduler() now properly shuts down all background goroutines
4. Router Integration:
- Updated SetupRoutes to accept queueProcessor parameter
- Main scanner handler starts background tasks after creation
- Library and sync route handlers don't start duplicate tasks
Impact:
- Fixes 2 major goroutine leaks (queue processor + connection cleanup)
- Application now properly shuts down all goroutines on exit
- No more resource leaks from long-running goroutines
- Test added to detect future goroutine regressions
Test: TestGoroutineCleanup verifies background services can be stopped.
- Create worker for background tasks (3 concurrent workers)
- Create CollectionHandler for collection endpoints
- Create MediaHandler with worker for media CRUD operations
- Create SearchHandler for query operations
- Create MatchingHandler for book matching/linking operations
- Update routerConfig to include new handlers instead of EbookHandler
All handlers properly initialized and passed to router package.
System is fully operational with new handler architecture.
This is Phase 6 of the ebook.go refactoring plan.
Remove the CollectionHandler field from router.Config struct and its
initialization in main.go. This field was never used - collections are
registered directly in handlers.SetupRoutes() where a CollectionHandler
is created locally.
Changes:
- Remove CollectionHandler field from internal/router/router.go Config
- Remove CollectionHandler: nil line from cmd/server/main.go
This cleans up dead code from the router refactoring. Collections
continue to work correctly as they are registered in SetupRoutes().
Related: Router refactoring completion
Phase 5: Application Lifecycle Management
Creates internal/app package for proper lifecycle management, signal
handling, and graceful shutdown of all services.
Changes:
- Create internal/app/app.go with App lifecycle manager
- Handles SIGINT, SIGTERM, SIGQUIT signals
- Graceful shutdown with 30-second timeout
- Manages HTTP server shutdown
- Manages scheduler start/stop
- Update cmd/server/main.go to use app lifecycle manager
- Replace defer-based cleanup with proper signal handling
- Server starts in background goroutine
- Blocks on app.Start() until shutdown signal
- Clean shutdown of all services
Benefits:
- Proper signal handling (Ctrl+C, kill, docker stop)
- Graceful shutdown prevents data corruption
- No more os.Exit(1) bypassing defer cleanup
- All services stopped in correct order
- Server stops accepting new connections first
- Then scheduler and background services stopped
Technical details:
- Uses sync.Mutex for shutdown safety
- Context with timeout for shutdown operations
- Channel-based coordination for shutdown completion
- Logs all lifecycle events for debugging
Fixes issue where e.Logger.Fatal() would call os.Exit(1)
immediately, skipping defer cleanup and causing unclean shutdown.
Phase 1 of scanner restoration plan
Changes:
- cmd/server/main.go: Capture ebookHandler from router.RegisterRoutes
- cmd/server/main.go: Start scheduler in background goroutine
- cmd/server/main.go: Defer StopScheduler() for graceful shutdown
- cmd/server/main.go: Start watch mode for all libraries after 2-second delay
- internal/router/router.go: Return ebookHandler from RegisterRoutes
This restores critical functionality that was removed during router refactor:
- Auto-scanning now works again
- Watch mode starts automatically for all libraries
- Graceful shutdown properly stops scheduler
Fixes issue where scheduler and watch mode were not starting on server boot.
Health check endpoint:
- Add /health endpoint that pings database with 2-second timeout
- Returns 200 when DB connected, 503 when unavailable
- Provides true end-to-end health verification
Frontend routes restoration (routes removed in c5f327b):
- Add public routes: /, /login, /register with smart auth detection
- Add redirect routes: /bookshelf, /dashboard
- Add admin routes: /admin, /admin/profile, /admin/library
- Add SSR routes: /api/devices-page, /api/conflicts-page
- Add 'FRONTEND ROUTES - DO NOT DELETE' comment block to prevent future removal
Docker Compose healthcheck:
- Update to use curl on /health endpoint (pg_isready not in Alpine)
- Add 10s start_period for app initialization
- Accurately reflects app + database health status
All changes maintain backward compatibility and existing API behavior.
- Add LibraryData type to templates/types.go
- Update bookshelf template to accept libraries parameter
- Render libraries server-side for faster initial page load
- Libraries now populated from server data instead of AJAX fetch
- JavaScript still uses API for dynamic content (bookshelf items)
- Update /bookshelf route to fetch libraries server-side before render
- Properly handle UUID and pgtype.Text conversions
- Maintain API endpoint compatibility for JavaScript calls
This improves initial page load performance while preserving
dynamic functionality via API calls.
Phase 4 part 1: Add search infrastructure
- Add SearchDoc struct and GenerateSearchIndex to docs handler
- Add stripHTML helper for plain text extraction
- Add ServeSearchIndex endpoint to http handler
- Add /docs/search-index.json route in main.go
- Search index includes all documentation files with ID, title, content, URL
- Add internal/docs package with markdown renderer (goldmark)
- Create docs layout template with sidebar navigation
- Implement hierarchical navigation auto-generated from docs folder
- Add table of contents generator (extract ## headings)
- Add syntax highlighting for code blocks (highlight.js)
- Add mobile responsive design
- Add /docs routes to main.go
The documentation system features:
- Dark theme matching app design
- Collapsible sidebar sections (Getting Started, User Guide, Device Setup, API Reference, Contributing)
- Table of contents for each page
- Breadcrumb navigation
- Full-text search (client-side JavaScript, API endpoint ready)
- Syntax highlighting for code blocks
- Mobile-friendly with hamburger menu
All documentation is served from /docs route, no authentication required.
Markdown files are rendered using goldmark with GFM extensions and syntax highlighting.
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
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
- 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
- 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 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.
- 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.
- 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
- Move migrations/ to database/schema/ for clarity on database schema definitions
- Move sqlc.yaml to internal/database/ to group with database code
- Move static/ to cmd/server/static/ to co-locate with server
- Update all configuration files and documentation
- Follow Go project conventions for better organization
john-okeefe