Traffic SQLite와 파일 저장 계약

traffic recorder의 SQLite 일반 table 3개, 선택적 FTS5 virtual table 1개와 body/blob/file 경계를 설명한다.

각 객체의 exact production Go symbol, SQL verb와 query 조건은 DB access matrix에서 역추적한다.

기준 · core db/schema.sql은 PostgreSQL 49개 table·최종 column 합집합 520개·명시 index 97개·function 4개·trigger 22개다. startup 보조 ledger llm_records와 llm_usage가 2개 table·31개 column·5개 index를 더해 선언 총계는 51개 table·551개 column·102개 index다. Ensure*Table 실패는 로그 후 계속되므로 보조 ledger 존재는 core startup 보장이 아니다. Traffic은 별도 SQLite 3개 일반 table·FTS5 virtual table 1개·index 6개다. 아래 DDL은 고정 source revision의 선언이며 실제 운영 DB 적용 상태는 관찰하지 않았다.

객체 색인

exchanges

캡처한 HTTP exchange의 검색/목록 metadata를 저장한다.

정의 원본은 traffic/traffic.go다. 등록 근거

CREATE TABLE IF NOT EXISTS exchanges (
  id           TEXT PRIMARY KEY,
  ts           INTEGER,
  host         TEXT,
  method       TEXT,
  url_template TEXT,
  url          TEXT,
  status       INTEGER,
  content_type TEXT,
  req_len      INTEGER,
  resp_len     INTEGER,
  path         TEXT
);

인덱스

• CREATE INDEX IF NOT EXISTS idx_ex_host ON exchanges(host);
• CREATE INDEX IF NOT EXISTS idx_ex_tmpl ON exchanges(host, url_template);
• CREATE INDEX IF NOT EXISTS idx_ex_ts ON exchanges(ts);
• CREATE INDEX IF NOT EXISTS idx_ex_status ON exchanges(status);
• CREATE INDEX IF NOT EXISTS idx_ex_resp ON exchanges(resp_len);

필드·접근 의미

Traffic.record가 같은 transaction에서 이 row와 body/blob reference/FTS row를 쓴다. public Traffic.Search는 host exact filter와 page만 제공한다. UI의 Page는 metadata·FTS filter를, agent tool이 호출하는 private query는 host/URL/body filter를 사용한다. Get, Hosts, Count와 deletion staging·GC도 읽고, deleteWhere가 관련 세 table과 FTS row를 함께 삭제한다. 다섯 index는 host/template/time/status/response-size filter와 정렬을 돕지만 capture마다 유지 비용을 낸다. FK가 없으므로 네 객체의 동일 ID 무결성은 이 transaction과 delete 순서가 유지한다. traffic store

ID는 <Unix-second>-<atomic sequence mod 10000>다. Sequence는 process 재시작 시 0에서 다시 시작하고 한 초에 10,000건을 넘으면 돌기 때문에 same-second restart·고속 capture에서 collision이 가능하다. INSERT OR REPLACE는 collision 시 기존 exchanges/exchange_bodies row를 대체하지만 구 blob_refs와 구 FTS row를 선행 정리하지 않는다. 충돌 빈도와 잔존 reference/index 영향은 실행 검증 전 U다.

exchange_bodies

작은 request/response body inline 값 또는 큰 body blob 참조를 저장한다.

정의 원본은 traffic/traffic.go다. 등록 근거

CREATE TABLE IF NOT EXISTS exchange_bodies (
  id        TEXT PRIMARY KEY,
  req_head  TEXT NOT NULL DEFAULT '',
  req_body  BLOB,
  req_blob  TEXT,
  resp_head TEXT NOT NULL DEFAULT '',
  resp_body BLOB,
  resp_blob TEXT
);

필드·접근 의미

Traffic.record가 INSERT OR REPLACE하고 Get이 exchanges와 join해 읽는다. blob file은 SQL transaction 전에 기록되므로 SQL rollback만으로 filesystem write가 되돌아가지 않는다. deleteWhere는 body row를 exchange보다 먼저 지운다. body/header redaction은 이 storage layer에 없으며 문서화한 크기 경계도 실행 환경의 row 내용을 검증한 결과는 아니다. traffic store

blob_refs

content-addressed body blob과 exchange 참조를 연결한다.

정의 원본은 traffic/traffic.go다. 등록 근거

CREATE TABLE IF NOT EXISTS blob_refs (
  hash        TEXT NOT NULL,
  exchange_id TEXT NOT NULL,
  PRIMARY KEY (hash, exchange_id)
);

인덱스

• CREATE INDEX IF NOT EXISTS idx_blob_refs_ex ON blob_refs(exchange_id);

