mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-29 18:36:22 +02:00
Structure the tech specs directory (#836)
Tech spec some subdirectories for different languages
This commit is contained in:
cybermaggedon
GitHub
parent
48da6c5f8b
commit
e7efb673ef
423 changed files with 0 additions and 0 deletions
339
docs/tech-specs/pt/cassandra-consolidation.pt.md
Normal file
339
docs/tech-specs/pt/cassandra-consolidation.pt.md
Normal file
|
|
@ -0,0 +1,339 @@
|
|||
---
|
||||
layout: default
|
||||
title: "Especificação Técnica: Consolidação da Configuração do Cassandra"
|
||||
parent: "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:
|
||||
```python
|
||||
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:
|
||||
|
||||
```python
|
||||
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:
|
||||
```python
|
||||
# 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:
|
||||
```python
|
||||
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)
|
||||
Loading…
Add table
Add a link
Reference in a new issue