Configuração#

O servidor é configurado via variáveis de ambiente. Todas são opcionais — os defaults permitem rodar em modo desenvolvimento sem configurar nada.

Variáveis de ambiente#

Servidor#

Armazenamento#

Autenticação#

Conexões#

Rate Limiting#

Segurança#

Export Policy#

Edit Policy#

Email#

O servidor suporta dois providers de email (para share notifications, OTP de exportação e OTP de edição):

Se nenhum provider for configurado, o servidor usa LogEmailProvider — emails são logados no stdout mas não enviados.

Exemplos de configuração#

Desenvolvimento local#

# Sem auth, sem persistência — tudo em memória
dart run bin/sulfite_server.dart

Produção com SQLite#

export AUTH_SECRET="meu-segredo-longo-e-aleatorio"
export STORAGE_BACKEND=sqlite
export DATABASE_URL=./data/reports.db
export CORS_ORIGINS="https://meuapp.com,https://admin.meuapp.com"
export RATE_LIMIT=true
export TOKEN_STORE_PATH=./data/tokens.json
dart run bin/sulfite_server.dart

Produção com PostgreSQL e criptografia#

export AUTH_SECRET="segredo-de-producao"
export STORAGE_BACKEND=postgres
export DATABASE_URL="postgres://user:pass@host:5432/sulfite"
export ENCRYPTION_KEY="base64-encoded-32-byte-key"
export ALLOWED_HOSTS="api.externa.com,supabase.co"
export CORS_ORIGINS="https://app.meudominio.com"
export RATE_LIMIT=true
export RATE_LIMIT_GENERATE=10
export MAX_OUTPUT_SIZE=104857600  # 100 MB
dart run bin/sulfite_server.dart

Hub externo (JWKS + registry remoto)#

export AUTH_JWKS_URL="https://auth.your-system.example.com/.well-known/jwks.json"
export AUTH_ISSUER="https://auth.your-system.example.com"
export AUTH_AUDIENCE="sulfite-api"
export CONNECTION_REGISTRY_BACKEND=remote
export CONNECTION_HUB_URL="https://hub.your-system.internal"
export CONNECTION_HUB_TOKEN="service-token"
export CONNECTION_ROUTES_ENABLED=false
export MULTI_TENANT_MODE=true
export STORAGE_BACKEND=postgres
export DATABASE_URL="postgres://user:pass@host:5432/sulfite_reports"
dart run bin/sulfite_server.dart

Veja Hub externo — autenticação e conexões para o fluxo completo.

Docker#

FROM dart:stable AS build
WORKDIR /app
COPY packages/sulfite_server/ .
RUN dart pub get
RUN dart compile exe bin/sulfite_server.dart -o server

FROM scratch
COPY --from=build /runtime/ /
COPY --from=build /app/server /app/server
EXPOSE 8080
CMD ["/app/server"]

Fluxo de inicialização#

O servidor inicializa os componentes nesta ordem:

1. ServerConfig — carrega variáveis de ambiente
2. ReportRepository — cria backend de armazenamento (SQLite, Postgres ou memória)
3. ConnectionRegistry — registro de conexões (opcionalmente com criptografia AES-256-GCM)
4. SulfiteEngine — instância do motor de renderização
5. DataSourceResolvers — RestDataSourceResolver, PostgresDataSourceResolver, PostgRestDataSourceResolver
6. SsrfGuard — proteção SSRF (se ALLOWED_HOSTS configurado)
7. JobQueue — fila de geração assíncrona
8. RateLimiter — rate limiting por IP (se RATE_LIMIT=true)
9. TokenStore — store de refresh tokens (persistente ou in-memory)
10. ReportSigner — assinatura de relatórios (se ENCRYPTION_KEY configurado)
11. SulfiteServer — monta o app HTTP com middleware pipeline e handlers

Pipeline de middleware#

Cada request passa por esta cadeia (nesta ordem):

→ CORS middleware        Valida origens, envia headers CORS
→ Security headers       X-Content-Type-Options, X-Frame-Options, Cache-Control
→ Error middleware        Captura exceções, sanitiza logs
→ Request logger         Loga método, path, status, duração
→ Auth middleware         Valida Bearer/X-API-Key, anexa AuthToken ao request
→ Rate limiter           Limita requests por IP (se habilitado)
→ Handler                Processa a request