vogel

vogel

vogel es la base compartida en Go extraída de go-bluprint, el ancestro común de go-crucible y go-licencias. Contiene los paquetes que una auditoría de los tres repositorios estableció como comprobadamente compartibles: puertos/adaptadores puros y utilidades pequeñas sin lógica de negocio, pensados para ser consumidos por ambos sistemas en lugar de duplicados.

Los puertos (interfaces) viven en paquetes sin dependencias; los adaptadores viven en subpaquetes, de modo que importar un puerto nunca arrastra transitivamente el AWS SDK, SendGrid o go-mail.

Documentación

Este README es el inventario: qué contiene cada paquete y por qué. Los tres documentos de arriba cubren lo que el inventario no puede — cómo se usa todo junto.

Mapa de paquetes

Ejecutar las migraciones de la librería junto a las de la aplicación

audit/migrations incluye su propia 001_create_audit_log.sql, numerada de forma independiente de como estén numeradas las propias migraciones de la aplicación. Si ambos conjuntos registraran las versiones aplicadas en la tabla predeterminada de goose, goose_db_version, el 001 de la librería y el 001 de la aplicación colisionarían — el que corriera en segundo lugar se vería como "ya aplicado" y sería omitido silenciosamente, o fallaría directamente.

Ejecute los dos conjuntos contra la misma base de datos con dos llamadas separadas a migrate.Up, dándole al conjunto de la librería su propia tabla de versión mediante migrate.Options.TableName:

import (
	"github.com/kafeiih/vogel/audit/migrations"
	"github.com/kafeiih/vogel/migrate"
)

// Application migrations track in goose's default "goose_db_version" table.
if err := migrate.Up(ctx, dbURL, appMigrationsFS); err != nil {
	return err
}

// Library migrations track in their own table, independently versioned from
// the application's own 001, 002, ... — migrations.DefaultTableName is
// "vogel_db_version".
if err := migrate.Up(ctx, dbURL, migrations.FS(), migrate.Options{
	TableName: migrations.DefaultTableName,
}); err != nil {
	return err
}

Ambas llamadas adquieren el advisory lock de PostgreSQL a nivel de sesión de migrate de forma independiente (ver el punto 10 más abajo), de modo que ejecutarlas una tras otra en el arranque de la aplicación es seguro incluso con múltiples réplicas compitiendo por migrar al iniciar. migrate.Status y las demás funciones de migrate aceptan las mismas Options para consultar el estado del conjunto de la librería por separado del de la aplicación.

Correcciones aplicadas durante la extracción

Los paquetes de origen tenían veinte problemas conocidos; todos se corrigieron como parte de este port, en lugar de arrastrarse. El punto 21 no es un problema de origen sino una divergencia entre los dos consumidores que hubo que resolver al unificarlos, y el punto 24 es una capacidad agregada después del port inicial, no una corrección:

1. logger ya no importa chi. El pkg/logger original leía el ID de request directamente desde github.com/go-chi/chi/v5/middleware, acoplando un paquete de logging a un router HTTP. logger ahora posee su propia clave de contexto (WithRequestID / RequestIDFromContext); httpx/middleware.LoggerRequestID es el puente que lee el ID de request de chi y lo alimenta a esa clave. Logger.WithContext fue reescrito para usar esta clave en lugar de ser código muerto.

2. pgxtx.PgxTxManager.WithTx es seguro ante panics. Un panic dentro del callback ahora revierte la transacción (mediante un defer/recover) antes de volver a lanzar el panic, en lugar de dejar filtrada una transacción abierta hasta que el pool la desaloje. Cubierto por TestPgxTxManager_WithTx_PanicInCallback_RollsBackAndPropagates.

