Barrel
EN GitHub

Audit et provenance

Chaque écriture appliquée laisse une entrée dans le journal d’historique conservé, et une écriture peut porter sa provenance : qui (acteur), dans quelle session, par quelle surface (source). Ensemble, elles répondent à la question « que savait l’agent, et quand » au niveau de la base de données. Lisez ce guide quand vous devez attribuer des écritures à des agents ou reconstituer l’état d’un document à un instant donné.

Quand l’utiliser

  • Vous faites travailler des agents sur une base partagée et devez savoir quel agent a écrit quoi, et quand.
  • Vous avez besoin des versions passées d’un document (corps compris) dans la fenêtre de rétention.
  • Vous exposez barrel en REST ou en MCP et voulez attribuer les écritures sans modifier le corps des documents.

Écrire avec une provenance

Passez provenance dans les options d’écriture. Chaque valeur est un binaire d’au plus 256 octets ; le blob encodé est limité à 1 Kio. Une provenance invalide fait échouer l’écriture avec {invalid_provenance, Reason}.

{ok, Db} = barrel:open(<<"mydb">>),
Prov = #{actor => <<"agent-9">>,
         session => <<"ses_abc">>,
         source => <<"planner">>},
{ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"a">>, <<"v">> => 1},
                         #{provenance => Prov}),
{ok, _} = barrel:delete_doc(Db, <<"a">>, #{provenance => Prov}).

En REST, ajoutez les en-têtes à n’importe quelle écriture ; sur _bulk_docs, ils s’appliquent à tout le lot :

$ curl -X PUT localhost:8080/db/mydb/doc/a \
    -H 'content-type: application/json' \
    -H 'x-barrel-actor: agent-9' \
    -H 'x-barrel-session: ses_abc' \
    -H 'x-barrel-source: planner' \
    -d '{"v":1}'

Les écritures en MCP portent leur provenance automatiquement : l’acteur est le sujet authentifié, la session est la session MCP (ou l’argument session de l’outil), la source est mcp. Voir le guide MCP.

Lire la piste d’audit

Le journal d’historique contient une entrée par écriture appliquée (sans les corps), ordonnée par HLC et purgée par la rétention. Les corps remplacés sont archivés et lisibles par version jusqu’à leur purge.

%% toute la piste conservée, ou une fenêtre
{ok, Entries} = barrel:history(Db),
{ok, Entries2} = barrel:history(Db, #{limit => 100}),
%% chaque entrée : #{hlc, id, version, deleted, cause, provenance?}
%% cause : local | replicated | resolve ; provenance seulement si
%% l'écriture en portait une

%% un document : version courante + versions archivées, puis un corps passé
{ok, Versions} = barrel:doc_versions(Db, <<"a">>),
[#{version := Rev} | _] = Versions,
{ok, OldBody} = barrel:version_body(Db, <<"a">>, Rev),

%% jusqu'où remonte la piste (undefined = rien de purgé pour l'instant)
Floor = barrel:history_floor(Db).

Options de history/2 : from et to (curseurs HLC, à décoder avec barrel:hlc_decode/1), limit, et id (filtre sur un document ; un parcours documenté de la fenêtre).

En REST

$ curl 'localhost:8080/db/mydb/_history?limit=50'
{"history":[{"id":"a","rev":"...","cause":"local","hlc":"...",
             "provenance":{"actor":"agent-9",...}}]}

$ curl 'localhost:8080/db/mydb/_history?since=<cursor>&until=<cursor>&id=a'
$ curl localhost:8080/db/mydb/doc/a/_versions
$ curl localhost:8080/db/mydb/doc/a/_versions/<rev>   # the archived body

since/until prennent les curseurs HLC que renvoient les autres points d’accès (le hlc d’un changement, le hlc d’une entrée d’historique). Des curseurs ou des limites invalides répondent 400.

Notes

  • La provenance est enregistrée deux fois : sur la version gagnante courante (renvoyée par doc_versions pour la tête) et dans l’entrée d’historique de chaque écriture appliquée (l’enregistrement d’audit durable).
  • Une écriture sans provenance efface la colonne de provenance de la version gagnante : l’attribution courante ne ment jamais.
  • En v1, la provenance ne voyage pas sur le protocole de réplication. Les arrivées répliquées portent cause => replicated et l’identité de la base d’origine ; la piste de l’origine contient l’agent qui a agi.
  • Les branches se créent avec l’historique du parent : une branche porte donc la provenance de tout ce qui précède la bifurcation (voir timeline).
  • La rétention purge ensemble les entrées d’historique et les corps archivés (retention_period, 30 jours par défaut). history_floor/1 vous donne le plus ancien point conservé.

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

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