Barrel
EN GitHub

Synchronisation

Barrel réplique les documents entre bases avec un protocole à vecteurs de versions : ordre causal issu d’une horloge logique hybride (HLC), gagnants déterministes, livraison idempotente et checkpoints pour reprendre. La réplication s’exécute dans la même VM ou sur HTTP face à un barrel_server. Lisez ce guide si vous devez copier deux bases ou les garder synchronisées, répliquer un sous-ensemble avec des canaux, ou déplacer les pièces jointes avec les documents.

Ce que c’est

La réplication vit dans barrel_docdb (barrel_rep). Une exécution :

  1. Lit le checkpoint (un document local des deux côtés) pour trouver le dernier HLC envoyé.
  2. Récupère les changements de la source depuis ce HLC, filtre appliqué à la source.
  3. Compare les jetons de version proposés avec la cible en un seul aller-retour.
  4. Fait un put_version des documents manquants sur la cible (idempotent : une livraison au moins une fois est donc sûre).
  5. Pose un checkpoint par lot, puis lance la phase des pièces jointes (voir plus bas).

Les deux côtés convergent vers le même gagnant, le même corps et le même état de suppression pour chaque document, quel que soit l’entrelacement des écritures. Les conflits sont enregistrés là où la concurrence a été observée et se résolvent en écrivant une version qui les remplace.

