> **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.
Esta especificación aborda los patrones de nombres y configuración inconsistentes para los parámetros de conexión de Cassandra en todo el código base de TrustGraph. Actualmente, existen dos esquemas de nombres de parámetros diferentes (`cassandra_*` frente a `graph_*`), lo que provoca confusión y complejidad en el mantenimiento.
## Declaración del Problema
El código base actualmente utiliza dos conjuntos distintos de parámetros de configuración de Cassandra:
1.**Módulos de Conocimiento/Config/Biblioteca** utilizan:
-`cassandra_host` (lista de hosts)
-`cassandra_usuario`
-`cassandra_contraseña`
2.**Módulos de Gráficos/Almacenamiento** utilizan:
-`graph_host` (único host, a veces convertido en lista)
-`graph_username`
-`graph_password`
3.**Exposición inconsistente de la línea de comandos:**
- Algunos procesadores (p. ej., `kg-store`) no expone la configuración de Cassandra como argumentos de línea de comandos
- Otros procesadores los expone con nombres y formatos diferentes
- El texto de ayuda no refleja los valores predeterminados de las variables de entorno
Ambos conjuntos de parámetros se conectan al mismo clúster de Cassandra, pero con diferentes convenciones de nombres, lo que provoca:
- Confusión en la configuración para los usuarios
- Mayor carga de mantenimiento
- Documentación inconsistente
- Posibilidad de configuración incorrecta
- Incapacidad de anular la configuración mediante argumentos de línea de comandos en algunos procesadores
## Solución Propuesta
### 1. Estandarizar los Nombres de los Parámetros
Todos los módulos utilizarán nombres de parámetros consistentes `cassandra_*`:
-`cassandra_host` - Lista de hosts (almacenado internamente como lista)
-`cassandra_username` - Nombre de usuario para la autenticación
-`cassandra_contraseña` - Contraseña para la autenticación
### 2. Argumentos de Línea de Comandos
Todos los procesadores DEBEN exponer la configuración de Cassandra a través de argumentos de línea de comandos:
-`--cassandra-host` - Lista separada por comas de hosts
-`--cassandra-username` - Nombre de usuario para la autenticación
-`--cassandra-password` - Contraseña para la autenticación
### 3. Fallback de Variables de Entorno
Si los parámetros de la línea de comandos no se proporcionan explícitamente, el sistema verificará las variables de entorno:
-`CASSANDRA_HOST` - Lista separada por comas de hosts
-`CASSANDRA_USERNAME` - Nombre de usuario para la autenticación
-`CASSANDRA_PASSWORD` - Contraseña para la autenticación
### 4. Valores Predeterminados
Si ni los parámetros de la línea de comandos ni las variables de entorno no se especifican:
-`cassandra_host` se establece en `["cassandra"]`
-`cassandra_username` se establece en `None` (sin autenticación)
-`cassandra_password` se establece en `None` (sin autenticación)
### 5. Requisitos de Ayuda
La salida `--help` DEBE:
- Mostrar los valores predeterminados de las variables de entorno
- Nunca mostrar los valores de la contraseña (mostrar `****` o `<set>` en su lugar)
- Indicar claramente el orden de resolución en la ayuda
Ejemplo de salida de ayuda:
```
--cassandra-host HOST
Lista de hosts de Cassandra, separada por comas (predeterminado: prod-cluster-1,prod-cluster-2)
[desde la variable de entorno CASSANDRA_HOST]
--cassandra-username USERNAME
Nombre de usuario de Cassandra (predeterminado: cassandra_user)
[desde la variable de entorno CASSANDRA_USERNAME]
--cassandra-password PASSWORD
Contraseña de Cassandra (predeterminado: <establecidodesdeelentorno>)
```
## Detalles de Implementación
### Orden de Resolución
Para cada parámetro de Cassandra, el orden de resolución será:
1. Valor del argumento de la línea de comandos
2. Variable de entorno (`CASSANDRA_*`)
3. Valor predeterminado
### Manejo del parámetro Host
El parámetro `cassandra_host`:
- La línea de comandos acepta una cadena separada por comas: `--cassandra-host "host1,host2,host3"`
- La variable de entorno acepta una cadena separada por comas: `CASSANDRA_HOST="host1,host2,host3"`
- Internamente siempre se almacena como una lista: `["host1", "host2", "host3"]`
### Código de Ejemplo
```python
# Código antiguo
@staticmethod
def add_args(parser):
parser.add_argument(
'-g', '--graph-host',
default="localhost",
help='Host del gráfico (predeterminado: localhost)'
)
parser.add_argument(
'--graph-username',
default=None,
help='Nombre de usuario de Cassandra'
)
# Código nuevo
@staticmethod
def add_args(parser):
FlowProcessor.add_args(parser)
add_cassandra_args(parser) # Usa el asistente estándar
```
### Actualización de Módulos que Utilizan `graph_*` Parámetros
1. Cambiar los nombres de los parámetros de `graph_*` a `cassandra_*`
2. Reemplazar los métodos `add_args()` personalizados
3. Utilizar las funciones `add_cassandra_args()` estándar
4. Actualizar las cadenas de documentación
Ejemplo de transformación:
```python
# Código antiguo
@staticmethod
def add_args(parser):
parser.add_argument(
'-g', '--graph-host',
default="localhost",
help=f'Host del gráfico (predeterminado: localhost)'
)
parser.add_argument(
'--graph-username',
default=None,
help=f'Nombre de usuario de Cassandra'
)
# Código nuevo
@staticmethod
def add_args(parser):
FlowProcessor.add_args(parser)
add_cassandra_args(parser) # Usa el asistente estándar
```
### Actualización de Módulos que Utilizan `cassandra_*` Parámetros
1. Agregar soporte para argumentos de línea de comandos (p. ej., `kg-store`)
2. Reemplazar las definiciones de argumentos existentes con `add_cassandra_args()`
3. Utilizar las funciones `resolve_cassandra_config()` para una resolución consistente
4. Asegurar el manejo consistente de las listas de hosts
### Actualización de Pruebas y Documentación
1. Actualizar todos los archivos de prueba
2. Actualizar la documentación de la línea de comandos
3. Actualizar la documentación de la API
4. Actualizar los ejemplos de Docker Compose
5. Actualizar la documentación de referencia de la configuración
## Compatibilidad con versiones anteriores
Para mantener la compatibilidad con versiones anteriores durante la transición:
1.**Advertencias de desuso** para los parámetros `graph_*`
2.**Alias de parámetros** - aceptar nombres antiguos y nuevos inicialmente
3.**Implementación gradual** durante varios lanzamientos
4.**Actualizaciones de documentación** con guía de migración
Ejemplo de código para la compatibilidad con versiones anteriores:
```python
def __init__(self, **params):
# Manejar parámetros graph_* desactualizados
if 'graph_host' in params:
warnings.warn("graph_host está desactualizado, usa cassandra_host", DeprecationWarning)
