[Notice] Removal of AngularJS 1.8 in the 2.11 release

[ashwin-pc]

AngularJS 1.x has reached its end of life as of January 2022. In our ongoing efforts to keep OpenSearch secure and reliable, we're committed to removing this risk, and as such, we'll be “deangularizing” the project and removing specific exports and internal APIs that rely on it.

Why this change?

Since Angular 1.x has reached its end of life, the first of many of its CVEs has been identified in #1558. There is no other mitigation for these CVEs besides removing the AngularJS dependency. Our goal is to eliminate this risk by the end of the year, which leaves 2.11 as the last release that can be released so that users on other platforms can receive the fix by the end of 2023. The project was already on the path to deprecate this dependency prior to the fork and as of writing has already migrated most of the core parts of the app away from Angular to React.

While this change does not impact any of the public REST APIs, it does impact some internal APIs. To the best of our knowledge, these internal APIs are just that —internal. But this notice is to call out the remaining changes and its impact on internal API’s and exports that other plugins might rely on.

Whats changing?

The following internal APIs will no longer work:

1. Discover’s docview Service:
   1. docviews.addDocview: removes the directive property

The following exports will no longer be available:

1. Global
   1. @osd/i18n/angular
   2. angular
   3. angular-sanitize
2. opensearch_dashboards_legacy plugin
   1. initAngularBootstrap
   2. configureAppAngularModule
   3. addFatalError (error prop will no longer accept the AngularHttpError’s)
   4. AngularHttpError
   5. subscribeWithScope
   6. PrivateProvider
   7. PromiseServiceCreator
   8. registerListenEventListener
   9. watchMultiDecorator
   10. createTopNavDirective
   11. createTopNavHelper
   12. formatMsg (remove Angular specific logic)
3. data plugin
   1. toAngularJson

We will also be removing some angularjs specific global styles in /src/core/server/core_app/assets/legacy_dark_theme.css and /src/core/server/core_app/assets/legacy_light_theme.css

What do you need to do?

1. Review the List: Check if your projects or components depend on any of the above exports or internal APIs.
2. Plan for Migration: Start preparing for the transition. Consider alternative methods or functions that can replace the deprecated features.
3. Stay Updated: Keep an eye on updates related to our 2.11 release to be well-prepared.

Need help?

Should these changes impact your plugin, or if you require advice on potential alternatives comment on the issue directly and we will get back to you.

[smortex]

I am not sure to follow: if I read and understand correctly, this PR explain how this change will break API. This mean that existing plugins using these API will break if they are not fixed.

According to SemVer that OpenSearch is supposed to follow, this is clearly something that should lead to a new MAJOR version: https://semver.org/#summary

More specifically: https://semver.org/#spec-item-8

Can you clarify if SemVer was dropped on the way or if should this target (trigger?) the next major version?

[dblock]

Thanks for the details @ashwin-pc. I had the same question as @smortex, and it first it sounded to me like a major version increment of OpenSearch Dashboards to 3.0 would be the obvious choice, however I actually am not so sure after thinking about it.

OpenSearch (not Dashboards) has been breaking "internal APIs" left and right in incremental versions, causing downstream plugins to have to change code every single time in minor increments. Majority of changes were simple, but that's beyond the point. When we raised a similar semver question (in opensearch-project/OpenSearch#8110), it was argued that these interfaces were never APIs in the semver sense, because OpenSearch requires that you rebuild and increment the plugin version every single minor release. So plugin 1.2.3 is not compatible with server 1.2.4 by design. This is different from clients, where client 1.2.3 is compatible with server 1.x.

It looks like this is the first time the same debate is happening in OpenSearch Dashboards. I would want to answer the following questions.

1. Are these changes an actual external API or an internal API? Are they APIs at all or implementation details? @ashwin-pc says "internal" above.
2. If these are internal, should internal APIs also follow semver, or should only externally documented REST APIs? Have we spelled it either way anywhere?
3. Is there anyone out there that is not maintaining 1:1 minor version dependency in a plugin, ie. plugin 1.2.3 is compatible with OpenSearch Dashboards 1.x?
4. Can this change be made semver compatible in a minor version increment, e.g. the exports be provided in an optional plugin?
5. @smortex or anyone else, do you have any plugins that will visibly break with these specific changes, and what are they?
6. @ashwin-pc What is the extra work required to major-version-increment?
7. Does the fact that we're talking about a dependency that's EOL change anything?
8. Should OpenSearch Dashboards do what OpenSearch does, especially because of their matching version and release relationship today?

[ashwin-pc]

@dblock Right now OSD and OS releases are coupled just like plugins. We are making progress to decouple atleast that relationship but it isnt trivial and might not be possible in the 2.11 timeline. Even if OSD decouples from OS, Plugins, the release infrastructure and other planned 3.0 changes that break REST API's might not be ready in time for it.

@AMoo-Miki @kavilla Can add more context here

[AMoo-Miki]

I am not sure to follow: if I read and understand correctly, this PR explain how this change will break API. This mean that existing plugins using these API will break if they are not fixed.

According to SemVer that OpenSearch is supposed to follow, this is clearly something that should lead to a new MAJOR version: https://semver.org/#summary

More specifically: https://semver.org/#spec-item-8

Can you clarify if SemVer was dropped on the way or if should this target (trigger?) the next major version?

@smortex The functionality planned for removal are mostly (if not all) functions that OSD used internally for generating the UX. These functions were never intended for consumption of plugins or users. However, OSD being a JavaScript project, there is always a way to use an internal function if one needs to. OSD knows that they have super smart and creative users and suspect that some might be using these internal methods - which, again, were never intended for public consumption. The only ones who would be using these are people who continue to use the outdated and vulnerable AngularJS.

As a plugin developer, you should still have access to all of the Public APIs that OSD offers. However, if you notice that a plugin of yours is unable to find an internal API that you depend on as a result of deangularization, please post here and the team would help figure a way out or reintroduce the missing API in a different way (if technically feasible).

Also, OSD is committed to its promise of semantic versioning. They also understand that not having a clear list of public APIs is counterproductive; there are efforts being made to better clarify these.

[smortex]

Are these changes an actual external API or an internal API? Are they APIs at all or implementation details? @ashwin-pc says "internal" above.

Right, I saw 2 sections, the first being labelled "internal" made me think the 2nd labelled "exports" was about "public" interfaces.

The functionality planned for removal are mostly (if not all) functions that OSD used internally for generating the UX. These functions were never intended for consumption of plugins or users. However, OSD being a JavaScript project, there is always a way to use an internal function if one needs to

Removing internal things is fine. Maybe JS allow to easily abuse third party internal classes and objects, and indeed removals may have unexpected consequences in this case. But the point of semver is to version public API, so internal things removal is out of scope.

I am not a plugin developer so am not personally affected by the change, I just saw something that I understood to be wrong, sorry if I misunderstood.

TL;DR if "The following exports will no longer be available" refers to internal things, this is 100% fine.

[wbeckler]

This is now released