3. notification/smtp documenta su comportamiento real en lugar de contradecirlo. El ADR original afirmaba un "connection pool"; el código abría una conexión SMTP nueva en cada Send. Este port mantiene el dial-per-send (más simple, siempre correcto, sin preocupaciones de concurrencia por cliente compartido) y lo declara explícitamente en el comentario de documentación de SMTPNotifier, incluyendo una referencia a lo que necesitaría una implementación con pool si el volumen de envíos llegara a justificarlo.

4. httpx/middleware.Metrics ya no entra en panic ante un doble registro. El original llamaba a prometheus.MustRegister en init(), lo que entra en panic si se construye más de una vez. Ahora es NewMetrics(reg prometheus.Registerer) (*Metrics, error) (un reg nulo usa por defecto prometheus.DefaultRegisterer), que trata AlreadyRegisteredError como éxito reutilizando el colector existente. Cubierto por TestNewMetrics_DoubleConstruction_DoesNotPanic.

5. El límite de bytes de request.JSON estaba mal por 2. Los tres repositorios de origen escribían maxBytes := 1_048_578 // 1mb; el valor real de 1 MiB es 1_048_576, y el error tipográfico ya se había copiado a un segundo sitio de llamada en uno de los repositorios. Corregido a 1_048_576 (request.JSONWithLimit también permite que los llamadores sobrescriban el límite por endpoint). Cubierto por TestJSON_DefaultLimitIsExactly1MiB.

6. config ganó validación semántica, no solo chequeos de presencia. El config.Load() de origen solo verificaba "¿esta variable de entorno no está vacía?" — un error tipográfico en NOTIFICATION_PROVIDER (por ejemplo, sendgrdi) caía silenciosamente al valor por defecto de SMTP y deshabilitaba el envío de correo, sin nada más que un log Warn para advertirlo. config agrega ValidURL, IntRange, OneOf y MinMax, más un acumulador Errors para que una falla de arranque reporte todas las variables faltantes/inválidas de una sola vez en lugar de una por reinicio.

7. postgres.NewPool falla rápido cuando no se puede honrar RequireTLS. El applyTLSConfig de origen solo elevaba la versión mínima de TLS si el DSN ya tenía TLS habilitado; un DSN con sslmode=disable producía silenciosamente una conexión en texto plano mientras el llamador creía que RequireTLS había surtido efecto — el código de origen incluso documentaba el hueco sin cerrarlo. Ahora, en cambio, devuelve un error de arranque que nombra la configuración culpable. Cubierto por TestApplyTLSConfig_RequireTLSTrueWithDisabledDSN_FailsFast y una prueba de integración que demuestra que el camino positivo sigue preservando ServerName (ver postgres_test.go).

8. postgres agrega los tres timeouts del lado del servidor que ninguno de los tres repositorios configuraba: statement_timeout, lock_timeout e idle_in_transaction_session_timeout, aplicados mediante el hook AfterConnect de pgxpool con valores por defecto configurables y razonables. idle_in_transaction_session_timeout es el más importante: es el único backstop del lado del servidor contra un handler que se cuelga mientras mantiene abierta una transacción y sus locks — statement_timeout no ayuda ahí porque no hay ningún statement en ejecución. Verificado contra un contenedor real en TestNewPool_AppliesServerSideTimeouts.

9. postgres.PoolMetricsCollector ya no entra en panic ante un doble registro — la misma clase de bug y la misma forma de corrección que httpx/middleware.Metrics (punto 4): NewPoolMetricsCollector(pool, reg) ahora devuelve (*PoolMetricsCollector, error) y reutiliza un colector ya registrado en lugar de llamar a MustRegister. Cubierto por TestNewPoolMetricsCollector_DoubleConstruction_DoesNotPanic.

