API 1.0: Reachable but not importable items

[SimonSapin]

trafficstars

Some items are part of the public API even if they cannot imported. For example:

mod a {
    mod b {
        pub fn c() -> D { /*…*/ }
        pub struct D;
        impl D {
            pub fn e() { /*…*/ }
        }
    }
    pub use b::c;
}

External users can call a::c().e(), which means that the type D and its methods such a e are part of the public API even though D cannot be named (imported) directly. Usually we want to avoid this: either an item should be importable or it should not be part of the public API in any way.

Thanks to enabling the warn(unreachable_pub), we’ve already changed from pub to pub(crate) any item that is truly not part of the public API. The remaining pub items are indeed public in some way, but not necessarily importable. By temporarily making all modules public and diffing the output of ./scripts/public_items.sh we can find items that are involved in the public API but are not importable:

apollo_router::configuration::ConfigurationError
apollo_router::configuration::ListenAddr
apollo_router::executable::StartExecutableBuilder
apollo_router::plugin::test::service::ExecutionService
apollo_router::plugin::test::service::QueryPlanningService
apollo_router::plugin::test::service::RouterService
apollo_router::plugin::test::service::SubgraphService
apollo_router::reload::Error
apollo_router::router::ApolloRouterError
apollo_router::router::NewApolloRouterBuilder
apollo_router::router::RouterHandle
apollo_router::service_registry::ServiceRegistry
apollo_router::spec::SpecError
apollo_router::spec::query::Query
apollo_router::spec::schema::Schema
apollo_router::plugin::test::service::__mock_MockExecutionService_ExecutionService::__call::Expectation
apollo_router::plugin::test::service::__mock_MockQueryPlanningService_QueryPlanningService::__call::Expectation
apollo_router::plugin::test::service::__mock_MockRouterService_RouterService::__call::Expectation
apollo_router::plugin::test::service::__mock_MockSubgraphService_SubgraphService::__call::Expectation

We should probably decide on a case by case basis if an item should be made importable, or if the public API should be reduced in some way (for example making a method of another type private because its signature the only place the item shows up).