diff --git a/README.md b/README.md index efbf2a2..5ad854e 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ **Proxy de download efêmero: a sua VPS baixa o arquivo por uma rota melhor e entrega para o seu navegador, com os arquivos apagados automaticamente depois.** +[![CI](https://github.com/evandrodevbr/Downloader/actions/workflows/ci.yml/badge.svg)](https://github.com/evandrodevbr/Downloader/actions/workflows/ci.yml) ![Node](https://img.shields.io/badge/Node-%3E%3D20.19-5FA04E?logo=nodedotjs&logoColor=white) ![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white) ![Fastify](https://img.shields.io/badge/Fastify-5-000000?logo=fastify&logoColor=white) @@ -49,8 +50,8 @@ navegador ## Requisitos -- Node.js 20.19 ou superior (exigência do Vite 7 e do undici 7; verificado no Node 24.20.0) -- pnpm 9 ou superior (verificado no pnpm 12.4.1; o lockfile é o formato 9.0) +- Node.js 20.19 ou superior para rodar e fazer o build (exigência do Vite 7 e do undici 7). Para rodar os testes (vitest 5) use Node 22.12 ou superior. +- pnpm 9 ou superior (verificado no pnpm 12.8.1 com Node 26.7.0; o lockfile é o formato 9.0) - Portas livres: backend (padrão 3000) e Vite (5173) em desenvolvimento Observação sobre pnpm: a seção `overrides` do `pnpm-workspace.yaml` (fastify e undici com versão mínima de segurança) só é aplicada pelo pnpm 10 ou superior. Com pnpm 9 ela é ignorada. @@ -90,7 +91,7 @@ PORT=3100 VITE_API_PROXY=http://localhost:3100 pnpm dev | GET | `/api/download/:taskId` | Entrega o arquivo concluído da task. | | GET | `/stream` | Descontinuado: responde 410. | -A sessão é identificada pelo header `x-session-id` (a interface guarda o id em `localStorage`). Erros observados: 400 para URL inválida (`{"error":"Invalid URL"}`) ou download não pronto, 403 para task de outra sessão e 404 para task inexistente. Se a origem falhar (por exemplo, 404 no host de origem), a task fica com `status: "error"` e a mensagem em `error`. +A sessão é identificada pelo header `x-session-id` (a interface guarda o id em `localStorage`). Erros observados: 400 para URL inválida (`{"error":"Invalid URL"}`), com protocolo que não seja http/https, apontando para endereço local ou privado, ou para download não pronto; 403 para task de outra sessão e 404 para task inexistente. Se a origem falhar (por exemplo, 404 no host de origem), a task fica com `status: "error"` e a mensagem em `error`. O servidor segue até 5 redirects; um nome de domínio que resolva para IP privado também faz a task terminar em erro. ## Produção @@ -101,50 +102,56 @@ PORT=3000 pnpm start # node server/dist/index.js: API + build do front na mesma O `nixpacks.toml` descreve esse fluxo: build em `pnpm install --frozen-lockfile && pnpm build` e start em `pnpm start`. -Variáveis de ambiente: `PORT` (padrão 3000) e `STORAGE_ROOT` (padrão `server/storage`) no backend; `VITE_API_URL` (host da API no frontend) e `VITE_API_PROXY` (alvo do proxy em dev). +## Configuração + +| Variável | Onde | Padrão | O que faz | +|---|---|---|---| +| `PORT` | backend | `3000` | Porta do Fastify. | +| `STORAGE_ROOT` | backend | `server/storage` | Diretório onde ficam os arquivos das sessões. | +| `ALLOW_PRIVATE_NETWORK` | backend | desligado | Com `true`, permite baixar de `localhost` e de endereços de rede privada. Por padrão o servidor recusa esses destinos (proteção contra SSRF). | +| `VITE_API_URL` | frontend | mesma origem | Host da API, se for diferente do que serve o front. | +| `VITE_API_PROXY` | frontend (dev) | `http://localhost:3000` | Alvo do proxy de `/api` no Vite. | ## Estrutura do projeto ``` server/ backend Fastify ├── src/index.ts rotas (/health, /api/*), CORS e static do front -└── src/lib/ - ├── DownloadManager.ts download da origem com undici e gravação na sessão - └── SessionManager.ts sessões, expiração (1 h) e limpeza dos arquivos +├── src/lib/ +│ ├── DownloadManager.ts download da origem com undici e gravação na sessão +│ ├── SessionManager.ts sessões, expiração (1 h) e limpeza dos arquivos +│ └── netGuard.ts validação de URL e bloqueio de destinos privados (SSRF) +└── test/ testes (vitest) web/ frontend React + Vite ├── src/context/ SessionContext (sessão e polling das tasks) ├── src/components/ ui/ (Input, Button, Card, Alert...) e feature/ (form, item, timer) └── vite.config.ts proxy de /api em desenvolvimento .agent/ scaffolding de agentes de IA (não faz parte do runtime) -docs/PLAN.md vazio (placeholder nunca preenchido) +.github/workflows/ CI (typecheck, lint, testes e build) nixpacks.toml comandos de build e start do deploy pnpm-workspace.yaml workspaces, allowBuilds e overrides ``` -## Verificação +## Testes e desenvolvimento -Não há testes automatizados neste repositório. O que existe de fato: +```bash +pnpm typecheck # tsc nos dois pacotes +pnpm lint # eslint no web +pnpm test # vitest no server e no web +pnpm build +``` -- `pnpm build` roda o `tsc` do server e `tsc -b && vite build` do web, e é o gate atual; -- `pnpm --filter web lint` roda o eslint (passa com 1 warning de `exhaustive-deps` em `SessionContext.tsx`); -- verificação manual executada em 14/09/2026 (Linux, Node 24.20.0, pnpm 12.4.1): `pnpm install` e `pnpm build` com exit 0; 13 checagens de API passando (`/health`, `/`, `/api/session`, `/api/queue` com URL inválida e válida, `/api/tasks`, `/api/download/:id`, 400/403/404 e `/stream` respondendo 410); download de 10 MB conferido por sha256 idêntico ao da origem; interface verificada em Chrome headless (sessão inicializada, task concluída e "Save to Disk" baixando o arquivo com o mesmo sha256). - -Adicionar testes automatizados é o próximo passo natural do projeto. +Os testes do servidor cobrem a validação de URL e o bloqueio de IPs privados, o tratamento de redirects, a expiração de sessões (com remoção das tasks e dos arquivos) e a validação do id de sessão. Os do web cobrem os estados do componente `DownloadItem`. O mesmo conjunto roda no GitHub Actions (`.github/workflows/ci.yml`). ## Estado atual e limitações - Sessões e tasks ficam em memória: reiniciar o servidor perde a lista de tasks (os arquivos em disco são removidos pelo coletor depois de 1 hora). -- Sem autenticação: qualquer um que alcance o servidor pode enfileirar downloads. Coloque atrás de VPN, autenticação reversa ou firewall. +- Sem autenticação: qualquer um que alcance o servidor pode enfileirar downloads (de destinos públicos). Coloque atrás de VPN, autenticação reversa ou firewall. - Não há retomada de download nem uso de `Range` no fluxo atual (o parâmetro `offset` do antigo `/stream` não existe mais). - Não há limite de tamanho, banda ou cota: um link muito grande ocupa o disco do servidor até a sessão expirar. -- URLs que não sejam http/https são aceitas na fila e falham depois com `status: "error"`. -- Sem CI configurada e sem arquivo de licença. +- "Save to Disk" carrega o arquivo inteiro na memória do navegador (`blob()`) antes de salvar, o que pesa em arquivos muito grandes. - O diretório `.agent/` é scaffolding de ferramentas de IA e não é usado pela aplicação. -## Documentação - -Não há documentação interna além deste README: `docs/PLAN.md` está vazio e `web/README.md` é o texto padrão do template do Vite. - ## Licença Sem licença definida no repositório: não existe arquivo `LICENSE` e o `package.json` está marcado como `private`. Defina uma licença antes de reutilizar ou publicar o código.