# Démarrage rapide : navigateur

[`barrel-lite`](/fr/docs/concepts/glossary#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.

<Goal items={["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_server` joignable. Voir [Démarrage rapide :
  serveur](/fr/docs/start/quickstart-server).
- 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 :

```shell
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:

```erlang
[{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](/fr/docs/concepts/glossary#space), une
base créée via la couche agents de Barrel et que vous pouvez partager, et
émettez pour lui un [jeton de
capacité](/fr/docs/concepts/glossary#capability-token). 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 :

```shell
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", ...}}
```

> **Note:** 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.

```ts

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"}
```

> **Note:** `put` a répondu avec l’id du document et sa `version`, le jeton de
> [révision](/fr/docs/concepts/glossary#revision) 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.

```ts
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 :

```ts
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"}]
```

> **Note:** 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](/fr/docs/concepts/glossary#conflict), à vous de le résoudre.
Modifiez la note sur les deux copies avant qu’elles se synchronisent,
puis synchronisez :

```ts
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"}}]
```

> **Note:** 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](/fr/docs/concepts/glossary#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 :

```ts
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"}
[]
```

> **Note:** 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](/fr/docs/guides/barrel-lite).

<NextSteps steps={[
  { href: '/docs/guides/barrel-lite', label: 'barrel-lite', why: 'Lisez la description complète du client : stockage, synchronisation continue, pièces jointes et onglets multiples.' },
  { href: '/docs/concepts/versions', label: 'Versions, conflits, convergence', why: 'Comprenez comment chaque copie choisit le même gagnant.' },
  { href: '/docs/concepts/spaces', label: 'Espaces et capacités', why: 'Restreignez et révoquez les jetons que vous donnez aux navigateurs et aux agents.' },
]} />
