README
¶
API de ejemplo
Una API HTTP ejecutable que cablea todos los paquetes de vogel en una sola
vertical de negocio. No es un catálogo de snippets: es un package main que
arranca, atiende requests y persiste en PostgreSQL. El README de la raíz explica
qué es cada paquete; este directorio muestra cómo se conectan entre sí, que
es la parte que ninguna tabla de paquetes puede enseñar.
El dominio es deliberadamente chico —un documento que pasa por un flujo de aprobación— para que lo interesante sea el cableado y no las reglas de negocio.
Arranque rápido
cd examples/api
docker compose up -d # PostgreSQL 17, publicado en el host en el 55432
cp env.example .env # revise DATABASE_URL si cambió algo
go run .
El ejemplo lee el .env por su cuenta (dotenv.go), así que no hace falta
exportar nada en la shell. Dos aclaraciones que importan:
- Corra
go run .parado enexamples/api, no desde la raíz del repo: el archivo se busca como.envrelativo al directorio actual. - Una variable ya presente en el entorno le gana al archivo, así que
PORT=9000 go run .hace lo que dice aunque el.envdiga otra cosa.
vogel/config lee os.Getenv y nada más — no conoce archivos, ni rutas de
búsqueda, ni reglas de precedencia. Eso es a propósito: de dónde sale el entorno
(un .env, un secrets manager, Kubernetes, systemd) es una decisión del
consumidor, y dotenv.go es esa decisión tomada acá, en treinta líneas y sin
dependencias.
El contenedor publica el 5432 interno en el 55432 del host, para no
chocar con un PostgreSQL que ya esté escuchando en el puerto default. El
DATABASE_URL de env.example ya apunta ahí.
Las migraciones corren solas al arrancar. Verificación:
curl -s localhost:8080/healthz
Autenticarse contra el ejemplo
El ejemplo trae un auth.Authenticator falso que acepta un token con la forma
<userID>:<username>:<rol1,rol2>. No hay nada que registrar:
TOKEN='u-1:oscar:admin'
# Crear un documento
curl -s -X POST localhost:8080/documents \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"title":"Contrato marco","kind":"contract","issued_at":"03/02/2026"}'
# Ver el rastro de auditoría que esa única llamada dejó
curl -s "localhost:8080/audit?resource_type=document" -H "Authorization: Bearer $TOKEN"
El authz.Checker falso permite todo al rol admin y sólo acciones de lectura
al resto. Pruebe con u-2:ana:viewer para ver un 403 real.
DELETE /documents/{id} es la única ruta que demuestra el chequeo por
instancia de vogel/access en lugar de conformarse con el chequeo grueso.
Con TOKEN='u-1:oscar:autor' (sin rol admin), borrar un documento propio
de kind contract funciona; el mismo intento sobre un documento de kind
report — igual de propio — responde 403, porque fakeChecker sólo conoce
esa distinción una vez que DocumentHandler.Delete cargó la fila y se lo
pasó en authz.Resource.Attr. Ver la fila DELETE en la tabla de rutas más
abajo y el comentario de documentación de DocumentHandler.Delete.
Por dónde empezar a leer
El orden importa: cada archivo asume el anterior.
| Orden | Archivo | Lo que enseña |
|---|---|---|
| 1 | main.go |
El composition root. Todo se construye acá y en ningún otro lado: config, pool, migraciones, métricas, adaptadores, cola, router, apagado ordenado. Si entiende este archivo, entiende el módulo. |
| 2 | handler.go → Create |
La pieza central. Una transacción, cuatro escrituras. Explicado abajo. |
| 3 | fakes.go, fakestorage.go |
Los cuatro puertos implementados en memoria, cada uno con el adaptador real que reemplaza. El de storage hace además de bucket: sirve las URL firmadas que emite. |
| 4 | router.go |
El orden del stack de middleware, con el porqué de cada posición. |
| 5 | store.go |
Un repositorio que recibe pgxtx.DBTX en vez de un pool, y por qué eso elimina la duplicación de métodos "con tx" y "sin tx". |
| 6 | workflow.go |
Una Definition válida y una guarda, con la restricción que define al motor. |
| 7 | jobs.go |
Dos jobs de River que auditan con SourceWorker, no con SourceHTTP: notify_reviewers y validate_upload, que inspecciona cada archivo subido. |
| 8 | config.go |
El acumulador de errores de configuración: un arranque reporta todos los problemas juntos. |
| 9 | dotenv.go |
Por qué vogel/config no lee archivos, y cómo el consumidor cubre ese hueco sin sumar dependencias. |
La pieza central: POST /documents
Un solo tx.WithTx hace cuatro escrituras:
- La fila del documento (
store.Create) - El caso de workflow (
engine.Open) - La entrada de auditoría (
recorder.Record) - El job de notificación (
queue.EnqueueTx)
Las cuatro commitean o no commitea ninguna. Ese es el motivo de que
worker.EnqueueTx exista además de Enqueue, y es el patrón transactional
outbox:
Si en vez de EnqueueTx usara… |
Qué se rompe |
|---|---|
Enqueue después del commit |
Una caída entre el commit y el encolado deja un documento cuya notificación no se envía nunca, y sin registro de que se debía |
Enqueue antes del commit |
Un worker puede procesar el job de un documento que un error posterior en el mismo handler termina revirtiendo: se notifica sobre algo que nunca existió |
EnqueueTx inserta la fila del job dentro de la misma transacción. El job se
vuelve visible para un worker si y sólo si todo commiteó.
Subir un archivo: el servidor no toca los bytes
La API nunca recibe ni reenvía el contenido de un archivo. El cliente lo sube directo al storage con una URL firmada, y la validación pesada corre en un job:
-
POST /documents/{id}/upload-urlcon{"content_type":"application/pdf","size":1234}. Un tipo fuera deallowedUploadTypesresponde415; unsizemenor que 1 o mayor quemaxUploadBytes(25 MiB),400. La respuesta traeurl,key(documents/{id}/uploads/{uuid}, una por subida),method(PUT),headersyexpires_at(aproxima el vencimiento firmado: se calcula con la misma expiración, pero con el reloj leído justo antes de firmar). La URL vive 5 minutos y firma elContent-Typey elContent-Lengthexactos: el bucket rechaza otro tipo o un cuerpo de otro tamaño. No se persiste nada todavía. -
El cliente hace el
PUTa esaurlcon esosheadersy el archivo. -
POST /documents/{id}/filecon{"key":"..."}confirma la subida. Lakeytiene que ser una emitida para ese documento (si no,400). En una sola transacción el documento queda confile_status: "pending", se encolavalidate_uploadconEnqueueTxy se auditadocument_attach_file. Responde202. Se valida una subida por vez: mientras la anterior sigapending, otra confirmación responde409("a previous upload is still being validated") sin cambiar nada, y el cliente reintenta cuando el job la resolvió. La fila guarda desde cuándo estápending(file_pending_since); si lleva más de una hora (stalePendingAfter, muy por encima de los ~12 minutos de reintentos del job), su job se perdió (un panic, una cancelación, la base caída en el último intento) y la confirmación la toma: conserva el archivo anterior que tuviera, y el job abandonado, si llega a correr, encuentra la fila cambiada y sólo limpia sus propios objetos. -
validate_upload(ValidateUploadWorkerenjobs.go) descarga el objeto y detecta el tipo por el contenido constorage.SniffContentType, leyendo sólo los primeros bytes. Si el objeto no existe, el archivo quedarejected; si el contenido no es un tipo permitido, borra el objeto y lo marcarejected; si es válido, copia esos mismos bytes a una key final,documents/{id}/file/{uuid}, deja el documentoreadyapuntando ahí con el tipo detectado y borra el objeto de subida. Cada veredicto se escribe sólo si el documento sigue apuntando a esakey: una subida más nueva gana y un job viejo no la pisa (si ya había copiado, borra su copia); además sólo cambia un archivopending, así que un reintento del job que ya resolvió la fila no hace nada ni se audita dos veces. Si la confirmación reemplazaba un archivoready, ese archivo queda en la fila como archivo anterior (previous_storage_key,previous_content_type). Un reemplazo aceptado lo retira: en la misma transacción del veredicto encola un jobdelete_objectcon su key, que River reintenta hasta borrarlo. Uno rechazado (inexistente o no permitido) lo restaura: el documento vuelve areadycon su archivo y su tipo, y la auditoría lo registra comodocument_restore_file, no como una aceptación. Así, repetir una confirmación con unakeyya consumida no destruye el archivo validado. El veredicto se graba antes de borrar el objeto de subida; si ese borrado falla, el reintento del job relee la fila y termina la limpieza. El job se encola con 5 intentos como máximo (validateUploadMaxAttempts, en vez de los 25 de River, que reparten los reintentos en semanas): con el backoff de River el último intento llega a unos 12 minutos de la confirmación. Si el job falla en todos sus intentos (por ejemplo, el storage no responde), el último intento no deja el documentopendingpara siempre: lo resuelve como un rechazo (restaura el archivo anterior o lo marcarejected), borra el objeto de subida si puede y lo deja en el log condocument_idykey.La copia cierra una carrera: la URL de subida sigue valiendo hasta 5 minutos después del job, y quien la tenga podría reescribir con ella un objeto ya validado. Nadie firma un
PUTbajofile/, y la confirmación sólo acepta keys deuploads/, así que el archivo que se sirve es siempre el que el job inspeccionó. -
GET /documents/{id}/download-urlfirma unGETde 5 minutos sobre la key final que el bucket sirve comoattachmenty con el tipo detectado, nunca con el que declaró el cliente. Mientras un reemplazo estápending, sirve el archivo anterior con su tipo: el documento no se queda sin descarga mientras se valida el nuevo. Sin archivoreadyni anterior, responde409.
TOKEN='u-1:oscar:admin'
DOC='...' # el id de un documento creado con POST /documents
printf '%%PDF-1.4\nhola\n' > /tmp/doc.pdf
curl -s -X POST localhost:8080/documents/$DOC/upload-url \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d "{\"content_type\":\"application/pdf\",\"size\":$(wc -c < /tmp/doc.pdf)}"
# Con la url y la key de la respuesta:
curl -s -X PUT "$URL" -H 'Content-Type: application/pdf' --data-binary @/tmp/doc.pdf
curl -s -X POST localhost:8080/documents/$DOC/file \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d "{\"key\":\"$KEY\"}"
Una URL firmada es una credencial: no se loguea, no va en mensajes de error ni en el rastro de auditoría. El access log registra sólo el path, nunca la query con la firma.
Con fakeStorage el "bucket" es este mismo servidor: las URL apuntan a
FAKE_STORAGE_BASE_URL (por defecto http://localhost:<PORT>) bajo
/fake-storage/, fuera de las rutas autenticadas y sin token, como el endpoint de un bucket
real. Llevan un HMAC del proceso sobre método, key, expiración, tipo y largo, y
el handler responde 403 ante una firma inválida, una URL vencida o un
Content-Type/Content-Length distinto del firmado. Con storage/s3 esas
rutas desaparecen y las URL apuntan al bucket, que debe seguir siendo privado.
Una URL de subida que nadie confirma deja un objeto bajo
documents/{id}/uploads/ que ninguna fila referencia. El ejemplo no los barre:
en producción la respuesta es una regla de ciclo de vida del bucket sobre ese
prefijo (por ejemplo, expirar a 1 día), que cubre también las subidas
abandonadas a mitad de camino. El bucket falso, que guarda todo en memoria,
limita en cambio el tamaño total de sus objetos a 256 MiB
(fakeMaxTotalBytes): un PUT que lo superaría responde 507, así que un
cliente con permiso de escritura no puede hacer crecer la memoria del proceso
sin límite.
Cambiar un fake por un adaptador real
Ese es el punto de la arquitectura de puertos, y acá se ve en una línea:
| Puerto | Fake del ejemplo | Adaptador real | Dónde se cambia |
|---|---|---|---|
auth.Authenticator |
fakeAuthenticator |
auth/zitadel |
main.go |
authz.Checker |
fakeChecker |
authz/cerbos |
main.go |
storage.Storage |
fakeStorage (un map con mutex, más un endpoint /fake-storage/ que verifica la firma de sus URL; un objeto inexistente es storage.ErrNotFound, igual que en storage/s3) |
storage/s3 (y quitar las dos rutas /fake-storage/* de router.go) |
main.go |
notification.Notifier |
fakeNotifier (loguea) |
notification/smtp o notification/sendgrid |
main.go |
Ningún handler, ningún job y ningún repositorio cambia. Ese es el resultado que la separación puerto/adaptador compra, y por eso el ejemplo usa fakes: si requiriera Zitadel, Cerbos y MinIO levantados a mano, nadie lo abriría — y de paso no demostraría nada, porque el cambio quedaría invisible.
Rutas
Toda ruta salvo /healthz y /fake-storage/ exige Authorization: Bearer <token>. Las rutas no llevan prefijo de versión: si hace falta versionar, el proxy inverso (nginx) publica cada versión de la app bajo su propio prefijo.
| Método | Ruta | Permiso | Qué demuestra |
|---|---|---|---|
POST |
/documents |
write | La transacción de cuatro escrituras |
GET |
/documents |
read | Paginación con response.JSONList |
GET |
/documents/{id} |
read | pgxtx.DBFromContext fuera de transacción |
POST |
/documents/{id}/upload-url |
write | storage.PresignedPutURL con WithContentLength: el cliente sube directo al storage (ver flujo) |
POST |
/documents/{id}/file |
write | Confirma la subida: EnqueueTx del job validate_upload + auditoría con WithChange (snapshot antes/después) |
GET |
/documents/{id}/download-url |
read | storage.PresignedGetURL con el tipo detectado (WithResponseContentType); 409 si el archivo no está ready |
POST |
/documents/{id}/transitions |
write | engine.Move, con guarda y errores mapeados a 409 |
POST |
/documents/{id}/claim |
write | engine.Claim con el actor sacado de auth.FromContext |
DELETE |
/documents/{id} |
delete (access.Guard) |
Chequeo por instancia: RequireAccess filtra por rol y por los IDs que el principal posee (resueltos vía access.WithPrincipalAttributes); DocumentHandler.Delete carga el documento y llama a guard.Check de nuevo, esta vez con Attr: {"kind": ...}, para negar el borrado de un "report" aunque el dueño coincida — un dato que sólo se conoce después de cargar la fila |
GET |
/documents/{id}/history |
read | engine.History |
GET |
/inbox |
read | engine.Inbox por elegibilidad |
GET |
/audit, /audit/{id} |
read | El handler de audit/httpx montado tal cual |
Sin autenticación: GET /healthz, que siempre responde: 200 con "ok"
si la base contesta un ping y 503 con "database unavailable" si no.
GET /metrics (Prometheus) no se sirve en el puerto de la API sino en un
listener interno aparte, METRICS_ADDR (por defecto 127.0.0.1:2112, solo
loopback; no 9090, que es el puerto por defecto del propio Prometheus):
curl localhost:2112/metrics. Dentro de un contenedor que Prometheus scrapea
desde otra red, usar METRICS_ADDR=:2112 y no publicar ese puerto hacia
afuera. Si la dirección está ocupada o es inválida, el arranque falla con un
error que la nombra.
El servidor de la API (newAPIServer en main.go) fija todos sus timeouts
desde la configuración: HTTP_READ_HEADER_TIMEOUT (5s), HTTP_READ_TIMEOUT
(15s), HTTP_WRITE_TIMEOUT (30s) y HTTP_IDLE_TIMEOUT (60s). Un valor cero
o negativo falla en el arranque, porque en net/http cero significa "sin
timeout". Las cabeceras se limitan a 64 KiB (maxHeaderBytes).
HTTP_READ_TIMEOUT también acota cuánto puede tardar en llegar el cuerpo de
un PUT al bucket falso, que corre en este mismo servidor.
router_test.go recorre el router con chi.Walk y falla si alguna ruta
que no esté declarada en publicRoutes (hoy, /healthz y el GET/PUT de
/fake-storage/*) responde sin pasar por RequirePermission o
RequireAccess. rolematrix_test.go fija, para cada ruta y cada tipo de
llamador (anónimo, token inválido, usuario común, dueño, admin), si los
guards lo dejan pasar, y falla si aparece una ruta sin fila en la matriz.
Las rutas autenticadas tienen un límite de pedidos por IP de cliente (ratelimit.go):
RATE_LIMIT_REQUESTS pedidos (300) por RATE_LIMIT_WINDOW (1m), con la IP
que vmw.RequestContext dejó en reqctx. Al pasarse responde 429 con el
código RATE_LIMITED y Retry-After. Se chequea antes de autenticar, así que
también frena a quien prueba tokens; /healthz queda afuera. Es una muestra,
no un limitador de producción: ventana fija, contadores en memoria por
proceso (N réplicas permiten N veces la tasa) y, detrás de un proxy, todos
los clientes comparten la IP del proxy. En una aplicación real, usar un
limitador compartido (gateway, Redis o httprate con vmw.RateLimitJSON)
como hace examples/boilerplate.
Tres conjuntos de migraciones, tres tablas de versión
main.go llama a migrate.Up tres veces:
| Conjunto | Tabla de versión |
|---|---|
Las de esta app (migrations/) |
goose_db_version (default) |
audit/migrations |
vogel_db_version |
workflow/migrations |
workflow_db_version |
Los tres empiezan a numerar en 001. Con una sola tabla compartida, el segundo
en correr se vería como "ya aplicado" y se saltearía en silencio. Por eso
migrate.Options.TableName es un parámetro del llamador y no una constante
escondida en la librería.
Dos trampas que este ejemplo ya pisó por usted
Ninguna de las dos rompe el compilador. Las dos rompen el arranque o la primera request, y las dos cuestan una tarde si no las vio antes.
1. Migraciones embebidas en un subdirectorio necesitan fs.Sub.
//go:embed migrations/*.sql produce un fs.FS cuya raíz contiene un
directorio migrations, no los .sql. goose escanea sólo la raíz del fs.FS
que recibe, así que pasarlo directo falla con no migrations found aunque los
archivos estén indiscutiblemente adentro del binario. La solución es
fs.Sub(appMigrations, "migrations") — ver appMigrationsFS en main.go.
audit/migrations y workflow/migrations no lo necesitan porque embeben
*.sql desde su propio directorio de paquete.
2. El ID del caso no es el ID del documento.
Todos los métodos de workflow.Engine —Move, Claim, Release, History—
van por el ID del caso. Pero las rutas HTTP están indexadas por el objeto de
dominio (/documents/{id}), que es la forma normal: lo que el cliente tiene en
la mano es el ID del documento. El Engine no expone ninguna búsqueda por
referencia de dominio, así que hay que bajar al puerto workflow.Repository y
usar GetByExternalID(domain, externalID) para traducir uno en otro. Por eso el
handler tiene el engine y el repositorio — ver caseFor en handler.go.
Lo que este ejemplo deliberadamente NO hace
Saber qué se dejó afuera vale tanto como lo que está adentro.
- No usa un limitador real.
ratelimit.goes un contador mínimo por proceso (ver Rutas).httpx/middleware.RateLimitJSON()se apoya engithub.com/go-chi/httprate, que no es dependencia devogel. Agregarla sólo para el ejemplo le impondría una dependencia a todos los consumidores. En su app, si ya tienehttprate:r.Use(httprate.Limit(100, time.Minute, httprate.WithLimitHandler(vmw.RateLimitJSON()))) - No separa API y worker. Acá un mismo proceso atiende HTTP y ejecuta
jobs, porque un ejemplo de dos binarios se lee peor. En producción se separan:
el proceso de API construye la cola con
workers == nil(modo sólo-inserción) y un binario aparte le pasa los workers reales. Esa es exactamente la razón de queworker.NewRiverQueueaceptenilahí. - Sus tests cubren el cableado, no la librería. Prueban rutas, roles
(
rolematrix_test.go), límites de entrada y configuración del ejemplo. Los tests de cada paquete de vogel viven junto a su paquete. - No valida la configuración de producción.
RequireTLSestá enfalsepara que el compose local funcione. En producción va entrue, ypostgres.NewPoolfalla en el arranque si el DSN deshabilita TLS.
Siguiente paso
Copie examples/api/ a su repo, borre fakes.go, cambie las cuatro líneas de
main.go por los adaptadores reales, y reemplace Document por su primera
entidad. El resto del cableado ya está resuelto.
Documentation
¶
Overview ¶
Command api is a runnable example that boots a real HTTP API wiring EVERY vogel package together, so a reader learns the composition root by reading this one directory.
Postgres is real (see docker-compose.yaml). auth, authz, storage, and notification get tiny in-memory fakes -- see fakes.go -- implementing vogel's ports; that is the point of this example: swapping a fake for auth/zitadel, authz/cerbos, storage/s3, or notification/smtp is a one-line change in run(), step 7 below, because every consumer depends only on the port interface.