O modelo em resumo
Conexões
Uma conexão guarda o tipo de fonte de dados, o host, a porta, o nome do banco, as credenciais e as configurações TLS opcionais de um banco de dados externo. Um
configName curto a identifica dentro do tenant, e toda chamada de job e de esquema endereça a fonte de dados por esse nome.
O Fetcher criptografa a senha com AES-256-GCM antes de ela chegar ao armazenamento. O registro armazenado também guarda a versão da chave que a protegeu. Uma conexão nunca volta para quem chama com a senha.
Leia Conexões para o ciclo de vida completo, o teste de conexão e a regra que bloqueia uma atualização ou uma exclusão enquanto ainda há jobs em execução.
Tipos de fonte de dados
Uma conexão declara um de cinco tipos. Envie o valor em maiúsculas: a validação da requisição compara exatamente essas cinco cadeias e rejeita qualquer outra capitalização com
400.
POSTGRESQLMYSQLORACLESQL_SERVERMONGODB
Esquemas
Um snapshot de esquema lista as tabelas de uma fonte de dados e os campos de cada tabela. O Fetcher o constrói diretamente da fonte de dados, então você não mantém um catálogo separado. Duas coisas se apoiam em um snapshot. A validação de esquema confere o mapeamento de um job contra ele antes de a extração começar. O cache de esquema guarda um snapshot recente sob o tenant e o nome da configuração, então trabalhos repetidos pulam a ida ao banco de dados. Leia Descoberta de esquema para o comportamento ao vivo versus em cache, as diferenças por banco de dados e o relatório de validação.
Jobs de extração
Um job nomeia os campos a extrair, por tabela, por fonte de dados:
["*"] para levar todos os campos de uma tabela.
O Manager aceita um job e responde 202 Accepted. Uma requisição repetida dentro de uma janela de cinco minutos responde 200 OK e retorna o job que já existe. Um job que falhou não impede uma nova tentativa.
Os limites do Engine delimitam o trabalho de fontes de dados genéricas. Os padrões permitem 10 fontes de dados por extração, 20 tabelas por fonte de dados, 50 campos por tabela e um prazo de cinco minutos. Quem incorpora o Engine pode reduzir, mas nunca elevar, esses limites com ExtractionRequest.Overrides. O payload de jobs do Manager autônomo não possui campo de override de limites, e o Worker aceita apenas um override positivo de ENGINE_MAX_RESULT_BYTES. A parte plugin_crm usa o caminho explícito de compatibilidade do Worker.
Filtros
Um filtro restringe as linhas de uma tabela. O payload do job aninha os filtros em quatro níveis: fonte de dados, depois tabela, depois campo, depois operador.
eq, ne, gt, gte, lt, lte, between, in, nin e like. Todo operador recebe um array JSON. Vários operadores sobre o mesmo campo se combinam com AND.
Resultados
Uma extração produz exatamente um formato de resultado. No modo direct, o Engine retorna as linhas inline como JSON indentado e carimba um digest SHA-256 sobre esses bytes. O payload sai do Engine sem criptografia, e o hospedeiro decide o que fazer em seguida. No modo store, o Engine envia as linhas em stream para um sink que o hospedeiro fornece, um objeto JSON por linha. Ele retorna uma referência em vez dos bytes, com um digest SHA-256 sobre exatamente os bytes gravados. O Engine não mantém nenhum resultado completo em memória nesse caminho. Cada modo faz o hash do que emite: o modo direct, do documento indentado; o modo store, das linhas transmitidas. O Engine canoniza a ordem planejada de campos e etapas antes da serialização. Um digest identifica os bytes exatos emitidos por aquela execução; não o trate como garantia de equivalência entre execuções, a menos que a ordem da consulta à fonte de dados e todo o processamento do hospedeiro estejam controlados. Os dois modos gravam formatos diferentes, então compare um digest apenas com outro digest do mesmo modo. O runner genérico do Engine interrompe-se na primeira etapa que falha e não retorna um resultado direto bem-sucedido. Hospedeiros definem o próprio comportamento para caminhos de compatibilidade ou de orquestração em múltiplas etapas. O Worker autônomo conduz o modo direct. Ele então assina o texto claro com HMAC-SHA256, o criptografa com AES-GCM e o grava em object storage compatível com S3. Veja Arquitetura.
Engine e hospedeiros
O Engine é a parte do Fetcher que é dona do ciclo de vida da conexão, da descoberta de esquema, do planejamento de consultas, da extração, dos limites e da segurança por tenant. Ele é distribuído como um módulo Go próprio, sem dependências de terceiros, e fala com o mundo externo apenas por portas que um hospedeiro fornece. Um hospedeiro fornece essas portas e é dono de tudo que o Engine se recusa a conhecer: HTTP, filas, object storage, autenticação e o ciclo de vida do job. O Manager e o Worker são dois desses hospedeiros. A sua própria aplicação pode ser um terceiro. Leia Arquitetura para os dois serviços, as portas e o que cada lado possui.
Tenants
O ID de tenant é a única fronteira de isolamento no Engine. Não há conceito de organização nem conceito de produto abaixo dele. Toda operação valida o tenant antes de tocar em uma conexão, em uma entrada de cache ou em uma fonte de dados. O modo single-tenant é o padrão. O modo multi-tenant dá a cada tenant o próprio banco de metadados, que o Fetcher resolve a partir das claims do JWT. Sem um banco de tenant no contexto, a chamada falha. Ela nunca cai de volta para o banco compartilhado. Veja Multi-tenancy para o modelo da plataforma.
Próximos passos
Arquitetura
O Manager, o Worker e o Engine sobre o qual os dois rodam.
Conexões
Registre, teste, atualize e exclua uma conexão com uma fonte de dados.
Descoberta de esquema
Como o Fetcher lê um esquema, o mantém em cache e valida um job contra ele.
Primeiros passos
Rode o Fetcher localmente e execute seu primeiro job de extração.