Les transports implémentent le behaviour barrel_rep_transport. Deux sont disponibles aujourd’hui : barrel_rep_transport_local (même VM, noms de bases) et barrel_rep_transport_http (client hackney qui parle le protocole /db/:db/_sync/* servi par barrel_server).

Quand l’utiliser

  • Copier une base vers une autre, dans la même VM ou sur un autre nœud.
  • Garder des répliques cohérentes à terme, en une fois par exécution ou en continu.
  • Répliquer un sous-ensemble de documents avec un filtre de canal, de chemin ou de requête.
  • Déplacer les blobs des pièces jointes avec leurs documents, adressés par contenu.

Comment faire (même VM)

{ok, _} = barrel_docdb:create_db(<<"source">>),
{ok, _} = barrel_docdb:create_db(<<"target">>),
{ok, _} = barrel_docdb:put_doc(<<"source">>, #{<<"id">> => <<"a">>, <<"v">> => 1}),

{ok, Result} = barrel_rep:replicate(<<"source">>, <<"target">>),
#{docs_written := N, att_sync := _} = Result.

Relancez-la plus tard pour récupérer les nouveaux changements ; elle reprend depuis le checkpoint.

Comment faire (sur HTTP)

Le côté distant est une URL sous un barrel_server en cours d’exécution. La base doit y exister : la réplication ne la crée pas, et une base inconnue répond 404. Créez-la d’abord (PUT /db/inventory). Construisez un endpoint, puis passez le transport correspondant :

Endpoint = barrel_rep_transport_http:endpoint(
    <<"http://edge-1.example.com:8080/db/inventory">>),

%% push
{ok, _} = barrel_rep:replicate(<<"inventory">>, Endpoint,
    #{target_transport => barrel_rep_transport_http}),

%% pull
{ok, _} = barrel_rep:replicate(Endpoint, <<"inventory">>,
    #{source_transport => barrel_rep_transport_http}).

endpoint/1 normalise l’URL (schéma et hôte en minuscules, pas de barre oblique finale). L’URL normalisée est l’identité de la réplication : changer son texte démarre un nouveau checkpoint, changer les identifiants ou les réglages non. La map d’endpoint accepte aussi pool, connect_timeout, recv_timeout et headers.

JSON et CBOR sur les routes de synchronisation

JSON reste le format par défaut. CBOR n’est utilisé que pour les documents que JSON ne peut pas transporter : un document contenant un binaire qui n’est pas de l’UTF-8 valide (un hash brut, par exemple). La réplication barrel choisit l’encodage à chaque requête ; un client JSON n’a rien à changer.

Ce que fait le serveur avec chaque encodage :

Vous envoyez ou demandezLe serveur
un corps sans content-type: application/cborle lit comme du JSON, comme avant ; vv est en base64
un corps avec content-type: application/cborle lit comme du CBOR ; vv est une chaîne d’octets
pas d'accept, */* ou application/jsonrépond en JSON, comme avant
un accept qui nomme application/cborrépond en CBOR, erreurs comprises
un document que JSON ne peut pas transporter, sans CBOR dans acceptrépond 406 not_acceptable

Un corps mal formé répond 400 (bad_json ou bad_cbor). Les routes de pièces jointes transmettent des octets bruts en flux et répondent les erreurs en JSON quel que soit votre accept.

La réplication barrel envoie du JSON chaque fois que JSON peut transporter le document et demande du CBOR quand elle en récupère un. Les deux pairs ont besoin de barrel_docdb 1.8.0 et barrel_server 1.11.0 pour déplacer un document que JSON ne peut pas transporter ; tout le reste se réplique avec des pairs plus anciens comme avant. Un client uniquement JSON, comme barrel-lite, ne produit jamais un tel document ; il ne reçoit une 406 que quand il en récupère un poussé par un pair CBOR.

Comment faire (authentification)

Protégez un serveur avec des jetons bearer statiques ; une liste accepte l’ancien et le nouveau pendant une rotation. /health reste ouvert, tout le reste exige le jeton :

%% côté serveur (env de l'application, avant le démarrage de barrel_server)
application:set_env(barrel_server, auth, #{tokens => [<<"s3cret">>]}).

Donnez au client son jeton sur l’endpoint, ou indexé par origine dans l’env de l’application pour que les configurations de tâches persistées ne contiennent aucun secret :

Authed = Endpoint#{auth => #{token => <<"s3cret">>}},
%% ou
application:set_env(barrel_docdb, sync_auth,
                    #{<<"http://edge-1.example.com:8080">> => <<"s3cret">>}).

Comment faire (requêtes signées)

Sans TLS, un jeton bearer peut être rejoué. Pour une authentification Ed25519 par requête, ajoutez accept (la liste des méthodes acceptées) et signers (keyId vers une clé publique brute de 32 octets). Chaque requête est signée sur ts|keyId|nonce|METHOD|target|sha256(body), où nonce est neuf à chaque requête et target est le chemin plus ? et la chaîne de requête brute quand il y en a une (signature v2), avec protection contre le rejeu et une fenêtre de décalage d’horloge. accept => [bearer, signed] accepte les deux, pour qu’une flotte bascule nœud par nœud ; accept => [bearer] (ou l’absence d'accept) donne exactement le comportement bearer seul décrit plus haut.

%% serveur : connaître la clé publique de chaque pair
application:set_env(barrel_server, auth,
                    #{accept  => [bearer, signed],
                      signers => #{<<"node1">> => PubKey32},
                      skew_ms => 300000}).

%% client : signer avec la clé privée correspondante (endpoint ou env par origine)
Signed = Endpoint#{signing => #{key_id => <<"node1">>, priv_key => Priv32}},
%% ou
application:set_env(barrel_docdb, sync_signing,
                    #{<<"https://edge-1.example.com:8443">> =>
                          #{key_id => <<"node1">>, priv_key => Priv32}}).

Générez une paire de clés avec crypto:generate_key(eddsa, ed25519). La signature l’emporte sur un jeton bearer sur le même endpoint. Les clés privées ne sont jamais écrites dans les configurations de tâches persistées.

Passer de la signature v1 (barrel_docdb < 1.4.0, sans nonce, chemin seul) à la v2 : les serveurs en barrel_server 1.6.0+ acceptent les deux, donc mettez d’abord à jour tous les serveurs, puis les clients, qui n’envoient que la v2 (un client v2 face à un serveur plus ancien est refusé avec une 401 sur chaque requête signée). Quand plus aucun client n’envoie de v1 (les acceptations v1 sont journalisées au niveau debug), fermez la fenêtre v1 :

application:set_env(barrel_server, auth,
                    #{accept => [signed], signers => Signers,
                      require_nonce => true}).

Un reverse proxy placé devant le point d’accès de synchronisation doit transmettre le chemin et la chaîne de requête sans les modifier : la requête fait partie de la cible signée.

La signature v3 couvre aussi les en-têtes de requête qui changent l’effet d’une écriture : content-type, if-match, if-none-match, x-barrel-actor, x-barrel-session, x-barrel-source, x-barrel-hlc et les en-têtes de pièces jointes x-barrel-att-origin, x-barrel-digest et x-barrel-att-touch. Chacun est signé comme présent avec sa valeur ou comme absent, et le serveur n’agit que sur les valeurs signées : modifiez-en un et la requête répond 401. Les clients à partir de barrel_docdb 2.1.0 n’envoient que la v3. Pour y passer :

  1. Mettez d’abord à jour tous les serveurs en barrel_server 1.13.0 (un client v3 est refusé par un serveur plus ancien).
  2. Mettez à jour les clients. Entre-temps, les requêtes v1 et v2 continuent de répliquer les documents, mais le serveur ignore leur x-barrel-hlc et les refuse avec une 401 {"error":"signature_v3_required"} quand elles écrivent une pièce jointe ou portent un des autres en-têtes ci-dessus.

Un proxy doit transmettre ces en-têtes sans les modifier et ne doit pas envoyer deux fois un en-tête signé.

Sur chaque requête signée avec un corps, sur n’importe quelle route, le serveur vérifie le corps par rapport au x-barrel-content-sha256 signé avant l’exécution du handler et répond 401 {"error":"content_hash_mismatch"} quand il manque ou ne correspond pas. Une requête qui présente une signature est jugée sur elle seule : une signature invalide répond 401 même si un jeton bearer ou un certificat client accepté aurait laissé passer la requête.

Ce que la signature vous apporte : elle authentifie le client et protège l’intégrité de chaque requête. Elle ne cache ni la requête ni la réponse, et n’authentifie pas les réponses du serveur. Faites passer le point d’accès de synchronisation en HTTPS vérifié si vous avez besoin de l’un ou de l’autre. Les requêtes bearer tirent leur intégrité du seul HTTPS.

Comment faire (TLS et mTLS)

barrel_server sert du HTTP/1.1 en clair par défaut. Configurez des listeners pour ajouter HTTP/2, HTTP/3 et TLS. Régler verify => verify_peer fait d’un listener un filtre TLS mutuel : un client sans certificat signé par l’autorité de certification est refusé lors de la poignée de main. Le client de réplication parle HTTP/1.1 : placez donc le filtre de synchronisation sur un listener H1 sur TLS (tls => true sur l’entrée http).

application:set_env(barrel_server, listeners,
                    #{http  => #{port => 8443, tls => true},  %% H1 sur TLS
                      https => #{port => 8444},               %% H2
                      http3 => #{port => 8444}}),             %% H3
application:set_env(barrel_server, tls,
                    #{certfile => "server.pem", keyfile => "server.key",
                      cacertfile => "ca.pem", verify => verify_peer}),
application:set_env(barrel_server, auth, #{accept => [mtls]}).

%% client : présenter son certificat (endpoint ou env par origine)
Mtls = Endpoint#{ssl_options => [{certfile, "client.pem"},
                                 {keyfile, "client.key"},
                                 {cacertfile, "ca.pem"}]}.

Notes : H1-TLS et H2 sont de vrais filtres mTLS (ssl d’OTP). H3 sert en TLS mais ne filtre pas encore par certificat client (un changement au niveau QUIC est en attente) ; ne comptez pas sur H3 pour le mTLS.

Ce que le mTLS authentifie : que le client détient un certificat chaîné à l’autorité de certification configurée, pas de quel client il s’agit. accept => [mtls] seul traite chacun de ces clients comme un même pair de confiance ayant accès à toutes les bases. Pour l’identité et des droits par base, ajoutez par-dessus une authentification bearer ou signée (accept => [mtls, signed] filtre le transport et identifie le pair par sa clé de signature). Associer un certificat client à une identité nécessite que livery expose le certificat du pair, ce qu’il ne fait pas encore.

Une requête est jugée sur l’identifiant qu’elle présente : une signature, sinon un jeton bearer ou de capacité dans Authorization. Si cet identifiant échoue, ou si son schéma n’est pas compris, la réponse est 401 même avec un certificat client accepté ; le certificat seul n’authentifie que les requêtes sans en-tête Authorization.

Comment faire (réplication sélective)

Les filtres s’appliquent à la source. Les filtres de chemin et de requête se combinent par AND :

{ok, _} = barrel_rep:replicate(<<"source">>, <<"target">>, #{
    filter => #{
        paths => [<<"users/#">>],
        query => #{where => [{path, [<<"status">>], <<"active">>}]}
    }
}).

Les canaux sont l’alternative indexée : des ensembles de motifs nommés déclarés à la création de la base, matérialisés à l’écriture dans un flux par canal, de sorte qu’un pull filtré est un seul parcours borné au lieu d’un parcours complet du flux :

{ok, _} = barrel_docdb:create_db(<<"source">>, #{
    channels => #{<<"mobile">> => [<<"type/task">>, <<"owner/+">>]}
}),
{ok, _} = barrel_rep:replicate(<<"source">>, <<"target">>, #{
    filter => #{channel => <<"mobile">>}
}).

