Barrel
EN GitHub

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

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 :

sys.config
[{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"]}'
Sortie d’une exécution sur barrel_server 1.13.0
{"ok":true,"space":"sp_7uitvqeved3z7seu"}
{"token":
"bsp_alrw6fxiqga5r47x_odwpp27li6m754pfsuhbwd2n2vxek3ox44hj3zxv",
"grant":{"rights":["read","write"],
        "space":"sp_7uitvqeved3z7seu", ...}}
Ce qui vient de se passer

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");
Sortie d’une exécution de barrel-lite 0.1.0 dans Node 22
{"id":"n1",
"version":"000001a1ba4159ea00000000@wd31d29e133c6788f"}
{"title":"hello","id":"n1"}
Ce qui vient de se passer

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'");
Sortie d’une exécution de barrel-lite 0.1.0 dans Node 22 contre barrel_server 1.13.0
{"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"}]
Ce qui vient de se passer

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");
Sortie d’une exécution de barrel-lite 0.1.0 dans Node 22 contre barrel_server 1.13.0
{"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"}}]
Ce qui vient de se passer

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");
Sortie d’une exécution de barrel-lite 0.1.0 dans Node 22 contre barrel_server 1.13.0
{"id":"n1","title":"hello from both"}
[]
Ce qui vient de se passer

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

Limite

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) et SUBSCRIBE ne s’exécutent que sur le serveur ; utilisez db.queryRemote. En local, elles lèvent BqlServerOnlyError.
  • 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.

Traduit de la page anglaise: /docs/start/quickstart-browser/ Modifier cette page Voir en Markdown

Haut et bas pour se déplacerEntrée pour ouvrir