Barrel
EN GitHub

Applications hors ligne d’abord

Gardez une copie des données dans le navigateur, pour qu’une application de terrain lise et écrive sans connexion et se synchronise dans les deux sens quand le réseau revient.

Construit avec barrel-lite, un client TypeScript qui parle le même protocole _sync que les nœuds Barrel, et barrel_server. barrel-lite n’est pas encore sur npm.

Le problème

Une application de terrain doit continuer à fonctionner dans un sous-sol ou un train et se remettre à jour ensuite sans perdre de modifications. Les applications qui font une requête par action cessent de fonctionner hors ligne, et les files de synchronisation écrites à la main perdent un côté de chaque modification concurrente.

Comment les pièces s’assemblent

  1. Dans le navigateur

    • Votre application web TypeScript, lit et écrit en local
    • barrel-lite la copie locale, stockée dans OPFS
  2. push et pull en HTTPS
  3. barrel_server

    • /db/:db/_sync le protocole de réplication, avec CORS
    • Space sp_… la copie du serveur
  4. réplication
  5. Autres copies

    • Autres appareils leur propre copie barrel-lite
    • Nœuds Erlang Barrel intégré, même protocole

La copie du navigateur est une réplique complète : elle marque ses écritures avec son propre identifiant de source et tient ses propres points de reprise, si bien que le serveur n’a besoin d’aucun état par client. Un seul onglet par origine se synchronise ; les autres passent par lui.

Le construire

Six étapes : compiler le client, ouvrir le serveur au navigateur, puis le code de votre application.

  1. Compiler barrel-lite

    barrel-lite 0.1.0 n’est pas encore sur npm. Compilez-le depuis le dépôt barrel et installez-le dans votre application depuis le chemin local.

    Shell
    cd barrel/clients/barrel-lite
    npm install && npm run build
    cd ../../../my-app
    npm install ../barrel/clients/barrel-lite
  2. Ouvrir le serveur au navigateur

    Autorisez votre origine avec CORS et exposez x-barrel-hlc, qui transporte l’horloge. Gardez le jeton global côté serveur.

    sys.config
    [{barrel_server, [
       {cors, #{origins => [<<"https://app.example">>],
                expose => [<<"x-barrel-hlc">>]}},
       {auth, #{tokens => [<<"global-token">>]}}
     ]}].
  3. Donner à chaque appareil un jeton pour un espace

    Votre backend crée un espace et accorde un jeton : read couvre le pull, write couvre le push. Le navigateur ne détient jamais que ce jeton.

    REST, depuis votre backend
    curl -X POST host:8080/spaces \
      -H 'authorization: Bearer global-token' \
      -H 'content-type: application/json' \
      -d '{"label":"field-visits"}'
    curl -X POST host:8080/spaces/sp_…/grants \
      -H 'authorization: Bearer global-token' \
      -H 'content-type: application/json' \
      -d '{"rights":["read","write"],"subject":"tablet-7"}'
  4. Ouvrir la copie locale et écrire, en ligne ou non

    Les écritures arrivent tout de suite dans le stockage local et sont poussées à la synchronisation suivante. Le stockage est OPFS quand le navigateur le propose, la mémoire sinon.

    TypeScript
    import { Database } from "barrel-lite";
    
    const db = await Database.open("visits", {
      remote: { url: "https://hub.example:8080",
                db: "sp_…", token: "bsp_…" },
      multiTab: true,
    });
    await db.put({ id: "v-311", site: "Lyon 2" });
    const visit = await db.get("v-311");
  5. Synchroniser tant que le réseau est là

    La synchronisation continue interroge le serveur 500 ms après une activité et espace ses appels jusqu’à 30 s au repos ; une écriture locale la réveille, et les erreurs espacent les tentatives de 1 s à 60 s. continuous: true ajoute un flux d’événements envoyés par le serveur.

    TypeScript
    const live = db.liveSync({ continuous: true });
    db.onStatus((s) => setBadge(s.state)); // idle, syncing…
    db.onChange((c) => render(c.id, c.source));
    // later
    live.stop();
  6. Résoudre les conflits sur l’appareil

    Si l’appareil et une autre copie ont modifié le même document chacun de leur côté, les deux versions sont conservées, sur l’appareil et sur le serveur, et toutes les copies affichent le même gagnant. resolve remplace le gagnant et tous les conflits.

    TypeScript
    const db = await Database.open("visits", {
      remote,
      onConflict: (e) => console.warn("conflict on", e.id),
    });
    await db.sync();
    const current = await db.get("v-311");
    const others = await db.conflicts("v-311");
    if (others.length > 0) {
      await db.resolve("v-311", merge(current, others));
      await db.push();
    }

Ce que fait Barrel

  • Garde la copie locale dans OPFS et y répond aux lectures et aux requêtes BQL locales
  • Fait push et pull via /db/:db/_sync, en reprenant depuis ses points de reprise
  • Garde les versions concurrentes comme conflits et choisit le même gagnant que le serveur
  • Élit un onglet meneur avec Web Locks et relaie les autres via BroadcastChannel
  • Synchronise les pièces jointes, dédupliquées par empreinte

Ce que fait votre application

  • Émet depuis votre backend un jeton de capacité par appareil ou par utilisateur
  • Affiche l’état de synchronisation et l’état hors ligne dans l’interface
  • Fusionne les versions en conflit d’une façon adaptée à vos données
  • Récupère un sous-ensemble avec un filtre ou un canal quand un appareil ne doit pas tout détenir

Limites

  • Pas encore sur npm : compilez-le depuis clients/barrel-lite dans le dépôt.
  • Le stockage local est un cache. Les écritures pas encore vidées sur disque sont perdues en cas de plantage, et le navigateur peut évincer le stockage (Safari le fait) ; la copie du serveur fait foi.
  • L’état offline n’est jamais émis : détectez l’absence de connexion dans votre application, par exemple avec navigator.onLine.
  • Les recherches vectorielle, par mots-clés et hybride et SUBSCRIBE ne tournent que sur le serveur. Il n’y a pas de recherche plein texte locale ; la recherche vectorielle locale classe les embeddings synchronisés par force brute.
  • Jetons bearer uniquement : pas de requêtes signées depuis le navigateur.

Aller plus loin

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