Federico Mariani created CAMEL-26344:
----------------------------------------
Summary: camel-jbang - plugin add: select community plugin
versions built for the installed CLI's minor line
Key: CAMEL-26344
URL: https://issues.apache.org/jira/browse/CAMEL-26344
Project: Camel
Issue Type: Improvement
Components: camel-jbang
Reporter: Federico Mariani
h3. Problem
{{camel plugin add <name>}} registers community plugins with Maven {{LATEST}}
when no version is given. The only load-time check is a minimum version
({{firstVersion}} in {{PluginHelper.versionCheck}}). Neither can express "this
release is built for Camel 4.22.x", so:
* On CLI 4.23.0, {{LATEST}} (Forage 1.6.2, built for 4.22) fails on {{camel
run}} with {{IllegalArgumentException: Unsupported runtime jbang}}. The
{{jbang}} run runtime is new in 4.23 (#26226).
* Once Forage 1.7.0 (built for 4.23, KaotoIO/forage#533) is published, 4.22 LTS
users will get it by default.
Every published plugin release already records the Camel version it was built
against: the version of its {{org.apache.camel:camel-jbang-core}} dependency
(scope {{provided}}) in the resolved POM. Camel can therefore choose a matching
release for existing plugins without new metadata:
||Plugin release||camel-jbang-core in the resolved POM||
|Forage 1.4.0 / 1.4.1 / 1.4.2|4.18.3 / 4.18.4 / 4.18.5|
|Forage 1.6.0 / 1.6.1 / 1.6.2|4.22.0 / 4.22.1 / 4.22.2|
|Forage 1.7.0 (upcoming)|4.23.0|
|kit 0.3.0 / 0.3.1|4.18.0|
|kit 0.4.0 / 0.4.1|4.22.0 / 4.22.1|
h3. Proposal
For each candidate release, read its resolved POM through the existing Maven
resolver, so repositories, mirrors, {{--repos}}, settings and offline mode all
apply. Take the supported range from:
# the property {{camel.jbang.plugin.camel-versions}} (Maven range syntax, e.g.
{{[4.23.0,4.24.0)}}): *declared*. Forage 1.7.0 publishes it.
# otherwise the {{camel-jbang-core}} dependency version, as its minor line
({{4.22.2}} -> {{[4.22.0,4.23.0)}}): *inferred*
# otherwise: *unknown*
Guiding rule: never break a setup that works today. Pick a better default when
there is evidence; otherwise keep today's behaviour and warn.
h3. Acceptance criteria
* *Scope.* Only community plugins added without {{--version}} or {{--gav}}.
Built-in {{org.apache.camel}} plugins keep resolving to the CLI version.
* *Selection.*
** List versions with {{resolveAvailableVersions}}, excluding SNAPSHOT and
qualifier versions.
** Walk newest-first, with a capped number of POM reads.
** Select the first release whose range (declared, else inferred) contains the
host CLI version. A SNAPSHOT CLI is compared without {{-SNAPSHOT}};
{{--camel-version}} is ignored.
* *Registration.* Resolve the selected jar before changing configuration. Store
the exact GAV, the range, and its kind (declared/inferred) in the plugin entry.
Print the selection, e.g. {{Selected forage 1.6.2 for Camel CLI 4.22.2 (built
for Camel 4.22.2)}}.
* *No match, newest release declares a range.* Fail (stderr, nonzero exit) and
leave configuration unchanged. Show the CLI version, the newest release per
line found during the walk, and commands for a supported pairing.
* *No match, inferred/unknown data only.* Keep today's behaviour ({{LATEST}})
and warn, naming the newest release and the Camel version it was built for.
* *Metadata or POMs unreadable* (network/offline). Keep today's behaviour and
warn that compatibility could not be checked.
* *Explicit choices.* {{--version}} and {{--gav}} register exactly what was
asked, with a warning if the release's range excludes the CLI. They are never
blocked.
* *Load time.* Extend the existing {{versionCheck}} step: if a stored range
excludes the CLI (e.g. after a CLI upgrade), warn and suggest {{camel plugin
add <name>}}. Use stored data only, with no network call. Entries without a
stored range, including all existing registrations, are not checked.
* *4.18 LTS.* Decide whether to backport the known-plugin catalog (CAMEL-23491,
first released in 4.21.0) together with this, or to document {{--gav}} for
4.18. Without the catalog, {{camel plugin add forage --version X}} on 4.18
registers {{org.apache.camel:camel-jbang-plugin-forage}}, which does not exist.
* *Docs.* Document the property and the inference in the custom-plugin guide.
* *Tests.*
** declared, inferred and unknown sources
** newer and older plugin patches within a line
** no match for each kind
** explicit {{--version}} / {{--gav}}
** built-in plugins unchanged
** SNAPSHOT CLI and an offline/unreachable repository
** existing registrations, and a CLI upgrade after add
** a fixture plugin, to keep the implementation generic
h3. Expected effect on today's plugins
||Plugin / case||Today||With this change||
|Forage on CLI 4.22.x|LATEST = 1.6.2 (1.7.0 once released)|1.6.2|
|Forage on CLI 4.23.0|LATEST = 1.6.2, {{camel run}} broken|1.7.0 once released|
|kit on CLI 4.22.x / 4.23.0|LATEST = 0.4.1|0.4.1, unchanged (warning on 4.23)|
|kit on CLI 4.18.x (if backported)|LATEST = 0.4.1|0.3.1 (built for 4.18.0),
printed|
|Built-in plugins|CLI version|unchanged|
|--version / --gav|as given|as given, plus a warning on a known mismatch|
|Existing registrations|-|untouched|
The kit maintainer should be notified before release. If kit 0.4.x supports
4.18, declaring {{camel.jbang.plugin.camel-versions}} keeps 0.4.1 selected.
h3. Evidence
A containerised compatibility matrix used the official launchers, a clean
{{user.home}} and a fresh Maven cache. It covered:
* CLI 4.22.0/4.22.1/4.22.2 x Forage 1.6.0/1.6.1/1.6.2
* CLI 4.18.3/4.18.5 x Forage 1.4.0/1.4.2
* CLI 4.22.x/4.23.0 x Forage 1.7.0-SNAPSHOT
Probes: config read, {{camel run}} / {{camel forage run}} with a JDBC
datasource, the Shiro example over platform-http, and export to main/Spring
Boot/Quarkus (plus {{mvn package}} for 4.23.0 x 1.7.0).
Results:
* Within each minor line, every patch combination behaved like the exact
pairing.
* CLI 4.23.0 x Forage 1.6.2 fails ({{jbang}} runtime).
Relevant code:
* {{PluginAdd.java}}, {{PluginHelper.java}}, {{known-plugins.json}} in
{{dsl/camel-jbang/camel-jbang-core}}
* {{MavenDownloader}} / {{MavenDownloaderImpl}} in
{{tooling/camel-tooling-maven}}: add a resolved-POM read next to
{{resolveAvailableVersions}}
Related: KaotoIO/forage#533 (Forage 1.7.0: {{jbang}} runtime fix, declared
range, self-check warning).
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)
