Skip to main content
Incorporar o Fetcher Engine leva três passos: importe, forneça as portas de que ele precisa, construa com engine.New. Nenhuma infraestrutura vem junto com a importação. Você liga apenas as partes que a sua aplicação hospedeira realmente usa.

1. Instalar


O Engine é um módulo Go distinto dos serviços do Fetcher (github.com/LerianStudio/fetcher/v2). Ele carrega zero dependências de terceiros e tem sua própria linha de versões, com tags prefixadas pelo caminho (pkg/engine/vX.Y.Z). A importação não traz nenhuma dependência dos serviços para o grafo do seu módulo.

2. Fornecer as portas


O Engine depende apenas de interfaces fornecidas pelo hospedeiro. Uma porta é sempre obrigatória. Uma segunda é obrigatória apenas quando a persistência criptografada está ligada. As demais são opcionais, e o Engine degrada de forma controlada sem elas. A referência de portas documenta cada contrato e cada degradação por completo. Leia-a antes de decidir quais portas pular — “opcional” não quer dizer “inofensivo”. Para testes e primeiras execuções, o harness pkg/engine/memory fornece implementações em memória das portas de armazenamento: o registro de conectores, o connection store, o cache de esquemas, o result sink e o execution store. Você não precisa de MongoDB, Redis, RabbitMQ nem object storage para exercitar o Engine. O harness não traz um CredentialProtector, então um teste que ligue a persistência criptografada precisa fornecer um.

3. Construir, planejar, executar


Este exemplo é autocontido. Ele usa o harness em memória, então roda com zero infraestrutura.

O que o exemplo mostra

  • Uma única opção obrigatória. WithConnectorRegistry é a única porta que engine.New exige. O armazenamento de conexões aqui é uma conveniência, mas pule-o e toda operação falha.
  • Validação no momento da construção. engine.New rejeita uma porta passada como nil tipado, e não apenas um nil literal. Um hospedeiro mal configurado falha na construção, em vez de quebrar no primeiro uso.
  • Escopo de tenant em toda chamada. NewTenantContext monta a única dimensão de isolamento que o Engine conhece. Ela carrega um ID de tenant e um ID de requisição opcional — sem organização e sem produto.
  • Planejar, depois executar. PlanExtraction valida a requisição contra o esquema ao vivo e aplica os limites. ExecuteExtraction lê o plano.
  • Modo por composição. O exemplo não liga nenhum ResultSink, então o Engine escolhe o modo direct e retorna os bytes inline com um digest SHA-256. Adicione um sink e o mesmo código retorna uma referência de storage. Veja Modo Direct e modo Store.

Indo para produção


Troque o harness em memória pelos adaptadores reais. Os próprios serviços do Fetcher são a implementação de referência, e o código deles é público. Eles fazem a ponte entre as portas do Engine e a infraestrutura real, em pkg/enginecompat: Veja como os serviços os ligam:
  • CRUD de conexõescomponents/manager/internal/bootstrap/connection_engine.go
  • Descoberta e cache de esquemacomponents/manager/internal/bootstrap/schema_engine.go
  • Planejar e executar a extraçãocomponents/worker/internal/bootstrap/extraction_engine.go
Duas regras valem do harness até a produção:
  1. Os seus adaptadores são donos do escopo de tenant. O Engine passa um contexto de tenant em toda chamada de porta e impõe a fronteira na própria borda. Um armazenamento que ignora o ID de tenant vaza dados entre tenants, e o Engine não consegue pegar isso por você.
  2. Os seus adaptadores são donos dos segredos. O Engine chama Protect e Reveal e registra apenas a versão de chave retornada como metadado. Derivação, rotação e armazenamento de chaves ficam no seu hospedeiro.

Próximos passos


Referência de portas

Cada porta, seu contrato e o comportamento que você tem sem ela.

Visão geral do Engine

O modelo de três camadas, a fronteira de importação e os dois modos de resultado.