필드·접근 의미

Traffic.record가 body를 spill할 때 INSERT OR IGNORE하고, gcBlobs가 distinct hash를 읽어 filesystem sweep의 live set으로 쓴다. deleteWhere가 exchange별 reference를 지운다. idx_blob_refs_ex는 exchange 삭제 조회를 빠르게 하지만 hash별 GC는 composite PK의 leading hash를 사용한다. 자동 기간 보존은 없고 API의 host/all deletion과 task archive staging이 retention을 결정한다. traffic store

ex_fts virtual table

request/response 본문 검색을 위한 contentless FTS5 index다. 원문은 크기에 따라 exchange_bodies inline body 또는 _blobs/sha256 CAS blob에 남고, FTS row는 rowid와 trigram index만 유지한다. 등록 근거

CREATE VIRTUAL TABLE IF NOT EXISTS ex_fts USING fts5(
  content, tokenize='trigram', content='', contentless_delete=1
);

적용과 fallback

ftsSchema는 일반 index schema와 별도로 적용된다. build/runtime SQLite가 FTS5 또는 해당 option을 지원하지 않으면 traffic store는 초기화 자체를 실패시키지 않고 FTS 기능을 비활성화한다. 따라서 선언상 virtual table이 있어도 실제 DB에 존재한다고 단정할 수 없다. 일반 table 3개와 명시 index 6개는 별도 경로다.

content 한 필드는 URL, request/response header 전체, text로 판정된 request body와 response body의 각각 최대 4 MiB를 합쳐 만든다. 두 body만 합쳐도 잠재적으로 약 8 MiB이며 URL/header는 별도다. contentless이므로 원문을 보관하지 않고 rowid로 exchanges에 논리 연결된다. UI Page의 broad/body filter와 agent tool private query의 body_contains가 3자 이상 검색에 이 index를 쓴다. public Traffic.Search는 FTS를 사용하지 않는 host-only 목록 API다. deleteWhere와 background merge/reclaim은 tombstone을 정리한다. 원문에 credential·cookie·token이 있으면 trigram에도 파생 정보가 남을 수 있다. FTS availability, 실제 index 크기와 merge 비용은 운영 파일 관찰 전에는 U다.

Archive export는 spilled body의 CAS blob 전체를 함께 복사한다. traffic.json의 inline body는 256 KiB 이하 body이면 전체이고, spill된 body이면 8 KiB preview(이진 body는 짧은 표시 문자열)다. Import는 blob을 복원한 뒤에도 FTS를 이 URL/header/inline 값으로만 재생성하므로, 원래 capture에서 8 KiB를 넘어 4 MiB까지 색인된 spilled text는 restore 후 8 KiB 밖이 재색인되지 않는다. body bytes 복원과 FTS 검색 커버리지는 다른 일관성 경계다.

SQLite 의미 판정

Filesystem 경계

Traffic.Open은 root 아래 _index/index.sqlite, _blobs/sha256/..., _ca를 사용한다. 현재 Traffic.record는 새 capture를 SQLite에 기록하고, 256 KiB를 넘는 body만 SHA-256 content-addressed blob으로 spill하며 8 KiB preview를 SQLite에 남긴다. 새 row의 exchanges.path는 빈 문자열이고 per-request .http/host-method tree를 만들지 않는다. non-empty path와 host/method tree는 이전 저장 형식의 조회·삭제·archive/recovery 호환 경계다. traffic store

SQLite transaction은 index/body/blob reference를 묶지만 blob file write는 transaction을 열기 전에 일어난다. spill과 archive import는 final CAS path에 직접 write하고 temp+fsync+rename이나 destination hash 재검증을 하지 않는다. Crash/I/O로 partial file이 남으면 현재 capture는 빈 hash+8 KiB clip으로 commit할 수 있고, 뒤의 동일 body는 os.Stat만으로 그 path를 신뢰해 hash reference를 저장할 수 있다. 성공한 spill 뒤 SQL이 실패하면 orphan CAS file도 남는다. Blob directory 생성·file write 실패로 SQLite commit만 계속되면 원문이 비가역적으로 잘릴 수 있다. index.sqlite만 백업하면 큰 body가 복원되지 않는다. 현재 capture에 legacy host tree는 필요 없지만 non-empty exchanges.path가 남은 설치에서는 그 tree도 함께 보존해야 한다. HTTPS MITM이 proxy/protocol 원인으로 실패한 host는 이후 transparent tunnel로 fail-open하며 그 트래픽은 기록되지 않는다.

초기화·commit·recovery matrix

상위 영역: 데이터 모델과 저장 계약

전체로 돌아가기 · Markdown 원본