10. migrate ahora usa locks. Ninguno de los runners de migración de los tres repositorios tomaba ningún lock, así que dos invocaciones concurrentes de migrate up (dos jobs de CI, dos init containers, una corrida manual solapada con un pipeline) podían intercalar DDL contra la misma base de datos. migrate ahora construye su goose.Provider con goose.WithSessionLocker (un advisory lock de PostgreSQL a nivel de sesión), serializando las corridas concurrentes en lugar de dejarlas competir. Verificado contra un contenedor real con 5 llamadas concurrentes a migrate.Up en TestUp_ConcurrentInvocations_SerializeInsteadOfRacing. Una migración que necesite CREATE INDEX CONCURRENTLY igual debe usar la anotación de goose -- +goose NO TRANSACTION, dado que PostgreSQL rechaza ese statement dentro de una transacción — ver el comentario de documentación en migrate/runner.go.

11. auth/authz eliminan por completo la multi-tenencia basada en org_id — nunca funcionó. Ambos sistemas de origen reflejaban un UserContext.OrgID en cada recurso de Cerbos para que los roles derivados pudieran comparar principal.attr.org_id == resource.attr.org_id, pero ResourceForUser copiaba ese org_id directamente del mismo principal, así que la comparación siempre era X == X — siempre verdadera. Incluso con ese bug corregido, la instancia de Zitadel del propietario tiene exactamente una organización ("intranet"), con la separación por sistema hecha en cambio a nivel de proyecto/aplicación, de modo que urn:zitadel:iam:user:resourceowner:id devuelve el mismo valor para cada usuario en cada sistema: nunca hubo un segundo valor contra el cual comparar. org_id tampoco aparece en ninguna consulta de repositorio ni en ninguna migración de ninguno de los dos sistemas. Principal.OrgID, extractOrgID, y el reflejo de org_id en ResourceForUser/principalAttr desaparecieron, junto con la rama de "tratar como no autenticado si falta org_id" que fallaba ruidosamente y que existía solo para proteger ese mecanismo muerto. La separación real entre sistemas es la validación de audience de OIDC, que el SDK de Zitadel ya realiza.

12. auth/zitadel prefiere preferred_username por sobre el campo legado Username. go-crucible leía authCtx.Username directamente, que queda vacío para tokens provenientes de un flujo conforme al estándar; go-licencias ya llevaba esta corrección. Portada aquí para que el único adaptador de este módulo lo haga bien.

13. Una caída del PDP/IdP ahora se mapea a HTTP 503, nunca a 401/403/500. go-crucible devolvía 500 cuando el chequeo de Cerbos fallaba; go-licencias devolvía deliberadamente 403 (su DEC-08, "para evitar un oráculo"); la base colapsaba también el ServiceUnavailableErr de Zitadel en 403. Los tres dejan al monitoreo ciego a la diferencia entre "el cliente hizo algo mal" y "nuestra infraestructura está caída", y ninguno de 401/403/500 es reintentable de forma significativa como sí lo es 503. Tanto httpx/middleware.Authenticate (proveedor de identidad) como httpx/middleware.RequirePermission (punto de decisión de política) ahora mapean un error del lado del proveedor a 503, una denegación genuina a 403, y credenciales faltantes/inválidas a 401 — ver los comentarios de documentación de ambos para el razonamiento completo. Esto reemplaza deliberadamente el DEC-08 de go-licencias.

14. Los mensajes de auth/authz orientados al usuario ya no están fijados en español dentro del código. Los orígenes devolvían literales como "No tenés permisos para realizar esta acción" incrustados en una librería — algo que un paquete compartido no debería poseer en un único idioma. httpx/middleware.AuthMessages (con DefaultAuthMessages para valores por defecto neutrales en inglés y WithAuthMessages para sobrescribirlos) hace configurable el texto de 401/403/503; cada sistema consumidor establece su propio texto localizado.

15. ZitadelAuthWithRole, IsGrantedRole y PrincipalFromUser no fueron portados. Los tres estaban exportados en cada repositorio de origen sin ningún sitio de llamada fuera de los tests. El comportamiento de wildcardResourceID = "*" de RequirePermission sí se mantuvo — es estructural, no cosmético: Cerbos rechaza cualquier recurso con un ID vacío antes de evaluar una política, lo cual de otro modo se manifiesta como un 500 en cada ruta a nivel de colección (list/create).

