Support for displaying 'engine' compatibility or filtering extensions by a specific Code OSS 'engine' value

[jthomasmock]

tldr:

For users who have to download extensions directly from the OpenVSX website to use them in offline/airgapped environments since their IDE cannot directly query OpenVSX API:

1. I think it's worth exposing the minimum engine version on each extensions page
2. It would be ideal to be able to filter the website and API for extensions based on a minimum engine version

---

Background

.vsix extensions have an engine value that determines the minimum version of the IDE that is required to be compatible with that particular extension.

This is returned in the raw JSON of an extension when requesting a specific version and is used by the IDE to install the appropriate version of an extension for the current IDE version.

# check IDE version
$ code --version
1.94.1

# from OpenVSX extension API JSON
 "engines": {
        "vscode": "^1.37.0"
    },

However, users in air-gapped or offline environments are not able to query OpenVSX directly from their IDE. They would need to go to OpenVSX in a separate browser, download an extension and attempt to install it in their Code OSS-based IDE. If it fails due to an engine mismatch, they would need to then go to the next version, and repeat the process until finding a compatible version.

More adventurous users might use the OpenVSX API to loop across the various versions and find a compatible version. For an example with the path-intellisense extension, with most of the extra JSON trimmed off, as seen if using an API request against: https://open-vsx.org/api/christian-kohler/path-intellisense/2.8.0

{
  "namespaceUrl": "https://open-vsx.org/api/christian-kohler",
  "name": "path-intellisense",
  "namespace": "christian-kohler",
  "targetPlatform": "universal",
  "version": "2.8.0",
...
  "unrelatedPublisher": false,
  "namespaceAccess": "restricted",
  "allVersions": {
    "latest": "https://open-vsx.org/api/christian-kohler/path-intellisense/latest",
    "2.8.0": "https://open-vsx.org/api/christian-kohler/path-intellisense/2.8.0",
    "2.7.0": "https://open-vsx.org/api/christian-kohler/path-intellisense/2.7.0",
...
  },
...
##### <--- Here is the engine version ---> ##### 
    "vscode": "^1.43.0"
  }

---

Friction points

This is useful information, but it requires querying the API many time per extension as the engine data is only exposed at each individual version rather than including it within some allVersion sub field. This is wasteful of OpenVSX resources as a request for even say 10 extensions might turn into 100 API calls (10 per extension) as it pages through the various calls to find a compatible engine version.

Additionally, users or administrators are required to make these requests via curl or equivalent as the website doesn't display the minimum engine version:

Suggestion

For users who have to download extensions to use them in offline/airgapped environments:

1. I think it's worth exposing the minimum engine version on each extensions page
2. It would be ideal to be able to filter the website and API for extensions based on a minimum engine version

[filiptronicek]

@jthomasmock do you have context about what VS Code versions are used in these air-gapped environments? I wonder how old these VS Code versions are in general, to see how widespread this issue potentially is.

If we were to implement something like this, we'd most likely need to implement a version range parser, since these fields are not always in a friendly format.

I quickly sampled data from extensions on https://open-vsx.org. These are results from all currently published extensions:

