From b9969e4f8a65cd656af1cbc6c8cae0cc6590273a Mon Sep 17 00:00:00 2001 From: Chris Wessels Date: Tue, 17 Nov 2026 15:19:18 +0000 Subject: [PATCH 1/2] feat: serve gateway version and indexer requirements at /version Indexers can't tell why the gateway stops sending them queries after an upgrade unless they know the gateway's minimum indexer-service and graph-node versions. Those minimums live only in the gateway's config. Add GET /version, which returns the gateway's crate version and the configured minimums as semver requirements: {"version": "27.7.1", "indexer_requirements": {"indexer_service": ">=1.0.0", "graph_node": ">=0.35.0"}} The route is public, like /ready and /blocklist. --- README.md | 17 +++++++ src/main.rs | 4 ++ src/version.rs | 135 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 156 insertions(+) create mode 100644 src/version.rs diff --git a/README.md b/README.md index 1c5eecc8..0b43cfad 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,23 @@ After the subgraph data is collected and organized, the gateway requests more in active indexer via the indexer-service. This includes software version information and, for each allocation, the indexing status (progress on chain indexed by subgraph deployment) and cost models. +Indexers running an indexer-service older than `min_indexer_version`, or a graph-node older than +`min_graph_node_version`, are not sent queries. The gateway serves these requirements, with its own +version, at `GET /version`: + +```json +{ + "version": "27.7.1", + "indexer_requirements": { + "indexer_service": ">=1.0.0", + "graph_node": ">=0.35.0" + } +} +``` + +An indexer whose graph-node doesn't report its version is not excluded by the graph-node +requirement. + The gateway may be configured to block public Proofs Of Indexing (POIs) that have been associated with bad query responses. In this case deployments with such POIs require an additional step in discovery where indexers are required to submit their public POI. If the indexer's POI has been diff --git a/src/main.rs b/src/main.rs index d7532d37..17fedfd0 100644 --- a/src/main.rs +++ b/src/main.rs @@ -20,6 +20,7 @@ mod receipts; mod reports; mod time; mod unattestable_errors; +mod version; use std::{ collections::HashSet, @@ -132,6 +133,8 @@ async fn main() { kafka_consumer.clone(), topic_name("gateway_blocklist"), ); + let version_info = + version::VersionInfo::new(&conf.min_indexer_version, &conf.min_graph_node_version); let mut network = network::service::spawn( http_client.clone(), network_subgraph_client, @@ -243,6 +246,7 @@ async fn main() { .route("/", routing::get(|| async { "Ready to roll!" })) // This path is required by NGINX ingress controller .route("/ready", routing::get(|| async { "Ready" })) + .route("/version", version::route(version_info)) .route( "/blocklist", routing::get(move || async move { axum::Json(blocklist.borrow().clone()) }), diff --git a/src/version.rs b/src/version.rs new file mode 100644 index 00000000..ea9e3ce2 --- /dev/null +++ b/src/version.rs @@ -0,0 +1,135 @@ +//! The public `/version` endpoint. +//! +//! It reports the gateway's own version and the minimum software versions an indexer must run to +//! receive queries from this gateway, so indexers and operators can check compatibility without +//! reading the gateway's configuration. + +use axum::{Json, routing::MethodRouter}; +use semver::{Comparator, Op, Version, VersionReq}; +use serde::Serialize; + +/// The `/version` response body. +#[derive(Clone, Debug, PartialEq, Eq, Serialize)] +pub struct VersionInfo { + /// The gateway's version, from its crate version. + pub version: Version, + /// Version requirements an indexer's software must meet to receive queries. + pub indexer_requirements: IndexerRequirements, +} + +/// Version requirements an indexer's software must meet to receive queries. +#[derive(Clone, Debug, PartialEq, Eq, Serialize)] +pub struct IndexerRequirements { + /// Requirement on the version indexer-service reports at its `/version` endpoint. + pub indexer_service: VersionReq, + /// Requirement on the version graph-node reports through indexer-service's `/status` + /// endpoint. An indexer whose graph-node doesn't report a version is not excluded. + pub graph_node: VersionReq, +} + +impl VersionInfo { + /// Describes this gateway, given the minimum versions it was configured with. + pub fn new(min_indexer_service_version: &Version, min_graph_node_version: &Version) -> Self { + Self { + version: env!("CARGO_PKG_VERSION") + .parse() + .expect("the crate version is valid semver"), + indexer_requirements: IndexerRequirements { + indexer_service: at_least(min_indexer_service_version), + graph_node: at_least(min_graph_node_version), + }, + } + } +} + +/// A route that answers `GET` with `info` as JSON. +pub fn route(info: VersionInfo) -> MethodRouter { + axum::routing::get(move || std::future::ready(Json(info.clone()))) +} + +/// The requirement `>=minimum`, which matches the gateway's `version < minimum` exclusion. +fn at_least(minimum: &Version) -> VersionReq { + VersionReq { + comparators: vec![Comparator { + op: Op::GreaterEq, + major: minimum.major, + minor: Some(minimum.minor), + patch: Some(minimum.patch), + pre: minimum.pre.clone(), + }], + } +} + +#[cfg(test)] +mod tests { + use axum::{ + Router, + body::Body, + http::{Method, Request, StatusCode}, + }; + use headers::{ContentType, HeaderMapExt}; + use http_body_util::BodyExt; + use serde_json::json; + use tower::ServiceExt; + + use super::*; + + fn version(s: &str) -> Version { + s.parse().unwrap() + } + + #[test] + fn reports_crate_version_and_minimums_as_requirements() { + let info = VersionInfo::new(&version("1.0.0-rc.2"), &version("0.35.1")); + + assert_eq!( + serde_json::to_value(&info).unwrap(), + json!({ + "version": env!("CARGO_PKG_VERSION"), + "indexer_requirements": { + "indexer_service": ">=1.0.0-rc.2", + "graph_node": ">=0.35.1", + }, + }) + ); + } + + #[test] + fn requirement_admits_exactly_the_versions_the_filter_admits() { + let minimum = version("1.2.3"); + let requirement = at_least(&minimum); + + for candidate in ["1.2.2", "1.2.3", "1.2.4", "1.3.0", "2.0.0", "0.9.9"] { + let candidate = version(candidate); + assert_eq!( + requirement.matches(&candidate), + candidate >= minimum, + "{candidate}" + ); + } + } + + #[tokio::test] + async fn get_version_returns_json() { + let info = VersionInfo::new(&version("1.0.0"), &version("0.35.0")); + let app = Router::new().route("/version", route(info.clone())); + let req = Request::builder() + .method(Method::GET) + .uri("/version") + .body(Body::empty()) + .unwrap(); + + let res = app.oneshot(req).await.expect("to be infallible"); + + assert_eq!(res.status(), StatusCode::OK); + assert_eq!( + res.headers().typed_get::(), + Some(ContentType::json()) + ); + let body = res.into_body().collect().await.unwrap().to_bytes(); + assert_eq!( + serde_json::from_slice::(&body).unwrap(), + serde_json::to_value(&info).unwrap() + ); + } +} From 8ac5323e0c5c87c62eb0a32d79ae4779cc8dc37f Mon Sep 17 00:00:00 2001 From: Chris Wessels Date: Wed, 18 Nov 2026 18:40:44 +0000 Subject: [PATCH 2/2] fix: serve minimum versions so prereleases match the version filter The served `>=minimum` requirements disagreed with VersionFilter for prereleases: the filter compares versions by semver precedence and accepts 1.3.0-rc.1 against a 1.2.3 minimum, but a `>=1.2.3` range excludes prereleases it doesn't name. Serve the minimum versions themselves, documented as compared by semver precedence, and cover prereleases in the equivalence test. --- README.md | 9 ++++--- src/version.rs | 72 +++++++++++++++++++++++++++----------------------- 2 files changed, 44 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 0b43cfad..dec0a7c2 100644 --- a/README.md +++ b/README.md @@ -39,14 +39,15 @@ version, at `GET /version`: { "version": "27.7.1", "indexer_requirements": { - "indexer_service": ">=1.0.0", - "graph_node": ">=0.35.0" + "min_indexer_service_version": "1.0.0", + "min_graph_node_version": "0.35.0" } } ``` -An indexer whose graph-node doesn't report its version is not excluded by the graph-node -requirement. +Versions are compared by semver precedence, so a prerelease of a later version meets a minimum +(`1.3.0-rc.1` meets `1.2.3`). An indexer whose graph-node doesn't report its version is not +excluded by the graph-node requirement. The gateway may be configured to block public Proofs Of Indexing (POIs) that have been associated with bad query responses. In this case deployments with such POIs require an additional step in diff --git a/src/version.rs b/src/version.rs index ea9e3ce2..0f9fb794 100644 --- a/src/version.rs +++ b/src/version.rs @@ -5,7 +5,7 @@ //! reading the gateway's configuration. use axum::{Json, routing::MethodRouter}; -use semver::{Comparator, Op, Version, VersionReq}; +use semver::Version; use serde::Serialize; /// The `/version` response body. @@ -18,13 +18,18 @@ pub struct VersionInfo { } /// Version requirements an indexer's software must meet to receive queries. +/// +/// Each is the lowest version that receives queries. Versions are compared by semver precedence, +/// as the gateway's version filter compares them, so a prerelease of a later version also meets +/// the minimum: `1.3.0-rc.1` meets `1.2.3`. A semver range such as `>=1.2.3` would not say this, +/// since ranges exclude prereleases they don't name. #[derive(Clone, Debug, PartialEq, Eq, Serialize)] pub struct IndexerRequirements { - /// Requirement on the version indexer-service reports at its `/version` endpoint. - pub indexer_service: VersionReq, - /// Requirement on the version graph-node reports through indexer-service's `/status` - /// endpoint. An indexer whose graph-node doesn't report a version is not excluded. - pub graph_node: VersionReq, + /// Minimum version indexer-service reports at its `/version` endpoint. + pub min_indexer_service_version: Version, + /// Minimum version graph-node reports through indexer-service's `/status` endpoint. An + /// indexer whose graph-node doesn't report a version is not excluded. + pub min_graph_node_version: Version, } impl VersionInfo { @@ -35,8 +40,8 @@ impl VersionInfo { .parse() .expect("the crate version is valid semver"), indexer_requirements: IndexerRequirements { - indexer_service: at_least(min_indexer_service_version), - graph_node: at_least(min_graph_node_version), + min_indexer_service_version: min_indexer_service_version.clone(), + min_graph_node_version: min_graph_node_version.clone(), }, } } @@ -47,19 +52,6 @@ pub fn route(info: VersionInfo) -> MethodRouter { axum::routing::get(move || std::future::ready(Json(info.clone()))) } -/// The requirement `>=minimum`, which matches the gateway's `version < minimum` exclusion. -fn at_least(minimum: &Version) -> VersionReq { - VersionReq { - comparators: vec![Comparator { - op: Op::GreaterEq, - major: minimum.major, - minor: Some(minimum.minor), - patch: Some(minimum.patch), - pre: minimum.pre.clone(), - }], - } -} - #[cfg(test)] mod tests { use axum::{ @@ -87,25 +79,39 @@ mod tests { json!({ "version": env!("CARGO_PKG_VERSION"), "indexer_requirements": { - "indexer_service": ">=1.0.0-rc.2", - "graph_node": ">=0.35.1", + "min_indexer_service_version": "1.0.0-rc.2", + "min_graph_node_version": "0.35.1", }, }) ); } #[test] - fn requirement_admits_exactly_the_versions_the_filter_admits() { + fn served_minimum_admits_exactly_the_versions_the_filter_admits() { let minimum = version("1.2.3"); - let requirement = at_least(&minimum); - - for candidate in ["1.2.2", "1.2.3", "1.2.4", "1.3.0", "2.0.0", "0.9.9"] { - let candidate = version(candidate); - assert_eq!( - requirement.matches(&candidate), - candidate >= minimum, - "{candidate}" - ); + let info = VersionInfo::new(&minimum, &minimum); + let served = serde_json::to_value(&info).unwrap(); + + for field in ["min_indexer_service_version", "min_graph_node_version"] { + let served = version(served["indexer_requirements"][field].as_str().unwrap()); + for candidate in [ + "1.2.2", + "1.2.3", + "1.2.4", + "1.3.0", + "2.0.0", + "0.9.9", + "1.2.3-rc.1", + "1.3.0-rc.1", + ] { + let candidate = version(candidate); + // Compared as clients are told to compare: by semver precedence. + assert_eq!( + candidate >= served, + candidate >= minimum, + "{field} {candidate}" + ); + } } }