Skip to content

AGENTS.md

Latest commit

 

History

History
300 lines (235 loc) · 14.9 KB

AGENTS.md

File metadata and controls

300 lines (235 loc) · 14.9 KB
Raw

Apache Camel Quarkus - AI Agent Guidelines

Rules & guidelines for AI agents working on this codebase.

Project Overview

Apache Camel Quarkus provides Quarkus extensions for Apache Camel components, enabling users to build integration applications with fast boot times and low memory footprints.

What NOT to do

  • Do NOT directly modify generated files under docs/modules or src/main/generated as they are automatically updated by maven
  • Do NOT use dynamic class loading or reflection (impacts native compilation)
  • Do NOT introduce Spring Boot or Spring unless explicitly required

Technology Stack

  • Java 21+
  • GraalVM 25+ / Mandrel 25+
  • Maven 3.9.11+ (For convenience the maven wrapper is provided in the root directory and can be invoked as ./mvnw or ./mvnw.cmd)
  • Apache Camel 4.x, Quarkus 3.x. Check pom.xml for the current Camel, and Quarkus versions used.

Repository Structure

extensions/          # Native-supported Camel component extensions
extensions-jvm/      # JVM-only extensions (not yet native-compatible)
extensions-core/     # Core Camel Quarkus extensions (core, yaml-dsl, etc.)
extensions-support/  # Shared support libraries used by multiple extensions
integration-tests/   # Integration tests JVM + native
integration-test-groups/  # Groupings of integration tests, primarilly for boosting CI speed & efficiency
integration-tests-jvm/   # JVM-only extension integration tests
integration-tests-support/ # Shared test utilities and test containers support
poms/bom/            # Runtime Bill of Materials
poms/bom-deployment/ # Deployment Bill of Materials
tooling/             # Maven plugin, scripts, templates, and tooling
catalog/             # Camel Quarkus catalog
docs/                # AsciiDoc documentation (Antora-based)
examples/            # Example projects (separate repo: camel-quarkus-examples)

Key Files

  • pom.xml - Project Maven dependency version properties and test container image names
  • poms/bom/pom.xml - Runtime dependencies BOM
  • poms/bom-test/pom.xml - Test dependencies BOM
  • tooling/scripts/test-categories.yaml - Test categorization for GitHub Actions CI
  • docs/antora/antora.yml - Antora documentation metadata. Note that docs/local-build.sh relies on an external camel-website repository and is not intended for self-contained local documentation generation within this project.

Build Commands

./mvnw clean install -Dquickly                 # fast build, no tests
./mvnw clean install -T1C -Dquickly            # parallel fast build, no tests
./mvnw clean install                           # full build with JVM tests
./mvnw clean install -pl integration-tests/kafka -Dnative  # native tests for a specific module (only for integration-tests/ or integration-test-groups/ modules)
./mvnw clean install -pl extensions/kafka -am  # single extension
./mvnw process-resources -Pformat -pl :camel-quarkus,<changed modules>  # format changed modules & update metadata (commit-time only, see "Code Formatting")

Tip: Use mvnd (Maven Daemon) for faster builds. Use -T1C for parallel builds (1 thread per CPU core).

Testing Commands

./mvnw test                              # unit tests
./mvnw verify                            # integration tests JVM mode
./mvnw verify -pl integration-tests/kafka -Dnative  # native tests for a specific module (only for integration-tests/ or integration-test-groups/ modules)
./mvnw test -Dtest=MyTest                # specific test
./mvnw test -pl integration-tests/kafka  # specific module

Code Formatting

Run it once, immediately before committing, only for the modules you changed, and only when the change actually needs it. Never run it after individual edits, and never across the whole reactor.

Run when you added files (license headers) or edited a pom.xml containing a mvn process-resources comment reference (for sorting or virtual dependencies):

./mvnw process-resources -Pformat -pl :camel-quarkus,<changed modules>  # e.g. -pl :camel-quarkus,extensions/kafka/runtime,integration-tests/kafka
./mvnw process-resources -Pformat -N                       # pom sorting, virtual dependencies & extension metadata only

Always include :camel-quarkus (the root project) in -pl: it runs the root-only goals (pom sorting, virtual dependencies, extension metadata), which cover the whole source tree. Without it they are silently skipped and the build still succeeds. Each listed module gets license headers.

Skip for Java-only or docs-only edits: the default build already formats Java and sorts imports at process-sources (unless -Dquickly).

