# Manual do Desenvolvedor WX para CurlWx

## Introdução

O `CurlWx` é um pacote abrangente projetado para integrar as poderosas capacidades da biblioteca `libcurl` em suas aplicações WINDEV (WX), WEBDEV e WINDEV Mobile. Ele oferece uma interface WLanguage orientada a objetos para realizar requisições HTTP de forma eficiente e segura, com suporte a funcionalidades avançadas como progresso de download/upload, cancelamento, autenticação baseada em token, mTLS, proxies e muito mais.

Este manual detalha a estrutura do projeto, o processo de instalação, o uso da classe `CurlWx`, funcionalidades avançadas, tratamento de erros e considerações de segurança, visando capacitar desenvolvedores WX a tirar o máximo proveito desta integração.

## 1. Estrutura do Projeto

O projeto `CurlWx` é organizado em módulos lógicos para facilitar a compreensão e a manutenção:

- **`Class/`**
- `CurlWx.wl`: A classe principal em WLanguage que serve como a interface de alto nível para todas as operações HTTP. Ela abstrai a complexidade da `libcurl` e da ponte nativa, oferecendo métodos fluentes para construir requisições. Inclui lógica para fallback para o modo CLI se a ponte nativa não estiver disponível.
- `CurlWx_v2_Entry.wl`: Um arquivo stub que define a função `CurlWx_v2(cmd)`. Esta função é o ponto de entrada para o fallback CLI, onde você pode implementar a chamada ao executável `curl.exe`.

- **`WX/`**
- `LibCurl_Bridge_Bindings_v2_Token.wl`: Contém as declarações `EXTERN` em WLanguage que mapeiam as funções exportadas da DLL nativa `wx_curl_bridge`. Estes bindings são essenciais para que o código WLanguage possa invocar as funções C da ponte.
- `CurlWx_Do_Native.wl`: O wrapper em WLanguage que orquestra a comunicação entre a classe `CurlWx` e a DLL nativa. Ele gerencia a inicialização e limpeza do contexto cURL, a configuração dos parâmetros da requisição, o tratamento de arquivos temporários para dados de resposta e métricas, e a execução da requisição nativa. Este módulo também incorpora tratamento de erros robusto para operações de arquivo e parsing JSON.

- **`Bridge_Helper/`**
- `wx_curl_bridge.c`: O código-fonte em C da ponte nativa. Este arquivo implementa a lógica de interação direta com a `libcurl`, incluindo a validação do token de segurança, configuração de requisições, callbacks de progresso/cancelamento e coleta de métricas. É o coração da integração nativa.
- `CMakeLists.txt`: O script de configuração para o CMake, utilizado para gerar os arquivos de build para a ponte C.
- `build_bridge_msvc.bat`: Um script de batch para compilar a ponte C usando o compilador MSVC (Visual Studio).
- `build.ps1`: Um script PowerShell para compilar a ponte C, oferecendo opções adicionais como empacotamento em ZIP.
- `README_BUILD.md`: Documentação específica sobre como compilar a ponte nativa.

- **`Demo/`**
- `WIN_CurlWx_Progress_Demo.wl`: Uma janela de demonstração em WLanguage que exemplifica o uso da classe `CurlWx` para downloads com barra de progresso e funcionalidade de cancelamento.
- `WIN_CurlWx_Progress_Demo — Layout sugerido.txt`: Um arquivo de texto que descreve o layout sugerido para a janela de demonstração.
- `README.md`: Instruções sobre como integrar a janela de demonstração ao seu projeto.

## 2. Instalação e Configuração

Para utilizar o `CurlWx`, você precisará compilar a ponte nativa e configurar os arquivos corretamente em seu projeto WX.

### 2.1. Pré-requisitos para Compilação da Ponte Nativa