16. audit_log.request_id finalmente se asigna. En los tres repositorios de origen, request_id estaba declarado en el DTO, mapeado desde la entidad y persistido por el repositorio — y nunca se asignaba en ningún lado. Cada fila de auditoría en producción tiene request_id = NULL, lo cual hace imposible vincular una entrada de auditoría con las líneas de log de su request, determinar que varias filas escritas por una operación fueron una sola acción, o seguir un cambio hasta el background job que generó. audit.Recorder.Record ahora lee el ID de request desde reqctx en el mismo paso incondicional en el que lee al principal actuante — no detrás de una opción que se pueda omitir por separado — de modo que un futuro sitio de llamada no pueda completar el actor mientras "olvida" el ID de request, como siempre hizo hasta ahora cada sitio de llamada. Cubierto por TestRecord_RequestIDInContext_IsPersistedOnEntry y TestRecord_NoRequestIDInContext_LeavesRequestIDNilWithoutError en audit/recorder_test.go, y verificado de punta a punta contra una base de datos real en audit/postgres/repository_integration_test.go.

17. audit ya no importa la capa de transporte HTTP. El application/audit/recorder.go de origen llamaba a middleware.UserFromContext/middleware.RequestInfoFromContext — un puerto de la capa de aplicación importando interfaces/http/middleware, la dirección equivocada, y la razón por la que este paquete no pudo publicarse en la tanda 3. audit.Recorder ahora lee al actor vía vogel/auth.FromContext y los metadatos de la request vía vogel/reqctx, ambos paquetes con pocas dependencias orientados a la aplicación. go list -deps ./audit no arrastra chi, ni httpx, ni net/http.

    El último de esos puntos requirió un segundo paso. Authenticator originalmente recibía un *http.Request, y como Go resuelve dependencias por paquete y no por archivo, todo consumidor que importaba auth solo para leer un Principal heredaba net/http — audit entre ellos. Angostar el puerto a un token desnudo la eliminó desde la fuente.

18. Los metadatos con alcance de request tienen un único dueño: reqctx. logger solía poseer su propia clave de contexto para el ID de request; httpx/middleware.RequestInfoMiddleware poseía por separado una clave no exportada para IP/User-Agent, con una vía de escape exportada RequestInfoContextKey() solo para que los tests pudieran inyectar valores. Ambos son ahora reqctx.WithRequestID/RequestIDFromContext y reqctx.WithRequestInfo/RequestInfoFromContext. logger.Logger.WithContext lee el ID de request desde reqctx en lugar de una clave que posee él mismo, de modo que el ID que llega a una línea de log y el que llega a una fila de audit_log son demostrablemente el mismo valor. httpx/middleware.RequestContext reemplaza al viejo par LoggerRequestID + RequestInfoMiddleware con un único middleware que escribe los tres valores en reqctx; el propio middleware.RequestID de chi sigue siendo la fuente del ID upstream. El RequestInfoContextKey() exportado desapareció — los tests usan reqctx.WithRequestInfo directamente.

19. Las migraciones propiedad de la librería obtienen su propia tabla de versión de goose. audit/migrations comienza su propia numeración en 001, exactamente igual que las propias migraciones de cada aplicación consumidora, de modo que una tabla goose_db_version compartida vería a los dos 001 como la misma versión. migrate.Options ganó TableName (una opción provista por el llamador, no una constante fijada dentro de migrate, dado que ese paquete no posee migraciones propias y no tiene opinión sobre el esquema de nombres de ningún consumidor en particular), de modo que las migraciones de la librería se registran en su propia tabla. El nombre lo elige cada conjunto, no la librería: audit usa vogel_db_version (audit/migrations.DefaultTableName) por ser el primero que existió, y workflow usa workflow_db_version. Cada conjunto de migraciones de vogel numera desde 001, así que dos conjuntos que compartan tabla colisionan igual que la librería y la aplicación: un tercer conjunto necesita su propio nombre, no reusar el de audit. Verificado contra una base de datos real, con ambos conjuntos reutilizando la versión 1 y aplicándose ambos por completo, en TestUp_IndependentTableNames_DoNotCollide (migrate/runner_integration_test.go).

