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
- Repose sur
barrel,barrel_docdb,barrel_spaces,barrel_ngram- 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
{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éfaut | Rô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âche | Appel | Renvoie |
|---|---|---|
| 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âche | Appel | Renvoie |
|---|---|---|
| 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âche | Appel | Renvoie |
|---|---|---|
| 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).
[
{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.
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" 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_optspour BM25 et la recherche hybride. - Il n’y a ni métriques sur les requêtes HTTP ni route
/metrics./healthne vérifie rien ; utilisez/readypour la disponibilité. - Un curseur
?sinceinvalide sur/changesrepart 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.