[infra] 共通基盤 (logging / errors / config / test fixtures)

[sotashimozono]

Question

共通基盤 (logging / errors / config / test fixtures) の crate 選定と pattern。

Categories

Logging

• tracing (推奨) — async-aware, structured, span/event model
• vs log + env_logger (シンプルだが async に弱い)
• subscriber: tracing-subscriber で env-driven (RUST_LOG)

Errors

• lib: thiserror で typed error enum
• bin (CLI): anyhow で context-rich
• MCP server: 別 type に変換 (MCP error response)

Config

• A. figment — 多 source merge (env + toml + cli)
• B. plain toml + clap flags — シンプル
• C. confy — 自動 path resolution、easy

CLI parsing

• clap derive macro 一択

HTTP client

• reqwest + rustls (no openssl deps)

Test fixtures

• wiremock for HTTP mocks
• assert_cmd + predicates for CLI integration tests
• tempfile for filesystem tests

Async runtime

• tokio full features

Path handling

• camino for guaranteed UTF-8 paths (Windows 対応)
• avoid raw std::path::Path for user-facing paths

Date/time

• chrono (serde feature)
• vs time crate (同等、好み)

Recommendation

• tracing / thiserror+anyhow / clap derive / reqwest+rustls / wiremock+assert_cmd / tokio / camino / chrono
• Config は B (plain toml + clap) で MVP、複雑化したら figment 移行

Open questions

• config 形式: TOML / YAML / JSON / 全部？
• CLI flag 命名規則: kebab-case (--source-policy) で確定？
• tracing subscriber は default human or --json で切替？

Decision

???

[sotashimozono]

Filed as external review by Claude (Anthropic, AI agent operating under souta's GitHub auth). Synthesizes crate choices that downstream Discussions implicitly depend on.

立場

本文の crate 選定 (tracing / thiserror+anyhow / clap / reqwest+rustls / wiremock+assert_cmd / tokio / camino / chrono) は 概ね Rust eco の標準的な選択 で、 reviewer も同意。

但し 本 reviewer の他 Discussion review で発生した spec (CapabilityProfile / secrecy / hash chain log / cargo-vet 等) を反映して、 crate 一覧を Phase 別の確定 list として再整理します。

1. Phase 0 必須 crate (確定 list)

[workspace.dependencies]
# Async runtime
tokio = { version = "1", features = ["rt-multi-thread", "macros", "fs", "process", "signal"] }

# CLI
clap = { version = "4", features = ["derive", "env", "string"] }

# Errors
thiserror = "1"
anyhow = "1"     # bin only

# Logging
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter", "json", "fmt"] }

# Secrets
secrecy = { version = "0.10", features = ["serde"] }    # #16 §1

# HTTP client
reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "json", "gzip", "brotli", "stream"] }

# Filesystem
camino = "1"      # UTF-8 paths
fs2 = "0.4"       # flock #1 §Contract 2
tempfile = "3"

# Concurrency
parking_lot = "0.12"   # mutex 系
once_cell = "1"

# Serialization
serde = { version = "1", features = ["derive"] }
serde_json = "1"
toml = "0.8"
toml_edit = "0.22"  # 既存 TOML を modify する時 (#2 §規律 2)

# Time
chrono = { version = "0.4", default-features = false, features = ["serde", "clock"] }

# Hashing (provenance log hash chain — #12 §threat 4)
sha2 = "0.10"
hex = "0.4"

# UUIDs (mcp_call_id 等)
uuid = { version = "1", features = ["v4", "serde"] }

# Test fixtures
[dev-dependencies]
wiremock = "0.6"           # HTTP mock
assert_cmd = "2"           # CLI test
predicates = "3"           # assertion
proptest = "1"             # property tests for safekey vectors

2. Phase 3 (MCP) で追加

# MCP server SDK
rmcp = "0.1"     # Anthropic 公式 Rust MCP SDK (もしくは similar)

# Async stream / channel
tokio-util = "0.7"
futures = "0.3"

rmcp 採用は仮。 Phase 3 着手時点での MCP Rust SDK の成熟度を再評価して決める。 もし rmcp が unstable なら自前実装も視野。

3. Phase 4 (citation graph) で追加

# Graph algorithms
petgraph = "0.6"   # cycle detection / BFS

# DOT format generator
dot-writer = "0.1"   # or generate manually

4. 採用 しない crate (明示)

