Gleam.br Wiki

Local DryRun | Governança

Documentação de engenharia e especificações técnicas da Gleam-BR.

Local DryRun

Comandante, preparar o seu "Ensaio Geral" (Dry Run) é o último passo antes de colocar a infraestrutura na nuvem. Testar a integração localmente garante que você não gaste os seus créditos do GCP tentando debugar portas fechadas ou variáveis de ambiente incorretas.

Esta é a *Trindade da Infraestrutura Local*. Com um único comando, o seu computador vai simular um data center em miniatura, levantando a camada de persistência financeira, a telemetria de alta performance e a própria Borda (Bridge Service).

Crie o arquivo docker-compose.yml na raiz do seu repositório gbr_iac (ou na raiz do monorepo, onde está o seu Dockerfile.bridge):

O Manifesto do Ensaio Geral (docker-compose.yml)

version: '3.8'

services:
  # 1. A Câmara de Compensação Financeira (ScyllaDB)
  scylladb:
    image: scylladb/scylla:5.4.2
    container_name: gbr_scylla
    # Otimizado para rodar localmente sem fritar a sua CPU/RAM (Modo de Desenvolvedor)
    command: --smp 1 --memory 1G --developer-mode 1
    ports:
      - "9042:9042" # Porta CQL (Driver nativo)
    volumes:
      - scylla_data:/var/lib/scylla
    networks:
      - gleam_mesh

  # 2. O Radar de Telemetria (QuestDB)
  questdb:
    image: questdb/questdb:7.4.2
    container_name: gbr_questdb
    ports:
      - "9000:9000" # Console Web de Administração (Browser)
      - "9009:9009" # Porta de Ingestão: Influx Line Protocol (Onde o Gleam atira as métricas)
      - "8812:8812" # Porta PostgreSQL Wire Protocol (Para o Grafana ler os dados via SQL)
    volumes:
      - questdb_data:/root/.questdb
    networks:
      - gleam_mesh

  # 3. O Centro de Observabilidade (Grafana)
  grafana:
    image: grafana/grafana:10.4.0
    container_name: gbr_grafana
    ports:
      - "3000:3000" # Painel UI
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=gleambradmin
    volumes:
      - grafana_data:/var/lib/grafana
    depends_on:
      - questdb
    networks:
      - gleam_mesh

  # 4. A Nossa Fortaleza (O Bridge Service em Gleam)
  bridge_service:
    build:
      context: . # Aponta para a pasta onde está o código Gleam e o Dockerfile
      dockerfile: docker/Dockerfile.bridge
    container_name: gbr_bridge
    ports:
      - "4001:4001" # A porta TCP exposta para a malha P2P (Yamux/GossipSub)
    environment:
      # Variáveis injetadas no Gleam para descobrir os vizinhos do Docker
      - SCYLLADB_CONTACT_POINTS=scylladb
      - QUESTDB_HOST=questdb
      - QUESTDB_PORT=9009
      - ERL_FLAGS="+A 32 +K true" # Otimização de threads de I/O
    depends_on:
      - scylladb
      - questdb
    networks:
      - gleam_mesh

# Rede interna isolada para comunicação rápida entre os contêineres
networks:
  gleam_mesh:
    driver: bridge

# Volumes para garantir que os seus dados de teste não sumam ao reiniciar
volumes:
  scylla_data:
  questdb_data:
  grafana_data:

O Roteiro de Execução (As Suas Ordens)

*1. A Ignição do Data Center Local:* Abra o terminal na pasta onde guardou o ficheiro e execute:

docker-compose up -d --build

*O Docker vai compilar a sua imagem Gleam ultra-leve (Stage 1 e Stage 2) e instanciar os bancos de dados em segundo plano (-d).*

