Komga integration is broken

[gabeklavans]

When I tried to set up komga integration, I kept receiving this error:

Receiver error: receiving on a closed channel

I tried various configurations, both with and without my reverse proxy, to get ryot to talk to komga, even over LAN, and I couldn't prevent this error from ocurring.

Discussions in the discord may point to the fact that komga now has a proper API for requesting information that ryot would want from an instance and that ryot should be updated to support it

https://komga.org/docs/openapi/get-read-progress-tachiyomi-v-2

[IgnisDa]

I had Claude analyze the new API and here are the results if anyone wants to try.

---

Komga API Migration Guide

Overview

This document outlines the required changes to migrate Ryot's Komga integration from the
current deprecated API endpoints to the new Komga API (version 1.22.0).

Current Integration

The Komga integration in Ryot consists of two main functions:

1. sync_to_owned_collection - Syncs Komga series to Ryot's "Owned" collection
2. yank_progress - Real-time progress tracking via Server-Sent Events

Current API Usage

• Series listing: GET /api/v1/series?unpaged=true
• Individual book: GET /api/v1/books/{bookId}
• Individual series: GET /api/v1/series/{seriesId}
• Progress events: GET /sse/v1/events (SSE)
• Authentication: HTTP Basic Auth

Critical Changes Required

1. Deprecated Series Endpoint

Status: 🚨 BREAKING CHANGE

The current series listing endpoint is deprecated since Komga v1.19.0.

Current Implementation (line 486-493 in komga.rs):

let series: komga_series::Response = client
    .get(format!("{}/{}", url, "series?unpaged=true"))  // ❌ DEPRECATED
    .basic_auth(username, Some(password))
    .send()
    .await?
    .error_for_status()?
    .json()
    .await?;

Required Migration:

let series_request = SeriesSearch {
    condition: None,  // Empty search for all series
};

let series: PageSeriesDto = client
    .post(format!("{}/series/list", url))  // ✅ NEW ENDPOINT
    .basic_auth(username, Some(password))
    .query(&[("unpaged", "true")])
    .json(&series_request)
    .send()
    .await?
    .error_for_status()?
    .json()
    .await?;

2. Response Structure Changes

Current: Direct content array

pub struct Response {
    pub content: Vec<Item>,
}

New: Paginated response structure

pub struct PageSeriesDto {
    pub content: Vec<SeriesDto>,
    pub number: i32,
    pub size: i32,
    pub total_elements: i64,
    pub total_pages: i32,
    // ... other pagination fields
}

3. SSE Endpoint Status

Status: ⚠️ NEEDS VERIFICATION

The /sse/v1/events endpoint is not documented in the OpenAPI spec. This could indicate:

• The endpoint is deprecated
• It's undocumented but still functional
• Alternative approaches are available

Alternative: Consider using /api/v1/history endpoint for historical events (requires ADMIN role).

Compatible Endpoints

✅ No Changes Required

• Individual book: GET /api/v1/books/{bookId}
• Individual series: GET /api/v1/series/{seriesId}
• Authentication: HTTP Basic Auth still supported

New Capabilities

Enhanced Search Options

The new SeriesSearch schema provides advanced filtering:

pub struct SeriesSearch {
    pub condition: Option<SearchCondition>,
}

pub struct SearchCondition {
    pub age_ratings: Option<Vec<String>>,
    pub genres: Option<Vec<String>>,
    pub languages: Option<Vec<String>>,
    pub publishers: Option<Vec<String>>,
    pub collections: Option<Vec<String>>,
    pub read_status: Option<Vec<String>>,
    // Boolean operations
    pub all_of: Option<Vec<SearchCondition>>,
    pub any_of: Option<Vec<SearchCondition>>,
    pub none_of: Option<Vec<SearchCondition>>,
}

Historical Events API

New /api/v1/history endpoint could supplement or replace SSE functionality:

• Requires ADMIN role
• Provides historical event tracking
• More reliable than SSE for batch processing

Migration Plan

Phase 1: Critical Updates (Required)

1. Update series listing endpoint

   • Replace GET with POST request
   • Add request body with SeriesSearch schema
   • Update response parsing for PageSeriesDto

2. Test SSE endpoint

   • Verify /sse/v1/events still works
   • Document any issues found

Phase 2: Enhanced Features (Optional)

1. Implement enhanced search

   • Add filtering capabilities
   • Improve performance for large libraries

2. Historical events integration

   • Add fallback to /api/v1/history endpoint
   • Implement batch progress updates

Phase 3: Optimization (Future)

1. Pagination support

   • Handle large series collections efficiently
   • Implement proper pagination logic

2. Error handling improvements

   • Better validation error messages
   • Retry logic for failed requests

Files to Update

Primary Files

• /crates/services/integration/src/yank/komga.rs (lines 486-493)

Data Models

• Update komga_series::Response to PageSeriesDto
• Add SeriesSearch request model
• Update error handling for POST requests

Testing

• Update integration tests
• Test with various Komga versions
• Verify SSE endpoint functionality

Timeline

• Immediate: Update deprecated series endpoint
• Short-term: Verify SSE endpoint and implement alternatives
• Long-term: Implement enhanced search and pagination features

Risks

1. Breaking changes: Current integration will fail with newer Komga versions
2. SSE dependency: Progress tracking may break if SSE endpoint is removed
3. Data format changes: Response parsing needs updates

Success Criteria

• Series listing works with new POST endpoint
• All existing functionality preserved
• SSE endpoint status verified
• Integration tests pass
• Performance maintains or improves