@dutodev/cli 0.4.1 → 0.4.3

package/README.md

@@ -51,25 +51,47 @@ Todos os túneis sobem juntos, numa única tela. A CLI procura o arquivo na past
 
 ### Host e cabeçalhos
 
-Por padrão, o serviço local recebe o Host público (`web-<usuário>.duto.dev`). Se ele escolhe o que responder pelo Host, como um proxy reverso local ou um app com vários domínios, troque o Host com `host:` e ajuste cabeçalhos com `headers:`:
+Por padrão, o serviço local recebe a requisição como ela chegou da internet: `Host: web-<usuário>.duto.dev`, `X-Forwarded-Proto: https` e os cabeçalhos da Cloudflare (`CF-Connecting-IP` e outros). Na maioria dos apps isso basta. Quando o app decide algo pelo domínio, há duas ferramentas por túnel:
 
 ```yaml
 tunnels:
   loja:
     port: 8080
-    host: loja.meuapp.test      # o serviço recebe este Host
-  painel:
-    port: 8080                  # mesma porta: vale quando cada túnel tem um host
-    host: painel.meuapp.test
-    headers:
-      X-Ambiente: tunel         # acrescenta ou sobrescreve
+    headers:                    # acrescenta ou sobrescreve cabeçalhos
+      X-Forwarded-Host: loja.meuapp.test
       X-Debug: ""               # valor vazio remove o cabeçalho
+  painel:
+    port: 8081
+    host: painel.meuapp.test    # troca o Host que o serviço recebe
 ```
 
-- Com `host:`, o `X-Forwarded-Host` não é enviado, para o app não ver o domínio público. Se quiser enviá-lo, coloque-o em `headers:`.
-- Redirecionamentos voltam com o endereço público: um `Location: http://loja.meuapp.test:8080/login` chega ao navegador como `https://loja-<usuário>.duto.dev/login`. Isso vale também dentro de parâmetros codificados, como o `redirect_uri` de um login OAuth. Para desligar, use `rewrite_redirects: false` no túnel.
-- Na linha de comando: `duto 8080 --host loja.meuapp.test` (e `--no-rewrite-redirects` para desligar a troca).
-- Links dentro das páginas (HTML, JSON) não são reescritos: se o app montar URLs a partir do Host, elas só abrem na sua máquina.
+**Qual usar:**
+
+| Situação | Use | Por quê |
+|---|---|---|
+| Um proxy reverso local (Traefik, Nginx, Caddy) escolhe o serviço pelo Host | `host:` | O proxy só conhece os domínios locais |
+| Vários túneis na mesma porta, um por domínio | `host:` ou `headers:` diferentes em cada um | A porta pode se repetir; cada túnel tem o próprio endereço |
+| O app identifica o domínio ou o cliente pelo `X-Forwarded-Host`, mas monta URLs a partir do `Host` | `headers:` com `X-Forwarded-Host` | O app vê o domínio local e continua gerando links públicos |
+| Login OAuth em que o app calcula o `redirect_uri` sozinho | evite `host:`; tente `headers:` | Veja abaixo |
+
+**O que o `host:` faz:**
+
+- O serviço recebe o Host informado, e o `X-Forwarded-Host` não é enviado. Para enviá-lo assim mesmo, coloque-o em `headers:`.
+- Os redirecionamentos voltam com o endereço público. Um `Location: http://painel.meuapp.test:8081/login` chega ao navegador como `https://painel-<usuário>.duto.dev/login`. Isso vale também dentro de parâmetros codificados no `Location`. Para desligar, use `rewrite_redirects: false` no túnel.
+- Links no corpo das respostas (HTML, JSON) não são reescritos. URLs que o app montar a partir do Host só abrem na sua máquina.
+- Na linha de comando: `duto 8081 --host painel.meuapp.test`, e `--no-rewrite-redirects` para desligar a troca.
+
+**OAuth e `host:`.** No fluxo de autorização por código, o app manda um `redirect_uri` duas vezes: na ida do navegador ao provedor de login e depois, servidor a servidor, ao trocar o código por token. O provedor exige que as duas sejam idênticas. Com `host:`, o app gera as duas com o domínio local. O Duto corrige a primeira, que passa pelo navegador, mas não alcança a segunda, que não passa pelo túnel. O provedor recusa a troca, em geral com `invalid_request` ou `invalid_grant`, e o app costuma voltar ao login em loop (`ERR_TOO_MANY_REDIRECTS`).
+
+Saídas, da mais simples para a mais trabalhosa:
+
+1. Não troque o Host. O app gera o `redirect_uri` com o endereço público nas duas vezes.
+2. Se o app precisa ver o domínio local para outras decisões e lê o `X-Forwarded-Host`, passe o domínio por `headers:` e mantenha o Host público.
+3. Configure no app a URL pública de retorno, se ele permitir.
+
+Em todos os casos, cadastre `https://<nome>-<usuário>.duto.dev/<caminho de retorno>` como URL de retorno no provedor. A comparação costuma ser exata, sem curingas: cada pessoa do time tem o próprio endereço.
+
+**Sobre o `X-Forwarded-*`.** `X-Forwarded-Host`, `X-Forwarded-Proto` e `X-Forwarded-For` são uma convenção antiga entre proxies reversos para contar ao app o que o cliente pediu de verdade. A versão padronizada é o cabeçalho `Forwarded` (RFC 7239), menos usado na prática. Frameworks costumam ler esses cabeçalhos só quando o proxy é marcado como confiável (`trusted proxies`, `trust proxy`, `USE_X_FORWARDED_HOST`), então o efeito de `headers:` depende de como o app está configurado. Por outro lado, se um app lê o `X-Forwarded-Host` sem essa checagem, qualquer cliente pode forjá-lo em produção. Vale garantir que o proxy da frente sobrescreva ou remova esse cabeçalho.
 
 ## A tela
 