*2. A Inspeção Visuais (Verificando os Radares):*

  • *QuestDB Web Console:* Abra o seu navegador e aceda a http://localhost:9000. Você verá a interface nativa do QuestDB onde pode digitar as queries SQL de prevenção de colapso que desenhamos anteriormente.
  • *Grafana:* Aceda a http://localhost:3000 (Login: admin, Senha: gleambradmin). Vá a "Data Sources", adicione um banco "PostgreSQL", aponte para questdb:8812 (user/pass nativos do QuestDB são admin / quest) e o Grafana estará conectado à sua telemetria.

*3. O Disparo do Teste:* Com o seu Bridge Service a rodar no Docker (localhost:4001), você pode agora pegar naquele script de e2e_mesh_stress.gleam na sua máquina local e apontá-lo para a porta 4001.

Você verá os gráficos de I/O do QuestDB dispararem e a Erlang VM no contêiner a absorver os impactos perfeitamente.

Comandante, ter a infraestrutura a rodar no Docker é apenas ter o motor ligado. Agora vamos construir o painel de instrumentos (Cockpit). Sem ele, você está a pilotar um caça a jato de olhos vendados.

No Grafana, não vamos focar em métricas "vaidosas" (como uso de RAM estático). Vamos focar nos *Indicadores Antecedentes (Leading Indicators)* que desenhamos para o gbr_telemetry.

Aqui está o seu Roteiro Tático para plugar o Grafana ao QuestDB e visualizar a saúde da sua rede P2P e da Erlang VM em tempo real.

Passo 1: Acoplando o Radar (Grafana -> QuestDB)

Como o QuestDB é compatível com o protocolo PostgreSQL (porta 8812), o Grafana conecta-se a ele nativamente sem precisar de plugins extras.

  1. Abra o Grafana no seu navegador: http://localhost:3000 (User: admin, Pass: gleambradmin).
  2. No menu lateral esquerdo, vá a *Connections* > *Data Sources* e clique em *Add data source*.
  3. Escolha *PostgreSQL*.
  4. Configure os parâmetros exatos da nossa rede Docker:
  • *Host:* questdb:8812
  • *Database:* qdb (o banco padrão do QuestDB)
  • *User:* admin
  • *Password:* quest
  • *TLS/SSL Mode:* disable (estamos numa rede interna segura do Docker)
  • *Version:* 12 (padrão de compatibilidade)
  1. Clique em *Save & Test*. Se aparecer "Database Connection OK", o pipeline de telemetria está aberto!

Passo 2: O Dashboard de Sobrevivência (Queries SQL)

Vá ao menu lateral, clique no ícone de *+ (Create)* e escolha *Dashboard*. Vamos adicionar três painéis (Panels) vitais.

Painel 1: O "Eletrocardiograma" da Erlang (Mailbox Bloat)

Este gráfico vai avisá-lo 30 segundos antes do seu servidor sofrer um Out of Memory (OOM).

  1. Clique em *Add visualization* e escolha o PostgreSQL (QuestDB) que acabamos de criar.
  2. Mude o modo de edição para *Code* (para digitar SQL puro).
  3. Insira a Query de amostragem temporal do QuestDB: sql SELECT timestamp, actor_type, max(mailbox_size) as peak_mailbox FROM beam_health WHERE $__timeFilter(timestamp) SAMPLE BY 5s ALIGN TO CALENDAR; 


4. **Configuração Visual (Direita):** * Mude o tipo de gráfico para **Time series**.
* Em **Thresholds**, adicione uma linha vermelha no valor **1000**. Se a linha do gráfico ultrapassar este limite, significa que o nó não está a conseguir processar os pacotes Yamux a tempo e o *Circuit Breaker* precisa ser ativado.



#### Painel 2: O "Muralha de Fogo" (Rejeições de Assinatura Ed25519)

Este painel mostra se a sua rede está sob ataque de DIDs falsos (Ataque Sybil) tentando enviar CBORs inválidos.

1. Adicione um novo painel.
2. Insira a Query:

