DEV Community: Gophers CL

SaaS Multi-Tenant en Go: Guia Practica de Row-Level Security en PostgreSQL

Roberto Araneda Espinoza — Sun, 08 Mar 2026 16:28:30 +0000

Estas construyendo una aplicacion SaaS. Multiples clientes comparten la misma base de datos. El Cliente A nunca debe ver datos del Cliente B. Un solo WHERE tenant_id = ? faltante y tienes una brecha de datos.

Este articulo muestra como implementar PostgreSQL Row-Level Security (RLS) en Go para que la base de datos misma aplique el aislamiento de tenant — de forma transparente, automatica, y sin depender de que los desarrolladores recuerden un filtro en cada query.

Por que RLS?

Hay cuatro enfoques comunes para multi-tenancy:

Enfoque	Como funciona	Riesgo
`WHERE` a nivel de app	Agregar `WHERE tenant_id = ?` a cada query	Uno faltante = brecha
Schema-per-tenant	Schema separado por cliente	Infierno de migraciones
Database-per-tenant	DB separada por cliente	Pesadilla de connection pooling
Row-Level Security	PostgreSQL aplica visibilidad por transaccion	Requiere disciplina transaccional

RLS gana porque la frontera de seguridad se mueve del codigo de aplicacion (donde los humanos cometen errores) al motor de base de datos (que aplica policies mecanicamente en cada query).

Arquitectura

El tenant ID fluye a traves de tres capas:

HTTP Request ──▶ Middleware ──▶ Go Context ──▶ PostgreSQL TX
(JWT/Header)     (Extraer)     (Propagar)     (SET LOCAL)
                                                   │
                                              RLS Policy
                                              (Enforce)

Cada operacion de base de datos corre dentro de una transaccion donde SET LOCAL setea el tenant actual. Las RLS policies luego filtran filas automaticamente. Tu codigo de aplicacion nunca escribe WHERE tenant_id = ?.

Paso 1: El Package de Contexto de Tenant

Un package pequeno que gestiona la identidad del tenant a traves de context.Context:

package tenant

import (
    "context"
    "errors"
    "regexp"
)

type contextKey string

const tenantIDKey contextKey = "tenant_id"

var (
    ErrNoTenant      = errors.New("no tenant ID in context")
    ErrInvalidTenant = errors.New("invalid tenant ID format")
)

