fn_registry/functions/infra/matrix/matrix_sync_service.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_sync_service	function	go	infra	0.1.0	impure	func MatrixSyncService(ctx context.Context, cfg MatrixSyncServiceConfig) (*MatrixSyncServiceHandle, error)	Arranca el sync loop de mautrix contra Synapse en background con backoff exponencial, emite eventos Matrix normalizados via canal Go y expone funcion de stop idempotente.	matrix mautrix sync longpoll reconnect goroutine channels infra matrix-mas	name desc ctx Context padre. Si se cancela, la goroutine sale limpiamente y cierra los channels. name desc cfg.Client *mautrix.Client ya inicializado con credenciales (HomeserverURL, AccessToken, UserID). Usar matrix_client_init para crearlo. Obligatorio. name desc cfg.InitialBackoffMS Milisegundos de espera inicial entre reintentos tras error de sync. Default: 1000 (1s). name desc cfg.MaxBackoffMS Techo del backoff exponencial en ms. Default: 60000 (60s). name desc cfg.ChannelBuffer Capacidad del buffer del canal Events. Si el consumer va lento y el buffer se llena, el sync se bloquea hasta que el consumer drene. Default: 256.	*MatrixSyncServiceHandle con Events <-chan MatrixSyncEvent (canal de eventos normalizados), Errors <-chan error (errores transitorios no fatales), Stop func() (cancela y cierra todo, idempotente).				false	error_go_core	maunium.net/go/mautrix maunium.net/go/mautrix/event maunium.net/go/mautrix/id	true	RecibeMensajeYStop BackoffRecovery Error401NoExit StopIdempotente CtxCancelCierraChannels	functions/infra/matrix/matrix_sync_service_test.go	functions/infra/matrix/matrix_sync_service.go

Ejemplo

ctx := context.Background()
h, err := MatrixSyncService(ctx, MatrixSyncServiceConfig{
    Client: client, // *mautrix.Client de matrix_client_init
})
if err != nil {
    panic(err)
}
defer h.Stop()

// Consumir errores transitorios en goroutine separada
go func() {
    for e := range h.Errors {
        log.Println("matrix sync error:", e)
    }
}()

// Loop de eventos (bloquea hasta que h.Stop() se llame o ctx sea cancelado)
for ev := range h.Events {
    fmt.Printf("[%s] %s: %s\n", ev.Type, ev.Sender, ev.Body)
}

Cuando usarla

Usar despues de MatrixClientInit (y opcionalmente MatrixCryptoInit) para recibir el stream de eventos de Matrix en tiempo real. Es el servicio long-running central de cualquier cliente Matrix: matrix_client_pc, admin_panel, bots, monitores. Un solo MatrixSyncService por client, durante toda la vida de la aplicacion.

Gotchas

• Solo UN Sync por client: dos goroutines llamando SyncWithContext simultaneamente sobre el mismo client rompe el since token y produce duplicados o perdidas. Esta funcion garantiza una sola goroutine de sync si es llamada una sola vez. NO llamar MatrixSyncService dos veces sobre el mismo *mautrix.Client.
• Crypto antes del Sync: mensajes m.room.encrypted que llegan antes de inicializar MatrixCryptoInit quedan sin descifrar (emitidos con Type:"encrypted", Body:"", Raw:*event.Event). Inicializar crypto siempre ANTES de llamar a esta funcion.
• Buffer de channel: si el consumer no drena Events con suficiente rapidez, el sync se bloquea en el punto de emision. Synapse puede acumular deltas. Mantener el consumer rapido o aumentar ChannelBuffer.
• Errores fatales (401/M_UNKNOWN_TOKEN): no cierran el servicio automaticamente — se emiten a Errors y el servicio espera con backoff maximo. El caller decide llamar Stop() y re-autenticar.
• Stop idempotente: llamar Stop() multiples veces es seguro; no causa panic.
• Build tag: el paquete infra requiere -tags goolm para compilar tests sin libolm (dependencia C de la crypto de mautrix). Los tests usan //go:build goolm.