Barrel
EN GitHub

barrel_server

Barrel sur HTTP : une API REST, un point d’accès MCP pour les agents, et le protocole de réplication par lequel les autres nœuds et les navigateurs se synchronisent.

Ce qu’elle résout

Les agents, les services et les navigateurs qui ne sont pas des processus Erlang doivent atteindre la base, avec un contrôle d’accès. barrel_server expose les bases, la recherche, la timeline, les espaces et les contextes en REST, sert 39 outils MCP sur /mcp, et vérifie les tokens bearer, les jetons de capacité, les requêtes signées ou le mTLS.

Quand l’utiliser

  • Des clients dans d’autres langages, ou des agents via MCP, doivent lire et écrire.
  • Des nœuds ou des navigateurs barrel-lite répliquent sur HTTP.
  • Vous voulez que les jetons de capacité soient appliqués : c’est le serveur qui les vérifie.

Quand ne pas l’utiliser

  • Tout tourne dans un seul nœud Erlang : appelez directement barrel.

Sa place dans Barrel

Utilisée par
barrel-lite, en HTTP
Autres dépendances
livery (HTTP/1.1, HTTP/2, HTTP/3) et barrel_mcp 4.5.1
Seule
Oui, comme service. Il apporte avec lui barrel, barrel_docdb, barrel_spaces et barrel_ngram. Vous pouvez aussi monter ses routes dans votre propre application livery.

Installation

dépendances rebar.config
{barrel_server, "~> 1.15"}

Dans l’umbrella : rebar3 as server compile, ou rebar3 as server,prod release -n barrel_server.

Configuration

Environnement de l’application (barrel_server)

CléDéfautRôle
http_port 8080 Un seul écouteur HTTP/1.1 en clair quand listeners n’est pas défini
data_dir le data_dir de docdb Copié dans le data_dir de barrel_docdb au démarrage ; les magasins de vecteurs y vont aussi, sous <name>.vectordb
listeners aucun #{http, https, http3}
tls aucun certfile, keyfile, cacertfile, verify
auth aucune (ouvert) #{tokens => [Bin]}, ou accept => [bearer, signed, mtls] avec signers
max_body 1 GiB Taille maximale du corps de requête
cors aucun #{origins, expose, max_age}
mcp activé enabled, allowed_origins, resources
open_opts aucune Options d’ouverture par défaut de chaque base (BM25, embedder)

Seulement les clés les plus utilisées. Pour toutes les options, voyez la référence de configuration et la référence de l’API.

L’API par tâche

Bases et documents (REST)

TâcheAppelRenvoie
Créer, supprimer une base PUT, DELETE /db/:db 201 {"ok":true,"db"} ; les autres routes répondent 404 db_not_found tant qu’elle n’existe pas
Écrire, lire, supprimer PUT, GET, DELETE /db/:db/doc/:id 201 {"id","ok","rev"} ; 409 sur un _rev périmé
En masse POST /db/:db/_bulk_docs, _bulk_get {"results":[...]}
Chercher POST /db/:db/find {"rows","meta"}
BQL POST, GET /db/:db/query lignes NDJSON puis meta ; SSE pour SUBSCRIBE
Changements GET /db/:db/changes JSON, SSE, ou feed=continuous
Pièces jointes PUT, GET, DELETE /db/:db/doc/:id/att/:name 201 avec les infos, octets bruts
Historique GET /db/:db/_history, /doc/:id/_versions versions avec leur provenance

Recherche, timeline, agents (REST)

TâcheAppelRenvoie
Recherche POST /db/:db/search/vector, bm25, hybrid {"hits":[...]}
Branche, fusion POST /db/:db/_timeline/branch, merge 201, 200 avec un rapport
Espaces, autorisations POST /spaces, /spaces/:space/grants {"space"}, {"token","grant"}
Passations POST /handoffs, /handoffs/accept, /handoffs/complete documents de passation
Contextes POST /contexts/_query lignes, sources, résumé

MCP et intégration

TâcheAppelRenvoie
Outils pour agents POST /mcp (tools/list, tools/call) 39 outils : db, doc, query, search, branch, space, session, handoff, context
Monter dans votre application barrel_server_api:routes/0,1, router/0,1 routes, avec groups et prefix

Le démarrer

Un sys.config minimal. Démarrez avec application:ensure_all_started(barrel_server).

sys.config
[
 {barrel_server, [{http_port, 8080},
                  {data_dir, "/var/lib/barrel"}]}
].

Écrire et interroger en REST

D’après une exécution en direct sur un serveur ouvert (sans authentification). Deux autres notes ont été écrites entre les appels montrés, et l’exécution a envoyé la requête en JSON ({"query": ...}) ; la route accepte aussi du BQL brut en texte.

Shell
curl -X PUT $B/db/demo
curl -X PUT $B/db/demo/doc/a \
  -H 'content-type: application/json' \
  -d '{"title":"hello world","kind":"note","n":1}'
curl -X PUT $B/db/demo/doc/a \
  -H 'content-type: application/json' \
  -d '{"title":"stale","_rev":"bogus"}'
curl -X POST $B/db/demo/query \
  -H 'content-type: text/plain' \
  --data-binary "SELECT id, title FROM c
    WHERE kind = 'note' ORDER BY id LIMIT 2"
Réponses d’une exécution sur barrel_server 1.13.0 (abrégées)
201 {"ok":true,"db":"demo"}

201 {"id":"a","ok":true,
     "rev":"000001a1b876972d00000000@w78160d59891ba7d7"}

409 {"error":"conflict"}

200 application/x-ndjson
{"row":{"id":"a","title":"hello world"}}
{"row":{"id":"c","title":"third"}}
{"meta":{"count":2,"bound":"limit_reached",
         "has_more":false, ...}}

Limites à connaître

  • Les erreurs de configuration de la recherche (bm25_not_enabled, embedder_not_configured, dimension_mismatch) répondent 500, pas 4xx.
  • Une base par défaut s’ouvre avec un magasin de vecteurs en 768 dimensions et BM25 désactivé ; définissez open_opts pour BM25 et la recherche hybride.
  • Il n’y a ni métriques sur les requêtes HTTP ni route /metrics. /health ne vérifie rien ; utilisez /ready pour la disponibilité.
  • Un curseur ?since invalide sur /changes repart sans bruit du premier changement.
  • MCP n’accepte que les tokens bearer, ni requêtes signées ni mTLS. HTTP/3 ne vérifie pas encore les certificats client.
  • Le mTLS authentifie l’autorité de certification, pas chaque pair, et ne s’applique qu’aux requêtes sans en-tête Authorization.
  • Aucun réglage ne permet de désactiver l’écouteur HTTP.

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