DEV Community: Marcus Dorbação

SSE (Server-Sent Events): como funciona por baixo dos panos

Marcus Dorbação — Thu, 16 Jul 2026 15:09:26 +0000

Se você já precisou que um servidor "avisasse" o navegador quando algo mudasse — sem ficar dando refresh ou fazendo polling a cada X segundos — provavelmente esbarrou em duas opções: WebSocket ou SSE (Server-Sent Events). Este artigo foca no segundo: o que é, e como ele funciona tecnicamente.

O que é

SSE é um mecanismo de comunicação unidirecional (servidor → cliente), construído sobre HTTP comum. O servidor mantém uma única conexão aberta e vai empurrando eventos de texto para o cliente conforme eles acontecem, sem que o cliente precise ficar perguntando "tem novidade?".

Diferente do WebSocket, não existe handshake especial nem troca de protocolo — é uma requisição HTTP GET normal, que simplesmente nunca termina.

O fluxo, passo a passo

1. O cliente abre a conexão

GET /stream HTTP/1.1
Host: api.exemplo.com
Accept: text/event-stream

Uma requisição GET comum — nada de upgrade de protocolo.

2. O servidor responde e não fecha a conexão

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

O Content-Type: text/event-stream avisa o cliente: "isso é um stream contínuo, não espere o corpo terminar".

3. O servidor envia eventos como texto

Cada evento é um bloco separado por linha em branco:

event: flag-update
data: {"flagKey": "novo-checkout", "value": true}

data: heartbeat

event: flag-update
data: {"flagKey": "cancelar-nota", "value": "variante-b"}

Campos possíveis:

Campo	Para que serve
`data:`	O payload do evento (pode ter várias linhas)
`event:`	Nome do tipo de evento — permite o cliente ter listeners diferentes por tipo
`id:`	Identificador do evento, usado para retomar de onde parou após reconexão
`retry:`	Tempo em ms que o cliente deve esperar antes de tentar reconectar

4. O cliente processa cada evento

No navegador, isso é nativo via EventSource:

const source = new EventSource('/stream');

source.addEventListener('flag-update', (e) => {
  const data = JSON.parse(e.data);
  console.log('Atualização recebida:', data);
});

5. Se a conexão cair, reconecta sozinho

Esse é um dos pontos mais úteis do SSE: o EventSource reconecta automaticamente, sem precisar de código extra — e reenvia o header Last-Event-ID com o último id: recebido, permitindo o servidor retomar exatamente de onde parou, em vez de reenviar tudo desde o início.

Características técnicas que valem lembrar

Só texto: o payload é sempre string, geralmente JSON serializado — não dá para mandar binário direto
Unidirecional: o cliente não consegue mandar dados de volta pela mesma conexão. Se precisar de um "ack" ou enviar algo, é uma requisição HTTP separada
Roda sobre infraestrutura HTTP comum: proxies, load balancers e CDNs já sabem lidar com isso, diferente do WebSocket, que às vezes exige suporte especial nesses componentes
Limite de conexões no HTTP/1.1: navegadores limitam a ~6 conexões simultâneas por domínio; isso deixa de ser um problema no HTTP/2, que multiplexa várias streams numa única conexão TCP

Quando faz sentido usar

SSE é a escolha certa quando o fluxo de dados é só do servidor para o cliente — notificações, atualizações de status, feeds em tempo real, mudanças de configuração. Se o cliente também precisa mandar dados pela mesma conexão em tempo real (ex: um chat, um jogo multiplayer), WebSocket é o caminho, porque ali a comunicação é bidirecional.

Feature Flags - Thinking

Marcus Dorbação — Thu, 16 Jul 2026 14:51:59 +0000

Sistema de Feature Flags — Documentação Técnica

Documentação em construção. Público-alvo: devs do time (uso técnico/API).
Sistema avançado: rollout percentual, segmentação de usuários e A/B test.

Índice

Visão geral
Core de flags
Targeting e segmentação
Rollout progressivo
A/B testing / Experimentação
SDKs e integração técnica
Autenticação (SDK Key)
Sincronização em tempo real
Eventos de conexão
Webhooks (integração externa)