- **CMake**: Versão 3.20 ou superior. Pode ser baixado de [cmake.org](https://cmake.org/).
- **Compilador C/C++**: Visual Studio (MSVC) no Windows ou GCC/Clang em sistemas tipo Unix (Linux, macOS).
- **Libcurl Development Libraries**: As bibliotecas de desenvolvimento da `libcurl`, incluindo os arquivos de cabeçalho (`include/`), bibliotecas (`lib/`) e binários (`bin/`). No Windows, você pode baixar pacotes pré-compilados da `libcurl` ou compilá-la a partir do código-fonte. Em Linux, geralmente são instaladas via gerenciador de pacotes (ex: `sudo apt-get install libcurl4-openssl-dev`).

### 2.2. Compilando a DLL da Ponte Nativa (`wx_curl_bridge.c`)

Navegue até o diretório `Bridge_Helper` no terminal ou prompt de comando.

#### Via MSVC (Windows)

Utilize o `build_bridge_msvc.bat`:

```bat
cd Bridge_Helper
build_bridge_msvc.bat x64 C:\caminho\para\sua\libcurl
```

Substitua `C:\caminho\para\sua\libcurl` pelo diretório raiz da sua instalação da `libcurl`.

#### Via PowerShell (Windows)

Utilize o `build.ps1`:

```powershell
cd Bridge_Helper
.\build.ps1 -Arch x64 -CurlRoot C:\caminho\para\sua\libcurl -Zip
```

O parâmetro `-Zip` é opcional e empacotará os binários resultantes em um arquivo ZIP.

#### Via CMake (Linux/macOS ou alternativo no Windows)

1. Crie um diretório de build:
```bash
cd Bridge_Helper
mkdir build
cd build
```
2. Configure o projeto com CMake (certifique-se de que a `libcurl` esteja instalada no sistema ou especifique seu caminho):
```bash
cmake ..
```
3. Compile a ponte:
```bash
cmake --build .
```

**Saída Esperada**: Após a compilação bem-sucedida, você encontrará a DLL (ou SO em Linux) `wx_curl_bridge.dll` (ou `libwx_curl_bridge.so`) e a `libcurl.dll` (ou `libcurl.so`) no diretório de saída (ex: `Bridge_Helper\distd\` ou `Bridge_Helper\build\`).

### 2.3. Configuração do Token de Segurança

O arquivo `wx_curl_bridge.c` contém um token de segurança hardcoded:

```c
#define SECRET_TOKEN "Umbrela@2025"
```

**É CRÍTICO alterar este token para um valor único e complexo antes de compilar para produção.** Se você alterar o token na ponte C, **deve** usar o mesmo token ao chamar o método `.BridgeToken(...)` da classe `CurlWx` em WLanguage. Isso garante que apenas sua aplicação autorizada possa usar a ponte nativa.

### 2.4. Deploy dos Arquivos

Para que o `CurlWx` funcione em sua aplicação WX, os seguintes arquivos devem ser colocados **no mesmo diretório** do seu executável WINDEV (`.EXE`):

- `SeuApp.exe`
- `wx_curl_bridge.dll` (ou `libwx_curl_bridge.so`)
- `libcurl.dll` (ou `libcurl.so`)

## 3. Uso da Classe `CurlWx` (WLanguage)

A classe `CurlWx` foi projetada para ser intuitiva e flexível, permitindo a construção de requisições HTTP complexas com uma sintaxe fluente.

### 3.1. Inicialização e Métodos Básicos

```wlanguage
// Cria uma nova instância da classe CurlWx
req is CurlWx()

// Define o método HTTP e a URL
req.GET("https://api.example.com/data")
// ou
req.POST("https://api.example.com/submit")
// ou PUT, PATCH, DELETE

// Adiciona um cabeçalho HTTP
req.Header("Accept", "application/json")
req.Header("X-Custom-Header", "MyValue")

// Adiciona parâmetros de query string
req.Query("param1", "value1")
req.Query("param2", "value2")

// Define o corpo da requisição como JSON
LOCAL sJsonData is string = "{\"name\":\"John Doe\", \"age\":30}"
req.JSON(sJsonData)

// Define o corpo da requisição como dados de formulário (application/x-www-form-urlencoded)
// Nota: Para multipart/form-data, veja a seção de funcionalidades avançadas.
req.Form("field1", "value1")
req.Form("field2", "value2")

// Configura autenticação Bearer Token
req.AuthBearer("seu_token_jwt_aqui")

// Configura autenticação Basic
req.AuthBasic("usuario", "senha")

// Define o token de segurança para a ponte nativa (OBRIGATÓRIO para uso nativo)
req.BridgeToken("Umbrela@2025") // Use o token configurado em wx_curl_bridge.c

// Executa a requisição e obtém a resposta
resp is WxResponse = req.Do()

// Verifica o resultado
IF resp.Ok THEN
Info("Requisição bem-sucedida! Status: " + resp.Status)
Trace("Corpo da resposta: " + resp.BodyText)
Trace("Content-Type: " + resp.Metrics.contentType)
FOR EACH hKey OF resp.Headers
Trace("Header: " + hKey + " = " + resp.Headers[hKey])
END
ELSE
Error("Erro na requisição: " + resp.ErrorText)
Trace("Status HTTP: " + resp.Status)
END
```

### 3.2. Download e Upload de Arquivos

#### Download para Arquivo

```wlanguage
LOCAL sDownloadPath is string = fCurrentDir() + "\meu_arquivo.zip"

req is CurlWx()
.GET("https://example.com/large_file.zip")
.DownloadTo(sDownloadPath) // O corpo da resposta será salvo neste arquivo
.BridgeToken("Umbrela@2025")

resp is WxResponse = req.Do()

IF resp.Ok THEN
Info("Download concluído para: " + sDownloadPath)
ELSE
Error("Falha no download: " + resp.ErrorText)
END
```

#### Upload de Arquivo

```wlanguage
LOCAL sUploadPath is string = fCurrentDir() + "\arquivo_para_upload.txt"

req is CurlWx()
.POST("https://api.example.com/upload")
.UploadFile(sUploadPath) // O conteúdo deste arquivo será enviado como corpo da requisição
.Header("Content-Type", "text/plain") // Defina o Content-Type apropriado
.BridgeToken("Umbrela@2025")

resp is WxResponse = req.Do()

IF resp.Ok THEN
Info("Upload concluído com sucesso!")
ELSE
Error("Falha no upload: " + resp.ErrorText)
END
```

### 3.3. Monitoramento de Progresso e Cancelamento

O `CurlWx` suporta monitoramento de progresso e cancelamento de requisições de longa duração, como downloads e uploads grandes. Isso é feito através de arquivos de flag e progresso.

```wlanguage
LOCAL sProgressFile is string = fTempFile("cwx_progress_", ".ndjson")
LOCAL sCancelFile is string = fTempFile("cwx_cancel_", ".flag")

// Limpa o arquivo de cancelamento se ele existir de uma execução anterior
IF fFileExist(sCancelFile) THEN fDelete(sCancelFile)

req is CurlWx()
.GET("https://example.com/very_large_file.bin")
.DownloadTo(fCurrentDir() + "\large_file.bin")
.EnableProgress(sProgressFile, sCancelFile) // Habilita o monitoramento
.BridgeToken("Umbrela@2025")

// Em uma thread separada ou timer, você pode ler o arquivo sProgressFile
// para atualizar uma barra de progresso na UI.
// Para cancelar, basta criar o arquivo sCancelFile:
// fCreate(sCancelFile)

resp is WxResponse = req.Do()

// Após a requisição, desabilite o progresso e limpe os arquivos temporários
req.DisableProgress()
fDelete(sProgressFile)
IF fFileExist(sCancelFile) THEN fDelete(sCancelFile)

IF resp.Ok THEN
Info("Operação concluída. Tamanho baixado: " + resp.Metrics.sizeDownload)
ELSE
Error("Operação falhou ou foi cancelada: " + resp.ErrorText)
END
```

**Como funciona o progresso/cancelamento:**

- **Arquivo de Progresso (`.ndjson`)**: A ponte nativa escreve periodicamente o status do progresso neste arquivo em formato NDJSON (Newline Delimited JSON). Cada linha é um objeto JSON com `dltotal`, `dlnow`, `ultotal`, `ulnow` (bytes totais/atuais de download/upload). Sua aplicação WX deve ler este arquivo (geralmente em um timer) para atualizar a interface do usuário.
- **Arquivo de Cancelamento (`.flag`)**: Se este arquivo for criado (mesmo que vazio) pela sua aplicação WX, a ponte nativa detectará sua presença e abortará a requisição cURL. Após o cancelamento, o arquivo de flag deve ser excluído.

### 3.4. Fallback para CLI

Se a DLL da ponte nativa (`wx_curl_bridge.dll`) não for encontrada ou o token de segurança for rejeitado, a classe `CurlWx` tentará usar o executável `curl.exe` como fallback. Para que isso funcione, você precisa garantir que `curl.exe` esteja acessível (no PATH do sistema ou no diretório da aplicação) e que a função `CurlWx_v2(cmd)` em `CurlWx_v2_Entry.wl` esteja implementada para chamar o `curl.exe`.

Exemplo de implementação `CurlWx_v2(cmd)` (em `CurlWx_v2_Entry.wl`):

```wlanguage
PROCEDURE CurlWx_v2(cmd is string) : string
// Exemplo simples de execução de comando via shell
// Em um ambiente real, considere usar fExecute ou um processo mais robusto
LOCAL sResult is string
LOCAL sCurlExePath is string = "curl.exe" // Ou o caminho completo para curl.exe

// Você pode precisar ajustar o comando para capturar a saída corretamente
// e lidar com erros de forma mais sofisticada.
sResult = fExecute(sCurlExePath + " " + cmd, fWaitFinish + fCaptureOutput)
RESULT sResult
END
```

## 4. Funcionalidades Avançadas

### 4.1. Multipart/Form-Data

Para enviar dados de formulário complexos, incluindo arquivos, use os métodos `Form` e `FormFile`:

```wlanguage
req is CurlWx()
.POST("https://api.example.com/upload_form")
.Form("username", "myuser")
.Form("email", "user@example.com")
.FormFile("profile_picture", fCurrentDir() + "\avatar.jpg", "avatar.jpg", "image/jpeg")
.FormFile("document", fCurrentDir() + "\report.pdf") // filename e contentType são opcionais
.BridgeToken("Umbrela@2025")

resp is WxResponse = req.Do()
// ... tratamento da resposta ...
```

### 4.2. Timeouts e Retries

Configure timeouts para conexão e requisição total, e defina um número de tentativas em caso de falha:

```wlanguage
req is CurlWx()
.GET("https://api.example.com/slow_service")
.Timeouts(5000, 15000) // 5 segundos para conectar, 15 segundos total
.Retry(3, 2) // Tenta 3 vezes com 2 segundos de atraso entre as tentativas
.BridgeToken("Umbrela@2025")

resp is WxResponse = req.Do()
// ... tratamento da resposta ...
```

### 4.3. Configurações TLS/SSL

- **Insecure TLS (Não recomendado para produção)**:
```wlanguage
req.InsecureTLS(True) // Ignora validação de certificado (apenas para desenvolvimento/testes)
```
- **mTLS (Mutual TLS)**:
```wlanguage
req.mTLS(fCurrentDir() + "\client.crt", fCurrentDir() + "\client.key", "senha_da_chave")
```
- **Certificado CA Personalizado**:
```wlanguage
req.CA(fCurrentDir() + "\my_ca.pem", fCurrentDir() + "\ca_certs_dir")
```

### 4.4. Proxies

- **Proxy HTTP**:
```wlanguage
req.ProxyHTTP("http://proxy.example.com:8080")
```
- **Proxy SOCKS5**:
```wlanguage
req.ProxySOCKS5("socks5://socks.example.com:1080")
```

### 4.5. ETag e If-Modified-Since

Para otimização de cache e requisições condicionais:

```wlanguage
LOCAL sETagFile is string = fCurrentDir() + "\last_etag.txt"
LOCAL sLastModified is string = "Mon, 29 Sep 2025 10:00:00 GMT" // Exemplo de data HTTP

req is CurlWx()
.GET("https://api.example.com/resource")
.ETagSave(sETagFile) // Salva o ETag da resposta neste arquivo
.ETagCompare(sETagFile) // Usa o ETag salvo para If-None-Match
.IfModifiedSince(sLastModified) // Usa a data para If-Modified-Since
.BridgeToken("Umbrela@2025")

resp is WxResponse = req.Do()

IF resp.Status = 304 THEN
Info("Recurso não modificado (cache hit).")
ELSE IF resp.Ok THEN
Info("Recurso atualizado. Novo ETag salvo.")
ELSE
Error("Erro: " + resp.ErrorText)
END
```

## 5. Tratamento de Erros

O `CurlWx` fornece informações detalhadas sobre erros através do objeto `WxResponse`.

- `resp.Ok`: Booleano que indica se a requisição foi bem-sucedida (status HTTP 2xx).
- `resp.Status`: O código de status HTTP retornado (ex: 200, 404, 500).
- `resp.ErrorText`: Uma string contendo uma descrição do erro, útil para depuração.
- `resp.Metrics`: A estrutura `WxMetrics` contém informações detalhadas de performance e resultado, mesmo em caso de erro, como `httpCode`, `timeTotalMS`, `urlEffective`, etc.

**Exemplo de Tratamento de Erros:**

```wlanguage
resp is WxResponse = myCurlRequest.Do()

IF NOT resp.Ok THEN
Error("A requisição falhou!")
Info("Código HTTP: " + resp.Status)
Info("Mensagem de Erro: " + resp.ErrorText)
Info("URL Efetiva: " + resp.Metrics.urlEffective)
// Você pode adicionar lógica para retentar, notificar o usuário, etc.
ELSE
Info("Requisição bem-sucedida!")
END
```

O wrapper `CurlWx_Do_Native.wl` foi aprimorado com blocos `TRY...EXCEPT` para operações de arquivo e parsing JSON, tornando-o mais resiliente a problemas inesperados e fornecendo mensagens de erro mais claras.

## 6. Considerações de Segurança

A segurança é uma preocupação primordial ao lidar com requisições de rede e componentes nativos. O `CurlWx` incorpora mecanismos de segurança, mas exige atenção do desenvolvedor.

- **Token Obrigatório**: A ponte nativa exige um `SECRET_TOKEN` para operar. **Nunca use o token padrão (`Umbrela@2025`) em produção.** Altere-o para um valor forte e único no `wx_curl_bridge.c` e use o mesmo valor no método `.BridgeToken()` da classe `CurlWx`. Considere mecanismos mais avançados de gerenciamento de tokens para aplicações críticas.
- **Atualização da Libcurl**: Mantenha a biblioteca `libcurl` sempre atualizada para garantir que você esteja protegido contra vulnerabilidades de segurança conhecidas.
- **Assinatura de Binários**: Assine digitalmente os arquivos `wx_curl_bridge.dll` e `libcurl.dll` para garantir sua integridade e autenticidade. Isso ajuda a prevenir ataques de substituição de DLL.
- **Restrição de ACLs**: Em ambientes Windows, restrinja as Listas de Controle de Acesso (ACLs) nos diretórios da sua aplicação para limitar quem pode modificar ou substituir os arquivos da DLL.
- **InsecureTLS**: Evite usar `InsecureTLS(True)` em ambientes de produção, pois isso desabilita a validação de certificados SSL/TLS, tornando sua aplicação vulnerável a ataques man-in-the-middle.
- **Validação de Entrada**: Sempre valide e sanitize todas as entradas do usuário antes de usá-las em requisições HTTP para prevenir ataques como injeção de cabeçalhos ou URLs maliciosas.
- **Processo Isolado (Avançado)**: Para aplicações de alta segurança, considere executar a ponte nativa em um processo separado e isolado, com privilégios mínimos, para limitar o impacto de possíveis vulnerabilidades.

## 7. Troubleshooting

- **`Native init failed` ou `Bridge token not provided/rejected`**: Verifique se `wx_curl_bridge.dll` e `libcurl.dll` estão no mesmo diretório do seu executável. Confirme se o token passado para `.BridgeToken()` corresponde exatamente ao `SECRET_TOKEN` definido em `wx_curl_bridge.c` e se a DLL foi compilada com o token correto.
- **`libcurl rc=XX http=YY`**: O `rc` é o código de retorno da `libcurl` (0 para sucesso). `http` é o código de status HTTP. Consulte a documentação da `libcurl` para o significado de `rc` e os códigos de status HTTP para `http`.
- **Fallback CLI não funciona**: Verifique se `curl.exe` está no PATH do sistema ou no diretório da aplicação. Certifique-se de que a função `CurlWx_v2(cmd)` em `CurlWx_v2_Entry.wl` está corretamente implementada para chamar `curl.exe` e capturar sua saída.
- **Problemas de compilação da ponte C**: Verifique se o CMake e as bibliotecas de desenvolvimento da `libcurl` estão corretamente instalados e configurados. Consulte `README_BUILD.md` para instruções detalhadas.

---

**Autor:** Manus AI
**Data da Última Atualização:** 29 de Setembro de 2025