@@ -84,6 +106,8 @@ Com os túneis no ar, o terminal mostra cada túnel (URL, destino local, requisi
 | `tab`, `↑↓` | Alterna entre túneis e requisições e move a seleção |
 | `q` ou Ctrl+C | Fecha os túneis e sai |
 
+Se o túnel está no ar mas nada responde na porta local, quem abrir o endereço no navegador vê uma página do Duto que tenta de novo a cada 3 segundos e volta sozinha quando o serviço sobe. Clientes que não são navegador (`curl`, APIs) recebem um 502 com uma mensagem em texto.
+
 Fora de um terminal interativo (pipe, CI) ou com `--no-ui`, a CLI imprime um log simples. No Windows a tela cheia vem desligada; use `--ui` para tentar.
 
 ## Comandos

package/dist/index.js

@@ -263,7 +263,6 @@ function parseConfig(text, file = CONFIG_FILES[0]) {
     throw fail3('declare os t\xFAneis em "tunnels:", um por linha (ex.: web: 3000).');
   }
   const specs = [];
-  const seen = /* @__PURE__ */ new Map();
   for (const pair of tunnels.items) {
     const raw = isScalar(pair.key) ? String(pair.key.value) : "";
     const line = lineAt(pair.key?.range?.[0]);
@@ -317,16 +316,7 @@ function parseConfig(text, file = CONFIG_FILES[0]) {
         if (value === false) spec.rewriteRedirects = false;
       }
     }
-    const users = seen.get(port) ?? [];
-    const clash = users.find((u) => !u.host || !spec.host || u.host === spec.host);
-    if (clash) {
-      throw fail3(
-        clash.host && clash.host === spec.host ? `a porta ${port} com host ${spec.host} aparece em "${clash.raw}" e em "${raw}"` : `a porta ${port} aparece em "${clash.raw}" e em "${raw}". Para usar a mesma porta, d\xEA um host a cada um.`,
-        line
-      );
-    }
     if (specs.some((s) => s.name === name)) throw fail3(`o nome "${raw}" aparece duas vezes`, line);
-    seen.set(port, [...users, { raw, host: spec.host }]);
     specs.push(spec);
   }
   return specs;
