# Ephemeral Downloader **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.** ![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) ![React](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=black) ![Vite](https://img.shields.io/badge/Vite-7-646CFF?logo=vite&logoColor=white) ![pnpm](https://img.shields.io/badge/pnpm-9%2B-F69220?logo=pnpm&logoColor=white) ## Sobre Baixar um arquivo grande direto de um host congestionado costuma ser lento, e muitas vezes o gargalo não é a sua internet nem o servidor de origem, e sim o caminho entre eles. O Ephemeral Downloader coloca a sua VPS no meio: o servidor faz o download (normalmente com peering melhor), mostra o progresso em tempo real e entrega o arquivo para você pelo navegador. O projeto é focado em uso efêmero. O arquivo fica em um diretório temporário da sessão no servidor e é apagado quando a sessão expira (1 hora sem interação). Não é um proxy de streaming puro: o download passa pelo disco do servidor antes de chegar até você. ## Como funciona ``` navegador (React + Vite) │ POST /api/queue {url} GET /api/tasks (polling de 2 s) ▼ ▲ Fastify (server/) ──undici GET──▶ host de origem │ │ │ ▼ │ server/storage//_ ────────┘ ▲ │ GET /api/download/:taskId (arquivo concluído) navegador ``` - `POST /api/queue` enfileira a URL e o backend baixa com `undici`, gravando em `server/storage//` por um pipeline (respeita backpressure e só marca a task como concluída depois do arquivo em disco). - O frontend faz polling de `GET /api/tasks` a cada 2 segundos e mostra status, progresso, bytes recebidos, total e velocidade em MB/s e Mbps. - Quando a task conclui, o botão "Save to Disk" busca `GET /api/download/:taskId` e salva o arquivo. - Em produção o próprio Fastify serve o build do Vite na raiz, com fallback da SPA. - `GET /stream` é o proxy antigo, mantido apenas respondendo 410 (descontinuado). ## Stack | Camada | Escolha | |---|---| | Runtime | Node.js 20.19 ou superior | | Backend | Fastify 5, undici 7 (cliente HTTP), zod (validação) | | Frontend | React 19, Vite 7, Tailwind CSS 4, lucide-react | | Linguagem | TypeScript 5.9 | | Monorepo | pnpm workspaces (`server` e `web`) | | Deploy | nixpacks (`nixpacks.toml`) | ## 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) - 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. ## Início rápido ```bash pnpm install # desenvolvimento: Fastify (3000) + Vite (5173) juntos pnpm dev # abra http://localhost:5173 ``` Em desenvolvimento o Vite encaminha `/api` para o backend (proxy configurado em `web/vite.config.ts`), então não é preciso arquivo `.env`. Se a porta 3000 estiver ocupada: ```bash PORT=3100 VITE_API_PROXY=http://localhost:3100 pnpm dev ``` ## Uso 1. Cole a URL direta (http ou https) de um arquivo e clique em **Download**. 2. A lista de downloads mostra status, progresso, tamanho e velocidade, atualizada a cada 2 segundos. 3. Quando o download conclui, use **Save to Disk** para salvar o arquivo na sua máquina. 4. A sessão dura 1 hora de inatividade (o contador reinicia a cada interação) e depois os arquivos são apagados do servidor. ## API | Método | Rota | O que faz | |---|---|---| | GET | `/health` | Devolve `{"status":"ok"}`. | | GET | `/` | Serve a SPA (build do Vite). | | GET | `/api/session` | Cria ou recupera a sessão e devolve `sessionId`, `expiresAt` e `remainingMs`. O id também vem no header `x-session-id`. | | POST | `/api/queue` | Corpo `{"url":"https://..."}`. Enfileira e inicia o download, devolvendo a task criada. | | GET | `/api/tasks` | Lista as tasks da sessão (usado no polling da interface). | | 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`. ## Produção ```bash pnpm build # server: tsc | web: tsc -b && vite build PORT=3000 pnpm start # node server/dist/index.js: API + build do front na mesma porta ``` 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). ## 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 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) nixpacks.toml comandos de build e start do deploy pnpm-workspace.yaml workspaces, allowBuilds e overrides ``` ## Verificação Não há testes automatizados neste repositório. O que existe de fato: - `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. ## 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. - 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. - 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.