Gravadora Decision Gate Asset Core
Docs
Recorder Docs

Documentació de gravació de proves i evidències que mostren manipulació.

Altres documents de producte

Arquitectura d’emmagatzematge del gravador

Audience: Engineers changing persistence logic, query semantics, schema, Audiència: Enginyers que canvien la lògica de persistència, la semàntica de consultes, l’esquema o els backends d’emmagatzematge.

Taula de continguts

  1. Visió Executiva
  2. Contractes de Trait de Botiga
  3. Backend en memòria
  4. SQLite Backend
  5. Esquema SQLite i Indexació
  6. Aplicació de la Continuïtat de la Cadena
  7. Semàntica de Consulta i Paginació
  8. Corrupció i Gestió d’Errors
  9. File per Fitxer Referència Creuada

Executive Overview

recorder-store proporciona l’abstracció de persistència i dos backends concrets:

  • InMemoryStore per a proves deterministes i execució local,
  • SqliteStore per a l’operació durable amb WAL i comprovacions transaccionals.

Ambdós implementen contractes de trait compartits per a operacions d’envelop, adjunt i segment. F:crates/recorder-store/src/lib.rs L11-L37 F:crates/recorder-store/src/lib.rs L49-L71

Contractes de Trait de Botiga

El contracte d’emmagatzematge s’expressa com tres característiques asíncrones:

  • EnvelopeStore: afegir/obtenir/consultar/cadenar-cap/segmentar-envelopes,
  • AttachmentStore: posar/obtenir/existir per blobs adreçats al contingut,
  • SegmentStore: crear/sellar/llistar/obtenir metadades i gènesi.

Els invariants bàsics inclouen un comportament d’append-only, comprovacions de continuïtat de la cadena i immutabilitat de segments segellats. La creació de segments és fail-closed: les botigues rebutgen un nou segment quan ja existeix un altre segment obert o quan ja existeix l’ID del segment. F:crates/recorder-store/src/traits.rs L43-L101 F:crates/recorder-store/src/traits.rs L107-L138 F:crates/recorder-store/src/traits.rs L144-L206

Nuances actuals de la ingestió de sidecar:

Backend en memòria

InMemoryStore utilitza mapes i vectors protegits per bloqueig, preservant les comprovacions d’invariants però sense garanties de consistència en cas de fallada. F:crates/recorder-store/src/memory.rs L12-L16

Aspectes destacats del comportament:

  • valida l’estat del segment i la continuïtat de la cadena en afegir,
  • manté les ID d’envelopes de primer/últim i les actualitzacions del cap de cadena,
  • aplica regles de creació de segment únic obert i sense ID de segment duplicat,
  • suporta la llista de segments determinista per created_at,
  • aplica un ordre de consulta d’envelopes determinista per segment_id i després per seqüència.

F:crates/recorder-store/src/memory.rs L124-L180 F:crates/recorder-store/src/memory.rs L317-L407

SQLite Backend

SqliteStore dirigeix totes les operacions de la base de dades a través d’un fil de connexió dedicat (SqliteConnection) per preservar de manera segura la semàntica de l’escriptor únic entre els cridadors asíncrons. F:crates/recorder-store/src/sqlite/mod.rs L12-L22 F:crates/recorder-store/src/sqlite/connection.rs L12-L21

SqliteConnection::execute utilitza sync_channel limitat + canals oneshot per connectar codi asíncron amb operacions síncrones de rusqlite. L’admissió a la cua és explícita: l’ saturació de la cua falla tancada amb StoreError::ConcurrencyConflict en lloc de permetre un creixement il·limitat de treball en memòria. F:crates/recorder-store/src/sqlite/connection.rs L42-L136 F:crates/recorder-store/src/sqlite/connection.rs L167-L222

La descoberta de segments actius (get_active_segment) ara falla de manera segura quan l’estat persistit està corromput per contenir múltiples segments oberts. Això impedeix un comportament de recuperació ambigu que selecciona un segment obert arbitrari. F:crates/recorder-store/src/sqlite/segment_ops.rs

SqliteStore a més exposa helpers de metadades tipades sobre store_meta (get_meta, set_meta, set_meta_batch) per a un estat d’execució determinista com ara marcadors d’idempotència per a la rotació de claus de signatura. F:crates/recorder-store/src/sqlite/mod.rs

SQLite open tuning ara suporta controls de temps d’execució explícits i validats:

Esquema SQLite i Indexació

