Primeiros passos com o Fetcher

Existem duas formas de ver o Fetcher funcionando. Escolha uma.

Caminho	O que custa	O que prova
A — Engine embarcado	Um `go get`. Nenhuma infraestrutura.	As regras de extração, o planejamento, os limites e o resultado em modo direct.
B — Serviços autônomos	Docker Compose. MongoDB, RabbitMQ, storage, Valkey.	A API REST, os jobs assíncronos e os resultados armazenados.

O caminho A é a rota mais curta até um primeiro sucesso. Comece por ele se você só quer avaliar o produto.

Caminho A — Rode o Engine sem infraestrutura

O Engine traz um harness em memória em pkg/engine/memory. Ele cobre as 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, de RabbitMQ nem de object storage. Ele não traz um CredentialProtector, então, se você ligar a persistência criptografada, precisa fornecer o seu.

Adicione o módulo

go get github.com/LerianStudio/fetcher/pkg/engine

O Engine é um módulo separado dos serviços. Ele não tem dependências de terceiros, então esse import não traz mais nada junto.

Construa, planeje, execute

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/LerianStudio/fetcher/pkg/engine"
	"github.com/LerianStudio/fetcher/pkg/engine/memory"
)

func main() {
	ctx := context.Background()

	store := memory.NewConnectionStore()
	registry := memory.NewConnectorRegistry()

	// WithConnectorRegistry is the only required option.
	eng, err := engine.New(
		engine.WithConnectorRegistry(registry),
		engine.WithConnectionStore(store),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Every operation is scoped to a tenant.
	tenant, err := engine.NewTenantContext("tenant-123")
	if err != nil {
		log.Fatal(err)
	}

	conn := memory.NewTemplateConnector(memory.ConnectorBehavior{
		Schema: engine.SchemaSnapshot{
			ConfigName: "pg-main",
			Tables:     []engine.TableSnapshot{{Name: "public.users", Fields: []string{"id", "email"}}},
		},
		Rows: map[string][]map[string]any{
			"public.users": {{"id": 1, "email": "a@example.com"}},
		},
	})
	registry.Register("postgres", memory.NewConnectorFactory(conn))

	if _, err = eng.CreateConnection(ctx, tenant, engine.NewConnectionInput(engine.ConnectionInputParams{
		ConfigName: "pg-main",
		Type:       "postgres",
		Host:       "localhost",
		Port:       5432,
	})); err != nil {
		log.Fatal(err)
	}

// Plan validates the request against a cache-first schema snapshot and enforces limits.
	plan, err := eng.PlanExtraction(ctx, tenant, engine.ExtractionRequest{
		MappedFields: map[string]engine.FieldSelection{
			"pg-main": {"public.users": {"id", "email"}},
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	result, err := eng.ExecuteExtraction(ctx, plan)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("rows=%d bytes=%d\n", result.Direct.RowCount, len(result.Direct.Data))
}

Leia o resultado

Nenhum destino de resultado está configurado aqui, então o Engine roda em modo direct. Ele devolve as linhas inline como JSON indentado, mais um digest SHA-256 sobre esses bytes exatos. Os bytes são determinísticos: a mesma entrada sempre produz o mesmo digest.

Para ir à produção, troque o harness em memória pelos seus próprios adaptadores. O Manager e o Worker do próprio Fetcher são a implementação de referência.

Caminho B — Rode os serviços autônomos

Este caminho entrega a API REST e os jobs assíncronos. Tudo roda localmente com Docker Compose.

Pré-requisitos

Docker e Docker Compose
Make
Go, apenas para desenvolvimento. A versão do toolchain está no go.mod do repositório.

Configurar e rodar

Clone o repositório

git clone https://github.com/LerianStudio/fetcher.git
cd fetcher

Crie os arquivos de ambiente

make set-env

Isso copia o .env.example de cada componente para .env.

Gere a chave-mestra de criptografia

make generate-master-key

Copie a chave para APP_ENC_KEY em ambos components/manager/.env e components/worker/.env. Os dois serviços precisam do mesmo valor. O Worker a usa para descriptografar credenciais e para conferir assinaturas de mensagens.

Substitua o placeholder antes de iniciar: use uma chave válida de 32 bytes codificada em Base64. O placeholder criado por make set-env falha ao decodificar uma chave-mestra Base64 inválida. A mensagem master key too short: got 0 bytes, minimum 32 required corresponde a um valor vazio ou curto que decodifica. O Fetcher não tem modo de fallback em texto claro.

Suba tudo

make up

Verifique se a API responde

API REST: http://localhost:4006
Referência da API no Scalar, quando SWAGGER_ENABLED=true: http://localhost:4006/swagger/docs
Gerenciamento do RabbitMQ: http://localhost:3008

Execute sua primeira extração

Uma extração tem três movimentos. Registre uma conexão, crie um job e depois consulte o job.

1. Registre uma conexão de banco de dados

curl -X POST http://localhost:4006/v1/management/connections \
  -H "Content-Type: application/json" \
  -H "X-Product-Name: quickstart" \
  -d '{
    "configName": "my_postgres",
    "type": "POSTGRESQL",
    "host": "host.docker.internal",
    "port": 5432,
    "databaseName": "mydb",
    "userName": "postgres",
    "password": "postgres"
  }'

O header X-Product-Name nomeia o produto dono da conexão. Use o mesmo valor em metadata.source do job no passo 2, porque o Fetcher compara os dois. O Fetcher criptografa a senha antes de gravar o registro. Teste a conexão antes de usá-la:

curl -X POST http://localhost:4006/v1/management/connections/{id}/test

2. Crie um job de extração

Nomeie os campos que você quer, por tabela, por fonte de dados:

curl -X POST http://localhost:4006/v1/fetcher \
  -H "Content-Type: application/json" \
  -d '{
    "dataRequest": {
      "mappedFields": {
        "my_postgres": {
          "accounts": ["id", "email", "created_at"]
        }
      }
    },
    "metadata": {
      "source": "quickstart"
    }
  }'

A API responde 202 Accepted com um ID de job. Envie a mesma requisição duas vezes dentro de 5 minutos e você recebe 200 OK com o primeiro job, em vez de um segundo. Um job que falhou não bloqueia uma nova tentativa.

3. Consulte o job

curl http://localhost:4006/v1/fetcher/{id}

Um job termina em um de dois estados terminais: completed ou failed. Na conclusão, o Worker já criptografou o resultado no object storage e publicou um evento job.completed. Os dois estados anteriores são pending e processing. Jobs de extração traz o ciclo de vida completo de quatro estados.

Ligue a autenticação com PLUGIN_AUTH_ENABLED=true. As requisições passam então a carregar um header Authorization: Bearer <token>. Este quickstart roda com a autenticação desligada.

Próximos passos

Conceitos centrais

Conexões, descoberta de esquema, jobs, filtros e resultados.

Configuração

Cada variável de ambiente, por componente.

Implantação

Dependências, filas, escala e as checagens fail-closed de inicialização.

Segurança

Derivação de chaves, rotação, assinatura de mensagens e validação de host.

Visão geral