Démarrage rapide : navigateur
barrel-lite est un client
TypeScript qui garde une copie d’une base Barrel dans le navigateur. Les
lectures et les écritures sont locales : l’application répond tout de
suite et continue de fonctionner hors ligne ; la synchronisation envoie
les écritures locales à un barrel_server et rapporte les modifications
faites par les autres copies. Dans ce démarrage rapide, vous construisez
une petite application de notes qui tourne sur deux appareils, un
portable et un téléphone : vous donnez au navigateur un jeton restreint,
écrivez une note, la synchronisez vers le deuxième appareil, puis la
modifiez sur les deux à la fois et résolvez le conflit. Suivez ce
parcours quand une application web doit continuer de fonctionner sans
réseau.
Ce que vous allez faire
- Compiler barrel-lite et l’ajouter à une application web
- Donner au navigateur un jeton limité à un espace
- Écrire et lire des documents en local
- Synchroniser deux copies via barrel_server
- Résoudre un conflit entre deux modifications
Avant de commencer
- Un
barrel_serverjoignable. Voir Démarrage rapide : serveur. - Node.js 20 ou plus récent, et npm.
1. Obtenir barrel-lite
Vous compilez le client depuis les sources de Barrel, car barrel-lite
0.1.0 n’est pas sur npm. Compilez-le depuis l’umbrella et
installez-le dans votre application depuis ce répertoire :
cd barrel/clients/barrel-lite
npm ci
npm run build
cd /path/to/your-app
npm install /path/to/barrel/clients/barrel-lite
2. Laisser entrer le navigateur
Une page web tourne sur sa propre origine et n’importe qui peut lire son
code : le serveur doit donc autoriser les requêtes cross-origin (CORS), et
la page doit porter un jeton qui accorde le moins possible. Ajoutez CORS
et un jeton d’administration global au sys.config du serveur et
redémarrez-le :
[{barrel_server, [
{http_port, 8080},
{cors, #{origins => '*',
expose => [<<"x-barrel-hlc">>]}},
{auth, #{tokens => [<<"global-token">>]}}]}]. Ne mettez jamais le jeton global dans une page web : il ouvre toutes les bases. Créez plutôt un espace, une base créée via la couche agents de Barrel et que vous pouvez partager, et émettez pour lui un jeton de capacité. Un jeton de capacité accorde des droits nommés sur un seul espace, et vous pouvez le révoquer. L’id de l’espace est le nom de base qu’utilise le navigateur :
curl -X POST localhost:8080/spaces \
-H 'authorization: Bearer global-token' \
-H 'content-type: application/json' -d '{"label":"app"}'
curl -X POST localhost:8080/spaces/sp_7uitvqeved3z7seu/grants \
-H 'authorization: Bearer global-token' \
-H 'content-type: application/json' \
-d '{"rights":["read","write"]}'
{"ok":true,"space":"sp_7uitvqeved3z7seu"}
{"token":
"bsp_alrw6fxiqga5r47x_odwpp27li6m754pfsuhbwd2n2vxek3ox44hj3zxv",
"grant":{"rights":["read","write"],
"space":"sp_7uitvqeved3z7seu", ...}} Le premier appel a créé l’espace sp_7uitvqeved3z7seu. Le second a émis
un jeton bsp_... avec read et write sur cet espace et rien d’autre.
Le jeton n’est affiché qu’une fois, car le serveur n’en garde qu’une
empreinte ; copiez-le maintenant. read couvre les pulls, write couvre
les pushes.
3. Ouvrir, écrire, lire
Database.open crée la copie locale et retient la base du serveur avec
laquelle elle se synchronise. Vous écrivez et lisez ensuite comme si la
base était locale, parce qu’elle l’est.
import { Database } from "barrel-lite";
const remote = {
url: "http://localhost:8080",
db: "sp_7uitvqeved3z7seu",
token: "bsp_alrw6fxiqga5r47x_...",
};
const laptop = await Database.open("notes", { remote });
await laptop.put({ id: "n1", title: "hello" });
await laptop.get("n1");
{"id":"n1",
"version":"000001a1ba4159ea00000000@wd31d29e133c6788f"}
{"title":"hello","id":"n1"} put a répondu avec l’id du document et sa version, le jeton de
révision de cette écriture, le
même que le serveur appelle _rev. get a relu la note depuis le
stockage local. Rien n’a encore atteint le serveur.
Les écritures vont tout de suite dans le stockage local. Dans un navigateur, ce stockage est OPFS ; là où OPFS manque (Node, par exemple), il est en mémoire.
4. Synchroniser
La synchronisation permet aux copies de se rattraper. Un push envoie les
écritures locales au serveur, un pull applique les changements que le
serveur tient des autres copies, et sync() fait les deux.
await laptop.sync(); // push, puis pull
const live = laptop.liveSync(); // synchroniser en continu
live.stop();
Ouvrez une deuxième copie de la même façon, sur un autre appareil ou dans un autre navigateur. Sa première synchronisation fait entrer le document, et le BQL local le lit :
const phone = await Database.open("notes", { remote });
await phone.sync();
await phone.get("n1");
await phone.query(
"SELECT id, title FROM db WHERE title = 'hello'");
{"push":{"pushed":1,"skipped":0,"conflicts":0},
"pull":{"scanned":1,"applied":0}}
{"push":{"pushed":0,"skipped":0,"conflicts":0},
"pull":{"scanned":1,"applied":1}}
{"id":"n1","title":"hello"}
[{"id":"n1","title":"hello"}] La première ligne est le sync() du portable : son push a envoyé un
document (pushed: 1), et son pull a vu un changement sur le serveur, le
sien, donc rien à appliquer. La deuxième ligne est celle du téléphone :
rien à pousser, et un changement appliqué, la note. Le téléphone relit
ensuite la note en local, par id et avec BQL.
5. Résoudre un conflit
Des copies hors ligne peuvent modifier la même note en même temps. Barrel ne jette aucune des deux modifications : les deux versions sont gardées, chaque copie choisit le même gagnant, et l’autre version est gardée comme conflit, à vous de le résoudre. Modifiez la note sur les deux copies avant qu’elles se synchronisent, puis synchronisez :
await laptop.put({ id: "n1", title: "hello from the laptop" });
await phone.put({ id: "n1", title: "hello from the phone" });
await laptop.sync(); await phone.sync(); await laptop.sync();
await laptop.get("n1");
await phone.get("n1");
await laptop.conflicts("n1");
{"id":"n1","title":"hello from the phone"}
{"id":"n1","title":"hello from the phone"}
[{"version":"000001a1ba415a1600000001@wd31d29e133c6788f",
"deleted":false,
"body":{"id":"n1","title":"hello from the laptop"}}] Les deux copies affichent la modification du téléphone : le gagnant est
la version au jeton le plus élevé, si bien que chaque copie arrive à la
même réponse sans se concerter. C’est la
convergence. La modification
du portable n’est pas perdue : conflicts la renvoie avec sa version et
son corps.
resolve remplace le gagnant et chaque conflit par un seul corps.
Poussez-le, et l’autre copie reçoit la résolution à son prochain pull :
await laptop.resolve("n1", { title: "hello from both" });
await laptop.push();
await phone.pull();
await phone.get("n1");
await phone.conflicts("n1");
{"id":"n1","title":"hello from both"}
[] Le téléphone lit maintenant le corps résolu, et sa liste de conflits est vide : la résolution a remplacé les deux versions sur chaque copie qui l’a reçue.
put sur un document en conflit ne remplace que le gagnant ; les
conflits restent. Passez null à resolve pour résoudre par une
suppression.
Notes
Le stockage local est un cache. Les écritures pas encore vidées sur disque sont perdues en cas de plantage, et le navigateur peut effacer tout le stockage. La copie du serveur fait foi : synchronisez souvent.
- La recherche vectorielle, par mot-clé et hybride (
vector_top_k,bm25_top_k,hybrid_top_k) etSUBSCRIBEne s’exécutent que sur le serveur ; utilisezdb.queryRemote. En local, elles lèventBqlServerOnlyError. - barrel-lite s’authentifie uniquement avec des jetons bearer, globaux ou de capacité. Il ne signe pas les requêtes.
- Avec
multiTab: true, un seul onglet synchronise et les autres passent par lui. - Le client complet est décrit dans barrel-lite.