api

command
v0.23.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 55 Imported by: 0

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 en examples/api, no desde la raíz del repo: el archivo se busca como .env relativo 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 .env diga 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:

  1. La fila del documento (store.Create)
  2. El caso de workflow (engine.Open)
  3. La entrada de auditoría (recorder.Record)
  4. 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:

  1. POST /documents/{id}/upload-url con {"content_type":"application/pdf","size":1234}. Un tipo fuera de allowedUploadTypes responde 415; un size menor que 1 o mayor que maxUploadBytes (25 MiB), 400. La respuesta trae url, key (documents/{id}/uploads/{uuid}, una por subida), method (PUT), headers y expires_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 el Content-Type y el Content-Length exactos: el bucket rechaza otro tipo o un cuerpo de otro tamaño. No se persiste nada todavía.

  2. El cliente hace el PUT a esa url con esos headers y el archivo.

  3. POST /documents/{id}/file con {"key":"..."} confirma la subida. La key tiene que ser una emitida para ese documento (si no, 400). En una sola transacción el documento queda con file_status: "pending", se encola validate_upload con EnqueueTx y se audita document_attach_file. Responde 202. Se valida una subida por vez: mientras la anterior siga pending, otra confirmación responde 409 ("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.

  4. validate_upload (ValidateUploadWorker en jobs.go) descarga el objeto y detecta el tipo por el contenido con storage.SniffContentType, leyendo sólo los primeros bytes. Si el objeto no existe, el archivo queda rejected; si el contenido no es un tipo permitido, borra el objeto y lo marca rejected; si es válido, copia esos mismos bytes a una key final, documents/{id}/file/{uuid}, deja el documento ready apuntando ahí con el tipo detectado y borra el objeto de subida. Cada veredicto se escribe sólo si el documento sigue apuntando a esa key: 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 archivo pending, 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 archivo ready, 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 job delete_object con su key, que River reintenta hasta borrarlo. Uno rechazado (inexistente o no permitido) lo restaura: el documento vuelve a ready con su archivo y su tipo, y la auditoría lo registra como document_restore_file, no como una aceptación. Así, repetir una confirmación con una key ya 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 documento pending para siempre: lo resuelve como un rechazo (restaura el archivo anterior o lo marca rejected), borra el objeto de subida si puede y lo deja en el log con document_id y key.

    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 PUT bajo file/, y la confirmación sólo acepta keys de uploads/, así que el archivo que se sirve es siempre el que el job inspeccionó.

  5. GET /documents/{id}/download-url firma un GET de 5 minutos sobre la key final que el bucket sirve como attachment y 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 archivo ready ni anterior, responde 409.

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.go es un contador mínimo por proceso (ver Rutas). httpx/middleware.RateLimitJSON() se apoya en github.com/go-chi/httprate, que no es dependencia de vogel. Agregarla sólo para el ejemplo le impondría una dependencia a todos los consumidores. En su app, si ya tiene httprate:
    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 que worker.NewRiverQueue acepte nil ahí.
  • 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. RequireTLS está en false para que el compose local funcione. En producción va en true, y postgres.NewPool falla 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL