Modo desktop no Windows bloqueia ações e modo browser não possui encerramento controlado

[pitangainnovare]

Descrição do problema

No ambiente Windows, o SPS Validator apresenta problemas no gerenciamento do servidor HTTP local nos modos desktop e browser. No modo desktop, iniciado ao clicar no executável, a aplicação escolhe uma porta local livre e abre a interface pelo pywebview. Entretanto, ao clicar nas ações Relatório, HTML ou PDF, o link é aberto no navegador externo, mas a página fica carregando indefinidamente.

A requisição foi testada diretamente com:

curl.exe --noproxy 127.0.0.1 --max-time 5 -v "http://127.0.0.1:PORTA/CAMINHO"

Resultado:

Request completely sent off
Operation timed out after 5002 milliseconds with 0 bytes received
Closing connection

Isso demonstra que:

1. A conexão TCP com o servidor local é estabelecida;
2. A requisição HTTP é enviada completamente;
3. O servidor não retorna sequer os cabeçalhos HTTP.

O modo desktop inicia o servidor com wsgiref.simple_server.make_server(), que processa conexões de forma síncrona. Uma conexão ociosa ou especulativa aberta pelo WebView2, Edge ou outro navegador pode ocupar o único atendimento disponível e impedir que as requisições seguintes sejam processadas. Os links das ações usam target="_blank". O comportamento padrão do pywebview no Windows é abrir esses links no navegador externo, aumentando a possibilidade de múltiplas conexões simultâneas ao servidor local.

No modo browser existe outro problema de usabilidade e ciclo de vida:

• Sem --port, a aplicação tenta usar a porta 5000;

• Neste ambiente, a porta 5000 já estava ocupada por outro serviço gRPC;

• Ao acessar essa porta, o navegador apresentou a mensagem:

  Communication with gRPC endpoints must be made through a gRPC client
  

• Ao executar o SPS Validator em outra porta, o funcionamento foi normal:

  .\spsvalidator.exe --browser --port 50005

Além disso, como o executável Windows é gerado com --windowed, não existe um console visível para usar Ctrl+C. Fechar a aba do navegador não deixa claro se o processo foi encerrado e pode manter o servidor executando em segundo plano.

Passos para reproduzir o problema

Modo desktop

1. Execute o SPS Validator no Windows clicando no arquivo .exe;
2. Valide um pacote SPS que gere relatório e prévias;
3. Na coluna Ações, clique em Relatório, HTML ou PDF;
4. Observe que o navegador externo é aberto;
5. Observe que a página permanece carregando sem apresentar resposta;
6. Execute curl.exe para a mesma URL;
7. Observe que a conexão é estabelecida, mas nenhum byte é recebido antes do timeout.

Modo browser com a porta padrão ocupada

1. Certifique-se de que outro serviço esteja usando a porta 5000;

2. Execute:

   .\spsvalidator.exe --browser

3. Acesse http://127.0.0.1:5000;

4. Observe que a resposta pertence ao outro serviço ou que o SPS Validator não inicia corretamente;

5. Execute novamente usando uma porta livre:

   .\spsvalidator.exe --browser --port 50005

6. Acesse http://127.0.0.1:50005;

7. Observe que o SPS Validator funciona normalmente.

Comportamento esperado

Modo desktop

• O servidor HTTP local deve processar múltiplas conexões simultaneamente;
• Relatórios e prévias não devem ficar bloqueados por uma conexão ociosa;
• As ações Relatório, HTML e PDF devem abrir na própria janela do aplicativo;
• Deve existir uma ação clara para voltar ao histórico;
• A porta pode continuar sendo selecionada automaticamente, pois é um detalhe interno;
• Ao fechar a janela nativa, o servidor HTTP e o processo devem ser encerrados;
• O encerramento deve chamar explicitamente server.shutdown() e aguardar o término do servidor.

Modo browser

• O servidor também deve aceitar múltiplas conexões;
• Quando --port não for informado, a aplicação deve selecionar uma porta livre e abrir automaticamente a URL correta no navegador;
• Quando uma porta for informada explicitamente e estiver ocupada, a aplicação deve apresentar uma mensagem clara, sem direcionar o usuário para outro serviço;
• A interface deve mostrar a URL/porta utilizada;
• Deve existir uma ação clara, como Encerrar SPS Validator, para finalizar o servidor;
• Fechar somente a aba do navegador não deve ser usado como mecanismo de encerramento, pois esse evento não é confiável;
• O servidor deve continuar restrito a 127.0.0.1.

Sugestão técnica

Utilizar um servidor WSGI com suporte a threads nos dois modos, mantendo uma referência ao objeto do servidor para permitir encerramento explícito.

Uma possibilidade é usar werkzeug.serving.make_server() com threaded=True.

Fluxo sugerido:

Servidor Werkzeug threaded
        |
        +-- modo desktop
        |     porta livre automática
        |     janela pywebview
        |     ações abertas na própria janela
        |     fechamento da janela → server.shutdown()
        |
        +-- modo browser
              porta livre ou --port
              abertura automática do navegador
              ação Encerrar → server.shutdown()

A ação de encerramento pelo navegador deve usar um POST protegido por um token local ou outro mecanismo que impeça uma página externa de finalizar o aplicativo indevidamente.

Critérios de aceitação

• O servidor usado no modo desktop processa requisições simultâneas;
• Relatório, HTML e PDF não ficam carregando indefinidamente no Windows;
• No modo desktop, as ações são abertas na própria janela do pywebview;
• Relatórios e prévias possuem navegação de retorno ao histórico;
• Fechar a janela desktop encerra o servidor e o processo;
• O modo browser seleciona uma porta livre quando --port não é informado;
• O navegador é aberto automaticamente na URL correta;
• Uma porta explicitamente solicitada e já ocupada produz erro claro;
• O modo browser oferece uma ação explícita para encerrar o SPS Validator;
• O servidor permanece vinculado somente a 127.0.0.1;
• Existem testes para concorrência, porta ocupada e encerramento do servidor;
• O comportamento é validado em Windows com WebView2 e navegador externo.

Screenshots ou vídeos

N/A

Anexos

N/A

Ambiente utilizado

• Sistema operacional: Windows 11;

• Aplicação: SPS Validator executável;

• Interface desktop: pywebview com WebView2;

• Navegador externo: Edge e Chrome;

• Modo desktop: porta local automática;

• Modo browser funcional:

  .\spsvalidator.exe --browser --port 50005

Arquivos relacionados

• spsvalidator/src/spsvalidator/main.py
• spsvalidator/src/spsvalidator/web/templates/_history_list.html
• spsvalidator/src/spsvalidator/web/templates/report.html
• spsvalidator/src/spsvalidator/web/routes.py
• spsvalidator/packaging/build_windows.ps1

Referências

• wsgiref.simple_server.WSGIServer é baseado no servidor HTTP síncrono do Python:
  https://docs.python.org/3/library/wsgiref.html
• Servidores síncronos processam uma requisição por vez; ThreadingMixIn permite atendimento concorrente:
  https://docs.python.org/3/library/socketserver.html
• O pywebview abre links com target="_blank" no navegador externo por padrão:
  https://pywebview.flowrl.com/api/