Skip to main content
Embeber el Fetcher Engine toma tres pasos: impórtalo, provee los puertos que necesita, constrúyelo con engine.New. La importación no trae infraestructura. Conectas solo las partes que tu aplicación anfitriona usa de verdad.

1. Instala


El Engine es un módulo Go distinto de los servicios de Fetcher (github.com/LerianStudio/fetcher/v2). Lleva cero dependencias de terceros y tiene su propia línea de versiones, con tags prefijados por ruta (pkg/engine/vX.Y.Z). La importación no aporta al grafo de tu módulo ninguna dependencia de los servicios.

2. Provee los puertos


El Engine depende solo de interfaces que provee el host. Un puerto es siempre obligatorio. Un segundo lo es solo cuando la persistencia cifrada está activada. El resto son opcionales, y el Engine degrada de forma controlada sin ellos. La referencia de puertos documenta cada contrato y cada degradación en detalle. Léela antes de decidir qué puertos omitir — “opcional” no significa “inofensivo”. Para tests y primeras corridas, el harness pkg/engine/memory provee implementaciones en memoria de los puertos de almacenamiento: el registro de conectores, el connection store, la caché de esquemas, el result sink y el execution store. No necesitas MongoDB, Redis, RabbitMQ ni object storage para ejercitar el Engine. El harness no incluye un CredentialProtector, así que un test que active la persistencia cifrada debe aportar uno.

3. Construye, planifica, ejecuta


Este ejemplo es autocontenido. Usa la implementación en memoria, así que corre con cero infraestructura.

Qué muestra el ejemplo

  • Una sola opción obligatoria. WithConnectorRegistry es el único puerto que engine.New exige. El almacén de conexiones aquí es una comodidad, pero si lo omites toda operación falla.
  • Validación en tiempo de construcción. engine.New rechaza un puerto pasado como nil tipado, no solo como nil literal. Un host mal configurado falla en la construcción en lugar de entrar en pánico en el primer uso.
  • Alcance por tenant en cada llamada. NewTenantContext construye la única dimensión de aislamiento que el Engine conoce. Lleva un tenant ID y un request ID opcional — ninguna organización y ningún producto.
  • Primero planifica, después ejecuta. PlanExtraction valida la petición contra el esquema en vivo y aplica los límites. ExecuteExtraction lee el plan.
  • El modo sale de la composición. El ejemplo no conecta ningún ResultSink, así que el Engine elige el modo Direct y devuelve los bytes inline con un digest SHA-256. Agrega un sink y el mismo código devuelve una referencia de storage. Consulta Modo Direct y modo Store.

Pasar a producción


Cambia la implementación en memoria por adaptadores reales. Los propios servicios de Fetcher son la implementación de referencia, y su código fuente es público. Ellos conectan los puertos del Engine a infraestructura real bajo pkg/enginecompat: Lee cómo los conectan los servicios:
  • CRUD de conexionescomponents/manager/internal/bootstrap/connection_engine.go
  • Descubrimiento y caché de esquemascomponents/manager/internal/bootstrap/schema_engine.go
  • Planificar y ejecutar extraccionescomponents/worker/internal/bootstrap/extraction_engine.go
Dos reglas pasan de la implementación en memoria a producción:
  1. Tus adaptadores son dueños del alcance por tenant. El Engine pasa un contexto de tenant a cada llamada de puerto y aplica el límite en su propio borde. Un almacén que ignora el tenant ID filtra datos entre tenants, y el Engine no puede detectarlo por ti.
  2. Tus adaptadores son dueños de los secretos. El Engine llama a Protect y Reveal y registra solo la versión de clave devuelta como metadato. La derivación, la rotación y el almacenamiento de claves se quedan en tu host.

Próximos pasos


Referencia de puertos

Cada puerto, su contrato y el comportamiento que obtienes sin él.

Visión general del Engine

El modelo de tres capas, la frontera de importación y los dos modos de resultado.