20. Las entradas de auditoría de un background job declaran su origen explícitamente. El Recorder.Record de cada repositorio de origen fijaba Source en "http" por defecto dentro del struct literal, así que un worker o job programado que lo llamara — ninguno lo hizo jamás, precisamente porque no había ningún valor correcto al cual recurrir por defecto — habría producido una fila con forma de HTTP para un trabajo que nunca tocó una request. Recorder.Record ahora recibe Source (SourceHTTP o SourceWorker) como argumento posicional obligatorio, no como una Option, de modo que cada sitio de llamada declara su origen en lugar de heredar uno. Una entrada SourceWorker legítimamente no tiene ID de request a menos que su contexto haya sido a su vez derivado de la request que generó el job — ver TestRecord_SourceHTTP_And_SourceWorker y TestRecord_WorkerOrigin_RequestIDStillPropagatedWhenPresent.

21. Los trabajos periódicos del worker pasaron de parámetro posicional a opción funcional. Los dos consumidores tenían la misma cola sobre River, con una única diferencia de firma: go-crucible había extendido NewRiverQueue(pool, workers, periodicJobs []*river.PeriodicJob, cfg, logger) para su sweep nocturno, mientras go-licencias seguía con NewRiverQueue(pool, workers, cfg, logger). Portar cualquiera de las dos tal cual rompía al otro consumidor. La firma unificada deja los parámetros obligatorios como estaban y mueve los trabajos periódicos a WithPeriodicJobs, de modo que go-licencias no cambia ninguna llamada y go-crucible sólo agrega la opción. TestBuildRiverConfig_WorkerMode_NoPeriodicJobsOption_MatchesLicenciasShape fija esa equivalencia: si algún día omitir la opción dejara de significar «sin trabajos periódicos», el test falla. Los trabajos periódicos siguen registrándose únicamente en modo binario worker — un cliente de sólo inserción no procesa nada, así que pasarlos junto a un *river.Workers nulo no los registra.

22. La capa de consulta de audit dejó de duplicarse a mano, y eso cerró un agujero. El DTO, su mapeo y el parseo de filtros eran el mismo código en los dos consumidores — mismos campos, mismos json tags, misma paginación — salvo en un punto: go-licencias filtra por resource_id (*uuid.UUID) y go-crucible directamente no tiene ese campo en su Filters. No es una diferencia de diseño: es lo que pasa cuando dos copias del mismo código evolucionan por separado. audit/httpx lo unifica con el filtro incluido. Queries no se portó: era repo.GetByID seguido de toResponse, y vogel ya expone Repository. Los mensajes visibles al usuario, que en el origen estaban incrustados en español dentro de la librería, salieron a Messages/WithMessages por la misma razón que el punto 14. Y las listas de valores aceptados para operation_category y status se derivan de audit.Actions()/audit.Statuses() en vez de repetirse como literales, con un test que falla si se agrega una Action sin decidir si además es filtrable.

