Dannex Download Manager
  1. Início
  2. Ajuda
  3. Arquitetura

Arquitetura

Como as partes do Dannex Download Manager se encaixam.

Crates

Caminho Crate Função
crates/engine mdm-engine Transfere um ficheiro por HTTP(S) ou FTP(S): sonda, planeador de segmentos, trabalhadores de ligação, estado de retoma, limites por anfitrião, limitador de velocidade, somas de verificação, scripts de proxy
crates/app mdm-app A aplicação de ambiente de trabalho (dannexdownloadmanager.exe, egui): lista, categorias, filas, agendador, diálogos, tabuleiro, definições
crates/cli mdm-cli Transferências sem interface com progresso (get, resume), vídeos, torrents e comandos da API de automação: uma biblioteca executada pelo programa da aplicação (dannexdownloadmanager --cli …), e dannexdownloadmanager-cli, um pequeno iniciador que executa a biblioteca com os mesmos argumentos, terminal e código de saída
crates/mcp mdm-mcp O servidor MCP (dannexdownloadmanager-mcp): os assistentes de IA usam a API de automação para listar, adicionar e controlar as transferências da aplicação em execução
crates/remote mdm-remote O controlo remoto (#141): o servidor HTTPS que um telemóvel ou computador emparelhado na rede local usa (a sua página, códigos de emparelhamento, tokens de dispositivo, o certificado autoassinado); cada pedido torna-se um comando da API de automação a que a aplicação responde
crates/nmhost mdm-nmhost O anfitrião de mensagens nativas do navegador: recebe as transferências capturadas da extensão e as entrega à aplicação
crates/ipc mdm-ipc O canal de instância única (um socket local protegido por token), a pasta de dados e as regras de captura partilhadas pela aplicação e pelo anfitrião
crates/debrid mdm-debrid Contas Debrid (#44): as APIs oficiais dos serviços (Real-Debrid, AllDebrid, Premiumize, TorBox) transformam uma ligação de um anfitrião de ficheiros numa ligação direta que o motor transfere
crates/extract mdm-extract Extração de arquivos (#37): zip, tar, gz e xz em processo; 7z e RAR através de um 7-Zip instalado, executado como programa próprio
crates/geo mdm-geo Onde está o servidor de uma transferência (#140): uma tabela de intervalos de IP para país, construída a partir dos dados Lite do DB-IP (tools/geo/build.py), consultada apenas neste computador, e as bandeiras dos países
crates/tools mdm-tools Páginas de vídeo através de yt-dlp e ffmpeg, galerias de imagens através de gallery-dl (executados como programas separados); quando é escolhido um adaptador de rede, as ligações passam por um proxy do DDM em 127.0.0.1, que as encaminha através desse adaptador (relay.rs)
crates/crash mdm-crash Relatórios de falhas e bloqueios: o processo de monitorização, minidumps fora do processo, pilhas simbolizadas, o texto do relatório e os registos de lançamento (crash-reports.md)
crates/torrent mdm-torrent BitTorrent e ligações magnéticas através de librqbit
crates/labserver mdm-labserver Um servidor HTTP Range com registo de pedidos e injeção de falhas, e um servidor FTP/FTPS com falhas próprias, para testes e testes de desempenho
extension/ — A extensão para Chromium (MV3) e Firefox
docs/ — O guia do utilizador e os tutoriais, este ficheiro e os dados dos testes de desempenho; o site usa o guia como páginas de ajuda, que são abertas através de Ajuda
website/ — As páginas próprias de dannex.kavangi.co.ke (início, transferência, funcionalidades, temas, FAQ); tools/website/build.py adiciona a ajuda de docs/ e as notícias do CHANGELOG, em 22 idiomas, e o GitHub Pages publica-o

As dependências apontam para dentro: app, cli, mcp, nmhost e remote usam engine e ipc; o motor não sabe nada da IU. A aplicação vê o motor apenas através dos seus eventos (progresso, instantâneos da tabela de segmentos, concluído, falhou).

Motor

Download
 ├─ probe()              size, resumable?, validators (ETag / Last-Modified), file name
 ├─ Planner (pure)       segment table: when a connection is free, the largest remaining
 │                       part is split in half (planner.rs, tested by random simulation)
 ├─ Worker × N           one HTTP/1.1 connection each, reused across segments; slow ones
 │                       are dropped and their part re-split
 │    └─ writes at its offset into <name>.mdm.part (created sparse)
 ├─ HostLimits           learns how many connections each server accepts
 ├─ Limiter (shared)     per-download and global token buckets
 ├─ State                segment table saved atomically (craft-atomic) for crash-safe resume
 └─ events → channel     Progress, Done, Failed

Quando todos os segmentos estão concluídos, o ficheiro temporário é verificado face ao tamanho esperado e colocado no destino com o nome final; a data do ficheiro pode ser a do servidor.

O primeiro pedido de uma transferência (get) segue redirecionamentos e páginas que levam a um ficheiro por si só (como a atualização automática de uma página de espera). Os sites cujas ligações não correspondem ao endereço do ficheiro têm um módulo em sites/ (Google Drive: sites/gdrive.rs): esse módulo transforma a ligação no endereço do ficheiro, lê as páginas do próprio site (um formulário de confirmação, uma página de erro) e identifica os motivos de recusa (Error::Refused), recorrendo a funções puras testadas sem ligação à rede. O servidor de laboratório simula esse site nos nomes de anfitrião reais para os testes de ponta a ponta (labserver/src/drive.rs).

FTP e FTPS (ftp.rs) usam o mesmo planeador, processos de ligação e estado: um segmento é REST + RETR numa sessão de controlo, em vez de um GET com intervalo; SIZE e MDTM substituem os cabeçalhos, e as sessões são agrupadas por transferência e reutilizadas entre segmentos.

Aplicação

Uma janela egui desenhada em coordenadas de píxeis fixas, mais uma área de visualização imediata por cada caixa de diálogo. app.rs guarda o estado (transferências, filas, definições, a seleção da lista) e transforma os comandos de menu, barra de ferramentas, teclado e IPC em ações. Cada caixa de diálogo é o seu próprio módulo e devolve um Outcome (aberta, fechada, concluída com um valor). As chamadas exclusivas do Windows estão confinadas a win32.rs e as suas contrapartes para Linux e macOS a unix.rs (a iniciar com a sessão, o anfitrião dos navegadores, sons, mostrar na pasta, o gestor de falhas); todos os outros ficheiros são Rust seguro e portátil. As fontes vêm do sistema: a pasta Fonts do Windows, as fontes de sistema do macOS, fontconfig no Linux (theme.rs). No Windows, o texto latino, grego e cirílico é desenhado por DirectWrite (win32.rs, através do "hook" do rasterizador de glifos do egui): Ver → Texto → Suave no seu modo natural, com "anti-aliasing" no tamanho pedido e colocado em quartos de píxel com os avanços da própria fonte; Clássico (o predefinido) no modo GDI-clássico, para que a forma "hinted" e a largura de píxel inteiro de cada letra se juntem. Outros scripts são formatados e desenhados por egui.

Temas

Cada cor e tamanho com que um controlo é desenhado provém do tema ativo (#45). Um tema é uma paleta clara e escura, métricas, estilos de controlo e um estilo de ícone (palette.rs):

  • Funções da paleta. palette.rs declara cada função com uma chave estável ("button.hot", "list.row", "caption"…), uma descrição e os valores claro e escuro do aspeto clássico, escritos por extenso (o aspeto clássico não é derivado). Os pintores partilhados (winui.rs, chrome.rs, list.rs, scrollbar.rs) leem-nos através de theme::colors() e theme::metrics() e decidem os estados de cada controlo a partir deles; nenhum código de pintura contém uma cor própria.
  • Paletas derivadas. derive.rs cria uma paleta completa a partir de algumas sementes (fundo, superfície, texto, destaque…), misturando todas as outras funções em OKLab e mantendo o contraste WCAG (4.5:1 para texto, 3:1 para arestas); o Alto contraste reforça cada aresta por cima. native.rs semeia o tema Nativo a partir do destaque e contraste do sistema (definições do Windows, o portal freedesktop no Linux, o destaque do macOS).
  • Estilos de controlo. palette::Controls nomeia a forma de cada controlo (caixas de texto, caixas de verificação, botões, barras de progresso, barras de deslocamento, a marca de foco, a barra de título); os temas de estilo (Metro, Adwaita, Breeze, Luna, Aero, Aqua, Emerald) escolhem os seus, e no Windows o DDM desenha a própria barra de título (as funções caption.*).
  • Ficheiros de tema. themefile.rs lê TOML ou JSON da pasta de dados themes (um ficheiro, ou <id>/theme.toml com ícones ao lado). Um ficheiro nomeia apenas o que altera; o resto vem do tema que inherits (um ID incorporado ou outro ficheiro, o aspeto clássico por predefinição), numa cadeia em que um ciclo é recusado. Chaves desconhecidas são avisos, não erros. Os temas de estilo incorporados também são esses ficheiros, transportados no programa (crates/app/assets/themes).
  • Conjuntos de ícones. themeicons.rs desenha os ícones de um tema (nomeados pelo que servem: tb-add-url, cat-music…, SVG ou PNG a 16, 24, 32 e 48 px, -symbolic tintados na cor do texto) onde o aspeto clássico desenha os seus; uma necessidade que o conjunto não tem mantém o ícone clássico.
  • Estilos dos ícones da barra de ferramentas. Ver → Barra de ferramentas → Estilo de linhas (os contornos, pintados como o tema indica) ou Estilo 3D: as imagens brilhantes do próprio DDM (assets/icons/toolbar3d, desenhadas por tools/icon/toolbar_3d.py de 16 a 64 px, a do tamanho em uso no ecrã; a cinzento por icons.rs quando desativadas). Aplicam-se onde o tema não tem ícone próprio para um botão, e os ícones têm as suas próprias cores; um tema com um conjunto de ícones, ou que pinta os ícones de uma só cor (Alto contraste), mantém o seu.

Onde uma janela coloca os seus controlos mantém o seu esquema. O mesmo acontece com os ícones antes dos nomes dos ficheiros (fileicons.rs): as listas de imagens do sistema da shell do Windows, do Finder do macOS (NSWorkspace), o tema de ícones do ambiente de trabalho Linux (xdgicons.rs, shared-mime-info e a Especificação de Tema de Ícones). Cada tipo é procurado uma vez por tamanho de pixel, num processo em segundo plano. Os ícones do Tango (incluídos) são usados até que o ícone do sistema esteja pronto, e onde o sistema não tem nenhum.

Desenho

As janelas são desenhadas com OpenGL (o brilho do eframe) ou com a API gráfica do próprio sistema através do wgpu do eframe, com apenas esse backend: Direct3D 12 no Windows (a predefinição lá), Vulkan no Linux, Metal no macOS (escolhas lá; OpenGL permanece a predefinição até que as placas gráficas reais os tenham experimentado, #206). Ver → Desenhar com escolhe um, a partir do próximo arranque. Um caminho de código faz isso em todos os sistemas (crates/app/src/renderer.rs): quando o escolhido não consegue iniciar, o outro é tentado, para que as janelas abram sempre. Um arranque monitorizado com a API do sistema deixa um marcador até que o seu primeiro fotograma seja desenhado: um arranque que termina antes disso (uma falha dentro do controlador), um cujo primeiro fotograma não chega em 10 segundos (o DDM então reinicia com OpenGL), ou uma placa gráfica perdida duas vezes em 10 minutos é lembrada com a sua razão, que o menu mostra.

Ver → Tamanho da interface (scale.rs, #262) é o fator de zoom do egui sobre a escala do próprio ecrã: cada janela é disposta em pontos, por isso abre muito maior; uma maior que o ecrã rola.

Dados

A lista de transferências e as definições são guardadas atomicamente na pasta de dados (downloads.json): %APPDATA%\dannexdownloadmanager\ no Windows, ~/.local/share/dannexdownloadmanager no Linux, ~/Library/Application Support/dannexdownloadmanager no macOS, uma pasta data ao lado de uma cópia portátil, ou MDM_DATA_DIR (mdm_ipc::data_dir). O anfitrião do navegador lê o mesmo ficheiro para as regras de captura, por isso uma alteração em Opções aplica-se à próxima transferência capturada.

Os segredos de início de sessão (contas debrid, palavras-passe de Inícios de Sessão de Sites e do proxy) residem no porta-chaves do sistema (secrets.rs, #44): Gestor de Credenciais do Windows (win32.rs), o Secret Service no Linux ou o porta-chaves do macOS (unix.rs). As definições mantêm uma referência keychain:<service>/<scope>/<key> no seu lugar, escrita apenas depois de o porta-chaves ter confirmado o segredo; sem um porta-chaves (ou com um bloqueado, nunca desbloqueado para o DDM) o segredo permanece nas definições como antes.

A localização do servidor de uma transferência (#140) é o país do endereço ao qual se ligou, procurado na tabela de mdm-geo neste computador (countries.rs nomeia-o no idioma da interface); a tarefa de lançamento reconstrói a tabela a partir dos dados do mês (tools/geo/build.py --release).

Integração com o navegador

page ──► extension ──native messaging──► mdm-nmhost ──ipc──► app

A extensão pergunta ao anfitrião que tipos de ficheiro deve aceitar, verifica cada transferência em relação a eles e cancela a transferência do navegador apenas depois de a aplicação a ter aceite; caso contrário, o navegador mantém-na e a extensão explica o motivo.

A mesma resposta traz as teclas de Opções → Geral (keys: pelo que o page.js reconhece um clique, para deixar uma ligação ao navegador ou forçá-la para a aplicação) e os itens do menu de contexto a mostrar (menu: o background.js refaz o seu menu quando mudam); a resposta sobre se o botão de vídeo pode aparecer traz as definições de Painéis de Transferência (panel: sobre vídeos ou leitores de som, a duração mínima, o primeiro canto). Os nomes e os valores por omissão são os de mdm_ipc::capture, lidos das definições que a aplicação guarda. A extensão pergunta de novo quando a janela do navegador volta a ter o foco (alguns segundos depois da última vez que perguntou), quando uma página arranca (15 s) e numa transferência (um minuto).

A lista de transferências da janela pop-up da barra de ferramentas (Interromper, Retomar, Abrir pasta) e o número do botão são o list e as ações da API de automatização, pedidos através do anfitrião com browser definido: a aplicação responde-lhes seja qual for o interruptor da API, tal como responde ao menu de qualidades do botão de vídeo, e o anfitrião nunca inicia a aplicação por causa deles. A extensão só pergunta enquanto a janela pop-up está aberta ou há transferências em curso.

O anfitrião serve apenas a extensão própria do DDM. Os seus IDs estão num só lugar, mdm_ipc::extension (crates/ipc/src/extension.rs): o da cópia descompactada (UNPACKED_ID, da chave pública do manifesto), o da Chrome Web Store (STORE_ID, assinado com a chave própria da loja: pack.ps1 omite a chave do manifesto da cópia da loja), o do suplemento do Firefox (FIREFOX_ID) e a sua página addons.mozilla.org; os das lojas Edge e Opera são marcadores de posição, nunca servidos, até que a extensão seja listada lá. O anfitrião escreve o manifesto de cada navegador com esses IDs, e a aplicação oferece a cópia da loja (Adicionar ao Chrome, Adicionar ao Firefox) antes da descompactada.

Controlo remoto

phone ──HTTPS (paired token)──► mdm-remote ──ipc::Sink──► app (answer, remote_add)

--headless(headless.rs, #157) executa o mesmo App sem eframe: um ciclo chama o seu tick (o que logic executa em cada fotograma) num egui::Context simples, ativado pelo canal de comando, e nunca o seu ui; os comandos são adicionados à medida que o controlo remoto os adiciona (sem janela). O Dockerfile e o docker/ (Compose, modelo do Unraid) executam-no num servidor (server.md).

O servidor é executado no runtime Tokio da aplicação, um ouvinte por endereço de rede local. Cada pedido é verificado (Host, Origin, token), transformado num mdm_ipc::Command marcado remote (um campo que nenhuma linha de pedido pode definir) e entregue à aplicação através do mesmo canal que o da linha de comandos; a aplicação responde-lhe no seu próximo frame, tal como responde à API de automação. A sua página é incorporada (crates/remote/web) e os seus textos vêm dos catálogos da aplicação (remote.rs).

Traduções

Cada texto que a IU mostra passa por crate::i18n (catálogos craft-i18n, i18n/<locale>.tsv). tools/i18n/extract.py reconstrói i18n/en.tsv a partir da fonte, com uma nota para os tradutores em cada texto (o que é, onde aparece, os seus marcadores de posição). tools/i18n/translate.py preenche o que falta nos outros catálogos (linhas marcadas #, machine), seguindo o guia de estilo de cada idioma (i18n/style/) e o glossário; uma linha revista por uma pessoa nunca é substituída, e o CI (reviewed_guard.py) falha uma alteração que a elimine. O site tem os seus próprios catálogos (i18n/site/, tools/website/translate_site.py).

Imagens

O ícone da aplicação é desenhado a partir de geometria (tools/icon/dannex_logo.py; build_icon.py escreve todos os tamanhos, colocados à mão em píxeis inteiros de 16 a 48 px). Cada local que o mostra usa o desenho do tamanho em uso no ecrã (logo.rs): no Windows, os ícones da barra de título e da barra de tarefas de cada janela na escala do respetivo ecrã (win32::crisp_icons, que também os mantém ao mudar para outro ecrã), o da bandeja na da barra de tarefas. Ver → DDM Ícone da bandeja mostra-o a cores (Estilo 3D) ou apenas a marca na cor da barra de tarefas (Estilo plano: branco numa barra de tarefas escura, escuro numa clara; uma imagem modelo no macOS), com uma barra fina na base enquanto há transferências em curso.

As imagens das páginas de ajuda (docs/images/help/) provêm de uma lista, tools/shots/shots.toml: tools/shots/make.py abre cada janela através da linha de comando /show <window> do próprio DDM numa instância de teste fora do ecrã, recorta e anota-a a partir da árvore de acessibilidade da janela e escreve WebP sem perdas; make.py check (CI) mantém a lista, as páginas e os ficheiros em sincronia. As publicadas são tiradas no executor do Windows do GitHub (docs-shots.yml).

Contribuidores

tools/contributors.pylê quem abriu pedidos de pull e problemas, e quem comentou, a partir da API pública do GitHub (o mantenedor, Claude e bots excluídos) para cada local que lhes agradece: a página inicial do site, /contributors.html e cada lançamento na página Notícias (build.py, em cada compilação), as notas de cada lançamento (release.yml, as pessoas ativas desde o lançamento anterior) e o README (python tools/contributors.py readme na preparação de cada lançamento: as suas fotos redondas são submetidas em art/contributors/, uma vez que o GitHub não consegue arredondar uma imagem num README).

Testes e benchmarks

cargo testexecuta testes unitários e transferências de ponta a ponta contra mdm-labserver com falhas simuladas (ligações lentas, interrompidas e recusadas, servidores sem suporte para intervalos, ficheiros que mudam). tools/bench executa a comparação de velocidade publicada; os dados em bruto estão em docs/bench/.

Os fotogramas das janelas são medidos, não adivinhados (crates/app/src/framestats.rs): MDM_FRAME_STATS=1 regista, a cada segundo, as passagens da janela principal, quantas resultaram de ações do utilizador, quanto custaram (a janela principal, as janelas de progresso, a sua disposição) e que linhas de código pediram as restantes; MDM_SYNTHETIC_LIST=10000 (com um MDM_DATA_DIR temporário) acrescenta outras tantas linhas inventadas; MDM_BENCH_SCROLL=10 desloca a lista sozinho durante dez segundos e regista os tempos dos fotogramas. Uma janela inativa só tem os fotogramas do seu relógio (um a cada 2 s); a lista desenha apenas as linhas visíveis.

Gratuito, de código aberto, sem anúncios, sem período de avaliação.

Transferir Dannex Download Manager