8. Headless-tila (palvelin)

Muista

Tässä osiossa kuvataan blunderDB:n edistynyt ja valinnainen tila, joka on tarkoitettu palvelinkäyttöön, monikäyttäjäympäristöihin ja automaatioon. blunderDB:n tavanomainen ja suositeltu käyttötapa on edelleen työpöytäsovellus, joka kuvataan edellisissä luvuissa. Jos käytät blunderDB:tä yksin omalla tietokoneellasi, et tarvitse tätä tilaa: voit ohittaa tämän luvun menettämättä mitään analyysiominaisuuksista.

8.1. Yleiskatsaus

Sama blunderdb-binääri voi työpöytäsovelluksen ja komentorivikomentojen (katso Komentoriviliittymä (CLI)) lisäksi toimia headless-tilassa: ilman graafista käyttöliittymää, ohjattuna kokonaan komentoriviltä tai verkon kautta. Tämä tila kattaa kolme käyttötapaa:

• demoni serve — tarjoaa blunderDB:n moottorin HTTP + JSON -palveluna, jotta jaettua tietokantaa voidaan pyörittää palvelimella ja käyttää usean käyttäjän kesken;

• yleiskäyttöinen call-välittäjä — kutsuu mitä tahansa tallennustoimintoa suoraan paikallisesti, skriptausta ja testausta varten;

• migrate-komento — siirtää yhden käyttäjän SQLite-tietokannan monikäyttäjäiseen PostgreSQL-taustajärjestelmään.

Nämä kolme käyttötapaa nojaavat yhteiseen tallennuskerrokseen, joka osaa puhua kahdelle taustajärjestelmälle: SQLite (työpöytäsovelluksen tavanomainen .db-tiedostomuoto) ja PostgreSQL (monikäyttäjäisiin palvelinkäyttöönottoihin).

8.2. serve-demoni

blunderdb serve käynnistää moottorin HTTP-palveluna, joka vastaa JSON-muodossa. Sen avulla voi isännöidä asematietokantaa yhdellä koneella ja käyttää sitä useasta asiakkaasta.

# Servir une base SQLite locale sur le port 8080
blunderdb serve --db ma_base.db --addr :8080

# Servir un backend PostgreSQL
blunderdb serve --backend postgres \
    --dsn "postgres://user:pass@host:5432/blunderdb?sslmode=disable" \
    --addr :8080

Varoitus

Demoni ei suorita minkäänlaista todennusta. Se luottaa X-Tenant-ID-pyyntöotsakkeeseen ja on ajettava todennuksesta huolehtivan käänteisvälityspalvelimen (nginx, Caddy…) takana. Älä koskaan altista sitä suoraan julkiseen internetiin.

Valinnat:

Valinta	Oletus	Merkitys
--db <polku>	–	SQLite-tiedosto (oikotie komennolle --backend sqlite --dsn <polku>)
--backend <tyyppi>	sqlite	tallennustaustajärjestelmä: sqlite tai postgres
--dsn <merkkijono>	$BLUNDERDB_DSN	taustajärjestelmän yhteysmerkkijono
--addr <isäntä:portti>	:8080	kuunteluosoite
--log-level <taso>	info	lokitustaso: debug|info|warn|error
--metrics	true	tarjoaa /metrics (Prometheus-muoto)
--cors-allow-origin <alkuperä>	–	ottaa CORS:n käyttöön tälle alkuperälle (oletuksena pois käytöstä)
--rate-limit-rps <n>	0	pyyntöraja sekunnissa vuokralaista kohti (0 = pois käytöstä)
--rate-limit-burst <n>	2×rps	token-ämpärin koko pyyntöpiikkejä varten
--rls	false	PostgreSQL: ottaa käyttöön vuokralaiskohtaisen Row-Level Securityn (syvyyspuolustus, valinnainen)

Useimmat valinnat voidaan antaa myös ympäristömuuttujalla (BLUNDERDB_BACKEND, BLUNDERDB_DSN, BLUNDERDB_ADDR, BLUNDERDB_LOG_LEVEL, BLUNDERDB_RLS).

8.2.1. Päätepisteet

Palvelu tarjoaa hallinnolliset päätepisteet, jotka ovat aina läsnä:

• GET /healthz — elossaolo (prosessi on käynnissä);

• GET /readyz — valmius (tallennus vastaa);

• GET /metrics — Prometheus-metriikat (jos --metrics on käytössä).

Toiminnallinen rajapinta noudattaa kaavaa POST /v1/<perhe>.<metodi> (esimerkiksi /v1/positions.save, /v1/matches.get). Perheet kattavat asemat, analyysit, ottelut, kommentit, kokoelmat, turnaukset, Anki-kortit, suodattimet, istunnot, haun, metatiedot, tilastot ja tuonnin. Listauspäätepisteet palauttavat NDJSON-virran (yksi JSON-objekti riviä kohti). Palvelin pysähtyy siististi signaaleilla SIGINT / SIGTERM.

Kaksi positions-perheen metodia purkaa aseman tallentamatta sitä: positions.fromXGID rakentaa aseman XGID-merkkijonosta ja positions.fromXGP yksittäisen aseman .xgp-tiedostosta.