^1.74.0: 154
^1.75.0: 151
^1.63.0: 127
^1.67.0: 110
^1.82.0: 104
^1.52.0: 100
*: 94
^1.60.0: 85
^1.70.0: 85
^1.0.0: 82
^1.65.0: 75
^1.77.0: 69
^1.46.0: 68
^1.80.0: 68
^1.66.0: 66
^1.73.0: 65
^1.68.0: 61
^1.64.0: 60
^1.85.0: 59
^1.78.0: 58
^1.76.0: 55
^1.59.0: 53
^1.88.0: 53
^1.53.0: 53
^1.58.0: 53
^1.50.0: 53
^1.48.0: 51
^1.43.0: 49
^1.72.0: 49
^1.40.0: 48
^1.54.0: 47
^1.90.0: 46
^1.5.0: 44
^1.56.0: 44
^1.92.0: 43
^1.30.0: 42
^1.57.0: 42
^1.71.0: 41
^1.51.0: 39
^1.69.0: 38
^1.55.0: 37
^1.62.0: 37
^1.87.0: 37
^1.41.0: 36
^1.86.0: 36
^1.49.0: 36
^1.89.0: 33
^1.45.0: 33
^1.79.0: 33
^1.47.0: 32
^1.95.0: 30
^1.83.0: 30
^1.91.0: 30
^1.81.0: 28
^1.26.0: 28
^1.42.0: 28
^1.84.0: 27
^1.32.0: 27
^1.22.0: 27
^1.34.0: 26
^1.20.0: 26
^1.94.0: 25
^1.61.0: 25
^1.93.0: 25
^1.15.0: 25
^1.44.0: 24
^1.23.0: 23
^1.31.0: 22
^1.13.0: 21
^1.12.0: 20
^1.39.0: 20
^1.17.0: 20
^1.38.0: 19
^1.33.0: 19
^1.37.0: 19
^1.36.0: 19
^1.18.0: 18
^1.35.0: 18
^1.28.0: 18
^0.10.1: 17
^1.19.0: 17
^1.10.0: 17
^1.14.0: 15
0.10.x: 14
0.10.0: 14
^1.63.1: 14
^1.25.0: 14
^1.63.2: 10
^1.29.0: 10
^1.83.1: 10
^1.8.0: 9
^1.21.0: 8
^1.45.1: 7
^1.66.2: 7
^1.6.0: 7
^1.57.1: 6
^1.73.1: 6
^0.10.10: 6
^1.92.1: 5
^1.79.1: 5
^1.75.1: 5
^1.16.0: 5
^1.89.1: 5
^1.27.0: 5
^1.84.2: 4
^1.51.1: 4
^1.66.1: 4
^1.84.1: 4
^1.9.0: 4
^1.59.1: 4
^1.41.1: 4
^1.85.2: 4
^1.70.2: 3
^1.74.3: 3
^1.68.1: 3
^1.64.2: 3
^1.7.0: 3
^0.10.0: 3
^1.78.2: 3
^1.88.1: 3
^1.86.2: 3
^1.62.3: 3
^0.10.x: 3
^1.24.0: 3
^1.58.1: 3
>=1.0.0: 3
^1.85.1: 3
^1.70.1: 3
^1.4.0: 3
^1.76.1: 3
^1.30.x: 2
^1.60.0-insider: 2
>=1.70.0: 2
^1.93.1: 2
^1.65.2: 2
1.x.x: 2
^1.71.2: 2
^1.52.1: 2
>=1.48.2: 2
^1.35.1: 2
^1.28.1: 2
>=1.91.0: 2
^1.65.1: 2
^1.30.2: 2
^1.47.2: 2
^1.31.1: 2
^1.67.2: 2
>=1.72.0: 2
^1.43.2: 2
^1.25.1: 2
^1.78.1: 2
^1.2.0: 2
^1.67.1: 2
^1.11.0: 2
1.50.0: 2
^1.22.2: 1
^1.37.1: 1
^1.81.1: 1
^1.94.0-20240918: 1
^1.94.2: 1
^1.77.3: 1
^1.91.1: 1
^1.9.1: 1
^1.18.x: 1
>=1.63.0: 1
^1.26.1: 1
1.63.0: 1
^1.50.1: 1
>=1.90.0: 1
^1.22.1: 1
>=1.82.3: 1
^1.79.0-insider: 1
^1.5.1: 1
>=1.53.0: 1
^1.58.2: 1
^1.7.5: 1
^0.10.7: 1
^1.59.0-20210722: 1
^1.89.0-insider: 1
^1.39.2: 1
^1.20.1: 1
^1.47.3: 1
^1.43.x: 1
^1.49.3: 1
^1.53.2: 1
>=1.85.0: 1
^1.21.1: 1
^1.79.2: 1
^1.60.1: 1
^1.81.2: 1
^1.92.2: 1
^1.80.2: 1
^1.80.1: 1
^1.74.2: 1
>=1.46.0: 1
^0.10.5: 1
^2023.0.0: 1
^1.77.1: 1
^1.72.2: 1
^1.32.3: 1
^1.29.1: 1
^1.12.1: 1
^1.82.2: 1
^1.56.2: 1
>=1.67.0: 1
1.22.0: 1
>=1.56.0: 1
^1.54.3: 1
^1.65.x: 1
^1.61.1: 1
^1.82.3: 1
^1.90.2: 1
^1.38.1: 1
^1.69.2: 1
>=1.75.0: 1
^1.56.1: 1
^1.72.0-insider: 1
^1.95.1: 1
>=1.79.0: 1
^1.86.0-20240105: 1
>=1.93.0: 1
^1.74.1: 1

[jthomasmock]

@jthomasmock do you have context about what VS Code versions are used in these air-gapped environments? I wonder how old these VS Code versions are in general, to see how widespread this issue potentially is.

Thanks Filip! It's quite variable, but it's often the case these air-gapped environments are in so-called "regulated industries" such as Finance, Insurance, Pharma, or Government that are thus very slow to make upgrades.

The painpoints I have seen are largely around fairly dated versions of Code OSS, maybe a good strawman would be 1.73 (Oct-2022, about 2 years ago). That's about 409 extensions of the top 4 most popular engine versions from your list:

^1.82.0: 104
^1.75.0: 151
^1.74.0: 154
^1.67.0: 110
^1.63.0: 127

However, realistically, the pain is felt even if there are 2-3 extensions with incompatibilities, as the back-and-forth testing or trying to parse GitHub source code or raw JSON is a bit of a pain even if you know where to look.

[amvanbaren]

@jthomasmock

I think it's worth exposing the minimum engine version on each extensions page

The engine version can be added to the Works with section.

It would be ideal to be able to filter the website and API for extensions based on a minimum engine version

An engine request parameter can be added to the /query, /search and /version-references endpoints for filtering extension versions. Only the /search endpoint is used in the webui.

Where should the engine search field be added to the webui?

[jthomasmock]

The engine version can be added to the Works with section.

This would be excellent!

An engine request parameter can be added to the /query, /search and /version-references endpoints for filtering extension versions. Only the /search endpoint is used in the webui.

Very good! I do think that being able to search for a version w/ engine compatibility programmatically would be ideal to avoid repetitive API calls against OpenVSX.

Where should the engine search field be added to the webui?

As far as expectations for the search web UI, perhaps something like this with a default that matches any engine:

That "Minimum Engine: Any" is the implicit search as it stands today, give me the newest extension version that matches any engine version of VS Code. That would not change the default behavior of the site, but allow for filtering down extensions to display the latest version compatible with a min engine.

engines: An object containing at least the vscode key matching the versions of VS Code that the extension is compatible with. Cannot be *. For example: ^0.10.5 indicates compatibility with a minimum VS Code version of 0.10.5.