Add minimal, feature gated methods for accessing internals of path_router

[chris-windsor]

Prior to this discussion, I had opened #3127. There has also been #3086 and #2515. David and Jonas have expressed concern over the scope of a feature like this expanding to undefinable bounds.

The goal is to get a similar change made, as done in #3127 or something else widely agreeable and well defined in scope. We do not need Axum to reinvent the wheel on every possible feature in every other framework. However, we do need additional, minimal exposure to some internals, to allow the creation of other libraries, in a similar capability that which we have to create middleware, extensions, etc.

In other web frameworks, the following abilities exist:

Framework	direct/intentional routes API	direct router internals access
Hono	✅	✅
Fastify	✅	✅
Express	🚫	✅ ¹
NestJs	🚫	✅ ²
Laravel	✅	🚫
FastAPI	✅	✅
Flask	✅	✅

• ¹ abusing access of 'private' properties and methods. can use _router
• ² built on top of express

If anyone else is looking for similar feature, please share a use case and a proposal for what methods or access level would be useful.

[FSMaxB]

I haven't been able to fully flesh out the idea yet, but I was thinking of having a way to expose a list of all routes together with some kind of HashSet<Box<dyn Any> container for every route, similar to Extension for requests and responses.

This could be used to build something like utoipa or aide but without having to fully wrap the entire router and instead adding custom metadata into the routes that can later be pulled out to create documentation from. You would still have to wrap handlers and I don't yet have an idea on how to deal with middlewares, but it should still make things easier (not having to reimplement the entire router APIs) and potentially make it possible to combine multiple tools that want access to the routes, which isn't possible by fully wrapping the API.

[jplatte]

This isn't really what I meant. Prior art (what do other frameworks do) is a relevant consideration, but the more important question to be answered is that of the use case(s).

we do need additional, minimal exposure to some internals, to allow the creation of other libraries, in a similar capability that which we have to create middleware, extensions, etc.

is notably not a concrete use case. What other libraries are you thinking of here?

[itssimon]

I'm the author of Apitally and this feature would allow a client library for Axum to be implemented.
Apitally's client libraries introspect apps on startup to capture a list of all endpoints, which would currently be difficult to implement efficiently for Axum. Most other frameworks make this relatively easy by exposing registered routes in their API.

[itssimon]

You're right. For frameworks that offer built-in OpenAPI spec generators, Apitally utilises that to gather more details about endpoints (e.g. FastAPI, Litestar). But as a minimum just a list of method + path of all endpoints is sufficient.
A core principle with Apitally's client libraries is to keep dependencies at a minimum and make setup as easy as possible for users. My preference would therefore be to not require users to also have something like aide or utoipa installed in order to use Apitally.

[jplatte]

I have a hard time imagining how a client library that doesn't know about the inputs and outputs of endpoints is of any use. Can you elaborate?

[itssimon]

Sorry, probably my poor choice of words, but by client library I mean the SDK for Apitally, an API analytics & monitoring tool, not a client library for the user's API implemented with Axum. Does it make more sense with this context?

[jplatte]

Okay, that makes more sense but I'm still not really seeing the whole picture - what does your apitally client SDK do with these endpoints?

[itssimon]

The SDK sends the list of endpoints to Apitally's servers, which allows the user to see a complete list of their endpoints on the dashboard immediately after the app started up, even before any requests have been handled. Apitally also uses this to generate endpoint groups that can be used for filtering and analysis (e.g. endpoints under "/v1/users" would be grouped together).

Feel free to create an account (free) and play around with the demo data, or check out the docs, to get a better idea.