fn_registry/bash/functions/infra/mas_syn2mas_migration.md

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

name	kind	lang	domain	version	purity	signature	description	tags	params	output	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path
mas_syn2mas_migration	function	bash	infra	0.1.0	impure	mas_syn2mas_migration --ssh-host <host> --mas-container <name> --synapse-config-path <path-on-host> --log-dir <local-path> [--max-conflicts N] [--apply]	Migra usuarios Synapse a Matrix Authentication Service (MAS) via mas-cli syn2mas. Fuerza dry-run primero, archiva el log, aborta si los conflicts superan el threshold, y solo ejecuta la migracion real con --apply.	matrix mas syn2mas migration mas-migration infra users docker ssh matrix-mas	name desc ssh-host Alias SSH del VPS donde corren los containers (ej. organic-machine.com) name desc mas-container Nombre del container Docker de MAS (ej. element_matrix_chat-mas-1) name desc synapse-config-path Ruta en el VPS al homeserver.yaml de Synapse (ej. /home/ubuntu/CodeProyects/element_matrix_chat/synapse_data/homeserver.yaml). El container debe tener el archivo accesible en /data/homeserver.yaml via volume mount. name desc log-dir Directorio local donde archivar logs dry-run y apply. Se crea con chmod 0700 y los logs con 0600 (contienen userIDs). name desc max-conflicts Tope de conflictos detectados en dry-run. Si conflicts > max-conflicts, status=aborted exit 2. Default 0 (abortar ante cualquier conflict). name desc apply Flag booleano. Sin --apply: solo dry-run (status=ok, sin cambios). Con --apply: ejecuta la migracion real tras pasar el threshold.	JSON en stdout: {"status":"ok|aborted|error","dry_run_log":"path","apply_log":"path|null","conflicts":N,"users_migrated":N,"duration_s":N}. Exit 0=ok, 1=error, 2=aborted por conflicts.				false	error_go_core		true	aborta con error cuando faltan args obligatorios help no devuelve error argumento desconocido retorna exit 1 max-conflicts invalido retorna exit 1	bash/functions/infra/mas_syn2mas_migration_test.sh	bash/functions/infra/mas_syn2mas_migration.sh

Ejemplo

# Paso 1: dry-run OBLIGATORIO (sin --apply — no modifica nada)
mas_syn2mas_migration \
  --ssh-host organic-machine.com \
  --mas-container element_matrix_chat-mas-1 \
  --synapse-config-path /home/ubuntu/CodeProyects/element_matrix_chat/synapse_data/homeserver.yaml \
  --log-dir ~/matrix_migration_logs \
  --max-conflicts 0

# Salida esperada (si hay 0 conflicts):
# {"status":"ok","dry_run_log":"/home/lucas/matrix_migration_logs/syn2mas_dryrun_1234567890.log","apply_log":null,"conflicts":0,"users_migrated":0,"duration_s":0}

# Revisar el log antes de continuar:
# cat ~/matrix_migration_logs/syn2mas_dryrun_*.log

# Paso 2: tras revisar el log dry-run, aplicar la migracion real
mas_syn2mas_migration \
  --ssh-host organic-machine.com \
  --mas-container element_matrix_chat-mas-1 \
  --synapse-config-path /home/ubuntu/CodeProyects/element_matrix_chat/synapse_data/homeserver.yaml \
  --log-dir ~/matrix_migration_logs \
  --max-conflicts 0 \
  --apply

# Salida esperada tras migracion exitosa:
# {"status":"ok","dry_run_log":"/home/lucas/matrix_migration_logs/syn2mas_dryrun_1234567890.log","apply_log":"/home/lucas/matrix_migration_logs/syn2mas_apply_1234567890.log","conflicts":0,"users_migrated":42,"duration_s":15}

Cuando usarla

Usar en el paso 4 de la migracion del issue 0162 (Synapse a MAS auth), tras activar MSC3861 en homeserver.yaml y verificar que MAS esta corriendo con syn2mas: true en su config. NUNCA ejecutar antes de activar MSC3861 — sin ese flag activo, syn2mas no puede mapear usuarios a las tablas MAS y la migracion resultara en estado inconsistente.

Gotchas

• Dry-run NO modifica nada — siempre ejecutar primero sin --apply y revisar el log manualmente antes de aplicar.
• Si el dry-run detecta usuarios con guest accounts, application services (bots), o passwords externos (LDAP/OIDC), revisar manualmente el log antes de aplicar — estos casos pueden requerir steps adicionales documentados en el issue 0162.
• Backup postgres pre-migracion NO esta cubierto por esta funcion. El operador es responsable de hacer pg_dump de la DB de Synapse antes de ejecutar con --apply. Ver issue 0162 paso 1.
• Si la migracion real falla a mitad, MAS puede quedar en estado inconsistente con usuarios parcialmente migrados. El rollback consiste en restaurar el backup postgres de Synapse + revertir homeserver.yaml a la configuracion pre-MSC3861.
• Los logs archivados en --log-dir incluyen userIDs (datos personales). Se crean con permisos 0600 (solo propietario puede leer). Mantener el directorio con chmod 0700. No subir los logs a repos publicos.
• El comando mas-cli syn2mas en el container asume que homeserver.yaml esta montado en /data/homeserver.yaml. Si el volume mount del container usa otra ruta, el comando fallara con "file not found". Verificar con docker inspect <container> | jq '.[].Mounts'.
• La postcondicion compara el count de usuarios MAS con una segunda ejecucion de dry-run para obtener el count esperado. Si el conteo no esta disponible (salida inesperada de mas-cli), la funcion emite status=ok con users_migrated del count real de MAS — no aborta por este motivo para evitar falsos negativos.