Komga

Detalhes específicos da integração com Komga, um servidor de biblioteca de quadrinhos self-hosted. Para o modelo geral de fonte remota (dado compartilhado com o Kavita, diálogo de conexão, credenciais, decisão de ações em massa) ver Fontes Remotas; para o Kavita especificamente, ver Kavita.

Autenticação

Basic Auth (usuário + senha) ou API key, à escolha do usuário no momento de conectar. Qualquer uma das duas é cifrada e guardada como descrito em Fontes Remotas.

Organização e modo de raiz

  • Organização FOLDERS: espelha a estrutura real de pastas configurada no servidor Komga. SERIES: uma pasta por série (agrupamento lógico do Komga), arquivos soltos dentro — útil quando a organização de pastas do servidor não bate com a série real do conteúdo.
  • Modo de raiz MERGE: o conteúdo da biblioteca entra direto na raiz do acervo, junto com tudo mais. LIBRARY_FOLDER: entra dentro de uma pasta com o nome da biblioteca Komga.
  • Capas HQ (hqCovers, exclusivo do Komga, desligado por padrão): usa a página em resolução cheia como capa em vez da miniatura padrão do servidor — mais nítido, mas baixa MBs por livro e decodifica uma página inteira só pra virar miniatura; numa biblioteca grande isso pesa na rede e na CPU durante a geração de capas (ver Sistema de Capas).

Múltiplos servidores Komga podem coexistir (cada um sua própria fonte, própria credencial); dentro de um mesmo servidor, cada biblioteca selecionada tem suas próprias opções.

Cliente e endpoints

KomgaClient fala com a API REST do Komga (/api/v1/...) via HttpURLConnection simples. Os pontos usados pelo InkShelf:

  • GET /api/v1/libraries — listagem de bibliotecas, usada tanto pro fluxo de conexão quanto pelo ping leve de disponibilidade.
  • GET /api/v1/books (paginado) — catálogo de livros de uma biblioteca, consumido pelo KomgaScanner.
  • GET /api/v1/books/{id}/thumbnail e GET /api/v1/books/{id}/pages/{n} — miniatura e página em resolução cheia (esta última só quando hqCovers está ligado), usadas por ensureKomgaCover (ver Sistema de Capas).
  • PATCH /api/v1/books/{id}/read-progress — envia progresso (página + completed); DELETE /api/v1/books/{id}/read-progress — desmarca como lido. Diferente do Kavita, o Komga tem um endpoint dedicado de remoção, não precisa reenviar page=0.
  • GET/POST /api/v1/readlists, PATCH /api/v1/readlists/{id} — read lists, usadas como substituto de favoritos (ver abaixo).

Progresso de leitura

KomgaProgressSync empurra o progresso (debounce de 1200ms por livro) via PATCH read-progress; marcar como não lido chama o DELETE dedicado imediatamente, sem debounce. Ler ou marcar como lido/não lido direto no Komga volta pro InkShelf no próximo resync, com a mesma janela de graça descrita em Fontes Remotas.

Favoritos

O Komga não tem favoritos nativos por livro. O InkShelf usa uma Read List chamada "Favoritos" (ou variante reconhecida do nome) como substituto — ver o mecanismo geral em Fontes Remotas. A API de read list do Komga só tem substituição completa (PATCH reescrevendo a lista de bookIds inteira) — não existe endpoint de adicionar/remover 1 item. Por isso KomgaFavoritesSync.push sempre recalcula o conjunto completo de favoritos daquele servidor e reenvia tudo de uma vez, em vez de enviar só o delta (ao contrário do Kavita).

Download

Baixar um item Komga pra leitura offline usa KomgaDownloadService (fila serial, cancelável, notificação de 1º plano). O download falha imediatamente se o servidor não estiver acessível no início do processo, em vez de tentar e ficar preso — checagem feita antes de começar a baixar, não durante.

Sincronização de biblioteca

KomgaScanner lê bibliotecas/séries/livros do servidor e o merge com o Room segue a filosofia geral descrita em Fontes Remotas. Bibliotecas grandes rodam via KomgaSyncService (serviço de 1º plano com notificação de progresso).