fn_registry/bash/functions/infra/mas_client_register.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
mas_client_register	function	bash	infra	0.1.0	impure	mas_client_register(ssh_host: string, container: string, config_file: string, dry_run: bool) -> json	Registra y sincroniza clientes OAuth en Matrix Authentication Service (MAS) ejecutando mas-cli config sync dentro del container Docker remoto via SSH. Verifica sintaxis YAML, soporte dry-run para ver diff antes de aplicar, y emite JSON estructurado con resultado. Idempotente: re-ejecucion con misma config no genera cambios.	matrix mas oauth oidc migration mas-migration infra docker ssh matrix-mas				false	error_go_core		name desc ssh_host alias SSH del VPS donde corre MAS (ej. organic-machine.com). Debe estar en ~/.ssh/config con key auth. name desc container nombre del container Docker con MAS (ej. element_matrix_chat-mas-1). El config dentro del container se espera en /data/config.yaml. name desc config_file ruta absoluta en el VPS al archivo mas/config.yaml (ej. /home/ubuntu/CodeProyects/element_matrix_chat/mas/config.yaml). MAS lo monta como /data/config.yaml. name desc dry_run flag opcional --dry-run: ejecuta mas-cli config dump y devuelve el estado sin aplicar cambios. Util para verificar antes de activar MSC3861.	JSON con: status ('ok'|'dry-run'|'error'), applied (bool), clients_total (int), clients_diff (array de lineas del output de mas-cli), stderr (string con logs de error si aplica).	true	help flag emite JSON parseable args faltantes retornan JSON de error sin ssh jq disponible en host local	bash/functions/infra/mas_client_register_test.sh	bash/functions/infra/mas_client_register.sh

Ejemplo

# Dry-run: verificar que clients se aplicarian correctamente
source bash/functions/infra/mas_client_register.sh

mas_client_register \
  --ssh-host organic-machine.com \
  --container element_matrix_chat-mas-1 \
  --config-file /home/ubuntu/CodeProyects/element_matrix_chat/mas/config.yaml \
  --dry-run

# Aplicar sync real (con --prune para eliminar clients viejos)
mas_client_register \
  --ssh-host organic-machine.com \
  --container element_matrix_chat-mas-1 \
  --config-file /home/ubuntu/CodeProyects/element_matrix_chat/mas/config.yaml

Salida esperada (sync OK):

{
  "status": "ok",
  "applied": true,
  "clients_total": 6,
  "clients_diff": ["synced client element-web", "synced client synapse-admin", "..."],
  "stderr": ""
}

Salida dry-run:

{
  "status": "dry-run",
  "applied": false,
  "clients_total": 42,
  "clients_diff": ["clients:", "  - client_id: element-web", "    ..."],
  "stderr": ""
}

Cuando usarla

Usar despues de editar mas/config.yaml localmente y antes de hacer restart a Synapse con msc3861 habilitado en homeserver.yaml. Ejecutar primero con --dry-run para verificar que los 6 clients OAuth (Element Web, Synapse-Admin, matrix_client_pc, matrix_client_android, matrix_admin_panel, Synapse-internal) estan correctamente definidos, luego sin --dry-run para aplicar el sync.

Gotchas

• --prune elimina clients no declarados en config: el sync real usa --prune, lo que borra cualquier client OAuth que exista en MAS pero no este en el config.yaml. Verificar con --dry-run antes de aplicar en produccion.
• Requiere jq en el host local: el JSON output se construye con jq. Si no esta instalado, la funcion falla con error claro antes de conectar al VPS.
• mas-cli debe estar en el container: la funcion asume que mas-cli esta en el PATH dentro del container MAS. Si el container usa una imagen diferente, verificar con docker exec <container> mas-cli --version.
• Config dentro del container siempre en /data/config.yaml: el --config-file apunta a la ruta en el VPS (para que el operador sepa que archivo editar), pero el comando dentro del container usa /data/config.yaml (el mount point estandar de MAS). Si el compose monta el archivo en otro path, ajustar la constante container_config en el script.
• SSH key debe estar en agent o ~/.ssh/config: la funcion usa ssh <alias> directamente. Si la key requiere passphrase, ejecutar ssh-add antes.
• Si config.yaml es invalido, sync aborta sin tocar estado: el paso 1 (mas-cli config check) detecta errores de sintaxis YAML antes de intentar sync. El estado de MAS no se modifica si la config tiene errores.
• Idempotente: re-ejecutar con la misma config no genera cambios en MAS (mas-cli detecta que el estado ya coincide).