trustgraph/docs/tech-specs/cassandra-consolidation.pt.md

layout	title	parent
default	Especificação Técnica: Consolidação da Configuração do Cassandra	Portuguese (Beta)

Especificação Técnica: Consolidação da Configuração do Cassandra

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Status: Rascunho Autor: Assistente Data: 2024-09-03

Visão Geral

Esta especificação aborda os padrões de nomenclatura e configuração inconsistentes para os parâmetros de conexão do Cassandra em todo o código-fonte do TrustGraph. Atualmente, existem dois esquemas de nomenclatura de parâmetros diferentes (cassandra_* vs graph_*), o que leva à confusão e à complexidade da manutenção.

Declaração do Problema

O código-fonte atualmente usa dois conjuntos distintos de parâmetros de configuração do Cassandra:

1. Módulos Knowledge/Config/Library usam: cassandra_host (lista de hosts) cassandra_user cassandra_password

2. Módulos Graph/Storage usam: graph_host (um único host, às vezes convertido em lista) graph_username graph_password

3. Exposição inconsistente na linha de comando: Alguns processadores (por exemplo, kg-store) não expõem as configurações do Cassandra como argumentos de linha de comando Outros processadores os expõem com nomes e formatos diferentes O texto de ajuda não reflete os valores padrão das variáveis de ambiente

Ambos os conjuntos de parâmetros se conectam ao mesmo cluster Cassandra, mas com convenções de nomenclatura diferentes, causando: Confusão na configuração para os usuários Aumento da carga de manutenção Documentação inconsistente Potencial para configuração incorreta Impossibilidade de substituir as configurações via linha de comando em alguns processadores

Solução Proposta

1. Padronização dos Nomes dos Parâmetros

Todos os módulos usarão nomes de parâmetros cassandra_* consistentes: cassandra_host - Lista de hosts (armazenada internamente como lista) cassandra_username - Nome de usuário para autenticação cassandra_password - Senha para autenticação

2. Argumentos da Linha de Comando

Todos os processadores DEVEM expor a configuração do Cassandra por meio de argumentos de linha de comando: --cassandra-host - Lista separada por vírgulas de hosts --cassandra-username - Nome de usuário para autenticação --cassandra-password - Senha para autenticação

3. Fallback de Variáveis de Ambiente

Se os parâmetros da linha de comando não forem fornecidos explicitamente, o sistema verificará as variáveis de ambiente: CASSANDRA_HOST - Lista separada por vírgulas de hosts CASSANDRA_USERNAME - Nome de usuário para autenticação CASSANDRA_PASSWORD - Senha para autenticação

4. Valores Padrão

Se nem os parâmetros da linha de comando nem as variáveis de ambiente forem especificados: cassandra_host tem como padrão ["cassandra"] cassandra_username tem como padrão None (sem autenticação) cassandra_password tem como padrão None (sem autenticação)

5. Requisitos do Texto de Ajuda

A saída --help deve: Mostrar os valores das variáveis de ambiente como padrões quando definidos Nunca exibir valores de senha (exibir **** ou <set> em vez disso) Indicar claramente a ordem de resolução no texto de ajuda

Exemplo de saída de ajuda:

--cassandra-host HOST
    Cassandra host list, comma-separated (default: prod-cluster-1,prod-cluster-2)
    [from CASSANDRA_HOST environment variable]

--cassandra-username USERNAME
    Cassandra username (default: cassandra_user)
    [from CASSANDRA_USERNAME environment variable]
    
--cassandra-password PASSWORD  
    Cassandra password (default: <set from environment>)

Detalhes de Implementação

Ordem de Resolução de Parâmetros

Para cada parâmetro do Cassandra, a ordem de resolução será:

1. Valor do argumento de linha de comando
2. Variável de ambiente (CASSANDRA_*)
3. Valor padrão

Tratamento de Parâmetros de Host

O parâmetro cassandra_host: A linha de comando aceita uma string separada por vírgulas: --cassandra-host "host1,host2,host3" A variável de ambiente aceita uma string separada por vírgulas: CASSANDRA_HOST="host1,host2,host3" Internamente sempre armazenado como uma lista: ["host1", "host2", "host3"] Host único: "localhost" → convertido para ["localhost"] Já é uma lista: ["host1", "host2"] → usado como está

