egutierrez
c441366f89
- mas_oidc_loopback_go_infra: OAuth2 PKCE + loopback HTTP for desktop login - keyring_token_store_go_infra: persist OAuth tokens in SO keychain - matrix_client_init_go_infra: init mautrix.Client from access_token + whoami Plus go.work workspace including matrix_client_pc sub-repo for shared import path during dev. All 3 fns tagged matrix-mas capability group. Tests: TestMasOidcLoopback (15 cases), TestKeyringTokenStore (5 cases, SKIP on headless), TestMatrixClientInit (6 cases) — all green/skip. Refs: dev/issues/0147-matrix-client-pc-scaffold.md Refs: dataforge/matrix_client_pc commit f28c2b1
88 lines
5.0 KiB
Markdown
88 lines
5.0 KiB
Markdown
---
|
|
name: matrix_client_init
|
|
kind: function
|
|
lang: go
|
|
domain: infra
|
|
version: "0.1.0"
|
|
purity: impure
|
|
signature: "func MatrixClientInit(cfg MatrixClientInitConfig) (*MatrixClientInitResult, error)"
|
|
description: "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."
|
|
tags: [matrix, mautrix, sync, client, store, sqlite, infra, matrix-mas]
|
|
params:
|
|
- name: cfg.HomeserverURL
|
|
desc: "URL base del servidor Matrix (Synapse). Debe empezar con https://. Ejemplo: https://matrix-af2f3d.organic-machine.com"
|
|
- name: cfg.UserID
|
|
desc: "MXID del usuario en formato @local:servidor. Ejemplo: @egutierrez:matrix-af2f3d.organic-machine.com"
|
|
- name: cfg.AccessToken
|
|
desc: "Bearer token obtenido del flow OIDC (mas_oidc_loopback). No puede estar vacio."
|
|
- name: cfg.DeviceID
|
|
desc: "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: cfg.StoreDir
|
|
desc: "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: cfg.EnableCrypto
|
|
desc: "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)."
|
|
output: "*MatrixClientInitResult con Client (*mautrix.Client listo para Sync), StorePath (ruta absoluta del directorio de estado) y CryptoPath (calculado pero vacio en v0.1.0)."
|
|
uses_functions: []
|
|
uses_types: []
|
|
returns: []
|
|
returns_optional: false
|
|
error_type: "error_go_core"
|
|
imports:
|
|
- "maunium.net/go/mautrix"
|
|
- "maunium.net/go/mautrix/id"
|
|
tested: true
|
|
tests:
|
|
- "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"
|
|
test_file_path: "functions/infra/matrix_client_init_test.go"
|
|
file_path: "functions/infra/matrix_client_init.go"
|
|
---
|
|
|
|
## Ejemplo
|
|
|
|
```go
|
|
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).
|