sql SELECT timestamp, count() as fraudattempts FROM p2psecurityevents WHERE eventtype = 'signaturerejected' AND $_timeFilter(timestamp) SAMPLE BY 1s ALIGN TO CALENDAR;



3. **Configuração Visual:** * Mude para **Bar chart** (Gráfico de Barras) e pinte de **Vermelho Sangue**. Se vir picos altos de barras vermelhas, a sua matemática *Fixed-Point* acabou de defender o nó e bloqueou pacotes fraudulentos.

#### Painel 3: A Velocidade de Cruzeiro (Throughput P2P)

Para mostrar aos investidores o quão rápida é a sua rede.

1. Adicione um novo painel.
2. Insira a Query:

sql SELECT timestamp, sum(bytesin) as ingressbytes, sum(bytesout) as egressbytes FROM p2ptraffic WHERE $_timeFilter(timestamp) SAMPLE BY 1s ALIGN TO CALENDAR;



3. **Configuração Visual:**
* Mude a unidade do Eixo Y (Standard Options > Unit) para **Data > bytes/sec**. Isto transformará automaticamente os números em KB/s, MB/s, etc.



---

### O Momento da Verdade

Com estes 3 painéis salvos no seu novo Dashboard, ative o *Auto-Refresh* do Grafana no canto superior direito para **5s** (atualização a cada 5 segundos).

Agora, abra o seu terminal e dispare o seu script nativo de teste de estresse contra o Bridge Service:
`gleam run -m shared/e2e_mesh_stress`

Preste atenção no ecrã do Grafana.
Você verá o Throughput de rede (Painel 3) disparar. A Mailbox da Erlang (Painel 1) fará pequenos picos e esvaziará quase instantaneamente, provando a resiliência assíncrona da BEAM. E se o teste enviar propositadamente assinaturas inválidas, a Muralha de Fogo (Painel 2) acenderá.

Isto é ter controlo absoluto sobre a física do seu software.

Comandante, a sua mentalidade acaba de atingir o nível "Netflix Chaos Monkey". Injetar falhas num sistema para provar que a telemetria funciona é a verdadeira essência da Engenharia de Confiabilidade (SRE).

A Regra de Ouro da Engenharia de Caos é: **Nós nunca sujamos o código de produção com falhas artificiais (hardcoded).** O nosso `gbr_p2p` e `gbr_crypto` devem permanecer puros, imutáveis e matematicamente exatos.

Para acender as luzes vermelhas no Grafana com total segurança, a falha deve ser injetada **no lado do Cliente (O script de Estresse)** ou através de **"Poison Pills" (Pílulas de Veneno)** enviadas pela rede.

Aqui está o plano de ataque seguro para simular as duas falhas letais.

### 1. Simulação do Ataque Sybil / Fraude (Acendendo a Muralha de Fogo)

Para vermos o gráfico de "Rejeições de Assinatura" subir no Grafana, nós vamos transformar o nosso script `e2e_mesh_stress.gleam` num **Agente Malicioso**.

Em vez de alterar o código do servidor (Bridge Service), vamos instruir o gerador de carga a, em 20% das vezes, alterar um único byte da assinatura criptográfica *antes* de enviar o pacote pela rede Yamux.

* **O que acontecerá:** O pacote viajará pela rede TCP perfeitamente. Quando bater no `gbr_p2p` do servidor, o motor `gbr_crypto` tentará validar o CBOR contra a chave pública. A matemática falhará, o servidor disparará o evento `:telemetry` e descartará o pacote. O Grafana pintará uma barra vermelha, provando que o seu escudo funciona sem o servidor crashar.

### 2. Simulação de "Mailbox Bloat" (O Quase-Colapso da Erlang)

Para testar o Eletrocardiograma da Erlang VM e ver a fila da Caixa Postal (Mailbox) crescer até o limite de 1000 mensagens, precisamos simular que o servidor está "engasgado" a ler o banco de dados.