Lógica de Autenticação

A autenticação será usada quando tanto cassandra_username quanto cassandra_password forem fornecidos:

if cassandra_username and cassandra_password:
    # Use SSL context and PlainTextAuthProvider
else:
    # Connect without authentication

Arquivos a serem modificados

Módulos que utilizam parâmetros graph_* (a serem alterados):

trustgraph-flow/trustgraph/storage/triples/cassandra/write.py trustgraph-flow/trustgraph/storage/objects/cassandra/write.py trustgraph-flow/trustgraph/storage/rows/cassandra/write.py trustgraph-flow/trustgraph/query/triples/cassandra/service.py

Módulos que utilizam parâmetros cassandra_* (a serem atualizados com fallback do ambiente):

trustgraph-flow/trustgraph/tables/config.py trustgraph-flow/trustgraph/tables/knowledge.py trustgraph-flow/trustgraph/tables/library.py trustgraph-flow/trustgraph/storage/knowledge/store.py trustgraph-flow/trustgraph/cores/knowledge.py trustgraph-flow/trustgraph/librarian/librarian.py trustgraph-flow/trustgraph/librarian/service.py trustgraph-flow/trustgraph/config/service/service.py trustgraph-flow/trustgraph/cores/service.py

Arquivos de teste a serem atualizados:

tests/unit/test_cores/test_knowledge_manager.py tests/unit/test_storage/test_triples_cassandra_storage.py tests/unit/test_query/test_triples_cassandra_query.py tests/integration/test_objects_cassandra_integration.py

Estratégia de implementação

Fase 1: Criar um utilitário de configuração comum

Crie funções utilitárias para padronizar a configuração do Cassandra em todos os processadores:

import os
import argparse

def get_cassandra_defaults():
    """Get default values from environment variables or fallback."""
    return {
        'host': os.getenv('CASSANDRA_HOST', 'cassandra'),
        'username': os.getenv('CASSANDRA_USERNAME'),
        'password': os.getenv('CASSANDRA_PASSWORD')
    }

def add_cassandra_args(parser: argparse.ArgumentParser):
    """
    Add standardized Cassandra arguments to an argument parser.
    Shows environment variable values in help text.
    """
    defaults = get_cassandra_defaults()
    
    # Format help text with env var indication
    host_help = f"Cassandra host list, comma-separated (default: {defaults['host']})"
    if 'CASSANDRA_HOST' in os.environ:
        host_help += " [from CASSANDRA_HOST]"
    
    username_help = f"Cassandra username"
    if defaults['username']:
        username_help += f" (default: {defaults['username']})"
        if 'CASSANDRA_USERNAME' in os.environ:
            username_help += " [from CASSANDRA_USERNAME]"
    
    password_help = "Cassandra password"
    if defaults['password']:
        password_help += " (default: <set>)"
        if 'CASSANDRA_PASSWORD' in os.environ:
            password_help += " [from CASSANDRA_PASSWORD]"
    
    parser.add_argument(
        '--cassandra-host',
        default=defaults['host'],
        help=host_help
    )
    
    parser.add_argument(
        '--cassandra-username',
        default=defaults['username'],
        help=username_help
    )
    
    parser.add_argument(
        '--cassandra-password',
        default=defaults['password'],
        help=password_help
    )

def resolve_cassandra_config(args) -> tuple[list[str], str|None, str|None]:
    """
    Convert argparse args to Cassandra configuration.
    
    Returns:
        tuple: (hosts_list, username, password)
    """
    # Convert host string to list
    if isinstance(args.cassandra_host, str):
        hosts = [h.strip() for h in args.cassandra_host.split(',')]
    else:
        hosts = args.cassandra_host
    
    return hosts, args.cassandra_username, args.cassandra_password

Fase 2: Atualizar Módulos Usando Parâmetros graph_*

1. Alterar os nomes dos parâmetros de graph_* para cassandra_*
2. Substituir os métodos personalizados add_args() por métodos padronizados add_cassandra_args()
3. Usar as funções auxiliares de configuração comuns
4. Atualizar as strings de documentação

Exemplo de transformação:

# OLD CODE
@staticmethod
def add_args(parser):
    parser.add_argument(
        '-g', '--graph-host',
        default="localhost",
        help=f'Graph host (default: localhost)'
    )
    parser.add_argument(
        '--graph-username',
        default=None,
        help=f'Cassandra username'
    )

# NEW CODE  
@staticmethod
def add_args(parser):
    FlowProcessor.add_args(parser)
    add_cassandra_args(parser)  # Use standard helper

Fase 3: Atualizar Módulos Usando Parâmetros cassandra_*

1. Adicionar suporte para argumentos de linha de comando onde estiver faltando (por exemplo, kg-store)
2. Substituir as definições de argumentos existentes por add_cassandra_args()
3. Usar resolve_cassandra_config() para resolução consistente
4. Garantir o tratamento consistente da lista de hosts

Fase 4: Atualizar Testes e Documentação

1. Atualizar todos os arquivos de teste para usar os novos nomes de parâmetros
2. Atualizar a documentação da CLI
3. Atualizar a documentação da API
4. Adicionar documentação de variáveis de ambiente

Compatibilidade com Versões Anteriores

Para manter a compatibilidade com versões anteriores durante a transição:

1. Avisos de descontinuação para parâmetros graph_*
2. Aliasing de parâmetros - aceitar tanto os nomes antigos quanto os novos inicialmente
3. Implementação gradual ao longo de várias versões
4. Atualizações na documentação com um guia de migração

Exemplo de código de compatibilidade com versões anteriores:

def __init__(self, **params):
    # Handle deprecated graph_* parameters
    if 'graph_host' in params:
        warnings.warn("graph_host is deprecated, use cassandra_host", DeprecationWarning)
        params.setdefault('cassandra_host', params.pop('graph_host'))
    
    if 'graph_username' in params:
        warnings.warn("graph_username is deprecated, use cassandra_username", DeprecationWarning)
        params.setdefault('cassandra_username', params.pop('graph_username'))
    
    # ... continue with standard resolution

Estratégia de Testes

1. Testes unitários para a lógica de resolução de configuração
2. Testes de integração com várias combinações de configuração
3. Testes de variáveis de ambiente
4. Testes de compatibilidade retroativa com parâmetros obsoletos
5. Testes do Docker Compose com variáveis de ambiente

Atualizações da Documentação

1. Atualizar toda a documentação dos comandos da linha de comando
2. Atualizar a documentação da API
3. Criar um guia de migração
4. Atualizar os exemplos do Docker Compose
5. Atualizar a documentação de referência de configuração

Riscos e Mitigações

Risco	Impacto	Mitigação
Mudanças que podem afetar os usuários	Alto	Implementar um período de compatibilidade retroativa
Confusão na configuração durante a transição	Médio	Documentação clara e avisos de descontinuação
Falhas nos testes	Médio	Atualizações abrangentes nos testes
Problemas de implantação do Docker	Alto	Atualizar todos os exemplos do Docker Compose

Critérios de Sucesso

[ ] Todos os módulos usam nomes de parâmetros cassandra_* consistentes [ ] Todos os processadores expõem as configurações do Cassandra por meio de argumentos da linha de comando [ ] O texto de ajuda da linha de comando mostra os valores padrão das variáveis de ambiente [ ] Os valores de senha nunca são exibidos no texto de ajuda [ ] O fallback de variáveis de ambiente funciona corretamente [ ] cassandra_host é tratado de forma consistente como uma lista internamente [ ] A compatibilidade retroativa é mantida por pelo menos 2 versões [ ] Todos os testes passam com o novo sistema de configuração [ ] A documentação está totalmente atualizada [ ] Os exemplos do Docker Compose funcionam com variáveis de ambiente

Cronograma

Semana 1: Implementar o utilitário de configuração comum e atualizar os módulos graph_* Semana 2: Adicionar suporte a variáveis de ambiente aos módulos cassandra_* existentes Semana 3: Atualizar testes e documentação Semana 4: Testes de integração e correção de bugs

Considerações Futuras

Considerar a extensão desse padrão para outras configurações de banco de dados (por exemplo, Elasticsearch) Implementar validação de configuração e melhores mensagens de erro Adicionar suporte para configuração de pool de conexões do Cassandra Considerar a adição de suporte para arquivos de configuração (.env)