Visão geral

Sistema de feature flags construído do zero, com suporte a:

Flags booleanas e multivariáveis
Segmentação por atributos de usuário
Rollout percentual com bucketing consistente
A/B testing com múltiplas variantes
SDKs client-side e server-side

Core de flags

Tipos de flag: boolean (on/off) e multivariável (string/número/JSON), permitindo retornar variantes diferentes, não só ligar/desligar
Ambientes: dev, staging, produção — cada um com seu próprio estado de flag
Kill switch: desligar uma flag instantaneamente em produção, sem deploy

Targeting e segmentação

Regras de segmentação: por atributo do usuário (país, plano, versão do app, device, etc.)
Targeting individual: ligar a flag para usuários específicos (por ID, email)
Grupos/coortes: listas de usuários (ex: beta testers, funcionários internos)

Rollout progressivo

Rollout percentual: liberar gradualmente para uma fatia da base (5%, 10%, 50%...)
Sticky bucketing: garante que o mesmo usuário sempre caia na mesma variante entre sessões
Hash consistente: normalmente hash do user ID + flag key para decidir o bucket

A/B testing / Experimentação

Múltiplas variantes com pesos configuráveis (ex: A 33%, B 33%, C 34%)
Integração com analytics: disparar eventos de exposição (quem viu qual variante)
Significância estatística geralmente delegada a uma ferramenta de análise externa, mas o sistema de flags precisa expor os dados de exposição

SDKs e integração técnica

SDK client-side vs server-side

A diferença não é só "onde roda o código" — é uma questão de segurança e vazamento de informação.

Server-side SDK

Roda em ambiente confiável (backend)
Pode ter acesso a todas as flags, incluindo as não lançadas, regras de segmentação completas e segredos usados no targeting
Comunica-se direto com a API central ou via um Relay Proxy (serviço intermediário que reduz chamadas repetidas)

Client-side SDK (browser, mobile, apps)

Roda em ambiente não confiável — qualquer um pode inspecionar o payload
Nunca deve receber a lista completa de flags. O backend avalia a flag para aquele usuário específico e envia só o payload já resolvido (ex: flag X = true, flag Y = variante B)
Isso é feito via endpoint do tipo /sdk/eval?context={user}, retornando um payload minimalista
Regra crítica: nunca usar a SDK key server-side (completa) dentro de um app client — isso vazaria todas as flags e regras internas

Avaliação local vs remota

Abordagem	Latência	Frescor dos dados
Remota (thin client)	Alta — chamada de rede a cada checagem	Sempre atualizado
Local (thick client, recomendada)	Baixa — avaliação em memória	Depende da estratégia de sync

Estratégias de atualização do cache local:

Polling: SDK pergunta "tem mudança?" a cada N segundos
Streaming: servidor empurra updates em tempo real assim que uma flag muda

Muitos SDKs combinam os dois: streaming como canal principal + polling como fallback caso a conexão caia.

Fallback / default values

Todo flag check exige um valor default obrigatório na chamada (nunca deixar o SDK "adivinhar")
Hierarquia de fallback:
1. Valor em cache local (último snapshot conhecido)
2. Se nunca conectou → default fornecido no código de chamada
Falha do serviço de flags nunca deve travar a aplicação — deve ser silenciosa e logada
Timeout de inicialização: tempo máximo de espera no boot para o primeiro fetch (ex: 5s); depois disso, segue com defaults e atualiza quando possível
Emitir métrica/log quando o SDK cai em modo fallback, para sinalizar degradação do serviço

Autenticação (SDK Key)

A SDK key funciona como um bearer token:

Authorization: Bearer sdk-a1b2c3d4...

Elemento	Papel
SDK key (bearer token)	Autentica + resolve escopo (projeto/ambiente) — não participa da decisão de segmentação
Context (key, plan, country...)	Fornece os dados para a decisão de segmentação e rollout

Exemplo de request:

POST /evaluate
Headers: { "Authorization": "Bearer sdk-a1b2c3d4..." }