var tenantIDRegex = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$`)

func ValidateTenantID(id string) error {
    if id == "" {
        return ErrNoTenant
    }
    if !tenantIDRegex.MatchString(id) {
        return ErrInvalidTenant
    }
    return nil
}

func WithTenantID(ctx context.Context, id string) (context.Context, error) {
    if err := ValidateTenantID(id); err != nil {
        return ctx, err
    }
    return context.WithValue(ctx, tenantIDKey, id), nil
}

func GetTenantID(ctx context.Context) string {
    if v, ok := ctx.Value(tenantIDKey).(string); ok {
        return v
    }
    return ""
}

Tres decisiones de diseno importan aca:

Context key no exportado — El tipo contextKey es privado. Ningun otro package puede leer o sobrescribir el tenant ID.
Validacion con regex — El patron ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$ valida formato y previene SQL injection. Defensa en profundidad.
String vacio = single-tenant — Sin tenant en el contexto, el sistema opera sin overhead. Mismo codebase para single-tenant y multi-tenant.

Paso 2: HTTP Middleware

Extraer el tenant de dos fuentes: JWT tokens y HTTP headers, con validacion cruzada.

import (
    "errors"
    "net/http"
    "strings"
)

var ErrTenantMismatch = errors.New("tenant ID mismatch between header and JWT")

type MiddlewareConfig struct {
    ValidateToken      func(token string) (tenantID string, err error)
    HeaderName         string // ej: "X-Tenant-ID"
    AllowAnonymous     bool
    DefaultTenant      string
    RequireTenantInJWT bool   // previene spoofing por header
}

func Middleware(cfg MiddlewareConfig) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            var headerTenant, jwtTenant string

            // Fuente 1: Header HTTP
            if cfg.HeaderName != "" {
                headerTenant = r.Header.Get(cfg.HeaderName)
            }

            // Fuente 2: JWT Bearer token
            if cfg.ValidateToken != nil {
                if auth := r.Header.Get("Authorization"); strings.HasPrefix(auth, "Bearer ") {
                    var err error
                    jwtTenant, err = cfg.ValidateToken(strings.TrimPrefix(auth, "Bearer "))
                    if err != nil {
                        http.Error(w, "invalid token", http.StatusUnauthorized)
                        return
                    }
                }
            }

            // Cross-check: si ambas fuentes proveen tenant, deben coincidir
            if headerTenant != "" && jwtTenant != "" && headerTenant != jwtTenant {
                http.Error(w, ErrTenantMismatch.Error(), http.StatusForbidden)
                return
            }

            // JWT tiene prioridad (verificado criptograficamente)
            tenantID := jwtTenant
            if tenantID == "" {
                tenantID = headerTenant
            }

            // Anti-spoofing
            if cfg.RequireTenantInJWT && jwtTenant == "" && headerTenant != "" {
                http.Error(w, "tenant must be in JWT", http.StatusUnauthorized)
                return
            }

            // Fallback
            if tenantID == "" {
                if cfg.DefaultTenant != "" {
                    tenantID = cfg.DefaultTenant
                } else if !cfg.AllowAnonymous {
                    http.Error(w, "tenant required", http.StatusUnauthorized)
                    return
                }
            }

            ctx := r.Context()
            if tenantID != "" {
                var err error
                ctx, err = WithTenantID(ctx, tenantID)
                if err != nil {
                    http.Error(w, err.Error(), http.StatusBadRequest)
                    return
                }
            }

            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

Sin la validacion cruzada, un atacante podria enviar un JWT valido para Tenant A pero setear el header X-Tenant-ID a Tenant B. RequireTenantInJWT fuerza que el tenant venga del JWT, no de un header falsificable.

Paso 3: Schema de Base de Datos

Cada tabla incluye tenant_id como parte de su primary key:

CREATE TABLE orders (
    tenant_id   VARCHAR(64)   NOT NULL,
    id          BIGSERIAL     NOT NULL,
    customer_id BIGINT        NOT NULL,
    total       NUMERIC(12,2) NOT NULL,
    status      VARCHAR(32)   NOT NULL DEFAULT 'pending',
    created_at  TIMESTAMPTZ   NOT NULL DEFAULT NOW(),

    PRIMARY KEY (tenant_id, id)
);

Por que en el PK?

La Orden #1001 en Tenant A y la Orden #1001 en Tenant B son registros diferentes
El B-tree primario sobre (tenant_id, id) soporta queries filtrados por tenant naturalmente
Keys compuestos funcionan con tenants dinamicos — sin overhead de particionamiento

Diseno de indices

Siempre tenant_id como columna lider:

-- CORRECTO: index range scan por tenant
CREATE INDEX orders_tenant_status_idx
    ON orders (tenant_id, status, created_at DESC);

-- INCORRECTO: escanea todos los tenants, luego filtra
CREATE INDEX orders_status_tenant_idx
    ON orders (status, created_at DESC, tenant_id);

Paso 4: RLS Policies

Habilitar RLS y crear una policy vinculada a una variable de sesion de PostgreSQL:

ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
ALTER TABLE orders FORCE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON orders
    USING (tenant_id = current_setting('app.current_tenant', true))
    WITH CHECK (tenant_id = current_setting('app.current_tenant', true));

Como funciona:

USING — SELECT, UPDATE, DELETE solo ven filas donde tenant_id coincide con la variable de sesion
WITH CHECK — INSERT y UPDATE son rechazados si tenant_id no coincide
current_setting(..., true) — retorna NULL cuando no esta seteada. Como NULL = algo es siempre false en SQL → cero filas visibles por defecto (fail-closed)
FORCE — aplica RLS incluso al table owner (sin esto, el usuario de la app bypasea RLS)

Automatizando en Go

func enableRLS(ctx context.Context, db *sql.DB, tables []string) error {
    for _, table := range tables {
        stmts := []string{
            fmt.Sprintf(`ALTER TABLE %s ENABLE ROW LEVEL SECURITY`, table),
            fmt.Sprintf(`ALTER TABLE %s FORCE ROW LEVEL SECURITY`, table),
        }
        for _, s := range stmts {
            if _, err := db.ExecContext(ctx, s); err != nil {
                return fmt.Errorf("enabling RLS on %s: %w", table, err)
            }
        }

        policy := fmt.Sprintf(`
            CREATE POLICY tenant_isolation_%s ON %s
                USING (tenant_id = current_setting('app.current_tenant', true))
                WITH CHECK (tenant_id = current_setting('app.current_tenant', true))
        `, table, table)

        if _, err := db.ExecContext(ctx, policy); err != nil {
            drop := fmt.Sprintf(
                `DROP POLICY IF EXISTS tenant_isolation_%s ON %s`, table, table,
            )
            db.ExecContext(ctx, drop)
            if _, err := db.ExecContext(ctx, policy); err != nil {
                return fmt.Errorf("creating policy on %s: %w", table, err)
            }
        }
    }
    return nil
}

Paso 5: El Patron tenantQuerier — SET LOCAL

Este es el nucleo de todo. Cada operacion de base de datos activa el contexto de tenant via SET LOCAL dentro de una transaccion.

type dbQuerier interface {
    ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
    QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
    QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

func tenantQuerier(ctx context.Context, db *sql.DB) (dbQuerier, func(), error) {
    tenantID := tenant.GetTenantID(ctx)
    if tenantID == "" {
        return db, func() {}, nil // single-tenant: cero overhead
    }

    tx, err := db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})
    if err != nil {
        return nil, nil, fmt.Errorf("begin tenant tx: %w", err)
    }

    if _, err := tx.ExecContext(ctx,
        "SET LOCAL app.current_tenant = $1", tenantID,
    ); err != nil {
        tx.Rollback()
        return nil, nil, fmt.Errorf("set tenant: %w", err)
    }

    return tx, func() { tx.Commit() }, nil
}

Por que `SET LOCAL` y no `SET`?

La decision mas importante de toda la implementacion.

┌──────────────────────────────────────────────────────┐
│            Connection Pool (database/sql)            │
│                                                      │
│  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐      │
│  │ Conn 1 │  │ Conn 2 │  │ Conn 3 │  │ Conn 4 │      │
│  └────────┘  └────────┘  └────────┘  └────────┘      │
│      ▲           ▲           ▲           ▲           │
│  Goroutine A Goroutine B Goroutine C Goroutine D     │
│  (Tenant X)  (Tenant Y)  (Tenant X)  (Tenant Z)      │
└──────────────────────────────────────────────────────┘

database/sql reutiliza conexiones entre goroutines. Si usas SET (scope de sesion), la variable persiste en la conexion. La siguiente goroutine hereda el tenant equivocado.

Comando	Scope	Seguridad en Pool
`SET app.current_tenant = 'X'`	Session	INSEGURO — se filtra al siguiente request
`SET LOCAL app.current_tenant = 'X'`	Transaction	SEGURO — no hay leaks posibles

SET LOCAL se limpia automaticamente en commit/rollback. Sin cleanup manual, sin race conditions.

Por que transacciones read-only?

&sql.TxOptions{ReadOnly: true} provee:

No puede modificar datos accidentalmente
PostgreSQL optimiza read-only (menor overhead de MVCC)
La transaccion existe solo para llevar SET LOCAL, no para agrupar escrituras

Paso 6: Usando el Patron

Lectura

func GetOrder(ctx context.Context, db *sql.DB, orderID int64) (*Order, error) {
    q, done, err := tenantQuerier(ctx, db)
    if err != nil {
        return nil, err
    }
    defer done()

    // Sin WHERE tenant_id — RLS lo maneja
    var o Order
    err = q.QueryRowContext(ctx,
        `SELECT id, customer_id, total, status, created_at
         FROM orders WHERE id = $1`,
        orderID,
    ).Scan(&o.ID, &o.CustomerID, &o.Total, &o.Status, &o.CreatedAt)

    if errors.Is(err, sql.ErrNoRows) {
        return nil, ErrNotFound
    }
    return &o, err
}

Si Tenant A pide la Orden #1001 pero pertenece a Tenant B → RLS retorna cero filas → 404. Indistinguible de una orden inexistente.

Escritura

Las escrituras ya usan transacciones. Setear tenant una vez al inicio:

func CreateOrder(ctx context.Context, db *sql.DB, order *Order, items []OrderItem) error {
    tenantID := tenant.GetTenantID(ctx)

    tx, err := db.BeginTx(ctx, nil)
    if err != nil {
        return err
    }
    defer tx.Rollback()

    if tenantID != "" {
        if _, err := tx.ExecContext(ctx,
            "SET LOCAL app.current_tenant = $1", tenantID,
        ); err != nil {
            return fmt.Errorf("set tenant: %w", err)
        }
    }

    var orderID int64
    err = tx.QueryRowContext(ctx,
        `INSERT INTO orders (tenant_id, customer_id, total, status)
         VALUES ($1, $2, $3, $4) RETURNING id`,
        tenantID, order.CustomerID, order.Total, order.Status,
    ).Scan(&orderID)
    if err != nil {
        return err
    }

    for _, item := range items {
        _, err := tx.ExecContext(ctx,
            `INSERT INTO order_items (tenant_id, order_id, product_id, quantity, price)
             VALUES ($1, $2, $3, $4, $5)`,
            tenantID, orderID, item.ProductID, item.Quantity, item.Price,
        )
        if err != nil {
            return err
        }
    }

    return tx.Commit()
}

Listado

func ListOrders(ctx context.Context, db *sql.DB, status string, limit int) ([]Order, error) {
    q, done, err := tenantQuerier(ctx, db)
    if err != nil {
        return nil, err
    }
    defer done()

    rows, err := q.QueryContext(ctx,
        `SELECT id, customer_id, total, status, created_at
         FROM orders WHERE status = $1
         ORDER BY created_at DESC LIMIT $2`,
        status, limit,
    )
    if err != nil {
        return nil, err
    }
    defer rows.Close()

    var orders []Order
    for rows.Next() {
        var o Order
        if err := rows.Scan(&o.ID, &o.CustomerID, &o.Total, &o.Status, &o.CreatedAt); err != nil {
            return nil, err
        }
        orders = append(orders, o)
    }
    return orders, rows.Err()
}

Sin filtro de tenant en el SQL. RLS se encarga.

Paso 7: Patron Repository (Produccion)

Encapsular el patron para codigo de produccion:

type OrderRepo struct {
    db              *sql.DB
    multiTenantMode bool
}

func NewOrderRepo(db *sql.DB, multiTenant bool) *OrderRepo {
    return &OrderRepo{db: db, multiTenantMode: multiTenant}
}

func (r *OrderRepo) querier(ctx context.Context) (dbQuerier, func(), error) {
    if !r.multiTenantMode {
        return r.db, func() {}, nil
    }
    return tenantQuerier(ctx, r.db)
}

func (r *OrderRepo) beginTx(ctx context.Context) (*sql.Tx, error) {
    tx, err := r.db.BeginTx(ctx, nil)
    if err != nil {
        return nil, err
    }

    if r.multiTenantMode {
        tenantID := tenant.GetTenantID(ctx)
        if tenantID != "" {
            if _, err := tx.ExecContext(ctx,
                "SET LOCAL app.current_tenant = $1", tenantID,
            ); err != nil {
                tx.Rollback()
                return nil, fmt.Errorf("set tenant: %w", err)
            }
        }
    }

    return tx, nil
}

func (r *OrderRepo) GetByID(ctx context.Context, id int64) (*Order, error) {
    q, done, err := r.querier(ctx)
    if err != nil {
        return nil, err
    }
    defer done()

    var o Order
    err = q.QueryRowContext(ctx,
        `SELECT id, customer_id, total, status FROM orders WHERE id = $1`, id,
    ).Scan(&o.ID, &o.CustomerID, &o.Total, &o.Status)

    if errors.Is(err, sql.ErrNoRows) {
        return nil, ErrNotFound
    }
    return &o, err
}

El flag multiTenantMode da cero overhead cuando multi-tenancy esta deshabilitado — querier() retorna *sql.DB directo.

Analisis de Seguridad

Modelo de amenazas

Amenaza	Mitigacion
`WHERE tenant_id` faltante	RLS enforced a nivel de DB
Spoofing via header	`RequireTenantInJWT` fuerza JWT
Mismatch header/JWT	Validacion cruzada rechaza
SQL injection en tenant	Regex + `SET LOCAL $1` parametrizado
Leak de variable en pool	`SET LOCAL` auto-limpiado
Superuser bypasea RLS	`FORCE ROW LEVEL SECURITY`
Tenant no seteado	`current_setting` → NULL → cero filas

Garantia fail-closed

Cada falla → cero acceso a datos, nunca acceso cross-tenant:

Variable no seteada → NULL → ninguna fila visible
JWT invalido → middleware rechaza antes de la DB
Header/JWT no coinciden → 403

No existe code path donde una misconfiguracion exponga datos cross-tenant.

Rendimiento

Modo	Lectura	Escritura
Single-tenant	Query directo	TX regular
Multi-tenant	TX read-only + `SET LOCAL` + query + commit	TX regular + `SET LOCAL`

El costo: un round-trip extra por lectura. SET LOCAL es sub-milisegundo — opera sobre variables GUC en memoria, sin I/O a disco. En la practica, el overhead es despreciable comparado con la latencia de red del query mismo.

Testing

Aislamiento basico

func TestOrderIsolation(t *testing.T) {
    db := setupTestDB(t)
    enableRLS(ctx, db, []string{"orders"})

    ctxA, _ := tenant.WithTenantID(context.Background(), "tenant-a")
    createTestOrder(t, db, ctxA, "order-1")

    ctxB, _ := tenant.WithTenantID(context.Background(), "tenant-b")
    createTestOrder(t, db, ctxB, "order-2")

    // Tenant A solo ve su orden
    orders := listOrders(t, db, ctxA)
    assert.Len(t, orders, 1)
    assert.Equal(t, "order-1", orders[0].Name)

    // Tenant B solo ve su orden
    orders = listOrders(t, db, ctxB)
    assert.Len(t, orders, 1)
    assert.Equal(t, "order-2", orders[0].Name)
}

Aislamiento concurrente

func TestConcurrentTenantIsolation(t *testing.T) {
    db := setupTestDB(t)
    enableRLS(ctx, db, []string{"orders"})

    for i := 0; i < 10; i++ {
        tid := fmt.Sprintf("tenant-%d", i)
        ctx, _ := tenant.WithTenantID(context.Background(), tid)
        createTestOrder(t, db, ctx, fmt.Sprintf("order-for-%s", tid))
    }

    var wg sync.WaitGroup
    errs := make(chan error, 100)

    for i := 0; i < 100; i++ {
        wg.Add(1)
        go func(n int) {
            defer wg.Done()
            tid := fmt.Sprintf("tenant-%d", n%10)
            ctx, _ := tenant.WithTenantID(context.Background(), tid)

            orders := listOrders(t, db, ctx)
            if len(orders) != 1 {
                errs <- fmt.Errorf("tenant %s: expected 1 order, got %d", tid, len(orders))
                return
            }
            if !strings.Contains(orders[0].Name, tid) {
                errs <- fmt.Errorf("tenant %s: order name %q doesn't match", tid, orders[0].Name)
            }
        }(i)
    }
    wg.Wait()
    close(errs)

    for err := range errs {
        t.Error(err)
    }
}

100 goroutines compartiendo el mismo connection pool. SET LOCAL previene contaminacion cruzada. Notar que las assertions se reportan via channel — t.Fatal/t.FailNow no son seguros desde goroutines.

5 Errores Comunes

1. `SET` en vez de `SET LOCAL`

// MAL — scope de sesion, se filtra en el pool
tx.ExecContext(ctx, "SET app.current_tenant = $1", tenantID)

// BIEN — scope de transaccion, auto-limpiado
tx.ExecContext(ctx, "SET LOCAL app.current_tenant = $1", tenantID)

2. Olvidar `FORCE ROW LEVEL SECURITY`

-- Sin FORCE, el table owner bypasea RLS
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;

-- Con FORCE, incluso el owner esta sujeto a policies
ALTER TABLE orders FORCE ROW LEVEL SECURITY;

3. No parametrizar `SET LOCAL`

// MAL — SQL injection
tx.ExecContext(ctx, fmt.Sprintf("SET LOCAL app.current_tenant = '%s'", tenantID))

// BIEN — parametrizado
tx.ExecContext(ctx, "SET LOCAL app.current_tenant = $1", tenantID)

4. `tenant_id` al final en indices

-- MAL — escanea todos los tenants
CREATE INDEX idx ON orders (status, tenant_id);

-- BIEN — escanea solo un tenant
CREATE INDEX idx ON orders (tenant_id, status);

5. Olvidar `defer done()`

// MAL — TX puede quedar abierto
q, done, err := tenantQuerier(ctx, db)

// BIEN — defer inmediato
q, done, err := tenantQuerier(ctx, db)
if err != nil { return err }
defer done()

Resumen

El patron completo en cuatro lineas:

tx, _ := db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})  // 1. Iniciar TX
tx.ExecContext(ctx, "SET LOCAL app.current_tenant = $1", t) // 2. Activar tenant
rows, _ := tx.QueryContext(ctx, "SELECT * FROM orders")     // 3. Query (RLS filtra)
tx.Commit()                                                  // 4. Cleanup automatico

PostgreSQL hace el resto. Sin WHERE tenant_id = ?. Sin filtrado a nivel de app. Sin brechas por filtros olvidados.

SET LOCAL + connection pooling de database/sql es la combinacion segura. SET filtra estado. SET LOCAL no. Esa es toda la diferencia entre un sistema seguro y una brecha de datos.

Somos GophersCL, la comunidad de Go en Chile. Siguenos en dev.to para mas contenido sobre Go en Latinoamerica.

Migrando de Supabase a una arquitectura full Go: La poesía de los binarios estáticos

igcodinap — Tue, 13 Jan 2026 14:26:48 +0000

Cómo el ecosistema Go nos permitió reemplazar un backend hosted por una infraestructura self-hosted elegante, mantenible y completamente gratuita.

Hace unos meses tomamos una decisión que parecía arriesgada: migrar una aplicación desde Supabase hosted hacia una arquitectura completamente self-hosted. El resultado fue inesperadamente hermoso.

El contexto

Teníamos una instancia Supabase para autenticación y base de datos. Funcionaba bien, pero dependíamos de sus restricciones y limitaciones para seguir creando features. Cuando el proyecto escaló, se hizo cada vez más difícil mantenerlo y añadir nuevos features debido al mismo diseño de supabase. Por esto, decidimos tomar control total de nuestra infraestructura.

Lo que no esperábamos era descubrir que todo el ecosistema que necesitábamos estaba escrito en Go.

La arquitectura resultante

                    ┌─────────────────────────────────────────┐
                    │         GCP Compute Engine VM           │
                    │                                         │
    Internet ───────┤  Caddy ──▶ go-app ──▶ Cloud SQL Proxy  │──▶ PostgreSQL
                    │    │                        │           │
                    │    └─────▶ GoTrue ──────────┘           │
                    │                                         │
                    │         Alloy ──▶ Grafana Cloud         │
                    └─────────────────────────────────────────┘

Cinco servicios. Todos escritos en Go.

Servicio	Propósito	Creador
go-app	Nuestra API REST	Nosotros
Caddy	Reverse proxy + TLS automático	Matt Holt
GoTrue	Autenticación (signup, login, OAuth)	Supabase
Alloy	Métricas y logs	Grafana Labs
Cloud SQL Proxy	Conexión segura a Cloud SQL	Google

¿Por qué esto es especial?

1. Binarios estáticos

Cada uno de estos servicios compila a un único binario sin dependencias externas. No hay runtime que instalar, no hay versiones de Node que gestionar, no hay virtualenvs. Un binario, un proceso.

# Así de simple es desplegar Caddy
wget https://github.com/caddyserver/caddy/releases/download/v2.8.4/caddy_2.8.4_linux_amd64.tar.gz
tar -xzf caddy_2.8.4_linux_amd64.tar.gz
./caddy run

2. Consumo de recursos mínimo

Nuestra VM de staging corre los 5 servicios con 2GB de RAM. En idle, el consumo total no supera los 400MB. Comparen eso con correr un cluster de Node.js + Redis + Nginx.

3. Configuración declarativa

Caddy, GoTrue y Alloy usan archivos de configuración simples y legibles:

# Caddyfile - 40 líneas para TLS + reverse proxy + CORS
api.dominio.com {
  handle /auth/v1/* {
    reverse_proxy gotrue:9999
  }
  handle {
    reverse_proxy api:8080
  }
}

4. El mismo idioma mental

Cuando debuggeas un problema, saltas entre servicios pero te mantienes en el mismo paradigma. Context propagation, structured logging, graceful shutdown - todos siguen los mismos patrones porque todos son Go.

GoTrue: El corazón de la autenticación

GoTrue es el servicio de autenticación de Supabase, pero es completamente standalone. Lo puedes correr con Docker:

# docker-compose.yml
auth:
  image: supabase/auth:v2.184.0
  environment:
    GOTRUE_DB_DATABASE_URL: postgres://user:pass@db:5432/mydb?search_path=auth
    GOTRUE_JWT_SECRET: ${JWT_SECRET}
    GOTRUE_SITE_URL: https://miapp.com
  command: ["sh", "-c", "gotrue migrate && gotrue serve"]

Y obtienes:

Signup/login con email y password
Magic links
OAuth (Google, Apple, GitHub, etc.)
Refresh tokens
JWT estándar compatible con cualquier middleware

Lo mejor: es el mismo servicio que usa Supabase en producción. No es una versión recortada.

Caddy: TLS sin dolor

Si nunca han usado Caddy, prepárense para olvidar todo lo que saben sobre configurar certificados SSL.

api.miapp.com {
  reverse_proxy localhost:8080
}

Eso es todo. Caddy obtiene certificados de Let's Encrypt automáticamente, los renueva, y configura HTTPS con los headers de seguridad correctos. Cero configuración adicional.

Alloy: Observabilidad moderna

Grafana Alloy (antes Grafana Agent) recolecta métricas y logs y los envía a Grafana Cloud (que tiene un tier gratuito generoso).

// Recolectar logs de todos los containers Docker
loki.source.docker "containers" {
  host = "unix:///var/run/docker.sock"
  targets = discovery.docker.containers.targets
}

Con 20 líneas de configuración tienes logs centralizados de todos tus servicios, con labels automáticos por container.

El flujo de autenticación

Usuario                    Frontend                   Caddy                    GoTrue                     GoApp
   │                          │                         │                         │                         │
   │──── Login ──────────────▶│                         │                         │                         │
   │                          │─── POST /auth/v1/token ▶│                         │                         │
   │                          │                         │──── proxy ─────────────▶│                         │
   │                          │                         │                         │── validate credentials ─│
   │                          │                         │◀─── JWT ────────────────│                         │
   │                          │◀── { access_token } ────│                         │                         │
   │◀─── Logged in ───────────│                         │                         │                         │
   │                          │                         │                         │                         │
   │──── Get entity ─────────▶│                         │                         │                         │
   │                          │── GET /api/entity ─────▶│                         │                         │
   │                          │   Authorization: Bearer │──── proxy ──────────────────────────────────────▶│
   │                          │                         │                         │                         │── validate JWT
   │                          │                         │                         │                         │── query DB
   │                          │◀──────────────────────────────────────────────────── { entity } ───────────│
   │◀─── entity ──────────────│                         │                         │                         │

entity: cualquiera sea el recurso de tu db que quieras consumir.

El JWT que emite GoTrue es validado por nuestro middleware en go-app. Mismo secreto, mismo formato, cero fricción.

Costos

Recurso	Costo mensual
VM e2-small (staging)	~$15 USD
Cloud SQL (db-f1-micro)	~$10 USD
Grafana Cloud	$0 (tier gratuito)
Caddy, GoTrue, Alloy	$0 (open source)
Total staging	~$25 USD

Para producción duplicamos los recursos, pero seguimos muy por debajo de lo que pagábamos por Supabase Pro.

Lo que aprendimos

1. Self-hosted no significa complejo

Con las herramientas correctas, self-hosted puede ser más simple que managed. Un docker-compose up -d y tienes todo corriendo.

2. Go es infraestructura

El ecosistema Go para herramientas de infraestructura es impresionante: Docker, Kubernetes, Terraform, Prometheus, Grafana, Caddy, Traefik, Hugo... La lista es interminable.

3. Supabase hizo bien su trabajo

GoTrue es un proyecto de calidad. Está bien documentado, es estable, y hace una cosa bien. Que sea open source y self-hosteable habla bien de Supabase como empresa.

4. La cohesión tiene valor

Hay algo satisfactorio en ver docker ps y saber que todos esos procesos comparten el mismo ADN. Cuando algo falla, el debugging sigue los mismos patrones.

Recursos

GoTrue GitHub
Caddy Server
Grafana Alloy
Huma v2 - Framework HTTP para Go que usamos en la go-app

Conclusión

Si están considerando migrar de un servicio hosted a self-hosted, el ecosistema Go les tiene cubiertos. No necesitan reinventar la rueda - solo necesitan ensamblar las piezas correctas.

Y si ya programan en Go, van a sentirse como en casa.

¿Preguntas sobre la migración o la arquitectura? Déjenlas en los comentarios o encuéntrenme en la comunidad de Golang Chile.

FHIRPath en Go: Cómo Construí un Motor de Consultas para Interoperabilidad en Salud

Roberto Araneda Espinoza — Fri, 09 Jan 2026 18:33:31 +0000

Construyendo una Librería FHIRPath en Go: Del Concepto a la Implementación

Cómo diseñé e implementé un motor de evaluación FHIRPath completo en Golang, desde el análisis léxico hasta la ejecución de expresiones

Introducción

En el ecosistema de la salud digital, la interoperabilidad no es un lujo, es una necesidad. FHIR® (Fast Healthcare Interoperability Resources) se ha convertido en el estándar de facto para el intercambio de datos clínicos, y FHIRPath es el lenguaje de consulta que nos permite navegar y extraer información de estos recursos de manera precisa y eficiente.

Este artículo documenta mi experiencia construyendo gofhir, una implementación completa de FHIRPath en Go. Compartiré las decisiones arquitectónicas, los patrones de diseño utilizados y los desafíos técnicos que enfrenté durante el desarrollo.

¿Qué es FHIR®?

FHIR® (pronunciado "fire") es un estándar desarrollado por HL7 International para el intercambio electrónico de información de salud. A diferencia de sus predecesores (HL7 v2 y v3), FHIR® fue diseñado desde cero con tecnologías web modernas en mente.

Características Principales de FHIR®

FHIR® se basa en el concepto de Resources (Recursos), que representan entidades clínicas y administrativas como Patient, Observation, Medication, Encounter, entre muchas otras. Cada recurso tiene una estructura bien definida que puede ser representada en JSON o XML.

{
  "resourceType": "Patient",
  "id": "example",
  "name": [
    {
      "use": "official",
      "family": "Garcia",
      "given": ["Maria", "Jose"]
    }
  ],
  "birthDate": "1990-05-15",
  "gender": "female",
  "address": [
    {
      "city": "Santiago",
      "country": "Chile"
    }
  ]
}

La arquitectura RESTful de FHIR® permite operaciones estándar HTTP (GET, POST, PUT, DELETE) sobre estos recursos, facilitando la integración entre sistemas de salud heterogéneos.

¿Qué es FHIRPath?

FHIRPath es un lenguaje de navegación y extracción de datos diseñado específicamente para trabajar con recursos FHIR®. Piensa en él como XPath para XML o JSONPath para JSON, pero optimizado para el modelo de datos de FHIR®.

Ejemplos de Expresiones FHIRPath

// Obtener el apellido de un paciente
Patient.name.family

// Filtrar nombres con uso "official"
Patient.name.where(use = 'official').given

// Verificar si el paciente es mayor de edad
Patient.birthDate <= today() - 18 years

// Obtener el primer elemento de una colección
Patient.address.first().city

// Combinar condiciones
Observation.value.where($this is Quantity and value > 100)

El poder de FHIRPath radica en su capacidad para expresar consultas complejas de manera concisa y legible.

Arquitectura de la Librería

Visión General

La arquitectura de gofhir/fhirpath sigue un diseño clásico de compilador/intérprete:

Principios de Diseño

1. Separación de Responsabilidades

Cada componente tiene una única responsabilidad bien definida:

ANTLR Parser: Análisis léxico, sintáctico y construcción del parse tree
Evaluator: Visitor pattern que recorre el parse tree
Funcs: Implementaciones de funciones FHIRPath
Types: Sistema de tipos que representa valores FHIRPath

2. Inmutabilidad

Las expresiones compiladas son inmutables, permitiendo su reutilización segura en entornos concurrentes:

// Una expresión compilada puede ser reutilizada múltiples veces
expr, err := fhirpath.Compile("Patient.name.given")
if err != nil {
    log.Fatal(err)
}

// Seguro para uso concurrente
for _, patientJSON := range patientsJSON {
    result, _ := expr.Evaluate(patientJSON)
    // procesar resultado
}

Implementación del Lexer y Parser con ANTLR

¿Por qué ANTLR?

ANTLR (ANother Tool for Language Recognition) es un generador de parsers que produce código en múltiples lenguajes, incluyendo Go. Las razones para elegir ANTLR fueron:

Gramática declarativa: Define la sintaxis de FHIRPath de forma clara y mantenible
Generación automática: Produce lexer y parser optimizados
Manejo de errores robusto: Proporciona mensajes de error precisos
Soporte oficial de Go: Target estable y bien mantenido

Definición de la Gramática

La gramática FHIRPath se define en un archivo .g4:

// FHIRPath.g4
grammar FHIRPath;

// Reglas del Parser
expression
    : term                                          # termExpression
    | expression '.' invocation                     # invocationExpression
    | expression '[' expression ']'                 # indexerExpression
    | ('+' | '-') expression                        # polarityExpression
    | expression ('*' | '/' | 'div' | 'mod') expression  # multiplicativeExpression
    | expression ('+' | '-' | '&') expression       # additiveExpression
    | expression ('|') expression                   # unionExpression
    | expression ('<=' | '<' | '>' | '>=') expression    # inequalityExpression
    | expression ('=' | '~' | '!=' | '!~') expression    # equalityExpression
    | expression ('in' | 'contains') expression     # membershipExpression
    | expression 'and' expression                   # andExpression
    | expression ('or' | 'xor') expression          # orExpression
    | expression 'implies' expression               # impliesExpression
    ;

term
    : invocation                                    # invocationTerm
    | literal                                       # literalTerm
    | externalConstant                              # externalConstantTerm
    | '(' expression ')'                            # parenthesizedTerm
    ;

// Reglas del Lexer
IDENTIFIER
    : ([A-Za-z] | '_') ([A-Za-z0-9] | '_')*
    ;

STRING
    : '\'' (ESC | ~['\\])* '\''
    ;

NUMBER
    : [0-9]+ ('.' [0-9]+)?
    ;

Generación del Código Go

# Generar lexer y parser en Go
antlr4 -Dlanguage=Go -package grammar -visitor FHIRPath.g4

Sistema de Tipos

FHIRPath define un conjunto de tipos primitivos del sistema. En la implementación, definimos una interfaz base Value:

// types/value.go
package types

// Value es la interfaz base para todos los valores FHIRPath
type Value interface {
    // Type retorna el nombre del tipo FHIRPath
    Type() string

    // Equal compara igualdad exacta (operador =)
    Equal(other Value) bool

    // Equivalent compara equivalencia (operador ~)
    // Para strings: case-insensitive, ignora espacios
    Equivalent(other Value) bool

    // String retorna representación como string
    String() string

    // IsEmpty indica si el valor representa vacío
    IsEmpty() bool
}

// Comparable es implementado por tipos que soportan ordenamiento
type Comparable interface {
    Value
    // Compare retorna -1 si menor, 0 si igual, 1 si mayor
    Compare(other Value) (int, error)
}

// Numeric es implementado por tipos numéricos (Integer, Decimal)
type Numeric interface {
    Value
    // ToDecimal convierte el valor a Decimal
    ToDecimal() Decimal
}

Tipos Implementados

Tipo	Descripción	Implementación
`Boolean`	Valores true/false	`types.Boolean`
`Integer`	Enteros de 64 bits	`types.Integer` (int64)
`Decimal`	Precisión arbitraria	`types.Decimal` (shopspring/decimal)
`String`	Cadenas UTF-8	`types.String`
`Date`	Fecha (YYYY-MM-DD)	`types.Date`
`DateTime`	Fecha y hora ISO 8601	`types.DateTime`
`Time`	Hora (HH:MM:SS)	`types.Time`
`Quantity`	Valor + unidad UCUM	`types.Quantity`

Implementación de Decimal con Precisión Arbitraria

Para manejar correctamente valores decimales sin pérdida de precisión, utilizamos la librería shopspring/decimal:

// types/decimal.go
package types

import (
    "github.com/shopspring/decimal"
)

// Decimal representa un valor decimal FHIRPath con precisión arbitraria
type Decimal struct {
    value decimal.Decimal
}

// NewDecimal crea un Decimal desde un string
func NewDecimal(s string) (Decimal, error) {
    d, err := decimal.NewFromString(s)
    if err != nil {
        return Decimal{}, fmt.Errorf("invalid decimal: %s", s)
    }
    return Decimal{value: d}, nil
}

func (d Decimal) Type() string {
    return "Decimal"
}

func (d Decimal) Equal(other Value) bool {
    switch o := other.(type) {
    case Decimal:
        return d.value.Equal(o.value)
    case Integer:
        return d.value.Equal(decimal.NewFromInt(o.value))
    }
    return false
}

// Operaciones aritméticas
func (d Decimal) Add(other Decimal) Decimal {
    return Decimal{value: d.value.Add(other.value)}
}

func (d Decimal) Divide(other Decimal) (Decimal, error) {
    if other.value.IsZero() {
        return Decimal{}, fmt.Errorf("division by zero")
    }
    return Decimal{value: d.value.DivRound(other.value, 16)}, nil
}

Collections: El Corazón de FHIRPath

En FHIRPath, todas las expresiones operan sobre y retornan colecciones. Esta es una característica fundamental que simplifica el manejo de valores opcionales y múltiples.

// types/collection.go
package types

// Collection es una secuencia ordenada de valores FHIRPath
type Collection []Value

Métodos Principales de Collection

Método	Descripción
`Empty() bool`	Retorna true si la colección está vacía
`Count() int`	Retorna el número de elementos
`First() (Value, bool)`	Retorna el primer elemento
`Last() (Value, bool)`	Retorna el último elemento
`Single() (Value, error)`	Retorna el único elemento (error si != 1)
`Contains(v Value) bool`	Verifica si contiene el valor
`Distinct() Collection`	Elimina duplicados
`Where(predicate) Collection`	Filtra elementos por criterio

La implementación incluye 21 métodos en total. Ver collection.go para la lista completa.

// Ejemplos de implementación:

func (c Collection) Empty() bool {
    return len(c) == 0
}

func (c Collection) First() (Value, bool) {
    if len(c) == 0 {
        return nil, false
    }
    return c[0], true
}

func (c Collection) Contains(v Value) bool {
    for _, item := range c {
        if item.Equal(v) {
            return true
        }
    }
    return false
}

func (c Collection) Distinct() Collection {
    result := make(Collection, 0, len(c))
    for _, item := range c {
        if !result.Contains(item) {
            result = append(result, item)
        }
    }
    return result
}

El Evaluador

El evaluador implementa el patrón Visitor sobre el parse tree generado por ANTLR.

Contexto de Evaluación

// eval/evaluator.go
package eval

import (
    "context"
    "github.com/robertoaraneda/gofhir/pkg/fhirpath/types"
)

// Context mantiene el estado durante la evaluación
type Context struct {
    root      types.Collection          // Recurso raíz
    this      types.Collection          // Contexto actual ($this)
    index     int                       // Índice actual ($index)
    total     types.Value               // Acumulador ($total)
    variables map[string]types.Collection // Variables externas (%name)
    limits    map[string]int            // Límites de evaluación
    goCtx     context.Context           // Context de Go para cancelación
    resolver  Resolver                  // Resolver de referencias FHIR®
}

// NewContext crea un nuevo contexto desde JSON
func NewContext(resource []byte) *Context {
    root, _ := types.JSONToCollection(resource)

    variables := make(map[string]types.Collection)
    variables["resource"] = root  // %resource para constraints FHIR®
    variables["context"] = root   // %context

    return &Context{
        root:      root,
        this:      root,
        variables: variables,
        limits:    make(map[string]int),
        goCtx:     context.Background(),
    }
}

// WithThis retorna un nuevo contexto con el $this dado
func (c *Context) WithThis(this types.Collection) *Context {
    newCtx := *c
    newCtx.this = this
    return &newCtx
}

// SetVariable define una variable externa
func (c *Context) SetVariable(name string, value types.Collection) {
    c.variables[name] = value
}

Implementación del Visitor

// eval/evaluator.go
package eval

import (
    "github.com/antlr4-go/antlr/v4"
    "github.com/robertoaraneda/gofhir/pkg/fhirpath/parser/grammar"
    "github.com/robertoaraneda/gofhir/pkg/fhirpath/types"
)

// Evaluator evalúa expresiones FHIRPath usando el patrón visitor
type Evaluator struct {
    grammar.BasefhirpathVisitor
    ctx   *Context
    funcs FuncRegistry
}

// Evaluate evalúa un parse tree y retorna el resultado
func (e *Evaluator) Evaluate(tree antlr.ParseTree) (types.Collection, error) {
    result := e.Visit(tree)
    if err, ok := result.(error); ok {
        return nil, err
    }
    if col, ok := result.(types.Collection); ok {
        return col, nil
    }
    return types.Collection{}, nil
}

// VisitInvocationExpression visita expr.invocation
func (e *Evaluator) VisitInvocationExpression(ctx *grammar.InvocationExpressionContext) interface{} {
    // Evaluar la expresión base
    base := e.Visit(ctx.Expression())
    if err, ok := base.(error); ok {
        return err
    }
    baseCol := base.(types.Collection)

    // Guardar $this actual y establecer nuevo
    oldThis := e.ctx.this
    e.ctx.this = baseCol
    defer func() { e.ctx.this = oldThis }()

    // Evaluar la invocación
    return e.Visit(ctx.Invocation())
}

// VisitEqualityExpression visita expresiones de igualdad
func (e *Evaluator) VisitEqualityExpression(ctx *grammar.EqualityExpressionContext) interface{} {
    left := e.Visit(ctx.Expression(0))
    if err, ok := left.(error); ok {
        return err
    }
    leftCol := left.(types.Collection)

    right := e.Visit(ctx.Expression(1))
    if err, ok := right.(error); ok {
        return err
    }
    rightCol := right.(types.Collection)

    op := ctx.GetChild(1).(antlr.TerminalNode).GetText()

    switch op {
    case "=":
        return Equal(leftCol, rightCol)
    case "!=":
        return NotEqual(leftCol, rightCol)
    case "~":
        return Equivalent(leftCol, rightCol)
    case "!~":
        return NotEquivalent(leftCol, rightCol)
    }

    return types.Collection{}
}

Funciones Built-in

La librería implementa 99 funciones organizadas en 10 categorías. A continuación se presentan las más relevantes para interoperabilidad FHIR®:

Resumen de Funciones por Categoría

Categoría	Funciones	Uso Principal
Existencia	`empty`, `exists`, `count`, `all`, `distinct`	Validación de datos obligatorios
Filtrado	`where`, `select`, `ofType`, `repeat`	Extracción de datos específicos
Subsetting	`first`, `last`, `single`, `skip`, `take`	Navegación de colecciones
Strings	`contains`, `startsWith`, `matches`, `lower`	Búsqueda y normalización de texto
Matemáticas	`round`, `abs`, `sum`, `min`, `max`, `avg`	Cálculos clínicos
Temporales	`now`, `today`, `year`, `month`, `day`	Validación de fechas
Conversión	`toInteger`, `toDecimal`, `toString`, `toDate`	Transformación de tipos
Navegación	`children`, `descendants`	Exploración de recursos
FHIR®	`resolve`, `extension`, `hasExtension`	Interoperabilidad FHIR®
Utility	`trace`, `iif`, `not`	Debugging y lógica condicional

Funciones Clave para Interoperabilidad

where() - Filtrado con Criterios

// Filtrar nombres por uso
Patient.name.where(use = 'official')

// Filtrar observaciones por código
Observation.where(code.coding.code = '8867-4')

// Filtrar con múltiples condiciones
Patient.telecom.where(system = 'phone' and use = 'mobile')

exists() - Validación de Datos

// Verificar campos obligatorios
Patient.identifier.exists()

// Validar con criterio
Patient.name.exists(use = 'official')

// Verificar referencias
Observation.subject.exists()

extension() - Acceso a Extensiones FHIR®

// Obtener extensión por URL
Patient.extension('http://hl7.org/fhir/StructureDefinition/patient-nationality')

// Verificar existencia
Patient.hasExtension('http://example.org/fhir/StructureDefinition/custom')

// Obtener valor directamente
Patient.getExtensionValue('http://example.org/extension-url')

resolve() - Resolución de Referencias

// Resolver referencia a paciente
Observation.subject.resolve()

// Encadenar navegación después de resolver
Observation.subject.resolve().name.family

Funciones Temporales

// Comparar fechas
Patient.birthDate <= today() - 18 years

// Extraer componentes
Patient.birthDate.year()
Observation.effectiveDateTime.month()

// Timestamp actual
now()  // DateTime completo
today() // Solo fecha

Funciones de Navegación de Árboles

// Obtener todos los hijos directos
Patient.children()

// Buscar en todo el árbol (recursivo)
Bundle.entry.resource.descendants().where($this is Coding)

Implementación de where()

El filtrado con where() establece contexto por elemento usando $this y $index:

func (e *Evaluator) evaluateWhere(input types.Collection, criteria grammar.IExpressionContext) interface{} {
    result := types.Collection{}

    for i, item := range input {
        e.ctx.this = types.Collection{item}  // $this = elemento actual
        e.ctx.index = i                       // $index = posición

        criteriaResult := e.Visit(criteria)

        if col, ok := criteriaResult.(types.Collection); ok && !col.Empty() {
            if b, ok := col[0].(types.Boolean); ok && b.Bool() {
                result = append(result, item)
            }
        }
    }
    return result
}

Función trace() para Debugging

// Debugging de expresiones FHIRPath
result := fhirpath.MustEvaluate(patientJSON,
    "Patient.name.trace('nombres').where(use = 'official').trace('filtrado')")

// Output en stderr:
// [trace] nombres: { Garcia }
// [trace] filtrado: { Garcia }

La función trace() soporta logging estructurado configurable vía SetTraceLogger() para integración con sistemas de observabilidad.

API Pública

Interfaz Simple y Expresiva

// fhirpath.go
package fhirpath

import "github.com/robertoaraneda/gofhir/pkg/fhirpath/types"

// Evaluate parsea y evalúa una expresión FHIRPath en un solo paso
// El recurso debe ser JSON válido como []byte
func Evaluate(resource []byte, expr string) (types.Collection, error) {
    compiled, err := Compile(expr)
    if err != nil {
        return nil, err
    }
    return compiled.Evaluate(resource)
}

// MustEvaluate es como Evaluate pero hace pánic en caso de error
func MustEvaluate(resource []byte, expr string) types.Collection {
    result, err := Evaluate(resource, expr)
    if err != nil {
        panic(err)
    }
    return result
}

// Compile parsea una expresión FHIRPath y retorna una Expression compilada
// La expresión compilada puede ser evaluada múltiples veces
func Compile(expr string) (*Expression, error) {
    return compile(expr)
}

// MustCompile es como Compile pero hace pánic en caso de error
func MustCompile(expr string) *Expression {
    compiled, err := Compile(expr)
    if err != nil {
        panic(err)
    }
    return compiled
}

Expression

// expression.go
package fhirpath

// Expression representa una expresión FHIRPath compilada
type Expression struct {
    source string
    tree   *grammar.EntireExpressionContext
}

// Evaluate ejecuta la expresión sobre un recurso JSON
func (e *Expression) Evaluate(resource []byte) (types.Collection, error) {
    ctx := eval.NewContext(resource)
    return e.EvaluateWithContext(ctx)
}

// EvaluateWithContext ejecuta la expresión con un contexto personalizado
func (e *Expression) EvaluateWithContext(ctx *eval.Context) (types.Collection, error) {
    evaluator := eval.NewEvaluator(ctx, funcs.GetRegistry())
    return evaluator.Evaluate(e.tree)
}

// EvaluateWithOptions evalúa con opciones funcionales personalizadas
func (e *Expression) EvaluateWithOptions(resource []byte, opts ...EvalOption) (types.Collection, error) {
    options := DefaultOptions()
    for _, opt := range opts {
        opt(options)
    }
    // Configura timeout, variables, límites, y resolver
    // Ver sección "Opciones de Evaluación" para detalles
}

// String retorna la expresión original
func (e *Expression) String() string {
    return e.source
}

Opciones de Evaluación (Functional Options Pattern)

La librería utiliza el patrón de opciones funcionales para configurar la evaluación:

// options.go
package fhirpath

// EvalOptions configura la evaluación de expresiones
type EvalOptions struct {
    Ctx               context.Context            // Context para cancelación y timeout
    Timeout           time.Duration              // Timeout para evaluación (default: 5s)
    MaxDepth          int                        // Profundidad máxima de recursión (default: 100)
    MaxCollectionSize int                        // Tamaño máximo de colección (default: 10000)
    Variables         map[string]types.Collection // Variables externas (%name)
    Resolver          ReferenceResolver          // Resolver para resolve()
}

// DefaultOptions retorna opciones por defecto para producción
func DefaultOptions() *EvalOptions {
    return &EvalOptions{
        Ctx:               context.Background(),
        Timeout:           5 * time.Second,
        MaxDepth:          100,
        MaxCollectionSize: 10000,
        Variables:         make(map[string]types.Collection),
    }
}

// Opciones funcionales disponibles
func WithContext(ctx context.Context) EvalOption      // Context para cancelación
func WithTimeout(d time.Duration) EvalOption          // Timeout de evaluación
func WithMaxDepth(depth int) EvalOption               // Límite de recursión
func WithMaxCollectionSize(size int) EvalOption       // Límite de colección
func WithVariable(name string, value types.Collection) EvalOption // Variable externa
func WithResolver(r ReferenceResolver) EvalOption     // Resolver de referencias FHIR®

// ReferenceResolver interface para resolver()
type ReferenceResolver interface {
    Resolve(ctx context.Context, reference string) ([]byte, error)
}

Ejemplo de uso con opciones:

expr := fhirpath.MustCompile("Patient.name.given")

// Evaluar con timeout y variables personalizadas
result, err := expr.EvaluateWithOptions(patientJSON,
    fhirpath.WithTimeout(2*time.Second),
    fhirpath.WithVariable("minAge", types.Collection{types.NewInteger(18)}),
    fhirpath.WithMaxCollectionSize(5000),
)

Ejemplo Completo de Uso

package main

import (
    "fmt"
    "log"

    "github.com/robertoaraneda/gofhir/pkg/fhirpath"
)

func main() {
    // Recurso Patient de ejemplo como JSON
    patientJSON := []byte(`{
        "resourceType": "Patient",
        "id": "example",
        "name": [
            {
                "use": "official",
                "family": "Garcia",
                "given": ["Maria", "Jose"]
            },
            {
                "use": "nickname",
                "given": ["Mari"]
            }
        ],
        "birthDate": "1990-05-15",
        "gender": "female",
        "address": [
            {
                "use": "home",
                "city": "Santiago",
                "country": "Chile"
            }
        ],
        "telecom": [
            {
                "system": "phone",
                "value": "+56912345678",
                "use": "mobile"
            },
            {
                "system": "email",
                "value": "maria.garcia@example.com"
            }
        ]
    }`)

    // Ejemplos de consultas FHIRPath
    examples := []struct {
        description string
        expression  string
    }{
        {"Obtener el apellido", "Patient.name.family"},
        {"Obtener el nombre oficial", "Patient.name.where(use = 'official').given"},
        {"Obtener el primer nombre dado", "Patient.name.first().given.first()"},
        {"Verificar si es mujer", "Patient.gender = 'female'"},
        {"Obtener el email", "Patient.telecom.where(system = 'email').value"},
        {"Contar direcciones", "Patient.address.count()"},
        {"Verificar teléfono móvil", "Patient.telecom.exists(system = 'phone' and use = 'mobile')"},
        {"Ciudad en mayúsculas", "Patient.address.city.upper()"},
    }

    for _, ex := range examples {
        // Compilar expresión (puede ser reutilizada)
        expr, err := fhirpath.Compile(ex.expression)
        if err != nil {
            log.Printf("Error compilando '%s': %v", ex.expression, err)
            continue
        }

        // Evaluar sobre el recurso JSON
        result, err := expr.Evaluate(patientJSON)
        if err != nil {
            log.Printf("Error evaluando '%s': %v", ex.expression, err)
            continue
        }

        fmt.Printf("\n%s\n", ex.description)
        fmt.Printf("  Expresión: %s\n", ex.expression)
        fmt.Printf("  Resultado: %v\n", result)
    }
}

Salida:

Obtener el apellido
  Expresión: Patient.name.family
  Resultado: [Garcia]

Obtener el nombre oficial
  Expresión: Patient.name.where(use = 'official').given
  Resultado: [Maria, Jose]

Obtener el primer nombre dado
  Expresión: Patient.name.first().given.first()
  Resultado: [Maria]

Verificar si es mujer
  Expresión: Patient.gender = 'female'
  Resultado: [true]

Obtener el email
  Expresión: Patient.telecom.where(system = 'email').value
  Resultado: [maria.garcia@example.com]

Contar direcciones
  Expresión: Patient.address.count()
  Resultado: [1]

Verificar teléfono móvil
  Expresión: Patient.telecom.exists(system = 'phone' and use = 'mobile')
  Resultado: [true]

Ciudad en mayúsculas
  Expresión: Patient.address.city.upper()
  Resultado: [SANTIAGO]

Operadores Soportados

La implementación soporta todos los operadores definidos en la especificación FHIRPath:

Categoría	Operadores	Notas
Aritméticos	`+`, `-`, `*`, `/`, `div`, `mod`	División `/` retorna Decimal
Concatenación	`+`, `&`	`&` trata empty como string vacío
Comparación	`=`, `!=`, `<`, `<=`, `>`, `>=`	Compara valores ordenables
Equivalencia	`~`, `!~`	Case-insensitive para strings
Lógicos	`and`, `or`, `xor`, `implies`, `not()`	Three-valued logic (true/false/empty)
Colección	\| (union), `in`, `contains`	Unión y membresía
Tipo	`is`, `as`	Verificación y casting

El desglose completo de operadores y funciones está disponible en el README del repositorio.

Características Avanzadas

Protección contra ReDoS

Las funciones matches() y replaceMatches() incluyen protección contra ataques de denegación de servicio por expresiones regulares:

// funcs/regex.go
type RegexCache struct {
    cache    *lru.Cache  // Cache LRU con 500 patrones
    maxLen   int         // Máximo 1000 caracteres por patrón
    timeout  time.Duration
}

// Valida patrones peligrosos (cuantificadores anidados, grupos profundos)
func (c *RegexCache) validatePattern(pattern string) error {
    // Detecta patrones como (a+)+ que causan backtracking exponencial
}

// Timeout de 100ms para strings largos
func (c *RegexCache) MatchWithTimeout(ctx context.Context, pattern, str string) (bool, error)

Soporte UCUM para Quantities

Las cantidades incluyen normalización de unidades UCUM para comparaciones correctas:

// types/quantity.go
type Quantity struct {
    value decimal.Decimal
    unit  string
}

// Normalize convierte a unidades canónicas para comparación
func (q Quantity) Normalize() NormalizedQuantity {
    return ucum.Normalize(q.value, q.unit)
}

Límites de Evaluación

ctx := eval.NewContext(resource)
ctx.SetLimit("maxDepth", 100)           // Profundidad máxima de recursión
ctx.SetLimit("maxCollectionSize", 10000) // Tamaño máximo de colección
ctx.SetContext(timeoutCtx)              // Context de Go para cancelación

Lecciones Aprendidas

1. El Poder de las Colecciones

Inicialmente consideré manejar valores singulares y colecciones de forma diferente. Sin embargo, el enfoque de FHIRPath donde todo es una colección simplifica enormemente la implementación y elimina muchos casos especiales.

2. ANTLR vs Parser Manual

ANTLR ahorra meses de trabajo. La gramática oficial de FHIRPath está disponible, y generar un parser robusto es cuestión de minutos. El mantenimiento también es más sencillo cuando la gramática está separada del código.

3. Precisión Decimal

Usar shopspring/decimal en lugar de float64 fue crucial para manejar correctamente valores financieros y médicos donde la precisión importa.

4. Inmutabilidad para Concurrencia

Mantener las expresiones compiladas inmutables permite compartirlas entre goroutines sin sincronización adicional. Este diseño es crucial en aplicaciones de servidor.

Conclusión

Construir una implementación de FHIRPath en Go fue un proyecto desafiante pero extremadamente educativo. La combinación de ANTLR para el parsing, el sistema de tipos de Go para la seguridad, y un diseño orientado a colecciones resultó en una librería robusta y fácil de usar.

El proyecto está disponible en GitHub y acepta contribuciones. Si trabajas con FHIR® y Go, espero que esta librería te sea útil.

Referencias

¿Tienes preguntas o sugerencias? Déjalas en los comentarios o abre un issue en el repositorio.

Tags: #go #golang #fhir #healthcare #fhirpath #parser #antlr #opensource

DEV Community: Gophers CL

SaaS Multi-Tenant en Go: Guia Practica de Row-Level Security en PostgreSQL

Por que RLS?

Arquitectura

Paso 1: El Package de Contexto de Tenant

Paso 2: HTTP Middleware

Paso 3: Schema de Base de Datos

Diseno de indices

Paso 4: RLS Policies

Automatizando en Go

Paso 5: El Patron tenantQuerier — SET LOCAL

Por que SET LOCAL y no SET?

Por que transacciones read-only?

Paso 6: Usando el Patron

Lectura

Escritura

Listado

Paso 7: Patron Repository (Produccion)

Analisis de Seguridad

Modelo de amenazas

Garantia fail-closed

Rendimiento

Testing

Aislamiento basico

Aislamiento concurrente

5 Errores Comunes

1. SET en vez de SET LOCAL

2. Olvidar FORCE ROW LEVEL SECURITY

3. No parametrizar SET LOCAL

4. tenant_id al final en indices

5. Olvidar defer done()

Resumen

Migrando de Supabase a una arquitectura full Go: La poesía de los binarios estáticos

El contexto

La arquitectura resultante

¿Por qué esto es especial?

1. Binarios estáticos

2. Consumo de recursos mínimo

3. Configuración declarativa

4. El mismo idioma mental

GoTrue: El corazón de la autenticación

Caddy: TLS sin dolor

Alloy: Observabilidad moderna

El flujo de autenticación

Costos

Lo que aprendimos

1. Self-hosted no significa complejo

2. Go es infraestructura

3. Supabase hizo bien su trabajo

4. La cohesión tiene valor

Recursos

Conclusión

FHIRPath en Go: Cómo Construí un Motor de Consultas para Interoperabilidad en Salud

Construyendo una Librería FHIRPath en Go: Del Concepto a la Implementación

Introducción

¿Qué es FHIR®?

Características Principales de FHIR®

¿Qué es FHIRPath?

Ejemplos de Expresiones FHIRPath

Arquitectura de la Librería

Visión General

Principios de Diseño

1. Separación de Responsabilidades

2. Inmutabilidad

Implementación del Lexer y Parser con ANTLR

¿Por qué ANTLR?

Definición de la Gramática

Generación del Código Go

Sistema de Tipos

Tipos Implementados

Implementación de Decimal con Precisión Arbitraria

Collections: El Corazón de FHIRPath

Métodos Principales de Collection

El Evaluador

Contexto de Evaluación

Implementación del Visitor

Funciones Built-in

Resumen de Funciones por Categoría

Funciones Clave para Interoperabilidad

where() - Filtrado con Criterios

Por que `SET LOCAL` y no `SET`?

1. `SET` en vez de `SET LOCAL`

2. Olvidar `FORCE ROW LEVEL SECURITY`

3. No parametrizar `SET LOCAL`

4. `tenant_id` al final en indices

5. Olvidar `defer done()`