@@ -372,6 +362,52 @@ async function isPortListening(port, timeoutMs = 500) {
 // src/session/proxy.ts
 import { Agent, createServer, request } from "http";
 import { connect as connect2 } from "net";
+
+// src/session/errorPage.ts
+var esc = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+function wantsHtml(accept) {
+  return /\btext\/html\b/i.test(accept ?? "");
+}
+function unavailablePage(o) {
+  const tunnel2 = esc(o.tunnel);
+  const local = `localhost:${o.port}`;
+  return `<!doctype html>
+<html lang="pt-BR">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+${o.retry ? '<meta http-equiv="refresh" content="3">\n' : ""}<meta name="robots" content="noindex">
+<title>Nada respondendo em ${local} \xB7 duto</title>
+<style>
+:root{--bg:#f6f6f3;--fg:#0f1110;--muted:#5f6360;--line:#dcddd8;--card:#fff;--signal:#2dd4bf;--signal-text:#0f766e}
+@media (prefers-color-scheme:dark){:root{--bg:#0b0d0c;--fg:#e9ebe7;--muted:#8a8f8b;--line:#222624;--card:#111413;--signal-text:#2dd4bf}}
+*{box-sizing:border-box}
+body{margin:0;min-height:100vh;display:grid;place-items:center;padding:24px 16px;background:var(--bg);color:var(--fg);font:15px/1.55 system-ui,-apple-system,"Segoe UI",sans-serif}
+main{width:100%;max-width:520px;border:1px solid var(--line);border-radius:.3rem;background:var(--card);padding:28px}
+.mark{display:flex;align-items:center;gap:8px;font:600 13px/1 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.02em;color:var(--muted);margin-bottom:22px}
+.dot{width:8px;height:8px;border-radius:50%;border:1.5px solid var(--signal)}
+h1{font-size:21px;line-height:1.3;margin:0 0 10px;font-weight:650;letter-spacing:-.01em}
+p{margin:0 0 12px;color:var(--muted)}
+code{font:13px ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--fg)}
+h1 code{font-size:.86em;font-weight:600}
+.retry{margin-top:20px;padding-top:14px;border-top:1px solid var(--line);font-size:13px;color:var(--muted)}
+.retry b{color:var(--signal-text);font-weight:600}
+</style>
+</head>
+<body>
+<main>
+<div class="mark"><span class="dot"></span>duto \xB7 ${tunnel2}</div>
+<h1>Nada respondendo em <code>${local}</code></h1>
+<p>O t\xFAnel <code>${tunnel2}</code> est\xE1 no ar, mas o servi\xE7o local n\xE3o respondeu. Suba o servidor na m\xE1quina que abriu o t\xFAnel.</p>
+<p>Se voc\xEA s\xF3 recebeu este link, avise quem o enviou.</p>
+<div class="retry">${o.retry ? "<b>Tentando de novo a cada 3 s.</b> A p\xE1gina volta sozinha quando o servi\xE7o responder." : "Recarregue a p\xE1gina quando o servi\xE7o estiver no ar."}</div>
+</main>
+</body>
+</html>
+`;
+}
+
+// src/session/proxy.ts
 var TEXT = /^(text\/|application\/(json|xml|javascript|x-www-form-urlencoded|graphql)|[^;]*\+(json|xml))/i;
 var MAX_BODY = 64 * 1024;
 var LOCAL_AGENT = new Agent({ keepAlive: false });
@@ -514,10 +550,11 @@ async function startProxy(o) {
     });
     upstream.on("error", (err) => {
       if (res.destroyed && res.writableFinished === false && !res.headersSent) return;
-      const msg = `Nada escutando em localhost:${route.port}. Suba o servidor e tente de novo.`;
+      const html = wantsHtml(req.headers.accept);
+      const msg = html ? unavailablePage({ tunnel: route.tunnel, port: route.port, retry: req.method === "GET" }) : `Nada escutando em localhost:${route.port}. Suba o servidor e tente de novo.`;
       if (!res.headersSent) {
-        res.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
-        res.end(msg);
+        res.writeHead(502, { "content-type": html ? "text/html; charset=utf-8" : "text/plain; charset=utf-8", "cache-control": "no-store" });
+        res.end(req.method === "HEAD" ? void 0 : msg);
       } else res.destroy();
       o.store.update(id, { status: 502, durationMs: Date.now() - started, bytes: res.headersSent ? 0 : Buffer.byteLength(msg), error: err.message || err.code || err.name, reqBody: reqCap.text() });
     });
@@ -920,9 +957,9 @@ async function runSession(specs, source, flags) {
   const session = new Session({ api, deviceId: config.deviceId, deviceName: hostname(), cloudflaredPath, source });
   if (wantsUi(flags)) {
     const { runFullscreen } = await import("./fullscreen-5437X7MP.js");
-    process.exit(await runFullscreen(session, specs, "0.4.1"));
+    process.exit(await runFullscreen(session, specs, "0.4.3"));
   }
-  console.log(`${mark()} ${paint("muted", `${"0.4.1"} \xB7 ${source} \xB7 Ctrl+C para encerrar`)}`);
+  console.log(`${mark()} ${paint("muted", `${"0.4.3"} \xB7 ${source} \xB7 Ctrl+C para encerrar`)}`);
   const stopLog = runPlain(session, (l) => console.log(l));
   const stopped = new Promise((resolve) => {
     const onSignal = () => {
@@ -1009,7 +1046,7 @@ cli.help(
     body: s.body.replace(/^\s*For more info, run any command with the `--help` flag:/m, "  Mais detalhes de um comando: duto <comando> --help").replace("Display this message", "Mostra esta ajuda").replace("Display version number", "Mostra a vers\xE3o")
   }))
 );
-cli.version("0.4.1");
+cli.version("0.4.3");
 try {
   cli.parse(process.argv, { run: false });
   await cli.runMatchedCommand();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dutodev/cli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Exponha uma porta local em https://<nome>-<usuário>.duto.dev com um comando.",
   "license": "MIT",
   "type": "module",