23. StructuredLogger leía el request ID de chi, no de reqctx. El punto 18 movió la propiedad de los metadatos de request a reqctx y el doc comment de RequestContext promete que una línea de log y una fila de audit_log de la misma request quedan enlazadas de forma demostrable, porque ambas leen la misma clave. La línea de acceso de httpx/middleware.StructuredLogger quedó afuera de ese movimiento: seguía llamando a chimw.GetReqID. Coincidía con lo que veían logger y audit sólo porque hoy los tres valores derivan del mismo ID upstream de chi — un request ID que llegara al contexto por otra vía (un worker que lo deriva de la request que lo generó, un test que lo inyecta) terminaba en la fila de auditoría mientras el log de acceso imprimía vacío. Ahora las tres lecturas van a reqctx, y el enlace es una propiedad del diseño en vez de una coincidencia. El paquete no tenía ni un test; los dos que ahora existen (TestStructuredLogger_ReadsRequestIDFromReqctx, TestStructuredLogger_NoRequestID_LogsEmpty) son la razón por la que esto apareció.

24. access y RequireAccess son una capacidad nueva, no una corrección heredada de los repositorios de origen — igual que el punto 21. Ninguno de los tres tenía un chequeo por instancia: RequirePermission (y su equivalente en cada sistema de origen) sólo podía comparar el principal contra el resourceKind y, a lo sumo, un ID sacado de la URL, porque corre antes de que el handler cargue nada. Un chequeo que dependa de un dato de la entidad misma — su dueño, su estado, si ya fue enviada — no era posible ahí, y la alternativa de que el propio middleware cargara la entidad habría significado leer la misma fila dos veces en cada ruta protegida (una para el chequeo, otra para el trabajo real del handler). access.Guard.Check, llamado desde el handler después de su propia carga, resuelve eso sin que authz deje de ser dependency-free ni que httpx/middleware tenga que adivinar qué cargar. RequirePermission ahora es un envoltorio delgado sobre access.New + RequireAccess, así que el mapeo de estados vive una sola vez. AuthOption — el tipo función que ya usaban Authenticate y RequirePermission — se dejó exactamente igual a propósito: convertirlo en un struct de configuración habría roto cualquier AuthOption escrito a mano como función literal en código consumidor ya existente, a cambio de nada que RequireAccess necesitara.

WithAffectedResources es la forma prevista de auditar una operación masiva/por lotes (bulk/batch): una única entrada sobre el recurso primario que nombra cada fila que tocó, en lugar de iterar y llamar a Record una vez por cada fila afectada dentro de la misma transacción (como hace hoy derecho_cobrar/commands.go de go-licencias) — esto último multiplica los INSERTs y extiende el tiempo de retención de los locks en proporción al tamaño del lote sin ningún beneficio, dado que AffectedResources es en sí misma una columna JSON consultable. Ver el comentario de documentación de WithAffectedResources y TestWithAffectedResources_SetsListOnSingleEntry.

Todavía no está acá

Esta es una cuarta tanda. Excluidos deliberadamente, decisiones pendientes:

• El prefijo de URL /v1 / router.go — bloqueado por decisiones de convergencia entre los dos sistemas sobre convenciones de ruteo.
• cmd/, migraciones (los archivos SQL en sí, más allá de las propias de audit), Dockerfile, docker-compose, swagger — fuera del alcance de una tanda de librería compartida; son asuntos propios de cada aplicación, no puertos/adaptadores compartibles. migrate/create.go (un scaffolder de archivos de migración) se dejó afuera de igual manera, por ser un asunto de CLI/plantilla y no de API de librería. Los jobs concretos de cada dominio (application/jobs/*) tampoco se portan: el andamiaje es compartible, el negocio que corre adentro no.
• Las anotaciones de Swagger y el registro de rutas de audit — lo único que quedó afuera de audit/httpx (ver el punto 22). Las anotaciones de swaggo se leen de los comentarios sobre las funciones handler de cada aplicación, así que una app que quiera documentar estos endpoints escribe su propio handler con las piezas exportadas en lugar de montar el Handler de vogel; las rutas y su prefijo siguen siendo decisión de cada app.
• null_helpers.go (nullInt/nullInt64) — dejado atrás deliberadamente. Devuelve nil cuando n == 0, confundiendo "sin establecer" con un cero legítimo. Además no se usaba en ninguno de los tres repositorios de origen.