8.3. PostgreSQL-taustajärjestelmä ja monikäyttäjäisyys

Jaettua käyttöönottoa varten blunderDB voi tallentaa tiedot PostgreSQL:ään SQLite-tiedoston sijaan. Taustajärjestelmä valitaan valinnalla --backend postgres ja yhteysmerkkijonolla --dsn. Skeema luodaan ja migroidaan automaattisesti käynnistyksen yhteydessä.

Tiedot on eristetty vuokralaisittain: jokainen pyyntö sisältää scope-tunnisteen (otsake X-Tenant-ID, oletuksena default), mikä sallii usean käyttäjän jakaa saman instanssin näkemättä toistensa tietoja. Valinta --rls ottaa lisäksi käyttöön PostgreSQL:n Row-Level Securityn: vuokralaiskohtaiset eristyskäytännöt asennetaan ja app.tenant_id asetetaan yhteyskohtaisesti. Tämä on valinnainen syvyyspuolustus, joka on oletuksena pois käytöstä.

8.4. SQLite-tietokannan siirtäminen PostgreSQL:ään

blunderdb migrate kopioi yhden käyttäjän SQLite-tietokannan PostgreSQL-taustajärjestelmään valitun vuokralais-scopen alle — tämä on tapa « ladata » työpöytäkirjasto palvelinkäyttöönottoon.

blunderdb migrate \
    --from sqlite:///chemin/vers/base.db \
    --to   "postgres://user:pass@host:5432/db?sslmode=disable" \
    --tenant-id mon-tenant

# Prévisualiser sans rien écrire
blunderdb migrate --from sqlite:///chemin/vers/base.db \
    --tenant-id mon-tenant --dry-run

Migraatio kopioi asemat, niiden analyysit ja kommentit, ottelut (pelit + siirrot), turnaukset (ottelulinkkeineen) ja kokoelmat (koostumuksineen), kohdistaen pää- ja viiteavaimet uudelleen, kaiken kohdepuolen yhdessä transaktiossa: toiminto on atominen (epäonnistuminen jättää kohteen koskemattomaksi, riittää että käynnistää uudelleen). Edistyminen ja lopullinen yhteenveto tulostetaan NDJSON-muodossa vakiotulosteeseen.

Valinta	Oletus	Merkitys
--from <uri>	–	lähde-SQLite-tietokanta (sqlite:///polku tai pelkkä polku)
--to <dsn>	–	kohde-PostgreSQL:n DSN (postgres://…)
--tenant-id <scope>	–	kohteen vuokralais-scope (pakollinen paitsi --dry-run-tilassa)
--dry-run	–	laskee, mitä kopioitaisiin, kirjoittamatta mitään
--on-conflict <käytäntö>	""	"" keskeyttää, jos vuokralaisella on jo tietoja; skip yhdistää (asemien deduplikointi Zobrist-hashin perusteella)

Muista

Vielä migroimatta jäävät sovellustilat: Anki-pakat/-kortit, suodatinkirjasto, haku- ja komentohistoria sekä istunnon metatiedot. Etusijalla on asemakirjaston ja otteluhistorian migraatio.

8.5. Yleiskäyttöinen call-välittäjä

Aiempien alikomentojen (Komentoriviliittymä (CLI)) lisäksi blunderdb call tarjoaa kaikki tallennustoiminnot suoraan paikallisesti. Se kulkee samojen käsittelijöiden kautta kuin serve-demoni: toiminta on siis identtinen komennon POST /v1/<perhe>.<metodi> kanssa. Tämä on hyödyllistä skriptauksessa ja integraatiotesteissä.

# Lister toutes les méthodes disponibles
blunderdb call --list

# Lectures
blunderdb call metadata.counts --db ma_base.db
blunderdb call positions.list  --db ma_base.db --json '{"limit":10}'
blunderdb call matches.get     --db ma_base.db --json '{"id":1}'

# Écritures
blunderdb call positions.save  --db ma_base.db --json '{"position":{...}}'
blunderdb call matches.delete  --db ma_base.db --json '{"id":42}'

Valinnat:

Valinta	Oletus	Merkitys
--db <polku>	–	SQLite-tiedosto (oikotie komennolle --backend sqlite --dsn <polku>)
--backend <tyyppi>	sqlite	sqlite tai postgres
--dsn <merkkijono>	$BLUNDERDB_DSN	taustajärjestelmän yhteysmerkkijono
--scope <merkkijono>	default	vuokralais-scope (lähetetään otsakkeena X-Tenant-ID)
--json <merkkijono>	{}	pyynnön runko JSON-muodossa
--json-file <polku>	–	lukee pyynnön rungon tiedostosta
--list	–	näyttää kaikki metodit <perhe>.<metodi> ja lopettaa

JSON-vastaus (tai NDJSON-virta *.list-päätepisteille) kirjoitetaan vakiotulosteeseen. Virhetilanteessa prosessi päättyy nollasta poikkeavalla koodilla ja kuori {"error":{…}} tulostetaan vakiotulosteeseen, jotta se pysyy jäsenneltävänä (esimerkiksi jq:lla).