merge: issue/0012-email-smtp — Email SMTP functions
This commit is contained in:
@@ -0,0 +1,348 @@
|
||||
# 0012 — Email & SMTP
|
||||
|
||||
## Metadata
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | 0012 |
|
||||
| **Estado** | pendiente |
|
||||
| **Prioridad** | media |
|
||||
| **Tipo** | feature |
|
||||
|
||||
## Dependencias
|
||||
|
||||
Ninguna.
|
||||
|
||||
---
|
||||
|
||||
## Objetivo
|
||||
|
||||
Crear funciones reutilizables de envio de email via SMTP en Go y Python (dominio infra), separando la construccion del mensaje (pure) del transporte (impure). Cualquier app del registry que necesite enviar notificaciones, alertas o reportes puede componer estas primitivas sin reimplementar SMTP desde cero.
|
||||
|
||||
## Contexto
|
||||
|
||||
- Actualmente existen **CERO funciones de email** en el registry. Busqueda FTS5 sobre `email` y `smtp` solo arroja coincidencias incidentales en funciones de Metabase (auth con email/password) y normalizacion de entidades OSINT.
|
||||
- El tipo `email_go_core` existe pero es un tipo de cybersecurity (direccion de email como entidad de interes), no un mensaje de correo.
|
||||
- Casi toda app no trivial termina necesitando enviar notificaciones: alertas del bucle reactivo cuando assertions fallan, reportes periodicos de ejecuciones, confirmaciones de deploy, etc.
|
||||
- Go stdlib tiene `net/smtp` y `crypto/tls` — suficiente para SMTP con TLS/STARTTLS sin dependencias externas. Python tiene `smtplib` y `email` en stdlib.
|
||||
- El patron pure core / impure shell aplica naturalmente: construir el mensaje es puro, enviarlo es impuro.
|
||||
|
||||
## Arquitectura
|
||||
|
||||
```
|
||||
functions/infra/
|
||||
├── smtp_connect.go — NEW: conexion SMTP con TLS/STARTTLS
|
||||
├── smtp_connect.md — NEW
|
||||
├── smtp_send.go — NEW: enviar email via conexion SMTP
|
||||
├── smtp_send.md — NEW
|
||||
├── email_build_html.go — NEW: construir email multipart con HTML
|
||||
├── email_build_html.md — NEW
|
||||
├── email_build_text.go — NEW: construir email plain text
|
||||
├── email_build_text.md — NEW
|
||||
├── email_with_attachment.go — NEW: anadir adjunto a un EmailMessage
|
||||
├── email_with_attachment.md — NEW
|
||||
├── email_template_render.go — NEW: renderizar body desde Go template
|
||||
├── email_template_render.md — NEW
|
||||
|
||||
python/functions/infra/
|
||||
├── smtp_send.py — NEW: enviar email via SMTP (smtplib)
|
||||
├── smtp_send.md — NEW
|
||||
├── email_build_html.py — NEW: construir email HTML (email.mime)
|
||||
├── email_build_html.md — NEW
|
||||
|
||||
types/infra/
|
||||
├── email_message.md — NEW: metadata del tipo EmailMessage
|
||||
├── smtp_config.md — NEW: metadata del tipo SMTPConfig
|
||||
├── email_attachment.md — NEW: metadata del tipo EmailAttachment
|
||||
```
|
||||
|
||||
### Patron pure core / impure shell
|
||||
|
||||
- **Pure:** `email_build_html`, `email_build_text`, `email_with_attachment`, `email_template_render`, `email_build_html` (Python) — construyen estructuras de datos sin I/O.
|
||||
- **Impure:** `smtp_connect`, `smtp_send` (Go), `smtp_send` (Python) — abren conexiones de red, envian datos por el socket.
|
||||
|
||||
## Diseno
|
||||
|
||||
### Tipos
|
||||
|
||||
```go
|
||||
// EmailMessage representa un email completo listo para enviar.
|
||||
type EmailMessage struct {
|
||||
From string `json:"from"`
|
||||
To []string `json:"to"`
|
||||
CC []string `json:"cc,omitempty"`
|
||||
BCC []string `json:"bcc,omitempty"`
|
||||
Subject string `json:"subject"`
|
||||
BodyHTML string `json:"body_html,omitempty"`
|
||||
BodyText string `json:"body_text,omitempty"`
|
||||
Attachments []EmailAttachment `json:"attachments,omitempty"`
|
||||
Headers map[string]string `json:"headers,omitempty"`
|
||||
}
|
||||
|
||||
// SMTPConfig contiene los datos de conexion al servidor SMTP.
|
||||
type SMTPConfig struct {
|
||||
Host string `json:"host"`
|
||||
Port int `json:"port"`
|
||||
Username string `json:"username"`
|
||||
Password string `json:"password"`
|
||||
TLSMode string `json:"tls_mode"` // "tls", "starttls", "none"
|
||||
}
|
||||
|
||||
// EmailAttachment representa un archivo adjunto.
|
||||
type EmailAttachment struct {
|
||||
Filename string `json:"filename"`
|
||||
ContentType string `json:"content_type"`
|
||||
Data []byte `json:"data"`
|
||||
}
|
||||
```
|
||||
|
||||
```python
|
||||
# Python equivalentes (dataclasses)
|
||||
@dataclass
|
||||
class EmailMessage:
|
||||
from_addr: str
|
||||
to: list[str]
|
||||
subject: str
|
||||
body_html: str = ""
|
||||
body_text: str = ""
|
||||
cc: list[str] = field(default_factory=list)
|
||||
bcc: list[str] = field(default_factory=list)
|
||||
attachments: list[EmailAttachment] = field(default_factory=list)
|
||||
|
||||
@dataclass
|
||||
class SMTPConfig:
|
||||
host: str
|
||||
port: int
|
||||
username: str
|
||||
password: str
|
||||
tls_mode: str = "tls" # "tls", "starttls", "none"
|
||||
|
||||
@dataclass
|
||||
class EmailAttachment:
|
||||
filename: str
|
||||
content_type: str
|
||||
data: bytes
|
||||
```
|
||||
|
||||
### Funciones
|
||||
|
||||
| ID | Purity | Firma (simplificada) | Descripcion |
|
||||
|----|--------|---------------------|-------------|
|
||||
| `smtp_connect_go_infra` | impure | `(cfg SMTPConfig) (*smtp.Client, error)` | Conecta al servidor SMTP con TLS o STARTTLS segun config, autentica con PLAIN/LOGIN y retorna el cliente listo para enviar |
|
||||
| `smtp_send_go_infra` | impure | `(client *smtp.Client, msg EmailMessage) error` | Serializa el EmailMessage a formato MIME, envia via el cliente SMTP abierto. Maneja To + CC + BCC como recipientes del sobre |
|
||||
| `smtp_send_py_infra` | impure | `(cfg: SMTPConfig, msg: EmailMessage) -> None` | Conecta, autentica y envia en un solo paso usando smtplib. Cierra la conexion al terminar |
|
||||
| `email_build_html_go_infra` | pure | `(from, subject string, to []string, html string) EmailMessage` | Construye un EmailMessage con body HTML. Setea BodyText vacio |
|
||||
| `email_build_text_go_infra` | pure | `(from, subject string, to []string, text string) EmailMessage` | Construye un EmailMessage con body plain text. Setea BodyHTML vacio |
|
||||
| `email_build_html_py_infra` | pure | `(from_addr, subject: str, to: list[str], html: str) -> EmailMessage` | Construye un EmailMessage con body HTML (Python) |
|
||||
| `email_with_attachment_go_infra` | pure | `(msg EmailMessage, filename, contentType string, data []byte) EmailMessage` | Retorna copia del EmailMessage con el adjunto anadido. No muta el original |
|
||||
| `email_template_render_go_infra` | pure | `(tmpl string, data any) (string, error)` | Renderiza un template Go (`text/template`) con los datos proporcionados. El resultado se usa como body del email |
|
||||
|
||||
### Notas de implementacion
|
||||
|
||||
**Go (`smtp_connect`):**
|
||||
- Puerto 465 → TLS directo con `tls.Dial`
|
||||
- Puerto 587 → conexion plain + STARTTLS con `smtp.Client.StartTLS`
|
||||
- Puerto 25 → sin cifrado (solo para redes internas, modo `none`)
|
||||
- Auth: `smtp.PlainAuth` con identity vacio (compatible con la mayoria de proveedores)
|
||||
- Retorna `*smtp.Client` que el caller cierra con `defer client.Close()`
|
||||
|
||||
**Go (`smtp_send`):**
|
||||
- Construye el mensaje MIME manualmente: headers (From, To, CC, Subject, MIME-Version, Content-Type) + body multipart si hay HTML + text o adjuntos
|
||||
- BCC no se incluye en headers pero si en `smtp.Client.Rcpt()`
|
||||
- Multipart boundary generado con `mime/multipart`
|
||||
|
||||
**Python (`smtp_send`):**
|
||||
- `smtplib.SMTP_SSL` para TLS directo, `smtplib.SMTP` + `starttls()` para STARTTLS
|
||||
- Construye el mensaje con `email.mime.multipart.MIMEMultipart` y `email.mime.text.MIMEText`
|
||||
- Adjuntos con `email.mime.base.MIMEBase` + `encoders.encode_base64`
|
||||
- Context manager para garantizar cierre de la conexion
|
||||
|
||||
**Template render:**
|
||||
- Usa `text/template` de Go stdlib, no `html/template` (el caller puede pasar HTML ya sanitizado)
|
||||
- Soporta las funciones built-in de Go templates: `{{if}}`, `{{range}}`, `{{with}}`, pipes
|
||||
- Error si el template no parsea o la ejecucion falla (campos faltantes en data)
|
||||
|
||||
## Tareas
|
||||
|
||||
### Fase 1: Tipos
|
||||
|
||||
- [ ] **1.1** Crear tipo `EmailMessage` en `functions/infra/email_message.go` con `.md` en `types/infra/email_message.md` — product type con los campos: From, To, CC, BCC, Subject, BodyHTML, BodyText, Attachments, Headers
|
||||
- [ ] **1.2** Crear tipo `SMTPConfig` en `functions/infra/smtp_config.go` con `.md` en `types/infra/smtp_config.md` — product type con: Host, Port, Username, Password, TLSMode
|
||||
- [ ] **1.3** Crear tipo `EmailAttachment` en `functions/infra/email_attachment.go` con `.md` en `types/infra/email_attachment.md` — product type con: Filename, ContentType, Data
|
||||
- [ ] **1.4** `fn index` y verificar los 3 tipos en registry.db
|
||||
|
||||
### Fase 2: Funciones puras (builders)
|
||||
|
||||
- [ ] **2.1** `email_build_html_go_infra` — construir EmailMessage con HTML body
|
||||
- [ ] **2.2** `email_build_text_go_infra` — construir EmailMessage con plain text body
|
||||
- [ ] **2.3** `email_with_attachment_go_infra` — retornar copia del mensaje con adjunto anadido (sin mutar original)
|
||||
- [ ] **2.4** `email_template_render_go_infra` — renderizar body desde Go template string + data map
|
||||
- [ ] **2.5** `email_build_html_py_infra` — construir EmailMessage con HTML body (Python)
|
||||
- [ ] **2.6** Tests para las 5 funciones puras: verificar campos del EmailMessage resultante, verificar render de templates con variables, verificar que adjuntos se anaden correctamente
|
||||
|
||||
### Fase 3: Funciones impuras (transporte SMTP)
|
||||
|
||||
- [ ] **3.1** `smtp_connect_go_infra` — conexion TLS directa (puerto 465), STARTTLS (puerto 587), sin cifrado (puerto 25). Auth con PLAIN. Retornar `*smtp.Client`
|
||||
- [ ] **3.2** `smtp_send_go_infra` — serializar EmailMessage a MIME, enviar via `smtp.Client`. Manejar multipart (HTML + text + adjuntos), BCC en el sobre pero no en headers
|
||||
- [ ] **3.3** `smtp_send_py_infra` — conectar + enviar + cerrar en un paso. Usar `smtplib.SMTP_SSL` o `smtplib.SMTP` + `starttls()` segun TLSMode
|
||||
- [ ] **3.4** Tests con stub SMTP server: Go con `net/smtp` test server, Python con `smtpd.DebuggingServer` o mock
|
||||
|
||||
### Fase 4: Integracion y cleanup
|
||||
|
||||
- [ ] **4.1** `fn index` y verificar que las 8 funciones y 3 tipos aparecen en registry.db
|
||||
- [ ] **4.2** `go vet -tags fts5 ./functions/infra/`
|
||||
- [ ] **4.3** Verificar composabilidad: `email_build_html` | `email_with_attachment` | `smtp_send` fluye sin adaptadores
|
||||
|
||||
---
|
||||
|
||||
## Ejemplo de uso
|
||||
|
||||
### Go: enviar notificacion HTML con adjunto
|
||||
|
||||
```go
|
||||
// Configurar conexion SMTP
|
||||
cfg := infra.SMTPConfig{
|
||||
Host: "smtp.gmail.com",
|
||||
Port: 587,
|
||||
Username: "alerts@midominio.com",
|
||||
Password: os.Getenv("SMTP_PASSWORD"),
|
||||
TLSMode: "starttls",
|
||||
}
|
||||
|
||||
// Construir el mensaje (puro)
|
||||
msg := infra.EmailBuildHtml(
|
||||
"alerts@midominio.com",
|
||||
"Alerta: assertion critica fallida",
|
||||
[]string{"lucas@midominio.com"},
|
||||
"<h1>Assertion fallida</h1><p>Entity X tiene valor fuera de rango.</p>",
|
||||
)
|
||||
|
||||
// Anadir adjunto (puro, retorna copia)
|
||||
reportData, _ := os.ReadFile("report.csv")
|
||||
msg = infra.EmailWithAttachment(msg, "report.csv", "text/csv", reportData)
|
||||
|
||||
// Enviar (impuro)
|
||||
client, err := infra.SmtpConnect(cfg)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
defer client.Close()
|
||||
|
||||
if err := infra.SmtpSend(client, msg); err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
```
|
||||
|
||||
### Go: email desde template
|
||||
|
||||
```go
|
||||
tmpl := `Hola {{.Nombre}},
|
||||
|
||||
El pipeline {{.Pipeline}} finalizó con status: {{.Status}}.
|
||||
Registros procesados: {{.Records}}
|
||||
Duración: {{.Duration}}
|
||||
|
||||
— fn_registry`
|
||||
|
||||
body, err := infra.EmailTemplateRender(tmpl, map[string]any{
|
||||
"Nombre": "Lucas",
|
||||
"Pipeline": "sync_metabase",
|
||||
"Status": "success",
|
||||
"Records": 1523,
|
||||
"Duration": "4.2s",
|
||||
})
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
msg := infra.EmailBuildText(
|
||||
"system@midominio.com",
|
||||
"Pipeline sync_metabase completado",
|
||||
[]string{"lucas@midominio.com"},
|
||||
body,
|
||||
)
|
||||
|
||||
client, _ := infra.SmtpConnect(cfg)
|
||||
defer client.Close()
|
||||
infra.SmtpSend(client, msg)
|
||||
```
|
||||
|
||||
### Python: enviar alerta desde un analysis notebook
|
||||
|
||||
```python
|
||||
from infra import smtp_send, email_build_html, SMTPConfig, EmailMessage
|
||||
|
||||
cfg = SMTPConfig(
|
||||
host="smtp.gmail.com",
|
||||
port=587,
|
||||
username="alerts@midominio.com",
|
||||
password=os.environ["SMTP_PASSWORD"],
|
||||
tls_mode="starttls",
|
||||
)
|
||||
|
||||
msg = email_build_html(
|
||||
from_addr="alerts@midominio.com",
|
||||
subject="Anomalia detectada en dataset",
|
||||
to=["lucas@midominio.com"],
|
||||
html="<h2>Anomalia</h2><p>3 outliers detectados en columna revenue.</p>",
|
||||
)
|
||||
|
||||
smtp_send(cfg, msg)
|
||||
```
|
||||
|
||||
### Composicion con el bucle reactivo
|
||||
|
||||
```go
|
||||
// En el paso MEJORAR del bucle reactivo, cuando una assertion critica falla:
|
||||
func notifyAssertionFailure(cfg infra.SMTPConfig, entity Entity, assertion Assertion, result AssertionResult) error {
|
||||
tmpl := `Assertion "{{.Assertion}}" FALLÓ para entity {{.Entity}}.
|
||||
Valor actual: {{.Value}}
|
||||
Regla: {{.Rule}}
|
||||
Timestamp: {{.Timestamp}}`
|
||||
|
||||
body, err := infra.EmailTemplateRender(tmpl, map[string]any{
|
||||
"Assertion": assertion.Name,
|
||||
"Entity": entity.ID,
|
||||
"Value": result.Value,
|
||||
"Rule": assertion.Rule,
|
||||
"Timestamp": result.CreatedAt,
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
msg := infra.EmailBuildText(cfg.Username, "ALERTA: "+assertion.Name, []string{"lucas@midominio.com"}, body)
|
||||
|
||||
client, err := infra.SmtpConnect(cfg)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer client.Close()
|
||||
|
||||
return infra.SmtpSend(client, msg)
|
||||
}
|
||||
```
|
||||
|
||||
## Decisiones de diseno
|
||||
|
||||
- **Solo stdlib `net/smtp` + `crypto/tls` (Go) y `smtplib` + `email` (Python):** sin dependencias externas. Go stdlib es suficiente para SMTP con TLS/STARTTLS y MIME multipart. No se necesita gomail, jordan-wright/email ni similares.
|
||||
- **Separar conexion de envio en Go:** `smtp_connect` retorna el client, `smtp_send` lo usa. Esto permite reusar una conexion para multiples envios (batch) sin reconectar cada vez. En Python se unifica porque `smtplib` maneja el ciclo de vida internamente con context managers.
|
||||
- **Builders puros retornan structs, no bytes:** las funciones `email_build_*` retornan `EmailMessage`, no el MIME serializado. La serializacion a bytes MIME ocurre dentro de `smtp_send` (impuro). Esto permite inspeccionar, modificar y componer mensajes antes de enviar.
|
||||
- **`email_with_attachment` no muta:** retorna una copia del `EmailMessage` con el adjunto anadido. Coherente con la regla de pureza — sin mutacion.
|
||||
- **`email_template_render` es generico:** renderiza cualquier template Go a string. No sabe nada de email — el resultado se pasa a `email_build_text` o `email_build_html`. Reutilizable para generar otros textos.
|
||||
- **TLSMode como string (`"tls"`, `"starttls"`, `"none"`):** mas explicito que un booleano. Cubre los 3 escenarios reales: TLS directo (465), STARTTLS (587), sin cifrado (25/internal).
|
||||
- **Headers como `map[string]string`:** permite anadir headers custom (Reply-To, X-Priority, List-Unsubscribe) sin cambiar la estructura del tipo.
|
||||
|
||||
## Prerequisitos
|
||||
|
||||
Ninguno. Solo Go stdlib y Python stdlib.
|
||||
|
||||
Para tests: un servidor SMTP de prueba local o mocks. Go tiene primitivas en `net` para levantar un listener TCP. Python puede usar `aiosmtpd` o mocks de `smtplib`.
|
||||
|
||||
## Riesgos
|
||||
|
||||
- **Credenciales SMTP hardcodeadas:** Mitigado por diseno — `SMTPConfig` recibe los valores, nunca los lee de archivos ni env vars directamente. El caller es responsable de obtener las credenciales (env vars, secrets manager, etc.).
|
||||
- **Emails enviados accidentalmente en tests:** Mitigado separando conexion de envio. Los tests de funciones puras no tocan la red. Los tests de funciones impuras usan un SMTP server mock local.
|
||||
- **Rate limiting del proveedor SMTP:** No se maneja en v1. Si una app necesita enviar muchos emails, deberia implementar rate limiting en la capa de aplicacion (fuera del scope de estas funciones atomicas).
|
||||
- **HTML injection en templates:** `email_template_render` usa `text/template`, no `html/template`, asi que no escapa HTML automaticamente. Documentar que el caller es responsable de sanitizar inputs si el template genera HTML.
|
||||
- **Compatibilidad MIME con clientes de email:** El formato multipart generado debe ser compatible con Gmail, Outlook, Apple Mail. Testar con al menos 2 clientes reales antes de cerrar la issue.
|
||||
Reference in New Issue
Block a user