engine.New.
Esta página é a referência das oito. A coluna Sem ela é o ponto central da página. A degradação controlada é o contrato com o qual você planeja, então leia-a antes de pular uma porta.
As portas em resumo
engine.New rejeita uma porta passada como nil tipado, e não apenas um nil literal. Um valor de interface que envolve um ponteiro nulo falha na construção com um erro de validação claro, em vez de quebrar no primeiro uso.ConnectorRegistry
Obrigatória: sempre. Esta é a única porta que o Engine valida incondicionalmente. O registro resolve uma factory de conector pelo tipo de fonte de dados. Ele não faz I/O, resolve de forma determinística pelo tipo e reporta
ok=false para um tipo que ninguém registrou. Construir e conectar um conector acontece depois, pela factory que ele retornou.
Sem ela: engine.New retorna um erro de validação com a mensagem connector registry is required. Você não obtém valor de Engine algum, então a extração é impossível.
CredentialProtector
Obrigatória: apenas com
WithEncryptedPersistence(true).
O protetor criptografa e descriptografa material de credencial para um tenant. A chamada Protect retorna os bytes protegidos mais a versão da chave que os protegeu. A chamada Reveal descriptografa com uma dada versão de chave, para que o seu hospedeiro possa resolver uma chave rotacionada.
O seu hospedeiro é dono da derivação, da rotação e do armazenamento de chaves. O Engine apenas chama o ponto de extensão e registra a versão de chave retornada como metadado livre de segredos.
Sem ela:
- Com a persistência criptografada ligada,
engine.Newfalha comcredential protector is required when encrypted persistence is enabled. O Engine se recusa a construir em vez de persistir credenciais em texto claro. - Com a persistência criptografada desligada, a porta é genuinamente opcional, e as credenciais chegam ao
ConnectionStoresem proteção.
ConnectionStore
Obrigatória: opcional na construção, indispensável em tempo de execução. O armazenamento persiste e resolve descritores de conexão que pertencem a um tenant. Ele é o único ponto de persistência que as operações de conexão usam — o Engine não embute MongoDB, nem SQL, nem repositório do hospedeiro. Ele expõe nove operações: create, find, find-by-id, update, update-by-id, delete, delete-by-id, list e list-paged. Duas obrigações recaem sobre a sua implementação. Ela precisa escopar todo registro pelo ID de tenant, para que um tenant nunca veja as conexões de outro. Ela não pode retornar material secreto — o descritor de conexão não carrega nenhum. Sem ela:
engine.New tem sucesso, e depois quase tudo falha. Toda operação que toca uma conexão retorna o erro de validação connection store is not configured. Isso cobre as nove operações de conexão mais planejar, executar, descobrir esquema, descoberta de esquema sempre atualizada, validar esquema e testar conexão. Um Engine sem armazenamento de conexões consegue reportar apenas os próprios limites.
ExecutionStore
Obrigatória: opcional. O armazenamento faz upsert do estado do ciclo de vida da execução para um tenant. O Engine escreve as transições de forma síncrona e inline:
running, depois completed, failed ou canceled.
Essas escritas são best-effort por desenho. O Engine descarta um erro de gravação, para que a persistência opcional nunca corrompa um resultado de extração. Uma falha de escrita no result sink se comporta de outra forma e realmente faz a execução falhar. As duas são deliberadamente distintas.
Sem ela: o Engine roda sem rastreamento durável de execução, e o seu hospedeiro é dono do estado de execução externamente.
ResultSink
Obrigatória: opcional. Ela seleciona o modo de resultado. O sink persiste os payloads de resultado no storage gerenciado pelo hospedeiro. A extração em modo store chama
OpenResultStream, de modo que o Engine escreve o resultado de forma incremental, com memória constante. PersistResult continua disponível para escritas do payload inteiro.
O formato do stream é NDJSON contratual — um objeto JSON por linha, terminado por quebra de linha, sem array envolvente:
Close. Trate um escritor não fechado como uma escrita descartada, porque um resultado parcial nunca pode virar uma referência retornada.
Sem ela: o modo store fica indisponível. O modo padrão auto resolve para direct, então a extração retorna bytes inline e não persiste nada. Um pedido explícito de modo store falha logo no início com store mode requires a configured result sink, antes de o Engine construir qualquer conector.
SchemaCache
Obrigatória: opcional. O cache guarda e devolve snapshots de esquema por tenant e por nome de configuração. O Engine o trata como um acelerador, nunca como fonte da verdade. Uma leitura de cache que falha degrada para descoberta ao vivo. Uma escrita de cache que falha ainda assim devolve o esquema descoberto a quem chamou. A chamada de descoberta sempre atualizada ignora o cache em toda invocação, mesmo quando você ligou um, para que o contrato de fonte de dados ao vivo do endpoint de esquema do Manager se mantenha. Sem ela: o Engine descobre o esquema ao vivo na fonte de dados a cada chamada.
ActiveExecutionChecker
Obrigatória: opcional. O verificador informa se uma conexão tem execuções ativas no momento. O Engine o consulta antes de mutar uma conexão. Um hospedeiro pode, assim, manter o comportamento do Manager, que bloqueia uma mudança enquanto há jobs rodando contra aquela conexão. A porta é deliberadamente lógica, e não um armazenamento durável de jobs. O seu hospedeiro decide como responder: um repositório de jobs, um rastreador em memória, um lock distribuído ou sempre falso. O Engine nunca importa um repositório de jobs para fazer a pergunta. A identidade de conexão que ele passa é o nome da configuração dentro do escopo do tenant. A sua resposta precisa ter escopo de tenant, para que o trabalho em andamento de um tenant nunca bloqueie a mutação de outro. Sem ela: o Engine não faz bloqueio por conflito, e atualizações e exclusões de conexão seguem adiante incondicionalmente.
Observability
Obrigatória: opcional. O contrato tem um único método.
StartSpan recebe um contexto e um nome de operação, e retorna um contexto derivado mais uma função de encerramento que o Engine adia. Um único método é justamente o ponto: o núcleo do Engine nunca importa uma biblioteca de tracing, e o seu hospedeiro adapta o próprio tracer por trás desse ponto de extensão.
Sem ela: a criação de span retorna o contexto recebido e uma função de encerramento no-op. Os ganchos de tracing desaparecem sem nenhuma outra mudança de comportamento.
Próximos passos
Incorporar o Engine
Importe, forneça as portas e construa com um exemplo executável.
Visão geral do Engine
O modelo de três camadas, a fronteira de importação e os dois modos de resultado.