To regenerate one extension's docs on its own: ./mvnw -pl extensions/kafka/deployment process-classes.

After adding or removing a *BuildItem class, or changing its Javadoc or fields, regenerate the build items page:

./mvnw -pl docs process-classes            # docs/modules/ROOT/pages/contributor-guide/build-items.adoc

A full build does this already, but -Dquickly builds skip it, so a stale page otherwise surfaces only as a CI failure.

It rewrites files in place, so run it before git add, or re-stage after. Always run it from the project root.

Extension Structure

extensions/kafka/
├── pom.xml                           # Parent POM
├── runtime/
│   ├── pom.xml
│   └── src/
│       ├── main/java/org/apache/camel/quarkus/component/kafka/
│       ├── main/resources/META-INF/quarkus-extension.yaml
│       └── main/doc/                 # Extension documentation
│           ├── configuration.adoc
│           └── usage.adoc
└── deployment/
    ├── pom.xml
    └── src/
        ├── main/java/org/apache/camel/quarkus/component/kafka/deployment/
        │   └── KafkaProcessor.java
        └── test/java/

Naming Conventions

Classes:

  • Deployment: *Processor.java for build-time processing @BuildStep
  • Runtime: *Recorder.java for recording and producing RuntimeValue used in deployment build steps
  • Runtime: *BuildTimeConfig.java for ConfigPhase.BUILD_TIME & ConfigPhase.BUILD_AND_RUN_TIME_FIXED annotated @ConfigMapping interfaces
  • Runtime: *RunTimeConfig.java for ConfigPhase.RUN_TIME annotated @ConfigMapping interfaces
  • Runtime: *Substitutions.java for GraalVM substitutions that live in src/main/java/.../graal/
  • Tests: *Test.java (JUnit 6), *IT.java for native tests

Packages:

  • Runtime: org.apache.camel.quarkus.component.<name>
  • Deployment: org.apache.camel.quarkus.component.<name>.deployment

Annotations:

  • @BuildStep for deployment processors
  • @Record(ExecutionTime.STATIC_INIT) for static init
  • @Record(ExecutionTime.RUNTIME_INIT) for runtime init
  • Recorder classes are annotated with @Recorder

Configuration:

  • @ConfigRoot(phase = ConfigPhase.BUILD_TIME) for build-time configuration (read during build, baked into native image)
  • @ConfigRoot(phase = ConfigPhase.RUN_TIME) for runtime configuration (can be changed at runtime)
  • @ConfigRoot(phase = ConfigPhase.BUILD_AND_RUN_TIME_FIXED) for config read at build time but also available at runtime (value cannot change)
  • Build-time config: extension enablement & configuration options used to bootstrap components at build time
  • Runtime config: connection strings, credentials, timeouts, dynamic behavior
  • Prefer runtime config when possible for flexibility; use build-time only when necessary for native compilation

Maven version properties:

  • artifactId.version for general version properties
  • *-maven-plugin.version for plugin version properties
  • Where appropriate, use @sync comments to automatically update version properties
  • Dependency versions MUST always be defined in the root project pom.xml

Creating Extensions

1. Scaffold Extension

For extensions providing native support:

./mvnw cq:create -N -Dcq.artifactIdBase=kafka

For extensions providing JVM only support:

./mvnw cq:create -N -Dcq.artifactIdBase=kafka -Dcq.nativeSupported=false

2. Add to Test Categories (native only)

Add the extension name to tooling/scripts/test-categories.yaml. Test categories should not be overloaded with too many extensions. But should be 'balanced' to ensure each one completes in roughly the same time as others.

3. Review Extension Metadata

View extensions/kafka/runtime/src/main/resources/META-INF/quarkus-extension.yaml

Update / sync with:

./mvnw -N cq:update-quarkus-metadata

4. Complete Integration Tests

Follow docs/modules/ROOT/pages/contributor-guide/extension-testing.adoc

5. Add Documentation

Follow docs/modules/ROOT/pages/contributor-guide/extension-documentation.adoc.

After making changes, run the following from the project root to sync and regenerate the project documentation:

./mvnw -pl extensions/kafka/deployment process-classes

6. Format & style

Deferred to commit time — do not run this after each edit. See "Code Formatting".

./mvnw process-resources -Pformat -pl :camel-quarkus,extensions/kafka/runtime,extensions/kafka/deployment,integration-tests/kafka

Integration Tests

Tests use the Quarkus test framework based on JUnit 6.

Test Structure