以下を cargo-deny の deny list に登録 (#12 supply-chain):

[bans]
deny = [
    # Telemetry
    { name = "sentry" },
    { name = "google_analytics" },
    { name = "posthog" },

    # HTTP server (HTTP transport 禁止 #4)
    { name = "axum" },
    { name = "actix-web" },
    { name = "hyper", wrappers = ["server"] },   # client は OK
    { name = "warp" },
    { name = "tide" },

    # Self-update (#12 §threat 5)
    { name = "self_update" },

    # OpenSSL (rustls 一本化、 supply-chain risk + cross-compile 苦痛)
    { name = "openssl" },
    { name = "openssl-sys" },
    { name = "native-tls" },
]

5. Config 戦略

本文 open question への reviewer 回答:

• Recommendation 通り B (plain toml + clap) で MVP
• precedence: CLI flag > env var > ~/.config/doiget/config.toml > defaults
• figment への移行は Phase 6 以降で再評価
• config 形式: TOML 一本 (YAML / JSON 不要、 Rust eco の慣習)

// crates/doiget-core/src/config.rs
pub struct Config {
    pub store_path: Utf8PathBuf,        // default ~/papers
    pub cache_path: Utf8PathBuf,        // default ~/.cache/doiget
    pub log_path: Utf8PathBuf,          // default ~/.config/doiget/access.log
    pub user_agent: String,
    pub email: Option<String>,          // Unpaywall politeness
    pub credentials: Credentials,       // wrapped in secrecy::Secret
    pub mode: OutputMode,
}

6. CLI flag 命名規則

本文 open question への reviewer 回答:

• kebab-case で確定: --source-policy, --max-concurrency, --store-path
• ENV var は SCREAMING_SNAKE_CASE with DOIGET_ prefix: DOIGET_STORE_PATH
• clap の #[arg(long, env = "DOIGET_STORE_PATH")] で 1 行 mapping

7. tracing subscriber の default

本文 open question への reviewer 回答:

• default: human format (色付き、 stderr 出力)
• --mode=mcp の場合: JSON Lines に強制 swap ([ux] User personas + 出力 mode 設計 (agent / researcher / CI / library) #14 §2 と整合)
• RUST_LOG_FORMAT=json env で明示 swap も可能

fn init_logging(mode: OutputMode) {
    let subscriber = tracing_subscriber::registry()
        .with(EnvFilter::from_default_env());

    match mode {
        OutputMode::Mcp => subscriber.with(json_layer().with_writer(stderr)),
        _ => subscriber.with(fmt_layer().with_writer(stderr)),
    }.init();
}

8. テスト戦略の補強

本文に追加すべき:

Unit tests

各 source / store 等の logic を crate 内 #[cfg(test)] mod tests。

Integration tests

tests/ 配下に CLI 経由の e2e:

• tests/cli_fetch.rs — assert_cmd で doiget fetch を spawn、 mock HTTP server (wiremock) を立てる
• tests/mcp_smoke.rs — doiget serve を spawn、 stdin/stdout 経由で JSON-RPC 検証

Golden tests

tests/fixtures/golden/ 配下に expected output を置き、 diff 比較:

• TOML output の normalization
• BibTeX / CSL output
• MCP tool response shape

Property tests

proptest で:

• safekey algorithm の collision-resistance ([design] BiblioFetch.jl との共存モデル #1 §Contract 4)
• TOML round-trip (parse → serialize → parse で同じになる)

9. Async runtime の選択肢

本文 "tokio full features" は OK、 但し 必要な features のみ に絞る:

tokio = { version = "1", features = [
    "rt-multi-thread",
    "macros",
    "fs",
    "process",
    "signal",
    "io-util",
    "sync",      # mpsc / broadcast
    "time",      # timeout
] }

full を使うと使わない features (test-util / tracing 等) も pull する。 binary size と compile time のため絞る。

10. Date / time

本文の chrono か time の選択は reviewer の好み:

• chrono を採用推奨 (歴史的 ecosystem 互換性が高い、 serde integration が枯れている)
• chrono の old vulnerability (localtime_r) は最近の version で修正済み
• 但し always UTC ([legal] Legal posture, tool neutrality framing, and required safeguards #16 §5 / log timezone)、 local time conversion は CLI 表示時のみ

11. URL 解析

本文に欠けている:

url = "2"

DOI URL / arXiv URL / publisher URL 解析で 必須。 自前 string parsing は SSRF risk (#12 §threat 2)。

Reviewer Decision proposal

• 上記 §1-3 の crate list を Phase 0 / 3 / 4 に振り分けて Cargo.toml に焼き込み
• deny list を deny.toml に登録: telemetry / HTTP server / self-update / openssl
• Config: TOML + clap + env (precedence: CLI > env > file > default)
• CLI flag: kebab-case、 env: DOIGET_* SCREAMING_SNAKE_CASE
• tracing subscriber: human (default) / JSON (MCP mode)
• Test: unit + integration + golden + property の 4 layer
• tokio features は necessary subset に絞る
• chrono 採用、 always UTC で扱う
• url crate 必須

最終 Decision 権は author に留保。

---

Reviewer: Claude (Anthropic). Filed 2026-05-05.