YRN é uma plataforma de orquestração de serviços distribuída construída em Go, projetada para gerenciar fluxos de trabalho baseados em plugins com descoberta dinâmica de serviços e validação de esquemas JSON.

• Visão Geral
• Arquitetura
• Componentes Principais
• Plugins Disponíveis
• Instalação e Uso
• Configuração
• Desenvolvimento
• API Reference

YRN oferece uma arquitetura de microserviços com os seguintes recursos principais:

• Descoberta de Serviços: Integração com HashiCorp Consul para registro e descoberta automática
• Sistema de Plugins: Arquitetura extensível com plugins para HTTP, Google Drive e autenticação OAuth
• Validação de Esquemas: Validação automática de entrada/saída usando JSON Schema
• Flow Manager: Sistema de orquestração de workflows com execução sequencial e paralela
• Multi-tenancy: Suporte nativo para múltiplos inquilinos
• Observabilidade: Métricas, logging e health checks integrados

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│     Agent       │    │   Connector     │    │      API        │
│   (Discovery)   │◄──►│  (Validation)   │◄──►│   (Interface)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────▼───────────────────────┘
                           ┌─────────────┐
                           │   Consul    │
                           │ (Registry)  │
                           └─────────────┘

Camada de Serviços (cmd/)

• agent - Serviço de descoberta e agregação de esquemas
• connector - Serviço de validação baseado em JSON Schema
• api - API HTTP básica com endpoints de saúde

Bibliotecas Compartilhadas (pkg/)

• ybase - Framework core com registro no Consul e health checks
• ylog - Utilitários de logging estruturado
• yctx - Gerenciamento de contexto
• plugin* - Implementações de plugins (HTTP, Google Drive, etc.)

Lógica de Negócio (internal/)

• producer - Produção de mensagens/eventos
• database - Adaptadores para MongoDB e PostgreSQL
• adapter - Adaptadores para serviços externos
• externalservice - Integrações com serviços externos

Módulos de Domínio (module/)

• flowmanager - Gerenciamento de workflows e execução de plugins
• team - Gerenciamento de equipes
• tenant - Multi-tenancy
• project - Gerenciamento de projetos

O Flow Manager é o coração do sistema de orquestração:

type Flow struct {
    Id               string       `json:"id"`
    Name             string       `json:"name"`
    Description      string       `json:"description"`
    Tenant           string       `json:"tenant"`
    FirstPluginToRun string       `json:"first_plugin_to_run"`
    Plugins          []FlowPlugin `json:"plugins"`
    Version          int          `json:"version"`
}

Características:

• Execução sequencial e condicional de plugins
• Compartilhamento de dados entre plugins
• Tratamento de erros configurável
• Versionamento de fluxos
• Suporte multi-tenant

Todos os plugins implementam a interface PluginExecutor:

type PluginExecutor interface {
    Do(ctx *yctx.Context, schemaInputs string, previousPluginResponse any, responseSharedForAll map[string]any) (output any, err error)
}

Validação de Esquemas: Cada plugin possui um esquema JSON que define:

• Parâmetros de entrada obrigatórios e opcionais
• Tipos de dados aceitos
• Validações customizadas
• Documentação integrada

Funcionalidade: Executa requisições HTTP configuráveis com suporte a retry e timeout.

Schema:

{
  "request": {
    "method": "POST|GET|PUT|DELETE|PATCH|HEAD|OPTIONS",
    "url": "https://api.exemplo.com/endpoint",
    "headers": {"Authorization": "Bearer {{.data.token}}"},
    "body": "Dados da requisição"
  },
  "retry": {
    "maxAttempts": 3,
    "delay": 1000
  }
}

Recursos:

• Suporte a todos os métodos HTTP
• Headers e query parameters customizáveis
• Template engine para dados dinâmicos
• Sistema de retry configurável
• Timeout personalizável

Funcionalidade: Autentica com Google OAuth2 e obtém tokens de acesso.

Schema:

{
  "client_id": "seu-client-id.googleusercontent.com",
  "client_secret": "seu-client-secret",
  "code": "authorization-code-from-oauth-flow",
  "redirect_uri": "http://localhost:8080/callback"
}

Recursos:

• Implementa fluxo OAuth2 Authorization Code
• Integração com Google APIs
• Tratamento automático de erros de autenticação
• Retorna access_token e refresh_token

Funcionalidade: Integração completa com Google Drive para listagem e download de arquivos.

Schema:

{
  "credentials": "json-da-conta-de-servico",
  "folderId": "id-da-pasta-no-drive",
  "sharedDriveId": "id-do-shared-drive"
}

Recursos:

• Autenticação via Service Account
• Listagem de arquivos por pasta
• Download automático de conteúdo
• Suporte a Shared Drives
• Metadados completos (nome, tipo, data de modificação)
• Filtros por tipo de arquivo

Exemplo de Saída:

[
  {
    "id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "name": "documento.pdf",
    "mimeType": "application/pdf",
    "content": "conteúdo-do-arquivo-em-base64"
  }
]

