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_versionspour 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 => replicatedet 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/1vous donne le plus ancien point conservé.