Leggere un server Quven dalla tua dashboard

Se tieni una dashboard di casa, probabilmente hai già i riquadri per il NAS, il router e qualunque altra cosa giri nello sgabuzzino. E Quven può esserne uno. Esiste una piccola API di sola lettura fatta apposta, ed ecco come si usa.

In breve: emetti una chiave dalle impostazioni del server, la mandi come header, e ti torna cosa contiene il server e cosa sta riproducendo in questo momento. La chiave può soltanto leggere. Non è una promessa scritta in un documento da qualche parte, è come sono costruite le rotte.

Emetti la chiave

Apri le Impostazioni, vai su Server e cerca la card delle chiavi di integrazione. Dai alla chiave un nome che avrà ancora senso per te fra sei mesi. “Homepage” va benissimo. “prova2” è il modo in cui ti ritrovi con quattro chiavi e nessuna idea di quale sia quale.

Il segreto compare una volta sola, nel pannello che si apre subito dopo l’emissione, quindi copialo in quel momento, perché non c’è modo di rileggerlo dopo, ed è voluto: il server ne conserva solo un hash, quindi un database rubato non dà a nessuno niente da riutilizzare. Quello che la lista mostra da lì in poi sono le ultime lettere, quanto basta a distinguere due chiavi.

Poi, se ne perdi una, revocala ed emettine un’altra. La revoca ha effetto subito ed è definitiva.

Mandala con la richiesta

Due modi, a seconda di cosa supporta il tuo strumento:

curl -H "X-Quven-Key: qvn_il-tuo-segreto" \
  http://your-server:5181/api/integration/v1/statistics

curl -H "Authorization: Bearer qvn_il-tuo-segreto" \
  http://your-server:5181/api/integration/v1/statistics

Molte dashboard ti danno solo un campo Authorization, ed è per questo che funziona anche la forma bearer. Se per caso li mandi entrambi, vince l’header dedicato.

Cosa puoi chiedere

Sei cose, tutte GET. Quattro rispondono JSON, una risponde testo Prometheus e la sesta pagina quello che è già stato riprodotto. Il riferimento campo per campo sta su quven.tv/api/integration/v1, con accanto il documento OpenAPI se il tuo client genera codice, ed è costruito dalle rotte del server, quindi descrive il server che stai eseguendo e non quello di cui qualcuno ha scritto.

/api/integration/v1/server ti dice con quale installazione stai parlando: nome, versione, quando è partito il processo e la versione di API che parla. Leggi quest’ultima se scrivi qualcosa che intendi condividere: è così che scopri se un certo server ti capisce.

/api/integration/v1/statistics è il riquadro che vogliono quasi tutti. Film, serie, episodi, file, byte su disco.

{
  "movieCount": 2284,
  "showCount": 91,
  "episodeCount": 4137,
  "fileCount": 6602,
  "totalStorageBytes": 41203847561216
}

/api/integration/v1/libraries elenca le librerie con il conteggio dei file e l’ultima volta che ciascuna ha finito una scansione. Conta i file, quindi una libreria che non ne ha ancora non compare: entra nell’elenco con la prima scansione che trova qualcosa.

/api/integration/v1/sessions è cosa sta andando adesso, con titolo, posizione, durata e se il server sta transcodificando. Ti passa anche un refreshAfterSeconds, che è il server che ti dice ogni quanto vale la pena richiedere. Rispettalo. Una dashboard che interroga ogni secondo è il modo più rapido in assoluto per far sembrare rotto un media server.

/api/integration/v1/metrics è la stessa roba in formato Prometheus, così Grafana interroga il server direttamente invece di passare da un exporter che qualcuno deve scrivere.

/api/integration/v1/history pagina quello che è già stato riprodotto, dal più recente, con limit e offset. Dice cosa ha riprodotto il server e quando, e niente su chi gliel’ha chiesto.

La reference su quven.tv/api/integration/v1 esegue queste letture contro il tuo server: metti indirizzo e chiave nella barra in alto e premi Send. La richiesta va dal tuo browser al tuo server e da nessun’altra parte, e tre cose la fermano, e la pagina dice quello che può: un server in http semplice raggiunto da quella pagina, a meno che non sia su questa macchina; un indirizzo che il browser non riesce a raggiungere; e un server più vecchio della console, che quella pagina non la ammette ancora. Il pulsante curl copre tutti e tre i casi.

Ogni lettura porta un ETag. Rimandalo come If-None-Match e un server che non è cambiato risponde 304 senza corpo: sul relay è la differenza tra un poll che costa un round trip e uno che costa l’elenco della libreria. Le sessioni in pratica fanno eccezione: la risposta porta l’istante in cui è stata scattata, quindi cambia sempre e il corpo lo ricevi comunque.

Cosa non ti dirà, di proposito

Due omissioni sono volute, e conviene saperlo prima di mettersi a cercarle.

L’endpoint delle librerie non porta nessun percorso. La disposizione del tuo disco è affare tuo, e un’integrazione non ha motivo di sapere che i film stanno in /mnt/tank/media/film. La lista è costruita dalle statistiche del catalogo invece che dalla configurazione delle librerie proprio perché quel percorso non possa finirci dentro.

L’endpoint delle sessioni non porta l’identità di chi guarda. Vedrai che qualcosa è in riproduzione e cosa, non chi la sta guardando. Chiedere cosa sta facendo il tuo server e chiedere chi in casa sta guardando cosa sono domande diverse, e solo la prima riguarda una dashboard.

Verificare che il server sia acceso

GET /health/live risponde 200 senza corpo e non vuole nessuna chiave, quindi un monitor può interrogarlo senza tenersi un segreto. Esiste anche /health/ready, ma richiede autenticazione e non serve a questo. L’uptime sta anche nelle letture: startedUtc sulla rotta server e quven_server_start_time_seconds nelle metriche.

I limiti, e perché ci sono

Una chiave ha diritto a 120 richieste al minuto, contate per chiave e non per indirizzo, e questo conta se fai girare più di un’integrazione dalla stessa macchina: quella configurata male brucia il proprio budget e lascia in pace le altre.

Un server tiene 25 chiavi attive alla volta, e se ci arrivi, quasi certamente ti sei dimenticato di revocare qualcosa.

Sul versionamento

Le rotte stanno sotto /api/integration/v1, apposta separate da quelle che usano le app Quven. Quelle si spostano quando serve a un client, il che va bene per codice che viaggia insieme ed è inutile per una dashboard che hai configurato una volta e dimenticato. Questo percorso è quello che intendo tenere stabile.

Un server più vecchio dell’API risponde 404 su tutto. È la risposta onesta invece di una che funziona a metà, ed è il motivo per cui /server restituisce un apiVersion: chiedi quello per primo e sai con cosa hai a che fare.

Un’ultima cosa sulla sicurezza

Conviene essere chiari su quanto ti costa una chiave trapelata: qualcosa sì, però meno di quello che di solito si teme. Chi ha la tua chiave può leggere il catalogo e vedere cosa è in riproduzione. Però non può avviare una scansione, cambiare una libreria, toccare un file o emettersi un’altra chiave. La gestione delle chiavi sta dietro il login del proprietario e nient’altro, il che significa che revocare l’originale la chiude davvero, e quel confine è la ragione per cui l’API esiste in questa forma. Dare a una dashboard il token del tuo account sarebbe stato molto meno lavoro e un’idea molto peggiore.