• Go 1.23+
• Docker e Docker Compose
• HashiCorp Consul (incluído no docker-compose)

# Clone o repositório
git clone https://github.com/yrn-go/yrn.git
cd yrn

# Inicie todos os serviços
make compose-up

# Verifique se os serviços estão funcionando
curl http://localhost:8500/ui  # Consul UI
curl http://localhost:8080/health  # Agent health
curl http://localhost:8081/health  # Connector health

# Instale dependências
go mod download

# Execute os testes
make test

# Build os binários
make build

# Execute serviços individualmente
go run ./cmd/agent &
go run ./cmd/connector &
go run ./cmd/api &

Obrigatórias para todos os serviços:

SERVICE_NAME=nome-do-servico        # Identificador do serviço no Consul
SERVICE_HOST=localhost              # Host onde o serviço está rodando
SERVICE_PORT=8080                   # Porta do serviço
CONSUL_HTTP_ADDR=localhost:8500     # Endereço do servidor Consul

Específicas do Agent:

CONNECTOR_SERVICE_NAME=connector    # Nome do serviço connector no Consul

Opcionais para banco de dados:

MONGO_URL=mongodb://localhost:27017      # String de conexão MongoDB
MONGO_DATABASE=yrn_database              # Nome da database MongoDB
REDIS_URL=redis://localhost:6379         # String de conexão Redis

O projeto utiliza Consul para descoberta de serviços. Cada serviço:

1. Registra-se automaticamente no Consul na inicialização
2. Expõe endpoints de health (/health) e schema (/schema)
3. Descobre outros serviços através de consultas ao Consul
4. Atualiza status através de health checks automáticos

yrn/
├── cmd/                    # Pontos de entrada dos serviços
│   ├── agent/             # Serviço de descoberta
│   ├── connector/         # Serviço de validação
│   └── api/               # API HTTP
├── pkg/                   # Bibliotecas reutilizáveis
│   ├── ybase/            # Framework core
│   ├── plugin*/          # Implementações de plugins
│   └── ylog/             # Logging
├── internal/             # Lógica interna
│   ├── database/         # Adaptadores de banco
│   └── adapter/          # Adaptadores externos
├── module/               # Módulos de domínio
│   ├── flowmanager/      # Orquestração de workflows
│   └── team/             # Gerenciamento de equipes
└── infra/                # Infraestrutura como código
    └── apps/             # Configurações Kubernetes

1. Crie um novo diretório em pkg/plugin{nome}
2. Implemente a interface PluginExecutor
3. Defina o JSON Schema em schema.json
4. Registre o plugin no sistema

Exemplo básico:

package pluginexemplo

import (
    _ "embed"
    "github.com/yrn-go/yrn/module/flowmanager"
    "github.com/yrn-go/yrn/pkg/yctx"
)

//go:embed schema.json
var Schema []byte

type Executor struct{}

func (e *Executor) Do(ctx *yctx.Context, schemaInputs string, previousPluginResponse any, responseSharedForAll map[string]any) (output any, err error) {
    // Validar entrada
    requestData, err := plugincore.ValidateAndGetRequestBody[MySchema](Schema, schemaInputs, previousPluginResponse, responseSharedForAll)
    if err != nil {
        return nil, err
    }

    // Executar lógica do plugin
    result := processData(requestData)

    return result, nil
}

# Construir projeto
make build

# Executar testes
make test

# Linting
make lint

# Construir imagem Docker
make docker-build

# Executar localmente
make run

# Limpar artefatos
make clean

Endpoint: http://localhost:8080

• GET /health - Health check
• GET /schema - Retorna esquema do serviço
• GET /services - Lista todos os serviços descobertos

Endpoint: http://localhost:8081

• GET /health - Health check
• GET /schema - Retorna esquema de validação
• POST /validate - Valida dados contra schema

Workflows são executados através do FlowManager com a seguinte estrutura:

{
  "id": "workflow-001",
  "name": "Processamento de Dados",
  "description": "Workflow para processar dados do Google Drive",
  "tenant": "cliente-001",
  "first_plugin_to_run": "gdrive-auth",
  "plugins": [
    {
      "id": "gdrive-auth",
      "slug": "gdrive-auth",
      "name": "Autenticação Google Drive",
      "schema_input": "{\"client_id\": \"{{.env.GOOGLE_CLIENT_ID}}\"}",
      "next_to_be_executed": ["gdrive-list"]
    },
    {
      "id": "gdrive-list",
      "slug": "google-drive",
      "name": "Listar Arquivos",
      "schema_input": "{\"credentials\": \"{{.data.access_token}}\"}",
      "next_to_be_executed": ["http-post"]
    }
  ]
}

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

• Siga as convenções do Go (go fmt, go vet)
• Execute make lint antes do commit
• Mantenha cobertura de testes alta
• Documente APIs públicas
• Use semantic versioning

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.

• Documentação do Consul
• JSON Schema Specification
• Google Drive API
• Gin Web Framework

Desenvolvido com ❤️ em Go