La inicialització permet:

  • mode WAL,
  • claus foranes,
  • taula de metadades d’esquema amb porta d’esquema tancada (schema_version=2),
  • segments, envoltants, fitxers adjunts i taules de connexió normalitzades,
  • writer/projection tables: streams, idempotency_entries, query_projection_envelopes,
  • stream identity columns on segments and envelopes used by sidecar escriptura-runtime per-stream ordenació i invariants de rotllana,
  • índexs per a patrons d’envolupament/segmentació/projecció de consulta deterministes.

F:crates/recorder-store/src/sqlite/schema.rs L111-L144 F:crates/recorder-store/src/sqlite/schema.rs L43-L105

Aplicació de la Continuïtat de la Cadena

Ambdós backends imposen la validació de la cadena en temps d’append mitjançant la recomputació de l’encapçalament de cadena esperat i la comparació en temps constant.

Validació d’append en memòria: F:crates/recorder-store/src/memory.rs L140-L158

La validació d’apèndix de SQLite és limitada a la transacció:

  1. verificar que el segment existeix i està obert,
  2. recalcular el hash esperat de la cadena,
  3. rebutjar desajustaments,
  4. inserir files d’envelopes + files d’adjunt d’envelopes,
  5. actualitzar la metadada del segment de manera atòmica.

F:crates/recorder-store/src/sqlite/envelope_ops.rs L42-L141

Semàntica de Consulta i Paginació

Les consultes d’envelopes admeten filtratge de múltiples camps, així com continuació de cursor i límit. Les consultes d’àrea de flux de sidecar utilitzen query_projection_envelopes i ORDER BY stream_sequence ASC dins de l’àmbit (tenant_id, recorder_id). Les consultes d’envelopes de segment continuen ordenant per sequence ASC.

F:crates/recorder-store/src/sqlite/envelope_ops.rs L167-L280 F:crates/recorder-store/src/sqlite/envelope_ops.rs L306-L347

La llista de segments admet filtres d’estat/temps/id i ordena per created_at ASC, segment_id ASC per preservar l’ordenació determinista sota marques de temps iguals a través de les diferents plataformes. F:crates/recorder-store/src/sqlite/segment_ops.rs L148-L245

Corrupció i Gestió d’Errors

StoreError diferencia explícitament les ruptures d’integritat, els casos no trobats, els conflictes de concurrència, les fallades del backend i la detecció de corrupció. F:crates/recorder-store/src/error.rs L36-L103

El processament de segments de SQLite tracta els valors de DB no vàlids com a corrupció (uuid no vàlid, estat desconegut, algoritme de hash desconegut, segells de temps no vàlids). F:crates/recorder-store/src/sqlite/segment_ops.rs L336-L416

Les proves del sistema ara validen el comportament de fallada tancada quan les files de SQLite persistents són manipulades amb dades de UUID/genesis de segment no vàlides entre les operacions de CLI. F:system-tests/tests/suites/persistence.rs L375-L468

File per Fitxer Referència Creuada

ÀreaFitxerNotes
Contractes d’emmagatzematgecrates/recorder-store/src/traits.rsInvariants del trait d’emmagatzematge canònic.
Tipus de segmentscrates/recorder-store/src/types.rsMetadades del segment i formes de filtre.
Backend en memòriacrates/recorder-store/src/memory.rsImplementació basada en mapes determinista.
Façana SQLitecrates/recorder-store/src/sqlite/mod.rsConstrucció de l’emmagatzematge i composició del backend.
Helpers de metadades SQLitecrates/recorder-store/src/sqlite/mod.rsHelpers de lectura/escriptura store_meta per a la persistència de l’estat en temps d’execució.
Pont SQLitecrates/recorder-store/src/sqlite/connection.rsPont async dedicat a fils.
Esquema SQLitecrates/recorder-store/src/sqlite/schema.rsDDL, índexs, versionat d’esquemes.
Operacions SQL d’envolupamentcrates/recorder-store/src/sqlite/envelope_ops.rsLògica de consulta de filtre i append transaccionals.
Operacions SQL de segmentcrates/recorder-store/src/sqlite/segment_ops.rsCicle de vida del segment i decodificació de metadades.
Operacions SQL d’adjuntcrates/recorder-store/src/sqlite/attachment_ops.rsSemàntica de put/get/exists adreçada al contingut.
Taxonomia d’errorscrates/recorder-store/src/error.rsModel de fallada d’emmagatzematge tipificat.