fn_registry/functions/infra/matrix/matrix_client_init.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
matrix_client_init	function	go	infra	0.1.0	impure	func MatrixClientInit(cfg MatrixClientInitConfig) (*MatrixClientInitResult, error)	Construye un *mautrix.Client listo para Sync a partir de un access_token ya obtenido (OIDC). Valida inputs, crea StoreDir con permisos 0700, descubre DeviceID via /whoami si no se proporciona. No maneja login — eso lo hace mas_oidc_loopback.	matrix mautrix sync client store sqlite infra matrix-mas	name desc cfg.HomeserverURL URL base del servidor Matrix (Synapse). Debe empezar con https://. Ejemplo: https://matrix-af2f3d.organic-machine.com name desc cfg.UserID MXID del usuario en formato @local:servidor. Ejemplo: @egutierrez:matrix-af2f3d.organic-machine.com name desc cfg.AccessToken Bearer token obtenido del flow OIDC (mas_oidc_loopback). No puede estar vacio. name desc cfg.DeviceID Device ID del cliente Matrix. Si vacio, se descubre via GET /whoami sumando ~100ms de latencia. Recomendado guardarlo en keyring tras el primer uso. name desc cfg.StoreDir Directorio donde se persiste el estado de sync (next_batch, filter_id). Se crea con permisos 0700. Puede ser relativo (se convierte a absoluto). Ejemplo: /home/lucas/.matrix_client_pc/egutierrez/ name desc cfg.EnableCrypto Si true, configura crypto store para E2EE (Olm/Megolm). En v0.1.0 devuelve error — implementacion completa en matrix_crypto_init_go_infra (issue 0150).	*MatrixClientInitResult con Client (*mautrix.Client listo para Sync), StorePath (ruta absoluta del directorio de estado) y CryptoPath (calculado pero vacio en v0.1.0).				false	error_go_core	maunium.net/go/mautrix maunium.net/go/mautrix/id	true	HomeserverURL invalido UserID format invalido DeviceID vacio Whoami exitoso Whoami 401 token invalido EnableCrypto true devuelve error not implemented StoreDir se crea con permisos 0700	functions/infra/matrix/matrix_client_init_test.go	functions/infra/matrix/matrix_client_init.go

Ejemplo

import (
    "fmt"
    infra "fn-registry/functions/infra"
)

cfg := infra.MatrixClientInitConfig{
    HomeserverURL: "https://matrix-af2f3d.organic-machine.com",
    UserID:        "@egutierrez:matrix-af2f3d.organic-machine.com",
    AccessToken:   "mxat_xyz...",  // de mas_oidc_loopback_go_infra
    DeviceID:      "",             // se descubre via whoami
    StoreDir:      "/home/lucas/.matrix_client_pc/egutierrez/",
    EnableCrypto:  false,          // v0.1.0
}
res, err := infra.MatrixClientInit(cfg)
if err != nil {
    panic(err)
}
// res.Client listo para res.Client.Sync()
fmt.Println("DeviceID:", res.Client.DeviceID)
fmt.Println("StorePath:", res.StorePath)

Cuando usarla

Llamar UNA vez por sesion, justo tras obtener el access_token via OIDC flow (mas_oidc_loopback_go_infra). El *mautrix.Client resultante se pasa al loop de Sync, al sender de mensajes y al handler de eventos. No volver a llamarla mientras el token siga valido.

Gotchas

• DeviceID vacio dispara GET /whoami: suma ~100ms de latencia al arranque. Si guardas el DeviceID en keyring tras el primer uso (recomendado), pasalo directamente para evitarlo.
• StoreDir permisos 0700: la funcion los aplica en Linux/macOS. En Windows el MkdirAll no soporta permisos Unix — usar una ubicacion bajo os.UserConfigDir() que ya esta protegida por el SO.
• mautrix-go v0.28+ cambio de tipos: id.UserID y id.DeviceID ya no son alias de string. Importar maunium.net/go/mautrix/id para conversiones explicitas.
• EnableCrypto=true devuelve error en v0.1.0: la inicializacion correcta de Olm/Megolm con cross-signing requiere configurar crypto.OlmMachine con su propio SQLite — issue 0150 lo aborda completo. No hacerlo a medias aqui evita estados de crypto corrompidos.
• M_UNKNOWN_TOKEN en Whoami: si el AccessToken esta caducado y DeviceID es vacio, el error menciona explicitamente "UNKNOWN_TOKEN". El caller debe refrescar via OIDC (refresh_token de MasOidcLoopbackResult).
• mautrix.NewClient normaliza HomeserverURL: llama ParseAndNormalizeBaseURL internamente. Si la URL tiene trailing slash o path extra, se normaliza. Verificar en res.Client.HomeserverURL.String() si hay dudas.

Notas

• El *mautrix.Client usa NewMemorySyncStore() por defecto (no persiste next_batch entre reinicios). Para persistencia real del sync state, el caller debe configurar un SQLiteSyncStore apuntando a {StoreDir}/sync.db — ver documentacion de mautrix-go SQLite stores.
• CryptoPath se calcula como {StoreDir}/crypto.db pero no se inicializa. Reservado para matrix_crypto_init_go_infra (issue 0150).
• La funcion no configura un Syncer ni StateStore custom — el caller lo hace segun sus necesidades (DefaultSyncer con handlers de eventos para matrix_client_pc).