Una connection string, cualquier plataforma: conectarse a Zaris

La mitad de los bugs de conexión "funciona en dev, se rompe en prod" se reducen a lo mismo: los detalles de conexión se escribieron de tres formas diferentes en tres lugares diferentes. El appsettings.json tenía una lista de hosts, el runbook de operaciones pegó otra en una sesión de PowerShell, y la cadena que alguien copió de una wiki tenía un token obsoleto incrustado directamente en ella.

Zaris saca de la mesa toda esa clase de problema con un único formato de connection string agnóstico de plataforma. La exacta misma cadena funciona cuando tu aplicación .NET la lee de la configuración, cuando un operador se la entrega a un cmdlet de PowerShell, y cuando alguien la copia directamente de la consola web. Una ortografía canónica, en todas partes.

Este post desglosa la cadena parte por parte, muestra las tres formas de usarla, y defiende la única regla que más importa en producción: nunca pongas un token en crudo en la cadena.

La forma de la cadena

Una connection string de Zaris es una URI. Aquí tienes una completamente cargada:

zariss://zaris-a.example.com:7861,zaris-b.example.com:7861/?store=orders&token=env:ZARIS_TOKEN

Cada parte de eso cumple una función:

• Esquema → seguridad de transporte. zaris:// es texto plano; zariss:// es TLS (la s extra, la misma convención que http/https). Elegir el esquema es cómo activas el cifrado de transporte — no hay un flag aparte que olvidar.
• Hosts separados por comas → lista de failover / semillas. Puedes listar más de un host:port, y el cliente los trata como una lista de semillas para el failover. Se conecta a través de cualquier semilla que responda y descubre el resto del clúster a partir de ahí, de modo que un único nodo caído al arranque no te deja fuera.
• Un nombre de almacén requerido. Cada conexión apunta a exactamente un almacén, y el nombre del almacén es requerido — no hay default implícito. Es deliberado: significa que una cadena siempre dice para qué almacén es, y no puedes apuntar accidentalmente un trabajo al almacén equivocado porque el destino se dejó en blanco.
• Un token suministrado de forma segura. Los tokens de autenticación son secretos, así que el formato los mantiene fuera de la cadena literal. En lugar de pegar el token, apuntas a dónde leerlo — token=env:ZARIS_TOKEN lo lee de una variable de entorno, y token=file:/path/to/token lo lee de un archivo en disco. El secreto nunca está en la cadena misma, así que nunca acaba en el control de versiones, en un historial de shell o en una captura de pantalla.

Ese último punto es el que vale la pena interiorizar: la cadena lleva una referencia a la credencial, no la credencial.

Usarla desde .NET

Las aplicaciones .NET leen la cadena de la configuración estándar de ConnectionStrings — el mismo mecanismo de appsettings.json / IConfiguration que ya usas para bases de datos. Ponla donde viven todas las demás connection strings:

{
  "ConnectionStrings": {
    "Orders": "zariss://zaris-a.example.com:7861,zaris-b.example.com:7861/?store=orders&token=env:ZARIS_TOKEN"
  }
}

Luego léela a través de la configuración como cualquier otra cosa:

var connectionString = builder.Configuration.GetConnectionString("Orders");
var store = await ZarisStore.ConnectAsync(connectionString);

Como el token es env:ZARIS_TOKEN, el appsettings.json versionado es seguro de registrar — nombra la variable de entorno en lugar de contener el secreto. Cada entorno suministra su propio ZARIS_TOKEN, y la cadena permanece idéntica desde la laptop de un desarrollador hasta los pods de producción.

Usarla desde PowerShell

Los cmdlets de administración toman la cadena idéntica. Connect-ZrStore la acepta directamente con -ConnectionString:

$conn = "zariss://zaris-a.example.com:7861,zaris-b.example.com:7861/?store=orders&token=env:ZARIS_TOKEN"
Connect-ZrStore -ConnectionString $conn

Nota que esta es la misma cadena que está en appsettings.json. Un operador que depura un problema de producción y un servicio corriendo en producción apuntan al clúster exactamente de la misma forma — sin un paso de traducción donde una diferencia sutil en la lista de hosts o el nombre del almacén pueda colarse. La indirección env: también funciona aquí: establece ZARIS_TOKEN en el entorno del shell y el cmdlet lo resuelve en el momento de conectar.

Cópiala directamente de la consola

La tercera fuente es la consola web. Para cualquier almacén, la consola muestra una connection string copiable — una correcta, ya escrita de la forma canónica, con los hosts y el nombre del almacén correctos rellenados. Un operador que necesita conectarse no ensambla a mano una URI de memoria; copia la cadena que la consola generó y la pega en la configuración de su aplicación o en una llamada a Connect-ZrStore.

Eso cierra el círculo. La consola produce la cadena canónica, la configuración de .NET la consume, y PowerShell la consume — tres superficies, un formato, sin reescritura.

La única regla para producción

Usa siempre la indirección de tokens env: o file: en despliegues reales. Nunca pegues un token en crudo en la cadena.

Es tentador en una prueba rápida incrustar la credencial solo para verla funcionar. El problema es lo que pasa después: esa cadena se copia en un archivo de configuración, se versiona, se comparte en un chat, o se vuelca en un ticket — y ahora una credencial viva está en algún sitio donde no debería, sin forma fácil de saber a todos los lugares a los que se filtró. Las formas env: y file: existen precisamente para que la cadena de trabajo y el secreto viajen por separado:

# Good — the secret lives in the environment, the string references it
zariss://zaris-a.example.com:7861/?store=orders&token=env:ZARIS_TOKEN

# Good — the secret lives in a mounted file, the string references it
zariss://zaris-a.example.com:7861/?store=orders&token=file:/var/run/secrets/zaris-token

En Kubernetes, file: combina de forma natural con un secret montado; en una VM o contenedor, env: combina con lo que sea que inyecte variables de entorno. En cualquier caso, rotar el token significa cambiar el secreto, no editar cada connection string.

La recompensa

Una única cadena canónica significa un único lugar donde acertar y una única cosa sobre la que razonar. La lista de hosts, la elección de TLS, el almacén y la fuente de la credencial están todos codificados de la misma forma, ya sea que el lector sea la configuración de .NET, un cmdlet de PowerShell, o una persona copiando desde la consola. Así es como retiras el bug de conexión "funciona en dev, se rompe en prod": simplemente no hay una segunda ortografía de la conexión con la que prod pueda discrepar.