Voltar

Integrações (OAuth2, Mail, Métricas)

🧪 Experimental — parte da camada core (kyrux/core), a mesma usada pelas APIs e o NoSQL. Rotulada "experimental" pelo próprio USE.md do framework.

OAuth2 — core.Auth.OAuth2

Fluxo Authorization Code, genérico pra qualquer provedor (Google, GitHub, IdP interno) — você informa authURL/tokenURL (o pacote golang.org/x/oauth2/endpoints já traz os dos provedores mais comuns).

import "kyrux/core"

c := core.New()
cfg, err := c.Auth.OAuth2("google",
    clientID, clientSecret,
    "https://accounts.google.com/o/oauth2/auth",
    "https://oauth2.googleapis.com/token",
    "https://meuapp.com/callback",
    "email", "profile", // scopes
)

// devolve *oauth2.Config padrão do golang.org/x/oauth2:
url := cfg.AuthCodeURL(state)
token, err := cfg.Exchange(ctx, code)
httpClient := cfg.Client(ctx, token)

Init falha rápido se clientID/clientSecret ou authURL/tokenURL estiverem vazios — erro na hora de montar, não no primeiro request.

Mail/SMTP — core.Mail.SMTP

Envio via net/smtp puro (sem lib de terceiros) — monta MIME multipart (alternative/mixed) sozinho, texto + HTML + anexos.

import (
    "kyrux/core"
    kymail "kyrux/core/mail"
)

c := core.New()
client, err := c.Mail.SMTP("principal", host, port, username, password, true) // true = STARTTLS

err = client.Send(ctx, kymail.Message{
    From:    "[email protected]",
    To:      []string{"[email protected]"},
    Subject: "Bem-vindo",
    Text:    "Obrigado por se cadastrar.",
    HTML:    "<p>Obrigado por se cadastrar.</p>",
    Attachments: []kymail.Attachment{
        {Filename: "nota.pdf", Content: pdfBytes, ContentType: "application/pdf"},
    },
})

Porta 465 usa TLS implícito (SMTPS) automaticamente — detectado pela porta, sem parâmetro extra: o handshake TLS começa antes de qualquer byte do protocolo SMTP, então StartTLS não entra em jogo e o useTLS do exemplo acima é ignorado nesse caso. Qualquer outra porta (ex: 587) segue o comportamento de sempre — texto plano com STARTTLS opcional via useTLS.

Configure faz apenas um dial TCP em texto plano como checagem de conectividade (sem TLS, mesmo na porta 465) antes de devolver um client utilizável — falha cedo se o servidor estiver inacessível, mas o handshake TLS em si (implícito ou STARTTLS) só acontece no primeiro Send.

kymail.Sender é a interface (Send(ctx, Message) error) — além do SMTP, existem adapters pra SendGrid (core/adapters/sendgrid) e AWS SES (core/adapters/ses) implementando a mesma interface. Esses dois não têm sugar no core.Mail (peso do SDK de terceiros) — ative via core.UseModule[kymail.Sender].

Métricas — Prometheus e OpenTelemetry

Sem sugar em nenhum dos dois (dependência de terceiros) — ative via core.UseModule.

Prometheus — core/adapters/prometheus

import (
    "kyrux/core"
    prometheusadapter "kyrux/core/adapters/prometheus"
    prom "github.com/prometheus/client_golang/prometheus"
)

c := core.New()
metrics, err := core.UseModule[*prometheusadapter.Client](
    c, prometheusadapter.New("principal"), "observability.prometheus.principal",
)

requestsTotal := prom.NewCounter(prom.CounterOpts{
    Name: "kyrux_requests_total",
    Help: "Total de requisições",
})
metrics.MustRegister(requestsTotal)

r, _ := c.API.REST(":8080")
r.HandlePrefix("/metrics", metrics.Handler()) // mesmo padrão usado pra montar SOAP

c.Run()

Configure já pré-registra os coletores padrão do runtime Go (goroutines, GC, etc.). O registry é isolado (*prometheus.Registry próprio) — não usa o DefaultRegisterer global, então múltiplas instâncias não colidem.

OpenTelemetry — core/adapters/opentelemetry

Segue o mesmo padrão (New + core.UseModule), exportação OTLP/HTTP apenas (sem gRPC, sem outros exporters). Consulte o pacote diretamente — ainda sem página própria na doc.