Follow docs/modules/root/contributor-guide/extension-testing.adoc.

JVM mode tests should be annotated with @QuarkusTest.

@QuarkusTest
class KafkaTest {
    // test code
}

Native mode tests should extend the JVM mode test and be annotated with @QuarkusIntegrationTest.

@QuarkusIntegrationTest
class KafkaIT extends KafkaTest {
}

Important Constraints

  • No @Inject in @QuarkusIntegrationTest: Integration tests run the application as a separate process, so CDI injection does not work. Expose application state via JAX-RS endpoints (using quarkus-resteasy) and assert via RestAssured in tests. See integration-test-groups/foundation/core/ for the pattern.
  • Every @QuarkusTest needs an IT class: Each @QuarkusTest class must have a corresponding @QuarkusIntegrationTest class that extends it, to ensure tests also run in native mode.
  • Grouped test modules share one native application: Modules under integration-test-groups/ are compiled into a single grouped native binary per group. Properties in one module's application.properties affect ALL modules in the group. Avoid setting properties that alter global Camel behavior (e.g. camel.main.duration-max-messages).

Troubleshooting Native Build Failures

Native compilation with GraalVM requires explicit registration of classes, resources, and proxies. Register these in the deployment module's *Processor.java using @BuildStep methods. Common patterns:

Issue Symptom Build item Example
Reflection ClassNotFoundException / NoSuchMethodException in native mode ReflectiveClassBuildItem extensions/sql/deployment/.../SqlProcessor.java
Missing resources FileNotFoundException in native mode NativeImageResourceBuildItem / NativeImageResourceDirectoryBuildItem extensions/xj/deployment/.../XJProcessor.java
Resource bundles MissingResourceException in native mode NativeImageResourceBundleBuildItem extensions/fhir/deployment/.../FhirProcessor.java
Proxy classes ClassNotFoundException for proxies NativeImageProxyDefinitionBuildItem extensions/influxdb/deployment/.../InfluxdbProcessor.java
Service providers ServiceConfigurationError in native mode ServiceProviderBuildItem extensions/fop/deployment/.../FopProcessor.java

Use CombinedIndexBuildItem to discover classes at build time — see extensions/servicenow/deployment/.../ServicenowProcessor.java.

Camel components already ship with a Jandex index. Do not add IndexDependencyBuildItem for Camel component JARs (e.g. camel-a2a, camel-kafka). CombinedIndexBuildItem can discover their classes directly. Only add IndexDependencyBuildItem for non-Camel third-party libraries that lack a Jandex index.

See also https://quarkus.io/guides/writing-extensions.

Security Model

Camel Quarkus inherits the security model from Apache Camel. The canonical document is docs/modules/ROOT/pages/user-guide/security-model.adoc. Use it as the reference when triaging security reports, deciding whether a finding warrants a CVE, or reviewing a security-sensitive PR.

Extension author review checklist (for security-sensitive PRs)

All guidance from https://camel.apache.org/manual/security-model.html applies (header filtering, object input filters, secure defaults, auth enforcement). In addition, for Camel Quarkus extensions:

  • Does the change add resource registration (NativeImageResourceBuildItem) for files that contain secrets or should not be embedded in the native image?
  • Does a new build-time configuration option control a security-relevant default? Prefer ConfigPhase.RUN_TIME unless build-time is strictly necessary for native compilation.

Common Tasks

Update Camel Version

Edit both the project camel-dependencies parent version and properties in root pom.xml:

  1. Parent camel-dependencies version (e.g., <version>4.18.0</version>)
  2. Property camel.major.minor (e.g., <camel.major.minor>4.18</camel.major.minor>)
  3. Property camel.version (defined as ${camel.major.minor}.0)

Update Quarkus Version

Edit quarkus.version in the project root pom.xml.

Sync Dependency Versions

When to sync dependency versions: Whenever the Camel or Quarkus version is updated. Or when version properties are updated that influence other properties annotated with @sync comments.

./mvnw cq:sync-versions -N

Regenerate camel-quarkus-bom

When to regenerate: Whenever a dependency version is updated in the root pom.xml or a new dependency is added to the project in poms/bom/pom.xml.

./mvnw clean install -pl poms/bom

Promote an extension from JVM-only support to Native mode support

./mvnw -N cq:promote -Dcq.artifactIdBase=kafka

Commit Messages

Reference GitHub issues when applicable.

Fixes #issueNumber. Brief description of the change

Longer detailed explanation of changes made.