RFC: URL Service (TTL: expired)

[streamich]

Summary

This RFC contains proposal and implementation details for the URL Service, which will replace our existing Short URL Service and URL Generator Service.

GitHub issue: #87304

Rendered text

[lukeelmers]

This might be a long comment, so apologies in advance... I've been thinking about this problem for over a year now, so I have a lot of thoughts 🙂 🙈

But suffice it to say I'm glad to see us finally tackling this problem.

---

The use case for short urls is clear, but IMHO the need for a shared generator service is still ambiguous (vs putting everything in plugin contracts).

One thing that I think would be useful in this RFC is a breakdown of when we would recommend to use:

• URL generator from a plugin contract, vs
• URL generator via generatorClient.get, vs
• core.app.navigateToApp

I think that would help to answer the concerns raised by @ppisljar and @joshdover around creating implicit dependencies.

For the case of apps with circular dependencies, what's the benefit of using URL generators vs using navigateToApp?

• generatorClient.get requires you to pass a known ID, which functionally is no different than the app ID you pass to navigateToApp
• URL generator lets you pass state, so does navigateToApp
• URL generator handles migrations which the app registers, but each app could be handling migrations behind the scenes for any state that's passed via navigateToApp
• In either case you won't have type safety anyway due to the circular dep

The only downside I could think of would be a case where there's a circular dependency, and one app is storing the state somewhere and needs a way to migrate it. In that case the app that they are navigating to would be responsible for migrating the state on-the-fly as there wouldn't be a way for them to explicitly call migrate

---

I guess what I'm getting hung up on is that we keep talking about URLs, but in my mind the problem we are really trying to solve is around sharing state and has nothing to do with URLs.

I'm probably oversimplifying, but an alternative approach I have in my mind would be:

• Update the short url service as described here
  • This needs to be cleaned up anyway
• Implement a redirect route which takes an app ID & state, and hands it off to each app via navigateToApp
  • This solves for external users (i.e. Cloud)
• Provide a standardized interface which apps can use to add navigate / migrate functionality to their plugin contracts
  • So everyone just goes through plugin contracts on both client & server
  • If that creates a circular dependency, they use navigateToApp (client), or the redirect route (server) as a workaround (or maybe we implement navigateToApp on the server in core)
• Each app exports an interface of whatever state they consider "public"
  • This becomes the source of truth for what state is supported during navigation
  • They would also need to handle incoming state from navigateToApp and automatically migrate it on-the-fly

The concept of "URL state" is then entirely out of the question: If apps want to put state in URLs, that becomes an implementation detail.

Again, I'm probably oversimplifying, so please help me poke holes in this as I'm sure there are some use cases I haven't considered. ❤️

[ppisljar]

@lukeelmers, i agree with your first point and i think even for migration purpose URL generators service doesn't bring any benefit. All the app needs to do is implement PeristableStateService as part of their contract. (for example discover app could provide discover.navigateState: PersistableStateService which would provide a way to migrate, collect telemetry and inject/extract variables for the navigateState)

I agree with proposed plan as well.

[elasticmachine]

Pinging @elastic/kibana-app-services (Team:AppServices)

[ppisljar]

LGTM

[Dosant]

LGTM,
After the latest review had a tranch of questions which we discussed with @streamich offline.
I am leaving key takeaways here:

1. Current RFC version briefly mentions paramsVersion=7.x and state migrations. From the discussion, the plan is that Locator implements PersistableState interface and Locator params persisted in the stored saved objects should be migrated when updating Kibana. The same logic is used when migrating _redirect URLs on the fly.
2. Was curious how do we teach teams deep-linking to Kibana to use endpoints as /app/goto/_redirect/DISCOVER_DEEP_LINKS?params={"indexPattern":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","highlightedField":"foo"}&paramsVersion=7.x instead of copying URLs from the browser window. Where do they learn about these URLs and how do they know about available params? Looks like each Locator should be documented separately and documentation for all of them should be centralized somewhere. Maybe some dev tool for generating those will be needed? Also a tool for exploration and validation?
3. In the current design locators/endpoints do not validate params. Apps validate incoming states when navigated to them.
4. In the current design we do not worry about params length. If URL is too long -> use a short URL.

---

We also reviewed this RFC from search-sessions perspective and looks like it would work. Comparing to URL generators this RFC unlocks navigation with history state (can support with this Lens editor and Canvas).
We will need to add server-side migrations to migrate app state inside the search-session saved objects using locators.