A lane de Fonte de dados

O Node tem quatro lanes HTTP. Três já eram conhecidas; a Fonte de dados é a quarta, e é a única em que o mundo externo lê do Supreme.

Um módulo publica um conjunto de dados; um consumidor autenticado — hoje o Google Ads Data Manager — busca esse conjunto sozinho, no ritmo dele. Nada é empurrado daqui para fora.

A rota tem esta forma:

GET /data/{slug}/{source_id}/{action}.{ext}

slug é o módulo, source_id é um identificador opaco da fonte, action é a ação de dados que o módulo declara e ext é a extensão que ele escolhe. A extensão é parte do contrato porque alguns consumidores recusam URLs sem ela.

O que o núcleo garante

O núcleo do Node é dono da lane e não sabe o que os dados significam. Ele garante:

• Resolução da rota por identificador opaco. O source_id não é derivado do id da Propriedade nem de nada adivinhável.
• HTTP Basic com comparação em tempo constante, credencial por fonte, rotacionável sem trocar a URL.
• Checagem de estado em cadeia — módulo, Propriedade, conexão e fonte precisam estar ativos. Uma fonte pausada responde sem servir dados.
• Guardrails: teto de linhas, teto de bytes, teto de tempo de execução, intervalo mínimo entre leituras e limite da janela histórica. O que estoura o teto é cortado de forma explícita e sinalizada, não truncado em silêncio.
• Streaming da resposta, para que o custo de memória não cresça com o tamanho do conjunto.
• Um formato de erro uniforme, que não revela o schema nem distingue "não existe" de "não autorizado".
• Telemetria de leitura: quando foi buscado, quantas linhas, quantos bytes, quanto tempo.

O que o módulo decide

Tudo o que é específico da plataforma:

• qual é o conjunto de dados e qual consulta o produz;
• qual é a janela de tempo;
• o formato de saída e a extensão do arquivo;
• a normalização dos valores e o que é hasheado antes de sair;
• a ordem e o nome das colunas;
• o contrato do destino, incluindo o que aquele destino considera uma linha válida.

O núcleo conhece lanes; o módulo conhece plataformas. Essa é a mesma fronteira que vale para webhooks e para encaminhamento, aplicada agora à leitura.

Uma fonte lê uma Propriedade

Uma fonte lê exatamente uma Propriedade, e esse escopo vem da linha da fonte gravada no Node. Não existe parâmetro de requisição que amplie o escopo — nem query string, nem cabeçalho, nem caminho. Quem tem a credencial de uma fonte lê o que aquela fonte foi criada para publicar, e nada além.

Isto não é uma API de consulta

O consumidor escolhe uma fonte. Ele não escolhe Propriedade, evento, janela, colunas, ordenação, filtro nem formato. Tudo isso é fixado no momento da criação, dentro do Console, por quem tem a chave mestra do Node.

Isso é uma fronteira deliberada, não uma funcionalidade faltando. A superfície pública da lane é uma URL que devolve um conjunto de dados decidido de antemão — o que mantém a credencial de longa duração que mora dentro da plataforma de destino com o menor poder possível.

Uma plataforma nova custa um módulo, não um release

A descoberta de capacidade é feita pelo manifesto do módulo. Nenhum slug de plataforma está escrito no núcleo, e nenhum if de plataforma existe na lane.

Consequências práticas:

• um módulo que não declara a capacidade não é afetado por nada disto e não precisa de release;
• publicar dados para uma plataforma nova é escrever um módulo, com o próprio versionamento e o próprio ciclo de publicação;
• o núcleo do Node não precisa subir de versão para que uma plataforma nova passe a ser servida.

A fronteira de observabilidade

Modelo de busca significa nenhum retorno sobre o que o consumidor fez com os dados. O Supreme reporta o que serviu: quando, quantas linhas, quantos bytes, em quanto tempo. Não existe canal por onde o destino informe o que processou, o que descartou e por quê — não é uma lacuna de implementação, é a forma da lane.

Quem precisa de confirmação por evento precisa de uma lane de envio, com uma API que devolva identificador de requisição e avisos por campo. Isso é outro produto: OAuth, projeto na nuvem por cliente, credenciais por conta e uma superfície de erro completamente diferente.

A lane de busca troca essa visibilidade por algo que ela faz melhor do que qualquer outra: funciona com nada além de uma URL e uma senha copiadas para dentro da plataforma de destino, sem infraestrutura nenhuma do lado de quem opera o Node.

O manual de operação do primeiro consumidor desta lane: Conecte o Google Ads Data Manager.