Notes sur les canaux :

  • Les motifs sont de style MQTT (+ pour un segment, # final pour le reste).
  • Les canaux sont fixés à la création et indexent les écritures faites après la création.
  • Un document qui cesse de correspondre cesse d’être envoyé ; les répliques gardent leur dernière copie (pas de suppression côté cible). Une nouvelle réplique ne voit jamais les documents partis.
  • Une réplication filtrée garde son propre checkpoint (le filtre fait partie de l’id de réplication).

Pièces jointes

La synchronisation des pièces jointes accompagne chaque exécution (attachments => true par défaut). C’est une seconde phase après la boucle des documents : le flux de pièces jointes de la source est comparé par empreinte avec la cible, seul le contenu manquant est transféré, et les écritures convergent en last-write-wins sur leur HLC d’origine. Le résultat arrive sous att_sync dans le résultat de la réplication :

{ok, #{att_sync := #{atts_written := _, atts_skipped := _}}} =
    barrel_rep:replicate(<<"source">>, Endpoint,
        #{target_transport => barrel_rep_transport_http}).

Notes :

  • Sur HTTP, les blobs circulent par morceaux dans les deux sens ; rien ne met un blob entier en mémoire tampon. Les pulls n’ont pas de plafond de taille. Les pushs sont bornés par l’env {barrel_server, max_body, Bytes} du serveur (1 Gio par défaut, infinity accepté) ; un push plus gros reçoit une 413, échoue pour cette pièce jointe seulement, et l’exécution le signale dans att_write_failures.
  • Il n’y a pas d’ordre entre les documents et leurs pièces jointes : un document peut arriver avant son blob (les lectures répondent 404 jusqu’à l’arrivée de la phase des pièces jointes).
  • Les pièces jointes écrites avant cette fonctionnalité ne se synchronisent pas tant qu’elles ne sont pas réécrites, ou synthétisez une fois leurs lignes de flux avec barrel_docdb:rebuild_attachment_feed/1.
  • Désactivez la phase avec attachments => false ; elle se dégrade d’elle-même en att_sync => skipped quand un côté ne peut pas suivre les pièces jointes.

Réplication continue (tâches)

Le gestionnaire de tâches (barrel_rep_tasks) conserve les réplications à travers les redémarrages. Les extrémités distantes sont des URL ; le transport HTTP est choisi automatiquement :

{ok, TaskId} = barrel_rep_tasks:start_task(#{
    source => <<"inventory">>,
    target => <<"http://edge-1.example.com:8080/db/inventory">>,
    mode => continuous,          %% ou one_shot
    direction => push,           %% push | pull | both
    filter => #{channel => <<"mobile">>}
}),
{ok, #{status := running}} = barrel_rep_tasks:get_task(TaskId),
ok = barrel_rep_tasks:stop_task(TaskId).

Comportement continu :

  • Les sources locales sont pilotées par événements : la tâche se réveille sur le flux de changements et le vide à travers son filtre, si bien que la convergence locale prend quelques dizaines de millisecondes. Si le flux se termine, la tâche continue et passe au polling.
  • Les sources distantes font un polling adaptatif, 500 ms après des données et en ralentissant jusqu’à 15 s au repos.
  • Les erreurs transitoires ne tuent pas une tâche continue : elle temporise (de 1 s à 60 s, avec gigue), enregistre last_error dans le document de tâche et reste running. Les tâches en une fois échouent vite.
  • Une base locale de la tâche qui se ferme (fermeture pour inactivité, close_db/1), source ou cible, met la tâche en pause : statut paused, paused_reason => <<"db_closed">>. Dans les 5 s qui suivent la réouverture de ses bases locales, la tâche reprend depuis son checkpoint. Une tâche que vous avez mise en pause avec pause_task/1 ou stop_task/1 reste en pause.
  • Les documents de tâche ne stockent les endpoints que sous forme d’URL ; les jetons viennent de sync_auth.

Vecteurs que vous fournissez

Un vecteur que vous écrivez avec un document (_embedding, source client) appartient à cette version et se réplique avec elle. Lisez cette section quand le vecteur ne peut pas être calculé à partir du texte sur un autre nœud, par exemple quand le texte est chiffré.

  • Chaque version vivante garde son propre vecteur : la version courante, les versions sœurs en conflit, et les versions passées jusqu’à ce que la rétention les supprime. Une version qui redevient courante, par une résolution ou une branche à un instant donné, est indexée avec son propre vecteur.
  • Les vecteurs calculés (source computed) ne voyagent pas. Chaque nœud les recalcule à partir du texte.

Résolvez un conflit avec un vecteur à vous quand le corps fusionné en a besoin : envoyez le document fusionné avec _observed (obtenu par GET /db/:db/doc/:id?conflicts=true) et _embedding.

$ curl -XPUT localhost:8080/db/mydb/doc/m -H 'content-type: application/json' \
    -d '{"text": "merged", "_observed": [...], "_embedding": [0.1, 0.2, 0.3]}'

Depuis Erlang, resolve_conflict garde le vecteur de la version choisie, et prend _embedding dans une fusion :

{ok, _} = barrel_docdb:resolve_conflict(Db, Id, Rev, {choose, Token}),
{ok, _} = barrel_docdb:resolve_conflict(Db, Id, Rev,
                                        {merge, Merged#{<<"_embedding">> => Vec}}).

Lisez une version passée avec son vecteur :

$ curl 'localhost:8080/db/mydb/doc/m/_versions/<rev>?include_embedding=true'

Notes :

  • Le vecteur d’une version passée coûte 4 octets par dimension (6 Ko à 1536 dimensions) et la rétention le supprime avec le corps archivé (retention_period, 30 jours par défaut ; 0 garde les deux pour toujours).
  • Un pair antérieur à barrel_docdb 3.0 ne garde que le vecteur de la version courante. Les vecteurs des autres versions qui passent par lui sont perdus, et reviennent à la prochaine synchronisation directe depuis un pair mis à jour.
  • Une fusion sans _embedding produit un nouveau corps sans vecteur : une base en mode enregistrement calcule l’embedding de son texte.

Horloges

Chaque échange sur le réseau porte un en-tête x-barrel-hlc et les deux côtés l’intègrent à leur horloge, en plus de la poignée de main explicite au début de chaque exécution. Un pair trop en avance est rejeté avec {error, clock_skew} (409 sur le réseau). Pour coupler les horloges à la main :

{ok, _Merged} = barrel_docdb:sync_hlc(RemoteHlc).

Clients navigateur

Le même protocole /db/:db/_sync/* pilote barrel-lite, le client navigateur TypeScript : il garde un stockage OPFS offline-first, horodate les modifications locales avec son propre identifiant de source, et fait push et pull sur ce protocole (polling adaptatif ; avec continuous: true il garde aussi un flux SSE GET /db/:db/changes?feed=continuous qui réveille le poller). Activez CORS et émettez-lui un jeton de capacité. Voir barrel-lite.

Ce qui n’est pas encore couvert

  • Index vectoriels. Les index ne sont pas transmis ; en mode enregistrement, les documents se répliquent, avec les vecteurs que vous avez fournis (voir Vecteurs que vous fournissez), et chaque nœud reconstruit son index. Un client qui a besoin des vecteurs stockés les récupère avec include_embedding sur GET /db/:db/doc/:id ou POST /db/:db/_bulk_get (c’est ce que fait barrel-lite).
  • Certificats client sur HTTP/3. Les listeners H3 servent en TLS mais ne vérifient pas les certificats client ; utilisez H1-TLS ou H2 pour un filtre mTLS.
  • API Barrel. barrel (la base embarquable complète) n’expose pas la réplication ; appelez barrel_rep et barrel_rep_tasks sur le nom docdb sous-jacent.
  • Provenance. L’acteur, la session et la source portés par une écriture (voir audit-provenance) ne voyagent pas sur le réseau. Les arrivées répliquées sont attribuées cause: replicated avec l’identité de la base d’origine ; l’agent qui a agi reste dans la piste propre à l’origine.

Traduit de la page anglaise: /docs/guides/synchronization/ (docs/guides/synchronization.md) Modifier cette page Voir en Markdown

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