Body: {
  "flagKey": "cancelar-nota-fiscal",
  "context": {
    "key": "user-12345",
    "plan": "enterprise",
    "country": "BR"
  }
}

Por que não expor projectId/environment como parâmetros públicos

Alternativa descartada: passar ?project=app-mobile&env=production abertamente, sem token.

Problemas dessa abordagem:

Enumeração — projectId previsível permite testar/descobrir outros projetos/ambientes
Sem autenticação — impossível distinguir chamada legítima de bisbilhotagem
Vazamento de lógica de negócio — testar contexts publicamente permite reconstruir regras de segmentação por engenharia reversa
Sem revogação/rotação — sem token não há "chave" para cortar acesso; seria preciso mudar a própria estrutura da API
Sem rate limiting/billing por cliente — impossível medir uso ou isolar consumidores
DoS mais fácil — sem identificação, não dá para aplicar throttling seletivo
Mistura acidental de ambientes — sem credencial vinculante, é mais fácil um client de produção acessar staging por engano

Sincronização em tempo real

Por que webhook não serve como mecanismo de sync do SDK

Webhook exige que o servidor inicie uma conexão de saída até o cliente — o que não funciona para a maioria dos consumidores reais de SDK:

Frontend/browser: sem endereço público
App mobile: sem IP público, sem porta aberta
Backend atrás de NAT/firewall corporativo: porta não exposta
Serverless/Lambda: função só existe durante a execução
Múltiplas réplicas atrás de load balancer: ambíguo para qual réplica enviar

Por isso, o padrão adotado (como na maioria dos sistemas de feature flag do mercado) é o inverso: o cliente inicia a conexão de saída (streaming ou polling) e mantém ela aberta.

SSE como alternativa ao WebSocket

WebSocket é bidirecional e mais pesado que o necessário — o caso de uso aqui é apenas server → client.

SSE (Server-Sent Events) cobre esse caso:

Conexão HTTP simples, unidirecional
Reconexão automática nativa
Funciona sobre HTTP/1.1 comum, sem upgrade de protocolo
Mais simples de implementar mantendo tempo real

Eventos de conexão

`SdkConnected`

Dispara quando o SDK abre a conexão de streaming (SSE/WebSocket) e o token é validado com sucesso. Não é só "TCP conectou" — é "conexão autenticada e pronta para receber updates daquele escopo (org/app/ambiente)".

`SdkDisconnected`

Dispara quando a conexão cai, por um de três motivos (importante diferenciar no payload):

Fechamento gracioso — shutdown, deploy, scale-down
Timeout/heartbeat perdido — SDK parou de responder ao keep-alive
Erro de rede — queda abrupta

Diferenciar o motivo importa para observabilidade: uma queda maciça de conexões pode ser "todo mundo fez deploy ao mesmo tempo" (normal) ou "o serviço de streaming caiu" (crítico).

Pontos de atenção:

Reconexões automáticas com backoff podem gerar ruído (SdkDisconnected → SdkConnected repetidos) — considerar debounce/agregação nas métricas
Incluir um connectionId único por sessão de streaming para correlacionar conexão/desconexão e calcular duração

Usos práticos:

Observabilidade — quantos SDKs ativos por ambiente
Detecção de degradação — queda anormal indica problema no Sync service
Billing/capacity planning — se cobrança for por conexões simultâneas

Webhooks (integração externa)

Webhook não é o mecanismo de sincronização do SDK, mas é útil como feature de integração opcional, quando o receptor é um serviço backend do próprio cliente, controlado por eles, com endpoint público de propósito.

Exemplos de uso:

Notificar o sistema de CI/CD do cliente quando uma flag mudar em produção
Sincronizar com um sistema de config interno do cliente

Modelo proposto: URL de webhook registrada no momento da autenticação (junto com organização/aplicação/ambiente), salva em uma tabela de webhooks associada à chave/token.

Em aberto

[ ] Detalhar payload dos eventos SdkConnected/SdkDisconnected
[ ] Fluxo completo de evaluate() (resolução de token → busca da flag → segmentação → rollout → resultado)
[ ] Desenho do schema de dados completo
[ ] Desenho detalhado da tabela de webhooks como feature de integração