From 23ce90e103e02ead9e0509ef240cfcc9c5dd103d Mon Sep 17 00:00:00 2001 From: Andreas Brenner Date: Fri, 24 Jul 2026 20:29:06 +0300 Subject: [PATCH 01/10] ANW-37 Telemetry: request metrics + selective traces over OTLP Optional OTLP export of request-level metrics (request and response-byte counters keyed by route/status/conditional-GET, a duration histogram out to 600s) plus server spans for slow or 5xx requests, nested under the incoming W3C trace context. Off unless an OTLP endpoint or uptrace DSN is configured; a config-less server is byte-for-byte unchanged. --- Cargo.lock | 1197 +++++++++++++++++++++++++++++++++++++++++++++- Cargo.toml | 9 + README.md | 26 +- src/app.rs | 26 +- src/cli.rs | 38 +- src/http.rs | 126 ++++- src/lib.rs | 1 + src/main.rs | 26 +- src/telemetry.rs | 620 ++++++++++++++++++++++++ 9 files changed, 2014 insertions(+), 55 deletions(-) create mode 100644 src/telemetry.rs diff --git a/Cargo.lock b/Cargo.lock index b01cf4a..854bfc5 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -79,8 +79,13 @@ dependencies = [ "blake3", "chrono", "clap", + "http-body", "hydra", "notify", + "opentelemetry", + "opentelemetry-otlp", + "opentelemetry-semantic-conventions", + "opentelemetry_sdk", "regex", "serde", "serde_json", @@ -122,6 +127,17 @@ version = "0.7.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50" +[[package]] +name = "async-trait" +version = "0.1.91" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae36dc4177970ef04fde5178d3e2429882def40e57a451f919c098f72baa6cec" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.3", +] + [[package]] name = "atomic-waker" version = "1.1.2" @@ -134,6 +150,29 @@ version = "1.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8" +[[package]] +name = "aws-lc-rs" +version = "1.17.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00bdb5da18dac48ca2cc7cd4a98e533e8635a58e2361d13a1a4ee3888e0d72f1" +dependencies = [ + "aws-lc-sys", + "zeroize", +] + +[[package]] +name = "aws-lc-sys" +version = "0.43.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "43103168cc76fe62678a375e722fc9cb3a0146159ac5828bc4f0dfd755c2224c" +dependencies = [ + "cc", + "cmake", + "dunce", + "fs_extra", + "pkg-config", +] + [[package]] name = "axum" version = "0.8.9" @@ -186,6 +225,12 @@ dependencies = [ "tracing", ] +[[package]] +name = "base64" +version = "0.22.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6" + [[package]] name = "bincode" version = "2.0.1" @@ -254,6 +299,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a1dce859f0832a7d088c4f1119888ab94ef4b5d6795d1ce05afb7fe159d79f98" dependencies = [ "find-msvc-tools", + "jobserver", + "libc", "shlex", ] @@ -263,6 +310,23 @@ version = "1.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" +[[package]] +name = "cfg_aliases" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527" + +[[package]] +name = "chacha20" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d524456ba66e72eb8b115ff89e01e497f8e6d11d78b70b1aa13c0fbd97540a81" +dependencies = [ + "cfg-if", + "cpufeatures 0.3.0", + "rand_core 0.10.1", +] + [[package]] name = "chrono" version = "0.4.44" @@ -306,7 +370,7 @@ dependencies = [ "heck", "proc-macro2", "quote", - "syn", + "syn 2.0.117", ] [[package]] @@ -315,18 +379,47 @@ version = "1.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9" +[[package]] +name = "cmake" +version = "0.1.58" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c0f78a02292a74a88ac736019ab962ece0bc380e3f977bf72e376c5d78ff0678" +dependencies = [ + "cc", +] + [[package]] name = "colorchoice" version = "1.0.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570" +[[package]] +name = "combine" +version = "4.6.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ba5a308b75df32fe02788e748662718f03fde005016435c444eea572398219fd" +dependencies = [ + "bytes", + "memchr", +] + [[package]] name = "constant_time_eq" version = "0.4.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3d52eff69cd5e647efe296129160853a42795992097e8af39800e1060caeea9b" +[[package]] +name = "core-foundation" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6" +dependencies = [ + "core-foundation-sys", + "libc", +] + [[package]] name = "core-foundation-sys" version = "0.8.7" @@ -392,6 +485,29 @@ dependencies = [ "subtle", ] +[[package]] +name = "displaydoc" +version = "0.2.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.117", +] + +[[package]] +name = "dunce" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813" + +[[package]] +name = "either" +version = "1.16.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e" + [[package]] name = "equivalent" version = "1.0.2" @@ -447,6 +563,12 @@ dependencies = [ "percent-encoding", ] +[[package]] +name = "fs_extra" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c" + [[package]] name = "fsevent-sys" version = "4.1.0" @@ -463,6 +585,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d" dependencies = [ "futures-core", + "futures-sink", ] [[package]] @@ -471,6 +594,34 @@ version = "0.3.32" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d" +[[package]] +name = "futures-executor" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "baf29c38818342a3b26b5b923639e7b1f4a61fc5e76102d4b1981c6dc7a7579d" +dependencies = [ + "futures-core", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-io" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4577ecaa3c4f96589d473f679a71b596316f6641bc350038b962a5daf0085d7a" + +[[package]] +name = "futures-macro" +version = "0.3.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e835b70203e41293343137df5c0664546da5745f82ec9b84d40be8336958447b" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.117", +] + [[package]] name = "futures-sink" version = "0.3.32" @@ -490,8 +641,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6" dependencies = [ "futures-core", + "futures-io", + "futures-macro", "futures-sink", "futures-task", + "memchr", "pin-project-lite", "slab", ] @@ -519,6 +673,18 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "getrandom" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd" +dependencies = [ + "cfg-if", + "libc", + "r-efi 5.3.0", + "wasip2", +] + [[package]] name = "getrandom" version = "0.4.2" @@ -526,10 +692,13 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555" dependencies = [ "cfg-if", + "js-sys", "libc", - "r-efi", + "r-efi 6.0.0", + "rand_core 0.10.1", "wasip2", "wasip3", + "wasm-bindgen", ] [[package]] @@ -647,7 +816,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0c4aba8078b9198d4ee315f08a44c9206614bfbc8fa6af39c2084965c13e4920" dependencies = [ "quote", - "syn", + "syn 2.0.117", ] [[package]] @@ -668,6 +837,22 @@ dependencies = [ "pin-project-lite", "smallvec", "tokio", + "want", +] + +[[package]] +name = "hyper-rustls" +version = "0.27.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f" +dependencies = [ + "http", + "hyper", + "hyper-util", + "rustls", + "tokio", + "tokio-rustls", + "tower-service", ] [[package]] @@ -676,13 +861,21 @@ version = "0.1.20" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0" dependencies = [ + "base64", "bytes", + "futures-channel", + "futures-util", "http", "http-body", "hyper", + "ipnet", + "libc", + "percent-encoding", "pin-project-lite", + "socket2", "tokio", "tower-service", + "tracing", ] [[package]] @@ -709,12 +902,115 @@ dependencies = [ "cc", ] +[[package]] +name = "icu_collections" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2984d1cd16c883d7935b9e07e44071dca8d917fd52ecc02c04d5fa0b5a3f191c" +dependencies = [ + "displaydoc", + "potential_utf", + "utf8_iter", + "yoke", + "zerofrom", + "zerovec", +] + +[[package]] +name = "icu_locale_core" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29" +dependencies = [ + "displaydoc", + "litemap", + "tinystr", + "writeable", + "zerovec", +] + +[[package]] +name = "icu_normalizer" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c56e5ee99d6e3d33bd91c5d85458b6005a22140021cc324cea84dd0e72cff3b4" +dependencies = [ + "icu_collections", + "icu_normalizer_data", + "icu_properties", + "icu_provider", + "smallvec", + "zerovec", +] + +[[package]] +name = "icu_normalizer_data" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "da3be0ae77ea334f4da67c12f149704f19f81d1adf7c51cf482943e84a2bad38" + +[[package]] +name = "icu_properties" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bee3b67d0ea5c2cca5003417989af8996f8604e34fb9ddf96208a033901e70de" +dependencies = [ + "icu_collections", + "icu_locale_core", + "icu_properties_data", + "icu_provider", + "zerotrie", + "zerovec", +] + +[[package]] +name = "icu_properties_data" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e2bbb201e0c04f7b4b3e14382af113e17ba4f63e2c9d2ee626b720cbce54a14" + +[[package]] +name = "icu_provider" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421" +dependencies = [ + "displaydoc", + "icu_locale_core", + "writeable", + "yoke", + "zerofrom", + "zerotrie", + "zerovec", +] + [[package]] name = "id-arena" version = "2.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954" +[[package]] +name = "idna" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de" +dependencies = [ + "idna_adapter", + "smallvec", + "utf8_iter", +] + +[[package]] +name = "idna_adapter" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714" +dependencies = [ + "icu_normalizer", + "icu_properties", +] + [[package]] name = "indexmap" version = "2.14.0" @@ -747,18 +1043,92 @@ dependencies = [ "libc", ] +[[package]] +name = "ipnet" +version = "2.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2" + [[package]] name = "is_terminal_polyfill" version = "1.70.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695" +[[package]] +name = "itertools" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b192c782037fadd9cfa75548310488aabdbf3d2da73885b31bd0abd03351285" +dependencies = [ + "either", +] + [[package]] name = "itoa" version = "1.0.18" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" +[[package]] +name = "jni" +version = "0.22.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5efd9a482cf3a427f00d6b35f14332adc7902ce91efb778580e180ff90fa3498" +dependencies = [ + "cfg-if", + "combine", + "jni-macros", + "jni-sys", + "log", + "simd_cesu8", + "thiserror", + "walkdir", + "windows-link", +] + +[[package]] +name = "jni-macros" +version = "0.22.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a00109accc170f0bdb141fed3e393c565b6f5e072365c3bd58f5b062591560a3" +dependencies = [ + "proc-macro2", + "quote", + "rustc_version", + "simd_cesu8", + "syn 2.0.117", +] + +[[package]] +name = "jni-sys" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6377a88cb3910bee9b0fa88d4f42e1d2da8e79915598f65fb0c7ee14c878af2" +dependencies = [ + "jni-sys-macros", +] + +[[package]] +name = "jni-sys-macros" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264" +dependencies = [ + "quote", + "syn 2.0.117", +] + +[[package]] +name = "jobserver" +version = "0.1.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c00acbd29eabad4a2392fa0e921c874934dbbf4194312ad20f04a0ed67a3cb3" +dependencies = [ + "getrandom 0.4.2", + "libc", +] + [[package]] name = "js-sys" version = "0.3.98" @@ -815,6 +1185,12 @@ version = "0.12.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53" +[[package]] +name = "litemap" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0" + [[package]] name = "lock_api" version = "0.4.14" @@ -830,6 +1206,12 @@ version = "0.4.29" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897" +[[package]] +name = "lru-slab" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154" + [[package]] name = "matchers" version = "0.2.0" @@ -935,6 +1317,88 @@ version = "1.70.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe" +[[package]] +name = "openssl-probe" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe" + +[[package]] +name = "opentelemetry" +version = "0.32.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b0142c63252a9e054e68a4c61a5778f7b14f576274d593f8ce883d191a099682" +dependencies = [ + "futures-core", + "futures-sink", + "js-sys", + "pin-project-lite", + "thiserror", + "tracing", +] + +[[package]] +name = "opentelemetry-http" +version = "0.32.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5683015d09e2df236ef005b17f6f196f0d5f6313c4fa43a7b6a53b52776e4331" +dependencies = [ + "async-trait", + "bytes", + "http", + "opentelemetry", + "reqwest", +] + +[[package]] +name = "opentelemetry-otlp" +version = "0.32.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9966929966d17620d7c316c643ba62631826e10021409357772d5eea84f62c35" +dependencies = [ + "http", + "opentelemetry", + "opentelemetry-http", + "opentelemetry-proto", + "opentelemetry_sdk", + "prost", + "reqwest", + "thiserror", +] + +[[package]] +name = "opentelemetry-proto" +version = "0.32.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "56d658ba1faf63f7b9c492cfbe6e0ec365440a16132d3270c1065f7b33f1b638" +dependencies = [ + "opentelemetry", + "opentelemetry_sdk", + "prost", +] + +[[package]] +name = "opentelemetry-semantic-conventions" +version = "0.32.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c913ac17a6c451661ee255f4625d143e51647ae78ebd969b75e41c4442f4fe47" + +[[package]] +name = "opentelemetry_sdk" +version = "0.32.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b59f80e1ac4d5ff7a2db8fb6c80badb7f0f3f858211fba08dd9aaec750894f9" +dependencies = [ + "futures-channel", + "futures-executor", + "futures-util", + "opentelemetry", + "percent-encoding", + "portable-atomic", + "rand 0.9.5", + "thiserror", +] + [[package]] name = "parking_lot" version = "0.12.5" @@ -983,6 +1447,36 @@ dependencies = [ "tokio", ] +[[package]] +name = "pkg-config" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e" + +[[package]] +name = "portable-atomic" +version = "1.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3d20d5497ef88037a52ff98267d066e7f11fcc5e99bbfbd58a42336193aacec3" + +[[package]] +name = "potential_utf" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564" +dependencies = [ + "zerovec", +] + +[[package]] +name = "ppv-lite86" +version = "0.2.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9" +dependencies = [ + "zerocopy", +] + [[package]] name = "prettyplease" version = "0.2.37" @@ -990,7 +1484,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b" dependencies = [ "proc-macro2", - "syn", + "syn 2.0.117", ] [[package]] @@ -1002,6 +1496,86 @@ dependencies = [ "unicode-ident", ] +[[package]] +name = "prost" +version = "0.14.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "528ac67416ff8646872a3c02cad9cc4ee5dc9f9540c9b10771855c95cb2e5ae1" +dependencies = [ + "bytes", + "prost-derive", +] + +[[package]] +name = "prost-derive" +version = "0.14.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b570b25f7617e43d59005d0990ccb79e950a423952cea19671b7a876da390adf" +dependencies = [ + "anyhow", + "itertools", + "proc-macro2", + "quote", + "syn 2.0.117", +] + +[[package]] +name = "quinn" +version = "0.11.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c1a41e437b6bbd489372cd4971de128e85c855f56c57f283d20ff016cf7c0a8" +dependencies = [ + "bytes", + "cfg_aliases", + "pin-project-lite", + "quinn-proto", + "quinn-udp", + "rustc-hash", + "rustls", + "socket2", + "thiserror", + "tokio", + "tracing", + "web-time", +] + +[[package]] +name = "quinn-proto" +version = "0.11.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2f4bfc015262b9df63c8845072ce59068853ff5872180c2ce2f13038b970e560" +dependencies = [ + "aws-lc-rs", + "bytes", + "getrandom 0.4.2", + "lru-slab", + "rand 0.10.2", + "rand_pcg", + "ring", + "rustc-hash", + "rustls", + "rustls-pki-types", + "slab", + "thiserror", + "tinyvec", + "tracing", + "web-time", +] + +[[package]] +name = "quinn-udp" +version = "0.5.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "35a133f956daabe89a61a685c2649f13d82d5aa4bd5d12d1277e1072a21c0694" +dependencies = [ + "cfg_aliases", + "libc", + "once_cell", + "socket2", + "tracing", + "windows-sys 0.60.2", +] + [[package]] name = "quote" version = "1.0.45" @@ -1011,12 +1585,73 @@ dependencies = [ "proc-macro2", ] +[[package]] +name = "r-efi" +version = "5.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f" + [[package]] name = "r-efi" version = "6.0.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" +[[package]] +name = "rand" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41" +dependencies = [ + "rand_chacha", + "rand_core 0.9.5", +] + +[[package]] +name = "rand" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c7f5fa3a058cd35567ef9bfa5e75732bee0f9e4c55fa90477bef2dfcdbc4be80" +dependencies = [ + "chacha20", + "getrandom 0.4.2", + "rand_core 0.10.1", +] + +[[package]] +name = "rand_chacha" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb" +dependencies = [ + "ppv-lite86", + "rand_core 0.9.5", +] + +[[package]] +name = "rand_core" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c" +dependencies = [ + "getrandom 0.3.4", +] + +[[package]] +name = "rand_core" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69" + +[[package]] +name = "rand_pcg" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "caa0f4137e1c0a72f4c651489402276c8e8e1cf081f3b0ba156d2cbeef09e86a" +dependencies = [ + "rand_core 0.10.1", +] + [[package]] name = "redox_syscall" version = "0.5.18" @@ -1055,6 +1690,57 @@ version = "0.8.10" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a" +[[package]] +name = "reqwest" +version = "0.13.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "219c5811de6525e5416c7d5d53bb656d3afdbc6c5af816e0802bcfa42dbdc1c3" +dependencies = [ + "base64", + "bytes", + "futures-channel", + "futures-core", + "futures-util", + "http", + "http-body", + "http-body-util", + "hyper", + "hyper-rustls", + "hyper-util", + "js-sys", + "log", + "percent-encoding", + "pin-project-lite", + "quinn", + "rustls", + "rustls-pki-types", + "rustls-platform-verifier", + "sync_wrapper", + "tokio", + "tokio-rustls", + "tower", + "tower-http", + "tower-service", + "url", + "wasm-bindgen", + "wasm-bindgen-futures", + "web-sys", +] + +[[package]] +name = "ring" +version = "0.17.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7" +dependencies = [ + "cc", + "cfg-if", + "getrandom 0.2.17", + "libc", + "untrusted", + "windows-sys 0.52.0", +] + [[package]] name = "rmp" version = "0.8.15" @@ -1074,6 +1760,21 @@ dependencies = [ "serde", ] +[[package]] +name = "rustc-hash" +version = "2.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d" + +[[package]] +name = "rustc_version" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92" +dependencies = [ + "semver", +] + [[package]] name = "rustix" version = "1.1.4" @@ -1087,6 +1788,81 @@ dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "rustls" +version = "0.23.42" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3c54fcab019b409d04215d3a17cb438fd7fbf192ee61461f20f4fe18704bc138" +dependencies = [ + "aws-lc-rs", + "once_cell", + "rustls-pki-types", + "rustls-webpki", + "subtle", + "zeroize", +] + +[[package]] +name = "rustls-native-certs" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dab5152771c58876a2146916e53e35057e1a4dfa2b9df0f0305b07f611fdea4d" +dependencies = [ + "openssl-probe", + "rustls-pki-types", + "schannel", + "security-framework", +] + +[[package]] +name = "rustls-pki-types" +version = "1.15.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96" +dependencies = [ + "web-time", + "zeroize", +] + +[[package]] +name = "rustls-platform-verifier" +version = "0.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "26d1e2536ce4f35f4846aa13bff16bd0ff40157cdb14cc056c7b14ba41233ba0" +dependencies = [ + "core-foundation", + "core-foundation-sys", + "jni", + "log", + "once_cell", + "rustls", + "rustls-native-certs", + "rustls-platform-verifier-android", + "rustls-webpki", + "security-framework", + "security-framework-sys", + "webpki-root-certs", + "windows-sys 0.60.2", +] + +[[package]] +name = "rustls-platform-verifier-android" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f87165f0995f63a9fbeea62b64d10b4d9d8e78ec6d7d51fb2125fda7bb36788f" + +[[package]] +name = "rustls-webpki" +version = "0.103.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e" +dependencies = [ + "aws-lc-rs", + "ring", + "rustls-pki-types", + "untrusted", +] + [[package]] name = "rustversion" version = "1.0.22" @@ -1108,12 +1884,44 @@ dependencies = [ "winapi-util", ] +[[package]] +name = "schannel" +version = "0.1.29" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "91c1b7e4904c873ef0710c1f407dde2e6287de2bebc1bbbf7d430bb7cbffd939" +dependencies = [ + "windows-sys 0.61.2", +] + [[package]] name = "scopeguard" version = "1.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" +[[package]] +name = "security-framework" +version = "3.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d" +dependencies = [ + "bitflags", + "core-foundation", + "core-foundation-sys", + "libc", + "security-framework-sys", +] + +[[package]] +name = "security-framework-sys" +version = "2.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3" +dependencies = [ + "core-foundation-sys", + "libc", +] + [[package]] name = "semver" version = "1.0.28" @@ -1147,7 +1955,7 @@ checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.117", ] [[package]] @@ -1235,6 +2043,22 @@ dependencies = [ "libc", ] +[[package]] +name = "simd_cesu8" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "11031e251abf8611c80f460e19dbdeb54a66db918e49c65a7065b46ac7aec520" +dependencies = [ + "rustc_version", + "simdutf8", +] + +[[package]] +name = "simdutf8" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e" + [[package]] name = "slab" version = "0.4.12" @@ -1266,6 +2090,12 @@ dependencies = [ "lock_api", ] +[[package]] +name = "stable_deref_trait" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596" + [[package]] name = "strsim" version = "0.11.1" @@ -1289,11 +2119,36 @@ dependencies = [ "unicode-ident", ] +[[package]] +name = "syn" +version = "3.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + [[package]] name = "sync_wrapper" version = "1.0.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263" +dependencies = [ + "futures-core", +] + +[[package]] +name = "synstructure" +version = "0.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.117", +] [[package]] name = "tempfile" @@ -1325,7 +2180,7 @@ checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.117", ] [[package]] @@ -1337,6 +2192,31 @@ dependencies = [ "cfg-if", ] +[[package]] +name = "tinystr" +version = "0.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d" +dependencies = [ + "displaydoc", + "zerovec", +] + +[[package]] +name = "tinyvec" +version = "1.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bb4ebadaa0af04fab11ae01eb5f9fdb5f9c5b875506e210e71c07873528baa7f" +dependencies = [ + "tinyvec_macros", +] + +[[package]] +name = "tinyvec_macros" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20" + [[package]] name = "tokio" version = "1.52.3" @@ -1362,7 +2242,17 @@ checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.117", +] + +[[package]] +name = "tokio-rustls" +version = "0.26.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1729aa945f29d91ba541258c8df89027d5792d85a8841fb65e8bf0f4ede4ef61" +dependencies = [ + "rustls", + "tokio", ] [[package]] @@ -1402,12 +2292,15 @@ checksum = "68d6fdd9f81c2819c9a8b0e0cd91660e7746a8e6ea2ba7c6b2b057985f6bcb51" dependencies = [ "bitflags", "bytes", + "futures-util", "http", "http-body", "pin-project-lite", + "tower", "tower-layer", "tower-service", "tracing", + "url", ] [[package]] @@ -1442,7 +2335,7 @@ checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.117", ] [[package]] @@ -1484,6 +2377,12 @@ dependencies = [ "tracing-log", ] +[[package]] +name = "try-lock" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b" + [[package]] name = "typenum" version = "1.20.0" @@ -1508,12 +2407,36 @@ version = "0.2.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861" +[[package]] +name = "untrusted" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1" + [[package]] name = "unty" version = "0.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "6d49784317cd0d1ee7ec5c716dd598ec5b4483ea832a2dced265471cc0f690ae" +[[package]] +name = "url" +version = "2.5.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed" +dependencies = [ + "form_urlencoded", + "idna", + "percent-encoding", + "serde", +] + +[[package]] +name = "utf8_iter" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be" + [[package]] name = "utf8parse" version = "0.2.2" @@ -1548,6 +2471,15 @@ dependencies = [ "winapi-util", ] +[[package]] +name = "want" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e" +dependencies = [ + "try-lock", +] + [[package]] name = "wasi" version = "0.11.1+wasi-snapshot-preview1" @@ -1585,6 +2517,16 @@ dependencies = [ "wasm-bindgen-shared", ] +[[package]] +name = "wasm-bindgen-futures" +version = "0.4.71" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "96492d0d3ffba25305a7dc88720d250b1401d7edca02cc3bcd50633b424673b8" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + [[package]] name = "wasm-bindgen-macro" version = "0.2.121" @@ -1604,7 +2546,7 @@ dependencies = [ "bumpalo", "proc-macro2", "quote", - "syn", + "syn 2.0.117", "wasm-bindgen-shared", ] @@ -1651,6 +2593,35 @@ dependencies = [ "semver", ] +[[package]] +name = "web-sys" +version = "0.3.98" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4b572dff8bcf38bad0fa19729c89bb5748b2b9b1d8be70cf90df697e3a8f32aa" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "web-time" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "webpki-root-certs" +version = "1.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b96554aa2acc8ccdb7e1c9a58a7a68dd5d13bccc69cd124cb09406db612a1c9b" +dependencies = [ + "rustls-pki-types", +] + [[package]] name = "winapi-util" version = "0.1.11" @@ -1681,7 +2652,7 @@ checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.117", ] [[package]] @@ -1692,7 +2663,7 @@ checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358" dependencies = [ "proc-macro2", "quote", - "syn", + "syn 2.0.117", ] [[package]] @@ -1719,13 +2690,22 @@ dependencies = [ "windows-link", ] +[[package]] +name = "windows-sys" +version = "0.52.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d" +dependencies = [ + "windows-targets 0.52.6", +] + [[package]] name = "windows-sys" version = "0.60.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb" dependencies = [ - "windows-targets", + "windows-targets 0.53.5", ] [[package]] @@ -1737,6 +2717,22 @@ dependencies = [ "windows-link", ] +[[package]] +name = "windows-targets" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" +dependencies = [ + "windows_aarch64_gnullvm 0.52.6", + "windows_aarch64_msvc 0.52.6", + "windows_i686_gnu 0.52.6", + "windows_i686_gnullvm 0.52.6", + "windows_i686_msvc 0.52.6", + "windows_x86_64_gnu 0.52.6", + "windows_x86_64_gnullvm 0.52.6", + "windows_x86_64_msvc 0.52.6", +] + [[package]] name = "windows-targets" version = "0.53.5" @@ -1744,58 +2740,106 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3" dependencies = [ "windows-link", - "windows_aarch64_gnullvm", - "windows_aarch64_msvc", - "windows_i686_gnu", - "windows_i686_gnullvm", - "windows_i686_msvc", - "windows_x86_64_gnu", - "windows_x86_64_gnullvm", - "windows_x86_64_msvc", + "windows_aarch64_gnullvm 0.53.1", + "windows_aarch64_msvc 0.53.1", + "windows_i686_gnu 0.53.1", + "windows_i686_gnullvm 0.53.1", + "windows_i686_msvc 0.53.1", + "windows_x86_64_gnu 0.53.1", + "windows_x86_64_gnullvm 0.53.1", + "windows_x86_64_msvc 0.53.1", ] +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" + [[package]] name = "windows_aarch64_gnullvm" version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53" +[[package]] +name = "windows_aarch64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" + [[package]] name = "windows_aarch64_msvc" version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006" +[[package]] +name = "windows_i686_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" + [[package]] name = "windows_i686_gnu" version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3" +[[package]] +name = "windows_i686_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" + [[package]] name = "windows_i686_gnullvm" version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c" +[[package]] +name = "windows_i686_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" + [[package]] name = "windows_i686_msvc" version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2" +[[package]] +name = "windows_x86_64_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" + [[package]] name = "windows_x86_64_gnu" version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499" +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" + [[package]] name = "windows_x86_64_gnullvm" version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1" +[[package]] +name = "windows_x86_64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" + [[package]] name = "windows_x86_64_msvc" version = "0.53.1" @@ -1838,7 +2882,7 @@ dependencies = [ "heck", "indexmap", "prettyplease", - "syn", + "syn 2.0.117", "wasm-metadata", "wit-bindgen-core", "wit-component", @@ -1854,7 +2898,7 @@ dependencies = [ "prettyplease", "proc-macro2", "quote", - "syn", + "syn 2.0.117", "wit-bindgen-core", "wit-bindgen-rust", ] @@ -1896,6 +2940,115 @@ dependencies = [ "wasmparser", ] +[[package]] +name = "writeable" +version = "0.6.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4" + +[[package]] +name = "yoke" +version = "0.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5" +dependencies = [ + "stable_deref_trait", + "yoke-derive", + "zerofrom", +] + +[[package]] +name = "yoke-derive" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.117", + "synstructure", +] + +[[package]] +name = "zerocopy" +version = "0.8.55" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b5a105cd7b140f6eeec8acff2ea38135d3cab283ada58540f629fe51e46696eb" +dependencies = [ + "zerocopy-derive", +] + +[[package]] +name = "zerocopy-derive" +version = "0.8.55" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fe976fb70c78cd64cccfe3a6fc142244e8a77b70959b30faf9d0ac37ee228eb" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.117", +] + +[[package]] +name = "zerofrom" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272" +dependencies = [ + "zerofrom-derive", +] + +[[package]] +name = "zerofrom-derive" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.117", + "synstructure", +] + +[[package]] +name = "zeroize" +version = "1.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e" + +[[package]] +name = "zerotrie" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf" +dependencies = [ + "displaydoc", + "yoke", + "zerofrom", +] + +[[package]] +name = "zerovec" +version = "0.11.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239" +dependencies = [ + "yoke", + "zerofrom", + "zerovec-derive", +] + +[[package]] +name = "zerovec-derive" +version = "0.11.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.117", +] + [[package]] name = "zmij" version = "1.0.21" diff --git a/Cargo.toml b/Cargo.toml index b98363a..d2d3565 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -17,8 +17,17 @@ axum = "0.8" blake3 = "1" chrono = { version = "0.4", default-features = false, features = ["std", "serde", "clock"] } clap = { version = "4", features = ["derive", "env"] } +http-body = "1" hydra = "0.1" notify = "8" +opentelemetry = "0.32" +# `reqwest-rustls` is required alongside `reqwest-blocking-client`: the +# default otlp features wire reqwest with no TLS backend at all, so HTTPS to +# the collector would fail. rustls (aws-lc-rs + OS trust store) keeps the +# release binary free of a system OpenSSL dependency. +opentelemetry-otlp = { version = "0.32", default-features = false, features = ["trace", "metrics", "http-proto", "reqwest-blocking-client", "reqwest-rustls"] } +opentelemetry-semantic-conventions = "0.32" +opentelemetry_sdk = { version = "0.32", features = ["metrics", "trace"] } regex = "1" serde = { version = "1", features = ["derive"] } serde_json = "1" diff --git a/README.md b/README.md index 33cac92..d4e2fc0 100644 --- a/README.md +++ b/README.md @@ -56,19 +56,31 @@ anwesen merge --vault /path/to/vault --query 'tags=adr&__anw-order=title' > ADRs ``` anwesen serve --vault [--bind ] [--log-level ] + [--uptrace-dsn | --otlp-endpoint ] + [--otlp-header ]... [--otlp-slow-request-ms ] anwesen doctor --vault anwesen merge --vault --query anwesen version ``` -| Flag | Env var | Default | Meaning | -| ------------------------ | ------------------- | ---------------------- | ----------------------------------------------------------------------- | -| `--vault ` | `ANWESEN_VAULT` | _required_ | Path to the vault root. | -| `--bind ` | `ANWESEN_BIND` | `127.0.0.1:8080` | Listen address for `serve`. | -| `--log-level ` | `ANWESEN_LOG_LEVEL` | `info` | `error`, `warn`, `info`, `debug`, or `trace`. | -| `--query ` | -- | _required for `merge`_ | A `/query` query string: frontmatter predicates plus `__anw-` controls. | +| Flag | Env var | Default | Meaning | +| --------------------------- | ------------------------------ | ---------------------- | ----------------------------------------------------------------------------- | +| `--vault ` | `ANWESEN_VAULT` | _required_ | Path to the vault root. | +| `--bind ` | `ANWESEN_BIND` | `127.0.0.1:8080` | Listen address for `serve`. | +| `--log-level ` | `ANWESEN_LOG_LEVEL` | `info` | `error`, `warn`, `info`, `debug`, or `trace`. | +| `--query ` | -- | _required for `merge`_ | A `/query` query string: frontmatter predicates plus `__anw-` controls. | +| `--uptrace-dsn ` | `ANWESEN_UPTRACE_DSN` | unset | uptrace DSN (`https://@api.uptrace.dev`). Excludes `--otlp-endpoint`. | +| `--otlp-endpoint ` | `ANWESEN_OTLP_ENDPOINT` | unset | OTLP/HTTP base URL. Excludes `--uptrace-dsn`. | +| `--otlp-header ` | `ANWESEN_OTLP_HEADERS` | none | Extra export header, repeatable. The env var takes a comma-separated list. | +| `--otlp-slow-request-ms` | `ANWESEN_OTLP_SLOW_REQUEST_MS` | `500` | Requests at or over this duration, or answering 5xx, also export a span. | -Every flag has a matching `ANWESEN_` environment variable; CLI flags win over env vars. +Every flag has a matching `ANWESEN_` environment variable, except +`--otlp-header`, whose env var is the plural `ANWESEN_OTLP_HEADERS` because it +takes a list. CLI flags win over env vars. + +Telemetry is off unless `--uptrace-dsn` or `--otlp-endpoint` is set. With +neither, nothing is exported and no exporter is built. The four telemetry +flags apply to `serve` only. - **`serve`** -- run the daemon: walk the vault, build the index, watch for changes, serve the API. - **`doctor`** -- walk the vault once and report what would stop clean ingestion: unreadable files, unparseable YAML, path collisions on the HTTP surface, and frontmatter type drift (the same key carrying incompatible types across notes). Read-only; non-zero exit if any issue is found. diff --git a/src/app.rs b/src/app.rs index 5677d57..17d193d 100644 --- a/src/app.rs +++ b/src/app.rs @@ -40,6 +40,7 @@ use tokio::task::JoinHandle; use crate::health::HealthState; use crate::http::{self as http_layer, HttpState}; use crate::store::NoteStore; +use crate::telemetry::Telemetry; use crate::vault::{self, Note}; use crate::watcher::run_debouncer; @@ -117,17 +118,21 @@ pub struct Anwesen { pub store: Arc, /// Shared mutable health surface consumed by `/health` ([ANW-8]). pub health: Arc, + /// Request-level telemetry handle ([ANW-37]). `None` disables export and + /// the request middleware entirely. + pub telemetry: Option>, } impl Anwesen { #[must_use] - pub fn new(vault: PathBuf, bind: SocketAddr) -> Self { + pub fn new(vault: PathBuf, bind: SocketAddr, telemetry: Option>) -> Self { Self { vault, bind, counters: RestartCounters::new(), store: NoteStore::new(), health: HealthState::new(), + telemetry, } } } @@ -177,6 +182,7 @@ impl Application for Anwesen { store: self.store.clone(), health: self.health.clone(), vault: self.vault.clone(), + telemetry: self.telemetry.clone(), } .child_spec(), ]; @@ -535,6 +541,7 @@ pub struct HttpServer { store: Arc, health: Arc, vault: PathBuf, + telemetry: Option>, } impl HttpServer { @@ -544,12 +551,14 @@ impl HttpServer { let store = self.store.clone(); let health = self.health.clone(); let vault = self.vault.clone(); + let telemetry = self.telemetry.clone(); ChildSpec::new(HTTP_SERVER_NAME).start(move || { let bind = bind; let counters = counters.clone(); let store = store.clone(); let health = health.clone(); let vault = vault.clone(); + let telemetry = telemetry.clone(); async move { // Bind eagerly so the supervisor sees `bind: : ...` // as the start error rather than a successful spawn that @@ -558,12 +567,15 @@ impl HttpServer { .await .map_err(|e| ExitReason::from(format!("http_server: bind {bind}: {e}")))?; let restart = counters.http_server.record_init(); - let router = http_layer::router(HttpState { - store, - health, - restart_counters: counters, - vault, - }); + let router = http_layer::router( + HttpState { + store, + health, + restart_counters: counters, + vault, + }, + telemetry, + ); let pid = Process::spawn_link(async move { Process::set_flags(ProcessFlags::TRAP_EXIT); tracing::info!(restart, bind = %bind, "http_server: init"); diff --git a/src/cli.rs b/src/cli.rs index c3b1f21..155ab5b 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -4,14 +4,18 @@ //! //! ```text //! anwesen serve --vault [--bind ] [--log-level ] +//! [--uptrace-dsn | --otlp-endpoint ] +//! [--otlp-header ]... [--otlp-slow-request-ms ] //! anwesen doctor --vault [--log-level ] //! anwesen merge --vault [--query ] [--log-level ] //! anwesen version //! ``` //! -//! `--bind` is `serve`-only; `doctor` and `merge` do not bind a port; -//! `version` takes no flags. Each flag has a matching `ANWESEN_` -//! environment variable and CLI wins over env per the manual. +//! `--bind` and the OTLP telemetry flags are `serve`-only ([ANW-37]); +//! `doctor` and `merge` do not bind a port; `version` takes no flags. Each +//! flag has a matching `ANWESEN_` environment variable and CLI wins +//! over env per the manual. With no `--otlp-endpoint`/`--uptrace-dsn`, +//! telemetry is off and the server behaves exactly as without these flags. use std::net::SocketAddr; use std::path::PathBuf; @@ -51,6 +55,34 @@ pub struct ServeArgs { /// Log verbosity. #[arg(long, env = "ANWESEN_LOG_LEVEL", default_value = "info")] pub log_level: LogLevel, + + /// uptrace DSN shorthand (`https://@api.uptrace.dev`), parsed + /// into the OTLP endpoint plus an `uptrace-dsn` header. Mutually + /// exclusive with --otlp-endpoint. When this and --otlp-endpoint are + /// both unset, telemetry is fully off (ANW-37). + #[arg(long, env = "ANWESEN_UPTRACE_DSN")] + pub uptrace_dsn: Option, + + /// Generic OTLP/HTTP endpoint base URL for telemetry export. The + /// per-signal path (`/v1/metrics`, `/v1/traces`) is appended by the + /// exporter. Mutually exclusive with --uptrace-dsn. + #[arg(long, env = "ANWESEN_OTLP_ENDPOINT")] + pub otlp_endpoint: Option, + + /// Extra OTLP export header as `key=value`, repeatable. On the env var + /// (`ANWESEN_OTLP_HEADERS`) pass a comma-separated `key=value` list. + #[arg( + long = "otlp-header", + env = "ANWESEN_OTLP_HEADERS", + value_delimiter = ',' + )] + pub otlp_headers: Vec, + + /// Requests at or over this duration in milliseconds, or answering a + /// 5xx, are additionally recorded as OTLP server spans; every other + /// request stays metrics-only. + #[arg(long, env = "ANWESEN_OTLP_SLOW_REQUEST_MS", default_value = "500")] + pub otlp_slow_request_ms: u64, } #[derive(Debug, clap::Args)] diff --git a/src/http.rs b/src/http.rs index 9296811..48ec78e 100644 --- a/src/http.rs +++ b/src/http.rs @@ -12,16 +12,18 @@ //! `/health` ([ANW-8]) onto the same [`Router`]. use std::sync::Arc; +use std::time::{Instant, SystemTime}; use axum::Router; use axum::body::Body; use axum::extract::{OriginalUri, Path as AxumPath, Request, State}; -use axum::http::header::{ACCEPT, CONTENT_TYPE, ETAG, IF_NONE_MATCH}; +use axum::http::header::{ACCEPT, CONTENT_LENGTH, CONTENT_TYPE, ETAG, IF_NONE_MATCH}; use axum::http::{HeaderMap, HeaderValue, StatusCode}; -use axum::middleware::{Next, from_fn}; +use axum::middleware::{Next, from_fn, from_fn_with_state}; use axum::response::{IntoResponse, Response}; use axum::routing::get; use chrono::{DateTime, SecondsFormat, Utc}; +use http_body::Body as _; use hydra::Process; use serde::Serialize; use std::collections::BTreeMap; @@ -31,6 +33,7 @@ use std::path::PathBuf; use crate::app::RestartCounters; use crate::health::HealthState; use crate::store::NoteStore; +use crate::telemetry::{self, Telemetry, TraceHeaders}; use crate::vault::{Note, frontmatter_to_json}; /// Canonical RFC 3339 form with a `Z` suffix -- the shape the User Manual @@ -49,18 +52,72 @@ pub struct HttpState { pub vault: PathBuf, } -pub fn router(state: HttpState) -> Router { +pub fn router(state: HttpState, telemetry: Option>) -> Router { // `/notes/{*path}` is greedy and includes any trailing slash; one // handler dispatches read-one vs folder-listing on that suffix. The // root listing (`/notes/`) needs its own route since the wildcard // requires at least one character. - Router::new() + let router = Router::new() .route("/notes/", get(list_root_folder)) .route("/notes/{*path}", get(get_notes)) .route("/query", get(get_query)) .route("/health", get(get_health)) - .layer(from_fn(process_wrap)) - .with_state(state) + .layer(from_fn(process_wrap)); + // Telemetry is the outermost layer so it observes the final response, + // including the `500` that `process_wrap` synthesizes on a handler + // panic. Installed only when export is configured; a config-less server + // never runs this layer and is byte-for-byte as before ([ANW-37]). + let router = match telemetry { + Some(tel) => router.layer(from_fn_with_state(tel, telemetry_wrap)), + None => router, + }; + router.with_state(state) +} + +/// Outermost middleware: time the request, classify its route, and hand the +/// completed observation to [`Telemetry`]. Trace-context headers are captured +/// up front (the handler consumes the request); the parent context is only +/// extracted later if the request turns out slow enough to span. +async fn telemetry_wrap( + State(tel): State>, + request: Request, + next: Next, +) -> Response { + let start_instant = Instant::now(); + let start_wall = SystemTime::now(); + let route = telemetry::classify_route(request.uri().path()); + let method = request.method().clone(); + let if_none_match_present = request.headers().contains_key(IF_NONE_MATCH); + let trace = TraceHeaders::from_headers(request.headers()); + + let response = next.run(request).await; + + let status = response.status().as_u16(); + // In-memory handler bodies carry an exact size hint; fall back to a + // Content-Length header, then to 0, so a streaming body never panics. + let body_bytes = response + .body() + .size_hint() + .exact() + .or_else(|| content_length(response.headers())) + .unwrap_or(0); + let duration = start_instant.elapsed(); + + tel.finish( + route, + method.as_str(), + status, + if_none_match_present, + body_bytes, + duration, + start_wall, + &trace, + ); + response +} + +fn content_length(headers: &HeaderMap) -> Option { + headers.get(CONTENT_LENGTH)?.to_str().ok()?.parse().ok() } /// Per [ANW-25](https://crvrs.youtrack.cloud/issue/ANW-25): run each request @@ -460,12 +517,15 @@ mod tests { fn router_with(notes: Vec) -> (Router, Arc) { let store = NoteStore::new(); store.replace(notes); - let r = router(HttpState { - store: store.clone(), - health: crate::health::HealthState::new(), - restart_counters: crate::app::RestartCounters::new(), - vault: PathBuf::from("/test/vault"), - }); + let r = router( + HttpState { + store: store.clone(), + health: crate::health::HealthState::new(), + restart_counters: crate::app::RestartCounters::new(), + vault: PathBuf::from("/test/vault"), + }, + None, + ); (r, store) } @@ -757,4 +817,46 @@ mod tests { assert!(resolve_path("").is_err()); assert!(resolve_path("a/%ZZ.md").is_err()); } + + /// With telemetry installed, a normal request is answered byte-for-byte + /// as without it. The exporter points at an unreachable local port, so + /// export fails instantly in the background and never touches the + /// response path. + #[tokio::test] + async fn telemetry_layer_does_not_alter_responses() { + use crate::telemetry::{self, RawTelemetryArgs, TelemetryConfig}; + + let cfg = TelemetryConfig::resolve(RawTelemetryArgs { + otlp_endpoint: Some("http://127.0.0.1:9".into()), + slow_request_ms: 500, + ..Default::default() + }) + .unwrap() + .expect("telemetry on"); + let tel = Arc::new(telemetry::init(cfg).expect("telemetry init")); + + let n = note("a.md", "body"); + let expected_etag = n.etag.clone(); + let store = NoteStore::new(); + store.replace(vec![n]); + let r = router( + HttpState { + store, + health: crate::health::HealthState::new(), + restart_counters: crate::app::RestartCounters::new(), + vault: PathBuf::from("/test/vault"), + }, + Some(tel.clone()), + ); + let req = Request::get("/notes/a.md").body(Body::empty()).unwrap(); + let resp = send(r, req).await; + assert_eq!(resp.status(), StatusCode::OK); + assert_eq!(resp.headers().get(ETAG).unwrap(), expected_etag.as_str()); + let bytes = to_bytes(resp.into_body(), 64 * 1024).await.unwrap(); + let v: serde_json::Value = serde_json::from_slice(&bytes).unwrap(); + assert_eq!(v["path"], "a.md"); + assert_eq!(v["body"], "body"); + + tel.shutdown(); + } } diff --git a/src/lib.rs b/src/lib.rs index 0111390..59f1689 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -13,5 +13,6 @@ pub mod http; pub mod merge; pub mod query; pub mod store; +pub mod telemetry; pub mod vault; pub mod watcher; diff --git a/src/main.rs b/src/main.rs index f265ced..f573e3f 100644 --- a/src/main.rs +++ b/src/main.rs @@ -5,9 +5,12 @@ mod cli; +use std::sync::Arc; + use anwesen::app::Anwesen; use anwesen::doctor; use anwesen::merge; +use anwesen::telemetry::{self, RawTelemetryArgs, TelemetryConfig}; use anyhow::Result; use clap::Parser; use hydra::Application; @@ -15,21 +18,36 @@ use hydra::Application; use crate::cli::{Cli, Command}; // Result is retained at the binary boundary per [[ADR-001 Language and -// Foundation Libraries]] (anyhow at main); current stubs do not yet -// surface errors. -#[allow(clippy::unnecessary_wraps)] +// Foundation Libraries]] (anyhow at main); telemetry config resolution and +// exporter setup surface startup errors through it. fn main() -> Result<()> { let cli = Cli::parse(); match cli.command { Command::Serve(args) => { init_logging(args.log_level); + // Resolve telemetry config before the supervisor starts; an + // unset endpoint leaves it `None` (export off, behaves as today). + let telemetry = match TelemetryConfig::resolve(RawTelemetryArgs { + uptrace_dsn: args.uptrace_dsn, + otlp_endpoint: args.otlp_endpoint, + otlp_headers: args.otlp_headers, + slow_request_ms: args.otlp_slow_request_ms, + })? { + Some(cfg) => Some(Arc::new(telemetry::init(cfg)?)), + None => None, + }; tracing::info!( vault = %args.vault.display(), bind = %args.bind, + telemetry = telemetry.is_some(), "anwesen serve: starting supervisor tree" ); // Blocks until the supervisor exits (SIGTERM / SIGINT / crash). - Anwesen::new(args.vault, args.bind).run(); + Anwesen::new(args.vault, args.bind, telemetry.clone()).run(); + // Flush and shut down exporters after the server loop returns. + if let Some(telemetry) = telemetry { + telemetry.shutdown(); + } } Command::Doctor(args) => { init_logging(args.log_level); diff --git a/src/telemetry.rs b/src/telemetry.rs new file mode 100644 index 0000000..a685b2d --- /dev/null +++ b/src/telemetry.rs @@ -0,0 +1,620 @@ +//! Request-level telemetry for the HTTP surface, per +//! [ANW-37](https://crvrs.youtrack.cloud/issue/ANW-37). +//! +//! Two halves: +//! +//! - **Metrics** (every request): a request counter and a response-bytes +//! counter keyed by route, status, and conditional-GET outcome, plus a +//! duration histogram keyed by route and status. Exported over OTLP. +//! - **Traces** (slow or failing requests only): the incoming W3C +//! `traceparent` is extracted, and a request at or over the configured +//! threshold, or answering a 5xx, is recorded as a server span nested in +//! the propagated context. Every other request stays metrics-only, so the +//! ~3.6k requests/min steady state does not drown the trace backend. +//! +//! When no OTLP endpoint (or uptrace DSN) is configured, [`init`] returns +//! `None`, the request middleware is not installed, and the server behaves +//! exactly as it did before this module existed. External installs run +//! unchanged. +//! +//! Config mirrors the gestell uptrace surface (see the gestell PDR-GES-136 +//! `[otel]` section): a `uptrace_dsn` shorthand, or a generic endpoint plus +//! headers. + +use std::collections::HashMap; +use std::time::{Duration, SystemTime}; + +use anyhow::{Context as _, anyhow, bail}; +use axum::http::HeaderMap; +use opentelemetry::KeyValue; +use opentelemetry::metrics::{Counter, Histogram, MeterProvider as _}; +use opentelemetry::propagation::{Extractor, TextMapPropagator}; +use opentelemetry::trace::{Span, SpanKind, Tracer, TracerProvider as _}; +use opentelemetry_otlp::{ + MetricExporter, Protocol, SpanExporter, WithExportConfig, WithHttpConfig, +}; +use opentelemetry_sdk::Resource; +use opentelemetry_sdk::metrics::{PeriodicReader, SdkMeterProvider}; +use opentelemetry_sdk::propagation::TraceContextPropagator; +use opentelemetry_sdk::trace::Sampler; +use opentelemetry_sdk::trace::{SdkTracer, SdkTracerProvider}; +use opentelemetry_semantic_conventions::resource::SERVICE_VERSION; + +/// Raw telemetry options as parsed by clap on the `serve` command. Resolved +/// into an [`Option`] by [`TelemetryConfig::resolve`]. +#[derive(Debug, Default)] +pub struct RawTelemetryArgs { + /// `--uptrace-dsn` / `ANWESEN_UPTRACE_DSN`. + pub uptrace_dsn: Option, + /// `--otlp-endpoint` / `ANWESEN_OTLP_ENDPOINT`. + pub otlp_endpoint: Option, + /// `--otlp-header` / `ANWESEN_OTLP_HEADERS`, each `key=value`. + pub otlp_headers: Vec, + /// `--otlp-slow-request-ms` / `ANWESEN_OTLP_SLOW_REQUEST_MS`. + pub slow_request_ms: u64, +} + +/// A resolved, telemetry-on configuration. Built only when an endpoint or a +/// DSN is present; absence is represented by `Ok(None)` from [`resolve`]. +/// +/// [`resolve`]: TelemetryConfig::resolve +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct TelemetryConfig { + /// OTLP/HTTP base URL. The exporter appends the per-signal path + /// (`/v1/metrics`, `/v1/traces`). + pub endpoint: String, + /// Export headers (for uptrace, the `uptrace-dsn` entry) as ordered + /// `(name, value)` pairs. + pub headers: Vec<(String, String)>, + /// A request at or over this duration, or answering a 5xx, is recorded + /// as a server span. + pub slow_request: Duration, +} + +impl TelemetryConfig { + /// Resolve raw clap options into an optional config. + /// + /// - Both `uptrace_dsn` and `otlp_endpoint` set is an error (they are + /// two ways to name the same endpoint). + /// - Neither set means telemetry is off: `Ok(None)`. + /// - A malformed `key=value` header or an unparseable DSN is an error, + /// surfaced at startup rather than silently dropping export. + /// + /// # Errors + /// Returns an error when the two endpoint sources conflict, a header is + /// not `key=value`, or the uptrace DSN cannot be parsed. + pub fn resolve(raw: RawTelemetryArgs) -> anyhow::Result> { + let slow_request = Duration::from_millis(raw.slow_request_ms); + let mut headers = parse_headers(&raw.otlp_headers)?; + + match (raw.uptrace_dsn, raw.otlp_endpoint) { + (Some(_), Some(_)) => { + bail!("--uptrace-dsn and --otlp-endpoint are mutually exclusive"); + } + (Some(dsn), None) => { + let (endpoint, dsn_header) = parse_uptrace_dsn(&dsn)?; + // The DSN header leads; any explicit --otlp-header follows. + headers.insert(0, dsn_header); + Ok(Some(Self { + endpoint, + headers, + slow_request, + })) + } + (None, Some(endpoint)) => Ok(Some(Self { + endpoint, + headers, + slow_request, + })), + (None, None) => Ok(None), + } + } +} + +/// Parse `key=value` header specs. Whitespace around key and value is +/// trimmed; an empty key or a spec with no `=` is an error. +fn parse_headers(specs: &[String]) -> anyhow::Result> { + let mut out = Vec::with_capacity(specs.len()); + for spec in specs { + let (k, v) = spec + .split_once('=') + .ok_or_else(|| anyhow!("OTLP header {spec:?} is not key=value"))?; + let k = k.trim(); + if k.is_empty() { + bail!("OTLP header {spec:?} has an empty key"); + } + out.push((k.to_string(), v.trim().to_string())); + } + Ok(out) +} + +/// Parse an uptrace DSN (`https://@host[:port]`) into the OTLP +/// endpoint base URL and the `uptrace-dsn` header uptrace expects. The full +/// DSN is echoed as the header value per uptrace's ingest contract. +fn parse_uptrace_dsn(dsn: &str) -> anyhow::Result<(String, (String, String))> { + let dsn = dsn.trim(); + let (scheme, rest) = dsn + .split_once("://") + .context("uptrace DSN has no scheme (expected https://@host)")?; + // Host is whatever follows the credentials `@`; a DSN with no `@` is + // treated as endpoint-only (lenient, though real uptrace DSNs carry a + // token). + let host = rest.rsplit_once('@').map_or(rest, |(_, h)| h); + let host = host.trim_end_matches('/'); + if host.is_empty() { + bail!("uptrace DSN has no host"); + } + let endpoint = format!("{scheme}://{host}"); + Ok((endpoint, ("uptrace-dsn".to_string(), dsn.to_string()))) +} + +/// Semantic route bucket for the `http.route` label. Coarser than the axum +/// template on purpose: `/notes/{*path}` serves both a note fetch and a +/// folder listing, and "304 share of note fetches" needs the two apart. The +/// bucket is a function of the request path prefix and its trailing slash. +#[must_use] +pub fn classify_route(path: &str) -> &'static str { + if path == "/health" { + "health" + } else if path == "/query" { + "query" + } else if path == "/notes/" { + "folder" + } else if path.starts_with("/notes/") { + if path.ends_with('/') { + "folder" + } else { + "note" + } + } else { + "other" + } +} + +/// Whether a completed request additionally warrants a server span: it took +/// at least the slow threshold, or answered a server error. Everything else +/// stays metrics-only so the steady-state request rate does not flood the +/// trace backend. +#[must_use] +pub fn should_span(duration: Duration, slow_request: Duration, status: u16) -> bool { + duration >= slow_request || status >= 500 +} + +/// Conditional-GET outcome for the `conditional_get` label, derived from the +/// response status and whether the request carried `If-None-Match`: +/// +/// - `not_modified`: a 304 (the client's etag matched); +/// - `revalidated`: `If-None-Match` was present but the body was still sent +/// (etag mismatch); +/// - `unconditional`: no `If-None-Match` header. +/// +/// Together these answer both the 304 share of note fetches and the +/// If-None-Match presence share. +#[must_use] +pub fn conditional_get(status: u16, if_none_match_present: bool) -> &'static str { + if status == 304 { + "not_modified" + } else if if_none_match_present { + "revalidated" + } else { + "unconditional" + } +} + +/// Histogram bucket boundaries for `http.server.request.duration`, in +/// seconds. Extended out to 600 s because the fleet p50 is ~305 s (ANW-38); +/// the default `OTel` buckets top out near 10 s, so every slow request would +/// land in one overflow bucket and the percentiles the issue needs would be +/// unreadable. +pub const DURATION_BUCKETS_SECONDS: &[f64] = &[ + 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0, 60.0, 120.0, 300.0, 600.0, +]; + +/// The W3C trace-context header values carried by a request, captured before +/// the handler consumes it. Extracting the parent context is deferred to +/// span-emission time, so the hot path (metrics-only requests) pays only two +/// header reads, not a full propagator extraction. +#[derive(Debug, Default, Clone)] +pub struct TraceHeaders { + pub traceparent: Option, + pub tracestate: Option, +} + +impl TraceHeaders { + #[must_use] + pub fn from_headers(headers: &HeaderMap) -> Self { + let get = |name: &str| { + headers + .get(name) + .and_then(|v| v.to_str().ok()) + .map(str::to_owned) + }; + Self { + traceparent: get("traceparent"), + tracestate: get("tracestate"), + } + } +} + +/// Lets the W3C propagator read the captured header values directly, without +/// rebuilding a `HeaderMap`. Only `traceparent` and `tracestate` matter for +/// trace-context extraction. +impl Extractor for TraceHeaders { + fn get(&self, key: &str) -> Option<&str> { + match key { + "traceparent" => self.traceparent.as_deref(), + "tracestate" => self.tracestate.as_deref(), + _ => None, + } + } + + fn keys(&self) -> Vec<&str> { + let mut keys = Vec::with_capacity(2); + if self.traceparent.is_some() { + keys.push("traceparent"); + } + if self.tracestate.is_some() { + keys.push("tracestate"); + } + keys + } +} + +/// Live telemetry handle: owns the OTLP meter and tracer providers and the +/// instruments, and records one observation per request. Created by [`init`] +/// only when telemetry is configured; when it is not, the request middleware +/// is never installed and this type is never constructed. +pub struct Telemetry { + inner: TelemetryInner, +} + +impl Telemetry { + /// Record one completed request: bump the metric instruments, and -- when + /// the request was at or over the slow threshold or answered a 5xx -- + /// emit a server span nested under the propagated trace context. + /// + /// `start` is the wall-clock instant the request arrived, used as the + /// span start time so the span's own duration matches `duration`. + #[allow(clippy::too_many_arguments)] + pub fn finish( + &self, + route: &'static str, + method: &str, + status: u16, + if_none_match_present: bool, + body_bytes: u64, + duration: Duration, + start: SystemTime, + trace: &TraceHeaders, + ) { + self.inner + .record_metrics(route, status, if_none_match_present, body_bytes, duration); + if should_span(duration, self.inner.slow_request, status) { + self.inner + .record_span(route, method, status, duration, start, trace); + } + } + + /// Flush and shut down the providers. Called once at server exit. + pub fn shutdown(&self) { + self.inner.shutdown(); + } +} + +/// Build the telemetry handle from a resolved config, standing up the OTLP +/// meter and tracer providers. +/// +/// # Errors +/// Returns an error when an OTLP exporter cannot be constructed. +pub fn init(config: TelemetryConfig) -> anyhow::Result { + Ok(Telemetry { + inner: TelemetryInner::new(config)?, + }) +} + +// -- OTLP wiring seam ------------------------------------------------------- +// +// `TelemetryInner` owns the OTel providers and instruments. The public +// surface above (`finish`, `shutdown`, `TraceHeaders`, `classify_route`, +// `conditional_get`, the bucket boundaries) is stable; only the bodies below +// change as the exporters are wired. + +struct TelemetryInner { + slow_request: Duration, + meter_provider: SdkMeterProvider, + tracer_provider: SdkTracerProvider, + tracer: SdkTracer, + requests: Counter, + response_bytes: Counter, + duration: Histogram, + propagator: TraceContextPropagator, +} + +impl TelemetryInner { + fn new(config: TelemetryConfig) -> anyhow::Result { + let TelemetryConfig { + endpoint, + headers, + slow_request, + } = config; + // `.with_endpoint()` is used verbatim by the exporter (the `/v1/*` + // suffix is only auto-appended for the generic OTEL env var), so we + // append the per-signal path ourselves. + let endpoint = endpoint.trim_end_matches('/').to_string(); + let header_map: HashMap = headers.into_iter().collect(); + + let resource = Resource::builder() + .with_service_name("anwesen") + .with_attribute(KeyValue::new(SERVICE_VERSION, env!("CARGO_PKG_VERSION"))) + .build(); + + // -- metrics: thread-based periodic reader over an OTLP/HTTP exporter. + let metric_exporter = MetricExporter::builder() + .with_http() + .with_protocol(Protocol::HttpBinary) + .with_endpoint(format!("{endpoint}/v1/metrics")) + .with_headers(header_map.clone()) + .build() + .context("build OTLP metric exporter")?; + let reader = PeriodicReader::builder(metric_exporter) + .with_interval(Duration::from_secs(15)) + .build(); + let meter_provider = SdkMeterProvider::builder() + .with_resource(resource.clone()) + .with_reader(reader) + .build(); + let meter = meter_provider.meter("anwesen"); + let requests = meter + .u64_counter("http.server.requests") + .with_unit("{request}") + .with_description("HTTP requests by route, status, and conditional-GET outcome") + .build(); + let response_bytes = meter + .u64_counter("http.server.response.body.size") + .with_unit("By") + .with_description( + "HTTP response body bytes by route, status, and conditional-GET outcome", + ) + .build(); + let duration = meter + .f64_histogram("http.server.request.duration") + .with_unit("s") + .with_description("HTTP request duration by route and status") + .with_boundaries(DURATION_BUCKETS_SECONDS.to_vec()) + .build(); + + // -- traces: thread-based batch processor over an OTLP/HTTP exporter. + let span_exporter = SpanExporter::builder() + .with_http() + .with_protocol(Protocol::HttpBinary) + .with_endpoint(format!("{endpoint}/v1/traces")) + .with_headers(header_map) + .build() + .context("build OTLP span exporter")?; + let tracer_provider = SdkTracerProvider::builder() + .with_resource(resource) + // Span creation is already gated to slow/5xx requests in + // `record_span`, so sample everything we choose to build. + .with_sampler(Sampler::AlwaysOn) + .with_batch_exporter(span_exporter) + .build(); + let tracer = tracer_provider.tracer("anwesen"); + + tracing::info!( + endpoint = %endpoint, + slow_request_ms = slow_request.as_millis(), + "telemetry: OTLP export enabled" + ); + + Ok(Self { + slow_request, + meter_provider, + tracer_provider, + tracer, + requests, + response_bytes, + duration, + propagator: TraceContextPropagator::new(), + }) + } + + fn record_metrics( + &self, + route: &'static str, + status: u16, + if_none_match_present: bool, + body_bytes: u64, + duration: Duration, + ) { + let attrs = [ + KeyValue::new("http.route", route), + KeyValue::new("http.response.status_code", i64::from(status)), + KeyValue::new( + "conditional_get", + conditional_get(status, if_none_match_present), + ), + ]; + self.requests.add(1, &attrs); + self.response_bytes.add(body_bytes, &attrs); + // The histogram stays at route x status per the contract; the + // conditional-GET dimension lives on the counters only. + self.duration.record( + duration.as_secs_f64(), + &[ + KeyValue::new("http.route", route), + KeyValue::new("http.response.status_code", i64::from(status)), + ], + ); + } + + fn record_span( + &self, + route: &'static str, + method: &str, + status: u16, + duration: Duration, + start: SystemTime, + trace: &TraceHeaders, + ) { + let parent_cx = self.propagator.extract(trace); + let mut span = self + .tracer + .span_builder(format!("{method} {route}")) + .with_kind(SpanKind::Server) + .with_start_time(start) + .with_attributes(vec![ + KeyValue::new("http.request.method", method.to_string()), + KeyValue::new("http.route", route), + KeyValue::new("http.response.status_code", i64::from(status)), + ]) + .start_with_context(&self.tracer, &parent_cx); + span.end_with_timestamp(start + duration); + } + + fn shutdown(&self) { + if let Err(e) = self.meter_provider.shutdown() { + tracing::warn!(error = %e, "telemetry: meter provider shutdown"); + } + if let Err(e) = self.tracer_provider.shutdown() { + tracing::warn!(error = %e, "telemetry: tracer provider shutdown"); + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn raw() -> RawTelemetryArgs { + RawTelemetryArgs::default() + } + + #[test] + fn resolve_off_when_nothing_set() { + let cfg = TelemetryConfig::resolve(raw()).unwrap(); + assert!(cfg.is_none(), "no endpoint/DSN means telemetry off"); + } + + #[test] + fn resolve_generic_endpoint() { + let cfg = TelemetryConfig::resolve(RawTelemetryArgs { + otlp_endpoint: Some("https://collector.example.com".into()), + otlp_headers: vec!["authorization=Bearer xyz".into()], + slow_request_ms: 500, + ..raw() + }) + .unwrap() + .expect("telemetry on"); + assert_eq!(cfg.endpoint, "https://collector.example.com"); + assert_eq!( + cfg.headers, + vec![("authorization".to_string(), "Bearer xyz".to_string())] + ); + assert_eq!(cfg.slow_request, Duration::from_millis(500)); + } + + #[test] + fn resolve_uptrace_dsn_splits_endpoint_and_header() { + let cfg = TelemetryConfig::resolve(RawTelemetryArgs { + uptrace_dsn: Some("https://SECRET_TOKEN@api.uptrace.dev".into()), + slow_request_ms: 250, + ..raw() + }) + .unwrap() + .expect("telemetry on"); + assert_eq!(cfg.endpoint, "https://api.uptrace.dev"); + assert_eq!( + cfg.headers, + vec![( + "uptrace-dsn".to_string(), + "https://SECRET_TOKEN@api.uptrace.dev".to_string() + )] + ); + assert_eq!(cfg.slow_request, Duration::from_millis(250)); + } + + #[test] + fn resolve_dsn_header_leads_explicit_headers() { + let cfg = TelemetryConfig::resolve(RawTelemetryArgs { + uptrace_dsn: Some("https://tok@api.uptrace.dev".into()), + otlp_headers: vec!["x-extra=1".into()], + ..raw() + }) + .unwrap() + .expect("telemetry on"); + assert_eq!(cfg.headers[0].0, "uptrace-dsn"); + assert_eq!(cfg.headers[1], ("x-extra".to_string(), "1".to_string())); + } + + #[test] + fn resolve_rejects_both_endpoint_sources() { + let err = TelemetryConfig::resolve(RawTelemetryArgs { + uptrace_dsn: Some("https://tok@api.uptrace.dev".into()), + otlp_endpoint: Some("https://collector.example.com".into()), + ..raw() + }) + .unwrap_err(); + assert!(err.to_string().contains("mutually exclusive")); + } + + #[test] + fn resolve_rejects_malformed_header() { + let err = TelemetryConfig::resolve(RawTelemetryArgs { + otlp_endpoint: Some("https://collector.example.com".into()), + otlp_headers: vec!["no-equals-sign".into()], + ..raw() + }) + .unwrap_err(); + assert!(err.to_string().contains("key=value")); + } + + #[test] + fn resolve_rejects_dsn_without_scheme() { + let err = TelemetryConfig::resolve(RawTelemetryArgs { + uptrace_dsn: Some("tok@api.uptrace.dev".into()), + ..raw() + }) + .unwrap_err(); + assert!(err.to_string().contains("scheme")); + } + + #[test] + fn classify_route_buckets() { + assert_eq!(classify_route("/health"), "health"); + assert_eq!(classify_route("/query"), "query"); + assert_eq!(classify_route("/notes/"), "folder"); + assert_eq!(classify_route("/notes/a.md"), "note"); + assert_eq!(classify_route("/notes/Projects/a.md"), "note"); + assert_eq!(classify_route("/notes/Projects/"), "folder"); + assert_eq!(classify_route("/notes/Projects/anwesen/"), "folder"); + assert_eq!(classify_route("/"), "other"); + assert_eq!(classify_route("/favicon.ico"), "other"); + } + + #[test] + fn should_span_on_slow_or_5xx() { + let threshold = Duration::from_millis(500); + // Fast + success: metrics-only. + assert!(!should_span(Duration::from_millis(10), threshold, 200)); + assert!(!should_span(Duration::from_millis(499), threshold, 304)); + // At or over the threshold: span. + assert!(should_span(Duration::from_millis(500), threshold, 200)); + assert!(should_span(Duration::from_secs(305), threshold, 200)); + // 5xx spans even when fast. + assert!(should_span(Duration::from_millis(1), threshold, 500)); + assert!(should_span(Duration::from_millis(1), threshold, 503)); + // 4xx is a client error, not a server span trigger on its own. + assert!(!should_span(Duration::from_millis(1), threshold, 404)); + } + + #[test] + fn conditional_get_outcomes() { + assert_eq!(conditional_get(304, true), "not_modified"); + // A 304 with no header cannot happen in practice, but the status + // wins: it is still "not modified". + assert_eq!(conditional_get(304, false), "not_modified"); + assert_eq!(conditional_get(200, true), "revalidated"); + assert_eq!(conditional_get(200, false), "unconditional"); + assert_eq!(conditional_get(404, false), "unconditional"); + } +} From 275c6ecfa061531845c13eb00b4a8faf546f2221 Mon Sep 17 00:00:00 2001 From: Andreas Brenner Date: Fri, 24 Jul 2026 20:58:31 +0300 Subject: [PATCH 02/10] ANW-36 Watcher: drop index entries when note files are deleted --- src/app.rs | 19 ++- src/store.rs | 63 +++++++++- src/vault.rs | 13 +- src/watcher.rs | 335 ++++++++++++++++++++++++++++++++++++++++++------- 4 files changed, 381 insertions(+), 49 deletions(-) diff --git a/src/app.rs b/src/app.rs index 17d193d..f3ee5fc 100644 --- a/src/app.rs +++ b/src/app.rs @@ -442,6 +442,14 @@ pub enum IndexWriterMessage { pub struct IndexBatch { pub upserts: Vec, pub deletes: Vec, + /// Directories whose indexed notes all drop before the upserts land. A + /// removed or renamed directory produces no per-file event, so the + /// prefix is the only handle on those notes. A directory that was + /// walked is listed here too: the index under that prefix has to match + /// the walk, not keep what an earlier directory of the same name left + /// behind [ANW-36]. + #[serde(default)] + pub delete_prefixes: Vec, } #[derive(Clone)] @@ -498,8 +506,15 @@ impl GenServer for IndexWriterState { } IndexWriterMessage::Batch(batch) => { let (u, d) = (batch.upserts.len(), batch.deletes.len()); - self.store.apply_batch(batch.upserts, &batch.deletes); - tracing::info!(upserts = u, deletes = d, "index_writer: batch applied"); + let dropped = + self.store + .apply_batch(batch.upserts, &batch.deletes, &batch.delete_prefixes); + tracing::info!( + upserts = u, + deletes = d, + dropped, + "index_writer: batch applied" + ); } IndexWriterMessage::Upsert(note) => { let path = note.path.clone(); diff --git a/src/store.rs b/src/store.rs index 7e63fb2..e4d58f6 100644 --- a/src/store.rs +++ b/src/store.rs @@ -40,19 +40,45 @@ impl NoteStore { } } - /// Apply one debounce-window's worth of changes. Mirrors the order in - /// [`crate::index::NoteIndex::apply_batch`]: deletes first, then upserts. + /// Apply one debounce-window's worth of changes: deletes first (paths, + /// then whole directories), then upserts. A "delete-then-upsert" + /// sequence on one path is therefore unambiguous, and a directory that + /// was removed and recreated inside one window keeps only what the walk + /// found. + /// + /// Each entry of `delete_prefixes` is a vault-relative directory; every + /// note under it drops [ANW-36]. Returns the number of notes dropped + /// that way. /// /// # Panics /// Panics if the inner `RwLock` has been poisoned. - pub fn apply_batch(&self, upserts: Vec, deletes: &[String]) { + pub fn apply_batch( + &self, + upserts: Vec, + deletes: &[String], + delete_prefixes: &[String], + ) -> usize { let mut guard = self.inner.write().expect("note_store: write lock poisoned"); for path in deletes { guard.remove(path); } + let mut dropped = 0; + for dir in delete_prefixes { + let prefix = format!("{}/", dir.trim_end_matches('/')); + let doomed: Vec = guard + .range(prefix.clone()..) + .take_while(|(p, _)| p.starts_with(&prefix)) + .map(|(p, _)| p.clone()) + .collect(); + dropped += doomed.len(); + for path in doomed { + guard.remove(&path); + } + } for note in upserts { guard.insert(note.path.clone(), note); } + dropped } /// # Panics @@ -143,13 +169,42 @@ mod tests { fn apply_batch_deletes_then_upserts() { let s = NoteStore::new(); s.replace(vec![note("a.md"), note("b.md")]); - s.apply_batch(vec![note("c.md")], &["a.md".to_string()]); + s.apply_batch(vec![note("c.md")], &["a.md".to_string()], &[]); assert_eq!(s.len(), 2); assert!(s.get("a.md").is_none()); assert!(s.get("b.md").is_some()); assert!(s.get("c.md").is_some()); } + #[test] + fn apply_batch_prefix_drops_the_whole_subtree() { + let s = NoteStore::new(); + s.replace(vec![ + note("Notes/a.md"), + note("Notes/deep/b.md"), + note("Notesy/c.md"), + note("Other/d.md"), + ]); + let dropped = s.apply_batch(vec![], &[], &["Notes".to_string()]); + assert_eq!(dropped, 2); + assert!(s.get("Notes/a.md").is_none()); + assert!(s.get("Notes/deep/b.md").is_none()); + // A sibling sharing the prefix as a string, but not as a directory. + assert!(s.get("Notesy/c.md").is_some()); + assert!(s.get("Other/d.md").is_some()); + } + + #[test] + fn apply_batch_prefix_delete_precedes_upserts() { + let s = NoteStore::new(); + s.replace(vec![note("Notes/gone.md")]); + // A directory removed and recreated inside one window: only what the + // walk found survives. + s.apply_batch(vec![note("Notes/fresh.md")], &[], &["Notes".to_string()]); + assert!(s.get("Notes/gone.md").is_none()); + assert!(s.get("Notes/fresh.md").is_some()); + } + #[test] fn upsert_replaces_by_path() { let s = NoteStore::new(); diff --git a/src/vault.rs b/src/vault.rs index d78802a..35aec07 100644 --- a/src/vault.rs +++ b/src/vault.rs @@ -154,12 +154,23 @@ pub enum ScanWarningKind { /// Walk the vault and return every readable Markdown note alongside any /// per-file issues. The walk never panics on a single broken file. +#[must_use] pub fn scan(vault_root: &Path) -> ScanResult { + scan_from(vault_root, vault_root) +} + +/// Walk `start` (a directory inside `vault_root`) and return every readable +/// Markdown note under it. Note paths stay relative to `vault_root`, so a +/// subtree result is directly comparable with a full [`scan`]. Used by the +/// watcher when a directory appears or is renamed into the vault [ANW-36]: +/// the native event names the directory, never its files. +#[must_use] +pub fn scan_from(vault_root: &Path, start: &Path) -> ScanResult { let mut notes = Vec::new(); let mut issues = Vec::new(); let mut warnings = Vec::new(); - let walker = WalkDir::new(vault_root) + let walker = WalkDir::new(start) .follow_links(false) .into_iter() // The root entry itself may have a dot-prefixed name (e.g., a diff --git a/src/watcher.rs b/src/watcher.rs index e197ed3..55c0620 100644 --- a/src/watcher.rs +++ b/src/watcher.rs @@ -28,10 +28,16 @@ use crate::vault; /// One path-scoped action derived from a native filesystem event. Always /// carries a vault-relative, forward-slash-normalized path string -- the /// same form [`vault::Note.path`] uses. +/// +/// The `*Tree` variants carry a directory instead of a note. Native events +/// name only the directory when one is created, removed, or renamed; the +/// files under it produce no events of their own [ANW-36]. #[derive(Debug, Clone, PartialEq, Eq)] pub enum WatchAction { Upsert(String), Delete(String), + UpsertTree(String), + DeleteTree(String), } /// One debouncer window's worth of coalesced changes. @@ -39,6 +45,10 @@ pub enum WatchAction { pub struct WatchBatch { pub upserts: Vec, pub deletes: Vec, + /// Directories to walk for notes to upsert. + pub upsert_trees: Vec, + /// Directories whose indexed notes are all gone. + pub delete_trees: Vec, } /// Classify one [`Event`] into zero or more [`WatchAction`]s. Dot-segments @@ -54,60 +64,104 @@ pub fn map_event(event: &Event, vault_root: &Path) -> Vec { let mut actions = Vec::new(); let action_kind = classify(event.kind); match action_kind { - Some(EventAction::Upsert) => { + Some(EventAction::Modify) => { + // Content and metadata events only ever name a file. for p in &event.paths { - if let Some(rel) = vault_relative(vault_root, p) { + if let Some(rel) = note_relative(vault_root, p) { actions.push(WatchAction::Upsert(rel)); } } } - Some(EventAction::Delete) => { + Some(EventAction::Appear) => { for p in &event.paths { - if let Some(rel) = vault_relative(vault_root, p) { - actions.push(WatchAction::Delete(rel)); - } + actions.extend(appear(vault_root, p)); + } + } + Some(EventAction::Vanish) => { + for p in &event.paths { + actions.extend(vanish(vault_root, p)); } } Some(EventAction::Rename) => { // Notify packs (from, to) in event.paths in that order. - if let Some(from) = event.paths.first() - && let Some(rel) = vault_relative(vault_root, from) - { - actions.push(WatchAction::Delete(rel)); + if let Some(from) = event.paths.first() { + actions.extend(vanish(vault_root, from)); } - if let Some(to) = event.paths.get(1) - && let Some(rel) = vault_relative(vault_root, to) - { - actions.push(WatchAction::Upsert(rel)); + if let Some(to) = event.paths.get(1) { + actions.extend(appear(vault_root, to)); } } + Some(EventAction::RenameUnpaired) => { + // FSEvents (macOS) cannot pair the two sides of a rename and + // reports `Modify(Name(Any))` for each side separately, so the + // direction has to come off the filesystem [ANW-36]. + for p in &event.paths { + if p.exists() { + actions.extend(appear(vault_root, p)); + } else { + actions.extend(vanish(vault_root, p)); + } + } + // `p.exists()` can only report the moment it is asked. A path + // that vanishes right after the probe is caught downstream: + // `build_index_batch` turns a not-found upsert into a delete. + } None => {} } actions } +/// A path that now exists: a note to read, or a directory to walk. The +/// filesystem answers which, so a non-note file (an attachment, an editor +/// temp file) costs nothing beyond the probe. +fn appear(vault_root: &Path, abs: &Path) -> Option { + if abs.is_dir() { + tree_relative(vault_root, abs).map(WatchAction::UpsertTree) + } else { + note_relative(vault_root, abs).map(WatchAction::Upsert) + } +} + +/// A path that is gone: a note to drop, or a directory whose notes are all +/// gone with it. The filesystem cannot be asked -- it no longer holds the +/// entry -- so the decision rests on the path's own shape. +fn vanish(vault_root: &Path, abs: &Path) -> Option { + if is_markdown(abs) { + note_relative(vault_root, abs).map(WatchAction::Delete) + } else { + tree_relative(vault_root, abs).map(WatchAction::DeleteTree) + } +} + #[derive(Debug, Clone, Copy, PartialEq, Eq)] enum EventAction { - Upsert, - Delete, + /// Existing file, new content. + Modify, + /// Path came into the vault. + Appear, + /// Path left the vault. + Vanish, + /// Both sides in one event, `(from, to)`. Rename, + /// One side of a rename, direction unknown. + RenameUnpaired, } fn classify(kind: EventKind) -> Option { match kind { - EventKind::Create(_) - | EventKind::Modify( - ModifyKind::Data(_) - | ModifyKind::Metadata(_) - | ModifyKind::Any - | ModifyKind::Name(RenameMode::To), - ) - | EventKind::Access(AccessKind::Close(AccessMode::Write)) => Some(EventAction::Upsert), + EventKind::Modify(ModifyKind::Data(_) | ModifyKind::Metadata(_) | ModifyKind::Any) + | EventKind::Access(AccessKind::Close(AccessMode::Write)) => Some(EventAction::Modify), + EventKind::Create(_) | EventKind::Modify(ModifyKind::Name(RenameMode::To)) => { + Some(EventAction::Appear) + } EventKind::Modify(ModifyKind::Name(RenameMode::From)) | EventKind::Remove(_) => { - Some(EventAction::Delete) + Some(EventAction::Vanish) } EventKind::Modify(ModifyKind::Name(RenameMode::Both)) => Some(EventAction::Rename), - // Access(non-close), Modify(Name(Any|Other)), Other, Any -> drop. + EventKind::Modify(ModifyKind::Name(RenameMode::Any | RenameMode::Other)) => { + Some(EventAction::RenameUnpaired) + } + // Access(non-close), Other, Any -> drop. _ => None, } } @@ -120,8 +174,10 @@ pub fn is_overflow(event: &Event) -> bool { } /// Collapse a sequence of [`WatchAction`]s into a single batch. The last -/// action per path wins (delete-then-upsert ends up as upsert, and so on). -/// The batch keeps deterministic order by sorting paths inside each list. +/// action per path wins (delete-then-upsert ends up as upsert, and so on); +/// notes and directories are tracked separately, since a directory action +/// covers paths a note action cannot name. The batch keeps deterministic +/// order by sorting paths inside each list. #[must_use] pub fn coalesce(actions: impl IntoIterator) -> WatchBatch { #[derive(Clone, Copy)] @@ -129,36 +185,64 @@ pub fn coalesce(actions: impl IntoIterator) -> WatchBatch { Upsert, Delete, } - let mut state: BTreeMap = BTreeMap::new(); + let mut notes: BTreeMap = BTreeMap::new(); + let mut trees: BTreeMap = BTreeMap::new(); for a in actions { match a { WatchAction::Upsert(p) => { - state.insert(p, Last::Upsert); + notes.insert(p, Last::Upsert); } WatchAction::Delete(p) => { - state.insert(p, Last::Delete); + notes.insert(p, Last::Delete); + } + WatchAction::UpsertTree(p) => { + trees.insert(p, Last::Upsert); + } + WatchAction::DeleteTree(p) => { + trees.insert(p, Last::Delete); } } } - let mut upserts = Vec::new(); - let mut deletes = Vec::new(); - for (path, last) in state { + let mut batch = WatchBatch::default(); + for (path, last) in notes { match last { - Last::Upsert => upserts.push(path), - Last::Delete => deletes.push(path), + Last::Upsert => batch.upserts.push(path), + Last::Delete => batch.deletes.push(path), } } - WatchBatch { upserts, deletes } + for (path, last) in trees { + match last { + Last::Upsert => batch.upsert_trees.push(path), + Last::Delete => batch.delete_trees.push(path), + } + } + batch +} + +fn is_markdown(path: &Path) -> bool { + path.extension().is_some_and(|e| e == "md") } /// Filter and normalize an absolute notify path. Returns the vault-relative /// forward-slash path if the entry is a `.md` file outside any dot-directory; /// returns `None` otherwise (so the caller drops the event). -fn vault_relative(vault_root: &Path, abs: &Path) -> Option { - let rel = abs.strip_prefix(vault_root).ok()?; - if rel.extension().is_none_or(|e| e != "md") { +fn note_relative(vault_root: &Path, abs: &Path) -> Option { + if !is_markdown(abs) { return None; } + relative(vault_root, abs) +} + +/// Same, for a directory: any path that is not a note. The vault root itself +/// relativizes to the empty string and is dropped -- a root-level event is a +/// vault-wide signal the rescan path handles, not a prefix to delete. +fn tree_relative(vault_root: &Path, abs: &Path) -> Option { + let rel = relative(vault_root, abs)?; + if rel.is_empty() { None } else { Some(rel) } +} + +fn relative(vault_root: &Path, abs: &Path) -> Option { + let rel = abs.strip_prefix(vault_root).ok()?; for component in rel.components() { let s = component.as_os_str().to_str()?; if s.starts_with('.') { @@ -226,7 +310,11 @@ pub async fn run_debouncer( ); } let batch = coalesce(actions); - if batch.upserts.is_empty() && batch.deletes.is_empty() { + if batch.upserts.is_empty() + && batch.deletes.is_empty() + && batch.upsert_trees.is_empty() + && batch.delete_trees.is_empty() + { continue; } let index_batch = build_index_batch(&vault_root, batch); @@ -239,10 +327,17 @@ pub async fn run_debouncer( fn build_index_batch(vault_root: &Path, batch: WatchBatch) -> IndexBatch { let mut upserts = Vec::with_capacity(batch.upserts.len()); + let mut deletes = batch.deletes; for rel in batch.upserts { let abs = absolute_path(vault_root, &rel); match vault::scan_one(vault_root, &abs) { Ok(note) => upserts.push(note), + // The file is gone by the time we read it. An event backend that + // coalesces create-and-remove into one upsert-shaped event would + // otherwise leave the entry in the index forever [ANW-36]. + Err(vault::ScanIssueKind::Io(e)) if e.kind() == std::io::ErrorKind::NotFound => { + deletes.push(rel); + } Err(kind) => { tracing::warn!( path = %abs.display(), @@ -252,9 +347,29 @@ fn build_index_batch(vault_root: &Path, batch: WatchBatch) -> IndexBatch { } } } + // A walked directory carries its own prefix delete: the index under that + // prefix must match what the walk found. Without it, a directory renamed + // out and another renamed in within one window coalesces to a bare + // `UpsertTree` -- the delete is lost and the old notes outlive their + // files [ANW-36]. + let mut delete_prefixes = batch.delete_trees; + delete_prefixes.extend(batch.upsert_trees.iter().cloned()); + for dir in &batch.upsert_trees { + let abs = absolute_path(vault_root, dir); + let result = vault::scan_from(vault_root, &abs); + for issue in &result.issues { + tracing::warn!( + path = %issue.path.display(), + error = %issue.kind, + "filesystem_watcher: subtree walk issue; skipping note" + ); + } + upserts.extend(result.notes); + } IndexBatch { upserts, - deletes: batch.deletes, + deletes, + delete_prefixes, } } @@ -393,6 +508,142 @@ mod tests { assert_eq!(batch.deletes, vec!["c.md".to_string()]); } + #[test] + fn coalesce_keeps_notes_and_trees_apart() { + let actions = vec![ + WatchAction::Upsert("Notes/a.md".into()), + WatchAction::DeleteTree("Notes".into()), + WatchAction::UpsertTree("Fresh".into()), + ]; + let batch = coalesce(actions); + assert_eq!(batch.upserts, vec!["Notes/a.md".to_string()]); + assert!(batch.deletes.is_empty()); + assert_eq!(batch.upsert_trees, vec!["Fresh".to_string()]); + assert_eq!(batch.delete_trees, vec!["Notes".to_string()]); + } + + #[test] + fn removed_directory_is_a_tree_delete() { + let e = ev(EventKind::Remove(RemoveKind::Folder), &["/v/Notes"]); + assert_eq!( + map_event(&e, &vault()), + vec![WatchAction::DeleteTree("Notes".into())] + ); + } + + #[test] + fn directory_renamed_away_is_a_tree_delete() { + let e = ev( + EventKind::Modify(ModifyKind::Name(RenameMode::From)), + &["/v/Notes"], + ); + assert_eq!( + map_event(&e, &vault()), + vec![WatchAction::DeleteTree("Notes".into())] + ); + } + + #[test] + fn vault_root_itself_is_not_a_tree_action() { + let e = ev(EventKind::Remove(RemoveKind::Folder), &["/v"]); + assert!(map_event(&e, &vault()).is_empty()); + } + + #[test] + fn removed_non_note_file_touches_no_note() { + // A vanished path with no `.md` suffix is treated as a directory; + // the prefix simply matches nothing in the store. + let e = ev(EventKind::Remove(RemoveKind::File), &["/v/image.png"]); + assert_eq!( + map_event(&e, &vault()), + vec![WatchAction::DeleteTree("image.png".into())] + ); + } + + #[test] + fn created_directory_is_a_tree_upsert() { + let root = tempfile::tempdir().unwrap(); + std::fs::create_dir(root.path().join("Notes")).unwrap(); + let e = ev(EventKind::Create(CreateKind::Folder), &[]).add_path(root.path().join("Notes")); + assert_eq!( + map_event(&e, root.path()), + vec![WatchAction::UpsertTree("Notes".into())] + ); + } + + #[test] + fn unpaired_rename_resolves_by_existence() { + // FSEvents (macOS) reports each side of a rename as + // `Modify(Name(Any))` with no way to pair them. + let root = tempfile::tempdir().unwrap(); + std::fs::write(root.path().join("here.md"), "x").unwrap(); + let kind = EventKind::Modify(ModifyKind::Name(RenameMode::Any)); + + let present = ev(kind, &[]).add_path(root.path().join("here.md")); + assert_eq!( + map_event(&present, root.path()), + vec![WatchAction::Upsert("here.md".into())] + ); + + let absent = ev(kind, &[]).add_path(root.path().join("gone.md")); + assert_eq!( + map_event(&absent, root.path()), + vec![WatchAction::Delete("gone.md".into())] + ); + } + + #[test] + fn upsert_of_a_vanished_file_becomes_a_delete() { + let root = tempfile::tempdir().unwrap(); + let batch = WatchBatch { + upserts: vec!["gone.md".to_string()], + ..WatchBatch::default() + }; + let index_batch = build_index_batch(root.path(), batch); + assert!(index_batch.upserts.is_empty()); + assert_eq!(index_batch.deletes, vec!["gone.md".to_string()]); + } + + #[test] + fn tree_upsert_walks_the_subtree() { + let root = tempfile::tempdir().unwrap(); + std::fs::create_dir_all(root.path().join("Notes/deep")).unwrap(); + std::fs::write(root.path().join("Notes/a.md"), "---\nk: 1\n---\nbody\n").unwrap(); + std::fs::write(root.path().join("Notes/deep/b.md"), "body\n").unwrap(); + std::fs::write(root.path().join("Notes/skip.txt"), "no\n").unwrap(); + std::fs::write(root.path().join("outside.md"), "no\n").unwrap(); + + let batch = WatchBatch { + upsert_trees: vec!["Notes".to_string()], + ..WatchBatch::default() + }; + let index_batch = build_index_batch(root.path(), batch); + let mut paths: Vec = index_batch.upserts.into_iter().map(|n| n.path).collect(); + paths.sort(); + assert_eq!(paths, vec!["Notes/a.md", "Notes/deep/b.md"]); + } + + #[test] + fn tree_upsert_carries_its_prefix_delete() { + // One directory renamed out and another renamed in within one window + // coalesces to a bare `UpsertTree`; the walk must still drop whatever + // the old directory left in the index [ANW-36]. + let root = tempfile::tempdir().unwrap(); + std::fs::create_dir_all(root.path().join("Notes")).unwrap(); + std::fs::write(root.path().join("Notes/new.md"), "body\n").unwrap(); + + let batch = coalesce([ + WatchAction::DeleteTree("Notes".to_string()), + WatchAction::UpsertTree("Notes".to_string()), + ]); + assert!(batch.delete_trees.is_empty()); + + let index_batch = build_index_batch(root.path(), batch); + assert_eq!(index_batch.delete_prefixes, vec!["Notes".to_string()]); + let paths: Vec = index_batch.upserts.into_iter().map(|n| n.path).collect(); + assert_eq!(paths, vec!["Notes/new.md"]); + } + #[test] fn overflow_event_returns_empty_actions() { // Caller dispatches rescan_now; map_event itself produces no per-path actions. From bbb052fdc7257c735040052b71ee205ad7a09ed4 Mon Sep 17 00:00:00 2001 From: Andreas Brenner Date: Fri, 24 Jul 2026 21:32:18 +0300 Subject: [PATCH 03/10] ANW-40 Watcher: emit both deletes for a vanished .md path A directory can be named *.md too, and a vanished path cannot be probed, so the suffix test alone stranded its notes in the index. Emit the note delete and the prefix delete together; the two key sets are disjoint. --- src/store.rs | 23 ++++++++++++++++++++++ src/watcher.rs | 52 +++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 66 insertions(+), 9 deletions(-) diff --git a/src/store.rs b/src/store.rs index e4d58f6..743ba7a 100644 --- a/src/store.rs +++ b/src/store.rs @@ -194,6 +194,29 @@ mod tests { assert!(s.get("Other/d.md").is_some()); } + #[test] + fn note_delete_and_prefix_delete_of_one_path_are_disjoint() { + // A vanished `*.md` path sends both, since it may have been a + // directory [ANW-40]. The note delete takes the key `Archive.md`, + // the prefix delete takes the keys under `Archive.md/`; neither + // reaches anything else. + let s = NoteStore::new(); + s.replace(vec![ + note("Archive.md"), + note("Archive.md/inner.md"), + note("Keep.md"), + ]); + let dropped = s.apply_batch( + vec![], + &["Archive.md".to_string()], + &["Archive.md".to_string()], + ); + assert_eq!(dropped, 1); + assert!(s.get("Archive.md").is_none()); + assert!(s.get("Archive.md/inner.md").is_none()); + assert!(s.get("Keep.md").is_some()); + } + #[test] fn apply_batch_prefix_delete_precedes_upserts() { let s = NoteStore::new(); diff --git a/src/watcher.rs b/src/watcher.rs index 55c0620..f004db0 100644 --- a/src/watcher.rs +++ b/src/watcher.rs @@ -124,13 +124,22 @@ fn appear(vault_root: &Path, abs: &Path) -> Option { /// A path that is gone: a note to drop, or a directory whose notes are all /// gone with it. The filesystem cannot be asked -- it no longer holds the -/// entry -- so the decision rests on the path's own shape. -fn vanish(vault_root: &Path, abs: &Path) -> Option { - if is_markdown(abs) { - note_relative(vault_root, abs).map(WatchAction::Delete) - } else { - tree_relative(vault_root, abs).map(WatchAction::DeleteTree) +/// entry -- so both are emitted and the index decides which one matches. +/// +/// A `.md` suffix does not prove the path was a file: a directory may carry +/// it too, and then the suffix test alone strands its notes in the index +/// [ANW-40]. The two key sets are disjoint -- the note delete removes the key +/// `dir`, the prefix delete removes keys under `dir/` -- so emitting both is +/// always safe. It costs one range scan per deleted note. +fn vanish(vault_root: &Path, abs: &Path) -> Vec { + let mut actions = Vec::new(); + if let Some(rel) = note_relative(vault_root, abs) { + actions.push(WatchAction::Delete(rel)); } + if let Some(rel) = tree_relative(vault_root, abs) { + actions.push(WatchAction::DeleteTree(rel)); + } + actions } #[derive(Debug, Clone, Copy, PartialEq, Eq)] @@ -454,7 +463,10 @@ mod tests { ); assert_eq!( map_event(&e, &vault()), - vec![WatchAction::Delete("a.md".into())] + vec![ + WatchAction::Delete("a.md".into()), + WatchAction::DeleteTree("a.md".into()) + ] ); } @@ -480,6 +492,7 @@ mod tests { map_event(&e, &vault()), vec![ WatchAction::Delete("a.md".into()), + WatchAction::DeleteTree("a.md".into()), WatchAction::Upsert("b.md".into()) ] ); @@ -490,7 +503,25 @@ mod tests { let e = ev(EventKind::Remove(RemoveKind::File), &["/v/a.md"]); assert_eq!( map_event(&e, &vault()), - vec![WatchAction::Delete("a.md".into())] + vec![ + WatchAction::Delete("a.md".into()), + WatchAction::DeleteTree("a.md".into()) + ] + ); + } + + #[test] + fn removed_md_directory_drops_the_notes_under_it() { + // A directory may be named `*.md` too. The vanished path cannot be + // probed, so the note delete and the prefix delete both go out and + // the index applies whichever matches [ANW-40]. + let e = ev(EventKind::Remove(RemoveKind::Folder), &["/v/Archive.md"]); + assert_eq!( + map_event(&e, &vault()), + vec![ + WatchAction::Delete("Archive.md".into()), + WatchAction::DeleteTree("Archive.md".into()) + ] ); } @@ -588,7 +619,10 @@ mod tests { let absent = ev(kind, &[]).add_path(root.path().join("gone.md")); assert_eq!( map_event(&absent, root.path()), - vec![WatchAction::Delete("gone.md".into())] + vec![ + WatchAction::Delete("gone.md".into()), + WatchAction::DeleteTree("gone.md".into()) + ] ); } From 134b1d44b3ee4725f8b483651b789b95f48df8c3 Mon Sep 17 00:00:00 2001 From: Andreas Brenner Date: Fri, 24 Jul 2026 21:41:58 +0300 Subject: [PATCH 04/10] ANW-39 Release: bump version to 0.2.0 --- Cargo.lock | 2 +- Cargo.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 854bfc5..3371c27 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -72,7 +72,7 @@ dependencies = [ [[package]] name = "anwesen" -version = "0.1.0" +version = "0.2.0" dependencies = [ "anyhow", "axum", diff --git a/Cargo.toml b/Cargo.toml index d2d3565..a20fc1d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "anwesen" description = "Read-only HTTP daemon over a markdown vault, querying YAML frontmatter." -version = "0.1.0" +version = "0.2.0" edition = "2024" rust-version = "1.95" license = "BSD-3-Clause" From 8894ea0c7bc2f108c4ed19a393f47497a336851c Mon Sep 17 00:00:00 2001 From: Andreas Brenner Date: Fri, 24 Jul 2026 23:41:33 +0300 Subject: [PATCH 05/10] ANW-41 Docs: fix four broken rustdoc intra-doc links cargo doc --no-deps is warning-free. No behaviour change. --- src/doctor.rs | 2 +- src/query.rs | 2 +- src/watcher.rs | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/doctor.rs b/src/doctor.rs index 58f3e8d..f53f09f 100644 --- a/src/doctor.rs +++ b/src/doctor.rs @@ -46,7 +46,7 @@ pub struct DriftShape { /// `"bool"`, `"number"`, `"string"`, `"date"`, `"list"`, `"mapping"`. pub shape: &'static str, pub count: usize, - /// Up to [`DRIFT_SAMPLES_PER_SHAPE`] vault-relative paths exhibiting + /// Up to `DRIFT_SAMPLES_PER_SHAPE` vault-relative paths exhibiting /// this shape, in the order they were scanned. pub samples: Vec, } diff --git a/src/query.rs b/src/query.rs index bf301f7..786e80d 100644 --- a/src/query.rs +++ b/src/query.rs @@ -11,7 +11,7 @@ //! `__in` / `__all` are comma-separated; unknown operators are `400`. //! //! Predicates are evaluated by iterating the in-memory [`NoteStore`] and -//! applying each [`Predicate::matches`] in turn. At the documented scale +//! applying each [`Predicate`] in turn. At the documented scale //! (low-thousands-of-notes vaults) this is sub-millisecond; see //! [[ADR-009 Reverse ADR-002 In-Memory Evaluation No Tantivy]] for the //! call to keep evaluation in-memory rather than carrying a Tantivy index. diff --git a/src/watcher.rs b/src/watcher.rs index f004db0..0f7ccc0 100644 --- a/src/watcher.rs +++ b/src/watcher.rs @@ -4,7 +4,7 @@ //! [`notify::RecommendedWatcher`] over the vault root. Each native event is //! pushed into a Tokio channel; [`run_debouncer`] drains the channel, //! classifies events into [`WatchAction`]s, coalesces a 100 ms window's -//! worth into one [`Batch`], and casts the batch to the `index_writer` +//! worth into one [`WatchBatch`], and casts the batch to the `index_writer` //! named process for a single [`crate::store::NoteStore`] write. //! //! See [[ADR-003 Filesystem Change Tracking]] for the event model. @@ -27,7 +27,7 @@ use crate::vault; /// One path-scoped action derived from a native filesystem event. Always /// carries a vault-relative, forward-slash-normalized path string -- the -/// same form [`vault::Note.path`] uses. +/// same form [`vault::Note::path`] uses. /// /// The `*Tree` variants carry a directory instead of a note. Native events /// name only the directory when one is created, removed, or renamed; the From dc113b8249d42081afb205fffa4b759f9f02265a Mon Sep 17 00:00:00 2001 From: Andreas Brenner Date: Sun, 26 Jul 2026 23:44:51 +0300 Subject: [PATCH 06/10] ANW-42 Telemetry: take export config from OTEL_ environment variables only Delete the uptrace DSN parser and the {endpoint}/v1/* concatenation that produced the dead export, and build the OTLP exporters with no endpoint, headers, or protocol so the SDK reads OTEL_EXPORTER_OTLP_* itself. The SDK concatenates as naively as we did: measured against a local sink, a ?query base sends POST /?query/v1/metrics and a #fragment base sends POST /. So one check stays -- a query or fragment on OTEL_EXPORTER_OTLP_ENDPOINT fails at startup. Per-signal variables are used verbatim and need none. A protocol variable is the second startup check. The exporter picks its transport at build time and this binary ships OTLP/HTTP alone, so OTEL_EXPORTER_OTLP_PROTOCOL=grpc kept exporting over HTTP with nothing in the log -- the same silence this change removes. service.name stays a default rather than policy: an attribute set on the resource builder wins over the SDK detectors that read OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES, so anwesen supplies its own only for keys the environment leaves alone. Telemetry-off is our own check on the endpoint variables: with none set the exporter would still build and aim at the SDK default localhost:4318. --uptrace-dsn, --otlp-endpoint, and --otlp-header stay parsed but hidden, so a deployment upgrading with them set fails naming the OTEL_ replacement instead of going quiet. Assumed hidden clap stubs are the right migration shape; clap rejecting the flags as unknown would say nothing about the replacement. Flag if a plain unknown-argument error is wanted instead. Assumed rejecting http/json alongside grpc is right: neither has a transport in this build. Flag if a build with both features is wanted instead. --- README.md | 59 ++++- src/cli.rs | 63 +++-- src/http.rs | 23 +- src/main.rs | 22 +- src/telemetry.rs | 623 +++++++++++++++++++++++++++++++++-------------- 5 files changed, 563 insertions(+), 227 deletions(-) diff --git a/README.md b/README.md index d4e2fc0..a7bb236 100644 --- a/README.md +++ b/README.md @@ -56,8 +56,7 @@ anwesen merge --vault /path/to/vault --query 'tags=adr&__anw-order=title' > ADRs ``` anwesen serve --vault [--bind ] [--log-level ] - [--uptrace-dsn | --otlp-endpoint ] - [--otlp-header ]... [--otlp-slow-request-ms ] + [--otlp-slow-request-ms ] anwesen doctor --vault anwesen merge --vault --query anwesen version @@ -69,24 +68,62 @@ anwesen version | `--bind ` | `ANWESEN_BIND` | `127.0.0.1:8080` | Listen address for `serve`. | | `--log-level ` | `ANWESEN_LOG_LEVEL` | `info` | `error`, `warn`, `info`, `debug`, or `trace`. | | `--query ` | -- | _required for `merge`_ | A `/query` query string: frontmatter predicates plus `__anw-` controls. | -| `--uptrace-dsn ` | `ANWESEN_UPTRACE_DSN` | unset | uptrace DSN (`https://@api.uptrace.dev`). Excludes `--otlp-endpoint`. | -| `--otlp-endpoint ` | `ANWESEN_OTLP_ENDPOINT` | unset | OTLP/HTTP base URL. Excludes `--uptrace-dsn`. | -| `--otlp-header ` | `ANWESEN_OTLP_HEADERS` | none | Extra export header, repeatable. The env var takes a comma-separated list. | | `--otlp-slow-request-ms` | `ANWESEN_OTLP_SLOW_REQUEST_MS` | `500` | Requests at or over this duration, or answering 5xx, also export a span. | -Every flag has a matching `ANWESEN_` environment variable, except -`--otlp-header`, whose env var is the plural `ANWESEN_OTLP_HEADERS` because it -takes a list. CLI flags win over env vars. +Every flag has a matching `ANWESEN_` environment variable. CLI flags win +over env vars. -Telemetry is off unless `--uptrace-dsn` or `--otlp-endpoint` is set. With -neither, nothing is exported and no exporter is built. The four telemetry -flags apply to `serve` only. +`--bind` and `--otlp-slow-request-ms` apply to `serve` only. Where telemetry is +exported is configured entirely through the standard `OTEL_` variables below. - **`serve`** -- run the daemon: walk the vault, build the index, watch for changes, serve the API. - **`doctor`** -- walk the vault once and report what would stop clean ingestion: unreadable files, unparseable YAML, path collisions on the HTTP surface, and frontmatter type drift (the same key carrying incompatible types across notes). Read-only; non-zero exit if any issue is found. - **`merge`** -- one-shot local generation: walk the vault, evaluate `--query`, and write the merged markdown document to stdout. No server, no HTTP. See [Local generation](#local-generation). - **`version`** -- print version and exit. +## Telemetry + +anwesen exports OTLP metrics for every request, and a span for requests at or +over `--otlp-slow-request-ms` or answering a 5xx. Export is configured through +the standard OpenTelemetry environment variables, which the SDK reads directly: + +| Variable | Meaning | +| -------------------------------------- | ---------------------------------------------------------------- | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base URL. The SDK appends `/v1/metrics` and `/v1/traces`. | +| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Full metrics URL, used as given. Overrides the base for metrics. | +| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Full traces URL, used as given. Overrides the base for traces. | +| `OTEL_EXPORTER_OTLP_HEADERS` | Export headers, `key=value` comma-separated. | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf`, the default and the only value this build speaks. | +| `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES` | Override the `anwesen` service identity. | + +The per-signal `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` and +`OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` are read the same way. + +With none of the three endpoint variables set, telemetry is off: no exporter is +built and the request middleware is not installed. + +Two settings fail at startup rather than export nowhere in silence: + +- A query or a fragment on `OTEL_EXPORTER_OTLP_ENDPOINT`. The base URL must be + a base URL; the SDK appends the signal path after whatever it is given. +- A protocol other than `http/protobuf`. The binary ships the OTLP/HTTP + transport alone, so `grpc` would keep exporting over HTTP with nothing in the + log. Point the endpoint at the collector's HTTP port, not its gRPC one. + +uptrace: + +``` +OTEL_EXPORTER_OTLP_ENDPOINT=https://api.uptrace.dev +OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=https://TOKEN@api.uptrace.dev?grpc=4317 +``` + +Paste the DSN from Project Settings into the header verbatim, tail and all -- +it is a credential there, not an address. The endpoint is the host alone. + +Removed in 0.3.0: `--uptrace-dsn`, `--otlp-endpoint`, `--otlp-header` and their +`ANWESEN_` variables. Passing any of them fails at startup with the `OTEL_` +replacement to use. + ## HTTP API All endpoints are `GET` and return JSON unless noted. diff --git a/src/cli.rs b/src/cli.rs index 155ab5b..52e65e4 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -4,18 +4,22 @@ //! //! ```text //! anwesen serve --vault [--bind ] [--log-level ] -//! [--uptrace-dsn | --otlp-endpoint ] -//! [--otlp-header ]... [--otlp-slow-request-ms ] +//! [--otlp-slow-request-ms ] //! anwesen doctor --vault [--log-level ] //! anwesen merge --vault [--query ] [--log-level ] //! anwesen version //! ``` //! -//! `--bind` and the OTLP telemetry flags are `serve`-only ([ANW-37]); +//! `--bind` and `--otlp-slow-request-ms` are `serve`-only ([ANW-37]); //! `doctor` and `merge` do not bind a port; `version` takes no flags. Each //! flag has a matching `ANWESEN_` environment variable and CLI wins -//! over env per the manual. With no `--otlp-endpoint`/`--uptrace-dsn`, -//! telemetry is off and the server behaves exactly as without these flags. +//! over env per the manual. +//! +//! Telemetry export is configured through the standard `OTEL_EXPORTER_OTLP_*` +//! environment variables ([ANW-42](https://crvrs.youtrack.cloud/issue/ANW-42)). +//! With none of them set, telemetry is off and the server behaves as it did +//! before telemetry existed. The removed flags below are still parsed so an +//! upgrade fails loudly instead of dropping export config in silence. use std::net::SocketAddr; use std::path::PathBuf; @@ -56,25 +60,22 @@ pub struct ServeArgs { #[arg(long, env = "ANWESEN_LOG_LEVEL", default_value = "info")] pub log_level: LogLevel, - /// uptrace DSN shorthand (`https://@api.uptrace.dev`), parsed - /// into the OTLP endpoint plus an `uptrace-dsn` header. Mutually - /// exclusive with --otlp-endpoint. When this and --otlp-endpoint are - /// both unset, telemetry is fully off (ANW-37). - #[arg(long, env = "ANWESEN_UPTRACE_DSN")] + /// Removed (ANW-42): use `OTEL_EXPORTER_OTLP_ENDPOINT` plus + /// `OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=`. Still accepted so + /// startup fails with that message rather than exporting nowhere. + #[arg(long, env = "ANWESEN_UPTRACE_DSN", hide = true)] pub uptrace_dsn: Option, - /// Generic OTLP/HTTP endpoint base URL for telemetry export. The - /// per-signal path (`/v1/metrics`, `/v1/traces`) is appended by the - /// exporter. Mutually exclusive with --uptrace-dsn. - #[arg(long, env = "ANWESEN_OTLP_ENDPOINT")] + /// Removed (ANW-42): use `OTEL_EXPORTER_OTLP_ENDPOINT`. + #[arg(long, env = "ANWESEN_OTLP_ENDPOINT", hide = true)] pub otlp_endpoint: Option, - /// Extra OTLP export header as `key=value`, repeatable. On the env var - /// (`ANWESEN_OTLP_HEADERS`) pass a comma-separated `key=value` list. + /// Removed (ANW-42): use `OTEL_EXPORTER_OTLP_HEADERS`. #[arg( long = "otlp-header", env = "ANWESEN_OTLP_HEADERS", - value_delimiter = ',' + value_delimiter = ',', + hide = true )] pub otlp_headers: Vec, @@ -172,6 +173,34 @@ mod tests { } } + /// The removed telemetry flags still parse, hidden from `--help`. Clap + /// rejecting them as unknown would say nothing about the `OTEL_` + /// replacement; the migration error in `telemetry::TelemetryConfig` + /// needs the values to reach it (ANW-42). + #[test] + fn serve_still_parses_the_removed_telemetry_flags() { + let cli = parse(&[ + "serve", + "--vault", + "/tmp/v", + "--uptrace-dsn", + "https://tok@api.uptrace.dev", + "--otlp-endpoint", + "https://collector.example.com", + "--otlp-header", + "authorization=Bearer xyz", + ]) + .expect("parse"); + match cli.command { + Command::Serve(a) => { + assert!(a.uptrace_dsn.is_some()); + assert!(a.otlp_endpoint.is_some()); + assert_eq!(a.otlp_headers, vec!["authorization=Bearer xyz".to_string()]); + } + _ => panic!("expected serve"), + } + } + #[test] fn serve_rejects_malformed_bind_at_parse_time() { let err = parse(&["serve", "--vault", "/tmp/v", "--bind", "not-an-addr"]).unwrap_err(); diff --git a/src/http.rs b/src/http.rs index 48ec78e..52d4c0f 100644 --- a/src/http.rs +++ b/src/http.rs @@ -819,18 +819,23 @@ mod tests { } /// With telemetry installed, a normal request is answered byte-for-byte - /// as without it. The exporter points at an unreachable local port, so - /// export fails instantly in the background and never touches the - /// response path. + /// as without it. The test process sets no `OTEL_EXPORTER_OTLP_*` + /// variables, so the exporter aims at the SDK default and fails in the + /// background without ever touching the response path. #[tokio::test] async fn telemetry_layer_does_not_alter_responses() { - use crate::telemetry::{self, RawTelemetryArgs, TelemetryConfig}; + use crate::telemetry::{self, OtelEnv, RawTelemetryArgs, TelemetryConfig}; - let cfg = TelemetryConfig::resolve(RawTelemetryArgs { - otlp_endpoint: Some("http://127.0.0.1:9".into()), - slow_request_ms: 500, - ..Default::default() - }) + let cfg = TelemetryConfig::resolve( + &RawTelemetryArgs { + slow_request_ms: 500, + ..Default::default() + }, + OtelEnv { + endpoint: Some("http://127.0.0.1:9".into()), + ..OtelEnv::default() + }, + ) .unwrap() .expect("telemetry on"); let tel = Arc::new(telemetry::init(cfg).expect("telemetry init")); diff --git a/src/main.rs b/src/main.rs index f573e3f..4ac8e27 100644 --- a/src/main.rs +++ b/src/main.rs @@ -10,7 +10,7 @@ use std::sync::Arc; use anwesen::app::Anwesen; use anwesen::doctor; use anwesen::merge; -use anwesen::telemetry::{self, RawTelemetryArgs, TelemetryConfig}; +use anwesen::telemetry::{self, OtelEnv, RawTelemetryArgs, TelemetryConfig}; use anyhow::Result; use clap::Parser; use hydra::Application; @@ -25,14 +25,18 @@ fn main() -> Result<()> { match cli.command { Command::Serve(args) => { init_logging(args.log_level); - // Resolve telemetry config before the supervisor starts; an - // unset endpoint leaves it `None` (export off, behaves as today). - let telemetry = match TelemetryConfig::resolve(RawTelemetryArgs { - uptrace_dsn: args.uptrace_dsn, - otlp_endpoint: args.otlp_endpoint, - otlp_headers: args.otlp_headers, - slow_request_ms: args.otlp_slow_request_ms, - })? { + // Resolve telemetry config before the supervisor starts; no + // OTEL_EXPORTER_OTLP_* endpoint leaves it `None` (export off, + // no middleware). A removed flag is a startup error (ANW-42). + let telemetry = match TelemetryConfig::resolve( + &RawTelemetryArgs { + uptrace_dsn: args.uptrace_dsn, + otlp_endpoint: args.otlp_endpoint, + otlp_headers: args.otlp_headers, + slow_request_ms: args.otlp_slow_request_ms, + }, + OtelEnv::from_env(), + )? { Some(cfg) => Some(Arc::new(telemetry::init(cfg)?)), None => None, }; diff --git a/src/telemetry.rs b/src/telemetry.rs index a685b2d..15511c6 100644 --- a/src/telemetry.rs +++ b/src/telemetry.rs @@ -12,140 +12,288 @@ //! the propagated context. Every other request stays metrics-only, so the //! ~3.6k requests/min steady state does not drown the trace backend. //! -//! When no OTLP endpoint (or uptrace DSN) is configured, [`init`] returns +//! Transport configuration comes from the standard `OTEL_EXPORTER_OTLP_*` +//! environment variables only, read by the `OpenTelemetry` SDK itself +//! ([ANW-42](https://crvrs.youtrack.cloud/issue/ANW-42)). anwesen parses no +//! addresses and appends no per-signal paths. It checks two things at +//! startup, both cases the SDK would otherwise export nowhere in silence: +//! +//! - `OTEL_EXPORTER_OTLP_ENDPOINT` carries no query or fragment, because the +//! SDK's own concatenation mangles those (measured against a sink: a +//! `?tail` base sends `POST /?tail/v1/metrics`, a `#frag` base sends +//! `POST /`). +//! - No protocol variable asks for anything but `http/protobuf`, the only +//! transport this binary is built with. +//! +//! When no endpoint variable is set, [`TelemetryConfig::resolve`] returns //! `None`, the request middleware is not installed, and the server behaves //! exactly as it did before this module existed. External installs run //! unchanged. -//! -//! Config mirrors the gestell uptrace surface (see the gestell PDR-GES-136 -//! `[otel]` section): a `uptrace_dsn` shorthand, or a generic endpoint plus -//! headers. -use std::collections::HashMap; use std::time::{Duration, SystemTime}; -use anyhow::{Context as _, anyhow, bail}; +use anyhow::{Context as _, bail}; use axum::http::HeaderMap; use opentelemetry::KeyValue; use opentelemetry::metrics::{Counter, Histogram, MeterProvider as _}; use opentelemetry::propagation::{Extractor, TextMapPropagator}; use opentelemetry::trace::{Span, SpanKind, Tracer, TracerProvider as _}; -use opentelemetry_otlp::{ - MetricExporter, Protocol, SpanExporter, WithExportConfig, WithHttpConfig, -}; +use opentelemetry_otlp::{MetricExporter, SpanExporter}; use opentelemetry_sdk::Resource; use opentelemetry_sdk::metrics::{PeriodicReader, SdkMeterProvider}; use opentelemetry_sdk::propagation::TraceContextPropagator; use opentelemetry_sdk::trace::Sampler; use opentelemetry_sdk::trace::{SdkTracer, SdkTracerProvider}; -use opentelemetry_semantic_conventions::resource::SERVICE_VERSION; +use opentelemetry_semantic_conventions::resource::{SERVICE_NAME, SERVICE_VERSION}; -/// Raw telemetry options as parsed by clap on the `serve` command. Resolved -/// into an [`Option`] by [`TelemetryConfig::resolve`]. +/// The removed telemetry options, still parsed so their presence is an error +/// rather than a silent config drop on upgrade +/// ([ANW-42](https://crvrs.youtrack.cloud/issue/ANW-42)), plus the one +/// surviving option. Resolved into an [`Option`] by +/// [`TelemetryConfig::resolve`]. #[derive(Debug, Default)] pub struct RawTelemetryArgs { - /// `--uptrace-dsn` / `ANWESEN_UPTRACE_DSN`. + /// Removed `--uptrace-dsn` / `ANWESEN_UPTRACE_DSN`. pub uptrace_dsn: Option, - /// `--otlp-endpoint` / `ANWESEN_OTLP_ENDPOINT`. + /// Removed `--otlp-endpoint` / `ANWESEN_OTLP_ENDPOINT`. pub otlp_endpoint: Option, - /// `--otlp-header` / `ANWESEN_OTLP_HEADERS`, each `key=value`. + /// Removed `--otlp-header` / `ANWESEN_OTLP_HEADERS`. pub otlp_headers: Vec, - /// `--otlp-slow-request-ms` / `ANWESEN_OTLP_SLOW_REQUEST_MS`. + /// `--otlp-slow-request-ms` / `ANWESEN_OTLP_SLOW_REQUEST_MS`. Kept: it + /// decides when anwesen emits a span, not where the export goes, and no + /// standard variable covers it. pub slow_request_ms: u64, } -/// A resolved, telemetry-on configuration. Built only when an endpoint or a -/// DSN is present; absence is represented by `Ok(None)` from [`resolve`]. +/// The OTLP transport variables the SDK reads, captured once at startup so +/// the telemetry-on decision and the startup checks stay pure functions of +/// them. Values are the raw strings; anwesen does not parse them beyond the +/// checks in [`check_generic_endpoint`] and [`check_protocols`]. +#[derive(Debug, Default, Clone, PartialEq, Eq)] +pub struct OtelEnv { + /// `OTEL_EXPORTER_OTLP_ENDPOINT`: base URL, per-signal path appended by + /// the SDK. + pub endpoint: Option, + /// `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`: full URL, used verbatim. + pub metrics_endpoint: Option, + /// `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`: full URL, used verbatim. + pub traces_endpoint: Option, + /// `OTEL_EXPORTER_OTLP_PROTOCOL`. + pub protocol: Option, + /// `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`. + pub metrics_protocol: Option, + /// `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`. + pub traces_protocol: Option, +} + +impl OtelEnv { + /// Read the transport variables from the process environment. An empty or + /// whitespace-only value counts as unset: an empty endpoint would + /// otherwise turn telemetry on and export to the SDK's `localhost:4318` + /// default. + #[must_use] + pub fn from_env() -> Self { + let var = |name: &str| { + std::env::var(name) + .ok() + .map(|v| v.trim().to_string()) + .filter(|v| !v.is_empty()) + }; + Self { + endpoint: var("OTEL_EXPORTER_OTLP_ENDPOINT"), + metrics_endpoint: var("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"), + traces_endpoint: var("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"), + protocol: var("OTEL_EXPORTER_OTLP_PROTOCOL"), + metrics_protocol: var("OTEL_EXPORTER_OTLP_METRICS_PROTOCOL"), + traces_protocol: var("OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"), + } + } + + /// Whether any endpoint variable is set. No endpoint means telemetry off. + fn any_endpoint(&self) -> bool { + self.endpoint.is_some() || self.metrics_endpoint.is_some() || self.traces_endpoint.is_some() + } + + /// The endpoint to name in the startup log: the generic base when set, + /// otherwise whichever per-signal URL is. + fn describe(&self) -> &str { + self.endpoint + .as_deref() + .or(self.metrics_endpoint.as_deref()) + .or(self.traces_endpoint.as_deref()) + .unwrap_or("") + } +} + +/// A resolved, telemetry-on configuration. Built only when an endpoint +/// variable is set; absence is represented by `Ok(None)` from [`resolve`]. +/// It carries no transport settings: the exporters read those from the +/// environment themselves. /// /// [`resolve`]: TelemetryConfig::resolve #[derive(Debug, Clone, PartialEq, Eq)] pub struct TelemetryConfig { - /// OTLP/HTTP base URL. The exporter appends the per-signal path - /// (`/v1/metrics`, `/v1/traces`). - pub endpoint: String, - /// Export headers (for uptrace, the `uptrace-dsn` entry) as ordered - /// `(name, value)` pairs. - pub headers: Vec<(String, String)>, /// A request at or over this duration, or answering a 5xx, is recorded /// as a server span. pub slow_request: Duration, + /// The transport variables, kept for the startup log line only. + env: OtelEnv, } impl TelemetryConfig { - /// Resolve raw clap options into an optional config. + /// Resolve the surviving option plus the OTLP transport variables into an + /// optional config. /// - /// - Both `uptrace_dsn` and `otlp_endpoint` set is an error (they are - /// two ways to name the same endpoint). - /// - Neither set means telemetry is off: `Ok(None)`. - /// - A malformed `key=value` header or an unparseable DSN is an error, - /// surfaced at startup rather than silently dropping export. + /// - A removed flag or `ANWESEN_` variable is an error naming its `OTEL_` + /// replacement: a deployment exporting today must fail one restart + /// rather than go quiet. + /// - No endpoint variable set means telemetry is off: `Ok(None)`. + /// - A query or fragment on `OTEL_EXPORTER_OTLP_ENDPOINT` is an error. + /// - A protocol this binary cannot speak is an error. /// /// # Errors - /// Returns an error when the two endpoint sources conflict, a header is - /// not `key=value`, or the uptrace DSN cannot be parsed. - pub fn resolve(raw: RawTelemetryArgs) -> anyhow::Result> { - let slow_request = Duration::from_millis(raw.slow_request_ms); - let mut headers = parse_headers(&raw.otlp_headers)?; - - match (raw.uptrace_dsn, raw.otlp_endpoint) { - (Some(_), Some(_)) => { - bail!("--uptrace-dsn and --otlp-endpoint are mutually exclusive"); - } - (Some(dsn), None) => { - let (endpoint, dsn_header) = parse_uptrace_dsn(&dsn)?; - // The DSN header leads; any explicit --otlp-header follows. - headers.insert(0, dsn_header); - Ok(Some(Self { - endpoint, - headers, - slow_request, - })) - } - (None, Some(endpoint)) => Ok(Some(Self { - endpoint, - headers, - slow_request, - })), - (None, None) => Ok(None), + /// Returns an error when a removed option is present, when the generic + /// endpoint carries a query or a fragment, or when a protocol variable + /// asks for anything but `http/protobuf`. + pub fn resolve(raw: &RawTelemetryArgs, env: OtelEnv) -> anyhow::Result> { + check_removed(raw)?; + if !env.any_endpoint() { + return Ok(None); } + if let Some(endpoint) = &env.endpoint { + check_generic_endpoint(endpoint)?; + } + check_protocols(&env)?; + Ok(Some(Self { + slow_request: Duration::from_millis(raw.slow_request_ms), + env, + })) } } -/// Parse `key=value` header specs. Whitespace around key and value is -/// trimmed; an empty key or a spec with no `=` is an error. -fn parse_headers(specs: &[String]) -> anyhow::Result> { - let mut out = Vec::with_capacity(specs.len()); - for spec in specs { - let (k, v) = spec - .split_once('=') - .ok_or_else(|| anyhow!("OTLP header {spec:?} is not key=value"))?; - let k = k.trim(); - if k.is_empty() { - bail!("OTLP header {spec:?} has an empty key"); +/// Fail on any removed telemetry option, naming the `OTEL_` variable that +/// replaces it. Silence is the expensive failure here: an upgrade that drops +/// the export config would stop telemetry with nothing in the log. +fn check_removed(raw: &RawTelemetryArgs) -> anyhow::Result<()> { + let removed: [(&str, &str, bool); 3] = [ + ( + "--uptrace-dsn / ANWESEN_UPTRACE_DSN", + "OTEL_EXPORTER_OTLP_ENDPOINT=https://api.uptrace.dev plus \ + OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=", + raw.uptrace_dsn.is_some(), + ), + ( + "--otlp-endpoint / ANWESEN_OTLP_ENDPOINT", + "OTEL_EXPORTER_OTLP_ENDPOINT", + raw.otlp_endpoint.is_some(), + ), + ( + "--otlp-header / ANWESEN_OTLP_HEADERS", + "OTEL_EXPORTER_OTLP_HEADERS", + !raw.otlp_headers.is_empty(), + ), + ]; + for (option, replacement, present) in removed { + if present { + bail!("{option} was removed in anwesen 0.3.0; use {replacement} instead"); } - out.push((k.to_string(), v.trim().to_string())); } - Ok(out) + Ok(()) } -/// Parse an uptrace DSN (`https://@host[:port]`) into the OTLP -/// endpoint base URL and the `uptrace-dsn` header uptrace expects. The full -/// DSN is echoed as the header value per uptrace's ingest contract. -fn parse_uptrace_dsn(dsn: &str) -> anyhow::Result<(String, (String, String))> { - let dsn = dsn.trim(); - let (scheme, rest) = dsn - .split_once("://") - .context("uptrace DSN has no scheme (expected https://@host)")?; - // Host is whatever follows the credentials `@`; a DSN with no `@` is - // treated as endpoint-only (lenient, though real uptrace DSNs carry a - // token). - let host = rest.rsplit_once('@').map_or(rest, |(_, h)| h); - let host = host.trim_end_matches('/'); - if host.is_empty() { - bail!("uptrace DSN has no host"); +/// Reject a query or fragment on `OTEL_EXPORTER_OTLP_ENDPOINT`. The SDK +/// appends the per-signal path to this value textually, so a `?grpc=4317` +/// tail sends `POST /?grpc=4317/v1/metrics` and a `#frag` tail sends +/// `POST /` -- both dead exports, neither logged. Measured against a sink on +/// opentelemetry-otlp 0.32 ([ANW-42]). A path prefix composes correctly and +/// is left alone. +/// +/// [ANW-42]: https://crvrs.youtrack.cloud/issue/ANW-42 +fn check_generic_endpoint(endpoint: &str) -> anyhow::Result<()> { + if let Some(bad) = endpoint.find(['?', '#']) { + let tail = &endpoint[bad..]; + bail!( + "OTEL_EXPORTER_OTLP_ENDPOINT {endpoint:?} has a trailing {tail:?}; \ + the exporter would append the signal path after it and export nowhere. \ + Pass the base URL alone, and put an uptrace DSN in \ + OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=" + ); } - let endpoint = format!("{scheme}://{host}"); - Ok((endpoint, ("uptrace-dsn".to_string(), dsn.to_string()))) + Ok(()) +} + +/// The one OTLP protocol this binary speaks. `opentelemetry-otlp` is built +/// with the `http-proto` feature alone (Cargo.toml), so neither `grpc` nor +/// `http/json` has a transport behind it. +const SUPPORTED_PROTOCOL: &str = "http/protobuf"; + +/// Reject a protocol variable this binary cannot honor. The exporter builder +/// picks its transport at compile time, so `OTEL_EXPORTER_OTLP_PROTOCOL=grpc` +/// does not switch anything: the export keeps going out as HTTP protobuf, +/// with nothing in the log (measured, [ANW-42]). An operator who follows +/// uptrace's console to the gRPC port would get exactly the dead-silent +/// export this issue exists to remove, so it fails at startup instead. +/// +/// [ANW-42]: https://crvrs.youtrack.cloud/issue/ANW-42 +fn check_protocols(env: &OtelEnv) -> anyhow::Result<()> { + let vars = [ + ("OTEL_EXPORTER_OTLP_PROTOCOL", env.protocol.as_deref()), + ( + "OTEL_EXPORTER_OTLP_METRICS_PROTOCOL", + env.metrics_protocol.as_deref(), + ), + ( + "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL", + env.traces_protocol.as_deref(), + ), + ]; + for (name, value) in vars { + let Some(value) = value else { continue }; + if value != SUPPORTED_PROTOCOL { + bail!( + "{name}={value:?} is not supported; this build speaks \ + {SUPPORTED_PROTOCOL} only. Unset the variable, and point the \ + endpoint at the collector's HTTP port rather than its gRPC one" + ); + } + } + Ok(()) +} + +/// The resource attributes anwesen supplies as defaults, minus every key the +/// environment already sets. +/// +/// `service.name=anwesen` and the crate version are defaults, not policy: +/// contract point 6 of [ANW-42] keeps `OTEL_SERVICE_NAME` and +/// `OTEL_RESOURCE_ATTRIBUTES` working. Attaching them unconditionally blocks +/// the override, because an attribute set on the builder wins over the one +/// the SDK's own detectors read from those variables (measured by sie). +/// +/// Only key presence matters here; the values stay the SDK's to parse. +/// +/// [ANW-42]: https://crvrs.youtrack.cloud/issue/ANW-42 +fn default_resource_attrs( + service_name: Option<&str>, + resource_attributes: Option<&str>, +) -> Vec { + let from_attrs: Vec<&str> = resource_attributes + .unwrap_or_default() + .split(',') + .filter_map(|entry| entry.split_once('=')) + .map(|(key, _)| key.trim()) + .collect(); + let set_by_env = |key: &str| { + (key == SERVICE_NAME && service_name.is_some_and(|v| !v.trim().is_empty())) + || from_attrs.contains(&key) + }; + [ + (SERVICE_NAME, "anwesen"), + (SERVICE_VERSION, env!("CARGO_PKG_VERSION")), + ] + .into_iter() + .filter(|(key, _)| !set_by_env(key)) + .map(|(key, value)| KeyValue::new(key, value)) + .collect() } /// Semantic route bucket for the `http.route` label. Coarser than the axum @@ -332,28 +480,29 @@ struct TelemetryInner { impl TelemetryInner { fn new(config: TelemetryConfig) -> anyhow::Result { - let TelemetryConfig { - endpoint, - headers, - slow_request, - } = config; - // `.with_endpoint()` is used verbatim by the exporter (the `/v1/*` - // suffix is only auto-appended for the generic OTEL env var), so we - // append the per-signal path ourselves. - let endpoint = endpoint.trim_end_matches('/').to_string(); - let header_map: HashMap = headers.into_iter().collect(); + let TelemetryConfig { slow_request, env } = config; - let resource = Resource::builder() - .with_service_name("anwesen") - .with_attribute(KeyValue::new(SERVICE_VERSION, env!("CARGO_PKG_VERSION"))) - .build(); + // Service identity is a default only: a key OTEL_SERVICE_NAME or + // OTEL_RESOURCE_ATTRIBUTES already carries is left to the SDK's own + // detectors, because a builder attribute would win over them. + let mut resource = Resource::builder(); + for attr in default_resource_attrs( + std::env::var("OTEL_SERVICE_NAME").ok().as_deref(), + std::env::var("OTEL_RESOURCE_ATTRIBUTES").ok().as_deref(), + ) { + resource = resource.with_attribute(attr); + } + let resource = resource.build(); // -- metrics: thread-based periodic reader over an OTLP/HTTP exporter. + // No endpoint, headers, or protocol here: the SDK reads + // OTEL_EXPORTER_OTLP_* itself and composes the per-signal URL + // (ANW-42). `.with_http()` picks the only transport this binary is + // built with, http/protobuf -- the default, and what anwesen sent + // before. Any other OTEL_EXPORTER_OTLP_PROTOCOL value would be + // ignored here, so `check_protocols` rejects it at startup. let metric_exporter = MetricExporter::builder() .with_http() - .with_protocol(Protocol::HttpBinary) - .with_endpoint(format!("{endpoint}/v1/metrics")) - .with_headers(header_map.clone()) .build() .context("build OTLP metric exporter")?; let reader = PeriodicReader::builder(metric_exporter) @@ -386,9 +535,6 @@ impl TelemetryInner { // -- traces: thread-based batch processor over an OTLP/HTTP exporter. let span_exporter = SpanExporter::builder() .with_http() - .with_protocol(Protocol::HttpBinary) - .with_endpoint(format!("{endpoint}/v1/traces")) - .with_headers(header_map) .build() .context("build OTLP span exporter")?; let tracer_provider = SdkTracerProvider::builder() @@ -401,7 +547,7 @@ impl TelemetryInner { let tracer = tracer_provider.tracer("anwesen"); tracing::info!( - endpoint = %endpoint, + endpoint = %env.describe(), slow_request_ms = slow_request.as_millis(), "telemetry: OTLP export enabled" ); @@ -489,93 +635,208 @@ mod tests { RawTelemetryArgs::default() } - #[test] - fn resolve_off_when_nothing_set() { - let cfg = TelemetryConfig::resolve(raw()).unwrap(); - assert!(cfg.is_none(), "no endpoint/DSN means telemetry off"); + fn generic(endpoint: &str) -> OtelEnv { + OtelEnv { + endpoint: Some(endpoint.into()), + ..OtelEnv::default() + } } #[test] - fn resolve_generic_endpoint() { - let cfg = TelemetryConfig::resolve(RawTelemetryArgs { - otlp_endpoint: Some("https://collector.example.com".into()), - otlp_headers: vec!["authorization=Bearer xyz".into()], - slow_request_ms: 500, - ..raw() - }) - .unwrap() - .expect("telemetry on"); - assert_eq!(cfg.endpoint, "https://collector.example.com"); - assert_eq!( - cfg.headers, - vec![("authorization".to_string(), "Bearer xyz".to_string())] + fn resolve_off_when_no_endpoint_variable_is_set() { + let cfg = TelemetryConfig::resolve(&raw(), OtelEnv::default()).unwrap(); + assert!(cfg.is_none(), "no OTEL_ endpoint means telemetry off"); + } + + #[test] + fn resolve_on_for_each_endpoint_variable() { + let per_signal = |field: fn(&mut OtelEnv)| { + let mut env = OtelEnv::default(); + field(&mut env); + env + }; + for env in [ + generic("https://collector.example.com"), + per_signal(|e| { + e.metrics_endpoint = Some("https://collector.example.com/v1/metrics".into()); + }), + per_signal(|e| { + e.traces_endpoint = Some("https://collector.example.com/v1/traces".into()); + }), + ] { + let cfg = TelemetryConfig::resolve( + &RawTelemetryArgs { + slow_request_ms: 250, + ..raw() + }, + env.clone(), + ) + .unwrap_or_else(|e| panic!("{env:?}: {e}")) + .expect("telemetry on"); + assert_eq!(cfg.slow_request, Duration::from_millis(250)); + } + } + + /// The tails the SDK mangles: a query lands in the query string with the + /// signal path behind it, a fragment drops the signal path entirely. + #[test] + fn resolve_rejects_a_query_or_fragment_on_the_generic_endpoint() { + for endpoint in [ + "https://api.uptrace.dev?grpc=4317", + "https://api.uptrace.dev/?grpc=4317", + "https://api.uptrace.dev:4318?grpc=4317", + "https://api.uptrace.dev#frag", + ] { + let err = TelemetryConfig::resolve(&raw(), generic(endpoint)).unwrap_err(); + assert!(err.to_string().contains("trailing"), "{endpoint}: {err}"); + } + } + + /// A path prefix composes correctly (`/otlp` -> `POST /otlp/v1/metrics`), + /// and the per-signal variables are used verbatim, tail and all. + #[test] + fn resolve_accepts_a_path_prefix_and_per_signal_tails() { + for env in [ + generic("https://collector.example.com/otlp"), + generic("https://collector.example.com/"), + OtelEnv { + metrics_endpoint: Some("https://api.uptrace.dev/v1/metrics?grpc=4317".into()), + ..OtelEnv::default() + }, + ] { + TelemetryConfig::resolve(&raw(), env.clone()) + .unwrap_or_else(|e| panic!("{env:?}: {e}")) + .expect("telemetry on"); + } + } + + /// `.with_http()` fixes the transport at compile time, so a protocol this + /// build cannot speak is a dead export with nothing in the log. + #[test] + fn resolve_rejects_a_protocol_this_build_cannot_speak() { + let with_protocol = |field: fn(&mut OtelEnv)| { + let mut env = generic("https://collector.example.com"); + field(&mut env); + env + }; + for env in [ + with_protocol(|e| e.protocol = Some("grpc".into())), + with_protocol(|e| e.protocol = Some("http/json".into())), + with_protocol(|e| e.metrics_protocol = Some("grpc".into())), + with_protocol(|e| e.traces_protocol = Some("grpc".into())), + ] { + let err = TelemetryConfig::resolve(&raw(), env.clone()) + .unwrap_err() + .to_string(); + assert!(err.contains("http/protobuf"), "{env:?}: {err}"); + } + } + + /// The default protocol is the one this build speaks, so naming it + /// explicitly is not an error. + #[test] + fn resolve_accepts_the_supported_protocol_spelled_out() { + let env = OtelEnv { + protocol: Some("http/protobuf".into()), + metrics_protocol: Some("http/protobuf".into()), + ..generic("https://collector.example.com") + }; + TelemetryConfig::resolve(&raw(), env) + .unwrap() + .expect("telemetry on"); + } + + /// Contract point 6: `service.name` stays anwesen's default only while + /// the environment supplies none. A builder attribute wins over the SDK's + /// detectors, so the default has to step aside for the override to work. + #[test] + fn service_identity_defaults_step_aside_for_the_environment() { + let keys = |attrs: &[KeyValue]| { + attrs + .iter() + .map(|kv| kv.key.as_str().to_string()) + .collect::>() + }; + + let plain = default_resource_attrs(None, None); + assert_eq!(keys(&plain), [SERVICE_NAME, SERVICE_VERSION]); + + let named = default_resource_attrs(Some("svcname-override"), None); + assert_eq!(keys(&named), [SERVICE_VERSION]); + + let attrs = default_resource_attrs( + None, + Some("deployment.environment=prod,service.name=attrs-override"), ); - assert_eq!(cfg.slow_request, Duration::from_millis(500)); + assert_eq!(keys(&attrs), [SERVICE_VERSION]); + + let versioned = default_resource_attrs(None, Some("service.version=9.9.9")); + assert_eq!(keys(&versioned), [SERVICE_NAME]); + + // An empty OTEL_SERVICE_NAME supplies nothing; the SDK ignores it too. + let empty = default_resource_attrs(Some(" "), None); + assert_eq!(keys(&empty), [SERVICE_NAME, SERVICE_VERSION]); } #[test] - fn resolve_uptrace_dsn_splits_endpoint_and_header() { - let cfg = TelemetryConfig::resolve(RawTelemetryArgs { - uptrace_dsn: Some("https://SECRET_TOKEN@api.uptrace.dev".into()), - slow_request_ms: 250, - ..raw() - }) - .unwrap() - .expect("telemetry on"); - assert_eq!(cfg.endpoint, "https://api.uptrace.dev"); - assert_eq!( - cfg.headers, - vec![( - "uptrace-dsn".to_string(), - "https://SECRET_TOKEN@api.uptrace.dev".to_string() - )] - ); - assert_eq!(cfg.slow_request, Duration::from_millis(250)); + fn resolve_rejects_the_removed_uptrace_dsn() { + let err = TelemetryConfig::resolve( + &RawTelemetryArgs { + uptrace_dsn: Some("https://tok@api.uptrace.dev".into()), + ..raw() + }, + OtelEnv::default(), + ) + .unwrap_err() + .to_string(); + assert!(err.contains("--uptrace-dsn"), "{err}"); + assert!(err.contains("OTEL_EXPORTER_OTLP_HEADERS"), "{err}"); } #[test] - fn resolve_dsn_header_leads_explicit_headers() { - let cfg = TelemetryConfig::resolve(RawTelemetryArgs { - uptrace_dsn: Some("https://tok@api.uptrace.dev".into()), - otlp_headers: vec!["x-extra=1".into()], - ..raw() - }) - .unwrap() - .expect("telemetry on"); - assert_eq!(cfg.headers[0].0, "uptrace-dsn"); - assert_eq!(cfg.headers[1], ("x-extra".to_string(), "1".to_string())); + fn resolve_rejects_the_removed_otlp_endpoint() { + let err = TelemetryConfig::resolve( + &RawTelemetryArgs { + otlp_endpoint: Some("https://collector.example.com".into()), + ..raw() + }, + OtelEnv::default(), + ) + .unwrap_err() + .to_string(); + assert!(err.contains("--otlp-endpoint"), "{err}"); + assert!(err.contains("OTEL_EXPORTER_OTLP_ENDPOINT"), "{err}"); } #[test] - fn resolve_rejects_both_endpoint_sources() { - let err = TelemetryConfig::resolve(RawTelemetryArgs { - uptrace_dsn: Some("https://tok@api.uptrace.dev".into()), - otlp_endpoint: Some("https://collector.example.com".into()), - ..raw() - }) + fn resolve_rejects_the_removed_otlp_header() { + let err = TelemetryConfig::resolve( + &RawTelemetryArgs { + otlp_headers: vec!["authorization=Bearer xyz".into()], + ..raw() + }, + OtelEnv::default(), + ) + .unwrap_err() + .to_string(); + assert!(err.contains("--otlp-header"), "{err}"); + assert!(err.contains("OTEL_EXPORTER_OTLP_HEADERS"), "{err}"); + } + + /// A removed option fails even with a correct `OTEL_` endpoint alongside + /// it: the operator's intent is in the flag, and half-applied config is + /// the silent failure this issue removes. + #[test] + fn resolve_rejects_a_removed_option_alongside_a_good_endpoint() { + let err = TelemetryConfig::resolve( + &RawTelemetryArgs { + uptrace_dsn: Some("https://tok@api.uptrace.dev".into()), + ..raw() + }, + generic("https://api.uptrace.dev"), + ) .unwrap_err(); - assert!(err.to_string().contains("mutually exclusive")); - } - - #[test] - fn resolve_rejects_malformed_header() { - let err = TelemetryConfig::resolve(RawTelemetryArgs { - otlp_endpoint: Some("https://collector.example.com".into()), - otlp_headers: vec!["no-equals-sign".into()], - ..raw() - }) - .unwrap_err(); - assert!(err.to_string().contains("key=value")); - } - - #[test] - fn resolve_rejects_dsn_without_scheme() { - let err = TelemetryConfig::resolve(RawTelemetryArgs { - uptrace_dsn: Some("tok@api.uptrace.dev".into()), - ..raw() - }) - .unwrap_err(); - assert!(err.to_string().contains("scheme")); + assert!(err.to_string().contains("removed"), "{err}"); } #[test] From d6261bd5f978efca75d2469b89d48b61907820be Mon Sep 17 00:00:00 2001 From: Andreas Brenner Date: Mon, 27 Jul 2026 00:21:23 +0300 Subject: [PATCH 07/10] ANW-44 Release: bump version to 0.3.0 --- Cargo.lock | 2 +- Cargo.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 3371c27..ac93aba 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -72,7 +72,7 @@ dependencies = [ [[package]] name = "anwesen" -version = "0.2.0" +version = "0.3.0" dependencies = [ "anyhow", "axum", diff --git a/Cargo.toml b/Cargo.toml index a20fc1d..57c7492 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "anwesen" description = "Read-only HTTP daemon over a markdown vault, querying YAML frontmatter." -version = "0.2.0" +version = "0.3.0" edition = "2024" rust-version = "1.95" license = "BSD-3-Clause" From 30bca24b5ccdfc57293780389b524d9e2a5f0304 Mon Sep 17 00:00:00 2001 From: Andreas Brenner Date: Wed, 29 Jul 2026 22:22:12 +0300 Subject: [PATCH 08/10] ANW-45 Serve: exit nonzero when the supervisor tree fails to start Hydra's Application::run logs a start failure and returns normally, so serve exited 0 after the tree never came up. systemd read that as a clean start and Restart=on-failure never retried; anwesen was unreachable on ap for 12 hours with NRestarts=0. Anwesen carries a started flag that start() sets once the supervisor is up, and main exits 1 when it is still false after run() returns. Assumed the flag is the only seam available: run() consumes self and returns (), so the Err is not observable at the call site. Flag if a newer hydra exposes the result. --- src/app.rs | 13 +++++++++++-- src/main.rs | 13 ++++++++++++- tests/serve_start_failure.rs | 33 +++++++++++++++++++++++++++++++++ 3 files changed, 56 insertions(+), 3 deletions(-) create mode 100644 tests/serve_start_failure.rs diff --git a/src/app.rs b/src/app.rs index f3ee5fc..cc4bcf6 100644 --- a/src/app.rs +++ b/src/app.rs @@ -121,6 +121,12 @@ pub struct Anwesen { /// Request-level telemetry handle ([ANW-37]). `None` disables export and /// the request middleware entirely. pub telemetry: Option>, + /// Set once the supervisor tree is up. Hydra's `Application::run` logs a + /// start failure and returns normally, so `serve` cannot tell a clean + /// shutdown from a tree that never came up. `main` reads this after `run` + /// and exits nonzero when it is still false, which is what lets systemd + /// retry ([ANW-45](https://crvrs.youtrack.cloud/issue/ANW-45)). + pub started: Arc, } impl Anwesen { @@ -133,6 +139,7 @@ impl Anwesen { store: NoteStore::new(), health: HealthState::new(), telemetry, + started: Arc::new(AtomicBool::new(false)), } } } @@ -187,10 +194,12 @@ impl Application for Anwesen { .child_spec(), ]; - Supervisor::with_children(children) + let pid = Supervisor::with_children(children) .strategy(SupervisionStrategy::OneForOne) .start_link(SupervisorOptions::new().name("anwesen_root")) - .await + .await?; + self.started.store(true, Ordering::Release); + Ok(pid) } } diff --git a/src/main.rs b/src/main.rs index 4ac8e27..7d7a756 100644 --- a/src/main.rs +++ b/src/main.rs @@ -6,6 +6,7 @@ mod cli; use std::sync::Arc; +use std::sync::atomic::Ordering; use anwesen::app::Anwesen; use anwesen::doctor; @@ -46,12 +47,22 @@ fn main() -> Result<()> { telemetry = telemetry.is_some(), "anwesen serve: starting supervisor tree" ); + let app = Anwesen::new(args.vault, args.bind, telemetry.clone()); + let started = app.started.clone(); // Blocks until the supervisor exits (SIGTERM / SIGINT / crash). - Anwesen::new(args.vault, args.bind, telemetry.clone()).run(); + app.run(); // Flush and shut down exporters after the server loop returns. if let Some(telemetry) = telemetry { telemetry.shutdown(); } + // `run` returns normally whether the tree came up or never + // started, so a failed start would otherwise look like a clean + // exit and systemd's `Restart=on-failure` would not retry + // (ANW-45). Exit nonzero when the tree never came up. + if !started.load(Ordering::Acquire) { + tracing::error!("anwesen serve: supervisor tree failed to start"); + std::process::exit(1); + } } Command::Doctor(args) => { init_logging(args.log_level); diff --git a/tests/serve_start_failure.rs b/tests/serve_start_failure.rs new file mode 100644 index 0000000..4c01948 --- /dev/null +++ b/tests/serve_start_failure.rs @@ -0,0 +1,33 @@ +//! `anwesen serve` must exit nonzero when the supervisor tree fails to start +//! ([ANW-45](https://crvrs.youtrack.cloud/issue/ANW-45)). Hydra's +//! `Application::run` logs the failure and returns normally, so without an +//! explicit check the process exits 0 and systemd's `Restart=on-failure` +//! never retries -- the vault stayed unreachable for 12 hours on ap. +//! +//! The forced failure is a taken bind address: `http_server` binds eagerly in +//! its child spec, so the address-in-use error fails the whole start. + +use std::net::TcpListener; +use std::process::Command; + +#[test] +fn serve_exits_nonzero_when_the_tree_fails_to_start() { + let vault = tempfile::tempdir().expect("tempdir"); + // Hold the port for the lifetime of the child so its bind cannot succeed. + let held = TcpListener::bind("127.0.0.1:0").expect("bind probe port"); + let addr = held.local_addr().expect("probe addr"); + + let status = Command::new(env!("CARGO_BIN_EXE_anwesen")) + .arg("serve") + .arg("--vault") + .arg(vault.path()) + .arg("--bind") + .arg(addr.to_string()) + .status() + .expect("spawn anwesen serve"); + + assert!( + !status.success(), + "serve exited {status} after a failed supervisor start; systemd reads that as a clean exit" + ); +} From 6e07bff08aedc0342097c9d29f1f04379f2a14f6 Mon Sep 17 00:00:00 2001 From: Andreas Brenner Date: Fri, 31 Jul 2026 15:52:50 +0300 Subject: [PATCH 09/10] ANW-43 CLI: add a query subcommand writing the /query JSON offline The README claims the query engine is available offline, but only the merge half was: no subcommand produced the path / frontmatter / last_modified / etag / size projection that GET /query returns. `anwesen query` takes the same --vault and --query flags as merge and writes that document to stdout, compact, one line. src/merge.rs becomes src/oneshot.rs and holds both: one parse-and-load path, so the two subcommands cannot drift in grammar or in how strictly they read a vault. cli.rs shares one VaultQueryArgs between them for the same reason. rfc3339_z moves from http.rs to query.rs, next to the projection whose timestamp dialect it is. Assumed a trailing newline on stdout is wanted here even though merge writes none: the JSON body is one line for jq and shell pipelines, and the newline terminates it rather than joining the document. Flag if wrong. The hurl harness now compares `anwesen query` against GET /query on the fixture vault for four queries before running the suite, so a drift between the two surfaces fails CI. --- README.md | 38 ++++- src/cli.rs | 61 +++++++- src/http.rs | 10 +- src/lib.rs | 2 +- src/main.rs | 21 ++- src/merge.rs | 205 --------------------------- src/oneshot.rs | 354 ++++++++++++++++++++++++++++++++++++++++++++++ src/query.rs | 12 +- tests/run-hurl.sh | 14 ++ 9 files changed, 489 insertions(+), 228 deletions(-) delete mode 100644 src/merge.rs create mode 100644 src/oneshot.rs diff --git a/README.md b/README.md index a7bb236..f51daa3 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Anwesen answers three kinds of question over HTTP: The frontmatter index is built once at startup and kept current by watching the vault directory. The index lives in memory; a restart rebuilds it, and there is nothing on disk to corrupt or migrate. -The same query-and-merge engine also runs offline, with no server: `anwesen merge` walks a directory, evaluates a query, and writes the merged markdown to stdout (see [Local generation](#local-generation)). +The same query-and-merge engine also runs offline, with no server. `anwesen merge` walks a directory, evaluates a query, and writes the merged markdown to stdout; `anwesen query` writes the same JSON document `GET /query` returns (see [Local generation](#local-generation)). ## Quick start @@ -52,6 +52,12 @@ Build one file out of many notes, without starting the daemon: anwesen merge --vault /path/to/vault --query 'tags=adr&__anw-order=title' > ADRs.md ``` +Ask which notes match, and what their frontmatter holds, without starting the daemon: + +``` +anwesen query --vault /path/to/vault --query 'tags=adr' | jq -r '.results[].path' +``` + ## CLI ``` @@ -59,6 +65,7 @@ anwesen serve --vault [--bind ] [--log-level ] [--otlp-slow-request-ms ] anwesen doctor --vault anwesen merge --vault --query +anwesen query --vault --query anwesen version ``` @@ -67,7 +74,7 @@ anwesen version | `--vault ` | `ANWESEN_VAULT` | _required_ | Path to the vault root. | | `--bind ` | `ANWESEN_BIND` | `127.0.0.1:8080` | Listen address for `serve`. | | `--log-level ` | `ANWESEN_LOG_LEVEL` | `info` | `error`, `warn`, `info`, `debug`, or `trace`. | -| `--query ` | -- | _required for `merge`_ | A `/query` query string: frontmatter predicates plus `__anw-` controls. | +| `--query ` | `ANWESEN_QUERY` | empty (match all) | A `/query` query string: frontmatter predicates plus `__anw-` controls. `merge` and `query` only. | | `--otlp-slow-request-ms` | `ANWESEN_OTLP_SLOW_REQUEST_MS` | `500` | Requests at or over this duration, or answering 5xx, also export a span. | Every flag has a matching `ANWESEN_` environment variable. CLI flags win @@ -79,6 +86,7 @@ exported is configured entirely through the standard `OTEL_` variables below. - **`serve`** -- run the daemon: walk the vault, build the index, watch for changes, serve the API. - **`doctor`** -- walk the vault once and report what would stop clean ingestion: unreadable files, unparseable YAML, path collisions on the HTTP surface, and frontmatter type drift (the same key carrying incompatible types across notes). Read-only; non-zero exit if any issue is found. - **`merge`** -- one-shot local generation: walk the vault, evaluate `--query`, and write the merged markdown document to stdout. No server, no HTTP. See [Local generation](#local-generation). +- **`query`** -- the same one-shot walk, writing the JSON document `GET /query` returns: which notes match, and what their frontmatter, `last_modified`, `etag` and `size` hold. No server, no HTTP. See [Local generation](#local-generation). - **`version`** -- print version and exit. ## Telemetry @@ -173,7 +181,7 @@ ISO-8601 dates and RFC 3339 datetimes are coerced to typed dates at read time, s | `__anw-order=[:asc\|:desc]` | path order | Order fragments (merge mode only). | | `__anw-kind=` | off | Refuse a mixed merge unless every matched note shares one value for the key (merge mode only). | -By default `/query` returns metadata only; fetch bodies with `/notes/`. +By default `/query` returns metadata only; fetch bodies with `/notes/`. The same JSON document is available offline, without the daemon, via `anwesen query` (see [Local generation](#local-generation)). #### Markdown-merge mode @@ -201,7 +209,11 @@ Returns vault path, note count, last index/event timestamps, watcher state, an i ## Local generation -`anwesen merge` produces the markdown-merge document on the command line, with no server and no HTTP round-trip. It walks the vault, evaluates the query, and writes the merged document to stdout: +Two subcommands answer a query on the command line, with no server and no HTTP round-trip: `merge` writes the merged markdown document, `query` writes the JSON projection. Both take the same `--vault` and `--query` flags, both walk the vault once, and both run the engine the endpoint runs -- so the output matches what the daemon would have returned for the same vault and query. + +### `merge` + +`anwesen merge` walks the vault, evaluates the query, and writes the merged document to stdout: ``` anwesen merge --vault /path/to/vault --query 'tags=adr&__anw-order=title&__anw-kind=kind' @@ -211,6 +223,24 @@ The `--query` string is the exact `/query` grammar: frontmatter predicates plus This is the materialization path: build a `CLAUDE.md`, a skill bundle, or any single file assembled from many notes, driven from a script or a one-off shell. +### `query` + +`anwesen query` answers the other half: which notes match, and what their frontmatter holds. It writes the same JSON document `GET /query` returns -- `results`, `total`, `truncated`, with `path`, `frontmatter`, `last_modified`, `etag` and `size` per row -- on one line, ready for `jq`: + +``` +anwesen query --vault /path/to/vault --query 'kind=PDR&__anw-limit=1' +``` + +```json +{"results":[{"path":"Projects/PDR-001-intro.md","frontmatter":{"kind":"PDR","num":1,"title":"PDR-001 Intro"},"last_modified":"2026-05-14T17:05:08Z","etag":"\"f657eab5...\"","size":57}],"total":2,"truncated":true} +``` + +`total` counts the full match set; `truncated` says the cap cut it. + +Bodies are elided here as they are on the endpoint; `merge` is the way to get them offline. `__anw-order` and `__anw-kind` are merge-mode controls and do not affect this output. A malformed query or an unreadable vault exits non-zero with the reason on stderr; an empty match set is an empty `results` list and exit `0`. + +A script can therefore move between the daemon and the CLI without a second parser: same shape, same field names, same timestamp dialect. + ## Design notes - **In place, read-only.** Anwesen reads the same directory Obsidian writes to and never writes back. The vault stays editable in Obsidian with no coordination, and there is no write API by design. diff --git a/src/cli.rs b/src/cli.rs index 52e65e4..32bbced 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -7,9 +7,14 @@ //! [--otlp-slow-request-ms ] //! anwesen doctor --vault [--log-level ] //! anwesen merge --vault [--query ] [--log-level ] +//! anwesen query --vault [--query ] [--log-level ] //! anwesen version //! ``` //! +//! `merge` and `query` differ only in what they write -- the merged markdown +//! document or the `/query` JSON projection ([ANW-43]) -- so they share one +//! [`VaultQueryArgs`] flag set and cannot drift. +//! //! `--bind` and `--otlp-slow-request-ms` are `serve`-only ([ANW-37]); //! `doctor` and `merge` do not bind a port; `version` takes no flags. Each //! flag has a matching `ANWESEN_` environment variable and CLI wins @@ -41,7 +46,11 @@ pub enum Command { Doctor(DoctorArgs), /// Walk the vault once, evaluate the query, and write the merged markdown /// document to stdout. One-shot; no server. Read-only. - Merge(MergeArgs), + Merge(VaultQueryArgs), + /// Walk the vault once, evaluate the query, and write the same JSON + /// document `GET /query` returns to stdout. One-shot; no server. + /// Read-only. + Query(VaultQueryArgs), /// Print the version and exit. Version, } @@ -97,8 +106,9 @@ pub struct DoctorArgs { pub log_level: LogLevel, } +/// Flags shared by the two one-shot subcommands, `merge` and `query`. #[derive(Debug, clap::Args)] -pub struct MergeArgs { +pub struct VaultQueryArgs { /// Path to the vault root. #[arg(long, env = "ANWESEN_VAULT")] pub vault: PathBuf, @@ -106,12 +116,12 @@ pub struct MergeArgs { /// Query in the `/query` query-string grammar, for example /// `tags=anwesen&__anw-kind=skill&__anw-order=order`. The `__anw-kind` /// homogeneity guard and `__anw-order` fragment ordering ride inside this - /// string -- there are no separate flags. Empty merges every note under - /// the vault root. + /// string -- there are no separate flags. `__anw-kind` and `__anw-order` + /// apply to `merge` only. Empty matches every note under the vault root. #[arg(long, env = "ANWESEN_QUERY", default_value = "")] pub query: String, - /// Log verbosity. Logs go to stderr; the merged document goes to stdout. + /// Log verbosity. Logs go to stderr; the document goes to stdout. #[arg(long, env = "ANWESEN_LOG_LEVEL", default_value = "info")] pub log_level: LogLevel, } @@ -271,6 +281,47 @@ mod tests { assert_eq!(err.kind(), clap::error::ErrorKind::UnknownArgument); } + #[test] + fn query_takes_the_same_flags_as_merge() { + let cli = parse(&[ + "query", + "--vault", + "/tmp/v", + "--query", + "tags=anwesen&__anw-limit=5", + "--log-level", + "warn", + ]) + .expect("parse"); + match cli.command { + Command::Query(a) => { + assert_eq!(a.vault, PathBuf::from("/tmp/v")); + assert_eq!(a.query, "tags=anwesen&__anw-limit=5"); + assert!(matches!(a.log_level, LogLevel::Warn)); + } + _ => panic!("expected query"), + } + } + + #[test] + fn query_requires_vault_and_defaults_the_query() { + assert!(parse(&["query"]).is_err()); + match parse(&["query", "--vault", "/tmp/v"]) + .expect("parse") + .command + { + Command::Query(a) => assert_eq!(a.query, ""), + _ => panic!("expected query"), + } + } + + #[test] + fn query_rejects_bind() { + // --bind is serve-only; query does not listen. + let err = parse(&["query", "--vault", "/tmp/v", "--bind", "0.0.0.0:9000"]).unwrap_err(); + assert_eq!(err.kind(), clap::error::ErrorKind::UnknownArgument); + } + #[test] fn version_takes_no_flags() { assert!(matches!( diff --git a/src/http.rs b/src/http.rs index 52d4c0f..1d847a9 100644 --- a/src/http.rs +++ b/src/http.rs @@ -22,7 +22,7 @@ use axum::http::{HeaderMap, HeaderValue, StatusCode}; use axum::middleware::{Next, from_fn, from_fn_with_state}; use axum::response::{IntoResponse, Response}; use axum::routing::get; -use chrono::{DateTime, SecondsFormat, Utc}; +use chrono::{DateTime, Utc}; use http_body::Body as _; use hydra::Process; use serde::Serialize; @@ -32,17 +32,11 @@ use std::path::PathBuf; use crate::app::RestartCounters; use crate::health::HealthState; +use crate::query::rfc3339_z; use crate::store::NoteStore; use crate::telemetry::{self, Telemetry, TraceHeaders}; use crate::vault::{Note, frontmatter_to_json}; -/// Canonical RFC 3339 form with a `Z` suffix -- the shape the User Manual -/// example uses for `last_modified`. Centralized here so every HTTP -/// `last_modified` field stays in the same dialect. -fn rfc3339_z(dt: DateTime) -> String { - dt.to_rfc3339_opts(SecondsFormat::Secs, true) -} - /// Shared state injected into every handler. #[derive(Clone)] pub struct HttpState { diff --git a/src/lib.rs b/src/lib.rs index 59f1689..818b23e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -10,7 +10,7 @@ pub mod app; pub mod doctor; pub mod health; pub mod http; -pub mod merge; +pub mod oneshot; pub mod query; pub mod store; pub mod telemetry; diff --git a/src/main.rs b/src/main.rs index 7d7a756..05027d9 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,6 +1,6 @@ //! Anwesen: read-only HTTP daemon over a markdown vault. //! -//! This module wires the CLI to the `serve`, `doctor`, `merge`, and +//! This module wires the CLI to the `serve`, `doctor`, `merge`, `query`, and //! `version` subcommands. mod cli; @@ -10,7 +10,7 @@ use std::sync::atomic::Ordering; use anwesen::app::Anwesen; use anwesen::doctor; -use anwesen::merge; +use anwesen::oneshot; use anwesen::telemetry::{self, OtelEnv, RawTelemetryArgs, TelemetryConfig}; use anyhow::Result; use clap::Parser; @@ -74,13 +74,26 @@ fn main() -> Result<()> { } Command::Merge(args) => { init_logging(args.log_level); - match merge::run(&args.vault, &args.query) { + match oneshot::merge(&args.vault, &args.query) { // `print!`, not `println!`: the merged document is byte-stable // and byte-identical to the HTTP merge body, which carries no // trailing newline. An empty match set prints nothing, exit 0. Ok(doc) => print!("{doc}"), Err(e) => { - eprint!("{}", e.render()); + eprint!("{}", e.render("merge")); + std::process::exit(1); + } + } + } + Command::Query(args) => { + init_logging(args.log_level); + match oneshot::query_json(&args.vault, &args.query) { + // `println!` here, unlike `merge`: the JSON body carries no + // trailing newline either, but stdout is one document per + // line for the shells and `jq` pipelines this exists for. + Ok(doc) => println!("{doc}"), + Err(e) => { + eprint!("{}", e.render("query")); std::process::exit(1); } } diff --git a/src/merge.rs b/src/merge.rs deleted file mode 100644 index a9b6d2b..0000000 --- a/src/merge.rs +++ /dev/null @@ -1,205 +0,0 @@ -//! One-shot local markdown-merge for the `anwesen merge` subcommand ([ANW-27]). -//! -//! Walks a vault directory once (the same [`vault::scan`] as `doctor`), -//! evaluates the `--query` string, and assembles the merged markdown document -//! with [`query::execute_merge`] -- the very engine the HTTP `/query` merge -//! mode ([ANW-26]) uses. CLI and HTTP output are therefore byte-identical for -//! the same vault and query. No HTTP, no watcher, no persistent index. - -use std::fmt::Write as _; -use std::path::Path; - -use crate::query::{self, MergeError, QueryError}; -use crate::store::NoteStore; -use crate::vault::{self, ScanIssue}; - -/// Why a one-shot merge could not produce a document. -#[derive(Debug)] -pub enum MergeCliError { - /// The `--query` string did not parse. Same grammar, same message as the - /// HTTP `/query` `400`. - Query(QueryError), - /// One or more files could not be read, or their frontmatter did not - /// parse. Same hard-failure posture as `doctor`; soft warnings (e.g. a - /// non-mapping frontmatter root) are ignored, matching what `serve` - /// ingests. - Scan(Vec), - /// The `__anw-kind` homogeneity guard rejected the matched set. The - /// `String` is the same naming message the HTTP path returns as `400`, - /// surfaced here on stderr instead. - Kind(String), -} - -impl MergeCliError { - /// Render the error for stderr. One concern per line, deterministic so the - /// stderr surface is golden-testable. - #[must_use] - pub fn render(&self) -> String { - match self { - Self::Query(e) => format!("{e}\n"), - Self::Scan(issues) => { - let mut s = String::from("merge: cannot read vault\n"); - for issue in issues { - let _ = writeln!(s, " {}: {}", issue.path.display(), issue.kind); - } - s - } - Self::Kind(msg) => msg.clone(), - } - } -} - -/// Walk `vault_root`, evaluate `raw_query`, and return the merged document. -/// -/// On success the returned `String` is byte-identical to the HTTP merge body -/// for the same vault and query. An empty match set yields an empty string. -/// -/// # Errors -/// - [`MergeCliError::Query`] when `raw_query` is malformed; -/// - [`MergeCliError::Scan`] when the directory is unreadable or any file's -/// frontmatter fails to parse; -/// - [`MergeCliError::Kind`] when the `__anw-kind` homogeneity guard fails. -pub fn run(vault_root: &Path, raw_query: &str) -> Result { - let parsed = query::parse(raw_query).map_err(MergeCliError::Query)?; - - let scan = vault::scan(vault_root); - if !scan.issues.is_empty() { - return Err(MergeCliError::Scan(scan.issues)); - } - - // The merge engine reads from a NoteStore exactly as the HTTP path does; - // a one-shot `replace` is the whole "index" this subcommand needs. - let store = NoteStore::new(); - store.replace(scan.notes); - - query::execute_merge(&store, &parsed) - .map_err(|MergeError::KindGuard(msg)| MergeCliError::Kind(msg)) -} - -#[cfg(test)] -mod tests { - use super::*; - use std::fs; - use std::path::Path; - use tempfile::TempDir; - - fn write(root: &Path, rel: &str, body: &str) { - let p = root.join(rel); - if let Some(parent) = p.parent() { - fs::create_dir_all(parent).unwrap(); - } - fs::write(p, body).unwrap(); - } - - #[test] - fn merges_bodies_with_source_markers() { - let tmp = TempDir::new().unwrap(); - write(tmp.path(), "a.md", "---\nnum: 1\n---\nalpha\n"); - write(tmp.path(), "b.md", "---\nnum: 2\n---\nbeta\n"); - let out = run(tmp.path(), "").unwrap(); - // Body is frontmatter-stripped; fragments join with a blank line and - // there is no trailing newline -- byte-identical to the HTTP body. - assert_eq!( - out, - "\nalpha\n\n\n\nbeta\n" - ); - } - - #[test] - fn order_desc_then_path_tiebreak() { - let tmp = TempDir::new().unwrap(); - write(tmp.path(), "a.md", "---\nnum: 1\n---\nlow\n"); - write(tmp.path(), "b.md", "---\nnum: 3\n---\nhigh\n"); - write(tmp.path(), "c.md", "---\nnum: 2\n---\nmid\n"); - let out = run(tmp.path(), "__anw-order=num:desc").unwrap(); - let bodies: Vec<&str> = out - .lines() - .filter(|l| !l.starts_with("\nalpha\n\n\n\nbeta\n" + ); + } + + #[test] + fn order_desc_then_path_tiebreak() { + let tmp = TempDir::new().unwrap(); + write(tmp.path(), "a.md", "---\nnum: 1\n---\nlow\n"); + write(tmp.path(), "b.md", "---\nnum: 3\n---\nhigh\n"); + write(tmp.path(), "c.md", "---\nnum: 2\n---\nmid\n"); + let out = merge(tmp.path(), "__anw-order=num:desc").unwrap(); + let bodies: Vec<&str> = out + .lines() + .filter(|l| !l.starts_with("