feat: enable listing canisters via query call with subnet ID in the URL (#9977)

This PR adds a new public HTTP endpoint
`/api/v3/subnet/<effective_subnet_id>/query` on the replica that
supports call to the `list_canisters` endpoint of the management
canister (`aaaaa-aa`). It is specified in this
[PR](dfinity/portal#6224).

Note. PocketIC support will be added in a separate PR.

---------

Co-authored-by: Leo Eichhorn <99166915+eichhorl@users.noreply.github.com>

Author: mraszyk

rs/http_endpoints/public/src/call.rs

@@ -261,7 +261,7 @@ impl IngressValidator {
                     Err(HttpError {
                         status: StatusCode::BAD_REQUEST,
                         message: format!(
-                            "Specified CanisterId {} does not match effective canister id in URL {}",
+                            "Specified canister ID {} does not match effective canister ID in URL {}",
                             msg.canister_id(),
                             effective_canister_id
                         ),
@@ -273,7 +273,7 @@ impl IngressValidator {
                     Err(HttpError {
                         status: StatusCode::BAD_REQUEST,
                         message: format!(
-                            "Specified SubnetId {} does not match the subnet id of this node {}",
+                            "Specified subnet ID {} does not match the subnet ID of this node {}",
                             effective_subnet_id, subnet_id
                         ),
                     })?;

rs/http_endpoints/public/src/lib.rs

@@ -133,6 +133,7 @@ struct HttpHandler {
     subnet_call_v4_router: Router,
     query_v2_router: Router,
     query_v3_router: Router,
+    subnet_query_v3_router: Router,
     catchup_router: Router,
     dashboard_router: Router,
     status_router: Router,
@@ -339,6 +340,7 @@ pub fn start_server(
             ingress_verifier.clone(),
             nns_delegation_reader.clone(),
             query_execution_service.clone(),
+            subnet_id,
             version,
         )
         .with_health_status(health_status.clone())
@@ -348,6 +350,7 @@ pub fn start_server(
 
     let query_v2_router = query_router(query::Version::V2);
     let query_v3_router = query_router(query::Version::V3);
+    let subnet_query_v3_router = query_router(query::Version::SubnetV3);
 
     let read_state_router = |version, target| {
         ReadStateServiceBuilder::builder(
@@ -417,6 +420,7 @@ pub fn start_server(
         subnet_call_v4_router,
         query_v2_router,
         query_v3_router,
+        subnet_query_v3_router,
         status_router,
         catchup_router,
         dashboard_router,
@@ -609,6 +613,9 @@ fn make_router(
             .merge(http_handler.query_v3_router.layer(service_builder(
                 GlobalConcurrencyLimitLayer::new(config.max_query_concurrent_requests),
             )))
+            .merge(http_handler.subnet_query_v3_router.layer(service_builder(
+                GlobalConcurrencyLimitLayer::new(config.max_query_concurrent_requests),
+            )))
             .merge(
                 http_handler
                     .subnet_read_state_v2_router
@@ -816,6 +823,10 @@ pub(crate) mod tests {
                 QueryService::route(query::Version::V3),
                 axum::routing::post(dummy_cbor),
             ),
+            subnet_query_v3_router: Router::new().route(
+                QueryService::route(query::Version::SubnetV3),
+                axum::routing::post(dummy_cbor),
+            ),
             catchup_router: Router::new().route(
                 CatchUpPackageService::route(),
                 axum::routing::post(dummy_cbor),

rs/http_endpoints/public/src/query.rs

@@ -1,4 +1,4 @@
-//! Module that deals with requests to /api/v2/canister/.../query
+//! Module that deals with requests to /api/v{2,3}/canister/.../query and /api/v3/subnet/.../query
 
 use crate::{
     ReplicaHealthStatus,
@@ -29,7 +29,7 @@ use ic_logger::{ReplicaLogger, error};
 use ic_nns_delegation_manager::{CanisterRangesFilter, NNSDelegationReader};
 use ic_registry_client_helpers::crypto::root_of_trust::RegistryRootOfTrustProvider;
 use ic_types::{
-    CanisterId, NodeId,
+    CanisterId, NodeId, PrincipalId, SubnetId,
     crypto::threshold_sig::IcRootOfTrust,
     ingress::WasmResult,
     malicious_flags::MaliciousFlags,
@@ -53,6 +53,8 @@ pub enum Version {
     V2,
     // Endpoint with the NNS delegation using the tree format of the canister ranges.
     V3,
+    // Subnet endpoint with no canister ranges in the NNS delegation.
+    SubnetV3,
 }
 
 #[derive(Clone)]
@@ -67,6 +69,7 @@ pub struct QueryService {
     registry_client: Arc<dyn RegistryClient>,
     additional_root_of_trust: Option<IcRootOfTrust>,
     query_execution_service: Arc<Mutex<QueryExecutionService>>,
+    subnet_id: SubnetId,
     version: Version,
 }
 
@@ -82,6 +85,7 @@ pub struct QueryServiceBuilder {
     registry_client: Arc<dyn RegistryClient>,
     additional_root_of_trust: Option<IcRootOfTrust>,
     query_execution_service: QueryExecutionService,
+    subnet_id: SubnetId,
     version: Version,
 }
 
@@ -90,6 +94,7 @@ impl QueryService {
         match version {
             Version::V2 => "/api/v2/canister/{effective_canister_id}/query",
             Version::V3 => "/api/v3/canister/{effective_canister_id}/query",
+            Version::SubnetV3 => "/api/v3/subnet/{effective_subnet_id}/query",
         }
     }
 }
@@ -103,6 +108,7 @@ impl QueryServiceBuilder {
         ingress_verifier: Arc<dyn IngressSigVerifier>,
         nns_delegation_reader: NNSDelegationReader,
         query_execution_service: QueryExecutionService,
+        subnet_id: SubnetId,
         version: Version,
     ) -> Self {
         Self {
@@ -117,6 +123,7 @@ impl QueryServiceBuilder {
             registry_client,
             additional_root_of_trust: None,
             query_execution_service,
+            subnet_id,
             version,
         }
     }
@@ -162,6 +169,7 @@ impl QueryServiceBuilder {
             registry_client: self.registry_client,
             additional_root_of_trust: self.additional_root_of_trust,
             query_execution_service: Arc::new(Mutex::new(self.query_execution_service)),
+            subnet_id: self.subnet_id,
             version: self.version,
         };
         Router::new().route_service(
@@ -179,7 +187,7 @@ impl QueryServiceBuilder {
 }
 
 pub(crate) async fn query(
-    axum::extract::Path(effective_canister_id): axum::extract::Path<CanisterId>,
+    axum::extract::Path(id): axum::extract::Path<PrincipalId>,
     State(QueryService {
         log,
         node_id,
@@ -191,6 +199,7 @@ pub(crate) async fn query(
         nns_delegation_reader,
         additional_root_of_trust,
         query_execution_service,
+        subnet_id,
         version,
     }): State<QueryService>,
     WithTimeout(Cbor(request)): WithTimeout<Cbor<HttpRequestEnvelope<HttpQueryContent>>>,
@@ -217,12 +226,41 @@ pub(crate) async fn query(
         }
     };
     let canister_id = request.content().canister_id();
-    if canister_id != CanisterId::ic_00() && canister_id != effective_canister_id {
-        let status = StatusCode::BAD_REQUEST;
-        let text = format!(
-            "Specified CanisterId {canister_id} does not match effective canister id in URL {effective_canister_id}"
-        );
-        return (status, text).into_response();
+
+    // Validate effective destination.
+    match version {
+        Version::V2 | Version::V3 => {
+            let effective_canister_id = CanisterId::unchecked_from_principal(id);
+            if canister_id != CanisterId::ic_00() && canister_id != effective_canister_id {
+                let status = StatusCode::BAD_REQUEST;
+                let text = format!(
+                    "Specified canister ID {canister_id} does not match effective canister ID in URL {effective_canister_id}"
+                );
+                return (status, text).into_response();
+            }
+        }
+        Version::SubnetV3 => {
+            let effective_subnet_id = SubnetId::from(id);
+            if effective_subnet_id != subnet_id {
+                let status = StatusCode::BAD_REQUEST;
+                let text = format!(
+                    "Specified subnet ID {effective_subnet_id} does not match the subnet ID of this node {subnet_id}"
+                );
+                return (status, text).into_response();
+            }
+            if canister_id != CanisterId::ic_00()
+                || request.content().method_name != "list_canisters"
+            {
+                let status = StatusCode::BAD_REQUEST;
+                let text = format!(
+                    "Subnet query endpoint only accepts queries to the management canister ({}) 'list_canisters' method, got canister_id={} method_name='{}'",
+                    CanisterId::ic_00(),
+                    canister_id,
+                    request.content().method_name
+                );
+                return (status, text).into_response();
+            }
+        }
     }
 
     let root_of_trust_provider = if let Some(additional_root_of_trust) = additional_root_of_trust {
@@ -263,8 +301,12 @@ pub(crate) async fn query(
         Version::V2 => {
             nns_delegation_reader.get_delegation_with_metadata(CanisterRangesFilter::Flat)
         }
-        Version::V3 => nns_delegation_reader
-            .get_delegation_with_metadata(CanisterRangesFilter::Tree(effective_canister_id)),
+        Version::V3 => nns_delegation_reader.get_delegation_with_metadata(
+            CanisterRangesFilter::Tree(CanisterId::unchecked_from_principal(id)),
+        ),
+        Version::SubnetV3 => {
+            nns_delegation_reader.get_delegation_with_metadata(CanisterRangesFilter::None)
+        }
     };
     let query_execution_input = QueryExecutionInput {
         query: user_query.clone(),

rs/http_endpoints/public/tests/common/mod.rs

@@ -13,7 +13,7 @@ use ic_crypto_test_utils_crypto_returning_ok::CryptoReturningOk;
 use ic_crypto_tls_interfaces::TlsConfig;
 use ic_crypto_tls_interfaces_mocks::MockTlsConfig;
 use ic_crypto_tree_hash::{Digest, LabeledTree, MatchPatternPath, MixedHashTree, Witness};
-use ic_http_endpoints_public::start_server;
+use ic_http_endpoints_public::{query, start_server};
 use ic_interfaces::{
     consensus_pool::ConsensusPoolCache,
     execution_environment::{
@@ -48,7 +48,7 @@ use ic_replicated_state::{
 };
 use ic_test_utilities_types::ids::{node_test_id, subnet_test_id};
 use ic_types::{
-    CanisterId, CryptoHashOfPartialState, Height, RegistryVersion,
+    CanisterId, CryptoHashOfPartialState, Height, PrincipalId, RegistryVersion,
     artifact::UnvalidatedArtifactMutation,
     batch::RawQueryStats,
     consensus::certification::{Certification, CertificationContent},
@@ -117,6 +117,25 @@ impl UpdateEndpoint {
     }
 }
 
+pub async fn query_endpoint(version: query::Version, addr: SocketAddr) -> reqwest::Response {
+    match version {
+        query::Version::V2 | query::Version::V3 => {
+            ic_http_endpoints_test_agent::Query::new(
+                PrincipalId::default(),
+                PrincipalId::default(),
+                version,
+            )
+            .query(addr)
+            .await
+        }
+        query::Version::SubnetV3 => {
+            ic_http_endpoints_test_agent::Query::new_subnet(subnet_test_id(1).get())
+                .query(addr)
+                .await
+        }
+    }
+}
+
 fn setup_query_execution_mock() -> (QueryExecutionService, QueryExecutionHandle) {
     let (service, handle) = tower_test::mock::pair::<QueryExecutionInput, QueryExecutionResponse>();
 

rs/http_endpoints/public/tests/load_shed_test.rs

@@ -3,17 +3,17 @@ pub mod common;
 use crate::common::{
     HttpEndpointBuilder, MockIngressPoolThrottler, UpdateEndpoint, default_certified_state_reader,
     default_get_latest_state, default_read_certified_state, get_free_localhost_socket_addr,
+    query_endpoint,
 };
 use async_trait::async_trait;
 use axum::body::Body;
 use hyper::{Method, Request, StatusCode};
 use hyper_util::{client::legacy::Client, rt::TokioExecutor};
 use ic_config::http_handler::Config;
 use ic_crypto_tree_hash::{Label, Path};
-use ic_http_endpoints_public::query;
-use ic_http_endpoints_public::read_state;
+use ic_http_endpoints_public::{query, read_state};
 use ic_http_endpoints_test_agent::{
-    self, Call, CallSubnet, CanisterReadState, IngressMessage, Query, wait_for_status_healthy,
+    self, Call, CallSubnet, CanisterReadState, IngressMessage, wait_for_status_healthy,
 };
 use ic_test_utilities_types::ids::subnet_test_id;
 
@@ -35,7 +35,8 @@ use tokio::{runtime::Runtime, sync::Notify};
 /// we return 429.
 #[rstest]
 fn test_load_shedding_query(
-    #[values(query::Version::V2, query::Version::V3)] version: query::Version,
+    #[values(query::Version::V2, query::Version::V3, query::Version::SubnetV3)]
+    version: query::Version,
 ) {
     let rt = Runtime::new().unwrap();
     let addr = get_free_localhost_socket_addr();
@@ -58,9 +59,7 @@ fn test_load_shedding_query(
     let load_shedded_request = rt.spawn(async move {
         query_exec_running_clone.notified().await;
 
-        let response = Query::new(PrincipalId::default(), PrincipalId::default(), version)
-            .query(addr)
-            .await;
+        let response = query_endpoint(version, addr).await;
 
         load_shedder_returned_clone.notify_one();
 
@@ -82,9 +81,7 @@ fn test_load_shedding_query(
     rt.block_on(async {
         wait_for_status_healthy(&addr).await.unwrap();
 
-        let response = Query::new(PrincipalId::default(), PrincipalId::default(), version)
-            .query(addr)
-            .await;
+        let response = query_endpoint(version, addr).await;
 
         assert_eq!(
             StatusCode::OK,