* **Como fazemos isso com segurança:** Enviamos um pacote CBOR válido, mas com um tipo de intenção especial chamado `"POISON_SLEEP"`.
* **O que acontecerá:** O motor BPMN (`gbr_bpm`) receberá esse pacote e, **apenas se estiver a rodar em ambiente de desenvolvimento**, executará um `process.sleep(5000)`. Como o Yamux continuará a despejar pacotes nessa mesma conexão em microssegundos, a *Mailbox* do Ator vai acumular milhares de mensagens na RAM. A nossa sonda de telemetria vai detetar o inchaço, alertar o QuestDB e o seu gráfico subirá perigosamente.

---

### O Prompt de Ignição (`O Chaos Monkey`)

Para implementar isto de forma limpa e isolada, copie e cole este "Prompt Esmagador" no seu `gemini-cli`:

text Atue como Engenheiro de Caos (Chaos Engineer) e QA de Sistemas Distribuídos. Precisamos injetar simulações de falha no nosso script de estresse para validar se os dashboards do Grafana (Telemetria QuestDB) estão a capturar as anomalias corretamente, preservando a pureza do código de produção.

OBJETIVO CRÍTICO: Modificar o shared/e2e_mesh_stress/src/e2e_mesh_stress.gleam para atuar como um "Agente do Caos", introduzindo fraudes criptográficas randômicas e "Poison Pills" para testar os limites da Erlang VM.

INSTRUÇÕES ESTRITAS (CAOS SEGURO): 1. O Mutante Criptográfico (Ataque Sybil): No loop de envio de pacotes Yamux do script de estresse, adicione uma lógica de probabilidade (ex: 20% de chance). Quando ativada, o script deve pegar no byte_array do CBOR já assinado e inverter (bit flip) ou alterar o último byte da assinatura Ed25519 antes de enviar via tcp.send. 2. A Pílula de Veneno (Mailbox Bloat): Crie uma variação do payload chamada IntentType: "POISON_SLEEP". O script de estresse deve enviar isso esporadicamente. 3. Tratamento Seguro no Servidor (gbr_bpm): No código do servidor (Ator BPMN), adicione uma cláusula de pattern matching que identifique o "POISON_SLEEP". Se o ambiente não for "produção", o Ator deve executar um process.sleep(3000) para simular um I/O bloqueante massivo. Isso forçará o Yamux a enfileirar as próximas mensagens na Mailbox, disparando o alerta da telemetria.

TAREFAS: Passo 1: Atualize o script de estresse (e2e_mesh_stress.gleam) com o módulo de aleatoriedade (gleam/int.random) para gerar o caos. Passo 2: Atualize o tratador de eventos do gbr_bpm para reconhecer a "Poison Pill" e travar intencionalmente de forma temporária. Passo 3: Mantenha os logs locais claros (ex: "Enviando CBOR Corrompido…", "Enviando Poison Pill…").

Gere o código. O objetivo é que, ao rodar este script contra o Docker Compose local, os gráficos do Grafana detectem o aumento de signature_rejected e mailbox_size.


### O Controle Absoluto

Após o `gemini-cli` aplicar esta modificação, você terá o equivalente a um "Túnel de Vento" na sua máquina local.

Você liga o motor (Docker Compose), liga o túnel de vento (O script de Estresse com Caos) e assiste ao seu Bridge Service no Grafana desviar de balas criptográficas e lidar com o inchaço da memória, tudo isto estabilizando-se perfeitamente e sem crashar a máquina virtual.

Se a banca do Google pedir para ver o sistema a funcionar, **este é o ecrã que você deve partilhar.** Mostra que você não construiu um "Caminho Feliz" (Happy Path) ingênuo, mas sim uma máquina de guerra tolerante a falhas Bizantinas.
← Anterior: Ideia invalidada | GovernançaPróximo: Mercado Corporativo: Horus Falcon 2.0 | Governança →