[
https://issues.apache.org/jira/browse/CAMEL-24961?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18130831#comment-18130831
]
Claus Ibsen commented on CAMEL-24961:
-------------------------------------
PR [#28343|https://github.com/apache/camel/pull/28343] (stacked on #28340): the
body types of the last eleven AWS components: aws-config, aws-parameter-store,
aws-security-hub, aws2-athena, aws2-ecs, aws2-eks, aws2-mq, aws2-msk,
aws2-redshift-data, aws2-s3-vectors and aws2-step-functions. With it every AWS
component has body types. These eleven have no uses in the human-written
routes, so the share stays at 98.1%.
* Checked at runtime with camel run, against the AWS emulator of camel infra
through a proxy that logs what Camel sends, and a fake of the AWS API for
Security Hub, Athena and Redshift Data, which the emulator does not answer.
* The bodies that are read: the SQL of startQueryExecution of athena, the value
of putParameter, the findings of batchImportFindings and the vector or the keys
of s3-vectors, each unless a header has it. The other operations take their
input from headers and give the response of the AWS SDK; athena gives no body
after startQueryExecution unless it waits, and an iterable of pages for
getQueryResults; s3-vectors gives a List for its query, get and list
operations, and its consumer one QueryOutputVector per vector found.
* aws-parameter-store is not in the catalog: its module is not registered for
the catalog generation (CAMEL-26093), so only its own JSON has the body types
until that is fixed.
* Docs fixed: the athena page now says what the body is after
getQueryExecution, listQueryExecutions, S3Pointer and startQueryExecution.
* The YAML validator has the same reports as before on 1204 human-written and
1209 model-written route files.
* Bugs found while checking them at runtime, one JIRA per component:
CAMEL-26091 (aws2-redshift-data), CAMEL-26092 (aws2-s3-vectors), CAMEL-26093
(aws-parameter-store), CAMEL-26094 (aws-security-hub), CAMEL-26095 (aws2-mq),
CAMEL-26096 (aws2-msk), CAMEL-26097 (aws2-eks), CAMEL-26098 (aws2-ecs),
CAMEL-26099 (aws-config), CAMEL-26100 (aws2-athena) and CAMEL-26101
(aws2-step-functions).
_Claude Code on behalf of davsclaus_
> camel-catalog: the body format and Java carrier each component, data format
> and language consumes and produces
> --------------------------------------------------------------------------------------------------------------
>
> Key: CAMEL-24961
> URL: https://issues.apache.org/jira/browse/CAMEL-24961
> Project: Camel
> Issue Type: Improvement
> Components: camel-catalog
> Reporter: Claus Ibsen
> Assignee: Claus Ibsen
> Priority: Major
> Fix For: 4.24.0
>
>
> Phase C of CAMEL-24844. CAMEL-11132 (2017) is the original ask and stays the
> umbrella; this issue is the executable spec for it.
> The catalog describes every option and every header of a component - {{file}}
> carries 17 headers with a javaType - and says nothing about the body. So a
> person, an IDE, the camel-jbang-mcp catalog tools and the YAML validator
> cannot answer the question that is asked most: *what is the body after this
> step*. The validator's body-presence walk (CAMEL-24844 phase A) has to carry
> its own hardcoded rules for that reason, which is the wrong place for them.
> h3. What to add
> Per component, data format, language and EIP, in the JSON the catalog already
> generates, two dimensions:
> * the *format* - what the payload is, with the Kamelet data type names so a
> Kamelet and a plain component read the same: json, xml, csv, text, binary,
> avro...
> * the *carrier* - the Java type the format arrives in: text, bytes, stream,
> file, map, list, pojo, null. This is what the failures are about: a JSON body
> as a {{Map}} and as text look identical in a description and behave
> differently in {{${body.orderId}}}, {{jsonpath}} and Groovy.
> Both for input and output, and where the type depends on an option
> ({{unmarshalType}}, {{charset}}, stream caching) the metadata names the
> option rather than picking one value.
> h3. Every entry is truthful: four values, no guesses
> A half-filled field is worse than an empty one - a consumer cannot tell
> "unknowable" from "not done yet". So all 407 components get an entry, and the
> value is one of:
> # *derived* - read from the component's own source at its {{setBody}} call
> site, recorded with file and line as provenance so a reviewer checks it in
> seconds. Measured: *322 of 407* components have a {{setBody}} call site in
> their package, and the argument is nearly always a local or field whose
> declared type is in the same file ({{result}} 519, {{response}} 191, {{body}}
> 191, {{out}} 53). This is a reading task, not a guessing task.
> # *unchanged* - the component does not replace the body ({{browse}},
> {{bean-validator}}, {{crypto}} which writes a header). A fact, not an absence.
> # *same as <scheme>* - delegating components state the reference instead of
> repeating it: {{activemq}}, {{activemq6}}, {{amqp}} to jms; {{class}} to
> bean; {{cron}} to quartz; the {{debezium-*}} family to debezium-common.
> # *unknown* - the genuinely dynamic ones, named as such. This is the case
> CAMEL-11132 describes: a component whose type comes from its configuration or
> from the remote system's schema.
> The 85 components with no {{setBody}} in their package fall almost entirely
> into 2 and 3, so *unknown* should end up a small set rather than the residue.
> h3. How it is verified
> # source-derived, with the citation, for the 322;
> # the message history of the reference runs (camel-jbang-examples and the doc
> examples) records the body class per step, so a derived carrier that
> disagrees with what actually flowed fails the check - this is what catches a
> systematic error in the derivation itself, and it is the runtime half of
> CAMEL-24844 (merged in 4.23.0) earning its keep;
> # a reviewer pass over the entries that are neither derived nor confirmed.
> h3. Scope note
> The routes people actually write concentrate hard - over 1712 real YAML files
> (camel-jbang-examples, camel-examples, camel-kamelets, benchmark output)
> there are 122 distinct schemes and the top 10 cover 89.5% of uses, with
> {{json}} at 1214 of 1317 data format uses. That concentration says where to
> *start* and where the benchmark can measure an effect. It does not say where
> to stop: the catalog is a public contract and is filled completely.
> h3. What it unlocks
> * the validator carries the type from step to step and suggests the step that
> fixes it - {{convertBodyTo}}, {{unmarshal}}, {{transformDataType}} - instead
> of only reporting (CAMEL-24844 phase D);
> * the catalog tools and the component documentation answer "what is the body
> here" from metadata rather than prose;
> * the rules leave the validator's source and become data every tool shares.
> Prior art to reuse rather than invent: the Kamelet spec already has
> {{dataTypes:}} for in, out and error (19 of 250 Kamelets declare it today),
> and CAMEL-18698 shipped the data type transformer registry and the
> {{transformDataType}} EIP in 4.0 as the conversion mechanism.
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)
