[jira] [Created] (CAMEL-25771) camel-core - a route checksum and revision, so tools can tell which routes changed between two runs or after a reload

["Claus Ibsen (Jira)" <ji...@apache.org>]

Claus Ibsen created CAMEL-25771:
-----------------------------------

             Summary: camel-core - a route checksum and revision, so tools can tell which routes changed between two runs or after a reload
                 Key: CAMEL-25771
                 URL: https://issues.apache.org/jira/browse/CAMEL-25771
             Project: Camel
          Issue Type: Improvement
          Components: camel-jbang, camel-core
            Reporter: Claus Ibsen
             Fix For: 4.24.0


A tool that watches a running Camel app (the Camel CLI, the MCP tools, an IDE, an AI agent) knows the routes by id and file. When the app is stopped and started again, or dev mode reloads a file, the tool cannot tell which routes changed: every route of the file comes back under the same file name, and a generated id such as {{route3}} may now belong to another route. A tool could diff the route dumps itself, but each tool would do it differently.

*Proposal:* give each route two values, shown the same way everywhere.

* *checksum*: a short hex digest (say the first 12 characters of a SHA-256) of the route as written: its own steps, options and expressions, with property placeholders as written. It leaves out generated ids and source lines, so moving the route in its file, adding a route above it, or changing comments and formatting does not change it. It also leaves out the onException, intercept and onCompletion parts that route configurations and the RouteBuilder merge into the route model (the route dumps show them merged today, see {{design/cross-cutting-binding.adoc}}). Otherwise one edit to a shared routeConfiguration would mark every route as changed. The same route gives the same checksum in every run, so a tool can compare two runs.
* *revision*: a counter in the running app. It is 1 when the route is added. A reload that brings the route back with a different checksum makes it 2, then 3; the same checksum keeps it (a reload of a file where only another route changed). The CamelContext keeps it by route id, so it survives the route being removed and added again. It starts over when the app restarts; across restarts, tools compare checksums.

*How (to be confirmed):* dump the route definition with the existing {{ModelToXMLDumper}} (resolvePlaceholders, generatedIds and sourceLocation all false) and hash the dump, once, where the route is prepared ({{RouteDefinitionHelper.prepareRoute}}) and before the merge. Without camel-xml-io on the classpath, the checksum is not known (null).

*Where it shows:*
# {{Route}} (camel-api): {{getChecksum()}} and {{getRevision()}}, @since 4.24.
# JMX: Checksum and Revision attributes on {{ManagedRouteMBean}}.
# Dev consoles: {{checksum}} and {{revision}} in each route entry of the {{route}} console. The CLI status file and the MCP {{camel_runtime_routes}} tool read that console as-is, so they get the fields with no extra work. The {{route-structure}} and {{route-dump}} consoles carry the checksum beside each route, so facts a tool keeps per line know which version of the route they belong to.
# Camel CLI: {{camel get route}} has both fields in its JSON output, and an opt-in column in the table.
# The reload summary log says which routes changed, e.g. {{Routes reloaded summary (total:3 started:3 changed:1)}}, and marks each changed route.
# MCP: the descriptions of {{camel_runtime_routes}} and {{camel_runtime_route_structure}} say the checksum is how to compare a route with an earlier run.

Other tools, such as the TUI, can use it once this is in.

*Limits to document:*
* The checksum covers the route, not the code it calls. A Java lambda in {{.process(...)}} dumps as a bare {{process}}, so changing the lambda does not change the checksum, and neither does a change inside a bean. A changed property value is configuration drift, not a changed route.
* The revision follows the route id. A generated id can move to another route when routes are added to or removed from a file, so tools should match routes with generated ids by checksum.

*Open questions:*
* Is an effective checksum (with the route configurations merged in) useful as well? Proposal: not now.
* Startup cost: measure the dump and hash on a large set of routes. If it is not negligible, compute it only when tooling is on (dev profile, or the CLI connector present).

*Used by:* CAMEL-25750 keys the body types it observes at each node by route id and checksum. A reload with a new checksum drops that route's observations, and the per-line facts carry the checksum, so a tool knows whether they still match the file it has.

_Filed by Claude Code on behalf of davsclaus_




--
This message was sent by Atlassian Jira
(v8.20.10#820010)