# Cameleer documentation (full text)

> Every page of the Cameleer documentation (https://pmsudhi.github.io/cameleer/docs/) concatenated as plain markdown, for LLMs and coding assistants. Cameleer is Apache Camel rewritten in Rust.

---

Source: https://pmsudhi.github.io/cameleer/docs/

# Cameleer documentation

> Cameleer is Apache Camel rewritten in Rust; these pages explain how to write, run and deploy its routes, and document every component, language and data format with tested examples.

If you already know Apache Camel, the routes, endpoint URIs, EIP names and the YAML DSL are the
same. Start with a guide, then look up the components your route uses.

## Where to find what

| you want to | go to |
|---|---|
| write and run your first route | [Guides](https://pmsudhi.github.io/cameleer/docs/guides/index.html) |
| send or receive messages with Kafka, HTTP, S3, Slack, SQL, ... | [Components](https://pmsudhi.github.io/cameleer/docs/components/index.html), one page per endpoint scheme, grouped by category |
| write expressions and predicates (`${header.x}`, JSONPath, XPath) | [Languages](https://pmsudhi.github.io/cameleer/docs/languages/index.html) |
| convert message bodies (JSON, CSV, XML, Avro, ...) | [Data formats](https://pmsudhi.github.io/cameleer/docs/dataformats/index.html) |
| run Cameleer in Docker, Kubernetes, Cloud Run or AWS Lambda | [Deployment](https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html) |
| build a smaller binary or image with only the components you use | [Build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) |
| check which Camel features are implemented, with their options | [Feature matrix](https://pmsudhi.github.io/cameleer/docs/FEATURES.html) |
| see what people run on it: AI agent tools, HL7 over MLLP, MQTT edge gateways, serverless, file and SFTP pipelines | [Use cases](https://pmsudhi.github.io/cameleer/use-cases/), the [agent cookbook](https://pmsudhi.github.io/cameleer/docs/guides/agents.html) and the [edge cookbook](https://pmsudhi.github.io/cameleer/docs/guides/edge.html) |
| compare Cameleer with Apache Camel: throughput, memory, startup | [Apache Camel vs Cameleer](https://pmsudhi.github.io/cameleer/compare/apache-camel-vs-cameleer/) and the [benchmark report](https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html) |
| choose between Apache Camel alternatives | [Apache Camel alternatives](https://pmsudhi.github.io/cameleer/alternatives/apache-camel-alternatives/) |
| see what was verified against real servers and clients | [Interop](https://pmsudhi.github.io/cameleer/docs/INTEROP.html) |
| see what is planned | [Roadmap](https://pmsudhi.github.io/cameleer/docs/ROADMAP.html) |

The project overview, the quick start and the examples are in the
[README](https://github.com/pmsudhi/cameleer/blob/main/README.md); the ready-to-run route files are in [examples/](https://github.com/pmsudhi/cameleer/tree/main/examples).

## Connect your coding agent

Give Cursor, Claude, Windsurf, VS Code or any MCP-capable assistant Cameleer's real docs, so it
writes routes from the documentation instead of guessing. The docs MCP server is
`https://gitmcp.io/pmsudhi/cameleer` (it serves this repository's `llms.txt`, docs and README).

| tool | add this |
|---|---|
| Claude Code | `claude mcp add --transport http cameleer-docs https://gitmcp.io/pmsudhi/cameleer` |
| Cursor (`~/.cursor/mcp.json`) | `{"mcpServers": {"cameleer-docs": {"url": "https://gitmcp.io/pmsudhi/cameleer"}}}` |
| Windsurf (`~/.codeium/windsurf/mcp_config.json`) | `{"mcpServers": {"cameleer-docs": {"serverUrl": "https://gitmcp.io/pmsudhi/cameleer"}}}` |
| VS Code (`.vscode/mcp.json`) | `{"servers": {"cameleer-docs": {"type": "http", "url": "https://gitmcp.io/pmsudhi/cameleer"}}}` |
| Claude Desktop (`claude_desktop_config.json`) | `{"mcpServers": {"cameleer-docs": {"command": "npx", "args": ["mcp-remote", "https://gitmcp.io/pmsudhi/cameleer"]}}}` |

The docs are also indexed by [Context7](https://context7.com) (ask your assistant to "use
context7" for Cameleer) and [DeepWiki](https://deepwiki.com/pmsudhi/cameleer). Agents that read
files directly can start from [llms.txt](https://pmsudhi.github.io/cameleer/llms.txt) or
[llms-full.txt](https://pmsudhi.github.io/cameleer/llms-full.txt).

## How the pages are organized

Every page starts with a one-sentence answer under its title, then shows a complete route you can
copy. Component pages follow the same layout: when to use it, the URI format, an example in YAML
and in the Rust DSL, the options, the message headers, how to run it with Docker, and common
questions.

Every YAML example is a complete Camel YAML DSL file. Save it as `route.camel.yaml` and run it
with the Docker image:

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/route.camel.yaml
```

Hosts and credentials in examples are written as `{{env:NAME:default}}` placeholders: set the
environment variable (`-e NAME=value` with Docker) or the default is used.

## Common questions

### Are the examples tested?

Yes. The test suite parses every YAML example with the real loader and resolves every endpoint URI,
which rejects unknown options the same way Apache Camel does. Many examples also run end to end
against embedded brokers and mock services.

### Is there a version of these docs for LLMs and coding assistants?

Yes. The site publishes `llms.txt` (a summary with links) and `llms-full.txt` (every page as plain
markdown), and every HTML page has its markdown source next to it under the same name with `.md`.

### Where do I report a mistake in the docs?

Open an issue or a pull request on [GitHub](https://github.com/pmsudhi/cameleer). Each page links
to its source file at the bottom.

## Writing documentation

- One page per component at `components/<scheme>.md`; alias schemes (`https` for `http`) go on
  the page's `**Also:**` line instead of getting their own page. Languages go in
  `languages/<name>.md`, data formats in `dataformats/<name>.md`, guides in `guides/`.
- The first line under the H1 is a blockquote with one plain sentence that answers what the
  page is about; it becomes the page's search description.
- Every ` ```yaml ` block is either a complete Camel route preceded by
  `<!-- example: <unique-id> -->` on the line directly above, or something else (a Compose or
  Kubernetes file) preceded by `<!-- not-camel -->`.
- A "Common questions" section with `###` question headings becomes FAQ data for search engines.
- Links between pages are relative markdown links (`../components/kafka.md`).

Check your changes, then build the site:

```sh
cargo test -p cameleer-main --test docs_harness
python3 scripts/build-docs.py        # writes site/docs/, site/sitemap.xml, site/llms*.txt
python3 -m http.server -d site 8000  # then open http://localhost:8000/docs/
```

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/getting-started.html

# Getting started with Cameleer

> Install Cameleer (Docker image, `cargo install` or Rust crates), run a first route and a first
> REST API, and configure them with properties and environment variables, in about ten minutes.

Cameleer is Apache Camel rewritten in Rust: the same routes, endpoint URIs, Enterprise
Integration Patterns and Simple language, as one native binary with no JVM. If you know Camel,
you already know how to write Cameleer routes. Every route on this page runs in the test suite
(`crates/cameleer-main/tests/docs_guides.rs`).

## Install

Pick one of three ways. They run the same routes.

### Docker

The image `pmsudhi/cameleer` on Docker Hub is a single binary on a distroless base, for
`linux/amd64` and `linux/arm64`, about 20 MB to download. Mount your route files and run them:

```sh
docker run --rm -p 8080:8080 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/hello.camel.yaml
```

It runs as a non-root user, works with `--read-only`, and stops gracefully on `SIGTERM`. The
[deployment guide](https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html) covers Docker Compose, Kubernetes and Cloud Run.

### The `cameleer` command line

With a Rust toolchain installed:

```sh
cargo install cameleer-main
cameleer run hello.camel.yaml
```

This installs the `cameleer` command with every component. Its subcommands follow Camel JBang (`run`, `init`, `ps`, `stop`, `log`, ...). To build from source:

```sh
git clone https://github.com/pmsudhi/cameleer && cd cameleer
cargo build --release -p cameleer-main
target/release/cameleer run examples/hello-api.camel.yaml
```

### Rust crates

To embed routes in your own Rust program, depend on `cameleer-core` (the engine, EIPs and Rust
DSL) and the crates for the components you need:

```toml
[dependencies]
cameleer-core = "0.4"
cameleer-http = "0.4"
```

`cameleer-main` bundles every component and runs YAML routes from Rust; see
[Embed routes in a Rust program](#embed-routes-in-a-rust-program) below.

### Every component is included by default

The image, `cargo install cameleer-main` and the crates' default features contain every
component, language and data format, so any route in these docs runs without extra setup.
For a smaller binary (a serverless function, an edge device, a slim image) pick only the
families your routes use with cargo features; [Build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) lists them
and shows the commands. Each component page names its feature in its header line.

## Your first route

A route has one input (`from`) and a list of steps. Save this as `hello.camel.yaml`:

```yaml
- route:
    id: hello
    from:
      uri: timer:hello
      parameters:
        period: 500
        repeatCount: 3
      steps:
        - setBody:
            simple: "Hello from Cameleer, message ${exchangeProperty.CamelTimerCounter}"
        - log: "${body}"
```

Run it with `cameleer run hello.camel.yaml` (or the `docker run` line above). The `timer`
endpoint fires three times, half a second apart; `setBody` builds a message with the
[Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html); `log` prints `Hello from Cameleer, message 1`, then 2 and 3, to standard output.

Without `repeatCount` the timer runs until you stop the process with Ctrl+C.

## Your first REST API

The REST DSL declares HTTP endpoints and hands each request to a route. Save this as
`hello-api.camel.yaml`:

```yaml
- rest:
    path: /hello
    get:
      - path: /{name}
        to: direct:greet
- route:
    id: greet
    from:
      uri: direct:greet
      steps:
        - setHeader:
            name: Content-Type
            constant: application/json
        - setBody:
            simple: '{"greeting": "Hello, ${header.name}!"}'
```

```sh
docker run --rm -p 8080:8080 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/hello-api.camel.yaml
curl localhost:8080/hello/Ada      # {"greeting": "Hello, Ada!"}
```

Path parameters such as `{name}` become headers. The server listens on port 8080 by default
(`camel.server.port` changes it). For JSON binding, validation and error responses, see
[examples/rest-api.camel.yaml](https://github.com/pmsudhi/cameleer/blob/main/examples/rest-api.camel.yaml) and the
[REST component](https://pmsudhi.github.io/cameleer/docs/components/rest.html).

## Configuration

Routes read configuration with property placeholders, as in Camel:

- `{{name}}` and `{{name:default}}` come from `application.properties` (or
  `application.yaml`), environment variables and `--prop name=value`.
- `{{env:NAME}}` and `{{env:NAME:default}}` read an environment variable directly.

```yaml
- route:
    id: configured
    from:
      uri: "timer:tick?period={{tick.period:1000}}&repeatCount=1"
      steps:
        - setBody:
            simple: "{{greeting}} from {{env:SITE_NAME:the lab}}"
        - log: "${body}"
```

With this `application.properties` next to the route:

```properties
greeting=Good morning
tick.period=200
camel.server.port=9090
```

```sh
cameleer run configured.camel.yaml --properties application.properties
SITE_NAME=plant-7 cameleer run configured.camel.yaml --prop greeting=Hi
```

The first command logs `Good morning from the lab`. Settings are applied in this order, the last
one winning: the properties file, `CAMEL_*` environment variables (`CAMEL_SERVER_PORT=9090`
sets `camel.server.port`), then `--prop`. Spring Boot and Quarkus names
(`server.port`, `spring.profiles.active`) and profiles (`application-dev.properties`) work too.
Never put secrets in route files: use `{{env:...}}` or a secrets vault
(`{{aws:...}}`, `{{azure:...}}`, `{{gcp:...}}`).

## Embed routes in a Rust program

The Rust DSL has the same EIPs as the YAML DSL, with Rust casing:

```rust
use cameleer_core::prelude::*;
use cameleer_http::rest::RestDslExt;

fn main() -> Result<()> {
    let ctx = CamelContext::new();
    cameleer_http::register(&ctx);
    ctx.properties().set("camel.server.port", "8080");
    ctx.add_routes(|b| {
        b.rest("/api/greet").get("/{name}").to("direct:greet");
        b.from("direct:greet")
            .set_header("Content-Type", constant("application/json"))
            .set_body(simple(r#"{"greeting": "Hello, ${header.name}!"}"#));
    })?;
    ctx.start()?;
    loop { std::thread::park(); }
}
```

To run YAML route files from your own binary with every component, depend on `cameleer-main`
and use `cameleer_main::new_main()`, then `add_route_file("routes/hello.camel.yaml")` and
`run()` ([example](https://github.com/pmsudhi/cameleer/blob/main/crates/cameleer-main/examples/embed_yaml.rs)).

## Useful commands

| command | what it does |
|---|---|
| `cameleer run route.camel.yaml` | run one or more route files (all route files of the current folder when none is given) |
| `cameleer run --dev route.camel.yaml` | reload route files when they change |
| `cameleer init my-route.camel.yaml` | write a starter route |
| `cameleer ps`, `cameleer stop --all` | list and stop running integrations |
| `cameleer get routes`, `cameleer get health` | inspect a running integration |
| `cameleer export --directory my-service` | turn routes into a standalone Rust project |
| `cameleer catalog components` | list the components |

## Where to go next

- [Concepts](https://pmsudhi.github.io/cameleer/docs/guides/concepts.html): routes, endpoints, exchanges, messages, components and the DSLs.
- [Build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html): a smaller build with only the components you use.
- [Enterprise Integration Patterns](https://pmsudhi.github.io/cameleer/docs/guides/eips.html): every EIP with a YAML and a Rust example.
- [Error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html): retries, dead letter channels, `onException`.
- [Cameleer for AI agents](https://pmsudhi.github.io/cameleer/docs/guides/agents.html) and [Cameleer at the edge](https://pmsudhi.github.io/cameleer/docs/guides/edge.html): cookbooks.
- [Migrating from Apache Camel](https://pmsudhi.github.io/cameleer/docs/guides/migrating-from-apache-camel.html) and the [FAQ](https://pmsudhi.github.io/cameleer/docs/guides/faq.html).
- [Examples](https://github.com/pmsudhi/cameleer/tree/main/examples): real routes for Kafka, S3, Slack and OpenAI, each with a
  `docker run` line.

## Common questions

### Do I need Java or Maven to run Cameleer?

No. Cameleer is a native binary with no JVM. You need Rust only to build it from source or to
embed it; the Docker image and the installed binary need nothing else.

### Can I run my existing Apache Camel YAML routes?

Mostly yes: Camel YAML and XML routes run unchanged when they use components and options
Cameleer supports. Java beans and processors must be rewritten in Rust. See
[Migrating from Apache Camel](https://pmsudhi.github.io/cameleer/docs/guides/migrating-from-apache-camel.html).

### How do I change the HTTP port?

Set `camel.server.port`: `--prop camel.server.port=9090`, the environment variable
`CAMEL_SERVER_PORT=9090`, or `camel.server.port=9090` in `application.properties`.

### Where do log messages go?

To standard output. Set the level with the `CAMEL_LOG_LEVEL` environment variable (`TRACE`,
`DEBUG`, `INFO`, `WARN`, `ERROR` or `OFF`).

## Related

- [README](https://github.com/pmsudhi/cameleer/blob/main/README.md), [deployment guide](https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html), [feature list](https://pmsudhi.github.io/cameleer/docs/FEATURES.html)
- Apache Camel: [Camel JBang](https://camel.apache.org/manual/camel-jbang.html),
  [YAML DSL](https://camel.apache.org/components/next/others/yaml-dsl.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/concepts.html

# Cameleer concepts

> Cameleer uses Apache Camel's model: a CamelContext runs routes; each route takes exchanges from
> an endpoint, passes their messages (body and headers) through processors and EIPs, and sends
> them to other endpoints created by components.

This page explains each concept, shows how it appears in the YAML, XML and Rust DSLs, and notes
where Cameleer differs from Apache Camel. The examples run in the test suite
(`crates/cameleer-main/tests/docs_guides.rs`).

## The model in one route

```yaml
- route:
    id: order-intake
    from:
      uri: direct:orders
      steps:
        - setHeader:
            name: priority
            simple: "${body[total] > 1000 ? 'high' : 'normal'}"
        - setProperty:
            name: receivedAt
            simple: "${date:now:yyyy-MM-dd}"
        - choice:
            when:
              - simple: "${header.priority} == 'high'"
                steps:
                  - to: mock:priority-orders
            otherwise:
              steps:
                - to: mock:orders
```

```rust
b.from("direct:orders")
    .route_id("order-intake")
    .set_header("priority", simple("${body[total] > 1000 ? 'high' : 'normal'}"))
    .set_property("receivedAt", simple("${date:now:yyyy-MM-dd}"))
    .choice()
        .when(simple("${header.priority} == 'high'"))
            .to("mock:priority-orders")
        .otherwise()
            .to("mock:orders")
    .end();
```

- The **CamelContext** loaded this route and runs it.
- `direct:orders` is an **endpoint URI**: the `direct` **component** created the endpoint, and
  the route's **consumer** takes messages from it.
- Each order arrives as an **exchange** holding a **message**. `${body[total]}` reads the
  message **body**; `setHeader` writes a message **header**; `setProperty` writes an
  **exchange property**.
- `setHeader`, `setProperty` and `choice` are **processors**; `choice` is an **EIP**.
- `mock:priority-orders` and `mock:orders` are endpoints too: the route's **producers** send to
  them.

An order with `total` 1500 reaches `mock:priority-orders` with the header `priority: high`.

## CamelContext

The CamelContext is the runtime: it holds the components, the registry of beans, the
properties, the type converters and the routes, and starts and stops them. Routes start in
`startupOrder` and stop in reverse order; stopping waits for in-flight exchanges (45 seconds by
default).

- **YAML and XML:** `cameleer run` (or `cameleer_main::new_main()`) creates the context, registers
  every component and loads the route files.
- **Rust:** `CamelContext::new()` creates an empty context; register the components you need
  (`cameleer_http::register(&ctx)`), add routes with `ctx.add_routes(|b| ...)`, then
  `ctx.start()`. A `CamelContext` is a cheap handle you can clone into threads.

## Routes

A route has one input, `from`, and a list of steps. It has an id (generated as `route1`,
`route2`... when you do not set one), and can be started, stopped, suspended and resumed at run
time (`cameleer cmd stop-route`, the dev console, or `ctx.stop_route(id)`). Options:
`autoStartup`, `startupOrder`, `group`, `description`, `routeConfigurationId`, `errorHandler`.

Route templates and Kamelets create routes from parameters; see
[route templates](https://pmsudhi.github.io/cameleer/docs/guides/eips/system.html#route-templates).

## Endpoints and URIs

An endpoint is addressed by a URI: `scheme:path?option=value&option=value`.

```text
kafka:orders?brokers=localhost:9092&groupId=billing
file:inbox?include=.*\.csv&move=.done
platform-http:/alerts?httpMethodRestrict=POST
```

The scheme picks the component, the path names the resource (a topic, a folder, a URL path), and
the options configure it. Options are checked when the endpoint is created: an unknown or
misspelled option fails the route at startup, as in Camel. URIs accept property placeholders
(`{{env:KAFKA_BROKERS:localhost:9092}}`), and in YAML the options can also go in a `parameters`
map. Endpoints are normalized and cached, so two spellings of the same URI share one endpoint.

`toD` computes the URI per message from a Simple expression (`toD: "kafka:${header.topic}"`).

## Components

A component creates endpoints for one scheme. Cameleer has about 230 components, languages and
data formats, all built in; there is nothing to download. They are grouped in crates:
`cameleer-core` (direct, seda, timer, file, log, mock, bean, rest...), `cameleer-http`,
`cameleer-kafka-mqtt`, `cameleer-cloud` (AWS, Azure, Google Cloud), `cameleer-saas` (OpenAI,
Slack, GitHub...) and others. [FEATURES.md](https://pmsudhi.github.io/cameleer/docs/FEATURES.html) lists every component with its
supported options; the [component pages](https://pmsudhi.github.io/cameleer/docs/components/index.html) document them one by one.

An endpoint can be a **consumer** (the `from` of a route: it receives or polls messages) and a
**producer** (a `to`: it sends). Most components are both.

## Exchanges and messages

An **exchange** is one message's trip through a route. It holds:

| part | what it is | in Simple |
|---|---|---|
| message body | the payload: text, bytes, a number, a list or a map (JSON-like) | `${body}`, `${body[field]}` |
| message headers | name/value pairs that travel with the message; components map them to protocol headers (HTTP, Kafka, MQTT, JMS...) | `${header.name}` |
| exchange properties | name/value pairs for the route's own bookkeeping; they are not sent out | `${exchangeProperty.name}` |
| variables | named values set with `setVariable` | `${variable.name}` |
| exception | the error, when a step failed | `${exception.message}` |
| pattern | `InOnly` (fire and forget) or `InOut` (request-reply) | |

Rules worth knowing:

- Header names are case-insensitive and keep their original spelling.
- Headers go out with the message (an `http` call sends them as HTTP headers, `kafka` as record
  headers), so remove what should not leave: `removeHeaders: {pattern: "Camel*"}`. Properties
  stay inside.
- Cameleer has no Java objects: bodies, headers and properties are dynamic values (null, bool,
  integer, float, string, bytes, list, map). JSON maps directly onto them, which is why
  `${body[field]}` works after `unmarshal: json: {}`.
- Camel's names carry over: `CamelFileName`, `CamelHttpResponseCode`, `CamelSplitIndex`,
  `kafka.KEY` and the rest.
- Variables are stored as exchange properties named `CamelVariable.<name>` (Camel has a separate
  variable repository).

## Processors and EIPs

Every step of a route is a processor: something that reads and changes the exchange. The
built-in ones are the EIPs (`filter`, `choice`, `split`, `aggregate`, `circuitBreaker`...) and the
message steps (`setBody`, `setHeader`, `marshal`, `convertBodyTo`...). See
[the EIP guide](https://pmsudhi.github.io/cameleer/docs/guides/eips.html) for all of them.

Custom logic is a processor written in Rust. In the Rust DSL it is a closure:

```rust
b.from("direct:score")
    .process(|ex: &mut Exchange| {
        let text = ex.body().to_string();
        let score = text.split_whitespace().filter(|w| w.eq_ignore_ascii_case("urgent")).count() as i64;
        ex.set_header("urgency", score);
        Ok(())
    })
    .to("mock:scored");
```

To use it from YAML or XML, bind it in the registry (`ctx.registry().bind_processor("scorer",
...)`) and call it with `- process: {ref: scorer}`. Returning
`Err(CamelError::new("IOException", "..."))` fails the exchange and hands it to the
[error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html). Camel's Java beans with reflection-based parameter binding
do not exist; scripts in Groovy, JavaScript, Python or Java syntax run in Cameleer's own
interpreters ([`script`](https://pmsudhi.github.io/cameleer/docs/guides/eips/transformation.html#script)).

## Expressions, predicates and languages

An **expression** computes a value from the exchange; a **predicate** is an expression used as a
condition. Both are written in a **language**:

- [Simple](https://pmsudhi.github.io/cameleer/docs/languages/simple.html): `${header.amount} > 100`, `Hello ${body[name]}`, the default
  for most steps.
- JSONPath (`$.items[0].sku`), jq, XPath and XQuery for structured data.
- `constant`, `header`, `exchangeProperty`, `variable` for plain lookups.
- Groovy, JavaScript, Python, MVEL, OGNL, SpEL, DataSonnet and Java-like snippets
  (`cameleer-script`).

In YAML the language is the key (`simple: ...`, `jsonpath: ...`); in Rust it is a function
(`simple("...")`, `jsonpath("$.items")`, `header("id")`, `constant(3)`).

## Data formats and type conversion

A **data format** converts between bytes and structured data: `unmarshal` parses, `marshal`
serializes. JSON, CSV, XML, YAML, Avro, Protobuf, CBOR, Base64, GZip, Zip, PGP, HL7 and others are
built in.

The **type converter** changes a value's type when a step needs it: `convertBodyTo` with Camel's
Java type names (`java.lang.String`, `java.lang.Integer`, `byte[]`), or implicitly when Simple
compares a text with a number.

## The three DSLs

The same route can be written in three ways. All three build the same route model and support
the same EIPs.

**YAML**, Camel's YAML DSL, the usual choice for route files (`*.camel.yaml`): see the route at
the top of this page.

**XML**, Camel's XML DSL (`<routes>`/`<route>` files), converted to the YAML model when loaded:

```xml
<routes xmlns="http://camel.apache.org/schema/spring">
  <route id="order-intake">
    <from uri="direct:orders"/>
    <setHeader name="priority">
      <simple>${body[total] &gt; 1000 ? 'high' : 'normal'}</simple>
    </setHeader>
    <choice>
      <when>
        <simple>${header.priority} == 'high'</simple>
        <to uri="mock:priority-orders"/>
      </when>
      <otherwise>
        <to uri="mock:orders"/>
      </otherwise>
    </choice>
  </route>
</routes>
```

**Rust**, the equivalent of Camel's Java DSL: `RouteBuilder` methods with snake_case names
(`set_header`, `wire_tap`, `to_d`, `loop_`), blocks closed with `.end()`. Use it when routes live
in a Rust program, need custom processors, or should be checked by the compiler.

The REST DSL (`rest:` in YAML, `b.rest(...)` in Rust) declares HTTP APIs in all three.

## How the concepts map to Apache Camel

| Apache Camel | Cameleer | notes |
|---|---|---|
| `CamelContext` | `CamelContext` | a cloneable handle |
| `RouteBuilder.configure()` (Java DSL) | `ctx.add_routes(\|b\| ...)` (Rust DSL) | snake_case method names |
| YAML DSL, XML DSL | YAML DSL, XML DSL | the same files |
| `Exchange`, `Message` | `Exchange`, `Message` | bodies and headers are dynamic `Value`s, not Java objects |
| `Processor` (Java class or lambda) | `Processor` (Rust closure or struct) | |
| exception classes | error kinds (`"IOException"`) with a parent hierarchy | `java.io.IOException` in YAML maps to `IOException` |
| Java beans, `bean:` with parameter binding | processor beans and named bean methods in the registry | no reflection |
| Camel Main, Spring Boot, Quarkus | `cameleer-main` (`application.properties`, profiles, `server.port`) | |
| Camel JBang (`cameleer run`) | `cameleer run` / `cameleer run` | the same commands |
| Maven dependencies per component | every component built in | |

## Common questions

### What is the difference between a header and an exchange property?

Headers belong to the message and are sent out by components (as HTTP headers, Kafka record
headers and so on); exchange properties belong to the exchange and never leave the route. Use
properties for intermediate values.

### What is an endpoint URI?

It is the address of an endpoint: `scheme:path?options`, for example
`kafka:orders?brokers=localhost:9092`. The scheme selects the component.

### Do I have to write Rust to use Cameleer?

No. YAML or XML route files cover all EIPs and components. Rust is needed only for custom
processors and for embedding routes in a Rust program.

### How do routes call each other?

With `direct:` (synchronous, in the same thread), `seda:` (asynchronous, through an in-memory
queue) or `vm:` (like seda, across contexts in the same process).

## Related

- [Getting started](https://pmsudhi.github.io/cameleer/docs/guides/getting-started.html), [EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html), [error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html)
- [Architecture](https://github.com/pmsudhi/cameleer/blob/main/ARCHITECTURE.md): the internals
- Apache Camel: [Architecture](https://camel.apache.org/manual/architecture.html),
  [Exchange](https://camel.apache.org/manual/exchange.html),
  [Endpoint](https://camel.apache.org/manual/endpoint.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/yaml-dsl.html

# YAML DSL reference

> The YAML DSL describes Cameleer routes in `*.camel.yaml` files: one input (`from`), a list
> of steps (EIPs), endpoints written as URIs, and expressions in Simple or another language,
> with the same names as the Apache Camel YAML DSL.

This page lists everything the YAML loader (`crates/cameleer-yaml`) accepts: the file layout,
every top-level element, the endpoint and expression forms, every step with its keys and
defaults, and the mistakes people make most. Every route on this page runs in the test suite
(`crates/cameleer-main/tests/docs_yaml.rs`): the test sends messages through it and checks the
result, and resolves every endpoint URI the way Apache Camel does, so an unknown option fails
the build.

If you generate routes with a coding assistant, read [YAML for coding agents](https://pmsudhi.github.io/cameleer/docs/guides/yaml-for-coding-agents.html)
too, and check every file with [`cameleer validate`](https://pmsudhi.github.io/cameleer/docs/guides/validate.html).

## A first look

```yaml
# hello.camel.yaml: a list of top-level elements
- route:
    id: hello                      # optional; generated when missing
    from:
      uri: timer:hello             # the input endpoint
      parameters:
        repeatCount: 1
      steps:                       # the steps, in order
        - setBody:
            simple: "Hello from ${routeId}"
        - log: "${body}"
        - to: mock:greetings
```

Three things to notice:

- The file is a YAML **list**. Each item has exactly one key: the element type (`route`,
  `rest`, `routeConfiguration`, ...).
- `steps` belongs to `from` (Camel 4 style). A `steps` list next to `from`, at route level,
  is accepted too and runs after the steps under `from`.
- Every step is a list item with one key: the step name (`setBody`, `log`, `to`, ...).

## Files: naming, finding and loading

### File names

| file name | what it holds |
|---|---|
| `*.camel.yaml` (recommended), any `*.yaml` or `*.yml` | routes and other top-level elements |
| `*.kamelet.yaml` | one Kamelet resource (`kind: Kamelet`) |
| `*.pipe.yaml` | one Pipe (`kind: Pipe` or the older `KameletBinding`) |
| `*.integration.yaml` | one Camel K `Integration` resource (its `spec.flows` are routes) |
| `*.xml` | routes in the XML DSL (same steps, same option names) |
| `application.properties`, `application.yaml` | configuration, never routes |

The `.camel.yaml` suffix is a convention from Camel JBang that makes route files easy to find
and lets editors pick the right schema; the loader only looks at the last extension. Use one
route per file for small services, or group related routes; there is no limit.

`cameleer init orders.camel.yaml` writes a starter route; `cameleer init x.kamelet.yaml`,
`x.pipe.yaml` and `x.integration.yaml` write starters for the other kinds.

### Running files

```sh
cameleer run orders.camel.yaml                    # one file
cameleer run orders.camel.yaml billing.camel.yaml # several files, one context
cameleer run routes/*.camel.yaml                  # a shell glob
cameleer run                                      # every .yaml/.yml/.xml file of the current folder
cameleer run --dev orders.camel.yaml              # reload when a file changes
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

- `cameleer run` with no file loads every `.yaml`, `.yml` and `.xml` file of the current
  folder whose name does not contain `application`.
- A directory is not accepted as a file argument: use a shell glob (`routes/*.camel.yaml`) or
  the include pattern below.
- `camel.main.routes-include-pattern` (in `application.properties`, as `--prop`, or the
  environment variable `CAMEL_MAIN_ROUTES_INCLUDE_PATTERN`) adds files by pattern. It is a comma
  separated list of Ant-style patterns: `*` matches within a folder, `**` matches any number
  of folders, and a `file:` or `classpath:` prefix is ignored, so Camel values work:

  ```sh
  cameleer run --prop camel.main.routes-include-pattern=routes/**/*.camel.yaml
  ```

- `--dev` checks the loaded route files about three times a second and, when one changed,
  removes every route that came from a file and loads all the files again. It also selects the
  `dev` profile (`application-dev.properties`). A file that fails to load is logged, and its
  routes stay missing until you fix the file and save it again.
- All files are loaded into one context. Route ids must be unique across files; `direct:`
  endpoints connect routes from different files.
- Kamelets in `./kamelets/` (or the folders of `camel.main.kamelet-locations`) are loaded
  before the route files.

### Inside a file

- Comments start with `#` (at the start of a line, or after a space).
- Several YAML documents in one file are allowed, separated by `---`; each is a list of
  top-level elements, loaded in order.
- A document may also be a single element written as a mapping (`route: ...` without the
  leading `-`), but lists are the norm.
- Anchors (`&name`), aliases (`*name`) and merge keys (`<<`) work, so a repeated block can
  be written once.
- Errors name the place: `at [0].route.from.steps[1].setBody (line 7, column 13 in orders.camel.yaml)`.

```yaml
# first document: the HTTP-facing route
- route:
    id: intake
    from:
      uri: direct:intake
      steps:
        - to: direct:store
---
# second document: the route it calls
- route:
    id: store
    from:
      uri: direct:store
      steps:
        - setBody:
            simple: "stored ${body}"
        - to: mock:stored
```

## Top-level elements

| element | what it does | section |
|---|---|---|
| `route` | a route: `from` plus steps | [route](#route) |
| `from` | a route without the `route:` wrapper | [from](#from-the-short-form) |
| `routeConfiguration` | `onException`, `onCompletion`, intercepts and an error handler shared by routes | [routeConfiguration](#routeconfiguration) |
| `onException`, `onCompletion`, `intercept`, `interceptFrom`, `interceptSendToEndpoint` | the same, written directly at top level (an anonymous route configuration that applies to every route without `routeConfigurationId`) | [routeConfiguration](#routeconfiguration) |
| `errorHandler` | the error handler of every route in the context | [errorHandler](#errorhandler) |
| `routeTemplate` (or `routeTemplates`) | a parameterized route | [templates](#routetemplate-and-templatedroute) |
| `templatedRoute` (or `templatedRoutes`) | a route created from a template | [templates](#routetemplate-and-templatedroute) |
| `rest` | REST endpoints (the REST DSL) | [REST DSL](#rest-and-restconfiguration) |
| `restConfiguration` | the HTTP server and binding for `rest` | [REST DSL](#rest-and-restconfiguration) |
| `beans` | named beans created by registered bean factories | [beans](#beans) |
| `dataFormats` | accepted and stored, but not used: configure data formats on the `marshal`/`unmarshal` step | |

A document whose top level is a mapping with `apiVersion` and `kind` is a Kubernetes-style
resource instead: `kind: Kamelet`, `kind: Pipe`, `kind: KameletBinding` or
`kind: Integration` (see [Kamelets and Pipes](#kamelets-and-pipes)).

Any other element name fails with `Unknown top-level element '...'` and the list of supported
names.

### route

| key | default | description |
|---|---|---|
| `from` | required | the input endpoint: a URI string, or a mapping with `uri`, `parameters` and `steps` |
| `steps` | | more steps, run after the steps under `from` |
| `id` (or `routeId`) | `route1`, `route2`, ... | the route id, used by management, logs and `cameleer get routes` |
| `description` | | free text |
| `group` | | a group name for management |
| `autoStartup` | `true` | `false` creates the route stopped; start it with `cameleer cmd start-route --id ID` |
| `startupOrder` | | an integer; lower numbers start first and stop last |
| `routeConfigurationId` | | the ids of the `routeConfiguration`s to apply, comma separated; `*` patterns match |
| `errorHandler` | the context's | an error handler for this route only (same shape as the top-level [errorHandler](#errorhandler)) |
| `errorHandlerRef` | | the name of an error handler bound in the registry |
| `routePolicy` (or `routePolicyRef`) | | names of `RoutePolicy` beans in the registry, comma separated |
| `inputType`, `outputType` | | `{urn, validate}` data type contracts, see [transformDataType](#message-content) |

Other keys are kept as route properties and do not change behaviour, so a misspelled option
(for example `autostartup`) is silently ignored by the loader. `cameleer validate` reports it.

```yaml
- route:
    id: nightly-report
    description: Builds the nightly report; started by an operator
    group: reports
    autoStartup: false
    from:
      uri: direct:report
      steps:
        - to: mock:report
- route:
    id: always-on
    startupOrder: 10
    from:
      uri: direct:ping
      steps:
        - setBody:
            constant: pong
```

### from: the short form

A route can be written without the `route:` wrapper when it needs no route options:

```yaml
- from:
    uri: direct:short
    steps:
      - setBody:
          simple: "short form: ${body}"
      - to: mock:short
```

### routeConfiguration

A `routeConfiguration` holds error handling and interceptors that several routes share, as
in Camel 4. Its keys:

| key | description |
|---|---|
| `id` | the id routes refer to with `routeConfigurationId` |
| `errorHandler` | an error handler for the routes it applies to |
| `onException` | a list of `- onException:` clauses (see [error handling steps](#error-handling)) |
| `onCompletion` | a list of `- onCompletion:` clauses |
| `intercept`, `interceptFrom`, `interceptSendToEndpoint` | lists of interceptors |
| `precondition`, `description` | accepted and ignored |

Which routes get it:

- a configuration **with** an `id` applies to the routes that list it in
  `routeConfigurationId`;
- a configuration **without** an `id` applies to every route that has no
  `routeConfigurationId`;
- `onException` and the other clauses written directly at top level count as a configuration
  without an `id`.

It does not matter whether the configuration comes before or after the routes in the file.
A `routeConfigurationId` that matches nothing fails at load time.

```yaml
- routeConfiguration:
    id: api-errors
    onException:
      - onException:
          exception:
            - java.lang.IllegalArgumentException
          handled:
            constant: true
          steps:
            - setBody:
                simple: "rejected: ${exception.message}"
            - to: mock:rejected
    onCompletion:
      - onCompletion:
          onCompleteOnly: true
          steps:
            - to: mock:audit
- route:
    id: create-order
    routeConfigurationId: api-errors
    from:
      uri: direct:create-order
      steps:
        - filter:
            simple: "${body} == ''"
            steps:
              - throwException:
                  exceptionType: java.lang.IllegalArgumentException
                  message: empty order
        - setBody:
            simple: "created ${body}"
```

### errorHandler

The top-level `errorHandler` applies to every route of the context; the `errorHandler` key of a
route or a `routeConfiguration` overrides it. It holds exactly one of:

| handler | keys |
|---|---|
| `defaultErrorHandler` | `redeliveryPolicy`, `redeliveryPolicyRef`, `useOriginalMessage`, `useOriginalBody`, `retryWhile`, `onRedeliveryRef`, `onExceptionOccurredRef`, `onPrepareFailureRef` |
| `deadLetterChannel` | `deadLetterUri` (required) plus the keys above and `deadLetterHandleNewException` |
| `noErrorHandler` | none: failures go straight back to the caller |
| `refErrorHandler` | the name of an error handler bound in the registry (or `{ref: name}`) |

`redeliveryPolicy` keys: `maximumRedeliveries` (default 0, `-1` = forever), `redeliveryDelay`
(default 1000 ms), `useExponentialBackOff`, `backOffMultiplier` (default 2),
`maximumRedeliveryDelay`, `useCollisionAvoidance`, `collisionAvoidanceFactor`, `delayPattern`
(`0:1000;5:5000`), `retryAttemptedLogLevel`, `retriesExhaustedLogLevel`, `logStackTrace`,
`logExhausted`, `logRetryAttempted`, `asyncDelayedRedelivery`. Durations take milliseconds or a
unit (`250ms`, `5s`, `PT1M`). Other Camel logging options are accepted and ignored. The
[error handling guide](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html) explains the behaviour.

```yaml
- errorHandler:
    deadLetterChannel:
      deadLetterUri: mock:dead-letters
      useOriginalMessage: true
      redeliveryPolicy:
        maximumRedeliveries: 2
        redeliveryDelay: 10ms
- route:
    id: charge
    from:
      uri: direct:charge
      steps:
        - setBody:
            simple: "charging ${body}"
        - throwException:
            exceptionType: java.io.IOException
            message: payment gateway down
```

### routeTemplate and templatedRoute

A `routeTemplate` is a route with `{{parameter}}` placeholders; a `templatedRoute` creates a
route from it. Templates are read before the other elements, so the order in the file does not
matter.

| `routeTemplate` key | description |
|---|---|
| `id` | required: the template id |
| `parameters` | a list of `{name, defaultValue, required, description}`; a parameter without `defaultValue` is required unless `required: false` |
| `from` (or `route: {from: ...}`) | the route; `{{name}}` and `{{name:default}}` are replaced in every string |
| `beans` | template-local beans, created when the template is used |
| `description` | free text |

| `templatedRoute` key | description |
|---|---|
| `routeTemplateRef` | required: the template id |
| `routeId` | the id of the new route |
| `prefixId` | a prefix added to the `id` of every step |
| `parameters` | a list of `{name, value}` or a plain mapping `{name: value}` |
| `beans` | beans to create for this route |

Placeholders that are not template parameters (`{{env:...}}`, application properties) are left
for the normal property resolution. A missing required parameter fails at load time:
`Route template sensor the following mandatory parameters are missing: room`.

```yaml
- routeTemplate:
    id: sensor
    parameters:
      - name: room
      - name: unit
        defaultValue: C
    from:
      uri: "direct:{{room}}"
      steps:
        - setBody:
            simple: "{{room}}: ${body} {{unit}}"
        - to: mock:readings
- templatedRoute:
    routeTemplateRef: sensor
    routeId: kitchen-sensor
    parameters:
      - name: room
        value: kitchen
- templatedRoute:
    routeTemplateRef: sensor
    routeId: lab-sensor
    parameters:
      room: lab
      unit: K
```

### rest and restConfiguration

The REST DSL declares HTTP operations and hands each request to a route, usually through
`direct:`. `restConfiguration` may appear in any file, before or after the `rest` elements: like
in Camel it is global, and REST routes are built when the context starts.

| `restConfiguration` key | default | description |
|---|---|---|
| `component` | `platform-http` | the HTTP server component |
| `host`, `port` | `camel.server.port` (8080) | where to listen |
| `contextPath` | | a prefix for every path, for example `/api` |
| `bindingMode` | `off` | `json`, `xml`, `json_xml`, `auto` or `off` |
| `scheme` | `http` | `http` or `https` |
| `apiContextPath` | | serve the OpenAPI document at this path (turns `apiDocs` on) |
| `apiDocs`, `enableCORS`, `skipBindingOnErrorCode` | | booleans |
| `corsHeaders`, `apiProperty`, `endpointProperty`, `consumerProperty` | | lists of `{key, value}` |

| `rest` key | description |
|---|---|
| `path` | the base path of the operations |
| `get`, `post`, `put`, `delete`, `patch`, `head`, `options` | lists of operations |
| `verb` | operations with an explicit `method` |
| `consumes`, `produces`, `bindingMode`, `description`, `tag` | defaults for the operations |

Each operation takes `path`, `to` (a URI, or `{uri, parameters}`; `toD` is accepted),
`id` (the route id), `description`, `consumes`, `produces`, `bindingMode`, `type`, `outType`,
`param` (a list of `{name, type: path|query|header|body|formData, required, dataType,
defaultValue, description, allowableValues}`), `responseMessage` (a list of `{code, message}`),
`apiDocs` and `deprecated`. Path parameters such as `{id}` become headers. Operations route
with `to`; they do not take inline steps.

```yaml
- restConfiguration:
    contextPath: /api
- rest:
    path: /orders
    get:
      - path: /{id}
        id: get-order
        produces: application/json
        to: direct:get-order
    post:
      - to: direct:create-order
- route:
    from:
      uri: direct:get-order
      steps:
        - setBody:
            simple: '{"id": "${header.id}", "status": "shipped"}'
- route:
    from:
      uri: direct:create-order
      steps:
        - setHeader:
            name: CamelHttpResponseCode
            constant: 201
        - setBody:
            simple: "created ${body}"
```

`GET /api/orders/42` returns `{"id": "42", "status": "shipped"}`; `POST /api/orders` returns
status 201. See the [REST component](https://pmsudhi.github.io/cameleer/docs/components/rest.html) for binding and OpenAPI.

### beans

A `beans` element is a list of `{name, type, properties}`. Rust cannot create Java classes by name, so a bean is created only when a bean factory is
registered for its `type` (`cameleer_yaml::register_bean_factory`) by a program that embeds
Cameleer. The `cameleer` binary registers no factories: it records the definition and logs
`No bean factory registered for bean 'greeter'`. To use processors, aggregation strategies or
repositories from YAML, bind them from Rust (`ctx.registry().bind_processor(...)`) and refer to
them by name; built-in aggregation strategies work by name without any bean (see
[split](#split-aggregate-and-reorder)).

```yaml
- beans:
    - name: greeter
      type: com.acme.Greeter
      properties:
        prefix: Hello
- route:
    from:
      uri: direct:beans
      steps:
        - to: mock:beans
```

### Kamelets and Pipes

A Kamelet is a reusable route snippet with typed properties. Use one as a source
(`from: kamelet:name?...`), a sink or an action (`to: kamelet:name?...`, or the `kamelet`
step). Built-in Kamelets: `timer-source`, `log-sink`, `log-action`, `insert-header-action` and
`set-body-action`; files in `./kamelets/` add more.

```yaml
- route:
    from:
      uri: kamelet:timer-source
      parameters:
        message: Hello from a Kamelet
        period: 100
        repeatCount: 1
      steps:
        - kamelet:
            name: insert-header-action
            parameters:
              name: origin
              value: kamelet
        - to: mock:from-kamelet
```

A Kamelet file (`greeting-source.kamelet.yaml`) is a resource, not a list of routes. Its
template uses `{{property}}` placeholders, filled from the URI parameters, then
`camel.kamelet.<name>.<property>` properties, then the declared `default`; `{{?property}}`
drops the option when it has no value:

```yaml
apiVersion: camel.apache.org/v1
kind: Kamelet
metadata:
  name: greeting-source
  labels:
    camel.apache.org/kamelet.type: source
spec:
  definition:
    required:
      - message
    properties:
      message:
        type: string
      period:
        type: integer
        default: 1000
  template:
    from:
      uri: timer:greeting
      parameters:
        period: "{{period}}"
      steps:
        - setBody:
            simple: "{{message}}"
        - to: kamelet:sink
```

A Pipe (`orders.pipe.yaml`) binds a source to a sink, with optional steps in between, and
becomes a route whose id is `metadata.name`. Each endpoint is a Kamelet `ref` with
`properties` or a plain `uri`; `spec.errorHandler` takes `sink`, `log` or `none`:

```yaml
apiVersion: camel.apache.org/v1
kind: Pipe
metadata:
  name: greetings-pipe
spec:
  source:
    ref:
      kind: Kamelet
      apiVersion: camel.apache.org/v1
      name: timer-source
    properties:
      message: Hello from a Pipe
      period: 100
      repeatCount: 1
  steps:
    - ref:
        kind: Kamelet
        apiVersion: camel.apache.org/v1
        name: set-body-action
      properties:
        value: "piped: ${body}"
  sink:
    uri: mock:piped
```

`cameleer bind my-pipe --source timer-source --sink log-sink` writes the Pipe file `my-pipe.yaml`
(`--output FILE` picks another name). The
[Kamelets section](https://pmsudhi.github.io/cameleer/docs/guides/eips/system.html#kamelets) of the EIP guide has more.

## Endpoints

An endpoint is a URI: `scheme:path?option=value&option=value`. Each component's page lists its
options: [docs/components/](https://pmsudhi.github.io/cameleer/docs/components/index.html) (for example [kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html)), and
`cameleer catalog components` lists every scheme. Unknown options fail when the route starts,
exactly like Apache Camel: `There are 1 parameters that couldn't be set on the endpoint ...
Unknown parameters=[perod]`.

Two equivalent ways to write options:

```yaml
- route:
    from:
      uri: direct:forms
      steps:
        # inline: the whole URI in one string
        - to: "seda:inline?size=100&blockWhenFull=true"
        # uri + parameters: easier to read, values are URL-encoded for you
        - to:
            uri: seda:mapped
            parameters:
              size: 100
              blockWhenFull: true
        - to: mock:forms
```

- With `parameters`, values are URL-encoded (spaces, `&`, `+`, `=` are safe), except values
  that contain `{{`, `${` or start with `RAW(`, which are passed as they are. A list value is
  joined with commas.
- In an inline URI you encode values yourself; `+` means a space. To pass a value exactly as
  written (passwords, regular expressions), wrap it in `RAW(...)`:
  `password=RAW(se+cr&t)`. `RAW{...}` works too when the value contains `)`.
- `from` takes the same forms: `from: {uri: ..., parameters: {...}, steps: [...]}`.
- Quote a URI when it contains `#` after a space, `: ` (colon and space), or starts with `{`,
  `*`, `&`, `!`, `%` or `@`; quoting is always safe.

```yaml
- route:
    from:
      uri: direct:raw
      steps:
        - to: "log:audit?marker=RAW(a+b&c)"
        - to:
            uri: log:audit-mapped
            parameters:
              marker: "a+b&c"
        - to: mock:raw
```

### Property placeholders

Any string (URIs, step options, expressions) can contain placeholders, resolved when the route
is created:

| placeholder | value |
|---|---|
| `{{name}}` | the property `name` from `application.properties`/`application.yaml`, `--prop`, `CAMEL_*` environment variables, or `CAMEL_PROPERTY_NAME`; fails when missing |
| `{{name:default}}` | the same, with a default (everything after the first `:`, so `{{broker:localhost:9092}}` works) |
| `{{env:NAME}}`, `{{env:NAME:default}}` | the environment variable `NAME` |
| `{{sys:NAME}}` | the environment variable `NAME` (there are no JVM system properties) |
| `{{aws:...}}`, `{{azure:...}}`, `{{gcp:...}}` | secrets from a cloud vault, see [cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html) |

```yaml
- route:
    from:
      uri: "timer:config?period={{poll.period:200}}&repeatCount=1"
      steps:
        - setBody:
            simple: "{{greeting:Hello}} from {{env:SITE_NAME:the lab}}"
        - to: mock:configured
```

A value that **starts** with `{{` must be quoted (`"{{broker}}"`), otherwise YAML reads it as a
flow mapping. Never write secrets in route files: use `{{env:...}}` or a vault.

### Sending to endpoints

| step | keys | description |
|---|---|---|
| `to` | a URI string, or `uri`, `parameters`, `pattern` (`InOnly`/`InOut`) | send the message and continue with the reply |
| `toD` | the same plus `ignoreInvalidEndpoint` (default `false`) | a dynamic URI, evaluated with Simple per message |
| `inOnly`, `inOut` | like `to` | `to` with a fixed exchange pattern (deprecated in Camel 4, kept for old routes) |
| `wireTap` | URI or `uri`/`parameters`, `copy` (default `true`), `body`, `setHeader` (list of `{name, <expression>}`), `onPrepare`, `ignoreInvalidEndpoint` | send a copy asynchronously and continue at once |
| `enrich` | URI, `uri`/`parameters`, or an expression; `aggregationStrategy`, `aggregateOnException`, `ignoreInvalidEndpoint`, `shareUnitOfWork` | call an endpoint and merge its reply (default: the reply replaces the message) |
| `pollEnrich` | like `enrich`, plus `timeout` (ms; default `-1` = wait) | consume one message from an endpoint (file, seda, ...) and merge it |
| `poll` | URI or `uri`/`parameters`, `timeout` (default 20000; whole milliseconds only, a unit such as `2s` is rejected) | consume one message and make it the message |
| `kamelet` | a name, or `name` and `parameters` | send to `kamelet:name` |
| `bean` | `ref` (or `beanType`), `method`, `scope` | call a bean bound in the registry (`bean:` endpoint) |
| `process` | a name, or `ref` | run a processor bound in the registry |
| `serviceCall` | `name`, `uri`, `component`, `pattern`, `expression`, `staticServiceDiscovery`, `serviceDiscoveryRef`, filters, `randomLoadBalancer`/`roundRobinLoadBalancer` | call a named service through a load balancer |

`uri` values with `${...}` need `toD`; `to` treats the URI as fixed text.

`pollEnrich` and `poll` consume from an endpoint in the middle of a route, for example a
message waiting on a queue or a file in a folder:

```yaml
- route:
    from:
      uri: direct:with-config
      steps:
        - pollEnrich:
            uri: seda:latest-config
            timeout: 2000
        - setBody:
            simple: "config is ${body}"
        - to: mock:configured-call
- route:
    from:
      uri: direct:next-job
      steps:
        - poll:
            uri: seda:jobs
            timeout: 2000
        - to: mock:job
```

```yaml
- route:
    from:
      uri: direct:dispatch
      steps:
        - wireTap: mock:audit-copy
        - enrich:
            uri: direct:price-lookup
        - toD: "mock:region-${header.region}"
- route:
    from:
      uri: direct:price-lookup
      steps:
        - setBody:
            simple: "${body} costs 42"
```

## Expressions and predicates

Steps such as `setBody`, `filter`, `split` and `choice`/`when` take an expression (a value) or
a predicate (an expression whose result is read as true or false). Every form below works
wherever a step takes one.

| form | example | meaning |
|---|---|---|
| short | `simple: "${body.length()}"` | a language key and the expression text |
| long | `simple: {expression: "${header.n}", resultType: int}` | the text plus language options |
| wrapped | `expression: {simple: "${body}"}` | the Camel schema's explicit form (also `expression: {constant: x}`) |
| plain string | `setBody: "Hello ${body}"` | a Simple expression |
| plain number or boolean | `setBody: 42` | a constant |
| generic language | `language: {language: groovy, expression: "..."}` | any registered language by name |

A step may name only one language key; two (for example `simple` and `constant`) fail with
`only one expression language may be specified`. Language options in the long form (for
example `resultType`, `trim`, `headerName`, `source`, `suppressExceptions`) are passed to the
language.

```yaml
- route:
    from:
      uri: direct:forms-of-expressions
      steps:
        - setHeader:
            name: short
            simple: "${body.toUpperCase()}"
        - setHeader:
            name: typed
            simple:
              expression: "${body.length()}"
              resultType: java.lang.Integer
        - setHeader:
            name: wrapped
            expression:
              constant: fixed
        - setHeader:
            name: plain
            expression: "plain ${body}"
        - setBody: "Hello ${body}"
        - to: mock:expressions
```

### Language keys

| key | language | notes |
|---|---|---|
| `simple` | [Simple](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) | the default; `${body}`, `${header.x}`, operators, functions |
| `constant` | [Constant](https://pmsudhi.github.io/cameleer/docs/languages/constant.html) | a fixed value |
| `header` | [Header](https://pmsudhi.github.io/cameleer/docs/languages/header.html) | the value of a header: `header: orderId` |
| `exchangeProperty` | [Exchange property](https://pmsudhi.github.io/cameleer/docs/languages/exchangeProperty.html) | the value of an exchange property |
| `variable` | [Variable](https://pmsudhi.github.io/cameleer/docs/languages/variable.html) | the value of a variable |
| `jsonpath` | [JSONPath](https://pmsudhi.github.io/cameleer/docs/languages/jsonpath.html) | `jsonpath: "$.items[*].sku"` |
| `jq` | [jq](https://pmsudhi.github.io/cameleer/docs/languages/jq.html) | `jq: ".items \| length"` |
| `xpath` | [XPath](https://pmsudhi.github.io/cameleer/docs/languages/xpath.html) | XPath 1.0 |
| `xquery` | [XQuery](https://pmsudhi.github.io/cameleer/docs/languages/xquery.html) | |
| `tokenize` | [Tokenize](https://pmsudhi.github.io/cameleer/docs/languages/tokenize.html) | `tokenize: ","` or `tokenize: {token: ",", group: 10}` |
| `method` | [Bean method](https://pmsudhi.github.io/cameleer/docs/languages/bean.html) | a bean in the registry |
| `ref` | [Ref](https://pmsudhi.github.io/cameleer/docs/languages/ref.html) | an expression bound in the registry |
| `groovy`, `js`/`javaScript`, `python`, `mvel`, `ognl`, `spel`, `datasonnet`, `csimple`, `joor`/`java` | script languages, for example [groovy](https://pmsudhi.github.io/cameleer/docs/languages/groovy.html) and [python](https://pmsudhi.github.io/cameleer/docs/languages/python.html) | interpreters from `cameleer-script` |
| `hl7terser` | [HL7 terser](https://pmsudhi.github.io/cameleer/docs/languages/hl7terser.html) | |
| `language` | any | `language: {language: <name>, expression: ...}` |

`cameleer catalog languages` lists the languages of your build. The loader also accepts the
keys `xtokenize` and `wasm`, but no language of those names is built in, so a route that uses
them fails when it starts.

```yaml
- route:
    from:
      uri: direct:languages
      steps:
        - setProperty:
            name: source
            constant: sensor-7
        - setHeader:
            name: firstSku
            jsonpath: "$.items[0].sku"
        - setHeader:
            name: count
            jq: ".items | length"
        - setHeader:
            name: from
            exchangeProperty: source
        - setHeader:
            name: copy
            header: firstSku
        - to: mock:languages
```

### Predicates

A predicate is an expression read as a boolean. Simple predicates use operators: `==`, `!=`,
`>`, `>=`, `<`, `<=`, `contains`, `not contains`, `startsWith`, `endsWith`, `regex`, `in`,
`range`, `is`, and `&&` / `||` to combine them. Quote string literals inside Simple with single
quotes: `${header.type} == 'gold'`. Any language works as a predicate (`jsonpath`, `jq`,
`xpath`, ...). The result is read as in Camel: a boolean is its value; a string is false only
when it is `false` (any case), so even an empty string is true; a list is true when it is not
empty; `null` is false; anything else (numbers, including `0`) is true.

## Steps

Every step is a list item with one key. Keys every step accepts:

- `id`: names the step (shown by `cameleer get routes` and in statistics; also applies to
  `when` and `otherwise`).
- `disabled: true`: skips the step, as if it were not there.

A step with no options can be written as a bare name (`- stop`) or with an empty mapping
(`- stop: {}`). Steps that contain other steps (`filter`, `split`, `doTry`, ...) take a
`steps` list, indented under the step's own keys. Unknown keys of a step are ignored by the
loader; [`cameleer validate`](https://pmsudhi.github.io/cameleer/docs/guides/validate.html) reports them.

The tables below give each step's keys and defaults. The EIP guides explain the patterns in
depth: [routing](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html), [split and aggregate](https://pmsudhi.github.io/cameleer/docs/guides/eips/split-aggregate.html),
[transformation](https://pmsudhi.github.io/cameleer/docs/guides/eips/transformation.html), [flow control](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html),
[interceptors, completions and templates](https://pmsudhi.github.io/cameleer/docs/guides/eips/system.html), and
[error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html).

### Message content

| step | keys | description |
|---|---|---|
| `setBody` | an expression | replace the body |
| `transform` | an expression | the same as `setBody` (the Message Translator name) |
| `setHeader` | `name`, an expression | set one header |
| `setHeaders` | `headers`: a list of `{name, <expression>}` | set several headers in order |
| `setProperty` | `name`, an expression | set an exchange property |
| `setVariable` | `name`, an expression | set a variable |
| `setVariables` | `variables`: a list of `{name, <expression>}` | set several variables |
| `removeHeader` | a name, or `name` | remove one header |
| `removeHeaders` | a pattern, or `pattern` and `excludePattern` (list or comma separated) | remove matching headers (`*` wildcards or a regex) |
| `removeProperty`, `removeProperties` | like the header steps | remove exchange properties |
| `removeVariable` | a name, or `name` | remove a variable |
| `convertBodyTo` | a type, or `type`, `mandatory` (default `false`) | convert the body: `String`, `Integer`, `Long`, `Double`, `Boolean`, `byte[]`, Java names like `java.lang.String` |
| `convertHeaderTo` | `name`, `type`, `mandatory` | convert a header |
| `marshal`, `unmarshal` | a data format: `json: {}`, `csv: {delimiter: ";"}`, `custom: {ref: name}`, or a plain name (`- marshal: json`) | object to text/bytes and back; see [data formats](https://pmsudhi.github.io/cameleer/docs/dataformats/index.html) |
| `transformDataType` | `toType`, `fromType` | apply a registered data type transformer |
| `script` | an expression | run a script; its result is discarded, its changes to the message are kept |
| `log` | a Simple message, or `message`, `loggingLevel` (default `INFO`), `logName`, `marker` | log a line |
| `setExchangePattern` | `InOnly` or `InOut` (or `pattern`) | change the exchange pattern |
| `claimCheck` | `operation` (`Set`, `Get`, `GetAndRemove`, `Push`, `Pop`), `key`, `filter` | store part of the message and get it back later |
| `sort` | an expression, `comparator` | sort a list body |

```yaml
- route:
    from:
      uri: direct:message
      steps:
        - setHeaders:
            headers:
              - name: customer
                simple: "${body[customer]}"
              - name: tmpTrace
                constant: "abc"
        - setProperty:
            name: total
            simple: "${body[total]}"
        - setVariable:
            name: greeting
            constant: Dear
        - removeHeaders:
            pattern: "tmp*"
        - marshal:
            json: {}
        - convertBodyTo: String
        - log:
            message: "order JSON: ${body}"
            loggingLevel: DEBUG
            logName: orders
        - setBody:
            simple: "${variable.greeting} ${header.customer}, total ${exchangeProperty.total}"
        - to: mock:message
```

```yaml
- route:
    from:
      uri: direct:more-message-steps
      steps:
        - setVariables:
            variables:
              - name: unit
                constant: kg
              - name: tmp
                constant: scratch
        - removeVariable: tmp
        - convertHeaderTo:
            name: weight
            type: Integer
        - claimCheck:
            operation: Push
        - transform:
            simple: "${header.weight} ${variable.unit}"
        - to: mock:weight
        - claimCheck:
            operation: Pop
        - sort:
            simple: "${body}"
        - to: mock:sorted
```

### Routing

| step | keys | description |
|---|---|---|
| `filter` | a predicate, `steps` | run the steps only for matching messages; others continue after the filter |
| `choice` | `when` (list of `{<predicate>, steps}`), `otherwise` (`{steps}` or a list), `precondition` | the first matching `when` runs; otherwise `otherwise` |
| `multicast` | `steps`, `parallelProcessing`, `aggregationStrategy`, `stopOnException`, `streaming`, `timeout`, `shareUnitOfWork` | send a copy of the message to each step |
| `recipientList` | an expression, `delimiter` (default `,`), `ignoreInvalidEndpoints`, plus the multicast keys | send to the endpoints the expression returns |
| `routingSlip` | an expression, `uriDelimiter` (default `,`), `ignoreInvalidEndpoints` | send through the endpoints one after another |
| `dynamicRouter` | an expression, `uriDelimiter`, `ignoreInvalidEndpoints` | ask the expression for the next endpoint until it returns nothing |
| `loadBalance` | one policy (`roundRobin`, `random`, `topic`, `sticky: {correlationExpression}`, `weighted: {distributionRatio, roundRobin}`, `failover: {exception, maximumFailoverAttempts, roundRobin, sticky}`, `custom: {ref}`), `steps` | send each message to one of the steps (default `roundRobin`) |
| `loop` | an expression (a count, or a predicate with `doWhile: true`), `copy` (default `false`), `steps` | repeat the steps; `CamelLoopIndex` holds the index |
| `pipeline` | `steps` | run steps in sequence (useful inside `multicast`) |
| `step` | `steps`, `id` | group steps under one id for statistics |
| `stop` | none | stop routing this message |

```yaml
- route:
    from:
      uri: direct:tickets
      steps:
        - choice:
            when:
              - simple: "${header.priority} == 'P1'"
                steps:
                  - to: mock:page-oncall
              - simple: "${header.priority} == 'P2'"
                steps:
                  - to: mock:team-queue
            otherwise:
              steps:
                - to: mock:backlog
        - filter:
            simple: "${header.priority} == 'P3'"
            steps:
              - stop
        - to: mock:escalated
```

```yaml
- route:
    from:
      uri: direct:fan-out
      steps:
        - multicast:
            aggregationStrategy: groupedBody
            steps:
              - pipeline:
                  steps:
                    - setBody:
                        simple: "email:${body}"
              - pipeline:
                  steps:
                    - setBody:
                        simple: "sms:${body}"
        - to: mock:fanned-out
        - loop:
            constant: 3
            steps:
              - setBody:
                  simple: "attempt ${exchangeProperty.CamelLoopIndex}"
              - to: mock:loop
        - loadBalance:
            roundRobin: {}
            steps:
              - to: mock:node-a
              - to: mock:node-b
```

```yaml
- route:
    from:
      uri: direct:notify
      steps:
        # endpoints listed in a header, comma separated
        - recipientList:
            simple: "${header.channels}"
- route:
    from:
      uri: direct:photo
      steps:
        # the endpoints in turn, each one's output feeding the next
        - routingSlip:
            header: slip
- route:
    from:
      uri: direct:resize
      steps:
        - setBody:
            simple: "${body}-resized"
```

### Split, aggregate and reorder

| step | keys | description |
|---|---|---|
| `split` | an expression, `steps`, `aggregationStrategy`, `parallelProcessing`, `streaming`, `stopOnException`, `timeout`, `shareUnitOfWork`, `delimiter` (default `,`, `"false"` to keep a string whole) | run the steps once per part; parts get `CamelSplitIndex`, `CamelSplitSize`, `CamelSplitComplete` |
| `aggregate` | `correlationExpression` (required), `aggregationStrategy` (required), `completionSize`, `completionTimeout`, `completionInterval`, `completionPredicate`, `completionSizeExpression`, `completionTimeoutExpression`, `completionFromBatchConsumer`, `completionOnNewCorrelationGroup`, `eagerCheckCompletion`, `forceCompletionOnStop`, `discardOnCompletionTimeout`, `ignoreInvalidCorrelationKeys`, `closeCorrelationKeyOnCompletion`, `aggregationRepository`, `steps` | combine related messages into one |
| `resequence` | an expression, `batchConfig: {batchSize: 100, batchTimeout: 1000, allowDuplicates, reverse, ignoreInvalidExchanges}` or `streamConfig: {capacity: 1000, timeout: 1000, rejectOld, ignoreInvalidExchanges}`, `steps` | put messages back in order |

`aggregationStrategy` takes the name of a strategy bound in the registry, or a built-in one:
`groupedBody` (a list of bodies), `groupedExchange`, `useLatest`, `useOriginal`, `string`
(concatenate), also written with Camel class names such as
`#class:org.apache.camel.processor.aggregate.GroupedBodyAggregationStrategy`. Without a
strategy, `split` continues with the original message, as in Camel.

```yaml
- route:
    from:
      uri: direct:csv-lines
      steps:
        - split:
            tokenize: "\n"
            aggregationStrategy: groupedBody
            steps:
              - setBody:
                  simple: "${body.toUpperCase()}"
              - to: mock:each-line
        - to: mock:all-lines
- route:
    from:
      uri: direct:readings
      steps:
        - aggregate:
            correlationExpression:
              header: device
            aggregationStrategy: groupedBody
            completionSize: 2
            completionTimeout: 5s
            steps:
              - to: mock:device-batch
```

```yaml
- route:
    from:
      uri: direct:out-of-order
      steps:
        - resequence:
            header: seq
            batchConfig:
              batchSize: 3
              batchTimeout: 200
            steps:
              - to: mock:in-order
```

### Error handling

| step | keys | description |
|---|---|---|
| `doTry` | `steps`, `doCatch` (list of `{exception: [...], onWhen, steps}`), `doFinally` (`{steps}`) | try/catch/finally inside a route |
| `onException` | `exception` (list of kinds), `handled`, `continued`, `onWhen`, `retryWhile`, `redeliveryPolicy`, `redeliveryPolicyRef`, `useOriginalMessage`, `useOriginalBody`, `onRedeliveryRef`, `onExceptionOccurredRef`, `steps` | react to a kind of failure; as a route step it applies to that route, in a `routeConfiguration` to many |
| `onCompletion` | `onCompleteOnly`, `onFailureOnly`, `mode` (`AfterConsumer` default, `BeforeConsumer`), `onWhen`, `steps` | run steps when the exchange finishes |
| `circuitBreaker` | `steps`, `onFallback` (`{steps}`), `resilience4jConfiguration` (`failureRateThreshold`, `minimumNumberOfCalls`, `slidingWindowSize`, `waitDurationInOpenState` in seconds, `permittedNumberOfCallsInHalfOpenState`, `timeoutEnabled`, `timeoutDuration`), `faultToleranceConfiguration`, `configuration` (a registry name) | stop calling a failing service for a while |
| `throwException` | `exceptionType` (required), `message` | fail the exchange with that kind of exception |
| `validate` | a predicate | fail with `PredicateValidationException` when it is false |
| `rollback` | a message, or `message`, `markRollbackOnly`, `markRollbackOnlyLast` | roll back the current transaction |
| `transacted` | a policy name, or `ref`; `steps` | run in a transaction (without `steps`: the rest of the route) |
| `policy` | `ref`, `steps` | wrap steps in a registered policy (without `steps`: the rest of the route) |
| `saga` | `propagation`, `completionMode`, `timeout`, `compensation`, `completion`, `option` (list of `{key, <expression>}`), `sagaService`, `steps` | a long-running transaction with compensation |
| `intercept`, `interceptFrom`, `interceptSendToEndpoint` | `onWhen`, `steps`; `interceptFrom` takes `uri` (default `*`); `interceptSendToEndpoint` takes `uri` (required) and `skipSendToOriginalEndpoint` | run steps before every step, every input, or every send to matching endpoints (usually in a `routeConfiguration`) |

Exception kinds are Camel's Java class names; the package is ignored, so
`java.lang.IllegalArgumentException` and `IllegalArgumentException` are the same. A kind matches
its subkinds (`java.lang.Exception` catches everything). `handled` and `continued` take `true`,
`false`, `{constant: true}` or a predicate.

```yaml
- route:
    from:
      uri: direct:fragile
      steps:
        - onException:
            exception:
              - java.io.IOException
            redeliveryPolicy:
              maximumRedeliveries: 1
              redeliveryDelay: 0
            handled:
              constant: true
            steps:
              - setBody:
                  constant: "service unavailable, queued"
              - to: mock:retry-later
        - doTry:
            steps:
              - validate:
                  simple: "${body} != 'bad'"
            doCatch:
              - exception:
                  - org.apache.camel.support.processor.validation.PredicateValidationException
                steps:
                  - setBody:
                      constant: "replaced a bad message"
            doFinally:
              steps:
                - to: mock:checked
        - circuitBreaker:
            steps:
              - filter:
                  simple: "${body} == 'boom'"
                  steps:
                    - throwException:
                        exceptionType: java.lang.IllegalStateException
                        message: downstream failed
            onFallback:
              steps:
                - setBody:
                    constant: "fallback answer"
        - filter:
            simple: "${body} == 'offline'"
            steps:
              - throwException:
                  exceptionType: java.io.IOException
                  message: disk offline
        - to: mock:fragile-done
```

Interceptors and completions are usually written once, at top level or in a
`routeConfiguration`, and apply to every route without `routeConfigurationId`:

```yaml
- interceptSendToEndpoint:
    uri: "mock:legacy*"
    skipSendToOriginalEndpoint: true
    steps:
      - setBody:
          simple: "redirected ${body}"
      - to: mock:modern
- onCompletion:
    onFailureOnly: true
    steps:
      - to: mock:failures
- route:
    from:
      uri: direct:intercepted
      steps:
        - to: mock:legacy-system
        - filter:
            simple: "${body} contains 'fail'"
            steps:
              - throwException:
                  exceptionType: java.lang.IllegalStateException
                  message: failed on purpose
```

### Flow control

| step | keys | description |
|---|---|---|
| `throttle` | a constant expression or `maximumRequests`, `timePeriodMillis` (default 1000), `correlationExpression`, `rejectExecution`, `asyncDelayed` | at most N messages per period |
| `delay` | an expression (milliseconds), `asyncDelayed` (default `true`) | wait before continuing |
| `sample` | a period, or `samplePeriod` (default 1 s) or `messageFrequency` | let one message through per period or per N messages |
| `idempotentConsumer` | an expression (the message id), `steps`, `idempotentRepository` (default: in memory, 1000 ids), `eager` (`true`), `skipDuplicate` (`true`), `removeOnFailure` (`true`), `completionEager` (`false`) | process each id once |
| `threads` | `poolSize`, `maxPoolSize`, `keepAliveTime` (+ `timeUnit`, default seconds), `maxQueueSize`, `allowCoreThreadTimeOut`, `rejectedPolicy`, `callerRunsWhenRejected`, `threadName`, `executorService`, `steps` | continue on a thread pool (without `steps`: the rest of the list) |

```yaml
- route:
    from:
      uri: direct:events
      steps:
        - idempotentConsumer:
            header: eventId
            steps:
              - throttle:
                  constant: 100
                  timePeriodMillis: 1000
              - delay:
                  constant: 10
              - to: mock:unique-events
```

## Values: booleans, numbers and durations

- Booleans are `true` and `false` (any case). YAML 1.2 is used, so `yes`, `no`, `on` and
  `off` are strings: a boolean option set to `yes` fails with `'yes' is not a boolean`, and
  `disabled: yes` does not disable the step. Placeholders work: `autoStartup: "{{orders.enabled:true}}"`.
- Numbers can be written plain (`completionSize: 10`) or quoted (`"10"`).
- Durations (`completionTimeout`, `redeliveryDelay`, `timePeriodMillis`, `timeout`, ...) are
  milliseconds when plain (`5000`), or take a unit: `250ms`, `5s`, `1m`, `PT1M`. The
  exception is the `timeout` of `poll`, which takes whole milliseconds only.
  `waitDurationInOpenState` of `resilience4jConfiguration` and `keepAliveTime` of `threads`
  are in seconds, as in Camel.
- Endpoint option values are text: `period: 1000` and `period: "1000"` are the same.

## Ids and descriptions

- Route ids: `id` on the route; a missing id becomes `route1`, `route2`, ... Ids must be unique
  in the context, across all files.
- Step ids: `id` on any step, `when` or `otherwise`. With `prefixId`, a `templatedRoute` adds a
  prefix to each.
- `description` on a route is kept for management; on a step it is ignored.

## Common mistakes

**`steps` at the wrong indentation.** `steps` belongs under `from` (at the same level as
`uri`) or under `route`; nested `steps` belong under their own step, at the level of its other
keys. Indentation decides which mapping a key belongs to:

```text
- route:
    from:
      uri: direct:a
      steps:           # right: under from, aligned with uri
        - to: mock:b
- route:
    from:
      uri: direct:c
  steps:               # wrong: a second key of the list item, rejected with
    - to: mock:d       # "Each top-level element must have exactly one key"
- route:
    from:
      uri: direct:e
      steps:
        - filter:
            simple: "${body} == 'x'"
          steps:       # wrong: a second key of the step, rejected with
            - to: mock:f   # "A step must have exactly one key"
```

**Two keys in one step.** Each list item is one step. Writing an option at the step level
fails with `A step must have exactly one key`:

```text
- to: mock:a
  pattern: InOut       # wrong: belongs under `to`
- to:
    uri: mock:a
    pattern: InOut     # right
```

**Unquoted special characters.** These need quotes:

| value | why | write |
|---|---|---|
| `log: Status: ${body}` | `: ` starts a mapping | `log: "Status: ${body}"` |
| `simple: Order #${body}` | ` #` starts a comment | `simple: "Order #${body}"` |
| `simple: {"id": 1}` | `{` starts a flow mapping | `simple: '{"id": 1}'` |
| `uri: {{broker}}` | `{{` starts a flow mapping | `uri: "{{broker}}"` |
| `constant: 007` | a number (7) | `constant: "007"` |
| `constant: true` | a boolean, not text | `constant: "true"` |

Single quotes keep backslashes and `${...}` literally (`'a\nb'` is four characters); double
quotes process escapes (`"a\nb"` has a line break). Use double quotes for `tokenize: "\n"`.

**`${...}` in a `to` URI.** `to` sends to the URI as written; use `toD` for a URI built from the
message.

**Booleans as words.** `yes`, `on` and `off` are not booleans (see [values](#values-booleans-numbers-and-durations)).

**`:` in URIs.** Plain URIs like `timer:tick?period=1000` need no quotes: a colon only matters
when a space follows it. Quote a URI that contains `: ` or `#`.

**Expecting `split` to return the parts.** Without `aggregationStrategy`, the message after a
`split` is the original one.

**Two expression languages in one step.** `setBody: {simple: ..., constant: ...}` fails; pick
one.

## Differences from Apache Camel

- Same element names, step names and option names as the Camel 4 YAML DSL; old Camel 3 shapes
  that the loader still reads: `expression: "text"` (Simple), `routeTemplates`/`templatedRoutes`,
  `inOnly`/`inOut`.
- Extra short forms: `setBody: "text"` (a Simple expression), `tokenize: ","`, steps as bare
  names (`- stop`), and a route mapping with `from` but without the `route:` wrapper.
- Beans of Java classes are not instantiated (see [beans](#beans)); processors and strategies are
  bound from Rust.
- `throttle` needs a constant maximum; `interceptSendToEndpoint` `afterUri` is ignored with a
  warning; `dataFormats` at top level is stored but not used; unknown step keys are ignored
  (Camel's schema rejects them); `cameleer validate` reports them.
- The loader uses YAML 1.2 (like Camel's snakeyaml-engine), so `yes`/`no` are strings.

## Common questions

### How do I write a Camel route in YAML?

Create a file ending in `.camel.yaml` with a list containing one `- route:`, give it a `from`
with a `uri` and a `steps` list, and run `cameleer run file.camel.yaml`. Start from the
[first look](#a-first-look) example.

### Can I run my Apache Camel YAML routes unchanged?

Yes when they use components and options Cameleer supports: the element, step and option names
are the same. Java beans and processors must be rewritten in Rust. `cameleer validate` tells
you what does not resolve; see [migrating from Apache Camel](https://pmsudhi.github.io/cameleer/docs/guides/migrating-from-apache-camel.html).

### How do I load all route files of a folder?

`cameleer run folder/*.camel.yaml`, or set `camel.main.routes-include-pattern=folder/**/*.camel.yaml`.
With no arguments, `cameleer run` loads the route files of the current folder.

### How do I share error handling between routes?

Put `onException` clauses and an `errorHandler` in a `routeConfiguration`. Without an `id` it
applies to every route; with an `id`, list it in each route's `routeConfigurationId`.

### Is there a JSON Schema for editors?

Yes: `cameleer schema > cameleer.schema.json` prints a JSON Schema of the YAML DSL that editors
(VS Code with the YAML extension, IntelliJ) use for completion and checks. Setup steps are in
[editor support](https://pmsudhi.github.io/cameleer/docs/guides/validate.html#editor-support); `cameleer validate` covers what a schema cannot,
such as endpoint options and expressions.

## Related

- [YAML for coding agents](https://pmsudhi.github.io/cameleer/docs/guides/yaml-for-coding-agents.html) and [`cameleer validate`](https://pmsudhi.github.io/cameleer/docs/guides/validate.html)
- [Getting started](https://pmsudhi.github.io/cameleer/docs/guides/getting-started.html), [concepts](https://pmsudhi.github.io/cameleer/docs/guides/concepts.html), [EIP guide](https://pmsudhi.github.io/cameleer/docs/guides/eips.html),
  [error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html)
- [Components](https://pmsudhi.github.io/cameleer/docs/components/index.html), [languages](https://pmsudhi.github.io/cameleer/docs/languages/index.html), [data formats](https://pmsudhi.github.io/cameleer/docs/dataformats/index.html)
- Apache Camel: [YAML DSL](https://camel.apache.org/components/next/others/yaml-dsl.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/eips.html

# Enterprise Integration Patterns in Cameleer

> Cameleer implements Apache Camel's Enterprise Integration Patterns (EIPs) with the same names,
> options and semantics; this page lists every one and links to a tested YAML example and its
> Rust DSL equivalent.

An EIP is a named solution to a messaging problem: filter, route, split, aggregate, retry. In a
route each EIP is a step. The YAML names are Camel's (`split`, `aggregate`, `circuitBreaker`);
the Rust DSL uses snake_case (`split`, `aggregate`, `circuit_breaker`) and closes blocks with
`.end()`. Every example on the linked pages runs twice in the test suite, once as YAML and once
as Rust, against the same assertions (`crates/cameleer-main/tests/docs_guides.rs`).

## Routing

| EIP | YAML | Rust DSL | page |
|---|---|---|---|
| Pipeline, To, Dynamic To, Step | `to`, `toD`, `step` | `to`, `to_d`, `step` | [routing](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html#pipeline-to-tod-and-step) |
| Message Filter | `filter` | `filter` | [routing](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html#message-filter) |
| Content-Based Router | `choice` / `when` / `otherwise` | `choice().when().otherwise().end()` | [routing](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html#content-based-router-choice) |
| Recipient List | `recipientList` | `recipient_list` | [routing](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html#recipient-list) |
| Routing Slip | `routingSlip` | `routing_slip` | [routing](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html#routing-slip) |
| Dynamic Router | `dynamicRouter` | `dynamic_router` | [routing](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html#dynamic-router) |
| Multicast | `multicast` | `multicast` | [routing](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html#multicast) |
| Wire Tap | `wireTap` | `wire_tap` | [routing](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html#wire-tap) |
| Load Balancer (round robin, random, sticky, weighted, topic, failover, custom) | `loadBalance` | `load_balance` | [routing](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html#load-balancer) |
| Loop | `loop` | `loop_` | [routing](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html#loop) |

## Splitting, aggregating and ordering

| EIP | YAML | Rust DSL | page |
|---|---|---|---|
| Splitter | `split` | `split` | [split and aggregate](https://pmsudhi.github.io/cameleer/docs/guides/eips/split-aggregate.html#splitter) |
| Composed Message Processor (split + aggregation strategy) | `split` with `aggregationStrategy` | `split(..).aggregation_strategy(..)` | [split and aggregate](https://pmsudhi.github.io/cameleer/docs/guides/eips/split-aggregate.html#split-and-aggregate-the-results) |
| Aggregator | `aggregate` | `aggregate` | [split and aggregate](https://pmsudhi.github.io/cameleer/docs/guides/eips/split-aggregate.html#aggregator) |
| Resequencer (batch, stream) | `resequence` | `resequence` | [split and aggregate](https://pmsudhi.github.io/cameleer/docs/guides/eips/split-aggregate.html#resequencer) |
| Sort | `sort` | `sort` | [split and aggregate](https://pmsudhi.github.io/cameleer/docs/guides/eips/split-aggregate.html#sort) |

## Transformation

| EIP | YAML | Rust DSL | page |
|---|---|---|---|
| Message Translator | `setBody`, `transform`, `setHeader`, `removeHeaders` | `set_body`, `transform`, `set_header`, `remove_headers` | [transformation](https://pmsudhi.github.io/cameleer/docs/guides/eips/transformation.html#message-translator-setbody-transform-setheader) |
| Marshal, Unmarshal (data formats) | `marshal`, `unmarshal` | `marshal`, `unmarshal`, `marshal_json` | [transformation](https://pmsudhi.github.io/cameleer/docs/guides/eips/transformation.html#marshal-and-unmarshal) |
| Convert Body | `convertBodyTo` | `convert_body_to` | [transformation](https://pmsudhi.github.io/cameleer/docs/guides/eips/transformation.html#convert-the-body-type) |
| Content Enricher | `enrich` | `enrich` | [transformation](https://pmsudhi.github.io/cameleer/docs/guides/eips/transformation.html#content-enricher-enrich) |
| Poll Enrich | `pollEnrich` | `poll_enrich` | [transformation](https://pmsudhi.github.io/cameleer/docs/guides/eips/transformation.html#poll-enrich-pollenrich) |
| Claim Check | `claimCheck` | `claim_check` | [transformation](https://pmsudhi.github.io/cameleer/docs/guides/eips/transformation.html#claim-check) |
| Script | `script` | `script`, `process(cameleer_script::script(..))` | [transformation](https://pmsudhi.github.io/cameleer/docs/guides/eips/transformation.html#script) |

## Flow control and resilience

| EIP | YAML | Rust DSL | page |
|---|---|---|---|
| Idempotent Consumer | `idempotentConsumer` | `idempotent_consumer` | [flow control](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html#idempotent-consumer) |
| Throttle | `throttle` | `throttle` | [flow control](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html#throttle) |
| Delay | `delay` | `delay` | [flow control](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html#delay) |
| Sampling | `sample` | `sample`, `sample_every` | [flow control](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html#sampling) |
| Circuit Breaker | `circuitBreaker` / `onFallback` | `circuit_breaker().on_fallback()` | [flow control](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html#circuit-breaker) |
| Validate | `validate` | `validate` | [flow control](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html#validate) |
| Threads | `threads` | `threads`, `threads_with` | [flow control](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html#threads) |

## Interceptors, completions and reuse

| EIP | YAML | Rust DSL | page |
|---|---|---|---|
| Intercept Send To Endpoint | `interceptSendToEndpoint` | `intercept_send_to_endpoint` | [system](https://pmsudhi.github.io/cameleer/docs/guides/eips/system.html#intercept-sends-to-an-endpoint) |
| Intercept From, Intercept | `interceptFrom`, `intercept` | `intercept_from`, `intercept` | [system](https://pmsudhi.github.io/cameleer/docs/guides/eips/system.html#intercept-every-input) |
| On Completion | `onCompletion` | `on_completion` | [system](https://pmsudhi.github.io/cameleer/docs/guides/eips/system.html#on-completion) |
| Saga | `saga` | `saga` | [system](https://pmsudhi.github.io/cameleer/docs/guides/eips/system.html#saga) |
| Route Template | `routeTemplate`, `templatedRoute` | `add_route_template`, `TemplatedRouteBuilder` | [system](https://pmsudhi.github.io/cameleer/docs/guides/eips/system.html#route-templates) |
| Kamelet | `kamelet` | `kamelet` | [system](https://pmsudhi.github.io/cameleer/docs/guides/eips/system.html#kamelets) |
| Poll | `poll` | `poll` | [system](https://pmsudhi.github.io/cameleer/docs/guides/eips/system.html#poll) |
| Stop | `stop` | `stop` | [system](https://pmsudhi.github.io/cameleer/docs/guides/eips/system.html#stop) |

## Error handling

| EIP | YAML | Rust DSL | page |
|---|---|---|---|
| Dead Letter Channel, redelivery | `errorHandler: deadLetterChannel` | `error_handler(dead_letter_channel(..))` | [error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html#dead-letter-channel-with-redelivery) |
| Exception clause | `onException` | `on_exception` | [error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html#onexception-react-to-one-kind-of-failure) |
| Try, catch, finally | `doTry` / `doCatch` / `doFinally` | `do_try().do_catch().do_finally().end_do_try()` | [error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html#dotry-docatch-and-dofinally) |
| Throw Exception, Rollback | `throwException`, `rollback` | `throw_exception`, `rollback`, `mark_rollback_only` | [error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html#onexception-react-to-one-kind-of-failure) |

## Patterns without a guide example yet

These are implemented and covered by Cameleer's own test suite, but this guide has no example
for them yet; [FEATURES.md](https://pmsudhi.github.io/cameleer/docs/FEATURES.html#enterprise-integration-patterns) describes their
options.

| EIP | YAML | Rust DSL |
|---|---|---|
| Process, Bean (custom Rust code) | `process`, `bean` | `process`, `process_ref` (see [concepts](https://pmsudhi.github.io/cameleer/docs/guides/concepts.html#processors-and-eips)) |
| Transacted, Policy | `transacted`, `policy` | `transacted`, `transacted_ref`, `policy` |
| Route Policy | route `routePolicy` | `route_policy` |
| Service Call | `serviceCall` | `service_call` |
| Transformer, Validator (data types) | route `inputType`/`outputType`, `transformDataType` | `input_type`, `output_type`, `transform_data_type` |
| Set Exchange Pattern (InOnly, InOut) | `setExchangePattern` | `set_exchange_pattern`, `in_only`, `in_out` |
| Message History, Tracer | `camel.main.messageHistory`, `--trace` | `set_message_history`, `set_tracing` |

## Common questions

### Which EIPs does Cameleer support?

All of Apache Camel's EIPs listed above, from the filter and content-based router to the saga
and circuit breaker. Differences from Camel are noted on each page and in
[FEATURES.md](https://pmsudhi.github.io/cameleer/docs/FEATURES.html).

### Are EIP options the same as in Apache Camel?

Yes: names, defaults and semantics follow Camel 4 (for example `completionTimeout` is an
inactivity timeout and a split without an aggregation strategy continues with the original
message). Options Cameleer does not model, such as `executorService` on some EIPs, are accepted
and ignored in YAML.

### How do I write an EIP in Rust instead of YAML?

Use the method with the snake_case name on the route builder and close blocks with `.end()`:
`b.from("direct:a").split(jsonpath("$.items")).to("mock:item").end();`. Each pattern page shows
both forms.

## Related

- [Routing](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html), [split and aggregate](https://pmsudhi.github.io/cameleer/docs/guides/eips/split-aggregate.html),
  [transformation](https://pmsudhi.github.io/cameleer/docs/guides/eips/transformation.html), [flow control](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html),
  [interceptors and reuse](https://pmsudhi.github.io/cameleer/docs/guides/eips/system.html), [error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html)
- [Concepts](https://pmsudhi.github.io/cameleer/docs/guides/concepts.html), [agents cookbook](https://pmsudhi.github.io/cameleer/docs/guides/agents.html), [edge cookbook](https://pmsudhi.github.io/cameleer/docs/guides/edge.html)
- Apache Camel: [EIP catalogue](https://camel.apache.org/components/next/eips/enterprise-integration-patterns.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html

# Error handling

> Cameleer handles failures the way Apache Camel does: an error handler retries failed steps
> with a redelivery policy and then gives up or moves the message to a dead letter channel,
> `onException` reacts to specific exception types, and `doTry`/`doCatch`/`doFinally` handle
> errors inline.

Every example on this page runs in the test suite (`crates/cameleer-main/tests/docs_guides.rs`)
as YAML and as Rust DSL.

## How failures work

- A step fails by returning an error. The error has a **kind**, a Java-like exception class
  name such as `IOException` or `IllegalArgumentException`. Kinds have parents, like Java
  classes (`FileNotFoundException` is an `IOException`, every kind is an `Exception`), and
  `onException` and `doCatch` match a kind and its subkinds. Java class names in YAML
  (`java.io.IOException`) are matched by their simple name.
- The **error handler** decides what happens next. The default one (`defaultErrorHandler`)
  does not retry and fails the exchange; the caller gets the error. The
  **dead letter channel** sends the failed message to an endpoint instead and marks it handled.
  `noErrorHandler` does nothing.
- **Redelivery** happens at the point of failure: only the failed step runs again, not the
  whole route. The headers `CamelRedelivered`, `CamelRedeliveryCounter` and
  `CamelRedeliveryMaxCounter` tell the step which attempt it is.
- After the last attempt the exception is on the exchange and the exchange property
  `CamelExceptionCaught` holds it for `onException` and dead letter routes; `${exception.message}`
  reads its text in Simple.

The examples below call an inventory API bound as a processor bean. It fails with
`IOException` on the first call and the first retry, and succeeds on the second retry; the
body `poison` always fails:

```rust
fn bind_inventory_api(ctx: &CamelContext) {
    ctx.registry().bind_processor("inventoryApi", |ex: &mut Exchange| {
        let attempt = ex.header("CamelRedeliveryCounter").map(|v| v.to_string()).unwrap_or_default();
        if ex.body().to_string() == "poison" || attempt != "2" {
            return Err(CamelError::new("IOException", "connection reset by inventory API"));
        }
        ex.set_body(format!("reserved {}", ex.body()));
        Ok(())
    });
}
```

## Dead letter channel with redelivery

The dead letter channel retries the failed step according to its `redeliveryPolicy`, then sends
the message to `deadLetterUri`. With `useOriginalMessage: true` the dead letter endpoint gets
the message as it entered the route, not the half-processed one, so it can be replayed.

```yaml
- errorHandler:
    deadLetterChannel:
      deadLetterUri: mock:dead-letters
      useOriginalMessage: true
      redeliveryPolicy:
        maximumRedeliveries: 3
        redeliveryDelay: 10
        useExponentialBackOff: true
        backOffMultiplier: 2
- route:
    from:
      uri: direct:reserve
      steps:
        - process:
            ref: inventoryApi
        - to: mock:reserved
```

```rust
b.error_handler(
    dead_letter_channel("mock:dead-letters")
        .use_original_message()
        .maximum_redeliveries(3)
        .redelivery_delay(10)
        .use_exponential_back_off()
        .back_off_multiplier(2.0),
);
b.from("direct:reserve")
    .process_ref("inventoryApi")
    .to("mock:reserved");
```

`sku-1` fails twice, succeeds on the second retry and reaches `mock:reserved` as
`reserved sku-1`. `poison` fails four times (one call and three retries, 10 ms, 20 ms and 40 ms
apart) and lands on `mock:dead-letters`; the caller does not get an error, because the dead
letter channel handled it. The YAML `errorHandler` applies to every route of the context;
`b.error_handler(...)` applies to the routes of one builder, and a route can set its own with
`errorHandler:` in YAML or `.error_handler(...)` in Rust.

Redelivery policy options: `maximumRedeliveries` (`-1` = forever), `redeliveryDelay`,
`useExponentialBackOff`, `backOffMultiplier`, `maximumRedeliveryDelay`,
`useCollisionAvoidance`, `collisionAvoidanceFactor`, `delayPattern` (`0:1000;5:5000`),
`retryAttemptedLogLevel`, `retriesExhaustedLogLevel`, `logStackTrace`, `logExhausted`,
`logRetryAttempted` and `asyncDelayedRedelivery` (release seda and timer consumer threads during
the delay). A dead letter channel can also set `deadLetterHandleNewException`.

## `onException`: react to one kind of failure

`onException` catches the listed exception kinds (and their subkinds). `handled: true` stops
the failure from reaching the caller, and the clause's steps build the reply. It can have its
own redelivery policy, `onWhen` (a predicate), `continued: true` (ignore the error and go on
with the route), `useOriginalMessage` and `retryWhile`. Put it in a `routeConfiguration` to
apply it to every route, as in Camel 4.

```yaml
- routeConfiguration:
    onException:
      - onException:
          exception:
            - java.lang.IllegalArgumentException
          handled:
            constant: true
          steps:
            - setHeader:
                name: CamelHttpResponseCode
                constant: 400
            - setBody:
                simple: "rejected: ${exception.message}"
      - onException:
          exception:
            - java.io.IOException
          redeliveryPolicy:
            maximumRedeliveries: 1
          handled:
            constant: true
          steps:
            - setBody:
                constant: "inventory unavailable, order queued"
            - to: mock:retry-later
- route:
    from:
      uri: direct:order
      steps:
        - filter:
            simple: "${body} == ''"
            steps:
              - throwException:
                  exceptionType: java.lang.IllegalArgumentException
                  message: empty order
        - process:
            ref: inventoryApi
        - to: mock:orders
```

```rust
b.on_exception(&["IllegalArgumentException"])
    .handled(true)
    .set_header("CamelHttpResponseCode", constant(400))
    .set_body(simple("rejected: ${exception.message}"));
b.on_exception(&["IOException"])
    .maximum_redeliveries(1)
    .handled(true)
    .set_body(constant("inventory unavailable, order queued"))
    .to("mock:retry-later");
b.from("direct:order")
    .filter(simple("${body} == ''"))
        .throw_exception("IllegalArgumentException", "empty order")
    .end()
    .process_ref("inventoryApi")
    .to("mock:orders");
```

An empty order gets the reply `rejected: empty order` with response code 400. An order for
`sku-1` fails once, is retried once (not enough: the API needs two retries), and goes to
`mock:retry-later` with the reply `inventory unavailable, order queued`. The most specific
matching `onException` wins, as in Camel.

## `doTry`, `doCatch` and `doFinally`

`doTry` handles errors inline, like `try`/`catch`/`finally`. `doCatch` takes a list of
exception kinds and an optional `onWhen`; `doFinally` always runs. The error handler does not
redeliver inside a `doTry`.

```yaml
- route:
    from:
      uri: direct:parse
      steps:
        - doTry:
            steps:
              - unmarshal:
                  json: {}
              - setBody:
                  simple: "order ${body[id]}"
            doCatch:
              - exception:
                  - java.lang.Exception
                steps:
                  - setBody:
                      simple: "not JSON: ${exception.message}"
            doFinally:
              steps:
                - to: mock:parse-attempts
        - to: mock:parsed
```

```rust
b.from("direct:parse")
    .do_try()
        .unmarshal_json()
        .set_body(simple("order ${body[id]}"))
    .do_catch(&["Exception"])
        .set_body(simple("not JSON: ${exception.message}"))
    .do_finally()
        .to("mock:parse-attempts")
    .end_do_try()
    .to("mock:parsed");
```

`{"id": 5}` becomes `order 5`; `hello` becomes `not JSON: ...` with the parser's message. Both
pass through `mock:parse-attempts` and continue to `mock:parsed`.

## Error handling for AI and edge routes

- Wrap model calls in redelivery for transient errors (`HttpOperationFailedException`,
  `IOException`) and in a
  [circuit breaker](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html#circuit-breaker) for outages. See
  [the agents cookbook](https://pmsudhi.github.io/cameleer/docs/guides/agents.html#rate-limits-and-a-circuit-breaker-around-a-model-api).
- On a gateway with an unreliable uplink, use a dead letter channel to a local `file:`
  directory and a second route that replays it. See
  [store and forward](https://pmsudhi.github.io/cameleer/docs/guides/edge.html#store-and-forward-when-the-uplink-is-down).
- Use `useOriginalMessage: true` whenever the dead letter queue is meant for replay.

## Differences from Apache Camel

- Exceptions are string kinds with a parent hierarchy, not Java classes. Custom kinds are
  registered with `register_kind_parent("MyException", "IOException")` so `onException` for
  `IOException` catches them.
- With `asyncDelayedRedelivery`, the waiting exchange is handed to a released thread and a new
  consumer thread takes over, instead of a scheduler continuation. The effect for the route is
  the same.
- A failure from a `ProducerTemplate` call is returned as `CamelExecutionException` with the
  original exception as its cause, as in Camel.

## Common questions

### How do I retry a failed HTTP call in Cameleer?

Add a `redeliveryPolicy` with `maximumRedeliveries` and `redeliveryDelay` to the error handler
or to an `onException` for `HttpOperationFailedException` or `IOException`. Only the failed
call is retried.

### How do I send failed messages to a dead letter queue?

Declare `errorHandler: deadLetterChannel: deadLetterUri: kafka:orders-dlq` (or any endpoint),
with `useOriginalMessage: true` so the queue holds replayable input.

### How do I return a 400 error from a REST route?

Throw `IllegalArgumentException` (or validate with `validate`), and handle it with an
`onException` that sets `CamelHttpResponseCode` to 400 and the body to
`${exception.message}`.

### What is the difference between `handled` and `continued`?

`handled: true` ends the route after the `onException` steps and answers the caller normally;
`continued: true` ignores the error and continues the route after the failed step.

## Related

- [EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html), [flow control and resilience](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html)
- Apache Camel: [Error handling](https://camel.apache.org/manual/error-handler.html),
  [Exception clause](https://camel.apache.org/manual/exception-clause.html),
  [Dead Letter Channel](https://camel.apache.org/components/next/eips/dead-letter-channel.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/agent-tool-calls.html

# AI agent tool calls: direct vs through Cameleer

> Direct tool calls leave retries, duplicates, half-done work and business rules to the model;
> routing them through Cameleer makes each tool a tested route that validates, runs once, rolls
> back, retries and audits, so the model only decides what to do.

The short version, with the comparison table and FAQ, is on the
[AI agent tool calls: direct vs Cameleer](https://pmsudhi.github.io/cameleer/compare/ai-agent-tool-calls-direct-vs-cameleer/)
page.

Function calling (also called tool use) is how an AI agent acts: the model answers with the
name of a tool and its arguments as JSON, and your code executes it. This page compares two
ways to execute those calls, on a real multi-step job, and shows the complete Cameleer route
for it. The route runs end to end in the test suite
(`crates/cameleer-main/tests/docs_guides.rs`) against mock order, payment, shipping and email
APIs.

![Direct tool calls: an agent with API keys calls the orders, payments, shipping and email APIs itself in four tool calls and five model turns. Through Cameleer: the agent makes one tool call to a route that validates, runs once, checks policy, runs a saga with rollback, retries and audits, then calls the same APIs.](https://pmsudhi.github.io/cameleer/docs/guides/agent-tool-calls.svg)

## The difference in one table

| concern | direct tool calls | through Cameleer |
|---|---|---|
| who runs a multi-step job | the model, one tool call per step, one model turn per call | a route; the model makes one call |
| wrong or invented arguments | reach the API unless your glue code checks them | rejected by a JSON schema with every error listed, so the model can correct itself (`400`) |
| the agent retries a call | the action runs again: a second refund, a second email | `idempotentConsumer` runs each `requestId` once; the repeat gets `duplicate` |
| a step fails after an earlier one succeeded | half-done work the model has to notice and undo | a `saga` calls the compensation (here: cancel the refund) |
| flaky APIs | the model sees the error and may retry, give up or improvise | retries with exponential back-off at the failing step, then a clear answer |
| business rules (amount, limits, approvals) | written in the prompt and trusted to the model | code in the route: the amount comes from the order, large refunds wait for a person |
| credentials | the agent process holds every API key | the route holds them; the agent can only call the tool |
| audit | whatever the agent framework logs | every accepted call appended to an audit log |
| rate limits and outages | per agent, if at all | `throttle` and `circuitBreaker` around any API ([agent cookbook](https://pmsudhi.github.io/cameleer/docs/guides/agents.html#rate-limits-and-a-circuit-breaker-around-a-model-api)) |
| tokens and latency | every step is a model turn that re-sends the conversation and tool results | one tool call, one final turn; the steps run at code speed |
| changing an API or vendor | change the tool, the prompt and maybe re-test the agent | change the route; the tool the model sees stays the same |
| testing | needs the model in the loop | the route is tested without a model (as this page's route is) |

## The use case: a damaged order

A customer writes to a support agent:

> My order EU-4411 arrived broken. I want my money back.

Resolving it takes four systems: read the order (is it delivered, what did it cost, who is the
customer), refund it with the payment provider, create a return label with the carrier, and
email the customer the label. Company rules: only delivered orders, the refund is the order
total and not a number someone typed, and refunds over 200 need a person.

### Direct: the model orchestrates

The agent gets four tools, roughly:

```json
[
  {"name": "get_order", "parameters": {"orderId": "string"}},
  {"name": "issue_refund", "parameters": {"orderId": "string", "amount": "number", "reason": "string"}},
  {"name": "create_return_label", "parameters": {"orderId": "string"}},
  {"name": "send_email", "parameters": {"to": "string", "template": "string", "data": "object"}}
]
```

and a system prompt with the rules. A good run is four tool calls and five model turns:
`get_order`, then `issue_refund` with the total the model read, then `create_return_label`,
then `send_email`, then the reply to the customer. Each turn sends the conversation, the tool
definitions and every tool result so far back to the model.

What goes wrong in production:

- **The refund is issued twice.** The payments API times out after it has refunded; the model,
  or the agent framework, retries `issue_refund`. Nothing in the call says it is the same
  request.
- **Half-done work.** The refund succeeds, then the carrier API is down. The customer has the
  money and no label, and the model has to notice it and decide what to do, every time,
  without a rule.
- **The model sets the amount.** `issue_refund` takes whatever `amount` the model passes: a
  misread total, a currency mix-up, or a customer's "refund me 1,299" injected into the chat.
  The 200 limit is a sentence in the prompt.
- **Every key in one place.** The agent process holds the payment, carrier and email
  credentials, and the tool definitions show the model how to use them.
- **No record.** Unless you add one, there is no log of which tool calls were made with which
  arguments, separate from the model's transcript.

Each of these can be fixed in glue code around every tool, in every agent, in every language
the team uses. That glue code is an integration layer; Cameleer is one.

### Through Cameleer: the model decides, a route executes

The agent gets one tool. Its parameters are the facts only the conversation knows:

```json
{
  "name": "resolve_damaged_order",
  "description": "Refund a delivered order that arrived damaged and send the customer a return label. The amount is taken from the order.",
  "parameters": {
    "type": "object",
    "required": ["requestId", "orderId", "reason"],
    "additionalProperties": false,
    "properties": {
      "requestId": {"type": "string", "pattern": "^[A-Za-z0-9-]{8,64}$"},
      "orderId": {"type": "string", "pattern": "^[A-Z]{2}-[0-9]+$"},
      "reason": {"type": "string", "enum": ["damaged", "missing_parts", "wrong_item"]}
    }
  }
}
```

The same file, [schemas/damaged-order-request.json](https://github.com/pmsudhi/cameleer/blob/main/examples/agents/schemas/damaged-order-request.json),
validates the call in the route, so the tool the model sees and the check that runs can't drift
apart. A good run is one tool call and two model turns. The route does the four steps:

1. **Validate** the arguments against the schema. An invented `amount` or a free-text reason
   gets `400` with every error.
2. **Run once.** `idempotentConsumer` on `requestId`: a retried call answers `duplicate` and
   does nothing.
3. **Read the order** and take the amount and the customer's email from it.
4. **Apply the rules.** Not delivered: `409`. Over `APPROVAL_LIMIT` (200): the request is
   parked as a file for a person and the agent gets `202 pending_approval`, with a sentence it
   can pass on. The [human approval pattern](https://pmsudhi.github.io/cameleer/docs/guides/agents.html#human-in-the-loop-approval) shows the
   Slack message and the approval endpoint.
5. **Refund and label as a saga.** The sub-route `refund-with-label` retries each call twice
   with exponential back-off. If the label still fails, the saga calls `cancel-refund` with the
   `requestId`, and the agent gets `502` with "nothing was changed".
6. **Email and audit** through wire taps, so they don't slow the answer down; the audit log has
   one JSON line per accepted call.

The answer is a small JSON object the model can turn into a reply:
`{"status": "resolved", "refundId": "r-1", "amount": 129.9, "returnLabel": "https://..."}`.

```yaml
- rest:
    path: /tools
    post:
      - path: /resolve-damaged-order
        to: direct:resolve-damaged-order
- routeConfiguration:
    id: tool-errors
    onException:
      - onException:
          exception:
            - org.apache.camel.component.jsonvalidator.JsonValidationException
          handled:
            constant: true
          steps:
            - setHeader:
                name: CamelHttpResponseCode
                constant: 400
            - setBody:
                simple: "invalid tool arguments: ${exception.message}"
      - onException:
          exception:
            - org.apache.camel.http.base.HttpOperationFailedException
            - java.io.IOException
          handled:
            constant: true
          steps:
            - setHeader:
                name: CamelHttpResponseCode
                constant: 502
            - setHeader:
                name: Content-Type
                constant: application/json
            - setBody:
                simple: '{"status": "failed", "requestId": "${header.requestId}", "detail": "a backend did not answer; nothing was changed, retry later with a new requestId"}'
- route:
    id: resolve-damaged-order
    routeConfigurationId: tool-errors
    from:
      uri: direct:resolve-damaged-order
      steps:
        - convertBodyTo:
            type: java.lang.String
        - to: "json-validator:file:{{env:SCHEMA_DIR:schemas}}/damaged-order-request.json"
        - unmarshal:
            json: {}
        - setHeader:
            name: requestId
            simple: "${body[requestId]}"
        - setHeader:
            name: orderId
            simple: "${body[orderId]}"
        - setHeader:
            name: reason
            simple: "${body[reason]}"
        - wireTap:
            uri: direct:audit-order-tool
        - idempotentConsumer:
            header: requestId
            steps:
              - removeHeaders:
                  pattern: "CamelHttp*"
              - toD: "{{env:ORDERS_URL:http://localhost:9001}}/orders/${header.orderId}?httpMethod=GET"
              - unmarshal:
                  json: {}
              - setHeader:
                  name: amount
                  simple: "${body[total]}"
              - setHeader:
                  name: email
                  simple: "${body[email]}"
              - choice:
                  when:
                    - simple: "${body[status]} != 'delivered'"
                      steps:
                        - setHeader:
                            name: CamelHttpResponseCode
                            constant: 409
                        - setBody:
                            simple: '{"status": "rejected", "requestId": "${header.requestId}", "detail": "order ${header.orderId} is ${body[status]}; only delivered orders can be refunded"}'
                    - simple: "${header.amount} > {{env:APPROVAL_LIMIT:200}}"
                      steps:
                        - setBody:
                            simple: '{"requestId": "${header.requestId}", "orderId": "${header.orderId}", "amount": ${header.amount}, "reason": "${header.reason}"}'
                        - to: "file:{{env:PENDING_DIR:pending}}?fileName=${header.requestId}.json"
                        - setHeader:
                            name: CamelHttpResponseCode
                            constant: 202
                        - setBody:
                            simple: '{"status": "pending_approval", "requestId": "${header.requestId}", "detail": "refunds over {{env:APPROVAL_LIMIT:200}} need a person; tell the customer they will hear back within one business day"}'
                  otherwise:
                    steps:
                      - doTry:
                          steps:
                            - to: direct:refund-with-label
                            - wireTap:
                                uri: direct:notify-customer
                            - setHeader:
                                name: CamelHttpResponseCode
                                constant: 200
                            - setBody:
                                simple: '{"status": "resolved", "requestId": "${header.requestId}", "refundId": "${header.refundId}", "amount": ${header.amount}, "returnLabel": "${header.labelUrl}"}'
                          doCatch:
                            - exception:
                                - org.apache.camel.http.base.HttpOperationFailedException
                                - java.io.IOException
                              steps:
                                - setHeader:
                                    name: CamelHttpResponseCode
                                    constant: 502
                                - setBody:
                                    simple: '{"status": "failed", "requestId": "${header.requestId}", "detail": "the return label failed, so the refund was cancelled; nothing was changed. To try again later, call with a new requestId"}'
        - filter:
            simple: "${exchangeProperty.CamelDuplicateMessage} == true"
            steps:
              - setBody:
                  simple: '{"status": "duplicate", "requestId": "${header.requestId}"}'
        - setHeader:
            name: Content-Type
            constant: application/json
- route:
    id: refund-with-label
    errorHandler:
      defaultErrorHandler:
        redeliveryPolicy:
          maximumRedeliveries: 2
          redeliveryDelay: 200
          useExponentialBackOff: true
    from:
      uri: direct:refund-with-label
      steps:
        - saga:
            compensation:
              uri: direct:cancel-refund
            option:
              - key: requestId
                expression:
                  simple: "${header.requestId}"
            steps:
              - setBody:
                  simple: '{"requestId": "${header.requestId}", "orderId": "${header.orderId}", "amount": ${header.amount}, "reason": "${header.reason}"}'
              - enrich:
                  uri: "{{env:PAYMENTS_URL:http://localhost:9002}}/refunds?httpMethod=POST"
              - unmarshal:
                  json: {}
              - setHeader:
                  name: refundId
                  simple: "${body[refundId]}"
              - setBody:
                  simple: '{"orderId": "${header.orderId}", "requestId": "${header.requestId}"}'
              - enrich:
                  uri: "{{env:SHIPPING_URL:http://localhost:9003}}/return-labels?httpMethod=POST"
              - unmarshal:
                  json: {}
              - setHeader:
                  name: labelUrl
                  simple: "${body[labelUrl]}"
- route:
    id: cancel-refund
    from:
      uri: direct:cancel-refund
      steps:
        - removeHeaders:
            pattern: "CamelHttp*"
        - setBody:
            simple: '{"requestId": "${header.requestId}"}'
        - to: "{{env:PAYMENTS_URL:http://localhost:9002}}/refunds/cancel?httpMethod=POST"
- route:
    id: notify-customer
    from:
      uri: direct:notify-customer
      steps:
        - removeHeaders:
            pattern: "CamelHttp*"
        - setBody:
            simple: '{"to": "${header.email}", "template": "refund-issued", "orderId": "${header.orderId}", "amount": ${header.amount}, "returnLabel": "${header.labelUrl}"}'
        - to: "{{env:EMAIL_URL:http://localhost:9004}}/messages?httpMethod=POST"
- route:
    id: audit-order-tool
    from:
      uri: direct:audit-order-tool
      steps:
        - marshal:
            json: {}
        - setBody:
            simple: "${body}\n"
        - to: "file:{{env:AUDIT_DIR:audit}}?fileName=tool-calls.jsonl&fileExist=Append"
```

Three details:

- The refund and the label are in their own route because the error handling has to be in the
  right place. A `handled` `onException` around the saga would clear the error before the saga
  sees it, so nothing would be compensated (Apache Camel behaves the same way). Inside
  `refund-with-label`, the default error handler retries and then lets the error through the
  saga, which compensates; the `doTry` in the main route turns it into the `502` answer.
- A failed call is still an answered call, so its `requestId` is used up, and the `502` tells
  the agent to retry with a new one. The other answers are final, so a repeat is correctly a
  `duplicate`.
- `removeHeaders: CamelHttp*` comes before the backend calls, because the incoming request's
  HTTP headers would otherwise change where the `http` producer sends them, as in Apache Camel.
  The calls with side effects use `enrich`, so a retry sends the original request again (see
  [the tool pattern](https://pmsudhi.github.io/cameleer/docs/guides/agents.html#expose-a-tool-to-an-agent-over-rest)).

### What the test checks

| the agent sends | the route answers | what happened |
|---|---|---|
| `EU-4411`, `damaged` | `200 resolved`, amount 129.9 from the order | payments failed once with `503` and was retried; label created; customer emailed |
| the same call again | `200 duplicate` | nothing executed a second time |
| `orderId: "4411"`, a free-text reason and `amount: 1299` | `400` naming `orderId`, `reason` and `amount` | nothing executed, nothing audited |
| `EU-1200`, not yet delivered | `409 rejected` | nothing executed |
| `EU-9000`, total 899 | `202 pending_approval` | parked for a person, no refund |
| `EU-5000`, carrier down | `502 failed` | refund issued once, label tried three times, refund cancelled, no email |

## When a direct call is enough

Not every tool needs a route. Call the API directly when the call:

- only reads, such as a search or a lookup, and a repeat does no harm;
- is a single step with no other system to keep consistent;
- is a prototype, and you will move the tool behind a route before real users touch it.

Use a route as soon as a call changes something (money, stock, messages, tickets), spans
several systems, needs a rule the model must not override, or must be audited. Read-only
tools can still go through Cameleer to hide credentials and add limits.

## Cameleer's advantages for agent tools

- **Fewer model turns.** A multi-step job is one tool call instead of one call per step, which
  cuts tokens, latency and the chances for the model to go off script.
- **Reliability is code, not prompt.** Idempotency, retries, back-off, sagas, throttling and
  circuit breakers are Enterprise Integration Patterns, configured in a few lines and tested
  without a model.
- **Rules the model can't override.** Amounts, limits and approvals are decided in the route
  from system data; the model only supplies what it learned in the conversation.
- **Least privilege.** API keys stay in the route's environment; the agent can call the tool and
  nothing else.
- **One audit trail** for every agent, framework and model.
- **230 components.** The same route style reaches databases, queues, SaaS APIs, files and
  cloud services ([components](https://pmsudhi.github.io/cameleer/docs/components/index.html)), and the routes run as a small sidecar or
  inside a Rust agent with `cameleer_main::new_main()`.
- **Model and framework neutral.** A tool is an HTTP endpoint with a JSON schema, so it works
  with any model provider and agent framework that supports function calling.

## Common questions

### Is Cameleer an AI agent framework?

No. The agent framework runs the model loop and decides which tool to call. Cameleer executes
the tool: it is the integration layer between the agent and your systems.

### Does routing tool calls through Cameleer replace function calling?

No. The model still uses function calling; the tool it calls is a Cameleer route behind an
HTTP endpoint, declared with the same JSON schema the route validates against.

### Which models and agent frameworks does it work with?

Any that support function calling or tool use and can make an HTTP request: OpenAI,
Anthropic, Google, AWS Bedrock and Azure OpenAI models, open models on Ollama or vLLM, and
frameworks that let you define a tool as an HTTP call. An MCP server is on the
[roadmap](https://pmsudhi.github.io/cameleer/docs/ROADMAP.html).

### What happens when an agent retries a tool call?

The route sees the same `requestId` and answers `duplicate` without executing anything. Keep the
ids across restarts and instances with the JDBC or Redis idempotent repository.

### Can the agent still handle a multi-step job itself?

Yes, and for open-ended tasks it should. Put a step behind a route when its order and rules are
known in advance, as in a refund: the model decides that the customer gets a refund, the route
decides how.

### Does an extra hop make tool calls slower?

A route adds microseconds to a call; a model turn takes hundreds of milliseconds to seconds. A
multi-step job through one route saves model turns, so it is usually faster end to end.

## Related

- [Cameleer for AI agents](https://pmsudhi.github.io/cameleer/docs/guides/agents.html): eight tested patterns, including the single-step
  [tool over REST](https://pmsudhi.github.io/cameleer/docs/guides/agents.html#expose-a-tool-to-an-agent-over-rest) and
  [human approval](https://pmsudhi.github.io/cameleer/docs/guides/agents.html#human-in-the-loop-approval)
- [Error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html), [EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html), [AI components](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html)
- The route file: [examples/agents/damaged-order-tool.camel.yaml](https://github.com/pmsudhi/cameleer/blob/main/examples/agents/damaged-order-tool.camel.yaml)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html

# AI components

> Cameleer calls large language models from routes with four components: `openai` (OpenAI and any OpenAI-compatible server such as Ollama or vLLM), `azure-openai`, `aws-bedrock` and `google-vertexai`; they cover chat, embeddings and, depending on the provider, streaming, tool calls and images.

Every AI component is a producer: a step in a route that sends the message body to a model and
replaces the body with the answer. Everything else (where the text comes from, what happens with
the answer, retries, filtering, splitting) is ordinary Camel routing, so an "AI agent" in
Cameleer is a route: a trigger, one or more model calls, and the systems the agent acts on.

## Which component to use

| | [openai](https://pmsudhi.github.io/cameleer/docs/components/openai.html) | [azure-openai](https://pmsudhi.github.io/cameleer/docs/components/azure-openai.html) | [aws-bedrock](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html) | [google-vertexai](https://pmsudhi.github.io/cameleer/docs/components/google-vertexai.html) |
|---|---|---|---|---|
| Providers | OpenAI, Ollama, vLLM, LM Studio, LiteLLM, any `/v1/chat/completions` server | Azure OpenAI deployments | Models on Amazon Bedrock (Anthropic, Amazon Titan, Meta, Mistral, ...) | Gemini; partner models (Anthropic, Meta, Mistral) via `rawPredict` |
| Chat | `chat-completion` | `chatCompletion` | `converse`, `invokeTextModel` | `generateText`, `generateChat`, `generateCode`, `generateMultimodal` |
| Embeddings | `embeddings` | `embeddings` | `invokeEmbeddingsModel` | `generateEmbeddings` |
| Streaming | no | yes (`streaming=true`) | yes (`converseStream`, `invoke*Streaming`) | yes (`generate*Streaming`, `streamRawPredict`) |
| Tool calls | pass-through only: send `tools` in a request map, read the raw response with `outputType=full` | the model's tool calls in the `CamelAzureOpenAIToolCalls` header | `CamelAwsBedrockConverseToolConfig` header; tool-use blocks in `CamelAwsBedrockConverseOutputMessage` | pass-through only: send `tools` in a request map, read the raw response in `CamelGoogleVertexAIResponse` |
| Images | no | `imageGeneration` (DALL-E) | `invokeImageModel` | `generateImage` (Imagen), image input with `generateMultimodal` |
| Extras | | Assistants API (`runAssistant`, threads, runs) | Guardrails, knowledge bases and agents (`aws-bedrock-agent-runtime`) | token counting (`countTokens`) |
| Auth | API key (Bearer) or none | API key or Entra ID client credentials | AWS credentials (SigV4) | Google service account / workload identity |

All four give the answer text as the body and token usage and finish reason as headers. Check
each component page for the exact option and header names.

## What is not supported

Be aware of these limits before you design around them:

- **No agent loop.** No component executes tools for you: when a model asks for a tool, your
  route must call the tool and send the result back in a new request. Server-side agents are the
  exception: Bedrock Agents (`aws-bedrock-agent-runtime`, `invokeAgent`) and Azure OpenAI
  Assistants (`runAssistant`) run the loop in the cloud service.
- **`openai` has no streaming and no tool-call options.** It waits for the complete answer.
- **No vector store component.** Embeddings are lists of numbers in the body; store and search
  them with the data store you already run ([mongodb](https://pmsudhi.github.io/cameleer/docs/components/mongodb.html),
  [elasticsearch](https://pmsudhi.github.io/cameleer/docs/components/elasticsearch.html), [spring-redis](https://pmsudhi.github.io/cameleer/docs/components/spring-redis.html),
  files).
- **No LangChain4j components** (`langchain4j-chat`, `langchain4j-embeddings`, ...), no MCP
  client or server, and no direct Anthropic or Gemini API component: use Claude through
  Bedrock or Vertex AI, and Gemini through Vertex AI.
- **No native Ollama API.** Ollama, vLLM and LM Studio are used through their OpenAI-compatible
  `/v1` endpoint with `openai:` and `baseUrl`.

## Classify and summarise with an LLM, then act

An agent that triages incidents: the model writes a one-line summary, which becomes the Jira
issue summary, while the original text stays the issue description.

```yaml
- route:
    id: ai-triage-to-jira
    from:
      uri: "direct:incident"
      steps:
        - setProperty:
            name: report
            simple: "${body}"
        - to: "openai:chat-completion?model={{env:OPENAI_MODEL:gpt-4o-mini}}&apiKey={{env:OPENAI_API_KEY}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}&temperature=0&maxTokens=40&systemMessage=Write a one-line Jira summary of this incident report."
        - setHeader:
            name: IssueSummary
            simple: "${body}"
        - setBody:
            simple: "${exchangeProperty.report}"
        - setHeader:
            name: ProjectKey
            constant: "OPS"
        - setHeader:
            name: IssueTypeName
            constant: "Bug"
        - to: "jira:addIssue?jiraUrl={{env:JIRA_URL:https://your-site.atlassian.net}}&username={{env:JIRA_USER}}&password={{env:JIRA_API_TOKEN}}"
        - log: "opened ${header.IssueKey}: ${header.IssueSummary}"
```

The same shape works with any target: post the answer to [Slack](https://pmsudhi.github.io/cameleer/docs/components/slack.html), reply
on [Telegram](https://pmsudhi.github.io/cameleer/docs/components/telegram.html), comment a [GitHub](https://pmsudhi.github.io/cameleer/docs/components/github.html) pull
request, or use the answer in a `choice` to route the message (see the
[ticket triage example](https://github.com/pmsudhi/cameleer/blob/main/examples/ai-ticket-triage.camel.yaml)).

## Embeddings into a store

Embed every text file dropped into a folder and write the vector next to it as JSON, ready to be
loaded into a vector index. Swap the last step for a database component to store it directly.

```yaml
- route:
    id: embed-documents
    from:
      uri: "file:{{env:DOCS_DIR:docs-in}}?include=.*\\.txt&delay=2000"
      steps:
        - convertBodyTo:
            type: String
        - to: "openai:embeddings?model={{env:OPENAI_EMBEDDING_MODEL:text-embedding-3-small}}&apiKey={{env:OPENAI_API_KEY}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}"
        - marshal:
            json: {}
        - to: "file:{{env:VECTOR_DIR:vectors}}?fileName=${file:onlyname.noext}.json"
```

## Local models: Ollama, vLLM, LM Studio

Point `baseUrl` at the server's OpenAI-compatible endpoint; nothing else changes. This keeps the
data on the machine, which matters on edge devices and in regulated networks.

| server | `baseUrl` |
|---|---|
| Ollama | `http://localhost:11434/v1` |
| vLLM | `http://localhost:8000/v1` |
| LM Studio | `http://localhost:1234/v1` |

The [openai page](https://pmsudhi.github.io/cameleer/docs/components/openai.html) has a complete local-model route.

## Tool calls

With Azure OpenAI, send the request as a map with `tools`; when the model decides to call a tool,
the finish reason is `tool_calls` and the calls (function name and JSON arguments) are in the
`CamelAzureOpenAIToolCalls` header. Your route runs the tool and sends a follow-up request.

```yaml
- route:
    id: weather-tool-call
    from:
      uri: "direct:ask-weather"
      steps:
        - setBody:
            constant: '{"messages":[{"role":"user","content":"What is the weather in Oslo?"}],"tools":[{"type":"function","function":{"name":"get_weather","parameters":{"type":"object","properties":{"city":{"type":"string"}}}}}]}'
        - unmarshal:
            json: {}
        - to: "azure-openai://{{env:AZURE_OPENAI_RESOURCE:my-resource}}/{{env:AZURE_OPENAI_DEPLOYMENT:gpt-4o}}?apiKey=RAW({{env:AZURE_OPENAI_KEY}})"
        - log: "finish=${header.CamelAzureOpenAIFinishReason} calls=${header.CamelAzureOpenAIToolCalls}"
```

With `openai:` the same request map is sent unchanged; add `outputType=full` to get the whole
response, including `choices[0].message.tool_calls`, as the body:

```yaml
- route:
    id: openai-tools-passthrough
    from:
      uri: "direct:ask-with-tools"
      steps:
        - setBody:
            constant: '{"messages":[{"role":"user","content":"What is the weather in Oslo?"}],"tools":[{"type":"function","function":{"name":"get_weather","parameters":{"type":"object","properties":{"city":{"type":"string"}}}}}]}'
        - unmarshal:
            json: {}
        - to: "openai:chat-completion?model={{env:OPENAI_MODEL:gpt-4o-mini}}&apiKey={{env:OPENAI_API_KEY}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}&outputType=full"
        - log: "finish reason: ${header.CamelOpenAIFinishReason}"
```

With Bedrock, put the tool configuration map in the `CamelAwsBedrockConverseToolConfig` header
of a `converse` call; see [aws-bedrock](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html).

## Google Vertex AI (Gemini)

```yaml
- route:
    id: gemini-answer
    from:
      uri: "direct:ask-gemini"
      steps:
        - to: "google-vertexai:{{env:GCP_PROJECT:my-project}}:us-central1:gemini-1.5-flash?temperature=0.2&maxOutputTokens=256&systemInstruction=Answer in one paragraph."
        - log: "finish=${header.CamelGoogleVertexAIFinishReason} tokens=${header.CamelGoogleVertexAITotalTokenCount}"
```

Credentials come from `serviceAccountKey` or the `GOOGLE_APPLICATION_CREDENTIALS` environment
variable. Embeddings use the same component with an embedding model:

```yaml
- route:
    id: gemini-embeddings
    from:
      uri: "direct:embed-gemini"
      steps:
        - to: "google-vertexai:{{env:GCP_PROJECT:my-project}}:us-central1:text-embedding-004?operation=generateEmbeddings&taskType=RETRIEVAL_DOCUMENT"
```

More options (streaming, multimodal input, Imagen, Claude on Vertex) are on the
[google-vertexai page](https://pmsudhi.github.io/cameleer/docs/components/google-vertexai.html).

## Amazon Bedrock

The `converse` operation works the same way for every Bedrock chat model:

```yaml
- route:
    id: bedrock-converse
    from:
      uri: "direct:ask-bedrock"
      steps:
        - setHeader:
            name: CamelAwsBedrockConverseSystem
            constant: "Answer in one sentence."
        - to: "aws-bedrock://chat?modelId=anthropic.claude-3-haiku-20240307-v1:0&operation=converse&region={{env:AWS_REGION:us-east-1}}&useDefaultCredentialsProvider=true"
        - log: "stop=${header.CamelAwsBedrockConverseStopReason}"
```

See [aws-bedrock](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html) for streaming, embeddings, guardrails,
knowledge bases and Bedrock Agents.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("direct:summarise")
        .to("openai:chat-completion?model=gpt-4o-mini&systemMessage=Summarise in one sentence.")
        .to("slack:#ops?webhookUrl={{env:SLACK_WEBHOOK_URL}}");
})?;
```

## Run it with Docker

```sh
export OPENAI_API_KEY=sk-... JIRA_USER=bot@example.com JIRA_API_TOKEN=... JIRA_URL=https://your-site.atlassian.net
docker run --rm -e OPENAI_API_KEY -e JIRA_URL -e JIRA_USER -e JIRA_API_TOKEN \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/ai-triage-to-jira.camel.yaml
```

## Common questions

### How do I keep the original message after calling the model?

Save it first (`setProperty` with `${body}`), call the model, move the answer into a header,
then restore the body from the property, as in the triage example above.

### How do I make model calls reliable?

Treat them like any remote call: `onException` with a redelivery policy for timeouts and 429
responses, a `circuitBreaker` around the call, and `temperature=0` for classification so the
answers are stable.

### Can the same route run against OpenAI in the cloud and Ollama at the edge?

Yes. Put `baseUrl`, `model` and `apiKey` in `{{env:...}}` placeholders, as in the examples, and
set them per deployment.

### How are the examples tested?

Every example on this page runs in the test suite against embedded mock servers of the OpenAI,
Azure OpenAI, Bedrock, Vertex AI and Jira APIs, so the option names and the request formats are
checked on every build.

## Related

- [openai](https://pmsudhi.github.io/cameleer/docs/components/openai.html), [azure-openai](https://pmsudhi.github.io/cameleer/docs/components/azure-openai.html), [aws-bedrock](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html), [google-vertexai](https://pmsudhi.github.io/cameleer/docs/components/google-vertexai.html)
- [slack](https://pmsudhi.github.io/cameleer/docs/components/slack.html), [jira](https://pmsudhi.github.io/cameleer/docs/components/jira.html), [github](https://pmsudhi.github.io/cameleer/docs/components/github.html), [telegram](https://pmsudhi.github.io/cameleer/docs/components/telegram.html)
- [EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html)
- [Apache Camel AI components](https://camel.apache.org/components/next/langchain4j-chat-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/build-features.html

# Build features: choose what goes into your build

> Cameleer's default build, image and `cargo install` include every component. Cargo features let
> you build a smaller binary that contains only the component families your routes use, for a
> serverless function, an edge device or a smaller container image.

**You don't need this page to get started.** The Docker image `pmsudhi/cameleer`, `cargo install
cameleer-main` and `cargo build -p cameleer-main` all contain every component, language and data
format. Every page in these docs works with them as is. Come back here when size or cold start
matters.

## What is always included

Every build, even the smallest one (`core`), contains:

- the routing engine, every EIP, error handling, sagas, route templates and Kamelets
- the YAML DSL, the XML DSL, the Rust DSL and the REST DSL
- HTTP/1.1 and TLS: `platform-http`, `http`/`https`, `rest`, `netty`, `netty-http`, `jetty`, `undertow`
- the core components: `direct`, `seda`, `vm`, `timer`, `scheduler`, `cron`, `quartz`, `file`,
  `log`, `mock`, `stub`, `bean`, `class`, `ref`, `browse`, `controlbus`, `dataformat`,
  `dataset`, `dataset-test`, `exec`, `json-validator`, `kamelet`, `language`, `saga`, `stream`,
  `test`
- the core languages: `simple`, `constant`, `header`, `exchangeProperty`, `variable`, `jsonpath`,
  `tokenize`, `bean`, `ref`
- the core data formats: `json`, `jacksonxml`, `csv`, `base64`, `hex`, `string`, `gzip`,
  `zip-deflater`, `urlencoded`
- the `cameleer` commands `run`, `init`, `ps`, `stop`, `log`, `get` and `version`

## The features

Each feature adds one family. Every component, language and data format page in these docs
names its feature in its header line (**Cargo feature:**).

| feature | adds | crate |
|---|---|---|
| `amqp` | `activemq`, `amqp-stomp`, `jms`, `rabbitmq`, `spring-rabbitmq`, `stomp` (AMQP 0-9-1, STOMP and JMS) | `cameleer-amqp` |
| `amqp10` | `amqp` (AMQP 1.0, JMS over AMQP), `azure-servicebus`, `azure-eventhubs` | `cameleer-amqp10` |
| `cloud` | every `aws*`, `azure-*` and `google-*` component except the two above (62 components: S3, SQS, SNS, DynamoDB, Lambda, Bedrock, Blob, Cosmos DB, Azure OpenAI, Pub/Sub, BigQuery, Vertex AI, ...) and the `{{aws:...}}`, `{{azure:...}}` and `{{gcp:...}}` secret placeholders | `cameleer-cloud` |
| `dataformats` | the data formats `asn1`, `avro`, `barcode`, `bindy`, `cbor`, `crypto`, `fory`, `ical`, `mime-multipart`, `pgp`, `tarfile`, `thrift`, `univocity`, `yaml`, `zipfile`, and the `thrift` component | `cameleer-dataformats` |
| `datastores` | `spring-redis`, `mongodb`, `mongodb-gridfs`, `elasticsearch`, `opensearch`, `cql` (Cassandra), `couchdb` | `cameleer-datastores` |
| `grpc` | the `grpc` component and the `protobuf` data format | `cameleer-grpc` |
| `kafka-mqtt` | `kafka`, `paho`, `paho-mqtt5` | `cameleer-kafka-mqtt` |
| `protocols` | `ftp`, `ftps`, `smtp`/`smtps`, `pop3`/`pop3s`, `imap`/`imaps`, `mllp`, `syslog`, `websocket`/`ws`/`wss`, `vertx-websocket`; the `hl7terser` language; the `hl7` and `syslog` data formats | `cameleer-protocols` |
| `saas` | `openai`, `slack`, `telegram`, `github`, `twilio`, `jira`, `webhook`, `graphql`, `rss`, `atom` | `cameleer-saas` |
| `script` | the languages `js`/`javascript`, `groovy`, `python`, `java`/`joor`, `csimple`, `mvel`, `ognl`, `spel`, `datasonnet`, and the `mvel` component | `cameleer-script` |
| `soap` | `cxf`, `cxfrs`, `spring-ws`, `fhir`; the `jaxb` and `fhir` data formats | `cameleer-soap` |
| `sql` | `sql`, `sql-stored`, `jdbc` (embedded SQL engine and PostgreSQL client) | `cameleer-sql` |
| `ssh` | `sftp`, `ssh` | `cameleer-ssh` |
| `xml` | `xslt`, `xslt-saxon`, `xquery`, full XML Schema validation for `validator`, `xj`, `xmlsecurity-sign`, `xmlsecurity-verify`; the `xquery` language and XPath 1.0 in full | `cameleer-xml` |
| `templates` | `mustache`, `velocity`, `freemarker`, `string-template` | part of `cameleer-core` |
| `jq` | the `jq` language and Simple's `${jq(...)}` | part of `cameleer-core` |
| `xpath` | a smaller XPath 1.0 subset for the `xpath` language and Simple's `${xpath(...)}` when `xml` is left out | part of `cameleer-core` |
| `http2` | `httpVersion=HTTP/2` on the `http` producer | part of `cameleer-http` |
| `validate` | the `cameleer validate` and `cameleer schema` commands | part of `cameleer-main` |

Two names cover sets of features:

- `full`, the default, is every feature above.
- `core` is none of them: only what is always included.

## Choose features for your routes

1. List the schemes your routes use: the part before `:` in every `from` and `to` URI, plus any
   `kamelet:` sources.
2. List the languages you use besides Simple and JSONPath (`jq`, `groovy`, `xpath`, ...), and
   the data formats in `marshal` and `unmarshal` steps.
3. Look each one up in the table above, or open its page under Components, Languages or
   Data formats. Anything that isn't in the table is always included.
4. Add `validate` if you run `cameleer validate` with this binary, and `http2` if an `http`
   endpoint sets `httpVersion=HTTP/2`.

For example, a route that reads SQS messages, transforms them with jq and writes rows to
PostgreSQL needs `cloud,jq,sql`. A webhook that calls Slack needs only `saas`, because the
`platform-http` consumer is always included.

**A feature list replaces the default; it doesn't add to it.** `--features cloud` gives `core`
plus `cloud` and nothing else, so jq, the template engines, HTTP/2 and `cameleer validate` are
left out. Name every feature you use, for example `--features cloud,jq,validate`.

## Build it

The same feature names work in every kind of build.

### Container image

```sh
git clone https://github.com/pmsudhi/cameleer && cd cameleer
docker build --build-arg FEATURES=cloud,jq,sql -t my-cameleer .
docker run --rm my-cameleer version
```

Leave out `FEATURES` for the full image, which is what `pmsudhi/cameleer` on Docker Hub is.
`FEATURES=core` gives the smallest image.

### The `cameleer` command

```sh
cargo install cameleer-main --no-default-features --features cloud,jq,sql
```

From a clone, `cargo build --profile dist -p cameleer-main --no-default-features --features
cloud,jq,sql` builds `target/dist/cameleer`. The `dist` profile optimizes for size and speed; use
`--release` if you want a quicker build.

### AWS Lambda

```sh
scripts/package-lambda.sh --arch x86_64 --features cloud,jq --out function.zip orders.camel.yaml
```

The [deployment guide](https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html#aws-lambda) explains the rest of the Lambda setup.

### Your own Rust program

Depend only on the crates you need. `cameleer-core` and `cameleer-http` have default features
too; turn them off to drop the parts you don't use:

```toml
[dependencies]
cameleer-core = { version = "0.4", default-features = false, features = ["jq"] }
cameleer-http = { version = "0.4", default-features = false }   # HTTP/1.1 only, no gRPC crate
cameleer-cloud = "0.4"
```

To run YAML routes from Rust with a reduced set of components, depend on `cameleer-main` with
the same feature list as the command above:

```toml
cameleer-main = { version = "0.4", default-features = false, features = ["cloud", "jq"] }
```

## Check what a binary contains

`cameleer version` lists the features compiled in:

```text
$ cameleer version
Cameleer 0.4.0 (components: core, http, yaml, cloud, sql, jq)
```

A full build lists every feature.

## When something is missing

A route that uses a component or language left out of the build fails when it starts, and the
error names the feature to add:

```text
No component found with scheme: kafka (this cameleer binary was built without the `kafka-mqtt`
feature; rebuild cameleer-main with `--features kafka-mqtt`)
```

The same applies to the template components (`templates`), the `jq` language and Simple's
`${jq(...)}` (`jq`), `${xpath(...)}` (`xpath` or `xml`), `httpVersion=HTTP/2` (`http2`) and the
`cameleer validate` and `cameleer schema` commands (`validate`). Rebuild with the feature added
to your list; nothing else needs to change.

Two parts don't fail when their feature is left out. They fall back to a smaller version that is
always included:

- **`validator` without `xml`** only checks that the XML is well-formed and that its root element
  is declared in the schema. It doesn't check content models, types or facets. Add `xml` if you
  validate against an XML Schema.
- **The `xpath` language without `xml`** uses the core XPath subset when the `xpath` feature is
  in, instead of XPath 1.0 in full.

## Sizes

Linux x86-64, `dist` profile, stripped:

| build | glibc | static musl |
|---|---:|---:|
| `core` | 5.8 MB | 6.0 MB |
| every feature (`full`) | 23.9 MB | 24.1 MB |

What each part adds to `core`: `templates` 0.50 MB, `jq` 0.42 MB, `validate` 0.27 MB, `http2`
0.26 MB, `xpath` 0.09 MB. A smaller binary starts a little faster and uses less memory; startup
is about 1 ms on Linux either way. Container image sizes, cold-start times and memory are in
[BENCHMARKS.md](https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html#faas-cold-start-and-size).

## Common questions

### Do I have to choose features?

No. The default build has everything, and it is what the Docker image and `cargo install
cameleer-main` give you. Features only matter when you want a smaller binary.

### Is the full build slower than a small one?

No. Throughput is the same: a component that a route doesn't use costs nothing at run time. The
full build is only bigger on disk and takes a little longer to load.

### I upgraded and `--features cloud` lost jq (or `cameleer validate`). Why?

Since 0.4.0, the template engines, jq, the core XPath subset, HTTP/2 and `validate` are features
too, and a feature list replaces the default. Add them to your list, for example `--features
cloud,jq,validate`.

### How do I find out which feature a component needs?

Open the component's page: the header line names its feature. You can also look it up in the
table above, or build with the features you think you need and read the error, which names
the missing one.

### Does leaving out a family change how the remaining components behave?

No. Each component is the same code in every build; only which components exist changes.

## Related

- [Getting started](https://pmsudhi.github.io/cameleer/docs/guides/getting-started.html): install Cameleer and run your first route
- [Deploying Cameleer](https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html): Docker, Compose, Kubernetes, Cloud Run and AWS Lambda
- [Benchmarks](https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html): sizes, cold start and throughput

## Found a problem?

If something on this page doesn't match what Cameleer does, please
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw, or
fork the repository, fix it, add or update a test, and open a pull request.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/edge.html

# Cameleer at the edge

> Cameleer runs integration routes on gateways and small devices: a single native binary of
> about 10 MB of memory that ingests MQTT, syslog and HL7 locally, filters and aggregates on
> site, buffers when the uplink is down, and forwards to Kafka or HTTP in the cloud.

Edge gateways sit between machines and the cloud. They need to speak local protocols, keep
working offline, and fit next to other software on small hardware. Apache Camel does all of
this on a JVM; Cameleer runs the same routes without one. This cookbook shows five patterns,
each a complete route file in [`examples/edge/`](https://github.com/pmsudhi/cameleer/tree/main/examples/edge) that runs end to end in
the test suite (`crates/cameleer-main/tests/docs_guides.rs`) against the embedded MQTT and Kafka
brokers and HTTP mocks.

| pattern | file | what it shows |
|---|---|---|
| [Sensor rollups](#filter-and-aggregate-mqtt-sensor-readings) | `mqtt-sensor-rollup.camel.yaml` | MQTT in, validation, per-sensor aggregation, Kafka out |
| [Store and forward](#store-and-forward-when-the-uplink-is-down) | `store-and-forward.camel.yaml` | retries, a local file buffer and replay when the uplink is down |
| [Syslog to Kafka](#syslog-to-kafka) | `syslog-to-kafka.camel.yaml` | protocol bridging with severity filtering |
| [HL7 over MLLP](#hl7-v2-over-mllp-to-an-http-api) | `hl7-mllp-to-http.camel.yaml` | healthcare messages with acknowledgements after delivery |
| [Gateway presence](#gateway-presence-with-retained-messages-and-a-last-will) | `gateway-heartbeat.camel.yaml` | retained status and MQTT last will |

## Filter and aggregate MQTT sensor readings

Sensors publish a reading every few seconds; the cloud needs a summary. The route subscribes
to `sensors/+/temperature`, takes the sensor id from the topic, drops readings that are not
numbers or are outside the sensor's range, and aggregates five readings per sensor (or what
arrived within a minute) into one rollup with count, min, max and average. Only rollups go to
Kafka, keyed by sensor, so a sensor's rollups stay in order on one partition.

```yaml
- route:
    id: sensor-rollup
    from:
      uri: "paho:sensors/+/temperature?brokerUrl={{env:MQTT_BROKER:tcp://localhost:1883}}&qos=1&clientId={{env:GATEWAY_ID:gateway-1}}-rollup"
      steps:
        - convertBodyTo:
            type: java.lang.String
        - setHeader:
            name: sensor
            simple: "${header.CamelMqttTopic.split('/')[1]}"
        - choice:
            when:
              - simple: "${body} !regex '-?[0-9]+(\\.[0-9]+)?'"
                steps:
                  - log: "dropped malformed reading '${body}' from ${header.sensor}"
                  - stop: {}
        - convertBodyTo:
            type: java.lang.Double
        - choice:
            when:
              - simple: "${body} < -40 || ${body} > 125"
                steps:
                  - log: "dropped out-of-range reading ${body} from ${header.sensor}"
                  - stop: {}
        - aggregate:
            correlationExpression:
              header: sensor
            aggregationStrategy: "#class:org.apache.camel.processor.aggregate.GroupedBodyAggregationStrategy"
            completionSize: 5
            completionInterval: 60000
            steps:
              - setBody:
                  jq: '{gateway: "{{env:GATEWAY_ID:gateway-1}}", sensor: header("sensor"), count: length, min: min, max: max, avg: (add / length)}'
              - marshal:
                  json: {}
              - setHeader:
                  name: kafka.KEY
                  simple: "${header.sensor}"
              - to: "kafka:sensor-rollups?brokers={{env:KAFKA_BROKERS:localhost:9092}}"
```

The test publishes `20`, `garbage`, `21.5`, `999`, `22`, `23.5` and `18` for sensor `t1` and one
reading for `t2`. Kafka receives one rollup for `t1` with count 5, min 18, max 23.5 and average
21; `garbage` and `999` are dropped, and `t2` waits for its minute.

MQTT payloads arrive as bytes, so the route converts them to text first. The `jq` step
computes the statistics on the list the `GroupedBodyAggregationStrategy` collected. To keep a
rollup per minute regardless of the number of readings, drop `completionSize` and keep
`completionInterval`. Aggregation state is in memory: rollups in progress are lost on a restart,
which is usually fine for telemetry; use `forceCompletionOnStop: true` to flush them on a clean
shutdown.

## Store and forward when the uplink is down

Gateways lose their uplink: cellular dead zones, maintenance windows, cloud outages. This route
keeps every message:

1. Telemetry from MQTT goes into a `seda` queue, so the MQTT consumer is never blocked by a slow
   uplink.
2. The uplink route posts each message to the cloud. A dead letter channel retries three times
   with exponential back-off, then writes the original message to a buffer folder.
3. A replay route polls the buffer folder every 30 seconds, posts each file, and moves it to
   `.sent` when the cloud accepts it. While the uplink is still down, the post fails and the file
   stays for the next poll.

```yaml
- route:
    id: telemetry-in
    from:
      uri: "paho:telemetry/#?brokerUrl={{env:MQTT_BROKER:tcp://localhost:1883}}&qos=1&clientId={{env:GATEWAY_ID:gateway-1}}-uplink"
      steps:
        - convertBodyTo:
            type: java.lang.String
        - to: "seda:uplink?size=10000&blockWhenFull=true"
- route:
    id: uplink
    errorHandler:
      deadLetterChannel:
        deadLetterUri: "file:{{env:BUFFER_DIR:buffer}}?fileName=${date:now:yyyyMMddHHmmssSSS}-${exchangeId}.msg"
        useOriginalMessage: true
        redeliveryPolicy:
          maximumRedeliveries: 3
          redeliveryDelay: "{{env:RETRY_DELAY_MS:1000}}"
          useExponentialBackOff: true
    from:
      uri: "seda:uplink?size=10000"
      steps:
        - setHeader:
            name: X-Gateway
            constant: "{{env:GATEWAY_ID:gateway-1}}"
        - enrich:
            uri: "{{env:UPLINK_URL:http://localhost:9000}}/telemetry?httpMethod=POST"
- route:
    id: replay-buffer
    from:
      uri: "file:{{env:BUFFER_DIR:buffer}}?include=.*\\.msg&sortBy=file:name&move=.sent&delay={{env:REPLAY_DELAY_MS:30000}}"
      steps:
        - convertBodyTo:
            type: java.lang.String
        - setHeader:
            name: X-Gateway
            constant: "{{env:GATEWAY_ID:gateway-1}}"
        - setHeader:
            name: X-Replayed
            constant: "true"
        - enrich:
            uri: "{{env:UPLINK_URL:http://localhost:9000}}/telemetry?httpMethod=POST"
```

The test starts with the cloud mock answering `503`: the message is tried four times and lands
in the buffer. When the mock recovers, the replay posts it (with `X-Replayed: true`) and moves
the file to `.sent`, and new messages go straight through.

Why `enrich` and not `to` for the uplink call: `enrich` sends a copy, so every retry posts the
original message. With `to`, Cameleer's `http` producer puts the error response into the message
before it fails, and a retry would post that instead (Apache Camel leaves the message unchanged).

Things to tune for production:

- Mount the buffer on persistent storage (`-v cameleer-buffer:/buffer`); the container root can
  stay read-only.
- `seda` is in memory: messages queued there when the process stops are lost. For zero loss
  across restarts, write to the buffer folder first and let the replay route be the only sender,
  at the cost of disk writes for every message.
- Order is kept per buffer folder (`sortBy=file:name`), not between live and replayed messages.
  Put a timestamp in the payload if the cloud must reorder.

## Protocol bridging

Bridges translate between what the site speaks and what the cloud accepts. The two routes
above already bridge MQTT to Kafka and MQTT to HTTP. Two more common ones follow.

### Syslog to Kafka

Routers, switches, PLCs and Linux hosts all speak syslog. The `syslog` component receives RFC
5424 and RFC 3164 messages over UDP or TCP (and TLS), parses them into a map, and sets headers
such as `CamelSyslogSeverity`, `CamelSyslogFacility` and `CamelSyslogHostname`. This route keeps
warnings and worse and sends them to Kafka as JSON.

```yaml
- route:
    id: syslog-alerts
    from:
      uri: "syslog:udp://{{env:SYSLOG_HOST:0.0.0.0}}:{{env:SYSLOG_PORT:5514}}"
      steps:
        - filter:
            simple: "${header.CamelSyslogSeverity} in 'EMERG,ALERT,CRIT,ERR,WARNING'"
            steps:
              - setHeader:
                  name: kafka.KEY
                  simple: "${header.CamelSyslogHostname}"
              - marshal:
                  json: {}
              - to: "kafka:syslog-alerts?brokers={{env:KAFKA_BROKERS:localhost:9092}}"
```

The test sends a `local4.notice` message (dropped) and an `auth.crit` message (forwarded to the
`syslog-alerts` topic, keyed by `router-1`).

### HL7 v2 over MLLP to an HTTP API

Hospital systems exchange HL7 v2 over MLLP. The `mllp` component frames and acknowledges
messages and sets `CamelMllp*` headers (message type, event, control id, sending application);
the `hl7terser` language reads fields by path (`PID-3-1` is the patient id). The acknowledgement
goes back after the route finishes, so the sender gets `AA` only once the EHR accepted the
message, and `AE` when it still failed after five retries, so it keeps the message and resends.

```yaml
- route:
    id: hl7-to-ehr
    errorHandler:
      defaultErrorHandler:
        redeliveryPolicy:
          maximumRedeliveries: 5
          redeliveryDelay: "{{env:RETRY_DELAY_MS:2000}}"
    from:
      uri: "mllp://{{env:MLLP_HOST:0.0.0.0}}:{{env:MLLP_PORT:2575}}"
      steps:
        - filter:
            simple: "${header.CamelMllpEventType} == 'ADT'"
            steps:
              - setHeader:
                  name: X-Patient-Id
                  hl7terser: "PID-3-1"
              - setHeader:
                  name: X-Message-Control-Id
                  simple: "${header.CamelMllpMessageControlId}"
              - setHeader:
                  name: Content-Type
                  constant: application/hl7-v2
              - enrich:
                  uri: "{{env:EHR_URL:http://localhost:9000}}/hl7/v2?httpMethod=POST"
```

The test sends an ADT message (posted, `AA`), an ORU message (acknowledged, not posted) and an
ADT message the EHR rejects (six posts with the original message, then `AE`). For TLS between
the systems, add `sslContextParameters=#ssl` to the `mllp` URI.

## Gateway presence with retained messages and a last will

Dashboards need to know which gateways are alive without polling them. The heartbeat route
publishes a retained `online` status every 30 seconds. Its MQTT connection registers a last will
of `offline`, retained too: if the gateway loses power or network, the broker publishes it.
Anyone subscribing to `gateways/+/status` gets the current state of every gateway at once.

```yaml
- route:
    id: gateway-heartbeat
    from:
      uri: "timer:heartbeat?period={{env:HEARTBEAT_MS:30000}}"
      steps:
        - setBody:
            constant: online
        - to: "paho:gateways/{{env:GATEWAY_ID:gateway-1}}/status?brokerUrl={{env:MQTT_BROKER:tcp://localhost:1883}}&clientId={{env:GATEWAY_ID:gateway-1}}-status&qos=1&retained=true&willTopic=gateways/{{env:GATEWAY_ID:gateway-1}}/status&willPayload=offline&willQos=1&willRetained=true"
```

The test checks that the broker holds the retained `online` status and that the gateway is
connected under its own client id. The broker sends the will only on an abnormal disconnect;
a clean stop of the route does not mark the gateway offline, so publish `offline` from an
`onCompletion` or a shutdown route if you need that too.

## Small footprint deployment

The Docker image `pmsudhi/cameleer` is one native binary on a distroless base, for `linux/amd64`
and `linux/arm64`, about 20 MB to download (12.5 MB built with `FEATURES=core`). A running route uses about 10 MB of memory (8 MB at startup in the
[benchmarks](https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html)) and starts its routes in milliseconds. Nothing is written to
the filesystem unless a route writes files, so the container runs with a read-only root:

```sh
docker run -d --name edge-routes --restart unless-stopped \
  --read-only --memory 64m --cpus 0.5 \
  --network host \
  -e MQTT_BROKER=tcp://localhost:1883 -e KAFKA_BROKERS -e GATEWAY_ID=plant-7 \
  -v "$PWD/routes:/routes:ro" \
  pmsudhi/cameleer run /routes/mqtt-sensor-rollup.camel.yaml
```

- **arm64 boards:** the same image runs on 64-bit Raspberry Pi OS (Pi 3, 4 and 5), NVIDIA
  Jetson, AWS Graviton and other arm64 Linux devices; Docker picks the right platform. There is
  no published 32-bit ARM image.
- **No container runtime:** `cargo install cameleer-main` builds the `cameleer` binary on the
  device (or cross-compile it: Cameleer has no dependencies outside the Rust standard library),
  then run it under systemd, for example `cameleer run /etc/cameleer/rollup.camel.yaml`.
- **Several route files:** pass several files to `run` (or none, to load every route file in
  the working directory); they share one process.
- **Health:** add `--prop camel.server.enabled=true --prop camel.server.healthCheckEnabled=true`
  for `/q/health/live` and `/q/health/ready` on port 8080. See the
  [deployment guide](https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html).

## Offline-first patterns

- **Decide locally.** Filters, thresholds and aggregation run on the gateway, so alarms fire
  without the cloud. A `choice` that writes to a local actuator topic (`paho:...`) keeps working
  when the uplink is gone.
- **Buffer, then forward.** A dead letter channel to `file:` plus a replay route is a durable
  outbox in a few lines of YAML. Use `seda` with `blockWhenFull=true` in front of slow calls.
- **Make delivery idempotent.** Replays and MQTT QoS 1 can deliver a message twice. Give each
  message an id at the edge and use an `idempotentConsumer` at the receiving side.
- **Report presence with the broker.** Retained status messages and a last will tell the cloud
  what is offline without a polling loop.
- **Thin out telemetry.** `sample` and `throttle` keep the uplink bill under control; aggregate
  before sending.

## Common questions

### Can Cameleer run on a Raspberry Pi?

Yes, on a 64-bit OS: the `pmsudhi/cameleer` image is published for `linux/arm64`, and a route
uses about 10 MB of memory. 32-bit ARM images are not published.

### How do I bridge MQTT to Kafka?

Use a route from `paho:topic/#?brokerUrl=tcp://...` to `kafka:topic?brokers=...`, converting the
payload with `convertBodyTo` and setting `kafka.KEY` from the MQTT topic if you need per-device
ordering. The [sensor rollup example](#filter-and-aggregate-mqtt-sensor-readings) shows it with
filtering and aggregation.

### What happens to messages when the internet connection drops?

Without precautions, a failed call fails the exchange. With a dead letter channel to a local
`file:` folder and a replay route, as in [store and forward](#store-and-forward-when-the-uplink-is-down),
messages wait on disk and are sent when the uplink returns.

### Does Cameleer support MQTT 5 and TLS?

Yes. `paho` speaks MQTT 3.1.1 and `paho-mqtt5` MQTT 5.0, both with QoS 0, 1 and 2, retained
messages, wills, persistent sessions, automatic reconnect and `ssl://` broker URLs. WebSocket
transports and shared subscriptions are not supported.

### Which industrial and healthcare protocols are supported?

MQTT, syslog, HL7 v2 over MLLP, TCP and UDP (`netty`), HTTP, WebSocket, FTP and SFTP, Kafka, AMQP
and STOMP. There are no OPC UA, Modbus or PLC4X components; reach those through an MQTT or HTTP
gateway.

## Related

- [EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html): [aggregate](https://pmsudhi.github.io/cameleer/docs/guides/eips/split-aggregate.html#aggregator),
  [sample and throttle](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html)
- [Error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html), [deployment guide](https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html),
  [benchmarks](https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html)
- Components: [paho](https://pmsudhi.github.io/cameleer/docs/components/paho.html), [kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html),
  [syslog](https://pmsudhi.github.io/cameleer/docs/components/syslog.html), [mllp](https://pmsudhi.github.io/cameleer/docs/components/mllp.html), [file](https://pmsudhi.github.io/cameleer/docs/components/file.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/faq.html

# Cameleer FAQ

> Short, factual answers to the questions people ask about Cameleer: what it is, how it relates
> to Apache Camel, how fast it is, where it runs, and how to use it with Kafka, LLMs and edge
> devices.

## About Cameleer

### What is Cameleer?

Cameleer is Apache Camel rewritten in Rust: an integration framework with the same routes,
Enterprise Integration Patterns, endpoint URIs, Simple language and YAML DSL, shipped as one
native binary with no dependencies outside the Rust standard library. See the
[README](https://github.com/pmsudhi/cameleer/blob/main/README.md) and [concepts](https://pmsudhi.github.io/cameleer/docs/guides/concepts.html).

### Is Cameleer compatible with Apache Camel?

It follows Camel 4's names and semantics: Camel YAML and XML routes, URIs, options, EIPs, Simple
expressions and `Camel*` headers work unchanged for the supported components. Java code
(processors, beans, custom components) does not run; it is rewritten in Rust. See
[migrating from Apache Camel](https://pmsudhi.github.io/cameleer/docs/guides/migrating-from-apache-camel.html).

### Is Cameleer affiliated with the Apache Software Foundation?

No. It is an independent project that follows Apache Camel's design and documentation but
contains no Camel source code, and it is not endorsed by the ASF. Apache Camel is a trademark of
the ASF.

### What was Cameleer called before?

rust-camel, up to version 0.1.0.

### What license does Cameleer use?

The Apache License 2.0 ([LICENSE](https://github.com/pmsudhi/cameleer/blob/main/LICENSE)).

## Performance and footprint

### How fast is Cameleer?

With the same routes, Cameleer handles 1.7 to 8.7 times the throughput of Apache Camel 4.23 on
Java 21 in every scenario measured: 2.1x on a REST API with JSON, 2.3x writing to PostgreSQL,
1.7x publishing to Kafka, 8.7x on Kafka stream processing and 3.0x on a content-based router.
Every scenario, the method and the raw data are on the
[Apache Camel vs Cameleer](https://pmsudhi.github.io/cameleer/compare/apache-camel-vs-cameleer/)
page and in [BENCHMARKS.md](https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html).

### How much memory does it use?

A route uses about 10 MB: 8 MB at startup, and 8 to 68 MB at peak across the benchmark scenarios,
against 213 to 440 MB for Apache Camel on the JVM (up to 54 times less). See
[BENCHMARKS.md](https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html).

### How long does it take to start?

3 ms from process start to routes running in the benchmark, against 1.1 s for Apache Camel on
the JVM and 30 ms compiled natively with Quarkus. A function build with only the components it
needs starts in under 1 ms. That makes scale-to-zero and serverless practical
([BENCHMARKS.md](https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html#faas-cold-start-and-size)).

### How big is the Docker image?

The `pmsudhi/cameleer` image is about 20 MB to download: one native binary on a distroless base. Built with only the
component families you need it is smaller: 14.5 MB with `FEATURES=cloud`, 12.5 MB with
`FEATURES=core`.
See the [deployment guide](https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html).

## Running it

### How do I install Cameleer?

Run the Docker image `pmsudhi/cameleer`, install the CLI with `cargo install cameleer-main`, or add
the `cameleer-core` crate (plus component crates) to a Rust project. See
[getting started](https://pmsudhi.github.io/cameleer/docs/guides/getting-started.html).

### Do I need Java, Maven or a JVM?

No. Cameleer is a native binary. Rust is needed only to build it from source or to embed it in a
Rust program.

### Can I run it on a Raspberry Pi?

Yes, on a 64-bit OS: the image is published for `linux/arm64` (Raspberry Pi 3, 4 and 5 with
64-bit Raspberry Pi OS), and a route uses about 10 MB of memory. There is no 32-bit ARM image.
See [Cameleer at the edge](https://pmsudhi.github.io/cameleer/docs/guides/edge.html#small-footprint-deployment).

### Does it run on Kubernetes, Cloud Run or AWS Lambda?

Kubernetes, Docker Compose, Google Cloud Run, Azure Container Apps, Knative and ECS/Fargate run
the container image as it is ([deployment guide](https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html)). On AWS Lambda, `cameleer`
is its own custom runtime for `provided.al2023`: API Gateway and function URL events go to your
`platform-http` routes, other events to `direct:lambda`
([AWS Lambda](https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html#aws-lambda)).

### Does it run on Windows and macOS?

Yes. The CLI builds and runs on Linux, macOS and Windows (the test suite passes on Windows 11);
the Docker image is Linux (amd64 and arm64).

### Can it run with a read-only filesystem?

Yes. The container writes nothing unless a route writes files, and it works with `--read-only`
and Kubernetes' `readOnlyRootFilesystem: true`.

### How do I check that it is healthy?

Start it with `--prop camel.server.enabled=true --prop camel.server.healthCheckEnabled=true` and
probe `/q/health/live` and `/q/health/ready` on port 8080, or run
`cameleer get health --url http://localhost:8080`.

## Features

### Which Enterprise Integration Patterns does it support?

All the patterns of Apache Camel's EIP catalogue, including split, aggregate, multicast,
recipient list, routing slip, dynamic router, wire tap, enrich, idempotent consumer, load
balancer, resequencer, throttle, circuit breaker, saga and transacted. See [EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html).

### Does it support Kafka?

Yes. The `kafka` component has its own Kafka wire protocol client: producer and consumer groups,
keys and partitions, offsets and commits, TLS and SASL (PLAIN, SCRAM, AWS MSK IAM). It is
verified with librdkafka, kcat and the kfake Kafka simulator. See the
[kafka component](https://pmsudhi.github.io/cameleer/docs/components/kafka.html).

### Does it support MQTT?

Yes: `paho` (MQTT 3.1.1) and `paho-mqtt5` (MQTT 5.0) with QoS 0 to 2, retained messages, wills,
persistent sessions and TLS, tested against Mosquitto, RabbitMQ and ActiveMQ. See
[the edge cookbook](https://pmsudhi.github.io/cameleer/docs/guides/edge.html).

### Which databases and clouds does it connect to?

PostgreSQL (`sql`, `jdbc`), Redis, MongoDB, Elasticsearch and OpenSearch, Cassandra and CouchDB,
plus all of Apache Camel's AWS, Azure and Google Cloud components (S3, SQS, SNS, DynamoDB,
Lambda, Bedrock, Blob Storage, Service Bus, Event Hubs, Cosmos DB, Cloud Storage, Pub/Sub,
BigQuery, Vertex AI and more). See [FEATURES.md](https://pmsudhi.github.io/cameleer/docs/FEATURES.html).

### Does it have every Camel component?

No. It has about 230 components, languages and data formats, chosen from the most used ones, but
not Camel's long tail of vendor connectors. [FEATURES.md](https://pmsudhi.github.io/cameleer/docs/FEATURES.html) lists what is there.

### Can I write routes in YAML, XML or code?

All three: Camel's YAML DSL, Camel's XML DSL, and a Rust DSL equivalent to Camel's Java DSL.
They support the same EIPs. See [concepts](https://pmsudhi.github.io/cameleer/docs/guides/concepts.html#the-three-dsls).

### Does it support REST APIs and OpenAPI?

Yes. The REST DSL (`rest:` in YAML, `b.rest(...)` in Rust) declares endpoints with path and query
parameters, JSON binding and CORS, and generates an OpenAPI 3 document.

## AI and agents

### How do I use Cameleer with an LLM?

Send the prompt as the message body to `openai:chat-completion?model=...` (OpenAI or any
OpenAI-compatible server such as Ollama or vLLM), `aws-bedrock`, `azure-openai` or
`google-vertexai`; the answer becomes the body, and you route on it with `choice`. See
[Cameleer for AI agents](https://pmsudhi.github.io/cameleer/docs/guides/agents.html).

### Can an AI agent call Cameleer routes as tools?

Yes. Expose a route over REST and add JSON schema validation, an idempotent consumer, retries
and an audit log, as in the [tool API pattern](https://pmsudhi.github.io/cameleer/docs/guides/agents.html#expose-a-tool-to-an-agent-over-rest).
A packaged MCP server is planned ([roadmap](https://pmsudhi.github.io/cameleer/docs/ROADMAP.html)).

### Does Cameleer run models or store embeddings?

No. It calls model APIs and writes embeddings to the stores you run, such as Elasticsearch,
OpenSearch or PostgreSQL with pgvector. See [RAG ingestion](https://pmsudhi.github.io/cameleer/docs/guides/agents.html#rag-ingestion-chunk-embed-and-store).

## Quality and support

### Is Cameleer production ready?

The feature list is complete against its 228-row parity table, with 2,300+ hermetic tests and
verification against real servers, official clients and emulators ([INTEROP.md](https://pmsudhi.github.io/cameleer/docs/INTEROP.html)).
Two caveats: it is young (version 0.2), and its from-scratch TLS and crypto code has not had an
independent security audit yet ([STATUS.md](https://pmsudhi.github.io/cameleer/docs/STATUS.html)). Evaluate it on your own workload.

### How is it tested?

With 2,300+ hermetic tests against embedded servers, live suites against real PostgreSQL, Redis,
RabbitMQ, ActiveMQ, Mosquitto, vsftpd, Postfix/Dovecot and nginx, official clients (librdkafka,
pymongo, the DataStax driver, boto3, the Azure SDK, gcloud, grpcio) and emulators (moto, Azurite,
fake-gcs-server, FerretDB). Every example in these guides runs in the test suite.

### Why are there no third-party dependencies?

The project was written with only the Rust standard library: TLS, HTTP/2, gRPC, the Kafka, AMQP,
MQTT, PostgreSQL, Redis, MongoDB and Cassandra protocols, XML and JSON are implemented from
scratch. There is no dependency tree to audit or patch, and builds need no downloads.

### How do I report a bug or a security issue?

Open an issue on [GitHub](https://github.com/pmsudhi/cameleer/issues) for bugs; report
vulnerabilities privately as described in [SECURITY.md](https://github.com/pmsudhi/cameleer/blob/main/SECURITY.md).

## Related

- [Getting started](https://pmsudhi.github.io/cameleer/docs/guides/getting-started.html), [concepts](https://pmsudhi.github.io/cameleer/docs/guides/concepts.html), [EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html)
- [Migrating from Apache Camel](https://pmsudhi.github.io/cameleer/docs/guides/migrating-from-apache-camel.html)
- [Benchmarks](https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html), [features](https://pmsudhi.github.io/cameleer/docs/FEATURES.html), [roadmap](https://pmsudhi.github.io/cameleer/docs/ROADMAP.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/agents.html

# Cameleer for AI agents

> Cameleer is the action layer for AI agents: the model decides what, a tested route decides
> how. It feeds events to models, routes on their answers, and turns agent tool calls into
> reliable actions with validation, idempotency, retries, sagas, human approval, rate limits,
> fallbacks and an audit log.

An agent decides what to do; a route does it. This cookbook shows eight patterns, each a
complete route file in [`examples/agents/`](https://github.com/pmsudhi/cameleer/tree/main/examples/agents) that runs end to end in the
test suite (`crates/cameleer-main/tests/docs_guides.rs`) against an OpenAI-compatible mock, the
embedded Kafka broker, an Elasticsearch emulator and Slack and payment API mocks.

The routes use the [`openai` component](https://pmsudhi.github.io/cameleer/docs/components/openai.html), which works with OpenAI and
every OpenAI-compatible server: Azure OpenAI gateways, Ollama, vLLM, LM Studio and LiteLLM.
Point it at another server with `OPENAI_BASE_URL` and `OPENAI_MODEL`. The component reads the
API key from the `OPENAI_API_KEY` environment variable, so the key never appears in a route.
AWS Bedrock (`aws-bedrock`), Azure OpenAI (`azure-openai`) and Google Vertex AI
(`google-vertexai`) work the same way in these patterns; see [AI components](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html).

| pattern | file | what it shows |
|---|---|---|
| [Classify and route](#classify-with-an-llm-and-route-on-the-answer) | `llm-classify-route.camel.yaml` | an LLM label drives a content-based router, with a fixed list of trusted labels |
| [Summarize](#summarization-pipeline) | `llm-summarize-pipeline.camel.yaml` | map-reduce summaries of long documents |
| [RAG ingestion](#rag-ingestion-chunk-embed-and-store) | `rag-ingest.camel.yaml` | chunk, embed and index documents in Elasticsearch |
| [Tools over REST](#expose-a-tool-to-an-agent-over-rest) | `agent-tool-api.camel.yaml` | schema validation, idempotency, retries and an audit log for agent tool calls |
| [Human approval](#human-in-the-loop-approval) | `human-approval.camel.yaml` | park risky actions until a person approves them |
| [Guard LLM output](#guard-llm-output-with-a-json-schema) | `llm-output-guard.camel.yaml` | validate model JSON against a schema, re-ask once |
| [Rate limits and breakers](#rate-limits-and-a-circuit-breaker-around-a-model-api) | `llm-rate-limit-breaker.camel.yaml` | throttle and circuit breaker around a model API |
| [Multi-model fallback](#multi-model-fallback) | `llm-multi-model-fallback.camel.yaml` | fail over from a hosted model to a local one |

## Classify with an LLM and route on the answer

Tickets arrive over HTTP. The model labels each one, and a `choice` sends the original ticket
to a Kafka topic per label. Two details make this safe to run:

- The ticket is kept in an exchange property and put back after the model call, so the
  topic receives the ticket, not the model's answer.
- The router compares the label against a fixed list. Anything else, including a ticket that
  tries "ignore previous instructions", goes to the general topic. Never use the model's
  answer directly in `toD` or as a topic name.

```yaml
- route:
    id: classify-ticket
    from:
      uri: "platform-http:/tickets?httpMethodRestrict=POST"
      steps:
        - convertBodyTo:
            type: java.lang.String
        - setProperty:
            name: ticket
            simple: "${body}"
        - to: "openai:chat-completion?model={{env:OPENAI_MODEL:gpt-4o-mini}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}&temperature=0&systemMessage=Label the support ticket with exactly one word. billing for payments and invoices, technical for errors and outages, other for everything else."
        - setHeader:
            name: category
            simple: "${body.trim().toLowerCase()}"
        - setBody:
            simple: "${exchangeProperty.ticket}"
        - choice:
            when:
              - simple: "${header.category} == 'billing'"
                steps:
                  - to: "kafka:tickets-billing?brokers={{env:KAFKA_BROKERS:localhost:9092}}"
              - simple: "${header.category} == 'technical'"
                steps:
                  - to: "kafka:tickets-technical?brokers={{env:KAFKA_BROKERS:localhost:9092}}"
            otherwise:
              steps:
                - setHeader:
                    name: category
                    constant: other
                - to: "kafka:tickets-general?brokers={{env:KAFKA_BROKERS:localhost:9092}}"
        - setHeader:
            name: CamelHttpResponseCode
            constant: 202
        - setHeader:
            name: Content-Type
            constant: application/json
        - setBody:
            simple: '{"category": "${header.category}"}'
```

The test sends three tickets: an invoice question goes to `tickets-billing`, an error report to
`tickets-technical`, and a prompt-injection attempt (the model answers with an invented label)
to `tickets-general`.

```sh
docker run --rm --network host -e KAFKA_BROKERS=localhost:9092 -e OPENAI_API_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/llm-classify-route.camel.yaml
```

To classify events from Kafka instead of HTTP, replace the `from` URI with
`kafka:support-tickets?brokers=...&groupId=triage`, as in
[ai-ticket-triage.camel.yaml](https://github.com/pmsudhi/cameleer/blob/main/examples/ai-ticket-triage.camel.yaml).

## Summarization pipeline

Long documents do not fit in one prompt, and one huge prompt is slow and expensive. The route
splits each document into paragraphs, summarizes each paragraph, and asks the model to combine
the partial summaries. The split's `GroupedBodyAggregationStrategy` collects the summaries into
a list, and a list body is sent to the `openai` component as one user message per item.

```yaml
- route:
    id: summarize-documents
    from:
      uri: "file:{{env:INBOX_DIR:inbox}}?include=.*\\.txt&move=.done&moveFailed=.failed"
      steps:
        - convertBodyTo:
            type: java.lang.String
        - split:
            tokenize: "\n\n"
            aggregationStrategy: "#class:org.apache.camel.processor.aggregate.GroupedBodyAggregationStrategy"
            steps:
              - to: "openai:chat-completion?model={{env:OPENAI_MODEL:gpt-4o-mini}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}&temperature=0&systemMessage=Summarize this paragraph in one sentence."
        - to: "openai:chat-completion?model={{env:OPENAI_MODEL:gpt-4o-mini}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}&temperature=0&systemMessage=The messages are summaries of consecutive paragraphs of one document. Combine them into a summary of at most five sentences."
        - to: "file:{{env:OUTBOX_DIR:outbox}}?fileName=${file:onlyname.noext}.summary.txt"
        - log: "summarized ${file:name} (${header.CamelOpenAITotalTokens} tokens for the last call)"
```

Drop `report.txt` into the inbox and `report.summary.txt` appears in the outbox. The test checks
that a three-paragraph document makes four model calls (three paragraphs, one combine). Add
`parallelProcessing: true` to the split to summarize paragraphs concurrently, and a
[throttle](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html#throttle) to stay under the provider's rate limit.

## RAG ingestion: chunk, embed and store

Retrieval-augmented generation needs an index of your documents. This route watches a folder,
splits each document into paragraph chunks, embeds each chunk with `openai:embeddings`, and
indexes `{source, chunk, text, embedding}` in Elasticsearch or OpenSearch under the id
`<file>-<chunk>`, so re-dropping a changed file overwrites its chunks.

```yaml
- route:
    id: rag-ingest
    from:
      uri: "file:{{env:INBOX_DIR:docs}}?include=.*\\.(md|txt)&move=.indexed&moveFailed=.failed"
      steps:
        - convertBodyTo:
            type: java.lang.String
        - setHeader:
            name: docId
            simple: "${file:onlyname.noext}"
        - split:
            tokenize: "\n\n"
            steps:
              - filter:
                  simple: "${body.trim()} != ''"
                  steps:
                    - setProperty:
                        name: chunk
                        simple: "${body.trim()}"
                    - to: "openai:embeddings?model={{env:EMBEDDING_MODEL:text-embedding-3-small}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}"
                    - setHeader:
                        name: indexId
                        simple: "${header.docId}-${exchangeProperty.CamelSplitIndex}"
                    - setBody:
                        jq: '{source: header("CamelFileName"), chunk: property("CamelSplitIndex"), text: property("chunk"), embedding: .}'
                    - to: "elasticsearch://rag?hostAddresses={{env:ES_HOSTS:localhost:9200}}&indexName={{env:ES_INDEX:docs}}&operation=Index"
        - log: "indexed ${file:name}"
```

The `jq` step builds the document: `.` is the embedding vector returned by the model, and
`header()` and `property()` read the file name and the chunk text. Empty chunks are skipped
by the filter. The same shape works for other sources (`aws2-s3`, `google-drive`, `sftp`, `mail`)
and other stores: PostgreSQL with pgvector through the [`sql` component](https://pmsudhi.github.io/cameleer/docs/components/sql.html),
or a vector database's REST API through [`http`](https://pmsudhi.github.io/cameleer/docs/components/http.html). Create the index with a
`dense_vector` (Elasticsearch) or `knn_vector` (OpenSearch) mapping before you ingest.

## Expose a tool to an agent over REST

Agents call tools; a tool is a route behind an HTTP endpoint. This refund tool shows the four
things every side-effecting tool needs:

1. **Validated arguments.** `json-validator` checks the call against
   [schemas/refund-request.json](https://github.com/pmsudhi/cameleer/blob/main/examples/agents/schemas/refund-request.json), the same
   schema you give the agent in its tool definition. A bad call gets `400` with every error, so
   the agent can correct itself.
2. **Idempotency.** Agents retry. `idempotentConsumer` on the `requestId` argument makes sure a
   repeated call does not refund twice; the repeat gets `{"status": "duplicate"}`.
3. **Retries.** The payments call is retried three times with exponential back-off on HTTP
   errors and I/O errors, then answered with `502`.
4. **An audit log.** A wire tap appends every accepted call to `tool-calls.jsonl` without slowing
   the call down.

```yaml
- rest:
    path: /tools
    post:
      - path: /refund
        to: direct:refund-tool
- routeConfiguration:
    onException:
      - onException:
          exception:
            - org.apache.camel.component.jsonvalidator.JsonValidationException
          handled:
            constant: true
          steps:
            - setHeader:
                name: CamelHttpResponseCode
                constant: 400
            - setBody:
                simple: "invalid tool arguments: ${exception.message}"
      - onException:
          exception:
            - org.apache.camel.http.base.HttpOperationFailedException
            - java.io.IOException
          redeliveryPolicy:
            maximumRedeliveries: 3
            redeliveryDelay: 200
            useExponentialBackOff: true
          handled:
            constant: true
          steps:
            - setHeader:
                name: CamelHttpResponseCode
                constant: 502
            - setBody:
                simple: "payments API unavailable, the refund was not confirmed; retry later with the same requestId"
- route:
    id: refund-tool
    from:
      uri: direct:refund-tool
      steps:
        - convertBodyTo:
            type: java.lang.String
        - to: "json-validator:file:{{env:SCHEMA_DIR:schemas}}/refund-request.json"
        - unmarshal:
            json: {}
        - setHeader:
            name: requestId
            simple: "${body[requestId]}"
        - wireTap:
            uri: direct:audit
        - idempotentConsumer:
            header: requestId
            steps:
              - removeHeaders:
                  pattern: "CamelHttp*"
              - marshal:
                  json: {}
              - enrich:
                  uri: "{{env:PAYMENTS_URL:http://localhost:9000}}/refunds?httpMethod=POST"
              - setBody:
                  simple: '{"status": "refunded", "requestId": "${header.requestId}", "payment": ${body}}'
        - filter:
            simple: "${exchangeProperty.CamelDuplicateMessage} == true"
            steps:
              - setBody:
                  simple: '{"status": "duplicate", "requestId": "${header.requestId}"}'
        - setHeader:
            name: Content-Type
            constant: application/json
- route:
    id: audit-tool-calls
    from:
      uri: direct:audit
      steps:
        - marshal:
            json: {}
        - setBody:
            simple: "${body}\n"
        - to: "file:{{env:AUDIT_DIR:audit}}?fileName=tool-calls.jsonl&fileExist=Append"
```

Two details in the payments call:

- `removeHeaders: CamelHttp*` comes first, because the incoming request's `CamelHttpUri` and
  `CamelHttpPath` headers would otherwise change where the `http` producer sends the request,
  as in Apache Camel.
- The call is an `enrich`, not a `to`. `enrich` sends a copy of the message, so a retry sends
  the original request again. With `to`, a retry after an HTTP error would send the error
  response instead, because Cameleer's `http` producer puts the response into the message
  before it fails (Apache Camel leaves the message unchanged). The reply of a successful call
  replaces the body, as with `to`.

The test makes the payments mock fail the first call with `503`, and checks the retry, the
duplicate, the `400` for a call without `orderId` and with an amount over the schema's maximum,
and the two audit lines.

For a tool that spans several systems (refund, return label, email) in one call, with a saga
that rolls back half-done work, see
[AI agent tool calls: direct vs through Cameleer](https://pmsudhi.github.io/cameleer/docs/guides/agent-tool-calls.html).

For one endpoint per tool without one route per tool, use `toD: direct:tool-${header.name}` on
a path parameter, with a fixed set of `direct:` routes behind it. A packaged MCP server is on the
[roadmap](https://pmsudhi.github.io/cameleer/docs/ROADMAP.html).

## Human-in-the-loop approval

Some actions should not run on the model's word alone. Here refunds up to `APPROVAL_LIMIT` run at
once. Larger ones are written to a `pending` folder, and a Slack message asks a person to
approve. The approval endpoint takes the parked action with `pollEnrich` (deleting the file) and
executes it, so an action runs at most once even if the link is clicked twice.

```yaml
- rest:
    post:
      - path: /actions
        to: direct:propose
      - path: /approvals/{id}
        to: direct:approve
- route:
    id: propose-action
    from:
      uri: direct:propose
      steps:
        - convertBodyTo:
            type: java.lang.String
        - setProperty:
            name: action
            simple: "${body}"
        - unmarshal:
            json: {}
        - setHeader:
            name: actionId
            simple: "${body[actionId]}"
        - choice:
            when:
              - simple: "${body[amount]} <= {{env:APPROVAL_LIMIT:100}}"
                steps:
                  - setBody:
                      simple: "${exchangeProperty.action}"
                  - to: direct:execute
                  - setBody:
                      simple: '{"status": "executed", "actionId": "${header.actionId}"}'
            otherwise:
              steps:
                - setBody:
                    simple: "${exchangeProperty.action}"
                - to: "file:{{env:PENDING_DIR:pending}}?fileName=${header.actionId}.json"
                - setBody:
                    simple: "Agent wants to refund ${jsonpath($.amount)} on order ${jsonpath($.orderId)}. Approve: {{env:PUBLIC_URL:http://localhost:8080}}/approvals/${header.actionId}"
                - to: "slack:#approvals?webhookUrl={{env:SLACK_WEBHOOK_URL}}"
                - setHeader:
                    name: CamelHttpResponseCode
                    constant: 202
                - setBody:
                    simple: '{"status": "pending_approval", "actionId": "${header.actionId}"}'
- route:
    id: approve-action
    from:
      uri: direct:approve
      steps:
        - setProperty:
            name: actionId
            simple: "${header.id}"
        - pollEnrich:
            uri: "file:{{env:PENDING_DIR:pending}}?fileName=${header.id}.json&delete=true"
            timeout: 1000
        - choice:
            when:
              - simple: "${body} == null"
                steps:
                  - setHeader:
                      name: CamelHttpResponseCode
                      constant: 404
                  - setBody:
                      simple: "no pending action ${exchangeProperty.actionId}"
            otherwise:
              steps:
                - to: direct:execute
                - setBody:
                    simple: '{"status": "executed", "actionId": "${exchangeProperty.actionId}"}'
- route:
    id: execute-action
    from:
      uri: direct:execute
      steps:
        - removeHeaders:
            pattern: "CamelHttp*"
        - to: "{{env:PAYMENTS_URL:http://localhost:9000}}/refunds?httpMethod=POST"
```

The test proposes a 40 refund (executed at once) and a 350 refund (parked, Slack message with
the approval link), approves it, checks that the payments API got it, and checks that a second
approval answers `404`. Protect `/approvals` with your SSO or API gateway: anyone who can call it
can approve. To approve from Slack buttons instead of links, point a Slack interactivity URL at
a `platform-http` route that parses the payload.

## Guard LLM output with a JSON schema

When a model's answer feeds another system, check it first. The route asks for JSON, validates
it with `json-validator` against
[schemas/invoice.json](https://github.com/pmsudhi/cameleer/blob/main/examples/agents/schemas/invoice.json), and on failure asks once
more, passing the validation errors back to the model. A second failure becomes `422`, so bad
data never reaches the caller.

```yaml
- route:
    id: extract-invoice
    from:
      uri: "platform-http:/extract?httpMethodRestrict=POST"
      steps:
        - convertBodyTo:
            type: java.lang.String
        - setProperty:
            name: document
            simple: "${body}"
        - doTry:
            steps:
              - to: direct:ask-for-json
            doCatch:
              - exception:
                  - org.apache.camel.ValidationException
                steps:
                  - setBody:
                      simple: "Your previous answer was rejected. ${exception.message}. Reply with corrected JSON only. Document follows. ${exchangeProperty.document}"
                  - doTry:
                      steps:
                        - to: direct:ask-for-json
                      doCatch:
                        - exception:
                            - org.apache.camel.ValidationException
                          steps:
                            - setHeader:
                                name: CamelHttpResponseCode
                                constant: 422
                            - setBody:
                                simple: "the model did not return a valid invoice: ${exception.message}"
        - setHeader:
            name: Content-Type
            constant: application/json
- route:
    id: ask-for-json
    from:
      uri: direct:ask-for-json
      steps:
        - to: "openai:chat-completion?model={{env:OPENAI_MODEL:gpt-4o-mini}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}&temperature=0&systemMessage=Extract the invoice as a JSON object with the fields vendor (string), total (number) and currency (ISO 4217 code). Reply with the JSON object only."
        - to: "json-validator:file:{{env:SCHEMA_DIR:schemas}}/invoice.json"
```

The outer `doTry` catches the first `ValidationException` (an answer that is not JSON at all is
a `JsonValidationException`, a subkind of it) and asks again with the errors; the inner `doTry`
turns a second failure into `422`. Both attempts call the same `direct:ask-for-json` route. The
test covers all three outcomes: valid at once, repaired on the second call, and rejected with
`422`.

## Rate limits and a circuit breaker around a model API

Model APIs have rate limits and outages. The `throttle` keeps calls under five per second
(others wait, instead of getting `429` from the provider). The `circuitBreaker` counts failures;
when half of the last ten calls failed, it stops calling the API for 30 seconds and answers
from `onFallback` with `503` and `Retry-After`.

```yaml
- route:
    id: ask-model
    from:
      uri: "platform-http:/ask?httpMethodRestrict=POST"
      steps:
        - convertBodyTo:
            type: java.lang.String
        - throttle:
            constant: 5
            timePeriodMillis: 1000
        - circuitBreaker:
            resilience4jConfiguration:
              slidingWindowSize: 10
              minimumNumberOfCalls: 5
              failureRateThreshold: 50
              waitDurationInOpenState: 30
              timeoutEnabled: true
              timeoutDuration: 60000
            steps:
              - to: "openai:chat-completion?model={{env:OPENAI_MODEL:gpt-4o-mini}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}&maxTokens=300&systemMessage=Answer in at most three sentences."
            onFallback:
              steps:
                - setHeader:
                    name: CamelHttpResponseCode
                    constant: 503
                - setHeader:
                    name: Retry-After
                    constant: 30
                - setBody:
                    constant: "The assistant is unavailable right now. Please retry in 30 seconds."
```

The test runs it twice: against the model mock (six calls take at least a second because of
the throttle), and against an API that is down (every call gets the fallback `503` at once).
For a limit per tenant or per API key, add `correlationExpression: {header: tenant}` to the
throttle.

## Multi-model fallback

Use a hosted model first and a local one when it fails. A failover load balancer tries the
primary endpoint and moves to the fallback on any exception: a connection error, a timeout, or
an HTTP error such as `429` or `401` (the `openai` component fails with
`HttpOperationFailedException` on API errors).

```yaml
- route:
    id: chat-with-fallback
    from:
      uri: "platform-http:/chat?httpMethodRestrict=POST"
      steps:
        - convertBodyTo:
            type: java.lang.String
        - loadBalance:
            failover:
              maximumFailoverAttempts: 1
            steps:
              - to: "openai:chat-completion?model={{env:PRIMARY_MODEL:gpt-4o-mini}}&baseUrl={{env:PRIMARY_BASE_URL:https://api.openai.com/v1}}&timeout=30s"
              - to: "openai:chat-completion?model={{env:FALLBACK_MODEL:llama3.1}}&baseUrl={{env:FALLBACK_BASE_URL:http://localhost:11434/v1}}&timeout=60s"
        - setHeader:
            name: X-Answered-By
            simple: "${header.CamelOpenAIResponseModel}"
```

The `X-Answered-By` header comes from `CamelOpenAIResponseModel`, the model name the API
reported. The test checks both paths: primary down (the local model answers) and primary up
(the fallback is never called). To prefer a cheaper model and fall back to a stronger one, swap
the two endpoints; to spread load instead, use `roundRobin` (see
[load balancer](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html#load-balancer)).

## Patterns that combine well

- Put a [`filter`](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html#message-filter) and an
  [`idempotentConsumer`](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html#idempotent-consumer) in front of model calls: spam
  and duplicates cost tokens too.
- [`wireTap`](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html#wire-tap) every prompt and answer to Kafka or a file for an audit
  trail and evaluation data.
- Use [`enrich`](https://pmsudhi.github.io/cameleer/docs/guides/eips/transformation.html#content-enricher-enrich) to add customer data from SQL
  or a CRM to the prompt.
- Run the routes as a sidecar that starts in milliseconds next to your agent (Docker image `pmsudhi/cameleer`) or embed
  them in a Rust agent with `cameleer_main::new_main()`.

## Common questions

### How do I call an LLM from a Cameleer route?

Send the prompt as the body to `openai:chat-completion?model=...`; the body becomes the
model's answer and the token counts are in `CamelOpenAI*Tokens` headers. Set `baseUrl` for
Ollama, vLLM or another OpenAI-compatible server, or use `aws-bedrock`, `azure-openai` or
`google-vertexai`.

### Can an AI agent call Cameleer routes as tools?

Yes. Expose each tool as a REST endpoint (`rest` or `platform-http`), validate the arguments
with `json-validator`, and add idempotency and retries, as in the
[tool pattern](#expose-a-tool-to-an-agent-over-rest). An MCP server component is planned.

### How do I stop an agent from executing the same action twice?

Have the agent send a unique request id with every tool call and wrap the side effect in
`idempotentConsumer` on that id. Use the JDBC or Redis idempotent repository to keep the ids
across restarts and instances.

### How do I test routes that call an LLM without paying for tokens?

Point `baseUrl` at a mock. `cameleer_saas::testing::OpenAiMock` is an OpenAI-compatible mock
for chat and embeddings, and the tests of this guide use it.

### Does Cameleer run models or store vectors?

No. It calls the models and moves embeddings into the stores you already run (Elasticsearch,
OpenSearch, PostgreSQL with pgvector, or any store with an HTTP API).

## Related

- [AI agent tool calls: direct vs through Cameleer](https://pmsudhi.github.io/cameleer/docs/guides/agent-tool-calls.html): a multi-step tool with a saga, compared with letting the model call each API
- [AI components](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html), [openai component](https://pmsudhi.github.io/cameleer/docs/components/openai.html)
- [EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html), [error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html), [edge cookbook](https://pmsudhi.github.io/cameleer/docs/guides/edge.html)
- [Roadmap: agent tool server and agent loop](https://pmsudhi.github.io/cameleer/docs/ROADMAP.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html

# Cloud credentials, regions and endpoints

> How Cameleer's AWS and Azure components find credentials (keys, profiles, instance and container roles, web identity, managed identity, SAS tokens), choose a region, and talk to emulators such as LocalStack and Azurite.

This guide covers every `aws*` component (for example [aws2-s3](https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html),
[aws2-sqs](https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html), [aws-bedrock](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html)) and every `azure-*`
component (for example [azure-storage-blob](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-blob.html),
[azure-servicebus](https://pmsudhi.github.io/cameleer/docs/components/azure-servicebus.html), [azure-openai](https://pmsudhi.github.io/cameleer/docs/components/azure-openai.html)).
All of them are implemented in Rust without the AWS or Azure SDKs; the behaviour below is that of
Cameleer's own code, which follows the SDKs' conventions.

## AWS

### Where credentials come from

When an endpoint has both `accessKey` and `secretKey`, they are used (with `sessionToken` for
temporary credentials). Otherwise Cameleer walks the default credentials chain, in this order:

| order | source | details |
|---|---|---|
| 1 | Environment variables | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (or `AWS_SECRET_KEY`), optional `AWS_SESSION_TOKEN`. |
| 2 | Shared credentials file | `AWS_SHARED_CREDENTIALS_FILE`, else `$HOME/.aws/credentials`; profile `profileCredentialsName`, else `AWS_PROFILE`, else `default`. Keys `aws_access_key_id`, `aws_secret_access_key`, `aws_session_token`. |
| 3 | Web identity (EKS IRSA, any OIDC federation) | `AWS_WEB_IDENTITY_TOKEN_FILE` + `AWS_ROLE_ARN` (optional `AWS_ROLE_SESSION_NAME`): STS `AssumeRoleWithWebIdentity`. The STS endpoint is `AWS_ENDPOINT_URL_STS`, `AWS_ENDPOINT_URL`, the endpoint override, or `https://sts.{region}.amazonaws.com`. |
| 4 | Container credentials (ECS task roles, EKS Pod Identity) | `AWS_CONTAINER_CREDENTIALS_FULL_URI`, or `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` on `http://169.254.170.2`; authorization from `AWS_CONTAINER_AUTHORIZATION_TOKEN` or `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE`. |
| 5 | EC2 instance metadata (instance profiles) | IMDSv2 with a session token, falling back to IMDSv1, on `AWS_EC2_METADATA_SERVICE_ENDPOINT` (default `http://169.254.169.254`). Disable with `AWS_EC2_METADATA_DISABLED=true`. |

Remote credentials are cached per process until five minutes before they expire. An unreachable
metadata endpoint is remembered for a minute, so the chain stays fast on machines that are not on EC2.

Two options narrow the chain:

- `useDefaultCredentialsProvider=true` ignores `accessKey` / `secretKey` on the endpoint and always
  uses the chain.
- `useProfileCredentialsProvider=true` (with `profileCredentialsName`) reads only the shared
  credentials file.

`useSessionCredentials`, `useIAMCredentials` and `autoDiscoverClient` are accepted for Camel
compatibility and have no effect: session tokens and roles are handled by the rules above.

Differences from the AWS SDKs: only the credentials file is read, not `~/.aws/config` (so the region
and `credential_process` / SSO settings in that file are not used), and on Windows the file is found
through `HOME` or `AWS_SHARED_CREDENTIALS_FILE`.

### Region

`region` on the endpoint, else `AWS_REGION`, else `AWS_DEFAULT_REGION`, else `us-east-1`. Names are
lower-cased and `_` becomes `-`, so Camel-style `EU_WEST_1` works. Requests go to
`https://{service}.{region}.amazonaws.com` (`.amazonaws.com.cn` for `cn-` regions); global services
(IAM) use their global endpoint and sign for `us-east-1`.

### AWS options

Every AWS component accepts these options:

| option | default | description |
|---|---|---|
| `accessKey`, `secretKey` | | Static credentials. Wrap them in `RAW(...)` so `+` and `/` survive. |
| `sessionToken` | | Session token of temporary credentials. |
| `region` | see above | Region. |
| `useDefaultCredentialsProvider` | `false` | Always use the default chain. |
| `useProfileCredentialsProvider` | `false` | Only the shared credentials file. |
| `profileCredentialsName` | | Profile of the credentials file. |
| `uriEndpointOverride` | | Base URL of an emulator or a VPC endpoint. |
| `overrideEndpoint` | `false` | Must be `true` for `uriEndpointOverride` to be used. |
| `proxyHost`, `proxyPort`, `proxyProtocol` | , `3128`, `HTTP` | Explicit proxy. Without it, the usual proxy environment variables apply. |
| `trustAllCertificates` | `false` | Disables certificate checks. Only for local test servers with self-signed certificates; never in production. |

### LocalStack, MinIO and other emulators

Set `uriEndpointOverride` and `overrideEndpoint=true`. LocalStack accepts any key, conventionally
`test` / `test`:

```yaml
- route:
    id: localstack-orders
    from:
      uri: "timer:localstack?repeatCount=1"
      steps:
        - setBody:
            constant: "hello from Cameleer"
        - to: "aws2-sqs://orders?region=us-east-1&accessKey=test&secretKey=test&uriEndpointOverride={{env:AWS_ENDPOINT_URL:http://localhost:4566}}&overrideEndpoint=true&autoCreateQueue=true"
```

S3 switches to path-style addressing (`http://host:port/bucket/key`) when the endpoint is
overridden, which is what MinIO and LocalStack expect. Note that Cameleer does not read
`AWS_ENDPOINT_URL` by itself for the components (only for STS web identity); pass it through a
placeholder as above.

## Azure

### Storage accounts (Blob, Queue, Data Lake, Files)

| `credentialType` | what it uses |
|---|---|
| `SHARED_ACCOUNT_KEY` (default when `accessKey` is set) | The base64 account key in `accessKey` (`accountKey` is accepted too). Requests are signed with Shared Key. |
| `AZURE_SAS` (default when only `sasToken` is set) | A SAS token (`sasToken`, with or without the leading `?`), appended to every request. |
| `AZURE_IDENTITY` | Microsoft Entra ID bearer tokens for `https://storage.azure.com/.default`, see below. |
| `CLIENT_SECRET` | Entra ID with an explicit service principal (`tenantId`, `clientId`, `clientSecret`). Setting `clientSecret` without a key or SAS selects it too. |

The account name is the first part of the uri path (`azure-storage-blob://myaccount/container`).
Requests go to `https://{account}.{blob|queue|dfs|file}.core.windows.net`.

### Microsoft Entra ID (service principals, workload identity, managed identity)

`credentialType=AZURE_IDENTITY` resolves like the SDK's `DefaultAzureCredential`. Options on the
endpoint win over the environment:

| order | source | details |
|---|---|---|
| 1 | Client secret | `clientSecret` / `AZURE_CLIENT_SECRET` with `tenantId` / `AZURE_TENANT_ID` and `clientId` / `AZURE_CLIENT_ID`. |
| 2 | Workload identity (AKS, any OIDC federation) | `federatedTokenFile` / `AZURE_FEDERATED_TOKEN_FILE` with the tenant and client id; the token file is read again on every refresh. |
| 3 | Managed identity | `managedIdentityEndpoint`, else the App Service / Functions / Container Apps endpoint (`IDENTITY_ENDPOINT` + `IDENTITY_HEADER`), else the instance metadata service `http://169.254.169.254`. `managedIdentityClientId` (or `clientId` / `AZURE_CLIENT_ID`) selects a user-assigned identity. |

The token endpoint is `{authorityHost}/{tenantId}/oauth2/v2.0/token`, with `authorityHost` from the
option, `AZURE_AUTHORITY_HOST` or `https://login.microsoftonline.com` (set it for sovereign clouds).
Tokens are cached per process until a minute before they expire, and a request that gets `401` is
retried once with a fresh token.

### Other Azure services

| component | credentials |
|---|---|
| [azure-key-vault](https://pmsudhi.github.io/cameleer/docs/components/azure-key-vault.html), [azure-schema-registry](https://pmsudhi.github.io/cameleer/docs/components/azure-schema-registry.html) | Entra ID: `CLIENT_SECRET` (default; `tenantId`, `clientId`, `clientSecret`) or `AZURE_IDENTITY`. |
| [azure-cosmosdb](https://pmsudhi.github.io/cameleer/docs/components/azure-cosmosdb.html) | `accountKey` (master key signature, default) or `credentialType=AZURE_IDENTITY`. |
| [azure-openai](https://pmsudhi.github.io/cameleer/docs/components/azure-openai.html) | `apiKey`, or Entra ID client credentials. |
| [azure-functions](https://pmsudhi.github.io/cameleer/docs/components/azure-functions.html) | `functionKey` / `masterKey`, or Entra ID tokens with `scope`. |
| [azure-eventgrid](https://pmsudhi.github.io/cameleer/docs/components/azure-eventgrid.html) | `accessKey`, a SAS token (`credentialType=AZURE_SAS`), or Entra ID. |
| [azure-servicebus](https://pmsudhi.github.io/cameleer/docs/components/azure-servicebus.html), [azure-eventhubs](https://pmsudhi.github.io/cameleer/docs/components/azure-eventhubs.html) | `connectionString`, or namespace + `sharedAccessName` + `sharedAccessKey` (SAS tokens on the AMQP `$cbs` node), or `credentialType=AZURE_IDENTITY` / `TOKEN_CREDENTIAL`. |

### Azure options

Storage components accept `accessKey` (or `accountKey`), `sasToken`, `credentialType`, `tenantId`,
`clientId`, `clientSecret`, `authorityHost`, `federatedTokenFile`, `managedIdentityClientId`,
`managedIdentityEndpoint`, `uriEndpointOverride` + `overrideEndpoint`, `proxyHost` + `proxyPort` and
`trustAllCertificates` (local tests only). The other Azure components accept the subset that applies
to them, listed on their pages.

### Azurite and other emulators

Storage endpoints with `uriEndpointOverride` and `overrideEndpoint=true` use Azurite's path-style
addressing, `http://host:port/{account}/...`. Azurite's development account is `devstoreaccount1`
with a well-known, public key:

```yaml
- route:
    id: azurite-upload
    from:
      uri: "timer:azurite?repeatCount=1"
      steps:
        - setBody:
            constant: "hello from Cameleer"
        - setHeader:
            name: CamelAzureStorageBlobBlobName
            constant: hello.txt
        - to: "azure-storage-blob://devstoreaccount1/uploads?operation=uploadBlockBlob&accessKey=RAW(Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==)&uriEndpointOverride={{env:AZURITE_BLOB_URL:http://127.0.0.1:10000}}&overrideEndpoint=true"
```

For Key Vault, Functions, OpenAI and Schema Registry, `uriEndpointOverride` replaces the service base
URL. Service Bus and Event Hubs emulators are reached with a connection string that contains
`UseDevelopmentEmulator=true`.

## Configure once for all endpoints

Every endpoint option can be set as a component default with
`camel.component.<scheme>.<option>`, in `application.properties` or as an environment variable
`CAMEL_COMPONENT_<SCHEME>_<OPTION>` (dashes in the scheme become underscores, the option is written in
upper snake case). Options in the uri win. This keeps route files free of regions and endpoints:

```yaml
- route:
    id: orders-with-defaults
    from:
      uri: "timer:defaults?repeatCount=1"
      steps:
        - setBody:
            constant: "order o-1001"
        - to: "aws2-sqs://orders?autoCreateQueue=true"
```

```properties
camel.component.aws2-sqs.region=eu-west-1
camel.component.aws2-sqs.uriEndpointOverride=http://localhost:4566
camel.component.aws2-sqs.overrideEndpoint=true
```

The same settings as environment variables:

```sh
export CAMEL_COMPONENT_AWS2_SQS_REGION=eu-west-1
export CAMEL_COMPONENT_AWS2_SQS_URI_ENDPOINT_OVERRIDE=http://localhost:4566
export CAMEL_COMPONENT_AWS2_SQS_OVERRIDE_ENDPOINT=true
```

## Secrets in routes

Instead of writing keys into routes, read them from a vault with placeholders:
`{{aws:name}}` resolves a secret from [AWS Secrets Manager](https://pmsudhi.github.io/cameleer/docs/components/aws-secrets-manager.html)
(configured with `camel.vault.aws.*`), `{{azure:name}}` one from
[Azure Key Vault](https://pmsudhi.github.io/cameleer/docs/components/azure-key-vault.html) (`camel.vault.azure.*`), and `{{env:NAME:default}}`
an environment variable. Both vaults can restart routes when a secret changes.

## Running in containers

With the Docker image, pass credentials as environment variables, or rely on the platform's identity:

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

On ECS, EKS (IRSA or Pod Identity), EC2, AKS (workload identity), App Service, Container Apps or Azure
VMs, no keys are needed: the container, web identity, instance metadata or managed identity sources
above provide short-lived credentials.

## Common questions

### Why do I get "Unable to load AWS credentials"?

None of the sources had credentials: set `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`, mount a
credentials file and set `AWS_SHARED_CREDENTIALS_FILE`, or run with a role. In containers, check that
`HOME` points to the directory that contains `.aws`.

### Why does my AWS secret key fail with a signature error?

A secret key with `+` or `/` in a uri must be wrapped in `RAW(...)`, otherwise `+` turns into a space.

### Which Azure credential should I use in production?

A managed identity or workload identity with `credentialType=AZURE_IDENTITY`: no secret to rotate.
Use SAS tokens with narrow permissions and short expiry for devices at the edge.

## Related

- [AWS S3](https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html), [AWS SQS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html), [AWS Secrets Manager](https://pmsudhi.github.io/cameleer/docs/components/aws-secrets-manager.html)
- [Azure Storage Blob](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-blob.html), [Azure Key Vault](https://pmsudhi.github.io/cameleer/docs/components/azure-key-vault.html), [Azure Service Bus](https://pmsudhi.github.io/cameleer/docs/components/azure-servicebus.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html

# Flow control and resilience patterns

> Flow control and resilience patterns protect routes and the systems they call: drop
> duplicates (idempotent consumer), limit the rate (throttle, sample, delay), stop calling a
> failing service (circuit breaker), check messages (validate) and process in parallel
> (threads).

These are the patterns to put around paid or rate-limited APIs such as LLMs, payment providers
and SaaS endpoints. Every example runs in the test suite as YAML and as Rust DSL. See
[the EIP guide](https://pmsudhi.github.io/cameleer/docs/guides/eips.html) for the other patterns and [error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html)
for retries.

## Idempotent consumer

The idempotent consumer remembers the keys it has seen and skips its block for a message whose
key was already processed. Use it so a redelivered webhook or Kafka message does not charge a
card or call a model twice.

```yaml
- route:
    from:
      uri: direct:payment-events
      steps:
        - idempotentConsumer:
            header: paymentId
            steps:
              - to: mock:charge
        - to: mock:seen
```

```rust
b.from("direct:payment-events")
    .idempotent_consumer(header("paymentId"), memory_idempotent_repository(1000))
        .to("mock:charge")
    .end()
    .to("mock:seen");
```

Two events with `paymentId` `p-1` and one with `p-2` give two charges. Duplicates skip only
the idempotent block, as in Camel, so `mock:seen` still gets all three; the exchange property
`CamelDuplicateMessage` is `true` on the duplicate. Options: `eager` (default true),
`skipDuplicate`, `removeOnFailure` (a failed message's key is forgotten so a retry can pass),
`completionEager`, and `idempotentRepository` (a bean). The default repository is an in-memory
LRU of 1000 keys; JDBC and Redis repositories are in `cameleer-sql` and `cameleer-datastores`
for keys that must survive restarts.

## Throttle

`throttle` lets at most N messages through per time period and delays the rest. It uses
Camel's classic time-period semantics (`timePeriodMillis`, default 1000).

```yaml
- route:
    from:
      uri: direct:model-calls
      steps:
        - throttle:
            constant: 2
            timePeriodMillis: 500
        - to: mock:model
```

```rust
b.from("direct:model-calls")
    .throttle(2, Duration::from_millis(500))
    .to("mock:model");
```

Five calls in a row take at least a second: two pass at once, the next two after 500 ms, the
last after 1000 ms. `rejectExecution: true` fails the extra messages with
`ThrottlerRejectedExecutionException` instead of waiting, `correlationExpression` keeps a
separate limit per key (per tenant, per API key), and `asyncDelayed: true` releases the
consumer thread of asynchronous consumers while a message waits. The maximum must be a
constant.

## Delay

`delay` waits before the next step. The expression gives milliseconds.

```yaml
- route:
    from:
      uri: direct:slow-down
      steps:
        - delay:
            constant: 200
        - to: mock:delayed
```

```rust
b.from("direct:slow-down")
    .delay(constant(200))
    .to("mock:delayed");
```

`asyncDelayed` defaults to true, as in Camel: seda and timer consumers hand the waiting
exchange to another thread. Synchronous callers (`direct:`, a producer template) still wait.

## Sampling

`sample` lets one message through per period (`samplePeriod`, default one second) or one in
every N messages (`messageFrequency`) and drops the rest. Use it to thin out high-rate
telemetry.

```yaml
- route:
    from:
      uri: direct:telemetry
      steps:
        - sample:
            messageFrequency: 3
        - to: mock:sampled
```

```rust
b.from("direct:telemetry")
    .sample_every(3)
    .to("mock:sampled");
```

Of six readings, two reach `mock:sampled`.

## Circuit breaker

The circuit breaker counts failures of its steps in a sliding window. When the failure rate
reaches `failureRateThreshold`, it opens: calls go straight to `onFallback` without trying the
steps, for `waitDurationInOpenState` seconds. Then it lets a few calls through (half-open) to
test whether the service is back.

```yaml
- route:
    from:
      uri: direct:ask-model
      steps:
        - circuitBreaker:
            resilience4jConfiguration:
              slidingWindowSize: 2
              minimumNumberOfCalls: 2
              failureRateThreshold: 50
              waitDurationInOpenState: 30
            steps:
              - to: direct:flaky-model
            onFallback:
              steps:
                - setBody:
                    constant: "The assistant is busy, please retry in a minute."
- route:
    from:
      uri: direct:flaky-model
      steps:
        - throwException:
            exceptionType: java.io.IOException
            message: model API timed out
```

```rust
b.from("direct:ask-model")
    .circuit_breaker()
        .sliding_window_size(2)
        .minimum_number_of_calls(2)
        .failure_rate_threshold(50.0)
        .wait_duration_in_open_state(Duration::from_secs(30))
        .to("direct:flaky-model")
    .on_fallback()
        .set_body(constant("The assistant is busy, please retry in a minute."))
    .end();
b.from("direct:flaky-model")
    .throw_exception("IOException", "model API timed out");
```

Every call gets the fallback answer. After two failed calls the breaker is open, and the third
call does not reach `direct:flaky-model` at all: its exchange property
`CamelCircuitBreakerResponseShortCircuited` is `true`. Other properties:
`CamelCircuitBreakerResponseFromFallback`, `CamelCircuitBreakerSuccessfulExecution`,
`CamelCircuitBreakerResponseTimedOut` and `CamelCircuitBreakerState`. `timeoutEnabled` and
`timeoutDuration` fail slow calls. The state machine is built in; the
`faultToleranceConfiguration` names are accepted too, but there is no Resilience4j or
MicroProfile library behind it.

## Validate

`validate` checks a predicate and fails the exchange with `PredicateValidationException` when
it is false. Pair it with `onException` or `doTry` to answer bad input with a clear error.

```yaml
- route:
    from:
      uri: direct:signup
      steps:
        - validate:
            simple: "${body} contains '@'"
        - to: mock:signups
```

```rust
b.from("direct:signup")
    .validate(simple("${body} contains '@'"))
    .to("mock:signups");
```

`ana@example.com` passes; `not-an-email` fails with `PredicateValidationException`. To check
JSON against a schema, use the [json-validator component](https://pmsudhi.github.io/cameleer/docs/components/json-validator.html).

## Threads

`threads` hands the rest of the route to a thread pool, so the caller is free at once and
messages are processed in parallel.

```yaml
- route:
    from:
      uri: direct:fan-out
      steps:
        - threads:
            poolSize: 4
            maxPoolSize: 8
        - to: mock:parallel
```

```rust
b.from("direct:fan-out")
    .threads(4)
    .to("mock:parallel");
```

Options: `poolSize`, `maxPoolSize`, `keepAliveTime`, `maxQueueSize` (0 hands off directly, -1
is unbounded), `rejectedPolicy` (`Abort`, `CallerRuns`, `Discard`, `DiscardOldest`),
`threadName` and `executorService` (a shared pool bean). `threads_with(ThreadsOptions)` sets the
same options in Rust. The pool follows Java's `ThreadPoolExecutor` rules.

## Common questions

### How do I stop processing duplicate messages?

Wrap the side effect in `idempotentConsumer` with a key expression such as `header: orderId`
or `jsonpath: "$.id"`. Use a JDBC or Redis repository when the keys must survive restarts or be
shared between instances.

### How do I rate limit calls to an API?

Use `throttle` with the number of calls per `timePeriodMillis`. For a limit per customer or API
key, add `correlationExpression`.

### What is the difference between a circuit breaker and retries?

Retries (redelivery) try the same call again a few times; a circuit breaker stops trying for a
while after repeated failures and answers from the fallback. They combine well: retry briefly
inside the breaker, and let the breaker protect the service when it is really down.

### How do I process messages in parallel?

Use `threads` for the rest of a route, `parallelProcessing: true` on `split`, `multicast` or
`recipientList`, or `concurrentConsumers` on a `seda` endpoint.

## Related

- [All EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html), [error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html)
- [Agents cookbook: rate limits and circuit breakers around model APIs](https://pmsudhi.github.io/cameleer/docs/guides/agents.html#rate-limits-and-a-circuit-breaker-around-a-model-api)
- Apache Camel: [Idempotent Consumer](https://camel.apache.org/components/next/eips/idempotentConsumer-eip.html),
  [Throttle](https://camel.apache.org/components/next/eips/throttle-eip.html),
  [Circuit Breaker](https://camel.apache.org/components/next/eips/circuitBreaker-eip.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/eips/system.html

# Interceptors, completions, sagas and reusable routes

> These patterns act around routes rather than on one message: interceptors that see every
> send or every input, `onCompletion` callbacks, sagas with compensation, route templates and
> Kamelets for reuse, the `poll` and `stop` EIPs.

Every example runs in the test suite (YAML, and Rust DSL where shown). See
[the EIP guide](https://pmsudhi.github.io/cameleer/docs/guides/eips.html) for the other patterns.

## Intercept sends to an endpoint

`interceptSendToEndpoint` runs its steps before every send to endpoints matching a pattern
(wildcards allowed). With `skipSendToOriginalEndpoint: true` the original endpoint is not
called at all, which is how you swap a real payment or model API for a sandbox in a test
profile.

```yaml
- routeConfiguration:
    interceptSendToEndpoint:
      - interceptSendToEndpoint:
          uri: "mock:payment-api*"
          skipSendToOriginalEndpoint: true
          steps:
            - setBody:
                simple: "sandbox charge for ${body}"
            - to: mock:sandbox
- route:
    from:
      uri: direct:checkout
      steps:
        - to: mock:payment-api
        - to: mock:receipts
```

```rust
b.intercept_send_to_endpoint("mock:payment-api*")
    .skip_send_to_original_endpoint()
    .set_body(simple("sandbox charge for ${body}"))
    .to("mock:sandbox");
b.from("direct:checkout")
    .to("mock:payment-api")
    .to("mock:receipts");
```

`mock:payment-api` receives nothing; `mock:sandbox` and `mock:receipts` get
`sandbox charge for order-9`. `afterUri` sends to another endpoint after the original one, and
`onWhen` limits the interception to matching messages.

## Intercept every input

`interceptFrom` runs before the first step of every route whose input matches the pattern
(`*` for all). `intercept` runs before every step of every route.

```yaml
- routeConfiguration:
    interceptFrom:
      - interceptFrom:
          uri: "direct:*"
          steps:
            - setHeader:
                name: receivedBy
                constant: edge-gateway-1
- route:
    from:
      uri: direct:sensor
      steps:
        - to: mock:stamped
```

```rust
b.intercept_from("direct:*")
    .set_header("receivedBy", constant("edge-gateway-1"));
b.from("direct:sensor")
    .to("mock:stamped");
```

Every message reaching `mock:stamped` carries the `receivedBy` header.

## On completion

`onCompletion` runs its steps after the exchange is done, on a copy, without changing the
reply. `onCompleteOnly` and `onFailureOnly` choose when it runs, `onWhen` adds a predicate, and
`mode: BeforeConsumer` runs it before the consumer answers.

```yaml
- route:
    from:
      uri: direct:place-order
      steps:
        - onCompletion:
            onFailureOnly: true
            steps:
              - setBody:
                  simple: "order failed: ${body}"
              - to: mock:failed-orders
        - filter:
            simple: "${body} contains 'invalid'"
            steps:
              - throwException:
                  exceptionType: java.lang.IllegalArgumentException
                  message: bad order
        - to: mock:orders
```

```rust
b.from("direct:place-order")
    .on_completion()
        .on_failure_only()
        .set_body(simple("order failed: ${body}"))
        .to("mock:failed-orders")
    .end()
    .filter(simple("${body} contains 'invalid'"))
        .throw_exception("IllegalArgumentException", "bad order")
    .end()
    .to("mock:orders");
```

The order `invalid-1` fails, and `mock:failed-orders` receives `order failed: invalid-1`; the
order `ok-1` goes to `mock:orders` and triggers nothing.

## Saga

A saga groups steps that call different services and registers a compensation for them. If
the exchange fails, the compensation endpoints are called (in reverse order of the steps that
joined), so you can undo bookings, charges or reservations without a distributed transaction.
On success, the optional `completion` endpoints are called.

```yaml
- route:
    from:
      uri: direct:book-trip
      steps:
        - saga:
            compensation:
              uri: direct:cancel-flight
            steps:
              - to: mock:flight-booked
              - filter:
                  simple: "${header.hotelFull} == 'true'"
                  steps:
                    - throwException:
                        exceptionType: java.lang.IllegalStateException
                        message: no hotel rooms
- route:
    from:
      uri: direct:cancel-flight
      steps:
        - to: mock:flight-cancelled
```

```rust
b.from("direct:book-trip")
    .saga()
        .compensation("direct:cancel-flight")
        .to("mock:flight-booked")
        .filter(simple("${header.hotelFull} == 'true'"))
            .throw_exception("IllegalStateException", "no hotel rooms")
        .end()
    .end();
b.from("direct:cancel-flight")
    .to("mock:flight-cancelled");
```

A booking with `hotelFull=true` fails and `mock:flight-cancelled` is called once. The default
saga service is in memory; `LraSagaService` talks to a Narayana LRA coordinator over plain HTTP.
Options: `propagation`, `completionMode` (`AUTO`, `MANUAL` with `saga:complete` and
`saga:compensate`), `timeout`, `option` (values passed to the compensation as headers).

## Route templates

A route template is a route with `{{parameters}}`; `templatedRoute` creates routes from it.
Use templates to stamp out the same integration for many tenants, devices or models.

```yaml
- routeTemplate:
    id: ask-model
    parameters:
      - name: name
      - name: prefix
        defaultValue: "Answer briefly:"
    route:
      from:
        uri: "direct:{{name}}"
        steps:
          - setBody:
              simple: "{{prefix}} ${body}"
          - to: "mock:{{name}}"
- templatedRoute:
    routeTemplateRef: ask-model
    parameters:
      - name: name
        value: support-bot
- templatedRoute:
    routeTemplateRef: ask-model
    parameters:
      - name: name
        value: sales-bot
      - name: prefix
        value: "Answer politely:"
```

```rust
ctx.add_route_template(
    "ask-model",
    &[TemplateParam::required("name"), TemplateParam::optional("prefix", "Answer briefly:")],
    |b, p| {
        b.from(format!("direct:{}", p.get("name")))
            .set_body(simple(format!("{} ${{body}}", p.get("prefix"))))
            .to(format!("mock:{}", p.get("name")));
    },
);
TemplatedRouteBuilder::new(ctx, "ask-model").parameter("name", "support-bot").add()?;
TemplatedRouteBuilder::new(ctx, "ask-model").parameter("name", "sales-bot").parameter("prefix", "Answer politely:").add()?;
```

`direct:support-bot` prefixes messages with `Answer briefly:`, `direct:sales-bot` with
`Answer politely:`. Templates can declare beans (`beans:`), and `prefixId` keeps node ids apart.

## Kamelets

A Kamelet is a route template packaged as a component: `kamelet:name?param=value` as a source,
a sink or an action. Built-in Kamelets: `timer-source`, `log-sink`, `log-action`,
`insert-header-action` and `set-body-action`; more are loaded from `camel.main.kamelet-locations`
(default `./kamelets`). The `kamelet` EIP calls one as a step.

```yaml
- route:
    from:
      uri: direct:tag-reading
      steps:
        - kamelet:
            name: insert-header-action
            parameters:
              name: site
              value: plant-7
        - to: mock:tagged
```

```rust
b.from("direct:tag-reading")
    .kamelet("insert-header-action?name=site&value=plant-7")
    .to("mock:tagged");
```

Every message reaching `mock:tagged` has the header `site=plant-7`. Pipes (`kind: Pipe`) and
KameletBindings connecting Kamelets run in-process too.

## Poll

`poll` consumes one message from an endpoint in the middle of a route and replaces the body
with it (Camel 4's `poll` EIP). The timeout is in milliseconds (default 20 seconds).

```yaml
- route:
    from:
      uri: direct:next-job
      steps:
        - poll:
            uri: seda:jobs
            timeout: 1000
        - to: mock:job
```

```rust
b.from("direct:next-job")
    .poll("seda:jobs", 1000)
    .to("mock:job");
```

## Stop

`stop` ends the routing of the current message: no later steps run. Inside a `split`, it stops
only the current part.

```yaml
- route:
    from:
      uri: direct:events
      steps:
        - filter:
            simple: "${header.type} == 'heartbeat'"
            steps:
              - stop: {}
        - to: mock:events
```

```rust
b.from("direct:events")
    .filter(simple("${header.type} == 'heartbeat'"))
        .stop()
    .end()
    .to("mock:events");
```

Heartbeats are dropped; every other event reaches `mock:events`.

## Common questions

### How do I mock an external API in a test without changing the route?

Add a `routeConfiguration` with `interceptSendToEndpoint` for the API's URI and
`skipSendToOriginalEndpoint: true`, and load it only in the test profile.

### How do I run something after a message is processed, even if it failed?

Use `onCompletion` (with `onFailureOnly` or `onCompleteOnly` to narrow it), or `doFinally` in a
`doTry` block for code that must run in the same flow.

### How do I reuse one route for many tenants or devices?

Write it once as a `routeTemplate` with parameters and add one `templatedRoute` per tenant, or
package it as a Kamelet.

## Related

- [All EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html), [error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html)
- Apache Camel: [Intercept](https://camel.apache.org/manual/intercept.html),
  [Saga](https://camel.apache.org/components/next/eips/saga-eip.html),
  [Route templates](https://camel.apache.org/manual/route-template.html),
  [Kamelets](https://camel.apache.org/manual/kamelets.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/eips/transformation.html

# Message transformation patterns

> Transformation patterns change what a message contains: its body and headers (message
> translator), its format (marshal and unmarshal), extra data fetched from elsewhere (content
> enricher), or a large payload parked aside (claim check).

Every example on this page runs in the test suite as YAML and as Rust DSL. See
[the EIP guide](https://pmsudhi.github.io/cameleer/docs/guides/eips.html) for the other patterns.

## Message translator: `setBody`, `transform`, `setHeader`

`setBody` (or its synonym `transform`) replaces the body with the value of an expression;
`setHeader`, `setProperty` and `setVariable` set one value; `removeHeader` and `removeHeaders`
(with a wildcard pattern) delete headers.

```yaml
- route:
    from:
      uri: direct:greet
      steps:
        - setHeader:
            name: customer
            simple: "${body[name]}"
        - transform:
            simple: "Hello ${header.customer}, your order ${body[order]} has shipped."
        - removeHeaders:
            pattern: "internal*"
        - to: mock:greeting
```

```rust
b.from("direct:greet")
    .set_header("customer", simple("${body[name]}"))
    .transform(simple("Hello ${header.customer}, your order ${body[order]} has shipped."))
    .remove_headers("internal*")
    .to("mock:greeting");
```

The body `{"name": "Ana", "order": 17}` (a map) becomes
`Hello Ana, your order 17 has shipped.`, and headers such as `internalTrace` are removed.

## Marshal and unmarshal

`unmarshal` turns bytes or text into structured data with a data format; `marshal` does the
reverse. JSON maps to Cameleer's dynamic `Value` (maps and lists), so Simple can read fields
with `${body[field]}`. Other formats include CSV, XML, YAML, Avro, Protobuf, CBOR, Base64,
GZip and Zip.

```yaml
- route:
    from:
      uri: direct:order-json
      steps:
        - unmarshal:
            json: {}
        - setBody:
            simple: '{"order": "${body[id]}", "total": ${body[qty]}}'
        - unmarshal:
            json: {}
        - marshal:
            json: {}
        - to: mock:order-out
```

```rust
b.from("direct:order-json")
    .unmarshal_json()
    .set_body(simple(r#"{"order": "${body[id]}", "total": ${body[qty]}}"#))
    .unmarshal_json()
    .marshal_json()
    .to("mock:order-out");
```

The text `{"id":"A-1","qty":3}` comes out as the JSON text `{"order":"A-1","total":3}`. There
is no POJO binding: data stays a `Value`, which is what Camel users get with
`unmarshal: json: {}` and no `unmarshalType`.

## Convert the body type

`convertBodyTo` converts the body with the type converter registry: `java.lang.String`,
`java.lang.Integer`, `byte[]`, `java.util.Map` and the other types Camel's core converters
know.

```yaml
- route:
    from:
      uri: direct:reading
      steps:
        - convertBodyTo:
            type: java.lang.Integer
        - filter:
            simple: "${body} > 100"
            steps:
              - to: mock:too-hot
```

```rust
b.from("direct:reading")
    .convert_body_to("java.lang.Integer")
    .filter(simple("${body} > 100"))
        .to("mock:too-hot")
    .end();
```

The text ` 250 ` (or the bytes of an MQTT payload) is converted to the integer `250`, so the
comparison is numeric. With `mandatory: true`, a value that cannot be converted fails the
exchange with `NoTypeConversionAvailableException`, as in Camel.

## Content enricher: `enrich`

`enrich` calls another endpoint with a copy of the message and merges the reply into the
message. Without an aggregation strategy the reply replaces the body. Use it to look up a
customer, a price or a document before calling a model.

```yaml
- route:
    from:
      uri: direct:ticket
      steps:
        - setProperty:
            name: ticket
            simple: "${body}"
        - enrich:
            uri: direct:crm-lookup
        - setBody:
            simple: "${exchangeProperty.ticket} (customer tier: ${body})"
        - to: mock:enriched
- route:
    from:
      uri: direct:crm-lookup
      steps:
        - choice:
            when:
              - simple: "${header.customerId} == 'c-1'"
                steps:
                  - setBody:
                      constant: gold
            otherwise:
              steps:
                - setBody:
                    constant: standard
```

```rust
b.from("direct:ticket")
    .set_property("ticket", simple("${body}"))
    .enrich("direct:crm-lookup")
    .set_body(simple("${exchangeProperty.ticket} (customer tier: ${body})"))
    .to("mock:enriched");
b.from("direct:crm-lookup")
    .choice()
        .when(simple("${header.customerId} == 'c-1'"))
            .set_body(constant("gold"))
        .otherwise()
            .set_body(constant("standard"))
    .end();
```

The ticket `Printer on fire` from customer `c-1` reaches `mock:enriched` as
`Printer on fire (customer tier: gold)`. Options: `aggregationStrategy`,
`aggregateOnException`, `ignoreInvalidEndpoint`, `shareUnitOfWork`, and a dynamic URI with
`${...}`.

## Poll enrich: `pollEnrich`

`pollEnrich` consumes one message from a polling endpoint (a seda queue, a file directory, an
FTP folder) and puts it into the current message. `timeout` is in milliseconds: `-1` waits
forever, `0` does not wait.

```yaml
- route:
    from:
      uri: direct:with-latest-config
      steps:
        - pollEnrich:
            uri: seda:config-updates
            timeout: 1000
        - to: mock:with-config
```

```rust
b.from("direct:with-latest-config")
    .poll_enrich("seda:config-updates", 1000)
    .to("mock:with-config");
```

When a message `threshold=40` is waiting on `seda:config-updates`, a request to
`direct:with-latest-config` continues with that body.

## Claim check

A claim check stores the body (or selected headers) under a key and gets it back later, so the
steps in between work with a small message. Operations: `Set`, `Get`, `GetAndRemove`, `Push`,
`Pop`.

```yaml
- route:
    from:
      uri: direct:big-document
      steps:
        - claimCheck:
            operation: Set
            key: document
        - setBody:
            constant: "summary request"
        - to: mock:light
        - claimCheck:
            operation: Get
            key: document
        - to: mock:restored
```

```rust
b.from("direct:big-document")
    .claim_check(ClaimCheckOperation::Set, "document")
    .set_body(constant("summary request"))
    .to("mock:light")
    .claim_check(ClaimCheckOperation::Get, "document")
    .to("mock:restored");
```

`mock:light` sees only `summary request`; `mock:restored` gets the original document back.

## Script

`script` runs an expression or a script for its side effects; its result is discarded. With
the script languages of `cameleer-script` (Groovy, JavaScript, Python, MVEL, Java), changes the
script makes to the message, headers and properties are kept.

```yaml
- route:
    from:
      uri: direct:tags
      steps:
        - script:
            groovy: |
              def tags = request.body.split(',')
              request.headers.tagCount = tags.size()
              request.body = tags.collect { it.trim().toLowerCase() }.join('|')
        - to: mock:tags
```

```rust
b.from("direct:tags")
    .process(cameleer_script::script("groovy", "def tags = request.body.split(',')\nrequest.headers.tagCount = tags.size()\nrequest.body = tags.collect { it.trim().toLowerCase() }.join('|')").unwrap())
    .to("mock:tags");
```

The body `Rust, Camel ,EIP` becomes `rust|camel|eip` with the header `tagCount` set to 3. The
scripts run in Cameleer's own interpreters, not on a JVM, so Java libraries are not available
to them.

## Common questions

### How do I change the message body in a route?

Use `setBody` (or `transform`) with an expression: `simple` for text templates, `jsonpath` or
`jq` to pick from JSON, `constant` for a fixed value.

### How do I parse JSON in a route?

Add `unmarshal: json: {}`. The body becomes a map or list, and `${body[field]}`,
`${body[items][0]}` and JSONPath read from it. `marshal: json: {}` turns it back into text.

### How do I call another service and keep my original message?

Store the original in a property (`setProperty`), call the service with `enrich` or `to`, and
build the result from `${exchangeProperty.name}` and `${body}`. An aggregation strategy bound in
the registry can do the merge instead.

## Related

- [All EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html), [routing](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html), [splitting and aggregating](https://pmsudhi.github.io/cameleer/docs/guides/eips/split-aggregate.html)
- Apache Camel: [Message Translator](https://camel.apache.org/components/next/eips/message-translator.html),
  [Content Enricher](https://camel.apache.org/components/next/eips/content-enricher.html),
  [Claim Check](https://camel.apache.org/components/next/eips/claimCheck-eip.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/migrating-from-apache-camel.html

# Migrating from Apache Camel

> Camel YAML and XML routes, endpoint URIs, EIPs, the Simple language, headers and error
> handling carry over to Cameleer unchanged; Java code (processors, beans, custom components)
> must be rewritten in Rust, and a few behaviours differ, listed on this page.

Cameleer follows Apache Camel 4's names and semantics, so most of a migration is running your
existing route files and checking that every component and option you use is supported. This
page lists what carries over, what differs, a checklist, and the known deviations.

## What carries over unchanged

- **Route files.** Camel YAML DSL (`*.camel.yaml`) and XML DSL (`<routes>`) files, including
  `routeConfiguration`, `routeTemplate`/`templatedRoute`, `rest`/`restConfiguration`, Kamelets,
  Pipes and Camel K `Integration` resources.
- **Endpoint URIs and options**, with the same names and defaults for the supported components.
  Unknown options fail at startup, as in Camel.
- **EIPs**: names, options and semantics, including the edge cases (a split without a strategy
  continues with the original message, `completionTimeout` is an inactivity timeout, duplicates
  skip only the idempotent block, the last reply wins in a multicast without a strategy).
- **Languages**: Simple (operators, functions, OGNL navigation, ternary), JSONPath, XPath,
  XQuery, jq (with camel-jq's `header()` and `property()`), constant, header, exchangeProperty.
- **Headers and properties**: `CamelFileName`, `CamelHttpResponseCode`, `CamelSplitIndex`,
  `CamelRedeliveryCounter`, `kafka.KEY`, `CamelMqttTopic` and the rest.
- **Error handling**: `errorHandler` (default, dead letter channel, none), redelivery policies,
  `onException` with `handled`/`continued`/`onWhen`/`retryWhile`, `doTry`/`doCatch`/`doFinally`,
  `onCompletion`. Java exception class names in routes are matched by their simple name.
- **Configuration**: `application.properties` and `application.yaml`, `{{placeholders}}` with
  defaults, `{{env:NAME}}`, profiles, `camel.component.<scheme>.<option>`, Spring Boot and Quarkus
  key aliases, `CAMEL_*` environment variables.
- **Tooling**: the `cameleer` command (the Camel JBang commands under a different name: `run`, `init`, `ps`, `stop`, `get`, `log`, `trace`,
  `export`, `bind`, `catalog`), health checks at `/q/health`, metrics, the dev console, message
  history and tracing.

This route uses Camel-specific spellings (fully qualified exception and strategy class names, a
`parameters` map, a `routeConfiguration`, a placeholder with a default) and runs as written:

```yaml
- routeConfiguration:
    onException:
      - onException:
          exception:
            - java.lang.IllegalArgumentException
          handled:
            constant: true
          steps:
            - setBody:
                simple: "rejected: ${exception.message}"
            - to: mock:rejected
- route:
    id: order-lines
    from:
      uri: direct:orders
      steps:
        - unmarshal:
            json:
              library: Jackson
        - filter:
            simple: "${body[lines]} == null"
            steps:
              - throwException:
                  exceptionType: java.lang.IllegalArgumentException
                  message: "order ${body[id]} has no lines"
        - split:
            simple: "${body[lines]}"
            aggregationStrategy: "#class:org.apache.camel.processor.aggregate.GroupedBodyAggregationStrategy"
            steps:
              - setBody:
                  simple: "${body[sku]} x ${body[qty]}"
        - to:
            uri: mock:order-summary
            parameters:
              retainFirst: "{{summary.retain:10}}"
```

An order `{"id": 7, "lines": [{"sku": "A1", "qty": 2}, {"sku": "B2", "qty": 1}]}` reaches
`mock:order-summary` as `["A1 x 2", "B2 x 1"]`; an order without lines goes to `mock:rejected`.

## What differs

| area | Apache Camel | Cameleer |
|---|---|---|
| runtime | JVM, Maven or Gradle | one native binary, or Rust crates |
| custom processors | Java classes or lambdas | Rust closures or structs (`Processor` trait), bound in the registry for YAML/XML |
| beans | Java beans with reflection-based parameter binding | processor beans and named bean methods; no reflection |
| message bodies | Java objects, POJO binding (`unmarshalType`) | dynamic values: null, bool, numbers, text, bytes, lists, maps; JSON maps onto them, no POJOs |
| exceptions | Java exception classes | string kinds with a parent hierarchy; `register_kind_parent` adds your own |
| scripts | Groovy, JavaScript (GraalJS), Python (Jython), Java (jOOR) on the JVM | Cameleer's own interpreters for the same syntaxes, without Java libraries |
| components | about 300 | about 230 components, languages and data formats; see [FEATURES.md](https://pmsudhi.github.io/cameleer/docs/FEATURES.html) |
| statistics | collected only with `camel-management` | always on; route and context counters by default, per-step timing opt-in (`camel.main.jmxManagementStatisticsLevel=Default`) |
| management | JMX | JSON and Prometheus export, health checks, dev console; no JMX |
| transactions | Spring or JTA transaction managers | a `TransactionManager` trait with Camel's propagation behaviours; no JTA/XA |
| variables | a variable repository | stored as exchange properties named `CamelVariable.<name>` |
| aggregation and idempotent repositories | memory, JDBC, LevelDB, Infinispan, Redis... | memory, JDBC and Redis |
| deployment to Kubernetes | Camel K operator, Kubernetes traits | `kind: Integration` files run in-process; deploy the container image yourself |

## Migration checklist

1. **Inventory the components.** List every scheme your routes use and check it in
   [FEATURES.md](https://pmsudhi.github.io/cameleer/docs/FEATURES.html) or the [component pages](https://pmsudhi.github.io/cameleer/docs/components/index.html), including the options.
   `cameleer catalog components` prints the list.
2. **Run the routes as they are.** `cameleer run routes/` (or the Docker image). Startup fails on
   an unknown component, an unknown endpoint option or an unsupported YAML element, with the file
   and line.
3. **Replace Java code.** Rewrite processors and beans as Rust processors and bind them in the
   registry under the same names, or replace them with EIPs and Simple, jq or JSONPath
   expressions (often possible for mapping code), or with a `script` step.
4. **Check type-dependent logic.** Steps that relied on POJO types (`bodyAs(Order.class)`,
   `unmarshalType`, typed beans) work on maps instead: `${body[field]}`, JSONPath, jq.
5. **Move configuration.** Keep `application.properties`; replace Spring XML beans with
   `camel.beans.*` entries or Rust code; Spring Boot keys (`server.port`,
   `spring.profiles.active`) are understood.
6. **Test with the same tests.** Camel's `mock:` endpoint, `ProducerTemplate`,
   `interceptSendToEndpoint` with `skipSendToOriginalEndpoint`, and the embedded test servers
   (Kafka, MQTT, AMQP, SQL, Redis, MongoDB, S3, SQS, OpenAI...) make hermetic tests possible.
7. **Review the deviations below**, then load-test: throughput and memory differ a lot (see the
   [benchmarks](https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html)), so thread pools and queue sizes tuned for a JVM may be too
   large.

## Known deviations

These differences are documented on purpose (from the conformance suite in
[FEATURES.md](https://pmsudhi.github.io/cameleer/docs/FEATURES.html#known-deviations-found-by-the-conformance-suite)) or found while
writing these guides:

1. In Simple text, `$${` is an escape that produces a literal `${`.
2. TLS comes from Cameleer's own `cameleer-tls` crate, not a mature, audited library.
3. Asynchronous delays (`asyncDelayed`, `asyncDelayedRedelivery`) hand the waiting exchange to a
   released thread and start a replacement consumer thread, instead of scheduling a continuation
   on a scheduler pool. The effect on the route is the same.
4. When an `http` call fails with an HTTP error status, Cameleer's `http` producer has already put
   the response body and headers into the message (Apache Camel leaves the message unchanged and
   puts the response in the `HttpOperationFailedException`). A redelivery of that step then sends
   the error response instead of the original request. Until this is fixed, call the API with
   `enrich` (which sends a copy of the message) when the call is retried; see the
   [tool API](https://pmsudhi.github.io/cameleer/docs/guides/agents.html#expose-a-tool-to-an-agent-over-rest) and
   [store and forward](https://pmsudhi.github.io/cameleer/docs/guides/edge.html#store-and-forward-when-the-uplink-is-down) examples.
5. `throttle` uses Camel's classic time-period mode (`timePeriodMillis`); the maximum must be a
   constant.
6. Management statistics default to route and context counters (see the table above).

## Common questions

### Is Cameleer a drop-in replacement for Apache Camel?

For route files, mostly: Camel YAML and XML routes run unchanged when their components and
options are supported. Java code is not: processors, beans and custom components must be
rewritten in Rust.

### Can I run Camel and Cameleer side by side?

Yes. They talk through the same brokers, APIs and files, so you can move routes one at a time,
for example the high-volume or edge routes first.

### Do Camel Kamelets work?

Yes. YAML Kamelets (`spec.definition`, `spec.template`), Pipes and KameletBindings run, loaded
from `camel.main.kamelet-locations` (default `./kamelets`). Remote `github:` locations are not
fetched.

### What about Camel's Java DSL?

The Rust DSL mirrors it method by method (`from`, `filter`, `split`, `aggregate`,
`on_exception`...), so a Java route translates line by line. See [concepts](https://pmsudhi.github.io/cameleer/docs/guides/concepts.html).

## Related

- [Concepts](https://pmsudhi.github.io/cameleer/docs/guides/concepts.html), [FAQ](https://pmsudhi.github.io/cameleer/docs/guides/faq.html), [feature list](https://pmsudhi.github.io/cameleer/docs/FEATURES.html)
- Apache Camel: [YAML DSL](https://camel.apache.org/components/next/others/yaml-dsl.html),
  [Camel 4 migration guide](https://camel.apache.org/manual/camel-4-migration-guide.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html

# Routing patterns

> Routing patterns decide where a message goes next: to one endpoint, to several, to a list
> computed at run time, or around a loop, using the same EIP names and options as Apache Camel.

This page covers the pipeline, message filter, content-based router, recipient list, routing
slip, dynamic router, multicast, wire tap, load balancer and loop. Each pattern has a YAML
route and the same route in the Rust DSL; both run in the test suite
(`crates/cameleer-main/tests/docs_guides.rs`). The index of all patterns is in
[the EIP guide](https://pmsudhi.github.io/cameleer/docs/guides/eips.html).

## Pipeline: `to`, `toD` and `step`

A route is a pipeline: each step gets the output of the step before it. `to` sends to a fixed
endpoint, `toD` computes the endpoint URI from a Simple expression for every message, and
`step` groups steps under one id for statistics.

```yaml
- route:
    id: pipeline
    from:
      uri: direct:orders
      steps:
        - step:
            id: normalize
            steps:
              - setHeader:
                  name: region
                  simple: "${body[region]}"
        - toD: "mock:region-${header.region}"
        - to: mock:all-orders
```

```rust
b.from("direct:orders")
    .route_id("pipeline")
    .step("normalize")
        .set_header("region", simple("${body[region]}"))
    .end()
    .to_d("mock:region-${header.region}")
    .to("mock:all-orders");
```

`toD` keeps a cache of the endpoints it created, as in Camel. Use it when the target depends on
the message (a tenant, a region, a model name); use `to` otherwise.

## Message filter

A filter lets a message through its block only when a predicate is true. After the block, the
route continues with every message. The exchange property `CamelFilterMatched` tells whether
the last filter matched.

```yaml
- route:
    from:
      uri: direct:payments
      steps:
        - filter:
            simple: "${header.amount} > 1000"
            steps:
              - to: mock:review
        - to: mock:ledger
```

```rust
b.from("direct:payments")
    .filter(simple("${header.amount} > 1000"))
        .to("mock:review")
    .end()
    .to("mock:ledger");
```

To drop non-matching messages entirely, put the rest of the route inside the filter block, or
use `stop` in a `choice`.

## Content-based router: `choice`

`choice` sends the message down the first `when` branch whose predicate is true, or to
`otherwise`. A `choice` without `otherwise` lets unmatched messages continue after the choice.

```yaml
- route:
    from:
      uri: direct:tickets
      steps:
        - choice:
            when:
              - simple: "${header.priority} == 'P1'"
                steps:
                  - to: mock:page-oncall
              - simple: "${header.priority} == 'P2'"
                steps:
                  - to: mock:team-queue
            otherwise:
              steps:
                - to: mock:backlog
```

```rust
b.from("direct:tickets")
    .choice()
        .when(simple("${header.priority} == 'P1'"))
            .to("mock:page-oncall")
        .when(simple("${header.priority} == 'P2'"))
            .to("mock:team-queue")
        .otherwise()
            .to("mock:backlog")
    .end();
```

A typical AI use: an LLM writes a label into a header, and `choice` routes on the label. See
[Cameleer for AI agents](https://pmsudhi.github.io/cameleer/docs/guides/agents.html#classify-with-an-llm-and-route-on-the-answer).

## Recipient list

A recipient list sends a copy of the message to every endpoint named by an expression,
evaluated per message. The default delimiter is a comma.

```yaml
- route:
    from:
      uri: direct:notify
      steps:
        - recipientList:
            simple: "${header.channels}"
```

```rust
b.from("direct:notify")
    .recipient_list(simple("${header.channels}"));
```

Send it a message with the header `channels` set to `mock:email,mock:sms` and both endpoints
get a copy. Options: `delimiter`, `parallelProcessing`, `ignoreInvalidEndpoints`,
`stopOnException`, `timeout`, `aggregationStrategy`.

## Routing slip

A routing slip sends the message through a sequence of endpoints, one after another, each
getting the output of the previous one. The list comes from an expression, often a header the
sender sets.

```yaml
- route:
    from:
      uri: direct:process
      steps:
        - routingSlip:
            simple: "${header.slip}"
- route:
    from:
      uri: direct:resize
      steps:
        - setBody:
            simple: "${body}-resized"
- route:
    from:
      uri: direct:watermark
      steps:
        - setBody:
            simple: "${body}-watermarked"
```

```rust
b.from("direct:process")
    .routing_slip(simple("${header.slip}"));
b.from("direct:resize")
    .set_body(simple("${body}-resized"));
b.from("direct:watermark")
    .set_body(simple("${body}-watermarked"));
```

With `slip` set to `direct:resize,direct:watermark,mock:done`, the body `photo` arrives at
`mock:done` as `photo-resized-watermarked`. The option `uriDelimiter` changes the separator.

## Dynamic router

A dynamic router evaluates its expression again after every hop and stops when the expression
returns nothing. Here each step names the next one in the `next` header, so the route itself
decides how far the message goes.

```yaml
- route:
    from:
      uri: direct:workflow
      steps:
        - dynamicRouter:
            simple: "${header.next}"
        - to: mock:workflow-done
- route:
    from:
      uri: direct:validate
      steps:
        - setHeader:
            name: next
            constant: direct:approve
- route:
    from:
      uri: direct:approve
      steps:
        - removeHeader:
            name: next
        - setBody:
            simple: "${body} approved"
```

```rust
b.from("direct:workflow")
    .dynamic_router(simple("${header.next}"))
    .to("mock:workflow-done");
b.from("direct:validate")
    .set_header("next", constant("direct:approve"));
b.from("direct:approve")
    .remove_header("next")
    .set_body(simple("${body} approved"));
```

Send `invoice 7` with the header `next` set to `direct:validate`: the router calls
`direct:validate`, then `direct:approve`, which removes the header, so the router ends and
`mock:workflow-done` receives `invoice 7 approved`. An agent's planner can fill the `next`
header the same way: the route runs whatever hop it names until there is none.

## Multicast

A multicast sends the same message to several steps, one after the other or in parallel. Without
an aggregation strategy the reply of the last step wins, as in Camel.

```yaml
- route:
    from:
      uri: direct:order-placed
      steps:
        - multicast:
            parallelProcessing: true
            steps:
              - to: mock:billing
              - to: mock:shipping
              - to: mock:analytics
```

```rust
b.from("direct:order-placed")
    .multicast()
        .parallel_processing()
        .to("mock:billing")
        .to("mock:shipping")
        .to("mock:analytics")
    .end();
```

Options: `parallelProcessing`, `stopOnException`, `timeout`, `shareUnitOfWork`,
`aggregationStrategy`. Use an aggregation strategy to combine the replies, for example to ask
several models the same question and keep all answers.

## Wire tap

A wire tap sends a copy of the message to another endpoint asynchronously, on a separate
exchange, and the route goes on at once. Use it for audit logs and side channels that must not
slow down or fail the main flow.

```yaml
- route:
    from:
      uri: direct:prompts
      steps:
        - wireTap:
            uri: mock:audit
        - setBody:
            simple: "answered: ${body}"
        - to: mock:answers
```

```rust
b.from("direct:prompts")
    .wire_tap("mock:audit")
    .set_body(simple("answered: ${body}"))
    .to("mock:answers");
```

The tapped copy is taken when the wire tap runs, so `mock:audit` receives the original prompt.
`newExchangeBody` and `setHeader` entries build a new message for the tap instead of copying.

## Load balancer

A load balancer sends each message to one of its steps. Policies: `roundRobin`, `random`,
`sticky` (by a correlation expression), `weighted`, `topic` (all of them) and `failover` (the
next step when one fails), plus custom balancers from the registry.

```yaml
- route:
    from:
      uri: direct:inference
      steps:
        - loadBalance:
            roundRobin: {}
            steps:
              - to: mock:gpu-1
              - to: mock:gpu-2
```

```rust
b.from("direct:inference")
    .load_balance()
        .round_robin()
        .to("mock:gpu-1")
        .to("mock:gpu-2")
    .end();
```

Failover moves to the next step when the current one throws one of the listed exceptions. With
`roundRobin: true` it also rotates the starting step:

```yaml
- route:
    from:
      uri: direct:call-model
      steps:
        - loadBalance:
            failover:
              exception:
                - java.io.IOException
            steps:
              - to: direct:primary-model
              - to: direct:backup-model
- route:
    from:
      uri: direct:primary-model
      steps:
        - throwException:
            exceptionType: java.io.IOException
            message: primary is down
- route:
    from:
      uri: direct:backup-model
      steps:
        - setBody:
            constant: answer from backup
```

```rust
b.from("direct:call-model")
    .load_balance()
        .failover(&["IOException"])
        .to("direct:primary-model")
        .to("direct:backup-model")
    .end();
b.from("direct:primary-model")
    .throw_exception("IOException", "primary is down");
b.from("direct:backup-model")
    .set_body(constant("answer from backup"));
```

Exception names are matched by their simple class name: `java.io.IOException` in YAML and
`IOException` in Rust are the same kind. For model calls, the
[circuit breaker](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html#circuit-breaker) is often the better tool, because it stops
calling a failing model for a while.

## Loop

`loop` runs its steps a fixed number of times, or while a predicate is true (`doWhile: true`).
The exchange property `CamelLoopIndex` holds the current iteration, starting at 0.

```yaml
- route:
    from:
      uri: direct:retry-poll
      steps:
        - loop:
            constant: 3
            steps:
              - setBody:
                  simple: "${body}+${exchangeProperty.CamelLoopIndex}"
        - to: mock:looped
```

```rust
b.from("direct:retry-poll")
    .loop_(constant(3))
        .set_body(simple("${body}+${exchangeProperty.CamelLoopIndex}"))
    .end()
    .to("mock:looped");
```

The body `x` comes out as `x+0+1+2`. With `copy: true` every iteration starts from a copy of
the original message instead of the previous iteration's output.

## Common questions

### How do I route messages based on their content?

Use `choice` with one `when` per case and an `otherwise` for the rest. Predicates are usually
Simple (`${header.type} == 'refund'`), but JSONPath, XPath and jq work too.

### What is the difference between a recipient list, a routing slip and a multicast?

A multicast and a recipient list send copies to several endpoints (a fixed list or one computed
per message); a routing slip sends one message through several endpoints in sequence.

### How do I send a message to an endpoint whose name is in a header?

Use `toD` with a Simple expression, for example `toD: "kafka:${header.topic}"`. For a list of
endpoints, use `recipientList`.

### Does a filter stop the route?

No. Messages that do not match skip the filter's block and continue after it. Put the remaining
steps inside the block, or use `stop`, to end the route for them.

## Related

- [All EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html), [splitting and aggregating](https://pmsudhi.github.io/cameleer/docs/guides/eips/split-aggregate.html),
  [flow control and resilience](https://pmsudhi.github.io/cameleer/docs/guides/eips/flow-control.html)
- [Error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html)
- Apache Camel: [Enterprise Integration Patterns](https://camel.apache.org/components/next/eips/enterprise-integration-patterns.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/eips/split-aggregate.html

# Splitting and aggregating messages

> The splitter breaks one message into many, the aggregator combines many messages into one,
> and the resequencer and sort EIPs put messages and lists back in order.

These are the patterns for batch files, JSON arrays, order lines, sensor readings and document
chunks. Every example runs in the test suite as YAML and as Rust DSL. See
[the EIP guide](https://pmsudhi.github.io/cameleer/docs/guides/eips.html) for the other patterns.

## Splitter

`split` evaluates an expression that returns a list (a JSON array, lines of text, XML nodes)
and runs its steps once per item. Each part has the exchange properties `CamelSplitIndex`,
`CamelSplitSize` and `CamelSplitComplete`.

```yaml
- route:
    from:
      uri: direct:order
      steps:
        - split:
            jsonpath: "$.items"
            steps:
              - setHeader:
                  name: sku
                  simple: "${body[sku]}"
              - to: mock:order-line
```

```rust
b.from("direct:order")
    .split(jsonpath("$.items"))
        .set_header("sku", simple("${body[sku]}"))
        .to("mock:order-line")
    .end();
```

The order `{"items":[{"sku":"A1"},{"sku":"B2"}]}` gives two messages on `mock:order-line`,
with `sku` set to `A1` and `B2`.

Options: `parallelProcessing`, `streaming` (split a large text body lazily, one part at a time),
`stopOnException`, `timeout`, `shareUnitOfWork`, `delimiter` and `aggregationStrategy`. Without
an aggregation strategy the original message continues after the split, as in Camel.

### Split and aggregate the results

With an aggregation strategy, the split combines the outputs of its parts, and the route
continues with the combined message. This is the "composed message processor": split a request,
handle each part, and put the answers back together.

```yaml
- route:
    from:
      uri: direct:lines
      steps:
        - split:
            tokenize: "\n"
            aggregationStrategy: "#class:org.apache.camel.processor.aggregate.GroupedBodyAggregationStrategy"
            steps:
              - setBody:
                  simple: "${body.toUpperCase()}"
        - to: mock:upper-lines
```

```rust
b.from("direct:lines")
    .split(tokenize("\n"))
        .aggregation_strategy(strategies::grouped_body())
        .set_body(simple("${body.toUpperCase()}"))
    .end()
    .to("mock:upper-lines");
```

The body `a\nb\nc` reaches `mock:upper-lines` as the list `["A", "B", "C"]`. Built-in
strategies by name: `GroupedBodyAggregationStrategy`, `GroupedExchangeAggregationStrategy`,
`UseLatestAggregationStrategy`, `UseOriginalAggregationStrategy` and
`StringAggregationStrategy`, written as `#class:` references like in Camel or bound in the
registry under a name.

## Aggregator

`aggregate` collects messages with the same correlation key and releases them as one message
when a completion condition is met: `completionSize`, `completionTimeout` (an inactivity
timeout), `completionInterval`, `completionPredicate`, or
`completionFromBatchConsumer`. The exchange property `CamelAggregatedCompletedBy` tells which condition
fired (`size`, `timeout`, `predicate`, `interval`, `force`...).

```yaml
- route:
    from:
      uri: direct:readings
      steps:
        - aggregate:
            correlationExpression:
              simple: "${header.device}"
            aggregationStrategy: "#class:org.apache.camel.processor.aggregate.GroupedBodyAggregationStrategy"
            completionSize: 3
            completionTimeout: 5000
            steps:
              - to: mock:device-batch
```

```rust
b.from("direct:readings")
    .aggregate(header("device"), strategies::grouped_body())
        .completion_size(3)
        .completion_timeout(Duration::from_millis(5000))
        .to("mock:device-batch")
    .end();
```

Three readings from device `t1` are released together as `["20", "21", "22"]`; readings from
other devices are kept in their own groups. A group that stops receiving messages is released
after five seconds, so a quiet device still sends what it has.

Notes for Camel users: aggregation repositories are in memory by default; JDBC and Redis
repositories are available in `cameleer-sql` and `cameleer-datastores`, there is no LevelDB
repository. `forceCompletionOnStop`, `discardOnCompletionTimeout`,
`closeCorrelationKeyOnCompletion`, `eagerCheckCompletion` and
`completionOnNewCorrelationGroup` work as in Camel.

## Resequencer

The resequencer puts messages back in order by an expression, usually a sequence number. The
batch mode collects messages for `batchTimeout` milliseconds or `batchSize` messages, sorts
them and sends them on; the stream mode releases each message as soon as the gap before it is
filled.

```yaml
- route:
    from:
      uri: direct:out-of-order
      steps:
        - resequence:
            simple: "${header.seq}"
            batchConfig:
              batchSize: 3
              batchTimeout: 2000
            steps:
              - to: mock:in-order
```

```rust
b.from("direct:out-of-order")
    .resequence(header("seq"))
        .batch()
        .batch_size(3)
        .batch_timeout(Duration::from_millis(2000))
        .to("mock:in-order")
    .end();
```

Messages with `seq` 3, 1 and 2 leave in the order 1, 2, 3. The stream mode is set with
`streamConfig` (`capacity`, `timeout`, `rejectOld`).

## Sort

`sort` sorts the list an expression returns and replaces the body with the sorted list. It
works on the body of one message, unlike the resequencer, which orders several messages.

```yaml
- route:
    from:
      uri: direct:names
      steps:
        - sort:
            tokenize: ","
        - to: mock:sorted
```

```rust
b.from("direct:names")
    .sort(tokenize(","))
    .to("mock:sorted");
```

The body `pear,apple,fig` becomes `["apple", "fig", "pear"]`. A custom comparator can be bound
in the registry and named with `comparator`.

## Common questions

### How do I split a JSON array into separate messages?

Use `split` with `jsonpath: "$.items"` (or `simple: "${body}"` when the body already is a
list). Each item becomes the body of its own message.

### How do I split a large file without loading it all?

Set `streaming: true` on the split with a `tokenize` expression. The text is split one part at
a time and each part's exchange is created when it is needed.

### How do I batch messages, for example 100 at a time or every 10 seconds?

Use `aggregate` with a constant correlation expression (`constant: "all"`), the
`GroupedBodyAggregationStrategy`, `completionSize: 100` and `completionInterval: 10000`.

### Why does my split not return the processed parts?

Without an `aggregationStrategy` the original message continues after the split, as in Apache
Camel. Add a strategy such as `GroupedBodyAggregationStrategy` to get the parts back.

## Related

- [All EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html), [routing patterns](https://pmsudhi.github.io/cameleer/docs/guides/eips/routing.html), [transformation](https://pmsudhi.github.io/cameleer/docs/guides/eips/transformation.html)
- [Edge cookbook: aggregate sensor readings](https://pmsudhi.github.io/cameleer/docs/guides/edge.html#filter-and-aggregate-mqtt-sensor-readings)
- [Agents cookbook: RAG ingestion](https://pmsudhi.github.io/cameleer/docs/guides/agents.html#rag-ingestion-chunk-embed-and-store)
- Apache Camel: [Split](https://camel.apache.org/components/next/eips/split-eip.html),
  [Aggregate](https://camel.apache.org/components/next/eips/aggregate-eip.html),
  [Resequence](https://camel.apache.org/components/next/eips/resequence-eip.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/validate.html

# Validate routes with `cameleer validate`

> `cameleer validate` checks YAML and XML route files for syntax, structure, endpoint options,
> expressions, placeholders and route ids without starting any route or connecting to
> anything, and reports each problem with its line, column and a hint.

Use it before every run, in CI, in a pre-commit hook, and in the loop of a coding agent that
generates routes ([YAML for coding agents](https://pmsudhi.github.io/cameleer/docs/guides/yaml-for-coding-agents.html#the-validate-loop)). It
resolves endpoints with the same code the runtime uses, so an option it accepts is an option
Cameleer supports, exactly as Apache Camel would decide.

## Usage

```text
cameleer validate <file-or-dir>... [--format text|json] [--strict]
                  [--properties FILE] [--prop key=value]...
```


| argument | description |
|---|---|
| `<file-or-dir>...` | one or more route files, or folders: `*.yaml`, `*.yml` and `*.xml` files are found recursively, skipping `application*` files, hidden folders and `target` |
| `--format text` | human-readable output (the default) |
| `--format json` | one JSON document on standard output, for tools and agents |
| `--strict` | warnings make the exit code 1 |
| `--properties FILE` | a properties file used to resolve `{{...}}` placeholders (repeatable). Without it, `application.*` in the current folder is loaded, as `run` does |
| `--prop key=value` | one property; repeat for more |

Files are validated together: a `direct:` endpoint used in one file and consumed in another is
not a dangling endpoint, and two files with the same route id are a duplicate.

The command never starts routes, never opens ports and never connects to brokers, databases or
APIs, so it needs no credentials and runs in sandboxes and CI without network access.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer validate /routes
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer validate /routes --format json --strict
```

## What it checks

| code | severity | what it means |
|---|---|---|
| `yaml-syntax` | error | the file is not valid YAML (bad indentation, an unclosed quote, a tab) |
| `xml-syntax` | error | an `.xml` route file is not well-formed XML |
| `dsl-structure` | error | the YAML does not have the shape of the YAML DSL: an unknown top-level element, step or key, a missing required key, a value of the wrong type. The hint suggests the name you probably meant ("did you mean ...") |
| `endpoint` | error | an unknown scheme, or an option the component does not support, decided the same way Apache Camel does |
| `expression` | error | an expression (Simple, JSONPath, jq, XPath, ...) does not compile |
| `unresolved-placeholder` | warning | a `{{...}}` placeholder has no value from `--properties`/`--prop` and no default |
| `dangling-endpoint` | warning | `to: direct:x` (or a similar in-process endpoint) with no route consuming `from: direct:x` |
| `duplicate-route-id` | error | two routes share an `id` |

`unresolved-placeholder` is a warning because the value often comes from the environment where
the route runs. Pass the same properties file you run with, or use `--strict` to make warnings
fail too.

How placeholders, secrets and beans are treated, so results are the same on every machine:

- `{{env:NAME}}` is looked up in `--prop`/`--properties` (key `NAME`), never in the process
  environment. `{{env:NAME:default}}` uses the default.
- A secret with an empty default (`accessKey=RAW({{env:KEY:}})`) is checked again with a stand-in
  value when the empty value is rejected, so misspelled option names are still caught.
- An endpoint that only fails because a bean is missing from the registry (a `dataSource`, a
  `ref:` endpoint) is not reported: beans can come from code, `camel.beans.*` or
  `camel.datasource.*`.
- Endpoints that read a companion file when they are created (a `.proto`, `.thrift` or WSDL file
  next to the route) are reported if the file is not where the URI says. Validate the route from
  the folder it runs in.
- XML routes go through the same structure checks after the loader converts them; findings in
  XML files have no line or column (except `xml-syntax`).

## Output

### Text

One line per finding, in the usual compiler format, then a summary:

```text
path:line:column: severity[code]: message (hint)
```

For example, for a file with a misspelled step and an unknown option:

```text
$ cameleer validate orders.camel.yaml
orders.camel.yaml:8:11: error[dsl-structure]: unknown step 'setbody' (did you mean 'setBody'?)
orders.camel.yaml:12:15: error[endpoint]: timer:tick?perod=1000: unknown option 'perod' (did you mean 'period'?)
orders.camel.yaml:15:15: warning[dangling-endpoint]: no route consumes direct:billing
1 file, 2 errors, 1 warning
```

### JSON

```json
{
  "valid": false,
  "files": [
    {
      "path": "orders.camel.yaml",
      "valid": false,
      "routes": 2,
      "findings": [
        {
          "severity": "error",
          "code": "dsl-structure",
          "message": "unknown step 'setbody'",
          "line": 8,
          "column": 11,
          "hint": "did you mean 'setBody'?"
        }
      ]
    }
  ],
  "summary": {"files": 1, "errors": 1, "warnings": 0}
}
```

| field | description |
|---|---|
| `valid` | `true` when no file has an error (and, with `--strict`, no warning) |
| `files[].path`, `files[].valid`, `files[].routes` | each file, whether it is valid, how many routes it defines |
| `findings[].severity` | `error` or `warning` |
| `findings[].code` | one of the codes above |
| `findings[].message`, `findings[].hint` | what is wrong, and a suggestion (the hint may be empty) |
| `findings[].line`, `findings[].column` | 1-based position in the file |
| `summary` | counts of files, errors and warnings |

### Exit codes

| code | meaning |
|---|---|
| `0` | valid |
| `1` | at least one error, or at least one warning with `--strict` |
| `2` | bad usage: an unknown option, no file given, a file that does not exist |

## A route that passes

This route validates cleanly: every option exists, the expression compiles, the placeholder has a
default and `direct:billing` is consumed in the same file.

```yaml
- route:
    id: orders
    from:
      uri: timer:tick
      parameters:
        period: "{{orders.period:1000}}"
        repeatCount: 1
      steps:
        - setBody:
            simple: "order of ${date:now:yyyy-MM-dd}"
        - to: direct:billing
- route:
    id: billing
    from:
      uri: direct:billing
      steps:
        - log: "billing ${body}"
        - to: mock:billed
```

## Use it in CI

A GitHub Actions job that fails the build when a route file is invalid:

```yaml
name: routes
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate route files
        run: docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer validate /routes --strict
```

As a pre-commit hook (`.git/hooks/pre-commit`):

```sh
#!/bin/sh
cameleer validate $(git diff --cached --name-only -- '*.camel.yaml') --strict
```

## Editor support

`cameleer schema` prints a JSON Schema (draft 2020-12) of the YAML DSL, generated from the
same tables the validator uses: every top-level element, all steps with their keys and types,
required keys, nested elements and every expression form. Use it for completion and inline
errors while you type:

```sh
cameleer schema > cameleer.schema.json
```

- VS Code with the YAML extension: add to `.vscode/settings.json`:
  `"yaml.schemas": {"./cameleer.schema.json": "*.camel.yaml"}`, or put
  `# yaml-language-server: $schema=./cameleer.schema.json` on the first line of a route file.
- JetBrains IDEs: Settings, Languages & Frameworks, Schemas and DTDs, JSON Schema Mappings, add
  the file for `*.camel.yaml`.

The schema does not know component options (they depend on the URI) or data-format and language
options, and covers Kamelet, Pipe and Integration resources only partly. Run `cameleer validate`
for those checks.

## Common questions

### Does validate start my routes or connect to my broker?

No. It loads the files with the real YAML loader, creates endpoint objects to check their
options, compiles expressions, and stops there. Nothing is started and nothing connects.

### Why is a missing property only a warning?

Because properties often come from the environment of the machine that runs the route. Pass
`--properties` with the file you run with, or use `--strict` in CI.

### Can I validate a whole folder?

Yes: `cameleer validate routes/` checks its route files together, which also makes
cross-file `direct:` references and duplicate ids visible.

### Is validate the same as running with `--max-seconds 1`?

No. Running starts routes and connects to real systems; validate does neither, so it is safe on
any machine and fast enough for every save.

## Related

- [YAML for coding agents](https://pmsudhi.github.io/cameleer/docs/guides/yaml-for-coding-agents.html), [YAML DSL reference](https://pmsudhi.github.io/cameleer/docs/guides/yaml-dsl.html)
- [Getting started](https://pmsudhi.github.io/cameleer/docs/guides/getting-started.html), [deployment guide](https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html)
- [Components](https://pmsudhi.github.io/cameleer/docs/components/index.html): the options each endpoint accepts

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/guides/yaml-for-coding-agents.html

# YAML routes for coding agents

> How an AI coding assistant should write Cameleer YAML routes: start from a tested skeleton,
> follow a short list of rules, look up component options instead of guessing, and run
> `cameleer validate` until the file is clean before running it.

This page is written for coding agents (Claude Code, Codex, Copilot, Cursor and similar) and for
the people who review their work. It is deliberately strict: it lists one way to do each thing,
the way that is known to work. The complete syntax is in the [YAML DSL reference](https://pmsudhi.github.io/cameleer/docs/guides/yaml-dsl.html).
Every skeleton below runs in the test suite (`crates/cameleer-main/tests/docs_yaml.rs`).

## The checklist

Do these in order for every route file you write or change:

1. Name the file `<purpose>.camel.yaml`.
2. Start from the closest [skeleton](#skeletons) on this page. Do not start from memory of the
   Java DSL or Spring XML.
3. For every endpoint, open `docs/components/<scheme>.md` (or run
   `cameleer catalog components`) and use only options listed there. Never invent an option.
4. Put hosts, ports, credentials and tokens in placeholders: `{{env:NAME:default}}` for
   environment variables, `{{name:default}}` for properties. No secret ever goes in the file.
5. Give every route an `id` (kebab-case, unique across files).
6. Validate: `cameleer validate <file> --format json`. Fix every finding with severity `error`,
   read every `warning`, and repeat until `"valid": true`.
7. Run it: `cameleer run <file>` (add `--max-seconds 10` for a smoke test), or in Docker:
   `docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/<file>`.
8. If you changed Cameleer itself rather than a route, run `cargo test --workspace`.

## Rules that prevent the usual mistakes

**Structure**

- The file is a YAML list: every top-level item starts with `- ` and has exactly one key
  (`route`, `rest`, `restConfiguration`, `routeConfiguration`, `routeTemplate`,
  `templatedRoute`, `errorHandler`, `beans`).
- A route is `- route:` with `id` and `from`; `from` has `uri` and `steps`; `steps` is
  indented under `from`, aligned with `uri`.
- Each step is one list item with exactly one key, the step name. All options of a step go
  under that key. A step that contains steps (`filter`, `split`, `choice`/`when`, `doTry`,
  `aggregate`, `loop`, ...) has its own `steps` list under its own keys.
- `choice` takes `when:` (a list, each item with one expression key and `steps`) and
  `otherwise:` (a mapping with `steps`).
- Use Camel 4 names exactly: `setBody`, `setHeader`, `toD`, `wireTap`, `doTry`/`doCatch`/
  `doFinally`, `onException`, `aggregationStrategy`, `completionSize`. They are camelCase.

**Expressions**

- Write expressions in the short form: `simple: "..."`, `constant: ...`, `header: name`,
  `jsonpath: "$.x"`. One language key per step.
- Always quote Simple expressions with double quotes. Use single quotes for string literals
  inside Simple: `simple: "${header.type} == 'gold'"`.
- A JSON body built with Simple goes in single quotes: `simple: '{"id": "${header.id}"}'`.
- `${...}` is evaluated only in expressions, `log` messages and `toD` URIs. In a `to` URI it is
  literal text: use `toD` when the URI depends on the message.
- Header values from HTTP requests, files and queues are text: compare numbers with
  `${header.amount} > 100` (Simple converts) rather than string equality.

**Endpoints**

- Prefer `uri:` plus `parameters:` over long inline query strings: values are URL-encoded for
  you and option names are easy to check.
- Quote any value that starts with `{{`, `{`, `*`, `&`, `!`, `%` or `@`, or that contains `: `
  or ` #`.
- Use `direct:` to connect your own routes; `seda:` for an in-process queue. Sending from a
  request/reply route (REST, HTTP) to `seda:` with the default pattern waits for the consumer;
  add `pattern: InOnly` to hand the message off and reply at once.
- Use booleans `true`/`false` only. `yes`, `no`, `on`, `off` are strings in YAML 1.2 and are
  rejected or ignored.

**Behaviour**

- Error handling goes in a `routeConfiguration` (shared) or an `onException` at the start of a
  route's steps. Use `handled: {constant: true}` when the error should not reach the caller.
- After `split`, the message is the original one unless you set `aggregationStrategy`
  (`groupedBody` collects the parts' bodies in a list).
- Durations: plain numbers are milliseconds; `5s`, `250ms`, `PT1M` also work.
- Do not use `beans:` for Java classes: the `cameleer` binary cannot create them. Use built-in
  aggregation strategies by name (`groupedBody`, `useLatest`, `string`) and Simple, JSONPath or
  jq instead of custom code.

## Look up a component's options

- `docs/components/<scheme>.md` has the URI format, every supported option with its default,
  the message headers, and a tested example. For example `docs/components/kafka.md`,
  `docs/components/http.md`, `docs/components/aws2-s3.md`.
- `cameleer catalog components` lists every scheme in your build; `cameleer catalog languages`
  lists the expression languages; `cameleer catalog kamelets` lists the Kamelets.
- Options and headers have the same names as in Apache Camel. When a page and the Camel docs
  disagree, the page (and the validator) describe what Cameleer does.
- An option that is not supported fails validation with code `endpoint`. Do not "fix" it by
  removing random options: look the option up.

## Secrets and configuration

```text
{{env:KAFKA_BROKERS:localhost:9092}}   environment variable with a default
{{env:SLACK_TOKEN}}                     environment variable, required
{{orders.topic:orders}}                 property from application.properties, --prop or CAMEL_* env vars
{{aws:db-password}}                     secret from AWS Secrets Manager (also azure:, gcp:)
```

A required placeholder (no default) that is not set fails at startup; `cameleer validate`
reports it as `unresolved-placeholder` (a warning, because it may be set where the route runs).
Pass test values with `--prop key=value` or `--properties application.properties`.

## Skeletons

Copy the closest skeleton, rename ids and endpoints, then validate.

### Consume, transform, deliver

Read JSON files from a folder, add a field, write them to another folder. The same shape works
for Kafka, AMQP, SQS or MQTT: change the two URIs and their options.

```yaml
- route:
    id: enrich-orders
    from:
      uri: "file:{{env:INBOX_DIR:inbox}}"
      parameters:
        include: ".*\\.json"
        move: .done
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: orderId
            simple: "${body[id]}"
        - setBody:
            simple: '{"id": "${header.orderId}", "status": "received"}'
        - log: "order ${header.orderId} received"
        - to:
            uri: "file:{{env:OUTBOX_DIR:outbox}}"
            parameters:
              fileName: "${header.orderId}.json"
```

### REST API

Two operations backed by `direct:` routes. Path parameters become headers; the response code
is the `CamelHttpResponseCode` header.

```yaml
- restConfiguration:
    contextPath: /api
- rest:
    path: /devices
    get:
      - path: /{id}
        id: get-device
        to: direct:get-device
    post:
      - id: register-device
        to: direct:register-device
- route:
    id: get-device-route
    from:
      uri: direct:get-device
      steps:
        - setHeader:
            name: Content-Type
            constant: application/json
        - setBody:
            simple: '{"id": "${header.id}", "online": true}'
- route:
    id: register-device-route
    from:
      uri: direct:register-device
      steps:
        - setHeader:
            name: CamelHttpResponseCode
            constant: 201
        - setBody:
            simple: "registered ${body}"
```

### Scheduled job

Call an HTTP API on a schedule and deliver the answer. `timer` takes a period in milliseconds;
use `cron` or `quartz` for calendar schedules.

```yaml
- route:
    id: poll-status
    from:
      uri: timer:poll-status
      parameters:
        period: "{{status.period:60000}}"
      steps:
        - setHeader:
            name: CamelHttpMethod
            constant: GET
        - to: "{{env:STATUS_URL:http://localhost:8080/health}}"
        - convertBodyTo: String
        - log: "status: ${body}"
        - to: "{{env:STATUS_SINK:log:status}}"
```

### Error handling

Retry, then send what still fails to a dead letter endpoint; turn bad input into a clear reply
instead.

```yaml
- routeConfiguration:
    errorHandler:
      deadLetterChannel:
        deadLetterUri: "{{env:DEAD_LETTER_URI:log:dead-letters}}"
        useOriginalMessage: true
        redeliveryPolicy:
          maximumRedeliveries: 3
          redeliveryDelay: 1s
          useExponentialBackOff: true
    onException:
      - onException:
          exception:
            - java.lang.IllegalArgumentException
          handled:
            constant: true
          steps:
            - setBody:
                simple: "invalid input: ${exception.message}"
- route:
    id: process-payment
    from:
      uri: direct:payment
      steps:
        - filter:
            simple: "${body} == ''"
            steps:
              - throwException:
                  exceptionType: java.lang.IllegalArgumentException
                  message: empty payment
        - to: direct:gateway
- route:
    id: gateway
    from:
      uri: direct:gateway
      steps:
        - setBody:
            simple: "charged ${body}"
```

## The validate loop

`cameleer validate` checks route files without starting routes or
connecting to anything. It is safe to run on any file, any number of times.

```sh
cameleer validate orders.camel.yaml --format json
cameleer validate routes/ --format json --strict --properties application.properties
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer validate /routes
```

The loop:

1. Write the file.
2. Run `cameleer validate <file> --format json`.
3. If `valid` is `false`, fix each finding, using `line`, `column`, `message` and `hint`.
   Fix the first `yaml-syntax` error first: later findings may come from it.
4. Repeat from step 2 until `valid` is `true` (exit code 0). With `--strict`, warnings count
   as errors, which is a good default for generated files.
5. Run the route.

The finding codes:

| code | severity | meaning | typical fix |
|---|---|---|---|
| `yaml-syntax` | error | the file is not valid YAML | fix indentation, quote the value |
| `dsl-structure` | error | the YAML is not a valid route: unknown element, step or key, a missing required key, a wrong type; the hint suggests the name you probably meant | rename or move the key as the hint says |
| `endpoint` | error | an unknown scheme or an option the component does not support (checked the same way Apache Camel does) | look up `docs/components/<scheme>.md` |
| `expression` | error | an expression does not compile | fix the Simple/JSONPath/jq syntax |
| `unresolved-placeholder` | warning | a `{{...}}` placeholder has no value and no default | add a default, or pass `--prop`/`--properties` |
| `dangling-endpoint` | warning | `to: direct:x` but no route consumes `from: direct:x` in the validated files | add the route, or validate all files together |
| `duplicate-route-id` | error | two routes have the same `id` | rename one |

Exit codes: `0` valid, `1` errors (or warnings with `--strict`), `2` bad usage. The full
reference, with the text and JSON output formats, is on the [validate page](https://pmsudhi.github.io/cameleer/docs/guides/validate.html).

## Worked example

**The request:** "Add an endpoint `POST /orders` that takes a JSON order. Reject an order with
no `id` with HTTP 400 and a JSON error. Put valid orders on a queue and answer 202 at once. A
worker with four consumers writes each order to the folder in `ORDERS_DIR` as
`order-<id>.json`."

**First draft.** The agent starts from the REST skeleton and writes the route. One line of the
draft:

```text
        - to: "seda:orders?concurrentConsumer=4"
```

**Validate.**

```text
$ cameleer validate orders.camel.yaml
orders.camel.yaml:33:15: error[endpoint]: seda:orders?concurrentConsumer=4: unknown option 'concurrentConsumer' (did you mean 'concurrentConsumers'?)
1 file, 1 error, 0 warnings
```

Two things are wrong here, and the validator found one of them: the option is
`concurrentConsumers`, and it belongs on the consumer (`from`), not on the producer. Looking up
[docs/components/seda.md](https://pmsudhi.github.io/cameleer/docs/components/seda.html) shows both. The agent also notices that a
REST route sending to `seda:` waits for the worker unless the send is `InOnly`.

**The fixed route**, which validates cleanly and runs:

```yaml
- rest:
    path: /orders
    post:
      - id: create-order
        consumes: application/json
        to: direct:create-order
- route:
    id: create-order-route
    from:
      uri: direct:create-order
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: Content-Type
            constant: application/json
        - choice:
            when:
              - simple: "${body[id]} == null"
                steps:
                  - setHeader:
                      name: CamelHttpResponseCode
                      constant: 400
                  - setBody:
                      constant: '{"error": "order id is required"}'
            otherwise:
              steps:
                - to:
                    uri: seda:orders
                    pattern: InOnly
                - setHeader:
                    name: CamelHttpResponseCode
                    constant: 202
                - setBody:
                    simple: '{"accepted": "${body[id]}"}'
- route:
    id: order-worker
    from:
      uri: seda:orders
      parameters:
        concurrentConsumers: 4
      steps:
        - setHeader:
            name: CamelFileName
            simple: "order-${body[id]}.json"
        - marshal:
            json: {}
        - to: "file:{{env:ORDERS_DIR:orders}}"
```

```text
$ cameleer validate orders.camel.yaml --format json
{"valid": true, "files": [{"path": "orders.camel.yaml", "valid": true, "routes": 3, "findings": []}], "summary": {"files": 1, "errors": 0, "warnings": 0}}
$ ORDERS_DIR=/tmp/orders cameleer run orders.camel.yaml
```

`curl -X POST localhost:8080/orders -d '{"id": "A-1", "total": 30}'` answers
`{"accepted": "A-1"}` with status 202 and writes `/tmp/orders/order-A-1.json`; a body without
`id` gets status 400 and `{"error": "order id is required"}`.

## Common questions

### Which file should an agent read first?

`AGENTS.md` at the repository root, then this page, then the [YAML DSL reference](https://pmsudhi.github.io/cameleer/docs/guides/yaml-dsl.html)
for anything a skeleton does not cover, and `docs/components/<scheme>.md` for each endpoint.

### How does an agent know an option exists?

It looks it up in `docs/components/<scheme>.md` and lets `cameleer validate` confirm it. The
validator resolves endpoints the same way the runtime does, so an option it accepts works.

### Can the validator run without the route's servers and credentials?

Yes. It never starts routes or connects to brokers, databases or APIs, so it runs anywhere,
including CI and sandboxes without network access. Placeholders without a value are reported as
warnings, not errors.

### What if the validator accepts a route that then fails at runtime?

The validator checks structure, endpoints and expressions, not reachability or data. Run the
route with `--max-seconds` against test inputs, and if the failure looks like a Cameleer bug,
report it (see below).

## Related

- [YAML DSL reference](https://pmsudhi.github.io/cameleer/docs/guides/yaml-dsl.html), [`cameleer validate`](https://pmsudhi.github.io/cameleer/docs/guides/validate.html)
- [Getting started](https://pmsudhi.github.io/cameleer/docs/guides/getting-started.html), [EIP guide](https://pmsudhi.github.io/cameleer/docs/guides/eips.html), [error handling](https://pmsudhi.github.io/cameleer/docs/guides/error-handling.html)
- [Cameleer for AI agents](https://pmsudhi.github.io/cameleer/docs/guides/agents.html): routes that call LLMs and tools
- [Components](https://pmsudhi.github.io/cameleer/docs/components/index.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/activemq.html

# ActiveMQ component

> The `activemq` component sends and receives messages on Apache ActiveMQ (Classic or Artemis) queues and topics with JMS semantics, over the broker's STOMP connector.

**Scheme:** `activemq:` · **Crate:** `cameleer-amqp` · **Cargo feature:** [`amqp`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [ActiveMQ](https://camel.apache.org/components/next/activemq-component.html)

## When to use it

- Keep Camel routes that use `activemq:queue:...` working against an existing ActiveMQ broker.
- Consume only matching messages with a JMS selector evaluated by the broker.
- Use transactions with redelivery and ActiveMQ's dead letter queue.

`activemq` is the [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html) component under another name: all options and headers are the same. It
uses the broker's STOMP connector (port 61613), not OpenWire. ActiveMQ 5 does not redeliver after a STOMP
`ABORT` or `NACK`, so Cameleer redelivers failed transacted messages itself, like ActiveMQ's JMS client
(configurable with `jms.redeliveryPolicy.*` options in the broker URL).

## URI format

```text
activemq:[queue:|topic:|temp-queue:|temp-topic:]destinationName[?options]
```

## Example

```yaml
- route:
    id: eu-orders
    from:
      uri: activemq:queue:orders
      parameters:
        brokerURL: "{{env:ACTIVEMQ_URL:tcp://localhost:61613}}"
        username: "{{env:ACTIVEMQ_USER:admin}}"
        password: "{{env:ACTIVEMQ_PASSWORD:admin}}"
        selector: "region = 'EU'"
      steps:
        - log: "EU order ${header.JMSMessageID}: ${body}"
        - to: log:eu-orders
```

Only messages whose `region` property is `EU` are delivered to this route; others stay on the queue for
other consumers.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("activemq:queue:orders?brokerURL=tcp://localhost:61613&selector=region = 'EU'")
            .route_id("eu-orders")
            .log("EU order ${header.JMSMessageID}: ${body}")
            .to("log:eu-orders");
    })
}
```

## Options

The same as [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html#options): `brokerURL`, `username`, `password`, `clientId`, `concurrentConsumers`,
`selector`, `transacted`, `acknowledgementModeName`, `replyTo`, `requestTimeout`, `deliveryPersistent`,
`priority`, `timeToLive`, `durableSubscriptionName`, ... Component-wide settings use the prefix
`camel.component.activemq.` (for example `camel.component.activemq.brokerUrl`).

## Message headers

The same as [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html#message-headers): `JMSMessageID`, `JMSCorrelationID`, `JMSDestination`,
`JMSReplyTo`, `JMSDeliveryMode`, `JMSPriority`, `JMSTimestamp`, `JMSType`, `JMSRedelivered`,
`JMSExpiration`, `CamelJmsDestinationName`, `CamelJmsRequestTimeout`.

## Run it with Docker

```sh
docker run --rm -e ACTIVEMQ_URL=tcp://activemq:61613 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

## Common questions

### Can Cameleer use ActiveMQ's OpenWire protocol (port 61616)?

No. Point `brokerURL` at the STOMP connector (61613), which ActiveMQ Classic and Artemis enable by default.
For AMQP 1.0 (port 5672) use [amqp](https://pmsudhi.github.io/cameleer/docs/components/amqp.html).

### Does the selector run in Cameleer or in the broker?

In the broker. Cameleer validates the selector syntax when the endpoint is created.

## Related

- [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html), [amqp](https://pmsudhi.github.io/cameleer/docs/components/amqp.html), [stomp](https://pmsudhi.github.io/cameleer/docs/components/stomp.html)
- [Apache Camel ActiveMQ component](https://camel.apache.org/components/next/activemq-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/amqp.html

# AMQP component

> The `amqp` component sends and receives messages over AMQP 1.0 with JMS semantics, for ActiveMQ Artemis, ActiveMQ Classic, Qpid, RabbitMQ's AMQP 1.0 support and Azure Service Bus.

**Scheme:** `amqp:` · **Crate:** `cameleer-amqp10` · **Cargo feature:** [`amqp10`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [AMQP](https://camel.apache.org/components/next/amqp-component.html)

## When to use it

- Integrate with brokers through the open AMQP 1.0 standard (port 5672, or 5671 with TLS).
- Use a broker queue as the work queue or event bus between AI agents and services, with request/reply,
  acknowledgements after processing and transactions.
- Store and forward from an edge site to a central broker over a standard, firewall-friendly protocol
  (also over WebSockets with `amqpws://` / `amqpwss://`).

The AMQP 1.0 stack is built into Cameleer (no Qpid JMS, no JVM). Messages follow the AMQP JMS mapping, so
Java JMS clients on the other side see normal JMS messages.

## URI format

```text
amqp:[queue:|topic:|temp-queue:]destinationName[?options]
```

## Example

```yaml
- route:
    id: process-orders
    from:
      uri: amqp:queue:orders
      parameters:
        remoteAddress: "{{env:AMQP_URL:amqp://localhost:5672}}"
        username: "{{env:AMQP_USER:admin}}"
        password: "{{env:AMQP_PASSWORD:admin}}"
        acknowledgementModeName: CLIENT_ACKNOWLEDGE
      steps:
        - setHeader:
            name: processedBy
            constant: cameleer
        - to: amqp:queue:orders.processed?remoteAddress={{env:AMQP_URL:amqp://localhost:5672}}&username={{env:AMQP_USER:admin}}&password={{env:AMQP_PASSWORD:admin}}
```

Each order is forwarded to `orders.processed` with an extra property. With `CLIENT_ACKNOWLEDGE` a message
whose route fails is returned to the broker and redelivered with `JMSRedelivered=true`.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.properties().set("camel.component.amqp.remoteAddress", "amqp://localhost:5672");
    ctx.add_routes(|b| {
        b.from("amqp:queue:orders?acknowledgementModeName=CLIENT_ACKNOWLEDGE")
            .route_id("process-orders")
            .set_header("processedBy", constant("cameleer"))
            .to("amqp:queue:orders.processed");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `remoteAddress` (aliases `remoteURI`, `brokerURL`, `connectionFactory.remoteURI`) | | `amqp://host:5672`, `amqps://host:5671` (TLS), `amqpws://` / `amqpwss://` (WebSockets). Also `camel.component.amqp.remoteAddress`, or `host` + `port`. |
| `username`, `password` | | Credentials (or user info in the URL). |
| `connectionFactory` | | `#bean` of type `AmqpConnectionFactory` with URI, credentials, client id and TLS. |
| `saslMechanism` | | Force a SASL mechanism. |
| `clientId` | | Container id, needed for durable subscriptions. |
| `concurrentConsumers` | `1` | Receivers on the destination. |
| `prefetchSize` | `100` | Link credit per receiver. |
| `selector` | | JMS selector, evaluated by the broker. |
| `acknowledgementModeName` | `AUTO_ACKNOWLEDGE` | `AUTO_ACKNOWLEDGE`, `DUPS_OK_ACKNOWLEDGE`, `CLIENT_ACKNOWLEDGE` (failed messages are returned for redelivery) or `SESSION_TRANSACTED`. |
| `transacted` | `false` | AMQP local transactions: acknowledge and reply inside a transaction; failures roll back. |
| `replyTo` | | Fixed reply address instead of a dynamic temporary queue. |
| `requestTimeout` | `20000` | InOut producer: wait (ms) for the reply. |
| `disableReplyTo` | `false` | Do not handle reply-to. |
| `deliveryPersistent` | `true` | Persistent sends wait for the broker's `accepted` outcome; others are sent pre-settled. |
| `deliveryMode` | | `1` or `2`. |
| `priority` | | Message priority. |
| `timeToLive` | `-1` | Expiry in ms. |
| `preserveMessageQos` | `false` | Take QoS from the JMS headers. |
| `jmsMessageType` | from the body | `Text`, `Bytes`, `Map` or `Object`. |
| `durableSubscriptionName`, `subscriptionName`, `subscriptionDurable`, `subscriptionShared` | | Durable and shared (JMS 2.0) topic subscriptions. |
| `includeAmqpAnnotations` | `false` | Message annotations become `JMS_AMQP_MA_<key>` headers. |
| `recoveryInterval` | `5000` | ms between reconnect attempts. |
| `idleTimeout` | `60000` | AMQP idle timeout (heartbeats). |
| `maxFrameSize` | `1048576` | Largest frame. |
| `sslContextParameters`, `useGlobalSslContextParameters` | | TLS trust settings. |

## Message headers

| header | direction | description |
|---|---|---|
| `JMSMessageID`, `JMSCorrelationID`, `JMSDestination`, `JMSReplyTo`, `JMSType`, `JMSTimestamp`, `JMSExpiration`, `JMSDeliveryMode`, `JMSPriority`, `JMSRedelivered` | out (consumer), some in (producer) | Mapped from the AMQP message properties and header. |
| `JMSXDeliveryCount`, `JMSXUserID`, `JMSXGroupID`, `JMSXGroupSeq` | out | AMQP delivery count, user id and group. |
| `JMS_AMQP_MA_<key>` | out | Message annotations, with `includeAmqpAnnotations=true`. |

Other headers are AMQP application properties.

## Run it with Docker

```sh
docker run --rm -e AMQP_URL=amqp://artemis:5672 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

## Common questions

### Which brokers work?

Anything that speaks AMQP 1.0: ActiveMQ Artemis, ActiveMQ Classic (with the `queue://` / `topic://`
prefixes it announces), Apache Qpid, RabbitMQ with AMQP 1.0, and Azure Service Bus (see also the
`azure-servicebus` component).

### Is this the same as RabbitMQ's AMQP 0-9-1?

No. AMQP 0-9-1 is a different protocol; use [spring-rabbitmq](https://pmsudhi.github.io/cameleer/docs/components/spring-rabbitmq.html) or
[rabbitmq](https://pmsudhi.github.io/cameleer/docs/components/rabbitmq.html) for it.

### My old Cameleer routes used `amqp:` for STOMP. What changed?

`amqp:` now means AMQP 1.0, as in Apache Camel. The STOMP flavour is available as
[amqp-stomp](https://pmsudhi.github.io/cameleer/docs/components/amqp-stomp.html) (and [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html)).

## Related

- [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html), [activemq](https://pmsudhi.github.io/cameleer/docs/components/activemq.html), [amqp-stomp](https://pmsudhi.github.io/cameleer/docs/components/amqp-stomp.html), [kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html)
- [Apache Camel AMQP component](https://camel.apache.org/components/next/amqp-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/amqp-stomp.html

# AMQP-STOMP component

> The `amqp-stomp` component is Cameleer's JMS-over-STOMP component under a third name, for routes that used Cameleer's former STOMP-based `amqp` scheme.

**Scheme:** `amqp-stomp:` · **Crate:** `cameleer-amqp` · **Cargo feature:** [`amqp`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** none (Cameleer only; see [JMS](https://camel.apache.org/components/next/jms-component.html))

## When to use it

- You have routes from an earlier Cameleer version where `amqp:` meant JMS over STOMP. Rename the scheme to
  `amqp-stomp:` and keep the rest.
- You want JMS semantics through a STOMP connector and also use [amqp](https://pmsudhi.github.io/cameleer/docs/components/amqp.html) (AMQP 1.0) in the same
  application, with separate component settings.

For new routes use [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html) (STOMP) or [amqp](https://pmsudhi.github.io/cameleer/docs/components/amqp.html) (AMQP 1.0, Camel's meaning of `amqp:`).

## URI format

```text
amqp-stomp:[queue:|topic:|temp-queue:|temp-topic:]destinationName[?options]
```

## Example

```yaml
- route:
    id: work-queue
    from:
      uri: amqp-stomp:queue:jobs
      parameters:
        brokerURL: "{{env:STOMP_BROKER_URL:tcp://localhost:61613}}"
        concurrentConsumers: 3
      steps:
        - log: "job ${body}"
        - to: log:jobs
```

Three consumers compete for the messages on the queue `jobs`.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("amqp-stomp:queue:jobs?brokerURL=tcp://localhost:61613&concurrentConsumers=3")
            .route_id("work-queue")
            .log("job ${body}")
            .to("log:jobs");
    })
}
```

## Options

The same as [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html#options). Component-wide settings use the prefix `camel.component.amqp-stomp.`;
the broker URL may also be given as `camel.component.amqp-stomp.remoteURI`.

## Message headers

The same as [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html#message-headers).

## Run it with Docker

```sh
docker run --rm -e STOMP_BROKER_URL=tcp://broker:61613 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/jobs.camel.yaml
```

## Common questions

### Why is there an amqp-stomp scheme at all?

Apache Camel's `amqp:` is JMS over AMQP 1.0. When Cameleer gained an AMQP 1.0 stack, `amqp:` took that
meaning and the older STOMP flavour moved to `amqp-stomp:`.

## Related

- [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html), [amqp](https://pmsudhi.github.io/cameleer/docs/components/amqp.html), [stomp](https://pmsudhi.github.io/cameleer/docs/components/stomp.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/atom.html

# Atom component

> The `atom` component polls an Atom feed and emits each new entry as an exchange whose body is the entry.

**Scheme:** `atom:` · **Crate:** `cameleer-saas` · **Cargo feature:** [`saas`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Atom](https://camel.apache.org/components/next/atom-component.html)

`atom` shares its implementation with [rss](https://pmsudhi.github.io/cameleer/docs/components/rss.html) and parses Atom 1.0, RSS 2.0 and RSS 1.0.
The difference: with `splitEntries=true` the body is the entry map itself (`${body[title]}`),
not a feed holding one entry.

## When to use it

- Watch GitHub release feeds (`https://github.com/<owner>/<repo>/releases.atom`) and start an
  upgrade check or notify a team.
- Follow blogs and changelogs that publish Atom.
- Feed new entries to an AI agent for summaries or tagging.

## URI format

```text
atom:feedUrl[?options]
```

## Example

Check a project's release feed every hour and queue each new release.

```yaml
- route:
    id: release-watch
    from:
      uri: "atom:{{env:RELEASES_FEED:https://github.com/apache/camel/releases.atom}}?delay=3600000&throttleEntries=false"
      steps:
        - setBody:
            simple: "new release ${body[title]}: ${body[link]}"
        - to: seda:releases
- route:
    id: notify-release
    from:
      uri: seda:releases
      steps:
        - log: "${body}"
```

## Rust DSL

```rust
fn release_watch_routes(b: &mut RouteBuilder, feed_url: &str) {
    b.from(&format!("atom:{}?delay=3600000&throttleEntries=false", feed_url))
        .route_id("release-watch")
        .set_body(simple("new release ${body[title]}: ${body[link]}"))
        .to("seda:releases");
    b.from("seda:releases").route_id("notify-release").log("${body}");
}
```

## Options

The same as [rss](https://pmsudhi.github.io/cameleer/docs/components/rss.html#options): `splitEntries`, `filter`, `lastUpdate`, `sortEntries`,
`throttleEntries`, `feedHeader`, and the scheduler options (`delay` 60000 ms). Unknown options
are added to the feed URL's query.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAtomFeed` | out | The whole feed (with `feedHeader=true`). |

Entry map: `title`, `link`, `uri` (the Atom `id`), `description` (summary), `contents`,
`author`, `publishedDate`, `updatedDate`, `categories`.

## Run it with Docker

```sh
docker run --rm -e RELEASES_FEED=https://github.com/apache/kafka/releases.atom \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/release-watch.camel.yaml
```

## Common questions

### Why do I only get one entry per poll?
`throttleEntries` defaults to `true`, as in Apache Camel. Set it to `false` to get all new
entries at once.

### How do I skip old entries on the first poll?
Set `lastUpdate=2026-11-01T00:00:00`; only newer entries are delivered.

## Related

- [rss](https://pmsudhi.github.io/cameleer/docs/components/rss.html), [http](https://pmsudhi.github.io/cameleer/docs/components/http.html).
- Apache Camel: [Atom component](https://camel.apache.org/components/next/atom-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-athena.html

# AWS Athena component

> The `aws2-athena` component runs SQL queries on data in S3 with Amazon Athena, waits for them to finish and returns the result rows.

**Scheme:** `aws2-athena:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Athena](https://camel.apache.org/components/next/aws2-athena-component.html)

## When to use it

- Produce scheduled reports from a data lake (orders per region, error counts).
- Feed query results into another system (e-mail, a database, an API).
- Let an AI agent answer analytical questions with a fixed, reviewed set of queries.

## URI format

```text
aws2-athena://label[?options]
```

## Example

Run a query, wait for it, and fetch all result rows:

```yaml
- route:
    id: orders-per-region
    from:
      uri: "timer:athena-report?repeatCount=1"
      steps:
        - setBody:
            constant: "SELECT region, count(*) AS orders FROM orders GROUP BY region"
        - to: "aws2-athena://report?region={{env:AWS_REGION:us-east-1}}&database=analytics&outputLocation=s3://{{env:ATHENA_RESULTS_BUCKET:athena-results}}/&waitTimeout=60000&operation=startQueryExecution"
        - to: "aws2-athena://report?region={{env:AWS_REGION:us-east-1}}&operation=getQueryResults"
        - log: "rows: ${body}"
        - to: "log:report"
```

`startQueryExecution` takes the SQL from the body, polls the query until it ends (up to
`waitTimeout` ms) and sets `CamelAwsAthenaQueryExecutionId`, which `getQueryResults` then uses. With
the default `outputType=StreamList` the body is a list of rows (each a list of strings), the header
row first.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:athena-report?repeatCount=1")
        .set_body(constant("SELECT region, count(*) AS orders FROM orders GROUP BY region"))
        .to("aws2-athena://report?region={{env:AWS_REGION:us-east-1}}&database=analytics&outputLocation=s3://{{env:ATHENA_RESULTS_BUCKET:athena-results}}/&waitTimeout=60000&operation=startQueryExecution")
        .to("aws2-athena://report?region={{env:AWS_REGION:us-east-1}}&operation=getQueryResults")
        .log("rows: ${body}")
        .to("log:report");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `startQueryExecution` | `startQueryExecution`, `getQueryExecution`, `getQueryResults`, `listQueryExecutions`. |
| `queryString` | | SQL (otherwise `CamelAwsAthenaQueryString` or the body). |
| `database` | | Database of the query. |
| `outputLocation` | | S3 location of the results. |
| `workGroup` | | Work group. |
| `encryptionOption`, `kmsKey` | | Encryption of the results. |
| `clientRequestToken` | | Idempotency token. |
| `waitTimeout` | `0` | Wait (ms) for the query to finish; 0 returns at once. |
| `initialDelay`, `delay` | `1000`, `2000` | First and next status checks while waiting (ms). |
| `maxAttempts` | `1` | Attempts for failed queries. |
| `retry` | `never` | When to retry: `never`, `always`, `retryable`, `exhausted`, `generic` (comma separated). |
| `outputType` | `StreamList` | `getQueryResults`: `StreamList` (all pages, list of rows), `SelectList` (one page, raw response) or `S3Pointer` (the S3 location). |
| `maxResults`, `nextToken` | | Paging of `SelectList` and `listQueryExecutions`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsAthenaOperation` | in | Overrides `operation`. |
| `CamelAwsAthenaQueryString`, `CamelAwsAthenaDatabase`, `CamelAwsAthenaWorkGroup`, `CamelAwsAthenaOutputLocation`, `CamelAwsAthenaEncryptionOption`, `CamelAwsAthenaKmsKey`, `CamelAwsAthenaClientRequestToken` | in | Override the options. |
| `CamelAwsAthenaWaitTimeout`, `CamelAwsAthenaInitialDelay`, `CamelAwsAthenaDelay`, `CamelAwsAthenaMaxAttempts`, `CamelAwsAthenaRetry` | in | Override the waiting options. |
| `CamelAwsAthenaQueryExecutionId` | in/out | Query execution. |
| `CamelAwsAthenaQueryExecutionState` | out | `SUCCEEDED`, `FAILED`, `CANCELLED`, ... |
| `CamelAwsAthenaOutputLocation` | out | Where the results are. |
| `CamelAwsAthenaStartQueryExecutionAttempts`, `CamelAwsAthenaStartQueryExecutionElapsedMillis` | out | Attempts and time spent. |
| `CamelAwsAthenaOutputType`, `CamelAwsAthenaMaxResults`, `CamelAwsAthenaNextToken` | in/out | Result paging. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e ATHENA_RESULTS_BUCKET \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/report.camel.yaml
```

## Common questions

### Why is the first row the column names?

Athena returns the header as the first row of the first page. To skip it, `split` on `${body}`
and `filter` on `${exchangeProperty.CamelSplitIndex} > 0`.

### How do I handle large results?

Use `outputType=S3Pointer` and read the CSV result file from S3 with [aws2-s3](https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html), or
`SelectList` with `maxResults` to page through the results.

## Related

- [AWS S3](https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html), [AWS Redshift Data](https://pmsudhi.github.io/cameleer/docs/components/aws2-redshift-data.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Athena](https://camel.apache.org/components/next/aws2-athena-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html

# AWS Bedrock component

> The `aws-bedrock` component calls foundation models on Amazon Bedrock (Claude, Llama, Titan, Mistral and others) with the Converse and InvokeModel APIs, including streaming and guardrails.

**Scheme:** `aws-bedrock:` · **Also:** `aws2-bedrock:` (same component) · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [AWS Bedrock](https://camel.apache.org/components/next/aws-bedrock-component.html)

## When to use it

- Summarize, classify or translate messages with a large language model inside a route.
- Build AI agents: the Converse API takes a message list, a system prompt and tool definitions, and
  returns the model's answer, stop reason and token usage.
- Create embeddings for retrieval (`invokeEmbeddingsModel`) or images (`invokeImageModel`).
- Check prompts and answers against a Bedrock guardrail before they reach users.

For knowledge bases and Bedrock Agents, use [aws-bedrock-agent-runtime](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock-agent-runtime.html).

## URI format

```text
aws-bedrock://label?modelId=...[&options]
```

The path is a free label. `modelId` is the Bedrock model id or an inference profile id.

## Example

Summarize support tickets from a queue with Claude and publish the summary to a topic:

```yaml
- route:
    id: summarize-tickets
    from:
      uri: "aws2-sqs://support-tickets?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - setHeader:
            name: CamelAwsBedrockConverseSystem
            constant: "Summarize the support ticket in one sentence."
        - to: "aws-bedrock://summarizer?region={{env:AWS_REGION:us-east-1}}&modelId={{env:BEDROCK_MODEL_ID:anthropic.claude-3-haiku-20240307-v1:0}}&operation=converse"
        - log: "summary (${header.CamelAwsBedrockConverseStopReason}): ${body}"
        - to: "aws2-sns://ticket-summaries?region={{env:AWS_REGION:us-east-1}}&autoCreateTopic=true"
```

With `converse`, a text body becomes one user message and the body after the call is the model's
answer text. The full output message, the stop reason and the token usage are in headers.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://support-tickets?region={{env:AWS_REGION:us-east-1}}")
        .set_header("CamelAwsBedrockConverseSystem", constant("Summarize the support ticket in one sentence."))
        .to("aws-bedrock://summarizer?region={{env:AWS_REGION:us-east-1}}&modelId={{env:BEDROCK_MODEL_ID:anthropic.claude-3-haiku-20240307-v1:0}}&operation=converse")
        .log("summary (${header.CamelAwsBedrockConverseStopReason}): ${body}")
        .to("aws2-sns://ticket-summaries?region={{env:AWS_REGION:us-east-1}}&autoCreateTopic=true");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `modelId` | | Model or inference profile id (`CamelAwsBedrockModelId` overrides it). |
| `operation` | `invokeTextModel` | `invokeTextModel`, `invokeImageModel`, `invokeEmbeddingsModel`, `converse`, `invokeTextModelStreaming`, `invokeImageModelStreaming`, `invokeEmbeddingsModelStreaming`, `converseStream`, `applyGuardrail`. |
| `streamOutputMode` | `complete` | Streaming operations: `complete` (body = whole text) or `chunks` (body = list of chunks). |
| `streamingChunkProcessor` | | `#bean` of a processor called for every chunk while the response streams (body = chunk text). |
| `guardrailIdentifier`, `guardrailVersion` | | Guardrail used by `applyGuardrail` and applied to invoke and converse requests. |
| `guardrailTrace` | `false` | Ask for the guardrail trace. |

The invoke operations post the body as is (a map is sent as JSON): you write the request in the
model's own format (for Anthropic models the Messages API body, for Titan `{"inputText": ...}`),
and the parsed JSON response becomes the body.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsBedrockOperation`, `CamelAwsBedrockModelId` | in | Override `operation` and `modelId`. |
| `CamelAwsBedrockContentType`, `CamelAwsBedrockAcceptContentType` | in | Content types of invoke requests (default `application/json`). |
| `CamelAwsBedrockConverseMessages` | in | Converse message list (`{role, content}` maps); otherwise the body is used. |
| `CamelAwsBedrockConverseSystem` | in | System prompt (text or content blocks). |
| `CamelAwsBedrockConverseInferenceConfig` | in | Map such as `{maxTokens, temperature, topP}`. |
| `CamelAwsBedrockConverseToolConfig` | in | Tool definitions for agentic tool use. |
| `CamelAwsBedrockConverseStopReason` | out | `end_turn`, `max_tokens`, `tool_use`, ... |
| `CamelAwsBedrockConverseUsage` | out | Token usage (map). |
| `CamelAwsBedrockConverseOutputMessage` | out | The assistant message, including tool use blocks. |
| `CamelAwsBedrockStreamOutputMode` | in | Overrides `streamOutputMode`. |
| `CamelAwsBedrockStreamingChunkCount`, `CamelAwsBedrockStreamingCompletionReason`, `CamelAwsBedrockStreamingTokenCount` | out | Streaming results. |
| `CamelAwsBedrockStreamingChunkIndex` | out | Index of the chunk given to `streamingChunkProcessor`. |
| `CamelAwsBedrockGuardrailIdentifier`, `CamelAwsBedrockGuardrailVersion` | in | Guardrail. |
| `CamelAwsBedrockGuardrailSource` | in | `INPUT` (default) or `OUTPUT` for `applyGuardrail`. |
| `CamelAwsBedrockGuardrailAction` | out | Result of `applyGuardrail` (`NONE`, `GUARDRAIL_INTERVENED`). |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e BEDROCK_MODEL_ID \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/summarize.camel.yaml
```

## Common questions

### How do I give the model tools (function calling)?

Set `CamelAwsBedrockConverseToolConfig` to a map with `tools` (each a `toolSpec` with name,
description and JSON schema). When the model wants a tool, the stop reason is `tool_use` and
`CamelAwsBedrockConverseOutputMessage` holds the tool use block; run the tool in the route and send
the next turn with `CamelAwsBedrockConverseMessages`.

### How do I stream the answer?

Use `operation=converseStream` (or an `...Streaming` invoke operation). The response is decoded as it
arrives; with `streamingChunkProcessor=#myProcessor` each chunk is handed to your processor while the
rest is still streaming.

### Which model id should I use?

Any id enabled in your account and region, for example
`anthropic.claude-3-haiku-20240307-v1:0` or a cross-region inference profile such as
`us.anthropic.claude-3-5-sonnet-20241022-v2:0`.

## Related

- [AWS Bedrock Agent Runtime](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock-agent-runtime.html), [Azure OpenAI](https://pmsudhi.github.io/cameleer/docs/components/azure-openai.html)
- [AWS Comprehend](https://pmsudhi.github.io/cameleer/docs/components/aws2-comprehend.html), [AWS Textract](https://pmsudhi.github.io/cameleer/docs/components/aws2-textract.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Bedrock](https://camel.apache.org/components/next/aws-bedrock-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock-agent-runtime.html

# AWS Bedrock Agent Runtime component

> The `aws-bedrock-agent-runtime` component queries Amazon Bedrock knowledge bases (retrieve, retrieve-and-generate) and invokes Bedrock Agents.

**Scheme:** `aws-bedrock-agent-runtime:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Bedrock Agent Runtime](https://camel.apache.org/components/next/aws-bedrock-agent-runtime-component.html)

## When to use it

- Answer questions from your own documents (retrieval-augmented generation) inside a route.
- Fetch the most relevant passages for a query and pass them to another model or service.
- Call a Bedrock Agent (with its action groups and memory) from an integration, keeping the session
  id between calls.

## URI format

```text
aws-bedrock-agent-runtime://label[?options]
```

## Example

Answer questions from a queue with a knowledge base and a Claude model:

```yaml
- route:
    id: answer-questions
    from:
      uri: "aws2-sqs://questions?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - to: "aws-bedrock-agent-runtime://kb?region={{env:AWS_REGION:us-east-1}}&knowledgeBaseId={{env:KNOWLEDGE_BASE_ID:KB12345678}}&modelId=anthropic.claude-3-haiku-20240307-v1:0&operation=retrieveAndGenerate"
        - log: "answer (session ${header.CamelAwsBedrockAgentRuntimeSessionId}): ${body}"
        - to: "log:answers"
```

The body text is the question; the body after the call is the generated answer. The citations are
in the `CamelAwsBedrockAgentRuntimeCitations` header. A model id that is not an ARN is expanded to
`arn:aws:bedrock:{region}::foundation-model/{id}`.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://questions?region={{env:AWS_REGION:us-east-1}}")
        .to("aws-bedrock-agent-runtime://kb?region={{env:AWS_REGION:us-east-1}}&knowledgeBaseId={{env:KNOWLEDGE_BASE_ID:KB12345678}}&modelId=anthropic.claude-3-haiku-20240307-v1:0&operation=retrieveAndGenerate")
        .log("answer (session ${header.CamelAwsBedrockAgentRuntimeSessionId}): ${body}")
        .to("log:answers");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `retrieve` | `retrieve`, `retrieveAndGenerate` or `invokeAgent`. |
| `knowledgeBaseId` | | Knowledge base of `retrieve` and `retrieveAndGenerate`. |
| `modelId` | | Model of `retrieveAndGenerate` (id or ARN). |
| `agentId`, `agentAliasId` | | Agent of `invokeAgent`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsBedrockAgentRuntimeOperation` | in | Overrides `operation`. |
| `CamelAwsBedrockAgentRuntimeKnowledgeBaseId` | in | Overrides `knowledgeBaseId`. |
| `CamelAwsBedrockAgentRuntimeNumberOfResults` | in | Results of `retrieve`. |
| `CamelAwsBedrockAgentRuntimeSessionId` | in/out | Session of `retrieveAndGenerate` and `invokeAgent` (generated when missing). |
| `CamelAwsBedrockAgentRuntimeCitations` | out | Citations of the answer. |
| `CamelAwsBedrockAgentRuntimeAgentId`, `CamelAwsBedrockAgentRuntimeAgentAliasId` | in | Override the agent. |
| `CamelAwsBedrockAgentRuntimeEnableTrace`, `CamelAwsBedrockAgentRuntimeEndSession` | in | `invokeAgent` flags. |
| `CamelAwsBedrockAgentRuntimeSessionAttributes`, `CamelAwsBedrockAgentRuntimePromptSessionAttributes` | in | `invokeAgent` session state (maps). |
| `CamelAwsBedrockAgentRuntimeTraces`, `CamelAwsBedrockAgentRuntimeReturnControl` | out | Agent traces and return-control requests. |

`retrieve` returns a list of results (`{content: {text}, location, score}`) as the body.

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e KNOWLEDGE_BASE_ID \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/rag.camel.yaml
```

## Common questions

### How do I keep a conversation going?

Copy `CamelAwsBedrockAgentRuntimeSessionId` from the first answer into the header of the next
question (for example by keeping it per user in a cache).

### How do I invoke a Bedrock Agent?

Use `operation=invokeAgent&agentId=...&agentAliasId=...`. The agent's event stream is decoded: the
body is its answer; traces and return-control requests (when the agent asks your code to run an
action) are in headers.

### Retrieve only, without generation?

Use the default `operation=retrieve` and pass the passages to any model, for example
[aws-bedrock](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html) or [azure-openai](https://pmsudhi.github.io/cameleer/docs/components/azure-openai.html).

## Related

- [AWS Bedrock](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html), [Azure OpenAI](https://pmsudhi.github.io/cameleer/docs/components/azure-openai.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Bedrock Agent Runtime](https://camel.apache.org/components/next/aws-bedrock-agent-runtime-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws-cloudtrail.html

# AWS CloudTrail component

> The `aws-cloudtrail` component polls AWS CloudTrail for new management events (who did what, when) and turns each event into a message.

**Scheme:** `aws-cloudtrail:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** no ·
**Apache Camel:** [AWS CloudTrail](https://camel.apache.org/components/next/aws-cloudtrail-component.html)

## When to use it

- Security alerting: react when someone deletes a bucket, changes IAM policies or disables logging.
- Audit trails: copy selected API calls into a SIEM, a database or a ticket system.
- Trigger automation when a resource is created (tagging, compliance checks).

## URI format

```text
aws-cloudtrail://label[?options]
```

## Example

Watch S3 API calls and forward each event:

```yaml
- route:
    id: s3-audit
    from:
      uri: "aws-cloudtrail://s3-audit?region={{env:AWS_REGION:us-east-1}}&eventSource=s3.amazonaws.com&maxResults=10&delay=60000"
      steps:
        - convertBodyTo: String
        - log: "${header.CamelAwsCloudTrailEventUsername} called ${header.CamelAwsCloudTrailEventName}"
        - to: "log:s3-audit"
```

Each poll calls `LookupEvents` from the newest event already seen (all events of the trail on the
first poll), oldest first, and skips events already delivered. The body is the CloudTrail event
JSON document.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws-cloudtrail://s3-audit?region={{env:AWS_REGION:us-east-1}}&eventSource=s3.amazonaws.com&maxResults=10&delay=60000")
        .convert_body_to("String")
        .log("${header.CamelAwsCloudTrailEventUsername} called ${header.CamelAwsCloudTrailEventName}")
        .to("log:s3-audit");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `eventSource` | | Only events of this source, for example `s3.amazonaws.com` or `iam.amazonaws.com`. |
| `maxResults` | `1` | Events per poll. |

The consumer accepts the scheduled poll options (`delay` default 500 ms, `initialDelay`,
`scheduler.cron`, ...). CloudTrail limits `LookupEvents` to two calls per second per account, so a
longer `delay` is a good idea.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsCloudTrailEventId` | out | Event id. |
| `CamelAwsCloudTrailEventSource` | out | Event source (service). |
| `CamelAwsCloudTrailEventName` | out | API call, for example `DeleteBucket`. |
| `CamelAwsCloudTrailEventUsername` | out | User or role that made the call. |
| `CamelAwsCloudTrailEventTime` | out | Event time (epoch millis). |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/audit.camel.yaml
```

## Common questions

### How fast are events delivered?

CloudTrail itself delivers events to `LookupEvents` with a delay of several minutes; the consumer
adds at most one poll `delay`.

### How do I alert only on some calls?

Add a `filter` on `${header.CamelAwsCloudTrailEventName}`, for example `in 'DeleteBucket,PutBucketPolicy'`.

## Related

- [AWS Config](https://pmsudhi.github.io/cameleer/docs/components/aws-config.html), [AWS Secrets Manager](https://pmsudhi.github.io/cameleer/docs/components/aws-secrets-manager.html) (secret refresh uses CloudTrail)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS CloudTrail](https://camel.apache.org/components/next/aws-cloudtrail-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-cw.html

# AWS CloudWatch component

> The `aws2-cw` component publishes custom metrics to Amazon CloudWatch.

**Scheme:** `aws2-cw:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS CloudWatch](https://camel.apache.org/components/next/aws2-cw-component.html)

## When to use it

- Count business events (orders received, failed payments) and alarm on them.
- Publish sensor or gateway readings from edge devices as metrics.
- Track route health (queue depth, processing time) next to your AWS dashboards.

## URI format

```text
aws2-cw://namespace[?options]
```

## Example

Count every order received, with the order's sales channel as a dimension. The queue messages are
small JSON objects such as `{"channel":"web"}`; after `unmarshal` the map is used as the
dimensions:

```yaml
- route:
    id: order-metrics-by-channel
    from:
      uri: "aws2-sqs://orders?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: CamelAwsCwMetricDimensions
            simple: "${body}"
        - to: "aws2-cw://Shop/Orders?region={{env:AWS_REGION:us-east-1}}&name=OrdersReceived&value=1&unit=Count"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://orders?region={{env:AWS_REGION:us-east-1}}")
        .unmarshal("json")
        .set_header("CamelAwsCwMetricDimensions", simple("${body}"))
        .to("aws2-cw://Shop/Orders?region={{env:AWS_REGION:us-east-1}}&name=OrdersReceived&value=1&unit=Count");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `name` | | Metric name. |
| `value` | `1.0` | Metric value. |
| `unit` | `Count` | Unit (`Count`, `Seconds`, `Milliseconds`, `Bytes`, `Percent`, ...). |
| `timestamp` | now | Timestamp (epoch millis or ISO 8601). |

Each exchange is one `PutMetricData` call. An array body sends several data, each an object
`{name, value, unit, timestamp, dimensions}`.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsCwMetricNamespace` | in | Overrides the namespace. |
| `CamelAwsCwMetricName`, `CamelAwsCwMetricValue`, `CamelAwsCwMetricUnit`, `CamelAwsCwMetricTimestamp` | in | Override the options. |
| `CamelAwsCwMetricDimensions` | in | Dimensions (map name to value). |
| `CamelAwsCwMetricDimensionName`, `CamelAwsCwMetricDimensionValue` | in | A single dimension. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/metrics.camel.yaml
```

## Common questions

### How do I publish a measured value?

Set `CamelAwsCwMetricValue` from the message, for example `${header.durationMs}`, with
`unit=Milliseconds`.

### Can I read metrics or alarms?

No. The component only publishes metrics (`PutMetricData`), as in Apache Camel.

## Related

- [AWS CloudTrail](https://pmsudhi.github.io/cameleer/docs/components/aws-cloudtrail.html), [AWS SNS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sns.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS CloudWatch](https://camel.apache.org/components/next/aws2-cw-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-comprehend.html

# AWS Comprehend component

> The `aws2-comprehend` component analyses text with Amazon Comprehend: sentiment, language, entities, key phrases, PII, syntax, toxicity and custom classification.

**Scheme:** `aws2-comprehend:` · **Also:** `aws-comprehend:` (same component) · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** `camel-aws-comprehend` (see the [component list](https://camel.apache.org/components/next/index.html))

## When to use it

- Route customer messages by sentiment (escalate negative reviews).
- Detect and redact personal data (PII) before text is stored or sent to an LLM.
- Detect the language of a message before translating it.
- Give an AI agent a cheap, deterministic text-analysis tool next to the model.

## URI format

```text
aws2-comprehend://label?operation=...[&options]
```

## Example

Escalate negative product reviews:

```yaml
- route:
    id: review-sentiment
    from:
      uri: "aws2-sqs://reviews?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - setProperty:
            name: review
            simple: "${body}"
        - to: "aws2-comprehend://reviews?region={{env:AWS_REGION:us-east-1}}&operation=detectSentiment&languageCode=en"
        - choice:
            when:
              - simple: "${body} == 'NEGATIVE'"
                steps:
                  - setBody:
                      simple: "${exchangeProperty.review}"
                  - to: "aws2-sqs://escalations?region={{env:AWS_REGION:us-east-1}}&autoCreateQueue=true"
            otherwise:
              steps:
                - log: "review sentiment: ${body}"
```

`detectSentiment` replaces the body with the sentiment (`POSITIVE`, `NEGATIVE`, `NEUTRAL` or `MIXED`)
and sets the scores in `CamelAwsComprehendSentimentScore`, so the original text is kept in a property.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://reviews?region={{env:AWS_REGION:us-east-1}}")
        .set_property("review", simple("${body}"))
        .to("aws2-comprehend://reviews?region={{env:AWS_REGION:us-east-1}}&operation=detectSentiment&languageCode=en")
        .choice()
            .when(simple("${body} == 'NEGATIVE'"))
                .set_body(simple("${exchangeProperty.review}"))
                .to("aws2-sqs://escalations?region={{env:AWS_REGION:us-east-1}}&autoCreateQueue=true")
            .otherwise()
                .log("review sentiment: ${body}")
        .end();
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `detectSentiment` | `detectDominantLanguage`, `detectEntities`, `detectKeyPhrases`, `detectPiiEntities`, `detectSyntax`, `detectSentiment`, `containsPiiEntities`, `detectToxicContent`, `classifyDocument`. |
| `languageCode` | `en` | Language of the text. |
| `endpointArn` | | Custom classifier endpoint of `classifyDocument`. |

| operation | body after the call |
|---|---|
| `detectDominantLanguage` | list of `{LanguageCode, Score}`; the best one in `CamelAwsComprehendDetectedLanguage` |
| `detectEntities`, `detectKeyPhrases`, `detectPiiEntities`, `detectSyntax` | list of entities, key phrases or tokens |
| `detectSentiment` | the sentiment; scores in `CamelAwsComprehendSentimentScore` |
| `containsPiiEntities` | list of PII labels |
| `detectToxicContent` | result list |
| `classifyDocument` | list of classes |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsComprehendOperation` | in | Overrides `operation`. |
| `CamelAwsComprehendLanguageCode` | in | Overrides `languageCode`. |
| `CamelAwsComprehendEndpointArn` | in | Overrides `endpointArn`. |
| `CamelAwsComprehendDetectedLanguage` | out | Best language of `detectDominantLanguage`. |
| `CamelAwsComprehendSentimentScore` | out | Scores of `detectSentiment` (map). |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/reviews.camel.yaml
```

## Common questions

### How do I find personal data in a message?

Use `operation=detectPiiEntities`: the body becomes the list of entities with their type and
offsets, which you can use to mask the text. `containsPiiEntities` only tells which kinds are present.

### How do I detect the language and then translate?

Call `detectDominantLanguage`, keep the text in a property, and pass
`${header.CamelAwsComprehendDetectedLanguage}` as the source language to [aws2-translate](https://pmsudhi.github.io/cameleer/docs/components/aws2-translate.html).

## Related

- [AWS Translate](https://pmsudhi.github.io/cameleer/docs/components/aws2-translate.html), [AWS Bedrock](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html), [AWS Textract](https://pmsudhi.github.io/cameleer/docs/components/aws2-textract.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws-config.html

# AWS Config component

> The `aws-config` component manages AWS Config rules and conformance packs and reads their compliance results.

**Scheme:** `aws-config:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Config Service](https://camel.apache.org/components/next/aws-config-component.html)

## When to use it

- Enable managed compliance rules from an automation route.
- Report rule compliance on a schedule to a chat channel or ticket system.
- Deploy conformance packs as part of an environment setup.

## URI format

```text
aws-config://label?operation=...[&options]
```

## Example

Enable the managed rule that forbids public-read S3 buckets when the route starts:

```yaml
- route:
    id: enable-config-rule
    from:
      uri: "timer:config-rules?repeatCount=1"
      steps:
        - setHeader:
            name: CamelAwsConfigRuleName
            constant: s3-bucket-public-read-prohibited
        - setHeader:
            name: CamelAwsConfigRuleSourceIdentifier
            constant: S3_BUCKET_PUBLIC_READ_PROHIBITED
        - to: "aws-config://rules?region={{env:AWS_REGION:us-east-1}}&operation=putConfigRule"
        - log: "rule ${header.CamelAwsConfigRuleName} is in place"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:config-rules?repeatCount=1")
        .set_header("CamelAwsConfigRuleName", constant("s3-bucket-public-read-prohibited"))
        .set_header("CamelAwsConfigRuleSourceIdentifier", constant("S3_BUCKET_PUBLIC_READ_PROHIBITED"))
        .to("aws-config://rules?region={{env:AWS_REGION:us-east-1}}&operation=putConfigRule")
        .log("rule ${header.CamelAwsConfigRuleName} is in place");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | | Required: `putConfigRule`, `removeConfigRule`, `describeConfigRules`, `describeRuleCompliance`, `putConformancePack`, `removeConformancePack`, `describeConformancePackCompliance`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsConfigOperation` | in | Overrides `operation`. |
| `CamelAwsConfigRuleName` | in | Rule name (optional filter for the describe operations). |
| `CamelAwsConfigRuleSourceIdentifier` | in | Managed rule identifier or Lambda ARN of `putConfigRule`. |
| `CamelAwsConfigRuleSourceOwner` | in | `AWS` (default) or `CUSTOM_LAMBDA`. |
| `CamelAwsConfigRuleInputParameters` | in | Rule parameters (map or JSON text). |
| `CamelAwsConfigRuleScope` | in | Rule scope (map). |
| `CamelAwsConformancePackName` | in | Conformance pack. |
| `CamelAwsConformancePackTemplateBody` | in | Template of `putConformancePack` (otherwise the body). |

`describeConfigRules` returns the list of rules; `describeRuleCompliance` the list of
`ComplianceByConfigRule` entries; `describeConformancePackCompliance` the rule compliance list.

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/config.camel.yaml
```

## Common questions

### How do I get a daily compliance report?

Use a timer with `period=86400000`, call `operation=describeRuleCompliance`, and `split` the body
to send one message per non-compliant rule.

## Related

- [AWS CloudTrail](https://pmsudhi.github.io/cameleer/docs/components/aws-cloudtrail.html), [AWS IAM](https://pmsudhi.github.io/cameleer/docs/components/aws2-iam.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Config](https://camel.apache.org/components/next/aws-config-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-ddb.html

# AWS DynamoDB component

> The `aws2-ddb` component writes, reads, queries, scans and deletes items in Amazon DynamoDB tables, using plain maps instead of DynamoDB attribute values.

**Scheme:** `aws2-ddb:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS DynamoDB](https://camel.apache.org/components/next/aws2-ddb-component.html)

## When to use it

- Store orders, device state or session data from a route.
- Look up an item by key to enrich a message.
- Keep the memory of an AI agent (conversation state keyed by session id) in a serverless table.

For change data capture on a table, use [aws2-ddbstream](https://pmsudhi.github.io/cameleer/docs/components/aws2-ddbstream.html).

## URI format

```text
aws2-ddb://tableName[?options]
```

## Example

Save each JSON order from a queue as an item:

```yaml
- route:
    id: save-orders
    from:
      uri: "aws2-sqs://orders?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: CamelAwsDdbItem
            simple: "${body}"
        - to: "aws2-ddb://orders?region={{env:AWS_REGION:us-east-1}}&operation=PutItem"
        - log: "saved order ${header.CamelAwsDdbItem[orderId]}"
```

Items, keys and conditions are plain maps. Strings become `S`, numbers `N`, booleans `BOOL`, null
`NULL`, bytes `B`, lists `L` and maps `M`; results are converted back the same way.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://orders?region={{env:AWS_REGION:us-east-1}}")
        .unmarshal("json")
        .set_header("CamelAwsDdbItem", simple("${body}"))
        .to("aws2-ddb://orders?region={{env:AWS_REGION:us-east-1}}&operation=PutItem")
        .log("saved order ${header.CamelAwsDdbItem[orderId]}");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `PutItem` | `PutItem`, `GetItem`, `UpdateItem`, `DeleteItem`, `Query`, `Scan`, `BatchGetItems`, `DescribeTable`, `UpdateTable`, `DeleteTable`. The `CamelAwsDdbOperation` header overrides it. |
| `consistentRead` | `false` | Strongly consistent reads. |
| `enabledInitialDescribeTable` | `true` | Describe the table when the endpoint starts. |
| `keyAttributeName` | | When set and the table is missing at start, create it with this hash key. |
| `keyAttributeType` | `S` | Type of the created hash key. |
| `readCapacity`, `writeCapacity` | `1` | Provisioned throughput of the created table. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsDdbItem` | in | Item of `PutItem` (map). |
| `CamelAwsDdbKey` | in | Key of `GetItem`, `UpdateItem`, `DeleteItem` (map). |
| `CamelAwsDdbUpdateValues` | in | `UpdateItem`: attribute to new value (null deletes). |
| `CamelAwsDdbUpdateExpression`, `CamelAwsDdbConditionExpression`, `CamelAwsDdbKeyConditionExpression`, `CamelAwsDdbFilterExpression`, `CamelAwsDdbProjectionExpression` | in | Expressions. |
| `CamelAwsDdbExpressionAttributeNames`, `CamelAwsDdbExpressionAttributeValues` | in | `#name` and `:value` placeholders (plain values). `CamelAwsDdbFilterExpressionAttributeNames` / `...Values` are accepted too. |
| `CamelAwsDdbKeyConditions`, `CamelAwsDdbScanFilter` | in | Legacy `Query` / `Scan` conditions. |
| `CamelAwsDdbReturnValues`, `CamelAwsDdbConsistentRead`, `CamelAwsDdbAttributeNames`, `CamelAwsDdbIndexName`, `CamelAwsDdbLimit`, `CamelAwsDdbStartKey`, `CamelAwsDdbScanIndexForward` | in | Request settings. |
| `CamelAwsDdbBatchItems` | in | `BatchGetItems`: table to `{Keys, ConsistentRead, ProjectionExpression}`. |
| `CamelAwsDdbReadCapacity`, `CamelAwsDdbWriteCapacity`, `CamelAwsDdbStreamViewType` | in | `UpdateTable` (stream view type is a Cameleer extension). |
| `CamelAwsDdbTableName`, `CamelAwsDdbOperation` | in | Override the table and the operation. |
| `CamelAwsDdbAttributes`, `CamelAwsDdbItems`, `CamelAwsDdbCount`, `CamelAwsDdbScannedCount`, `CamelAwsDdbLastEvaluatedKey` | out | Results. |
| `CamelAwsDdbBatchResponse`, `CamelAwsDdbUnprocessedKeys` | out | `BatchGetItems` results. |
| `CamelAwsDdbTableStatus`, `CamelAwsDdbItemCount`, `CamelAwsDdbKeySchema`, `CamelAwsDdbProvisionedThroughput`, `CamelAwsDdbStreamArn` | out | Table information. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

## Common questions

### How do I read an item by key?

Set `CamelAwsDdbKey` to a map such as `{"orderId": "o-1001"}` and use `operation=GetItem`; the item
is returned in the `CamelAwsDdbAttributes` header.

### How do I increment a counter?

Use `UpdateItem` with `CamelAwsDdbUpdateExpression` = `SET hits = hits + :one` and
`CamelAwsDdbExpressionAttributeValues` = `{":one": 1}`.

### Does it work with DynamoDB Local?

Yes: `uriEndpointOverride=http://localhost:8000&overrideEndpoint=true`.

## Related

- [AWS DynamoDB Streams](https://pmsudhi.github.io/cameleer/docs/components/aws2-ddbstream.html), [AWS SQS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html)
- [Azure Cosmos DB](https://pmsudhi.github.io/cameleer/docs/components/azure-cosmosdb.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS DynamoDB](https://camel.apache.org/components/next/aws2-ddb-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-ddbstream.html

# AWS DynamoDB Streams component

> The `aws2-ddbstream` component consumes the change records (inserts, updates, deletes) of an Amazon DynamoDB table's stream.

**Scheme:** `aws2-ddbstream:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** no ·
**Apache Camel:** [AWS DynamoDB Streams](https://camel.apache.org/components/next/aws2-ddbstream-component.html)

## When to use it

- Change data capture: react to every new or changed item without polling the table.
- Replicate a table into a search index, a cache or another region.
- Trigger notifications or workflows when an item is inserted.

## URI format

```text
aws2-ddbstream://tableName[?options]
```

The stream must be enabled on the table. Its ARN is read with `DescribeTable`.

## Example

Forward every new order item to a queue:

```yaml
- route:
    id: new-orders-cdc
    from:
      uri: "aws2-ddbstream://orders?region={{env:AWS_REGION:us-east-1}}&streamIteratorType=FROM_START"
      steps:
        - filter:
            simple: "${header.CamelAwsDdbStreamEventName} == 'INSERT'"
            steps:
              - marshal:
                  json: {}
              - to: "aws2-sqs://new-orders?region={{env:AWS_REGION:us-east-1}}&autoCreateQueue=true"
```

The body is the stream record as a map: `eventID`, `eventName` (`INSERT`, `MODIFY`, `REMOVE`),
`eventSource`, `awsRegion` and `dynamodb` with `Keys`, `NewImage` and `OldImage` already converted to
plain maps, plus `SequenceNumber`, `SizeBytes` and `StreamViewType`.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-ddbstream://orders?region={{env:AWS_REGION:us-east-1}}&streamIteratorType=FROM_START")
        .filter(simple("${header.CamelAwsDdbStreamEventName} == 'INSERT'"))
        .marshal("json")
        .to("aws2-sqs://new-orders?region={{env:AWS_REGION:us-east-1}}&autoCreateQueue=true");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `streamIteratorType` | `FROM_LATEST` | `FROM_LATEST`, `FROM_START` or `FROM_SEQUENCE_NUMBER`. |
| `sequenceNumberProvider` | | Start sequence number for `FROM_SEQUENCE_NUMBER`. |
| `maxResultsPerRequest` | `100` | Records per `GetRecords` call. |

The consumer also accepts the scheduled poll options (`delay` default 500 ms, ...). New child
shards after a split are picked up and read from their start; expired iterators are re-created
after the last sequence number seen.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsDdbStreamEventName` | out | Cameleer: `INSERT`, `MODIFY` or `REMOVE`. |
| `CamelAwsDdbStreamSequenceNumber` | out | Cameleer: sequence number of the record. |
| `CamelAwsDdbStreamShardId` | out | Cameleer: shard of the record. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/cdc.camel.yaml
```

## Common questions

### Why do I get no records?

The table needs a stream (`StreamSpecification`), and with the default `FROM_LATEST` only changes
made after the consumer started are delivered. Use `FROM_START` to read the retained records.

### Which images are in the record?

That depends on the table's stream view type: `KEYS_ONLY`, `NEW_IMAGE`, `OLD_IMAGE` or
`NEW_AND_OLD_IMAGES`. You can change it with `aws2-ddb` `UpdateTable` and the
`CamelAwsDdbStreamViewType` header.

## Related

- [AWS DynamoDB](https://pmsudhi.github.io/cameleer/docs/components/aws2-ddb.html), [AWS Kinesis](https://pmsudhi.github.io/cameleer/docs/components/aws2-kinesis.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS DynamoDB Streams](https://camel.apache.org/components/next/aws2-ddbstream-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-ec2.html

# AWS EC2 component

> The `aws2-ec2` component starts, stops, creates, terminates, tags and describes Amazon EC2 instances.

**Scheme:** `aws2-ec2:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Elastic Compute Cloud (EC2)](https://camel.apache.org/components/next/aws2-ec2-component.html)

## When to use it

- Stop development instances every evening and start them in the morning.
- Launch worker instances when a queue grows, and terminate them afterwards.
- Tag instances or report their state from an operations route.

## URI format

```text
aws2-ec2://label?operation=...[&options]
```

## Example

Stop the development instances once a day (the timer fires at start and then every 24 hours):

```yaml
- route:
    id: stop-dev-instances
    from:
      uri: "timer:stop-dev?period=86400000"
      steps:
        - setHeader:
            name: CamelAwsEC2InstancesIds
            constant: "{{env:DEV_INSTANCE_IDS:i-0123456789abcdef0}}"
        - to: "aws2-ec2://ops?region={{env:AWS_REGION:us-east-1}}&operation=stopInstances"
        - log: "state changes: ${body}"
```

`CamelAwsEC2InstancesIds` takes a list or comma separated ids. The body after the call is the list
of state changes `{instanceId, previousState, currentState}`.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:stop-dev?period=86400000")
        .set_header("CamelAwsEC2InstancesIds", constant("{{env:DEV_INSTANCE_IDS:i-0123456789abcdef0}}"))
        .to("aws2-ec2://ops?region={{env:AWS_REGION:us-east-1}}&operation=stopInstances")
        .log("state changes: ${body}");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | | Required: `describeInstances`, `describeInstancesStatus`, `createAndRunInstances`, `startInstances`, `stopInstances`, `terminateInstances`, `rebootInstances`, `monitorInstances`, `unmonitorInstances`, `createTags`, `deleteTags`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsEC2Operation` | in | Overrides `operation`. |
| `CamelAwsEC2InstancesIds` | in | Instance ids (list or comma separated). |
| `CamelAwsEC2ImageId`, `CamelAwsEC2InstanceType` | in | AMI and type of `createAndRunInstances`. |
| `CamelAwsEC2InstanceMinCount`, `CamelAwsEC2InstanceMaxCount` | in | Instance count (default 1). |
| `CamelAwsEC2InstanceKeyPair`, `CamelAwsEC2InstanceMonitoring`, `CamelAwsEC2InstanceKernelId`, `CamelAwsEC2InstanceEbsOptimized` | in | Launch settings. |
| `CamelAwsEC2InstanceSecurityGroups` | in | Security group names or `sg-` ids. |
| `CamelAwsEC2InstancesClientToken`, `CamelAwsEC2InstancesPlacement`, `CamelAwsEC2SubnetId` | in | Idempotency token, availability zone, subnet. |
| `CamelAwsEC2InstancesTags` | in | Tags (map); for `deleteTags` a list of keys or a map. |

Bodies: lists of instances (`instanceId`, `imageId`, `instanceType`, `state`, `launchTime`,
`privateIpAddress`, `tags`, ...), of state changes or of monitoring states.

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e DEV_INSTANCE_IDS \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/stop-dev.camel.yaml
```

## Common questions

### How do I launch an instance?

Use `operation=createAndRunInstances` with `CamelAwsEC2ImageId` and `CamelAwsEC2InstanceType`
(plus subnet, security groups and tags as needed); the body is the list of new instances.

## Related

- [AWS ECS](https://pmsudhi.github.io/cameleer/docs/components/aws2-ecs.html), [AWS EKS](https://pmsudhi.github.io/cameleer/docs/components/aws2-eks.html), [AWS IAM](https://pmsudhi.github.io/cameleer/docs/components/aws2-iam.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS EC2](https://camel.apache.org/components/next/aws2-ec2-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-ecs.html

# AWS ECS component

> The `aws2-ecs` component lists, creates, describes and deletes Amazon ECS clusters.

**Scheme:** `aws2-ecs:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Elastic Container Service (ECS)](https://camel.apache.org/components/next/aws2-ecs-component.html)

## When to use it

- Report the ECS clusters of an account from an inventory route.
- Create or remove clusters as part of environment automation.

## URI format

```text
aws2-ecs://label?operation=...[&options]
```

## Example

List the clusters when the route starts:

```yaml
- route:
    id: ecs-inventory
    from:
      uri: "timer:ecs-inventory?repeatCount=1"
      steps:
        - to: "aws2-ecs://inventory?region={{env:AWS_REGION:us-east-1}}&operation=listClusters"
        - log: "ECS clusters: ${body}"
        - to: "log:ecs-clusters"
```

The body after `listClusters` is the list of cluster ARNs (all pages).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:ecs-inventory?repeatCount=1")
        .to("aws2-ecs://inventory?region={{env:AWS_REGION:us-east-1}}&operation=listClusters")
        .log("ECS clusters: ${body}")
        .to("log:ecs-clusters");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | | Required: `listClusters`, `createCluster`, `describeCluster`, `deleteCluster`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsECSOperation` | in | Overrides `operation`. |
| `CamelAwsECSMaxResults` | in | Page size of `listClusters`. |
| `CamelAwsECSClusterName` | in | Cluster of the create, describe and delete operations (body = the cluster map). |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/ecs.camel.yaml
```

## Common questions

### Can it run tasks or update services?

No. Like Apache Camel's component it covers cluster operations only.

## Related

- [AWS EKS](https://pmsudhi.github.io/cameleer/docs/components/aws2-eks.html), [AWS EC2](https://pmsudhi.github.io/cameleer/docs/components/aws2-ec2.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS ECS](https://camel.apache.org/components/next/aws2-ecs-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-eks.html

# AWS EKS component

> The `aws2-eks` component lists, creates, describes and deletes Amazon EKS (Kubernetes) clusters.

**Scheme:** `aws2-eks:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Elastic Kubernetes Service (EKS)](https://camel.apache.org/components/next/aws2-eks-component.html)

## When to use it

- Report the EKS clusters of an account from an inventory route.
- Create or delete clusters as part of environment automation.

## URI format

```text
aws2-eks://label?operation=...[&options]
```

## Example

List the cluster names when the route starts:

```yaml
- route:
    id: eks-inventory
    from:
      uri: "timer:eks-inventory?repeatCount=1"
      steps:
        - to: "aws2-eks://inventory?region={{env:AWS_REGION:us-east-1}}&operation=listClusters"
        - log: "EKS clusters: ${body}"
        - to: "log:eks-clusters"
```

The body after `listClusters` is the list of cluster names (all pages).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:eks-inventory?repeatCount=1")
        .to("aws2-eks://inventory?region={{env:AWS_REGION:us-east-1}}&operation=listClusters")
        .log("EKS clusters: ${body}")
        .to("log:eks-clusters");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | | Required: `listClusters`, `createCluster`, `describeCluster`, `deleteCluster`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsEKSOperation` | in | Overrides `operation`. |
| `CamelAwsEKSMaxResults` | in | Page size of `listClusters`. |
| `CamelAwsEKSClusterName` | in | Cluster of the create, describe and delete operations (body = the cluster map). |
| `CamelAwsEKSRoleARN` | in | Cluster role of `createCluster`. |
| `CamelAwsEKSVPCConfig` | in | `createCluster` network: map of `subnetIds` and `securityGroupIds`. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/eks.camel.yaml
```

## Common questions

### Can it deploy to Kubernetes?

No. It manages EKS clusters through the AWS API; it does not talk to the Kubernetes API server.

## Related

- [AWS ECS](https://pmsudhi.github.io/cameleer/docs/components/aws2-ecs.html), [AWS EC2](https://pmsudhi.github.io/cameleer/docs/components/aws2-ec2.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS EKS](https://camel.apache.org/components/next/aws2-eks-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-eventbridge.html

# AWS EventBridge component

> The `aws2-eventbridge` component publishes events to Amazon EventBridge buses and manages rules and targets.

**Scheme:** `aws2-eventbridge:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Eventbridge](https://camel.apache.org/components/next/aws2-eventbridge-component.html)

## When to use it

- Emit business events (order placed, device offline) that serverless consumers react to.
- Bridge events from on-premises systems, MQTT or Kafka into an AWS event-driven architecture.
- Create and wire rules from an automation route (`putRule`, `putTargets`).

## URI format

```text
aws2-eventbridge://eventbusNameOrArn[?options]
```

Use `default` for the account's default event bus.

## Example

Turn every order message into an `OrderPlaced` event on the default bus:

```yaml
- route:
    id: orders-to-eventbridge
    from:
      uri: "aws2-sqs://orders?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - setHeader:
            name: CamelAwsEventbridgeEventSource
            constant: com.example.shop
        - setHeader:
            name: CamelAwsEventbridgeEventDetailType
            constant: OrderPlaced
        - to: "aws2-eventbridge://default?region={{env:AWS_REGION:us-east-1}}&operation=putEvent"
        - log: "event entry ids: ${body}"
```

The body is the event detail and must be JSON.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://orders?region={{env:AWS_REGION:us-east-1}}")
        .set_header("CamelAwsEventbridgeEventSource", constant("com.example.shop"))
        .set_header("CamelAwsEventbridgeEventDetailType", constant("OrderPlaced"))
        .to("aws2-eventbridge://default?region={{env:AWS_REGION:us-east-1}}&operation=putEvent")
        .log("event entry ids: ${body}");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `putRule` | `putRule`, `putTargets`, `removeTargets`, `deleteRule`, `enableRule`, `disableRule`, `describeRule`, `listRules`, `listTargetsByRule`, `listRuleNamesByTarget`, `putEvent`. The `CamelAwsEventbridgeOperation` header overrides it. |
| `eventPatternFile` | | Event pattern of `putRule`, read from a file (`file:` prefix or a plain path). |

Note that the default operation is `putRule`, as in Apache Camel: set `operation=putEvent` to publish.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsEventbridgeOperation` | in | Overrides `operation`. |
| `CamelAwsEventbridgeEventSource` | in | Source of `putEvent`. |
| `CamelAwsEventbridgeEventDetailType` | in | Detail type of `putEvent`. |
| `CamelAwsEventbridgeEventResources` | in | Resource ARNs of `putEvent` (list or comma separated). |
| `CamelAwsEventbridgeFailedEntryCount` | out | Failed entries of `putEvent`. |
| `CamelAwsEventbridgeRuleName` | in | Rule of the rule operations. |
| `CamelAwsEventbridgeRuleNamePrefix` | in | Prefix of `listRules`. |
| `CamelAwsEventbridgeEventPattern` | in | Event pattern of `putRule`. |
| `CamelAwsEventbridgeTargets` | in | Targets of `putTargets` (list of `{id, arn, input}` maps). |
| `CamelAwsEventbridgeTargetsIds` | in | Ids of `removeTargets`. |
| `CamelAwsEventbridgeTargetArn` | in | Target of `listRuleNamesByTarget`. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/events.camel.yaml
```

## Common questions

### How do I consume EventBridge events in a route?

Create a rule whose target is an SQS queue, and consume the queue with [aws2-sqs](https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html). The
event arrives as the JSON envelope (`source`, `detail-type`, `detail`, ...).

### Why was my event not delivered?

Check `CamelAwsEventbridgeFailedEntryCount`, then the rule's event pattern: `source` and
`detail-type` must match exactly.

## Related

- [AWS SQS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html), [AWS SNS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sns.html), [AWS Lambda](https://pmsudhi.github.io/cameleer/docs/components/aws2-lambda.html)
- [Azure Event Grid](https://pmsudhi.github.io/cameleer/docs/components/azure-eventgrid.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS EventBridge](https://camel.apache.org/components/next/aws2-eventbridge-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-iam.html

# AWS IAM component

> The `aws2-iam` component manages AWS IAM users, groups, access keys, roles, policies and instance profiles.

**Scheme:** `aws2-iam:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Identity and Access Management (IAM)](https://camel.apache.org/components/next/aws2-iam-component.html)

## When to use it

- Onboard and offboard users from an HR or ticket system.
- Rotate access keys on a schedule.
- Create roles and attach policies as part of environment automation.

## URI format

```text
aws2-iam://label?operation=...[&options]
```

IAM is a global service: requests go to `iam.amazonaws.com`, signed for `us-east-1`.

## Example

Create an IAM user for every user name that arrives on an onboarding queue:

```yaml
- route:
    id: onboard-users
    from:
      uri: "aws2-sqs://onboarding?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - setHeader:
            name: CamelAwsIAMUsername
            simple: "${body}"
        - to: "aws2-iam://iam?operation=createUser"
        - log: "created IAM user ${body[userName]} (${body[arn]})"
```

The body after `createUser` is the user map `{userName, userId, arn, path, createDate}`.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://onboarding?region={{env:AWS_REGION:us-east-1}}")
        .set_header("CamelAwsIAMUsername", simple("${body}"))
        .to("aws2-iam://iam?operation=createUser")
        .log("created IAM user ${body[userName]} (${body[arn]})");
})?;
```

## Options

Common AWS options (credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | | Required. Users and keys: `createUser`, `getUser`, `deleteUser`, `listUsers`, `createAccessKey`, `listAccessKeys`, `deleteAccessKey`, `updateAccessKey`. Groups: `createGroup`, `getGroup`, `deleteGroup`, `listGroups`, `addUserToGroup`, `removeUserFromGroup`. Roles and policies: `createRole`, `getRole`, `deleteRole`, `listRoles`, `createPolicy`, `getPolicy`, `deletePolicy`, `listPolicies`, `attachUserPolicy`, `detachUserPolicy`, `listAttachedUserPolicies`, `attachGroupPolicy`, `detachGroupPolicy`, `listAttachedGroupPolicies`, `attachRolePolicy`, `detachRolePolicy`, `listAttachedRolePolicies`. Instance profiles: `createInstanceProfile`, `getInstanceProfile`, `deleteInstanceProfile`, `listInstanceProfiles`, `addRoleToInstanceProfile`, `removeRoleFromInstanceProfile`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsIAMOperation` | in | Overrides `operation`. |
| `CamelAwsIAMUsername` | in | User. |
| `CamelAwsIAMGroupName`, `CamelAwsIAMGroupPath` | in | Group. |
| `CamelAwsIAMAccessKeyID`, `CamelAwsIAMAccessKeyStatus` | in | Access key and its new status (`Active`, `Inactive`). |
| `CamelAwsIAMRoleName`, `CamelAwsIAMAssumeRolePolicyDocument` | in | Role and its trust policy. |
| `CamelAwsIAMPolicyName`, `CamelAwsIAMPolicyDocument`, `CamelAwsIAMPolicyArn` | in | Policy (the document may also be the body). |
| `CamelAwsIAMInstanceProfileName` | in | Instance profile. |
| `CamelAwsIAMPath`, `CamelAwsIAMDescription` | in | Path and description of roles. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/onboarding.camel.yaml
```

## Common questions

### How do I create an access key for a user?

Use `operation=createAccessKey` with `CamelAwsIAMUsername`. The body is
`{accessKeyId, secretAccessKey, status}`: store it right away, for example in
[Secrets Manager](https://pmsudhi.github.io/cameleer/docs/components/aws-secrets-manager.html), since the secret cannot be read again.

## Related

- [AWS STS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sts.html), [AWS Secrets Manager](https://pmsudhi.github.io/cameleer/docs/components/aws-secrets-manager.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS IAM](https://camel.apache.org/components/next/aws2-iam-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-kinesis.html

# AWS Kinesis component

> The `aws2-kinesis` component puts records into and consumes records from Amazon Kinesis Data Streams.

**Scheme:** `aws2-kinesis:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [AWS Kinesis](https://camel.apache.org/components/next/aws2-kinesis-component.html)

## When to use it

- Stream clickstream, telemetry or log records from devices and gateways into AWS.
- Consume a stream shard by shard and forward records to storage, Firehose or analytics.
- Replay a stream from the beginning (`TRIM_HORIZON`) or resume after a stored sequence number.

## URI format

```text
aws2-kinesis://streamName[?options]
```

## Example

Put a click event. The partition key header is required:

```yaml
- route:
    id: put-click
    from:
      uri: "timer:click?repeatCount=1"
      steps:
        - setBody:
            constant: '{"user":"user-42","page":"/pricing"}'
        - setHeader:
            name: CamelAwsKinesisPartitionKey
            constant: user-42
        - to: "aws2-kinesis://clickstream?region={{env:AWS_REGION:us-east-1}}"
        - log: "stored in ${header.CamelAwsKinesisShardId} at ${header.CamelAwsKinesisSequenceNumber}"
```

Consume the stream from its oldest record:

```yaml
- route:
    id: read-clickstream
    from:
      uri: "aws2-kinesis://clickstream?region={{env:AWS_REGION:us-east-1}}&iteratorType=TRIM_HORIZON&maxResultsPerRequest=100"
      steps:
        - convertBodyTo: String
        - log: "click from ${header.CamelAwsKinesisPartitionKey}: ${body}"
        - to: "log:clicks"
```

Record data arrives as bytes; `convertBodyTo: String` turns it into text.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-kinesis://clickstream?region={{env:AWS_REGION:us-east-1}}&iteratorType=TRIM_HORIZON&maxResultsPerRequest=100")
        .convert_body_to("String")
        .log("click from ${header.CamelAwsKinesisPartitionKey}: ${body}")
        .to("log:clicks");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `putRecord` | Cameleer: producer operation `putRecord`, `putRecords`, `createStream`, `describeStream`, `listShards`, `deleteStream`. An array body is sent with `PutRecords`. |
| `shardCount` | `1` | Shards of `createStream`. |
| `iteratorType` | `TRIM_HORIZON` | Consumer start: `TRIM_HORIZON`, `LATEST`, `AT_SEQUENCE_NUMBER`, `AFTER_SEQUENCE_NUMBER`, `AT_TIMESTAMP`. |
| `sequenceNumber` | | Start sequence number for the `*_SEQUENCE_NUMBER` iterator types. |
| `messageTimestamp` | | Start time (epoch millis) for `AT_TIMESTAMP`. |
| `maxResultsPerRequest` | `1` | Records read per shard and poll. |
| `shardId` | | Consume only this shard. |
| `shardClosed` | `ignore` | What to do at the end of a closed shard: `ignore` (logged), `silent` or `fail`. |
| `resumeStrategy` | | `#bean` of a `KinesisResumeStrategy` that stores and returns the last processed sequence number per shard. |
| `useKclConsumers` | `false` | KCL-style lease table consumers (`applicationName`, `workerIdentifier`, `failoverTimeMillis`); `kclDisableCloudwatchMetricsExport` is accepted, no metrics are published. |
| `enhancedFanOut` | `false` | Cameleer: enhanced fan-out (`SubscribeToShard` over HTTP/2) with consumer `consumerName` (default `camel-{stream}`). |
| `cborEnabled` | `false` | Use the CBOR flavour of the protocol (JSON otherwise). |

The consumer also accepts the scheduled poll options (`delay` default 500 ms, ...).

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsKinesisPartitionKey` | in/out | Partition key (required when putting a record). |
| `CamelAwsKinesisSequenceNumber` | in/out | Sequence number of the record (input: `SequenceNumberForOrdering`). |
| `CamelAwsKinesisShardId` | out | Shard of the record. |
| `CamelAwsKinesisApproximateArrivalTimestamp` | out | Arrival time. |
| `CamelMessageTimestamp` | out | Arrival time as the message timestamp. |
| `CamelAwsKinesisOperation` | in | Overrides `operation`. |
| `CamelAwsKinesisFailedRecordCount` | out | Failed records of `PutRecords`. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/clickstream.camel.yaml
```

## Common questions

### How do I put many records in one call?

Send an array body: each element is a record (or an object `{data, partitionKey}`); the body then
becomes the list of results and `CamelAwsKinesisFailedRecordCount` is set.

### How do I resume after a restart?

Bind a `KinesisResumeStrategy` (for example backed by a database) and set `resumeStrategy=#name`,
or use `useKclConsumers=true` to keep leases and checkpoints in a DynamoDB lease table.

### Does it support resharding?

Yes. Shards are listed on every poll, so child shards are picked up, and closed shards are handled
according to `shardClosed`.

## Related

- [AWS Kinesis Firehose](https://pmsudhi.github.io/cameleer/docs/components/aws2-kinesis-firehose.html), [AWS DynamoDB Streams](https://pmsudhi.github.io/cameleer/docs/components/aws2-ddbstream.html)
- [Azure Event Hubs](https://pmsudhi.github.io/cameleer/docs/components/azure-eventhubs.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Kinesis](https://camel.apache.org/components/next/aws2-kinesis-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-kinesis-firehose.html

# AWS Kinesis Firehose component

> The `aws2-kinesis-firehose` component sends records to Amazon Data Firehose (Kinesis Data Firehose) delivery streams, which deliver them to S3, Redshift, OpenSearch or HTTP endpoints.

**Scheme:** `aws2-kinesis-firehose:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Kinesis Firehose](https://camel.apache.org/components/next/aws2-kinesis-firehose-component.html)

## When to use it

- Ship application logs or metrics to S3 without managing batching and retries yourself.
- Load events into Redshift or OpenSearch through a delivery stream.
- Forward records consumed from Kafka, MQTT or SQS to a data lake.

## URI format

```text
aws2-kinesis-firehose://deliveryStreamName[?options]
```

## Example

Ship log lines from an SQS queue to a delivery stream:

```yaml
- route:
    id: logs-to-firehose
    from:
      uri: "aws2-sqs://app-logs?region={{env:AWS_REGION:us-east-1}}&maxMessagesPerPoll=10"
      steps:
        - to: "aws2-kinesis-firehose://app-logs-to-s3?region={{env:AWS_REGION:us-east-1}}"
        - log: "record ${header.CamelAwsKinesisFirehoseRecordId}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://app-logs?region={{env:AWS_REGION:us-east-1}}&maxMessagesPerPoll=10")
        .to("aws2-kinesis-firehose://app-logs-to-s3?region={{env:AWS_REGION:us-east-1}}")
        .log("record ${header.CamelAwsKinesisFirehoseRecordId}");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `sendRecord` | `sendRecord`, `putRecordBatch` (default for an array body), `createDeliveryStream` (DirectPut; a map body is merged into the request), `describeDeliveryStream`, `deleteDeliveryStream`. |

`cborEnabled` is accepted for compatibility and has no effect.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsKinesisFirehoseOperation` | in | Overrides `operation`. |
| `CamelAwsKinesisFirehoseRecordId` | out | Id of the record of `sendRecord`. |
| `CamelAwsKinesisFirehoseDeliveryStreamName` | in | Overrides the stream name. |
| `CamelAwsKinesisFirehoseFailedPutCount` | out | Failed records of `putRecordBatch`. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/logs.camel.yaml
```

## Common questions

### How do I send a batch?

Send an array body: one record per element, with `PutRecordBatch`. The body becomes the list of
record ids or errors, and `CamelAwsKinesisFirehoseFailedPutCount` is set.

### Does Firehose add newlines between records?

No. Firehose concatenates records as sent; add a newline to each body if the destination expects
one record per line.

## Related

- [AWS Kinesis](https://pmsudhi.github.io/cameleer/docs/components/aws2-kinesis.html), [AWS S3](https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Kinesis Firehose](https://camel.apache.org/components/next/aws2-kinesis-firehose-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-kms.html

# AWS KMS component

> The `aws2-kms` component manages AWS KMS keys and, as a Cameleer extension, encrypts and decrypts data with them.

**Scheme:** `aws2-kms:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Key Management Service (KMS)](https://camel.apache.org/components/next/aws2-kms-component.html)

## When to use it

- Encrypt sensitive payloads (personal data, documents) before they are stored or sent on.
- Create, enable, disable and schedule deletion of keys from automation routes.
- List keys for an inventory or audit report.

## URI format

```text
aws2-kms://label?operation=...[&options]
```

## Example

Encrypt every message of a queue with a KMS key before it is archived in S3:

```yaml
- route:
    id: encrypt-and-archive
    from:
      uri: "aws2-sqs://customer-records?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - setHeader:
            name: CamelAwsKMSKeyId
            constant: "{{env:KMS_KEY_ID:alias/customer-data}}"
        - setHeader:
            name: CamelAwsS3Key
            simple: "records/${header.CamelAwsSqsMessageId}.bin"
        - to: "aws2-kms://crypto?region={{env:AWS_REGION:us-east-1}}&operation=encrypt"
        - to: "aws2-s3://{{env:ARCHIVE_BUCKET:encrypted-archive}}?region={{env:AWS_REGION:us-east-1}}&autoCreateBucket=true"
```

`encrypt` replaces the body with the ciphertext blob (bytes). `decrypt` turns it back into the
plaintext and sets `CamelAwsKMSKeyId` to the key that was used. KMS encrypts at most 4 KB per call;
for larger data, encrypt a data key or use S3 server-side encryption (`useAwsKMS=true` on
[aws2-s3](https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html)).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://customer-records?region={{env:AWS_REGION:us-east-1}}")
        .set_header("CamelAwsKMSKeyId", constant("{{env:KMS_KEY_ID:alias/customer-data}}"))
        .set_header("CamelAwsS3Key", simple("records/${header.CamelAwsSqsMessageId}.bin"))
        .to("aws2-kms://crypto?region={{env:AWS_REGION:us-east-1}}&operation=encrypt")
        .to("aws2-s3://{{env:ARCHIVE_BUCKET:encrypted-archive}}?region={{env:AWS_REGION:us-east-1}}&autoCreateBucket=true");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | | Required: `listKeys`, `createKey`, `describeKey`, `enableKey`, `disableKey`, `scheduleKeyDeletion`, and the Cameleer operations `encrypt`, `decrypt`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsKMSOperation` | in | Overrides `operation`. |
| `CamelAwsKMSKeyId` | in/out | Key id, ARN or alias; set by `createKey` and `decrypt`. |
| `CamelAwsKMSDescription` | in | Description of `createKey`. |
| `CamelAwsKMSLimit` | in | Page size of `listKeys` (all pages are read). |
| `CamelAwsKMSPendingWindowInDays` | in | Waiting period of `scheduleKeyDeletion`. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e KMS_KEY_ID -e ARCHIVE_BUCKET \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/encrypt.camel.yaml
```

## Common questions

### Is `encrypt` available in Apache Camel?

No. Apache Camel's KMS component only manages keys; `encrypt` and `decrypt` are Cameleer
extensions with the same naming style.

## Related

- [AWS Secrets Manager](https://pmsudhi.github.io/cameleer/docs/components/aws-secrets-manager.html), [AWS S3](https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html), [Azure Key Vault](https://pmsudhi.github.io/cameleer/docs/components/azure-key-vault.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS KMS](https://camel.apache.org/components/next/aws2-kms-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-lambda.html

# AWS Lambda component

> The `aws2-lambda` component invokes AWS Lambda functions and manages functions, versions, aliases, tags and event source mappings.

**Scheme:** `aws2-lambda:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Lambda](https://camel.apache.org/components/next/aws2-lambda-component.html)

## When to use it

- Call serverless business logic from a route and continue with its result.
- Offload heavy work (image resizing, PDF rendering, model inference) from an edge device to Lambda.
- Expose a Lambda function to an AI agent as a tool behind a queue or an HTTP route.
- Deploy or update functions from a CI route (`createFunction`, `updateFunction`, `publishVersion`).

## URI format

```text
aws2-lambda://functionNameOrArn[?options]
```

## Example

Invoke a function for each message of a queue and send its response to another queue:

```yaml
- route:
    id: resize-images
    from:
      uri: "aws2-sqs://images-to-resize?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - to: "aws2-lambda://resize-image?region={{env:AWS_REGION:us-east-1}}&operation=invokeFunction"
        - to: "aws2-sqs://resized-images?region={{env:AWS_REGION:us-east-1}}&autoCreateQueue=true"
```

The body is sent as the payload; the response payload becomes the body. When the function fails,
the `CamelAwsLambdaFunctionError` header is set and the body holds the error document.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://images-to-resize?region={{env:AWS_REGION:us-east-1}}")
        .to("aws2-lambda://resize-image?region={{env:AWS_REGION:us-east-1}}&operation=invokeFunction")
        .to("aws2-sqs://resized-images?region={{env:AWS_REGION:us-east-1}}&autoCreateQueue=true");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `invokeFunction` | `invokeFunction`, `listFunctions`, `getFunction`, `deleteFunction`, `createFunction`, `updateFunction`, `createEventSourceMapping`, `deleteEventSourceMapping`, `listEventSourceMapping`, `listTags`, `tagResource`, `untagResource`, `publishVersion`, `listVersions`, `createAlias`, `deleteAlias`, `getAlias`, `listAliases`. The `CamelAwsLambdaOperation` header overrides it. |

Every operation except `invokeFunction` sets the response document (a map, or a list for the list
operations) as the body.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsLambdaOperation` | in | Overrides `operation`. |
| `CamelAwsLambdaInvocationType` | in | `RequestResponse` (default), `Event` (asynchronous) or `DryRun`. |
| `CamelAwsLambdaFunctionError` | out | Set when the function returned an error. |
| `CamelAwsLambdaStatusCode` | out | HTTP status of the invocation. |
| `CamelAwsLambdaS3Bucket`, `CamelAwsLambdaS3Key`, `CamelAwsLambdaS3ObjectVersion` | in | Code location of `createFunction` / `updateFunction` (otherwise the body is the zip). |
| `CamelAwsLambdaRole`, `CamelAwsLambdaRuntime`, `CamelAwsLambdaHandler`, `CamelAwsLambdaDescription`, `CamelAwsLambdaTargetArn`, `CamelAwsLambdaMemorySize`, `CamelAwsLambdaKMSKeyArn`, `CamelAwsLambdaPublish`, `CamelAwsLambdaTimeout`, `CamelAwsLambdaTracingConfig`, `CamelAwsLambdaEnvironmentVariables`, `CamelAwsLambdaTags`, `CamelAwsLambdaSecurityGroupIds`, `CamelAwsLambdaSubnetIds` | in | Function settings of `createFunction`. |
| `CamelAwsLambdaEventSourceArn`, `CamelAwsLambdaEventSourceBatchSize`, `CamelAwsLambdaEventSourceUuid`, `CamelAwsLambdaEventSourceStartingPosition` | in | Event source mappings (`StartingPosition` is a Cameleer extension). |
| `CamelAwsLambdaResourceArn`, `CamelAwsLambdaResourceTags`, `CamelAwsLambdaResourceTagKeys` | in | Tag operations. |
| `CamelAwsLambdaVersionDescription`, `CamelAwsLambdaFunctionVersion`, `CamelAwsLambdaAliasFunctionName`, `CamelAwsLambdaAliasFunctionDescription` | in | Versions and aliases. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/resize.camel.yaml
```

## Common questions

### How do I invoke a function asynchronously?

Set the header `CamelAwsLambdaInvocationType` to `Event`. Lambda queues the event and returns at once.

### How do I call a specific version or alias?

Use the qualified ARN as the path, for example `aws2-lambda://arn:aws:lambda:eu-west-1:123456789012:function:resize-image:prod`.

### How does the route know the function failed?

A function error does not throw: check `${header.CamelAwsLambdaFunctionError}` (for example in a
`choice`) and read the error document from the body.

## Related

- [AWS SQS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html), [AWS Step Functions](https://pmsudhi.github.io/cameleer/docs/components/aws2-step-functions.html), [AWS EventBridge](https://pmsudhi.github.io/cameleer/docs/components/aws2-eventbridge.html)
- [Azure Functions](https://pmsudhi.github.io/cameleer/docs/components/azure-functions.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Lambda](https://camel.apache.org/components/next/aws2-lambda-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-mq.html

# AWS MQ component

> The `aws2-mq` component lists, creates, describes, reboots and deletes Amazon MQ brokers (ActiveMQ and RabbitMQ).

**Scheme:** `aws2-mq:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS MQ](https://camel.apache.org/components/next/aws2-mq-component.html)

## When to use it

- Report the brokers of an account and their state.
- Provision or reboot brokers from an operations route.

To send and receive messages through an Amazon MQ broker, use the protocol components instead
(AMQP, STOMP, MQTT or JMS-style `amqp:`).

## URI format

```text
aws2-mq://label?operation=...[&options]
```

## Example

List the brokers when the route starts:

```yaml
- route:
    id: mq-inventory
    from:
      uri: "timer:mq-inventory?repeatCount=1"
      steps:
        - to: "aws2-mq://inventory?region={{env:AWS_REGION:us-east-1}}&operation=listBrokers"
        - log: "brokers: ${body}"
        - to: "log:brokers"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:mq-inventory?repeatCount=1")
        .to("aws2-mq://inventory?region={{env:AWS_REGION:us-east-1}}&operation=listBrokers")
        .log("brokers: ${body}")
        .to("log:brokers");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | | Required: `listBrokers`, `createBroker`, `describeBroker`, `deleteBroker`, `rebootBroker`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsMQOperation` | in | Overrides `operation`. |
| `CamelAwsMQMaxResults` | in | Page size of `listBrokers` (all pages are read). |
| `CamelAwsMQBrokerName` | in | Name of `createBroker`. |
| `CamelAwsMQBrokerEngine`, `CamelAwsMQBrokerEngineVersion` | in | Engine (default `ACTIVEMQ`) and version. |
| `CamelAwsMQBrokerInstanceType`, `CamelAwsMQBrokerDeploymentMode`, `CamelAwsMQBrokerPubliclyAccessible` | in | Broker settings (deployment mode default `SINGLE_INSTANCE`). |
| `CamelAwsMQBrokerUsers` | in | Users: list of `{username, password, consoleAccess}`. |
| `CamelAwsMQBrokerId` | in/out | Broker of describe, delete and reboot; set by `createBroker`. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/mq.camel.yaml
```

## Common questions

### What does `listBrokers` return?

The list of broker summaries (id, name, state, engine, deployment mode, ...) of all pages.

## Related

- [AWS MSK](https://pmsudhi.github.io/cameleer/docs/components/aws2-msk.html), [Azure Service Bus](https://pmsudhi.github.io/cameleer/docs/components/azure-servicebus.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS MQ](https://camel.apache.org/components/next/aws2-mq-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-msk.html

# AWS MSK component

> The `aws2-msk` component manages Amazon MSK (Managed Streaming for Apache Kafka) clusters, and Cameleer adds the `AWS_MSK_IAM` SASL mechanism so the `kafka` component can connect to MSK with IAM authentication.

**Scheme:** `aws2-msk:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Managed Streaming for Apache Kafka (MSK)](https://camel.apache.org/components/next/aws2-msk-component.html)

## When to use it

- Look up the bootstrap brokers of a cluster, then configure the `kafka` component with them.
- List, create or delete clusters from automation routes.
- Connect to MSK with IAM roles instead of SCRAM passwords (`saslMechanism=AWS_MSK_IAM` on `kafka:`).

## URI format

```text
aws2-msk://label?operation=...[&options]
```

## Example

Print the bootstrap broker strings of a cluster:

```yaml
- route:
    id: msk-bootstrap
    from:
      uri: "timer:msk?repeatCount=1"
      steps:
        - setHeader:
            name: CamelAwsMSKClusterArn
            constant: "{{env:MSK_CLUSTER_ARN:arn:aws:kafka:us-east-1:123456789012:cluster/events/abcd}}"
        - to: "aws2-msk://ops?region={{env:AWS_REGION:us-east-1}}&operation=getBootstrapBrokers"
        - log: "IAM bootstrap: ${body[bootstrapBrokerStringSaslIam]}"
        - to: "log:bootstrap"
```

`getBootstrapBrokers` (Cameleer) returns the map of broker strings (`bootstrapBrokerStringTls`,
`bootstrapBrokerStringSaslIam`, ...).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:msk?repeatCount=1")
        .set_header("CamelAwsMSKClusterArn", constant("{{env:MSK_CLUSTER_ARN:arn:aws:kafka:us-east-1:123456789012:cluster/events/abcd}}"))
        .to("aws2-msk://ops?region={{env:AWS_REGION:us-east-1}}&operation=getBootstrapBrokers")
        .log("IAM bootstrap: ${body[bootstrapBrokerStringSaslIam]}")
        .to("log:bootstrap");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | | Required: `listClusters`, `createCluster`, `describeCluster`, `deleteCluster`, and the Cameleer operation `getBootstrapBrokers`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsMSKOperation` | in | Overrides `operation`. |
| `CamelAwsMSKClusterFilter` | in | Name prefix of `listClusters`. |
| `CamelAwsMSKClusterName`, `CamelAwsMSKClusterKafkaVersion`, `CamelAwsMSKBrokerNodesNumber`, `CamelAwsMSKBrokerNodesGroupInfo` | in | `createCluster` settings (the group info is a map with `clientSubnets`, `instanceType`, ...). |
| `CamelAwsMSKClusterArn` | in/out | Cluster; set by `createCluster`. |
| `CamelAwsMSKClusterState` | out | Cluster state. |

## Connecting the kafka component with IAM

```text
kafka:orders?brokers=b-1.events.abcd.c2.kafka.eu-west-1.amazonaws.com:9098&securityProtocol=SASL_SSL&saslMechanism=AWS_MSK_IAM&saslJaasConfig=software.amazon.msk.auth.iam.IAMLoginModule required;
```

Credentials come from the default AWS chain (or `awsProfileName="..."` in the JAAS config); the region
from the broker host name or `AWS_REGION`.

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e MSK_CLUSTER_ARN \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/msk.camel.yaml
```

## Common questions

### Do I need the aws-msk-iam-auth jar?

No. The `AWS_MSK_IAM` mechanism is built into Cameleer; the JAAS line is accepted for compatibility
with Camel and Kafka client configurations.

## Related

- [AWS Kinesis](https://pmsudhi.github.io/cameleer/docs/components/aws2-kinesis.html), [AWS MQ](https://pmsudhi.github.io/cameleer/docs/components/aws2-mq.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS MSK](https://camel.apache.org/components/next/aws2-msk-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-polly.html

# AWS Polly component

> The `aws2-polly` component turns text into speech with Amazon Polly and manages lexicons and long speech synthesis tasks.

**Scheme:** `aws2-polly:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Polly](https://camel.apache.org/components/next/aws2-polly-component.html)

## When to use it

- Generate audio announcements (station displays, IVR prompts, kiosk messages) from text.
- Give a voice to an AI assistant's answers on a device.
- Convert long articles to audio files in S3 (`startSpeechSynthesisTask`).

## URI format

```text
aws2-polly://label[?options]
```

## Example

Turn announcements from a queue into MP3 files in S3:

```yaml
- route:
    id: announcements-to-audio
    from:
      uri: "aws2-sqs://announcements?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - setHeader:
            name: CamelAwsS3Key
            simple: "audio/${header.CamelAwsSqsMessageId}.mp3"
        - to: "aws2-polly://speech?region={{env:AWS_REGION:us-east-1}}&operation=synthesizeSpeech&voiceId=Joanna&outputFormat=mp3"
        - to: "aws2-s3://{{env:AUDIO_BUCKET:announcement-audio}}?region={{env:AWS_REGION:us-east-1}}&autoCreateBucket=true"
```

The body text is spoken; the body after the call is the audio bytes and `CamelAwsPollyContentType`
is set (for example `audio/mpeg`).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://announcements?region={{env:AWS_REGION:us-east-1}}")
        .set_header("CamelAwsS3Key", simple("audio/${header.CamelAwsSqsMessageId}.mp3"))
        .to("aws2-polly://speech?region={{env:AWS_REGION:us-east-1}}&operation=synthesizeSpeech&voiceId=Joanna&outputFormat=mp3")
        .to("aws2-s3://{{env:AUDIO_BUCKET:announcement-audio}}?region={{env:AWS_REGION:us-east-1}}&autoCreateBucket=true");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `synthesizeSpeech` | `synthesizeSpeech`, `describeVoices`, `listLexicons`, `getLexicon`, `putLexicon`, `deleteLexicon`, `startSpeechSynthesisTask`, `getSpeechSynthesisTask`. |
| `voiceId` | | Voice, for example `Joanna`. |
| `outputFormat` | `mp3` | `mp3`, `ogg_vorbis`, `pcm` or `json` (speech marks). |
| `textType` | `text` | `text` or `ssml`. |
| `engine` | | `standard`, `neural`, `long-form` or `generative`. |
| `sampleRate` | | Sample rate in Hz. |
| `languageCode` | | Language of bilingual voices. |
| `lexiconNames` | | Lexicons to apply. |

Each option can also be given per message with the matching `CamelAwsPolly*` header.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsPollyOperation` | in | Overrides `operation`. |
| `CamelAwsPollyVoiceId`, `CamelAwsPollyOutputFormat`, `CamelAwsPollyTextType`, `CamelAwsPollyEngine`, `CamelAwsPollySampleRate`, `CamelAwsPollyLanguageCode`, `CamelAwsPollyLexiconNames` | in | Override the options. |
| `CamelAwsPollyLexiconName` | in | Lexicon of the lexicon operations (`putLexicon`: the body is the PLS content). |
| `CamelAwsPollyS3Bucket`, `CamelAwsPollyS3KeyPrefix` | in | Output of `startSpeechSynthesisTask`. |
| `CamelAwsPollyTaskId` | in/out | Task of the synthesis task operations. |
| `CamelAwsPollyContentType` | out | Content type of the audio. |
| `CamelAwsPollyRequestCharacters` | out | Characters billed. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AUDIO_BUCKET \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/announcements.camel.yaml
```

## Common questions

### How do I control pronunciation and pauses?

Send SSML (`<speak>...<break time="1s"/>...</speak>`) with `textType=ssml`, or upload a lexicon with
`putLexicon` and reference it in `lexiconNames`.

### How do I convert a very long text?

Use `startSpeechSynthesisTask` with `CamelAwsPollyS3Bucket`: Polly writes the audio to S3 and you
poll the task with `getSpeechSynthesisTask`.

## Related

- [AWS Transcribe](https://pmsudhi.github.io/cameleer/docs/components/aws2-transcribe.html), [AWS Translate](https://pmsudhi.github.io/cameleer/docs/components/aws2-translate.html), [AWS S3](https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Polly](https://camel.apache.org/components/next/aws2-polly-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-redshift-data.html

# AWS Redshift Data component

> The `aws2-redshift-data` component runs SQL on Amazon Redshift clusters and Redshift Serverless workgroups through the Redshift Data API, without a database driver or connection pool.

**Scheme:** `aws2-redshift-data:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Redshift Data](https://camel.apache.org/components/next/aws2-redshift-data-component.html)

## When to use it

- Run scheduled reports or maintenance statements on a warehouse from a route.
- Load small batches of rows (`INSERT`) from events into Redshift.
- Query Redshift from serverless or edge environments where JDBC-style connections are impractical.

## URI format

```text
aws2-redshift-data://label?operation=...[&options]
```

## Example

Run a query, wait for it and fetch the rows:

```yaml
- route:
    id: sales-report
    from:
      uri: "timer:sales-report?repeatCount=1"
      steps:
        - setBody:
            constant: "SELECT * FROM sales"
        - to: "aws2-redshift-data://warehouse?region={{env:AWS_REGION:us-east-1}}&database=dev&clusterIdentifier={{env:REDSHIFT_CLUSTER:analytics-cluster}}&dbUser=reporter&operation=executeStatement&waitTimeout=60000"
        - to: "aws2-redshift-data://warehouse?region={{env:AWS_REGION:us-east-1}}&operation=getStatementResult"
        - log: "${header.CamelAwsRedshiftDataTotalNumRows} rows: ${body}"
        - to: "log:sales"
```

`executeStatement` returns the statement id (also in `CamelAwsRedshiftDataStatementId`); with
`waitTimeout` it waits until the statement finished. `getStatementResult` then returns the rows as a
list of maps (column name to value), all pages.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:sales-report?repeatCount=1")
        .set_body(constant("SELECT * FROM sales"))
        .to("aws2-redshift-data://warehouse?region={{env:AWS_REGION:us-east-1}}&database=dev&clusterIdentifier={{env:REDSHIFT_CLUSTER:analytics-cluster}}&dbUser=reporter&operation=executeStatement&waitTimeout=60000")
        .to("aws2-redshift-data://warehouse?region={{env:AWS_REGION:us-east-1}}&operation=getStatementResult")
        .log("${header.CamelAwsRedshiftDataTotalNumRows} rows: ${body}")
        .to("log:sales");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | | Required: `executeStatement`, `batchExecuteStatement`, `describeStatement`, `getStatementResult`, `cancelStatement`, `listStatements`, `listDatabases`, `listSchemas`, `listTables`, `describeTable`. |
| `database` | | Database. |
| `clusterIdentifier` | | Provisioned cluster (or use `workgroupName`). |
| `workgroupName` | | Redshift Serverless workgroup. |
| `secretArn` | | Secrets Manager secret with the database credentials. |
| `dbUser` | | Database user (temporary credentials, provisioned clusters). |
| `waitTimeout` | `0` | Cameleer: wait (ms) for `executeStatement` to finish; a failed statement raises an error. |
| `delay` | `200` | Status check interval while waiting (ms). |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsRedshiftDataOperation` | in | Overrides `operation`. |
| `CamelAwsRedshiftDataDatabase`, `CamelAwsRedshiftDataClusterIdentifier`, `CamelAwsRedshiftDataWorkgroupName`, `CamelAwsRedshiftDataSecretArn`, `CamelAwsRedshiftDataDbUser` | in | Override the connection options. |
| `CamelAwsRedshiftDataSql` | in | SQL (otherwise the body). |
| `CamelAwsRedshiftDataSqlStatementList` | in | Statements of `batchExecuteStatement` (or a list body). |
| `CamelAwsRedshiftDataStatementName`, `CamelAwsRedshiftDataParameters` | in | Statement name and parameters (list of `{name, value}`). |
| `CamelAwsRedshiftDataStatementId` | in/out | Statement. |
| `CamelAwsRedshiftDataStatus` | out | Statement status. |
| `CamelAwsRedshiftDataSchema`, `CamelAwsRedshiftDataTable` | in | Patterns of `listSchemas`, `listTables`, `describeTable`. |
| `CamelAwsRedshiftDataTotalNumRows` | out | Rows of `getStatementResult`. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e REDSHIFT_CLUSTER \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/sales.camel.yaml
```

## Common questions

### How do I pass parameters safely?

Use `:name` placeholders in the SQL and set `CamelAwsRedshiftDataParameters` to a list of
`{name, value}` maps instead of building SQL strings.

## Related

- [AWS Athena](https://pmsudhi.github.io/cameleer/docs/components/aws2-athena.html), [AWS Secrets Manager](https://pmsudhi.github.io/cameleer/docs/components/aws-secrets-manager.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Redshift Data](https://camel.apache.org/components/next/aws2-redshift-data-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-rekognition.html

# AWS Rekognition component

> The `aws2-rekognition` component analyses images and stored videos with Amazon Rekognition: labels, text, faces, moderation labels, celebrities and face collections.

**Scheme:** `aws2-rekognition:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** none (a Cameleer component that follows the naming of the other `aws2-*` components)

## When to use it

- Tag uploaded photos with labels for search.
- Moderate user images before they are published.
- Read text in images (licence plates, labels, signs) from edge cameras.
- Match faces against a collection (access control, photo organisation).

## URI format

```text
aws2-rekognition://label[?options]
```

The image is the S3 object named by `s3Bucket` / `s3Object` (options or headers) or the body bytes.

## Example

Label every photo uploaded to a bucket and queue the labels as JSON:

```yaml
- route:
    id: label-photos
    from:
      uri: "aws2-s3://uploaded-photos?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - setProperty:
            name: photo
            simple: "${header.CamelAwsS3Key}"
        - to: "aws2-rekognition://photos?region={{env:AWS_REGION:us-east-1}}&operation=detectLabels&minConfidence=80"
        - marshal:
            json: {}
        - setHeader:
            name: photo
            simple: "${exchangeProperty.photo}"
        - to: "aws2-sqs://photo-labels?region={{env:AWS_REGION:us-east-1}}&autoCreateQueue=true"
```

`detectLabels` returns the list of labels (`Name`, `Confidence`, ...) as the body. The photo key is
sent along as the `photo` message attribute.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-s3://uploaded-photos?region={{env:AWS_REGION:us-east-1}}")
        .set_property("photo", simple("${header.CamelAwsS3Key}"))
        .to("aws2-rekognition://photos?region={{env:AWS_REGION:us-east-1}}&operation=detectLabels&minConfidence=80")
        .marshal("json")
        .set_header("photo", simple("${exchangeProperty.photo}"))
        .to("aws2-sqs://photo-labels?region={{env:AWS_REGION:us-east-1}}&autoCreateQueue=true");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `detectLabels` | Images: `detectLabels`, `detectText`, `detectFaces`, `detectModerationLabels`, `recognizeCelebrities`, `compareFaces`. Collections: `createCollection`, `deleteCollection`, `describeCollection`, `listCollections`, `indexFaces`, `listFaces`, `deleteFaces`, `searchFaces`, `searchFacesByImage`. Stored video: `startLabelDetection`, `startFaceDetection`, `startTextDetection`, `startFaceSearch`, `getLabelDetection`, `getFaceDetection`, `getTextDetection`, `getFaceSearch`. |
| `s3Bucket`, `s3Object` | | Image or video in S3 (otherwise the body bytes). |
| `minConfidence` | | Minimum confidence of `detectLabels`. |
| `maxLabels` | | Maximum labels of `detectLabels`. |
| `collectionId` | | Face collection. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsRekognitionOperation` | in | Overrides `operation`. |
| `CamelAwsRekognitionS3Bucket`, `CamelAwsRekognitionS3Object` | in | Image or video in S3. |
| `CamelAwsRekognitionMaxLabels`, `CamelAwsRekognitionMinConfidence` | in | `detectLabels` limits. |
| `CamelAwsRekognitionCollectionId` | in | Face collection. |
| `CamelAwsRekognitionExternalImageId`, `CamelAwsRekognitionMaxFaces` | in | `indexFaces`, searches. |
| `CamelAwsRekognitionFaceId`, `CamelAwsRekognitionFaceIds`, `CamelAwsRekognitionFaceMatchThreshold` | in | Face searches and deletion. |
| `CamelAwsRekognitionTargetS3Bucket`, `CamelAwsRekognitionTargetS3Object`, `CamelAwsRekognitionTargetImage` | in | Target image of `compareFaces`. |
| `CamelAwsRekognitionUnmatchedFaces` | out | Unmatched faces of `compareFaces`. |
| `CamelAwsRekognitionJobId`, `CamelAwsRekognitionJobStatus` | in/out | Stored video jobs. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/photos.camel.yaml
```

## Common questions

### How do I analyse an image without downloading it?

Pass the S3 location with `s3Bucket` and `s3Object` (or the headers); Rekognition reads it directly.
With the S3 consumer, `ignoreBody=true` avoids downloading the image.

### How do I analyse a video?

Start a job (`startLabelDetection` with the video in S3), keep `CamelAwsRekognitionJobId`, then call
the matching `get...` operation until `CamelAwsRekognitionJobStatus` is `SUCCEEDED`.

## Related

- [AWS S3](https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html), [AWS Textract](https://pmsudhi.github.io/cameleer/docs/components/aws2-textract.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html

# AWS S3 component

> The `aws2-s3` component uploads, downloads, lists, copies and deletes objects in Amazon S3 buckets, and polls a bucket for new objects.

**Scheme:** `aws2-s3:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [AWS S3 Storage Service](https://camel.apache.org/components/next/aws2-s3-component.html)

## When to use it

- Archive files, reports or message payloads to S3.
- Read files that partners or other systems drop into a bucket, then move or delete them.
- Hand large documents to other services through presigned download or upload links.
- Collect sensor data on an edge device and upload it in multipart batches (`streamingUploadMode`).

## URI format

```text
aws2-s3://bucketNameOrArn[?options]
```

## Example

Upload a report. The object key comes from the `CamelAwsS3Key` header (or the `keyName` option):

```yaml
- route:
    id: upload-report
    from:
      uri: "timer:daily-report?repeatCount=1"
      steps:
        - setBody:
            constant: "region,total;eu,42;us,17"
        - setHeader:
            name: CamelAwsS3Key
            constant: reports/daily.csv
        - setHeader:
            name: CamelAwsS3ContentType
            constant: text/csv
        - to: "aws2-s3://{{env:S3_BUCKET:my-reports}}?region={{env:AWS_REGION:us-east-1}}&autoCreateBucket=true"
        - log: "uploaded s3://{{env:S3_BUCKET:my-reports}}/${header.CamelAwsS3Key}"
```

Poll a bucket for invoices. Each object becomes one exchange; after successful processing it is
copied to `processed-invoices` and deleted from the source bucket:

```yaml
- route:
    id: invoices-from-s3
    from:
      uri: "aws2-s3://incoming-invoices?region={{env:AWS_REGION:us-east-1}}&prefix=invoices/&moveAfterRead=true&destinationBucket=processed-invoices"
      steps:
        - log: "received ${header.CamelAwsS3Key} (${header.CamelAwsS3ContentLength} bytes)"
        - to: "log:invoices"
```

Credentials come from the default AWS chain; see [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-s3://incoming-invoices?region={{env:AWS_REGION:us-east-1}}&prefix=invoices/&moveAfterRead=true&destinationBucket=processed-invoices")
        .log("received ${header.CamelAwsS3Key} (${header.CamelAwsS3ContentLength} bytes)")
        .to("log:invoices");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `putObject` | Producer operation: `putObject`, `getObject`, `getObjectRange`, `headObject`, `listObjects`, `deleteObject`, `deleteObjects`, `copyObject`, `listBuckets`, `createBucket`, `deleteBucket`, `headBucket`, `createDownloadLink`, `createUploadLink`, `restoreObject`, `getObjectTagging`, `putObjectTagging`, `deleteObjectTagging`, `getObjectAcl`, `putObjectAcl`, and the Cameleer operations `putObjectRetention`, `getObjectRetention`, `putObjectLegalHold`, `getObjectLegalHold`, `putBucketVersioning`, `getBucketVersioning`, `listObjectVersions`. |
| `keyName` | | Object key (the `CamelAwsS3Key` header wins). |
| `prefix` | | Consumer and `listObjects`: only keys with this prefix. |
| `delimiter` | | Delimiter of the listing. |
| `fileName` | | Consumer: poll this single object. |
| `maxMessagesPerPoll` | `10` | Consumer: objects per poll. |
| `includeBody` | `true` | Consumer: download the object content. |
| `ignoreBody` | `false` | Consumer: do not download at all (HEAD only, empty body). |
| `includeFolders` | `true` | Consumer: also emit folder placeholder objects. |
| `deleteAfterRead` | `true` | Consumer: delete objects after successful processing. |
| `moveAfterRead` | `false` | Consumer: copy objects to `destinationBucket` first. |
| `destinationBucket`, `destinationBucketPrefix`, `destinationBucketSuffix` | | Target of `moveAfterRead`. |
| `localDirectory` | | Cameleer: consumer streams each object to `{localDirectory}/{key}` without buffering (body = path). |
| `autoCreateBucket` | `false` | Create the bucket when it does not exist. |
| `forcePathStyle` | `false` | Path-style addressing (virtual-host style otherwise; path style is used with an endpoint override). |
| `storageClass` | | Storage class of uploads. |
| `conditionalWritesEnabled` | `false` | Send `If-None-Match: *` so an existing object is never overwritten. |
| `multiPartUpload` | `false` | Upload bodies larger than `partSize` with a multipart upload. |
| `partSize` | 25 MiB | Part size of multipart uploads. |
| `streamingUploadMode` | `false` | Aggregate the bodies of many exchanges into multipart objects. |
| `batchMessageNumber`, `batchSize`, `streamingUploadTimeout` | `10`, `1000000` | When a streaming upload object is completed. |
| `namingStrategy` | `progressive` | Streaming upload object names: `progressive` or `random`. |
| `restartingPolicy` | `override` | Streaming upload: `override` or `lastPart`. |
| `useAwsKMS`, `awsKMSKeyId` | `false` | SSE-KMS encryption of uploads. |
| `useSSES3` | `false` | SSE-S3 encryption. |
| `useCustomerKey`, `customerKeyId`, `customerKeyMD5`, `customerAlgorithm` | `false` | SSE-C encryption with your own key. |

The consumer also accepts the scheduled poll options (`delay` default 500 ms, `initialDelay`,
`greedy`, `scheduler.cron`, ...).

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsS3Key` | in/out | Object key. |
| `CamelAwsS3BucketName` | in/out | Bucket name. |
| `CamelAwsS3Operation` | in | Overrides `operation`. |
| `CamelAwsS3ContentType`, `CamelAwsS3ContentLength` | in/out | Content type and length. |
| `CamelAwsS3ETag`, `CamelAwsS3LastModified`, `CamelAwsS3VersionId` | out | Object metadata (`CamelAwsS3VersionId` is also an input of get, head and delete). |
| `CamelAwsS3Metadata` | in/out | User metadata (map). |
| `CamelAwsS3BucketDestinationName`, `CamelAwsS3DestinationKey` | in | Target of `copyObject`. |
| `CamelAwsS3Prefix`, `CamelAwsS3Delimiter` | in | Listing filters. |
| `CamelAwsS3StorageClass` | in | Storage class. |
| `CamelAwsS3RangeStart`, `CamelAwsS3RangeEnd` | in | Byte range of `getObjectRange`. |
| `CamelAwsS3DownloadLinkExpirationTime`, `CamelAwsS3UploadLinkExpirationTime` | in | Expiry (millis) of presigned links. |
| `CamelAwsS3KeysToDelete`, `CamelAwsS3DeleteErrors` | in/out | Keys of `deleteObjects` and its failures. |
| `CamelAwsS3CannedAcl`, `CamelAwsS3ServerSideEncryption`, `CamelAwsS3ContentDisposition`, `CamelAwsS3ContentEncoding`, `CamelAwsS3ContentControl`, `CamelAwsS3ObjectTags`, `CamelAwsS3Headers` | in | Upload settings. |
| `CamelAwsS3ObjectLockMode`, `CamelAwsS3ObjectLockRetainUntilDate`, `CamelAwsS3ObjectLockLegalHoldStatus`, `CamelAwsS3BypassGovernanceRetention`, `CamelAwsS3VersioningStatus` | in | Object lock and versioning. |
| `CamelAwsS3RestoreDays`, `CamelAwsS3RestoreTier` | in | `restoreObject`. |
| `CamelAwsS3SourceFile` | in | Cameleer: upload this local file without loading it in memory. |
| `CamelAwsS3DownloadFile` | in | Cameleer: `getObject` streams the object into this local file. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e S3_BUCKET \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/s3.camel.yaml
```

## Common questions

### How do I upload a large file without loading it in memory?

Set the `CamelAwsS3SourceFile` header to the file path. With `multiPartUpload=true` the file is
uploaded one part at a time; otherwise it is streamed in a single PUT.

### How do I create a presigned download link?

Use `operation=createDownloadLink` with `CamelAwsS3Key`; the body becomes the URL, valid for
`CamelAwsS3DownloadLinkExpirationTime` milliseconds.

### How do I keep the objects in the bucket after reading them?

Set `deleteAfterRead=false`. The consumer then sees the same objects again on every poll, so
usually you combine it with an idempotent consumer or move the objects with `moveAfterRead`.

### Does it work with MinIO or LocalStack?

Yes: `uriEndpointOverride=http://localhost:9000&overrideEndpoint=true` (path-style addressing is used
automatically with an override).

## Related

- [AWS SQS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html), [AWS Textract](https://pmsudhi.github.io/cameleer/docs/components/aws2-textract.html), [AWS Rekognition](https://pmsudhi.github.io/cameleer/docs/components/aws2-rekognition.html)
- [Azure Storage Blob](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-blob.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS S3](https://camel.apache.org/components/next/aws2-s3-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws-secrets-manager.html

# AWS Secrets Manager component

> The `aws-secrets-manager` component creates, reads, updates, rotates and deletes secrets in AWS Secrets Manager, and the `{{aws:...}}` placeholder puts secrets into routes and endpoint options.

**Scheme:** `aws-secrets-manager:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Secrets Manager](https://camel.apache.org/components/next/aws-secrets-manager-component.html)

## When to use it

- Keep passwords, API keys and tokens out of route files: reference them as `{{aws:name}}`.
- Store credentials generated by a route (for example a partner token) as a secret.
- Restart routes automatically when a secret is rotated (secret refresh).

## URI format

```text
aws-secrets-manager://label?operation=...[&options]
```

## Example

Use a secret in a route with the `{{aws:...}}` placeholder. It is resolved when the route starts:

```yaml
- route:
    id: call-partner-api
    from:
      uri: "timer:partner-sync?repeatCount=1"
      steps:
        - setHeader:
            name: Authorization
            constant: "Bearer {{aws:partner-api/token}}"
        - to: "log:partner-api"
```

The placeholder reads its configuration from these properties (for example in
`application.properties`):

```properties
camel.vault.aws.region=eu-west-1
camel.vault.aws.defaultCredentialsProvider=true
```

Create a secret:

```yaml
- route:
    id: store-partner-token
    from:
      uri: "timer:store-token?repeatCount=1"
      steps:
        - setHeader:
            name: CamelAwsSecretsManagerSecretName
            constant: partner-api
        - setHeader:
            name: CamelAwsSecretsManagerSecretDescription
            constant: Token of the partner API
        - setBody:
            constant: '{"token":"{{env:PARTNER_TOKEN:}}"}'
        - to: "aws-secrets-manager://secrets?region={{env:AWS_REGION:us-east-1}}&operation=createSecret"
        - log: "created ${body} (version ${header.CamelAwsSecretsManagerSecretVersionId})"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:store-token?repeatCount=1")
        .set_header("CamelAwsSecretsManagerSecretName", constant("partner-api"))
        .set_header("CamelAwsSecretsManagerSecretDescription", constant("Token of the partner API"))
        .set_body(constant(r#"{"token":"{{env:PARTNER_TOKEN:}}"}"#))
        .to("aws-secrets-manager://secrets?region={{env:AWS_REGION:us-east-1}}&operation=createSecret")
        .log("created ${body} (version ${header.CamelAwsSecretsManagerSecretVersionId})");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `getSecret` | `createSecret`, `getSecret`, `describeSecret`, `listSecrets`, `deleteSecret`, `restoreSecret`, `updateSecret`, `rotateSecret`, `replicateSecretToRegions`. |
| `binaryPayload` | `false` | `createSecret`: store a bytes body as `SecretBinary`. |

### The `{{aws:...}}` placeholder

| syntax | result |
|---|---|
| `{{aws:name}}` | The secret string. |
| `{{aws:name/field}}` | A field of a JSON secret, for example `{{aws:prod-db/password}}` reads `password` of the JSON secret `prod-db`. |
| `{{aws:name@version}}` | A specific version. |
| `{{aws:name/field:default}}` | A default when the secret or field does not exist. |

The secret name ends at the first `/`, as in Apache Camel: a secret whose name contains `/` (such as
`prod/db`) cannot be read with the placeholder. Use names like `prod-db` and JSON fields instead.

Configuration properties: `camel.vault.aws.accessKey`, `secretKey`, `region`,
`defaultCredentialsProvider`, `profileCredentialsProvider`, `profileName`, `uriEndpointOverride`,
`overrideEndpoint`. Secret refresh: `camel.vault.aws.refreshEnabled=true`,
`camel.vault.aws.refreshPeriod` (ms, default 30000) and `camel.vault.aws.secrets` (names or `*`
patterns; empty = the secrets used through placeholders). Changes are detected through CloudTrail
events (`PutSecretValue`, `UpdateSecret`, `RotateSecret`, ...) and restart the started routes.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsSecretsManagerOperation` | in | Overrides `operation`. |
| `CamelAwsSecretsManagerSecretName` | in | Name of `createSecret`. |
| `CamelAwsSecretsManagerSecretDescription` | in | Description of `createSecret`. |
| `CamelAwsSecretsManagerSecretId` | in | Name or ARN for the other operations. |
| `CamelAwsSecretsManagerSecretVersionId` | in/out | Version to read; the new version after create. |
| `CamelAwsSecretsManagerForceDeletion` | in | `deleteSecret` without recovery window. |
| `CamelAwsSecretsManagerLambdaRotationFunctionArn`, `CamelAwsSecretsManagerRotateImmediately` | in | `rotateSecret`. |
| `CamelAwsSecretsManagerSecretReplicationRegions` | in | `replicateSecretToRegions`. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/partner.camel.yaml \
  --properties /routes/application.properties
```

`--prop camel.vault.aws.region=eu-west-1` sets a single property on the command line.

## Common questions

### How do I put a database password into an endpoint option?

Write it in the uri, for example `password=RAW({{aws:prod-db/password}})`. `RAW(...)` keeps special
characters of the password intact.

### What does `getSecret` return for binary secrets?

The bytes of `SecretBinary`; string secrets are returned as text.

## Related

- [Azure Key Vault](https://pmsudhi.github.io/cameleer/docs/components/azure-key-vault.html) (`{{azure:...}}`)
- [AWS CloudTrail](https://pmsudhi.github.io/cameleer/docs/components/aws-cloudtrail.html), [AWS KMS](https://pmsudhi.github.io/cameleer/docs/components/aws2-kms.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Secrets Manager](https://camel.apache.org/components/next/aws-secrets-manager-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-ses.html

# AWS SES component

> The `aws2-ses` component sends e-mails (text, HTML or raw MIME) with Amazon Simple Email Service.

**Scheme:** `aws2-ses:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Simple Email Service (SES)](https://camel.apache.org/components/next/aws2-ses-component.html)

## When to use it

- Send notifications and alerts from routes without running an SMTP server.
- Send transactional mails (order confirmations, password resets) from events.
- Forward complete MIME messages built by another system (`SendRawEmail`).

## URI format

```text
aws2-ses://from@example.com[?options]
```

The path is the sender address; it must be verified in SES.

## Example

Mail every alert of a queue to the on-call address:

```yaml
- route:
    id: mail-alerts
    from:
      uri: "aws2-sqs://alerts?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - to: "aws2-ses://{{env:ALERT_SENDER:alerts@example.com}}?region={{env:AWS_REGION:us-east-1}}&to={{env:ONCALL_ADDRESS:oncall@example.com}}&subject=Production alert"
        - log: "sent mail ${header.CamelAwsSesMessageId}"
```

A text body is sent with `SendEmail` (as HTML with `htmlEmail=true`); a bytes body is sent as a
complete MIME message with `SendRawEmail`.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://alerts?region={{env:AWS_REGION:us-east-1}}")
        .to("aws2-ses://{{env:ALERT_SENDER:alerts@example.com}}?region={{env:AWS_REGION:us-east-1}}&to={{env:ONCALL_ADDRESS:oncall@example.com}}&subject=Production alert")
        .log("sent mail ${header.CamelAwsSesMessageId}");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `to`, `cc`, `bcc` | | Recipients (comma separated). |
| `subject` | | Subject. |
| `replyToAddresses` | | Reply-to addresses. |
| `returnPath` | | Bounce address. |
| `configurationSet` | | SES configuration set. |
| `htmlEmail` | `false` | Send the body as HTML. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsSesFrom` | in | Overrides the sender. |
| `CamelAwsSesTo`, `CamelAwsSesCc`, `CamelAwsSesBcc` | in | Recipients (list or comma separated). |
| `CamelAwsSesSubject`, `CamelAwsSesReturnPath`, `CamelAwsSesReplyToAddresses`, `CamelAwsSesConfigurationSet` | in | Override the options. |
| `CamelAwsSesHtmlEmail` | in | Send as HTML. |
| `CamelAwsSesMessageId` | out | Id of the sent mail. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e ALERT_SENDER -e ONCALL_ADDRESS \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/alerts.camel.yaml
```

## Common questions

### How do I send attachments?

Build a MIME message (for example with the `mime-multipart` data format) and send it as bytes:
it then goes out with `SendRawEmail`.

### Which SES API is used?

SES v1 (`SendEmail` / `SendRawEmail` over the Query API), as in Apache Camel's component.

## Related

- [AWS SNS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sns.html), [AWS SQS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS SES](https://camel.apache.org/components/next/aws2-ses-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-sns.html

# AWS SNS component

> The `aws2-sns` component publishes messages to Amazon SNS topics, including FIFO topics and batches.

**Scheme:** `aws2-sns:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Simple Notification System (SNS)](https://camel.apache.org/components/next/aws2-sns-component.html)

## When to use it

- Fan out an event to many subscribers (SQS queues, Lambda functions, e-mail, SMS, HTTPS).
- Send operational alerts from a route to an on-call topic.
- Connect a Cameleer route on an edge device to a serverless backend that subscribes to the topic.

## URI format

```text
aws2-sns://topicNameOrArn[?options]
```

When the path is a topic ARN it is used as is. Otherwise the topic is looked up by name
(`ListTopics`) or created with `autoCreateTopic=true`.

## Example

Forward alerts from an SQS queue to an SNS topic with a subject:

```yaml
- route:
    id: alerts-to-sns
    from:
      uri: "aws2-sqs://alerts?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - to: "aws2-sns://ops-alerts?region={{env:AWS_REGION:us-east-1}}&subject=Ops alert&autoCreateTopic=true"
        - log: "published ${header.CamelAwsSnsMessageId}"
```

Credentials come from the default AWS chain; see [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://alerts?region={{env:AWS_REGION:us-east-1}}")
        .to("aws2-sns://ops-alerts?region={{env:AWS_REGION:us-east-1}}&subject=Ops alert&autoCreateTopic=true")
        .log("published ${header.CamelAwsSnsMessageId}");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `subject` | | Message subject (`CamelAwsSnsSubject` wins). |
| `messageStructure` | | `json` to send a different message per protocol. |
| `autoCreateTopic` | `false` | Create the topic when it does not exist. |
| `messageGroupIdStrategy` | | FIFO topics: `useConstant`, `useExchangeId` or `usePropertyValue`. |
| `messageDeduplicationIdStrategy` | `useExchangeId` | FIFO topics: `useExchangeId` or `useContentBasedDeduplication`. |
| `subscribeSNStoSQS` | `false` | Subscribe the SQS queue `queueArn` to the topic when the endpoint starts. |
| `queueArn` | | Queue to subscribe with `subscribeSNStoSQS`. |
| `policy` | | Topic policy (JSON text, or a `file:` / `classpath:` resource). |
| `serverSideEncryptionEnabled`, `kmsMasterKeyId` | `false` | Topic encryption. |
| `batchEnabled` | `false` | Publish a list body with `PublishBatch` (10 per request); body = `{successful, failed}`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsSnsMessageId` | out | Id of the published message. |
| `CamelAwsSnsSubject` | in | Subject. |
| `CamelAwsSnsMessageStructure` | in | Message structure. |
| `CamelAwsSnsMessageGroupId` | in (property) | Group id with `messageGroupIdStrategy=usePropertyValue`. |

Other message headers are published as SNS message attributes.

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/alerts.camel.yaml
```

## Common questions

### How do I fan out to an SQS queue?

Add `subscribeSNStoSQS=true&queueArn=arn:aws:sqs:<region>:<account>:<queue>`; the subscription is
created when the endpoint starts (it is idempotent). The queue policy must allow the topic to send.

### Can I consume from SNS?

No. SNS pushes to subscribers; subscribe an SQS queue and consume it with [aws2-sqs](https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html).

### How do I publish many messages in one call?

Send a list body with `batchEnabled=true`.

## Related

- [AWS SQS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html), [AWS EventBridge](https://pmsudhi.github.io/cameleer/docs/components/aws2-eventbridge.html), [AWS SES](https://pmsudhi.github.io/cameleer/docs/components/aws2-ses.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS SNS](https://camel.apache.org/components/next/aws2-sns-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html

# AWS SQS component

> The `aws2-sqs` component sends messages to and receives messages from Amazon SQS queues, including FIFO queues.

**Scheme:** `aws2-sqs:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [AWS Simple Queue Service (SQS)](https://camel.apache.org/components/next/aws2-sqs-component.html)

## When to use it

- Decouple services: one route sends work to a queue, workers on other machines consume it.
- Process S3, SNS or EventBridge notifications that AWS delivers to a queue.
- Feed serverless pipelines: a Lambda or Step Functions workflow writes to SQS, a Cameleer route on
  an edge device or a container reads from it.
- Give an AI agent a durable task queue: the agent enqueues jobs, a route executes them and
  deletes each message only after it was processed.

## URI format

```text
aws2-sqs://queueNameOrArn[?options]
```

The path is the queue name (or the queue ARN; the last `:` segment is used). The queue URL is
looked up with `GetQueueUrl`, or set it directly with `queueUrl`.

## Example

Send an order to a queue (user headers become SQS message attributes):

```yaml
- route:
    id: send-order
    from:
      uri: "timer:new-order?repeatCount=1"
      steps:
        - setBody:
            constant: '{"orderId":"o-1001","item":"camel saddle","qty":2}'
        - setHeader:
            name: orderType
            constant: express
        - to: "aws2-sqs://orders?region={{env:AWS_REGION:us-east-1}}&autoCreateQueue=true"
        - log: "sent order ${header.CamelAwsSqsMessageId}"
```

Consume the queue. Each message becomes one exchange; it is deleted from the queue only when the
route finishes without an exception, otherwise it becomes visible again after the visibility timeout:

```yaml
- route:
    id: process-orders
    from:
      uri: "aws2-sqs://orders?region={{env:AWS_REGION:us-east-1}}&maxMessagesPerPoll=10&visibilityTimeout=30"
      steps:
        - log: "order ${header.CamelAwsSqsMessageId} (${header.orderType}): ${body}"
        - to: "log:orders"
```

Credentials are not in the uri: they come from the default AWS chain (environment variables,
`~/.aws/credentials`, web identity, ECS or EC2 instance roles). See
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://orders?region={{env:AWS_REGION:us-east-1}}&maxMessagesPerPoll=10&visibilityTimeout=30")
        .log("order ${header.CamelAwsSqsMessageId} (${header.orderType}): ${body}")
        .to("log:orders");
})?;
```

## Options

Common AWS options (`region`, `accessKey`, `secretKey`, `sessionToken`, `profileCredentialsName`,
`useDefaultCredentialsProvider`, `useProfileCredentialsProvider`, `uriEndpointOverride`,
`overrideEndpoint`, `proxyHost`, `proxyPort`, `proxyProtocol`, `trustAllCertificates`) are described in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html).

| option | default | description |
|---|---|---|
| `operation` | `sendMessage` | Producer operation: `sendMessage`, `sendBatchMessage`, `deleteMessage`, `listQueues`, `purgeQueue`, `deleteQueue`, `receiveMessage`, and the Cameleer operations `changeMessageVisibility`, `deleteMessageBatch`, `getQueueAttributes`, `setQueueAttributes`. The `CamelAwsSqsOperation` header overrides it. |
| `queueUrl` | | Use this queue URL instead of looking it up. |
| `autoCreateQueue` | `false` | Create the queue when it does not exist. |
| `queueOwnerAWSAccountId` | | Account that owns the queue (cross-account access). |
| `maxMessagesPerPoll` | `1` | Messages per poll. Above 10, several `ReceiveMessage` calls are made. |
| `waitTimeSeconds` | | Long polling wait of `ReceiveMessage` (seconds). |
| `visibilityTimeout` | | Visibility timeout of received messages (seconds). |
| `extendMessageVisibility` | `false` | Keep extending the visibility of a message while it is processed (needs `visibilityTimeout`). |
| `deleteAfterRead` | `true` | Delete each message after successful processing. |
| `deleteIfFiltered` | `true` | Also delete messages whose exchange was filtered out. |
| `messageAttributeNames` | `All` | Message attributes to receive (comma separated). |
| `attributeNames` | `All` | System attributes to receive (comma separated). |
| `concurrentConsumers` | `1` | Parallel receive and process threads. |
| `concurrentRequestLimit` | `50` | Maximum parallel `ReceiveMessage` calls when `maxMessagesPerPoll` is above 10. |
| `sortAttributeName` | | Sort each received batch by this attribute. |
| `delaySeconds` | | Delay of sent messages (seconds). With `delayQueue=true` it becomes the queue's `DelaySeconds` attribute instead. |
| `delayQueue` | `false` | See `delaySeconds`. |
| `messageGroupIdStrategy` | | FIFO queues: `useConstant`, `useExchangeId` or `usePropertyValue` (property `CamelAwsSqsMessageGroupId`). |
| `messageDeduplicationIdStrategy` | `useExchangeId` | FIFO queues: `useExchangeId` or `useContentBasedDeduplication`. |
| `batchSeparator` | `,` | Separator used to split a string body for `sendBatchMessage`. |
| `defaultVisibilityTimeout`, `messageRetentionPeriod`, `maximumMessageSize`, `receiveMessageWaitTimeSeconds`, `policy`, `redrivePolicy` | | Queue attributes applied when the queue is created, or with `SetQueueAttributes` when the endpoint starts. |
| `serverSideEncryptionEnabled`, `kmsMasterKeyId`, `kmsDataKeyReusePeriodSeconds` | `false` | Server-side encryption of the queue. |
| `protocol` | `auto` | Cameleer: `json` (AWS JSON 1.0), `query` (legacy Query protocol, for older SQS-compatible servers) or `auto` (JSON first, Query when the server rejects JSON). |

The consumer also accepts the scheduled poll options (`delay` default 500 ms, `initialDelay`,
`greedy`, `sendEmptyMessageWhenIdle`, `backoffMultiplier`, `scheduler.cron`, ...).

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsSqsMessageId` | out | Id of the received or sent message. |
| `CamelAwsSqsReceiptHandle` | in/out | Receipt handle (consumer); input of `deleteMessage` and `changeMessageVisibility`. |
| `CamelAwsSqsMD5OfBody` | out | MD5 of the message body. |
| `CamelAwsSqsAttributes` | out | System attributes (map). |
| `CamelAwsSqsMessageAttributes` | out | Message attributes (map); each attribute is also set as its own header. |
| `CamelAwsSqsDelaySeconds` | in | Per-message delay. |
| `CamelAwsSqsOperation` | in | Overrides `operation`. |
| `CamelAwsSqsPrefix` | in | Queue name prefix of `listQueues`. |
| `CamelAwsSqsMaxNumberOfMessages` | in | Messages to receive with `receiveMessage`. |
| `CamelAwsSqsVisibilityTimeout` | in | New timeout of `changeMessageVisibility`. |
| `CamelAwsSqsMessageGroupId` | in (property) | Group id with `messageGroupIdStrategy=usePropertyValue`. |

On send, other message headers become SQS message attributes.

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

## Common questions

### How do I read from a FIFO queue?

Use the queue name with its `.fifo` suffix, for example `aws2-sqs://orders.fifo`. When sending, set
`messageGroupIdStrategy` (for example `useConstant`) and, if the queue has content-based
deduplication, `messageDeduplicationIdStrategy=useContentBasedDeduplication`.

### What happens when processing fails?

The message is not deleted. It becomes visible again after the visibility timeout and is received
again; configure a `redrivePolicy` on the queue to move it to a dead-letter queue after a number of
attempts.

### How do I test against LocalStack or ElasticMQ?

Add `uriEndpointOverride=http://localhost:4566&overrideEndpoint=true`. For servers that only speak
the old Query protocol, add `protocol=query` (or keep the default `auto`).

## Related

- [AWS SNS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sns.html), [AWS EventBridge](https://pmsudhi.github.io/cameleer/docs/components/aws2-eventbridge.html), [AWS Lambda](https://pmsudhi.github.io/cameleer/docs/components/aws2-lambda.html)
- [Azure Storage Queue](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-queue.html), [Azure Service Bus](https://pmsudhi.github.io/cameleer/docs/components/azure-servicebus.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS SQS](https://camel.apache.org/components/next/aws2-sqs-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-step-functions.html

# AWS Step Functions component

> The `aws2-step-functions` component starts and manages AWS Step Functions workflows (state machines, executions and activities).

**Scheme:** `aws2-step-functions:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Step Functions](https://camel.apache.org/components/next/aws2-step-functions-component.html)

## When to use it

- Start a serverless workflow (order fulfilment, document processing) for each incoming event.
- Run a synchronous Express workflow and continue the route with its output (`startSyncExecution`).
- Implement activity workers in a route: fetch a task, do the work, report success or failure.
- Orchestrate long-running AI agent steps (approval, retries, human review) in Step Functions while
  Cameleer handles the connections to your systems.

## URI format

```text
aws2-step-functions://label?operation=...[&options]
```

## Example

Start a workflow execution for every order, with the order JSON as input:

```yaml
- route:
    id: start-order-workflow
    from:
      uri: "aws2-sqs://orders?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - setHeader:
            name: CamelAwsStepFunctionsStateMachineArn
            constant: "{{env:STATE_MACHINE_ARN:arn:aws:states:us-east-1:123456789012:stateMachine:order-fulfilment}}"
        - to: "aws2-step-functions://orders?region={{env:AWS_REGION:us-east-1}}&operation=startExecution"
        - log: "started ${body}"
        - to: "log:executions"
```

The body is the execution input (JSON); after `startExecution` the body is the execution ARN (also in
`CamelAwsStepFunctionsExecutionArn`).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://orders?region={{env:AWS_REGION:us-east-1}}")
        .set_header("CamelAwsStepFunctionsStateMachineArn", constant("{{env:STATE_MACHINE_ARN:arn:aws:states:us-east-1:123456789012:stateMachine:order-fulfilment}}"))
        .to("aws2-step-functions://orders?region={{env:AWS_REGION:us-east-1}}&operation=startExecution")
        .log("started ${body}")
        .to("log:executions");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | | Required. State machines: `createStateMachine`, `deleteStateMachine`, `updateStateMachine`, `describeStateMachine`, `listStateMachines`. Executions: `startExecution`, `startSyncExecution`, `stopExecution`, `describeExecution`, `listExecutions`, `getExecutionHistory`. Activities: `createActivity`, `deleteActivity`, `describeActivity`, `listActivities`, `getActivityTask`, and the Cameleer worker callbacks `sendTaskSuccess`, `sendTaskFailure`, `sendTaskHeartbeat`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsStepFunctionsOperation` | in | Overrides `operation`. |
| `CamelAwsStepFunctionsStateMachineName`, `CamelAwsStepFunctionsStateMachineDefinition`, `CamelAwsStepFunctionsStateMachineRoleArn` | in | State machine settings (the definition may also be the body). |
| `CamelAwsStepFunctionsStateMachineArn` | in | State machine. |
| `CamelAwsStepFunctionsExecutionInput`, `CamelAwsStepFunctionsExecutionName` | in | Input (otherwise the body) and name of an execution. |
| `CamelAwsStepFunctionsExecutionArn` | in/out | Execution. |
| `CamelAwsStepFunctionsExecutionStatusFilter` | in | Status filter of `listExecutions`. |
| `CamelAwsStepFunctionsActivityName`, `CamelAwsStepFunctionsActivityArn`, `CamelAwsStepFunctionsActivityWorkerName` | in/out | Activities. |
| `CamelAwsStepFunctionsTaskToken` | in/out | Token of an activity task (set by `getActivityTask`). |
| `CamelAwsStepFunctionsTaskError`, `CamelAwsStepFunctionsTaskCause` | in | `sendTaskFailure`. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e STATE_MACHINE_ARN \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

## Common questions

### How do I write an activity worker?

Poll with `getActivityTask` (body = task input, `CamelAwsStepFunctionsTaskToken` set; empty body when
no task is waiting), do the work, then call `sendTaskSuccess` with the output as body, or
`sendTaskFailure` with an error and cause.

### How do I get the workflow result in the route?

For Express workflows use `startSyncExecution`: the body becomes the execution result.

## Related

- [AWS Lambda](https://pmsudhi.github.io/cameleer/docs/components/aws2-lambda.html), [AWS SQS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html), [AWS EventBridge](https://pmsudhi.github.io/cameleer/docs/components/aws2-eventbridge.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Step Functions](https://camel.apache.org/components/next/aws2-step-functions-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-sts.html

# AWS STS component

> The `aws2-sts` component gets temporary AWS credentials (assume role, session and federation tokens) and tells which identity the credentials belong to.

**Scheme:** `aws2-sts:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Security Token Service (STS)](https://camel.apache.org/components/next/aws2-sts-component.html)

## When to use it

- Check at startup which account and role an integration runs as (`getCallerIdentity`).
- Assume a role in another account and use the temporary credentials for other AWS endpoints.
- Issue short-lived federation tokens for clients.

## URI format

```text
aws2-sts://label[?options]
```

## Example

Log the identity of the integration when it starts:

```yaml
- route:
    id: who-am-i
    from:
      uri: "timer:whoami?repeatCount=1"
      steps:
        - to: "aws2-sts://sts?region={{env:AWS_REGION:us-east-1}}&operation=getCallerIdentity"
        - log: "running as ${body[arn]} in account ${body[account]}"
        - to: "log:identity"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:whoami?repeatCount=1")
        .to("aws2-sts://sts?region={{env:AWS_REGION:us-east-1}}&operation=getCallerIdentity")
        .log("running as ${body[arn]} in account ${body[account]}")
        .to("log:identity");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `assumeRole` | `assumeRole`, `getSessionToken`, `getFederationToken`, `getCallerIdentity`. |

The credential operations return the map `{accessKeyId, secretAccessKey, sessionToken, expiration}`
(plus `assumedRoleArn` or `federatedUserArn`), ready to be used as the `accessKey`, `secretKey` and
`sessionToken` options of other AWS endpoints. `getCallerIdentity` returns the identity map.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsStsOperation` | in | Overrides `operation`. |
| `CamelAwsStsRoleArn`, `CamelAwsStsRoleSessionName` | in | Role of `assumeRole`. |
| `CamelAwsStsDurationSeconds` | in | Lifetime of the credentials. |
| `CamelAwsStsFederatedName`, `CamelAwsStsPolicy` | in | `getFederationToken`. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/whoami.camel.yaml
```

## Common questions

### Do I need this component to use IAM roles?

No. Instance roles, ECS task roles and EKS web identity (IRSA) are picked up by the default
credentials chain of every AWS component; see [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html).

## Related

- [AWS IAM](https://pmsudhi.github.io/cameleer/docs/components/aws2-iam.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS STS](https://camel.apache.org/components/next/aws2-sts-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-textract.html

# AWS Textract component

> The `aws2-textract` component extracts text, forms, tables and invoice fields from documents and images with Amazon Textract.

**Scheme:** `aws2-textract:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Textract](https://camel.apache.org/components/next/aws2-textract-component.html)

## When to use it

- Read invoices and receipts dropped into a bucket and send their fields to an ERP.
- Turn scanned PDFs into text for search or for an LLM.
- Give an AI agent a document-reading tool: the route returns structured fields the model can use.

## URI format

```text
aws2-textract://label?operation=...[&options]
```

The document is the S3 object named by `s3Bucket` / `s3Object` (options or headers) or, for the
synchronous operations, the body bytes.

## Example

Extract invoice fields from every file uploaded to a bucket and queue them as JSON:

```yaml
- route:
    id: extract-invoices
    from:
      uri: "aws2-s3://scanned-invoices?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - to: "aws2-textract://invoices?region={{env:AWS_REGION:us-east-1}}&operation=analyzeExpense"
        - marshal:
            json: {}
        - to: "aws2-sqs://extracted-invoices?region={{env:AWS_REGION:us-east-1}}&autoCreateQueue=true"
```

The S3 consumer passes the object content as the body; `analyzeExpense` returns the Textract
response (with `ExpenseDocuments` and their `SummaryFields`) as a map.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-s3://scanned-invoices?region={{env:AWS_REGION:us-east-1}}")
        .to("aws2-textract://invoices?region={{env:AWS_REGION:us-east-1}}&operation=analyzeExpense")
        .marshal("json")
        .to("aws2-sqs://extracted-invoices?region={{env:AWS_REGION:us-east-1}}&autoCreateQueue=true");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `detectDocumentText` | `detectDocumentText`, `analyzeDocument`, `analyzeExpense`, `startDocumentTextDetection`, `startDocumentAnalysis`, `startExpenseAnalysis`, `getDocumentTextDetection`, `getDocumentAnalysis`, `getExpenseAnalysis`. |
| `s3Bucket`, `s3Object`, `s3ObjectVersion` | | Document in S3 (required for the asynchronous `start*` operations). |

The synchronous operations return the response map (`Blocks` or `ExpenseDocuments`). The `start*`
operations return the job id (also in `CamelAwsTextractJobId`); the `get*` operations return the
job status and results.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsTextractOperation` | in | Overrides `operation`. |
| `CamelAwsTextractS3Bucket`, `CamelAwsTextractS3Object`, `CamelAwsTextractS3ObjectVersion` | in | Document in S3. |
| `CamelAwsTextractFeatureTypes` | in | `analyzeDocument` features (default `TABLES,FORMS`). |
| `CamelAwsTextractJobId` | in/out | Job of the asynchronous operations. |
| `CamelAwsTextractMaxResults`, `CamelAwsTextractNextToken` | in | Paging of the `get*` operations. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/invoices.camel.yaml
```

## Common questions

### How do I process multi-page PDFs?

Use the asynchronous operations: `startDocumentAnalysis` with `s3Bucket` / `s3Object`, keep the job
id, then call `getDocumentAnalysis` until `JobStatus` is `SUCCEEDED`.

### How do I get only the text lines?

Use `detectDocumentText` and keep the blocks whose `BlockType` is `LINE`, for example with a
`split` on `${body[Blocks]}` and a `filter`.

## Related

- [AWS S3](https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html), [AWS Comprehend](https://pmsudhi.github.io/cameleer/docs/components/aws2-comprehend.html), [AWS Bedrock](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Textract](https://camel.apache.org/components/next/aws2-textract-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-timestream.html

# AWS Timestream component

> The `aws2-timestream` component writes time series records to Amazon Timestream and runs queries on them.

**Scheme:** `aws2-timestream:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Timestream](https://camel.apache.org/components/next/aws2-timestream-component.html)

## When to use it

- Store sensor readings from IoT gateways and edge devices.
- Record operational metrics with dimensions (device, site, region).
- Query recent values for dashboards, alerts or an AI agent that answers questions about devices.

## URI format

```text
aws2-timestream://write:label[?options]
aws2-timestream://query:label[?options]
```

`write:` endpoints use Timestream Write, `query:` endpoints Timestream Query. Without an endpoint
override the client discovers the service endpoint (`DescribeEndpoints`) and caches it.

## Example

Write each sensor reading of a queue as a record. The messages are already Timestream records:

```yaml
- route:
    id: readings-to-timestream
    from:
      uri: "aws2-sqs://sensor-readings?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: CamelAwsTimestreamDatabaseName
            constant: iot
        - setHeader:
            name: CamelAwsTimestreamTableName
            constant: readings
        - to: "aws2-timestream://write:sensors?region={{env:AWS_REGION:us-east-1}}&operation=writeRecords"
        - log: "records ingested: ${body}"
```

A reading looks like
`{"Dimensions":[{"Name":"device","Value":"edge-7"}],"MeasureName":"temperature","MeasureValue":"21.5","MeasureValueType":"DOUBLE","Time":"1730800000000"}`.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://sensor-readings?region={{env:AWS_REGION:us-east-1}}")
        .unmarshal("json")
        .set_header("CamelAwsTimestreamDatabaseName", constant("iot"))
        .set_header("CamelAwsTimestreamTableName", constant("readings"))
        .to("aws2-timestream://write:sensors?region={{env:AWS_REGION:us-east-1}}&operation=writeRecords")
        .log("records ingested: ${body}");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `query` on `query:` endpoints | Write: `describeEndpoints`, `createDatabase`, `deleteDatabase`, `describeDatabase`, `listDatabases`, `createTable`, `deleteTable`, `describeTable`, `listTables`, `writeRecords`. Query: `query`, `cancelQuery`, `describeEndpoints`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsTimestreamOperation` | in | Overrides `operation`. |
| `CamelAwsTimestreamDatabaseName`, `CamelAwsTimestreamTableName` | in | Database and table. |
| `CamelAwsTimestreamRecord`, `CamelAwsTimestreamRecordList` | in | Records of `writeRecords` (otherwise the body: a record map or a list). |
| `CamelAwsTimestreamCommonAttributes` | in | Attributes shared by all records. |
| `CamelAwsTimestreamMemoryStoreRetentionPeriodInHours`, `CamelAwsTimestreamMagneticStoreRetentionPeriodInDays` | in | Retention of `createTable`. |
| `CamelAwsTimestreamQueryString` | in | SQL of `query` (otherwise the body). |
| `CamelAwsTimestreamQueryId` | in/out | Query (set by `query`, input of `cancelQuery`). |

`query` returns all pages as a list of rows (maps of column name to value).

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/readings.camel.yaml
```

## Common questions

### How do I query the last hour?

Send `SELECT * FROM "iot"."readings" WHERE time > ago(1h)` to a `query:` endpoint
(`aws2-timestream://query:sensors`); the body becomes the list of rows.

## Related

- [AWS Kinesis](https://pmsudhi.github.io/cameleer/docs/components/aws2-kinesis.html), [AWS CloudWatch](https://pmsudhi.github.io/cameleer/docs/components/aws2-cw.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Timestream](https://camel.apache.org/components/next/aws2-timestream-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-transcribe.html

# AWS Transcribe component

> The `aws2-transcribe` component starts and manages Amazon Transcribe speech-to-text jobs, including medical and call analytics jobs, custom vocabularies and language models.

**Scheme:** `aws2-transcribe:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Transcribe](https://camel.apache.org/components/next/aws2-transcribe-component.html)

## When to use it

- Transcribe call recordings or voice messages uploaded to S3.
- Feed transcripts to an LLM for summaries, or to Comprehend for sentiment.
- Analyse contact center calls with call analytics categories.

## URI format

```text
aws2-transcribe://label?operation=...[&options]
```

## Example

Start a transcription job for every recording URI that arrives on a queue:

```yaml
- route:
    id: transcribe-recordings
    from:
      uri: "aws2-sqs://recordings?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - setHeader:
            name: CamelAwsTranscribeTranscriptionJobName
            simple: "call-${header.CamelAwsSqsMessageId}"
        - setHeader:
            name: CamelAwsTranscribeOutputBucketName
            constant: "{{env:TRANSCRIPT_BUCKET:call-transcripts}}"
        - to: "aws2-transcribe://calls?region={{env:AWS_REGION:us-east-1}}&operation=startTranscriptionJob&languageCode=en-US"
        - log: "job ${header.CamelAwsTranscribeTranscriptionJobName}: ${header.CamelAwsTranscribeTranscriptionJobStatus}"
        - to: "log:jobs"
```

The body is the media URI (for example `s3://recordings/call-17.wav`); the body after the call is the
job map and `CamelAwsTranscribeTranscriptionJobStatus` is set.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://recordings?region={{env:AWS_REGION:us-east-1}}")
        .set_header("CamelAwsTranscribeTranscriptionJobName", simple("call-${header.CamelAwsSqsMessageId}"))
        .set_header("CamelAwsTranscribeOutputBucketName", constant("{{env:TRANSCRIPT_BUCKET:call-transcripts}}"))
        .to("aws2-transcribe://calls?region={{env:AWS_REGION:us-east-1}}&operation=startTranscriptionJob&languageCode=en-US")
        .log("job ${header.CamelAwsTranscribeTranscriptionJobName}: ${header.CamelAwsTranscribeTranscriptionJobStatus}")
        .to("log:jobs");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | | Required. Jobs: `startTranscriptionJob`, `getTranscriptionJob`, `deleteTranscriptionJob`, `listTranscriptionJobs`. Medical: `startMedicalTranscriptionJob`, `getMedicalTranscriptionJob`, `deleteMedicalTranscriptionJob`, `listMedicalTranscriptionJobs`. Call analytics: `startCallAnalyticsJob`, `getCallAnalyticsJob`, `deleteCallAnalyticsJob`, `listCallAnalyticsJobs`, `createCallAnalyticsCategory`, `updateCallAnalyticsCategory`, `getCallAnalyticsCategory`, `deleteCallAnalyticsCategory`, `listCallAnalyticsCategories`. Vocabularies: `createVocabulary`, `updateVocabulary`, `getVocabulary`, `deleteVocabulary`, `listVocabularies` and the `...MedicalVocabulary` variants. Language models: `createLanguageModel`, `describeLanguageModel`, `deleteLanguageModel`, `listLanguageModels`. Tags: `tagResource`, `untagResource`, `listTagsForResource`. |
| `languageCode` | | Language of the media (`CamelAwsTranscribeLanguageCode` wins). |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsTranscribeOperation` | in | Overrides `operation`. |
| `CamelAwsTranscribeTranscriptionJobName` | in | Job name. |
| `CamelAwsTranscribeMediaUri` | in | Media URI (otherwise the body). |
| `CamelAwsTranscribeLanguageCode`, `CamelAwsTranscribeIdentifyLanguage` | in | Language, or automatic identification. |
| `CamelAwsTranscribeMediaFormat`, `CamelAwsTranscribeMediaSampleRateHertz` | in | Media settings. |
| `CamelAwsTranscribeOutputBucketName` | in | Bucket for the transcript. |
| `CamelAwsTranscribeStatus`, `CamelAwsTranscribeJobNameContains` | in | Filters of `listTranscriptionJobs`. |
| `CamelAwsTranscribeTranscriptionJobStatus` | out | Job status (or vocabulary state / model status). |
| `CamelAwsTranscribeMedicalTranscriptionJobName`, `CamelAwsTranscribeSpecialty`, `CamelAwsTranscribeType` | in | Medical jobs. |
| `CamelAwsTranscribeCallAnalyticsJobName`, `CamelAwsTranscribeDataAccessRoleArn`, `CamelAwsTranscribeOutputLocation`, `CamelAwsTranscribeChannelDefinitions`, `CamelAwsTranscribeCategoryName`, `CamelAwsTranscribeRules` | in | Call analytics. |
| `CamelAwsTranscribeVocabularyName`, `CamelAwsTranscribePhrases`, `CamelAwsTranscribeVocabularyFileUri`, `CamelAwsTranscribeNameContains`, `CamelAwsTranscribeStateEquals` | in | Vocabularies. |
| `CamelAwsTranscribeLanguageModelName`, `CamelAwsTranscribeBaseModelName`, `CamelAwsTranscribeInputDataS3Uri` | in | Language models. |
| `CamelAwsTranscribeResourceArn`, `CamelAwsTranscribeTags`, `CamelAwsTranscribeTagKeys` | in | Tags. |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e TRANSCRIPT_BUCKET \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/transcribe.camel.yaml
```

## Common questions

### How do I know when the transcript is ready?

Poll `getTranscriptionJob` with the job name until the status is `COMPLETED` (for example from a
timer route), or let S3 notify you when the transcript object appears in the output bucket.

### Can it transcribe a live audio stream?

No. Streaming transcription is a separate WebSocket / HTTP/2 API that this component does not cover;
it works with recorded media in S3.

## Related

- [AWS Polly](https://pmsudhi.github.io/cameleer/docs/components/aws2-polly.html), [AWS Comprehend](https://pmsudhi.github.io/cameleer/docs/components/aws2-comprehend.html), [AWS S3](https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Transcribe](https://camel.apache.org/components/next/aws2-transcribe-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/aws2-translate.html

# AWS Translate component

> The `aws2-translate` component translates text between languages with Amazon Translate, with optional automatic source language detection.

**Scheme:** `aws2-translate:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [AWS Translate](https://camel.apache.org/components/next/aws2-translate-component.html)

## When to use it

- Translate support replies or product texts into the customer's language.
- Normalize incoming messages to one language before classification or an LLM call.
- Apply custom terminologies (brand names, product terms) to every translation.

## URI format

```text
aws2-translate://label[?options]
```

## Example

Translate replies into German:

```yaml
- route:
    id: translate-replies
    from:
      uri: "aws2-sqs://replies-en?region={{env:AWS_REGION:us-east-1}}"
      steps:
        - to: "aws2-translate://replies?region={{env:AWS_REGION:us-east-1}}&sourceLanguage=en&targetLanguage=de"
        - to: "aws2-sqs://replies-de?region={{env:AWS_REGION:us-east-1}}&autoCreateQueue=true"
```

The body text is translated; the body after the call is the translation.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("aws2-sqs://replies-en?region={{env:AWS_REGION:us-east-1}}")
        .to("aws2-translate://replies?region={{env:AWS_REGION:us-east-1}}&sourceLanguage=en&targetLanguage=de")
        .to("aws2-sqs://replies-de?region={{env:AWS_REGION:us-east-1}}&autoCreateQueue=true");
})?;
```

## Options

Common AWS options (region, credentials, endpoint override, proxy) are listed in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#aws-options).

| option | default | description |
|---|---|---|
| `operation` | `translateText` | The only operation. |
| `sourceLanguage` | | Source language code. |
| `targetLanguage` | | Target language code. |
| `autodetectSourceLanguage` | `false` | Send `auto` as the source language; the detected language is set in `CamelAwsTranslateSourceLanguage`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAwsTranslateOperation` | in | Overrides `operation`. |
| `CamelAwsTranslateSourceLanguage` | in/out | Source language (out: the detected one with auto-detection). |
| `CamelAwsTranslateTargetLanguage` | in | Target language. |
| `CamelAwsTranslateTerminologyNames` | in | Custom terminologies (list). |

## Run it with Docker

```sh
docker run --rm -e AWS_REGION -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/translate.camel.yaml
```

## Common questions

### How do I translate into the language of each customer?

Set `CamelAwsTranslateTargetLanguage` per message (for example from a customer header) instead of
the `targetLanguage` option.

### What if I do not know the source language?

Set `autodetectSourceLanguage=true`.

## Related

- [AWS Comprehend](https://pmsudhi.github.io/cameleer/docs/components/aws2-comprehend.html), [AWS Polly](https://pmsudhi.github.io/cameleer/docs/components/aws2-polly.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel AWS Translate](https://camel.apache.org/components/next/aws2-translate-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/azure-cosmosdb.html

# Azure Cosmos DB component

> The `azure-cosmosdb` component creates, reads, upserts, queries and deletes items in Azure Cosmos DB (SQL API) and consumes a container's change feed.

**Scheme:** `azure-cosmosdb:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [Azure CosmosDB](https://camel.apache.org/components/next/azure-cosmosdb-component.html)

## When to use it

- Store orders, device twins or user profiles from routes.
- Query items with SQL and parameters to enrich messages.
- Change data capture: react to every inserted or updated item through the change feed, with
  leases shared between several instances.
- Keep the conversation state or memory of an AI agent in a globally distributed store.

## URI format

```text
azure-cosmosdb://databaseName[/containerName][?options]
```

## Example

Upsert an order, creating the database and the container on first use:

```yaml
- route:
    id: save-order
    from:
      uri: "timer:order?repeatCount=1"
      steps:
        - setBody:
            constant: '{"id":"o-1001","customerId":"c-42","total":99.5}'
        - unmarshal:
            json: {}
        - setHeader:
            name: CamelAzureCosmosDbItemPartitionKey
            simple: "${body[customerId]}"
        - to: "azure-cosmosdb://shop/orders?databaseEndpoint={{env:COSMOS_ENDPOINT:https://myaccount.documents.azure.com:443/}}&accountKey=RAW({{env:COSMOS_KEY:}})&operation=upsertItem&createDatabaseIfNotExists=true&createContainerIfNotExists=true&containerPartitionKeyPath=/customerId"
        - log: "saved order (status ${header.CamelAzureCosmosDbStatusCode})"
```

Consume the change feed of the container from the beginning. Each non-empty batch arrives as a
list of the changed items:

```yaml
- route:
    id: order-changes
    from:
      uri: "azure-cosmosdb://shop/orders?databaseEndpoint={{env:COSMOS_ENDPOINT:https://myaccount.documents.azure.com:443/}}&accountKey=RAW({{env:COSMOS_KEY:}})&changeFeedStartFromBeginning=true"
      steps:
        - log: "changed orders: ${body}"
        - to: "log:order-changes"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("azure-cosmosdb://shop/orders?databaseEndpoint={{env:COSMOS_ENDPOINT:https://myaccount.documents.azure.com:443/}}&accountKey=RAW({{env:COSMOS_KEY:}})&changeFeedStartFromBeginning=true")
        .log("changed orders: ${body}")
        .to("log:order-changes");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `databaseEndpoint` | | Account endpoint, for example `https://myaccount.documents.azure.com:443/` (or the emulator). |
| `accountKey` | | Primary or secondary key (master key authorization). |
| `credentialType` | `SHARED_ACCOUNT_KEY` | `SHARED_ACCOUNT_KEY`, or `AZURE_IDENTITY` for Microsoft Entra ID (client secret, workload or managed identity; see [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#azure)). |
| `operation` | `listDatabases` | Databases: `listDatabases`, `createDatabase`, `queryDatabases`, `deleteDatabase`. Containers: `createContainer`, `listContainers`, `queryContainers`, `deleteContainer`. Items: `createItem`, `upsertItem`, `replaceItem`, `deleteItem`, `readItem`, `readAllItems`, `queryItems`. Throughput: `replaceDatabaseThroughput`, `replaceContainerThroughput`, `readDatabaseThroughput`, `readContainerThroughput` (the read ones are Cameleer extensions). |
| `query` | | SQL of `queryItems` (parameters from `CamelAzureCosmosDbQueryParameters`). |
| `itemId`, `itemPartitionKey` | | Item of `readItem` / `deleteItem`, and the partition key value. |
| `containerPartitionKeyPath` | | Partition key path of a created container, for example `/customerId`. |
| `createDatabaseIfNotExists`, `createContainerIfNotExists` | `false` | Create them when the endpoint starts. |
| `throughputProperties` | | RU/s of created resources (a number, or autoscale settings via the header). |
| `consistencyLevel` | | `STRONG`, `BOUNDED_STALENESS`, `SESSION`, `CONSISTENT_PREFIX`, `EVENTUAL`. |
| `contentResponseOnWriteEnabled` | `true` | `false` sends `Prefer: return=minimal` (writes return no item). |
| `changeFeedStartFromBeginning` | `false` | Cameleer: the consumer starts at the beginning of the change feed instead of now. |
| `leaseContainerName`, `leaseDatabaseName`, `createLeaseContainerIfNotExists`, `createLeaseDatabaseIfNotExists`, `hostName`, `leaseExpirationInterval` | | Consumer as a change feed processor: one lease per partition key range, balanced between hosts (`leaseExpirationInterval` ms, default 60000). Without a lease container the continuations are kept in memory. |
| `uriEndpointOverride`, `proxyHost`, `proxyPort`, `trustAllCertificates` | | Connection settings. |

Cameleer always talks to the REST gateway; the SDK's direct (TCP) connection mode options do not apply.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAzureCosmosDbOperation` | in | Overrides `operation`. |
| `CamelAzureCosmosDbDatabaseName`, `CamelAzureCosmosDbContainerName` | in | Override the database and container. |
| `CamelAzureCosmosDbQuery`, `CamelAzureCosmosDbQueryParameters` | in | SQL and its parameters (map). |
| `CamelAzureCosmosDbItemId`, `CamelAzureCosmosDbItemPartitionKey` | in | Item and partition key value. |
| `CamelAzureCosmosDbContainerPartitionKeyPath` | in | Partition key path of `createContainer`. |
| `CamelAzureCosmosDbThroughputProperties` | in | RU/s (number) or `{throughput}` / `{autoscaleMaxThroughput}`. |
| `CamelAzureCosmosDbResourceId`, `CamelAzureCosmosDbEtag`, `CamelAzureCosmosDbStatusCode`, `CamelAzureCosmosDbResponseHeaders` | out | Response details. |

## Run it with Docker

```sh
docker run --rm -e COSMOS_ENDPOINT -e COSMOS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

## Common questions

### How do I query with parameters?

Set `query=SELECT * FROM c WHERE c.customerId = @customer` and the header
`CamelAzureCosmosDbQueryParameters` to `{"@customer": "c-42"}`; all result pages are returned as a list.

### How do I run the change feed on several instances?

Add `leaseContainerName=leases&createLeaseContainerIfNotExists=true`: each instance takes a fair
share of the partition key ranges and checkpoints its progress in the lease container.

### Does it work with the Cosmos DB emulator?

Yes: point `databaseEndpoint` at the emulator, for example `https://localhost:8081/`, with the
emulator's key.

## Related

- [AWS DynamoDB](https://pmsudhi.github.io/cameleer/docs/components/aws2-ddb.html), [Azure Storage Blob](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-blob.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel Azure Cosmos DB](https://camel.apache.org/components/next/azure-cosmosdb-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/azure-storage-datalake.html

# Azure Data Lake Storage component

> The `azure-storage-datalake` component reads, writes, appends, lists and deletes files and directories in Azure Data Lake Storage Gen2, sets ACLs and runs query acceleration.

**Scheme:** `azure-storage-datalake:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [Azure Storage Datalake Service](https://camel.apache.org/components/next/azure-storage-datalake-component.html)

## When to use it

- Land raw data (events, sensor readings, exports) in a data lake for analytics.
- Append records to a file in place, then flush it (`appendToFile`, `flushToFile`).
- Pick up files that analytics jobs write and hand them to other systems.
- Filter large CSV or JSON files on the server with SQL (`openQueryInputStream`).

## URI format

```text
azure-storage-datalake://accountName[/fileSystemName][?options]
```

## Example

Upload a file into a directory of a file system:

```yaml
- route:
    id: land-readings
    from:
      uri: "timer:readings?repeatCount=1"
      steps:
        - setBody:
            constant: '{"device":"edge-7","temperature":21.5}'
        - setHeader:
            name: CamelAzureStorageDataLakeFileName
            constant: readings.json
        - to: "azure-storage-datalake://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/raw?operation=upload&directoryName=sensors&accountKey=RAW({{env:AZURE_STORAGE_KEY:}})"
        - log: "stored sensors/${header.CamelAzureStorageDataLakeFileName}"
```

`upload` creates the file, appends the body and flushes it. The directory name is prefixed to the
file name.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:readings?repeatCount=1")
        .set_body(constant(r#"{"device":"edge-7","temperature":21.5}"#))
        .set_header("CamelAzureStorageDataLakeFileName", constant("readings.json"))
        .to("azure-storage-datalake://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/raw?operation=upload&directoryName=sensors&accountKey=RAW({{env:AZURE_STORAGE_KEY:}})")
        .log("stored sensors/${header.CamelAzureStorageDataLakeFileName}");
})?;
```

## Options

Common Azure options (credentials, endpoint override, proxy) are described in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#azure-options). The account key option is
`accountKey` (as in Camel; `accessKey` works too).

| option | default | description |
|---|---|---|
| `operation` | `listFileSystem` | `listFileSystem`, `createFileSystem`, `deleteFileSystem`, `listPaths`, `createFile`, `upload`, `uploadFromFile`, `appendToFile`, `flushToFile`, `getFile`, `downloadToFile`, `downloadLink`, `deleteFile`, `createDirectory` (Cameleer), `deleteDirectory`, `openQueryInputStream`, and the Cameleer ACL operations `getAccessControl`, `setAccessControl`. |
| `fileName` | | File (the `CamelAzureStorageDataLakeFileName` header wins). |
| `directoryName` | | Directory, prefixed to the file name. |
| `path` | | Directory of `listPaths` and of the consumer. |
| `recursive` | `false` | Recursive listing and consumer. |
| `regex` | | Consumer: only file names matching this regular expression. |
| `deleteAfterRead` | `false` | Cameleer: consumer deletes processed files (otherwise it reads them again on every poll, as in Camel). |
| `permission`, `umask` | | Permissions of `createFile` (symbolic `rwxr-x---` or octal). |
| `userPrincipalNameReturned` | `false` | `getAccessControl` returns user principal names. |
| `fileDir` | | Local directory of `downloadToFile` and `uploadFromFile`. |
| `downloadLinkExpiration` | 1 hour | Validity (ms) of `downloadLink`. |
| `expression` | | SQL of `openQueryInputStream`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAzureStorageDataLakeOperation` | in | Overrides `operation`. |
| `CamelAzureStorageDataLakeFileSystemName`, `CamelAzureStorageDataLakeDirectoryName`, `CamelAzureStorageDataLakeFileName`, `CamelAzureStorageDataLakePath`, `CamelAzureStorageDataLakeRecursive` | in/out | Location. |
| `CamelAzureStorageDataLakeFileOffset`, `CamelAzureStorageDataLakePosition` | in/out | `appendToFile` offset and the position to flush. |
| `CamelAzureStorageDataLakeETag`, `CamelAzureStorageDataLakeLastModified`, `CamelAzureStorageDataLakeContentLength` | out | File properties. |
| `CamelAzureStorageDataLakeFileDir`, `CamelAzureStorageDataLakeDownloadLink`, `CamelAzureStorageDataLakeDownloadLinkExpiration` | in/out | Downloads and links. |
| `CamelAzureStorageDataLakeExpression`, `CamelAzureStorageDataLakeQueryInputFormat`, `CamelAzureStorageDataLakeQueryHasHeaders` | in | Query acceleration (`csv` default or `json`). |
| `CamelAzureStorageDataLakeAcl`, `CamelAzureStorageDataLakePermission`, `CamelAzureStorageDataLakeOwner`, `CamelAzureStorageDataLakeGroup` | in | `setAccessControl`. |

## Run it with Docker

```sh
docker run --rm -e AZURE_STORAGE_ACCOUNT -e AZURE_STORAGE_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/lake.camel.yaml
```

## Common questions

### How do I append to an existing file?

Use `appendToFile` (the data goes to the current end, or `CamelAzureStorageDataLakeFileOffset`), then
`flushToFile`, which commits up to `CamelAzureStorageDataLakePosition`.

### How do I use a service principal?

Set `clientId`, `clientSecret` and `tenantId` (with `credentialType=CLIENT_SECRET`), or use
`credentialType=AZURE_IDENTITY` for workload and managed identities.

## Related

- [Azure Storage Blob](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-blob.html), [Azure Files](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-files.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel Azure Storage Data Lake](https://camel.apache.org/components/next/azure-storage-datalake-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/azure-eventgrid.html

# Azure Event Grid component

> The `azure-eventgrid` component publishes events to an Azure Event Grid topic, as CloudEvents or in the Event Grid schema.

**Scheme:** `azure-eventgrid:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [Azure Event Grid](https://camel.apache.org/components/next/azure-eventgrid-component.html)

## When to use it

- Publish business events (order placed, device offline) that Azure Functions, Logic Apps or
  webhooks subscribe to.
- Bridge events from MQTT, Kafka or on-premises systems into Azure's event routing.

## URI format

```text
azure-eventgrid:topicEndpoint[?options]
```

The path is the topic endpoint URL, for example
`https://mytopic.westeurope-1.eventgrid.azure.net/api/events`.

## Example

Publish an `OrderPlaced` CloudEvent:

```yaml
- route:
    id: publish-order-event
    from:
      uri: "timer:order-event?repeatCount=1"
      steps:
        - setBody:
            constant: '{"orderId":"o-1001","total":99.5}'
        - unmarshal:
            json: {}
        - setHeader:
            name: CamelAzureEventGridEventType
            constant: Shop.OrderPlaced
        - setHeader:
            name: CamelAzureEventGridSubject
            constant: orders/o-1001
        - to: "azure-eventgrid:{{env:EVENTGRID_TOPIC_ENDPOINT:https://mytopic.westeurope-1.eventgrid.azure.net/api/events}}?accessKey=RAW({{env:EVENTGRID_ACCESS_KEY:}})"
        - log: "published event ${header.CamelAzureEventGridEventId}"
```

The body is the event `data`; a list body publishes one event per element.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:order-event?repeatCount=1")
        .set_body(constant(r#"{"orderId":"o-1001","total":99.5}"#))
        .unmarshal("json")
        .set_header("CamelAzureEventGridEventType", constant("Shop.OrderPlaced"))
        .set_header("CamelAzureEventGridSubject", constant("orders/o-1001"))
        .to("azure-eventgrid:{{env:EVENTGRID_TOPIC_ENDPOINT:https://mytopic.westeurope-1.eventgrid.azure.net/api/events}}?accessKey=RAW({{env:EVENTGRID_ACCESS_KEY:}})")
        .log("published event ${header.CamelAzureEventGridEventId}");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `eventSchema` | `CloudEvent` | `CloudEvent` (CloudEvents 1.0 JSON batch) or `EventGrid` (Event Grid schema). |
| `accessKey` | | Topic access key (`aeg-sas-key` header). |
| `credentialType` | `ACCESS_KEY` with a key | `ACCESS_KEY`, `AZURE_SAS` (an `aeg-sas-token`: `sharedAccessSignature`, or one signed with `accessKey`), or Entra ID (`tenantId`, `clientId`, `clientSecret`, `authorityHost`; `AZURE_IDENTITY` reads `AZURE_*` variables). |
| `sharedAccessSignature` | | Pre-built SAS token. |
| `sasTokenTtl` | `3600` | Lifetime (seconds) of tokens signed with `accessKey`. |
| `topicEndpoint` | | Alternative to the path. |
| `uriEndpointOverride`, `proxyHost`, `proxyPort`, `trustAllCertificates` | | Connection settings. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAzureEventGridEventType` | in | Event type (default `org.apache.camel.event`). |
| `CamelAzureEventGridSubject` | in | Subject. |
| `CamelAzureEventGridSource` | in | CloudEvents source (default: the topic endpoint). |
| `CamelAzureEventGridEventId` | in/out | Event id (random UUID by default); the ids sent (a list for list bodies). |
| `CamelAzureEventGridDataVersion` | in | Event Grid schema data version (default `1.0`). |
| `CamelAzureEventGridDataContentType` | in | CloudEvents data content type (default `application/json`). |

## Run it with Docker

```sh
docker run --rm -e EVENTGRID_TOPIC_ENDPOINT -e EVENTGRID_ACCESS_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/events.camel.yaml
```

## Common questions

### How do I receive Event Grid events in a route?

Subscribe an Event Hub, a Storage queue or a Service Bus queue to the topic and consume it with
[azure-eventhubs](https://pmsudhi.github.io/cameleer/docs/components/azure-eventhubs.html), [azure-storage-queue](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-queue.html) or
[azure-servicebus](https://pmsudhi.github.io/cameleer/docs/components/azure-servicebus.html).

### Which schema should I use?

`CloudEvent` for new topics; `EventGrid` when the topic was created with the Event Grid schema.

## Related

- [Azure Event Hubs](https://pmsudhi.github.io/cameleer/docs/components/azure-eventhubs.html), [Azure Service Bus](https://pmsudhi.github.io/cameleer/docs/components/azure-servicebus.html)
- [AWS EventBridge](https://pmsudhi.github.io/cameleer/docs/components/aws2-eventbridge.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel Azure Event Grid](https://camel.apache.org/components/next/azure-eventgrid-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/azure-eventhubs.html

# Azure Event Hubs component

> The `azure-eventhubs` component sends events to and consumes events from Azure Event Hubs over AMQP 1.0, with partitions, checkpoints and load balancing between consumers.

**Scheme:** `azure-eventhubs:` · **Crate:** `cameleer-amqp10` · **Cargo feature:** [`amqp10`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [Azure Event Hubs](https://camel.apache.org/components/next/azure-eventhubs-component.html)

## When to use it

- Stream telemetry from devices and gateways into Azure.
- Consume high-volume event streams partition by partition, resuming from checkpoints.
- Run several consumer instances that share the partitions (like the Azure SDK's event processor).
- Read Event Grid events (for example Key Vault or Storage events) that are forwarded to an event hub.

## URI format

```text
azure-eventhubs:namespace/eventHubName[?options]
azure-eventhubs:?connectionString=...;EntityPath=eventHubName
```

## Example

Send device telemetry; events with the same partition key go to the same partition:

```yaml
- route:
    id: send-telemetry
    from:
      uri: "timer:telemetry?repeatCount=1"
      steps:
        - setBody:
            constant: '{"device":"edge-7","temperature":21.5}'
        - to: "azure-eventhubs:?connectionString=RAW({{env:EVENTHUBS_CONNECTION_STRING:Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=change-me;EntityPath=telemetry}})&partitionKey=edge-7"
```

Consume the event hub from the oldest retained event:

```yaml
- route:
    id: read-telemetry
    from:
      uri: "azure-eventhubs:?connectionString=RAW({{env:EVENTHUBS_CONNECTION_STRING:Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=change-me;EntityPath=telemetry}})&initialPosition=earliest"
      steps:
        - convertBodyTo: String
        - log: "partition ${header.CamelAzureEventHubsPartitionId} offset ${header.CamelAzureEventHubsOffset}: ${body}"
        - to: "log:telemetry"
```

The event body arrives as bytes. Checkpoints are kept in memory unless you configure a checkpoint
store (see the options).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("azure-eventhubs:?connectionString=RAW({{env:EVENTHUBS_CONNECTION_STRING:Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=change-me;EntityPath=telemetry}})&initialPosition=earliest")
        .convert_body_to("String")
        .log("partition ${header.CamelAzureEventHubsPartitionId} offset ${header.CamelAzureEventHubsOffset}: ${body}")
        .to("log:telemetry");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `connectionString` | | Connection string; `EntityPath` names the event hub when the uri has none. |
| `sharedAccessName`, `sharedAccessKey`, `fullyQualifiedNamespace` | | Instead of a connection string (with `namespace/eventHubName` in the uri). |
| `credentialType` | `CONNECTION_STRING` | `CONNECTION_STRING`, `AZURE_IDENTITY` or `TOKEN_CREDENTIAL` (see [Azure Service Bus](https://pmsudhi.github.io/cameleer/docs/components/azure-servicebus.html)). |
| `amqpTransportType` | `AMQP` | `AMQP` or `AMQP_WEB_SOCKETS`. |
| `consumerGroupName` | `$Default` | Consumer group. |
| `partitionId` | | Producer: send to this partition. Consumer: read only this partition. |
| `partitionKey` | | Producer: partition key. |
| `prefetchCount` | `500` | Events to prefetch per partition. |
| `initialPosition` | `latest` | Cameleer: where to start without a checkpoint, `latest` or `earliest`. |
| `eventPosition` | | Start position per partition, for example `0=earliest,1=offset:42,2=sequenceNumber:7:inclusive` (or `#bean`). |
| `checkpointStore` | in memory | `#bean` of a `CheckpointStore`. |
| `blobAccountName`, `blobContainerName`, `blobAccessKey`, `blobEndpoint` | | Checkpoints and ownership in Azure Blob Storage (layout of the Azure SDK's blob checkpoint store). |
| `checkpointBatchSize`, `checkpointBatchTimeout` | `500`, `5000` | Checkpoint every N events or T ms (and when stopping). |
| `loadBalancing` | `true` | Share partitions with other instances using the same checkpoint store. |
| `loadBalancingUpdateInterval`, `partitionOwnershipExpirationInterval` | 10 s, 60 s | Load balancing timings (Cameleer). |
| `ownerId`, `ownerLevel` | random, | Owner id of ownership records and the receiver epoch. |
| `sasTokenTtl`, `idleTimeout`, `requestTimeout`, `recoveryInterval` | | Connection timings. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAzureEventHubsPartitionId` | in/out | Partition (input: target partition). |
| `CamelAzureEventHubsPartitionKey` | in/out | Partition key. |
| `CamelAzureEventHubsOffset`, `CamelAzureEventHubsSequenceNumber` | out | Position of the event. |
| `CamelAzureEventHubsEnqueuedTime` | out | Enqueued time (epoch millis), also `CamelMessageTimestamp`. |

Other headers are sent as application properties, and received application properties become headers.

## Run it with Docker

```sh
docker run --rm -e EVENTHUBS_CONNECTION_STRING \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/telemetry.camel.yaml
```

## Common questions

### How do I resume after a restart?

Configure a persistent checkpoint store, for example Azure Blob Storage with `blobAccountName`,
`blobContainerName` and `blobAccessKey`; the consumer continues after the last checkpoint.

### How do I scale out consumers?

Start more instances with the same consumer group and the same blob checkpoint store: partitions are
balanced between them, and a new owner takes over the partitions of a stopped instance.

### Can I use Kafka clients instead?

Event Hubs also has a Kafka endpoint; the `kafka` component can use it with SASL `PLAIN` and the
connection string as password. This component uses the native AMQP protocol.

## Related

- [Azure Service Bus](https://pmsudhi.github.io/cameleer/docs/components/azure-servicebus.html), [Azure Schema Registry](https://pmsudhi.github.io/cameleer/docs/components/azure-schema-registry.html), [Azure Key Vault](https://pmsudhi.github.io/cameleer/docs/components/azure-key-vault.html)
- [AWS Kinesis](https://pmsudhi.github.io/cameleer/docs/components/aws2-kinesis.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel Azure Event Hubs](https://camel.apache.org/components/next/azure-eventhubs-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/azure-storage-files.html

# Azure Files component

> The `azure-storage-files` component uploads, downloads, lists and deletes files and directories in Azure Files shares, and polls a directory for new files.

**Scheme:** `azure-storage-files:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** Camel's [Azure Files](https://camel.apache.org/components/next/azure-files-component.html) component uses the scheme `azure-files` and FTP-style options; `azure-storage-files` follows the other Azure storage components and also supports those FTP-style options

## When to use it

- Exchange files with applications that mount an Azure file share (SMB) from a route.
- Pick up files written to a share, then delete or move them.
- Publish exports to a share with an atomic rename (`tempPrefix`).

## URI format

```text
azure-storage-files://accountName/shareName[?options]
```

## Example

Upload an export into a directory of a share:

```yaml
- route:
    id: export-to-share
    from:
      uri: "timer:export?repeatCount=1"
      steps:
        - setBody:
            constant: "sku,stock;A-1,12;B-7,0"
        - setHeader:
            name: CamelAzureStorageFilesFileName
            constant: stock.csv
        - to: "azure-storage-files://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/exports?operation=uploadFile&directoryName=daily&accessKey=RAW({{env:AZURE_STORAGE_KEY:}})"
        - log: "uploaded daily/${header.CamelAzureStorageFilesFileName}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:export?repeatCount=1")
        .set_body(constant("sku,stock;A-1,12;B-7,0"))
        .set_header("CamelAzureStorageFilesFileName", constant("stock.csv"))
        .to("azure-storage-files://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/exports?operation=uploadFile&directoryName=daily&accessKey=RAW({{env:AZURE_STORAGE_KEY:}})")
        .log("uploaded daily/${header.CamelAzureStorageFilesFileName}");
})?;
```

## Options

Common Azure options (credentials, endpoint override, proxy) are described in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#azure-options). Shared Key and SAS are supported.

| option | default | description |
|---|---|---|
| `operation` | `listDirectoriesAndFiles` | `listShares`, `createShare`, `deleteShare`, `listDirectoriesAndFiles`, `createDirectory`, `deleteDirectory`, `uploadFile`, `downloadFile`, `getFileProperties`, `deleteFile`, `renameFile` (Cameleer). |
| `directoryName` | share root | Directory. |
| `fileName` | | File (the `CamelAzureStorageFilesFileName` header wins). |
| `prefix` | | Listing prefix. |
| `maxMessagesPerPoll` | `10` | Consumer: files per poll. |
| `delete` | `false` | Consumer: delete processed files (otherwise files already delivered, by name and ETag, are skipped). |
| `recursive`, `minDepth`, `maxDepth` | `false` | Consumer: descend into sub-directories. |
| `include`, `exclude` | | Consumer: regular expressions on file names. |
| `noop`, `idempotent`, `idempotentKey`, `idempotentRepository` | `false` | Consumer: leave files in place and remember them (`idempotentKey=name-etag` re-reads changed files). |
| `preMove`, `move`, `moveFailed` | | Consumer: rename files before processing, after success or after failure. |
| `fileExist` | `Override` | `uploadFile` when the file exists: `Override`, `Append`, `Fail`, `Ignore`, `Move` (into `moveExisting`). |
| `tempPrefix` | | Upload to a temporary name, then rename (atomic replace). |
| `autoCreate` | `true` | Create missing directories of `CamelFileName`. |
| `flatten` | `false` | Keep only the last segment of the file name. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAzureStorageFilesOperation` | in | Overrides `operation`. |
| `CamelAzureStorageFilesShareName`, `CamelAzureStorageFilesDirectoryName`, `CamelAzureStorageFilesFileName` | in/out | Location. |
| `CamelAzureStorageFilesPrefix`, `CamelAzureStorageFilesContentType` | in | Listing prefix, content type. |
| `CamelAzureStorageFilesContentLength`, `CamelAzureStorageFilesETag`, `CamelAzureStorageFilesLastModified` | out | File properties. |
| `CamelAzureStorageFilesRenameTo` | in | Target of `renameFile`. |
| `CamelFileName`, `CamelFileNameOnly`, `CamelFileParent`, `CamelFileRelativePath`, `CamelFileLength` | out | Consumer file headers. |

## Run it with Docker

```sh
docker run --rm -e AZURE_STORAGE_ACCOUNT -e AZURE_STORAGE_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/export.camel.yaml
```

## Common questions

### How do I avoid readers seeing half-written files?

Set `tempPrefix=.tmp-`: the file is uploaded under a temporary name and renamed when complete.

### Can I process files and keep them?

Yes: `noop=true` leaves them and remembers which ones were consumed (in memory, or in your
`idempotentRepository`).

## Related

- [Azure Storage Blob](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-blob.html), [Azure Data Lake Storage](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-datalake.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/azure-functions.html

# Azure Functions component

> The `azure-functions` component invokes HTTP-triggered Azure Functions and returns their response.

**Scheme:** `azure-functions:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** none (a Cameleer component)

## When to use it

- Call serverless business logic on Azure from a route and continue with the result.
- Expose an Azure Function to an AI agent as a tool behind a queue.
- Offload heavy processing from an edge gateway to a function.

## URI format

```text
azure-functions://functionApp/functionName[?options]
```

The request goes to `https://{functionApp}.azurewebsites.net/api/{functionName}`.

## Example

Score each lead of a queue with a function and parse its JSON answer:

```yaml
- route:
    id: score-leads
    from:
      uri: "azure-storage-queue://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/leads?accessKey=RAW({{env:AZURE_STORAGE_KEY:}})"
      steps:
        - to: "azure-functions://{{env:FUNCTION_APP:my-function-app}}/score-lead?functionKey=RAW({{env:FUNCTION_KEY:}})&parseJson=true"
        - log: "lead score ${body[score]} (HTTP ${header.CamelAzureFunctionsStatusCode})"
        - to: "log:scores"
```

The body is sent as is (maps and lists as JSON) with `POST`; the response text becomes the body, or
a map/list with `parseJson=true`.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("azure-storage-queue://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/leads?accessKey=RAW({{env:AZURE_STORAGE_KEY:}})")
        .to("azure-functions://{{env:FUNCTION_APP:my-function-app}}/score-lead?functionKey=RAW({{env:FUNCTION_KEY:}})&parseJson=true")
        .log("lead score ${body[score]} (HTTP ${header.CamelAzureFunctionsStatusCode})")
        .to("log:scores");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `functionKey` | | Function key, sent in the `x-functions-key` header. |
| `masterKey` | | Host master key (instead of a function key). |
| `keyInQuery` | `false` | Send the key as the `code` query parameter instead. |
| `httpMethod` | `POST` | HTTP method (`GET` and `DELETE` send no body). |
| `parseJson` | `false` | Parse JSON responses into maps and lists. |
| `credentialType`, `tenantId`, `clientId`, `clientSecret`, `scope` | | Microsoft Entra ID tokens for functions protected by App Service authentication. |
| `uriEndpointOverride` | | Base URL instead of `https://{functionApp}.azurewebsites.net` (for example the local Functions host). |
| `proxyHost`, `proxyPort`, `trustAllCertificates` | | Connection settings. |

Anonymous functions need no key. A non-2xx response raises an `HttpResponseException` with the status
in the message.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAzureFunctionsHttpMethod` | in | Overrides `httpMethod`. |
| `CamelAzureFunctionsQuery` | in | Extra query parameters (`a=1&b=2`). |
| `CamelAzureFunctionsStatusCode` | out | HTTP status. |
| `CamelAzureFunctionsContentType` | out | Content type of the response. |

## Run it with Docker

```sh
docker run --rm -e AZURE_STORAGE_ACCOUNT -e AZURE_STORAGE_KEY -e FUNCTION_APP -e FUNCTION_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/leads.camel.yaml
```

## Common questions

### How do I call a function running locally?

Run `func start` and set `uriEndpointOverride=http://localhost:7071`; the path `/api/{functionName}`
is added.

### How do I handle errors from the function?

Non-2xx responses throw, so `onException` or `doTry` in the route can catch them and retry or route
the message elsewhere.

## Related

- [AWS Lambda](https://pmsudhi.github.io/cameleer/docs/components/aws2-lambda.html), [Azure Storage Queue](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-queue.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/azure-key-vault.html

# Azure Key Vault component

> The `azure-key-vault` component manages secrets, keys and certificates in Azure Key Vault and signs, verifies, encrypts and decrypts with vault keys; the `{{azure:...}}` placeholder puts secrets into routes.

**Scheme:** `azure-key-vault:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [Azure Key Vault](https://camel.apache.org/components/next/azure-key-vault-component.html)

## When to use it

- Keep passwords and API keys out of route files: reference them as `{{azure:name}}`.
- Store credentials generated by a route as secrets.
- Sign or encrypt data with keys that never leave the vault (HSM-backed keys included).
- Restart routes automatically when a secret gets a new version (secret refresh).

## URI format

```text
azure-key-vault://vaultName[?options]
```

## Example

Store a partner token as a secret, authenticated with a service principal:

```yaml
- route:
    id: store-partner-token
    from:
      uri: "timer:store-token?repeatCount=1"
      steps:
        - setHeader:
            name: CamelAzureKeyVaultSecretName
            constant: partner-api-token
        - setBody:
            constant: "{{env:PARTNER_TOKEN:}}"
        - to: "azure-key-vault://{{env:AZURE_KEY_VAULT_NAME:my-vault}}?operation=createSecret&tenantId={{env:AZURE_TENANT_ID:}}&clientId={{env:AZURE_CLIENT_ID:}}&clientSecret=RAW({{env:AZURE_CLIENT_SECRET:}})"
        - log: "stored ${body} (version ${header.CamelAzureKeyVaultSecretVersion})"
```

Use a secret with the `{{azure:...}}` placeholder; it is resolved when the route starts:

```yaml
- route:
    id: call-partner-api
    from:
      uri: "timer:partner-sync?repeatCount=1"
      steps:
        - setHeader:
            name: Authorization
            constant: "Bearer {{azure:partner-api-token}}"
        - to: "log:partner-api"
```

The placeholder is configured with properties, for example in `application.properties`:

```properties
camel.vault.azure.vaultName=my-vault
camel.vault.azure.tenantId=00000000-0000-0000-0000-000000000000
camel.vault.azure.clientId=11111111-1111-1111-1111-111111111111
camel.vault.azure.clientSecret=change-me
# or, for managed identities and AZURE_* environment variables:
# camel.vault.azure.azureIdentityEnabled=true
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:store-token?repeatCount=1")
        .set_header("CamelAzureKeyVaultSecretName", constant("partner-api-token"))
        .set_body(constant("{{env:PARTNER_TOKEN:}}"))
        .to("azure-key-vault://{{env:AZURE_KEY_VAULT_NAME:my-vault}}?operation=createSecret&tenantId={{env:AZURE_TENANT_ID:}}&clientId={{env:AZURE_CLIENT_ID:}}&clientSecret=RAW({{env:AZURE_CLIENT_SECRET:}})")
        .log("stored ${body} (version ${header.CamelAzureKeyVaultSecretVersion})");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `operation` | `getSecret` | Secrets: `createSecret`, `getSecret`, `deleteSecret`, `purgeDeletedSecret`, `recoverDeletedSecret`, `listSecrets`. Keys (Cameleer): `createKey`, `importKey`, `getKey`, `listKeys`, `deleteKey`, `signData`, `verifyData`, `encrypt`, `decrypt`, `wrapKey`, `unwrapKey`. Certificates (Cameleer): `createCertificate`, `getCertificate`, `importCertificate`, `listCertificates`, `deleteCertificate`. |
| `credentialType` | `CLIENT_SECRET` | `CLIENT_SECRET` (`tenantId`, `clientId`, `clientSecret`) or `AZURE_IDENTITY` (environment client secret, workload identity or managed identity). |
| `tenantId`, `clientId`, `clientSecret` | | Service principal. |
| `authorityHost` | `https://login.microsoftonline.com` | Entra ID host (sovereign clouds). |
| `uriEndpointOverride`, `overrideEndpoint` | | Cameleer: vault URL instead of `https://{vaultName}.vault.azure.net`. |
| `proxyHost`, `proxyPort`, `trustAllCertificates` | | Connection settings. |

### The `{{azure:...}}` placeholder

| syntax | result |
|---|---|
| `{{azure:name}}` | The secret value. |
| `{{azure:name/field}}` | A field of a JSON secret. |
| `{{azure:name@version}}` | A specific version. |
| `{{azure:name:default}}` | A default when the secret does not exist. |

Properties: `camel.vault.azure.vaultName`, `clientId`, `clientSecret`, `tenantId`,
`azureIdentityEnabled`, and (Cameleer) `authorityHost`, `uriEndpointOverride`. Secret refresh:
`camel.vault.azure.refreshEnabled=true` with `camel.vault.azure.eventhubConnectionString` (an Event Hub
that Event Grid feeds with the vault's events), optional blob checkpoint properties
(`blobAccountName`, `blobContainerName`, `blobAccessKey`), `refreshPeriod` (ms, default 30000) and
`secrets` (names or `*` patterns).

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAzureKeyVaultOperation` | in | Overrides `operation`. |
| `CamelAzureKeyVaultSecretName`, `CamelAzureKeyVaultSecretVersion` | in/out | Secret and version (set by `createSecret`). |
| `CamelAzureKeyVaultKeyName`, `CamelAzureKeyVaultKeyVersion`, `CamelAzureKeyVaultKeyType`, `CamelAzureKeyVaultKeyCurve`, `CamelAzureKeyVaultKeySize`, `CamelAzureKeyVaultKeyOperations`, `CamelAzureKeyVaultKeyJwk` | in/out | Keys (type `EC` default, `RSA`, `EC-HSM`, `RSA-HSM`, `oct`, `oct-HSM`). |
| `CamelAzureKeyVaultSignatureAlgorithm`, `CamelAzureKeyVaultSignature` | in | `signData` / `verifyData` (`ES256` default, `RS256`, `PS256`, ...). |
| `CamelAzureKeyVaultEncryptionAlgorithm`, `CamelAzureKeyVaultIv`, `CamelAzureKeyVaultAuthenticationTag`, `CamelAzureKeyVaultAdditionalAuthenticatedData` | in/out | `encrypt`, `decrypt`, `wrapKey`, `unwrapKey`. |
| `CamelAzureKeyVaultCertificateName`, `CamelAzureKeyVaultCertificateVersion`, `CamelAzureKeyVaultCertificateSubject`, `CamelAzureKeyVaultCertificateValidityMonths`, `CamelAzureKeyVaultCertificatePassword` | in | Certificates. |

## Run it with Docker

```sh
docker run --rm -e AZURE_KEY_VAULT_NAME -e AZURE_TENANT_ID -e AZURE_CLIENT_ID -e AZURE_CLIENT_SECRET -e PARTNER_TOKEN \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/vault.camel.yaml
```

## Common questions

### How do I use a managed identity?

Use `credentialType=AZURE_IDENTITY` on the endpoint (and `camel.vault.azure.azureIdentityEnabled=true`
for the placeholder); the token comes from the managed identity endpoint, workload identity or the
`AZURE_*` variables.

### How do I sign data without exporting the key?

Create a key (`createKey`), then call `signData` with the data as the body: it is hashed locally and the
digest is signed by the vault; the body becomes the signature bytes.

## Related

- [AWS Secrets Manager](https://pmsudhi.github.io/cameleer/docs/components/aws-secrets-manager.html) (`{{aws:...}}`), [AWS KMS](https://pmsudhi.github.io/cameleer/docs/components/aws2-kms.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel Azure Key Vault](https://camel.apache.org/components/next/azure-key-vault-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/azure-openai.html

# Azure OpenAI component

> The `azure-openai` component calls models deployed on Azure OpenAI: chat completions (with streaming and tool calls), embeddings, image generation and the Assistants API.

**Scheme:** `azure-openai:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** none (Apache Camel reaches Azure OpenAI through LangChain4j; this is a Cameleer component)

## When to use it

- Answer, summarize or classify messages with GPT models deployed in your Azure tenant.
- Build AI agents: send a message list with tool definitions and handle the tool calls in the route.
- Create embeddings for search and retrieval.
- Run an Assistants API thread from a route (`runAssistant`).

## URI format

```text
azure-openai://resourceName/deploymentName[?options]
```

Requests go to `https://{resourceName}.openai.azure.com/openai/deployments/{deploymentName}/...`.

## Example

Answer questions from a Storage queue with a system prompt:

```yaml
- route:
    id: answer-questions
    from:
      uri: "azure-storage-queue://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/questions?accessKey=RAW({{env:AZURE_STORAGE_KEY:}})"
      steps:
        - to: "azure-openai://{{env:AZURE_OPENAI_RESOURCE:my-openai}}/{{env:AZURE_OPENAI_DEPLOYMENT:gpt-4o-mini}}?apiKey=RAW({{env:AZURE_OPENAI_API_KEY:}})&operation=chatCompletion&temperature=0.2&systemMessage=You answer customer questions about shipping in two sentences."
        - log: "answer (${header.CamelAzureOpenAIFinishReason}): ${body}"
        - to: "log:answers"
```

A text body becomes the user message (after the `systemMessage`); the body after the call is the
assistant's answer. Token usage and the model are in headers.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("azure-storage-queue://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/questions?accessKey=RAW({{env:AZURE_STORAGE_KEY:}})")
        .to("azure-openai://{{env:AZURE_OPENAI_RESOURCE:my-openai}}/{{env:AZURE_OPENAI_DEPLOYMENT:gpt-4o-mini}}?apiKey=RAW({{env:AZURE_OPENAI_API_KEY:}})&operation=chatCompletion&temperature=0.2&systemMessage=You answer customer questions about shipping in two sentences.")
        .log("answer (${header.CamelAzureOpenAIFinishReason}): ${body}")
        .to("log:answers");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `apiKey` | | API key (`api-key` header). |
| `credentialType`, `tenantId`, `clientId`, `clientSecret` | | Microsoft Entra ID client credentials instead of a key (scope `https://cognitiveservices.azure.com/.default`). |
| `apiVersion` | `2024-06-01` | REST API version. |
| `operation` | `chatCompletion` | `chatCompletion`, `chatCompletionStream`, `embeddings`, `imageGeneration`, `createAssistant`, `getAssistant`, `listAssistants`, `deleteAssistant`, `createThread`, `createMessage`, `listMessages`, `createRun`, `getRun`, `runAssistant`. |
| `systemMessage` | | System prompt for a text body. |
| `temperature`, `maxTokens`, `topP` | | Sampling settings. |
| `streaming` | `false` | Stream the chat answer (`text/event-stream`). |
| `streamOutputMode` | `complete` | `complete` (body = whole text) or `chunks` (list of deltas). |
| `streamingChunkProcessor` | | `#bean` of a processor called for every delta while streaming. |
| `imageSize`, `imageCount`, `imageQuality`, `imageResponseFormat` | `1024x1024`, , , `url` | `imageGeneration` settings (`url` or `b64_json`). |
| `assistantsApiVersion` | `2024-05-01-preview` | API version of the Assistants operations. |
| `runPollInterval`, `runTimeout` | `200`, `60000` | Polling of `runAssistant` (ms). |
| `uriEndpointOverride`, `proxyHost`, `proxyPort`, `trustAllCertificates` | | Connection settings (for example an API gateway in front of Azure OpenAI). |

A list body is sent as the message list (`{role, content}` maps); a map body is sent as the request.
For `embeddings` a text body gives one vector and a list body a list of vectors.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAzureOpenAIOperation` | in | Overrides `operation`. |
| `CamelAzureOpenAISystemMessage` | in | Overrides `systemMessage`. |
| `CamelAzureOpenAIStreaming` | in | Overrides `streaming`. |
| `CamelAzureOpenAIFinishReason` | out | `stop`, `length`, `tool_calls`, ... |
| `CamelAzureOpenAIUsage` | out | Token usage (map). |
| `CamelAzureOpenAIModel` | out | Model that answered. |
| `CamelAzureOpenAIToolCalls` | out | Tool calls requested by the model. |
| `CamelAzureOpenAIStreamingChunkCount`, `CamelAzureOpenAIStreamingChunkIndex` | out | Streaming. |
| `CamelAzureOpenAIImageSize`, `CamelAzureOpenAIRevisedPrompts` | in/out | Image generation. |
| `CamelAzureOpenAIAssistantId`, `CamelAzureOpenAIAssistantName`, `CamelAzureOpenAIThreadId`, `CamelAzureOpenAIRunId`, `CamelAzureOpenAIRunStatus` | in/out | Assistants API. |

## Run it with Docker

```sh
docker run --rm -e AZURE_STORAGE_ACCOUNT -e AZURE_STORAGE_KEY -e AZURE_OPENAI_RESOURCE -e AZURE_OPENAI_DEPLOYMENT -e AZURE_OPENAI_API_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/answers.camel.yaml
```

## Common questions

### How do I let the model call tools?

Send a map body with `messages` and `tools` (OpenAI function definitions). When the model calls a tool,
`CamelAzureOpenAIFinishReason` is `tool_calls` and `CamelAzureOpenAIToolCalls` lists the calls; run
them in the route and send the next request with the tool results.

### Can I use OpenAI or a local model instead?

Use the `openai` component for OpenAI-compatible APIs (OpenAI, Ollama, vLLM); `azure-openai` speaks
the Azure deployment URLs and authentication.

## Related

- [AWS Bedrock](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html), [AWS Bedrock Agent Runtime](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock-agent-runtime.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/azure-schema-registry.html

# Azure Schema Registry component

> The `azure-schema-registry` component registers and looks up Avro, JSON and custom schemas in the Azure Event Hubs Schema Registry.

**Scheme:** `azure-schema-registry:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** none (Apache Camel offers the registry only as a Kafka serializer library; this is a Cameleer component)

## When to use it

- Register the schema of the events a route produces, as part of a deployment.
- Look up a schema by id when a message carries only the schema id.
- List the versions of a schema for compatibility checks.

## URI format

```text
azure-schema-registry://namespace/group[?options]
```

`namespace` is the Event Hubs namespace (`myns` means `https://myns.servicebus.windows.net`, or give a
fully qualified name); `group` is the schema group.

## Example

Register an Avro schema when the route starts:

```yaml
- route:
    id: register-order-schema
    from:
      uri: "timer:register-schema?repeatCount=1"
      steps:
        - setBody:
            constant: '{"type":"record","name":"Order","namespace":"com.example","fields":[{"name":"id","type":"string"},{"name":"total","type":"double"}]}'
        - to: "azure-schema-registry://{{env:EVENTHUBS_NAMESPACE:my-namespace}}/orders?operation=registerSchema&schemaName=com.example.Order&tenantId={{env:AZURE_TENANT_ID:}}&clientId={{env:AZURE_CLIENT_ID:}}&clientSecret=RAW({{env:AZURE_CLIENT_SECRET:}})"
        - log: "schema id ${body}, version ${header.CamelAzureSchemaRegistrySchemaVersion}"
        - to: "log:schemas"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:register-schema?repeatCount=1")
        .set_body(constant(r#"{"type":"record","name":"Order","namespace":"com.example","fields":[{"name":"id","type":"string"},{"name":"total","type":"double"}]}"#))
        .to("azure-schema-registry://{{env:EVENTHUBS_NAMESPACE:my-namespace}}/orders?operation=registerSchema&schemaName=com.example.Order&tenantId={{env:AZURE_TENANT_ID:}}&clientId={{env:AZURE_CLIENT_ID:}}&clientSecret=RAW({{env:AZURE_CLIENT_SECRET:}})")
        .log("schema id ${body}, version ${header.CamelAzureSchemaRegistrySchemaVersion}")
        .to("log:schemas");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `operation` | `getSchema` | `registerSchema`, `getSchemaProperties` (id of the body's definition), `getSchema` (by id), `getSchemaByVersion`, `listVersions`, `listGroups`. |
| `schemaName` | | Schema name. |
| `schemaId` | | Schema id of `getSchema`. |
| `format` | `Avro` | `Avro`, `Json` or `Custom`. |
| `credentialType` | `CLIENT_SECRET` | `CLIENT_SECRET` (`tenantId`, `clientId`, `clientSecret`, `authorityHost`) or `AZURE_IDENTITY`. |
| `uriEndpointOverride`, `proxyHost`, `proxyPort`, `trustAllCertificates` | | Connection settings. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAzureSchemaRegistryOperation` | in | Overrides `operation`. |
| `CamelAzureSchemaRegistrySchemaName`, `CamelAzureSchemaRegistryFormat` | in/out | Name and format. |
| `CamelAzureSchemaRegistrySchemaId` | in/out | Schema id. |
| `CamelAzureSchemaRegistrySchemaVersion` | in/out | Version (input of `getSchemaByVersion`). |
| `CamelAzureSchemaRegistrySchemaGroup` | out | Group of the schema. |

## Run it with Docker

```sh
docker run --rm -e EVENTHUBS_NAMESPACE -e AZURE_TENANT_ID -e AZURE_CLIENT_ID -e AZURE_CLIENT_SECRET \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/schemas.camel.yaml
```

## Common questions

### Does it serialize Kafka or Event Hubs messages?

No. It manages schemas through the REST API; serialize with the `avro` or `json` data formats and use
the schema id in a header.

## Related

- [Azure Event Hubs](https://pmsudhi.github.io/cameleer/docs/components/azure-eventhubs.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/azure-servicebus.html

# Azure Service Bus component

> The `azure-servicebus` component sends messages to and receives messages from Azure Service Bus queues and topic subscriptions over AMQP 1.0, with peek-lock, sessions, scheduling, dead-lettering and transactions.

**Scheme:** `azure-servicebus:` · **Crate:** `cameleer-amqp10` · **Cargo feature:** [`amqp10`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [Azure ServiceBus](https://camel.apache.org/components/next/azure-servicebus-component.html)

## When to use it

- Reliable enterprise messaging between services on Azure (orders, payments, commands).
- Publish to a topic and let several subscriptions process the same message.
- Ordered processing per customer or device with sessions.
- Schedule messages for later delivery, or defer them and fetch them by sequence number.

## URI format

```text
azure-servicebus:queueOrTopicName[?options]
```

Authenticate with a `connectionString`, with `fullyQualifiedNamespace` + `sharedAccessName` +
`sharedAccessKey`, or with Microsoft Entra ID (`credentialType=AZURE_IDENTITY`).

## Example

Send an order to a queue:

```yaml
- route:
    id: send-order
    from:
      uri: "timer:new-order?repeatCount=1"
      steps:
        - setBody:
            constant: '{"orderId":"o-1001","item":"camel saddle"}'
        - setHeader:
            name: CamelAzureServiceBusContentType
            constant: application/json
        - to: "azure-servicebus:orders?connectionString=RAW({{env:SERVICEBUS_CONNECTION_STRING:Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=change-me}})"
```

Process the queue with peek-lock. A message is completed when the route succeeds, and abandoned
(redelivered) when it fails:

```yaml
- route:
    id: process-orders
    from:
      uri: "azure-servicebus:orders?connectionString=RAW({{env:SERVICEBUS_CONNECTION_STRING:Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=change-me}})&maxConcurrentCalls=4"
      steps:
        - log: "order ${header.CamelAzureServiceBusMessageId} (delivery ${header.CamelAzureServiceBusDeliveryCount}): ${body}"
        - to: "log:orders"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("azure-servicebus:orders?connectionString=RAW({{env:SERVICEBUS_CONNECTION_STRING:Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=change-me}})&maxConcurrentCalls=4")
        .log("order ${header.CamelAzureServiceBusMessageId} (delivery ${header.CamelAzureServiceBusDeliveryCount}): ${body}")
        .to("log:orders");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `connectionString` | | Namespace connection string (`Endpoint=sb://...;SharedAccessKeyName=...;SharedAccessKey=...`; `UseDevelopmentEmulator=true` for the emulator). |
| `fullyQualifiedNamespace`, `sharedAccessName`, `sharedAccessKey` | | Instead of a connection string. |
| `credentialType` | `CONNECTION_STRING` | `CONNECTION_STRING`, `AZURE_IDENTITY` (environment, client secret or managed identity; options `tenantId`, `clientId`, `clientSecret`, `authorityHost`, `managedIdentityEndpoint`, `managedIdentityClientId`) or `TOKEN_CREDENTIAL` (`tokenCredential=#bean`). |
| `amqpTransportType` | `AMQP` | `AMQP` (port 5671) or `AMQP_WEB_SOCKETS` (port 443). |
| `serviceBusType` | `queue` | `queue` or `topic`. |
| `subscriptionName` | | Subscription of a topic consumer. |
| `receiveMode` | `PEEK_LOCK` | `PEEK_LOCK` or `RECEIVE_AND_DELETE`. |
| `consumerOperation` | `receiveMessages` | `receiveMessages` or `peekMessages` (without locking; `peekNumMaxMessages` per poll, default 10). |
| `producerOperation` | `sendMessages` | `sendMessages`, `scheduleMessages`, and the Cameleer operations `receiveDeferredMessages`, `getSessionState`, `setSessionState`. |
| `scheduledEnqueueTime` | | Enqueue time of `scheduleMessages` (epoch millis or ISO-8601). |
| `prefetchCount` | `0` | Messages to prefetch. |
| `maxConcurrentCalls` | `1` | Parallel receivers. |
| `subQueue` | `NONE` | `DEAD_LETTER_QUEUE` reads the dead-letter queue. |
| `enableDeadLettering` | `false` | Dead-letter failed messages instead of abandoning them. |
| `disableAutoComplete` | `false` | Do not settle automatically (use `CamelAzureServiceBusDisposition`). |
| `maxAutoLockRenewDuration` | `PT5M` | Renew message and session locks while processing (0 disables). |
| `sessionEnabled`, `sessionId`, `sessionIdleTimeout` | `false`, , 1 s | Sessions: accept any or one session; release it after the idle timeout (Cameleer). |
| `transacted` | `false` | Cameleer: send the messages of an exchange in one AMQP transaction. |
| `binary` | `false` | Send the body as binary. |
| `sasTokenTtl`, `idleTimeout`, `requestTimeout`, `recoveryInterval`, `delay` | | Connection and polling timings. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAzureServiceBusMessageId`, `CamelAzureServiceBusCorrelationId`, `CamelAzureServiceBusContentType`, `CamelAzureServiceBusSubject`, `CamelAzureServiceBusTo`, `CamelAzureServiceBusReplyTo`, `CamelAzureServiceBusSessionId`, `CamelAzureServiceBusPartitionKey`, `CamelAzureServiceBusTimeToLive` | in/out | Message properties. |
| `CamelAzureServiceBusApplicationProperties` | in/out | Application properties (map). |
| `CamelAzureServiceBusReplyToSessionId` | out | Reply-to session. |
| `CamelAzureServiceBusEnqueuedTime`, `CamelAzureServiceBusLockedUntil`, `CamelAzureServiceBusExpiresAt` | out | Times (epoch millis). |
| `CamelAzureServiceBusSequenceNumber` | in/out | Sequence number (set by `scheduleMessages`, input of `receiveDeferredMessages`). |
| `CamelAzureServiceBusDeliveryCount`, `CamelAzureServiceBusLockToken` | out | Delivery count and lock token. |
| `CamelAzureServiceBusDeadLetterReason`, `CamelAzureServiceBusDeadLetterErrorDescription`, `CamelAzureServiceBusDeadLetterSource` | out | Dead-letter details. |
| `CamelAzureServiceBusScheduledEnqueueTime`, `CamelAzureServiceBusProducerOperation` | in | Producer overrides. |
| `CamelAzureServiceBusDisposition` | in | Cameleer: settle explicitly with `complete`, `abandon`, `deadLetter` or `defer`. |

## Run it with Docker

```sh
docker run --rm -e SERVICEBUS_CONNECTION_STRING \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

## Common questions

### How do I consume a topic subscription?

`azure-servicebus:events?serviceBusType=topic&subscriptionName=billing&connectionString=...`.

### How do I read the dead-letter queue?

Add `subQueue=DEAD_LETTER_QUEUE`; the dead-letter reason and description are in headers.

### Does it work with the Service Bus emulator?

Yes: a connection string with `UseDevelopmentEmulator=true` uses plain AMQP to the emulator.

## Related

- [Azure Event Hubs](https://pmsudhi.github.io/cameleer/docs/components/azure-eventhubs.html), [Azure Storage Queue](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-queue.html)
- [AWS SQS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel Azure Service Bus](https://camel.apache.org/components/next/azure-servicebus-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/azure-storage-blob.html

# Azure Storage Blob component

> The `azure-storage-blob` component uploads, downloads, lists, copies and deletes blobs in Azure Blob Storage (block, append and page blobs), and polls a container for new blobs.

**Scheme:** `azure-storage-blob:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [Azure Storage Blob Service](https://camel.apache.org/components/next/azure-storage-blob-component.html)

## When to use it

- Archive files, reports and message payloads in Azure.
- Read files that partners drop into a container, then delete them.
- Append log lines to an append blob from many routes or devices.
- React to every blob change in an account with the change feed consumer.

## URI format

```text
azure-storage-blob://accountName[/containerName][?options]
```

## Example

Upload a daily report. The blob name comes from the `CamelAzureStorageBlobBlobName` header (or the
`blobName` option):

```yaml
- route:
    id: upload-report
    from:
      uri: "timer:daily-report?repeatCount=1"
      steps:
        - setBody:
            constant: "region,total;eu,42;us,17"
        - setHeader:
            name: CamelAzureStorageBlobBlobName
            simple: "reports/${date:now:yyyy-MM-dd}.csv"
        - setHeader:
            name: CamelAzureStorageBlobContentType
            constant: text/csv
        - to: "azure-storage-blob://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/reports?operation=uploadBlockBlob&accessKey=RAW({{env:AZURE_STORAGE_KEY:}})"
        - log: "uploaded ${header.CamelAzureStorageBlobBlobName} (etag ${header.CamelAzureStorageBlobETag})"
```

Poll a container and delete each blob after it was processed:

```yaml
- route:
    id: incoming-blobs
    from:
      uri: "azure-storage-blob://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/incoming?accessKey=RAW({{env:AZURE_STORAGE_KEY:}})&deleteAfterRead=true"
      steps:
        - log: "received ${header.CamelAzureStorageBlobBlobName} (${header.CamelAzureStorageBlobBlobSize} bytes)"
        - to: "log:incoming"
```

Instead of the account key you can use a SAS token (`sasToken=RAW(...)`) or Microsoft Entra ID
(`credentialType=AZURE_IDENTITY`, for managed identities); see
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#azure).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("azure-storage-blob://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/incoming?accessKey=RAW({{env:AZURE_STORAGE_KEY:}})&deleteAfterRead=true")
        .log("received ${header.CamelAzureStorageBlobBlobName} (${header.CamelAzureStorageBlobBlobSize} bytes)")
        .to("log:incoming");
})?;
```

## Options

Common Azure options (`accessKey`, `sasToken`, `credentialType`, Entra ID options,
`uriEndpointOverride`, `overrideEndpoint`, `proxyHost`, `proxyPort`, `trustAllCertificates`) are
described in [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#azure-options).

| option | default | description |
|---|---|---|
| `operation` | `listBlobContainers` | Containers: `listBlobContainers`, `createBlobContainer`, `deleteBlobContainer`. Blobs: `listBlobs`, `uploadBlockBlob`, `getBlob`, `deleteBlob`, `downloadBlobToFile`, `downloadLink`, `copyBlob`, `stageBlockBlobList`, `commitBlobBlockList`, `getBlobBlockList`. Append blobs: `createAppendBlob`, `commitAppendBlob`. Page blobs: `createPageBlob`, `uploadPageBlob`, `resizePageBlob`, `clearPageBlob`, `getPageBlobRanges`. Leases (Cameleer): `acquireBlobLease`, `renewBlobLease`, `releaseBlobLease`, `breakBlobLease`. Change feed: `getChangeFeed`. |
| `blobName` | | Blob (the `CamelAzureStorageBlobBlobName` header wins). |
| `prefix` | | `listBlobs` and consumer: only blobs with this prefix. |
| `maxResultsPerPage` | | Page size of listings (all pages are read). |
| `deleteAfterRead` | `false` | Cameleer: consumer deletes blobs after successful processing (otherwise it reads the container again on every poll, as in Camel). |
| `createAppendBlob` | `true` | `commitAppendBlob` creates the blob when missing. |
| `createPageBlob` | `true` | `uploadPageBlob` creates the blob when missing. |
| `pageBlobSize` | `512` | Size of `createPageBlob`. |
| `leaseBlob` | `false` | Hold a lease while writing or deleting. |
| `leaseDurationInSeconds` | `60` | Lease duration (-1 = infinite). |
| `commitBlockListLater` | `true` | `stageBlockBlobList` stages without committing. |
| `blockListType` | `COMMITTED` | `getBlobBlockList`: `COMMITTED`, `UNCOMMITTED` or `ALL`. |
| `fileDir` | | Target directory of `downloadBlobToFile`. |
| `downloadLinkExpiration` | 1 hour | Validity (ms) of `downloadLink`. |
| `sourceBlobAccessKey` | | Key of the source account of a cross-account `copyBlob`. |
| `changeFeed` | `false` | Cameleer: consume the account's change feed instead of a container. |
| `changeFeedStartTime`, `changeFeedEndTime` | | Change feed window (epoch millis or ISO-8601). |

The consumer also accepts the scheduled poll options (`delay`, `initialDelay`, `scheduler.cron`, ...).

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAzureStorageBlobOperation` | in | Overrides `operation`. |
| `CamelAzureStorageBlobBlobName`, `CamelAzureStorageBlobContainerName` | in/out | Blob and container. |
| `CamelAzureStorageBlobContentType`, `CamelAzureStorageBlobMetadata` | in/out | Content type and metadata (map, `x-ms-meta-*`). |
| `CamelAzureStorageBlobETag`, `CamelAzureStorageBlobLastModified`, `CamelAzureStorageBlobBlobSize`, `CamelAzureStorageBlobContentMD5`, `CamelAzureStorageBlobBlobType` | out | Blob properties. |
| `CamelAzureStorageBlobPrefix` | in | Listing prefix. |
| `CamelAzureStorageBlobPageBlobRange`, `CamelAzureStorageBlobPageBlobSize`, `CamelAzureStorageBlobCreateAppendBlob`, `CamelAzureStorageBlobCreatePageBlob` | in | Append and page blobs. |
| `CamelAzureStorageBlobCommittedBlockCount` | out | Blocks of an append blob. |
| `CamelAzureStorageBlobLeaseId`, `CamelAzureStorageBlobLeaseDuration` | in/out | Leases. |
| `CamelAzureStorageBlobBlockIds`, `CamelAzureStorageBlobCommitBlobBlockListLater`, `CamelAzureStorageBlobBlockListType` | in/out | Block lists. |
| `CamelAzureStorageBlobDownloadLink`, `CamelAzureStorageBlobDownloadLinkExpiration` | in/out | `downloadLink`. |
| `CamelAzureStorageBlobFileDir`, `CamelAzureStorageBlobFileName` | in | `downloadBlobToFile`. |
| `CamelAzureStorageBlobSourceBlobAccountName`, `CamelAzureStorageBlobSourceBlobContainerName`, `CamelAzureStorageBlobSourceBlobName`, `CamelAzureStorageBlobCopyId`, `CamelAzureStorageBlobCopyStatus` | in/out | `copyBlob`. |
| `CamelAzureStorageBlobChangeFeedStartTime`, `CamelAzureStorageBlobChangeFeedEndTime`, `CamelAzureStorageBlobChangeFeedEventType`, `CamelAzureStorageBlobChangeFeedEventTime`, `CamelAzureStorageBlobChangeFeedEventId` | in/out | Change feed. |

## Run it with Docker

```sh
docker run --rm -e AZURE_STORAGE_ACCOUNT -e AZURE_STORAGE_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/blobs.camel.yaml
```

## Common questions

### Why do I get `ContainerNotFound`?

Uploads do not create the container. Create it once with `operation=createBlobContainer` (or in the
portal or your infrastructure code).

### How do I test against Azurite?

Use the account `devstoreaccount1` with Azurite's well-known key and add
`uriEndpointOverride=http://127.0.0.1:10000&overrideEndpoint=true`; requests then use Azurite's path
style (`http://127.0.0.1:10000/devstoreaccount1/...`).

### How do I share a blob with someone for an hour?

Use `operation=downloadLink`: the body becomes a read-only SAS URL valid for
`downloadLinkExpiration` milliseconds (default one hour).

### How do I use a managed identity?

Set `credentialType=AZURE_IDENTITY` and drop the key: tokens come from the environment, workload
identity or the managed identity endpoint.

## Related

- [Azure Storage Queue](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-queue.html), [Azure Data Lake Storage](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-datalake.html), [Azure Files](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-files.html)
- [AWS S3](https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel Azure Storage Blob](https://camel.apache.org/components/next/azure-storage-blob-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/azure-storage-queue.html

# Azure Storage Queue component

> The `azure-storage-queue` component sends messages to and receives messages from Azure Queue Storage.

**Scheme:** `azure-storage-queue:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [Azure Storage Queue Service](https://camel.apache.org/components/next/azure-storage-queue-component.html)

## When to use it

- A simple, cheap work queue between services on Azure.
- Hand jobs from Azure Functions or Logic Apps to a Cameleer worker, and back.
- Buffer messages from edge devices with an account key or a SAS token.

For topics, sessions and transactions, use [Azure Service Bus](https://pmsudhi.github.io/cameleer/docs/components/azure-servicebus.html).

## URI format

```text
azure-storage-queue://accountName/queueName[?options]
```

## Example

Send a job (the queue is created when it does not exist):

```yaml
- route:
    id: send-job
    from:
      uri: "timer:new-job?repeatCount=1"
      steps:
        - setBody:
            constant: '{"job":"resize","image":"cat.jpg"}'
        - to: "azure-storage-queue://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/jobs?operation=sendMessage&createQueue=true&accessKey=RAW({{env:AZURE_STORAGE_KEY:}})"
        - log: "queued message ${header.CamelAzureStorageQueueMessageId}"
```

Work through the queue. Each message is deleted after it was processed successfully:

```yaml
- route:
    id: job-worker
    from:
      uri: "azure-storage-queue://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/jobs?maxMessages=10&visibilityTimeout=PT60S&accessKey=RAW({{env:AZURE_STORAGE_KEY:}})"
      steps:
        - log: "job ${header.CamelAzureStorageQueueMessageId} (dequeued ${header.CamelAzureStorageQueueDequeueCount}x): ${body}"
        - to: "log:jobs"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("azure-storage-queue://{{env:AZURE_STORAGE_ACCOUNT:mystorageaccount}}/jobs?maxMessages=10&visibilityTimeout=PT60S&accessKey=RAW({{env:AZURE_STORAGE_KEY:}})")
        .log("job ${header.CamelAzureStorageQueueMessageId} (dequeued ${header.CamelAzureStorageQueueDequeueCount}x): ${body}")
        .to("log:jobs");
})?;
```

## Options

Common Azure options (credentials, endpoint override, proxy) are described in
[Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html#azure-options).

| option | default | description |
|---|---|---|
| `operation` | `sendMessage` | `listQueues`, `createQueue`, `deleteQueue`, `clearQueue`, `sendMessage`, `receiveMessages`, `peekMessages`, `deleteMessage`, `updateMessage`. |
| `createQueue` | `false` | `sendMessage` creates the queue first. |
| `maxMessages` | `1` | Messages per poll (consumer) or per `receiveMessages` / `peekMessages`. |
| `visibilityTimeout` | | Visibility timeout (ISO-8601 duration such as `PT60S`, or seconds). |
| `timeToLive` | | Time to live of sent messages. |

The consumer also accepts the scheduled poll options. Message text is sent as is (not base64),
like the Azure SDK v12.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelAzureStorageQueueOperation` | in | Overrides `operation`. |
| `CamelAzureStorageQueueName` | in | Overrides the queue. |
| `CamelAzureStorageQueueMessageId`, `CamelAzureStorageQueuePopReceipt` | in/out | Message; input of `deleteMessage` and `updateMessage`. |
| `CamelAzureStorageQueueVisibilityTimeout`, `CamelAzureStorageQueueTimeToLive`, `CamelAzureStorageQueueMaxMessages` | in | Override the options. |
| `CamelAzureStorageQueueInsertionTime`, `CamelAzureStorageQueueExpirationTime`, `CamelAzureStorageQueueTimeNextVisible` | out | Message times. |
| `CamelAzureStorageQueueDequeueCount` | out | How often the message was received. |

## Run it with Docker

```sh
docker run --rm -e AZURE_STORAGE_ACCOUNT -e AZURE_STORAGE_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/jobs.camel.yaml
```

## Common questions

### What happens when a job fails?

The message is not deleted. It becomes visible again after the visibility timeout and
`CamelAzureStorageQueueDequeueCount` grows, so the route can move poison messages away after a few tries.

### Are messages base64 encoded?

No. Text is sent as is. Azure Functions queue triggers expect base64 by default; configure the
function's `messageEncoding` to `none`, or encode the body with the `base64` data format.

## Related

- [Azure Service Bus](https://pmsudhi.github.io/cameleer/docs/components/azure-servicebus.html), [Azure Storage Blob](https://pmsudhi.github.io/cameleer/docs/components/azure-storage-blob.html)
- [AWS SQS](https://pmsudhi.github.io/cameleer/docs/components/aws2-sqs.html)
- [Cloud credentials](https://pmsudhi.github.io/cameleer/docs/guides/cloud-credentials.html)
- [Apache Camel Azure Storage Queue](https://camel.apache.org/components/next/azure-storage-queue-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/bean.html

# Bean component

> The `bean` component calls your own Rust code, registered in the registry under a name, from a route.

**Scheme:** `bean:` · **Also:** `class:` (see [class](https://pmsudhi.github.io/cameleer/docs/components/class.html)) · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Bean](https://camel.apache.org/components/next/bean-component.html)

## When to use it

- Put business logic (pricing, scoring, validation) in plain Rust functions and call them from YAML or Rust routes.
- Give an AI agent route a deterministic tool, such as a fraud score, that runs in-process.
- Reuse one service object with several named methods (`?method=score`, `?method=explain`).

## URI format

```text
bean:beanName[?method=name]
```

## Example

```yaml
- route:
    id: score-payment
    from:
      uri: direct:score
      steps:
        - to: bean:fraudScorer?method=score
        - setBody:
            simple: "risk=${body}"
```

The bean is registered from Rust before the routes start. Methods added with `method_value` return the
new body:

```rust
use cameleer_core::component::bean::{bind_bean, BeanMethods};
use cameleer_core::prelude::*;

pub fn register(ctx: &CamelContext) {
    let scorer = BeanMethods::new()
        .method_value("score", |ex: &Exchange| {
            let amount: f64 = ex.body().to_string().parse().unwrap_or(0.0);
            Ok(Value::from(if amount > 1000.0 { "high" } else { "low" }))
        })
        .method("tag", |ex: &mut Exchange| {
            ex.set_header("scored", true);
            Ok(())
        });
    bind_bean(ctx.registry(), "fraudScorer", scorer);
}
```

Sending `2500` to `direct:score` returns `risk=high`.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:score")
            .route_id("score-payment")
            .to("bean:fraudScorer?method=score")
            .set_body(simple("risk=${body}"));
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `method` | | The method to call. `score(${body})` is read as `score`; argument binding is up to the bean. Without it, the bean's only or default method is called. |
| `scope`, `cache`, `multiParameterArray`, `lazyStartProducer`, `parameters.*`, `bean.*` | | Accepted and ignored. |

A registry entry can be:

- a `BeanMethods` value: named closures (`method` works on the exchange, `method_value` returns the body);
- any type implementing the `Bean` trait, bound with `bind_bean`;
- a `Processor` bound with `Registry::bind_processor` (the method name is ignored).

## Message headers

| header | direction | description |
|---|---|---|
| `CamelBeanMethodName` | in | Overrides the `method` option for this message. |

## Run it with Docker

Beans are Rust code, so they need a Rust program that registers them (build your own binary with
`cameleer-main` and call `bind_bean` in `main.configure(...)`). The stock `pmsudhi/cameleer` image has no
custom beans; use [language](https://pmsudhi.github.io/cameleer/docs/components/language.html) or a `script` step there instead.

## Common questions

### Why do I get NoSuchBeanException?

Nothing is bound under that name in the registry. Bind it before the route first uses it.

### How do I call a different method per message?

Set the header `CamelBeanMethodName`, for example from a `choice`.

### What happens when the method does not exist?

The exchange fails with `MethodNotFoundException`, which lists the methods of the bean.

## Related

- [class](https://pmsudhi.github.io/cameleer/docs/components/class.html), [ref](https://pmsudhi.github.io/cameleer/docs/components/ref.html), [language](https://pmsudhi.github.io/cameleer/docs/components/language.html)
- [Apache Camel Bean component](https://camel.apache.org/components/next/bean-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/browse.html

# Browse component

> The `browse` component keeps the messages sent to it in memory so they can be listed later, and passes them on to a consuming route if there is one.

**Scheme:** `browse:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Browse](https://camel.apache.org/components/next/browse-component.html)

## When to use it

- Keep the last rejected or failed messages for inspection while debugging.
- Show recent messages of a route on a status page or to an operator tool.
- Record what passed a point in a route during development.

## URI format

```text
browse:name[?options]
```

## Example

```yaml
- route:
    id: record-rejections
    from:
      uri: direct:reject
      steps:
        - setHeader:
            name: rejectedAt
            simple: "${date:now:yyyy-MM-dd'T'HH:mm:ss}"
        - to: browse:rejected?browseLimit=100
```

The last 100 rejected messages are kept. List them from Rust with
`cameleer_core::component::browse::browse_exchanges(&ctx, "browse:rejected?browseLimit=100")`.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:reject")
            .route_id("record-rejections")
            .set_header("rejectedAt", simple("${date:now:yyyy-MM-dd'T'HH:mm:ss}"))
            .to("browse:rejected?browseLimit=100");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `browseLimit` | unlimited | Maximum number of exchanges kept; older ones are dropped. |
| `synchronous` | | Accepted and ignored. |

## Message headers

None added.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/rejections.camel.yaml
```

## Common questions

### Does browse keep messages after a restart?

No. They are in memory only. Write them to a file or a broker when you need to keep them.

### Can another route consume from a browse endpoint?

Yes. `from: browse:rejected` receives each message synchronously as it is sent, and the message is still
kept for browsing.

## Related

- [mock](https://pmsudhi.github.io/cameleer/docs/components/mock.html), [log](https://pmsudhi.github.io/cameleer/docs/components/log.html), [seda](https://pmsudhi.github.io/cameleer/docs/components/seda.html)
- [Apache Camel Browse component](https://camel.apache.org/components/next/browse-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/cql.html

# Cassandra CQL component

> The `cql` component runs CQL statements against Apache Cassandra and ScyllaDB, and polls a CQL query on a schedule.

**Scheme:** `cql:` · **Crate:** `cameleer-datastores` · **Cargo feature:** [`datastores`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [Cassandra CQL](https://camel.apache.org/components/next/cql-component.html)

## When to use it

- Write time-series or event data (sensor readings at the edge, click streams, agent run
  logs) into a Cassandra table partitioned by day or device.
- Read rows by partition key in the middle of a route.
- Poll a small table on a schedule, for example a configuration or feature-flag table.

## URI format

```text
cql://host1,host2:port/keyspace?cql=<statement>[&options]
cql:bean:<sessionBean>?cql=<statement>[&options]
```

A port on the last host applies to all hosts (`cql://a,b,c:9042/shop`); the default is 9042.
`cql:bean:name` uses a `CqlSession` bound in the registry.

The producer runs `cql` (or the `CamelCqlQuery` header) as a prepared statement with the
message body as bind values: a list for several `?` markers, a single value for one, nothing
for a null body. The result goes to the body according to `resultSetConversionStrategy`.

The client is Cameleer's own implementation of the CQL native protocol v4: PasswordAuthenticator,
prepared statements (re-prepared when the server forgets them), paging, TLS, LZ4 and Snappy
compression and token-aware routing.

## Example

`POST /events` with `{"day":"2026-11-05","seq":1,"msg":"door opened"}` inserts a row. The `jq`
step turns the JSON object into the list of bind values.

```yaml
- route:
    id: save-event
    from:
      uri: "platform-http:/events?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - setBody:
            jq: "[.day, .seq, .msg]"
        - to: "cql://{{env:CASSANDRA_HOSTS:localhost:9042}}/iot?cql=INSERT INTO events (day, seq, msg) VALUES (?, ?, ?)&consistencyLevel=QUORUM"
        - setBody:
            constant: "saved"
```

The table:

```sql
CREATE KEYSPACE iot WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};
CREATE TABLE iot.events (day text, seq int, msg text, PRIMARY KEY ((day), seq));
```

This route polls one partition every 10 seconds and logs each row. Each poll sends the whole
result set as one exchange (a list of row maps), so `split` handles the rows one by one.

```yaml
- route:
    id: poll-events
    from:
      uri: "cql://{{env:CASSANDRA_HOSTS:localhost:9042}}/iot?cql=SELECT seq, msg FROM events WHERE day = '2026-11-05'&delay=10000"
      steps:
        - split:
            simple: "${body}"
            steps:
              - to: "log:events"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("direct:event")
        .to("cql://localhost:9042/iot?cql=INSERT INTO events (day, seq, msg) VALUES (?, ?, ?)");
    b.from("direct:day")
        .to("cql://localhost:9042/iot?cql=SELECT seq, msg FROM events WHERE day = ?&resultSetConversionStrategy=LIMIT_10");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `cql` | | the statement (header `CamelCqlQuery` overrides it) |
| `consistencyLevel` | `LOCAL_ONE` | `ANY`, `ONE`, `TWO`, `THREE`, `QUORUM`, `ALL`, `LOCAL_QUORUM`, `EACH_QUORUM`, `LOCAL_ONE`, ... |
| `serialConsistencyLevel` | | `SERIAL` or `LOCAL_SERIAL` for lightweight transactions |
| `prepareStatements` | `true` | `false` sends plain QUERY frames with inferred value types |
| `resultSetConversionStrategy` | `ALL` | `ALL` (list of row maps), `ONE` (first row or null) or `LIMIT_<n>` (first n rows) |
| `fetchSize` | `5000` | page size; all pages are read |
| `username`, `password` | | PasswordAuthenticator credentials |
| `connectTimeout` | `10s` | connection timeout |
| `readTimeout` | `30s` | request timeout |
| `ssl` | `false` | TLS (or `sslContextParameters=#bean`, `useGlobalSslContextParameters=true`) |
| `compression` | none | `lz4` or `snappy` frame compression |
| `tokenAware` | `true` | send prepared statements to the node that owns the partition key; `false` uses the contact points in order |
| `delay`, `initialDelay`, ... | `500` ms, `1000` ms | consumer: the scheduled poll options |

`clusterName`, `loadBalancingPolicyClass`, `datacenter`, `extraTypeCodecs` and `session` are
accepted and ignored. There is no datacenter-aware load balancing.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelCqlQuery` | in | statement to run instead of `cql` |

## Values

Rows are maps. Timestamps come back as ISO-8601 text (epoch milliseconds are accepted on input),
UUIDs and decimals as text, dates as `YYYY-MM-DD`, blobs as bytes, durations as Cassandra duration
text (`1mo2d3h`), lists and sets as arrays, maps and user-defined types as objects.

## Run it with Docker

```sh
docker run --rm -p 8080:8080 -e CASSANDRA_HOSTS=cassandra1,cassandra2:9042 \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/events.camel.yaml
```

## Common questions

### How do I pass several bind values?

Make the body a list in the order of the `?` markers, for example with
`jq: "[.day, .seq, .msg]"` after `unmarshal: json`.

### Does the consumer send one exchange per row?

No. As in Apache Camel, each poll sends one exchange with the converted result set. Use `split`
to process rows individually.

### Does it work with ScyllaDB and Amazon Keyspaces?

The client speaks CQL protocol v4, which ScyllaDB supports. It is tested against an embedded CQL
server, not against Cassandra, ScyllaDB or Keyspaces clusters.

## Related

- [sql](https://pmsudhi.github.io/cameleer/docs/components/sql.html): relational databases.
- [Split EIP](https://pmsudhi.github.io/cameleer/docs/guides/eips.html)
- [Apache Camel CQL component](https://camel.apache.org/components/next/cql-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/class.html

# Class component

> The `class` component calls a bean by name, like [bean](https://pmsudhi.github.io/cameleer/docs/components/bean.html); in Cameleer the "class name" is looked up in the registry.

**Scheme:** `class:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Class](https://camel.apache.org/components/next/class-component.html)

## When to use it

- Keep Camel routes that use `class:com.example.Greeter` working: bind a Rust bean under that name.
- Any case where [bean](https://pmsudhi.github.io/cameleer/docs/components/bean.html) fits; the two schemes behave the same.

Difference from Apache Camel: Camel creates a new instance of a Java class. Rust has no runtime class
loading, so Cameleer resolves the name in the registry, exactly like `bean:`.

## URI format

```text
class:name[?method=methodName]
```

## Example

```yaml
- route:
    id: greet
    from:
      uri: direct:greet
      steps:
        - to: class:com.example.Greeter?method=greet
```

Register the bean under the class name:

```rust
use cameleer_core::component::bean::{bind_bean, BeanMethods};
use cameleer_core::prelude::*;

pub fn register(ctx: &CamelContext) {
    let greeter = BeanMethods::new().method_value("greet", |ex: &Exchange| Ok(Value::from(format!("Hello {}", ex.body()))));
    bind_bean(ctx.registry(), "com.example.Greeter", greeter);
}
```

Sending `Ada` returns `Hello Ada`.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:greet").route_id("greet").to("class:com.example.Greeter?method=greet");
    })
}
```

## Options

The same as [bean](https://pmsudhi.github.io/cameleer/docs/components/bean.html#options): `method`; `scope`, `cache`, `parameters.*` and `bean.*` are accepted
and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelBeanMethodName` | in | Overrides the `method` option. |

## Run it with Docker

Like [bean](https://pmsudhi.github.io/cameleer/docs/components/bean.html), the bean must be registered by a Rust program, so the stock image cannot run this
route on its own.

## Common questions

### Does `class:` create a new object per call?

No. It calls the object bound in the registry under that name.

## Related

- [bean](https://pmsudhi.github.io/cameleer/docs/components/bean.html), [ref](https://pmsudhi.github.io/cameleer/docs/components/ref.html)
- [Apache Camel Class component](https://camel.apache.org/components/next/class-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/controlbus.html

# Control Bus component

> The `controlbus` component starts, stops, suspends and inspects routes from a message, and evaluates scripts sent as messages.

**Scheme:** `controlbus:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Control Bus](https://camel.apache.org/components/next/controlbus-component.html)

## When to use it

- Pause a route during a maintenance window and resume it afterwards.
- Expose route status and statistics to an operator, a dashboard or an AI agent ("is the ingest route running?").
- Stop a consumer when a downstream system is down, from an error handler.

## URI format

```text
controlbus:route?routeId=id&action=start|stop|suspend|resume|restart|status|stats|fail
controlbus:language:languageName
```

## Example

```yaml
- route:
    id: ingest
    from:
      uri: timer:ingest
      parameters:
        period: 60000
      steps:
        - to: log:ingest
- route:
    id: ingest-status
    from:
      uri: direct:status
      steps:
        - to: controlbus:route?routeId=ingest&action=status
- route:
    id: ingest-pause
    from:
      uri: direct:pause
      steps:
        - to: controlbus:route?routeId=ingest&action=stop
```

Calling `direct:status` returns `Started`. After `direct:pause`, it returns `Stopped`.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("timer:ingest?period=60000").route_id("ingest").to("log:ingest");
        b.from("direct:status")
            .route_id("ingest-status")
            .to("controlbus:route?routeId=ingest&action=status");
        b.from("direct:pause")
            .route_id("ingest-pause")
            .to("controlbus:route?routeId=ingest&action=stop");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `routeId` | | The route to act on. `current` means the route of the exchange. Without it, `status` returns the context status and `stats` the statistics of all routes. |
| `action` | `status` | `start`, `stop`, `suspend`, `resume`, `restart`, `status`, `stats` or `fail`. |
| `async` | `false` | Run the action in the background and return at once. |
| `restartDelay` | `1000` | ms between stop and start for `restart`. |
| `loggingLevel` | `INFO` | Level of the log line written for each action. |

`status` and `stats` put their result in the message body. Stopping, suspending or restarting the route
that is processing the exchange always happens in the background, so the exchange can complete.

With `controlbus:language:simple` (or another language), the message body is evaluated as a script and
the result becomes the body.

## Message headers

None read or added.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/maintenance.camel.yaml
```

## Common questions

### How do I stop a route from inside itself?

Use `controlbus:route?routeId=current&action=stop`. The stop runs in the background after the exchange
completes.

### How do I get statistics for all routes?

Send any message to `controlbus:route?action=stats` (no `routeId`).

## Related

- [direct](https://pmsudhi.github.io/cameleer/docs/components/direct.html), [timer](https://pmsudhi.github.io/cameleer/docs/components/timer.html)
- [Apache Camel Control Bus component](https://camel.apache.org/components/next/controlbus-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/couchdb.html

# CouchDB component

> The `couchdb` component saves, reads and deletes JSON documents in Apache CouchDB and consumes the database's changes feed.

**Scheme:** `couchdb:` · **Crate:** `cameleer-datastores` · **Cargo feature:** [`datastores`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [CouchDB](https://camel.apache.org/components/next/couchdb-component.html)

## When to use it

- Store JSON documents over CouchDB's HTTP API, including from edge sites that later
  replicate to a central CouchDB.
- React to every change in a database: the consumer follows the `_changes` feed and routes
  each new, updated or deleted document.
- Save batches of documents in one `_bulk_docs` request.

## URI format

```text
couchdb:http://host[:port]/database[?options]
couchdb:https://host[:port]/database[?options]
```

The port defaults to 5984. `https` uses TLS with the system trust store, the global
`camel.ssl.*` parameters or `sslContextParameters=#bean`.

**Producer.** Without a `CouchDbMethod` header the body (a map or JSON text) is saved:
`PUT /db/{_id}` when it has an `_id`, else `POST /db`. A body with `_rev` updates that
revision. `CouchDbMethod=GET` reads the document `CouchDbId` (or the id in the body);
`CouchDbMethod=DELETE` deletes the document given by the body's `_id` and `_rev` or by the
`CouchDbId` and `CouchDbRev` headers. A list body is saved with one `_bulk_docs` request.

**Consumer.** Follows `_changes?feed=longpoll&include_docs=true` from the current update
sequence (or `since`). The body is the document.

## Example

`POST /notes` saves the JSON body as a new document and answers with its id. `createDatabase`
creates the database on first use.

```yaml
- route:
    id: save-note
    from:
      uri: "platform-http:/notes?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - to: "couchdb:{{env:COUCHDB_URL:http://localhost:5984}}/notes?createDatabase=true&username={{env:COUCHDB_USER:admin}}&password={{env:COUCHDB_PASSWORD:secret}}"
        - setBody:
            simple: "${header.CouchDbId}"
```

This route follows the changes feed of the same database and logs every change.

```yaml
- route:
    id: note-changes
    from:
      uri: "couchdb:{{env:COUCHDB_URL:http://localhost:5984}}/notes?username={{env:COUCHDB_USER:admin}}&password={{env:COUCHDB_PASSWORD:secret}}"
      steps:
        - log: "${header.CouchDbMethod} ${header.CouchDbId} rev ${header.CouchDbRev}"
        - to: "log:changes"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("direct:save")
        .to("couchdb:http://localhost:5984/notes?createDatabase=true&username=admin&password=secret");
    b.from("direct:get")
        .set_header("CouchDbMethod", constant("GET"))
        .to("couchdb:http://localhost:5984/notes?username=admin&password=secret");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `createDatabase` | `false` | create the database if it does not exist |
| `username`, `password` | | basic authentication |
| `since` | current sequence | consumer: start the feed after this update sequence |
| `updates` | `true` | consumer: route created and updated documents |
| `deletes` | `true` | consumer: route deletions |
| `heartbeat` | `30000` ms | consumer: longpoll timeout |
| `style` | `main_only` | consumer: `main_only` or `all_docs` (all leaf revisions) |
| `maxMessagesPerPoll` | `0` | consumer: changes per feed request (`limit`; 0 = unlimited) |
| `sslContextParameters` | | TLS trust for `https` |

## Message headers

| header | direction | description |
|---|---|---|
| `CouchDbMethod` | in/out | in: `GET` or `DELETE` (save otherwise); out (consumer): `UPDATE` or `DELETE` |
| `CouchDbId` | in/out | document id (a list of ids after a bulk save) |
| `CouchDbRev` | in/out | document revision (a list after a bulk save) |
| `CouchDbDatabase` | out | consumer: the database name |
| `CouchDbSeq` | out | consumer: the update sequence of the change |

Errors: a revision conflict raises `DocumentConflictException`, a missing document
`NoDocumentException`.

## Run it with Docker

```sh
docker run --rm -p 8080:8080 \
  -e COUCHDB_URL=http://couchdb.example.com:5984 -e COUCHDB_USER=app -e COUCHDB_PASSWORD \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/notes.camel.yaml
```

## Common questions

### How do I update a document?

Send the document with its `_id` and current `_rev`. A stale `_rev` raises
`DocumentConflictException`; read the latest revision with `CouchDbMethod=GET` and retry.

### How do I resume the changes feed after a restart?

Store the last `CouchDbSeq` you processed and start the consumer with `since=<seq>`. Without
`since`, the feed starts at the current sequence and skips older changes.

### Is Couchbase supported?

No. Couchbase uses a binary key-value protocol that Cameleer does not implement.

## Related

- [mongodb](https://pmsudhi.github.io/cameleer/docs/components/mongodb.html): another document database.
- [Apache Camel CouchDB component](https://camel.apache.org/components/next/couchdb-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/cron.html

# Cron component

> The `cron` component starts a route on a cron schedule, such as every night at 02:00 in a given time zone.

**Scheme:** `cron:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Cron](https://camel.apache.org/components/next/cron-component.html)

## When to use it

- Nightly reports, exports and clean-up jobs.
- Business-hours polling (`0 0/15 8-18 ? * MON-FRI`).
- Scheduled AI agent tasks, such as a daily summary of yesterday's tickets.

Cameleer has its own cron engine (no Quartz library): it understands Quartz 6 and 7 field syntax,
Unix 5 field syntax, `L`, `W`, `#`, month and day names, and macros such as `@daily`.

## URI format

```text
cron:name?schedule=expression[&timeZone=zone]
```

In a URI, write spaces in the expression as `+`. In the YAML `parameters` block you can use spaces.

## Example

```yaml
- route:
    id: nightly-report
    from:
      uri: cron:nightly
      parameters:
        schedule: "0 0 2 * * ?"
        timeZone: Europe/Paris
      steps:
        - setBody:
            simple: "report fired at ${header.fireTime}"
        - to: log:reports
```

The route fires every day at 02:00 Paris time.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("cron:nightly?schedule=0+0+2+*+*+?&timeZone=Europe/Paris")
            .route_id("nightly-report")
            .set_body(simple("report fired at ${header.fireTime}"))
            .to("log:reports");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `schedule` | (required) | The cron expression. |
| `timeZone` (alias `trigger.timeZone`) | process default zone | A region id (`Europe/Paris`) or a fixed offset (`GMT+02:00`). |
| `exchangePattern` | `InOnly` | `InOnly` or `InOut`. |
| `bridgeErrorHandler`, `exceptionHandler` | | Accepted and ignored. |

Fields of a Quartz expression: seconds, minutes, hours, day of month, month, day of week, optional
year. A 5 field expression is read as Unix cron (minutes first).

## Message headers

Each fire sends an exchange with a null body and these Quartz headers. Times are epoch
milliseconds (Camel uses `java.util.Date`).

| header | description |
|---|---|
| `fireTime` | When the trigger actually fired. |
| `scheduledFireTime` | When it was scheduled to fire. |
| `nextFireTime` | The next fire time. |
| `previousFireTime` | The previous fire time. |
| `refireCount` | Always `0`. |
| `jobRunTime` | Always `-1` (as in Quartz before the job finishes). |
| `triggerName`, `triggerGroup` | Trigger identity. |

The exchange properties `CamelTimerName`, `CamelTimerFiredTime` and `CamelTimerCounter` are set as well.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/report.camel.yaml
```

The container has the IANA time-zone database built in, so `timeZone: Europe/Paris` works without
system zoneinfo files.

## Common questions

### What happens if a run takes longer than the interval?

Fires missed while the route is busy are skipped (the Quartz "do nothing" misfire policy).

### Which time zone is used without `timeZone`?

The process default zone: UTC unless the `TZ` environment variable is set.

### How do I run every 30 seconds?

`schedule: "0/30 * * * * ?"`.

## Related

- [quartz](https://pmsudhi.github.io/cameleer/docs/components/quartz.html), [scheduler](https://pmsudhi.github.io/cameleer/docs/components/scheduler.html), [timer](https://pmsudhi.github.io/cameleer/docs/components/timer.html)
- [Apache Camel Cron component](https://camel.apache.org/components/next/cron-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/cxf.html

# CXF component

> The `cxf` component calls SOAP web services and hosts SOAP services in a route, from a WSDL, with SOAP 1.1 and 1.2, faults, WS-Security, WS-Addressing and MTOM.

**Scheme:** `cxf:` · **Crate:** `cameleer-soap` · **Cargo feature:** [`soap`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [CXF](https://camel.apache.org/components/next/cxf-component.html)

There is no Apache CXF inside: Cameleer parses the WSDL and XSD itself and maps parameters to
and from XML. In the default `POJO` data format the body is the parameter list (an array or a
map) and the result is the return value, typed from the schema.

## When to use it

- Put a JSON or REST front on a legacy SOAP service, so newer apps and AI agents can use it
  without SOAP tooling.
- Host a SOAP service that existing clients (.NET, Java) call, from a WSDL.
- Call SOAP services in finance, telecom, government and healthcare integrations.

## URI format

```text
cxf://http://host:port/path?wsdlURL=...&serviceName={ns}Service&portName={ns}Port[&options]
cxf:/path?...                (consumer on the platform HTTP port)
cxf:bean:name                (endpoint options from a registry bean)
```

## Example

A JSON endpoint in front of a SOAP calculator service. `POST /calc/add` with `{"a": 2, "b": 3}`
calls the SOAP operation `Add` with named parameters and answers `{"sum": 5}`. The WSDL is the
service's contract file (`calculator.wsdl`).

```yaml
- route:
    id: calc-json-bridge
    from:
      uri: platform-http:/calc/add?httpMethodRestrict=POST
      steps:
        - unmarshal:
            json: {}
        - removeHeaders:
            pattern: "*"
        - to: "cxf://http://{{env:CALC_ADDRESS:localhost:9000}}/calculator?wsdlURL={{env:CALC_WSDL:calculator.wsdl}}&serviceName={http://example.org/calculator}CalculatorService&portName={http://example.org/calculator}CalculatorSoap&defaultOperationName=Add"
        - setHeader:
            name: Content-Type
            constant: application/json
        - setBody:
            simple: '{"sum": ${body}}'
```

A SOAP fault from the service fails the exchange with a `SoapFault` error (the HTTP endpoint
then answers 500); the fault code, string and detail are in the `CamelCxfFault*` headers.

## Rust DSL

```rust
fn calc_bridge_route(b: &mut RouteBuilder, address: &str, wsdl: &str) {
    b.from("platform-http:/calc/add?httpMethodRestrict=POST")
        .route_id("calc-json-bridge")
        .unmarshal_json()
        .remove_headers("*")
        .to(&format!(
            "cxf://http://{}/calculator?wsdlURL={}&serviceName={{http://example.org/calculator}}CalculatorService&portName={{http://example.org/calculator}}CalculatorSoap&defaultOperationName=Add",
            address, wsdl
        ))
        .set_header("Content-Type", constant("application/json"))
        .set_body(simple(r#"{"sum": ${body}}"#));
}
```

## Options

| option | default | description |
|---|---|---|
| `wsdlURL` | | WSDL location (file path, `file:`, `classpath:`, `http(s)://` or `#bean` holding the text). |
| `serviceName`, `portName` | first in the WSDL | `{namespace}local` names of the WSDL service and port. |
| `dataFormat` | `POJO` | `POJO` (typed parameters), `PAYLOAD` (body element XML), `RAW` / `CXF_MESSAGE` (the whole envelope). |
| `defaultOperationName` | | Operation when the `operationName` header is not set. |
| `defaultOperationNamespace` | WSDL namespace | Operation namespace. |
| `address` | URI address | Service address (overrides the URI and the WSDL `soap:address`). |
| `soapVersion` | `1.1` | `1.1` or `1.2` when there is no WSDL. |
| `username`, `password` | | HTTP basic authentication. |
| `receiveTimeout`, `connectionTimeout` | 60000, 30000 | Client timeouts in ms. |
| `sslContextParameters` | | `#bean` with TLS material for `https`. |
| `schemaValidationEnabled` | `false` | Consumer: validate requests against the WSDL schema. |
| `publishedEndpointUrl` | | Consumer: address written into the `?wsdl` document. |
| `attributePrefix` | `@` | POJO: prefix of XML attribute keys. |
| `wsSecurityUsername`, `wsSecurityPassword`, `wsSecurityPasswordType` | | Producer: WS-Security UsernameToken (`PasswordText` or `PasswordDigest`). |
| `wsSecurityUsers` | | Consumer: `alice:secret,bob:pw` required UsernameTokens. |
| `wsSecuritySignatureKey`, `wsSecuritySignatureCertificate` | | Producer: sign the envelope (PEM). |
| `wsSecuritySignatureVerifyCertificate`, `wsSecuritySignatureTrustedCertificates` | | Consumer: require a valid signature. |
| `wsSecurityEncryptionCertificate`, `wsSecurityEncryptionAlgorithm`, `wsSecurityDecryptionKey` | | XML Encryption of the body. |
| `wsSecuritySamlSubject`, `wsSecuritySamlIssuer`, `wsSecuritySamlAttributes` | | Add a SAML 2.0 assertion; consumer checks with `wsSecuritySamlRequired`, `wsSecuritySamlTrustedIssuers`. |
| `wsAddressingEnabled` | `false` | Add and check WS-Addressing headers (also `features=wsa`). |
| `wsrmEnabled` | `false` | WS-ReliableMessaging. |
| `mtomEnabled`, `mtomThreshold` | `false`, 1024 | Send large base64 content as MTOM/XOP parts. |

`loggingFeatureEnabled`, `serviceClass`, `wrappedStyle` and other CXF tuning options are accepted
and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `operationName` | in / out | Operation to call (producer) or being called (consumer). |
| `operationNamespace` | in / out | Namespace of the operation. |
| `SOAPAction` | in / out | SOAP action. |
| `CamelCxfSoapHeaders` | in / out | Extra SOAP header blocks (XML). |
| `CamelCxfSoapVersion` | out | Consumer: `1.1` or `1.2`. |
| `CamelCxfFaultCode`, `CamelCxfFaultString`, `CamelCxfFaultDetail` | out | Producer: details of a SOAP fault. |
| `CamelCxfWsaAction`, `CamelCxfWsaMessageId`, `CamelCxfWsaRelatesTo` | in / out | WS-Addressing values. |

Attachments travel in the `CamelAttachments` exchange property.

## Run it with Docker

```sh
docker run --rm -p 8080:8080 -e CALC_ADDRESS=soap.example.com:9000 -e CALC_WSDL=/routes/calculator.wsdl \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/calc-json-bridge.camel.yaml
curl -XPOST -H 'Content-Type: application/json' -d '{"a": 2, "b": 3}' localhost:8080/calc/add
```

## Common questions

### How do I pass parameters in POJO mode?
An array is positional (`[2, 3]`), a map is by name (`{"a": 2, "b": 3}`), a single value fills a
one-parameter operation. Values are typed from the XSD.

### How do I host a SOAP service?
Use the same URI in `from:` (`cxf://http://0.0.0.0:9000/calculator?wsdlURL=...`). The route
gets the parameter list as the body and `operationName` as a header; the body at the end is the
return value. `GET /calculator?wsdl` serves the WSDL.

### How do I return a SOAP fault?
Throw an exception; `IllegalArgumentException` becomes a `Client` (1.1) / `Sender` (1.2) fault,
anything else a `Server` / `Receiver` fault.

### Can I work with the raw XML?
Yes: `dataFormat=PAYLOAD` gives the body element XML; `dataFormat=RAW` gives the whole envelope.

## Related

- [spring-ws](https://pmsudhi.github.io/cameleer/docs/components/spring-ws.html): payload-oriented SOAP endpoints.
- [cxfrs](https://pmsudhi.github.io/cameleer/docs/components/cxfrs.html): JAX-RS style REST endpoints.
- [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html), [rest](https://pmsudhi.github.io/cameleer/docs/components/rest.html).
- Apache Camel: [CXF component](https://camel.apache.org/components/next/cxf-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/cxfrs.html

# CXF-RS component

> The `cxfrs` component serves and calls JAX-RS style REST resources: operations are matched by HTTP method and path template, and the matching operation name is passed to the route.

**Scheme:** `cxfrs:` · **Crate:** `cameleer-soap` · **Cargo feature:** [`soap`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [CXF-RS](https://camel.apache.org/components/next/cxfrs-component.html)

Java resource classes do not exist in Cameleer. The resource model is given inline with
`operations=name:METHOD:/path;...`, or with `ResourceDescriptor` beans (`resourceClasses=#bean`)
in Rust. For new APIs the [REST DSL](https://pmsudhi.github.io/cameleer/docs/components/rest.html) is usually simpler; `cxfrs` is for routes migrated
from camel-cxf-rest that branch on `operationName`.

## When to use it

- Migrate Camel routes that use `cxfrs:` and switch on `operationName`.
- One route serving several REST operations of a resource.
- Call a REST service with method, path and query from headers.

## URI format

```text
cxfrs:http://host:port/base[?options]
cxfrs:/base[?options]          (consumer on the platform HTTP port)
```

## Example

A customer resource with two operations in one route. The route branches on `operationName`;
path parameters (`id`) are headers.

```yaml
- route:
    id: customer-resource
    from:
      uri: "cxfrs:http://0.0.0.0:{{env:API_PORT:9000}}/api?operations=getCustomer:GET:/customers/{id};addCustomer:POST:/customers"
      steps:
        - choice:
            when:
              - simple: "${header.operationName} == 'getCustomer'"
                steps:
                  - setBody:
                      simple: '{"id": "${header.id}", "name": "Ada"}'
                  - unmarshal:
                      json: {}
              - simple: "${header.operationName} == 'addCustomer'"
                steps:
                  - setHeader:
                      name: CamelHttpResponseCode
                      constant: 201
                  - setBody:
                      simple: '{"created": "${body[name]}"}'
                  - unmarshal:
                      json: {}
```

JSON request bodies arrive parsed, so `${body[name]}` reads a field. A map or array result is
sent as JSON; a request that matches no operation gets `404`.

## Rust DSL

```rust
fn customer_resource_route(b: &mut RouteBuilder, port: u16) {
    b.from(&format!("cxfrs:http://0.0.0.0:{}/api?operations=getCustomer:GET:/customers/{{id}};addCustomer:POST:/customers", port))
        .route_id("customer-resource")
        .choice()
        .when(simple("${header.operationName} == 'getCustomer'"))
        .set_body(simple(r#"{"id": "${header.id}", "name": "Ada"}"#))
        .unmarshal_json()
        .when(simple("${header.operationName} == 'addCustomer'"))
        .set_header("CamelHttpResponseCode", constant(201))
        .set_body(simple(r#"{"created": "${body[name]}"}"#))
        .unmarshal_json()
        .end_choice();
}
```

## Options

| option | default | description |
|---|---|---|
| `operations` | | Inline resource model: `name:METHOD:/path/{param};...`. |
| `resourceClasses` | | `#bean` list of `ResourceDescriptor` beans (Java class names are ignored). |
| `providers` | | `#bean` list of `EntityProvider` beans (readers/writers for media types other than JSON). |
| `bindingStyle` | `SimpleConsumer` | `Default` stops mapping query parameters to headers. |
| `produces` | | Default response media type for string bodies. |
| `address` | URI address | Base address. |
| `throwExceptionOnFailure` | `true` | Producer: fail on status 300 and above. |
| `parseJson` | `false` | Producer: parse JSON responses into values. |
| `username`, `password` | | Producer: basic authentication. |
| `receiveTimeout`, `connectionTimeout` | 60000, 30000 | Producer timeouts in ms. |
| `sslContextParameters` | | `#bean` for `https`. |

## Message headers

| header | direction | description |
|---|---|---|
| `operationName` | out | Consumer: the matched operation (else the HTTP method). |
| `CamelHttpMethod` | out / in | Request method; producer: method to send (default GET, POST with a body). |
| `CamelHttpPath` | out / in | Path relative to the base; producer: appended to the base. |
| `CamelHttpUri`, `CamelHttpQuery` | out / in | Request URI and query. |
| `CamelHttpResponseCode` | in / out | Response status. |
| `Content-Type`, `Accept` | in / out | Media types; a `415` or `406` answers mismatches with declared `consumes` / `produces`. |

Path template parameters and query parameters become headers.

## Run it with Docker

```sh
docker run --rm -p 9000:9000 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/customer-resource.camel.yaml
curl localhost:9000/api/customers/7
curl -XPOST -H 'Content-Type: application/json' -d '{"name": "Grace"}' localhost:9000/api/customers
```

## Common questions

### Do I need JAX-RS annotated classes?
No. Describe the operations with `operations=` or `ResourceDescriptor` beans.

### What does a string result look like?
It is sent as `text/plain` (or the `produces` type); maps and arrays are sent as JSON; a null
body answers `204`.

### What is not supported?
The JAX-RS proxy client API and sub-resource locators.

## Related

- [rest](https://pmsudhi.github.io/cameleer/docs/components/rest.html), [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html), [cxf](https://pmsudhi.github.io/cameleer/docs/components/cxf.html).
- Apache Camel: [CXF-RS component](https://camel.apache.org/components/next/cxfrs-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/dataformat.html

# Data Format component

> The `dataformat` component marshals or unmarshals the message body with a data format (JSON, CSV, Base64, ...) as an endpoint, so it can be used anywhere a URI is accepted.

**Scheme:** `dataformat:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Data Format](https://camel.apache.org/components/next/dataformat-component.html)

## When to use it

- Parse JSON from an MQTT sensor or an HTTP call into a map, then read fields with Simple.
- Encode or compress a payload before sending it (`base64`, `gzipDeflater`).
- Use a data format where only a URI fits, such as `recipientList`, `toD` or `enrich`.

Inside a route, the `marshal` and `unmarshal` steps do the same thing.

## URI format

```text
dataformat:name:marshal|unmarshal[?options]
```

`name` is a data format bound in the registry under that name, or a built-in one (`json`, `csv`,
`base64`, `gzipDeflater`, ...) created with the endpoint options.

## Example

```yaml
- route:
    id: parse-reading
    from:
      uri: direct:reading
      steps:
        - to: dataformat:json:unmarshal
        - setBody:
            simple: "${body[device]}=${body[temperature]}"
```

Sending `{"device":"t1","temperature":21.5}` returns `t1=21.5`.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:reading")
            .route_id("parse-reading")
            .to("dataformat:json:unmarshal")
            .set_body(simple("${body[device]}=${body[temperature]}"));
    })
}
```

## Options

The options are those of the chosen data format, for example `prettyPrint=true` for `json` or
`delimiter=;` for `csv`. See the data format pages in [../dataformats/](https://pmsudhi.github.io/cameleer/docs/dataformats/index.html). When the name
refers to a data format bound in the registry, endpoint options are ignored.

## Message headers

Whatever the data format reads or sets.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/readings.camel.yaml
```

## Common questions

### What does unmarshal json give me?

A map (or list) value. Read fields with `${body[name]}` in Simple, or with JSONPath.

### Why do I get "Operation must be marshal or unmarshal"?

The last part of the URI must be `marshal` or `unmarshal`, for example `dataformat:base64:marshal`.

## Related

- [language](https://pmsudhi.github.io/cameleer/docs/components/language.html)
- [Apache Camel Data Format component](https://camel.apache.org/components/next/dataformat-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/dataset.html

# DataSet component

> The `dataset` component load-tests a route: it sends a known set of messages into the route and checks that the same messages come out.

**Scheme:** `dataset:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [DataSet](https://camel.apache.org/components/next/dataset-component.html)

## When to use it

- Soak-test a route with thousands of messages and check that none are lost or reordered.
- Measure throughput with a fixed message rate (`produceDelay`) or a minimum rate (`minRate`).
- Verify that a route chain (seda queues, brokers) delivers every message exactly once.

## URI format

```text
dataset:name[?options]
```

`name` is a data set bound in the registry: a `SimpleDataSet` (N copies of one body), a `ListDataSet`
(a list of bodies) or your own type implementing the `DataSet` trait.

## Example

```yaml
- route:
    id: load-source
    from:
      uri: dataset:orders
      parameters:
        produceDelay: 1
        initialDelay: 100
      steps:
        - to: seda:work
- route:
    id: system-under-test
    from:
      uri: seda:work
      steps:
        - setHeader:
            name: processed
            constant: true
        - to: dataset:orders
```

Bind the data set in Rust before starting, then wait for all messages to arrive:

```rust
use cameleer_core::component::dataset::{bind_dataset, dataset_endpoint, SimpleDataSet};

bind_dataset(ctx.registry(), "orders", SimpleDataSet::new(500).with_body("order"));
// ... start the routes ...
dataset_endpoint(&ctx, "dataset:orders")?.assert_is_satisfied_within(std::time::Duration::from_secs(30))?;
```

## Rust DSL

```rust
use cameleer_core::component::dataset::{bind_dataset, SimpleDataSet};
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    bind_dataset(ctx.registry(), "orders", SimpleDataSet::new(500).with_body("order"));
    ctx.add_routes(|b| {
        b.from("dataset:orders?produceDelay=1&initialDelay=100")
            .route_id("load-source")
            .to("seda:work");
        b.from("seda:work")
            .route_id("system-under-test")
            .set_header("processed", constant(true))
            .to("dataset:orders");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `produceDelay` | `3` | Consumer: delay (ms) between sent messages. |
| `consumeDelay` | `0` | Producer: delay (ms) after each received message. |
| `preloadSize` | `0` | Consumer: send this many messages at once before applying `produceDelay`. |
| `initialDelay` | `1000` | Consumer: wait (ms) before sending the first message. |
| `dataSetIndex` | `lenient` | `strict` (every message must carry the right `CamelDataSetIndex`), `lenient` (checked when present) or `off`. |
| `minRate` | `0` | Fail when fewer messages per second arrive. |
| `expectedCount` | data set size | Override the number of expected messages. |
| `assertPeriod`, `resultWaitTime`, `retainFirst`, `retainLast`, `reportGroup`, `log`, `copyOnExchange`, `failFast`, `bridgeErrorHandler` | | Accepted and ignored. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelDataSetIndex` | out (consumer), in (producer) | Index of the message in the data set, starting at 0. |

## Run it with Docker

Data sets are bound from Rust code, so this component is used in Rust tests rather than in a plain
container run.

## Common questions

### Where do the messages come from?

From the `DataSet` bound under the endpoint name. `SimpleDataSet::new(n).with_body(b).with_header(k, v)`
and `ListDataSet::new(vec![...])` cover most cases.

### How do I check the result?

`dataset_endpoint(&ctx, "dataset:name")?.assert_is_satisfied_within(timeout)` waits for all messages and
fails on missing, extra or wrongly indexed ones.

## Related

- [dataset-test](https://pmsudhi.github.io/cameleer/docs/components/dataset-test.html), [test](https://pmsudhi.github.io/cameleer/docs/components/test.html), [mock](https://pmsudhi.github.io/cameleer/docs/components/mock.html), [seda](https://pmsudhi.github.io/cameleer/docs/components/seda.html)
- [Apache Camel DataSet component](https://camel.apache.org/components/next/dataset-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/dataset-test.html

# DataSet Test component

> The `dataset-test` component checks a route's output against expected messages read from another endpoint, such as a file of expected lines.

**Scheme:** `dataset-test:` · **Also:** `test:` (see [test](https://pmsudhi.github.io/cameleer/docs/components/test.html)) · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [DataSet Test](https://camel.apache.org/components/next/dataset-test-component.html)

## When to use it

- Golden-file tests: compare what a transformation route produces with a file of expected results.
- Regression tests for message mappings, where the expected output is kept next to the routes.
- Compare against messages waiting on a queue, such as `seda:expected`.

## URI format

```text
dataset-test:expectedEndpointUri[?options]
```

Options this component does not know are passed on to the expected endpoint URI.

## Example

```yaml
- route:
    id: normalize-codes
    from:
      uri: direct:normalize
      steps:
        - setBody:
            simple: "${body.toUpperCase()}"
        - to: dataset-test:file:{{env:EXPECTED_DIR:expected}}?noop=true&split=true
```

With a file `expected/codes.txt` that contains `AB-1` and `CD-2` on two lines, sending `ab-1` and `cd-2`
satisfies the endpoint. Check it from Rust:

```rust
use cameleer_core::component::dataset::dataset_test_endpoint;

let uri = "dataset-test:file:expected?noop=true&split=true";
dataset_test_endpoint(&ctx, uri)?.assert_is_satisfied()?;
```

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:normalize")
            .route_id("normalize-codes")
            .set_body(simple("${body.toUpperCase()}"))
            .to("dataset-test:file:expected?noop=true&split=true");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `timeout` | `2000` | How long (ms) to wait for the first expected message when loading them. |
| `anyOrder` | `false` | Accept the messages in any order. |
| `split` | `false` | Split each expected message into lines (or by `delimiter`), one expected message per part. |
| `delimiter` | `\n` | Separator used with `split`. |

## Message headers

None added.

## Run it with Docker

The expectations are checked from Rust test code, so this component is used in tests.

## Common questions

### When are the expected messages read?

On the first `assert_is_satisfied` call: the endpoint polls the expected URI until nothing arrives for
the `timeout`, then compares.

### Can I see what was received?

Yes. `dataset_test_endpoint(&ctx, uri)?.mock()` is a regular [mock](https://pmsudhi.github.io/cameleer/docs/components/mock.html) endpoint with the received
exchanges.

## Related

- [test](https://pmsudhi.github.io/cameleer/docs/components/test.html), [dataset](https://pmsudhi.github.io/cameleer/docs/components/dataset.html), [mock](https://pmsudhi.github.io/cameleer/docs/components/mock.html)
- [Apache Camel DataSet Test component](https://camel.apache.org/components/next/dataset-test-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/direct.html

# Direct component

> The `direct` component calls another route synchronously, in the same thread, inside the same Cameleer process.

**Scheme:** `direct:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Direct](https://camel.apache.org/components/next/direct-component.html)

## When to use it

- Split a long route into small named sub-routes (`direct:validate`, `direct:enrich`) and call them like functions.
- Share one piece of logic between several routes, for example one validation route used by a REST API and a Kafka consumer.
- Give tests and tools an entry point: send a message to `direct:...` with a producer template and read the reply.
- Expose a tool to an AI agent as a request/reply route: the caller blocks until the route returns its answer.

## URI format

```text
direct:name[?options]
```

`name` identifies the route that consumes from it. Only one route can consume from a given `direct:` name.

## Example

```yaml
- route:
    id: orders
    from:
      uri: direct:orders
      steps:
        - to: direct:validate
        - setBody:
            simple: "accepted ${body}"
- route:
    id: validate
    from:
      uri: direct:validate
      steps:
        - filter:
            simple: "${body} == ''"
            steps:
              - throwException:
                  exceptionType: java.lang.IllegalArgumentException
                  message: empty order
        - setHeader:
            name: validated
            constant: true
```

Sending `o-1` to `direct:orders` returns `accepted o-1`. Sending an empty body fails the exchange with
`IllegalArgumentException`, and the error travels back to the caller because the call is synchronous.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:orders")
            .route_id("orders")
            .to("direct:validate")
            .set_body(simple("accepted ${body}"));
        b.from("direct:validate")
            .route_id("validate")
            .filter(simple("${body} == ''"))
            .throw_exception("java.lang.IllegalArgumentException", "empty order")
            .end()
            .set_header("validated", constant(true));
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `block` | `true` | When no consumer is running, wait up to `timeout` for one to start instead of failing at once. |
| `timeout` | `30000` | How long (ms, or a duration such as `5s`) a blocked producer waits for a consumer. |
| `failIfNoConsumers` | `true` | Fail with `DirectConsumerNotAvailableException` when there is no consumer. With `false` the message is dropped silently. |
| `synchronous` | | Accepted for compatibility; direct is always synchronous. |

## Message headers

The direct component does not add headers. Headers, properties and the body pass to the called
route unchanged, and the called route's changes are visible to the caller.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

A `direct:` route only runs when something calls it, so combine it with a consumer such as
[timer](https://pmsudhi.github.io/cameleer/docs/components/timer.html), [kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html) or a REST endpoint in the same file.

## Common questions

### What is the difference between direct and seda?

`direct` runs the called route in the caller's thread and returns its result. [seda](https://pmsudhi.github.io/cameleer/docs/components/seda.html) puts
the message on an in-memory queue and a different thread processes it later.

### Why do I get DirectConsumerNotAvailableException?

No route consumes from that `direct:` name, or the route is stopped. Check the name for typos, or set
`failIfNoConsumers=false` if dropping the message is acceptable.

### Can I call a direct route in another Cameleer process?

No. `direct` works inside one process (one `CamelContext`). Use [vm](https://pmsudhi.github.io/cameleer/docs/components/vm.html) for other contexts in the
same process, and a broker such as [kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html) or a network component between processes.

## Related

- [seda](https://pmsudhi.github.io/cameleer/docs/components/seda.html), [vm](https://pmsudhi.github.io/cameleer/docs/components/vm.html): asynchronous in-process queues
- [EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html)
- [Apache Camel Direct component](https://camel.apache.org/components/next/direct-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/elasticsearch.html

# Elasticsearch component

> The `elasticsearch` component indexes, updates, gets, deletes and searches documents in Elasticsearch over its REST API.

**Scheme:** `elasticsearch:` · **Also:** `opensearch:` (same component, see [opensearch](https://pmsudhi.github.io/cameleer/docs/components/opensearch.html)) · **Crate:** `cameleer-datastores` · **Cargo feature:** [`datastores`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Elasticsearch](https://camel.apache.org/components/next/elasticsearch-component.html)

## When to use it

- Index documents, logs or events as they flow through a route.
- Retrieval for AI agents: run a full-text search and pass the top documents to an LLM as
  context (retrieval-augmented generation).
- Bulk-load or re-index data, and scroll through large result sets.

## URI format

```text
elasticsearch://clusterName?hostAddresses=host:9200&operation=<op>[&indexName=<index>][&options]
```

`clusterName` is a label. `hostAddresses` is a comma-separated list tried in order (default
`localhost:9200`). Requests use HTTP, or HTTPS with `enableSSL=true`.

## Example

`POST /articles` indexes the JSON body into the `articles` index and returns the document id.

```yaml
- route:
    id: index-article
    from:
      uri: "platform-http:/articles?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - to: "elasticsearch://search?hostAddresses={{env:ES_HOSTS:localhost:9200}}&user={{env:ES_USER:elastic}}&password={{env:ES_PASSWORD:changeme}}&operation=Index&indexName=articles"
```

`GET /search?q=rust` returns the three best-matching articles. Put the result in a prompt and
an LLM can answer from your own documents. Queries with characters other than letters, digits,
spaces and simple punctuation are rejected, because the query text is placed inside JSON.

```yaml
- route:
    id: search-articles
    from:
      uri: "platform-http:/search?httpMethodRestrict=GET"
      steps:
        - filter:
            simple: "${header.q} !regex '^[A-Za-z0-9 ,.?_-]+$'"
            steps:
              - setHeader:
                  name: CamelHttpResponseCode
                  constant: 400
              - setBody:
                  constant: "invalid query"
              - stop: {}
        - setBody:
            simple: '{"query": {"match": {"text": "${header.q}"}}}'
        - to: "elasticsearch://search?hostAddresses={{env:ES_HOSTS:localhost:9200}}&user={{env:ES_USER:elastic}}&password={{env:ES_PASSWORD:changeme}}&operation=Search&indexName=articles&size=3&enableDocumentOnlyMode=true"
        - marshal:
            json: {}
```

A body that is JSON text, like the one built by `setBody` above, is sent as the full search
request, so it must contain `query` (and can add `knn`, `aggs` or `sort`). A body that is a map
is treated as the query and wrapped into `{"query": ...}`, unless it already has a `query` key.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("direct:index")
        .to("elasticsearch://search?hostAddresses=localhost:9200&operation=Index&indexName=articles");
    b.from("direct:search")
        .to("elasticsearch://search?hostAddresses=localhost:9200&operation=Search&indexName=articles&enableDocumentOnlyMode=true");
})?;
```

## Operations

| operation | body | result |
|---|---|---|
| `Index` | document | the id (header `indexId` sets it, else generated) |
| `Update` | partial document (wrapped in `{"doc": ...}` unless it has `doc`, `script` or `upsert`) | the id |
| `Bulk` | list of documents, or of `{"index"/"create"/"update"/"delete": {...}}` actions | the item results |
| `GetById` | the id (or header `indexId`) | the response, or the `_source` with `enableDocumentOnlyMode` |
| `MultiGet` | list of ids | the responses or documents |
| `Delete` | the id | the result, for example `deleted` |
| `DeleteIndex` | | `acknowledged` |
| `Exists` | | whether the index exists |
| `Search` | query object or full request | the `hits` object, or the documents with `enableDocumentOnlyMode` |
| `MultiSearch` | list of search requests | the responses or documents |
| `Ping` | | whether the cluster answers |

Operation names are case-insensitive; `BulkIndex` is accepted for `Bulk`.

## Options

| option | default | description |
|---|---|---|
| `hostAddresses` | `localhost:9200` | comma-separated `host:port` list, tried in order |
| `operation` | | operation (header `operation` overrides it) |
| `indexName` | | index (header `indexName` overrides it) |
| `from`, `size` | | paging for searches |
| `enableDocumentOnlyMode` | `false` | return `_source` documents instead of response objects |
| `user`, `password` | | basic authentication |
| `apiKey` | | sent as `Authorization: ApiKey <value>` |
| `enableSSL` | `false` | HTTPS; trust from `sslContextParameters=#bean`, the global `camel.ssl.*` parameters or the system store |
| `connectionTimeout` | `30s` | connect timeout |
| `socketTimeout` | `30s` | read timeout |
| `useScroll` | `false` | run `Search` as a scroll search and return all hits |
| `scrollKeepAliveMs` | `60000` | scroll context keep-alive |
| `enableSniffing` | `false` | replace `hostAddresses` with the nodes from `GET /_nodes/http` |
| `sniffInterval` | `300000` | milliseconds between sniffs |
| `sniffAfterFailureDelay` | `60000` | milliseconds before sniffing again after a connection failure |
| `documentClass` | | map `_source` documents to declared fields: an inline spec such as `title:string,year:int,price:double`, or a `#bean` |

`maxRetryTimeout`, `certificatePath` (use `sslContextParameters`), `waitForActiveShards` and
`connectionManagerMaxConnections` are accepted and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `operation` | in | operation for this exchange |
| `indexName` | in | index for this exchange |
| `indexId` | in | document id for `Index`, `Update`, `GetById`, `Delete` |
| `size`, `from` | in | paging for searches |
| `documentClass` | in | typed documents for this exchange |

With `useScroll=true` the exchange property `CamelElasticsearchScrollQueryCount` holds the number
of scroll requests.

## Run it with Docker

```sh
docker run --rm -p 8080:8080 -e ES_HOSTS=es1.example.com:9200 -e ES_USER=app -e ES_PASSWORD \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/articles.camel.yaml
```

## Common questions

### How do I connect to Elastic Cloud?

Use `hostAddresses=<deployment>.es.<region>.cloud.es.io:443&enableSSL=true&apiKey=<encoded key>`.

### Can I run vector (kNN) search?

Send a full search request with a `knn` section as the body; it is passed to Elasticsearch as is.
Computing the query vector is up to you, for example with the [openai](https://pmsudhi.github.io/cameleer/docs/components/openai.html) embeddings
endpoint. The embedded test server does not implement kNN, so this path is not covered by tests.

### How do I get all results, not just the first page?

Set `useScroll=true`. Every page is fetched with `_search/scroll` and the scroll context is
cleared at the end.

## Related

- [opensearch](https://pmsudhi.github.io/cameleer/docs/components/opensearch.html): the same component for OpenSearch.
- [AI components guide](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html)
- [Apache Camel Elasticsearch component](https://camel.apache.org/components/next/elasticsearch-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/exec.html

# Exec component

> The `exec` component runs a local program or script from a route, writes the message body to its standard input and returns its standard output as the new body.

**Scheme:** `exec:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Exec](https://camel.apache.org/components/next/exec-component.html)

## When to use it

- Call an existing command-line tool or script from an integration (convert a file, run a diagnostic).
- On an edge gateway, read device state with a local command (`vcgencmd`, `nvidia-smi`, `df`) on a timer.
- Let an AI agent route run a fixed, allow-listed command as a tool. Keep the executable fixed in the
  route; never build it from model output.

## URI format

```text
exec:executable[?options]
```

## Example

```yaml
- route:
    id: record-tool-version
    from:
      uri: timer:version
      parameters:
        repeatCount: 1
        delay: 0
      steps:
        - to: exec:git?args=--version&timeout=5000
        - log: "exit ${header.CamelExecExitValue}: ${body}"
        - to: log:versions
```

At startup the route runs `git --version` once; the body becomes the output, such as `git version 2.47.0`.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("timer:version?repeatCount=1&delay=0")
            .route_id("record-tool-version")
            .to("exec:git?args=--version&timeout=5000")
            .log("exit ${header.CamelExecExitValue}: ${body}")
            .to("log:versions");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `args` | | Arguments, separated by spaces. Quote an argument that contains spaces with `"`. |
| `workingDir` | current directory | Directory to run the program in. |
| `timeout` | none | Kill the program and fail with `ExecException` after this many ms. |
| `outFile` | | Use the content of this file as the result instead of standard output. |
| `useStderrOnEmptyStdout` | `false` | Use standard error as the body when standard output is empty. |
| `exitValues` | any | Comma separated list of accepted exit codes; any other code fails with `ExecException`. |
| `binding`, `commandExecutor`, `commandLogLevel`, `lazyStartProducer` | | Accepted and ignored. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelExecCommandExecutable` | in | Overrides the executable. |
| `CamelExecCommandArgs` | in | Overrides `args` (a string or a list). |
| `CamelExecCommandWorkingDir` | in | Overrides `workingDir`. |
| `CamelExecCommandTimeout` | in | Overrides `timeout` (ms). |
| `CamelExecCommandOutFile` | in | Overrides `outFile`. |
| `CamelExecUseStderrOnEmptyStdout` | in | Overrides `useStderrOnEmptyStdout`. |
| `CamelExecExitValue` | out | The exit code. |
| `CamelExecStderr` | out | Standard error output. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/version.camel.yaml
```

The program must exist inside the container. The image is minimal, so build your own image `FROM
pmsudhi/cameleer` with the tools you need.

## Common questions

### Does exec use a shell?

No. The program is started directly with its arguments, so pipes and `*` do not work. To use them, run
`exec:sh?args=-c "your | pipeline"` explicitly.

### How do I fail the route when the command fails?

Set `exitValues=0`. Any other exit code then fails the exchange with `ExecException`.

### Is the message body passed to the program?

Yes. A non-null body is written to standard input.

## Related

- [stream](https://pmsudhi.github.io/cameleer/docs/components/stream.html), [timer](https://pmsudhi.github.io/cameleer/docs/components/timer.html)
- [Apache Camel Exec component](https://camel.apache.org/components/next/exec-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/fhir.html

# FHIR component

> The `fhir` component reads and writes healthcare data on a FHIR server (R4, R4B, R5, DSTU3): create, read, update, delete, search, history, transactions, operations, patch and validation.

**Scheme:** `fhir:` · **Crate:** `cameleer-soap` · **Cargo feature:** [`soap`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [FHIR](https://camel.apache.org/components/next/fhir-component.html)

Cameleer implements the FHIR REST API and the JSON and XML formats itself (no HAPI). Resources
are maps on the Camel side (`${body[id]}`, `${body[resourceType]}`), and can be sent as values
or as FHIR JSON / XML text.

## When to use it

- Turn readings from medical devices at the edge (blood pressure cuffs, glucose meters) into FHIR
  `Observation` resources.
- Sync patients or appointments between an EHR and other systems.
- Search a FHIR server and feed the results to reports or to an AI assistant that summarizes a
  patient record.

## URI format

```text
fhir://api/method?serverUrl=https://host/fhir[&options]
```

| api / method | main parameter (body) | result |
|---|---|---|
| `create/resource` | `resource` | the created resource |
| `read/resourceById` | `id` (with `resourceClass` / `type`) | the resource |
| `read/resourceByUrl` | `url` | the resource |
| `update/resource` | `resource` | the updated resource |
| `delete/resource`, `delete/resourceById`, `delete/resourceConditionalByUrl` | `resource` / `id` / `url` | `OperationOutcome` or null |
| `search/searchByUrl` | `url`, e.g. `Patient?family=Chalmers` | a `searchset` Bundle |
| `history/onInstance`, `onType`, `onServer` | | a `history` Bundle |
| `transaction/withBundle`, `withResources` | `bundle` / `resources` | the response Bundle / resources |
| `capabilities/ofType` | | the `CapabilityStatement` |
| `load-page/next`, `previous`, `byUrl` | `bundle` / `url` | the linked Bundle |
| `operation/onServer`, `onType`, `onInstance`, `onInstanceVersion`, `processMessage` | `parameters` / `bundle` | the operation's response |
| `patch/withBody`, `withUrl` | `patchBody` | the patched resource |
| `meta/getFromServer`, `getFromType`, `getFromResource`, `add`, `delete` | `meta` | the `Meta` |
| `validate/resource` | `resource` | an `OperationOutcome` |

## Example

A gateway endpoint for blood pressure cuffs. A reading such as
`{"patient": "123", "systolic": 128}` becomes a FHIR R4 `Observation` on the server, and the
endpoint answers `201` with the new resource id.

```yaml
- route:
    id: bp-to-fhir
    from:
      uri: platform-http:/readings/blood-pressure?httpMethodRestrict=POST
      steps:
        - unmarshal:
            json: {}
        - removeHeaders:
            pattern: "*"
        - setBody:
            simple: '{"resourceType": "Observation", "status": "final", "code": {"text": "Systolic blood pressure"}, "subject": {"reference": "Patient/${body[patient]}"}, "valueQuantity": {"value": ${body[systolic]}, "unit": "mmHg"}}'
        - to: "fhir://create/resource?serverUrl={{env:FHIR_SERVER:http://localhost:8080/fhir}}&fhirVersion=R4"
        - setBody:
            simple: '{"observation": "${body[id]}"}'
        - removeHeaders:
            pattern: "*"
        - setHeader:
            name: CamelHttpResponseCode
            constant: 201
        - setHeader:
            name: Content-Type
            constant: application/json
```

## Rust DSL

```rust
fn bp_to_fhir_route(b: &mut RouteBuilder, server: &str) {
    b.from("platform-http:/readings/blood-pressure?httpMethodRestrict=POST")
        .route_id("bp-to-fhir")
        .unmarshal_json()
        .remove_headers("*")
        .set_body(simple(r#"{"resourceType": "Observation", "status": "final", "code": {"text": "Systolic blood pressure"}, "subject": {"reference": "Patient/${body[patient]}"}, "valueQuantity": {"value": ${body[systolic]}, "unit": "mmHg"}}"#))
        .to(&format!("fhir://create/resource?serverUrl={}&fhirVersion=R4", server))
        .set_body(simple(r#"{"observation": "${body[id]}"}"#))
        .remove_headers("*")
        .set_header("CamelHttpResponseCode", constant(201))
        .set_header("Content-Type", constant("application/json"));
}
```

## Options

| option | default | description |
|---|---|---|
| `serverUrl` | | FHIR base URL. Required. |
| `fhirVersion` | `R4` | `DSTU3`, `R4`, `R4B` or `R5`: selects the resource definitions. |
| `encoding` | `JSON` | `JSON` or `XML` on the wire. |
| `prettyPrint` | `false` | Pretty-print request bodies. |
| `inBody` | per method | Which parameter the body supplies. |
| `username`, `password` | | Basic authentication. |
| `accessToken` | | Bearer token. |
| `socketTimeout` / `receiveTimeout`, `connectionTimeout` | 60000, 30000 | Timeouts in ms. |
| `sslContextParameters` | | `#bean` for `https`. |
| method parameters | | `resource`, `resourceAsString`, `resourceClass`, `type`, `resourceType`, `id`, `stringId`, `version`, `url`, `bundle`, `resources`, `count`, `extraParameters`, `preferReturn`, `name`, `parameters`, `useHttpGet`, `returnType`, `respondToUri`, `asynchronous`, `patchBody`, `meta`, `profile`. |

`log`, `compress`, `summary`, `validationMode`, `proxyHost` and other HAPI client options are
accepted and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelFhir.<parameter>` | in | Any method parameter, e.g. `CamelFhir.id`; headers win over options. |
| `CamelFhirValidationSuccessful` | out | `validate/resource`: whether the outcome has no errors. |
| `Location`, `ETag` | out | Copied from the server response. |

HTTP errors fail with the HAPI exception names: `ResourceNotFoundException`,
`ResourceGoneException`, `InvalidRequestException`, `AuthenticationException`,
`UnprocessableEntityException` and others, with the `OperationOutcome` diagnostics as the
message.

## Run it with Docker

```sh
docker run --rm -p 8080:8080 -e FHIR_SERVER=https://fhir.example.org/fhir \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/bp-to-fhir.camel.yaml
curl -XPOST -H 'Content-Type: application/json' -d '{"patient": "123", "systolic": 128}' \
  localhost:8080/readings/blood-pressure
```

## Common questions

### How do I read a patient by id?
`fhir://read/resourceById?serverUrl=...&resourceClass=Patient` with the id as the body (or
`CamelFhir.id`); `Patient/123` is accepted too.

### How do I search?
`fhir://search/searchByUrl?serverUrl=...` with a body like `Patient?family=Chalmers`. The
result is a `searchset` Bundle; split `${body[entry]}` to process each match.

### Can I validate a resource against a profile without a server?
Yes: `validate/resource` with `profile` set to a StructureDefinition (file, `#bean` or text)
validates locally.

### Which FHIR versions are supported?
DSTU3, R4, R4B and R5, selected with `fhirVersion`.

## Related

- [http](https://pmsudhi.github.io/cameleer/docs/components/http.html), [rest](https://pmsudhi.github.io/cameleer/docs/components/rest.html), [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html).
- Data formats: `fhirJson`, `fhirXml`.
- Apache Camel: [FHIR component](https://camel.apache.org/components/next/fhir-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/file.html

# File component

> The `file` component reads files from a directory (polling for new ones) and writes message bodies to files.

**Scheme:** `file:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [File](https://camel.apache.org/components/next/file-component.html)

## When to use it

- Watch a drop folder on an edge gateway: machines, scanners or other programs write files, a
  route picks each one up, processes it and moves it aside.
- Write exports, reports or received messages to disk.
- Feed documents from a folder into an AI pipeline (summarize, classify, extract) one file at a
  time.

## URI format

```text
file:directoryName[?options]
```

The directory is relative to the working directory unless it is absolute. On Windows, use
forward slashes (`file:C:/data/inbox`).

## Example

A drop folder for CSV files. A file is picked up only after its size has stopped changing
(`readLock=changed`), copied to the outbox under a new name, and moved into a dated archive
folder; on failure it goes to `.failed`.

```yaml
- route:
    id: drop-folder
    from:
      uri: "file:{{env:INBOX:inbox}}?include=.*\\.csv&readLock=changed&move=.done/${date:now:yyyyMMdd}/${file:name}&moveFailed=.failed"
      steps:
        - log: "picked up ${file:name} (${file:size} bytes)"
        - to: "file:{{env:OUTBOX:outbox}}?fileName=${file:name.noext}-processed.csv&tempPrefix=.part-"
```

`tempPrefix` writes to a temporary name first and renames when complete, so a program watching
the outbox never sees a half-written file.

## Rust DSL

```rust
fn drop_folder_route(b: &mut RouteBuilder, inbox: &str, outbox: &str) {
    b.from(&format!("file:{}?include=.*\\.csv&readLock=changed&move=.done/${{date:now:yyyyMMdd}}/${{file:name}}&moveFailed=.failed", inbox))
        .route_id("drop-folder")
        .log("picked up ${file:name} (${file:size} bytes)")
        .to(&format!("file:{}?fileName=${{file:name.noext}}-processed.csv&tempPrefix=.part-", outbox));
}
```

## Options

Consumer:

| option | default | description |
|---|---|---|
| `delay` | `500` | Milliseconds between polls (with `initialDelay` 1000, `useFixedDelay`, `greedy`, `timeUnit`, `startScheduler`, `sendEmptyMessageWhenIdle`, `scheduler`). |
| `noop` | `false` | Leave files in place (implies `idempotent=true`). |
| `delete` | `false` | Delete files after processing. |
| `move` | `.camel` | Where to move processed files (file language expression). |
| `moveFailed` | | Where to move files whose processing failed. |
| `preMove` | | Where to move files before processing. |
| `include`, `exclude` | | Regular expressions on the file name. |
| `includeExt`, `excludeExt` | | Comma-separated extensions, e.g. `csv,txt`. |
| `antInclude`, `antExclude` | | Ant patterns on the relative path, e.g. `**/*.xml`. `antFilterCaseSensitive` (default `true`). |
| `fileName` | | Consume only this file (expression). |
| `filter` | | `#bean` with a custom file filter. |
| `recursive` | `false` | Also read subdirectories (`minDepth`, `maxDepth`). |
| `maxMessagesPerPoll` | `0` | Limit per poll (`0` = no limit). |
| `sortBy` | | `file:name`, `file:modified` or `file:size`, with `reverse:` / `ignoreCase:` prefixes; groups separated by `;`. |
| `shuffle` | `false` | Random order. |
| `readLock` | `none` | `markerFile`, `changed`, `fileLock`, `rename`, or `none`. |
| `readLockCheckInterval`, `readLockTimeout`, `readLockMinLength`, `readLockMinAge` | 1000 ms, 10000 ms, 1, 0 | Read lock tuning. |
| `readLockMarkerFile`, `readLockDeleteOrphanLockFiles` | `true` | Marker file handling. |
| `idempotent`, `idempotentKey`, `idempotentRepository` | | Skip files already processed. |
| `doneFileName` | | Only consume a file when this done file exists. |
| `charset` | | Read the body as text in this charset. |
| `includeHiddenFiles`, `includeHiddenDirs` | `false` | Also read hidden entries. |
| `startingDirectoryMustExist`, `directoryMustExist` | `false` | Fail when the directory is missing. |
| `autoCreate` | `true` | Create the directory. |

Producer:

| option | default | description |
|---|---|---|
| `fileName` | message id | File name expression; header `CamelFileName` also sets it. |
| `fileExist` | `Override` | `Override`, `Append`, `Fail`, `Ignore`, `Move` (with `moveExisting`), `TryRename`. |
| `tempFileName`, `tempPrefix` | | Write to a temporary name, then rename. |
| `doneFileName` | | Write a done file after the file. |
| `appendChars` | | Characters appended after each write (e.g. `\n`). |
| `charset` | | Encoding of string bodies. |
| `flatten` | `false` | Drop directories from the file name. |
| `keepLastModified` | `false` | Keep the `CamelFileLastModified` time. |
| `allowNullBody` | `false` | Write an empty file for a null body. |
| `eagerDeleteTargetFile` | `true` | Delete an existing target before renaming a temp file. |
| `jailStartingDirectory` | `true` | Refuse to write outside the directory. |
| `autoCreate` | `true` | Create missing directories. |

Expressions support `${file:name}`, `${file:name.noext}`, `${file:ext}`, `${file:onlyname}`,
`${file:parent}`, `${file:path}`, `${file:absolute.path}`, `${file:size}`, `${file:modified}`,
`${date:now:FORMAT}`, `${date:file:FORMAT}`, `${exchangeId}` and any other Simple expression.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelFileName` | out / in | Relative file name; producer: target name. |
| `CamelFileNameOnly` | out | Name without path. |
| `CamelFileAbsolutePath`, `CamelFileAbsolute` | out | Absolute path / whether the path is absolute. |
| `CamelFileRelativePath`, `CamelFilePath`, `CamelFileParent` | out | Path details. |
| `CamelFileLength` | out | Size in bytes. |
| `CamelFileLastModified` | out | Modification time. |
| `CamelFileNameConsumed` | out | Name of the consumed file. |
| `CamelFileNameProduced` | out | Producer: the absolute path written. |
| `CamelOverruleFileName` | in | Producer: overrides the name once. |

The body of a consumed file is its bytes. File errors raise `GenericFileOperationFailedException`.

## Run it with Docker

```sh
mkdir -p inbox outbox
docker run --rm --user "$(id -u):$(id -g)" -e INBOX=/data/inbox -e OUTBOX=/data/outbox \
  -v "$PWD:/data" -v "$PWD/drop-folder.camel.yaml:/routes/drop-folder.camel.yaml:ro" \
  pmsudhi/cameleer run /routes/drop-folder.camel.yaml
```

The data folder is mounted writable; the route file stays read-only.

## Common questions

### How do I avoid reading a file that is still being written?
Use `readLock=changed` (waits until the size and time stop changing), or have the writer use a
done file (`doneFileName`) or a temporary name that the `include` pattern does not match.

### How do I keep the original file where it is?
`noop=true`. Cameleer remembers the files it has read (in memory, or in an
`idempotentRepository`).

### How do I process files in order?
`sortBy=file:modified` (oldest first) or `sortBy=reverse:file:name`.

### Where do processed files go by default?
Into a `.camel` subfolder, as in Apache Camel. Set `move`, `delete=true` or `noop=true` to change
that.

## Related

- [ftp](https://pmsudhi.github.io/cameleer/docs/components/ftp.html), [ftps](https://pmsudhi.github.io/cameleer/docs/components/ftps.html), [sftp](https://pmsudhi.github.io/cameleer/docs/components/sftp.html): the same options for remote servers.
- Apache Camel: [File component](https://camel.apache.org/components/next/file-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/freemarker.html

# FreeMarker component

> The `freemarker` component renders a FreeMarker (FTL) template against the message and sets the rendered text as the new body.

**Scheme:** `freemarker:` · **Crate:** `cameleer-core` · **Cargo feature:** [`templates`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [FreeMarker](https://camel.apache.org/components/next/freemarker-component.html)

## When to use it

- Build a JSON request for an LLM API from an incoming message, with `?json_string` escaping
  so user text cannot break the JSON.
- Render documents with logic: conditionals, loops with separators, macros, number formats.
- Reuse existing FreeMarker templates from a Java Camel application unchanged.

## URI format

```text
freemarker:templateResource[?options]
```

`templateResource` is a file path relative to the working directory, `file:path`,
`classpath:path` (read as a relative path) or `ref:beanName` (a `String` in the registry).

## Example

Turn a support ticket into an OpenAI-style chat completion request. The template escapes the
ticket text with `?json_string`, lists the tags with `<#sep>` and picks the model by priority.

```text
{
  "model": "<#if body.priority == "high">gpt-4o<#else>gpt-4o-mini</#if>",
  "messages": [
    {"role": "system", "content": "Classify the ticket. Tags: <#list body.tags as t>${t}<#sep>, </#list>."},
    {"role": "user", "content": "${body.text?json_string}"}
  ],
  "max_tokens": ${headers.maxTokens}
}
```

```yaml
- route:
    id: freemarker-request
    from:
      uri: direct:freemarker-request
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: maxTokens
            constant: 200
        - to: freemarker:templates/chat-request.ftl
```

```json
{"priority":"high","tags":["billing","refund"],"text":"I was charged twice, see \"order 42\"."}
```

```json
{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "Classify the ticket. Tags: billing, refund."},
    {"role": "user", "content": "I was charged twice, see \"order 42\"."}
  ],
  "max_tokens": 200
}
```

### Built-ins and defaults

Missing values are errors in FreeMarker. Use `!` for a default and `??` to test presence:

```text
Hello ${body.name?cap_first}<#if body.vip??> (VIP)</#if>, you have ${body.points!0} points.
```

```yaml
- route:
    id: freemarker-defaults
    from:
      uri: direct:freemarker-defaults
      steps:
        - unmarshal:
            json: {}
        - to: freemarker:templates/greeting.ftl
```

```json
{"name":"ada","vip":true,"points":120}
```

```text
Hello Ada (VIP), you have 120 points.
```

```json
{"name":"bo"}
```

```text
Hello Bo, you have 0 points.
```

## Rust DSL

```rust
b.from("direct:freemarker-rust")
    .unmarshal(DataFormatDefinition::json())
    .to("freemarker:templates/greeting.ftl");
```

## Options

| option | default | description |
|---|---|---|
| `allowTemplateFromHeader` | `false` | Use the `CamelFreemarkerTemplate` / `CamelFreemarkerResourceUri` headers when present. |
| `contentCache` | `false` | Read the template once; otherwise it is re-read for every message. |
| `allowContextMapAll` | `false` | Add `camelContext` (with `name`) to the data model. |
| `encoding` | UTF-8 | Accepted; templates are always read as UTF-8. |
| `configuration`, `templateUpdateDelay`, `localizedLookup` | | Accepted and ignored (Java FreeMarker settings). |

The data model is the same as for the other template components: `body`, `headers`,
`variables`, `exchange` (`exchange.properties`, `exchange.exchangeId`...), `request` / `in`,
and `camelContext` with `allowContextMapAll=true`.

### Supported FTL

Interpolations `${...}`, comments `<#-- -->`, `if/elseif/else`, `list` (with `items`, `sep`,
`else`, `break`, `continue`), `assign/global/local`, `macro` and `<@name/>` calls, `function`,
`include`, `import`, `switch/case`, `attempt/recover`, `compress`, `noparse`, HTML/XML
auto-escaping (`outputformat`, `autoesc`), `setting` for `number_format` and `boolean_format`;
the string, number, boolean, sequence and hash built-ins (`upper_case`, `cap_first`,
`json_string`, `replace`, `split`, `string("0.00")`, `size`, `join`, `sort_by`, `filter`,
`map`, `keys`...), defaults `x!d` and missing tests `x??`. **Dates and times are not
supported.**

## Message headers

| header | direction | description |
|---|---|---|
| `CamelFreemarkerTemplate` | in | Template text used instead of the resource (needs `allowTemplateFromHeader=true`). |
| `CamelFreemarkerResourceUri` | in | Template resource used instead of the endpoint's one (needs `allowTemplateFromHeader=true`). |
| `CamelFreemarkerDataModel` | in | A map used as the whole data model instead of the default one. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/chat-request.camel.yaml
```

Relative template paths resolve against `/routes`, the image's working directory.

## Common questions

### How do I put user text inside a JSON template safely?

Use `${value?json_string}`; it escapes quotes, backslashes and control characters. The example
above embeds a ticket that contains quotes.

### Why does my template fail with "has evaluated to null or missing"?

FreeMarker treats a missing value as an error. Give a default (`${body.points!0}`) or test it
first (`<#if body.vip??>`).

### Can I keep a FreeMarker template inside the YAML route?

Use `allowTemplateFromHeader=true` and set `CamelFreemarkerTemplate` with `constant:`. Do not
use `simple:` for it: Simple would evaluate the `${...}` interpolations itself. Files are
easier to read and edit.

## Related

- [Mustache](https://pmsudhi.github.io/cameleer/docs/components/mustache.html), [Velocity](https://pmsudhi.github.io/cameleer/docs/components/velocity.html), [StringTemplate](https://pmsudhi.github.io/cameleer/docs/components/string-template.html),
  [MVEL](https://pmsudhi.github.io/cameleer/docs/components/mvel.html).
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html).
- [Apache Camel FreeMarker component](https://camel.apache.org/components/next/freemarker-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/ftp.html

# FTP component

> The `ftp` component downloads files from and uploads files to an FTP server, polling a remote directory for new files.

**Scheme:** `ftp:` · **Crate:** `cameleer-protocols` · **Cargo feature:** [`protocols`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [FTP](https://camel.apache.org/components/next/ftp-component.html)

The options and headers follow the [file](https://pmsudhi.github.io/cameleer/docs/components/file.html) component. For TLS use [ftps](https://pmsudhi.github.io/cameleer/docs/components/ftps.html); for
SSH use [sftp](https://pmsudhi.github.io/cameleer/docs/components/sftp.html).

## When to use it

- Collect files that remote sites, partners or machines drop on an FTP server.
- Upload exports and reports to a partner's FTP server.
- Move files from FTP into object storage, a database or a message broker.

## URI format

```text
ftp://[username@]host[:port]/directory[?options]
```

The directory is relative to the login directory; `ftp://host//abs/dir` is absolute. The
default port is 21.

## Example

Collect XML orders that a partner leaves in `outgoing/`, save them locally, and move each file
into `outgoing/.archive` on the server once it has been saved.

```yaml
- route:
    id: collect-orders
    from:
      uri: "ftp://{{env:FTP_USER:camel}}@{{env:FTP_HOST:localhost:21}}/outgoing?password={{env:FTP_PASSWORD:changeme}}&passiveMode=true&include=.*\\.xml&move=.archive&delay=10000"
      steps:
        - log: "received ${file:name} from ${header.CamelFileHost}"
        - to: "file:{{env:LOCAL_DIR:received}}"
```

## Rust DSL

```rust
fn collect_orders_route(b: &mut RouteBuilder, ftp: &str, password: &str, local_dir: &str) {
    b.from(&format!("ftp://{}/outgoing?password={}&passiveMode=true&include=.*\\.xml&move=.archive&delay=10000", ftp, password))
        .route_id("collect-orders")
        .log("received ${file:name} from ${header.CamelFileHost}")
        .to(&format!("file:{}", local_dir));
}
```

## Options

Connection:

| option | default | description |
|---|---|---|
| `username`, `password` | `anonymous` | Login (also `user@` in the URI). |
| `passiveMode` | `false` | Passive mode (needed behind NAT and most firewalls). `false` uses active mode (`PORT`/`EPRT`). |
| `binary` | `false` | `TYPE I`; `false` transfers in ASCII mode with line-ending conversion. |
| `stepwise` | `true` | `CWD` into each directory level. |
| `disconnect` | `false` | Close the connection after each poll or upload. |
| `connectTimeout` | `10s` | Connect timeout. |
| `soTimeout` | `5m` | Control connection read timeout. |
| `timeout` | `30s` | Data connection timeout. |
| `sendNoop` | `true` | Check pooled connections with `NOOP`. |
| `maximumReconnectAttempts`, `reconnectDelay` | 3, 1s | Reconnects. |
| `throwExceptionOnConnectFailed` | `false` | Fail the poll on connect errors. |
| `siteCommand` | | `SITE` commands after login (one per line). |
| `autoCreate` | `true` | Create the remote directory. |
| `charset` | | Text encoding of bodies. |

Consumer: `delay` (500 ms), `initialDelay` (1000 ms) and the scheduler options, `noop`,
`delete`, `move`, `moveFailed`, `preMove`, `include`, `exclude`, `includeExt`, `excludeExt`,
`antInclude`, `antExclude`, `antFilterCaseSensitive`, `fileName`, `recursive`, `minDepth`,
`maxDepth`, `maxMessagesPerPoll`, `sortBy`, `idempotent`, `idempotentKey`,
`idempotentRepository`, `download` (`false` = headers only), `localWorkDirectory` (stream
downloads to a local file instead of memory), `resumeDownload` (continue partial downloads, needs
`localWorkDirectory`), `streamDownload` (body is a stream handle), `ignoreFileNotFoundOrPermissionError`,
`readLock` (`none`, `changed`, `rename`, `idempotent`, `idempotent-changed`, `idempotent-rename`)
with `readLockCheckInterval` (5s), `readLockTimeout` (20s), `readLockMinLength`,
`readLockMinAge`.

Producer: `fileName`, `fileExist` (`Override`, `Append`, `Fail`, `Ignore`, `Move` with
`moveExisting`, `TryRename`), `tempFileName`, `tempPrefix`, `eagerDeleteTargetFile`,
`allowNullBody`, `flatten`, `doneFileName`.

As in Apache Camel, consumed files stay on the server unless `delete`, `move`, `noop` or
`idempotent` is set. Options such as `account`, `chmod`, `bufferSize`, `fastExistsCheck` and the
`ftpClient.*` group are accepted and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelFileName` | out / in | Relative file name; producer: target name. |
| `CamelFileNameOnly`, `CamelFileAbsolutePath`, `CamelFileRelativePath`, `CamelFilePath`, `CamelFileParent` | out | Path details. |
| `CamelFileLength`, `CamelFileLastModified` | out | Size and time. |
| `CamelFileHost` | out | Server host. |
| `CamelFileLocalWorkPath` | out | Local copy with `localWorkDirectory`. |
| `CamelFtpReplyCode`, `CamelFtpReplyString` | out | Last FTP reply. |
| `CamelFtpResumedFrom` | out | Offset a resumed download continued from. |
| `CamelFileNameProduced` | out | Producer: the remote path written. |
| `CamelOverruleFileName` | in | Producer: overrides the name once. |

## Run it with Docker

```sh
docker run --rm --user "$(id -u):$(id -g)" -e FTP_HOST=ftp.partner.example -e FTP_USER -e FTP_PASSWORD \
  -e LOCAL_DIR=/data/received -v "$PWD:/data" \
  -v "$PWD/collect-orders.camel.yaml:/routes/collect-orders.camel.yaml:ro" \
  pmsudhi/cameleer run /routes/collect-orders.camel.yaml
```

## Common questions

### How do I upload a file to FTP?
`to: ftp://user@host/incoming?password=...&passiveMode=true`; the name comes from the
`CamelFileName` header or `fileName`. Add `tempPrefix=.part-` so the partner never reads a
partial file.

### My downloads hang or time out. What should I check?
Most servers behind NAT or a firewall need `passiveMode=true`.

### How do I download large files without holding them in memory?
Set `localWorkDirectory=/tmp/ftp-work` (and `resumeDownload=true` to continue interrupted
transfers), or `streamDownload=true`.

### How do I avoid picking up a file that is still uploading?
`readLock=changed` waits until the size and time stop changing; `readLock=rename` checks that the
file can be renamed.

## Related

- [ftps](https://pmsudhi.github.io/cameleer/docs/components/ftps.html), [sftp](https://pmsudhi.github.io/cameleer/docs/components/sftp.html), [file](https://pmsudhi.github.io/cameleer/docs/components/file.html).
- Apache Camel: [FTP component](https://camel.apache.org/components/next/ftp-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/ftps.html

# FTPS component

> The `ftps` component transfers files with an FTP server over TLS (FTPS), in explicit (`AUTH TLS`) or implicit mode, with encrypted data connections.

**Scheme:** `ftps:` · **Crate:** `cameleer-protocols` · **Cargo feature:** [`protocols`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [FTPS](https://camel.apache.org/components/next/ftps-component.html)

`ftps` has every option of [ftp](https://pmsudhi.github.io/cameleer/docs/components/ftp.html) plus the TLS options below. The server certificate and
host name are always verified. FTPS is FTP over TLS; it is not [sftp](https://pmsudhi.github.io/cameleer/docs/components/sftp.html), which runs over
SSH.

## When to use it

- Send reports or invoices to a partner who requires FTPS.
- Collect files from a bank, a carrier or a public agency that only offers FTPS.
- Upload data from edge sites to a central server without sending credentials in clear text.

## URI format

```text
ftps://[username@]host[:port]/directory[?options]
```

Default port: 21 (explicit), 990 with `isImplicit=true`.

## Example

An edge site uploads finished CSV reports from its outbox to the central server, into a folder
per site, and moves each file to `.sent` locally afterwards.

```yaml
- route:
    id: upload-reports
    from:
      uri: "file:{{env:OUTBOX:outbox}}?include=.*\\.csv&move=.sent"
      steps:
        - to: "ftps://{{env:FTPS_USER:edge}}@{{env:FTPS_HOST:ftp.example.com}}/reports/{{env:SITE_ID:site-1}}?password={{env:FTPS_PASSWORD:changeme}}&passiveMode=true&binary=true&tempPrefix=.part-"
        - log: "uploaded ${file:name}"
```

The server certificate is checked against the system trust store, or against the global
`camel.ssl.*` parameters (for example `camel.ssl.trustStore=/routes/ca.pem`) or an
`sslContextParameters` bean.

## Rust DSL

```rust
fn upload_reports_route(b: &mut RouteBuilder, outbox: &str, ftps: &str, password: &str) {
    b.from(&format!("file:{}?include=.*\\.csv&move=.sent", outbox))
        .route_id("upload-reports")
        .to(&format!("ftps://{}/reports/site-1?password={}&passiveMode=true&binary=true&tempPrefix=.part-", ftps, password))
        .log("uploaded ${file:name}");
}
```

## Options

All [ftp options](https://pmsudhi.github.io/cameleer/docs/components/ftp.html#options), plus:

| option | default | description |
|---|---|---|
| `isImplicit` | `false` | Implicit TLS (TLS from the first byte, port 990). |
| `execPbsz` | `0` | `PBSZ` value sent after login. |
| `execProt` | `P` | `PROT` level: `P` encrypts data connections, `C` leaves them clear. |
| `disableSecureDataChannelDefaults` | `false` | Send `PBSZ` / `PROT` only when set explicitly. |
| `securityProtocol` | | `TLSv1.2`, `TLSv1.3` or `TLS`. |
| `sslContextParameters` | | `#bean` with trust and key material. |
| `useGlobalSslContextParameters` | `false` | Use the global `camel.ssl.*` parameters. |

Data connections resume the control connection's TLS session, which servers configured like
vsftpd `require_ssl_reuse=YES` demand. The `ftpClient.trustStore.*` / `ftpClient.keyStore.*`
options are accepted and ignored; use `sslContextParameters`.

## Message headers

The same as [ftp](https://pmsudhi.github.io/cameleer/docs/components/ftp.html#message-headers).

## Run it with Docker

```sh
docker run --rm --user "$(id -u):$(id -g)" -e FTPS_HOST=ftp.example.com -e FTPS_USER -e FTPS_PASSWORD \
  -e SITE_ID=site-7 -e OUTBOX=/data/outbox -v "$PWD:/data" \
  -v "$PWD/upload-reports.camel.yaml:/routes/upload-reports.camel.yaml:ro" \
  pmsudhi/cameleer run /routes/upload-reports.camel.yaml
```

## Common questions

### Explicit or implicit FTPS?
Most servers use explicit FTPS on port 21 (the default). Use `isImplicit=true` for servers that
expect TLS immediately, usually on port 990.

### The server uses a private CA. How do I trust it?
Set `camel.ssl.trustStore` to the CA's PEM file, or bind an `SSLContextParameters` bean and add
`sslContextParameters=#myTls`. Certificate checks cannot be turned off per endpoint.

### Is FTPS the same as SFTP?
No. FTPS is FTP with TLS; SFTP is a different protocol over SSH. Use [sftp](https://pmsudhi.github.io/cameleer/docs/components/sftp.html) for SSH
servers.

## Related

- [ftp](https://pmsudhi.github.io/cameleer/docs/components/ftp.html), [sftp](https://pmsudhi.github.io/cameleer/docs/components/sftp.html), [file](https://pmsudhi.github.io/cameleer/docs/components/file.html).
- Apache Camel: [FTPS component](https://camel.apache.org/components/next/ftps-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/github.html

# GitHub component

> The `github` component polls a GitHub repository for new pull requests, issues, commits, tags and events, and creates issues, comments and commit statuses through the GitHub REST API.

**Scheme:** `github:` · **Crate:** `cameleer-saas` · **Cargo feature:** [`saas`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [GitHub](https://camel.apache.org/components/next/github-component.html)

## When to use it

- Greet or triage new pull requests and issues automatically (labels, first comment, review bot).
- Let an AI agent open an issue when it finds a bug, a failed job or a security finding.
- Feed new commits or tags into a release, deployment or changelog pipeline.
- Read the files a pull request changes, for example to hand them to an LLM reviewer.

## URI format

```text
github:type[/branch]?repoOwner=owner&repoName=repo[&options]
```

Consumer types: `pullRequest`, `issue`, `commit/<branch>`, `tag`, `event`.
Producer types: `createIssue`, `pullRequestComment`, `issueComment`, `pullRequestState`,
`pullRequestFiles`, `getCommitFile`, `closePullRequest`.

## Example

Comment every new pull request. The consumer sets the `GitHubPullRequest` header to the pull
request number, so the producer knows where to comment. The first poll only records the pull
requests that are already open.

```yaml
- route:
    id: pr-welcome
    from:
      uri: "github:pullRequest?repoOwner={{env:GITHUB_OWNER:apache}}&repoName={{env:GITHUB_REPO:camel}}&oauthToken={{env:GITHUB_TOKEN}}&serverUrl={{env:GITHUB_API_URL:https://api.github.com}}&delay=30000"
      steps:
        - log: "new pull request #${header.GitHubPullRequest}: ${body[title]}"
        - setBody:
            simple: "Thanks for the pull request '${body[title]}'. A maintainer will review it soon."
        - to: "github:pullRequestComment?repoOwner={{env:GITHUB_OWNER:apache}}&repoName={{env:GITHUB_REPO:camel}}&oauthToken={{env:GITHUB_TOKEN}}&serverUrl={{env:GITHUB_API_URL:https://api.github.com}}"
```

An agent that files an issue. Other routes (a failed nightly job, an LLM log analyser) send the
problem description to `direct:file-bug`; the title comes from the `GitHubIssueTitle` header and
the body becomes the issue text. Afterwards the body is the created issue and `GitHubIssue` its
number.

```yaml
- route:
    id: file-bug
    from:
      uri: "direct:file-bug"
      steps:
        - setHeader:
            name: GitHubIssueTitle
            simple: "Nightly job failed: ${header.job}"
        - to: "github:createIssue?repoOwner={{env:GITHUB_OWNER:apache}}&repoName={{env:GITHUB_REPO:camel}}&oauthToken={{env:GITHUB_TOKEN}}&serverUrl={{env:GITHUB_API_URL:https://api.github.com}}"
        - log: "opened issue #${header.GitHubIssue}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("github:pullRequest?repoOwner=apache&repoName=camel&oauthToken={{env:GITHUB_TOKEN}}&delay=30000")
        .set_body(simple("Thanks for the pull request '${body[title]}'. A maintainer will review it soon."))
        .to("github:pullRequestComment?repoOwner=apache&repoName=camel&oauthToken={{env:GITHUB_TOKEN}}");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `repoOwner` | | Repository owner (required). |
| `repoName` | | Repository name (required). |
| `oauthToken` | | Personal access token or GitHub App token, sent as a Bearer token. |
| `startingSha` | `last` | `commit` consumer: `last` skips existing commits, `beginning` delivers them all, oldest first. |
| `state` | | `pullRequestState`: `success`, `error`, `failure` or `pending` (required there). |
| `targetUrl` | | `pullRequestState`: link shown with the status. |
| `encoding` | | `getCommitFile`: `base64` keeps the content base64-encoded instead of decoding it. |
| `hookEvents` | `push,pull_request,issues` | Events subscribed when used through `webhook:github:...`. |
| `serverUrl` | `https://api.github.com` | API base URL (Cameleer extension: GitHub Enterprise `https://ghe.example.com/api/v3`, a test server). |
| `delay`, `initialDelay`, ... | `delay=10000` | Consumers: the standard scheduled-poll options. |

`eventFetchStrategy` is accepted for Camel compatibility and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `GitHubPullRequest` | in / out | Pull request number: set by the `pullRequest` consumer; read by `pullRequestComment`, `pullRequestFiles`, `closePullRequest`. |
| `GitHubIssue` | in / out | Issue number: set by the `issue` consumer and `createIssue`; read by `issueComment`. |
| `GitHubIssueTitle` | in | `createIssue`: the title (required). |
| `GitHubInResponseTo` | in | `pullRequestComment`: reply to this review comment id. |
| `GitHubPullRequestHeadCommitSHA` | in | `pullRequestState`: commit to set the status on. |
| `GitHubCommitSha`, `GitHubCommitAuthor`, `GitHubCommitCommitter`, `GitHubCommitUrl` | out | `commit` consumer (the body is the commit message). |
| `GitHubEvent`, `GitHubEventId`, `CamelGitHubEventPayload` | out | `event` consumer (the body is the event type, such as `PushEvent`). Webhooks set `GitHubEvent` from `X-GitHub-Event`. |

## Run it with Docker

```sh
export GITHUB_TOKEN=ghp_... GITHUB_OWNER=my-org GITHUB_REPO=my-repo
docker run --rm -e GITHUB_TOKEN -e GITHUB_OWNER -e GITHUB_REPO -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/pr-welcome.camel.yaml
```

## Common questions

### How do I get the files of a pull request for an AI review?

Send an exchange with the `GitHubPullRequest` header to `github:pullRequestFiles`: the body
becomes the list of changed files (`filename`, `status`, `additions`, `sha`, ...). Split it and
send each file to `github:getCommitFile` to get the decoded content, then to an LLM.

### Can I receive webhooks instead of polling?

Yes: consume from `webhook:github:pullRequest?repoOwner=...&repoName=...&oauthToken=...&webhookExternalUrl=https://ci.example.com`.
The repository hook is created on start and deleted on stop; the payload becomes the body.

### Does the issue consumer return pull requests?

No. GitHub lists pull requests as issues, but the `issue` consumer filters them out. Use
`pullRequest` for those.

### How do I set a CI status on a commit?

Use `github:pullRequestState?state=success&targetUrl=https://ci.example.com/run/42` with the
`GitHubPullRequestHeadCommitSHA` header; the body becomes the status description.

## Related

- [jira](https://pmsudhi.github.io/cameleer/docs/components/jira.html), [slack](https://pmsudhi.github.io/cameleer/docs/components/slack.html)
- [openai](https://pmsudhi.github.io/cameleer/docs/components/openai.html) and the [AI components guide](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html)
- [Apache Camel GitHub component](https://camel.apache.org/components/next/github-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-bigquery.html

# Google BigQuery component

> The `google-bigquery` component streams rows into Google BigQuery tables, runs load and extract jobs between BigQuery and Cloud Storage, and manages tables and datasets.

**Scheme:** `google-bigquery:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Google BigQuery](https://camel.apache.org/components/next/google-bigquery-component.html)

For SQL queries use [`google-bigquery-sql`](https://pmsudhi.github.io/cameleer/docs/components/google-bigquery-sql.html).

## When to use it

- Stream events from Pub/Sub, Kafka or HTTP into a BigQuery table for analytics.
- Load CSV or JSON files from Cloud Storage into a table on a schedule.
- Export a table to Cloud Storage for another system.
- Log AI agent actions or LLM results (prompt, answer, tokens) to a table for evaluation.

## URI format

```text
google-bigquery://projectId:datasetId[:tableId][?options]
```

Without a table in the URI, the `CamelGoogleBigQueryTableId` header names it.

## Example

Consume JSON events from a Pub/Sub subscription and insert each one as a row. The `id` field is
the insert id, so a redelivered message is not inserted twice:

```yaml
- route:
    id: pubsub-to-bigquery
    from:
      uri: "google-pubsub://{{env:GCP_PROJECT:my-project}}:{{env:PUBSUB_SUBSCRIPTION:events-sub}}"
      steps:
        - unmarshal:
            json: {}
        - to: "google-bigquery://{{env:GCP_PROJECT:my-project}}:{{env:BQ_DATASET:analytics}}:{{env:BQ_TABLE:events}}?useAsInsertId=id"
```

Load newline-delimited JSON files from Cloud Storage into a table once a day (a load job,
polled until it finishes):

```yaml
- route:
    id: nightly-load
    from:
      uri: "timer:nightly-load?period=86400000"
      steps:
        - to: "google-bigquery://{{env:GCP_PROJECT:my-project}}:{{env:BQ_DATASET:analytics}}:{{env:BQ_TABLE:events}}?operation=load&sourceUris=gs://{{env:GCS_BUCKET:my-bucket}}/exports/events.json&sourceFormat=NEWLINE_DELIMITED_JSON&writeDisposition=WRITE_APPEND"
        - log: "load job ${header.CamelGoogleBigQueryJobId} finished"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("google-pubsub://my-project:events-sub")
        .unmarshal(DataFormatDefinition::json())
        .to("google-bigquery://my-project:analytics:events?useAsInsertId=id");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `useAsInsertId` | | Row field used as the insert id (de-duplication). |
| `operation` | `insert` | Cameleer: `insert` (streaming insert), `load`, `extract`, `createTable`, `getTable`, `listTables`, `deleteTable`, `createDataset`, `listDatasets`, `deleteDataset`. Header `CamelGoogleBigQueryOperation`. |
| `createTableIfNotExists` | `false` | Streaming insert: create a missing table with `tableSchema` first. |
| `sourceUris` | | `load`: comma-separated `gs://` URIs (or the header, or a list / text body). |
| `sourceFormat` | `CSV` | `load`: `CSV`, `NEWLINE_DELIMITED_JSON`, `AVRO`, `PARQUET`, ... |
| `skipLeadingRows` | | `load`: header rows to skip (CSV). |
| `fieldDelimiter` | | `load`: CSV delimiter. |
| `writeDisposition` | `WRITE_APPEND` | `load`: `WRITE_APPEND`, `WRITE_TRUNCATE`, `WRITE_EMPTY`. |
| `createDisposition` | | `load`: `CREATE_IF_NEEDED` or `CREATE_NEVER`. |
| `autodetect` | | `load`: detect the schema. |
| `destinationUris` | | `extract`: `gs://` URIs (or the header). |
| `destinationFormat` | `NEWLINE_DELIMITED_JSON` | `extract`: `NEWLINE_DELIMITED_JSON` or `CSV`. |
| `printHeader` | | `extract`: CSV header row. |
| `compression` | | `extract`: compression, for example `GZIP`. |
| `jobPollInterval` | `200` | Milliseconds between job status checks. |
| `jobTimeout` | `60000` | Milliseconds to wait for a job. |
| `tableSchema` | | `createTable`: a list of `{name, type, mode, description}` maps, its JSON text, or `name:TYPE,name:TYPE`. Header `CamelGoogleBigQueryTableSchema`. |
| `timePartitioningField`, `timePartitioningType` | `DAY` | `createTable`: time partitioning. |
| `clusteringFields` | | `createTable`: clustering fields. |
| `tableDescription`, `expirationMs` | | `createTable`: description and expiration. |
| `datasetLocation` | `US` | `createDataset`: location. |
| `deleteContents` | | `deleteDataset`: also delete the tables. |

Credentials are shared by all Google components: see [credentials](https://pmsudhi.github.io/cameleer/docs/components/google-storage.html#credentials).

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGoogleBigQueryTableId` | in | Table (when the URI has none). |
| `CamelGoogleBigQueryTableSuffix` | in | Template suffix: rows go to `table + suffix`. |
| `CamelGoogleBigQueryPartitionDecorator` | in | Partition, for example `20260101` (`table$20260101`). |
| `CamelGoogleBigQueryInsertId` | in | Insert id of the row. |
| `CamelGoogleBigQueryOperation` | in | Cameleer: operation. |
| `CamelGoogleBigQuerySourceUris` | in | Cameleer: `load` source URIs. |
| `CamelGoogleBigQueryDestinationUris` | in | Cameleer: `extract` destination URIs. |
| `CamelGoogleBigQueryJobId` | out | Id of the load or extract job. |

A map body is one row, a list body several rows. Rejected rows raise a `BigQueryException` that
lists the insert errors; a job that ends with an error raises one too.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" \
  -v "$HOME/keys/sa.json:/keys/sa.json:ro" -e GOOGLE_APPLICATION_CREDENTIALS=/keys/sa.json \
  -e GCP_PROJECT=my-project -e BQ_DATASET=analytics -e BQ_TABLE=events \
  pmsudhi/cameleer run /routes/pubsub-to-bigquery.camel.yaml
```

## Common questions

### How do I insert several rows in one request?
Send a list of maps; the whole list is one `insertAll` call.

### How do I avoid duplicate rows on retries?
Set `useAsInsertId` to a unique field (or the `CamelGoogleBigQueryInsertId` header). BigQuery
de-duplicates rows with the same insert id for a short window.

### How do I query BigQuery?
Use [`google-bigquery-sql`](https://pmsudhi.github.io/cameleer/docs/components/google-bigquery-sql.html) with a standard SQL query.

### How is this different from Apache Camel?
Streaming inserts match Camel. Load and extract jobs and table and dataset management are
Cameleer additions.

## Related

- [Google BigQuery SQL](https://pmsudhi.github.io/cameleer/docs/components/google-bigquery-sql.html), [Google Pub/Sub](https://pmsudhi.github.io/cameleer/docs/components/google-pubsub.html), [Google Storage](https://pmsudhi.github.io/cameleer/docs/components/google-storage.html)
- [Apache Camel Google BigQuery](https://camel.apache.org/components/next/google-bigquery-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-bigquery-sql.html

# Google BigQuery SQL component

> The `google-bigquery-sql` component runs standard SQL queries and DML statements on Google BigQuery, with named `@parameters` bound from message headers or the body.

**Scheme:** `google-bigquery-sql:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Google BigQuery Standard SQL](https://camel.apache.org/components/next/google-bigquery-sql-component.html)

## When to use it

- Run a report query on a schedule and send the rows to a file, an API or a chat channel.
- Insert, update or delete rows with DML from incoming messages.
- Give an AI agent a safe, fixed query (only the parameters change) instead of free-form SQL.

## URI format

```text
google-bigquery-sql://projectId:query[?options]
google-bigquery-sql://projectId:file:/path/to/query.sql
```

The query can be written in the URI (URL-encoded where needed) or read from a `file:` or
`classpath:` resource. `@name` parameters are bound from the header `name`, else from the
body map entry `name`. `${header.x}`, `${headers.x}`, `${exchangeProperty.x}` and `${body}`
are substituted into the query text first.

## Example

Every hour, query the large orders and write them to a JSON file:

```yaml
- route:
    id: large-orders-report
    from:
      uri: "timer:report?period=3600000"
      steps:
        - setHeader:
            name: min
            constant: 50
        - to: "google-bigquery-sql://{{env:GCP_PROJECT:my-project}}:SELECT id, customer, total FROM shop.orders WHERE total > @min ORDER BY total DESC"
        - marshal:
            json: {}
        - setHeader:
            name: CamelFileName
            constant: large-orders.json
        - to: "file:{{env:OUT_DIR:out}}"
```

Insert a row for every JSON order posted to an HTTP endpoint; the parameters come from the
body map, and the body becomes the number of inserted rows:

```yaml
- route:
    id: http-to-bigquery
    from:
      uri: "platform-http:/orders?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - to: "google-bigquery-sql://{{env:GCP_PROJECT:my-project}}:INSERT INTO shop.orders (id, customer, total) VALUES (@id, @customer, @total)"
        - setBody:
            simple: "inserted ${body} row(s)"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:report?period=3600000")
        .set_header("min", constant(50))
        .to("google-bigquery-sql://my-project:SELECT id, total FROM shop.orders WHERE total > @min")
        .log("${body}");
})?;
```

## Options

| option | default | description |
|---|---|---|
| (credentials) | | `serviceAccountKey`, `GOOGLE_APPLICATION_CREDENTIALS`, `useMetadataServer`, ...: see [credentials](https://pmsudhi.github.io/cameleer/docs/components/google-storage.html#credentials). |

`connectionFactory` and `projectId` are accepted for Camel compatibility and ignored (the project
is the first part of the URI).

## Message headers

| header | direction | description |
|---|---|---|
| any `name` | in | Value of the `@name` query parameter. |
| `CamelGoogleBigQueryTranslatedQuery` | out | The query after `${...}` substitution. |
| `CamelGoogleBigQueryJobId` | out | Id of the query job. |

The body after the call: the number of affected rows for DML (`INSERT`, `UPDATE`, `DELETE`,
`MERGE`), otherwise a list of rows as maps, with values typed after the result schema
(integers, floats, booleans, strings). All result pages are read.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" -v "$PWD/out:/out" \
  -v "$HOME/keys/sa.json:/keys/sa.json:ro" -e GOOGLE_APPLICATION_CREDENTIALS=/keys/sa.json \
  -e GCP_PROJECT=my-project -e OUT_DIR=/out \
  pmsudhi/cameleer run /routes/large-orders-report.camel.yaml
```

## Common questions

### How do I pass parameters to a BigQuery query?
Write `@name` in the query and set a header `name` (or a body map entry `name`). Missing
parameters fail the exchange with a clear message.

### How do I keep a long query out of the URI?
Put it in a file and use `google-bigquery-sql://my-project:file:/routes/report.sql`.

### Can I use legacy SQL?
No. Queries run as standard SQL (`useLegacySql=false`), as in Camel.

## Related

- [Google BigQuery](https://pmsudhi.github.io/cameleer/docs/components/google-bigquery.html) for streaming inserts and load jobs
- [SQL component](https://pmsudhi.github.io/cameleer/docs/components/sql.html) for relational databases
- [Apache Camel Google BigQuery Standard SQL](https://camel.apache.org/components/next/google-bigquery-sql-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-calendar.html

# Google Calendar component

> The `google-calendar` component creates, lists, updates and deletes Google Calendar events and manages calendars, ACLs and watch channels through the Calendar v3 REST API.

**Scheme:** `google-calendar:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no (see [google-calendar-stream](https://pmsudhi.github.io/cameleer/docs/components/google-calendar-stream.html)) · **Producer:** yes · **Apache Camel:** [Google Calendar](https://camel.apache.org/components/next/google-calendar-component.html)

## When to use it

- Give an AI scheduling assistant a "book meeting" tool that creates events in a user's calendar.
- Create calendar entries from bookings, maintenance windows or on-call rotations.
- Check availability with `freebusy/query` before proposing a time.
- Sync events from another system with `events/list`, `events/update` and `events/delete`.

## URI format

```text
google-calendar://apiName/methodName[?options]
```

Core methods: `events/list`, `events/insert`, `events/get`, `events/update`, `events/patch`,
`events/delete`, `events/quickAdd`, `calendarList/list`, `calendars/get`.
Also: `acl/list|get|insert|update|delete|watch`, `colors/get`, `freebusy/query`,
`settings/list|get|watch`, `calendars/insert|update|delete|clear`,
`calendarList/get|insert|delete|watch`, `events/instances`, `events/move`, `events/import`,
`events/watch`, `channels/stop`. Unknown methods fail when the endpoint is created.

## Example

An HTTP tool that books a meeting: `POST /tools/book-meeting` with a Calendar event as JSON
creates it in the user's calendar, invites the attendees and returns the created event.

```yaml
- route:
    id: book-meeting
    from:
      uri: "platform-http:/tools/book-meeting?httpMethodRestrict=POST"
      steps:
        - to: "google-calendar://events/insert?calendarId={{env:CALENDAR_ID:primary}}&sendUpdates=all&delegate={{env:GOOGLE_USER}}"
        - log: "created event ${body[id]}"
        - marshal:
            json: {}
```

Try it:

```sh
curl -XPOST localhost:8080/tools/book-meeting -H 'Content-Type: application/json' -d '{
  "summary": "Design review",
  "start": {"dateTime": "2026-11-12T10:00:00Z"},
  "end": {"dateTime": "2026-11-12T10:30:00Z"},
  "attendees": [{"email": "ada@example.com"}]}'
```

The event body is a map, or JSON text that is parsed into one. It can also come from the
`CamelGoogleCalendar.content` header.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("platform-http:/tools/book-meeting?httpMethodRestrict=POST")
        .to("google-calendar://events/insert?calendarId={{env:CALENDAR_ID:primary}}&sendUpdates=all&delegate={{env:GOOGLE_USER}}")
        .log("created event ${body[id]}")
        .marshal("json");
})?;
```

## What the core methods do

| api/method | input | body after the call |
|---|---|---|
| `events/list` | `calendarId`, `timeMin`, `timeMax`, `q`, `maxResults`, `singleEvents`, `orderBy` | list of events; all pages unless `maxResults` is set (then one page) |
| `events/insert` | event map (body or `content` header), `sendUpdates` | created event |
| `events/get` | `eventId` | the event |
| `events/update` | `eventId`, full event map, `sendUpdates` | updated event (PUT) |
| `events/patch` | `eventId`, partial event map, `sendUpdates` | updated event (PATCH) |
| `events/delete` | `eventId` | unchanged |
| `events/quickAdd` | `text` option, or the body text (for example `Lunch with Ada tomorrow 12:30`) | created event |
| `calendarList/list` | | list of the user's calendars |
| `calendars/get` | `calendarId` | the calendar |
| `freebusy/query` | content `{timeMin, timeMax, items: [{id}]}` | the free/busy response |
| `events/watch`, `acl/watch`, `calendarList/watch`, `settings/watch` | content `{id, type: web_hook, address, token}` or the `channelId`, `address`, `token` options | the channel; header `CamelGoogleCalendar.resourceId` |
| `channels/stop` | `channelId`, `resourceId` | |

Push notifications from a watch channel arrive as HTTP POSTs to your `address`, with the
`X-Goog-Channel-ID`, `X-Goog-Resource-ID`, `X-Goog-Resource-State` (`sync`, `exists`, ...),
`X-Goog-Message-Number` and `X-Goog-Channel-Token` headers. Receive them with
[platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html).

## Options

| option | default | description |
|---|---|---|
| `calendarId` | `primary` | Calendar to use (`primary` or a calendar id such as `team@group.calendar.google.com`). |
| `eventId` | | Event id for `events/get`, `update`, `patch`, `delete`, `instances`, `move`. |
| `timeMin`, `timeMax` | | RFC 3339 bounds for `events/list`. |
| `q` | | Free-text search for `events/list`. |
| `maxResults` | | Page size; when set, only one page is returned. |
| `singleEvents` | | `true` expands recurring events into instances. |
| `orderBy` | | `startTime` (needs `singleEvents=true` on the real API) or `updated`. |
| `text` | | Text for `events/quickAdd`. |
| `sendUpdates` | | `all`, `externalOnly` or `none`: whether attendees get e-mails for `insert`, `update`, `patch`. |
| `ruleId`, `setting`, `destination`, `channelId`, `address`, `token`, `resourceId`, `syncToken`, `sendNotifications` | | Parameters of the ACL, settings, move and watch methods. |
| `delegate` (alias `subject`) | | User to impersonate with domain-wide delegation. |
| `scopes` | `https://www.googleapis.com/auth/calendar` | Comma separated OAuth scopes. |
| `serviceAccountKey` | `GOOGLE_APPLICATION_CREDENTIALS` | Service account JSON key: `file:path`, a plain path or inline JSON. |
| `clientId`, `clientSecret`, `refreshToken` | | OAuth user credentials (refresh-token flow). |
| `accessToken` | | A fixed OAuth access token. |
| `tokenServerUrl` | `https://oauth2.googleapis.com/token` | Token endpoint for the refresh-token flow (Cameleer). |
| `uriEndpointOverride` + `overrideEndpoint=true` | | Base URL of an emulator or proxy. |

`useMetadataServer`, `authenticate`, `proxyHost`, `proxyPort` and `trustAllCertificates` work as
on the [google-sheets](https://pmsudhi.github.io/cameleer/docs/components/google-sheets.html#options) page. `applicationName`, `inBody` and
`splitResult` are accepted and ignored.

## Message headers

Every option can also be set per message with a `CamelGoogleCalendar.<option>` header (for
example `CamelGoogleCalendar.eventId`), which wins over the URI option.

| header | direction | description |
|---|---|---|
| `CamelGoogleCalendar.content` | in | Event or request map (instead of the body). |
| `CamelGoogleCalendar.eventId` | in | Event id. |
| `CamelGoogleCalendar.resourceId` | out | Resource id of a created watch channel. |

## Run it with Docker

```sh
docker run --rm -p 8080:8080 \
  -e GOOGLE_USER=ada@example.com \
  -e GOOGLE_APPLICATION_CREDENTIALS=/secrets/key.json \
  -v "$PWD/key.json:/secrets/key.json:ro" \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/book-meeting.camel.yaml
```

## Common questions

### How do I create a Google Calendar event from a route?
Send an event map with `summary`, `start` and `end` to
`google-calendar://events/insert?calendarId=primary`. Add `sendUpdates=all` to e-mail attendees.

### How do I update only one field of an event?
Use `events/patch` with `CamelGoogleCalendar.eventId` and a map holding just that field, for
example `{"location": "Room 2"}`.

### Can a service account use its own calendar?
Yes, without `delegate` it uses the service account's calendar. To act on a person's calendar,
share the calendar with the service account or use `delegate` with domain-wide delegation.

### How do I react to new or changed events?
Use the [google-calendar-stream](https://pmsudhi.github.io/cameleer/docs/components/google-calendar-stream.html) consumer, or a watch channel with
`events/watch`.

## Related

- [google-calendar-stream](https://pmsudhi.github.io/cameleer/docs/components/google-calendar-stream.html): consume new and changed events.
- [google-mail](https://pmsudhi.github.io/cameleer/docs/components/google-mail.html), [google-drive](https://pmsudhi.github.io/cameleer/docs/components/google-drive.html), [google-sheets](https://pmsudhi.github.io/cameleer/docs/components/google-sheets.html).
- [Apache Camel Google Calendar component](https://camel.apache.org/components/next/google-calendar-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-calendar-stream.html

# Google Calendar Stream component

> The `google-calendar-stream` component polls a Google Calendar and emits new and changed events, optionally using incremental sync tokens so deleted events are reported too.

**Scheme:** `google-calendar-stream:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Google Calendar Stream](https://camel.apache.org/components/next/google-calendar-stream-component.html)

## When to use it

- Prepare for meetings automatically: when an event is created, have an agent collect the
  attendees' recent tickets or e-mails and post a briefing.
- Mirror a calendar into another system (a room display, a CRM, a database).
- React to cancellations with `syncFlow=true`, which reports deleted events.

## URI format

```text
google-calendar-stream://index[?options]
```

The path is a free name (Camel uses `index`); it is not used.

## Example

Every minute, emit the events of the user's primary calendar that start in the future and were
created or changed since the previous poll.

```yaml
- route:
    id: new-meetings
    from:
      uri: "google-calendar-stream://index?calendarId={{env:CALENDAR_ID:primary}}&considerLastUpdate=true&delay=60000&delegate={{env:GOOGLE_USER}}"
      steps:
        - log: "event ${header.CamelGoogleCalendarStreamEventId}: ${body[summary]}"
        - marshal:
            json: {}
        - to: "log:meetings"
```

The body of each exchange is the Calendar event resource (`id`, `summary`, `start`, `end`,
`attendees`, `updated`, ...).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("google-calendar-stream://index?calendarId={{env:CALENDAR_ID:primary}}&considerLastUpdate=true&delay=60000&delegate={{env:GOOGLE_USER}}")
        .log("event ${header.CamelGoogleCalendarStreamEventId}: ${body[summary]}")
        .marshal("json")
        .to("log:meetings");
})?;
```

## How it polls

**Default mode.** Each poll calls `events.list` with `singleEvents=true`, `orderBy=startTime`
and `maxResults`. With `consumeFromNow=true` (default) only events starting after the consumer
started are listed (`timeMin`). With `considerLastUpdate=true` only events updated since the
previous poll are asked for (`updatedMin`). An event is emitted when it is new or its `updated`
time changed, so an unchanged event is never emitted twice. Deleted events are not reported in
this mode.

**Sync mode (`syncFlow=true`).** The first poll does a full sync and keeps the
`nextSyncToken`; its events are emitted only with `consumeFromNow=false`. Every later poll asks
for the changes since the token and emits them, cancelled (deleted) events included, with the
`CamelGoogleCalendarStreamEventStatus` header. When Google answers `410 Gone` (expired token), the
consumer runs a full sync again and emits only events it has not delivered before.

State (seen events, sync token) is kept in memory; after a restart the consumer starts over.

## Options

| option | default | description |
|---|---|---|
| `calendarId` | `primary` | Calendar to watch. |
| `query` | | Free-text search (`q`) in default mode. |
| `maxResults` | `10` | Maximum events per poll in default mode. |
| `consumeFromNow` | `true` | Only events starting after the consumer started (default mode); in sync mode, skip the events of the initial full sync. |
| `considerLastUpdate` | `false` | Ask only for events updated since the previous poll. |
| `syncFlow` | `false` | Use incremental sync tokens; reports changes and deletions. |
| `delay` | `500` | Milliseconds between polls. Scheduled poll options such as `initialDelay` (default `1000`) also apply. |
| `delegate` (alias `subject`) | | User to impersonate with domain-wide delegation. |
| `serviceAccountKey` | `GOOGLE_APPLICATION_CREDENTIALS` | Service account JSON key. |
| `clientId`, `clientSecret`, `refreshToken` | | OAuth user credentials (refresh-token flow). |
| `accessToken` | | A fixed OAuth access token. |
| `scopes` | `https://www.googleapis.com/auth/calendar` | Comma separated OAuth scopes. |
| `uriEndpointOverride` + `overrideEndpoint=true` | | Base URL of an emulator or proxy. |

`tokenServerUrl`, `useMetadataServer`, `authenticate`, `proxyHost`, `proxyPort` and
`trustAllCertificates` work as on the [google-sheets](https://pmsudhi.github.io/cameleer/docs/components/google-sheets.html#options) page.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGoogleCalendarStreamEventId` | out | Event id. |
| `CamelGoogleCalendarStreamEventStatus` | out | With `syncFlow=true`: `confirmed`, `tentative` or `cancelled`. |

## Run it with Docker

```sh
docker run --rm \
  -e GOOGLE_USER=ada@example.com \
  -e GOOGLE_APPLICATION_CREDENTIALS=/secrets/key.json \
  -v "$PWD/key.json:/secrets/key.json:ro" \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/new-meetings.camel.yaml
```

## Common questions

### How do I get notified when a Google Calendar event is created or changed?
Consume `google-calendar-stream://index?calendarId=...&considerLastUpdate=true`. Each new or
changed event arrives as one exchange.

### How do I detect cancelled events?
Set `syncFlow=true` and check `CamelGoogleCalendarStreamEventStatus` for `cancelled`.

### Why are past events not emitted?
`consumeFromNow=true` (default) lists only events that start after the consumer started. Set it
to `false` to include them.

## Related

- [google-calendar](https://pmsudhi.github.io/cameleer/docs/components/google-calendar.html): create and manage events.
- [Apache Camel Google Calendar Stream component](https://camel.apache.org/components/next/google-calendar-stream-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-functions.html

# Google Cloud Functions component

> The `google-functions` component calls Google Cloud Functions (1st gen) and manages them: list, get, create, update, delete and source upload URLs.

**Scheme:** `google-functions:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Google Functions](https://camel.apache.org/components/next/google-functions-component.html)

## When to use it

- Call a function from a route with the message body as input and its result as the new body.
- Offload one heavy step (image resize, scoring, an ML model) to a serverless function.
- Give an AI agent a tool: the agent's request goes through a route that calls the function.
- Deploy or update a function from a pipeline (`createFunction`, `updateFunction`).

## URI format

```text
google-functions://functionName[?options]
```

## Example

Expose a function behind an HTTP endpoint; the request body is the call data and the response is
the function's result:

```yaml
- route:
    id: http-to-function
    from:
      uri: "platform-http:/greet?httpMethodRestrict=POST"
      steps:
        - to: "google-functions://{{env:FUNCTION_NAME:greet}}?project={{env:GCP_PROJECT:my-project}}&location={{env:FUNCTION_LOCATION:europe-west1}}"
        - log: "execution ${header.CamelGoogleCloudFunctionsExecutionId}: ${body}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("platform-http:/greet")
        .to("google-functions://greet?project=my-project&location=europe-west1");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `project` | the key's project | Google Cloud project. |
| `location` | `us-central1` | Region of the function. |
| `operation` | `callFunction` | `callFunction`, `listFunctions`, `getFunction`, `deleteFunction`, `generateUploadUrl`, `generateDownloadUrl`, `createFunction`, `updateFunction`. Header `CamelGoogleCloudFunctionsOperation`. |
| `entryPoint` | | `createFunction` / `updateFunction`: entry point. |
| `runtime` | | `createFunction` / `updateFunction`: runtime, for example `nodejs20`. |

`client` and `pojoRequest` are accepted for Camel compatibility and ignored. Credentials are
shared by all Google components: see [credentials](https://pmsudhi.github.io/cameleer/docs/components/google-storage.html#credentials).

### Operations

- `callFunction`: the body (text, or a map / list sent as JSON) is the call data; the body
  becomes the result. A function error raises an `ApiException`.
- `listFunctions`: body = list of function names. `getFunction`: the function resource.
  `deleteFunction`: deletes it.
- `generateUploadUrl`: body = a signed upload URL; with a byte body the zip archive is uploaded
  to it right away. `generateDownloadUrl`: body = the URL of the function's source.
- `createFunction` / `updateFunction`: from the entry point, runtime and source headers (HTTPS
  trigger by default), or a map body that is the CloudFunction resource. The long-running
  operation is polled until done; body = the function.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGoogleCloudFunctionsOperation` | in | Operation. |
| `CamelGoogleCloudFunctionsExecutionId` | out | Cameleer: execution id of `callFunction`. |
| `CamelGoogleCloudFunctionsEntryPoint` | in | Entry point for create / update. |
| `CamelGoogleCloudFunctionsRuntime` | in | Runtime for create / update. |
| `CamelGoogleCloudFunctionsSourceArchiveUrl` | in | `gs://` source archive for create / update. |
| `CamelGoogleCloudFunctionsSourceUploadUrl` | in | Upload URL (from `generateUploadUrl`) for create / update. |

## Run it with Docker

```sh
docker run --rm -p 8080:8080 -v "$PWD:/routes:ro" \
  -v "$HOME/keys/sa.json:/keys/sa.json:ro" -e GOOGLE_APPLICATION_CREDENTIALS=/keys/sa.json \
  -e GCP_PROJECT=my-project -e FUNCTION_NAME=greet \
  pmsudhi/cameleer run /routes/http-to-function.camel.yaml
```

## Common questions

### How do I call a Cloud Function with JSON?
Send a map or list body (for example after `unmarshal: json`); it is serialized as the call data.

### Does it work with 2nd gen functions or Cloud Run?
It uses the Cloud Functions v1 API (`functions:call`). For 2nd gen functions and Cloud Run
services call their HTTPS URL with the [HTTP component](https://pmsudhi.github.io/cameleer/docs/components/http.html) and a bearer token.

### What happens when the function throws?
The exchange fails with an `ApiException` carrying the function's error message, so the route's
error handler decides what to do.

## Related

- [AWS Lambda](https://pmsudhi.github.io/cameleer/docs/components/aws2-lambda.html), [Azure Functions](https://pmsudhi.github.io/cameleer/docs/components/azure-functions.html)
- [Apache Camel Google Functions](https://camel.apache.org/components/next/google-functions-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-storage.html

# Google Cloud Storage component

> The `google-storage` component uploads, downloads, lists, copies and deletes objects in Google Cloud Storage buckets, and consumes new objects from a bucket.

**Scheme:** `google-storage:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Google Storage](https://camel.apache.org/components/next/google-storage-component.html)

## When to use it

- Upload files, reports or exports to a bucket ("write files to GCS").
- Pick up objects that land in a bucket and process them, then delete or archive them.
- Ship sensor data or logs from an edge device to the cloud: a small Cameleer binary watches a
  local folder and uploads each file, retrying on failure.
- Hand out time-limited download links (V4 signed URLs) to users or AI agents without making
  the bucket public.

## URI format

```text
google-storage://bucketName[?options]
```

The bucket is created on start when it does not exist (`autoCreateBucket=true`, in the project
of the service account key).

## Example

Upload every file that appears in a local folder, under its own file name:

```yaml
- route:
    id: files-to-gcs
    from:
      uri: "file:{{env:INBOX_DIR:inbox}}?move=.done"
      steps:
        - setHeader:
            name: CamelGoogleCloudStorageObjectName
            simple: "uploads/${file:name}"
        - to: "google-storage://{{env:GCS_BUCKET:my-bucket}}"
        - log: "uploaded ${file:name} to gs://{{env:GCS_BUCKET:my-bucket}}/uploads/"
```

Consume the objects of a bucket: each object becomes one exchange with its content as the body,
and after processing it is copied to an archive bucket and deleted from the source bucket:

```yaml
- route:
    id: gcs-incoming
    from:
      uri: "google-storage://{{env:GCS_BUCKET:incoming-bucket}}?prefix=orders/&moveAfterRead=true&destinationBucket={{env:GCS_ARCHIVE_BUCKET:archive-bucket}}"
      steps:
        - log: "received ${header.CamelGoogleCloudStorageObjectName} (${header.CamelGoogleCloudStorageContentLength} bytes)"
        - setHeader:
            name: CamelFileName
            simple: "${header.CamelGoogleCloudStorageObjectName}"
        - to: "file:{{env:OUT_DIR:out}}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("file:inbox?move=.done")
        .set_header("CamelGoogleCloudStorageObjectName", simple("uploads/${file:name}"))
        .to("google-storage://my-bucket")
        .log("uploaded ${file:name}");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `operation` | `putObject` | Producer operation: `putObject`, `getObject`, `listObjects`, `deleteObject`, `copyObject`, `listBuckets`, `createBucket`, `deleteBucket`, `createDownloadLink`. The `CamelGoogleCloudStorageOperation` header overrides it. |
| `objectName` | | Object name for the producer (or the single object a consumer reads). The header `CamelGoogleCloudStorageObjectName` wins. |
| `prefix` | | Only list or consume objects whose name starts with this prefix. |
| `autoCreateBucket` | `true` | Create the bucket on start if it does not exist. |
| `storageClass` | `STANDARD` | Storage class of auto-created buckets. |
| `storageLocation` | `US-EAST1` | Location of auto-created buckets. |
| `deleteAfterRead` | `true` | Consumer: delete the object after it was processed successfully. |
| `moveAfterRead` | `false` | Consumer: copy the object to `destinationBucket` after processing. Needs `destinationBucket`. |
| `destinationBucket` | | Consumer: target bucket for `moveAfterRead`. |
| `includeBody` | `true` | Consumer: put the object content in the body (otherwise only the headers are set). |
| `includeFolders` | `true` | Consumer: also emit folder placeholder objects. |
| `maxMessagesPerPoll` | `10` | Consumer: objects per poll. |
| `resumableUploadThreshold` | `16777216` | Cameleer: bodies larger than this many bytes use a resumable upload session (`0` = always). |
| `resumableChunkSize` | `8388608` | Cameleer: chunk size of resumable uploads, rounded up to a multiple of 256 KiB. A failed chunk is resumed from the committed size (up to 5 times). |
| `delay`, `initialDelay`, ... | `500`, `1000` | Consumer poll schedule (milliseconds) and the other scheduled-poll options (`useFixedDelay`, `greedy`, `sendEmptyMessageWhenIdle`, `backoffMultiplier`, ...). |

### Credentials

These options are shared by every Google component (`google-pubsub`, `google-bigquery`,
`google-vertexai`, ...).

| option | default | description |
|---|---|---|
| `serviceAccountKey` | `GOOGLE_APPLICATION_CREDENTIALS` | Service account JSON key: a path, `file:path`, `classpath:path` or the inline JSON. An `authorized_user` file (from `gcloud auth application-default login`) or an `external_account` file (workload identity federation) works too. Without the option the `GOOGLE_APPLICATION_CREDENTIALS` environment variable is used, like Google's client libraries. |
| `clientId`, `clientSecret`, `refreshToken` | | OAuth user credentials (refresh token). They take precedence over a service account key. |
| `accessToken` | | A fixed bearer token. |
| `tokenServerUrl` | `https://oauth2.googleapis.com/token` | Cameleer: token endpoint for refresh-token credentials. |
| `useMetadataServer` | `false` | Take tokens from the GCE / GKE metadata server (also used when `GCE_METADATA_HOST` is set and no other credentials are given). |
| `metadataServerUrl` | | Cameleer: base URL of the metadata server. |
| `delegate` (or `subject`) | | User to impersonate with domain-wide delegation (JWT `sub` claim). |
| `authenticate` | `true` | `false` sends no credentials (emulators). |
| `uriEndpointOverride` + `overrideEndpoint=true`, or `endpoint` | | Send requests to another base URL, for example an emulator such as fake-gcs-server. |
| `proxyHost`, `proxyPort` | `3128` | HTTP proxy. |

Tokens are cached per credential until shortly before they expire, and refreshed after a 401.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGoogleCloudStorageOperation` | in | Operation to run (overrides `operation`). |
| `CamelGoogleCloudStorageBucketName` | in / out | Bucket for this exchange (overrides the URI); set by the consumer. |
| `CamelGoogleCloudStorageObjectName` | in / out | Object name; set by the consumer. |
| `CamelGoogleCloudStorageContentType` | in / out | Content type of the upload; set from the object metadata. |
| `CamelGoogleCloudStoragePrefix` | in | Prefix for `listObjects`. |
| `CamelGoogleCloudStorageDestinationBucketName` | in | Target bucket of `copyObject` (required). |
| `CamelGoogleCloudStorageDestinationObjectName` | in | Target name of `copyObject` (default: the same name). |
| `CamelGoogleCloudStorageDownloadLinkExpirationTime` | in | Lifetime of a `createDownloadLink` URL in milliseconds (default 5 minutes, at most 7 days). |
| `CamelGoogleCloudStorageDownloadLink` | out | The signed URL created by `createDownloadLink` (also the body). |
| `CamelGoogleCloudStorageContentLength` | out | Object size in bytes. |
| `CamelGoogleCloudStorageETag` | out | Object ETag. |
| `CamelGoogleCloudStorageContentMd5` | out | Base64 MD5 of the content. |
| `CamelGoogleCloudStorageCreateTime`, `CamelGoogleCloudStorageUpdateTime` | out | Object timestamps. |
| `CamelGoogleCloudStorageGeneration` | out | Object generation. |

Bodies: `putObject` returns the object metadata map, `getObject` the content bytes,
`listObjects` a list of metadata maps, `copyObject` the new object's metadata,
`deleteObject` and `deleteBucket` `true`.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" -v "$PWD/inbox:/inbox" \
  -v "$HOME/keys/sa.json:/keys/sa.json:ro" -e GOOGLE_APPLICATION_CREDENTIALS=/keys/sa.json \
  -e GCS_BUCKET=my-bucket -e INBOX_DIR=/inbox \
  pmsudhi/cameleer run /routes/files-to-gcs.camel.yaml
```

## Common questions

### How do I authenticate to Google Cloud Storage?
Set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key file, or pass `serviceAccountKey`
on the URI. On GCE, GKE or Cloud Run use `useMetadataServer=true` and no key at all.

### How do I download a single object?
Send any message with `operation=getObject` and the `CamelGoogleCloudStorageObjectName` header;
the body becomes the object bytes.

### How do I create a signed download URL?
Use `operation=createDownloadLink` with the object name header. It needs a service account key
(the URL is signed with it, `GOOG4-RSA-SHA256`); the body is the URL.

### How is this different from Apache Camel?
Options and headers follow Camel. Resumable uploads (`resumableUploadThreshold`,
`resumableChunkSize`) are Cameleer additions; the `filter` and `downloadFileName` options are
accepted but ignored.

## Related

- [Google Pub/Sub](https://pmsudhi.github.io/cameleer/docs/components/google-pubsub.html), [BigQuery](https://pmsudhi.github.io/cameleer/docs/components/google-bigquery.html) (load jobs read `gs://` files)
- [AWS S3](https://pmsudhi.github.io/cameleer/docs/components/aws2-s3.html) for the same pattern on AWS
- [Apache Camel Google Storage](https://camel.apache.org/components/next/google-storage-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-drive.html

# Google Drive component

> The `google-drive` component uploads, downloads, lists, copies and deletes Google Drive files through the Drive v3 REST API, and can poll a file listing to emit created, modified and removed files.

**Scheme:** `google-drive:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes (file changes of `drive-files/list`) · **Producer:** yes · **Apache Camel:** [Google Drive](https://camel.apache.org/components/next/google-drive-component.html)

## When to use it

- Upload generated reports, invoices or exports to a shared Drive folder.
- Watch a folder and start a workflow when someone drops a file in it, for example to have an
  LLM summarize a new document or to load a CSV into a database.
- Download files for processing at the edge, then move or delete them.
- Manage sharing (`drive-permissions/*`) and comments (`drive-comments/*`) from a route.

## URI format

```text
google-drive://apiName/methodName[?options]
```

Core methods: `drive-files/list`, `drive-files/get`, `drive-files/download`,
`drive-files/create` (alias `drive-files/insert`), `drive-files/update`, `drive-files/copy`,
`drive-files/delete`. Also: `drive-about/get`, `drive-changes/getStartPageToken|list|watch`,
`drive-files/watch|emptyTrash|generateIds`, `drive-channels/stop`,
`drive-permissions/create|list|get|update|delete`, `drive-comments/create|list|get|update|delete`,
`drive-replies/create|list|get|delete`, `drive-revisions/list|get|delete`,
`drive-drives/create|list|get|update|delete`, `drive-teamdrives/list`.

## Example

Upload every PDF that appears in a local `reports` directory to a Drive folder. The Drive file
name is the local file name (`CamelFileName`); uploaded files are moved to `reports/.uploaded`.

```yaml
- route:
    id: reports-to-drive
    from:
      uri: "file:{{env:REPORTS_DIR:reports}}?antInclude=*.pdf&move=.uploaded"
      steps:
        - to: "google-drive://drive-files/create?parents={{env:DRIVE_FOLDER_ID}}&mimeType=application/pdf"
        - log: "uploaded ${header.CamelFileName} as Drive file ${body[id]}"
```

Watch the same folder: the first poll is skipped (`consumeExisting=false`), then each poll emits
one exchange per created, modified or removed file.

```yaml
- route:
    id: watch-drive-folder
    from:
      uri: "google-drive://drive-files/list?q='{{env:DRIVE_FOLDER_ID}}' in parents and trashed = false&consumeExisting=false&delay=60000"
      steps:
        - log: "${header[CamelGoogleDrive.changeType]}: ${body[name]} (${header[CamelGoogleDrive.fileId]})"
        - to: "log:drive-changes"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("file:{{env:REPORTS_DIR:reports}}?antInclude=*.pdf&move=.uploaded")
        .to("google-drive://drive-files/create?parents={{env:DRIVE_FOLDER_ID}}&mimeType=application/pdf")
        .log("uploaded ${header.CamelFileName} as Drive file ${body[id]}");
    b.from("google-drive://drive-files/list?q='{{env:DRIVE_FOLDER_ID}}' in parents and trashed = false&consumeExisting=false&delay=60000")
        .log("${header[CamelGoogleDrive.changeType]}: ${body[name]} (${header[CamelGoogleDrive.fileId]})")
        .to("log:drive-changes");
})?;
```

## What the core methods do

| api/method | input | body after the call |
|---|---|---|
| `drive-files/list` | `q`, `pageSize`, `orderBy`, `fields` | list of files (all pages); default fields `id, name, mimeType, size, parents, modifiedTime` |
| `drive-files/get` | `fileId` | file metadata |
| `drive-files/download` | `fileId` | file content as bytes |
| `drive-files/create` | body = content; `name` (or `title`, or the `CamelFileName` header), `mimeType` (default `application/octet-stream`), `parents` | created file (multipart upload) |
| `drive-files/update` | `fileId`, body = new content, `mimeType` | updated file |
| `drive-files/copy` | `fileId`, optional `name` | the copy |
| `drive-files/delete` | `fileId` | unchanged |

Methods that take a request body (`drive-permissions/create`, `drive-comments/create`, ...) read
it from the `CamelGoogleDrive.content` header or a map body. For the other Drive methods,
`fields` defaults to `*`.

## The file-change consumer

`from("google-drive://drive-files/list?...")` polls the listing (with your `q`) and compares it
with the previous poll:

- a file that was not listed before: `created`
- a file whose `modifiedTime` changed: `modified` (content or metadata)
- a file that is no longer listed: `removed` (body = `{id}`)

The first poll emits every listed file as `created`; set `consumeExisting=false` (Cameleer) to
report only later changes. The snapshot is kept in memory, so after a restart the first poll
counts again as the first. Apache Camel's Drive consumer instead re-runs the API call on every
poll and emits its whole result.

## Options

| option | default | description |
|---|---|---|
| `fileId` | | File id. |
| `q` | | Drive search query, for example `'<folderId>' in parents and trashed = false`. |
| `pageSize`, `orderBy` | | Listing options. |
| `fields` | see above | Fields to return. |
| `name` (alias `title`) | `CamelFileName` header | File name for `create` and `copy`. |
| `mimeType` | `application/octet-stream` | Content type for `create` and `update`. |
| `parents` | | Comma separated parent folder ids for `create`. |
| `consumeExisting` | `true` | Consumer: emit the files of the first poll as `created`. |
| `delay` | `500` | Consumer: milliseconds between polls. Scheduled poll options such as `initialDelay` (default `1000`) also apply. |
| `permissionId`, `commentId`, `replyId`, `revisionId`, `driveId`, `pageToken`, `count`, `requestId`, `channelId`, `address`, `token`, `resourceId` | | Parameters of the extra methods. |
| `delegate` (alias `subject`) | | User to impersonate with domain-wide delegation. |
| `scopes` | `https://www.googleapis.com/auth/drive` | Comma separated OAuth scopes. |
| `serviceAccountKey` | `GOOGLE_APPLICATION_CREDENTIALS` | Service account JSON key: `file:path`, a plain path or inline JSON. |
| `clientId`, `clientSecret`, `refreshToken` | | OAuth user credentials (refresh-token flow). |
| `accessToken` | | A fixed OAuth access token. |
| `uriEndpointOverride` + `overrideEndpoint=true` | | Base URL of an emulator or proxy. |

`tokenServerUrl`, `useMetadataServer`, `authenticate`, `proxyHost`, `proxyPort` and
`trustAllCertificates` work as on the [google-sheets](https://pmsudhi.github.io/cameleer/docs/components/google-sheets.html#options) page.
`applicationName`, `inBody` and `splitResult` are accepted and ignored.

## Message headers

Every option can also be set per message with a `CamelGoogleDrive.<option>` header (for example
`CamelGoogleDrive.fileId`), which wins over the URI option.

| header | direction | description |
|---|---|---|
| `CamelGoogleDrive.content` | in | Request map for methods that take one. |
| `CamelFileName` | in | File name for `drive-files/create` when `name` is not set. |
| `CamelGoogleDrive.changeType` | out (consumer) | `created`, `modified` or `removed`. |
| `CamelGoogleDrive.fileId` | out (consumer) | Id of the changed file. |
| `CamelGoogleDrive.resourceId` | out | Resource id of a created watch channel. |

## Run it with Docker

Share the folder with the service account's e-mail address, then:

```sh
docker run --rm \
  -e DRIVE_FOLDER_ID=1x2y3z... -e REPORTS_DIR=/data/reports \
  -e GOOGLE_APPLICATION_CREDENTIALS=/secrets/key.json \
  -v "$PWD/key.json:/secrets/key.json:ro" \
  -v "$PWD/reports:/data/reports" \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/reports-to-drive.camel.yaml
```

The reports directory is mounted read-write because uploaded files are moved.

## Common questions

### How do I upload a file to a Google Drive folder?
Send the content to `google-drive://drive-files/create?parents=<folderId>&mimeType=...` with a
`name` option or a `CamelFileName` header. A `file:` consumer sets `CamelFileName` for you.

### How do I download a Drive file?
Call `drive-files/download` with `CamelGoogleDrive.fileId`; the body becomes the file's bytes.
Google Docs, Sheets and Slides cannot be downloaded this way (they need an export).

### Where do files uploaded by a service account go?
Without `parents` they go to the service account's own Drive, which no person sees. Share a
folder with the service account and pass its id as `parents`.

### How do I process new files dropped into a folder?
Consume `google-drive://drive-files/list?q='<folderId>' in parents and trashed = false`; each new
file arrives with `CamelGoogleDrive.changeType` = `created`. Download it with
`drive-files/download` in the same route.

## Related

- [google-storage](https://pmsudhi.github.io/cameleer/docs/components/google-storage.html) for bucket storage, [file](https://pmsudhi.github.io/cameleer/docs/components/file.html).
- [google-sheets](https://pmsudhi.github.io/cameleer/docs/components/google-sheets.html), [google-mail](https://pmsudhi.github.io/cameleer/docs/components/google-mail.html), [google-calendar](https://pmsudhi.github.io/cameleer/docs/components/google-calendar.html).
- [Apache Camel Google Drive component](https://camel.apache.org/components/next/google-drive-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-firestore.html

# Google Firestore component

> The `google-firestore` component reads, writes, queries and listens to documents in Google Cloud Firestore, with plain maps as message bodies.

**Scheme:** `google-firestore:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** none (Cameleer component; Camel has no Firestore component)

## When to use it

- Save incoming JSON (orders, form posts, device state) as Firestore documents.
- React to document changes: a polled snapshot listener emits `ADDED`, `MODIFIED` and
  `REMOVED` events.
- Keep small state for AI agents, such as conversation memory or task status, keyed by id.
- Run atomic batched writes or read-write transactions.

## URI format

```text
google-firestore://projectId[:collection][?options]
```

Sub-collections are written as `parent/docId/child`. Documents are plain maps; values are
converted to and from Firestore typed values (strings, integers, doubles, booleans, null,
bytes, arrays and maps).

## Example

Store every JSON document posted to an HTTP endpoint, using its `id` field as the document id:

```yaml
- route:
    id: http-to-firestore
    from:
      uri: "platform-http:/devices?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: CamelGoogleFirestoreDocumentId
            simple: "${body[id]}"
        - to: "google-firestore://{{env:GCP_PROJECT:my-project}}:devices?operation=setDocument"
        - setBody:
            simple: "saved ${header.CamelGoogleFirestoreDocumentId}"
```

Listen to a collection and write one line per change to a file:

```yaml
- route:
    id: firestore-changes
    from:
      uri: "google-firestore://{{env:GCP_PROJECT:my-project}}:devices?delay=2000"
      steps:
        - setBody:
            simple: "${header.CamelGoogleFirestoreChangeType} ${header.CamelGoogleFirestoreDocumentId}\n"
        - to: "file:{{env:OUT_DIR:out}}?fileName=changes.log&fileExist=Append"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("google-firestore://my-project:devices")
        .log("${header.CamelGoogleFirestoreChangeType}: ${body}");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `operation` | `getDocument` | `getDocument`, `listDocuments`, `createDocument`, `setDocument`, `updateDocument`, `deleteDocument`, `runQuery`, `commit`, `batchWrite`, `beginTransaction`, `rollback`. Header `CamelGoogleFirestoreOperation`. |
| `databaseId` | `(default)` | Firestore database. |
| `orderBy` | | `runQuery`: field to order by. |
| `descending` | `false` | `runQuery`: descending order. |
| `limit` | | `runQuery`: maximum documents. |
| `skipInitialSnapshot` | `false` | Consumer: do not report the documents that exist when the route starts. |
| `delay`, `initialDelay`, ... | `500`, `1000` | Consumer poll schedule (milliseconds) and the other scheduled-poll options. |

Credentials are shared by all Google components: see [credentials](https://pmsudhi.github.io/cameleer/docs/components/google-storage.html#credentials).
Without a project in the URI, the project of the service account key is used.

### Operations

- `getDocument`: body = the fields map. `listDocuments`: a list of maps with `_id`.
- `createDocument`: the body map; the id is generated unless `CamelGoogleFirestoreDocumentId`
  is set, and the header is set to the new id. `setDocument` creates or replaces.
  `updateDocument` merges the body's top-level fields into an existing document.
  `deleteDocument` deletes.
- `runQuery`: the body (or `CamelGoogleFirestoreQuery`) is a `structuredQuery` object, passed
  through, or a map of field to value equality filters. Body = a list of maps with `_id`.
- `commit` (atomic) and `batchWrite` (independent writes, body = per-write `{code, message}`):
  a list body of `{op: set | update | create | delete, collection, id, data}` maps.
- Transactions: `beginTransaction` sets `CamelGoogleFirestoreTransaction`; `getDocument` with
  that header reads inside the transaction; `commit` with it commits (an `ABORTED` error when
  a document read in it changed meanwhile: retry), `rollback` abandons it.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGoogleFirestoreOperation` | in | Operation. |
| `CamelGoogleFirestoreCollection` | in | Collection (overrides the URI). |
| `CamelGoogleFirestoreDocumentId` | in / out | Document id; set by `createDocument` and the consumer. |
| `CamelGoogleFirestoreQuery` | in | Query for `runQuery`. |
| `CamelGoogleFirestoreOrderBy`, `CamelGoogleFirestoreLimit` | in | `runQuery` ordering and limit. |
| `CamelGoogleFirestoreReadOnly` | in | `beginTransaction`: read-only transaction. |
| `CamelGoogleFirestoreTransaction` | in / out | Transaction id. |
| `CamelGoogleFirestoreUpdateTime` | out | Update time of the document. |
| `CamelGoogleFirestoreCommitTime` | out | Commit time of `commit`. |
| `CamelGoogleFirestoreChangeType` | out | Consumer: `ADDED`, `MODIFIED` or `REMOVED`. |

## Run it with Docker

```sh
docker run --rm -p 8080:8080 -v "$PWD:/routes:ro" \
  -v "$HOME/keys/sa.json:/keys/sa.json:ro" -e GOOGLE_APPLICATION_CREDENTIALS=/keys/sa.json \
  -e GCP_PROJECT=my-project \
  pmsudhi/cameleer run /routes/http-to-firestore.camel.yaml
```

## Common questions

### How do I query Firestore documents by a field?
Send a map such as `{"city": "Rome"}` to `operation=runQuery`, optionally with `orderBy`,
`descending` and `limit`. For range filters send a full `structuredQuery` object.

### Is the consumer a real-time listener?
It is polled: every poll lists the collection and compares it with the previous snapshot. The
gRPC `Listen` stream is not used.

### How do I write several documents atomically?
Send a list of write maps to `operation=commit`. Either all writes apply or none.

## Related

- [Google Pub/Sub](https://pmsudhi.github.io/cameleer/docs/components/google-pubsub.html), [Google Sheets](https://pmsudhi.github.io/cameleer/docs/components/google-sheets.html), [MongoDB](https://pmsudhi.github.io/cameleer/docs/components/mongodb.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-mail.html

# Google Mail component

> The `google-mail` component sends, lists, reads, labels and deletes Gmail messages, drafts, labels and threads through the Gmail v1 REST API.

**Scheme:** `google-mail:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no (see [google-mail-stream](https://pmsudhi.github.io/cameleer/docs/components/google-mail-stream.html)) · **Producer:** yes · **Apache Camel:** [Google Mail](https://camel.apache.org/components/next/google-mail-component.html)

## When to use it

- Send notification or report e-mails from a Google Workspace mailbox without an SMTP relay.
- Let an AI agent search a mailbox (`messages/list` with a Gmail query), read a message
  (`messages/get`) and file it (`messages/modify` with labels).
- Create drafts for a human to review before sending (`drafts/create`).
- Watch a mailbox through Pub/Sub push notifications (`users/watch`).

## URI format

```text
google-mail://apiName/methodName[?options]
```

Core methods: `messages/send`, `messages/list`, `messages/get`, `messages/delete`,
`messages/trash`, `messages/untrash`, `messages/modify`, `labels/list`, `threads/get`.
Also: `drafts/create|list|get|update|send|delete`, `history/list`, `attachments/get`,
`users/getProfile`, `users/watch`, `users/stop`, `labels/create|get|update|delete`,
`threads/list|modify|trash|untrash|delete`. Unknown methods fail when the endpoint is created.

## Example

Once a day, send a short digest from a Workspace mailbox. The service account acts as
`GOOGLE_USER` through domain-wide delegation.

```yaml
- route:
    id: daily-digest
    from:
      uri: "timer:daily-digest?period=86400000"
      steps:
        - setBody:
            simple: "Good morning. This digest was generated at ${date:now:yyyy-MM-dd HH:mm}."
        - to: "google-mail://messages/send?delegate={{env:GOOGLE_USER}}&to={{env:DIGEST_TO}}&subject=Daily digest"
        - log: "sent Gmail message ${header[CamelGoogleMail.id]}"
```

A text body with the `to` option becomes a plain-text MIME message. A map body
`{to, cc, bcc, from, subject, text, html, replyTo}` gives you full control (with `text` and `html`
it becomes `multipart/alternative`). A text body without `to` is sent as a raw RFC 822 message.
After the call the body is the sent message resource (`id`, `threadId`, `labelIds`).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:daily-digest?period=86400000")
        .set_body(simple("Good morning. This digest was generated at ${date:now:yyyy-MM-dd HH:mm}."))
        .to("google-mail://messages/send?delegate={{env:GOOGLE_USER}}&to={{env:DIGEST_TO}}&subject=Daily digest")
        .log("sent Gmail message ${header[CamelGoogleMail.id]}");
})?;
```

## What the core methods do

| api/method | input | body after the call |
|---|---|---|
| `messages/send` | map body, or text body + `to`/`subject`/`cc`/`bcc`/`from`/`replyTo`, or raw RFC 822 | sent message resource; header `CamelGoogleMail.id` |
| `messages/list` | `q`, `labelIds`, `maxResults`, `includeSpamTrash` | list of `{id, threadId}`; all pages unless `maxResults` is set (then one page) |
| `messages/get` | `id`, `format` (default `full`) | message resource; headers `CamelGoogleMail.text`, `.subject`, `.from`, `.to` |
| `messages/modify` | `id`, `addLabelIds`, `removeLabelIds` | updated message |
| `messages/trash`, `messages/untrash` | `id` | the message |
| `messages/delete` | `id` | unchanged (permanent delete) |
| `labels/list` | | list of labels |
| `threads/get` | `id` | the thread |
| `drafts/create`, `drafts/update` | message map or text body (like `messages/send`), or a `{message}` map | the draft |
| `drafts/send` | `id`, or a content map | the sent message |
| `attachments/get` | `messageId`, `id` | decoded attachment bytes; header `CamelGoogleMail.size` |
| `users/watch` | `topicName` (a Pub/Sub topic), `labelIds` | `{historyId, expiration}`; Gmail then publishes `{emailAddress, historyId}` to the topic |
| `history/list` | `startHistoryId`, `historyTypes`, `labelId`, `maxResults` | history records (all pages) |

Methods that take a request body (`labels/create`, `threads/modify`, ...) read it from the
`CamelGoogleMail.content` header or a map body.

## Options

| option | default | description |
|---|---|---|
| `userId` | `me` | Mailbox to act on (`me` = the authenticated or delegated user). |
| `to`, `cc`, `bcc`, `from`, `replyTo`, `subject` | | Message fields for a text body sent with `messages/send` or `drafts/create`. |
| `id` | | Message, thread, draft or label id. |
| `q` | | Gmail search query for `messages/list`, `threads/list`, `drafts/list` (for example `from:billing@example.com is:unread`). |
| `labelIds` | | Comma separated label ids to filter by. |
| `maxResults` | | Page size; when set, only one page is returned. |
| `includeSpamTrash` | | Include spam and trash in `messages/list`. |
| `format` | `full` | `full`, `metadata`, `minimal` or `raw` for `messages/get` and `drafts/get`. |
| `addLabelIds`, `removeLabelIds` | | Labels to add or remove with `messages/modify`. |
| `messageId`, `startHistoryId`, `historyTypes`, `labelId`, `topicName` | | Parameters of `attachments/get`, `history/list` and `users/watch`. |
| `delegate` (alias `subject`) | | User to impersonate with domain-wide delegation. A service account needs it to reach a mailbox. |
| `scopes` | `https://mail.google.com/` | Comma separated OAuth scopes. |
| `serviceAccountKey` | `GOOGLE_APPLICATION_CREDENTIALS` | Service account JSON key: `file:path`, a plain path or inline JSON (`authorized_user` and `external_account` files also work). |
| `clientId`, `clientSecret`, `refreshToken` | | OAuth user credentials (refresh-token flow) instead of a service account. |
| `accessToken` | | A fixed OAuth access token. |
| `tokenServerUrl` | `https://oauth2.googleapis.com/token` | Token endpoint for the refresh-token flow (Cameleer). |
| `uriEndpointOverride` + `overrideEndpoint=true` | | Base URL of an emulator or proxy. |

`useMetadataServer`, `authenticate`, `proxyHost`, `proxyPort` and `trustAllCertificates` work as
on the [google-sheets](https://pmsudhi.github.io/cameleer/docs/components/google-sheets.html#options) page. `applicationName`, `inBody` and
`splitResult` are accepted and ignored.

## Message headers

Every option can also be set per message with a `CamelGoogleMail.<option>` header (for example
`CamelGoogleMail.id`, `CamelGoogleMail.q`), which wins over the URI option.

| header | direction | description |
|---|---|---|
| `CamelGoogleMail.content` | in | Request body for methods that take one. |
| `CamelGoogleMail.id` | out | Id of the message sent by `messages/send`. |
| `CamelGoogleMail.text` | out | Decoded plain-text part, after `messages/get`. |
| `CamelGoogleMail.subject`, `CamelGoogleMail.from`, `CamelGoogleMail.to` | out | Decoded headers, after `messages/get`. |
| `CamelGoogleMail.size` | out | Attachment size, after `attachments/get`. |

## Run it with Docker

The service account needs domain-wide delegation for the `https://mail.google.com/` scope
(Google Admin console, Security, API controls).

```sh
docker run --rm \
  -e GOOGLE_USER=reports@example.com -e DIGEST_TO=team@example.com \
  -e GOOGLE_APPLICATION_CREDENTIALS=/secrets/key.json \
  -v "$PWD/key.json:/secrets/key.json:ro" \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/digest.camel.yaml
```

## Common questions

### How do I send an e-mail with Gmail from a route?
Send a text body to `google-mail://messages/send?to=...&subject=...`, or send a map with `to`,
`subject`, `text` and optionally `html`. Authenticate as the sender with a service account plus
`delegate`, or with `clientId`/`clientSecret`/`refreshToken`.

### Why does Gmail return 400 "Precondition check failed" or 403?
A service account has no mailbox of its own. Set `delegate` to a user of your domain and allow
the service account's client id for the Gmail scope in the Admin console.

### How do I read the text of a message?
Call `messages/get` with `CamelGoogleMail.id`; the plain-text part is decoded into the
`CamelGoogleMail.text` header and the body keeps the full resource.

### How do I process new e-mails as they arrive?
Use the [google-mail-stream](https://pmsudhi.github.io/cameleer/docs/components/google-mail-stream.html) consumer.

## Related

- [google-mail-stream](https://pmsudhi.github.io/cameleer/docs/components/google-mail-stream.html): consume new messages.
- [google-calendar](https://pmsudhi.github.io/cameleer/docs/components/google-calendar.html), [google-drive](https://pmsudhi.github.io/cameleer/docs/components/google-drive.html),
  [google-sheets](https://pmsudhi.github.io/cameleer/docs/components/google-sheets.html).
- [Apache Camel Google Mail component](https://camel.apache.org/components/next/google-mail-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-mail-stream.html

# Google Mail Stream component

> The `google-mail-stream` component polls a Gmail mailbox and emits each new message that matches a Gmail search query, then marks it as read.

**Scheme:** `google-mail-stream:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Google Mail Stream](https://camel.apache.org/components/next/google-mail-stream-component.html)

## When to use it

- Triage an inbox with an LLM: summarize or classify each new e-mail and route it to the right
  team, ticket system or chat channel.
- Turn e-mails sent to a shared address (orders@, invoices@) into messages on a queue.
- Extract data from automated e-mails (alerts, receipts) without running an IMAP client.

## URI format

```text
google-mail-stream://index[?options]
```

The path is a free name (Camel uses `index`); it is not used.

## Example

Every minute, take the unread messages of the authenticated user, ask an LLM for a one-line
summary and a label, and log the result. The route authenticates as the user with an OAuth
refresh token. The OpenAI endpoint works with any OpenAI-compatible server (set
`OPENAI_BASE_URL`, for example to an Ollama or vLLM server).

```yaml
- route:
    id: inbox-triage
    from:
      uri: "google-mail-stream://index?maxResults=20&clientId={{env:GOOGLE_CLIENT_ID}}&clientSecret=RAW({{env:GOOGLE_CLIENT_SECRET}})&refreshToken=RAW({{env:GOOGLE_REFRESH_TOKEN}})&delay=60000"
      steps:
        - setHeader:
            name: subject
            simple: "${header.CamelGoogleMailStreamSubject}"
        - to: "openai:chat-completion?model={{env:OPENAI_MODEL:gpt-4o-mini}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}&temperature=0&systemMessage=Summarize this email in one sentence, then label it URGENT, ACTION or FYI."
        - log: "${header.subject}: ${body}"
        - to: "log:inbox-triage"
```

The body of each exchange is the plain-text part of the message (the raw RFC 822 bytes with
`raw=true`). After the route processes a message successfully, the consumer removes its
`UNREAD` label, so the default query `is:unread` does not return it again. If processing fails,
the message stays unread and is not emitted again by this consumer while it keeps running.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("google-mail-stream://index?maxResults=20&clientId={{env:GOOGLE_CLIENT_ID}}&clientSecret=RAW({{env:GOOGLE_CLIENT_SECRET}})&refreshToken=RAW({{env:GOOGLE_REFRESH_TOKEN}})&delay=60000")
        .set_header("subject", simple("${header.CamelGoogleMailStreamSubject}"))
        .to("openai:chat-completion?model={{env:OPENAI_MODEL:gpt-4o-mini}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}&temperature=0&systemMessage=Summarize this email in one sentence, then label it URGENT, ACTION or FYI.")
        .log("${header.subject}: ${body}")
        .to("log:inbox-triage");
})?;
```

## How it polls

Each poll lists up to `maxResults` messages matching `query` and `labels`, fetches each one and
emits them oldest first. Messages already emitted are remembered (in memory) while they still
match the query, so a message is not emitted twice even with `markAsRead=false`. After a
restart, messages that are still unread are emitted again.

## Options

| option | default | description |
|---|---|---|
| `query` | `is:unread` | Gmail search query, for example `is:unread label:invoices`. |
| `labels` | | Comma separated label ids that messages must have (for example `INBOX`). |
| `maxResults` | `10` | Maximum messages per poll. |
| `markAsRead` | `true` | Remove the `UNREAD` label after a message is processed successfully. |
| `raw` | `false` | Body = the raw RFC 822 message bytes instead of the decoded text part. |
| `userId` | `me` | Mailbox to read. |
| `delay` | `500` | Milliseconds between polls. Scheduled poll options such as `initialDelay` (default `1000`), `repeatCount` and `backoffMultiplier` also apply. |
| `clientId`, `clientSecret`, `refreshToken` | | OAuth user credentials (refresh-token flow). Wrap secrets in `RAW(...)`. |
| `serviceAccountKey` | `GOOGLE_APPLICATION_CREDENTIALS` | Service account JSON key; needs `delegate`. |
| `delegate` (alias `subject`) | | User to impersonate with domain-wide delegation. |
| `accessToken` | | A fixed OAuth access token. |
| `tokenServerUrl` | `https://oauth2.googleapis.com/token` | Token endpoint for the refresh-token flow (Cameleer). |
| `scopes` | `https://mail.google.com/` | Comma separated OAuth scopes. |
| `uriEndpointOverride` + `overrideEndpoint=true` | | Base URL of an emulator or proxy. |

`useMetadataServer`, `authenticate`, `proxyHost`, `proxyPort` and `trustAllCertificates` work as
on the [google-sheets](https://pmsudhi.github.io/cameleer/docs/components/google-sheets.html#options) page.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGoogleMailStreamId` | out | Message id. |
| `CamelGoogleMailStreamThreadId` | out | Thread id. |
| `CamelGoogleMailStreamSubject` | out | `Subject` header. |
| `CamelGoogleMailStreamFrom` | out | `From` header. |
| `CamelGoogleMailStreamTo`, `CamelGoogleMailStreamCc`, `CamelGoogleMailStreamBcc` | out | Recipient headers. |
| `CamelGoogleMailStreamReceivedDate` | out | Gmail `internalDate` (milliseconds since the epoch). |
| `CamelGoogleMailStreamLabels` | out | List of label ids. |

## Run it with Docker

```sh
docker run --rm \
  -e GOOGLE_CLIENT_ID -e GOOGLE_CLIENT_SECRET -e GOOGLE_REFRESH_TOKEN \
  -e OPENAI_API_KEY \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/inbox-triage.camel.yaml
```

Get a refresh token once with the OAuth consent flow for the `https://mail.google.com/` scope
(for example with the OAuth 2.0 Playground and your own client id).

## Common questions

### How do I process new Gmail messages in a route?
Use `from: google-mail-stream://index` with credentials. Each new unread message arrives with
its text as the body and its subject and sender in `CamelGoogleMailStream*` headers.

### How do I read only one label?
Set `query=label:my-label is:unread`, or `labels=<labelId>` with a label id from
`google-mail://labels/list`.

### How do I keep messages unread?
Set `markAsRead=false`. The consumer still does not emit the same message twice while it runs.

### Does it use Gmail push notifications?
No, it polls. For push, call `google-mail://users/watch` with a Pub/Sub topic and consume that
topic with [google-pubsub](https://pmsudhi.github.io/cameleer/docs/components/google-pubsub.html).

## Related

- [google-mail](https://pmsudhi.github.io/cameleer/docs/components/google-mail.html): send and manage messages.
- [openai](https://pmsudhi.github.io/cameleer/docs/components/openai.html) and the [AI components guide](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html).
- [Apache Camel Google Mail Stream component](https://camel.apache.org/components/next/google-mail-stream-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-pubsub.html

# Google Pub/Sub component

> The `google-pubsub` component publishes messages to Google Cloud Pub/Sub topics and consumes messages from Pub/Sub subscriptions, with gRPC streaming pull by default.

**Scheme:** `google-pubsub:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Google Pubsub](https://camel.apache.org/components/next/google-pubsub-component.html)

## When to use it

- Turn webhooks or HTTP calls into Pub/Sub events for downstream services.
- Consume a subscription and write each message to a database, a file or another system.
- Connect edge gateways to Google Cloud: publish readings from the device, consume commands.
- Feed AI agents: publish tasks to a topic and let several workers consume the subscription.

## URI format

```text
google-pubsub://projectId:destinationName[?options]
```

The destination is a **topic** for the producer and a **subscription** for the consumer.

## Example

Accept JSON events on an HTTP endpoint and publish each one to a topic:

```yaml
- route:
    id: webhook-to-pubsub
    from:
      uri: "platform-http:/events?httpMethodRestrict=POST"
      steps:
        - to: "google-pubsub://{{env:GCP_PROJECT:my-project}}:{{env:PUBSUB_TOPIC:events}}"
        - setHeader:
            name: CamelHttpResponseCode
            constant: 202
        - setBody:
            simple: "${header.CamelGooglePubsubMessageId}"
```

Consume a subscription (streaming pull) and write every message to a file named after its
message id. Successful exchanges are acknowledged, failed ones are nacked and redelivered:

```yaml
- route:
    id: pubsub-to-files
    from:
      uri: "google-pubsub://{{env:GCP_PROJECT:my-project}}:{{env:PUBSUB_SUBSCRIPTION:events-sub}}?concurrentConsumers=2"
      steps:
        - log: "message ${header.CamelGooglePubsubMessageId} published at ${header.CamelGooglePubsubPublishTime}"
        - setHeader:
            name: CamelFileName
            simple: "${header.CamelGooglePubsubMessageId}.json"
        - to: "file:{{env:OUT_DIR:out}}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("google-pubsub://my-project:events-sub")
        .log("got ${body}")
        .to("google-pubsub://my-project:audit");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `ackMode` | `AUTO` | Consumer: `AUTO` acknowledges successful exchanges and nacks failed ones; `NONE` leaves it to the subscription's ack deadline. |
| `synchronousPull` | `false` | Consumer: `false` uses gRPC streaming pull (`Subscriber/StreamingPull`), `true` uses scheduled REST `pull` calls. |
| `concurrentConsumers` | `1` | Streaming pull: number of parallel streams. |
| `maxOutstandingMessages` | `1000` | Streaming pull flow control: unacknowledged messages. |
| `maxOutstandingBytes` | `104857600` | Streaming pull flow control: unacknowledged bytes. |
| `ackDeadlineSeconds` | `10` | Ack deadline of the stream (1 to 600); also the deadline of `createSubscription`. |
| `maxAckExtensionPeriod` | `3600` | Seconds a message's lease is extended while it is still being processed. |
| `maxMessagesPerPoll` | `1` | Synchronous pull: messages per `pull` call. |
| `pubsubEndpoint` | `pubsub.googleapis.com:443` | gRPC target for streaming pull (`host:port`; `https://` for TLS, a bare address is plaintext, as for the emulator). |
| `messageOrderingEnabled` | `false` | Enable message ordering on `createSubscription`. |
| `operation` | `publish` | Cameleer producer operations: `publish`, `createTopic`, `deleteTopic`, `createSubscription`, `getSubscription`, `deleteSubscription`. The header `CamelGooglePubsubOperation` overrides it. |
| `topic` | | Topic of `createSubscription`. |
| `deadLetterTopic` | | `createSubscription`: dead-letter topic. |
| `maxDeliveryAttempts` | | `createSubscription`: delivery attempts before dead-lettering (5 to 100). |
| `enableExactlyOnceDelivery` | `false` | `createSubscription`: exactly-once delivery. The synchronous pull consumer then extends leases while processing and checks each acknowledgement. |
| `delay`, `initialDelay`, ... | `500`, `1000` | Synchronous pull poll schedule (milliseconds) and the other scheduled-poll options. |

Credentials and endpoint options (`serviceAccountKey`, `GOOGLE_APPLICATION_CREDENTIALS`,
`useMetadataServer`, `authenticate=false` and `endpoint` for the Pub/Sub emulator, ...) are
the same for every Google component: see [credentials](https://pmsudhi.github.io/cameleer/docs/components/google-storage.html#credentials).

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGooglePubsubAttributes` | in / out | Message attributes (a map). |
| `CamelGooglePubsubOrderingKey` | in / out | Ordering key. |
| `CamelGooglePubsubMessageId` | out | Id of the published message (a list for a list body) or of the consumed message. |
| `CamelGooglePubsubAckId` | out | Ack id of a consumed message. |
| `CamelGooglePubsubPublishTime` | out | Publish time of a consumed message. |
| `CamelGooglePubsubDeliveryAttempt` | out | Delivery attempt (subscriptions with a dead-letter policy). |
| `CamelGooglePubsubOperation` | in | Cameleer: operation to run. |
| `CamelGooglePubsubTopic` | in | Cameleer: topic of `createSubscription`. |

A list body is published as one message per element. The consumer's body is the message
data as bytes.

## Run it with Docker

```sh
docker run --rm -p 8080:8080 -v "$PWD:/routes:ro" \
  -v "$HOME/keys/sa.json:/keys/sa.json:ro" -e GOOGLE_APPLICATION_CREDENTIALS=/keys/sa.json \
  -e GCP_PROJECT=my-project -e PUBSUB_TOPIC=events \
  pmsudhi/cameleer run /routes/webhook-to-pubsub.camel.yaml
```

## Common questions

### How do I use the Pub/Sub emulator?
Add `authenticate=false&endpoint=localhost:8085`. The REST calls and streaming pull both go to
that address (plaintext); `pubsubEndpoint` overrides the streaming pull target alone.

### How do I set message attributes?
Put a map in the `CamelGooglePubsubAttributes` header before the producer, for example with a
processor or a `setHeader` whose expression returns a map.

### How do I create a subscription with a dead-letter topic?
Send a message to `google-pubsub://project:my-sub?operation=createSubscription&topic=orders&deadLetterTopic=orders-dlq&maxDeliveryAttempts=5`.

### Why does my consumer get each message only once even when it fails?
It does not: with `ackMode=AUTO` a failed exchange is nacked, and Pub/Sub delivers it again.
Use the error handler or a dead-letter policy to stop endless retries.

## Related

- [Google Pub/Sub Lite](https://pmsudhi.github.io/cameleer/docs/components/google-pubsub-lite.html), [Google BigQuery](https://pmsudhi.github.io/cameleer/docs/components/google-bigquery.html)
- [Kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html) for self-hosted streaming
- [Apache Camel Google Pubsub](https://camel.apache.org/components/next/google-pubsub-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-pubsub-lite.html

# Google Pub/Sub Lite component

> The `google-pubsub-lite` component publishes messages to Google Cloud Pub/Sub Lite topics and consumes Pub/Sub Lite subscriptions over gRPC, partition by partition.

**Scheme:** `google-pubsub-lite:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Google PubSub Lite](https://camel.apache.org/components/next/google-pubsub-lite-component.html)

**Note:** Google deprecated Pub/Sub Lite in 2024 and announced its shutdown for March 2026.
The component is kept for parity with Apache Camel and for existing emulator-based setups. For
new work use [Google Pub/Sub](https://pmsudhi.github.io/cameleer/docs/components/google-pubsub.html) or [Kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html).

## When to use it

- Keep running an existing Pub/Sub Lite integration while migrating away from it.
- Partitioned, ordered streams: messages with the same ordering key go to the same partition.
- Test partition and cursor handling against a Pub/Sub Lite emulator.

## URI format

```text
google-pubsub-lite:projectId:location:destinationName[?options]
```

`location` is a zone (`us-central1-a`) or region. The destination is a topic for the producer
and a subscription for the consumer. The gRPC target is `{region}-pubsublite.googleapis.com:443`
unless `pubsubEndpoint` (or `endpoint`) points elsewhere.

## Example

Publish one message per second, keyed by device so each device's messages stay in order:

```yaml
- route:
    id: telemetry-to-pubsub-lite
    from:
      uri: "timer:telemetry?period=1000"
      steps:
        - setHeader:
            name: CamelGooglePubsubLiteOrderingKey
            constant: "{{env:DEVICE_ID:device-1}}"
        - setBody:
            simple: "reading ${exchangeProperty.CamelTimerCounter}"
        - to: "google-pubsub-lite:{{env:GCP_PROJECT:my-project}}:{{env:LITE_LOCATION:us-central1-a}}:{{env:LITE_TOPIC:telemetry}}"
        - log: "published as ${header.CamelGooglePubsubLiteMessageId}"
```

Consume a subscription; each processed message commits the partition cursor:

```yaml
- route:
    id: pubsub-lite-to-files
    from:
      uri: "google-pubsub-lite:{{env:GCP_PROJECT:my-project}}:{{env:LITE_LOCATION:us-central1-a}}:{{env:LITE_SUBSCRIPTION:telemetry-sub}}?maxMessagesPerPoll=50"
      steps:
        - setHeader:
            name: CamelFileName
            simple: "p${header.CamelGooglePubsubLitePartition}-${header.CamelGooglePubsubLiteOffset}.txt"
        - to: "file:{{env:OUT_DIR:out}}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("google-pubsub-lite:my-project:us-central1-a:telemetry-sub")
        .log("partition ${header.CamelGooglePubsubLitePartition}: ${body}");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `ackMode` | `AUTO` | Consumer: `AUTO` commits the cursor after each successfully processed message; `NONE` never commits. |
| `maxMessagesPerPoll` | `100` | Consumer flow control: messages per partition per poll. |
| `perPartitionBytes` | `10485760` | Consumer flow control bytes per partition; also the per-partition storage of `createTopic`. |
| `streamIdleTimeout` | `300` | Consumer: milliseconds without a message after which a partition's stream ends for this poll. |
| `pubsubEndpoint` | `{region}-pubsublite.googleapis.com:443` | gRPC target (`host:port`; plaintext for emulators). |
| `operation` | publish | Cameleer admin operations: `createTopic`, `createSubscription`, `deleteTopic`, `deleteSubscription`, `getTopicPartitions` (body = partition count). Header `CamelGooglePubsubLiteOperation`. |
| `partitionCount` | `1` | `createTopic`: number of partitions. |
| `topic` | | `createSubscription`: the topic to subscribe to. |
| `delay`, `initialDelay`, ... | `500`, `1000` | Consumer poll schedule (milliseconds) and the other scheduled-poll options. |

`concurrentConsumers`, `maxAckExtensionPeriod`, `publisherCacheSize`, `publisherCacheTimeout`,
`publisherTerminationTimeout`, `serializer` and `loggerId` are accepted for Camel
compatibility and ignored. Credentials are shared by all Google components: see
[credentials](https://pmsudhi.github.io/cameleer/docs/components/google-storage.html#credentials).

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGooglePubsubLiteOrderingKey` | in / out | Ordering key; messages with a key go to partition `hash(key) % partitions`, others round robin. |
| `CamelGooglePubsubLiteAttributes` | in / out | Attributes (a map; consumed values are strings). |
| `CamelGooglePubsubLiteEventTime` | in | Event time (epoch milliseconds). |
| `CamelGooglePubsubLiteMessageId` | out | `partition:offset` of the published or consumed message (a list for a list body). |
| `CamelGooglePubsubLitePublishTime` | out | Publish time of a consumed message. |
| `CamelGooglePubsubLitePartition` | out | Partition. |
| `CamelGooglePubsubLiteOffset` | out | Offset in the partition. |
| `CamelGooglePubsubLiteOperation` | in | Cameleer: admin operation. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" \
  -v "$HOME/keys/sa.json:/keys/sa.json:ro" -e GOOGLE_APPLICATION_CREDENTIALS=/keys/sa.json \
  -e GCP_PROJECT=my-project -e LITE_TOPIC=telemetry \
  pmsudhi/cameleer run /routes/telemetry-to-pubsub-lite.camel.yaml
```

## Common questions

### How do I create a Pub/Sub Lite topic with several partitions?
Send a message to `google-pubsub-lite:project:zone:telemetry?operation=createTopic&partitionCount=3`.

### What happens when processing fails?
The partition stops for that poll without committing, so the failed message (and the ones after
it) are delivered again on the next poll.

### Does the consumer keep a stream open?
No. Each poll opens one `Subscribe` stream per partition from the committed cursor and reads until
the stream is idle. This differs from Camel, which keeps long-lived streams.

## Related

- [Google Pub/Sub](https://pmsudhi.github.io/cameleer/docs/components/google-pubsub.html), [Kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html)
- [Apache Camel Google PubSub Lite](https://camel.apache.org/components/next/google-pubsub-lite-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-secret-manager.html

# Google Secret Manager component

> The `google-secret-manager` component creates, reads, versions, lists and deletes secrets in Google Cloud Secret Manager, and the `{{gcp:name}}` placeholder reads secrets into route configuration.

**Scheme:** `google-secret-manager:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Google Secret Manager](https://camel.apache.org/components/next/google-secret-manager-component.html)

## When to use it

- Keep API keys, database passwords and tokens out of route files: write `{{gcp:db-password}}`.
- Rotate a secret on a schedule by adding a new version.
- Read a secret at runtime, for example to hand a short-lived credential to an AI agent tool.

## URI format

```text
google-secret-manager://projectId[?options]
```

Without a project in the URI, the project of the service account key is used.

## Example

Add a new random version of a secret once a day:

```yaml
- route:
    id: rotate-webhook-token
    from:
      uri: "timer:rotate?period=86400000"
      steps:
        - setHeader:
            name: CamelGoogleSecretManagerSecretId
            constant: "{{env:SECRET_ID:webhook-token}}"
        - setBody:
            simple: "${uuid}"
        - to: "google-secret-manager://{{env:GCP_PROJECT:my-project}}?operation=addSecretVersion"
        - log: "added ${body}"
```

Read the latest version of a secret and use it as a header for the next step:

```yaml
- route:
    id: read-api-key
    from:
      uri: "timer:read-key?repeatCount=1"
      steps:
        - setHeader:
            name: CamelGoogleSecretManagerSecretId
            constant: "{{env:SECRET_ID:api-key}}"
        - to: "google-secret-manager://{{env:GCP_PROJECT:my-project}}"
        - setHeader:
            name: X-Api-Key
            simple: "${body}"
        - setBody:
            constant: "key loaded"
        - to: "file:{{env:OUT_DIR:out}}?fileName=status.txt"
```

### Secrets as placeholders

With these properties in `application.properties`, any route can use `{{gcp:name}}`, `{{gcp:name/field}}` (a field of a JSON
secret), `{{gcp:name@version}}` and `{{gcp:name:default}}`:

```properties
camel.vault.gcp.projectId=my-project
camel.vault.gcp.serviceAccountKey=file:/keys/sa.json
# or: camel.vault.gcp.useDefaultInstance=true  (uses GOOGLE_APPLICATION_CREDENTIALS)
```

```text
- to: "https://api.example.com/orders?apiKey={{gcp:api-key}}"
- setBody:
    simple: "{{gcp:db/password}}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:read-key?repeatCount=1")
        .set_header("CamelGoogleSecretManagerSecretId", constant("api-key"))
        .to("google-secret-manager://my-project")
        .log("secret length ${body.length()}");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `operation` | `getSecretVersion` | `getSecretVersion`, `createSecret`, `addSecretVersion` (Cameleer), `deleteSecret`, `listSecrets`. Header `CamelGoogleSecretManagerOperation`. |

`client` is accepted for Camel compatibility and ignored. Credentials are shared by all Google
components: see [credentials](https://pmsudhi.github.io/cameleer/docs/components/google-storage.html#credentials).

### Operations

- `getSecretVersion`: body = the payload (text) of `CamelGoogleSecretManagerVersionId`,
  default `latest`.
- `createSecret`: creates the secret (automatic replication) with the body as version 1;
  body = the version name `projects/p/secrets/s/versions/1`.
- `addSecretVersion`: adds the body as a new version.
- `deleteSecret`: deletes the secret and all versions. `listSecrets`: body = list of secret ids.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGoogleSecretManagerOperation` | in | Operation. |
| `CamelGoogleSecretManagerSecretId` | in | Secret id (required by all operations except `listSecrets`). |
| `CamelGoogleSecretManagerVersionId` | in | Version for `getSecretVersion` (default `latest`). |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" \
  -v "$HOME/keys/sa.json:/keys/sa.json:ro" -e GOOGLE_APPLICATION_CREDENTIALS=/keys/sa.json \
  -e GCP_PROJECT=my-project -e SECRET_ID=webhook-token \
  pmsudhi/cameleer run /routes/rotate-webhook-token.camel.yaml
```

## Common questions

### How do I use a Google secret in an endpoint URI?
Configure `camel.vault.gcp.projectId` and credentials, then write `{{gcp:secret-name}}` in the
URI. The secret is read when the route starts.

### How do I read one field of a JSON secret?
Use `{{gcp:name/field}}`, for example `{{gcp:db/password}}` for a secret `{"user":..,"password":..}`.

### How do I read an older version?
Set `CamelGoogleSecretManagerVersionId` (producer) or write `{{gcp:name@3}}` (placeholder).

## Related

- [AWS Secrets Manager](https://pmsudhi.github.io/cameleer/docs/components/aws-secrets-manager.html), [Azure Key Vault](https://pmsudhi.github.io/cameleer/docs/components/azure-key-vault.html)
- [Apache Camel Google Secret Manager](https://camel.apache.org/components/next/google-secret-manager-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-sheets.html

# Google Sheets component

> The `google-sheets` component reads, writes, appends and clears cell values in Google Sheets spreadsheets, and creates and updates spreadsheets, over the Sheets v4 REST API.

**Scheme:** `google-sheets:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no (see [google-sheets-stream](https://pmsudhi.github.io/cameleer/docs/components/google-sheets-stream.html)) · **Producer:** yes · **Apache Camel:** [Google Sheets](https://camel.apache.org/components/next/google-sheets-component.html)

## When to use it

- Use a spreadsheet as a lightweight database for an AI agent: one tool appends rows, another
  reads them back, and people can see and edit the data in the browser.
- Append form submissions, orders or leads to a sheet that a business team already uses.
- Export a report into a shared sheet on a schedule (`data/update` or `data/batchUpdate`).
- Create spreadsheets and add or rename tabs (`spreadsheets/create`, `spreadsheets/batchUpdate`).

## URI format

```text
google-sheets://apiName/methodName[?options]
```

`apiName/methodName` is one of `data/get`, `data/update`, `data/append`, `data/clear`,
`data/batchGet`, `data/batchUpdate`, `data/batchClear`, `spreadsheets/get`,
`spreadsheets/create` or `spreadsheets/batchUpdate`. Any other value fails when the endpoint is
created.

## Example

Two HTTP tools for an agent that keeps its leads in a sheet. `POST /tools/save-lead` with
`{"name": "Ada", "email": "ada@example.com", "score": 92}` appends one row to the `Leads` tab;
`GET /tools/list-leads` returns all rows as JSON.

```yaml
- route:
    id: save-lead
    from:
      uri: "platform-http:/tools/save-lead?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - setBody:
            simple: '[["${body[name]}", "${body[email]}", "${body[score]}"]]'
        - to: "google-sheets://data/append?spreadsheetId={{env:SHEET_ID}}&range=Leads!A:C&valueInputOption=RAW"
        - marshal:
            json: {}
- route:
    id: list-leads
    from:
      uri: "platform-http:/tools/list-leads?httpMethodRestrict=GET"
      steps:
        - to: "google-sheets://data/get?spreadsheetId={{env:SHEET_ID}}&range=Leads!A2:C1000"
        - marshal:
            json: {}
```

The append returns the update result (`updatedRange`, `updatedRows`, `updatedCells`, ...). The
get returns the rows as a list of lists of strings, for example
`[["Ada","ada@example.com","92"]]`. The values are built with a Simple template here, so a name
that contains a double quote would break the JSON; build the row in a processor or send a JSON
array from the client when the input is untrusted.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("platform-http:/tools/save-lead?httpMethodRestrict=POST")
        .unmarshal("json")
        .set_body(simple(r#"[["${body[name]}", "${body[email]}", "${body[score]}"]]"#))
        .to("google-sheets://data/append?spreadsheetId={{env:SHEET_ID}}&range=Leads!A:C&valueInputOption=RAW")
        .marshal("json");
    b.from("platform-http:/tools/list-leads?httpMethodRestrict=GET")
        .to("google-sheets://data/get?spreadsheetId={{env:SHEET_ID}}&range=Leads!A2:C1000")
        .marshal("json");
})?;
```

## What each method does

| api/method | input | body after the call |
|---|---|---|
| `data/get` | `spreadsheetId`, `range`, optional `majorDimension` | the values (list of rows) |
| `data/update` | `range`, values (see below), `valueInputOption` | the update result |
| `data/append` | `range`, values, `valueInputOption` | the `updates` object of the append result |
| `data/clear` | `range` | the clear result |
| `data/batchGet` | `ranges` (comma separated, or a list in the `CamelGoogleSheets.ranges` header) | a list with the values of each range |
| `data/batchUpdate` | body or `CamelGoogleSheets.data` header: a list of `{range, values}` maps (or a request map with `data`), `valueInputOption` | the response (`totalUpdatedCells`, ...) |
| `data/batchClear` | `ranges` | the cleared ranges |
| `spreadsheets/get` | `spreadsheetId` | the spreadsheet resource (title, sheets, ...) |
| `spreadsheets/create` | `title` (default `Untitled spreadsheet`) | the new spreadsheet; header `CamelGoogleSheets.spreadsheetId` is set |
| `spreadsheets/batchUpdate` | body or `CamelGoogleSheets.batchUpdateSpreadsheetRequest` header: a list of requests, one request map, or a map with `requests` | the response (`replies`) |

Values for `data/update` and `data/append` come from the `CamelGoogleSheets.values` header, or
else the body. Accepted shapes: a list of rows (lists), a single flat list (one row), a
`ValueRange` map with a `values` field, or JSON text of any of these.

## Options

| option | default | description |
|---|---|---|
| `spreadsheetId` | | The spreadsheet id (from the sheet URL). Required except for `spreadsheets/create`. |
| `range` | | A1 range, for example `Sheet1!A1:C10` or `Leads!A:C`. Required for `data/get`, `update`, `append`, `clear`. |
| `ranges` | | Comma separated ranges for `data/batchGet` and `data/batchClear`. |
| `valueInputOption` | `USER_ENTERED` | `USER_ENTERED` (parse like typed input: numbers, dates, formulas) or `RAW`. |
| `majorDimension` | | `ROWS` or `COLUMNS` for `data/get`. |
| `title` | | Title for `spreadsheets/create`. |
| `serviceAccountKey` | `GOOGLE_APPLICATION_CREDENTIALS` | Service account JSON key: `file:path`, a plain path or inline JSON. An `authorized_user` or `external_account` (workload identity federation) file also works. |
| `clientId`, `clientSecret`, `refreshToken` | | OAuth user credentials (refresh-token flow), used instead of a service account. |
| `accessToken` | | A fixed OAuth access token. |
| `tokenServerUrl` | `https://oauth2.googleapis.com/token` | Token endpoint for the refresh-token flow (Cameleer). |
| `delegate` (alias `subject`) | | User to impersonate with domain-wide delegation. |
| `useMetadataServer` | `false` | Take tokens from the GCE/GKE metadata server (also used automatically when `GCE_METADATA_HOST` is set and no other credentials are given). `metadataServerUrl` overrides its URL (Cameleer). |
| `authenticate` | `true` | `false` sends no credentials (emulators). |
| `uriEndpointOverride` + `overrideEndpoint=true` | | Send requests to another base URL (an emulator or a proxy). `endpoint` (`host:port` or a URL) does the same. |
| `proxyHost`, `proxyPort` | `3128` | HTTP proxy. Without them the `HTTPS_PROXY`/`NO_PROXY` environment variables apply. |
| `trustAllCertificates` | `false` | Only for local emulators with self-signed certificates. |

`applicationName`, `scopes`, `splitResult`, `inBody` and `includeGridData` are accepted for
compatibility with Camel and ignored. The OAuth scope is always
`https://www.googleapis.com/auth/spreadsheets`.

## Message headers

Every option above that the methods read (`spreadsheetId`, `range`, `ranges`,
`valueInputOption`, `majorDimension`, `title`) can also be set per message as a
`CamelGoogleSheets.<option>` header, which wins over the URI option.

| header | direction | description |
|---|---|---|
| `CamelGoogleSheets.values` | in | Values for `data/update` / `data/append` (instead of the body). |
| `CamelGoogleSheets.data` | in | Value ranges for `data/batchUpdate`. |
| `CamelGoogleSheets.batchUpdateSpreadsheetRequest` | in | Requests for `spreadsheets/batchUpdate`. |
| `CamelGoogleSheets.spreadsheetId` | in / out | Spreadsheet id; set after `spreadsheets/create`. |

## Run it with Docker

Share the spreadsheet with the service account's e-mail address (Editor), then:

```sh
docker run --rm -p 8080:8080 \
  -e SHEET_ID=1AbC...xyz \
  -e GOOGLE_APPLICATION_CREDENTIALS=/secrets/key.json \
  -v "$PWD/key.json:/secrets/key.json:ro" \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/leads.camel.yaml
```

## Common questions

### How do I append a row to a Google Sheet?
Send a list (one row) or a list of lists (several rows) to
`google-sheets://data/append?spreadsheetId=...&range=Sheet1!A:C`. Rows are added after the last
row of the table found in the range.

### Why does Sheets return "The caller does not have permission"?
The service account is a separate Google identity. Share the spreadsheet with its e-mail address
(`...@...iam.gserviceaccount.com`), or use `clientId`/`clientSecret`/`refreshToken` to act as a
user.

### How do I add a new tab?
Call `spreadsheets/batchUpdate` with the body `[{"addSheet": {"properties": {"title": "2026"}}}]`.
Requests are passed through to the API unchanged.

### How do I get notified of new rows?
Use the [google-sheets-stream](https://pmsudhi.github.io/cameleer/docs/components/google-sheets-stream.html) consumer, which emits only the rows
appended since the previous poll.

## Related

- [google-sheets-stream](https://pmsudhi.github.io/cameleer/docs/components/google-sheets-stream.html): consume new rows.
- [google-drive](https://pmsudhi.github.io/cameleer/docs/components/google-drive.html), [google-mail](https://pmsudhi.github.io/cameleer/docs/components/google-mail.html),
  [google-calendar](https://pmsudhi.github.io/cameleer/docs/components/google-calendar.html).
- [Apache Camel Google Sheets component](https://camel.apache.org/components/next/google-sheets-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-sheets-stream.html

# Google Sheets Stream component

> The `google-sheets-stream` component polls a range of a Google Sheets spreadsheet and emits the rows that were appended since the previous poll.

**Scheme:** `google-sheets-stream:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Google Sheets Stream](https://camel.apache.org/components/next/google-sheets-stream-component.html)

## When to use it

- Trigger a route when someone adds a row to a shared sheet: a new order, a support request, a
  task for an AI agent to work on.
- Feed rows entered by a business team into a database, a queue or an API.
- Run a "sheet as inbox" workflow at the edge without a webhook or a public URL (it only polls).

## URI format

```text
google-sheets-stream://spreadsheetId?range=Sheet1!A2:D1000[&options]
```

The spreadsheet id is the path (or the `spreadsheetId` option). `range` is required; the endpoint
fails to start without it.

## Example

Every 30 seconds, read `Orders!A2:D1000` and send each new row on its own, as JSON, to the log.
The first poll emits all rows already in the range.

```yaml
- route:
    id: new-orders
    from:
      uri: "google-sheets-stream://{{env:SHEET_ID}}?range=Orders!A2:D1000&splitResults=true&delay=30000"
      steps:
        - log: "row ${header[CamelGoogleSheets.valueIndex]}: ${body}"
        - marshal:
            json: {}
        - to: "log:new-orders"
```

With `splitResults=true` the body of each exchange is one row, for example
`["1042","Ada","3","shipped"]`, and `CamelGoogleSheets.valueIndex` is its 1-based row number
inside the range. Without it, one exchange per poll carries all new rows as a `ValueRange` map
(`range`, `majorDimension`, `values`).

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("google-sheets-stream://{{env:SHEET_ID}}?range=Orders!A2:D1000&splitResults=true&delay=30000")
        .log("row ${header[CamelGoogleSheets.valueIndex]}: ${body}")
        .marshal("json")
        .to("log:new-orders");
})?;
```

## How new rows are detected

The consumer remembers how many rows the range had at the previous poll and emits only the rows
after that position. If rows are deleted so that the range becomes shorter, it starts counting
again from the new end. Edits to rows that were already emitted are not detected.

This differs from Apache Camel, whose consumer emits the whole range on every poll. Use a
filter or an idempotent consumer there; with Cameleer you get only the appended rows. The
position is kept in memory, so after a restart the first poll emits the whole range again.

## Options

| option | default | description |
|---|---|---|
| `spreadsheetId` | path | The spreadsheet id (instead of the path). |
| `range` | | A1 range to read, for example `Orders!A2:D1000`. Required. |
| `splitResults` | `false` | One exchange per new row instead of one per poll. |
| `majorDimension` | `ROWS` | `ROWS` or `COLUMNS`. |
| `valueRenderOption` | | `FORMATTED_VALUE`, `UNFORMATTED_VALUE` or `FORMULA`. |
| `delay` | `500` | Milliseconds between polls (scheduled poll consumer options such as `initialDelay` (default `1000`), `repeatCount` and `backoffMultiplier` also apply). |
| `serviceAccountKey` | `GOOGLE_APPLICATION_CREDENTIALS` | Service account JSON key (`file:path`, path or inline JSON). |
| `clientId`, `clientSecret`, `refreshToken` | | OAuth user credentials (refresh-token flow). |
| `accessToken` | | A fixed OAuth access token. |
| `delegate` (alias `subject`) | | User to impersonate with domain-wide delegation. |
| `scopes` | `https://www.googleapis.com/auth/spreadsheets` | Comma separated OAuth scopes. |
| `uriEndpointOverride` + `overrideEndpoint=true` | | Base URL of an emulator or proxy. |

The other shared Google options (`tokenServerUrl`, `useMetadataServer`, `authenticate`,
`proxyHost`, `proxyPort`, `trustAllCertificates`) work as on the
[google-sheets](https://pmsudhi.github.io/cameleer/docs/components/google-sheets.html#options) page. `includeGridData` and `maxResults` are accepted
and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGoogleSheets.spreadsheetId` | out | The spreadsheet id. |
| `CamelGoogleSheets.range` | out | The range returned by the API (for example `Orders!A2:D1000`). |
| `CamelGoogleSheets.majorDimension` | out | `ROWS` or `COLUMNS`. |
| `CamelGoogleSheets.valueIndex` | out | With `splitResults=true`: the 1-based row number within the range. |

Header names contain dots, so read them in Simple with the bracket form:
`${header[CamelGoogleSheets.valueIndex]}`.

## Run it with Docker

```sh
docker run --rm \
  -e SHEET_ID=1AbC...xyz \
  -e GOOGLE_APPLICATION_CREDENTIALS=/secrets/key.json \
  -v "$PWD/key.json:/secrets/key.json:ro" \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/new-orders.camel.yaml
```

## Common questions

### How do I trigger a route when a row is added to a Google Sheet?
Use `google-sheets-stream://<spreadsheetId>?range=...&splitResults=true`. Each appended row
arrives as one exchange with the row as a list.

### Why do I get all rows again after a restart?
The last row position is kept in memory only. Skip the first batch with a filter, or record
processed ids with an idempotent repository.

### Can I watch several tabs?
Use one route per range, each with its own `google-sheets-stream` endpoint.

## Related

- [google-sheets](https://pmsudhi.github.io/cameleer/docs/components/google-sheets.html): read and write values.
- [Idempotent consumer](https://pmsudhi.github.io/cameleer/docs/guides/eips.html)
- [Apache Camel Google Sheets Stream component](https://camel.apache.org/components/next/google-sheets-stream-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-speech-to-text.html

# Google Speech-to-Text component

> The `google-speech-to-text` component transcribes audio to text with the Google Cloud Speech-to-Text v1 API, from audio bytes or a `gs://` file.

**Scheme:** `google-speech-to-text:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** none (Cameleer component)

## When to use it

- Transcribe voice notes, call recordings or voicemail dropped into a folder or bucket.
- Turn spoken commands from an edge device into text, then route on the text.
- Feed transcripts to an LLM for summarization or classification
  ([OpenAI](https://pmsudhi.github.io/cameleer/docs/components/openai.html), [Vertex AI](https://pmsudhi.github.io/cameleer/docs/components/google-vertexai.html)).

## URI format

```text
google-speech-to-text://label[?options]
```

The label is free text that names the endpoint; it is not sent to the API.

## Example

Transcribe every `.wav` file in a folder and write the transcript next to it as a `.txt` file:

```yaml
- route:
    id: transcribe-voice-notes
    from:
      uri: "file:{{env:INBOX_DIR:voice-notes}}?include=.*\\.wav&move=.done"
      steps:
        - to: "google-speech-to-text://notes?languageCode={{env:LANGUAGE:en-US}}&sampleRateHertz=16000&enableAutomaticPunctuation=true"
        - log: "transcribed ${file:name} (confidence ${header.CamelGoogleSpeechToTextConfidence})"
        - setHeader:
            name: CamelFileName
            simple: "${file:onlyname.noext}.txt"
        - to: "file:{{env:OUT_DIR:transcripts}}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("file:voice-notes?include=.*\\.wav")
        .to("google-speech-to-text://notes?sampleRateHertz=16000")
        .log("${body}");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `operation` | `recognize` | `recognize`, `longRunningRecognize`, `getOperation`. Header `CamelGoogleSpeechToTextOperation`. |
| `encoding` | `LINEAR16` | Audio encoding (`LINEAR16`, `FLAC`, `MULAW`, `OGG_OPUS`, ...). |
| `sampleRateHertz` | | Sample rate of the audio. |
| `languageCode` | `en-US` | Language of the speech. |
| `model` | | Recognition model, for example `latest_long` or `phone_call`. |
| `enableAutomaticPunctuation` | `false` | Add punctuation to the transcript. |

Credentials are shared by all Google components: see [credentials](https://pmsudhi.github.io/cameleer/docs/components/google-storage.html#credentials).

### Operations

- `recognize`: the body is the audio bytes, or a text `gs://bucket/file` URI. Body = the best
  transcript (results joined with spaces).
- `longRunningRecognize`: starts an asynchronous recognition (for audio longer than a minute);
  body and `CamelGoogleSpeechToTextOperationName` = the operation name.
- `getOperation`: checks the operation in `CamelGoogleSpeechToTextOperationName`; sets
  `CamelGoogleSpeechToTextDone`, and the body is the transcript once done.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGoogleSpeechToTextOperation` | in | Operation. |
| `CamelGoogleSpeechToTextConfidence` | out | Confidence of the first result. |
| `CamelGoogleSpeechToTextResults` | out | All results returned by the API. |
| `CamelGoogleSpeechToTextOperationName` | in / out | Long-running operation name. |
| `CamelGoogleSpeechToTextDone` | out | `getOperation`: whether the operation finished. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" -v "$PWD/voice-notes:/in" -v "$PWD/transcripts:/out" \
  -v "$HOME/keys/sa.json:/keys/sa.json:ro" -e GOOGLE_APPLICATION_CREDENTIALS=/keys/sa.json \
  -e INBOX_DIR=/in -e OUT_DIR=/out \
  pmsudhi/cameleer run /routes/transcribe-voice-notes.camel.yaml
```

## Common questions

### How do I transcribe a file stored in Cloud Storage?
Send its URI as the body text, for example `gs://my-bucket/call.wav`.

### How do I transcribe long recordings?
Use `operation=longRunningRecognize`, then poll with `operation=getOperation` (for example from a
timer route) until `CamelGoogleSpeechToTextDone` is true.

### Is streaming recognition supported?
No. Only the `recognize` and `longrunningrecognize` REST calls are implemented.

## Related

- [Google Text-to-Speech](https://pmsudhi.github.io/cameleer/docs/components/google-text-to-speech.html), [Google Vertex AI](https://pmsudhi.github.io/cameleer/docs/components/google-vertexai.html), [AWS Transcribe](https://pmsudhi.github.io/cameleer/docs/components/aws2-transcribe.html)
- [AI components guide](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-text-to-speech.html

# Google Text-to-Speech component

> The `google-text-to-speech` component turns text or SSML into speech audio (MP3, OGG Opus, WAV) with the Google Cloud Text-to-Speech v1 API.

**Scheme:** `google-text-to-speech:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** none (Cameleer component)

## When to use it

- Generate audio announcements, alerts or prompts for IVR and kiosks.
- Read out an AI agent's answer: chain an LLM call and this component.
- Produce spoken versions of short articles or notifications in a batch job.

## URI format

```text
google-text-to-speech://label[?options]
```

The label is free text that names the endpoint; it is not sent to the API.

## Example

Turn every `.txt` file in a folder into an MP3 file with a chosen voice:

```yaml
- route:
    id: text-to-mp3
    from:
      uri: "file:{{env:INBOX_DIR:announcements}}?include=.*\\.txt&move=.done"
      steps:
        - to: "google-text-to-speech://announcer?voiceName={{env:VOICE:en-US-Neural2-C}}&audioEncoding=MP3&speakingRate=0.95"
        - setHeader:
            name: CamelFileName
            simple: "${file:onlyname.noext}.mp3"
        - to: "file:{{env:OUT_DIR:audio}}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("file:announcements?include=.*\\.txt")
        .to("google-text-to-speech://announcer?voiceName=en-US-Neural2-C")
        .set_header("CamelFileName", simple("${file:onlyname.noext}.mp3"))
        .to("file:audio");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `operation` | `synthesize` | `synthesize` or `listVoices`. Header `CamelGoogleTextToSpeechOperation`. |
| `languageCode` | `en-US` | Voice language; also the filter of `listVoices`. |
| `voiceName` | | Voice, for example `en-US-Neural2-C`. |
| `ssmlGender` | | `MALE`, `FEMALE` or `NEUTRAL`. |
| `audioEncoding` | `MP3` | `MP3`, `OGG_OPUS`, `LINEAR16`, `MULAW`, `ALAW`. |
| `speakingRate` | | Speed, 0.25 to 4.0 (1.0 is normal). |
| `pitch` | | Pitch in semitones, -20.0 to 20.0. |
| `textType` | | `ssml` to send the body as SSML. A body starting with `<speak` is SSML anyway. |

Credentials are shared by all Google components: see [credentials](https://pmsudhi.github.io/cameleer/docs/components/google-storage.html#credentials).

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGoogleTextToSpeechOperation` | in | Operation. |
| `CamelGoogleTextToSpeechAudioEncoding` | out | Encoding of the returned audio. |

`synthesize` returns the audio bytes as the body; `listVoices` returns the list of voices.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" -v "$PWD/announcements:/in" -v "$PWD/audio:/out" \
  -v "$HOME/keys/sa.json:/keys/sa.json:ro" -e GOOGLE_APPLICATION_CREDENTIALS=/keys/sa.json \
  -e INBOX_DIR=/in -e OUT_DIR=/out \
  pmsudhi/cameleer run /routes/text-to-mp3.camel.yaml
```

## Common questions

### How do I use SSML?
Send a body that starts with `<speak>`, or set `textType=ssml`.

### Which voices can I use?
Call `operation=listVoices` (optionally with `languageCode`) and pick a `name`.

### Can it stream audio?
No. Each call returns the complete audio file.

## Related

- [Google Speech-to-Text](https://pmsudhi.github.io/cameleer/docs/components/google-speech-to-text.html), [AWS Polly](https://pmsudhi.github.io/cameleer/docs/components/aws2-polly.html)
- [AI components guide](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/google-vertexai.html

# Google Vertex AI component

> The `google-vertexai` component calls Gemini and other models on Google Cloud Vertex AI: text and chat generation, streaming, multimodal prompts, embeddings, Imagen images, token counts and partner models such as Claude.

**Scheme:** `google-vertexai:` · **Crate:** `cameleer-cloud` · **Cargo feature:** [`cloud`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Google Vertex AI](https://camel.apache.org/components/next/google-vertexai-component.html)

## When to use it

- Summarize, classify or extract data from messages with Gemini inside a route.
- Create embeddings for documents and store them for semantic search (RAG).
- Describe images or documents (`generateMultimodal`) from a folder or a `gs://` bucket.
- Call Anthropic Claude or other partner models through Vertex AI (`rawPredict`) when your
  data must stay in your Google Cloud project.

## URI format

```text
google-vertexai:projectId:location:modelId[?options]
```

For example `google-vertexai:my-project:us-central1:gemini-2.0-flash`.

## Example

Summarize every support ticket that lands in a folder and write the summary to another folder:

```yaml
- route:
    id: summarize-tickets
    from:
      uri: "file:{{env:INBOX_DIR:tickets}}?include=.*\\.txt&move=.done"
      steps:
        - to: "google-vertexai:{{env:GCP_PROJECT:my-project}}:{{env:VERTEX_LOCATION:us-central1}}:{{env:VERTEX_MODEL:gemini-2.0-flash}}?temperature=0.2&maxOutputTokens=256&systemInstruction=Summarize the support ticket in one sentence."
        - log: "summary of ${file:name}: ${body} (${header.CamelGoogleVertexAITotalTokenCount} tokens)"
        - to: "file:{{env:OUT_DIR:summaries}}"
```

Create an embedding for each document and save the vector as JSON:

```yaml
- route:
    id: embed-documents
    from:
      uri: "file:{{env:INBOX_DIR:docs}}?include=.*\\.txt&move=.done"
      steps:
        - convertBodyTo:
            type: String
        - to: "google-vertexai:{{env:GCP_PROJECT:my-project}}:{{env:VERTEX_LOCATION:us-central1}}:text-embedding-004?operation=generateEmbeddings&taskType=RETRIEVAL_DOCUMENT"
        - marshal:
            json: {}
        - setHeader:
            name: CamelFileName
            simple: "${file:onlyname.noext}.json"
        - to: "file:{{env:OUT_DIR:vectors}}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("file:tickets?include=.*\\.txt")
        .to("google-vertexai:my-project:us-central1:gemini-2.0-flash?systemInstruction=Summarize in one sentence.")
        .to("file:summaries");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `operation` | `generateText` | See the operations below. Header `CamelGoogleVertexAIOperation`. |
| `temperature`, `topP`, `topK` | | Sampling settings (`generationConfig`). |
| `maxOutputTokens` | | Maximum tokens in the answer (`rawPredict`: `max_tokens`, default 1024). |
| `candidateCount` | | Number of candidates. |
| `systemInstruction` | | System prompt (header `CamelGoogleVertexAISystemInstruction` wins). |
| `publisher` | `google` | Model publisher: `google`, or a partner such as `anthropic`, `meta`, `mistralai`. |
| `streamOutputMode` | `complete` | Streaming: `complete` (body = whole text) or `chunks` (body = list of chunks). |
| `streamingChunkProcessor` | | Streaming: `#bean` processor called with each chunk. |
| `taskType` | | `generateEmbeddings`: for example `RETRIEVAL_DOCUMENT`, `RETRIEVAL_QUERY`. |
| `outputDimensionality` | | `generateEmbeddings`: vector size. |
| `sampleCount` | `1` | `generateImage`: number of images. |
| `aspectRatio` | | `generateImage`: for example `16:9`. |

Credentials are shared by all Google components: see [credentials](https://pmsudhi.github.io/cameleer/docs/components/google-storage.html#credentials)
(scope `cloud-platform`).

### Operations

- `generateText` (default), `generateChat`, `generateCode`: a text body is one user turn; a list
  body is a conversation of `{role, content}` (or `{role, parts}`) maps, where role `assistant`
  becomes `model`; a map body is sent as the request as it is (use this for `tools`,
  `responseSchema` or safety settings). Body = the text of the first candidate.
- `generateTextStreaming`, `generateChatStreaming`, `generateCodeStreaming`: the same with
  `streamGenerateContent` (server-sent events, decoded as they arrive).
- `generateMultimodal`: the body bytes (MIME type `CamelGoogleVertexAIMediaMimeType`, default
  `image/png`) or a `gs://` URI in `CamelGoogleVertexAIMediaGcsUri`, with the prompt in
  `CamelGoogleVertexAIPrompt`.
- `countTokens`: body = total token count.
- `generateEmbeddings`: a text body gives one vector, a list body a list of vectors.
- `generateImage` (Imagen): body = list of image bytes.
- `rawPredict` / `streamRawPredict` (partner models): a map body is sent as it is (for example an
  Anthropic Messages request); a text body is wrapped into an Anthropic Messages request
  (`anthropic_version` `vertex-2023-10-16`). The answer text is in
  `CamelGoogleVertexAIResponseText` (`rawPredict`) or the body (`streamRawPredict`).

### What is not supported

- No automatic function-calling loop: you can send `tools` in a map body, but the body is only
  the text parts of the answer. Read `functionCall` parts from the raw response in the
  `CamelGoogleVertexAIResponse` header and call the tool yourself.
- No Live API (bidirectional audio / video), no context caching, no batch prediction jobs.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGoogleVertexAIOperation` | in | Operation. |
| `CamelGoogleVertexAISystemInstruction` | in | System prompt. |
| `CamelGoogleVertexAIPrompt` | in | Text prompt of `generateMultimodal`. |
| `CamelGoogleVertexAIMediaMimeType` | in | MIME type of the media body. |
| `CamelGoogleVertexAIMediaGcsUri` | in | `gs://` URI of the media. |
| `CamelGoogleVertexAIFinishReason` | out | `STOP`, `MAX_TOKENS`, `SAFETY`, ... |
| `CamelGoogleVertexAIPromptTokenCount` | out | Prompt tokens. |
| `CamelGoogleVertexAICandidatesTokenCount` | out | Answer tokens. |
| `CamelGoogleVertexAITotalTokenCount` | out | Total tokens. |
| `CamelGoogleVertexAISafetyRatings` | out | Safety ratings of the first candidate. |
| `CamelGoogleVertexAIResponse` | out | The raw response. |
| `CamelGoogleVertexAIResponseText` | out | Text of a partner model answer. |
| `CamelGoogleVertexAIStreamingChunkCount` | out | Streaming: number of chunks. |
| `CamelGoogleVertexAIStreamingChunkIndex` | out | Streaming: index of the chunk given to the chunk processor. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" -v "$PWD/tickets:/in" -v "$PWD/summaries:/out" \
  -v "$HOME/keys/sa.json:/keys/sa.json:ro" -e GOOGLE_APPLICATION_CREDENTIALS=/keys/sa.json \
  -e GCP_PROJECT=my-project -e INBOX_DIR=/in -e OUT_DIR=/out \
  pmsudhi/cameleer run /routes/summarize-tickets.camel.yaml
```

## Common questions

### How do I send a chat history to Gemini?
Send a list of `{role, content}` maps with `operation=generateChat`; use roles `user` and
`assistant` (or `model`).

### How do I get JSON output from Gemini?
Send a map body with `contents` and `generationConfig.responseMimeType=application/json`
(and a `responseSchema`), then `unmarshal: json` the body.

### How do I call Claude on Vertex AI?
Use the Claude model id with `publisher=anthropic&operation=rawPredict` and a text body, or a
map body with an Anthropic Messages request.

### How does this compare to the openai component?
[`openai`](https://pmsudhi.github.io/cameleer/docs/components/openai.html) talks to any OpenAI-compatible server (OpenAI, Ollama, vLLM). See the
[AI components guide](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html) for a side-by-side view.

## Related

- [OpenAI](https://pmsudhi.github.io/cameleer/docs/components/openai.html), [AWS Bedrock](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html), [Azure OpenAI](https://pmsudhi.github.io/cameleer/docs/components/azure-openai.html)
- [AI components guide](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html)
- [Apache Camel Google Vertex AI](https://camel.apache.org/components/next/google-vertexai-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/graphql.html

# GraphQL component

> The `graphql` component sends GraphQL queries and mutations to a GraphQL server over HTTP or HTTPS and returns the JSON response.

**Scheme:** `graphql:` · **Crate:** `cameleer-saas` · **Cargo feature:** [`saas`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [GraphQL](https://camel.apache.org/components/next/graphql-component.html)

## When to use it

- Query a GraphQL API (GitHub, Shopify, Hasura, your own) from a route.
- Run a mutation for each incoming message, with the message supplying the variables.
- Let an AI agent fetch structured data through one fixed, reviewed query.

## URI format

```text
graphql://http://host[:port]/path[?options]
graphql://host/path[?options]      (https is assumed without a scheme)
```

## Example

Look up a book by id: the `id` header becomes the query variable, and the response JSON is
reduced to the book's name.

```yaml
- route:
    id: book-lookup
    from:
      uri: direct:book
      steps:
        - setHeader:
            name: gqlVariables
            simple: '{"id": "${header.bookId}"}'
        - to: "graphql://{{env:GRAPHQL_URL:http://localhost:4000/graphql}}?query=query Book($id: ID) { book(id: $id) { id name author } }&variablesHeader=gqlVariables&accessToken={{env:GRAPHQL_TOKEN:changeme}}"
        - unmarshal:
            json: {}
        - setBody:
            simple: "${body[data][book][name]}"
```

The variables are taken from the header named by `variablesHeader` (JSON text or an object),
else from the `variables` option, else from the body when the body is an object (for example
after `unmarshal: json`).

## Rust DSL

```rust
fn book_lookup_route(b: &mut RouteBuilder, url: &str, token: &str) {
    b.from("direct:book")
        .route_id("book-lookup")
        .set_header("gqlVariables", simple(r#"{"id": "${header.bookId}"}"#))
        .to(&format!("graphql://{}?query=query Book($id: ID) {{ book(id: $id) {{ id name author }} }}&variablesHeader=gqlVariables&accessToken={}", url, token))
        .unmarshal_json()
        .set_body(simple("${body[data][book][name]}"));
}
```

## Options

| option | default | description |
|---|---|---|
| `query` | | The query or mutation text. |
| `queryFile` | | File holding the query (`classpath:` / file path). |
| `queryHeader` | | Header holding the query. |
| `operationName` | | Operation to run when the document has several. |
| `variables` | | Variables as a JSON object, or `#bean` holding a map. |
| `variablesHeader` | | Header holding the variables. |
| `accessToken` | | Token sent as `Authorization: <jwtAuthorizationType> <token>`. |
| `jwtAuthorizationType` | `Bearer` | Authorization scheme for `accessToken`. |
| `username`, `password` | | Basic authentication. |
| `throwExceptionOnFailure` | `true` | Fail on HTTP errors. |

Without `query`, `queryFile` or `queryHeader` the body is the query. With one of them, an object
body supplies the variables when neither `variablesHeader` nor `variables` gives them.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGraphqlResponseCode` | out | HTTP status of the response. |

The result body is the response JSON as text (`{"data": ..., "errors": ...}`), as in Apache
Camel; unmarshal it with `json` to read fields.

## Run it with Docker

```sh
docker run --rm -e GRAPHQL_URL=https://api.example.com/graphql -e GRAPHQL_TOKEN \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/book-lookup.camel.yaml
```

The example starts from `direct:book`; in practice, put a REST endpoint, a Kafka consumer or a
timer in front of it.

## Common questions

### How do I pass variables?
Put JSON text or an object in a header named by `variablesHeader`, fix them with
`variables={"id":"1"}`, or send an object body (not JSON text) together with `query`.

### Why is the response a string?
Apache Camel returns the response text too. Add `unmarshal: json` to work with fields.

### Do GraphQL errors fail the exchange?
Only HTTP errors do. A `200` response with an `errors` array is returned as is; check
`${body[errors]}` after unmarshalling.

## Related

- [http](https://pmsudhi.github.io/cameleer/docs/components/http.html), [rest](https://pmsudhi.github.io/cameleer/docs/components/rest.html).
- Apache Camel: [GraphQL component](https://camel.apache.org/components/next/graphql-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/grpc.html

# gRPC component

> The `grpc` component calls gRPC services and hosts gRPC services in a route, with messages described by a `.proto` file read at runtime.

**Scheme:** `grpc:` · **Crate:** `cameleer-grpc` · **Cargo feature:** [`grpc`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [gRPC](https://camel.apache.org/components/next/grpc-component.html)

Cameleer has its own HTTP/2, HPACK and protobuf implementation. Instead of generated Java stubs,
it reads the service and message definitions from `protoFile` when the route starts; messages
are maps (`{"sku": "A-100"}`) on the Camel side. Without `protoFile`, bodies are raw protobuf
bytes. It interoperates with grpcio, grpc-go and curl.

## When to use it

- Expose an operation as a gRPC service for other microservices or for an AI agent's tool
  layer.
- Call a gRPC backend from a route (unary, server streaming, client streaming, bidirectional).
- Low-latency calls between edge gateways and a central service over one HTTP/2 connection.

## URI format

```text
grpc://host:port/package.Service[?options]
```

A consumer hosts the service on `host:port`; a producer calls `method` on the service at
`host:port`.

## Example: host a gRPC service

The service definition, saved next to the route as `inventory.proto`:

```proto
syntax = "proto3";
package inventory;

service Inventory {
  rpc GetStock (StockRequest) returns (StockReply);
}

message StockRequest { string sku = 1; }
message StockReply { string sku = 1; int32 quantity = 2; }
```

The route implements `GetStock`. The request arrives as a map; the route's result (a map, here
built from JSON) is the response.

```yaml
- route:
    id: inventory-service
    from:
      uri: "grpc://0.0.0.0:{{env:GRPC_PORT:50051}}/inventory.Inventory?protoFile={{env:PROTO_FILE:inventory.proto}}"
      steps:
        - log: "${header.CamelGrpcMethodName} for ${body[sku]}"
        - setBody:
            simple: '{"sku": "${body[sku]}", "quantity": 12}'
        - unmarshal:
            json: {}
```

## Example: call a gRPC service

```yaml
- route:
    id: check-stock
    from:
      uri: timer:check-stock?repeatCount=1
      steps:
        - setBody:
            constant: '{"sku": "A-100"}'
        - to: "grpc://{{env:INVENTORY_ADDRESS:localhost:50051}}/inventory.Inventory?method=getStock&protoFile={{env:PROTO_FILE:inventory.proto}}"
        - log: "A-100: ${body[quantity]} in stock"
```

The method can be given as the stub name (`getStock`) or the proto name (`GetStock`). A JSON
text body is accepted as the request message.

## Rust DSL

```rust
fn inventory_service_route(b: &mut RouteBuilder, port: u16, proto: &str) {
    b.from(&format!("grpc://0.0.0.0:{}/inventory.Inventory?protoFile={}", port, proto))
        .route_id("inventory-service")
        .log("${header.CamelGrpcMethodName} for ${body[sku]}")
        .set_body(simple(r#"{"sku": "${body[sku]}", "quantity": 12}"#))
        .unmarshal_json();
}
```

## Options

| option | default | description |
|---|---|---|
| `protoFile` | | `.proto` file with the service and messages (`classpath:` / `file:` prefixes allowed). Without it, bodies are raw bytes. |
| `method` | | Producer: method to call. |
| `producerStrategy` | `SIMPLE` | `SIMPLE`: one call per exchange (server streaming returns an array). `STREAMING`: a long-lived client-streaming or bidi call across exchanges. |
| `streamRepliesTo` | | Endpoint that receives each streamed response. |
| `consumerStrategy` | `AGGREGATION` | `AGGREGATION`: the route runs once per call. `PROPAGATION` (or `DELEGATION`): once per request message. |
| `forwardOnCompleted`, `forwardOnError` | `false` | `PROPAGATION`: also route the completion / error event. |
| `routeControlledStreamObserver` | `false` | Consumer: the route answers through the response observer in the `CamelGrpcResponseObserver` property. |
| `deadline` | | Producer: call deadline (`grpc-timeout`), e.g. `2s`. |
| `usePlainText` | `true` | `false` uses TLS with ALPN `h2`. |
| `negotiationType` | `PLAINTEXT` | `PLAINTEXT`, `PLAINTEXT_UPGRADE` (h2c upgrade) or `TLS`. |
| `keyCertChainResource`, `keyResource` | | PEM certificate chain and key: the consumer's server identity, or the producer's client certificate. |
| `trustCertCollectionResource` | | PEM CAs: the producer trusts them; on a consumer, client certificates from them are required. |
| `authenticationType` | `NONE` | `JWT` (with `jwtSecret`, `jwtAlgorithm` HMAC256/384/512, `jwtIssuer`, `jwtSubject`) or `GOOGLE` (with `serviceAccountResource`). |
| `compression` | | `gzip` or `deflate` for requests. Alias `compressorName`. |
| `maxMessageSize` | 4 MiB | Largest message. |
| `maxConcurrentCallsPerConnection` | 256 | Consumer limit. |
| `flowControlWindow` | 1 MiB | HTTP/2 flow control window. |
| `shutdownTimeout` | `5s` | Consumer shutdown grace time. |
| `clientInterceptors`, `serverInterceptors` | | `#bean` lists of interceptors; `autoDiscoverClientInterceptors` / `autoDiscoverServerInterceptors` (default `true`) pick up registry beans. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelGrpcMethodName` | out | Consumer: method being called (stub name, e.g. `getStock`). |
| `CamelGrpcEventType` | out / in | `onNext`, `onCompleted`, `onError`. Producer with `STREAMING`: `onCompleted` half-closes the call. |
| `CamelGrpcUserAgent` | out | Consumer: client user agent. |

Request metadata becomes headers on the consumer; on the producer, non-`Camel*` scalar headers
are sent as metadata and response metadata becomes headers. Failures raise
`StatusRuntimeException` with the message `CODE: description`. On the consumer, exceptions map
to status codes: `IllegalArgumentException` to `INVALID_ARGUMENT`, `TimeoutException` to
`DEADLINE_EXCEEDED`, `UnsupportedOperationException` to `UNIMPLEMENTED`, others to `INTERNAL`.

## Run it with Docker

```sh
docker run --rm -p 50051:50051 -e PROTO_FILE=/routes/inventory.proto \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/inventory-service.camel.yaml
grpcurl -plaintext -proto inventory.proto -d '{"sku":"A-100"}' localhost:50051 inventory.Inventory/GetStock
```

## Common questions

### Do I need to generate code from the .proto file?
No. Point `protoFile` at the file; Cameleer parses it at startup.

### How do I return an error status?
Throw an exception in the route: `IllegalArgumentException` gives `INVALID_ARGUMENT`; a
`StatusRuntimeException` with message `NOT_FOUND: no such sku` gives that code.

### How do I call a server-streaming method?
With the default `SIMPLE` strategy the body becomes an array of responses; set
`streamRepliesTo=seda:replies` to also handle each response as it arrives.

### Does it support TLS?
Yes: `usePlainText=false` with `keyCertChainResource` and `keyResource` on the server and
`trustCertCollectionResource` on the client. Mutual TLS is supported.

## Related

- [thrift](https://pmsudhi.github.io/cameleer/docs/components/thrift.html): Thrift RPC.
- [rest](https://pmsudhi.github.io/cameleer/docs/components/rest.html), [http](https://pmsudhi.github.io/cameleer/docs/components/http.html).
- Apache Camel: [gRPC component](https://camel.apache.org/components/next/grpc-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/http.html

# HTTP component

> The `http` component calls HTTP and HTTPS endpoints from a route: REST APIs, webhooks and LLM APIs, over HTTP/1.1 or HTTP/2.

**Scheme:** `http:` · **Also:** `https:` · **Crate:** `cameleer-http` · **Cargo feature:** none, always included; HTTP/2 needs [`http2`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [HTTP](https://camel.apache.org/components/next/http-component.html)

The `http` component is a client only. To serve HTTP requests, use
[platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html) or the [REST DSL](https://pmsudhi.github.io/cameleer/docs/components/rest.html).

## When to use it

- Call a REST API from a route and work with the JSON response.
- Call an LLM API (OpenAI, or any OpenAI-compatible server such as Ollama or vLLM) from an AI
  agent workflow.
- Post events to a webhook (Slack, Teams, a CI system).
- Proxy or bridge requests from a `platform-http` route to a backend (`bridgeEndpoint=true`).

## URI format

```text
http://host[:port]/path[?options]
https://host[:port]/path[?options]
```

The scheme picks plain HTTP or TLS. Query parameters that are not component options are sent
to the server as query parameters, as in Apache Camel. This also means that a misspelled option
is not rejected: it is sent to the server.

## Example

An endpoint that answers questions with an LLM. `POST /ask` with a question as the body; the
route calls the chat completions API and returns the answer as plain text. The same route works
with any OpenAI-compatible server: point `LLM_BASE_URL` at it.

```yaml
- route:
    id: ask-llm
    from:
      uri: platform-http:/ask?httpMethodRestrict=POST
      steps:
        - removeHeaders:
            pattern: "*"
        - setHeader:
            name: Authorization
            simple: "Bearer {{env:OPENAI_API_KEY:sk-test-key}}"
        - setHeader:
            name: Content-Type
            constant: application/json
        - setBody:
            simple: '{"model": "{{env:LLM_MODEL:gpt-4o-mini}}", "messages": [{"role": "user", "content": "${body}"}]}'
        - to: "{{env:LLM_BASE_URL:https://api.openai.com/v1}}/chat/completions?httpMethod=POST"
        - unmarshal:
            json: {}
        - setBody:
            simple: "${body[choices][0][message][content]}"
        - removeHeaders:
            pattern: "*"
        - setHeader:
            name: Content-Type
            constant: text/plain
```

The question is placed into the JSON as is; a question containing double quotes needs escaping
first. `removeHeaders` keeps the incoming request headers (and the API's response headers) from
being forwarded.

## Rust DSL

```rust
fn ask_llm_route(b: &mut RouteBuilder, base_url: &str, api_key: &str) {
    b.from("platform-http:/ask?httpMethodRestrict=POST")
        .route_id("ask-llm")
        .remove_headers("*")
        .set_header("Authorization", constant(format!("Bearer {}", api_key)))
        .set_header("Content-Type", constant("application/json"))
        .set_body(simple(r#"{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "${body}"}]}"#))
        .to(&format!("{}/chat/completions?httpMethod=POST", base_url))
        .unmarshal_json()
        .set_body(simple("${body[choices][0][message][content]}"))
        .remove_headers("*")
        .set_header("Content-Type", constant("text/plain"));
}
```

## Options

| option | default | description |
|---|---|---|
| `httpMethod` | GET, or POST when there is a body | HTTP method. The `CamelHttpMethod` header wins over it. |
| `httpVersion` | `HTTP/1.1` | `HTTP/2` uses HTTP/2 (TLS with ALPN `h2`, or h2c prior knowledge for `http:`), one multiplexed connection per target. Alias `protocolVersion`. |
| `throwExceptionOnFailure` | `true` | Fail with `HttpOperationFailedException` when the status is outside `okStatusCodeRange`. |
| `okStatusCodeRange` | `200-299` | Status codes treated as success, e.g. `200-299,404`. |
| `bridgeEndpoint` | `false` | Ignore the `CamelHttpUri` header and use the endpoint URI (for proxies). |
| `connectTimeout` | `30s` | TCP connect timeout. |
| `socketTimeout` | `60s` | Read timeout. Aliases `soTimeout`, `responseTimeout`. |
| `followRedirects` | `false` | Follow 3xx redirects. |
| `copyHeaders` | `true` | Copy the response headers to the message. |
| `skipRequestHeaders` | `false` | Do not send the message headers as request headers. |
| `skipResponseHeaders` | `false` | Do not map response headers to message headers. |
| `userAgent` | | `User-Agent` header value. |
| `authUsername`, `authPassword` | | Basic authentication. `authMethod` accepts only `Basic`. |
| `chunked` | `false` | Send the request body with chunked transfer coding. |
| `getWithBody`, `deleteWithBody` | `false` | Send a body with GET / DELETE. |
| `ignoreResponseBody` | `false` | Do not read the response body into the message. |
| `customHostHeader` | | Value for the `Host` header. |
| `preserveHostHeader` | `false` | Forward the incoming `Host` header. |
| `contentCompressionDisabled` | `false` | Do not send `Accept-Encoding: gzip, deflate` and do not decode compressed responses. |
| `connectionClose` | `false` | Do not pool keep-alive connections. |
| `connectionsPerRoute` | `20` | Pooled connections per host and port. |
| `disableStreamCache` | `false` | Return the response body as a stream handle instead of bytes. |
| `proxyHost`, `proxyPort` | | HTTP proxy (CONNECT tunnelling for `https`). Aliases `proxyAuthHost`, `proxyAuthPort`. |
| `proxyAuthUsername`, `proxyAuthPassword` | | Proxy credentials. |
| `useSystemProperties` | `false` | Take the proxy from `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`. |
| `sslContextParameters` | | `#bean` with trust and key material for `https` (client certificates come from its key store). |
| `useGlobalSslContextParameters` | `false` | Use the global `camel.ssl.*` parameters. |

Certificates and host names are always verified for `https`. Several Apache Camel options
(`headerFilterStrategy`, `httpClientConfigurer`, `cookieHandler`, `maxTotalConnections` and
others) are accepted and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelHttpMethod` | in | Method for this request. |
| `CamelHttpUri` | in | Full target URI (ignored with `bridgeEndpoint=true`). |
| `CamelHttpPath` | in | Path appended to the endpoint path. |
| `CamelHttpQuery` | in | Query string for this request. |
| `Content-Type` | in / out | Request and response media type. |
| `CamelHttpResponseCode` | out | Response status code. |
| `CamelHttpResponseText` | out | Response reason phrase. |

Other message headers (except `Camel*` ones) are sent as request headers, and response headers
become message headers. A failure raises `HttpOperationFailedException` carrying the status code
and the response body.

## Run it with Docker

```sh
docker run --rm -p 8080:8080 -e OPENAI_API_KEY -v "$PWD:/routes:ro" \
  pmsudhi/cameleer run /routes/ask-llm.camel.yaml
curl -XPOST --data 'What is Apache Camel?' localhost:8080/ask
```

For a local model, add `-e LLM_BASE_URL=http://host.docker.internal:11434/v1 -e LLM_MODEL=llama3.2`.

## Common questions

### How do I send JSON with a POST request?
Set the body to the JSON text, set `Content-Type: application/json`, and use
`httpMethod=POST` (a body alone also makes the request a POST).

### How do I handle a 404 without an exception?
Add `throwExceptionOnFailure=false` and branch on `${header.CamelHttpResponseCode}`, or widen
`okStatusCodeRange`.

### How do I call an API that needs a client certificate?
Bind an `SSLContextParameters` bean with a key store and reference it with
`sslContextParameters=#myTls`. Mutual TLS works with TLS 1.2 and 1.3.

### Why does a typo in an option not fail?
Unknown options are sent as query parameters, as in Apache Camel. Check the request the server
receives.

## Related

- [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html): serve HTTP requests.
- [rest](https://pmsudhi.github.io/cameleer/docs/components/rest.html): REST DSL and the `rest:` producer.
- [graphql](https://pmsudhi.github.io/cameleer/docs/components/graphql.html), [webhook](https://pmsudhi.github.io/cameleer/docs/components/webhook.html).
- Apache Camel: [HTTP component](https://camel.apache.org/components/next/http-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/imap.html

# IMAP component

> The `imap` component reads email from an IMAP mailbox: it polls a folder for new (unseen) messages and turns each one into an exchange.

**Scheme:** `imap:` · **Also:** `imaps:` · **Crate:** `cameleer-protocols` · **Cargo feature:** [`protocols`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Mail](https://camel.apache.org/components/next/mail-component.html)

`imaps:` uses implicit TLS (port 993); `imap:` can upgrade with STARTTLS
(`mail.imap.starttls.enable=true`). Each mail header becomes a message header, the body is the
first `text/plain` part, and other parts are attachments.

## When to use it

- Triage a shared inbox: route invoices, orders and support requests to different systems.
- Feed incoming mail to an AI agent that classifies or answers it.
- Turn mail from devices or legacy systems that can only send email into events.

## URI format

```text
imap://[username@]host[:port][?options]
imaps://[username@]host[:port][?options]
```

Default ports: 143 (`imap`), 993 (`imaps`).

## Example

Poll a support mailbox every 30 seconds. Mails with "invoice" in the subject are saved for the
accounting system and moved to the `Processed` folder; everything else goes to a queue for an
AI triage agent.

```yaml
- route:
    id: mail-triage
    from:
      uri: "imaps://{{env:IMAP_HOST:imap.example.com}}?username={{env:IMAP_USER:support@example.com}}&password={{env:IMAP_PASSWORD:changeme}}&moveTo=Processed&delay=30000"
      steps:
        - choice:
            when:
              - simple: "${header.Subject} contains 'invoice'"
                steps:
                  - to: "file:{{env:INVOICE_DIR:invoices}}?fileName=${exchangeId}.txt"
            otherwise:
              steps:
                - to: seda:triage
- route:
    id: triage-agent
    from:
      uri: seda:triage
      steps:
        - log: "to triage: ${header.Subject} from ${header.From}"
```

## Rust DSL

```rust
fn mail_triage_routes(b: &mut RouteBuilder, imap: &str, invoice_dir: &str) {
    b.from(imap)
        .route_id("mail-triage")
        .choice()
        .when(simple("${header.Subject} contains 'invoice'"))
        .to(&format!("file:{}?fileName=${{exchangeId}}.txt", invoice_dir))
        .otherwise()
        .to("seda:triage")
        .end_choice();
    b.from("seda:triage").route_id("triage-agent").log("to triage: ${header.Subject} from ${header.From}");
}
```

## Options

| option | default | description |
|---|---|---|
| `username`, `password` | | Login. |
| `folderName` | `INBOX` | Folder to read. |
| `unseen` | `true` | Only messages without the `\Seen` flag. |
| `delete` | `false` | Delete messages after processing. |
| `copyTo` | | Copy processed messages to this folder. |
| `moveTo` | | Move processed messages to this folder. |
| `maxMessagesPerPoll` / `fetchSize` | no limit | Messages per poll. |
| `mapMailMessage` | `true` | `true`: the body is the text content. `false`: the raw RFC 822 message. |
| `delay` | `60000` | Milliseconds between polls (`initialDelay` 1000 and the other scheduler options). |
| `connectionTimeout` | `30s` | Connect timeout. |
| `mail.imap.starttls.enable`, `mail.imap.starttls.required` | `false` | STARTTLS on `imap:`. |
| `sslContextParameters` | | `#bean` with trust material for TLS. |
| `useGlobalSslContextParameters` | `false` | Use the global `camel.ssl.*` parameters. |

`peek`, `closeFolder`, `disconnect`, `skipFailedMessage`, `searchTerm.*` and other `mail.*`
options are accepted and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `Subject`, `From`, `To`, `Cc`, `Date`, `Message-ID`, ... | out | Every mail header; repeated headers become a list. |

MIME parts other than the body are put in the `CamelAttachments` exchange property as bytes.

## Run it with Docker

```sh
docker run --rm --user "$(id -u):$(id -g)" -e IMAP_HOST=imap.example.com -e IMAP_USER -e IMAP_PASSWORD \
  -e INVOICE_DIR=/data/invoices -v "$PWD:/data" \
  -v "$PWD/mail-triage.camel.yaml:/routes/mail-triage.camel.yaml:ro" \
  pmsudhi/cameleer run /routes/mail-triage.camel.yaml
```

## Common questions

### How do I avoid processing the same mail twice?
Keep `unseen=true` (the default): read messages get the `\Seen` flag. `moveTo` or `delete=true`
also take them out of the folder.

### How do I read another folder?
`folderName=Support/Escalations`.

### How do I get the raw message with all parts?
`mapMailMessage=false` gives the raw RFC 822 text as the body.

### IMAP or POP3?
IMAP keeps mail on the server and supports folders, flags and moving; [pop3](https://pmsudhi.github.io/cameleer/docs/components/pop3.html) only
downloads and optionally deletes.

## Related

- [pop3](https://pmsudhi.github.io/cameleer/docs/components/pop3.html), [smtp](https://pmsudhi.github.io/cameleer/docs/components/smtp.html).
- Apache Camel: [Mail component](https://camel.apache.org/components/next/mail-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/jdbc.html

# JDBC component

> The `jdbc` component executes the SQL statement in the message body against a data source and returns the rows or the update count.

**Scheme:** `jdbc:` · **Crate:** `cameleer-sql` · **Cargo feature:** [`sql`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [JDBC](https://camel.apache.org/components/next/jdbc-component.html)

## When to use it

- The SQL is built at runtime: by a template, by a previous step, or by an AI agent that
  writes a read-only report query (validate it before you run it).
- Run admin statements or DDL from a route.
- Port a Camel route that already uses `jdbc:` without rewriting it to `sql:`.

For fixed statements with parameters, the [sql](https://pmsudhi.github.io/cameleer/docs/components/sql.html) component is usually simpler.

## URI format

```text
jdbc:<dataSourceName>[?options]
```

`dataSourceName` is the registry name of a data source. Cameleer binds one named `dataSource`
from the `camel.datasource.url` property (environment variable `CAMEL_DATASOURCE_URL`, plus
`camel.datasource.username` and `camel.datasource.password`), and more with
`camel.datasource.<name>.url`. Supported URLs are `jdbc:rustsql:mem:<name>` (the embedded
in-memory engine) and `jdbc:postgresql://host:port/db`.

With `useHeadersAsParameters=true`, `:?name` placeholders in the SQL are filled from the
`CamelJdbcParameters` header (a map, or a list for positional values) and then from the message
headers.

## Example

`GET /products?maxPrice=2` runs a parameterised query and returns the rows as JSON. The query
parameter becomes the `maxPrice` header, which fills `:?maxPrice`.

```yaml
- route:
    id: cheap-products
    from:
      uri: "platform-http:/products?httpMethodRestrict=GET"
      steps:
        - setBody:
            constant: "select name, price from products where price < :?maxPrice order by name"
        - to: "jdbc:dataSource?useHeadersAsParameters=true&outputType=SelectList"
        - marshal:
            json: {}
```

Run it with the data source set by a property:

```properties
camel.datasource.url={{env:DB_URL:jdbc:rustsql:mem:shop}}
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("direct:report")
        .set_body(constant("select count(*) as orders from orders"))
        .to("jdbc:dataSource?outputType=SelectOne");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `outputType` | `SelectList` | `SelectList` (list of row maps), `SelectOne` (one row map, or the value when there is one column) or `StreamList` (read fully into a list) |
| `useHeadersAsParameters` | `false` | fill `:?name` placeholders from `CamelJdbcParameters` and the headers |
| `allowNamedParameters` | `true` | recognise `:?name` placeholders |
| `readSize` | `0` | read at most this many rows (0 = all) |
| `statement.maxRows` | | same as `readSize` (the smaller wins) |
| `resetAutoCommit` | `true` | accepted; see below |
| `transacted` | `false` | accepted |
| `parameters.*` | | accepted, ignored |

`outputClass`, `beanRowMapper`, `useJDBC4ColumnNameAndLabelSemantics`, `useGetBytesForBlob`,
`prepareStatementStrategy` and `connectionStrategy` are accepted and ignored: rows are maps.

**Difference from Camel:** `resetAutoCommit=false` does not open a transaction. Outside a JDBC
transaction policy every statement commits on its own.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelJdbcParameters` | in | named (map) or positional (list) parameter values |
| `CamelRetrieveGeneratedKeys` | in | `true` to return the generated keys of an INSERT |
| `CamelJdbcRowCount` | out | rows returned by a SELECT |
| `CamelJdbcColumnNames` | out | column names of a SELECT |
| `CamelJdbcUpdateCount` | out | rows changed by other statements |
| `CamelGeneratedKeysRowCount` | out | number of generated key rows |
| `CamelGeneratedKeysRows` | out | the generated keys, a list of maps |

## Run it with Docker

```sh
docker run --rm -p 8080:8080 \
  -e CAMEL_DATASOURCE_URL='jdbc:postgresql://db.example.com:5432/shop' \
  -e CAMEL_DATASOURCE_USERNAME=camel -e CAMEL_DATASOURCE_PASSWORD \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/products.camel.yaml
```

## Common questions

### Where does the data source come from?

From the registry. Set `camel.datasource.url` (or `CAMEL_DATASOURCE_URL`) to bind `dataSource`,
or bind your own in Rust with `cameleer_sql::bind_datasource(ctx, "name", ds)`.

### How do I pass parameters safely?

Use `useHeadersAsParameters=true` and `:?name` placeholders. Values are sent as bind parameters,
never pasted into the SQL text.

### Is it safe to run SQL written by an LLM?

Only with a read-only database user and a check of the statement before it runs. The component
executes whatever the body contains.

## Related

- [sql](https://pmsudhi.github.io/cameleer/docs/components/sql.html): fixed statements with parameters, and table polling.
- [sql-stored](https://pmsudhi.github.io/cameleer/docs/components/sql-stored.html): stored procedures.
- [Apache Camel JDBC component](https://camel.apache.org/components/next/jdbc-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/jetty.html

# Jetty component

> The `jetty` component serves HTTP requests on an address given in the URI, for routes written for Apache Camel's camel-jetty.

**Scheme:** `jetty:` · **Crate:** `cameleer-http` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Jetty](https://camel.apache.org/components/next/jetty-component.html)

Cameleer has no Jetty: `jetty:` endpoints run on the same embedded HTTP/1.1 server as
[platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html), so routes that use `jetty:http://...` keep working
unchanged. The difference from `platform-http` is that the host and port are part of the URI.
[undertow](https://pmsudhi.github.io/cameleer/docs/components/undertow.html) and [netty-http](https://pmsudhi.github.io/cameleer/docs/components/netty-http.html) behave the same way.

## When to use it

- Run an existing Camel route that uses `jetty:` without changes.
- Listen on a specific interface and port per route, e.g. an admin endpoint on `127.0.0.1` only.
- Serve HTTPS on a given port with `jetty:https://`.

## URI format

```text
jetty:http://host:port/path[?options]
jetty:https://host:port/path[?options]
```

## Example

A status endpoint for an edge device, served on its own port and answering every path below
`/status` (`matchOnUriPrefix=true`).

```yaml
- route:
    id: device-status
    from:
      uri: "jetty:http://0.0.0.0:{{env:STATUS_PORT:8081}}/status?matchOnUriPrefix=true&httpMethodRestrict=GET"
      steps:
        - setHeader:
            name: Content-Type
            constant: application/json
        - setBody:
            simple: '{"device": "{{env:DEVICE_ID:gateway-1}}", "path": "${header.CamelHttpPath}", "status": "up"}'
```

## Rust DSL

```rust
fn device_status_route(b: &mut RouteBuilder, port: u16) {
    b.from(&format!("jetty:http://0.0.0.0:{}/status?matchOnUriPrefix=true&httpMethodRestrict=GET", port))
        .route_id("device-status")
        .set_header("Content-Type", constant("application/json"))
        .set_body(simple(r#"{"device": "gateway-1", "path": "${header.CamelHttpPath}", "status": "up"}"#));
}
```

## Options

The options are those of [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html#options): `httpMethodRestrict`,
`matchOnUriPrefix`, `consumes`, `produces`, `muteException`, `chunked`, `mapHttpMessageBody`,
`mapHttpMessageHeaders`, `mapHttpMessageFormUrlEncodedBody`, `disableStreamCache`,
`sslContextParameters`, `useGlobalSslContextParameters`, `needClientAuth` / `clientAuth`. The
host and port come from the URI (`port` and `host` options override them). Jetty-specific
options such as `handlers`, `sessionSupport` and `httpBinding` are accepted and ignored.

## Message headers

The same as [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html#message-headers): `CamelHttpMethod`,
`CamelHttpUri`, `CamelHttpPath`, `CamelHttpQuery`, `CamelHttpRawQuery`,
`CamelHttpRemoteAddress` on the way in, `CamelHttpResponseCode` and `Content-Type` on the way
out.

## Run it with Docker

```sh
docker run --rm -p 8081:8081 -e DEVICE_ID=gateway-7 -v "$PWD:/routes:ro" \
  pmsudhi/cameleer run /routes/device-status.camel.yaml
curl localhost:8081/status/disk
```

## Common questions

### Do I need to install Jetty?
No. The scheme is kept for compatibility with Apache Camel routes; the server is built into
Cameleer.

### Can two jetty routes share a port?
Yes. Routes on the same host and port share one listener and are told apart by path.

### How do I serve HTTPS?
Use `jetty:https://0.0.0.0:8443/path` with `sslContextParameters=#tls`, or set the
`camel.server.ssl.*` properties.

## Related

- [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html), [undertow](https://pmsudhi.github.io/cameleer/docs/components/undertow.html), [netty-http](https://pmsudhi.github.io/cameleer/docs/components/netty-http.html).
- [rest](https://pmsudhi.github.io/cameleer/docs/components/rest.html): `restConfiguration` with `component: jetty`.
- Apache Camel: [Jetty component](https://camel.apache.org/components/next/jetty-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/jira.html

# Jira component

> The `jira` component creates, updates, transitions, comments and searches Jira issues over the Jira REST API v2, and polls for new issues, new comments and field changes.

**Scheme:** `jira:` · **Crate:** `cameleer-saas` · **Cargo feature:** [`saas`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Jira](https://camel.apache.org/components/next/jira-component.html)

## When to use it

- Open a ticket automatically when monitoring, a failed job or an AI agent detects a problem.
- Forward new issues or comments to Slack, Teams or e-mail.
- React to status or priority changes (escalate when an issue becomes `Blocker`).
- Attach logs, add work logs, link related issues from an integration flow.

## URI format

```text
jira:type?jiraUrl=https://your-site.atlassian.net&username=...&password=...[&options]
```

Producer types: `addIssue`, `updateIssue`, `addComment`, `deleteIssue`, `fetchIssue`,
`fetchComments`, `searchIssues`, `transitionIssue`, `attach`, `watchers`, `addIssueLink`,
`addWorkLog`. Consumer types: `newIssues`, `newComments`, `watchUpdates`.

## Example

An agent that turns an incident into a ticket. The body becomes the issue description; project,
type and summary come from headers. After the call the body is the created issue (`id`, `key`,
`self`) and the `IssueKey` header holds its key.

```yaml
- route:
    id: incident-to-jira
    from:
      uri: "direct:incident"
      steps:
        - setHeader:
            name: ProjectKey
            constant: "OPS"
        - setHeader:
            name: IssueTypeName
            constant: "Bug"
        - setHeader:
            name: IssueSummary
            simple: "Incident on ${header.service}"
        - setHeader:
            name: IssuePriorityName
            constant: "High"
        - to: "jira:addIssue?jiraUrl={{env:JIRA_URL:https://your-site.atlassian.net}}&username={{env:JIRA_USER}}&password={{env:JIRA_API_TOKEN}}"
        - log: "created ${header.IssueKey}"
```

Announce every new issue of a project in Slack. The consumer's first poll records the issues
that already exist; after that each new issue is delivered once, with the `IssueKey` header.

```yaml
- route:
    id: new-issues-to-slack
    from:
      uri: "jira:newIssues?jiraUrl={{env:JIRA_URL:https://your-site.atlassian.net}}&username={{env:JIRA_USER}}&password={{env:JIRA_API_TOKEN}}&jql=project=OPS&delay=60000"
      steps:
        - setBody:
            simple: "New Jira issue ${header.IssueKey}: ${body[fields][summary]}"
        - to: "slack:#ops?webhookUrl={{env:SLACK_WEBHOOK_URL}}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("direct:incident")
        .set_header("ProjectKey", constant("OPS"))
        .set_header("IssueTypeName", constant("Bug"))
        .set_header("IssueSummary", simple("Incident on ${header.service}"))
        .to("jira:addIssue?jiraUrl={{env:JIRA_URL:https://your-site.atlassian.net}}&username={{env:JIRA_USER}}&password={{env:JIRA_API_TOKEN}}");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `jiraUrl` | | Base URL of the Jira site (required). |
| `username` | | User (e-mail on Jira Cloud) for Basic authentication. |
| `password` | | Password or API token for Basic authentication. |
| `accessToken` | | Personal access token (Bearer). Used instead of `username`/`password` when set. |
| `jql` | | JQL query: required by the consumers, optional for `searchIssues`. `ORDER BY key desc` is appended when the query has no `ORDER BY`. |
| `maxResults` | `50` | Maximum issues per search. |
| `watchedFields` | `Status,Priority` | `watchUpdates`: fields to watch (case-insensitive). |
| `sendOnlyUpdatedField` | `true` | `watchUpdates`: send only the new field value (`false` sends the whole issue). |
| `delay`, `initialDelay`, ... | `delay=6000` | Consumers: the standard scheduled-poll options. |

`consumerKey`, `privateKey` and `verificationCode` (OAuth 1.0a) are accepted for Camel
compatibility but not used: authenticate with an API token or a personal access token.

## Message headers

| header | direction | description |
|---|---|---|
| `ProjectKey` | in | `addIssue`: project key (required). |
| `IssueTypeName` / `IssueTypeId` | in | `addIssue` (one required), `updateIssue`. |
| `IssueSummary` | in | `addIssue` (required), `updateIssue`. |
| `IssueAssignee` / `IssueAssigneeId` | in | Assignee name or account id. |
| `IssuePriorityName` / `IssuePriorityId` | in | Priority. |
| `IssueComponents` | in | Comma-separated component names. |
| `IssueKey` | in / out | Target issue of most producers; set by `addIssue` and by the consumers. |
| `CamelJiraJql` | in | `searchIssues`: JQL (else the `jql` option, else the body). |
| `IssueTransitionId` | in | `transitionIssue`: transition id; a non-null body is added as a comment. |
| `IssueWatchersAdd` / `IssueWatchersRemove` | in | `watchers`: comma-separated text or a list of user names. |
| `ParentIssueKey`, `ChildIssueKey`, `linkType` | in | `addIssueLink`. |
| `minutesSpent` | in | `addWorkLog`; the body is the work log comment. |
| `CamelFileName` | in | `attach`: file name (default `attachment`); the body is the content. |
| `IssueChanged`, `IssueWatchedIssues` | out | `watchUpdates`: the changed field and the keys of the watched issues. |

## Run it with Docker

```sh
export JIRA_URL=https://your-site.atlassian.net JIRA_USER=bot@example.com JIRA_API_TOKEN=... SLACK_WEBHOOK_URL=...
docker run --rm -e JIRA_URL -e JIRA_USER -e JIRA_API_TOKEN -e SLACK_WEBHOOK_URL \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/new-issues-to-slack.camel.yaml
```

## Common questions

### How do I authenticate with Jira Cloud?

Use your account e-mail as `username` and an API token (from id.atlassian.com) as `password`.
For Jira Data Center, a personal access token in `accessToken` works too.

### How do I let an LLM write the ticket?

Call [openai](https://pmsudhi.github.io/cameleer/docs/components/openai.html) first with a system message such as "Write a one-line Jira summary",
store the answer in the `IssueSummary` header (`setHeader` with `${body}`), restore the original
text as the body, then call `jira:addIssue`. The [AI components guide](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html)
shows the pattern.

### How do I search issues?

`jira:searchIssues?jql=project=OPS AND status=Open` (or the JQL in the body or the
`CamelJiraJql` header); the body becomes the list of issues.

### Does it use Jira REST API v3?

No, v2 (`/rest/api/2`), which Jira Cloud and Data Center both still serve. Descriptions and
comments are plain text, not Atlassian Document Format.

## Related

- [github](https://pmsudhi.github.io/cameleer/docs/components/github.html), [slack](https://pmsudhi.github.io/cameleer/docs/components/slack.html), [openai](https://pmsudhi.github.io/cameleer/docs/components/openai.html)
- [Apache Camel Jira component](https://camel.apache.org/components/next/jira-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/jms.html

# JMS component

> The `jms` component sends and receives JMS-style messages (queues, topics, selectors, request/reply, transactions) through any broker that speaks STOMP 1.2, such as ActiveMQ, Artemis or RabbitMQ.

**Scheme:** `jms:` · **Also:** `activemq:`, `amqp-stomp:` (same component, see [activemq](https://pmsudhi.github.io/cameleer/docs/components/activemq.html), [amqp-stomp](https://pmsudhi.github.io/cameleer/docs/components/amqp-stomp.html)) · **Crate:** `cameleer-amqp` · **Cargo feature:** [`amqp`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [JMS](https://camel.apache.org/components/next/jms-component.html)

## When to use it

- Move Camel routes that use `jms:queue:...` to Cameleer without a JVM or a JMS client library.
- Request/reply over a queue: a service answers on a temporary reply queue, as with JMS `replyTo`.
- Competing consumers on a queue, publish-subscribe on a topic, durable and shared subscriptions.
- Expose an AI model or agent as a queue-based service that other systems call with request/reply.

Difference from Apache Camel: there is no JMS API in Rust, so Cameleer speaks STOMP 1.2 to the broker
and maps JMS semantics onto it. Use [amqp](https://pmsudhi.github.io/cameleer/docs/components/amqp.html) for JMS over AMQP 1.0. XA transactions are not
possible over STOMP (`transactionManager` is accepted and ignored); `transacted=true` gives local
transactions.

## URI format

```text
jms:[queue:|topic:|temp-queue:|temp-topic:]destinationName[?options]
```

Without a prefix the destination is a queue.

## Example

```yaml
- route:
    id: price-service
    from:
      uri: jms:queue:prices
      parameters:
        brokerURL: "{{env:JMS_BROKER_URL:tcp://localhost:61613}}"
        username: "{{env:JMS_USER:admin}}"
        password: "{{env:JMS_PASSWORD:admin}}"
        concurrentConsumers: 2
      steps:
        - setBody:
            simple: "price of ${body}: 42.00 EUR"
```

A caller that sends `ACME` as an InOut message to `jms:queue:prices` gets `price of ACME: 42.00 EUR`
back through a temporary reply queue.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("jms:queue:prices?brokerURL=tcp://localhost:61613&concurrentConsumers=2")
            .route_id("price-service")
            .set_body(simple("price of ${body}: 42.00 EUR"));
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `brokerURL` (alias `brokerUrl`) | `tcp://localhost:61613` | Broker STOMP address: `tcp://`, `stomp://`, `amqp://` or `failover:(...)` (first address used). `ssl://`, `stomp+ssl://` or `stomps://` use TLS. Also `camel.component.jms.brokerUrl`. |
| `username`, `password` | | Credentials (also `camel.component.jms.username` / `password`). |
| `host` | | STOMP virtual host. |
| `clientId` | | Client id, needed for durable subscriptions. |
| `concurrentConsumers` | `1` | Consumers on a queue (one STOMP subscription each). |
| `prefetchSize` | `1` | Unacknowledged messages per consumer. |
| `selector` | | JMS selector, evaluated by the broker, for example `region = 'EU' AND priority > 5`. |
| `acknowledgementModeName` (or `acknowledgementMode` 0-3) | `AUTO_ACKNOWLEDGE` | `AUTO_ACKNOWLEDGE`, `DUPS_OK_ACKNOWLEDGE`, `CLIENT_ACKNOWLEDGE` (failed messages are redelivered) or `SESSION_TRANSACTED`. |
| `transacted` | `false` | Process each message in a STOMP transaction; a failure aborts it and the broker redelivers. |
| `replyTo` | | Fixed reply queue instead of a temporary one. |
| `replyToType` | `Temporary` (`Shared` with `replyTo`) | `Temporary`, `Shared` or `Exclusive`. |
| `requestTimeout` | `20000` | InOut producer: wait (ms) for the reply. |
| `disableReplyTo` | `false` | Do not handle reply-to. |
| `useMessageIDAsCorrelationID` | `false` | Reply with the request's `JMSMessageID` as correlation id. |
| `deliveryPersistent` | `true` | Persistent sends (wait for a broker receipt). |
| `deliveryMode` | | `1` (non-persistent) or `2` (persistent). |
| `priority` | broker default | Message priority, 0 to 9. |
| `timeToLive` | `-1` | Message expiry in ms. `-1` never expires. |
| `explicitQosEnabled` | | Accepted; QoS options always apply. |
| `preserveMessageQos` | `false` | Take priority, delivery mode and expiry from the `JMSPriority`, `JMSDeliveryMode`, `JMSExpiration` headers. |
| `jmsMessageType` | from the body | `Text`, `Bytes`, `Map` or `Object` (map and object bodies travel as JSON). |
| `durableSubscriptionName` | | Durable topic subscription name. |
| `subscriptionName`, `subscriptionDurable`, `subscriptionShared` | | JMS 2.0 durable and shared subscriptions. |
| `recoveryInterval` | `5000` | ms between reconnect attempts. |
| `sslContextParameters`, `useGlobalSslContextParameters` | | TLS trust settings. |

## Message headers

| header | direction | description |
|---|---|---|
| `JMSMessageID`, `JMSCorrelationID`, `JMSDestination`, `JMSReplyTo`, `JMSDeliveryMode`, `JMSPriority`, `JMSTimestamp`, `JMSType`, `JMSRedelivered`, `JMSExpiration` | out (consumer), some in (producer) | JMS message headers. |
| `CamelJmsDestinationName` | in | Producer: send to this destination instead. |
| `CamelJmsRequestTimeout` | in | Producer: reply timeout for this message. |

Other headers travel as message properties (keys encoded with Camel's `_DOT_` / `_HYPHEN_` strategy).

## Run it with Docker

```sh
docker run --rm -e JMS_BROKER_URL=tcp://activemq:61613 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/prices.camel.yaml
```

The broker must have its STOMP connector enabled (port 61613 by default on ActiveMQ and Artemis; the
`rabbitmq_stomp` plugin on RabbitMQ).

## Common questions

### How do I call a JMS service and wait for the answer?

Send an InOut exchange: add a `setExchangePattern: InOut` step before `to: jms:queue:prices`, or call
`request_body` on a producer template. The reply body replaces the message.

### How do I keep topic messages while my route is stopped?

Set `clientId` and `durableSubscriptionName` (or `subscriptionName` with `subscriptionDurable=true`).
A durable subscription that is not shared requires `clientId`.

### Does Cameleer support XA transactions with JMS?

No. STOMP has no two-phase commit. Use `transacted=true` for local transactions and an idempotent consumer
for exactly-once processing.

## Related

- [activemq](https://pmsudhi.github.io/cameleer/docs/components/activemq.html), [amqp-stomp](https://pmsudhi.github.io/cameleer/docs/components/amqp-stomp.html), [stomp](https://pmsudhi.github.io/cameleer/docs/components/stomp.html), [amqp](https://pmsudhi.github.io/cameleer/docs/components/amqp.html)
- [Apache Camel JMS component](https://camel.apache.org/components/next/jms-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/json-validator.html

# JSON Schema validator component

> The `json-validator` component checks the message body (or a header) against a JSON Schema and fails the exchange with a `JsonValidationException` listing every error when it does not conform.

**Scheme:** `json-validator:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [JSON Schema Validator](https://camel.apache.org/components/next/json-validator-component.html)

## When to use it

- Check an LLM's JSON answer against a schema before acting on it: a tool call, a
  classification, an extraction. Ask the model again or route to a human when it fails.
- Validate incoming REST payloads before they reach a database or a queue.
- Enforce a contract between services that exchange JSON events.

## URI format

```text
json-validator:schemaResource[?options]
```

`schemaResource` is a file path relative to the working directory, `file:path`,
`classpath:path` (read as a relative path) or `ref:beanName` (a `String` in the registry).

## Example

A model was asked to triage a ticket and answer with JSON. The route checks the answer before
any action is taken and reports the schema errors otherwise (for a retry prompt, for example).

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["priority", "team", "summary"],
  "additionalProperties": false,
  "properties": {
    "priority": {"enum": ["P1", "P2", "P3"]},
    "team": {"type": "string", "minLength": 2},
    "summary": {"type": "string", "maxLength": 120},
    "confidence": {"type": "number", "minimum": 0, "maximum": 1}
  }
}
```

```yaml
- route:
    id: json-validator-llm-answer
    from:
      uri: direct:check-llm-answer
      steps:
        - doTry:
            steps:
              - to: json-validator:schemas/triage-answer.json
              - setBody:
                  simple: "accepted: ${body}"
            doCatch:
              - exception:
                  - org.apache.camel.ValidationException
                steps:
                  - setBody:
                      simple: "rejected: ${exception.message}"
```

A well-formed answer passes unchanged:

```json
{"priority":"P1","team":"payments","summary":"Checkout fails for EU cards","confidence":0.92}
```

```text
accepted: {"priority":"P1","team":"payments","summary":"Checkout fails for EU cards","confidence":0.92}
```

An answer with an invented priority, a missing field and an extra key is rejected with every
error:

```json
{"priority":"urgent","team":"payments","reason":"card declined"}
```

```text
rejected: JSON validation error with 3 errors:
$.priority
$.summary
$.reason
```

## Rust DSL

```rust
b.from("direct:json-validator-rust")
    .to("json-validator:schemas/triage-answer.json")
    .set_body(constant("ok"));
```

## Options

| option | default | description |
|---|---|---|
| `failOnNullBody` | `true` | Fail with `NoJsonBodyValidationException` when the body is null. |
| `failOnNullHeader` | `true` | Fail with `NoJsonHeaderValidationException` when `headerName` is set and the header is missing. |
| `headerName` | (none) | Validate this header instead of the body. |
| `contentCache` | `false` | Load the schema once instead of for every message. |

Accepted and ignored (Java-only settings): `allowContextMapAll`, `allowTemplateFromHeader`,
`errorHandler`, `schemaLoader`, `uriSchemaLoader`, `objectMapper`,
`disabledDeserializationFeatures`, `enabledDeserializationFeatures`, `lazyStartProducer`.

A string or bytes body is parsed as JSON (invalid JSON is itself a validation error); an object
body, for example after `unmarshal: json`, is validated directly.

### Supported JSON Schema

Drafts 04 to 07 and a 2019-09 subset: boolean schemas, `type` (also lists), `enum`, `const`,
`minimum` / `maximum`, `exclusiveMinimum` / `exclusiveMaximum`, `multipleOf`,
`minLength` / `maxLength`, `pattern`, `format` (`date-time`, `date`, `time`, `email`, `ipv4`,
`uuid`, `hostname`, `uri`; other formats are ignored), `items` / `additionalItems`,
`minItems` / `maxItems`, `uniqueItems`, `contains`, `properties`, `required`,
`additionalProperties`, `patternProperties`, `propertyNames`, `minProperties` /
`maxProperties`, `dependencies` / `dependentRequired`, `allOf` / `anyOf` / `oneOf` / `not`,
`if` / `then` / `else`, and `$ref` to local pointers (`#/definitions/x`, `#/$defs/x`).
**Remote `$ref`s are not supported.**

## Message headers

| header / property | direction | description |
|---|---|---|
| `CamelJsonValidationErrors` (exchange property) | out | The list of error messages, set when validation fails. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/check-answer.camel.yaml
```

## Common questions

### How do I check that an LLM returned valid JSON in the shape I asked for?

Send the model's answer to `json-validator:schema.json`. Invalid JSON and schema violations
both fail with `JsonValidationException`, which you can catch to retry or escalate.

### How do I read the individual errors?

The exception message lists them, one per line (`$.field: ...`), and the
`CamelJsonValidationErrors` exchange property holds them as a list, handy for building a
correction prompt.

### Can my schema reference another file?

No, only local `$ref`s (`#/definitions/...`, `#/$defs/...`) are resolved. Inline the shared
definitions in one schema file.

## Related

- [validator](https://pmsudhi.github.io/cameleer/docs/components/validator.html) for XML Schema.
- [JSONPath language](https://pmsudhi.github.io/cameleer/docs/languages/jsonpath.html) and [jq language](https://pmsudhi.github.io/cameleer/docs/languages/jq.html) for
  reading fields after validation.
- [Apache Camel JSON Schema Validator component](https://camel.apache.org/components/next/json-validator-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/kafka.html

# Kafka component

> The `kafka` component sends messages to and consumes messages from Apache Kafka topics, with consumer groups, keys, partitions, TLS and SASL.

**Scheme:** `kafka:` · **Crate:** `cameleer-kafka-mqtt` · **Cargo feature:** [`kafka-mqtt`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Kafka](https://camel.apache.org/components/next/kafka-component.html)

## When to use it

- Consume events from a topic and process them (billing, enrichment, indexing) with a consumer group.
- Publish events from an API, a database poll or an MQTT bridge to a topic.
- Use Kafka as an AI agent's event bus: agents publish their actions and observations keyed by agent id,
  and other routes or agents react to them.
- Store and forward from the edge: buffer readings locally and push them to a central Kafka cluster.

The Kafka wire protocol client is built into Cameleer (no librdkafka, no JVM). It works with Apache
Kafka, Redpanda and Kafka-compatible cloud services.

## URI format

```text
kafka:topic[?options]
```

## Example

```yaml
- route:
    id: orders-consumer
    from:
      uri: kafka:orders
      parameters:
        brokers: "{{env:KAFKA_BROKERS:localhost:9092}}"
        groupId: billing
        autoOffsetReset: earliest
      steps:
        - log: "partition ${header[kafka.PARTITION]} offset ${header[kafka.OFFSET]}: ${body}"
        - to: log:orders
```

The route joins the consumer group `billing`, starts at the oldest record when the group has no committed
offset, and commits offsets automatically.

### Agent event bus

```yaml
- route:
    id: publish-agent-event
    from:
      uri: direct:agent-event
      steps:
        - setHeader:
            name: kafka.KEY
            simple: "${header.agentId}"
        - to: kafka:agent-events?brokers={{env:KAFKA_BROKERS:localhost:9092}}
```

Events of one agent share a key, so they land on the same partition and stay in order.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("kafka:orders?brokers=localhost:9092&groupId=billing&autoOffsetReset=earliest")
            .route_id("orders-consumer")
            .log("partition ${header[kafka.PARTITION]} offset ${header[kafka.OFFSET]}: ${body}")
            .to("log:orders");
        b.from("direct:agent-event")
            .route_id("publish-agent-event")
            .set_header("kafka.KEY", simple("${header.agentId}"))
            .to("kafka:agent-events?brokers=localhost:9092");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `brokers` | `localhost:9092` | Bootstrap servers, comma separated. |
| `clientId` | generated | Client id sent to the brokers. |
| `groupId` | | Consumer group. Without it, each consumer thread reads all partitions and commits nothing. |
| `consumersCount` | `1` | Consumer threads (group members). |
| `autoOffsetReset` | `latest` | Where to start without a committed offset: `earliest`, `latest` or `none`. |
| `seekTo` | | `beginning` or `end`: seek on start, ignoring committed offsets. |
| `maxPollRecords` | `500` | Maximum records per poll. |
| `autoCommitEnable` | `true` | Commit offsets automatically. |
| `autoCommitIntervalMs` | `5000` | Auto-commit interval. |
| `autoCommitOnStop` | `sync` | Commit on stop: `sync`, `async` or `none`. |
| `allowManualCommit` | `false` | Put a manual committer in the `CamelKafkaManualCommit` header. |
| `breakOnFirstError` | `false` | Stop the batch at the first failed record and retry from it. |
| `topicIsPattern` | `false` | The topic is a regular expression. |
| `pollTimeoutMs` | `5000` | Poll timeout. |
| `fetchWaitMaxMs` | `500` | Broker wait for data. |
| `fetchMaxBytes`, `maxPartitionFetchBytes` | | Fetch size limits. |
| `heartbeatIntervalMs` | `3000` | Group heartbeat interval. |
| `sessionTimeoutMs` | `45000` | Group session timeout. |
| `maxPollIntervalMs` | `300000` | Maximum time between polls. |
| `requestTimeoutMs` | `30000` | Request timeout. |
| `keyDeserializer`, `valueDeserializer` | string | A `ByteArrayDeserializer` (or `BytesDeserializer`) gives byte bodies. |
| `key` | | Producer: record key. |
| `partitionKey` | | Producer: target partition. |
| `requestRequiredAcks` | `all` | Producer acks: `all` / `-1`, `1` or `0`. |
| `compressionCodec` | `none` | Producer batch compression: `none`, `gzip`, `snappy`, `lz4` (`zstd` is not supported). |
| `recordMetadata` | `true` | Producer: set `kafka.RECORD_META` after the send. |
| `securityProtocol` | `PLAINTEXT` | `PLAINTEXT`, `SSL`, `SASL_PLAINTEXT` or `SASL_SSL`. |
| `saslMechanism` | `PLAIN` | `PLAIN`, `SCRAM-SHA-256` or `SCRAM-SHA-512` (and `AWS_MSK_IAM` with `cameleer-cloud`). |
| `saslJaasConfig` | | Credentials: `... required username="u" password="p";`. |
| `sslTruststoreLocation` | | PEM file with trusted CA certificates (Java keystores are not supported). |
| `sslEndpointIdentificationAlgorithm` | `https` | Empty value disables host name verification. |
| `sslProtocol` | | Restrict the TLS version. |
| `sslContextParameters`, `useGlobalSslContextParameters` | | TLS settings from a bean or the global `camel.ssl.*` parameters. |

GSSAPI (Kerberos), OAUTHBEARER and client certificates (`sslKeystoreLocation`) are not supported. Other
Camel Kafka tuning options are accepted and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `kafka.KEY` | in (producer), out (consumer) | Record key. |
| `kafka.PARTITION_KEY` | in | Producer: target partition. |
| `kafka.OVERRIDE_TOPIC` | in | Producer: send to this topic instead (the header is removed). |
| `kafka.OVERRIDE_TIMESTAMP` | in | Producer: record timestamp (epoch ms). |
| `kafka.TOPIC`, `kafka.PARTITION`, `kafka.OFFSET`, `kafka.TIMESTAMP` | out | Where the record came from (consumer) or went (producer: partition and offset). |
| `kafka.LAST_POLL_RECORD`, `kafka.LAST_RECORD_BEFORE_COMMIT` | out | Consumer: last record of the poll / before the commit. |
| `kafka.RECORD_META` | out | Producer: list of `{topic, partition, offset, timestamp}`. |
| `CamelKafkaManualCommit` | out | Consumer with `allowManualCommit=true`: commits the record's offset. |

Other headers become Kafka record headers (strings as UTF-8, integers as 8-byte longs), except `Camel*`,
`org.apache.camel*` and `kafka.*`. Received record headers become message headers (as bytes).

## Run it with Docker

```sh
docker run --rm -e KAFKA_BROKERS=broker:9092 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

Use `--network host` or the broker's network name so the container can reach Kafka.

## Common questions

### How do I read a topic from the beginning?

Set `autoOffsetReset=earliest` with a new `groupId`, or `seekTo=beginning` to ignore committed offsets.

### How do I send one record per list element?

Send a list body: an array body sends one record per element.

### How do I connect to Confluent Cloud or another SASL_SSL cluster?

`securityProtocol=SASL_SSL&saslMechanism=PLAIN&saslJaasConfig=RAW(org.apache.kafka.common.security.plain.PlainLoginModule required username="{{env:KAFKA_KEY}}" password="{{env:KAFKA_SECRET}}";)`.

### How do I commit offsets only after my processing succeeded?

Set `autoCommitEnable=false&allowManualCommit=true` and call the committer in `CamelKafkaManualCommit`
from a processor, or keep auto-commit with `breakOnFirstError=true`.

## Related

- [paho](https://pmsudhi.github.io/cameleer/docs/components/paho.html) (MQTT to Kafka bridge), [seda](https://pmsudhi.github.io/cameleer/docs/components/seda.html), [amqp](https://pmsudhi.github.io/cameleer/docs/components/amqp.html)
- [Apache Camel Kafka component](https://camel.apache.org/components/next/kafka-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/kamelet.html

# Kamelet component

> The `kamelet` component uses Kamelets, reusable route snippets with typed parameters, as sources, actions and sinks in a route.

**Scheme:** `kamelet:` · **Crate:** `cameleer-yaml` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Kamelet](https://camel.apache.org/components/next/kamelet-component.html)

## When to use it

- Reuse a connector configured once (a "source" or "sink") in many routes with different parameters.
- Hide connection details from route authors: they only set the documented Kamelet properties.
- Run Kamelet Pipes (`kind: Pipe` / `KameletBinding`) from Kubernetes manifests outside Kubernetes.

Built-in Kamelets, mirroring the Apache Camel catalog: `timer-source`, `log-sink`, `log-action`,
`insert-header-action`, `set-body-action`. Add your own by loading `kind: Kamelet` YAML files.

## URI format

```text
kamelet:name[/routeId][?properties]
```

- `from: kamelet:name` uses a source Kamelet; its `kamelet:sink` feeds your route.
- `to: kamelet:name` uses an action or sink Kamelet; the exchange returns to your route afterwards.

## Example

```yaml
- route:
    id: greetings
    from:
      uri: kamelet:timer-source
      parameters:
        message: hello from the edge
        period: 10000
      steps:
        - to:
            uri: kamelet:insert-header-action
            parameters:
              name: site
              value: edge-1
        - to: log:greetings
```

Every 10 seconds the route receives `hello from the edge` with the header `site: edge-1`.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    cameleer_yaml::kamelet::register_kamelet_component(ctx);
    ctx.add_routes(|b| {
        b.from("kamelet:timer-source?message=hello from the edge&period=10000")
            .route_id("greetings")
            .to("kamelet:insert-header-action?name=site&value=edge-1")
            .to("log:greetings");
    })
}
```

## Options

The URI options are the properties of the Kamelet. For the built-ins:

| Kamelet | properties |
|---|---|
| `timer-source` | `message` (required), `period` (`1000`), `contentType` (`text/plain`), `repeatCount` |
| `log-sink` | `loggerName` (`log-sink`), `level` (`INFO`), `logMask`, `multiline`, `showAllProperties`, `showBody`, `showBodyType`, `showExchangePattern`, `showHeaders`, `showProperties`, `showStreams`, `showCachedStreams`, `marker` |
| `insert-header-action` | `name`, `value` |
| `set-body-action` | `value` |
| `log-action` | like `log-sink` |

Property values are resolved from, in order: the URI options, the application properties
`camel.kamelet.<name>.<routeId>.<property>` and `camel.kamelet.<name>.<property>`, then the declared
`default`. A missing required property fails endpoint creation. `kamelet:name/myRoute` sets the id of
the generated route (default `name-N`).

## Message headers

Whatever the Kamelet sets. `timer-source` sets `Content-Type`; `insert-header-action` sets the header
you name.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/greetings.camel.yaml
```

Put your own `kind: Kamelet` files in the same directory and pass them to `run` as well.

## Common questions

### How do I write my own Kamelet?

Write a YAML document with `apiVersion: camel.apache.org/v1`, `kind: Kamelet`, `metadata.name`,
`spec.definition.properties` and a `spec.template` route that ends in `kamelet:sink` (sources) or starts
at `kamelet:source` (sinks and actions). Load it with your routes.

### Can Cameleer run a Kamelet Pipe?

Yes. `kind: Pipe` and the older `kind: KameletBinding` become a route named after `metadata.name`.
Strimzi `KafkaTopic` refs become `kafka:` endpoints and Knative `Channel`/`Broker` refs become `vm:`.

### What does `{{?property}}` mean in a Kamelet template?

It is an optional property: when it has no value, the option that uses it is removed.

## Related

- [timer](https://pmsudhi.github.io/cameleer/docs/components/timer.html), [log](https://pmsudhi.github.io/cameleer/docs/components/log.html), [vm](https://pmsudhi.github.io/cameleer/docs/components/vm.html), [kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html)
- [Apache Camel Kamelet component](https://camel.apache.org/components/next/kamelet-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/language.html

# Language component

> The `language` component evaluates a script in any supported language (Simple, JSONPath, XPath, jq, ...) and uses the result as the new message body.

**Scheme:** `language:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Language](https://camel.apache.org/components/next/language-component.html)

## When to use it

- Build a reply or a prompt from a template script, for example a prompt for an LLM from message fields.
- Run a script stored in a file (`script=resource:file:/scripts/reply.txt`), so it can change without editing the route.
- Evaluate a script that arrives with the message (header `CamelLanguageScript` or the body).

## URI format

```text
language:languageName[:script][?options]
```

## Example

```yaml
- route:
    id: build-prompt
    from:
      uri: direct:prompt
      steps:
        - to: "language:simple:Summarize this support ticket in one sentence: ${body}"
```

Sending `Printer on floor 3 is jammed` returns
`Summarize this support ticket in one sentence: Printer on floor 3 is jammed`.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:prompt")
            .route_id("build-prompt")
            .to("language:simple:Summarize this support ticket in one sentence: ${body}");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `script` | | The script, instead of the URI path. Prefix `resource:file:` (or `file:`) to load it from a file. `classpath:` is not supported. |
| `transform` | `true` | Replace the body with the result. With `false` the message is left unchanged. |
| `resultType` | | Convert the result to this type. |
| `contentCache`, `cacheScript`, `binary`, `allowContextMapAll`, `allowTemplateFromHeader`, `lazyStartProducer` | | Accepted and ignored. |

Without a script in the URI or `script`, the script comes from the `CamelLanguageScript` header, or else
from the message body.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelLanguageScript` | in | The script to evaluate when the endpoint has none. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/prompt.camel.yaml
```

## Common questions

### Which languages can I use?

Any language registered in the context, for example `simple`, `constant`, `header`, `jsonpath`, `jq`,
`xpath` and the script languages of `cameleer-script`.

### How do I keep the body and only run the script for its side effects?

Add `transform=false`.

## Related

- [controlbus](https://pmsudhi.github.io/cameleer/docs/components/controlbus.html) (`controlbus:language:...`), [dataformat](https://pmsudhi.github.io/cameleer/docs/components/dataformat.html)
- [Apache Camel Language component](https://camel.apache.org/components/next/language-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/log.html

# Log component

> The `log` component writes each message that reaches it to the log, with control over the level and which parts (body, headers, properties) are shown.

**Scheme:** `log:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Log](https://camel.apache.org/components/next/log-component.html)

## When to use it

- See what flows through a route while developing or debugging.
- Keep an audit trail of the messages an AI agent route sends and receives (`showHeaders=true`).
- Log throughput instead of every message on busy routes (`groupSize` or `groupInterval`).

For a free-text log line inside a route, the `log` EIP step (`- log: "..."`) is shorter.

## URI format

```text
log:loggerName[?options]
```

## Example

```yaml
- route:
    id: debug-orders
    from:
      uri: direct:orders
      steps:
        - to:
            uri: log:orders
            parameters:
              level: DEBUG
              showHeaders: true
              showBodyType: false
              maxChars: 500
        - setBody:
            simple: "logged ${body}"
```

Each message produces a line such as
`Exchange[ExchangePattern: InOut, Headers: {region=EU}, Body: order-1]` on the `orders` logger at DEBUG.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:orders")
            .route_id("debug-orders")
            .to("log:orders?level=DEBUG&showHeaders=true&showBodyType=false&maxChars=500")
            .set_body(simple("logged ${body}"));
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `level` | `INFO` | `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` or `OFF`. |
| `showAll` | `false` | Show everything below. |
| `showExchangeId` | `false` | Show the exchange id. |
| `showExchangePattern` | `true` | Show `InOnly` / `InOut`. |
| `showProperties` | `false` | Show exchange properties. |
| `showHeaders` | `false` | Show message headers. |
| `showBody` | `true` | Show the body. |
| `showBodyType` | `true` | Show the body type, as the Java class name Camel would show (`java.lang.String`, ...). |
| `showException` | `true` | Show the exception of a failed exchange. |
| `showRouteId` | `false` | Show the route id. |
| `multiline` | `false` | One line per part instead of one line in total. |
| `maxChars` | `10000` | Cut the body after this many characters. |
| `skipBodyLineSeparator` | `true` | Replace line breaks in the body with spaces. |
| `groupSize` | | Log one throughput line every N messages instead of each message. |
| `groupInterval` | | Log one throughput line per interval (ms or a duration). |
| `logMask` | `false` | Mask values of sensitive keys such as `password` or `secret`. |
| `groupDelay`, `groupActiveOnly`, `showCaughtException`, `showStackTrace`, `showFiles`, `showFuture`, `showStreams`, `showCachedStreams`, `showAllProperties`, `showVariables`, `plain`, `style`, `marker`, `sourceLocationLoggerName`, `showRouteGroup` | | Accepted and ignored. |

## Message headers

The log component reads the message but does not change it.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

Log lines go to standard output, so `docker logs` shows them.

## Common questions

### How do I log only throughput on a busy route?

Use `log:throughput?groupSize=1000` to get one line per 1000 messages with the rate, or
`groupInterval=10000` for one line every 10 seconds.

### How do I hide passwords in the log?

Add `logMask=true`. Values of keys that look like secrets are replaced with `xxxxxx`.

### What is the difference between `to: log:x` and `- log: "..."`?

`to: log:x` prints a formatted view of the whole exchange. The `log` step prints the message you write,
with Simple expressions such as `${body}`.

## Related

- [mock](https://pmsudhi.github.io/cameleer/docs/components/mock.html), [browse](https://pmsudhi.github.io/cameleer/docs/components/browse.html)
- [Apache Camel Log component](https://camel.apache.org/components/next/log-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/mllp.html

# MLLP component

> The `mllp` component sends and receives HL7 v2 healthcare messages over TCP with MLLP framing, and generates HL7 acknowledgements automatically.

**Scheme:** `mllp:` · **Crate:** `cameleer-protocols` · **Cargo feature:** [`protocols`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [MLLP](https://camel.apache.org/components/next/mllp-component.html)

## When to use it

- Build an HL7 interface engine: receive ADT, ORM or ORU messages from a hospital system and forward them.
- Run a small HL7 gateway next to lab devices or in a clinic (edge), forwarding messages to Kafka or HTTP.
- Send HL7 messages to a remote system and check its acknowledgement (`AA`, `AE`, `AR`).

## URI format

```text
mllp://host:port[?options]
```

A consumer listens on `host:port` (`0.0.0.0` for all interfaces); a producer connects to it.

## Example

```yaml
- route:
    id: hl7-inbound
    from:
      uri: mllp://0.0.0.0:{{env:MLLP_PORT:2575}}
      steps:
        - log: "HL7 ${header.CamelMllpMessageType} from ${header.CamelMllpSendingApplication}, control id ${header.CamelMllpMessageControlId}"
        - to: log:hl7
```

Each message is answered with `MSA|AA|<control id>` when the route succeeds and `MSA|AE|...` when it
fails. Send a test message with another route: `to: mllp://localhost:2575`.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("mllp://0.0.0.0:2575")
            .route_id("hl7-inbound")
            .log("HL7 ${header.CamelMllpMessageType} from ${header.CamelMllpSendingApplication}, control id ${header.CamelMllpMessageControlId}")
            .to("log:hl7");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `autoAck` | `true` | Consumer: generate the HL7 acknowledgement. |
| `hl7Headers` | `true` | Consumer: set the `CamelMllp*` headers from the `MSH` segment. |
| `stringPayload` | `true` | Body as a string; `false` gives bytes. |
| `validatePayload` | `false` | Check the HL7 structure of received messages. |
| `charsetName` | `UTF-8` | `UTF-8` or `ISO-8859-1`. |
| `receiveTimeout` | `15000` | Producer: how long (ms) to wait for the acknowledgement. |
| `readTimeout` | `5000` | How long (ms) to wait for the rest of a started frame. |
| `connectTimeout` | `30000` | Producer: connect timeout (ms). |
| `idleTimeout` | `0` | Consumer: close idle connections after this many ms. `0` never closes. |
| `keepAlive` | `true` | TCP keep-alive. |
| `tcpNoDelay` | `true` | Disable Nagle's algorithm. |
| `maxBufferSize` | 1 GiB | Largest accepted frame. |
| `sslContextParameters` | | `#bean`: the consumer accepts TLS (needs key material) and the producer connects with TLS. |
| `useGlobalSslContextParameters` | `false` | Use the global `camel.ssl.*` parameters for TLS. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelMllpSendingApplication`, `CamelMllpSendingFacility`, `CamelMllpReceivingApplication`, `CamelMllpReceivingFacility` | out (consumer) | From `MSH-3` to `MSH-6`. |
| `CamelMllpTimestamp`, `CamelMllpSecurity`, `CamelMllpMessageType`, `CamelMllpEventType`, `CamelMllpTriggerEvent`, `CamelMllpMessageControlId`, `CamelMllpProcessingId`, `CamelMllpVersionId` | out (consumer) | From the other `MSH` fields. |
| `CamelMllpCharset` | out (consumer) | The character set. |
| `CamelMllpLocalAddress`, `CamelMllpRemoteAddress` | out | Socket addresses. |
| `CamelMllpAcknowledgement` / `CamelMllpAcknowledgementString` | in (consumer), out (producer) | The acknowledgement as bytes / string. A route can set it to send its own. |
| `CamelMllpAcknowledgementType` | in (consumer), out (producer) | `AA`, `AE`, `AR` (or `CA`, `CE`, `CR`). A route can set it to force the code. |

A producer that receives `AE` / `AR` fails with `MllpApplicationErrorAcknowledgementException` /
`MllpApplicationRejectAcknowledgementException`; no acknowledgement gives
`MllpAcknowledgementTimeoutException`.

## Run it with Docker

```sh
docker run --rm -p 2575:2575 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/hl7.camel.yaml
```

## Common questions

### How do I send my own acknowledgement?

Set the header `CamelMllpAcknowledgementString` (or `CamelMllpAcknowledgement` as bytes) in the route.
To only change the code, set `CamelMllpAcknowledgementType` to `AE` or `AR`.

### How do I read HL7 fields?

Use the `hl7terser` language with a terser path, for example a `setHeader` step whose expression is
`hl7terser: PID-5-1` (the patient's family name). The `hl7` data format parses the whole message.

### Is the connection kept open?

Yes. The producer reuses its connection between messages.

## Related

- [netty](https://pmsudhi.github.io/cameleer/docs/components/netty.html), [syslog](https://pmsudhi.github.io/cameleer/docs/components/syslog.html), [kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html)
- [Apache Camel MLLP component](https://camel.apache.org/components/next/mllp-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/mock.html

# Mock component

> The `mock` component records the messages a route sends to it and checks them against expectations, so you can test routes without real systems.

**Scheme:** `mock:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Mock](https://camel.apache.org/components/next/mock-component.html)

## When to use it

- Unit-test routing logic: send test messages in, assert what reached each `mock:` endpoint.
- Replace a real endpoint during a test (see the [stub](https://pmsudhi.github.io/cameleer/docs/components/stub.html) component for a queue instead).
- Check counts, bodies, order, headers and properties, with a wait time for asynchronous routes.

## URI format

```text
mock:name[?options]
```

All endpoints with the same `name` share one recorder in a context.

## Example

```yaml
- route:
    id: route-temperatures
    from:
      uri: direct:temperature
      steps:
        - choice:
            when:
              - simple: "${body} > 80"
                steps:
                  - to: mock:alerts
            otherwise:
              steps:
                - to: mock:normal
```

A test sends `85` and `20` to `direct:temperature` and expects one message at `mock:alerts` and one at
`mock:normal`:

```rust
let alerts = ctx.mock_endpoint("mock:alerts")?;
alerts.expected_message_count(1);
let template = ctx.create_producer_template();
template.send_body("direct:temperature", 85)?;
template.send_body("direct:temperature", 20)?;
alerts.assert_is_satisfied()?;
```

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:temperature")
            .route_id("route-temperatures")
            .choice()
            .when(simple("${body} > 80"))
            .to("mock:alerts")
            .otherwise()
            .to("mock:normal")
            .end();
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `expectedCount` | | Expect exactly this many messages. |
| `retainFirst` | | Keep only the first N exchanges (counts stay exact). |
| `retainLast` | | Keep only the last N exchanges. |
| `assertPeriod` | | After the expectations are met, keep checking for this long (catches extra messages). |
| `resultWaitTime` | | Maximum time `assert_is_satisfied` waits for the expectations. |
| `log`, `reportGroup` | | Accepted and ignored. |

Expectations are set from Rust on the `MockEndpoint` (from `ctx.mock_endpoint(uri)`):
`expected_message_count`, `expected_minimum_message_count`, `expected_bodies_received`,
`expected_bodies_received_in_any_order`, `expected_header_received`, `expected_property_received`,
`expects_no_duplicate_bodies`, `message(i, predicate)`, `all_messages(predicate)`, `expects(fn)`.
Behaviour: `return_reply_body`, `when_any_exchange_received`, `when_exchange_received`. Inspection:
`received_counter`, `received_exchanges`, `received_bodies`, `wait_for_messages`. Asserts:
`assert_is_satisfied`, `assert_is_satisfied_within`, `assert_is_not_satisfied`,
`MockEndpoint::assert_all_satisfied`.

## Message headers

None added. The recorded exchanges keep their headers for inspection.

## Run it with Docker

Mock endpoints are for tests. In a container they accept and record messages in memory:

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/temperatures.camel.yaml
```

## Common questions

### How do I test a YAML route with mocks?

Load the YAML with `cameleer_main::new_main()` and `add_route_source`, start it, send messages with
`ctx.create_producer_template()`, and assert on `ctx.mock_endpoint("mock:...")`.

### How do I make a mock reply like a real service?

Call `return_reply_body(constant("..."))` or `when_any_exchange_received(processor)` on the mock.

### Why does my assertion pass even though extra messages arrive later?

Assertions succeed as soon as the expectations hold. Set `assertPeriod` (or `set_assert_period`) to keep
checking for a while.

## Related

- [stub](https://pmsudhi.github.io/cameleer/docs/components/stub.html), [dataset](https://pmsudhi.github.io/cameleer/docs/components/dataset.html), [dataset-test](https://pmsudhi.github.io/cameleer/docs/components/dataset-test.html), [browse](https://pmsudhi.github.io/cameleer/docs/components/browse.html)
- [Apache Camel Mock component](https://camel.apache.org/components/next/mock-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/mongodb.html

# MongoDB component

> The `mongodb` component inserts, queries, updates and deletes documents in MongoDB, and consumes change streams and tailable cursors.

**Scheme:** `mongodb:` · **Crate:** `cameleer-datastores` · **Cargo feature:** [`datastores`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [MongoDB](https://camel.apache.org/components/next/mongodb-component.html)

## When to use it

- Store JSON documents from HTTP, Kafka or files without defining a schema first.
- Give an AI agent a memory: save notes, tool results or conversation turns per session and
  read the latest ones back before the next model call.
- React to changes: a change stream consumer routes every insert, update and delete.
- Run aggregations and bulk writes from a route.

## URI format

```text
mongodb:<connectionBean>?database=<db>&collection=<coll>&operation=<op>[&options]
```

The connection is one of:

- `connectionUriString=mongodb://host:27017` (or `mongodb+srv://cluster.example.com`, resolved
  with Cameleer's own DNS client), the path is then just a name;
- `hosts=host1:27017,host2:27017` with `username`, `password` and `authSource`;
- a `MongoClient` bound in the registry under the path name.

Put credentials in `username` and `password` rather than in `connectionUriString`: a
connection string with its own `?` options does not fit inside the endpoint URI.

Bodies are documents: maps, JSON text (Extended JSON and shell syntax such as
`ObjectId("...")` are accepted) or lists of them. Results use Extended JSON for BSON-only types
(`{"$oid": "..."}`, `{"$date": "..."}`).

## Example

`POST /notes` stores the JSON body as a document and returns it with its generated `_id`. An
agent can call this as a "remember" tool.

```yaml
- route:
    id: save-note
    from:
      uri: "platform-http:/notes?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - to: "mongodb:agentDb?connectionUriString={{env:MONGODB_URI:mongodb://localhost:27017}}&database=agent&collection=notes&operation=insert"
        - marshal:
            json: {}
```

`GET /notes?session=s1` returns the 20 newest notes of one session. The query document comes
from the body; sort and limit come from headers.

```yaml
- route:
    id: recent-notes
    from:
      uri: "platform-http:/notes?httpMethodRestrict=GET"
      steps:
        - filter:
            simple: "${header.session} !regex '^[A-Za-z0-9_-]+$'"
            steps:
              - setHeader:
                  name: CamelHttpResponseCode
                  constant: 400
              - setBody:
                  constant: "invalid session"
              - stop: {}
        - setBody:
            simple: '{"session": "${header.session}"}'
        - setHeader:
            name: CamelMongoDbSortBy
            constant: '{"_id": -1}'
        - setHeader:
            name: CamelMongoDbLimit
            constant: 20
        - to: "mongodb:agentDb?connectionUriString={{env:MONGODB_URI:mongodb://localhost:27017}}&database=agent&collection=notes&operation=findAll"
        - marshal:
            json: {}
```

The filter rejects session ids that are not plain words, so a request cannot inject query
operators into the JSON.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("direct:remember")
        .to("mongodb:agentDb?connectionUriString=mongodb://localhost:27017&database=agent&collection=notes&operation=insert");
    b.from("mongodb:agentDb?connectionUriString=mongodb://localhost:27017&database=agent&collection=notes&consumerType=changeStreams")
        .log("${header.CamelMongoDbStreamOperationType}: ${body}");
})?;
```

## Operations

| operation | body | result |
|---|---|---|
| `findById` | the id | the document or null |
| `findOneByQuery` | query document | the first match or null |
| `findAll` | query document (null = all) | list of documents; headers `CamelMongoDbResultTotalSize`, `CamelMongoDbResultPageSize` |
| `findDistinct` | query document | distinct values of the field in `CamelMongoDbDistinctQueryField` |
| `count` | query document | the number of matches |
| `insert` | document or list | the inserted document(s) with `_id`; header `CamelMongoOid` |
| `save` | document with `_id` | replaces or inserts it |
| `update` | `[filter, update]` list, or the update with the filter in `CamelMongoDbCriteria` | `CamelMongoDbRecordsAffected`, `CamelMongoDbRecordsMatched`; `CamelMongoDbMultiUpdate`, `CamelMongoDbUpsert` |
| `remove` | query document | `{deletedCount}`; header `CamelMongoDbRecordsAffected` |
| `bulkWrite` | list of `insertOne`, `updateOne`, `updateMany`, `replaceOne`, `deleteOne`, `deleteMany` models | counts; ordered unless `CamelMongoDbBulkOrdered=false`; write errors raise `MongoBulkWriteException` |
| `aggregate` | pipeline (list of stages) | list of documents; `CamelMongoDbAllowDiskUse` |
| `getDbStats`, `getColStats` | | the stats document |
| `command` | command document | the reply |

## Options

| option | default | description |
|---|---|---|
| `connectionUriString` | | `mongodb://` or `mongodb+srv://` connection string |
| `hosts` | | `host:port` list, used with `username`, `password`, `authSource` |
| `database` | | database name |
| `collection` | | collection name |
| `operation` | | producer operation (header `CamelMongoDbOperation` overrides it) |
| `createCollection` | `true` | create the collection on first use |
| `dynamicity` | `false` | allow `CamelMongoDbDatabase` and `CamelMongoDbCollection` headers to pick the target |
| `writeResultAsHeader` | `false` | put write results in `CamelMongoWriteResult` and keep the body |
| `consumerType` | | `changeStreams` or `tailable` |
| `streamFilter` | | change streams: a `$match` document, for example `{"operationType":"insert"}` |
| `fullDocument` | | change streams: `updateLookup` to receive the whole document on updates |
| `tailTrackIncreasingField` | | tailable: the increasing field to resume from |
| `cursorRegenerationDelay` | `1000` ms | tailable: wait before reopening a dead cursor |
| `sslContextParameters` | | TLS trust (with `tls=true` in the connection string) |

Authentication supports SCRAM-SHA-256, SCRAM-SHA-1 and MONGODB-X509. Replica sets are
discovered with `hello` and followed after a primary change. `readPreference`, `writeConcern`,
`collectionIndex`, `outputType` and the persistent tail-tracking options are accepted and
ignored; tail tracking is kept in memory only.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelMongoDbOperation` | in | operation for this exchange |
| `CamelMongoDbCriteria` | in | query document (instead of the body) |
| `CamelMongoDbFieldsProjection` | in | projection document |
| `CamelMongoDbSortBy` | in | sort document |
| `CamelMongoDbLimit`, `CamelMongoDbNumToSkip`, `CamelMongoDbBatchSize` | in | paging |
| `CamelMongoDbMultiUpdate`, `CamelMongoDbUpsert` | in | update flags |
| `CamelMongoDbDistinctQueryField` | in | field for `findDistinct` |
| `CamelMongoDbAllowDiskUse` | in | aggregation flag |
| `CamelMongoDbBulkOrdered` | in | `false` for unordered bulk writes |
| `CamelMongoDbDatabase`, `CamelMongoDbCollection` | in | target, with `dynamicity=true` |
| `CamelMongoOid` | out | id(s) of inserted documents |
| `CamelMongoDbRecordsAffected`, `CamelMongoDbRecordsMatched` | out | write counts |
| `CamelMongoDbResultTotalSize`, `CamelMongoDbResultPageSize` | out | query counts |
| `CamelMongoWriteResult` | out | write result with `writeResultAsHeader=true` |
| `CamelMongoDbStreamOperationType` | out | change streams: `insert`, `update`, `delete`, ... |
| `_id` | out | change streams: the document key |

## Run it with Docker

```sh
docker run --rm -p 8080:8080 -e MONGODB_URI=mongodb://mongo.example.com:27017 \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/notes.camel.yaml
```

## Common questions

### How do I connect with a username and password?

Use `hosts=mongo.example.com:27017&username=app&password={{env:MONGODB_PASSWORD}}&authSource=admin`
instead of putting them in `connectionUriString`.

### How do I sort and limit a query?

Set the headers `CamelMongoDbSortBy` (for example `{"_id": -1}`) and `CamelMongoDbLimit` before a
`findAll`.

### How do I react to new documents?

Consume with `consumerType=changeStreams`; add `streamFilter={"operationType":"insert"}` to see
inserts only. Change streams need a replica set on the server.

### Does it work with Azure Cosmos DB or FerretDB?

It speaks the MongoDB wire protocol (`OP_MSG`) and was verified against FerretDB 1.24 and an
embedded server. Other compatible servers are not tested.

## Related

- [mongodb-gridfs](https://pmsudhi.github.io/cameleer/docs/components/mongodb-gridfs.html): store files in MongoDB.
- [couchdb](https://pmsudhi.github.io/cameleer/docs/components/couchdb.html), [elasticsearch](https://pmsudhi.github.io/cameleer/docs/components/elasticsearch.html): other document stores.
- [Apache Camel MongoDB component](https://camel.apache.org/components/next/mongodb-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/mongodb-gridfs.html

# MongoDB GridFS component

> The `mongodb-gridfs` component stores, reads, lists and deletes files in MongoDB GridFS buckets, and polls a bucket for new files.

**Scheme:** `mongodb-gridfs:` · **Crate:** `cameleer-datastores` · **Cargo feature:** [`datastores`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [MongoDB GridFS](https://camel.apache.org/components/next/mongodb-gridfs-component.html)

## When to use it

- Keep documents, images or model outputs (generated reports, audio, embeddings dumps) next
  to the MongoDB data that refers to them.
- Archive files dropped into a folder by an edge device or a scanner.
- Serve stored files over HTTP, or hand every new upload to a processing route.

## URI format

```text
mongodb-gridfs:<connectionBean>?database=<db>[&bucket=fs][&operation=create][&options]
```

The connection is `connectionUriString=mongodb://host:27017` (the path is then just a name) or
a `MongoClient` bound in the registry under the path name. Files use the standard GridFS layout
(`<bucket>.files` and `<bucket>.chunks`), so files written by other drivers can be read and
the other way round.

## Example

This route uploads every file dropped into a folder into the `reports` bucket. The file
component sets `CamelFileName`, which becomes the GridFS file name.

```yaml
- route:
    id: archive-reports
    from:
      uri: "file:{{env:INBOX_DIR:inbox}}?move=.done"
      steps:
        - to: "mongodb-gridfs:archive?connectionUriString={{env:MONGODB_URI:mongodb://localhost:27017}}&database=docs&bucket=reports&operation=create"
        - log: "stored ${header.CamelFileName} as ${header[gridfs.fileid]}"
```

`GET /reports?name=q3.csv` returns the newest file with that name.

```yaml
- route:
    id: download-report
    from:
      uri: "platform-http:/reports?httpMethodRestrict=GET"
      steps:
        - setHeader:
            name: CamelFileName
            simple: "${header.name}"
        - to: "mongodb-gridfs:archive?connectionUriString={{env:MONGODB_URI:mongodb://localhost:27017}}&database=docs&bucket=reports&operation=findOne"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("file:inbox?move=.done")
        .to("mongodb-gridfs:archive?connectionUriString=mongodb://localhost:27017&database=docs&bucket=reports");
    b.from("mongodb-gridfs:archive?connectionUriString=mongodb://localhost:27017&database=docs&bucket=reports&queryStrategy=FileAttribute")
        .to("file:outbox");
})?;
```

## Operations

| operation | needs | result |
|---|---|---|
| `create` (default) | body (bytes or text), `CamelFileName` | stores the file; header `gridfs.fileid` |
| `findOne` | `gridfs.objectid` or `CamelFileName` | body = file content (the newest file with that name); headers `CamelFileName`, `CamelFileLength`, `CamelFileLastModified`, `Content-Type`, `gridfs.metadata`, `gridfs.fileid` |
| `remove` | `gridfs.objectid` or `CamelFileName` | deletes the file (or all files with that name) and its chunks |
| `listAll` | optional `CamelFileName` | body = one `filename<TAB>id` line per file |
| `count` | optional `CamelFileName` | body = number of files |

## Options

| option | default | description |
|---|---|---|
| `connectionUriString` | | `mongodb://` connection string (else the path names a `MongoClient` bean) |
| `database` | the connection string's database | database name (required) |
| `bucket` | `fs` | bucket name |
| `operation` | `create` | producer operation (header `gridfs.operation` overrides it) |
| `query` | | consumer: extra filter on the files collection, as JSON |
| `queryStrategy` | `TimeStamp` | consumer: `TimeStamp` (files uploaded after the consumer started), `FileAttribute` (files without the marker attribute) or `TimeStampAndFileAttribute` |
| `fileAttributeName` | `camel-processed` | consumer: the `metadata` field used as marker: `processing` while routed, `done` afterwards |
| `delay`, `initialDelay` | `500` ms, `1000` ms | consumer: the scheduled poll options |

`readPreference`, `writeConcern`, `persistentTSCollection` and `persistentTSObject` are accepted
and ignored. `PersistentTimestamp` is treated as `TimeStamp`: the timestamp is kept in memory,
so after a restart the `TimeStamp` strategy only sees files uploaded after the new start. Use
`FileAttribute` when every file must be processed exactly once across restarts.

## Message headers

| header | direction | description |
|---|---|---|
| `gridfs.operation` | in | operation for this exchange |
| `CamelFileName` | in/out | file name |
| `gridfs.objectid` | in | file id (hex) for `findOne` and `remove` |
| `gridfs.chunksize` | in | chunk size for `create` (default 261120 bytes) |
| `gridfs.metadata` | in/out | metadata as a JSON object |
| `Content-Type` | in/out | content type stored with the file |
| `gridfs.fileid` | out | id of the stored or read file |
| `CamelFileLength`, `CamelFileLastModified` | out | size and upload time (epoch milliseconds) |

## Run it with Docker

```sh
docker run --rm -e MONGODB_URI=mongodb://mongo.example.com:27017 -e INBOX_DIR=/inbox \
  -v "$PWD/inbox:/inbox" -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/archive.camel.yaml
```

The inbox is mounted read-write because `move=.done` moves processed files.

## Common questions

### How do I store metadata with a file?

Set the `gridfs.metadata` header to a JSON object, for example `{"customer": "acme"}`. It is
saved in the file's `metadata` field and returned by `findOne`.

### How do I process every new file once?

Consume with `queryStrategy=FileAttribute`: each file is marked in its metadata while and
after it is routed, so it is not picked up again, even after a restart.

### What chunk size is used?

261120 bytes (255 KiB), like the MongoDB drivers. Override it per file with `gridfs.chunksize`.

## Related

- [mongodb](https://pmsudhi.github.io/cameleer/docs/components/mongodb.html): documents and queries.
- [file](https://pmsudhi.github.io/cameleer/docs/components/file.html): read and write local files.
- [Apache Camel MongoDB GridFS component](https://camel.apache.org/components/next/mongodb-gridfs-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/mustache.html

# Mustache component

> The `mustache` component renders a Mustache template against the message (body, headers, properties) and sets the rendered text as the new body.

**Scheme:** `mustache:` · **Crate:** `cameleer-core` · **Cargo feature:** [`templates`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [Mustache](https://camel.apache.org/components/next/mustache-component.html)

## When to use it

- Build an LLM prompt from a JSON request: fill a prompt template with the user's question
  and context documents before calling a model.
- Render an email, a Slack message or a report from structured data.
- Produce a text payload (CSV line, SQL, XML snippet) without code.
- Keep wording in a file that non-developers can edit, separate from the route.

## URI format

```text
mustache:templateResource[?options]
```

`templateResource` is a file path relative to the working directory, `file:path`,
`classpath:path` (read as a relative path, there is no classpath) or `ref:beanName` (a
`String` bound in the registry).

## Example

A support agent receives `{"customer": ..., "question": ..., "docs": [...]}` and turns it into
a prompt for a model. The body is unmarshalled from JSON first so the template can read its
fields.

```text
You are a support assistant for {{headers.product}}.
Customer: {{body.customer}}
Question: {{body.question}}
{{#body.docs}}
- {{title}}: {{text}}
{{/body.docs}}
{{^body.docs}}
No documents matched.
{{/body.docs}}
Answer in at most {{headers.maxWords}} words.
```

```yaml
- route:
    id: mustache-prompt
    from:
      uri: direct:mustache-prompt
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: product
            constant: Cameleer
        - setHeader:
            name: maxWords
            constant: "80"
        - to: mustache:templates/support-prompt.mustache
```

```json
{"customer":"Ada","question":"How do I retry a failed HTTP call?","docs":[{"title":"Error handling","text":"Use onException with maximumRedeliveries."},{"title":"HTTP","text":"Set throwExceptionOnFailure=true."}]}
```

```text
You are a support assistant for Cameleer.
Customer: Ada
Question: How do I retry a failed HTTP call?
- Error handling: Use onException with maximumRedeliveries.
- HTTP: Set throwExceptionOnFailure=true.
Answer in at most 80 words.
```

With no documents, the inverted section renders instead:

```json
{"customer":"Bo","question":"Is there a Kafka component?","docs":[]}
```

```text
You are a support assistant for Cameleer.
Customer: Bo
Question: Is there a Kafka component?
No documents matched.
Answer in at most 80 words.
```

### Template from a header

With `allowTemplateFromHeader=true` the `CamelMustacheTemplate` header replaces the template
file, so a route can render templates stored elsewhere (a database, a config service).

`{{...}}` inside a route file is a property placeholder, so a template written in the route
itself uses other delimiters (`startDelimiter` / `endDelimiter`). Template files are not
affected.

```yaml
- route:
    id: mustache-header
    from:
      uri: direct:mustache-header
      steps:
        - setHeader:
            name: CamelMustacheTemplate
            constant: "Hello [[body]]!"
        - to:
            uri: mustache:templates/support-prompt.mustache
            parameters:
              allowTemplateFromHeader: true
              startDelimiter: "[["
              endDelimiter: "]]"
```

```text
World
```

```text
Hello World!
```

## Rust DSL

```rust
b.from("direct:mustache-rust")
    .to("mustache:templates/support-prompt.mustache?contentCache=true");
```

## Options

| option | default | description |
|---|---|---|
| `allowTemplateFromHeader` | `false` | Use the `CamelMustacheTemplate` / `CamelMustacheResourceUri` headers when present. |
| `contentCache` | `false` | Read the template once and keep it; otherwise it is re-read for every message. |
| `allowContextMapAll` | `false` | Add `camelContext` (with `name`) to the data model. |
| `startDelimiter` | `{{` | Opening tag delimiter. |
| `endDelimiter` | `}}` | Closing tag delimiter. |
| `encoding` | UTF-8 | Accepted; templates are always read as UTF-8. |

### Data model

| name | value |
|---|---|
| `body` | the message body (an object after `unmarshal: json`, so `body.field` works) |
| `headers` | the message headers (`headers.name`) |
| `variables` | the exchange variables |
| `exchange` | `exchange.properties`, `exchange.exchangeId`, `exchange.pattern`, `exchange.message` |
| `request`, `in` | `body`, `headers`, `messageId` of the message |
| `camelContext` | `camelContext.name`, only with `allowContextMapAll=true` |

### Supported Mustache features

Escaped `{{name}}` and unescaped `{{{name}}}` / `{{& name}}` variables, dotted names, the
implicit iterator `{{.}}`, sections over lists, objects and booleans, inverted sections
`{{^x}}`, comments `{{! ... }}`, partials `{{> name}}` (loaded from the template's directory as
`name` or `name.mustache`), set-delimiter tags `{{=<% %>=}}` and standalone-line removal.
Lambdas are not supported.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelMustacheTemplate` | in | Template text used instead of the endpoint's resource (needs `allowTemplateFromHeader=true`). Removed after use. |
| `CamelMustacheResourceUri` | in | Template resource used instead of the endpoint's one (needs `allowTemplateFromHeader=true`). |

## Run it with Docker

Put the route in `prompt.camel.yaml` and the template in `templates/` next to it:

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/prompt.camel.yaml
```

The image's working directory is `/routes`, so `templates/support-prompt.mustache` resolves to
the mounted file.

## Common questions

### How do I read JSON fields in a Mustache template?

Unmarshal the body first (`unmarshal: json: {}`); then `{{body.field}}` and sections over
`body.list` work. A plain JSON string body has no fields.

### Why does `{{body.text}}` turn `<` into `&lt;`?

Double braces HTML-escape the value, as in every Mustache implementation. Use `{{{body.text}}}`
or `{{& body.text}}` for raw text, which is what you want for prompts and plain text.

### Why do I get "Property with key [x] not found"?

The template text is inside the route file, where `{{x}}` is a property placeholder resolved
when the route starts. Keep templates in files, or switch delimiters with `startDelimiter` and
`endDelimiter` as in the header example above.

### Does the template reload when I edit the file?

Yes, by default the file is read for every message. Set `contentCache=true` to read it once.

## Related

- [FreeMarker](https://pmsudhi.github.io/cameleer/docs/components/freemarker.html), [Velocity](https://pmsudhi.github.io/cameleer/docs/components/velocity.html), [StringTemplate](https://pmsudhi.github.io/cameleer/docs/components/string-template.html),
  [MVEL](https://pmsudhi.github.io/cameleer/docs/components/mvel.html): other template engines.
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html): unmarshal JSON before rendering.
- [Apache Camel Mustache component](https://camel.apache.org/components/next/mustache-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/mvel.html

# MVEL component

> The `mvel` component renders an MVEL 2 template (orb tags such as `@{expr}` and `@foreach{}`) against the message and sets the rendered text as the new body.

**Scheme:** `mvel:` · **Crate:** `cameleer-script` · **Cargo feature:** [`script`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [MVEL](https://camel.apache.org/components/next/mvel-component.html)

## When to use it

- Render text with real expressions inside the template: arithmetic, method calls, ternaries.
- Build an order summary or a prompt where values need computing, not just inserting.
- Reuse MVEL templates from a Java Camel application.

For MVEL as an expression language (in `setBody`, `filter`...), see the
[MVEL language](https://pmsudhi.github.io/cameleer/docs/languages/mvel.html).

## URI format

```text
mvel:templateResource[?options]
```

`templateResource` is a file path relative to the working directory, `file:path`,
`classpath:path` (read as a relative path) or `ref:beanName`.

## Example

An order summary with a computed total, a loop with a separator and a condition.

```text
Order @{body.id} for @{body.customer.toUpperCase()}: @foreach{i : body.items}@{i.qty} x @{i.sku}@end{', '}
@code{total = 0; foreach (i : body.items) { total += i.qty * i.price; }}Total: @{total}
@if{total > 50}Free shipping.@else{}Shipping: 5.@end{}
```

```yaml
- route:
    id: mvel-order
    from:
      uri: direct:mvel-order
      steps:
        - unmarshal:
            json: {}
        - to: mvel:templates/order.mvel
```

```json
{"id":42,"customer":"ada","items":[{"sku":"A1","qty":2,"price":10},{"sku":"B2","qty":1,"price":40}]}
```

```text
Order 42 for ADA: 2 x A1, 1 x B2
Total: 60
Free shipping.
```

## Rust DSL

```rust
b.from("direct:mvel-rust")
    .unmarshal(DataFormatDefinition::json())
    .to("mvel:templates/order.mvel");
```

## Options

| option | default | description |
|---|---|---|
| `allowTemplateFromHeader` | `false` | Use the `CamelMvelTemplate` / `CamelMvelResourceUri` headers when present. |
| `contentCache` | `false` | Read the template once; otherwise it is re-read for every message. |
| `allowContextMapAll` | `false` | Add `camelContext` (with `name`) to the data model. |
| `encoding` | UTF-8 | Accepted; templates are always read as UTF-8. |

The data model: `body`, `headers`, `variables`, `exchange`, `request` / `in`, and
`camelContext` with `allowContextMapAll=true`.

### Supported orb tags

`@{expr}`, `@if{cond}...@elseif{cond}...@else{}...@end{}`, `@foreach{x : list}...@end{}` (an
optional separator in `@end{', '}`, several iterables `@foreach{a : as, b : bs}`),
`@code{statements}` (runs without output), `@comment{...}`, `@include{'file'}`,
`@declare{'name'}...@end{}` with `@includeNamed{'name'}`, and `@@` for a literal `@`.
Expressions are full MVEL 2.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelMvelTemplate` | in | Template text used instead of the resource (needs `allowTemplateFromHeader=true`). |
| `CamelMvelResourceUri` | in | Template resource used instead of the endpoint's one (needs `allowTemplateFromHeader=true`). |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/order.camel.yaml
```

## Common questions

### How do I compute a value once and reuse it?

Assign it in `@code{...}` (no output), then print it with `@{name}`, as `total` in the example.

### How do I put a separator between loop items?

Give `@end{}` an expression: `@foreach{i : items}@{i}@end{', '}`.

### Is the `mvel` component the same as the MVEL language?

They share the MVEL interpreter. The component renders a template file; the language
evaluates one expression inside a route step.

## Related

- [MVEL language](https://pmsudhi.github.io/cameleer/docs/languages/mvel.html).
- [Mustache](https://pmsudhi.github.io/cameleer/docs/components/mustache.html), [FreeMarker](https://pmsudhi.github.io/cameleer/docs/components/freemarker.html), [Velocity](https://pmsudhi.github.io/cameleer/docs/components/velocity.html),
  [StringTemplate](https://pmsudhi.github.io/cameleer/docs/components/string-template.html).
- [Apache Camel MVEL component](https://camel.apache.org/components/next/mvel-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/netty.html

# Netty component

> The `netty` component runs TCP and UDP servers and clients for plain socket protocols: text lines or raw bytes, one-way or request/reply.

**Scheme:** `netty:` · **Crate:** `cameleer-http` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Netty](https://camel.apache.org/components/next/netty-component.html)

## When to use it

- Accept line-based messages from devices, PLC gateways or legacy systems on a TCP port and answer each one.
- Receive UDP datagrams, such as telemetry from sensors on an edge network.
- Talk to a TCP service that speaks a simple text protocol (send a line, read a line back).

There is no Netty library underneath: Cameleer implements the same endpoint options with the Rust
standard library.

## URI format

```text
netty:tcp://host:port[?options]
netty:udp://host:port[?options]
```

A consumer binds `host:port`; port `0` picks a free port. A producer connects to `host:port`.

## Example

```yaml
- route:
    id: tcp-line-server
    from:
      uri: netty:tcp://0.0.0.0:{{env:TCP_PORT:5150}}
      parameters:
        textline: true
        sync: true
      steps:
        - setBody:
            simple: "ACK ${body}"
```

A client that sends the line `reading-42` gets `ACK reading-42` back on the same connection.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("netty:tcp://0.0.0.0:5150?textline=true&sync=true")
            .route_id("tcp-line-server")
            .set_body(simple("ACK ${body}"));
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `textline` | `false` | Messages are delimited text lines. Otherwise each read (TCP) or datagram (UDP) is one message of raw bytes. |
| `sync` | `true` | Request/reply: the consumer writes the result back; the producer waits for one reply. |
| `delimiter` | `LINE` | `LINE` (`\n`) or `NULL` (`\0`). |
| `autoAppendDelimiter` | `true` | Add the delimiter to outgoing text lines. |
| `decoderMaxLineLength` | `1024` | Longest accepted line. |
| `encoding` | `UTF-8` | `UTF-8`, `US-ASCII` or `ISO-8859-1`. |
| `allowDefaultCodec` | `true` | Accepted; the default codec is raw bytes. |
| `disconnect` | `false` | Close the connection after each exchange. |
| `disconnectOnNoReply` | `true` | Close the connection when `sync` is on and there is no reply. |
| `keepAlive` | `true` | TCP keep-alive. |
| `reuseAddress` | `true` | `SO_REUSEADDR` on the server socket. |
| `tcpNoDelay` | `true` | Disable Nagle's algorithm. |
| `requestTimeout` | `0` | Producer: how long (ms) to wait for a reply. `0` waits forever on TCP. |
| `connectTimeout` | `10000` | Producer: connect timeout (ms). |
| `workerCount` | `16` | Consumer: worker threads for connections. |
| `ssl` | `false` | TCP only: use TLS. |
| `sslContextParameters` | | `#bean` with the TLS settings. |
| `keyStoreFile` / `keyStoreResource` | | Server certificate and key: PEM, PKCS#12 or JKS (with `passphrase`). |
| `trustStoreFile` / `trustStoreResource` | | CA certificates to trust. |
| `keyStoreFormat`, `passphrase` | | Store format (`JKS`, `PKCS12`, `PEM`) and password. |
| `hostnameVerification` | `false` | Producer: check the server certificate's host name (the chain is always verified). |
| `encoders`, `decoders`, `encoder`, `decoder` | | Not supported (custom Netty codecs); ignored with a warning. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelNettyRemoteAddress` | out (consumer) | The client's address. |
| `CamelNettyLocalAddress` | out (consumer) | The server's address. |
| `CamelNettyCloseChannelWhenComplete` | in | `true` closes the connection after the reply. |

## Run it with Docker

```sh
docker run --rm -p 5150:5150 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/tcp.camel.yaml
```

Add `/udp` to the published port for `netty:udp://` (`-p 5150:5150/udp`).

## Common questions

### How do I send a line to a TCP server and read the answer?

`to: netty:tcp://server:5150?textline=true&sync=true`. The reply line becomes the body.

### How do I receive UDP without replying?

`from: netty:udp://0.0.0.0:5150?sync=false`. Each datagram becomes one message.

### Does netty support DTLS for UDP?

No. TLS works with TCP only.

## Related

- [mllp](https://pmsudhi.github.io/cameleer/docs/components/mllp.html), [syslog](https://pmsudhi.github.io/cameleer/docs/components/syslog.html)
- [Apache Camel Netty component](https://camel.apache.org/components/next/netty-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/netty-http.html

# Netty HTTP component

> The `netty-http` component serves HTTP requests on an address given in the URI, for routes written for Apache Camel's camel-netty-http.

**Scheme:** `netty-http:` · **Crate:** `cameleer-http` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Netty HTTP](https://camel.apache.org/components/next/netty-http-component.html)

`netty-http:` endpoints run on Cameleer's embedded HTTP/1.1 server, the same one as
[platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html). There is no Netty: the scheme exists so Camel routes run
unchanged. For raw TCP and UDP use the `netty` component; for outgoing HTTP use [http](https://pmsudhi.github.io/cameleer/docs/components/http.html).

## When to use it

- Run an existing Camel route that uses `netty-http:` without changes.
- A liveness probe for a container orchestrator on its own port.

## URI format

```text
netty-http:http://host:port/path[?options]
netty-http:https://host:port/path[?options]
```

## Example

A liveness probe that answers `pong` and echoes a `probe` query parameter, so a load balancer
or Kubernetes can check the integration.

```yaml
- route:
    id: liveness
    from:
      uri: "netty-http:http://0.0.0.0:{{env:PROBE_PORT:8083}}/ping"
      steps:
        - setBody:
            simple: "pong ${header.probe}"
```

## Rust DSL

```rust
fn liveness_route(b: &mut RouteBuilder, port: u16) {
    b.from(&format!("netty-http:http://0.0.0.0:{}/ping", port))
        .route_id("liveness")
        .set_body(simple("pong ${header.probe}"));
}
```

## Options

The options of [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html#options) apply: `httpMethodRestrict`,
`matchOnUriPrefix`, `consumes`, `produces`, `muteException`, `chunked`, `mapHttpMessageBody`,
`mapHttpMessageHeaders`, `mapHttpMessageFormUrlEncodedBody`, `disableStreamCache`,
`sslContextParameters`, `useGlobalSslContextParameters`, `needClientAuth` / `clientAuth`, and
`host` / `port` to override the URI. Netty tuning options (worker groups, codecs) are not
supported.

## Message headers

The same as [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html#message-headers). Query parameters such as
`?probe=lb` become message headers.

## Run it with Docker

```sh
docker run --rm -p 8083:8083 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/liveness.camel.yaml
curl 'localhost:8083/ping?probe=lb'
```

## Common questions

### Does netty-http need Netty?
No. It runs on the built-in server.

### What happens to query parameters?
They become message headers (`${header.probe}`), and the whole query string is in
`CamelHttpQuery`.

### Can I use netty-http as a client?
No. Use [http](https://pmsudhi.github.io/cameleer/docs/components/http.html).

## Related

- [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html), [jetty](https://pmsudhi.github.io/cameleer/docs/components/jetty.html), [undertow](https://pmsudhi.github.io/cameleer/docs/components/undertow.html).
- Apache Camel: [Netty HTTP component](https://camel.apache.org/components/next/netty-http-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/openai.html

# OpenAI component

> The `openai` component calls any OpenAI-compatible API (OpenAI, Ollama, vLLM, LM Studio, LiteLLM and other gateways) for chat completions and embeddings.

**Scheme:** `openai:` · **Crate:** `cameleer-saas` · **Cargo feature:** [`saas`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** no direct equivalent; closest are [LangChain4j Chat](https://camel.apache.org/components/next/langchain4j-chat-component.html) and [LangChain4j Embeddings](https://camel.apache.org/components/next/langchain4j-embeddings-component.html)

## When to use it

- Classify, route or tag messages with an LLM (ticket priority, sentiment, language, intent).
- Summarise or rewrite text inside a route (incident reports, e-mails, logs) before sending it on.
- Create embeddings for semantic search or retrieval-augmented generation (RAG) and store them.
- Run against a local model (Ollama, vLLM) on an edge box or an air-gapped network with the same route.

## URI format

```text
openai:chat-completion[?options]
openai:embeddings[?options]
```

`chat`, `chat-completions` and `embedding` are accepted as aliases. Any other operation fails
when the endpoint is created.

## Example

Classify a support ticket. A text body is the user message; `systemMessage` is the system
prompt. The body becomes the assistant's answer; the token usage is in headers.

```yaml
- route:
    id: classify-ticket
    from:
      uri: "direct:classify"
      steps:
        - to: "openai:chat-completion?model={{env:OPENAI_MODEL:gpt-4o-mini}}&apiKey={{env:OPENAI_API_KEY}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}&temperature=0&maxTokens=5&systemMessage=Classify the ticket as billing, bug or question. Reply with one word."
        - setHeader:
            name: category
            simple: "${body}"
        - log: "category=${header.category} tokens=${header.CamelOpenAITotalTokens}"
```

Create an embedding. A text body becomes one vector (a list of numbers); a list body becomes a
list of vectors, in the same order.

```yaml
- route:
    id: embed-text
    from:
      uri: "direct:embed"
      steps:
        - to: "openai:embeddings?model={{env:OPENAI_EMBEDDING_MODEL:text-embedding-3-small}}&apiKey={{env:OPENAI_API_KEY}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}"
        - log: "vector with ${body.size()} dimensions"
```

Use a local model with Ollama (or vLLM, LM Studio): only `baseUrl` and `model` change. Ollama
does not check the API key, so none is set. A list body is a conversation: maps with `role`
and `content`, plain strings become user messages.

```yaml
- route:
    id: local-llm
    from:
      uri: "direct:ask-local"
      steps:
        - to: "openai:chat-completion?model={{env:OLLAMA_MODEL:llama3.2}}&baseUrl={{env:OLLAMA_URL:http://localhost:11434/v1}}&systemMessage=Answer briefly."
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("direct:classify")
        .to("openai:chat-completion?model=gpt-4o-mini&temperature=0&systemMessage=Classify the ticket as billing, bug or question. Reply with one word.")
        .set_header("category", simple("${body}"));
})?;
```

## Options

| option | default | description |
|---|---|---|
| `model` | | Model name (`gpt-4o-mini`, `text-embedding-3-small`, `llama3.2`, ...). The `CamelOpenAIModel` header overrides it. |
| `apiKey` | `OPENAI_API_KEY` env | Sent as `Authorization: Bearer ...`. |
| `organization` | | Sent as the `OpenAI-Organization` header. |
| `baseUrl` | `https://api.openai.com/v1` | API base URL: any OpenAI-compatible server. |
| `systemMessage` | | Chat: system prompt (the `CamelOpenAISystemMessage` header overrides it). |
| `temperature` | | Chat: sampling temperature. |
| `maxTokens` | | Chat: `max_tokens`. |
| `topP` | | Chat: `top_p`. |
| `user` | | Chat: end-user id sent as `user`. |
| `outputType` | | `full` keeps the whole JSON response as the body instead of the answer text (or the vectors). |
| `timeout` | `120s` | HTTP timeout. |

Values in a request-map body win over the options (an option is only added when the key is
missing).

## Message headers

| header | direction | description |
|---|---|---|
| `CamelOpenAISystemMessage` | in | Chat: system prompt. |
| `CamelOpenAIModel` | in | Model for this call. |
| `CamelOpenAIResponseId` | out | Chat: response id. |
| `CamelOpenAIResponseModel` | out | Chat: model that answered. |
| `CamelOpenAIFinishReason` | out | Chat: `stop`, `length`, `tool_calls`, ... |
| `CamelOpenAIPromptTokens`, `CamelOpenAICompletionTokens`, `CamelOpenAITotalTokens` | out | Chat: token usage. |

Chat bodies: a text body is one user message (after the system message); a list body is the
message list; a map body is sent as the whole request (`model` and the options are added when
missing), which lets you pass fields the component has no option for, such as
`response_format`, `seed` or `tools`.

## Run it with Docker

```sh
export OPENAI_API_KEY=sk-...
docker run --rm -e OPENAI_API_KEY -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/classify-ticket.camel.yaml
```

With Ollama on the host (Docker Desktop):

```sh
docker run --rm -e OLLAMA_URL=http://host.docker.internal:11434/v1 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/local-llm.camel.yaml
```

## Common questions

### Does it support streaming?

No. The component sends one request and waits for the complete answer (`timeout`, default 120
seconds). For streaming, use [azure-openai](https://pmsudhi.github.io/cameleer/docs/components/azure-openai.html) (`streaming=true`),
[aws-bedrock](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html) or [google-vertexai](https://pmsudhi.github.io/cameleer/docs/components/google-vertexai.html).

### Does it support tool calls (function calling)?

Not natively: there is no tool option, no tool-call header and no agent loop. You can send a
request map with `tools` and `outputType=full`, then read `choices[0].message.tool_calls` from
the response yourself. The [AI components guide](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html) shows this and
the components with built-in tool-call support.

### How do I get JSON output?

Put `"response_format": {"type": "json_object"}` in a request-map body (or ask for JSON in the
system message) and `unmarshal: json` the answer.

### What happens on an API error?

A non-2xx response fails with `HttpOperationFailedException`; the message contains the status
and the API's `error.message` (for example `Incorrect API key provided`). Rate limits (429) can
be retried with `onException` and a redelivery policy.

## Related

- [AI components guide](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html)
- [azure-openai](https://pmsudhi.github.io/cameleer/docs/components/azure-openai.html), [aws-bedrock](https://pmsudhi.github.io/cameleer/docs/components/aws-bedrock.html), [google-vertexai](https://pmsudhi.github.io/cameleer/docs/components/google-vertexai.html)
- [slack](https://pmsudhi.github.io/cameleer/docs/components/slack.html), [jira](https://pmsudhi.github.io/cameleer/docs/components/jira.html), [telegram](https://pmsudhi.github.io/cameleer/docs/components/telegram.html) for agents that post their results
- [Apache Camel LangChain4j Chat](https://camel.apache.org/components/next/langchain4j-chat-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/opensearch.html

# OpenSearch component

> The `opensearch` component indexes, gets, deletes and searches documents in OpenSearch (including Amazon OpenSearch Service with basic authentication) over its REST API.

**Scheme:** `opensearch:` · **Crate:** `cameleer-datastores` · **Cargo feature:** [`datastores`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [OpenSearch](https://camel.apache.org/components/next/opensearch-component.html)

## When to use it

- Ship application logs or events into OpenSearch in batches with one bulk request.
- Full-text search as the retrieval step of an AI agent or a support chatbot.
- Keep a search index in step with a database: index on insert, delete on removal.

The `opensearch` scheme is the [elasticsearch](https://pmsudhi.github.io/cameleer/docs/components/elasticsearch.html) component registered under a
second name: the operations, options and headers are the same, and so is the REST API they use.

## URI format

```text
opensearch://clusterName?hostAddresses=host:9200&operation=<op>[&indexName=<index>][&options]
```

## Example

`POST /logs` takes a JSON array of log records and indexes them with one `_bulk` request into
the `app-logs` index. The answer is the list of per-document results.

```yaml
- route:
    id: bulk-logs
    from:
      uri: "platform-http:/logs?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - to: "opensearch://logs?hostAddresses={{env:OPENSEARCH_HOSTS:localhost:9200}}&user={{env:OPENSEARCH_USER:admin}}&password={{env:OPENSEARCH_PASSWORD:admin}}&operation=Bulk&indexName=app-logs"
        - marshal:
            json: {}
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("direct:logs")
        .to("opensearch://logs?hostAddresses=localhost:9200&operation=Bulk&indexName=app-logs");
    b.from("direct:find")
        .to("opensearch://logs?hostAddresses=localhost:9200&operation=Search&indexName=app-logs&size=10&enableDocumentOnlyMode=true");
})?;
```

## Options

The most used options are below; the full list, with scrolling, sniffing and typed documents,
is on the [elasticsearch](https://pmsudhi.github.io/cameleer/docs/components/elasticsearch.html#options) page.

| option | default | description |
|---|---|---|
| `hostAddresses` | `localhost:9200` | comma-separated `host:port` list, tried in order |
| `operation` | | `Index`, `Update`, `Bulk`, `GetById`, `MultiGet`, `Delete`, `DeleteIndex`, `Exists`, `Search`, `MultiSearch`, `Ping` (header `operation` overrides it) |
| `indexName` | | index (header `indexName` overrides it) |
| `from`, `size` | | paging for searches |
| `enableDocumentOnlyMode` | `false` | return `_source` documents instead of response objects |
| `user`, `password` | | basic authentication |
| `apiKey` | | sent as `Authorization: ApiKey <value>` |
| `enableSSL` | `false` | HTTPS; trust from `sslContextParameters=#bean`, the global `camel.ssl.*` parameters or the system store |
| `useScroll` | `false` | run `Search` as a scroll search and return all hits |

## Message headers

| header | direction | description |
|---|---|---|
| `operation` | in | operation for this exchange |
| `indexName` | in | index for this exchange |
| `indexId` | in | document id for `Index`, `Update`, `GetById`, `Delete` |
| `size`, `from` | in | paging for searches |

## Run it with Docker

```sh
docker run --rm -p 8080:8080 \
  -e OPENSEARCH_HOSTS=search.example.com:9200 -e OPENSEARCH_USER=app -e OPENSEARCH_PASSWORD \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/logs.camel.yaml
```

## Common questions

### Does it sign requests for Amazon OpenSearch Service (SigV4)?

No. Use a domain with fine-grained access control and basic authentication (`user` and
`password`), or an API key. AWS SigV4 request signing is not implemented for this component.

### What does a bulk body look like?

A list of documents (each is indexed with a generated id), or a list of actions such as
`{"index": {"_id": "1"}, "doc": {...}}`, `{"update": {"_id": "1"}, "doc": {...}}` and
`{"delete": {"_id": "2"}}`. The two forms can be mixed.

### What is the difference from the elasticsearch component?

Only the scheme name. Both send the same REST requests, which OpenSearch and Elasticsearch
share for these operations.

## Related

- [elasticsearch](https://pmsudhi.github.io/cameleer/docs/components/elasticsearch.html): all operations and options.
- [Apache Camel OpenSearch component](https://camel.apache.org/components/next/opensearch-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/paho.html

# Paho (MQTT) component

> The `paho` component publishes and subscribes to MQTT 3.1.1 topics, for IoT sensors, edge gateways and any MQTT broker such as Mosquitto, EMQX, HiveMQ or AWS IoT Core.

**Scheme:** `paho:` · **Crate:** `cameleer-kafka-mqtt` · **Cargo feature:** [`kafka-mqtt`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Paho](https://camel.apache.org/components/next/paho-component.html)

## When to use it

- Collect readings from sensors that publish to MQTT (`sensors/+/temperature`) and forward them to Kafka,
  a database or an HTTP API.
- Send commands or configuration to devices on an edge network.
- Bridge MQTT and another broker (Kafka, AMQP) on a gateway, with QoS 1 or 2 for reliable delivery.

For MQTT 5 features (user properties, session expiry) use [paho-mqtt5](https://pmsudhi.github.io/cameleer/docs/components/paho-mqtt5.html). The MQTT client is
built into Cameleer (no Eclipse Paho library).

## URI format

```text
paho:topic[?options]
```

Consumers may use the wildcards `+` (one level) and `#` (all remaining levels). In a URI query write `#`
as `%23`; in the YAML `parameters` block or the path it can be written as is.

## Example

```yaml
- route:
    id: sensors-to-kafka
    from:
      uri: paho:sensors/+/temperature
      parameters:
        brokerUrl: "{{env:MQTT_URL:tcp://localhost:1883}}"
        clientId: edge-gw-1
        qos: 1
      steps:
        - setHeader:
            name: kafka.KEY
            simple: "${header.CamelMqttTopic}"
        - to: kafka:temperatures?brokers={{env:KAFKA_BROKERS:localhost:9092}}
```

A reading published to `sensors/room1/temperature` reaches the Kafka topic `temperatures` with the MQTT
topic as record key. The MQTT message is acknowledged after the Kafka send succeeded.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("paho:sensors/+/temperature?brokerUrl=tcp://localhost:1883&clientId=edge-gw-1&qos=1")
            .route_id("sensors-to-kafka")
            .set_header("kafka.KEY", simple("${header.CamelMqttTopic}"))
            .to("kafka:temperatures?brokers=localhost:9092");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `brokerUrl` | `tcp://localhost:1883` | Broker address. `ssl://`, `mqtts://` or `tls://` connect with TLS (default port 8883). `ws://` and `wss://` are not supported. |
| `serverURIs` | | List of brokers; the first one is used. |
| `clientId` | generated | MQTT client id. Use a fixed id for persistent sessions. |
| `qos` | `2` | Quality of service: `0`, `1` or `2`. |
| `retained` | `false` | Producer: publish as a retained message. |
| `userName`, `password` | | Credentials. |
| `cleanSession` | `true` | Start a clean session. `false` keeps subscriptions and queued messages while the route is down. |
| `keepAliveInterval` | `60` | Keep-alive in seconds. |
| `connectionTimeout` | `30` | Connect timeout in seconds. |
| `automaticReconnect` | `true` | Reconnect after a lost connection. |
| `maxReconnectDelay` | `128000` | Longest wait (ms) between reconnect attempts. |
| `willTopic`, `willPayload`, `willQos`, `willRetained` | | Last will message, published by the broker if the client disappears. |
| `httpsHostnameVerificationEnabled` | `true` | `false` skips the host name check of the broker certificate. |
| `sslContextParameters`, `useGlobalSslContextParameters` | | TLS trust settings. |
| `persistence`, `filePersistenceDirectory`, `maxInflight`, `executorServiceTimeout`, ... | | Accepted and ignored. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelMqttTopic` | out | Topic the message was published to. |
| `CamelMqttQoS` | out | QoS of the delivery. |
| `CamelMqttRetained` | out | Whether it was a retained message. |
| `CamelPahoDuplicate` | out | The broker's duplicate flag. |
| `CamelPahoMessageId` | out | MQTT packet id. |
| `CamelPahoOverrideTopic` | in | Producer: publish to this topic instead. |
| `CamelPahoQos` | in | Producer: override `qos`. |
| `CamelPahoRetained` | in | Producer: override `retained`. |

The consumer's body is the payload as bytes. Producers send byte bodies as is and other values as UTF-8
text; QoS 1 and 2 sends wait for the broker's acknowledgement.

## Run it with Docker

```sh
docker run --rm -e MQTT_URL=tcp://mosquitto:1883 -e KAFKA_BROKERS=kafka:9092 \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/sensors.camel.yaml
```

The image is small and starts in milliseconds, so it fits on gateways such as a Raspberry Pi class device.

## Common questions

### How do I subscribe to all topics under a prefix?

Use `#` at the end: `paho:sensors/#`. In a URI query string encode it as `%23`.

### How do I keep messages while my route is offline?

Use a fixed `clientId`, `cleanSession=false` and `qos=1` or `2`. The broker queues messages for the session.

### How do I connect to AWS IoT Core or another TLS broker?

Use `brokerUrl=ssl://endpoint:8883`. Trust comes from `sslContextParameters=#bean`,
`useGlobalSslContextParameters=true`, the global `camel.ssl.*` parameters, or else the system trust store.

## Related

- [paho-mqtt5](https://pmsudhi.github.io/cameleer/docs/components/paho-mqtt5.html), [kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html), [seda](https://pmsudhi.github.io/cameleer/docs/components/seda.html)
- [Apache Camel Paho component](https://camel.apache.org/components/next/paho-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/paho-mqtt5.html

# Paho MQTT 5 component

> The `paho-mqtt5` component publishes and subscribes to MQTT 5.0 topics, with user properties, clean start and session expiry.

**Scheme:** `paho-mqtt5:` · **Crate:** `cameleer-kafka-mqtt` · **Cargo feature:** [`kafka-mqtt`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Paho MQTT 5](https://camel.apache.org/components/next/paho-mqtt5-component.html)

## When to use it

- Publish device status from an edge gateway as a retained message, so new subscribers see the latest value.
- Use MQTT 5 user properties as message headers (trace ids, device metadata).
- Keep a session for a limited time with `sessionExpiryInterval`.

Everything in [paho](https://pmsudhi.github.io/cameleer/docs/components/paho.html) applies; this page lists the differences.

## URI format

```text
paho-mqtt5:topic[?options]
```

## Example

```yaml
- route:
    id: publish-gateway-status
    from:
      uri: timer:status
      parameters:
        period: 30000
        delay: 0
      steps:
        - setBody:
            simple: '{"gateway":"edge-gw-1","status":"online","seq":${exchangeProperty.CamelTimerCounter}}'
        - to: paho-mqtt5:devices/edge-gw-1/status?brokerUrl={{env:MQTT_URL:tcp://localhost:1883}}&qos=1&retained=true
```

Every 30 seconds the gateway publishes its status as a retained QoS 1 message. A dashboard that subscribes
later gets the last status at once.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("timer:status?period=30000&delay=0")
            .route_id("publish-gateway-status")
            .set_body(simple(r#"{"gateway":"edge-gw-1","status":"online","seq":${exchangeProperty.CamelTimerCounter}}"#))
            .to("paho-mqtt5:devices/edge-gw-1/status?brokerUrl=tcp://localhost:1883&qos=1&retained=true");
    })
}
```

## Options

The options of [paho](https://pmsudhi.github.io/cameleer/docs/components/paho.html#options), with these differences:

| option | default | description |
|---|---|---|
| `cleanStart` | `true` | MQTT 5 name of `cleanSession`. |
| `sessionExpiryInterval` | `-1` | Seconds the broker keeps the session after a disconnect. `-1` does not send the property. |

## Message headers

The headers of [paho](https://pmsudhi.github.io/cameleer/docs/components/paho.html#message-headers). In addition, MQTT 5 user properties of received messages
become headers, and the producer also reads `CamelPahoMqtt5OverrideTopic`.

## Run it with Docker

```sh
docker run --rm -e MQTT_URL=tcp://mosquitto:1883 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/status.camel.yaml
```

## Common questions

### Should I use paho or paho-mqtt5?

Use `paho-mqtt5` when the broker supports MQTT 5 and you need user properties or session expiry. Use
`paho` for MQTT 3.1.1 brokers and devices.

### How do I clear a retained message?

Publish an empty body with `retained=true` to the same topic.

## Related

- [paho](https://pmsudhi.github.io/cameleer/docs/components/paho.html), [timer](https://pmsudhi.github.io/cameleer/docs/components/timer.html), [kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html)
- [Apache Camel Paho MQTT 5 component](https://camel.apache.org/components/next/paho-mqtt5-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/platform-http.html

# Platform HTTP component

> The `platform-http` component serves HTTP requests on Cameleer's embedded HTTP/1.1 server: each route binds a path and its reply becomes the HTTP response.

**Scheme:** `platform-http:` · **Crate:** `cameleer-http` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Platform HTTP](https://camel.apache.org/components/next/platform-http-component.html)

All `platform-http` routes share one server and one port (`camel.server.port`, default 8080).
[jetty](https://pmsudhi.github.io/cameleer/docs/components/jetty.html), [undertow](https://pmsudhi.github.io/cameleer/docs/components/undertow.html) and [netty-http](https://pmsudhi.github.io/cameleer/docs/components/netty-http.html) are the same server
with the host and port in the URI. The [REST DSL](https://pmsudhi.github.io/cameleer/docs/components/rest.html) generates `platform-http` routes.

## When to use it

- Expose an HTTP API or a webhook receiver from a route.
- Give an AI agent a tool endpoint it can call over HTTP.
- Receive telemetry from devices on an edge gateway and hand it to a queue.
- Serve health or status endpoints next to other routes.

## URI format

```text
platform-http:/path[?options]
platform-http:/path/{param}[?options]
```

`{param}` path segments become message headers. The host comes from `camel.server.host`
(default `0.0.0.0`), the port from the `port` option, `camel.component.platform-http.port`,
`camel.server.port` or 8080. Port `0` picks a free port.

## Example

An edge gateway endpoint that accepts sensor readings for a device, answers `202 Accepted` and
forwards the reading to an in-memory queue for processing.

```yaml
- route:
    id: device-readings
    from:
      uri: platform-http:/devices/{id}/readings?httpMethodRestrict=POST
      steps:
        - setHeader:
            name: deviceId
            simple: "${header.id}"
        - wireTap: seda:readings
        - setHeader:
            name: CamelHttpResponseCode
            constant: 202
        - setHeader:
            name: Content-Type
            constant: application/json
        - setBody:
            simple: '{"device": "${header.id}", "accepted": true}'
- route:
    id: store-readings
    from:
      uri: seda:readings
      steps:
        - log: "device ${header.deviceId}: ${body}"
```

A `GET` on the same path answers `405 Method Not Allowed`; an unknown path answers `404`.

## Rust DSL

```rust
fn device_readings_routes(b: &mut RouteBuilder) {
    b.from("platform-http:/devices/{id}/readings?httpMethodRestrict=POST")
        .route_id("device-readings")
        .set_header("deviceId", simple("${header.id}"))
        .wire_tap("seda:readings")
        .set_header("CamelHttpResponseCode", constant(202))
        .set_header("Content-Type", constant("application/json"))
        .set_body(simple(r#"{"device": "${header.id}", "accepted": true}"#));
    b.from("seda:readings").route_id("store-readings").log("device ${header.deviceId}: ${body}");
}
```

## Options

| option | default | description |
|---|---|---|
| `httpMethodRestrict` | any | Comma-separated methods, e.g. `GET,POST`. Other methods get `405`. |
| `matchOnUriPrefix` | `false` | Also match every path below this one. |
| `consumes` | | Accepted request media type. |
| `produces` | | Response media type. |
| `port` | `camel.server.port` or 8080 | Port of this endpoint (`0` = free port). |
| `host` | `camel.server.host` or `0.0.0.0` | Interface to bind. |
| `muteException` | `false` | On failure, answer 500 without the exception text. |
| `chunked` | `false` | Send responses with chunked transfer coding. |
| `mapHttpMessageBody` | `true` | Put the request body in the message body. |
| `mapHttpMessageHeaders` | `true` | Map request headers to message headers. |
| `mapHttpMessageFormUrlEncodedBody` | `true` | Map form fields of `application/x-www-form-urlencoded` bodies to headers. |
| `disableStreamCache` | `false` | Pass the request body as a stream handle read lazily from the connection. |
| `ssl` | `false` | Serve HTTPS (certificate from `camel.server.ssl.*` or `sslContextParameters`). |
| `sslContextParameters` | | `#bean` with the server key store; also enables HTTPS. |
| `useGlobalSslContextParameters` | `false` | Use the global `camel.ssl.*` parameters. |
| `needClientAuth` | `false` | Require a client certificate (mutual TLS). `clientAuth=NONE\|WANT\|REQUIRE` is the long form. |

`camel.server.sslEnabled=true` turns on HTTPS for every `platform-http` endpoint. Apache Camel
options such as `transferException`, `useStreaming`, `headerFilterStrategy` and
`sessionSupport` are accepted and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelHttpMethod` | out | Request method. |
| `CamelHttpUri` | out | Request target as received. |
| `CamelHttpPath` | out | Request path. |
| `CamelHttpQuery` | out | Decoded query string. |
| `CamelHttpRawQuery` | out | Raw query string. |
| `CamelHttpRemoteAddress` | out | Client address. |
| `Content-Type` | in / out | Request media type; set it to choose the response media type. |
| `CamelHttpResponseCode` | in | Response status (default 200). |
| `CamelHttpResponseText` | in | Response reason phrase. |
| `CamelHttpChunked` | in | `true` sends this response chunked. |
| `CamelHttpSslClientCert` | out | Verified client certificate (PEM) with mutual TLS; also `...SubjectName`, `...IssuerName`, `...SerialNo`, `...NotBefore`, `...NotAfter`. |

Path parameters, query parameters and request headers become message headers. A failed exchange
answers 500 with the exception text; a handled exception answers 200 with the handled body (set
`CamelHttpResponseCode` in the handler to change it).

## Run it with Docker

```sh
docker run --rm -p 8080:8080 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/device-readings.camel.yaml
curl -XPOST -d '{"temp": 21.5}' localhost:8080/devices/sensor-7/readings
```

## Common questions

### How do I change the port?
Set `camel.server.port` (for example `--prop camel.server.port=9000` on `run`, or
`CAMEL_SERVER_PORT=9000` in the environment), or add `port=9000` to one endpoint.

### How do I return a different status code?
Set the `CamelHttpResponseCode` header before the route ends, e.g. 201 or 404.

### How do I serve HTTPS?
Set `camel.server.ssl.keyStore` (or `certFile` and `keyFile`) and `camel.server.sslEnabled=true`,
or add `ssl=true` / `sslContextParameters=#tls` to an endpoint.

### Can I serve every path below a prefix?
Yes: `platform-http:/files?matchOnUriPrefix=true`; `CamelHttpPath` holds the full path.

## Related

- [rest](https://pmsudhi.github.io/cameleer/docs/components/rest.html): the REST DSL with OpenAPI generation.
- [jetty](https://pmsudhi.github.io/cameleer/docs/components/jetty.html), [undertow](https://pmsudhi.github.io/cameleer/docs/components/undertow.html), [netty-http](https://pmsudhi.github.io/cameleer/docs/components/netty-http.html): the same server with the address in the URI.
- [http](https://pmsudhi.github.io/cameleer/docs/components/http.html): call HTTP services.
- [webhook](https://pmsudhi.github.io/cameleer/docs/components/webhook.html): register webhooks with SaaS services.
- Apache Camel: [Platform HTTP component](https://camel.apache.org/components/next/platform-http-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/pop3.html

# POP3 component

> The `pop3` component downloads email from a POP3 mailbox on a schedule and turns each message into an exchange.

**Scheme:** `pop3:` · **Also:** `pop3s:` · **Crate:** `cameleer-protocols` · **Cargo feature:** [`protocols`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Mail](https://camel.apache.org/components/next/mail-component.html)

`pop3s:` uses implicit TLS (port 995); `pop3:` can upgrade with STLS
(`mail.pop3.starttls.enable=true`). For folders and flags use [imap](https://pmsudhi.github.io/cameleer/docs/components/imap.html).

## When to use it

- Archive every incoming message of a mailbox to disk or object storage.
- Collect mail from devices or old systems that report by email.
- Simple mail intake where messages are deleted from the server once handled.

## URI format

```text
pop3://[username@]host[:port][?options]
pop3s://[username@]host[:port][?options]
```

Default ports: 110 (`pop3`), 995 (`pop3s`).

## Example

Archive each new message as a raw `.eml` file and delete it from the server.

```yaml
- route:
    id: archive-mail
    from:
      uri: "pop3s://{{env:POP3_HOST:pop.example.com}}?username={{env:POP3_USER:archive@example.com}}&password={{env:POP3_PASSWORD:changeme}}&mapMailMessage=false&delete=true&delay=60000"
      steps:
        - to: "file:{{env:ARCHIVE_DIR:mail-archive}}?fileName=${date:now:yyyyMMdd}/${exchangeId}.eml"
```

## Rust DSL

```rust
fn archive_mail_route(b: &mut RouteBuilder, pop3: &str, archive_dir: &str) {
    b.from(pop3)
        .route_id("archive-mail")
        .to(&format!("file:{}?fileName=${{date:now:yyyyMMdd}}/${{exchangeId}}.eml", archive_dir));
}
```

## Options

| option | default | description |
|---|---|---|
| `username`, `password` | | Login. |
| `delete` | `false` | Delete messages after processing. |
| `unseen` | `true` | Only messages not seen before (tracked by `UIDL`, in memory). |
| `maxMessagesPerPoll` / `fetchSize` | no limit | Messages per poll. |
| `mapMailMessage` | `true` | `true`: the body is the text content. `false`: the raw message. |
| `delay` | `60000` | Milliseconds between polls (`initialDelay` 1000 and the other scheduler options). |
| `connectionTimeout` | `30s` | Connect timeout. |
| `mail.pop3.starttls.enable`, `mail.pop3.starttls.required` | `false` | STLS on `pop3:`. |
| `sslContextParameters` | | `#bean` with trust material for TLS. |
| `useGlobalSslContextParameters` | `false` | Use the global `camel.ssl.*` parameters. |

## Message headers

| header | direction | description |
|---|---|---|
| `Subject`, `From`, `To`, `Date`, `Message-ID`, ... | out | Every mail header; repeated headers become a list. |

MIME parts other than the body go to the `CamelAttachments` exchange property.

## Run it with Docker

```sh
docker run --rm --user "$(id -u):$(id -g)" -e POP3_HOST=pop.example.com -e POP3_USER -e POP3_PASSWORD \
  -e ARCHIVE_DIR=/data/mail-archive -v "$PWD:/data" \
  -v "$PWD/archive-mail.camel.yaml:/routes/archive-mail.camel.yaml:ro" \
  pmsudhi/cameleer run /routes/archive-mail.camel.yaml
```

## Common questions

### Does pop3 remember which messages it has read?
Without `delete=true`, it remembers message `UIDL`s in memory, so a restart reads them again. Use
`delete=true` or IMAP for durable tracking.

### How do I get only the text?
Keep `mapMailMessage=true` (the default): the body is the first `text/plain` part.

## Related

- [imap](https://pmsudhi.github.io/cameleer/docs/components/imap.html), [smtp](https://pmsudhi.github.io/cameleer/docs/components/smtp.html), [file](https://pmsudhi.github.io/cameleer/docs/components/file.html).
- Apache Camel: [Mail component](https://camel.apache.org/components/next/mail-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/quartz.html

# Quartz component

> The `quartz` component starts a route from a cron trigger or a simple repeating trigger, using Apache Camel's Quartz endpoint syntax.

**Scheme:** `quartz:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Quartz](https://camel.apache.org/components/next/quartz-component.html)

## When to use it

- Move existing Camel routes that use `quartz://group/name?cron=...` without changing them.
- Run a job on a cron schedule, such as syncing device configuration every 15 minutes.
- Fire N times at a fixed interval with a simple trigger (`trigger.repeatInterval`, `trigger.repeatCount`).

There is no Quartz scheduler underneath: each endpoint runs its own trigger thread with the same cron
engine as [cron](https://pmsudhi.github.io/cameleer/docs/components/cron.html). There is no job store and no clustering.

## URI format

```text
quartz:[group/]name?cron=expression[&options]
quartz:[group/]name?trigger.repeatInterval=ms&trigger.repeatCount=n
```

## Example

```yaml
- route:
    id: sync-devices
    from:
      uri: quartz:edge/sync-devices
      parameters:
        cron: "0 0/15 * * * ?"
        trigger.timeZone: UTC
      steps:
        - setBody:
            constant: sync
        - to: log:sync
```

The route fires at minute 0, 15, 30 and 45 of every hour, UTC.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("quartz:edge/sync-devices?cron=0+0/15+*+*+*+?&trigger.timeZone=UTC")
            .route_id("sync-devices")
            .set_body(constant("sync"))
            .to("log:sync");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `cron` | | Cron expression; without it the endpoint uses a simple trigger. |
| `trigger.timeZone` (or `timeZone`) | process default zone | Time zone of the cron expression. |
| `trigger.repeatInterval` | `1000` | Simple trigger: ms between fires. |
| `trigger.repeatCount` | `-1` | Simple trigger: extra fires after the first one. `-1` fires forever. |
| `triggerStartDelay` | `500` | ms before the first simple fire. |
| `fireNow` | `false` | Fire the simple trigger immediately at start. |
| `startDelayedSeconds` | `0` | Delay the start of the trigger by this many seconds. |
| `exchangePattern` | `InOnly` | `InOnly` or `InOut`. |
| `deleteJob`, `pauseJob`, `durableJob`, `stateful`, `recoverableJob`, `usingFixedCamelContextName`, `customCalendar`, `job.*`, other `trigger.*` | | Accepted and ignored (no Quartz job store). |

## Message headers

The same Quartz headers as [cron](https://pmsudhi.github.io/cameleer/docs/components/cron.html#message-headers): `fireTime`, `scheduledFireTime`,
`nextFireTime`, `previousFireTime`, `refireCount`, `jobRunTime`, `triggerName`, `triggerGroup`.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/sync.camel.yaml
```

## Common questions

### Should I use quartz or cron?

They share one engine. Use `quartz` to keep Camel URIs that already use it or for simple triggers, and
`cron` for new routes.

### Do quartz jobs survive a restart or run once in a cluster?

No. Without a Quartz job store, triggers live in the process. Run one instance for jobs that must run
once, or guard the job with an idempotent consumer.

## Related

- [cron](https://pmsudhi.github.io/cameleer/docs/components/cron.html), [timer](https://pmsudhi.github.io/cameleer/docs/components/timer.html), [scheduler](https://pmsudhi.github.io/cameleer/docs/components/scheduler.html)
- [Apache Camel Quartz component](https://camel.apache.org/components/next/quartz-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/rabbitmq.html

# RabbitMQ component

> The `rabbitmq` component sends and consumes RabbitMQ messages over AMQP 0-9-1 with the options of Apache Camel's older `camel-rabbitmq` component.

**Scheme:** `rabbitmq:` · **Crate:** `cameleer-amqp` · **Cargo feature:** [`amqp`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [RabbitMQ (Camel 3)](https://camel.apache.org/components/3.20.x/rabbitmq-component.html)

## When to use it

- Run routes written for Camel 2 or 3 `rabbitmq:` endpoints without rewriting them.
- Consume a RabbitMQ queue with manual acknowledgement (`autoAck=false`).
- Publish to an exchange with a routing key, publisher confirms or guaranteed delivery.

Apache Camel 4 replaced this component with [spring-rabbitmq](https://pmsudhi.github.io/cameleer/docs/components/spring-rabbitmq.html); Cameleer keeps both.

## URI format

```text
rabbitmq:exchangeName[?options]
rabbitmq://host:port/exchangeName[?options]     (Camel 2 style)
```

## Example

```yaml
- route:
    id: eu-orders
    from:
      uri: rabbitmq:orders
      parameters:
        hostname: "{{env:RABBITMQ_HOST:localhost}}"
        portNumber: "{{env:RABBITMQ_PORT:5672}}"
        username: "{{env:RABBITMQ_USER:guest}}"
        password: "{{env:RABBITMQ_PASSWORD:guest}}"
        queue: eu-orders
        routingKey: eu
        autoAck: false
        autoDelete: false
      steps:
        - log: "EU order: ${body}"
        - to: log:orders
```

The route declares the direct exchange `orders` and the queue `eu-orders` bound with key `eu`, and
acknowledges each message after the route has processed it.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("rabbitmq:orders?hostname=localhost&portNumber=5672&queue=eu-orders&routingKey=eu&autoAck=false&autoDelete=false")
            .route_id("eu-orders")
            .log("EU order: ${body}")
            .to("log:orders");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `hostname`, `portNumber` | `localhost`, `5672` | Broker address. |
| `addresses` | | `host:port` list; takes precedence over hostname and port. |
| `username`, `password`, `vhost` | `guest`, `guest`, `/` | Credentials and virtual host. |
| `queue` | | Queue to consume (comma separated for several). |
| `routingKey` | | Binding key / routing key. |
| `exchangeType` | `direct` | `direct`, `fanout`, `topic` or `headers`. |
| `declare` | `true` | Declare the exchange, queue and binding. |
| `durable` | `true` | Durable exchange and queue. |
| `autoDelete` | `true` | Auto-delete exchange and queue. |
| `exclusive`, `exclusiveConsumer` | `false` | Exclusive queue / consumer. |
| `autoAck` | `true` | Broker auto-ack. `false`: ack after success, reject on failure (requeued only when the exchange has header `CamelRabbitmqRequeue=true`). |
| `concurrentConsumers` | `1` | Consumer channels. |
| `prefetchEnabled`, `prefetchCount`, `prefetchGlobal` | `false`, `0`, `false` | `basic.qos` settings. |
| `deadLetterExchange`, `deadLetterQueue`, `deadLetterRoutingKey`, `deadLetterExchangeType` | | Dead letter topology. |
| `requestTimeout` | `20000` | InOut producer: wait (ms) for the reply. |
| `publisherAcknowledgements` | `false` | Wait for publisher confirms. |
| `publisherAcknowledgementsTimeout` | `5000` | ms to wait for a confirm. |
| `mandatory` | `false` | Publish with the mandatory flag. |
| `guaranteedDeliveries` | `false` | Confirms plus mandatory. |
| `bridgeEndpoint` | `false` | Ignore the `CamelRabbitmqRoutingKey` / `CamelRabbitmqExchangeName` headers of incoming messages. |
| `skipQueueDeclare`, `skipQueueBind`, `skipExchangeDeclare` | `false` | Skip parts of the declaration. |
| `arg.queue.*`, `arg.exchange.*`, `arg.binding.*` | | Declaration arguments. |
| `requestedHeartbeat` | `60` | Heartbeat in seconds. |
| `sslProtocol` | | `true`, `TLS`, `TLSv1.2` or `TLSv1.3` enables TLS (amqps). |
| `sslContextParameters`, `useGlobalSslContextParameters` | | TLS trust settings. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelRabbitmqRoutingKey` | in/out | Routing key (producer override unless `bridgeEndpoint`). |
| `CamelRabbitmqExchangeName` | in/out | Exchange (producer override unless `bridgeEndpoint`). |
| `CamelRabbitmqExchangeOverrideName` | in | Producer: exchange for this message. |
| `CamelRabbitmqDeliveryTag`, `CamelRabbitmqRedeliveryTag` | out | Consumer delivery information. |
| `CamelRabbitmqRequeue` | in | With `autoAck=false`: requeue a failed message. |
| `CamelRabbitmqRequestTimeout` | in | Producer: reply timeout for this message. |
| `CamelRabbitmqContentType`, `CamelRabbitmqCorrelationId`, `CamelRabbitmqMessageId`, `CamelRabbitmqPriority`, `CamelRabbitmqDeliveryMode`, `CamelRabbitmqExpiration`, `CamelRabbitmqTimestamp`, `CamelRabbitmqType`, `CamelRabbitmqUserId`, `CamelRabbitmqAppId`, `CamelRabbitmqReplyTo` | in/out | AMQP message properties. |

## Run it with Docker

```sh
docker run --rm -e RABBITMQ_HOST=rabbitmq -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

## Common questions

### Why does my queue disappear when the route stops?

`autoDelete` defaults to `true` in this component, as in Camel's. Set `autoDelete=false` for a lasting queue.

### How do I requeue a message that failed?

With `autoAck=false`, set the header `CamelRabbitmqRequeue` to `true` in the error handling; otherwise a
failed message is rejected without requeue.

## Related

- [spring-rabbitmq](https://pmsudhi.github.io/cameleer/docs/components/spring-rabbitmq.html), [amqp](https://pmsudhi.github.io/cameleer/docs/components/amqp.html)
- [Apache Camel RabbitMQ component (Camel 3)](https://camel.apache.org/components/3.20.x/rabbitmq-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/ref.html

# Ref component

> The `ref` component uses an endpoint looked up by name in the registry, so the real endpoint can be chosen at startup instead of in the route.

**Scheme:** `ref:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Ref](https://camel.apache.org/components/next/ref-component.html)

## When to use it

- Keep routes independent of the environment: bind `outbound` to `seda:outbound` in tests and to a
  broker URI in production.
- Share one configured endpoint object between several routes.

## URI format

```text
ref:name
```

The registry entry is either an endpoint (`Arc<dyn Endpoint>`) or a `String` holding an endpoint URI.

## Example

```yaml
- route:
    id: publish-events
    from:
      uri: direct:publish
      steps:
        - setHeader:
            name: source
            constant: edge-gw-1
        - to: ref:outbound
```

Bind `outbound` before starting:

```rust
ctx.registry().bind("outbound", "seda:outbound".to_string());
```

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.registry().bind("outbound", "seda:outbound".to_string());
    ctx.add_routes(|b| {
        b.from("direct:publish")
            .route_id("publish-events")
            .set_header("source", constant("edge-gw-1"))
            .to("ref:outbound");
    })
}
```

## Options

None. Options belong to the bound endpoint.

## Message headers

None added.

## Run it with Docker

The stock image has no way to bind registry entries from YAML, so `ref:` is used from Rust programs. In
a container, put the URI in a property placeholder instead: `to: "{{outbound.uri}}"`.

## Common questions

### What happens if nothing is bound under the name?

Creating the endpoint fails with a `NoSuchEndpointException`: "No bean could be found in the registry
for: name of type: Endpoint".

### Should I use ref or property placeholders?

Placeholders (`{{name}}`) work everywhere, including YAML-only deployments. `ref:` is useful when Rust
code builds or chooses the endpoint object.

## Related

- [bean](https://pmsudhi.github.io/cameleer/docs/components/bean.html), [direct](https://pmsudhi.github.io/cameleer/docs/components/direct.html)
- [Apache Camel Ref component](https://camel.apache.org/components/next/ref-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/rest.html

# REST component

> The `rest` component defines REST endpoints (the REST DSL, with a generated OpenAPI 3 document) and calls REST APIs with path templates filled from headers.

**Scheme:** `rest:` · **Crate:** `cameleer-http` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [REST](https://camel.apache.org/components/next/rest-component.html)

Most people use REST through the REST DSL: `rest` and `restConfiguration` blocks in YAML (or
`b.rest(...)` in Rust). Each verb becomes a [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html) route (or a
[jetty](https://pmsudhi.github.io/cameleer/docs/components/jetty.html) / [undertow](https://pmsudhi.github.io/cameleer/docs/components/undertow.html) / [netty-http](https://pmsudhi.github.io/cameleer/docs/components/netty-http.html) route, per
`restConfiguration.component`). The `rest:` URI scheme is the lower-level form of the same thing.

## When to use it

- Publish a JSON API with an OpenAPI document.
- Give an AI agent a set of tools: the agent reads the OpenAPI document to learn the
  operations and calls them over HTTP.
- Call a REST API whose path has parameters (`/orders/{id}`), filled from message headers.

## URI format

```text
rest:method:path[:uriTemplate][?options]
```

For example `rest:get:/orders/{id}` (consumer) or `rest:get:/orders/{id}?host=api.example.com`
(producer).

## Example: tools for an AI agent

Two inventory tools under `/tools`, with an OpenAPI 3 document at `/tools/openapi.json` that an
agent framework can load to discover them. `bindingMode: json` turns the route's result into
JSON.

```yaml
- restConfiguration:
    contextPath: /tools
    apiContextPath: /openapi.json
    bindingMode: json
- rest:
    path: /inventory
    get:
      - path: /{sku}
        id: getStock
        description: Current stock level of a product
        to: direct:getStock
    post:
      - path: /{sku}/reserve
        id: reserveStock
        description: Reserve units of a product for an order
        to: direct:reserveStock
- route:
    from:
      uri: direct:getStock
      steps:
        - setBody:
            simple: '{"sku": "${header.sku}", "inStock": 12}'
        - unmarshal:
            json: {}
- route:
    from:
      uri: direct:reserveStock
      steps:
        - setBody:
            simple: '{"sku": "${header.sku}", "reserved": ${body[qty]}}'
        - unmarshal:
            json: {}
```

With `bindingMode: json` the JSON request body arrives already parsed, so `${body[qty]}` reads
a field.

## Example: call a REST API

The `rest:` producer fills `{id}` from the `id` header and sends the request to `host`.

```yaml
- route:
    id: fetch-order
    from:
      uri: timer:fetch-order?repeatCount=1
      steps:
        - setHeader:
            name: id
            constant: "42"
        - to: "rest:get:/orders/{id}?host={{env:ORDERS_API:http://localhost:8080}}"
        - log: "order 42: ${body}"
```

## Rust DSL

```rust
fn agent_tools_routes(b: &mut RouteBuilder) {
    b.rest_configuration().context_path("/tools").api_context_path("/openapi.json").binding_mode(RestBindingMode::Json);
    b.rest("/inventory")
        .get("/{sku}").route_id("getStock").description("Current stock level of a product").to("direct:getStock")
        .post("/{sku}/reserve").route_id("reserveStock").description("Reserve units of a product for an order").to("direct:reserveStock");
    b.from("direct:getStock").set_body(simple(r#"{"sku": "${header.sku}", "inStock": 12}"#)).unmarshal_json();
    b.from("direct:reserveStock").set_body(simple(r#"{"sku": "${header.sku}", "reserved": ${body[qty]}}"#)).unmarshal_json();
}
```

## Options

`rest:` endpoint options:

| option | default | description |
|---|---|---|
| `host` | | Producer: target `host:port`, or `https://host` for TLS. Required for producers. |
| `producerComponentName` | `http` | Component that sends producer requests. |
| `componentName` | `camel.rest.component` or `platform-http` | Consumer: HTTP server component. |
| `port` | | Consumer port. |
| `consumes`, `produces` | | Media types. |

`inType`, `outType`, `routeId`, `description`, `apiDoc` and `bindingMode` are accepted on the
endpoint and ignored (use the REST DSL for binding).

`restConfiguration` keys in YAML: `component`, `host`, `port`, `scheme` (`https` for TLS),
`contextPath`, `apiContextPath` (default `/api-doc`), `bindingMode` (`off`, `auto`, `json`),
`enableCORS` and `corsHeaders`, `skipBindingOnErrorCode`, `endpointProperty`,
`consumerProperty`, `apiProperty`. Verbs take `path`, `id` (route id and OpenAPI
`operationId`), `description`, `consumes`, `produces`, `param`, `responseMessage`, `deprecated`,
`apiDocs`, `outType`, `tag`, and `to` / `toD` or inline `steps`.

Not supported: XML binding (`bindingMode: xml`) and `clientRequestValidation`.

## Message headers

| header | direction | description |
|---|---|---|
| path parameters (`sku`, `id`, ...) | out / in | Consumer: set from the request path. Producer: fill the `{name}` placeholders. |
| query parameters | out | Consumer: each becomes a header. |
| `CamelHttpResponseCode` | in | Consumer: response status. |
| `CamelHttpMethod`, `CamelHttpPath`, `CamelHttpQuery` | out | As for [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html#message-headers). |

## Run it with Docker

```sh
docker run --rm -p 8080:8080 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/agent-tools.camel.yaml
curl localhost:8080/tools/inventory/A-100
curl -XPOST -H 'Content-Type: application/json' -d '{"qty": 3}' localhost:8080/tools/inventory/A-100/reserve
curl localhost:8080/tools/openapi.json
```

## Common questions

### Where is the OpenAPI document?
At `<contextPath><apiContextPath>`, by default `/api-doc` (here `/tools/openapi.json`). It is an
OpenAPI 3.0.3 JSON document with one operation per verb.

### How do I return 201 or 400?
Set `CamelHttpResponseCode` in the route that handles the verb; with an `onException` handler
you can map errors to 400.

### How do I call an HTTPS API with `rest:`?
Use `host=https://api.example.com`; the request is sent with the `https` component.

### Which server does the REST DSL use?
`platform-http` unless `restConfiguration.component` names `jetty`, `undertow` or `netty-http`.

## Related

- [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html), [http](https://pmsudhi.github.io/cameleer/docs/components/http.html).
- [cxfrs](https://pmsudhi.github.io/cameleer/docs/components/cxfrs.html): JAX-RS style REST endpoints.
- Apache Camel: [REST component](https://camel.apache.org/components/next/rest-component.html),
  [REST DSL](https://camel.apache.org/manual/rest-dsl.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/rss.html

# RSS component

> The `rss` component polls an RSS feed (RSS 2.0, RSS 1.0 or Atom) and emits new entries as exchanges.

**Scheme:** `rss:` · **Crate:** `cameleer-saas` · **Cargo feature:** [`saas`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [RSS](https://camel.apache.org/components/next/rss-component.html)

Feeds and entries are maps. With `splitEntries=true` (the default) each exchange carries the feed
with only one entry in `entries`. For entry bodies, see [atom](https://pmsudhi.github.io/cameleer/docs/components/atom.html).

## When to use it

- Build a news or security-advisory digest that an AI agent summarizes.
- Watch vendor status pages, blogs or release feeds and alert a channel.
- Turn any RSS feed into events on a queue.

## URI format

```text
rss:feedUrl[?options]
```

The feed URL can be `http:`, `https:` or `file:`. Options the component does not know are added
to the feed URL's query, as in Apache Camel.

## Example

Every five minutes, take the new entries of a feed and queue their title and link for a
summarizing agent.

```yaml
- route:
    id: news-digest
    from:
      uri: "rss:{{env:FEED_URL:https://example.com/feed.xml}}?delay=300000&throttleEntries=false"
      steps:
        - setBody:
            simple: "${body[entries][0][title]} - ${body[entries][0][link]}"
        - to: seda:digest
- route:
    id: summarizer
    from:
      uri: seda:digest
      steps:
        - log: "new item: ${body}"
```

## Rust DSL

```rust
fn news_digest_routes(b: &mut RouteBuilder, feed_url: &str) {
    b.from(&format!("rss:{}?delay=300000&throttleEntries=false", feed_url))
        .route_id("news-digest")
        .set_body(simple("${body[entries][0][title]} - ${body[entries][0][link]}"))
        .to("seda:digest");
    b.from("seda:digest").route_id("summarizer").log("new item: ${body}");
}
```

## Options

| option | default | description |
|---|---|---|
| `splitEntries` | `true` | One exchange per entry; `false` sends the whole feed. |
| `filter` | `true` | Only entries newer than the last one delivered (entries without a date are delivered once). |
| `lastUpdate` | | Initial filter date, `yyyy-MM-ddTHH:mm:ss` (UTC). |
| `sortEntries` | `false` | Sort entries by date. |
| `throttleEntries` | `true` | Deliver one entry per poll; `false` delivers all new entries at once. |
| `feedHeader` | `true` | Put the whole feed in the `CamelRssFeed` header. |
| `delay` | `60000` | Milliseconds between polls (`initialDelay` 500 and the other scheduler options). |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelRssFeed` | out | The whole feed (with `feedHeader=true`). |

Feed map: `title`, `link`, `description`, `author`, `publishedDate`, `type` (`rss_2.0`,
`rss_1.0`, `atom_1.0`), `entries`. Entry map: `title`, `link`, `uri` (guid / id), `description`,
`contents`, `author`, `publishedDate`, `updatedDate`, `categories`.

## Run it with Docker

```sh
docker run --rm -e FEED_URL=https://www.example.com/news/rss.xml \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/news-digest.camel.yaml
```

## Common questions

### How do I get every new entry, not one per poll?
Set `throttleEntries=false`.

### Does it remember entries after a restart?
No. It remembers the last date in memory; use `lastUpdate` to skip old entries after a restart.

### Can it read Atom feeds?
Yes; `rss` parses Atom too. Use [atom](https://pmsudhi.github.io/cameleer/docs/components/atom.html) if you want the entry itself as the body.

## Related

- [atom](https://pmsudhi.github.io/cameleer/docs/components/atom.html), [http](https://pmsudhi.github.io/cameleer/docs/components/http.html).
- Apache Camel: [RSS component](https://camel.apache.org/components/next/rss-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/saga.html

# Saga component

> The `saga` component completes or compensates the current saga from a route, for sagas started with the Saga EIP.

**Scheme:** `saga:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Saga](https://camel.apache.org/components/next/saga-component.html)

## When to use it

- Undo earlier steps of a long-running business transaction when a later step fails (book hotel, charge
  card, cancel the hotel if the charge fails).
- End a saga with `completionMode: MANUAL` explicitly once an asynchronous confirmation arrives
  (`to: saga:complete`), or roll it back (`to: saga:compensate`).
- Give multi-step AI agent workflows an undo path for actions with side effects.

## URI format

```text
saga:complete
saga:compensate
```

## Example

```yaml
- route:
    id: book-trip
    from:
      uri: direct:book
      steps:
        - saga:
            compensation:
              uri: direct:cancel-booking
            option:
              - key: bookingId
                expression:
                  simple: "${body}"
            steps:
              - to: direct:reserve-hotel
              - to: direct:charge-card
- route:
    id: reserve-hotel
    from:
      uri: direct:reserve-hotel
      steps:
        - log: "hotel reserved for ${body}"
- route:
    id: charge-card
    from:
      uri: direct:charge-card
      steps:
        - filter:
            simple: "${body} contains 'declined'"
            steps:
              - throwException:
                  exceptionType: java.lang.IllegalStateException
                  message: card declined
- route:
    id: cancel-booking
    from:
      uri: direct:cancel-booking
      steps:
        - log: "cancelling ${header.bookingId}"
        - to: log:compensations
```

Booking `trip-1` completes. Booking `trip-2-declined` fails in `charge-card`, so the saga is compensated:
`direct:cancel-booking` is called with the header `bookingId: trip-2-declined` and the
`Long-Running-Action` header holding the saga id.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:book")
            .route_id("book-trip")
            .saga()
            .compensation("direct:cancel-booking")
            .option("bookingId", simple("${body}"))
            .to("direct:reserve-hotel")
            .to("direct:charge-card")
            .end();
        b.from("direct:reserve-hotel").route_id("reserve-hotel").log("hotel reserved for ${body}");
        b.from("direct:charge-card")
            .route_id("charge-card")
            .filter(simple("${body} contains 'declined'"))
            .throw_exception("java.lang.IllegalStateException", "card declined")
            .end();
        b.from("direct:cancel-booking")
            .route_id("cancel-booking")
            .log("cancelling ${header.bookingId}")
            .to("log:compensations");
    })
}
```

## Options

The `saga:` endpoint has no options; the path is `complete` or `compensate`. The Saga EIP block takes:

| setting | default | description |
|---|---|---|
| `propagation` | `REQUIRED` | `REQUIRED`, `REQUIRES_NEW`, `MANDATORY`, `SUPPORTS`, `NOT_SUPPORTED`, `NEVER`. |
| `completionMode` | `AUTO` | `AUTO` completes when the block succeeds; `MANUAL` waits for `saga:complete` or a timeout. |
| `compensation` | | Endpoint called (in reverse step order) when the saga is compensated. |
| `completion` | | Endpoint called when the saga completes. |
| `option` | | `key` plus an expression, evaluated when the step starts and passed to compensation and completion as headers. |
| `timeout` | | Compensate the saga when it is not finished in time (for example `5s`). |

The default saga service is in memory. A Narayana LRA compatible coordinator client is available from
Rust (`cameleer_core::processor::saga::lra::LraSagaService`).

## Message headers

| header | direction | description |
|---|---|---|
| `Long-Running-Action` | out | The saga id, on compensation and completion calls. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/trip.camel.yaml
```

## Common questions

### Are compensations retried if they fail?

The in-memory service calls each compensation endpoint once per saga step. Make compensation routes
idempotent and add an error handler with redelivery to them.

### Does the saga survive a restart?

Not with the in-memory service. Use an LRA coordinator for sagas that must survive restarts.

## Related

- [EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html)
- [direct](https://pmsudhi.github.io/cameleer/docs/components/direct.html)
- [Apache Camel Saga component](https://camel.apache.org/components/next/saga-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/scheduler.html

# Scheduler component

> The `scheduler` component starts a route repeatedly with a scheduled poll consumer: a delay between runs, optional back-off when idle, or a cron expression.

**Scheme:** `scheduler:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Scheduler](https://camel.apache.org/components/next/scheduler-component.html)

## When to use it

- Poll an inventory API, a database table or a mailbox with a fixed delay between polls.
- Slow down polling when there is nothing to do (`backoffMultiplier` with `backoffIdleThreshold`).
- Poll on a calendar schedule with `scheduler=quartz&scheduler.cron=...`.

The scheduler waits `delay` after a run finishes (fixed delay). Use [timer](https://pmsudhi.github.io/cameleer/docs/components/timer.html) for a fixed rate.

## URI format

```text
scheduler:name[?options]
```

## Example

```yaml
- route:
    id: poll-inventory
    from:
      uri: scheduler:inventory
      parameters:
        initialDelay: 1000
        delay: 60000
      steps:
        - setBody:
            constant: refresh
        - to: log:inventory
```

The route runs one second after startup and then one minute after each run finishes.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("scheduler:inventory?initialDelay=1000&delay=60000")
            .route_id("poll-inventory")
            .set_body(constant("refresh"))
            .to("log:inventory");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `initialDelay` | `1000` | Wait before the first poll (in `timeUnit`, or with a unit such as `5s`). |
| `delay` | `500` | Wait between polls. |
| `timeUnit` | `MILLISECONDS` | Unit of `initialDelay` and `delay` (`NANOSECONDS` ... `DAYS`). |
| `useFixedDelay` | `true` | Wait `delay` after each poll finishes; `false` schedules at a fixed rate. |
| `repeatCount` | `0` | Stop after this many polls. `0` polls forever. |
| `greedy` | `false` | Poll again at once when the previous poll processed messages. |
| `sendEmptyMessageWhenIdle` | `false` | Accepted for poll consumers that may find nothing; the scheduler always sends one exchange per poll. |
| `backoffMultiplier` | `0` | Skip this many polls after the idle or error threshold is reached. Required with the thresholds. |
| `backoffIdleThreshold` | `0` | Number of idle polls in a row before backing off. |
| `backoffErrorThreshold` | `0` | Number of failed polls in a row before backing off. |
| `runLoggingLevel` | `TRACE` | Log level of the "poll start/end" messages. |
| `startScheduler` | `true` | With `false`, the scheduler thread is not started. |
| `scheduler` | | `quartz` or `spring` (any value is accepted). Combined with `scheduler.cron`, polls happen at the cron fire times and the delays are ignored. |
| `scheduler.cron` | | A cron expression, see [cron](https://pmsudhi.github.io/cameleer/docs/components/cron.html). |
| `scheduler.timeZone` / `scheduler.trigger.timeZone` | process zone | Time zone of `scheduler.cron`. |
| `poolSize`, `synchronous`, `pollStrategy`, `bridgeErrorHandler`, `exceptionHandler`, `exchangePattern` | | Accepted and ignored. |

A route tells the scheduler that a poll found nothing by setting the exchange property
`CamelSchedulerPolledMessages` to `false`. This drives `greedy` and the idle back-off.

## Message headers

Each poll sends an exchange with a null body and the exchange properties `CamelTimerName` and
`CamelTimerFiredTime`.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/inventory.camel.yaml
```

## Common questions

### What is the difference between scheduler and timer?

Both start a route repeatedly. `scheduler` is a poll consumer: fixed delay after each run, greedy
polling and back-off. `timer` fires at fixed intervals and counts fires in `CamelTimerCounter`.

### How do I poll every weekday at 08:00?

`scheduler:report?scheduler=quartz&scheduler.cron=0+0+8+?+*+MON-FRI` (`+` is a space in a URI).

## Related

- [timer](https://pmsudhi.github.io/cameleer/docs/components/timer.html), [cron](https://pmsudhi.github.io/cameleer/docs/components/cron.html), [quartz](https://pmsudhi.github.io/cameleer/docs/components/quartz.html)
- [Apache Camel Scheduler component](https://camel.apache.org/components/next/scheduler-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/seda.html

# SEDA component

> The `seda` component hands messages to another route through a bounded in-memory queue, so the sender does not wait for the processing.

**Scheme:** `seda:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [SEDA](https://camel.apache.org/components/next/seda-component.html)

## When to use it

- Decouple a fast producer from slow work: accept a request, queue it, answer at once.
- Store and forward on an edge gateway: buffer sensor readings in memory while a slower uplink route
  forwards them (combine with [kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html) or [paho](https://pmsudhi.github.io/cameleer/docs/components/paho.html) for the uplink).
- Process messages in parallel with `concurrentConsumers`.
- Fan out one message to several routes with `multipleConsumers=true` (publish-subscribe).

## URI format

```text
seda:name[?options]
```

Endpoints with the same `name` share one queue inside a `CamelContext`. Use [vm](https://pmsudhi.github.io/cameleer/docs/components/vm.html) to share a
queue across contexts.

## Example

```yaml
- route:
    id: ingest-readings
    from:
      uri: direct:reading
      steps:
        - to: seda:readings?size=10000&blockWhenFull=true
        - setBody:
            constant: queued
- route:
    id: store-readings
    from:
      uri: seda:readings
      parameters:
        size: 10000
        concurrentConsumers: 2
      steps:
        - log: "storing ${body}"
        - to: log:stored
```

The caller of `direct:reading` gets `queued` back immediately. Two threads take readings off the queue
and process them. When 10000 readings are waiting, `blockWhenFull=true` makes the sender wait instead
of failing.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:reading")
            .route_id("ingest-readings")
            .to("seda:readings?size=10000&blockWhenFull=true")
            .set_body(constant("queued"));
        b.from("seda:readings?size=10000&concurrentConsumers=2")
            .route_id("store-readings")
            .log("storing ${body}")
            .to("log:stored");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `size` (alias `queueSize`) | `1000` | Maximum number of messages in the queue. Every endpoint that names a size for the same queue must use the same value. |
| `concurrentConsumers` | `1` | Number of threads consuming from the queue. |
| `waitForTaskToComplete` | `IfReplyExpected` | `Always`, `Never` or `IfReplyExpected`: whether the sender waits for the consumer to finish. InOut exchanges wait with the default. |
| `timeout` | `30000` | How long (ms) a waiting sender waits for the consumer. `0` waits forever. |
| `multipleConsumers` | `false` | Publish-subscribe: every consumer gets a copy of each message. Otherwise consumers compete. |
| `limitConcurrentConsumers` | `true` | Reject `concurrentConsumers` above 500. |
| `blockWhenFull` | `false` | When the queue is full, wait instead of failing. |
| `discardWhenFull` | `false` | When the queue is full, drop the message silently. |
| `offerTimeout` | `0` | With `blockWhenFull`, how long (ms) to wait for space. `0` waits forever. |
| `pollTimeout` | `1000` | How long (ms) a consumer thread waits for a message before checking for shutdown. |
| `purgeWhenStopping` | `false` | Empty the queue when the consumer stops. |
| `failIfNoConsumers` | `false` | Fail the send when no consumer is running. |
| `discardIfNoConsumers` | `false` | Drop the message when no consumer is running. |

## Message headers

The queue does not add headers. The consumer receives a copy of the exchange with a new exchange id
and the property `CamelCorrelationId` set to the sender's exchange id.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/readings.camel.yaml
```

## Common questions

### Are seda messages lost when the process stops?

Yes. The queue lives in memory. For durable store and forward, put the messages on a broker such as
[kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html), [amqp](https://pmsudhi.github.io/cameleer/docs/components/amqp.html) or [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html), or write them to files.

### How do I make every route get every message?

Set `multipleConsumers=true` on the consumers. Each consumer then gets its own copy, like a topic.

### What happens when the queue is full?

By default the send fails with an `IllegalStateException` ("Queue full"). Use `blockWhenFull=true` to
apply back pressure or `discardWhenFull=true` to drop new messages.

### Can I read a seda queue on demand?

Yes. seda endpoints support polling consumers, so `pollEnrich` and a consumer template can take one
message at a time.

## Related

- [direct](https://pmsudhi.github.io/cameleer/docs/components/direct.html), [vm](https://pmsudhi.github.io/cameleer/docs/components/vm.html), [stub](https://pmsudhi.github.io/cameleer/docs/components/stub.html)
- [EIPs](https://pmsudhi.github.io/cameleer/docs/guides/eips.html)
- [Apache Camel SEDA component](https://camel.apache.org/components/next/seda-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/sftp.html

# SFTP component

> The `sftp` component downloads files from and uploads files to an SSH server over SFTP, polling a remote directory for new files.

**Scheme:** `sftp:` · **Crate:** `cameleer-ssh` · **Cargo feature:** [`ssh`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [SFTP](https://camel.apache.org/components/next/sftp-component.html)

Cameleer has its own SSH-2 and SFTP v3 implementation (interop-tested against OpenSSH), with
password, public key, agent and certificate authentication. The consumer and producer options
and headers are those of [ftp](https://pmsudhi.github.io/cameleer/docs/components/ftp.html).

## When to use it

- Pick up files at remote or edge sites (stores, plants, field devices) that expose SFTP.
- Exchange files with partners and banks over SFTP.
- Push configuration or firmware files to devices.

## URI format

```text
sftp://[username@]host[:port]/directory[?options]
```

The directory is relative to the login (home) directory; `sftp://host//abs/dir` is absolute.
The default port is 22.

## Example

A central server collects JSON files that remote sites leave in `outbox/`, saves them locally
and deletes them on the site. The host key must match `known_hosts`
(`strictHostKeyChecking=yes`).

```yaml
- route:
    id: site-pickup
    from:
      uri: "sftp://{{env:SFTP_USER:edge}}@{{env:SFTP_HOST:localhost:22}}/outbox?password={{env:SFTP_PASSWORD:changeme}}&knownHostsFile={{env:KNOWN_HOSTS:known_hosts}}&strictHostKeyChecking=yes&include=.*\\.json&delete=true&delay=30000"
      steps:
        - log: "picked up ${file:name} from ${header.CamelFileHost}"
        - to: "file:{{env:LOCAL_DIR:incoming}}"
```

For key authentication, replace `password=...` with `privateKeyFile=/routes/id_ed25519` (and
`privateKeyPassphrase` for an encrypted key).

## Rust DSL

```rust
fn site_pickup_route(b: &mut RouteBuilder, sftp: &str, password: &str, known_hosts: &str, local_dir: &str) {
    b.from(&format!(
        "sftp://{}/outbox?password={}&knownHostsFile={}&strictHostKeyChecking=yes&include=.*\\.json&delete=true&delay=30000",
        sftp, password, known_hosts
    ))
    .route_id("site-pickup")
    .log("picked up ${file:name} from ${header.CamelFileHost}")
    .to(&format!("file:{}", local_dir));
}
```

## Options

Connection and authentication:

| option | default | description |
|---|---|---|
| `username`, `password` | `$USER` | Login (also `user[:password]@` in the URI). |
| `privateKeyFile`, `privateKeyUri`, `privateKey` | | Private key: path, `file:` URI, or key text / `#bean`. OpenSSH or PEM. |
| `privateKeyPassphrase` | | Passphrase of an encrypted key. |
| `useAgent`, `agentSocket` | `false` | Authenticate with an SSH agent (`SSH_AUTH_SOCK` or the given socket). |
| `certificateFile` | | OpenSSH user certificate for the key. |
| `knownHostsFile`, `knownHostsUri`, `knownHosts` | | `known_hosts` path, URI or text. |
| `useUserKnownHostsFile` | `true` | Also read `~/.ssh/known_hosts`. |
| `strictHostKeyChecking` | `no` | `yes`: the host key must be known. `no` (Apache Camel's default) accepts unknown hosts; changed or revoked keys are always rejected. |
| `preferredAuthentications` | | e.g. `publickey,keyboard-interactive,password`. |
| `ciphers`, `keyExchangeProtocols`, `serverHostKeys`, `macs`, `compressionAlgorithms` | | Algorithm lists. |
| `compression` | `0` | A level above 0 enables zlib compression. |
| `connectTimeout` | `10s` | Connect timeout. |
| `soTimeout` | `5m` | Read timeout. |
| `disconnect` | `false` | Close the connection after each poll or upload. |
| `sendNoop` | `true` | Check pooled connections before use. |
| `maximumReconnectAttempts`, `reconnectDelay` | 3, 1s | Reconnects. |
| `throwExceptionOnConnectFailed` | `false` | Fail the poll on connect errors. |
| `autoCreate` | `true` | Create the remote directory. |
| `bulkRequests` | `16` | Pipelined SFTP read / write requests. |
| `chmod`, `chmodDirectory` | | Octal permissions of uploaded files / created directories. |
| `charset` | | Text encoding of bodies. |

Consumer: the scheduler options (`delay` 500 ms, `initialDelay` 1000 ms, ...), `noop`, `delete`,
`move`, `moveFailed`, `preMove`, `include`, `exclude`, `includeExt`, `excludeExt`, `antInclude`,
`antExclude`, `antFilterCaseSensitive`, `fileName`, `recursive`, `minDepth`, `maxDepth`,
`maxMessagesPerPoll`, `sortBy`, `idempotent`, `idempotentKey`, `idempotentRepository`,
`download`, `ignoreFileNotFoundOrPermissionError`.

Producer: `fileName`, `fileExist`, `moveExisting`, `tempFileName`, `tempPrefix`,
`eagerDeleteTargetFile`, `allowNullBody`, `flatten`, `doneFileName`.

Not supported: `readLock` (accepted with a warning and ignored) and proxies.

## Message headers

The same as [ftp](https://pmsudhi.github.io/cameleer/docs/components/ftp.html#message-headers): `CamelFileName`, `CamelFileNameOnly`,
`CamelFileAbsolutePath`, `CamelFileRelativePath`, `CamelFilePath`, `CamelFileParent`,
`CamelFileLength`, `CamelFileLastModified`, `CamelFileNameConsumed`, `CamelFileHost`, and
`CamelFileNameProduced` on upload.

## Run it with Docker

```sh
ssh-keyscan -p 22 site7.example.com > known_hosts
docker run --rm --user "$(id -u):$(id -g)" -e SFTP_HOST=site7.example.com:22 -e SFTP_USER -e SFTP_PASSWORD \
  -e KNOWN_HOSTS=/routes/known_hosts -e LOCAL_DIR=/data/incoming -v "$PWD:/data" \
  -v "$PWD/site-pickup.camel.yaml:/routes/site-pickup.camel.yaml:ro" -v "$PWD/known_hosts:/routes/known_hosts:ro" \
  pmsudhi/cameleer run /routes/site-pickup.camel.yaml
```

## Common questions

### How do I log in with a private key?
`privateKeyFile=/path/id_ed25519`; add `privateKeyPassphrase=...` if it is encrypted. Ed25519,
ECDSA and RSA keys in OpenSSH or PEM format work.

### Why should I set strictHostKeyChecking=yes?
With the default `no`, the first host key seen is accepted, so a man in the middle on the first
connection is not detected. Provide `knownHostsFile` and `strictHostKeyChecking=yes` in
production.

### Can I upload with SFTP?
Yes: `to: sftp://user@host/inbox?password=...&tempPrefix=.part-`.

### How do I wait for a file to be fully written on the remote side?
`readLock` is not supported for SFTP. Have the sender write under a temporary name and rename the
file when it is complete, and match only the final names with `include`.

## Related

- [ssh](https://pmsudhi.github.io/cameleer/docs/components/ssh.html): run commands over SSH.
- [ftp](https://pmsudhi.github.io/cameleer/docs/components/ftp.html), [ftps](https://pmsudhi.github.io/cameleer/docs/components/ftps.html), [file](https://pmsudhi.github.io/cameleer/docs/components/file.html).
- Apache Camel: [SFTP component](https://camel.apache.org/components/next/sftp-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/slack.html

# Slack component

> The `slack` component posts messages to Slack channels (incoming webhook or the `chat.postMessage` Web API) and reads new channel messages by polling `conversations.history`.

**Scheme:** `slack:` · **Crate:** `cameleer-saas` · **Cargo feature:** [`saas`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Slack](https://camel.apache.org/components/next/slack-component.html)

## When to use it

- Post alerts, deployment notices or daily reports to a channel.
- Let an AI agent publish its summaries or answers to a team channel.
- React to messages people write in a channel (a support bot, a "deploy" keyword, a triage queue).
- Mirror a channel into another system (a ticket tracker, a database, a search index).

## URI format

```text
slack:#channel[?options]
slack://channel[?options]
```

The channel is a name (`#ops`, `general`) or a channel id (`C0123456`). The producer needs
either `webhookUrl` or `token`; the consumer always needs `token`.

## Example

Post a message with an incoming webhook. A text body becomes the message `text`; `username`
and `iconEmoji` are added to the webhook payload.

```yaml
- route:
    id: deploy-notice
    from:
      uri: "timer:deploy-notice?repeatCount=1"
      steps:
        - setBody:
            constant: "Deployment of checkout v42 finished"
        - to: "slack:#ops?webhookUrl={{env:SLACK_WEBHOOK_URL}}&username=cameleer&iconEmoji=:rocket:"
```

An AI agent that summarises an incident report with an LLM and posts the summary through the
Web API (`chat.postMessage` with a bot token). The Web API response is kept in the
`CamelSlackResponse` header.

```yaml
- route:
    id: incident-summary-to-slack
    from:
      uri: "direct:incident-report"
      steps:
        - to: "openai:chat-completion?model={{env:OPENAI_MODEL:gpt-4o-mini}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}&apiKey={{env:OPENAI_API_KEY}}&temperature=0&systemMessage=Summarise this incident report in two sentences for the on-call channel."
        - setBody:
            simple: ":memo: ${body}"
        - to: "slack:#general?token={{env:SLACK_TOKEN}}&serverUrl={{env:SLACK_API_URL:https://slack.com}}"
        - log: "posted to Slack at ts ${header.CamelSlackResponse[ts]}"
```

Read new messages from `#general`. Each message becomes one exchange whose body is the Slack
message object (`text`, `user`, `ts`, ...). The first poll delivers the latest `maxResults`
messages; later polls deliver only newer ones.

```yaml
- route:
    id: read-general
    from:
      uri: "slack://general?token={{env:SLACK_TOKEN}}&serverUrl={{env:SLACK_API_URL:https://slack.com}}&maxResults=20&naturalOrder=true&delay=5000"
      steps:
        - filter:
            simple: "${body[text]} contains 'deploy'"
            steps:
              - setBody:
                  simple: "${body[user]} asked: ${body[text]}"
              - to: "log:slack-deploy-requests"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:deploy-notice?repeatCount=1")
        .set_body(constant("Deployment of checkout v42 finished"))
        .to("slack:#ops?webhookUrl={{env:SLACK_WEBHOOK_URL}}&username=cameleer&iconEmoji=:rocket:");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `webhookUrl` | | Incoming webhook URL. When set, the producer posts to the webhook. |
| `token` | | Bot or user token (`xoxb-...`). Producer: `chat.postMessage`. Required by the consumer. |
| `username` | | Display name added to webhook payloads. |
| `iconUrl` | | Icon URL added to webhook payloads (`icon_url`). |
| `iconEmoji` | | Icon emoji added to webhook payloads (`icon_emoji`), e.g. `:rocket:`. |
| `maxResults` | `10` | Consumer: messages fetched per poll (`limit`). |
| `naturalOrder` | `false` | Consumer: deliver the oldest message first (Slack returns newest first). |
| `conversationType` | `PUBLIC_CHANNEL` | Consumer: channel type used to resolve the name: `PUBLIC_CHANNEL`, `PRIVATE_CHANNEL`, `MPIM`, `IM`. |
| `serverUrl` | `https://slack.com` | Web API base URL (Cameleer extension: a proxy, a gateway or a test server). |
| `delay`, `initialDelay`, ... | `delay=10000` | Consumer: the standard scheduled-poll options. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelSlackResponse` | out (producer) | The Web API response of `chat.postMessage` (`ok`, `channel`, `ts`). Not set for webhooks. |

The message body decides the payload: a text body is the message `text`; a map body is sent as
the whole payload (`blocks`, `attachments`, `thread_ts`, ...; `channel` is added when missing).

## Run it with Docker

```sh
export SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T000/B000/XXXX
docker run --rm -e SLACK_WEBHOOK_URL -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/deploy-notice.camel.yaml
```

## Common questions

### Webhook or token: which one should I use?

A webhook is the simplest: one URL, one channel, no scopes. Use a bot token (`chat:write`
scope, plus `channels:history` and `channels:read` for the consumer) when you need to post to
several channels, read messages, or get the message `ts` back for threads.

### How do I send blocks or reply in a thread?

Make the body a map, for example with `unmarshal: json` on a JSON string such as
`{"text":"fallback","thread_ts":"1700000001.000100","blocks":[...]}`. Map bodies are sent as the
payload unchanged.

### What happens when Slack rejects the message?

With a token, a response with `"ok": false` fails the exchange with an `ApiException` whose
message is the Slack error (`Slack: channel_not_found`). With a webhook, a non-2xx response fails
with `HttpOperationFailedException`. Use `onException` or `errorHandler` to retry.

### Is Slack's Socket Mode or Events API supported?

No. The consumer polls `conversations.history`. For push delivery, expose an HTTP endpoint with
[platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html) and point a Slack event subscription at it.

## Related

- [openai](https://pmsudhi.github.io/cameleer/docs/components/openai.html) for LLM summaries before posting, and the [AI components guide](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html)
- [jira](https://pmsudhi.github.io/cameleer/docs/components/jira.html), [github](https://pmsudhi.github.io/cameleer/docs/components/github.html), [telegram](https://pmsudhi.github.io/cameleer/docs/components/telegram.html)
- [Filter EIP](https://pmsudhi.github.io/cameleer/docs/guides/eips.html)
- [Apache Camel Slack component](https://camel.apache.org/components/next/slack-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/smtp.html

# SMTP component

> The `smtp` component sends email: the message body becomes the mail text and headers such as `To` and `Subject` set the recipients and subject.

**Scheme:** `smtp:` · **Also:** `smtps:` · **Crate:** `cameleer-protocols` · **Cargo feature:** [`protocols`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Mail](https://camel.apache.org/components/next/mail-component.html)

`smtps:` uses implicit TLS (port 465). Plain `smtp:` can upgrade with STARTTLS
(`mail.smtp.starttls.enable=true`). To read mail, use [imap](https://pmsudhi.github.io/cameleer/docs/components/imap.html) or [pop3](https://pmsudhi.github.io/cameleer/docs/components/pop3.html).

## When to use it

- Email a daily report produced at an edge site or by a batch job.
- Send alerts and notifications from any route.
- Let an AI agent send its summary or answer by mail.

## URI format

```text
smtp://[username@]host[:port][?options]
smtps://[username@]host[:port][?options]
```

Default ports: 25 (`smtp`), 465 (`smtps`).

## Example

Mail every text report that appears in the reports folder, with the file name in the subject.

```yaml
- route:
    id: mail-reports
    from:
      uri: "file:{{env:REPORTS_DIR:reports}}?include=.*\\.txt&move=.sent"
      steps:
        - setHeader:
            name: Subject
            simple: "Daily report ${file:name.noext}"
        - convertBodyTo:
            type: String
        - to: "smtp://{{env:SMTP_USER:reports}}@{{env:SMTP_HOST:localhost:25}}?password={{env:SMTP_PASSWORD:changeme}}&from={{env:MAIL_FROM:reports@example.com}}&to={{env:MAIL_TO:ops@example.com}}&mail.smtp.starttls.enable=true"
```

`mail.smtp.starttls.enable=true` upgrades to TLS when the server offers it; use
`mail.smtp.starttls.required=true` to refuse plain connections, or `smtps://` for port 465.

## Rust DSL

```rust
fn mail_reports_route(b: &mut RouteBuilder, reports_dir: &str, smtp: &str) {
    b.from(&format!("file:{}?include=.*\\.txt&move=.sent", reports_dir))
        .route_id("mail-reports")
        .set_header("Subject", simple("Daily report ${file:name.noext}"))
        .convert_body_to("String")
        .to(smtp);
}
```

## Options

| option | default | description |
|---|---|---|
| `username`, `password` | | Authenticate with `AUTH PLAIN` or `AUTH LOGIN`. |
| `from` | `camel@localhost` | Sender. |
| `to` | `username@host` | Recipients (comma-separated). |
| `cc`, `bcc` | | Copy recipients. |
| `replyTo` | | `Reply-To` address. |
| `subject` | | Subject. |
| `contentType` | `text/plain` | Content type of the body, e.g. `text/html`. |
| `connectionTimeout` | `30s` | Connect timeout. |
| `mail.smtp.starttls.enable` | `false` | Upgrade with STARTTLS when offered. |
| `mail.smtp.starttls.required` | `false` | Fail when STARTTLS is not offered. |
| `sslContextParameters` | | `#bean` with trust material for TLS. |
| `useGlobalSslContextParameters` | `false` | Use the global `camel.ssl.*` parameters. |

Other `mail.*` properties are accepted and ignored, as are `debugMode`, `peek` and similar
Apache Camel options.

## Message headers

| header | direction | description |
|---|---|---|
| `To`, `Cc`, `Bcc` | in | Recipients; override the options. |
| `From`, `Reply-To` | in | Sender and reply address. |
| `Subject` | in | Subject. |
| `Content-Type` | in | Content type of the body. |

Other headers with simple values (except `Camel*` ones) are added to the mail as headers.
Attachments come from the `CamelAttachments` exchange property (a map of file name to content)
and are sent as `multipart/mixed`.

## Run it with Docker

```sh
docker run --rm --user "$(id -u):$(id -g)" -e SMTP_HOST=smtp.example.com:587 -e SMTP_USER -e SMTP_PASSWORD \
  -e MAIL_TO=ops@example.com -e REPORTS_DIR=/data/reports -v "$PWD:/data" \
  -v "$PWD/mail-reports.camel.yaml:/routes/mail-reports.camel.yaml:ro" \
  pmsudhi/cameleer run /routes/mail-reports.camel.yaml
```

## Common questions

### How do I send HTML mail?
Set `contentType=text/html` or the `Content-Type` header to `text/html; charset=UTF-8`.

### How do I send to several people?
Comma-separate the addresses in `to` or in the `To` header; `Bcc` recipients are not shown in
the mail.

### How do I add an attachment?
Put a map of file name to content in the `CamelAttachments` exchange property.

### Which port: 25, 465 or 587?
465 is `smtps://` (implicit TLS). 587 and 25 are `smtp://` with
`mail.smtp.starttls.enable=true` (or `.required=true`).

## Related

- [imap](https://pmsudhi.github.io/cameleer/docs/components/imap.html), [pop3](https://pmsudhi.github.io/cameleer/docs/components/pop3.html): read mail.
- Apache Camel: [Mail component](https://camel.apache.org/components/next/mail-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/spring-rabbitmq.html

# Spring RabbitMQ component

> The `spring-rabbitmq` component sends messages to and consumes messages from RabbitMQ exchanges and queues over AMQP 0-9-1, with Apache Camel's `spring-rabbitmq` options.

**Scheme:** `spring-rabbitmq:` · **Crate:** `cameleer-amqp` · **Cargo feature:** [`amqp`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Spring RabbitMQ](https://camel.apache.org/components/next/spring-rabbitmq-component.html)

## When to use it

- Consume work from RabbitMQ queues with acknowledgements, retries and dead-lettering.
- Route telemetry by topic routing keys (`sensor.*`) from many devices to the right consumers.
- Request/reply over RabbitMQ: the producer waits for the answer on a temporary reply queue.
- Connect AI agent workers through a RabbitMQ work queue (competing consumers, `prefetchCount`).

The AMQP 0-9-1 client is built into Cameleer; no Spring or Java library is involved.

## URI format

```text
spring-rabbitmq:exchangeName[?options]
```

`default` or an empty name means the AMQP default exchange.

## Example

```yaml
- route:
    id: telemetry-consumer
    from:
      uri: spring-rabbitmq:telemetry
      parameters:
        host: "{{env:RABBITMQ_HOST:localhost}}"
        port: "{{env:RABBITMQ_PORT:5672}}"
        username: "{{env:RABBITMQ_USER:guest}}"
        password: "{{env:RABBITMQ_PASSWORD:guest}}"
        exchangeType: topic
        queues: edge-readings
        routingKey: "sensor.*"
      steps:
        - log: "${header.CamelRabbitmqRoutingKey}: ${body}"
        - to: log:telemetry
- route:
    id: telemetry-publisher
    from:
      uri: direct:reading
      steps:
        - to:
            uri: spring-rabbitmq:telemetry
            parameters:
              host: "{{env:RABBITMQ_HOST:localhost}}"
              port: "{{env:RABBITMQ_PORT:5672}}"
              username: "{{env:RABBITMQ_USER:guest}}"
              password: "{{env:RABBITMQ_PASSWORD:guest}}"
              exchangeType: topic
              routingKey: sensor.temperature
```

The consumer declares the topic exchange `telemetry`, the durable queue `edge-readings` and the binding
`sensor.*`. Messages sent to `direct:reading` are published with routing key `sensor.temperature` and
reach it.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("spring-rabbitmq:telemetry?host=localhost&port=5672&exchangeType=topic&queues=edge-readings&routingKey=sensor.*")
            .route_id("telemetry-consumer")
            .log("${header.CamelRabbitmqRoutingKey}: ${body}")
            .to("log:telemetry");
        b.from("direct:reading")
            .route_id("telemetry-publisher")
            .to("spring-rabbitmq:telemetry?host=localhost&port=5672&exchangeType=topic&routingKey=sensor.temperature");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `host`, `port` | `localhost`, `5672` | Broker address (Cameleer addition; Camel uses a `connectionFactory` bean). Also `spring.rabbitmq.host` / `port`. |
| `addresses` | | `host:port` list or `amqps://host:5671`; takes precedence over host and port. |
| `username`, `password`, `vhost` | `guest`, `guest`, `/` | Credentials and virtual host (also `spring.rabbitmq.*`). |
| `routingKey` | | Binding key (consumer) or routing key (producer). |
| `queues` | | Comma separated queues to consume. Without it, an exclusive server-named queue is used. |
| `exchangeType` | `direct` | `direct`, `fanout`, `topic` or `headers`. |
| `autoDeclare` | `true` | Consumer: declare the exchange, queues and bindings. |
| `autoDeclareProducer` | `false` | Producer: declare the exchange. |
| `durable` | `true` | Declare durable exchanges and queues. |
| `exclusive` | `false` | Declare exclusive queues. |
| `exclusiveConsumer` | `false` | Ask for an exclusive consumer. |
| `concurrentConsumers` | `1` | Consumer channels. |
| `acknowledgeMode` | `AUTO` | `AUTO` (ack on success, retry then reject on failure), `MANUAL` or `NONE` (broker auto-ack). |
| `prefetchCount` | `250` | `basic.qos` prefetch per consumer. |
| `maximumRetryAttempts` | `5` | `AUTO` mode: attempts before rejecting. |
| `retryDelay` | `1000` | ms between attempts. |
| `rejectAndDontRequeue` | `true` | Rejected messages are not requeued (they go to the dead letter exchange, if any). |
| `deadLetterExchange`, `deadLetterQueue`, `deadLetterRoutingKey`, `deadLetterExchangeType` | `direct` type | Dead letter topology, declared with the queue. |
| `replyTimeout` | `30000` | InOut producer: wait (ms) for the reply. |
| `disableReplyTo` | `false` | Ignore reply-to (consumer) / do not wait for a reply (producer). |
| `confirm` | `auto` | `enabled` waits for publisher confirms; `auto` / `disabled` do not. |
| `confirmTimeout` | `5000` | ms to wait for a confirm. |
| `allowNullBody` | `false` | Allow sending a null body. |
| `skipQueueDeclare`, `skipQueueBind`, `skipExchangeDeclare` | `false` | Skip parts of the declaration. |
| `arg.queue.*`, `arg.exchange.*`, `arg.binding.*` | | Declaration arguments, for example `arg.queue.x-message-ttl=60000`. |
| `requestedHeartbeat` | `60` | Heartbeat in seconds. |
| `requestedFrameMax`, `requestedChannelMax`, `connectionTimeout` | | Connection tuning. |
| `recoveryInterval` | `5000` | ms between reconnect attempts. |
| `sslContextParameters`, `useGlobalSslContextParameters` | | TLS (also enabled by an `amqps://` address or `spring.rabbitmq.ssl.enabled=true`). |

Spring-specific options with no meaning here (`connectionFactory`, `messageConverter`,
`maxConcurrentConsumers`, `messageListenerContainerType`, ...) are accepted and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelSpringRabbitmqRoutingOverrideKey` | in | Producer: routing key for this message. |
| `CamelSpringRabbitmqExchangeOverrideName` | in | Producer: exchange for this message. |
| `CamelSpringRabbitmqDeliveryTag` | out | Consumer: delivery tag. |
| `CamelRabbitmqRoutingKey`, `CamelRabbitmqExchangeName`, `CamelRabbitmqDeliveryTag`, `CamelRabbitmqRedeliveryTag` | out | Consumer: where the message came from. |
| `CamelRabbitmqContentType`, `CamelRabbitmqCorrelationId`, `CamelRabbitmqMessageId`, `CamelRabbitmqPriority`, `CamelRabbitmqDeliveryMode`, `CamelRabbitmqExpiration`, `CamelRabbitmqTimestamp`, `CamelRabbitmqType`, `CamelRabbitmqUserId`, `CamelRabbitmqAppId`, `CamelRabbitmqReplyTo`, `CamelRabbitmqContentEncoding`, `CamelRabbitmqClusterId` | in/out | AMQP message properties. |

Other headers (not starting with `Camel`) travel in the AMQP header table. String bodies are sent as
UTF-8 `text/plain`; maps and lists as JSON (`application/json`).

## Run it with Docker

```sh
docker run --rm -e RABBITMQ_HOST=rabbitmq -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/telemetry.camel.yaml
```

## Common questions

### How do I send failed messages to a dead letter queue?

Set `deadLetterExchange`, `deadLetterQueue` and optionally `deadLetterRoutingKey` on the consumer. After
`maximumRetryAttempts` the message is rejected and RabbitMQ moves it there.

### How do I do request/reply?

Send an InOut exchange (for example with `setExchangePattern: InOut`). The producer publishes with a
reply-to queue and waits up to `replyTimeout`; the consumer's result is sent back automatically.

### Should I use spring-rabbitmq or rabbitmq?

Use `spring-rabbitmq` for new routes (it is the Camel 4 component). [rabbitmq](https://pmsudhi.github.io/cameleer/docs/components/rabbitmq.html) keeps routes
written for the older Camel RabbitMQ component working.

## Related

- [rabbitmq](https://pmsudhi.github.io/cameleer/docs/components/rabbitmq.html), [amqp](https://pmsudhi.github.io/cameleer/docs/components/amqp.html), [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html)
- [Apache Camel Spring RabbitMQ component](https://camel.apache.org/components/next/spring-rabbitmq-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/spring-redis.html

# Spring Redis component

> The `spring-redis` component runs Redis commands (strings, hashes, lists, sets, sorted sets, geo, pub/sub) and subscribes to Redis channels.

**Scheme:** `spring-redis:` · **Crate:** `cameleer-datastores` · **Cargo feature:** [`datastores`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [Spring Redis](https://camel.apache.org/components/next/spring-redis-component.html)

## When to use it

- Short-term memory for an AI agent: append each conversation turn to a list per session and
  read the list back before the next model call.
- Cache expensive results (LLM answers, API lookups) with `SETEX` and read them with `GET`.
- Counters, rate limits and leaderboards with `INCR` and sorted sets.
- Lightweight messaging: publish to a channel, or consume a channel with `SUBSCRIBE` and
  `PSUBSCRIBE`.

The name comes from Apache Camel, where the component is built on Spring Data Redis. Cameleer
has no Spring: it has its own RESP2/RESP3 client, and keeps the scheme, options and headers so
Camel routes run unchanged.

## URI format

```text
spring-redis://host:port[?options]
```

The port defaults to 6379. The producer runs `command` (default `SET`, header
`CamelRedis.Command` overrides it) with arguments from the `CamelRedis.*` headers and puts the
reply in the body. Commands that return nothing in Spring Data Redis (`SET`, `HSET`, `PUBLISH`,
...) keep the body.

## Example

`POST /memory?session=s1` appends the request body to the session's list. The reply of `RPUSH`,
the new length of the list, becomes the response.

```yaml
- route:
    id: remember
    from:
      uri: "platform-http:/memory?httpMethodRestrict=POST"
      steps:
        - setHeader:
            name: CamelRedis.Key
            simple: "memory:${header.session}"
        - setHeader:
            name: CamelRedis.Value
            simple: "${body}"
        - to: "spring-redis://{{env:REDIS_HOST:localhost}}:6379?command=RPUSH"
```

`GET /memory?session=s1` returns every turn of the session as a JSON array, oldest first.

```yaml
- route:
    id: recall
    from:
      uri: "platform-http:/memory?httpMethodRestrict=GET"
      steps:
        - setHeader:
            name: CamelRedis.Key
            simple: "memory:${header.session}"
        - setHeader:
            name: CamelRedis.Start
            constant: 0
        - setHeader:
            name: CamelRedis.End
            constant: -1
        - to: "spring-redis://{{env:REDIS_HOST:localhost}}:6379?command=LRANGE"
        - marshal:
            json: {}
```

This route subscribes to the `alerts` channel and logs every message.

```yaml
- route:
    id: alerts
    from:
      uri: "spring-redis://{{env:REDIS_HOST:localhost}}:6379?command=SUBSCRIBE&channels=alerts"
      steps:
        - to: "log:alerts"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("direct:cache-answer")
        .set_header("CamelRedis.Key", simple("answer:${header.questionId}"))
        .set_header("CamelRedis.Value", simple("${body}"))
        .set_header("CamelRedis.Timeout", constant(3600))
        .to("spring-redis://localhost:6379?command=SETEX");
    b.from("spring-redis://localhost:6379?command=PSUBSCRIBE&channels=orders.*")
        .log("${header[CamelRedis.Channel]}: ${body}");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `command` | `SET` | command to run (header `CamelRedis.Command` overrides it); `SUBSCRIBE` or `PSUBSCRIBE` for the consumer |
| `channels` | | consumer: comma-separated channels or patterns |
| `password` | | `AUTH` password |
| `username` | | ACL user name (Redis 6+) |
| `database` | `0` | `SELECT` this database |
| `protocol` | `2` | `3` switches to RESP3 with `HELLO 3` |
| `connectTimeout` | `10s` | connect timeout |
| `timeout` | `30s` | reply timeout |
| `serializer` | text | `string`, `json` (values written as JSON, replies parsed), `bytes` (replies stay bytes) or a `#bean` |
| `redisTemplate`, `connectionFactory` | | `#bean` of type `RedisClient` to share a connection |
| `ssl` | `false` | TLS (or `sslContextParameters=#bean`, `useGlobalSslContextParameters=true`) |
| `sentinels` | | Redis Sentinel addresses (`host:port,...`); the master is resolved through them |
| `sentinelMaster` | `mymaster` | Sentinel master name (also `masterName`) |
| `cluster` | `false` | Redis Cluster: route by key slot and follow `MOVED` and `ASK` redirections |

`listenerContainer` is accepted and ignored. Java serialization (Camel's default
`JdkSerializationRedisSerializer`) does not exist here: the default writes text (bytes as is,
lists and maps as JSON) and returns text replies, or bytes when a reply is not UTF-8.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelRedis.Command` | in | command for this exchange |
| `CamelRedis.Key`, `CamelRedis.Keys` | in | key, or keys for `DEL`, `SUNION`, ... |
| `CamelRedis.Field`, `CamelRedis.Fields` | in | hash field(s) |
| `CamelRedis.Value`, `CamelRedis.Values` | in | value, or values (`MSET` takes a map) |
| `CamelRedis.Timeout` | in | seconds for `EXPIRE`, `SETEX`, blocking pops |
| `CamelRedis.Start`, `CamelRedis.End` | in | ranges for `LRANGE`, `ZRANGE`, `GETRANGE` |
| `CamelRedis.Index`, `CamelRedis.Offset`, `CamelRedis.Count` | in | positions and counts |
| `CamelRedis.Destination` | in | target key (`RPOPLPUSH`, `SMOVE`, ...) |
| `CamelRedis.Channel`, `CamelRedis.Message` | in | `PUBLISH` channel and message |
| `CamelRedis.Pivot`, `CamelRedis.Position` | in | `LINSERT` arguments |
| `CamelRedis.Pattern` | in | pattern for `KEYS` |
| `CamelRedis.Timestamp`, `CamelRedis.Db` | in | `EXPIREAT`, `MOVE` arguments |
| `CamelRedis.Score`, `CamelRedis.Min`, `CamelRedis.Max`, `CamelRedis.Increment`, `CamelRedis.WithScore` | in | sorted-set arguments |
| `CamelRedis.Longitude`, `CamelRedis.Latitude`, `CamelRedis.Radius` | in | geo arguments (radius in meters) |
| `CamelRedis.Channel` | out | consumer: channel of the message |
| `CamelRedis.Pattern` | out | consumer: matching pattern for `PSUBSCRIBE` |

Unknown commands are sent as they are, with the key and values as arguments.

## Run it with Docker

```sh
docker run --rm -p 8080:8080 -e REDIS_HOST=redis.example.com \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/memory.camel.yaml
```

## Common questions

### How do I cache a value with an expiry?

Use `command=SETEX` with the headers `CamelRedis.Key`, `CamelRedis.Value` and
`CamelRedis.Timeout` (seconds). Read it back with `GET`; a missing key gives a null body.

### How do I store JSON objects?

Set `serializer=json`: maps and lists are written as JSON and replies are parsed back into maps
and lists.

### Does it work with Redis Cluster, Sentinel or managed Redis?

Cluster (`cluster=true`) and Sentinel (`sentinels=...`) are supported, with AUTH, ACL users and
TLS (`ssl=true`). Live tests run against Redis 7.0; other RESP servers are not tested.

## Related

- [Idempotent consumer EIP](https://pmsudhi.github.io/cameleer/docs/guides/eips.html): Cameleer also has a Redis idempotent repository.
- [Apache Camel Spring Redis component](https://camel.apache.org/components/next/spring-redis-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/spring-ws.html

# Spring Web Services component

> The `spring-ws` component hosts and calls payload-oriented SOAP web services: consumers are selected by the payload root element, SOAP action, XPath or WS-Addressing, and the body is the payload XML.

**Scheme:** `spring-ws:` · **Crate:** `cameleer-soap` · **Cargo feature:** [`soap`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Spring Web Services](https://camel.apache.org/components/next/spring-ws-component.html)

No Spring is involved: the scheme reproduces camel-spring-ws on Cameleer's HTTP server. Unlike
[cxf](https://pmsudhi.github.io/cameleer/docs/components/cxf.html), there is no WSDL and no parameter mapping; routes work with the XML payload.

## When to use it

- Host a contract-first SOAP service where the route builds the XML response itself.
- Route different SOAP requests arriving at one address to different routes by root element or
  SOAP action.
- Send a payload to a SOAP service and get the response payload back.

## URI format

```text
spring-ws:rootqname:{namespace}localName[?options]      (consumer)
spring-ws:soapaction:action[?options]                   (consumer)
spring-ws:uri:http://host:port/path                     (consumer: every request to the address)
spring-ws:xpathresult:value?expression=xpath[&options]  (consumer)
spring-ws:action:wsaAction / spring-ws:to:wsaTo         (consumer, WS-Addressing)
spring-ws:beanname:mappingBean                          (consumer)
spring-ws:http://host:port/path[?options]               (producer)
```

Consumers listen on `address` (default `/ws` on the platform HTTP port). All consumers on one
address share a dispatcher; a request that matches none gets `404`.

## Example

An order status service. Requests whose payload root is `{urn:orders}GetOrderStatus` reach this
route; the order id is read with XPath and the response payload is built with Simple.

```yaml
- route:
    id: order-status
    from:
      uri: "spring-ws:rootqname:{urn:orders}GetOrderStatus?address=http://0.0.0.0:{{env:SOAP_PORT:8088}}/ws"
      steps:
        - setHeader:
            name: orderId
            xpath: "//*[local-name()='id']/text()"
        - setBody:
            simple: '<GetOrderStatusResponse xmlns="urn:orders"><id>${header.orderId}</id><status>shipped</status></GetOrderStatusResponse>'
```

A client sends `<GetOrderStatus xmlns="urn:orders"><id>42</id></GetOrderStatus>` with
`spring-ws:http://host:8088/ws` and gets the response payload back.

## Rust DSL

```rust
fn order_status_route(b: &mut RouteBuilder, port: u16) {
    b.from(&format!("spring-ws:rootqname:{{urn:orders}}GetOrderStatus?address=http://0.0.0.0:{}/ws", port))
        .route_id("order-status")
        .set_header("orderId", xpath("//*[local-name()='id']/text()"))
        .set_body(simple(r#"<GetOrderStatusResponse xmlns="urn:orders"><id>${header.orderId}</id><status>shipped</status></GetOrderStatusResponse>"#));
}
```

## Options

| option | default | description |
|---|---|---|
| `address` | `/ws` on the platform port | Consumer: `http(s)://host:port/path` or a path. |
| `expression` | | `xpathresult`: XPath evaluated on the payload. |
| `namespaces` | | Namespace prefixes for `expression`. |
| `soapAction` | | Producer: SOAP action. |
| `wsAddressingAction` | | Producer: WS-Addressing `Action`. |
| `soapVersion` | `1.1` | Producer: `1.1` or `1.2`. |
| `timeout` | | Producer: timeout in ms. |
| `username`, `password` | | Producer: basic authentication. |
| `sslContextParameters` | | `#bean` for `https`. |
| `wsSecurityUsername`, ... | | The WS-Security options of [cxf](https://pmsudhi.github.io/cameleer/docs/components/cxf.html#options). |

Spring message factories and interceptors are accepted and ignored. SOAP attachments are not
supported.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelSpringWebserviceSoapAction` | out / in | SOAP action of the request; producer: overrides `soapAction`. |
| `CamelSpringWebserviceSoapHeader` | out / in | SOAP header blocks. |
| `CamelSpringWebserviceAddressingAction` | out / in | WS-Addressing action. |
| `CamelSpringWebserviceEndpointUri` | in | Producer: overrides the target address. |

A null reply body answers `202`; an exception becomes a SOAP fault. On the producer, a fault
fails the exchange with `SoapFaultClientException`.

## Run it with Docker

```sh
docker run --rm -p 8088:8088 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/order-status.camel.yaml
curl -XPOST -H 'Content-Type: text/xml' localhost:8088/ws -d \
  '<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><GetOrderStatus xmlns="urn:orders"><id>42</id></GetOrderStatus></s:Body></s:Envelope>'
```

## Common questions

### How is this different from cxf?
`cxf` maps typed parameters from a WSDL; `spring-ws` hands the route the XML payload and sends
back whatever XML the route produces.

### How do I serve several operations at one address?
Add one route per root element or SOAP action, all with the same `address`.

### How do I return a SOAP fault?
Throw an exception in the route; it becomes a `Server` (1.1) / `Receiver` (1.2) fault.

## Related

- [cxf](https://pmsudhi.github.io/cameleer/docs/components/cxf.html), [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html).
- Apache Camel: [Spring Web Services component](https://camel.apache.org/components/next/spring-ws-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/sql.html

# SQL component

> The `sql` component runs SQL queries and updates against PostgreSQL or the embedded in-memory database, and polls tables for new rows.

**Scheme:** `sql:` · **Crate:** `cameleer-sql` · **Cargo feature:** [`sql`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** yes · **Producer:** yes ·
**Apache Camel:** [SQL](https://camel.apache.org/components/next/sql-component.html)

## When to use it

- Insert or update rows from a route: save orders received over HTTP, keep an audit table of
  the decisions an AI agent made, store an LLM's classification next to the ticket.
- Poll a table as a work queue: pick up rows where `processed = false`, route each one, and
  mark it done with `onConsume`.
- Look up reference data in the middle of a route (`outputType=SelectOne`).
- Prototype without a database server: `jdbc:rustsql:mem:<name>` is an embedded in-memory SQL
  engine with the PostgreSQL dialect, so the same routes later run against PostgreSQL.

## URI format

```text
sql:<statement>[?options]
sql:file:<path-to-sql-file>[?options]
```

The statement uses Camel's parameter syntax:

| placeholder | value |
|---|---|
| `:#name` | `name` from the body (when it is a map), else a header, an exchange property or a variable |
| `:#${simple}` | the result of a Simple expression, for example `:#${header.id}` |
| `:#in:name` | a list, expanded to `?, ?, ...` for `IN (...)` |
| `?` or `#` | positional, taken in order from the body (a list, or a string split by `separator`) |

### Choosing the database

`dataSource` names the database. It is either a JDBC-style URL or a registry bean:

| value | database |
|---|---|
| `jdbc:rustsql:mem:shop` | the embedded in-memory engine; every endpoint with the same name shares one database |
| `jdbc:postgresql://user:password@host:5432/db` | PostgreSQL over its wire protocol (SCRAM-SHA-256, MD5 or cleartext authentication, TLS with `?sslmode=require` or `verify-full`) |
| `#name` | a data source bound in the registry |

Without `dataSource`, the endpoint uses the only data source in the registry. Cameleer binds one
named `dataSource` from the `camel.datasource.url` property (with `camel.datasource.username`
and `camel.datasource.password`), which the container also reads from the
`CAMEL_DATASOURCE_URL` environment variable. `camel.datasource.<name>.url` binds more data
sources by name. Other databases (MySQL, Oracle, SQL Server) are not supported: there are no
JDBC drivers, only these two engines.

A PostgreSQL data source is a connection pool, sized in its URL like HikariCP:
`?poolSize=16` opens at most 16 connections (default 8) and reuses them. When all of them are
busy, a caller waits for one to come back, up to `poolTimeout` seconds (default 30), then fails
with `Connection is not available`. Size the pool for the database, not for the number of
concurrent requests: PostgreSQL handles a few busy connections better than many.

## Example

This route polls a table as a work queue: every new order is logged once and marked as
processed. A one-shot timer route creates the table first, so the file runs as is against the
embedded database or against PostgreSQL.

```yaml
- route:
    id: create-schema
    from:
      uri: "timer:schema?repeatCount=1&delay=0"
      steps:
        - to: "sql:create table if not exists orders (id serial primary key, item text, qty int, processed boolean default false)?dataSource={{env:DB_URL:jdbc:rustsql:mem:shop}}"
- route:
    id: new-orders
    from:
      uri: "sql:select * from orders where processed = false order by id?dataSource={{env:DB_URL:jdbc:rustsql:mem:shop}}&onConsume=update orders set processed = true where id = :#id&delay=2000"
      steps:
        - log: "new order ${body[id]}: ${body[qty]} x ${body[item]}"
```

Each row arrives as a map (`${body[item]}`), one exchange per row. `onConsume` runs once per row
after the route finished it, with the row's columns as `:#` parameters.

This route saves JSON orders posted over HTTP. The fields of the JSON object fill the `:#item`
and `:#qty` parameters, and the response reports the number of inserted rows.

```yaml
- route:
    id: save-order
    from:
      uri: "platform-http:/orders?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - to: "sql:insert into orders (item, qty) values (:#item, :#qty)?dataSource={{env:DB_URL:jdbc:rustsql:mem:shop}}"
        - setBody:
            simple: "inserted ${header.CamelSqlUpdateCount}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("direct:save-order")
        .to("sql:insert into orders (item, qty) values (:#item, :#qty)?dataSource=jdbc:rustsql:mem:shop");
    b.from("direct:find-order")
        .to("sql:select item, qty from orders where id = :#${header.id}?dataSource=jdbc:rustsql:mem:shop&outputType=SelectOne");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `dataSource` | the only data source in the registry | a JDBC-style URL or `#bean` (also `dataSourceRef`) |
| `outputType` | `SelectList` | `SelectList` (list of row maps), `SelectOne` (one row map, or the value when there is one column; more than one row is an error) or `StreamList` (read fully into a list) |
| `outputHeader` | | store the query result in this header and keep the body |
| `noop` | `false` | run the statement but keep the body |
| `batch` | `false` | the body is a list; run the statement once per element, in one transaction |
| `useMessageBodyForSql` | `false` | the SQL is the message body; positional values come from the `CamelSqlParameters` header |
| `parametersCount` | `0` | number of positional parameters to bind (0 = as many as the statement has) |
| `placeholder` | `#` | extra positional placeholder character next to `?` |
| `usePlaceholder` | `true` | whether `placeholder` is recognised |
| `separator` | `,` | splits a string body into positional values |
| `allowNamedParameters` | `true` | recognise `:#name` parameters |
| `template.maxRows` | `0` | stop reading after this many rows (0 = all) |
| `useIterator` | `true` | consumer: one exchange per row; `false` sends all rows as one list (header `CamelSqlRowCount`) |
| `onConsume` | | consumer: statement run per row after it was processed successfully |
| `onConsumeFailed` | | consumer: statement run per row when processing failed |
| `onConsumeBatchComplete` | | consumer: statement run once after all rows of a poll |
| `maxMessagesPerPoll` | `0` | consumer: at most this many rows per poll (0 = all) |
| `routeEmptyResultSet` | `false` | consumer: route an empty list when the query returns no rows |
| `transacted` | `false` | consumer: run each poll in one transaction, rolled back when a row fails |
| `breakBatchOnConsumeFail` | `false` | consumer: stop the poll when `onConsume` fails |
| `expectedUpdateCount` | `-1` | consumer: fail when `onConsume` changes a different number of rows |
| `delay`, `initialDelay`, `repeatCount`, ... | `500` ms, `1000` ms | consumer: the scheduled poll options |

`outputClass`, `processingStrategy`, `prepareStatementStrategy`, `alwaysPopulateStatement` and
`rowMapperFactory` are accepted for compatibility and ignored: rows are always maps.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelSqlQuery` | in | SQL to run instead of the endpoint's statement |
| `CamelSqlParameters` | in | positional values when `useMessageBodyForSql=true` |
| `CamelSqlRetrieveGeneratedKeys` | in | `true` to return the generated keys of an INSERT |
| `CamelSqlUpdateCount` | out | rows changed by INSERT, UPDATE or DELETE (the total for `batch`) |
| `CamelSqlRowCount` | out | rows returned by a SELECT |
| `CamelSqlGeneratedKeysRowCount` | out | number of generated key rows |
| `CamelSqlGeneratedKeysRows` | out | the generated keys, a list of maps |

The consumer sets the exchange properties `CamelBatchIndex`, `CamelBatchSize` and
`CamelBatchComplete`.

## Run it with Docker

Against the embedded database (data is lost when the container stops):

```sh
docker run --rm -p 8080:8080 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

Against PostgreSQL:

```sh
docker run --rm -p 8080:8080 \
  -e DB_URL='jdbc:postgresql://camel:secret@db.example.com:5432/shop?sslmode=require' \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/orders.camel.yaml
```

## Common questions

### How do I connect to PostgreSQL?

Set `dataSource=jdbc:postgresql://user:password@host:5432/db`, or set `camel.datasource.url`
(environment variable `CAMEL_DATASOURCE_URL`) and leave `dataSource` out. URL-encode special
characters in the password.

### How do I get the id of an inserted row?

Set the header `CamelSqlRetrieveGeneratedKeys` to `true`. The keys come back in
`CamelSqlGeneratedKeysRows`, for example `[{id=7}]`. On PostgreSQL you can also write
`insert ... returning id` and read the result as a query.

### How do I process each row only once?

Use `onConsume` to mark the row (`update ... set processed = true where id = :#id`) and filter on
that column in the polling query. Add `transacted=true` to roll the marks back when a row fails.

### Does it support MySQL or Oracle?

No. Cameleer has no JDBC drivers: it speaks the PostgreSQL wire protocol (tested against
PostgreSQL 16) and embeds its own engine.

## Related

- [sql-stored](https://pmsudhi.github.io/cameleer/docs/components/sql-stored.html): call stored procedures and functions.
- [jdbc](https://pmsudhi.github.io/cameleer/docs/components/jdbc.html): run SQL taken from the message body.
- [Apache Camel SQL component](https://camel.apache.org/components/next/sql-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/sql-stored.html

# SQL Stored Procedure component

> The `sql-stored` component calls stored procedures and functions in PostgreSQL or the embedded database, passing IN parameters and returning OUT values and result sets.

**Scheme:** `sql-stored:` · **Crate:** `cameleer-sql` · **Cargo feature:** [`sql`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [SQL Stored Procedure](https://camel.apache.org/components/next/sql-stored-component.html)

## When to use it

- Keep business rules in the database: call a procedure that validates and inserts an order
  and returns a running total.
- Call a set-returning function (`RETURNS TABLE`) and route the rows.
- Reuse existing PL/pgSQL code from an integration route or an AI agent's tool call without
  rewriting it.

## URI format

```text
sql-stored:<template>[?options]
sql-stored:file:<path-to-template-file>[?options]
```

The template follows Camel's syntax: `NAME(parameter, parameter, ...)`.

| parameter | form | example |
|---|---|---|
| IN | `[IN] TYPE[(scale)] valueSource` | `INTEGER ${header.qty}`, `VARCHAR :#item` |
| OUT | `OUT TYPE name` | `OUT INTEGER total` |
| INOUT | `INOUT TYPE valueSource name` | `INOUT INTEGER ${body[qty]} qty` |

`TYPE` is a `java.sql.Types` name (`INTEGER`, `BIGINT`, `VARCHAR`, `DECIMAL(10)`, `BOOLEAN`, ...)
or its numeric code; IN values are converted to it. A value source is a Simple expression
(`${header.num}`, `${body[qty]}`), `:#name` (a body map entry, then a header, an exchange
property or a variable), `:#${simple}`, or a literal (`5`, `'text'`).

A procedure is called as `CALL name(?, ?, NULL)` (OUT positions are passed as `NULL`, as
PostgreSQL 14 and later expect). With `function=true` it is called as
`SELECT * FROM name(?, ?)` and the first OUT parameter names the return value.

The database is chosen with `dataSource`, exactly as for the [sql](https://pmsudhi.github.io/cameleer/docs/components/sql.html) component: a
`jdbc:rustsql:mem:<name>` or `jdbc:postgresql://user:password@host:port/db` URL, a `#bean`, or
the only data source in the registry.

## Example

The procedure, in PostgreSQL or the embedded engine:

```sql
create table orders (id serial primary key, item text, qty int);
create procedure add_order(in p_item text, in p_qty integer, out total integer)
language plpgsql as $$
begin
  if p_qty <= 0 then raise exception 'invalid quantity % for %', p_qty, p_item; end if;
  insert into orders (item, qty) values (p_item, p_qty);
  select sum(qty) into total from orders;
end $$;
```

The route takes a JSON order over HTTP, calls the procedure and answers with its OUT value.

```yaml
- route:
    id: add-order
    from:
      uri: "platform-http:/orders?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - to: "sql-stored:add_order(VARCHAR :#item, INTEGER :#qty, OUT INTEGER total)?dataSource={{env:DB_URL:jdbc:rustsql:mem:shop}}"
        - marshal:
            json: {}
```

Posting `{"item":"camel","qty":3}` answers `{"total":3}`. A `raise exception` in the procedure
fails the exchange with an `SQLException` that carries the message.

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("direct:add-order")
        .to("sql-stored:add_order(VARCHAR :#item, INTEGER :#qty, OUT INTEGER total)?dataSource=jdbc:rustsql:mem:shop");
    b.from("direct:big-orders")
        .to("sql-stored:orders_over(INTEGER ${header.min})?dataSource=jdbc:rustsql:mem:shop&function=true");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `dataSource` | the only data source in the registry | a JDBC-style URL or `#bean` (also `dataSourceRef`) |
| `function` | `false` | call a function (`SELECT * FROM name(...)`) instead of a procedure |
| `outputType` | `SelectList` for result sets | `SelectList` (list of row maps) or `SelectOne` (one row map, or the value when there is one column) |
| `outputHeader` | | put the result in this header and keep the body |
| `noop` | `false` | call the procedure but keep the body |
| `batch` | `false` | the body is a list; each element (a map or a value) is the parameter source of one call, all in one transaction |
| `useMessageBodyForTemplate` | `false` | the template is the message body |
| `templateOptions.*` | | accepted for compatibility, ignored |

`outputClass` and `lazyStartProducer` are accepted and ignored.

## Result

- OUT and INOUT values become a map body, `{total=3}` (or the `outputHeader` header).
- Result sets (functions returning `SETOF` or `TABLE`, and procedures whose body runs a plain
  SELECT on the embedded engine) become rows according to `outputType`.
- When a template has OUT parameters and the call also returns rows, the rows are added to the
  map under `#result-set-1`, unless `outputType` is set, which makes the rows the result.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelSqlStoredTemplate` | in | template to use instead of the endpoint's |
| `CamelSqlStoredUpdateCount` | out | rows changed by the call |

Over the PostgreSQL protocol, `CALL` reports no row count, so `CamelSqlStoredUpdateCount` is 0 for
procedures without OUT parameters.

## Run it with Docker

```sh
docker run --rm -p 8080:8080 \
  -e DB_URL='jdbc:postgresql://camel:secret@db.example.com:5432/shop' \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/add-order.camel.yaml
```

## Common questions

### How do I read the OUT value?

The body is a map keyed by the OUT parameter names: `${body[total]}` in Simple. Use
`outputHeader=result` to keep the original body and read `${header.result[total]}`.

### How do I call a function instead of a procedure?

Add `function=true`. Name the return value with a leading `OUT` parameter, for example
`sql-stored:subtract(OUT INTEGER result, INTEGER ${header.a}, INTEGER ${header.b})?function=true`.

### Can the call join the route's transaction?

Yes. Calls use the connection of a JDBC transaction policy bound with
`cameleer_sql::bind_transaction_policy` and roll back with the route.

## Related

- [sql](https://pmsudhi.github.io/cameleer/docs/components/sql.html): plain SQL statements and table polling.
- [jdbc](https://pmsudhi.github.io/cameleer/docs/components/jdbc.html): SQL from the message body.
- [Apache Camel SQL Stored Procedure component](https://camel.apache.org/components/next/sql-stored-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/ssh.html

# SSH component

> The `ssh` component runs commands on remote hosts over SSH: the producer runs the message body as a command and returns its output, the consumer runs a command on a schedule.

**Scheme:** `ssh:` · **Crate:** `cameleer-ssh` · **Cargo feature:** [`ssh`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [SSH](https://camel.apache.org/components/next/ssh-component.html)

Cameleer has its own SSH-2 client (interop-tested against OpenSSH): password, public key,
keyboard-interactive, agent and certificate authentication, port forwarding from Rust, and
zlib compression.

## When to use it

- Check the health of edge devices or servers on a schedule (`uptime`, `df`, a status script).
- Restart a service or run a script on a remote host when an alert arrives.
- Give an AI operations agent a narrow, audited way to run predefined commands.

## URI format

```text
ssh://[username[:password]@]host[:port][?options]
```

The default port is 22.

## Example

Every minute, run `uptime` on an edge device and log the result. The host key must be in
`known_hosts` (`failOnUnknownHost=true`).

```yaml
- route:
    id: device-uptime
    from:
      uri: "ssh://{{env:SSH_USER:monitor}}@{{env:DEVICE_HOST:localhost:22}}?password={{env:SSH_PASSWORD:changeme}}&knownHostsFile={{env:KNOWN_HOSTS:known_hosts}}&failOnUnknownHost=true&pollCommand=uptime&delay=60000"
      steps:
        - filter:
            simple: "${header.CamelSshExitValue} == 0"
            steps:
              - log: "uptime: ${body}"
```

To run a command on demand instead, send it as the body to the same URI without `pollCommand`
(`to: ssh://...`); the reply body is the command's stdout.

## Rust DSL

```rust
fn device_uptime_route(b: &mut RouteBuilder, host: &str, password: &str, known_hosts: &str) {
    b.from(&format!("ssh://monitor@{}?password={}&knownHostsFile={}&failOnUnknownHost=true&pollCommand=uptime&delay=60000", host, password, known_hosts))
        .route_id("device-uptime")
        .filter(simple("${header.CamelSshExitValue} == 0"))
        .log("uptime: ${body}");
}
```

## Options

| option | default | description |
|---|---|---|
| `username`, `password` | | Credentials (also `user:password@` in the URI). |
| `pollCommand` | | Consumer: the command to run on each poll. |
| `delay`, `initialDelay` | 500, 1000 ms | Consumer schedule (plus the other scheduler options). |
| `channelType` | `exec` | `exec`, or `shell` (the command is written to an interactive shell). |
| `timeout` | `30000` | Read timeout in ms. |
| `certResource`, `privateKeyFile` | | Private key path (`file:` prefix allowed). |
| `certResourcePassword`, `privateKeyPassphrase` | | Passphrase of an encrypted key. |
| `knownHostsResource`, `knownHostsFile`, `knownHosts` | | `known_hosts` file or text. |
| `useUserKnownHostsFile` | `false` | Also read `~/.ssh/known_hosts`. |
| `failOnUnknownHost` | `false` | Reject hosts not in `known_hosts`. Alias `strictHostKeyChecking`. Changed keys are always rejected. |
| `useAgent`, `agentSocket` | `false` | Authenticate with an SSH agent. |
| `certificateFile` | | OpenSSH user certificate. |
| `preferredAuthentications` | | e.g. `publickey,password`. |
| `kex`, `ciphers`, `macs`, `signatures`, `compressionAlgorithms` | | Algorithm lists. |
| `connectTimeout` | `10s` | Connect timeout. |
| `charset` | UTF-8 | Decoding of stdout and stderr. |

`shellPrompt`, `sleepForShellPrompt`, `keyPairProvider`, `keyType`, `clientBuilder` and
`compressions` are accepted and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelSshStderr` | out | The command's stderr. |
| `CamelSshExitValue` | out | The exit status. |
| `CamelSshUsername`, `CamelSshPassword` | in | Producer: credentials for this exchange. |

The body is the command's stdout. The producer keeps the connection open between exchanges.

## Run it with Docker

```sh
ssh-keyscan device7.example.com > known_hosts
docker run --rm -e DEVICE_HOST=device7.example.com:22 -e SSH_USER -e SSH_PASSWORD -e KNOWN_HOSTS=/routes/known_hosts \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/device-uptime.camel.yaml
```

## Common questions

### How do I run a command when a message arrives?
Set the body to the command and send it to `ssh://user@host?...`. Read stdout from the body and
the exit status from `CamelSshExitValue`.

### How do I use a private key?
`privateKeyFile=/routes/id_ed25519` (or `certResource=file:/routes/id_ed25519`), with
`privateKeyPassphrase` for an encrypted key.

### Is it safe to let an AI agent run commands this way?
Only if the agent picks from fixed commands. Build the command in the route from an allow-list,
never from free text, and use an account with minimal rights.

## Related

- [sftp](https://pmsudhi.github.io/cameleer/docs/components/sftp.html): file transfer over SSH.
- Apache Camel: [SSH component](https://camel.apache.org/components/next/ssh-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/stomp.html

# STOMP component

> The `stomp` component sends and receives messages over STOMP 1.2 with brokers such as ActiveMQ, Artemis and RabbitMQ, mapping STOMP headers to message headers.

**Scheme:** `stomp:` · **Crate:** `cameleer-amqp` · **Cargo feature:** [`amqp`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Stomp](https://camel.apache.org/components/next/stomp-component.html)

## When to use it

- Exchange plain messages with a STOMP destination (`/queue/...`, `/topic/...`) where JMS semantics are not needed.
- Talk to web or IoT clients that use STOMP (for example browser apps through a broker's STOMP gateway).
- Bridge STOMP destinations to Kafka, MQTT or HTTP on a gateway.

For acknowledgements per message, selectors, request/reply and transactions use [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html), which runs
over the same STOMP client.

## URI format

```text
stomp:queue:name[?options]
stomp:topic:name[?options]
```

`stomp:queue:alerts` is the STOMP destination `/queue/alerts`.

## Example

```yaml
- route:
    id: stomp-alerts
    from:
      uri: stomp:queue:alerts
      parameters:
        brokerURL: "{{env:STOMP_URL:tcp://localhost:61613}}"
        login: "{{env:STOMP_USER:guest}}"
        passcode: "{{env:STOMP_PASSWORD:guest}}"
      steps:
        - log: "alert on ${header.destination}: ${body}"
        - to: log:alerts
```

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("stomp:queue:alerts?brokerURL=tcp://localhost:61613&login=guest&passcode=guest")
            .route_id("stomp-alerts")
            .log("alert on ${header.destination}: ${body}")
            .to("log:alerts");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `brokerURL` (alias `brokerUrl`) | `tcp://localhost:61613` | Broker address. `ssl://`, `stomp+ssl://` or `stomps://` connect with TLS. Also `camel.component.stomp.brokerUrl`. |
| `login`, `passcode` | | Credentials. |
| `host` | | STOMP virtual host (RabbitMQ vhost). |
| `clientId` | | Client id. |
| `sslContextParameters`, `useGlobalSslContextParameters` | | TLS trust settings. |

The [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html#options) options are also accepted.

## Message headers

Consumers subscribe with `ack:auto` and turn every STOMP header (`destination`, `message-id`,
`subscription`, `content-type`, custom headers, ...) into a message header. Producers `SEND` the body
with every header that does not start with `Camel`.

## Run it with Docker

```sh
docker run --rm -e STOMP_URL=tcp://rabbitmq:61613 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/alerts.camel.yaml
```

## Common questions

### How do I connect to RabbitMQ over STOMP?

Enable the `rabbitmq_stomp` plugin and use `brokerURL=tcp://host:61613`, with `host=/` for the default vhost.

### What happens to a message when my route fails?

`stomp` consumers use `ack:auto`, so the broker considers it delivered. Use [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html) with
`acknowledgementModeName=CLIENT_ACKNOWLEDGE` or `transacted=true` for redelivery.

## Related

- [jms](https://pmsudhi.github.io/cameleer/docs/components/jms.html), [activemq](https://pmsudhi.github.io/cameleer/docs/components/activemq.html), [paho](https://pmsudhi.github.io/cameleer/docs/components/paho.html)
- [Apache Camel Stomp component](https://camel.apache.org/components/next/stomp-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/stream.html

# Stream component

> The `stream` component reads lines from standard input or a file (optionally tailing it) and writes messages to standard output, standard error or a file.

**Scheme:** `stream:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Stream](https://camel.apache.org/components/next/stream-component.html)

## When to use it

- Tail an application log file on an edge device and forward error lines (like `tail -f | grep ERROR`).
- Build command-line pipelines: read lines from `stdin`, transform them, print to `stdout`.
- Print results to the console in a demo or a one-off job.

## URI format

```text
stream:in | stream:out | stream:err | stream:file?fileName=path[&options]
```

## Example

```yaml
- route:
    id: tail-errors
    from:
      uri: stream:file
      parameters:
        fileName: "{{env:LOG_FILE:/var/log/app.log}}"
        scanStream: true
        scanStreamDelay: 500
      steps:
        - filter:
            simple: "${body} contains 'ERROR'"
            steps:
              - to: stream:out
```

Every line of the file, and each line appended later, is checked; lines containing `ERROR` are printed.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("stream:file?fileName=/var/log/app.log&scanStream=true&scanStreamDelay=500")
            .route_id("tail-errors")
            .filter(simple("${body} contains 'ERROR'"))
            .to("stream:out")
            .end();
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `fileName` | | Required for `stream:file`. Producers append to it; consumers read it. |
| `encoding` | `UTF-8` | `UTF-8` or `ISO-8859-1`. |
| `delay` | `0` | Producer: wait (ms) before each write. Consumer: wait between messages. |
| `appendNewLine` | `true` | Producer: add a line break after each message. |
| `scanStream` | `false` | Consumer: keep reading the file as it grows. |
| `scanStreamDelay` | `100` | Consumer: ms between checks for new lines with `scanStream`. |
| `groupLines` | `0` | Consumer: send N lines per message, joined with `\n`. |
| `initialPromptDelay` | `2000` | `stream:in`: wait before the first prompt. |
| `promptMessage` | | `stream:in`: prompt printed before reading each line. |
| `promptDelay` | `0` | `stream:in`: wait before each prompt. |
| `closeOnDone`, `autoCloseCount`, `retry`, `fileWatcher`, `readTimeout`, `readLine`, `groupStrategy`, `lazyStartProducer`, `bridgeErrorHandler` | | Accepted and ignored. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelStreamIndex` | out | Line number of the message, starting at 0. |
| `CamelStreamComplete` | out | `true` on the last message when the input ended. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" -v /var/log/app:/logs:ro -e LOG_FILE=/logs/app.log \
  pmsudhi/cameleer run /routes/tail.camel.yaml
```

## Common questions

### How do I read standard input line by line?

`from: stream:in`, then run with `docker run -i ...` or pipe into the `cameleer` CLI.

### Does `scanStream` start at the end of the file?

No. It reads the existing lines first, then follows new ones.

## Related

- [exec](https://pmsudhi.github.io/cameleer/docs/components/exec.html), [log](https://pmsudhi.github.io/cameleer/docs/components/log.html), [syslog](https://pmsudhi.github.io/cameleer/docs/components/syslog.html)
- [Apache Camel Stream component](https://camel.apache.org/components/next/stream-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/string-template.html

# StringTemplate component

> The `string-template` component renders a StringTemplate 4 template against the message and sets the rendered text as the new body.

**Scheme:** `string-template:` · **Crate:** `cameleer-core` · **Cargo feature:** [`templates`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [String Template](https://camel.apache.org/components/next/string-template-component.html)

## When to use it

- Render text where the template must stay logic-free: only attribute references, conditions
  on presence and list application.
- Produce lists with separators (`; separator=", "`) without loop code.
- Reuse StringTemplate files from a Java Camel application.

## URI format

```text
string-template:templateResource[?options]
```

`templateResource` is a file path relative to the working directory, `file:path`,
`classpath:path` (read as a relative path) or `ref:beanName`.

## Example

Summarize the tools an agent may call. Attributes use `<...>`, an anonymous sub-template is
applied to each list item, and `if` tests presence.

```text
Agent <body.name> may call: <body.tools; separator=", ">.
<body.tools:{t | <i>. <t>}; separator="\n">
<if(headers.readonly)>Read-only mode: do not call write tools.<endif>
```

```yaml
- route:
    id: string-template-tools
    from:
      uri: direct:string-template-tools
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: readonly
            constant: "yes"
        - to: string-template:templates/tools.st
```

```json
{"name":"triage","tools":["search_docs","read_ticket","close_ticket"]}
```

```text
Agent triage may call: search_docs, read_ticket, close_ticket.
1. search_docs
2. read_ticket
3. close_ticket
Read-only mode: do not call write tools.
```

### Other delimiters

`delimiterStart` and `delimiterStop` change `<` and `>`, which helps when the output is HTML
or XML:

```text
<li>$body$</li>
```

```yaml
- route:
    id: string-template-dollar
    from:
      uri: direct:string-template-dollar
      steps:
        - to: string-template:templates/item.st?delimiterStart=$&delimiterStop=$
```

```text
Cameleer
```

```text
<li>Cameleer</li>
```

## Rust DSL

```rust
b.from("direct:string-template-rust")
    .to("string-template:templates/item.st?delimiterStart=$&delimiterStop=$");
```

## Options

| option | default | description |
|---|---|---|
| `delimiterStart` | `<` | Character that opens an expression. |
| `delimiterStop` | `>` | Character that closes an expression. |
| `allowTemplateFromHeader` | `false` | Use the `CamelStringTemplateTemplate` / `CamelStringTemplateResourceUri` headers when present. |
| `contentCache` | `false` | Read the template once; otherwise it is re-read for every message. |
| `allowContextMapAll` | `false` | Add `camelContext` (with `name`) to the data model. |
| `encoding` | UTF-8 | Accepted; templates are always read as UTF-8. |

The data model: `body`, `headers`, `variables`, `exchange` (`exchange.properties`...),
`request` / `in`, and `camelContext` with `allowContextMapAll=true`.

### Supported StringTemplate

Attribute references and properties (`<a.b>`, `<a.(expr)>`), string and list literals,
multi-valued attributes with `separator` and `null` options, anonymous sub-templates
(`<names:{n | <n>}>`, implicit `it`, `<i>` / `<i0>`, chained and zipped application),
`if/elseif/else/endif` with `!`, `&&`, `||`, the functions `first last rest trunc strip length
reverse trim strlen`, special characters (`<\n>`, `<\t>`, `<\uXXXX>`), comments `<! !>` and
escapes. Named template references (`<x:t()>`) need template groups and are not supported.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelStringTemplateTemplate` | in | Template text used instead of the resource (needs `allowTemplateFromHeader=true`). |
| `CamelStringTemplateResourceUri` | in | Template resource used instead of the endpoint's one (needs `allowTemplateFromHeader=true`). |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/tools.camel.yaml
```

## Common questions

### How do I join a list with commas?

`<body.tools; separator=", ">`. Missing items can be replaced with `null="n/a"`.

### How do I write HTML or XML with StringTemplate?

Switch the delimiters with `delimiterStart=$&delimiterStop=$`, so `<` and `>` are plain text.

### Why does `<if(x)>` not compare values?

StringTemplate is logic-free: `if` only tests that an attribute is present, not `false` and not
an empty list. Compute the condition before rendering, for example in a header.

## Related

- [Mustache](https://pmsudhi.github.io/cameleer/docs/components/mustache.html), [FreeMarker](https://pmsudhi.github.io/cameleer/docs/components/freemarker.html), [Velocity](https://pmsudhi.github.io/cameleer/docs/components/velocity.html), [MVEL](https://pmsudhi.github.io/cameleer/docs/components/mvel.html).
- [Apache Camel String Template component](https://camel.apache.org/components/next/string-template-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/stub.html

# Stub component

> The `stub` component stands in for any endpoint: it accepts any URI and options and queues the messages in memory like [seda](https://pmsudhi.github.io/cameleer/docs/components/seda.html), so you can run a route without the real system.

**Scheme:** `stub:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Stub](https://camel.apache.org/components/next/stub-component.html)

## When to use it

- Run a route locally when a downstream system (mail server, cloud queue, payment API) is not reachable.
- Try a route in a test or a demo without credentials: prefix the real URI with `stub:`.
- Check what a route would send: consume from the same `stub:` URI and inspect the messages.

## URI format

```text
stub:anyScheme:anything[?anyOptions]
```

Everything after `stub:` is kept as the queue name and is never validated.

## Example

```yaml
- route:
    id: notify-shipping
    from:
      uri: direct:notify
      steps:
        - setBody:
            simple: "Order ${body} shipped"
        - to: stub:smtp://mail.example.com?to=ops@example.com
```

The real mail server is never contacted. The message waits on an in-memory queue, where another route
or a consumer template can read it.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:notify")
            .route_id("notify-shipping")
            .set_body(simple("Order ${body} shipped"))
            .to("stub:smtp://mail.example.com?to=ops@example.com");
    })
}
```

## Options

None. All options are accepted and ignored, and the queue uses the [seda](https://pmsudhi.github.io/cameleer/docs/components/seda.html) defaults
(1000 messages, one consumer).

## Message headers

None added.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/notify.camel.yaml
```

## Common questions

### How do I see what was sent to a stub endpoint?

Consume from the exact same URI, for example `from: stub:smtp://mail.example.com?to=ops@example.com`
followed by `log:`, or poll it with a consumer template in a test.

### Is there a way to switch between stub and the real endpoint?

Put the scheme in a property placeholder, for example `to: "{{mail.prefix:stub:}}smtp://..."`, and set
`mail.prefix` to an empty value in production.

## Related

- [seda](https://pmsudhi.github.io/cameleer/docs/components/seda.html), [mock](https://pmsudhi.github.io/cameleer/docs/components/mock.html)
- [Apache Camel Stub component](https://camel.apache.org/components/next/stub-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/syslog.html

# Syslog component

> The `syslog` component receives and sends syslog messages (RFC 5424 and RFC 3164) over UDP, TCP or TLS and parses them into structured fields.

**Scheme:** `syslog:` · **Crate:** `cameleer-protocols` · **Cargo feature:** [`protocols`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Syslog data format](https://camel.apache.org/components/next/dataformats/syslog-dataformat.html)

## When to use it

- Run a syslog gateway on an edge site: collect logs from routers, switches and devices and forward only
  the important ones upstream (Kafka, HTTP, a chat alert).
- Turn syslog into structured JSON for a log pipeline or for an AI agent that triages alerts.
- Send syslog messages from a route to an existing syslog server.

Difference from Apache Camel: Camel has a syslog data format that you combine with `netty:udp://`.
Cameleer adds this `syslog:` component, and also provides the `syslog` data format.

## URI format

```text
syslog:udp://host:port[?options]
syslog:tcp://host:port[?options]
syslog:tls://host:port[?options]
```

The default port is 514 (6514 for `tls`). A consumer listens on `host:port`; a producer sends to it.

## Example

```yaml
- route:
    id: syslog-gateway
    from:
      uri: syslog:udp://0.0.0.0:{{env:SYSLOG_PORT:5514}}
      steps:
        - filter:
            simple: "${header.CamelSyslogSeverity} in 'EMERG,ALERT,CRIT,ERR'"
            steps:
              - setBody:
                  simple: "${header.CamelSyslogHostname}: ${body[logMessage]}"
              - to: log:alerts
```

`<34>1 2026-11-05T10:00:00Z router1 sshd - - - authentication failure` (severity `CRIT`) becomes
`router1: authentication failure`; `INFO` messages are dropped.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("syslog:udp://0.0.0.0:5514")
            .route_id("syslog-gateway")
            .filter(simple("${header.CamelSyslogSeverity} in 'EMERG,ALERT,CRIT,ERR'"))
            .set_body(simple("${header.CamelSyslogHostname}: ${body[logMessage]}"))
            .to("log:alerts")
            .end();
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `unmarshal` | `true` | Consumer: the body is the parsed message (a map). `false` keeps the raw text. |
| `ssl` | `false` | Use TLS with `syslog:tcp://` (RFC 5425). |
| `sslContextParameters` | | `#bean` with TLS settings; the consumer needs key material. |
| `useGlobalSslContextParameters` | `false` | Use the global `camel.ssl.*` parameters. |
| `charset`, `sync`, `textline`, `delimiter`, `receiveBufferSize`, `sendBufferSize` | | Accepted and ignored. |

The parsed body has the fields `format` (`RFC5424` / `RFC3164`), `priority`, `facility` (name such as
`AUTH`), `facilityCode`, `severity` (`EMERG`, `ALERT`, `CRIT`, `ERR`, `WARNING`, `NOTICE`, `INFO`,
`DEBUG`), `severityCode`, `version`, `timestamp`, `timestampMillis`, `hostname`, `appName`, `procId`,
`msgId`, `structuredData` and `logMessage`.

TCP accepts octet-counted (RFC 6587) and line-terminated frames. The producer sends one datagram (UDP) or
one line (TCP), or an octet-counted frame over TLS. A map body is formatted as RFC 5424 first.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelSyslogFacility` | out | Facility name. |
| `CamelSyslogSeverity` | out | Severity name. |
| `CamelSyslogHostname` | out | Host name from the message. |
| `CamelSyslogTimestamp` | out | Timestamp from the message. |
| `CamelSyslogRemoteAddress`, `CamelSyslogLocalAddress` | out | Socket addresses. |

## Run it with Docker

```sh
docker run --rm -p 5514:5514/udp -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/syslog.camel.yaml
```

Point devices at UDP port 5514 of the host. Use port 514 only if the container may bind privileged ports.

## Common questions

### How do I forward the parsed message as JSON?

Add a `marshal` step with `json` after the consumer, then send it on (for example to [kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html)).

### Does it understand old BSD syslog lines?

Yes. RFC 3164 lines are parsed too; `format` tells you which kind arrived.

## Related

- [netty](https://pmsudhi.github.io/cameleer/docs/components/netty.html), [mllp](https://pmsudhi.github.io/cameleer/docs/components/mllp.html), [kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html), [stream](https://pmsudhi.github.io/cameleer/docs/components/stream.html)
- [Apache Camel Syslog data format](https://camel.apache.org/components/next/dataformats/syslog-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/telegram.html

# Telegram component

> The `telegram` component sends messages, photos and documents through a Telegram bot and receives the messages people send to the bot (long polling with `getUpdates`, or a webhook).

**Scheme:** `telegram:` · **Crate:** `cameleer-saas` · **Cargo feature:** [`saas`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Telegram](https://camel.apache.org/components/next/telegram-component.html)

## When to use it

- Build a chat bot: receive a message, answer it with an LLM or a lookup, reply in the same chat.
- Push alerts from monitoring, IoT sensors or edge devices to a phone, without running a server.
- Send reports, photos or documents to a group.
- Turn Telegram into a command channel for an AI agent ("status", "restart worker 3").

## URI format

```text
telegram:bots[?options]
```

`bots` is the only endpoint type. `authorizationToken` (from BotFather) is required.

## Example

An AI chat bot. The consumer delivers each incoming message with the `CamelTelegramChatId`
header set, the LLM writes the answer, and the producer replies to the same chat because the
header is still there.

```yaml
- route:
    id: telegram-ai-bot
    from:
      uri: "telegram:bots?authorizationToken={{env:TELEGRAM_TOKEN}}&baseUri={{env:TELEGRAM_API_URL:https://api.telegram.org}}&timeout=30"
      steps:
        - setBody:
            simple: "${body[text]}"
        - to: "openai:chat-completion?model={{env:OPENAI_MODEL:gpt-4o-mini}}&baseUrl={{env:OPENAI_BASE_URL:https://api.openai.com/v1}}&apiKey={{env:OPENAI_API_KEY}}&systemMessage=You are a helpful assistant. Answer in at most three sentences."
        - to: "telegram:bots?authorizationToken={{env:TELEGRAM_TOKEN}}&baseUri={{env:TELEGRAM_API_URL:https://api.telegram.org}}"
```

Send an alert to a fixed chat with HTML formatting:

```yaml
- route:
    id: telegram-alert
    from:
      uri: "timer:disk-check?repeatCount=1"
      steps:
        - setBody:
            constant: "<b>edge-gw-07</b>: disk 91% full"
        - to: "telegram:bots?authorizationToken={{env:TELEGRAM_TOKEN}}&chatId={{env:TELEGRAM_CHAT_ID}}&parseMode=HTML&baseUri={{env:TELEGRAM_API_URL:https://api.telegram.org}}"
        - log: "sent Telegram message ${header.CamelTelegramMessageId}"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("timer:disk-check?repeatCount=1")
        .set_body(constant("<b>edge-gw-07</b>: disk 91% full"))
        .to("telegram:bots?authorizationToken={{env:TELEGRAM_TOKEN}}&chatId={{env:TELEGRAM_CHAT_ID}}&parseMode=HTML");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `authorizationToken` | | Bot token (required). |
| `chatId` | | Default chat id for the producer (the `CamelTelegramChatId` header wins). |
| `parseMode` | | `HTML`, `MARKDOWN` or `MarkdownV2` for text messages. |
| `timeout` | `30` | Consumer: long-poll timeout in seconds for `getUpdates`. |
| `limit` | `100` | Consumer: maximum updates per poll. |
| `baseUri` | `https://api.telegram.org` | Bot API base URL (a local Bot API server, a proxy or a test server). |
| `delay`, `initialDelay`, ... | `delay=500` | Consumer: the standard scheduled-poll options. |

`proxyHost`, `proxyPort`, `proxyType`, `client` and `bufferSize` are accepted for Camel
compatibility and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelTelegramChatId` | in / out | Producer: target chat. Consumer: chat of the incoming message. |
| `CamelTelegramParseMode` | in | Overrides `parseMode`. |
| `CamelTelegramMediaType` | in | With a byte body: `PHOTO_JPG`, `PHOTO_PNG`, `AUDIO`, `VIDEO` or `DOCUMENT` (multipart upload with `sendPhoto`, `sendAudio`, `sendVideo`, `sendDocument`). |
| `CamelTelegramMediaTitleCaption` | in | Caption of an uploaded file. |
| `CamelTelegramMessageId` | out | Id of the sent message. |

Bodies: a text body is sent with `sendMessage`; a byte body with `CamelTelegramMediaType` is
uploaded; a map body is sent as the API parameters (`sendPhoto` when it has `photo`,
`sendDocument` when it has `document`, otherwise `sendMessage`). For InOut exchanges the body
becomes the API `result`. Consumer bodies are the message object (`text`, `chat`, `from`, ...),
or the whole update for other update kinds.

## Run it with Docker

```sh
export TELEGRAM_TOKEN=123456:ABC... OPENAI_API_KEY=sk-...
docker run --rm -e TELEGRAM_TOKEN -e OPENAI_API_KEY -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/telegram-ai-bot.camel.yaml
```

The bot only needs outbound HTTPS, so it runs behind NAT on a Raspberry Pi or an edge box.

## Common questions

### How do I find my chat id?

Send any message to the bot and run the consumer route with a `log` step: the
`CamelTelegramChatId` header of the incoming message is the chat id.

### Can I use a webhook instead of polling?

Yes: consume from `webhook:telegram:bots?authorizationToken=...&webhookExternalUrl=https://bot.example.com`
(the `webhook` component). It listens with `platform-http`, registers the public URL with
`setWebhook` on start and removes it with `deleteWebhook` on stop. Telegram does not allow
`getUpdates` while a webhook is set.

### How do I send a photo?

Set the body to the image bytes (for example from a `file:` consumer) and the
`CamelTelegramMediaType` header to `PHOTO_JPG` or `PHOTO_PNG`; add
`CamelTelegramMediaTitleCaption` for a caption.

### What happens on errors?

A Bot API answer with `"ok": false` fails the exchange with an `ApiException` carrying the
Telegram description (`Telegram: Bad Request: chat not found`). The bot token is removed from
error messages.

## Related

- [openai](https://pmsudhi.github.io/cameleer/docs/components/openai.html) and the [AI components guide](https://pmsudhi.github.io/cameleer/docs/guides/ai-components.html)
- [slack](https://pmsudhi.github.io/cameleer/docs/components/slack.html), [twilio](https://pmsudhi.github.io/cameleer/docs/components/twilio.html)
- [Apache Camel Telegram component](https://camel.apache.org/components/next/telegram-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/test.html

# Test component

> The `test` component is the short name of [dataset-test](https://pmsudhi.github.io/cameleer/docs/components/dataset-test.html): it checks a route's output against expected messages read from another endpoint.

**Scheme:** `test:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [DataSet Test](https://camel.apache.org/components/next/dataset-test-component.html)

## When to use it

- Move older Camel tests that use `test:file:...` without changing them.
- Compare a route's output with a file of expected lines, in any order.

## URI format

```text
test:expectedEndpointUri[?options]
```

## Example

```yaml
- route:
    id: enrich-devices
    from:
      uri: direct:device
      steps:
        - setBody:
            simple: "device:${body}"
        - to: test:file:{{env:EXPECTED_DIR:expected}}?noop=true&split=true&anyOrder=true
```

With a file that lists `device:a` and `device:b`, the messages may arrive in either order.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:device")
            .route_id("enrich-devices")
            .set_body(simple("device:${body}"))
            .to("test:file:expected?noop=true&split=true&anyOrder=true");
    })
}
```

## Options

The same as [dataset-test](https://pmsudhi.github.io/cameleer/docs/components/dataset-test.html#options): `timeout`, `anyOrder`, `split`, `delimiter`. Other
options go to the expected endpoint URI.

## Message headers

None added.

## Run it with Docker

Used from Rust tests (`cameleer_core::component::dataset::dataset_test_endpoint`).

## Common questions

### Is test the same as dataset-test?

Yes. Both schemes are the same component, as in Apache Camel 2 where `test:` was the original name.

## Related

- [dataset-test](https://pmsudhi.github.io/cameleer/docs/components/dataset-test.html), [dataset](https://pmsudhi.github.io/cameleer/docs/components/dataset.html), [mock](https://pmsudhi.github.io/cameleer/docs/components/mock.html)
- [Apache Camel DataSet Test component](https://camel.apache.org/components/next/dataset-test-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/thrift.html

# Thrift component

> The `thrift` component calls Apache Thrift services and hosts Thrift services in a route, driven by a Thrift IDL file read at runtime.

**Scheme:** `thrift:` · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Thrift](https://camel.apache.org/components/next/thrift-component.html)

Apache Camel uses classes generated by the Thrift compiler. Cameleer reads the IDL
(`idlFile`, or inline `schema`) instead: no code generation. Arguments and results are plain
values and maps. Binary, compact and JSON protocols, framed and buffered transports, and TLS
are supported.

## When to use it

- Talk to existing Thrift services (common in older data platforms and ad tech) from routes.
- Put a Thrift front on a route so Thrift clients can call it.
- Bridge Thrift to REST or a message broker.

## URI format

```text
thrift://host:port/[package.]Service[?options]
```

## Example

A device registry service. The IDL, saved as `registry.thrift`:

```thrift
namespace java registry

service DeviceRegistry {
  string location(1: string deviceId)
}
```

The route implements the service. Each call arrives with the arguments as an array body and the
method name in a header; the body at the end is the return value.

```yaml
- route:
    id: device-registry
    from:
      uri: "thrift://0.0.0.0:{{env:THRIFT_PORT:9090}}/registry.DeviceRegistry?idlFile={{env:IDL_FILE:registry.thrift}}"
      steps:
        - setBody:
            simple: "site-north/rack-${body[0]}"
```

A client calls it with `thrift://registry-host:9090/registry.DeviceRegistry?method=location&idlFile=registry.thrift`
and the device id as the body.

## Rust DSL

```rust
fn device_registry_route(b: &mut RouteBuilder, port: u16, idl: &str) {
    b.from(&format!("thrift://0.0.0.0:{}/registry.DeviceRegistry?idlFile={}", port, idl))
        .route_id("device-registry")
        .set_body(simple("site-north/rack-${body[0]}"));
}
```

## Options

| option | default | description |
|---|---|---|
| `idlFile` | | Thrift IDL file. Either this or `schema` is required. |
| `schema` | | Inline IDL text. |
| `method` | | Producer: method to call (or header `CamelThriftMethodName`). |
| `exchangeProtocol` | `BINARY` | `BINARY`, `COMPACT` or `JSON`. |
| `transport` | `FRAMED` | `FRAMED` or `BUFFERED`. Servers accept both. |
| `compressionType` | `NONE` | `ZLIB` wraps the transport in TZlibTransport (both sides must use it). |
| `negotiationType` | `PLAINTEXT` | `SSL` uses TLS with `sslContextParameters`. |
| `sslContextParameters` | | `#bean` with trust / key material for `SSL`. |
| `clientTimeout` | `0` | Producer read timeout in ms (`0` = none). |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelThriftMethodName` | out / in | Consumer: the called method. Producer: overrides `method`. |
| `CamelThriftException` | out | Producer: the declared exception struct the server returned. |

Producer bodies: an array of arguments, an object keyed by argument name, a single value for a
one-argument method, or null. A declared exception fails the exchange with the exception's name
as the error kind; to return one from a consumer, fail with that kind or return an object with
`@exception` set to the name.

## Run it with Docker

```sh
docker run --rm -p 9090:9090 -e IDL_FILE=/routes/registry.thrift \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/device-registry.camel.yaml
```

## Common questions

### Do I need the Thrift compiler?
No. Cameleer reads the IDL at startup.

### How do I call a method with several arguments?
Send an array in declaration order (`[2, 3]`) or an object (`{"a": 2, "b": 3}`).

### Which protocol does my existing service use?
Most Java services use `BINARY` over `FRAMED`, the defaults. Match `exchangeProtocol` and
`transport` to the server.

## Related

- [grpc](https://pmsudhi.github.io/cameleer/docs/components/grpc.html).
- Data format: Thrift serialization (`thrift`) in the data format pages.
- Apache Camel: [Thrift component](https://camel.apache.org/components/next/thrift-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/timer.html

# Timer component

> The `timer` component starts a route at a fixed interval, for example every 5 seconds, a set number of times or forever.

**Scheme:** `timer:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Timer](https://camel.apache.org/components/next/timer-component.html)

## When to use it

- Send a heartbeat or health status from an edge device every few seconds.
- Poll an HTTP API or a database at a fixed rate.
- Trigger an AI agent loop at a regular interval ("check the inbox every minute").
- Fire once at startup (`repeatCount=1`) or once at a given time (`time=...`).

For calendar schedules ("every night at 02:00") use [cron](https://pmsudhi.github.io/cameleer/docs/components/cron.html) or [quartz](https://pmsudhi.github.io/cameleer/docs/components/quartz.html).

## URI format

```text
timer:name[?options]
```

## Example

```yaml
- route:
    id: heartbeat
    from:
      uri: timer:heartbeat
      parameters:
        period: 5000
        delay: 0
        includeMetadata: true
      steps:
        - setBody:
            simple: "edge-gw-1 alive #${exchangeProperty.CamelTimerCounter}"
        - to: log:heartbeat
```

The first message fires right away (`delay: 0`), then every 5 seconds: `edge-gw-1 alive #1`,
`edge-gw-1 alive #2`, ...

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("timer:heartbeat?period=5000&delay=0&includeMetadata=true")
            .route_id("heartbeat")
            .set_body(simple("edge-gw-1 alive #${exchangeProperty.CamelTimerCounter}"))
            .to("log:heartbeat");
    })
}
```

## Options

| option | default | description |
|---|---|---|
| `period` | `1000` | Interval between fires, in ms or with a unit (`5s`, `1m`). |
| `delay` | `1000` | Wait before the first fire, in ms or with a unit. |
| `repeatCount` | `0` | Stop after this many fires. `0` fires forever. |
| `fixedRate` | `false` | Schedule at a fixed rate (catch up after a slow exchange) instead of a fixed delay between fires. |
| `includeMetadata` | `false` | Also set the metadata properties and headers listed below. |
| `time` | | First fire at this local time: `yyyy-MM-dd HH:mm:ss` or `yyyy-MM-ddTHH:mm:ss`. A trailing `Z`, an offset (`+02:00`) or a zone in brackets (`[Europe/Paris]`) selects another zone. |
| `pattern` | | Accepted; the two formats above are always recognised. |
| `exchangePattern` | `InOnly` | `InOnly` or `InOut`. |
| `synchronous`, `daemon`, `runLoggingLevel`, `timer`, `bridgeErrorHandler`, `exceptionHandler` | | Accepted and ignored. |

## Message headers

Each fired exchange has a null body and the exchange property `CamelTimerCounter` (1, 2, 3, ...).

| name | kind | description |
|---|---|---|
| `CamelTimerCounter` | property (always), header (with `includeMetadata`) | Fire count, starting at 1. |
| `CamelTimerName` | property (with `includeMetadata`) | The timer name from the URI. |
| `CamelTimerPeriod` | property (with `includeMetadata`) | The period in ms. |
| `CamelTimerFiredTime` | property and header (with `includeMetadata`) | When the timer fired. |
| `CamelMessageTimestamp` | header (with `includeMetadata`) | The fire time in epoch ms. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/heartbeat.camel.yaml
```

## Common questions

### How do I run a route only once at startup?

Use `timer:once?repeatCount=1&delay=0`.

### How do I run a route every day at a fixed time?

The timer only knows intervals. Use [cron](https://pmsudhi.github.io/cameleer/docs/components/cron.html) (`schedule=0 0 2 * * ?`) or [quartz](https://pmsudhi.github.io/cameleer/docs/components/quartz.html).

### Do timer routes run on their own threads?

As in Camel, all routes that use the same timer name share one thread (Camel keeps one
`java.util.Timer` per name): their fires run one after the other, so a slow route delays the
others of that name. Give routes different names (`timer:a`, `timer:b`) to run them
independently. The thread starts with the first route of a name and exits when the last one
stops or finishes its `repeatCount`.

### What time zone does the `time` option use?

The process default zone, which is UTC unless `TZ` is set. Add `Z`, an offset or `[Zone/Id]` to choose
another one.

## Related

- [scheduler](https://pmsudhi.github.io/cameleer/docs/components/scheduler.html), [cron](https://pmsudhi.github.io/cameleer/docs/components/cron.html), [quartz](https://pmsudhi.github.io/cameleer/docs/components/quartz.html)
- [Apache Camel Timer component](https://camel.apache.org/components/next/timer-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/twilio.html

# Twilio component

> The `twilio` component calls the Twilio REST API (2010-04-01): send and list SMS and MMS messages, place calls, manage phone numbers, queues, recordings and the other resources Camel's `twilio` component exposes.

**Scheme:** `twilio:` · **Crate:** `cameleer-saas` · **Cargo feature:** [`saas`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** no · **Producer:** yes · **Apache Camel:** [Twilio](https://camel.apache.org/components/next/twilio-component.html)

## When to use it

- Send an SMS when an alert fires, an order ships or an IoT sensor crosses a threshold.
- Let an AI agent text a short summary to the on-call phone.
- Read the message log, or fetch a message's delivery status.
- Automate calls, queues, phone numbers or usage reports.

## URI format

```text
twilio:api/method[?options]
```

`api` is a Twilio resource in Camel's naming (`message`, `call`, `queue`, `incoming-phone-number`,
`recording`, `usage-record-today`, ...). `method` is `create`, `read`, `fetch`, `update` or
`delete` (or Camel's `creator`, `reader`, `fetcher`, `updater`, `deleter`). Unsupported
combinations fail when the endpoint is created.

## Example

Send an SMS. For `message/create` the body is the message text unless a `body` or `mediaUrl`
parameter is set. After the call the body is the created message (`sid`, `status`, ...).

```yaml
- route:
    id: sms-alert
    from:
      uri: "direct:sms-alert"
      steps:
        - setBody:
            simple: "ALERT ${header.device}: temperature ${header.celsius} C"
        - to: "twilio:message/create?from=RAW({{env:TWILIO_FROM:+15005550006}})&to=RAW({{env:ONCALL_PHONE:+15005550001}})&username={{env:TWILIO_ACCOUNT_SID}}&password={{env:TWILIO_AUTH_TOKEN}}&serverUrl={{env:TWILIO_API_URL:https://api.twilio.com}}"
        - log: "sent SMS ${body[sid]}"
```

List the messages sent to a number. `read` returns the resource list as the body; every
parameter that is not a `path*` parameter becomes a query filter (`to` → `To`).

```yaml
- route:
    id: sms-log
    from:
      uri: "timer:sms-log?repeatCount=1"
      steps:
        - to: "twilio:message/read?to=RAW({{env:ONCALL_PHONE:+15005550001}})&username={{env:TWILIO_ACCOUNT_SID}}&password={{env:TWILIO_AUTH_TOKEN}}&serverUrl={{env:TWILIO_API_URL:https://api.twilio.com}}"
        - split:
            simple: "${body}"
            steps:
              - to: "log:sms-log"
```

## Rust DSL

```rust
ctx.add_routes(|b| {
    b.from("direct:sms-alert")
        .set_body(simple("ALERT ${header.device}: temperature ${header.celsius} C"))
        .to("twilio:message/create?from=RAW(+15005550006)&to=RAW(+15005550001)&username={{env:TWILIO_ACCOUNT_SID}}&password={{env:TWILIO_AUTH_TOKEN}}");
})?;
```

## Options

| option | default | description |
|---|---|---|
| `username` | | Account SID (or API key SID), required. |
| `password` | | Auth token (or API key secret), required. |
| `accountSid` | `username` | Account the resources belong to (`Accounts/{accountSid}/...`). |
| `inBody` | | Name of the parameter taken from the message body (default `body` for `message/create`). |
| `serverUrl` | `https://api.twilio.com` | API base URL (Cameleer extension: a proxy or a test server). |
| `path*` | | Resource path parameters: `pathSid` (the instance for `fetch`, `update`, `delete`), `pathAccountSid`, `pathCallSid`, `pathConferenceSid`, `pathQueueSid`, `pathMessageSid`, `pathCountryCode`, ... |
| any other | | Sent to Twilio as a form field (`create`, `update`) or query parameter (`read`), with the Twilio capitalisation: `to` → `To`, `statusCallback` → `StatusCallback`. |

Because every unknown option is an API parameter, a misspelled option is sent to Twilio rather
than rejected when the endpoint is created.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelTwilio.<parameter>` | in | Any API parameter, for example `CamelTwilio.to` or `CamelTwilio.pathSid`. Headers win over endpoint options. List values repeat the field. |

The body after the call: the created, fetched or updated resource as a map; the resource list
for `read`; `true` for `delete`.

## Run it with Docker

```sh
export TWILIO_ACCOUNT_SID=AC... TWILIO_AUTH_TOKEN=... TWILIO_FROM=+1... ONCALL_PHONE=+1...
docker run --rm -e TWILIO_ACCOUNT_SID -e TWILIO_AUTH_TOKEN -e TWILIO_FROM -e ONCALL_PHONE \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/sms-log.camel.yaml
```

## Common questions

### How do I send to a different number per message?

Set the `CamelTwilio.to` header before the endpoint; it overrides the `to` option.

### Why do phone numbers need `RAW(...)`?

In an endpoint URI a `+` is decoded as a space, as in Apache Camel, so `to=+15005550001` would
reach Twilio as ` 15005550001`. Write `to=RAW(+15005550001)` or `to=%2B15005550001`, or set the
number in the `CamelTwilio.to` header, which is not URI-decoded.

### How do I send an MMS?

Add `mediaUrl=https://example.com/chart.png` (or the `CamelTwilio.mediaUrl` header, a list for
several images). Set `inBody=body` if the body should still be the text.

### What happens when Twilio rejects a request?

The exchange fails with `HttpOperationFailedException`; the message contains the HTTP status,
the Twilio error code and message (for example `code: 21211, message: Invalid 'To' Phone Number`).

### Is there a consumer for incoming SMS?

No. Twilio pushes incoming messages with webhooks; receive them with
[platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html) and point the number's messaging webhook at that URL.

## Related

- [telegram](https://pmsudhi.github.io/cameleer/docs/components/telegram.html), [slack](https://pmsudhi.github.io/cameleer/docs/components/slack.html)
- [Split EIP](https://pmsudhi.github.io/cameleer/docs/guides/eips.html)
- [Apache Camel Twilio component](https://camel.apache.org/components/next/twilio-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/undertow.html

# Undertow component

> The `undertow` component serves HTTP requests on an address given in the URI, for routes written for Apache Camel's camel-undertow.

**Scheme:** `undertow:` · **Crate:** `cameleer-http` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Undertow](https://camel.apache.org/components/next/undertow-component.html)

`undertow:` endpoints run on Cameleer's embedded HTTP/1.1 server, the same one as
[platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html) and [jetty](https://pmsudhi.github.io/cameleer/docs/components/jetty.html). Host and port are part of the URI.
Cameleer's `undertow` is a consumer only: to call HTTP services use [http](https://pmsudhi.github.io/cameleer/docs/components/http.html). Undertow's
WebSocket support is not part of this scheme; use [websocket](https://pmsudhi.github.io/cameleer/docs/components/websocket.html).

## When to use it

- Run an existing Camel route that uses `undertow:` without changes.
- Echo or transform request bodies on a dedicated port, e.g. a small adapter in front of a
  legacy device.

## URI format

```text
undertow:http://host:port/path[?options]
undertow:https://host:port/path[?options]
```

## Example

An adapter that takes a plain-text command from a client, normalizes it to upper case and
returns it with the request method.

```yaml
- route:
    id: command-adapter
    from:
      uri: "undertow:http://0.0.0.0:{{env:ADAPTER_PORT:8082}}/command?httpMethodRestrict=POST,PUT"
      steps:
        - setBody:
            simple: "${header.CamelHttpMethod} ${body.toUpperCase()}"
        - setHeader:
            name: Content-Type
            constant: text/plain
```

## Rust DSL

```rust
fn command_adapter_route(b: &mut RouteBuilder, port: u16) {
    b.from(&format!("undertow:http://0.0.0.0:{}/command?httpMethodRestrict=POST,PUT", port))
        .route_id("command-adapter")
        .set_body(simple("${header.CamelHttpMethod} ${body.toUpperCase()}"))
        .set_header("Content-Type", constant("text/plain"));
}
```

## Options

The options of [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html#options) apply: `httpMethodRestrict`,
`matchOnUriPrefix`, `consumes`, `produces`, `muteException`, `chunked`, `mapHttpMessageBody`,
`mapHttpMessageHeaders`, `mapHttpMessageFormUrlEncodedBody`, `disableStreamCache`,
`sslContextParameters`, `useGlobalSslContextParameters`, `needClientAuth` / `clientAuth`, and
`host` / `port` to override the URI.

## Message headers

The same as [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html#message-headers).

## Run it with Docker

```sh
docker run --rm -p 8082:8082 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/command-adapter.camel.yaml
curl -XPOST -d 'restart pump 3' localhost:8082/command
```

## Common questions

### Is this the real Undertow server?
No. The scheme maps to Cameleer's built-in server so Apache Camel routes run unchanged.

### Can I use undertow as an HTTP client?
Not in Cameleer. Use the [http](https://pmsudhi.github.io/cameleer/docs/components/http.html) component for outgoing calls.

### How do I accept only some methods?
`httpMethodRestrict=POST,PUT`; other methods get `405`.

## Related

- [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html), [jetty](https://pmsudhi.github.io/cameleer/docs/components/jetty.html), [netty-http](https://pmsudhi.github.io/cameleer/docs/components/netty-http.html).
- [http](https://pmsudhi.github.io/cameleer/docs/components/http.html) for outgoing requests.
- Apache Camel: [Undertow component](https://camel.apache.org/components/next/undertow-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/validator.html

# Validator component

> The `validator` component checks the XML message body against an XML Schema (XSD) and fails the exchange with a `SchemaValidationException` listing every error when it does not conform.

**Scheme:** `validator:` · **Crate:** `cameleer-xml` · **Cargo feature:** none for a well-formedness check; [`xml`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) for full XML Schema validation · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [Validator](https://camel.apache.org/components/next/validator-component.html)

## When to use it

- Reject malformed partner documents (orders, invoices, HL7 v3, UBL) at the edge of a route.
- Check XML produced by an LLM or a transformation before sending it to a strict backend.
- Route invalid documents to a dead letter or error queue with `doTry` / `onException`.

## URI format

```text
validator:schemaResource[?options]
```

`schemaResource` is a file path relative to the working directory, `file:path`,
`classpath:path` (read as a relative path) or `ref:beanName`. `xs:include` and `xs:import`
resolve relative to the schema file.

## Example

Validate orders and answer with the validation errors instead of failing the caller.

```xml
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="order">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="customer" type="xs:string"/>
        <xs:element name="qty" type="xs:positiveInteger"/>
      </xs:sequence>
      <xs:attribute name="id" type="xs:string" use="required"/>
    </xs:complexType>
  </xs:element>
</xs:schema>
```

```yaml
- route:
    id: validator-order
    from:
      uri: direct:validator-order
      steps:
        - doTry:
            steps:
              - to: validator:xsd/order.xsd
              - setBody:
                  constant: valid
            doCatch:
              - exception:
                  - org.apache.camel.ValidationException
                steps:
                  - setBody:
                      simple: "invalid: ${exception.message}"
```

A valid order:

```xml
<order id="o-1"><customer>Ada</customer><qty>2</qty></order>
```

```text
valid
```

An order with a missing attribute and a negative quantity:

```xml
<order><customer>Ada</customer><qty>-1</qty></order>
```

```text
invalid: Validation failed for: xsd/order.xsd
cvc-complex-type.4
cvc-datatype-valid.1.2.1
```

`SchemaValidationException` is a `ValidationException`, so the catch above takes both schema
errors and documents that are not well-formed.

## Rust DSL

```rust
b.from("direct:validator-rust")
    .to("validator:xsd/order.xsd")
    .set_body(constant("valid"));
```

## Options

| option | default | description |
|---|---|---|
| `failOnNullBody` | `true` | Fail with `NoXmlBodyValidationException` when the body is null. |
| `failOnNullHeader` | `true` | Fail with `NoXmlHeaderValidationException` when `headerName` is set and the header is missing. |
| `headerName` | (none) | Validate this header instead of the body. |
| `useSharedSchema` | `true` | Load and compile the schema once. |
| `contentCache` | `true` | Same effect as `useSharedSchema`: `false` reloads the schema per message. |

Accepted and ignored (Java-only settings): `schemaFactory`, `schemaLanguage`,
`resourceResolver`, `resourceResolverFactory`, `errorHandler`, `useDom`,
`schemaReaderFactory`, `lazyStartProducer`.

### Supported XML Schema

A subset of XML Schema 1.0: global and local elements, `ref`, `minOccurs` / `maxOccurs`,
`sequence` / `choice` / `all`, model groups, attributes, simple types with restrictions
(facets), the built-in data types, `include` and `import`. Without `cameleer-xml` registered,
cameleer-core's `validator` only checks well-formedness; `cameleer_main::new_main()` and the
`cameleer` CLI always register the full validator.

## Message headers

| header / property | direction | description |
|---|---|---|
| `CamelValidationErrors` (exchange property) | out | The list of error messages, set when validation fails. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/validate.camel.yaml
```

## Common questions

### How do I get all validation errors, not just the first?

The exception message lists every error, and the `CamelValidationErrors` exchange property
holds them as a list.

### How do I validate a header instead of the body?

Set `headerName=myHeader`.

### Does it also catch XML that is not well-formed?

Yes. A parse error fails with `SchemaValidationException` too, as Xerces reports it through
the same error handler in Camel.

## Related

- [json-validator](https://pmsudhi.github.io/cameleer/docs/components/json-validator.html) for JSON Schema.
- [xslt](https://pmsudhi.github.io/cameleer/docs/components/xslt.html), [xmlsecurity-verify](https://pmsudhi.github.io/cameleer/docs/components/xmlsecurity-verify.html).
- [Apache Camel Validator component](https://camel.apache.org/components/next/validator-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/velocity.html

# Velocity component

> The `velocity` component renders an Apache Velocity (VTL) template against the message and sets the rendered text as the new body.

**Scheme:** `velocity:` · **Crate:** `cameleer-core` · **Cargo feature:** [`templates`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [Velocity](https://camel.apache.org/components/next/velocity-component.html)

## When to use it

- Render emails, notifications and reports from a message with loops and conditions.
- Build a few-shot prompt for a model: loop over example pairs and append the new input.
- Reuse Velocity templates from an existing Java Camel application.

## URI format

```text
velocity:templateResource[?options]
```

`templateResource` is a file path relative to the working directory, `file:path`,
`classpath:path` (read as a relative path) or `ref:beanName` (a `String` in the registry).

## Example

A few-shot classification prompt: the examples come from the request, the count from
`$foreach.count`, and the instruction changes with a header.

```text
#set($n = $body.examples.size())
Classify the sentiment. $n examples follow.
#foreach($e in $body.examples)
$foreach.count. "$e.text" => $e.label
#end
Text: "$body.input"
#if($headers.strict == "true")
Answer with exactly one word.
#end
```

```yaml
- route:
    id: velocity-few-shot
    from:
      uri: direct:velocity-few-shot
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: strict
            constant: "true"
        - to: velocity:templates/few-shot.vm
```

```json
{"examples":[{"text":"Great support, thanks!","label":"positive"},{"text":"Still broken after a week.","label":"negative"}],"input":"The update fixed it."}
```

```text
Classify the sentiment. 2 examples follow.
1. "Great support, thanks!" => positive
2. "Still broken after a week." => negative
Text: "The update fixed it."
Answer with exactly one word.
```

### Supplemental context

The `CamelVelocitySupplementalContext` header (a map) adds entries to the data model; the
`CamelVelocityContext` header replaces it entirely.

```text
Hello $name from $team, quiet missing value: [$!missing]
```

```yaml
- route:
    id: velocity-supplemental
    from:
      uri: direct:velocity-supplemental
      steps:
        - setHeader:
            name: CamelVelocitySupplementalContext
            simple: "${map('name','Ada','team','platform')}"
        - to: velocity:templates/hello.vm
```

```text
ignored
```

```text
Hello Ada from platform, quiet missing value: []
```

## Rust DSL

```rust
b.from("direct:velocity-rust")
    .set_header("CamelVelocitySupplementalContext", simple("${map('name','Ada','team','ops')}"))
    .to("velocity:templates/hello.vm");
```

## Options

| option | default | description |
|---|---|---|
| `allowTemplateFromHeader` | `false` | Use the `CamelVelocityTemplate` / `CamelVelocityResourceUri` headers when present. |
| `contentCache` | `false` | Read the template once; otherwise it is re-read for every message. |
| `allowContextMapAll` | `false` | Add `camelContext` (with `name`) to the data model. |
| `encoding` | UTF-8 | Accepted; templates are always read as UTF-8. |
| `loaderCache`, `propertiesFile` | | Accepted and ignored (Java Velocity settings). |

The data model: `$body`, `$headers`, `$variables`, `$exchange` (`$exchange.properties`,
`$exchange.exchangeId`, `$exchange.getIn().getHeader("x")`), `$request` / `$in`, and
`$camelContext` with `allowContextMapAll=true`.

### Supported VTL

References `$x`, `${x}`, quiet `$!x`, properties, method calls (`$s.toUpperCase()`,
`$headers.get("x")`), index access `$list[0]` and `$map["k"]`; `#set`, `#if/#elseif/#else`,
`#foreach` with `$foreach.count/index/hasNext/first/last`, `#break`, `#stop`, `#macro` and
calls, `#include`, `#parse`, `#evaluate`, `#define`, comments `##` and `#* *#`, unparsed
blocks `#[[ ]]#`, escapes, arithmetic, comparisons and logical operators. Conditions follow
Velocity 2: null, `false`, empty strings, empty collections and zero are false.

Known difference: a `#end` line directly followed by another directive line (such as
`#if(...)`) can leave an empty line in the output where Velocity 2 removes both lines. Put a text line between the two directives, as the example does.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelVelocityTemplate` | in | Template text used instead of the resource (needs `allowTemplateFromHeader=true`). |
| `CamelVelocityResourceUri` | in | Template resource used instead of the endpoint's one (needs `allowTemplateFromHeader=true`). |
| `CamelVelocityContext` | in | A map used as the whole data model. |
| `CamelVelocitySupplementalContext` | in | A map merged into the data model. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/few-shot.camel.yaml
```

## Common questions

### How do I print nothing for a missing value?

Use a quiet reference: `$!name`. A plain `$name` that is null renders as the literal text
`$name`, as in Velocity.

### How do I get the loop index?

`$foreach.count` starts at 1, `$foreach.index` at 0; `$foreach.hasNext` helps with
separators.

### Can I pass extra values without changing the body?

Yes: set `CamelVelocitySupplementalContext` to a map (for example with Simple's
`${map(...)}`), and its keys become top-level template variables.

## Related

- [Mustache](https://pmsudhi.github.io/cameleer/docs/components/mustache.html), [FreeMarker](https://pmsudhi.github.io/cameleer/docs/components/freemarker.html), [StringTemplate](https://pmsudhi.github.io/cameleer/docs/components/string-template.html),
  [MVEL](https://pmsudhi.github.io/cameleer/docs/components/mvel.html).
- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) for the `map(...)` function.
- [Apache Camel Velocity component](https://camel.apache.org/components/next/velocity-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/vertx-websocket.html

# Vert.x WebSocket component

> The `vertx-websocket` component runs a WebSocket server (or client) with Vert.x-style headers, including events when a client connects or disconnects.

**Scheme:** `vertx-websocket:` · **Crate:** `cameleer-protocols` · **Cargo feature:** [`protocols`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [Vert.x WebSocket](https://camel.apache.org/components/next/vertx-websocket-component.html)

Cameleer has no Vert.x; the scheme runs on the same RFC 6455 implementation as
[websocket](https://pmsudhi.github.io/cameleer/docs/components/websocket.html) and uses the `CamelVertxWebsocket.*` header names, so Camel routes
written for camel-vertx-websocket run unchanged.

## When to use it

- Know when clients connect and disconnect (`fireWebSocketConnectionEvents=true`), e.g. to
  track which AI agents or devices are online.
- Answer each client individually over its own connection.
- Consume from a remote WebSocket server as a client (`consumeAsClient=true`).

## URI format

```text
vertx-websocket:host:port/path[?options]
```

The default port is `0` (a free port), so give one explicitly. A producer whose URI matches a
server endpoint sends to that server's clients; otherwise it connects as a client.

## Example

A presence-aware endpoint for agents: connections and disconnections are logged, and every
message is acknowledged to the client that sent it.

```yaml
- route:
    id: agent-presence
    from:
      uri: "vertx-websocket:0.0.0.0:{{env:WS_PORT:8090}}/agents?fireWebSocketConnectionEvents=true"
      steps:
        - choice:
            when:
              - simple: "${header[CamelVertxWebsocket.event]} == 'MESSAGE'"
                steps:
                  - setBody:
                      simple: "ack: ${body}"
                  - to: "vertx-websocket:0.0.0.0:{{env:WS_PORT:8090}}/agents"
            otherwise:
              steps:
                - log: "${header[CamelVertxWebsocket.event]} ${header[CamelVertxWebsocket.remoteAddress]}"
```

## Rust DSL

```rust
fn agent_presence_route(b: &mut RouteBuilder, port: u16) {
    let endpoint = format!("vertx-websocket:0.0.0.0:{}/agents", port);
    b.from(&format!("{}?fireWebSocketConnectionEvents=true", endpoint))
        .route_id("agent-presence")
        .choice()
        .when(simple("${header[CamelVertxWebsocket.event]} == 'MESSAGE'"))
        .set_body(simple("ack: ${body}"))
        .to(&endpoint)
        .otherwise()
        .log("${header[CamelVertxWebsocket.event]} ${header[CamelVertxWebsocket.remoteAddress]}")
        .end_choice();
}
```

## Options

| option | default | description |
|---|---|---|
| `fireWebSocketConnectionEvents` | `false` | Also route `OPEN` and `CLOSE` events (header `CamelVertxWebsocket.event`). |
| `consumeAsClient` | `false` | The consumer connects to `host:port/path` as a client instead of serving it. |
| `sendToAll` | `false` | Producer: send to every connection of the path. |
| `connectTimeout` | `10s` | Client connect timeout. |
| `reconnectInterval` | `0` | Client consumer: reconnect delay (`0` = no reconnect). |
| `allowedOrigins` | any | Accepted `Origin` values. Alias `allowedOriginPattern`. |
| `subProtocol` | | Subprotocols. Aliases `subProtocols`, `clientSubProtocols`. |
| `maxTextMessageSize`, `maxBinaryMessageSize`, `maxMessageSize` | 64 MiB | Largest incoming message. |
| `maxFrameSize` | 65536 | Outgoing frame size. |
| `sslContextParameters` | | `#bean` with a key store: serve `wss`. |
| `useGlobalSslContextParameters` | `false` | Serve `wss` with the global `camel.ssl.*` parameters. |

`router`, `serverOptions`, `clientOptions` and `handshakeHeaders` are accepted and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelVertxWebsocket.connectionKey` | out / in | Consumer: the sending connection. Producer: comma-separated connections to send to. |
| `CamelVertxWebsocket.remoteAddress` | out | Client address. |
| `CamelVertxWebsocket.event` | out | `MESSAGE`, `OPEN` or `CLOSE`. |
| `CamelVertxWebsocket.sendToAll` | in | `true` broadcasts this message. |

## Run it with Docker

```sh
docker run --rm -p 8090:8090 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/agent-presence.camel.yaml
websocat ws://localhost:8090/agents
```

## Common questions

### How do I know when a client disconnects?
Set `fireWebSocketConnectionEvents=true`; a `CLOSE` exchange arrives with the connection key.

### How do I reply only to the sender?
Send to the same server URI with the `CamelVertxWebsocket.connectionKey` header the consumer
set, as in the example.

### Can it connect to another server?
Yes: `consumeAsClient=true` on the consumer, and a producer whose URI has no local server
connects as a client.

## Related

- [websocket](https://pmsudhi.github.io/cameleer/docs/components/websocket.html), [ws](https://pmsudhi.github.io/cameleer/docs/components/ws.html).
- Apache Camel: [Vert.x WebSocket component](https://camel.apache.org/components/next/vertx-websocket-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/vm.html

# VM component

> The `vm` component is a [seda](https://pmsudhi.github.io/cameleer/docs/components/seda.html) queue shared by every `CamelContext` in the same process, so separately deployed route sets can pass messages in memory.

**Scheme:** `vm:` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [VM](https://camel.apache.org/components/next/vm-component.html)

## When to use it

- Connect two `CamelContext`s embedded in one Rust program (for example a plugin's routes and the host's routes).
- Feed a shared audit or metrics route from several independent route sets.
- Kamelet Pipes map Knative `Channel` and `Broker` references to `vm:<name>`, an in-process channel.

## URI format

```text
vm:name[?options]
```

## Example

```yaml
- route:
    id: audit-publisher
    from:
      uri: direct:audit
      steps:
        - to: vm:audit
- route:
    id: audit-writer
    from:
      uri: vm:audit
      parameters:
        concurrentConsumers: 1
      steps:
        - log: "audit: ${body}"
        - to: log:audit
```

Any context in the process that sends to `vm:audit` reaches the `audit-writer` route.

## Rust DSL

```rust
use cameleer_core::prelude::*;

pub fn routes(ctx: &CamelContext) -> Result<()> {
    ctx.add_routes(|b| {
        b.from("direct:audit").route_id("audit-publisher").to("vm:audit");
        b.from("vm:audit?concurrentConsumers=1")
            .route_id("audit-writer")
            .log("audit: ${body}")
            .to("log:audit");
    })
}
```

## Options

`vm` takes exactly the same options as [seda](https://pmsudhi.github.io/cameleer/docs/components/seda.html#options): `size`, `concurrentConsumers`,
`waitForTaskToComplete`, `timeout`, `multipleConsumers`, `blockWhenFull`, `discardWhenFull`,
`offerTimeout`, `pollTimeout`, `purgeWhenStopping`, `failIfNoConsumers`, `discardIfNoConsumers`,
`limitConcurrentConsumers`.

## Message headers

None added. The consumer gets a copy of the exchange with the property `CamelCorrelationId`.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/audit.camel.yaml
```

The container runs one context, so `vm` behaves like `seda` there.

## Common questions

### What is the difference between vm and seda?

A `seda` queue is visible only inside its own `CamelContext`. A `vm` queue with the same name is the
same queue for every context in the process.

### Can vm connect two separate processes or containers?

No. It is in memory. Use a broker ([kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html), [amqp](https://pmsudhi.github.io/cameleer/docs/components/amqp.html), [paho](https://pmsudhi.github.io/cameleer/docs/components/paho.html)) between processes.

## Related

- [seda](https://pmsudhi.github.io/cameleer/docs/components/seda.html), [direct](https://pmsudhi.github.io/cameleer/docs/components/direct.html), [kamelet](https://pmsudhi.github.io/cameleer/docs/components/kamelet.html)
- [Apache Camel VM component](https://camel.apache.org/components/next/vm-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/webhook.html

# Webhook component

> The `webhook` component receives events from a SaaS service through a webhook: it serves an HTTP endpoint for a delegate endpoint (GitHub or Telegram) and registers that endpoint with the service on start.

**Scheme:** `webhook:` · **Crate:** `cameleer-saas` · **Cargo feature:** [`saas`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** no · **Apache Camel:** [Webhook](https://camel.apache.org/components/next/webhook-component.html)

`webhook:` wraps another endpoint URI. On start it binds an HTTP path on
[platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html) and asks the service to call
`webhookExternalUrl + path`; on stop it removes the registration. Delegates that support
webhooks: `github` (repository hooks) and `telegram` (`setWebhook`).

## When to use it

- Start an AI code-review agent when a pull request is opened, without polling GitHub.
- Answer Telegram bot messages as they arrive.
- Any push-based integration where the service needs a public URL to call.

## URI format

```text
webhook:delegateScheme:delegatePath[?options]
```

Options starting with `webhook` belong to this component; all other options are passed to the
delegate endpoint.

## Example

Pull request events from a GitHub repository feed a review queue. On start Cameleer creates
the repository hook pointing at `PUBLIC_URL/github`; on stop it deletes it.

```yaml
- route:
    id: pr-intake
    from:
      uri: "webhook:github:pullRequest?repoOwner={{env:GITHUB_OWNER:acme}}&repoName={{env:GITHUB_REPO:shop}}&oauthToken={{env:GITHUB_TOKEN:changeme}}&serverUrl={{env:GITHUB_API:https://api.github.com}}&webhookExternalUrl={{env:PUBLIC_URL:https://hooks.example.com}}&webhookPath=/github"
      steps:
        - filter:
            simple: "${header.GitHubEvent} == 'pull_request' && ${body[action]} == 'opened'"
            steps:
              - setBody:
                  simple: "Review pull request #${body[number]}"
              - to: seda:review-queue
- route:
    id: reviewer
    from:
      uri: seda:review-queue
      steps:
        - log: "${body}"
```

The `reviewer` route is where an agent would pick up the work (for example with the `openai`
component).

## Rust DSL

```rust
fn pr_intake_routes(b: &mut RouteBuilder, github: &str, public_url: &str) {
    b.from(&format!("webhook:{}&webhookExternalUrl={}&webhookPath=/github", github, public_url))
        .route_id("pr-intake")
        .filter(simple("${header.GitHubEvent} == 'pull_request' && ${body[action]} == 'opened'"))
        .set_body(simple("Review pull request #${body[number]}"))
        .to("seda:review-queue");
    b.from("seda:review-queue").route_id("reviewer").log("${body}");
}
```

## Options

| option | default | description |
|---|---|---|
| `webhookExternalUrl` | | Public base URL announced to the service. Required when registering. Also from `camel.component.webhook.webhookExternalUrl`. |
| `webhookPath` | `/webhook/<scheme>-<hash>` | Path of the HTTP endpoint. |
| `webhookBasePath` | | Prefix for the path. |
| `webhookAutoRegister` | `true` | Register on start and unregister on stop. With `false`, register the URL yourself. |
| `webhookComponentName` | `platform-http` | HTTP server component; its port is `camel.server.port`. |

Delegate options are those of the delegate component, e.g. for `github`: `repoOwner`,
`repoName`, `oauthToken`, `hookEvents` (default `push,pull_request,issues`) and `serverUrl` (API
base URL, default `https://api.github.com`, for GitHub Enterprise); for `telegram`:
`authorizationToken` and `baseUri`.

## Message headers

| header | direction | description |
|---|---|---|
| `GitHubEvent` | out | GitHub: the `X-GitHub-Event` request header (`pull_request`, `push`, `issues`). |
| `CamelTelegramChatId` | out | Telegram: the chat of the incoming message. |

The body is the parsed JSON payload (GitHub) or the Telegram message.

## Run it with Docker

```sh
docker run --rm -p 8080:8080 -e GITHUB_OWNER -e GITHUB_REPO -e GITHUB_TOKEN \
  -e PUBLIC_URL=https://hooks.example.com -v "$PWD:/routes:ro" \
  pmsudhi/cameleer run /routes/pr-intake.camel.yaml
```

`PUBLIC_URL` must reach port 8080 of the container (a reverse proxy or a tunnel).

## Common questions

### Why does start fail with "webhookExternalUrl"?
Registration needs the public URL. Set `webhookExternalUrl`, or `webhookAutoRegister=false` if
you register the hook yourself.

### Is the GitHub payload signature checked?
No. Cameleer does not verify `X-Hub-Signature-256`. Keep the path secret, put a proxy that
checks the signature in front, or restrict the source addresses.

### Which port does the webhook listen on?
The `platform-http` port, `camel.server.port` (default 8080).

## Related

- [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html), [http](https://pmsudhi.github.io/cameleer/docs/components/http.html), [rest](https://pmsudhi.github.io/cameleer/docs/components/rest.html).
- Apache Camel: [Webhook component](https://camel.apache.org/components/next/webhook-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/websocket.html

# WebSocket component

> The `websocket` component runs a WebSocket server: the consumer receives messages from connected clients and the producer sends to one client or broadcasts to all of them.

**Scheme:** `websocket:` · **Crate:** `cameleer-protocols` · **Cargo feature:** [`protocols`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [WebSocket (Jetty)](https://camel.apache.org/components/next/websocket-component.html)

Cameleer implements RFC 6455 itself (no Jetty): text and binary messages, fragmentation,
ping/pong and the closing handshake. To connect to a WebSocket server as a client, use
[ws](https://pmsudhi.github.io/cameleer/docs/components/ws.html). For a Vert.x-style server with connection events, see
[vertx-websocket](https://pmsudhi.github.io/cameleer/docs/components/vertx-websocket.html).

## When to use it

- Push live updates (sensor readings, order status, alerts) to browser dashboards.
- Stream an AI agent's progress or tokens to a web UI as they arrive.
- A simple chat or notification hub: every message from one client is broadcast to all.

## URI format

```text
websocket://host:port/path[?options]
```

Defaults: host `0.0.0.0`, port 9292. Consumers and producers on the same host and port share
one listener. A producer also starts the server for its path, so clients can connect to receive
broadcasts even without a consumer route.

## Example

A broadcast hub for an operations dashboard: every message a client sends is stamped with its
sender and sent to every client connected to `/ops`.

```yaml
- route:
    id: ops-hub
    from:
      uri: "websocket://0.0.0.0:{{env:WS_PORT:9292}}/ops"
      steps:
        - setBody:
            simple: "${header.CamelWebsocketRemoteAddress}: ${body}"
        - to: "websocket://0.0.0.0:{{env:WS_PORT:9292}}/ops?sendToAll=true"
```

Without `sendToAll`, the producer replies only to the connection named by the
`CamelWebsocketConnectionKey` header, which the consumer sets: `from` and `to` on the same URI
make an echo server.

## Rust DSL

```rust
fn ops_hub_route(b: &mut RouteBuilder, port: u16) {
    b.from(&format!("websocket://0.0.0.0:{}/ops", port))
        .route_id("ops-hub")
        .set_body(simple("${header.CamelWebsocketRemoteAddress}: ${body}"))
        .to(&format!("websocket://0.0.0.0:{}/ops?sendToAll=true", port));
}
```

## Options

| option | default | description |
|---|---|---|
| `sendToAll` | `false` | Producer: send to every connection of the path. |
| `maxTextMessageSize`, `maxBinaryMessageSize`, `maxMessageSize` | 64 MiB | Largest incoming message. |
| `maxFrameSize` | 65536 | Outgoing messages are fragmented into frames of this size. |
| `allowedOrigins` | any | Comma-separated `Origin` values accepted at the handshake (`*` = any). Alias `allowedOriginPattern`. |
| `subProtocol` | | Comma-separated subprotocols to accept. Aliases `subProtocols`, `clientSubProtocols`. |
| `sslContextParameters` | | `#bean` with the server key store: serves `wss`. |
| `useGlobalSslContextParameters` | `false` | Serve `wss` with the global `camel.ssl.*` parameters. |

The first endpoint that binds a host and port decides whether it serves TLS. Jetty options such
as `staticResources`, `sessionSupport`, `minThreads` and `maxThreads` are accepted and ignored.
No compression extensions (`permessage-deflate`) are negotiated.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelWebsocketConnectionKey` | out / in | Consumer: the sending connection. Producer: the connection to send to. |
| `CamelWebsocketRemoteAddress` | out | Client address. |
| `CamelWebsocketSendToAll` | in | `true` broadcasts this message. |

Text messages arrive as strings, binary messages as bytes. A byte body is sent as a binary
message, anything else as text. A send failure raises `WebsocketSendException`.

## Run it with Docker

```sh
docker run --rm -p 9292:9292 -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/ops-hub.camel.yaml
# in two terminals (websocat or any WebSocket client):
websocat ws://localhost:9292/ops
```

## Common questions

### How do I send to one client only?
Keep the `CamelWebsocketConnectionKey` header the consumer set and send to the same URI without
`sendToAll`.

### How do I push data that does not come from a client?
Send to `websocket://0.0.0.0:9292/path?sendToAll=true` from any route (a timer, a Kafka
consumer). The producer starts the server, so clients can connect before anything is sent.

### How do I serve wss?
Add `sslContextParameters=#tls` with a key store, or `useGlobalSslContextParameters=true`.

## Related

- [ws](https://pmsudhi.github.io/cameleer/docs/components/ws.html): WebSocket client.
- [vertx-websocket](https://pmsudhi.github.io/cameleer/docs/components/vertx-websocket.html): server with open/close events.
- [platform-http](https://pmsudhi.github.io/cameleer/docs/components/platform-http.html): plain HTTP endpoints.
- Apache Camel: [WebSocket component](https://camel.apache.org/components/next/websocket-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/ws.html

# WS component

> The `ws` component is a WebSocket client: it connects to a WebSocket server, receives the server's messages as exchanges and sends messages on the same connection.

**Scheme:** `ws:` · **Also:** `wss:` · **Crate:** `cameleer-protocols` · **Cargo feature:** [`protocols`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Consumer:** yes · **Producer:** yes · **Apache Camel:** [AHC WebSocket](https://camel.apache.org/components/next/ahc-ws-component.html)

`wss:` connects over TLS and always verifies the server certificate. To run a WebSocket server,
use [websocket](https://pmsudhi.github.io/cameleer/docs/components/websocket.html) or [vertx-websocket](https://pmsudhi.github.io/cameleer/docs/components/vertx-websocket.html).

## When to use it

- Subscribe to a streaming API (market data, chat, a realtime events feed) and route each
  message.
- Connect an edge device to a central WebSocket hub and receive commands.
- Send messages to a WebSocket service from any route.

## URI format

```text
ws://host[:port]/path[?options]
wss://host[:port]/path[?options]
```

Default ports: 80 for `ws`, 443 for `wss`. A consumer and a producer with the same URI share
one connection.

## Example

An edge agent that connects to a central hub, receives commands and keeps only those addressed
to its site. `reconnectInterval` makes the client reconnect after the connection drops.

```yaml
- route:
    id: hub-commands
    from:
      uri: "ws://{{env:HUB_ADDRESS:localhost:9292}}/commands?reconnectInterval=5s"
      steps:
        - filter:
            simple: "${body} starts with '{{env:SITE_ID:site-1}}:'"
            steps:
              - log: "command for this site: ${body}"
```

## Rust DSL

```rust
fn hub_commands_route(b: &mut RouteBuilder, hub: &str) {
    b.from(&format!("ws://{}/commands?reconnectInterval=5s", hub))
        .route_id("hub-commands")
        .filter(simple("${body} starts with 'site-1:'"))
        .log("command for this site: ${body}");
}
```

## Options

| option | default | description |
|---|---|---|
| `connectTimeout` | `10s` | Connect and handshake timeout. |
| `reconnectInterval` | `0` | Consumer: reconnect after this delay when the connection drops (`0` = no reconnect). |
| `subProtocol` | | Subprotocols to request. Aliases `subProtocols`, `clientSubProtocols`. |
| `maxTextMessageSize`, `maxBinaryMessageSize`, `maxMessageSize` | 64 MiB | Largest incoming message. |
| `maxFrameSize` | 65536 | Fragment outgoing messages into frames of this size. |
| `sslContextParameters` | | `wss`: `#bean` with the trust store (and a key store for client certificates). |
| `useGlobalSslContextParameters` | `false` | `wss`: use the global `camel.ssl.*` parameters. |

Options of Apache Camel's AHC client (`clientOptions`, `reconnectMaxAttempts`, ...) are accepted
and ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelWebsocketConnectionKey` | out | Key of the client connection. |

Text messages arrive as strings and binary messages as bytes. The producer sends byte bodies as
binary messages and anything else as text.

## Run it with Docker

```sh
docker run --rm -e HUB_ADDRESS=hub.example.com:9292 -e SITE_ID=site-7 \
  -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/hub-commands.camel.yaml
```

## Common questions

### How do I connect over TLS?
Use `wss://host/path`. The certificate is checked against the system trust store, or the trust
store in `sslContextParameters`.

### How do I send a message to the server?
`to: ws://host:port/path` sends the body on the connection; a consumer on the same URI receives
the replies.

### What happens when the server goes away?
Without `reconnectInterval` the consumer stops receiving. With it, the client reconnects on that
interval.

## Related

- [websocket](https://pmsudhi.github.io/cameleer/docs/components/websocket.html), [vertx-websocket](https://pmsudhi.github.io/cameleer/docs/components/vertx-websocket.html): WebSocket servers.
- [http](https://pmsudhi.github.io/cameleer/docs/components/http.html): request/response HTTP calls.
- Apache Camel: [AHC WebSocket component](https://camel.apache.org/components/next/ahc-ws-component.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/xj.html

# XJ component

> The `xj` component converts XML to JSON and JSON to XML, either directly (`xj:identity`) or through an XSLT stylesheet.

**Scheme:** `xj:` · **Crate:** `cameleer-xml` · **Cargo feature:** [`xml`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [XJ](https://camel.apache.org/components/next/xj-component.html)

## When to use it

- Expose a legacy XML or SOAP backend to an AI agent or a JSON API: convert the XML answer to
  JSON the model's tool-calling layer can read.
- Accept JSON from a web client and turn it into XML for an older system.
- Combine conversion and mapping in one step by naming an XSLT stylesheet.

## URI format

```text
xj:identity?transformDirection=XML2JSON|JSON2XML[&options]
xj:stylesheetResource?transformDirection=XML2JSON|JSON2XML[&options]
```

`identity` converts without a stylesheet. Otherwise the stylesheet is loaded like an
[xslt](https://pmsudhi.github.io/cameleer/docs/components/xslt.html) resource (path, `file:`, `classpath:`, `ref:`).

## Example

Convert an XML customer record from a legacy system to JSON for an agent tool.

```yaml
- route:
    id: xj-xml2json
    from:
      uri: direct:xj-xml2json
      steps:
        - to: xj:identity?transformDirection=XML2JSON
```

```xml
<customer id="c-7">
  <name>Ada</name>
  <tier>gold</tier>
  <phones><phone>111</phone><phone>222</phone></phones>
</customer>
```

```json
{"@id":"c-7","name":"Ada","tier":"gold","phones":["111","222"]}
```

The rules for plain XML: the root element's content is the result; an element with only text
becomes a string; an element with child elements or attributes becomes an object (attributes
as `@name` keys, mixed text as `#text`, repeated names as arrays); an element whose children
all share one name (two or more) becomes an array.

### JSON to XML

JSON becomes Camel's xj representation: every value is an `object` element with `xj:name` and
`xj:type` attributes.

```yaml
- route:
    id: xj-json2xml
    from:
      uri: direct:xj-json2xml
      steps:
        - to: xj:identity?transformDirection=JSON2XML
```

```json
{"name":"camel","tags":["a"],"stars":5}
```

```xml
<object xj:name="name" xj:type="string">camel</object>
<object xj:name="tags" xj:type="array"><object xj:type="string">a</object></object>
<object xj:name="stars" xj:type="int">5</object>
```

`xj:type` is one of `object`, `array`, `string`, `int`, `float`, `boolean` or `null`.

### With a stylesheet

With a stylesheet, JSON → XML feeds the xj document into the stylesheet; XML → JSON converts
the stylesheet's result.

```xml
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xj="http://camel.apache.org/component/xj" exclude-result-prefixes="xj">
  <xsl:output method="xml" omit-xml-declaration="yes"/>
  <xsl:template match="/object">
    <person name="{object[@xj:name='name']}" stars="{object[@xj:name='stars']}"/>
  </xsl:template>
</xsl:stylesheet>
```

```yaml
- route:
    id: xj-json2xml-xsl
    from:
      uri: direct:xj-json2xml-xsl
      steps:
        - to: xj:xsl/xj-person.xsl?transformDirection=JSON2XML
```

```json
{"name":"camel","stars":5}
```

```xml
<person name="camel" stars="5"/>
```

## Rust DSL

```rust
b.from("direct:xj-rust")
    .to("xj:identity?transformDirection=XML2JSON");
```

## Options

| option | default | description |
|---|---|---|
| `transformDirection` | (required) | `XML2JSON` or `JSON2XML`. |
| `output` | `string` | `string` or `bytes`. |
| `contentCache` | `true` | Compile the stylesheet once. |
| `failOnNullBody` | `true` | Fail when the body is null. |

The other [xslt](https://pmsudhi.github.io/cameleer/docs/components/xslt.html#options) options are accepted and ignored.

## Message headers

None of its own. With a stylesheet, headers and exchange properties are passed as
`xsl:param` values, as in the xslt component.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/xj.camel.yaml
```

## Common questions

### How do I turn an XML API response into JSON?

Send it to `xj:identity?transformDirection=XML2JSON`. Attributes become `@name` keys and
repeated elements become arrays.

### Why is a single repeated element not an array?

An element with one child is converted as an object (or a string). Only two or more children
with the same name become an array. If a consumer always needs an array, map it with a
stylesheet or with the [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html) and Simple afterwards.

### What is the `xj:` namespace in the JSON2XML output?

It is Camel's xj namespace (`http://camel.apache.org/component/xj`), so stylesheets written for
Camel's xj component work unchanged.

## Related

- [xslt](https://pmsudhi.github.io/cameleer/docs/components/xslt.html), [xquery](https://pmsudhi.github.io/cameleer/docs/components/xquery.html).
- [Jackson XML data format](https://pmsudhi.github.io/cameleer/docs/dataformats/jacksonxml.html): a configurable value ⇄ XML mapping.
- [Apache Camel XJ component](https://camel.apache.org/components/next/xj-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/xmlsecurity-sign.html

# XML Security Sign component

> The `xmlsecurity-sign` component adds an XML Signature (XMLDSig, RSA-SHA256 or ECDSA-SHA256) to the XML message body, enveloped, enveloping or detached.

**Scheme:** `xmlsecurity-sign:` · **Crate:** `cameleer-xml` · **Cargo feature:** [`xml`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [XML Security Sign](https://camel.apache.org/components/next/xmlsecurity-sign-component.html)

## When to use it

- Sign XML documents sent to partners, banks or authorities that require XMLDSig (invoices,
  payment files, SAML-style assertions).
- Make an edge device's XML reports tamper-evident before they leave the site.
- Prove that an audit record produced by an automated agent was not changed afterwards.

Verify signatures with [xmlsecurity-verify](https://pmsudhi.github.io/cameleer/docs/components/xmlsecurity-verify.html).

## URI format

```text
xmlsecurity-sign:name[?options]
```

`name` is a free label. The key comes from `privateKey` (PEM) or a `keyStore`.

## Example

The keys below were generated for this page only (an EC P-256 key pair). Never use them for
real data; create your own with
`openssl ecparam -name prime256v1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt`.

```text
-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgr/S1wGY1NANslHGn
cIOGLnu4z9xeORbVQWm3MG3pzSKhRANCAARxi5ySY82uB37ucvRnkz5+fB8LfsKx
7L+7rqAlSeMVXVNAj0CN66ElvjSUk7CGLSLIVz/QY6wSzOkKjDGCDtII
-----END PRIVATE KEY-----
```

Sign an invoice; the signature is appended to the document element (enveloped):

```yaml
- route:
    id: xmlsecurity-sign-invoice
    from:
      uri: direct:sign-invoice
      steps:
        - to: xmlsecurity-sign:invoice?privateKey=file:keys/docs-sign.pem&keyName=docs-key
```

```xml
<invoice id="INV-1"><amount currency="EUR">99.00</amount></invoice>
```

```xml
<invoice id="INV-1"><amount currency="EUR">99.00</amount><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256"/>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
<ds:KeyName>docs-key</ds:KeyName>
</ds:Signature></invoice>
```

The digest and signature values differ on every run (ECDSA signatures are randomized), so
they are not shown. The [xmlsecurity-verify](https://pmsudhi.github.io/cameleer/docs/components/xmlsecurity-verify.html) page signs and verifies
this document in one route.

## Rust DSL

```rust
b.from("direct:xmlsecurity-sign-rust")
    .to("xmlsecurity-sign:invoice?privateKey=file:keys/docs-sign.pem&addKeyValue=true");
```

## Options

| option | default | description |
|---|---|---|
| `privateKey` | | Signing key: a PEM file (`file:path` or plain path), `ref:bean` holding PEM text, or inline PEM. PKCS#8, PKCS#1 (RSA) or SEC1 (EC). |
| `certificate` | | PEM certificate added as `ds:X509Certificate` in `ds:KeyInfo`. |
| `keyStore` | | PKCS#12, JKS or JCEKS file, or `#bean` with a key store (alias names `keyAccessor`, `keySelector`). |
| `keyStorePassword`, `keyPassword`, `alias` | | Key store access and the key entry to use. |
| `addKeyValue` | `false` | Add `ds:KeyValue` (`RSAKeyValue` or `dsig11:ECKeyValue`) with the public key. |
| `keyName` | | Add `ds:KeyName`. |
| `signatureId` | | `Id` attribute of `ds:Signature`. |
| `parentLocalName`, `parentNamespace` | | Enveloped: append the signature to this element. |
| `parentXpath` | | Enveloped: append the signature to the element selected by this XPath. |
| `xpathsToIdAttributes` | | Detached: comma-separated XPaths selecting `Id` attributes; one reference per element. |
| `contentObjectId`, `envelopingSignature` | `false` | Enveloping: the body becomes a `ds:Object` inside `ds:Signature`. |
| `xpathFilter` | | XPath Filter transform expression; namespaces from `xpathNamespaces=p=uri,...`. |
| `xpath2Filter` | | XPath Filter 2.0 transforms: `intersect:expr;subtract:expr;union:expr`. |
| `signatureAlgorithm` | from the key | `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256` or `...#ecdsa-sha256`; others are rejected. |
| `digestAlgorithm` | SHA-256 | Only `http://www.w3.org/2001/04/xmlenc#sha256`. |
| `canonicalizationMethod` | exclusive c14n | Exclusive or inclusive canonicalization. |
| `prefixForXmlSignatureNamespace` | `ds` | Prefix of the signature elements; empty for none. |
| `omitXmlDeclaration` | `false` | Leave out the XML declaration in the output. |

Without `parentLocalName`, `parentXpath`, `xpathsToIdAttributes` or enveloping options, the
signature is enveloped into the document element. Accepted and ignored: `transformMethods`,
`contentReferenceUri`, `contentReferenceType`, `addKeyInfoReference`, `clearHeaders`,
`outputXmlEncoding`, `baseUri`, `cryptoContextProperties`, `disallowDoctypeDecl`,
`schemaResourceUri`, `plainText`, `plainTextEncoding` and a few other Java-only settings.

**Differences from Apache Camel:** only RSA-SHA256 and ECDSA-SHA256 (P-256) signatures and
SHA-256 digests; no `ds:Manifest`, no external references, no XSLT transforms.

## Message headers

None.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/sign.camel.yaml
```

Mount the key with the routes (read-only), or point `privateKey` at a secret mounted by your
orchestrator.

## Common questions

### How do I sign with an RSA key and a certificate?

Set `privateKey=file:key.pem&certificate=file:cert.pem`; the algorithm follows the key type
(RSA-SHA256), and the certificate goes into `ds:KeyInfo` for the receiver.

### How do I sign only part of a document?

Use `xpathsToIdAttributes` for a detached signature over elements with an `Id` attribute, or
an `xpathFilter` / `xpath2Filter` transform.

### Where should the private key live in production?

Outside the route file: a mounted secret file, or a key store with its password from
`{{env:KEYSTORE_PASSWORD}}`.

## Related

- [xmlsecurity-verify](https://pmsudhi.github.io/cameleer/docs/components/xmlsecurity-verify.html).
- [Crypto data format](https://pmsudhi.github.io/cameleer/docs/dataformats/crypto.html), [PGP data format](https://pmsudhi.github.io/cameleer/docs/dataformats/pgp.html).
- [Apache Camel XML Security Sign component](https://camel.apache.org/components/next/xmlsecurity-sign-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/xmlsecurity-verify.html

# XML Security Verify component

> The `xmlsecurity-verify` component checks the XML Signature in the message body against a trusted key and, by default, removes the signature; a bad signature fails the exchange.

**Scheme:** `xmlsecurity-verify:` · **Crate:** `cameleer-xml` · **Cargo feature:** [`xml`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [XML Security Verify](https://camel.apache.org/components/next/xmlsecurity-verify-component.html)

## When to use it

- Accept signed XML from partners (invoices, payment files, assertions) only when the signature
  is valid and made with their key.
- Detect tampering of XML reports sent by edge devices before they are processed.
- Check signed configuration or policy files before an automated agent applies them.

Create signatures with [xmlsecurity-sign](https://pmsudhi.github.io/cameleer/docs/components/xmlsecurity-sign.html).

## URI format

```text
xmlsecurity-verify:name[?options]
```

`name` is a free label. The trusted key comes from `publicKey`, `certificate` or `keyStore`.

## Example

The key pair below was generated for these pages only; never use it for real data.

```text
-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgr/S1wGY1NANslHGn
cIOGLnu4z9xeORbVQWm3MG3pzSKhRANCAARxi5ySY82uB37ucvRnkz5+fB8LfsKx
7L+7rqAlSeMVXVNAj0CN66ElvjSUk7CGLSLIVz/QY6wSzOkKjDGCDtII
-----END PRIVATE KEY-----
```

```text
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEcYuckmPNrgd+7nL0Z5M+fnwfC37C
sey/u66gJUnjFV1TQI9AjeuhJb40lJOwhi0iyFc/0GOsEszpCowxgg7SCA==
-----END PUBLIC KEY-----
```

Sign and verify in one route (a round trip). In practice the two steps run in different
systems: the sender signs with the private key, the receiver verifies with the public key.

```yaml
- route:
    id: xmlsecurity-round-trip
    from:
      uri: direct:xmlsecurity-round-trip
      steps:
        - to: xmlsecurity-sign:report?privateKey=file:keys/docs-verify.pem
        - to: xmlsecurity-verify:report?publicKey=file:keys/docs-verify.pub.pem
```

```xml
<report site="plant-7"><temp>21.5</temp></report>
```

The verified document comes back without the signature (and with an XML declaration):

```xml
<?xml version="1.0" encoding="UTF-8"?><report site="plant-7"><temp>21.5</temp></report>
```

### Tampered documents fail

Here the document is changed after signing; verification fails with
`XmlSignatureInvalidContentHashException` (the reference digest no longer matches), which the
route turns into a rejection message.

```yaml
- route:
    id: xmlsecurity-tampered
    from:
      uri: direct:xmlsecurity-tampered
      steps:
        - to: xmlsecurity-sign:report?privateKey=file:keys/docs-verify.pem
        - setBody:
            simple: "${body.replace('21.5','99.9')}"
        - doTry:
            steps:
              - to: xmlsecurity-verify:report?publicKey=file:keys/docs-verify.pub.pem
            doCatch:
              - exception:
                  - XmlSignatureInvalidException
                steps:
                  - setBody:
                      simple: "rejected: ${exception.class}"
```

```xml
<report site="plant-7"><temp>21.5</temp></report>
```

```text
rejected: XmlSignatureInvalidContentHashException
```

## Rust DSL

```rust
b.from("direct:xmlsecurity-verify-rust")
    .to("xmlsecurity-sign:report?privateKey=file:keys/docs-verify.pem")
    .to("xmlsecurity-verify:report?publicKey=file:keys/docs-verify.pub.pem&removeSignature=false");
```

## Options

| option | default | description |
|---|---|---|
| `publicKey` | | Trusted public key (PEM file, `ref:` bean or inline PEM). |
| `certificate` | | Trusted certificate (PEM). |
| `keyStore` | | Key store with trusted certificates (also `keyAccessor`, `keySelector`); with `keyStorePassword` and `alias`. The signature's `X509Certificate` must be one of the store's certificates, or its `KeyName` an alias; otherwise every key in the store is tried. |
| `trustKeyInfoCertificate` | `false` | Trust the `ds:X509Certificate` or `ds:KeyValue` inside the signature itself. Only for tests or with out-of-band trust. |
| `removeSignature` | `true` | Remove `ds:Signature` from the body after verification; for an enveloping signature the body becomes the content of its `ds:Object`. |
## Exceptions

| exception | when |
|---|---|
| `XmlSignatureFormatException` | No signature, or a malformed one. |
| `XmlSignatureInvalidContentHashException` | A reference digest does not match: the content was changed. |
| `XmlSignatureInvalidValueException` | The signature value does not verify with the key. |
| `XmlSignatureInvalidKeyException` | No trusted key for the signature. |

All of them are `XmlSignatureInvalidException`s (except the format error), so one `doCatch` or
`onException` covers tampering and wrong keys.

## Message headers

None.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/verify.camel.yaml
```

## Common questions

### How do I keep the signature in the verified document?

Set `removeSignature=false`.

### Which key should the receiver configure?

Only the sender's public key or certificate (`publicKey` or `certificate`), never the private
key. Use `trustKeyInfoCertificate=true` only in tests: it accepts any key the document brings.

### Which algorithms are supported?

RSA-SHA256 and ECDSA-SHA256 (P-256) signatures with SHA-256 digests; SHA-1 and SHA-512 digests
are accepted when verifying. `ds:Manifest`, external references and XSLT transforms are not
supported.

## Related

- [xmlsecurity-sign](https://pmsudhi.github.io/cameleer/docs/components/xmlsecurity-sign.html), [validator](https://pmsudhi.github.io/cameleer/docs/components/validator.html).
- [Apache Camel XML Security Verify component](https://camel.apache.org/components/next/xmlsecurity-verify-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/xquery.html

# XQuery component

> The `xquery` component runs an XQuery file against the XML message body and replaces the body with the query result.

**Scheme:** `xquery:` · **Crate:** `cameleer-xml` · **Cargo feature:** [`xml`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [XQuery](https://camel.apache.org/components/next/xquery-component.html)

## When to use it

- Query and reshape XML with FLWOR expressions (`for`, `let`, `where`, `order by`, `return`).
- Build a new XML document from parts of a large one, for example only the overdue invoices.
- Extract a short text answer from an XML API response before handing it to an agent.

For a single expression inside a route step, use the [XQuery language](https://pmsudhi.github.io/cameleer/docs/languages/xquery.html).

## URI format

```text
xquery:queryResource[?options]
```

`queryResource` is a file path relative to the working directory, `file:path`,
`classpath:path` (read as a relative path) or `ref:beanName`.

## Example

Select overdue invoices, sort them by amount and build a new document. The `days` header is
bound to an external variable.

```text
declare variable $in.headers.days as xs:integer external;
<overdue days="{$in.headers.days}">{
  for $i in /invoices/invoice
  where xs:integer($i/@age) gt $in.headers.days
  order by xs:decimal($i/amount) descending
  return <invoice id="{$i/@id}">{data($i/amount)}</invoice>
}</overdue>
```

```yaml
- route:
    id: xquery-overdue
    from:
      uri: direct:xquery-overdue
      steps:
        - setHeader:
            name: days
            constant: "30"
        - to: xquery:xq/overdue.xq
```

```xml
<invoices>
  <invoice id="1" age="10"><amount>100</amount></invoice>
  <invoice id="2" age="45"><amount>75.5</amount></invoice>
  <invoice id="3" age="90"><amount>300</amount></invoice>
</invoices>
```

```xml
<overdue days="30"><invoice id="3">300</invoice><invoice id="2">75.5</invoice></overdue>
```

### Text results

`resultsFormat=String` concatenates the string values of the result:

```text
string-join(for $p in //person order by $p/@name return string($p/@name), ', ')
```

```yaml
- route:
    id: xquery-names
    from:
      uri: direct:xquery-names
      steps:
        - to: xquery:xq/names.xq?resultsFormat=String
```

```xml
<team><person name="zoe"/><person name="ali"/><person name="max"/></team>
```

```text
ali, max, zoe
```

## Rust DSL

```rust
b.from("direct:xquery-rust")
    .to("xquery:xq/names.xq?resultsFormat=String");
```

## Options

| option | default | description |
|---|---|---|
| `resultsFormat` | `DOM` | `DOM` (the result serialized as XML text), `String`, `Bytes` or `List`. `BytesSource`, `StringSource` and `DOMSource` map to `Bytes`, `String` and `DOM`. |
| `stripsAllWhiteSpace` | `true` | Drop whitespace-only text nodes of the input, as Saxon does for Camel. |
| `contentCache` | `true` | Compile the query once. |
| `headerName` | (none) | Read the input document from this header instead of the body. |
| `source` | (none) | Input source, as in Camel (`header:name`, `variable:name`, `property:name`). |
| `namespacePrefixes` | (none) | Prefix bindings, for example `p=urn:p`. |

Accepted and ignored (Saxon settings): `configuration`, `configurationProperties`,
`staticQueryContext`, `moduleURIResolver`, `parameters`, `properties`, `allowStAX`,
`resultType`, `lazyStartProducer`. Relative `doc()` URIs resolve against the query file's
directory.

### External variables

As in camel-saxon: `declare variable $in.body external;` is the body,
`$in.headers.NAME` a header, and `$NAME` an exchange property, then a header, then a variable.
A declared atomic type casts the value (`as xs:integer`); a node type (`as element()`) parses
it as XML.

## Message headers

| header | direction | description |
|---|---|---|
| any header | in | Available as `$in.headers.NAME` (or `$NAME`) when declared `external`. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/overdue.camel.yaml
```

## Common questions

### How do I pass a parameter to the query?

Set a header and declare it in the query: `declare variable $in.headers.days as xs:integer external;`.

### How do I get plain text instead of XML?

Add `resultsFormat=String`.

### Which XQuery version is supported?

XQuery 1.0 plus common 3.x conveniences such as `string-join`. Schema-aware features and
Saxon extensions are not available.

## Related

- [XQuery language](https://pmsudhi.github.io/cameleer/docs/languages/xquery.html), [XPath language](https://pmsudhi.github.io/cameleer/docs/languages/xpath.html).
- [xslt](https://pmsudhi.github.io/cameleer/docs/components/xslt.html), [xj](https://pmsudhi.github.io/cameleer/docs/components/xj.html).
- [Apache Camel XQuery component](https://camel.apache.org/components/next/xquery-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/xslt.html

# XSLT component

> The `xslt` component transforms the XML message body with an XSLT stylesheet and sets the result (XML, HTML or text) as the new body.

**Scheme:** `xslt:` · **Crate:** `cameleer-xml` · **Cargo feature:** [`xml`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [XSLT](https://camel.apache.org/components/next/xslt-component.html)

## When to use it

- Turn legacy XML (SOAP payloads, EDI exports, partner feeds) into the JSON an agent tool or a
  REST API expects, with `xsl:output method="text"`.
- Map one XML vocabulary to another (order formats, invoice standards).
- Render XML to HTML reports.
- Reuse XSLT 1.0 stylesheets from an existing Camel or BizTalk-style integration.

## URI format

```text
xslt:templateResource[?options]
```

`templateResource` is a file path relative to the working directory, `file:path`,
`classpath:path` (read as a relative path, there is no classpath) or `ref:beanName` (a
`String` in the registry). `xsl:include`, `xsl:import` and `document()` resolve relative to the
stylesheet file.

## Example

A partner sends orders as XML; an agent tool wants compact JSON. The stylesheet writes JSON
text, and the `currency` header arrives as the `xsl:param` of the same name.

```xml
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="text"/>
  <xsl:param name="currency" select="'USD'"/>
  <xsl:template match="/order">
    <xsl:text>{"id":"</xsl:text><xsl:value-of select="@id"/>
    <xsl:text>","customer":"</xsl:text><xsl:value-of select="customer/name"/>
    <xsl:text>","currency":"</xsl:text><xsl:value-of select="$currency"/>
    <xsl:text>","lines":[</xsl:text>
    <xsl:for-each select="line">
      <xsl:sort select="@sku"/>
      <xsl:text>{"sku":"</xsl:text><xsl:value-of select="@sku"/>
      <xsl:text>","qty":</xsl:text><xsl:value-of select="@qty"/>
      <xsl:text>}</xsl:text>
      <xsl:if test="position() != last()">,</xsl:if>
    </xsl:for-each>
    <xsl:text>],"total":</xsl:text>
    <xsl:value-of select="format-number(sum(line/@price), '0.00')"/>
    <xsl:text>}</xsl:text>
  </xsl:template>
</xsl:stylesheet>
```

```yaml
- route:
    id: xslt-order-to-json
    from:
      uri: direct:xslt-order
      steps:
        - setHeader:
            name: currency
            constant: EUR
        - to: xslt:xsl/order-to-json.xsl
```

```xml
<order id="A-17">
  <customer><name>Ada Lovelace</name></customer>
  <line sku="Z9" qty="1" price="12.5"/>
  <line sku="B2" qty="3" price="30"/>
</order>
```

```json
{"id":"A-17","customer":"Ada Lovelace","currency":"EUR","lines":[{"sku":"B2","qty":3},{"sku":"Z9","qty":1}],"total":42.50}
```

### XML to XML

```xml
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml" omit-xml-declaration="yes"/>
  <xsl:template match="/person">
    <contact name="{first} {last}"><xsl:copy-of select="email"/></contact>
  </xsl:template>
</xsl:stylesheet>
```

```yaml
- route:
    id: xslt-rename
    from:
      uri: direct:xslt-rename
      steps:
        - to: xslt:xsl/rename.xsl
```

```xml
<person><first>Grace</first><last>Hopper</last><email>grace@example.com</email></person>
```

```xml
<contact name="Grace Hopper"><email>grace@example.com</email></contact>
```

## Rust DSL

```rust
b.from("direct:xslt-rust")
    .set_header("currency", constant("GBP"))
    .to("xslt:xsl/order-to-json.xsl");
```

## Options

| option | default | description |
|---|---|---|
| `output` | `string` | `string`, `bytes`, `DOM` (serialized XML text, as there is no DOM type) or `file` (written to the file named by the `CamelXsltFileName` header; the body becomes the file path). |
| `contentCache` | `true` | Compile the stylesheet once. Set `false` to re-read it for every message. |
| `failOnNullBody` | `true` | Fail when the body is null. |
| `deleteOutputFile` | `false` | With `output=file`, delete the file when the exchange completes. |
| `allowTemplateFromHeader` | `false` | Use the `CamelXsltStylesheet` / `CamelXsltResourceUri` headers when present. |

Accepted and ignored (Java-only settings): `transformerFactory`, `transformerFactoryClass`,
`transformerFactoryConfigurationStrategy`, `uriResolver`, `uriResolverFactory`,
`resultHandlerFactory`, `entityResolver`, `errorListener`, `xsltMessageLogger`,
`transformerCacheSize`, `allowStAX`, `lazyStartProducer`.

**Parameters:** exchange properties, then message headers, are passed as global `xsl:param`
values, as in Camel.

### What the processor supports

A complete XSLT 1.0 processor: templates with match patterns, priorities and modes,
`apply-templates`, `call-template`, parameters, variables, `for-each`, `choose`, `sort`,
`copy`/`copy-of`, `element`/`attribute`, `number`, `key()`, `format-number()`, `document()`,
`generate-id()`, `exsl:node-set()`, and `xsl:output` with the xml, html and text methods.
Stylesheets with `version="2.0"` get XPath 2.0 and the XSLT 2.0 core; see
[xslt-saxon](https://pmsudhi.github.io/cameleer/docs/components/xslt-saxon.html).

## Message headers

| header | direction | description |
|---|---|---|
| `CamelXsltFileName` | in | Output file for `output=file`. |
| `CamelXsltStylesheet` | in | Stylesheet text used instead of the resource (needs `allowTemplateFromHeader=true`). |
| `CamelXsltResourceUri` | in | Stylesheet resource used instead of the endpoint's one (needs `allowTemplateFromHeader=true`). |
| any header | in | Available to the stylesheet as an `xsl:param` with the header's name. |

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/order-to-json.camel.yaml
```

Relative stylesheet paths resolve against `/routes`, the image's working directory.

## Common questions

### How do I pass a value into the stylesheet?

Declare `<xsl:param name="x"/>` at the top level and set a header (or exchange property)
named `x` before the `xslt` step.

### How do I produce JSON with XSLT?

Use `<xsl:output method="text"/>` and write the JSON with `xsl:text` and `xsl:value-of`, as in
the example. For a generic XML-to-JSON mapping without a stylesheet, use [xj](https://pmsudhi.github.io/cameleer/docs/components/xj.html).

### Is XSLT 2.0 or 3.0 supported?

XSLT 1.0 fully; `version="2.0"` stylesheets get the XSLT 2.0 core (grouping, functions, regex).
XSLT 3.0-only instructions such as `xsl:iterate` and `xsl:try` fail with a
`TransformerConfigurationException` naming the instruction.

## Related

- [xslt-saxon](https://pmsudhi.github.io/cameleer/docs/components/xslt-saxon.html): the same processor under Camel's Saxon scheme.
- [xj](https://pmsudhi.github.io/cameleer/docs/components/xj.html), [xquery](https://pmsudhi.github.io/cameleer/docs/components/xquery.html), [validator](https://pmsudhi.github.io/cameleer/docs/components/validator.html).
- [XPath language](https://pmsudhi.github.io/cameleer/docs/languages/xpath.html).
- [Apache Camel XSLT component](https://camel.apache.org/components/next/xslt-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/components/xslt-saxon.html

# XSLT Saxon component

> The `xslt-saxon` component transforms XML with an XSLT stylesheet like `xslt`, under the scheme Camel uses for Saxon; `version="2.0"` stylesheets get XPath 2.0 and the XSLT 2.0 core.

**Scheme:** `xslt-saxon:` · **Crate:** `cameleer-xml` · **Cargo feature:** [`xml`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Consumer:** no · **Producer:** yes ·
**Apache Camel:** [XSLT Saxon](https://camel.apache.org/components/next/xslt-saxon-component.html)

## When to use it

- Run routes written for Camel's `xslt-saxon` component without changing them.
- Group and aggregate XML with `xsl:for-each-group`, write reusable `xsl:function`s, or split
  text with `xsl:analyze-string` (XSLT 2.0).
- Summarize a large XML export into a short report that fits in an LLM context window.

There is no Saxon inside Cameleer: `xslt-saxon` and [`xslt`](https://pmsudhi.github.io/cameleer/docs/components/xslt.html) use the same built-in
processor. The XSLT version comes from the stylesheet's `version` attribute in both cases.

## URI format

```text
xslt-saxon:templateResource[?options]
```

## Example

Group sales lines by region and total them, an XSLT 2.0 task (`for-each-group`,
`current-group()`, `string-join`).

```xml
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="text"/>
  <xsl:template match="/sales">
    <xsl:for-each-group select="sale" group-by="@region">
      <xsl:sort select="current-grouping-key()"/>
      <xsl:value-of select="current-grouping-key()"/>
      <xsl:text>: </xsl:text>
      <xsl:value-of select="sum(current-group()/@amount)"/>
      <xsl:text> (</xsl:text>
      <xsl:value-of select="string-join(current-group()/@rep, ', ')"/>
      <xsl:text>)&#10;</xsl:text>
    </xsl:for-each-group>
  </xsl:template>
</xsl:stylesheet>
```

```yaml
- route:
    id: xslt-saxon-group
    from:
      uri: direct:xslt-saxon-group
      steps:
        - to: xslt-saxon:xsl/sales-by-region.xsl
```

```xml
<sales>
  <sale region="west" rep="ann" amount="100"/>
  <sale region="east" rep="bob" amount="250"/>
  <sale region="west" rep="cid" amount="50"/>
</sales>
```

```text
east: 250 (bob)
west: 150 (ann, cid)
```

## Rust DSL

```rust
b.from("direct:xslt-saxon-rust")
    .to("xslt-saxon:xsl/sales-by-region.xsl");
```

## Options

The options of the [xslt component](https://pmsudhi.github.io/cameleer/docs/components/xslt.html#options): `output`, `contentCache` (default
`true`), `failOnNullBody`, `deleteOutputFile`, `allowTemplateFromHeader`. Also accepted and
ignored: `saxonExtensionFunctions`, `saxonConfiguration`, `saxonReaderProperties`,
`secureProcessing`, plus the Java-only settings listed on the xslt page.

### XSLT 2.0 support

With `version="2.0"`: XPath 2.0 expressions, `xsl:for-each-group` (`group-by`,
`group-adjacent`, `group-starting-with`, `group-ending-with`), `xsl:function`,
`xsl:sequence`, typed variables and parameters (`as`), `xsl:analyze-string` with
`regex-group()`, tunnel parameters, `xsl:result-document`, `xsl:next-match`, `xsl:namespace`,
`xsl:perform-sort`, `xsl:value-of` with `separator`. XSLT 3.0-only instructions
(`xsl:iterate`, `xsl:try`, `xsl:merge`) and schema-aware processing fail with a
`TransformerConfigurationException`. Saxon extension functions are not available.

## Message headers

Same as [xslt](https://pmsudhi.github.io/cameleer/docs/components/xslt.html#message-headers): `CamelXsltFileName`, `CamelXsltStylesheet`,
`CamelXsltResourceUri`, and every header as an `xsl:param`.

## Run it with Docker

```sh
docker run --rm -v "$PWD:/routes:ro" pmsudhi/cameleer run /routes/sales.camel.yaml
```

## Common questions

### Do I need a Saxon license or jar?

No. Cameleer has its own processor; the scheme only exists so Camel routes keep working.

### What is the difference between `xslt` and `xslt-saxon` here?

Only the extra accepted Saxon option names. Both run XSLT 1.0, and XSLT 2.0 when the
stylesheet says `version="2.0"`.

### My stylesheet uses `xsl:iterate`. What can I do?

Rewrite it with recursion (a named template or an `xsl:function`) or `xsl:for-each`; XSLT 3.0
is not supported.

## Related

- [xslt](https://pmsudhi.github.io/cameleer/docs/components/xslt.html), [xquery](https://pmsudhi.github.io/cameleer/docs/components/xquery.html), [xj](https://pmsudhi.github.io/cameleer/docs/components/xj.html).
- [Apache Camel XSLT Saxon component](https://camel.apache.org/components/next/xslt-saxon-component.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/bean.html

# Bean language

> The `bean` language (also named `method`) calls a function registered in the registry and uses its return value as the expression result.

**Name:** `bean` · **Also:** `method` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) · **Apache Camel:** [Bean method](https://camel.apache.org/components/next/languages/bean-language.html)

## When to use it

- Compute a value in Rust (a price, a risk score, a lookup in a local cache) and use it in a
  YAML route wherever an expression is expected.
- Route with a Rust function as the predicate.
- Replace Java bean calls when you port Camel routes: `method: {ref: pricing, method: discount}`.

## Syntax

Cameleer has no Java classes, so "beans" are functions bound in the registry with
`cameleer_core::language::bind_bean_method(registry, name, |ex| ...)`. The expression names
the bean and, optionally, the method:

| text | looks up |
|---|---|
| `pricing.discount`, `pricing::discount`, `pricing?method=discount` | `pricing.discount`, then `pricing::discount`, then `pricing` |
| `pricing` | `pricing` |

A parameter list in the method name (`discount(${body})`) is stripped: the function always
receives the whole exchange. A registered processor can be used too: it runs on a copy of the
exchange and its resulting body is the value.

In YAML the language key is `method:` (`bean` is the name of the bean processor step). Use
`method: pricing.discount`, or the mapping form with `ref` and `method`. In
[Simple](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) the same call is `${bean:pricing.discount}`.

## Examples

The registry holds two functions bound in Rust (see [Rust DSL](#rust-dsl)):
`pricing.discount` and `risk.isHigh`.

```yaml
- route:
    id: bean-demo
    from:
      uri: direct:bean
      steps:
        - setHeader:
            name: discount
            method:
              ref: pricing
              method: discount
        - choice:
            when:
              - method: risk.isHigh
                steps:
                  - setBody:
                      simple: "manual review (discount ${header.discount}%)"
            otherwise:
              steps:
                - setBody:
                    simple: "auto approve (discount ${header.discount}%)"
```

```text
120
```

```text
auto approve (discount 10%)
```

```text
5000
```

```text
manual review (discount 10%)
```

## Options

| option | default | description |
|---|---|---|
| `ref` | (none) | The bean name, when the expression text is empty. |
| `method` | (none) | The method name; overrides a method given in the text. |
| `beanType`, `scope` | | Not used by the language (there are no classes to instantiate). |

## Rust DSL

Bind the functions:

```rust
let reg = ctx.registry();
cameleer_core::language::bind_bean_method(reg, "pricing.discount", |ex: &Exchange| -> Result<Value> {
    let amount = ex.body().to_string().parse::<i64>().unwrap_or(0);
    Ok(Value::Int(if amount >= 100 { 10 } else { 0 }))
});
cameleer_core::language::bind_bean_method(reg, "risk.isHigh", |ex: &Exchange| -> Result<Value> {
    Ok(Value::Bool(ex.body().to_string().parse::<i64>().unwrap_or(0) > 1000))
});
```

Use them in a route:

```rust
b.from("direct:bean-rust")
    .set_header("discount", bean_method("pricing", "discount"))
    .set_body(method("risk.isHigh"));
```

## Common questions

### How do I call a Rust function from YAML?

Bind it with `bind_bean_method(ctx.registry(), "name.method", |ex| ...)` and use
`method: name.method` in the route.

### Can I pass arguments to the method?

Not as a parameter list. The function receives the exchange, so read the body, headers or
properties from it; set them with `setHeader` before the call if needed.

### What is the difference between the `bean` language and the `bean` step?

The language returns a value for an expression (`setHeader`, `filter`, `choice`...). The
`bean` step calls the bean as a processor and sets the body.

## Related

- [Ref language](https://pmsudhi.github.io/cameleer/docs/languages/ref.html), [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) (`${bean:name.method}`)
- [Apache Camel Bean language](https://camel.apache.org/components/next/languages/bean-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/constant.html

# Constant language

> The `constant` language returns its text unchanged, optionally converted to a type with `resultType`.

**Name:** `constant` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) · **Apache Camel:** [Constant](https://camel.apache.org/components/next/languages/constant-language.html)

## When to use it

- Set a header, property or body to a fixed value: a content type, a status, a model name.
- Pass a literal where an expression is required, without Simple parsing `${...}` in it.
- Set a typed value (a number or a boolean) with `resultType`.

## Syntax

The expression text is the value. Nothing in it is evaluated, so `${body}` stays the literal
text `${body}`.

In YAML, a plain number or boolean in an expression position is also a constant:
`setHeader: {name: retries, expression: 3}` gives the integer `3`.

## Example

Set a header and the body to fixed values.

```yaml
- route:
    id: constant-demo
    from:
      uri: direct:constant
      steps:
        - setHeader:
            name: Content-Type
            constant: application/json
        - setHeader:
            name: retries
            constant:
              expression: "3"
              resultType: int
        - setBody:
            simple: '{"type":"${header.Content-Type}","retries":${header.retries},"retriesType":"${header.retries.getClass()}"}'
```

```text
anything
```

```json
{"type":"application/json","retries":3,"retriesType":"java.lang.Integer"}
```

The text is not evaluated:

```json
{"body": "Hello"}
```

| expression | result |
|---|---|
| `application/json` | `application/json` |
| `${body}` | `${body}` |
| `42` | `42` |

## Options

| option | default | description |
|---|---|---|
| `resultType` | (none) | Convert the text to this type: `int`, `Integer`, `long`, `double`, `boolean`, `String`... |

## Rust DSL

```rust
b.from("direct:constant-rust")
    .set_header("Content-Type", constant("application/json"))
    .set_body(constant("fixed body"));
```

## Common questions

### How do I set a header to a fixed value?

Use `setHeader` with `constant: value`. A plain string under `expression:` is parsed as Simple,
so prefer `constant:` when the value contains `${`.

### How do I set a number instead of a string?

Add `resultType: int` (or `long`, `double`, `boolean`), or write the number unquoted as the
expression in YAML.

## Related

- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html): templates with `${...}` functions.
- [Header language](https://pmsudhi.github.io/cameleer/docs/languages/header.html), [exchangeProperty language](https://pmsudhi.github.io/cameleer/docs/languages/exchangeProperty.html),
  [variable language](https://pmsudhi.github.io/cameleer/docs/languages/variable.html).
- [Apache Camel Constant language](https://camel.apache.org/components/next/languages/constant-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/csimple.html

# CSimple language

> The `csimple` language is an alias of the Simple language in Cameleer: the same syntax and the same results, so routes written for Camel's compiled Simple run unchanged.

**Name:** `csimple` · **Crate:** `cameleer-script` · **Cargo feature:** [`script`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Apache Camel:** [CSimple](https://camel.apache.org/components/next/languages/csimple-language.html)

## When to use it

- You are moving routes from Apache Camel that use `csimple:` and want them to run as they are.
- For new routes, use `simple:` directly; it is already parsed once into a syntax tree when the
  route starts, which is what csimple gives you in Camel.

## Syntax

Everything on the [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) page applies. In Apache Camel, csimple compiles
the expression to Java source at build time and supports a smaller function set; in Cameleer
it is the full Simple language.

## Examples

```yaml
- route:
    id: csimple-demo
    from:
      uri: direct:csimple
      steps:
        - filter:
            csimple: "${header.amount} > 100"
            steps:
              - setHeader:
                  name: review
                  constant: "true"
        - setBody:
            csimple: "Hello ${body}, review=${header.review}"
```

```text
Ada
```

```text
Hello Ada, review=true
```

```json
{"body": "Hello World", "headers": {"amount": 250}}
```

| expression | result |
|---|---|
| `${body.toUpperCase()}` | `HELLO WORLD` |
| `${header.amount > 100 ? 'big' : 'small'}` | `big` |

| expression | result |
|---|---|
| `${header.amount} range '100..300'` | `true` |
| `${body} contains 'Moon'` | `false` |

## Options

None.

## Rust DSL

```rust
b.from("direct:csimple-rust")
    .set_body(language("csimple", "Hello ${body}"));
```

## Common questions

### Is csimple faster than simple in Cameleer?

No, they are the same code. Both parse the expression once when the route is created.

## Related

- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html)
- [Apache Camel CSimple language](https://camel.apache.org/components/next/languages/csimple-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/datasonnet.html

# DataSonnet language

> The `datasonnet` language maps the message body to a new document with Jsonnet: the body is `payload`, the result is JSON text by default.

**Name:** `datasonnet` · **Crate:** `cameleer-script` · **Cargo feature:** [`script`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [DataSonnet](https://camel.apache.org/components/next/languages/datasonnet-language.html)

## When to use it

- Map an incoming JSON request into the payload a model API or another service expects, as a
  declarative template.
- Convert between JSON, XML, CSV and form data with `bodyMediaType` and `outputMediaType`.
- Aggregate and reshape arrays (`std.foldl`, comprehensions, the `ds` library).

## Syntax

The expression is a Jsonnet program. Cameleer runs its own Jsonnet interpreter (no JVM, no
sjsonnet). Available:

| name | what it is |
|---|---|
| `payload` | the body, read according to `bodyMediaType` (JSON is parsed) |
| `cml.header(name)` | a header |
| `cml.exchangeProperty(name)` | an exchange property |
| `cml.variable(name)` | an exchange variable |
| `cml.properties(key)` | a property placeholder value |
| `std.*` | the common Jsonnet standard library functions |
| `ds.*` | the DataSonnet library: `ds.map`, `ds.filter`, `ds.upper`, `ds.datetime`, `ds.crypto`, `ds.strings`... |

The language covers Jsonnet objects (with `self`, `super`, hidden `::` fields, `+:` merges),
arrays, `local`, functions, `if`/`then`/`else`, comprehensions, `%` formatting, `error`,
`assert` and local `import`. The result is written according to `outputMediaType`: with the
default `application/json` it is JSON text with the object keys sorted (as sjsonnet does), so a
string result comes back quoted (`"x"`). Use `outputMediaType: text/plain` for plain text.

## Examples

### Map a request into a model API payload

```yaml
- route:
    id: datasonnet-payload
    from:
      uri: direct:datasonnet-payload
      steps:
        - setBody:
            datasonnet: |
              {
                model: cml.header('model'),
                messages: [
                  { role: 'system', content: 'You answer questions about orders.' },
                  { role: 'user', content: payload.question },
                ],
                max_tokens: if payload.short then 100 else 500,
              }
```

```json
{"question":"Where is order 42?","short":true}
```

```json
{"max_tokens":100,"messages":[{"content":"You answer questions about orders.","role":"system"},{"content":"Where is order 42?","role":"user"}],"model":"gpt-4o-mini"}
```

### Aggregate an array to plain text

```yaml
- route:
    id: datasonnet-total
    from:
      uri: direct:datasonnet-total
      steps:
        - setBody:
            datasonnet:
              expression: "'total=' + std.toString(std.foldl(function(t, i) t + i.qty, payload.items, 0))"
              outputMediaType: text/plain
```

```json
{"items":[{"qty":2},{"qty":5},{"qty":1}]}
```

```text
total=8
```

### Expressions

```json
{"bodyText": "{\"user\":{\"name\":\"Ada\"},\"values\":[1,2,3]}", "headers": {"h": "v"}, "properties": {"p": "q"}}
```

| expression | result |
|---|---|
| `{name: payload.user.name}` | `{"name":"Ada"}` |
| `std.foldl(function(t, i) t + i, payload.values, 0)` | `6` |
| `[v * 2 for v in payload.values]` | `[2,4,6]` |
| `ds.upper(payload.user.name)` | `"ADA"` |
| `cml.header('h')` | `"v"` |
| `cml.exchangeProperty('p')` | `"q"` |
| `std.length(payload.values)` | `3` |

## Options

| option | default | description |
|---|---|---|
| `bodyMediaType` | `application/json` | How to read the body into `payload`: `application/json`, `text/plain`, `application/xml`, `application/csv`, `application/x-www-form-urlencoded`, `application/x-java-object`. Parameters such as `application/csv; separator=;` are supported. |
| `outputMediaType` | `application/json` | How to write the result: the same media types. |
| `resultType` | (none) | Convert the result to this type instead of writing it with `outputMediaType`. |

## Rust DSL

```rust
b.from("direct:datasonnet-rust")
    .set_body(cameleer_script::datasonnet("{total: std.foldl(function(t, i) t + i, payload.values, 0)}"));
```

## Common questions

### Why is my string result wrapped in quotes?

The default output media type is `application/json`, and a JSON string is quoted. Set
`outputMediaType: text/plain`.

### Why are the keys of my output sorted?

Jsonnet objects have no field order; the output is written with sorted keys, like sjsonnet used
by Apache Camel.

### How do I read a header?

`cml.header('name')`. Properties and variables use `cml.exchangeProperty` and `cml.variable`.

## Related

- [JSONPath](https://pmsudhi.github.io/cameleer/docs/languages/jsonpath.html) and [jq](https://pmsudhi.github.io/cameleer/docs/languages/jq.html) for picking fields.
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html).
- [Apache Camel DataSonnet language](https://camel.apache.org/components/next/languages/datasonnet-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/exchangeProperty.html

# ExchangeProperty language

> The `exchangeProperty` language returns the value of one exchange property, or null when the property is not set.

**Name:** `exchangeProperty` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) · **Apache Camel:** [ExchangeProperty](https://camel.apache.org/components/next/languages/exchangeProperty-language.html)

## When to use it

- Keep a value for the whole exchange (it is not sent to endpoints like headers are) and read
  it back later in the route: the original request, a tenant id, a correlation key.
- Restore the original body after a call that replaced it, for example after asking a model.
- Read properties that Cameleer sets, such as `CamelSplitIndex` inside a split or
  `CamelTimerCounter` on timer routes.

## Syntax

The expression text is the property name. The value keeps its type. In
[Simple](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) the same value is `${exchangeProperty.name}`.

## Examples

Save the request in a property, replace the body, then put the request back:

```yaml
- route:
    id: property-demo
    from:
      uri: direct:property
      steps:
        - setProperty:
            name: originalRequest
            simple: "${body}"
        - setBody:
            constant: "(answer from a model)"
        - setHeader:
            name: answer
            simple: "${body}"
        - setBody:
            exchangeProperty: originalRequest
        - setBody:
            simple: "${body} -> ${header.answer}"
```

```text
Summarize ticket 42
```

```text
Summarize ticket 42 -> (answer from a model)
```

Read the split index set by the `split` EIP:

```yaml
- route:
    id: property-split-index
    from:
      uri: direct:property-split
      steps:
        - split:
            tokenize: ","
            aggregationStrategy: GroupedBodyAggregationStrategy
            steps:
              - setHeader:
                  name: index
                  exchangeProperty: CamelSplitIndex
              - setBody:
                  simple: "${header.index}=${body}"
```

```text
a,b,c
```

```text
["0=a","1=b","2=c"]
```

```json
{"body": "x", "properties": {"tenant": "acme", "attempt": 2}}
```

| expression | result |
|---|---|
| `tenant` | `acme` |
| `attempt` | `2` |
| `missing` | (empty) |

## Options

The exchangeProperty language has no options.

## Rust DSL

```rust
b.from("direct:property-rust")
    .set_property("original", body())
    .set_body(constant("replaced"))
    .set_body(exchange_property("original"));
```

## Common questions

### What is the difference between a header and an exchange property?

Headers belong to the message and are sent to endpoints (HTTP headers, Kafka headers...).
Exchange properties stay inside Cameleer for the life of the exchange.

### How do I read the split index or the loop counter?

Use `exchangeProperty: CamelSplitIndex` (or `CamelSplitSize`, `CamelSplitComplete`,
`CamelLoopIndex`).

## Related

- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) (`${exchangeProperty.name}`)
- [Header language](https://pmsudhi.github.io/cameleer/docs/languages/header.html), [variable language](https://pmsudhi.github.io/cameleer/docs/languages/variable.html)
- [Apache Camel ExchangeProperty language](https://camel.apache.org/components/next/languages/exchangeProperty-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/groovy.html

# Groovy language

> The `groovy` language evaluates Groovy expressions and scripts against the message, with `body`, `headers`, `request` and `exchange` available as variables.

**Name:** `groovy` · **Crate:** `cameleer-script` · **Cargo feature:** [`script`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [Groovy](https://camel.apache.org/components/next/languages/groovy-language.html)

## When to use it

- Port existing Camel routes that use Groovy predicates and transformations without a JVM.
- Transform lists and maps with GDK methods (`collect`, `findAll`, `sum`, `groupBy`) and
  GPath (`items*.price`).
- Write a short `script` step that changes several headers and the body.

## Syntax

Cameleer runs Groovy in its own interpreter, written in Rust. There is no JVM and no Groovy
compiler. It covers Groovy as used in route scripts: `def` and typed variables, closures (`it`),
GStrings, `?.`, `?:`, the spread operator `*.`, GPath, list and map literals, ranges, regex
operators (`=~`, `==~`), `switch` expressions, classes, traits, enums, common AST transforms
(`@ToString`, `@Canonical`, `@Immutable`...), metaclass additions, `JsonSlurper` and
`JsonOutput`, and the GDK collection methods. Not supported: `@Grab` (no dependencies can be
loaded), static type checking (`@CompileStatic` is accepted and ignored), arbitrary Java
libraries.

Variables available to the script:

| variable | what it is |
|---|---|
| `body` | the message body |
| `headers` | the message headers (`headers.name`, `headers['name']`) |
| `request`, `message` | the message: `request.body`, `request.headers.name = 'x'` |
| `exchange` | the exchange: `exchange.in.body`, `exchange.properties.x`, `exchange.getIn().setHeader(...)` |
| `properties`, `exchangeProperties` | the exchange properties |
| `variables` | the exchange variables |
| `camelContext` | the context |
| `log` | a logger |

The value of the last statement is the result. Used as an expression the script works on a copy
of the message; in a `script` step its changes are kept and the result is ignored.

## Examples

### Total an order with GPath

```yaml
- route:
    id: groovy-total
    from:
      uri: direct:groovy-total
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: total
            groovy: "body.items.collect { it.qty * it.price }.sum()"
        - setBody:
            groovy: "\"${body.items*.sku.join(',')} = ${headers.total}\""
```

```json
{"items":[{"sku":"A1","qty":2,"price":5},{"sku":"B2","qty":1,"price":12}]}
```

```text
A1,B2 = 22
```

### Filter with a Groovy predicate

```yaml
- route:
    id: groovy-filter
    from:
      uri: direct:groovy-filter
      steps:
        - setHeader:
            name: verdict
            constant: dropped
        - filter:
            groovy: "request.body ==~ /(?i).*refund.*/"
            steps:
              - setHeader:
                  name: verdict
                  constant: kept
        - setBody:
            simple: "${header.verdict}"
```

```text
Please process my Refund
```

```text
kept
```

```text
Where is my parcel?
```

```text
dropped
```

### A script step

```yaml
- route:
    id: groovy-script
    from:
      uri: direct:groovy-script
      steps:
        - script:
            groovy: |
              def items = request.body.split(',')
              request.headers.count = items.size()
              request.body = items.collect { it.trim().toUpperCase() }.join('|')
        - setBody:
            simple: "${body} (${header.count})"
```

```text
kafka, mqtt , amqp
```

```text
KAFKA|MQTT|AMQP (3)
```

### Expressions

```json
{"body": "hello", "headers": {"amount": 250, "name": "Ada"}}
```

| expression | result |
|---|---|
| `body.toUpperCase()` | `HELLO` |
| `body.reverse()` | `olleh` |
| `request.headers.amount > 100` | `true` |
| `"Hi ${headers.name}"` | `Hi Ada` |
| `[1, 2, 3].collect { it * 2 }.sum()` | `12` |
| `headers.missing ?: 'none'` | `none` |
| `body?.size()` | `5` |
| `(1..4).findAll { it % 2 == 0 }` | `[2,4]` |

## Options

| option | default | description |
|---|---|---|
| `resultType` | (none) | Convert the result to this type (`int`, `String`, `boolean`...). |

## Rust DSL

```rust
b.from("direct:groovy-rust")
    .filter(cameleer_script::groovy("request.headers.amount > 100"))
    .set_body(cameleer_script::groovy("'big order: ' + headers.amount"));
```

## Common questions

### Can I run my existing Camel Groovy scripts?

Usually yes, if they only use the Camel bindings, Groovy syntax and the GDK. Scripts that load
Java libraries, use `@Grab` or call Spring beans by class need changes.

### How do I parse JSON in Groovy?

Either unmarshal first (`unmarshal: json`) and navigate `body.field`, or call
`new groovy.json.JsonSlurper().parseText(body)`.

### Why does my header change disappear?

Changes made in `setBody`/`setHeader`/`filter` expressions are made on a copy. Use a `script`
step to modify the message.

## Related

- [JavaScript](https://pmsudhi.github.io/cameleer/docs/languages/js.html), [Python](https://pmsudhi.github.io/cameleer/docs/languages/python.html), [Java](https://pmsudhi.github.io/cameleer/docs/languages/java.html) script languages.
- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html).
- [Apache Camel Groovy language](https://camel.apache.org/components/next/languages/groovy-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/header.html

# Header language

> The `header` language returns the value of one message header, or null when the header is not set.

**Name:** `header` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) · **Apache Camel:** [Header](https://camel.apache.org/components/next/languages/header-language.html)

## When to use it

- Copy a header into the body, a property or another header without writing a Simple template.
- Use a header as a predicate in `filter` or `choice`: a header is true when it is set and not
  `false`, `0` or empty.
- Use a header that holds a list as the expression of a `split`.

## Syntax

The expression text is the header name, for example `priority` or `CamelFileName`. Leading
and trailing spaces are trimmed. The value keeps its type: a number stays a number and a list
stays a list. The same value is `${header.priority}` in [Simple](https://pmsudhi.github.io/cameleer/docs/languages/simple.html).

## Examples

Route on a header set by the caller (for example a model's classification of a ticket):

```yaml
- route:
    id: header-demo
    from:
      uri: direct:header
      steps:
        - choice:
            when:
              - header: urgent
                steps:
                  - setBody:
                      header: assignee
            otherwise:
              steps:
                - setBody:
                    constant: backlog
```

```text
Checkout is down
```

```text
on-call
```

Without the `urgent` header the predicate is false:

```text
How do I change my address?
```

```text
backlog
```

Split a header that holds a list:

```yaml
- route:
    id: header-split
    from:
      uri: direct:header-split
      steps:
        - setHeader:
            name: tags
            simple: "${body.split(',')}"
        - split:
            header: tags
            aggregationStrategy: GroupedBodyAggregationStrategy
            steps:
              - setBody:
                  simple: "tag:${body}"
```

```text
red,green,blue
```

```text
["tag:red","tag:green","tag:blue"]
```

Values against a fixture message:

```json
{"body": "x", "headers": {"priority": "high", "retries": 3, "tags": ["a", "b"]}}
```

| expression | result |
|---|---|
| `priority` | `high` |
| `retries` | `3` |
| `tags` | `["a","b"]` |
| `missing` | (empty) |

## Options

The header language has no options.

## Rust DSL

```rust
b.from("direct:header-rust")
    .filter(header("urgent"))
    .set_body(header("assignee"));
```

## Common questions

### How do I read a header in a route?

Use `header: name` wherever an expression is expected, or `${header.name}` inside a Simple
template when you need it in a larger text.

### What happens when the header does not exist?

The result is null. As a predicate it is false, and `setBody` with a missing header sets an
empty body.

### Are header names case sensitive?

Yes, names are matched exactly.

## Related

- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) (`${header.name}`, `${headers}`)
- [exchangeProperty language](https://pmsudhi.github.io/cameleer/docs/languages/exchangeProperty.html), [variable language](https://pmsudhi.github.io/cameleer/docs/languages/variable.html),
  [constant language](https://pmsudhi.github.io/cameleer/docs/languages/constant.html)
- [Apache Camel Header language](https://camel.apache.org/components/next/languages/header-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/hl7terser.html

# HL7 Terser language

> The `hl7terser` language reads a field from an HL7 v2 message with a terser path such as `PID-5-1` (patient family name).

**Name:** `hl7terser` · **Crate:** `cameleer-protocols` · **Cargo feature:** [`protocols`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Apache Camel:** [HL7 Terser](https://camel.apache.org/components/next/languages/hl7terser-language.html)

## When to use it

- Route hospital messages by type (`MSH-9`, `MSH-9-2`) or sending application (`MSH-3`).
- Copy patient or order fields into headers before converting the message to JSON for another
  system, or before handing a de-identified summary to an AI service.

## Syntax

The body is an HL7 v2 message in ER7 text (segments separated by `\r` or newlines) or the
structure produced by the [hl7 data format](https://pmsudhi.github.io/cameleer/docs/dataformats/hl7.html).

| path | meaning |
|---|---|
| `PID-5` | segment `PID`, field 5 (the first component when the field has components) |
| `PID-5-2` | field 5, component 2 |
| `PID-5-1-1` | sub-component |
| `PID-3(1)-1` | the second repetition (0-based) of field 3, component 1 |
| `OBX(1)-5` | the second `OBX` segment (0-based), field 5 |
| `/.MSH-10` | a leading `/.` is accepted, as in HAPI terser paths |

For `MSH`, field 1 is the field separator and field 2 the encoding characters, as in HL7.
Escape sequences (`\F\`, `\S\`...) are decoded. A field that is absent in an existing segment
gives an empty string; a missing segment gives null. An invalid path fails when the route is
created.

## Examples

```yaml
- route:
    id: hl7terser-demo
    from:
      uri: direct:hl7terser
      steps:
        - setHeader:
            name: patient
            hl7terser: PID-5-1
        - setHeader:
            name: mrn
            hl7terser: PID-3-1
        - choice:
            when:
              - hl7terser: PV1-2
                steps:
                  - setBody:
                      simple: "visit for ${header.patient} (MRN ${header.mrn})"
            otherwise:
              steps:
                - setBody:
                    simple: "no visit for ${header.patient}"
```

A terser path used as a predicate is true when the field has a value:

```text
MSH|^~\&|ADT|HOSP|EHR|HOSP|20240102120000||ADT^A01|MSG0001|P|2.5
PID|1||12345^^^MRN||Doe^John
PV1|1|I
```

```text
visit for Doe (MRN 12345)
```

```text
MSH|^~\&|ADT|HOSP|EHR|HOSP|20240102120000||ADT^A08|MSG0002|P|2.5
PID|1||12345^^^MRN||Doe^John
```

```text
no visit for Doe
```

Read several fields, including repetitions and repeated segments:

```yaml
- route:
    id: hl7terser-fields
    from:
      uri: direct:hl7terser-fields
      steps:
        - setHeader:
            name: type
            hl7terser: MSH-9
        - setHeader:
            name: event
            hl7terser: MSH-9-2
        - setHeader:
            name: secondId
            hl7terser: PID-3(1)-1
        - setHeader:
            name: secondObx
            hl7terser: OBX(1)-5
        - setBody:
            simple: "${header.type}^${header.event} ids=${header.secondId} obx=${header.secondObx}"
```

```text
MSH|^~\&|LAB|HOSP|EHR|HOSP|20240102120000||ORU^R01|MSG0001|P|2.5
PID|1||12345^^^MRN~67890^^^SSN||Doe^John
OBX|1|ST|GLU||5.4
OBX|2|ST|HB||13.9
```

```text
ORU^R01 ids=67890 obx=13.9
```

## Options

None.

## Rust DSL

```rust
b.from("direct:hl7terser-rust")
    .set_header("patient", language("hl7terser", "PID-5-1"))
    .set_body(language("hl7terser", "MSH-9-2"));
```

## Common questions

### How do I get the message type of an HL7 message?

`hl7terser: MSH-9` gives the message code (`ADT`), `MSH-9-2` the trigger event (`A01`). The
[hl7 data format](https://pmsudhi.github.io/cameleer/docs/dataformats/hl7.html) also sets `CamelHL7MessageType` and `CamelHL7TriggerEvent`
headers when it unmarshals.

### Are repetition and segment indexes 0-based?

Yes, as in HAPI: `PID-3(0)` is the first repetition, `OBX(1)` the second OBX segment.

## Related

- [HL7 data format](https://pmsudhi.github.io/cameleer/docs/dataformats/hl7.html), [mllp component](https://pmsudhi.github.io/cameleer/docs/components/mllp.html)
- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html)
- [Apache Camel HL7 Terser language](https://camel.apache.org/components/next/languages/hl7terser-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/java.html

# Java language

> The `java` language (also `joor`) evaluates Java snippets against the message, with `exchange`, `message` and `body` available as variables.

**Name:** `java` · **Also:** `joor` · **Crate:** `cameleer-script` · **Cargo feature:** [`script`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [Java](https://camel.apache.org/components/next/languages/java-language.html),
[jOOR](https://camel.apache.org/components/next/languages/joor-language.html)

## When to use it

- Reuse Java snippets from existing Camel `java`/`joor` expressions.
- Write a transformation with streams, `String.format` or `java.time` when the team thinks in
  Java.

## Syntax

Apache Camel compiles these snippets with the JDK at startup. Cameleer interprets them instead:
there is no JDK, no compiler and no classpath. The snippet is Java syntax evaluated with Java
semantics (integer division, `ArithmeticException`, Java `toString`): typed locals and `var`,
casts, `if`/`for`/`while`/`switch` (also switch expressions and type patterns), lambdas, method
references, text blocks, classes, records and enums declared in the snippet, `try`/`catch`, and
the common JDK API (`String`, `Math`, `List`/`Map`/`Set`, `Arrays`, `Collections`, `Optional`,
streams and `Collectors`, `java.time`). Not available: other JDK or third-party classes,
reflection, threads, and compile-time checks (generics are not checked).

A single expression is its own result; a snippet with statements ends with `return`.

Variables and helpers:

| name | what it is |
|---|---|
| `exchange` | the exchange (`exchange.getIn()`, `exchange.getMessage()`, `exchange.setProperty(..)`) |
| `message` | the message (`message.getHeader("x")`, `message.getHeader("x", String.class)`, `message.setBody(..)`) |
| `body` | the message body (cast it: `((String) body)`) |
| `optionalBody` | the body as an `Optional` |
| `bodyAs(Type.class)` | the body converted to a type |
| `header(name)`, `headerAs(name, Type.class)` | a header |
| `exchangeProperty(name)`, `variable(name)` | a property, a variable |

## Examples

### Format a summary with streams

```yaml
- route:
    id: java-summary
    from:
      uri: direct:java-summary
      steps:
        - setBody:
            java: |
              var parts = ((String) body).split(",");
              int total = Arrays.stream(parts).mapToInt(p -> Integer.parseInt(p.trim())).sum();
              return String.format("%d readings, total %d", parts.length, total);
```

```text
4, 8, 15, 16
```

```text
4 readings, total 43
```

### A script step that sets a header

```yaml
- route:
    id: java-script
    from:
      uri: direct:java-script
      steps:
        - script:
            joor: |
              exchange.getMessage().setHeader("len", body.toString().length());
              message.setBody(((String) body).toUpperCase());
        - setBody:
            simple: "${body}/${header.len}"
```

```text
camel
```

```text
CAMEL/5
```

### Expressions

```json
{"body": "hello", "headers": {"amount": 250, "name": "Ada"}}
```

| expression | result |
|---|---|
| `((String) body).toUpperCase()` | `HELLO` |
| `message.getHeader("name")` | `Ada` |
| `"Hi " + message.getHeader("name", String.class)` | `Hi Ada` |
| `var n = (Integer) message.getHeader("amount"); return n > 100;` | `true` |
| `exchange.getIn().getBody(String.class).substring(1)` | `ello` |
| `7 / 2` | `3` |

## Options

| option | default | description |
|---|---|---|
| `resultType` | (none) | Convert the result to this type. |

## Rust DSL

```rust
b.from("direct:java-rust")
    .set_body(cameleer_script::joor("((String) body).length() * 2"));
```

## Common questions

### Is my Java code compiled?

No. It is parsed and interpreted at route start, so a syntax error fails the route at startup,
but type errors (wrong generics, missing returns) are not reported.

### What is the difference between `java` and `joor`?

None in Cameleer: both names select the same interpreter. Camel 4 renamed `joor` to `java`.

## Related

- [Groovy](https://pmsudhi.github.io/cameleer/docs/languages/groovy.html), [JavaScript](https://pmsudhi.github.io/cameleer/docs/languages/js.html) script languages.
- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html).
- [Apache Camel Java language](https://camel.apache.org/components/next/languages/java-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/js.html

# JavaScript language

> The `js` language evaluates JavaScript expressions and scripts against the message, with `body`, `headers` and `exchange` available as variables.

**Name:** `js` · **Also:** `javascript`, `javaScript` · **Crate:** `cameleer-script` · **Cargo feature:** [`script`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [JavaScript](https://camel.apache.org/components/next/languages/js-language.html)

## When to use it

- Reshape a JSON answer from an LLM or an API with a few lines of code (`JSON.parse`, `map`,
  `filter`, `JSON.stringify`) where Simple or JSONPath gets awkward.
- Route on a computed condition in `filter` or `choice`.
- Run a small script step that sets several headers at once.

## Syntax

Cameleer runs JavaScript in its own interpreter, written in Rust. It is not GraalJS or V8 and
does not need a JVM. It covers ES5.1 plus most of ES2015-2023 as used in route scripts: `let` and
`const`, arrow functions, template literals, destructuring, spread, classes, optional chaining
`?.`, `??`, `Map` and `Set`, generators, `Promise` and `async`/`await` (drained before the
result is returned), `JSON`, `Math`, `Intl` for a few locales. There is no Node.js API
(`require('fs')`, `process`, network access), and no access to Java classes beyond a few safe
JDK types through `Java.type`.

Variables available to the script:

| variable | what it is |
|---|---|
| `body` | the message body (a string body stays a string: use `JSON.parse(body)` for JSON text) |
| `headers` | the message headers: `headers.get('name')` or `headers.name` |
| `request`, `message` | the message: `request.body`, `request.headers.name`, `request.setHeader(k, v)` |
| `exchange` | the exchange with Java-like accessors: `exchange.getIn().getHeader('x')`, `exchange.setProperty(k, v)` |
| `properties`, `exchangeProperties` | the exchange properties |
| `variables` | the exchange variables |
| `camelContext` | the context (`camelContext.getName()`) |
| `log` | a logger (`log.info('...')`) |

The value of the last expression statement is the result. Used as an expression (in `setBody`,
`setHeader`, `filter`...) the script works on a copy of the message and only its result counts.
In a `script` step the result is ignored and its changes to body, headers, properties and
variables are kept.

## Examples

### Reshape an LLM's JSON answer

The model answered with JSON text. Keep only confident labels and build a compact routing
decision.

```yaml
- route:
    id: js-reshape
    from:
      uri: direct:js-reshape
      steps:
        - setBody:
            js: |
              const answer = JSON.parse(body);
              const labels = answer.labels.filter(l => l.score >= 0.5).map(l => l.name);
              JSON.stringify({ ticket: answer.id, labels, urgent: labels.includes('outage') });
```

```json
{"id":"T-17","labels":[{"name":"billing","score":0.2},{"name":"outage","score":0.93},{"name":"eu","score":0.71}]}
```

```json
{"ticket":"T-17","labels":["outage","eu"],"urgent":true}
```

### Route with a JavaScript predicate

```yaml
- route:
    id: js-choice
    from:
      uri: direct:js-choice
      steps:
        - choice:
            when:
              - js: "headers.get('amount') > 1000"
                steps:
                  - setBody:
                      constant: needs approval
            otherwise:
              steps:
                - setBody:
                    js: "'auto-approved: ' + headers.get('amount')"
```

```text
order
```

```text
needs approval
```

```text
order
```

```text
auto-approved: 40
```

### A script step that changes the message

```yaml
- route:
    id: js-script
    from:
      uri: direct:js-script
      steps:
        - script:
            js: |
              const words = body.trim().split(/\s+/);
              request.setHeader('wordCount', words.length);
              request.body = words.map(w => w[0].toUpperCase() + w.slice(1)).join(' ');
        - setBody:
            simple: "${body} (${header.wordCount} words)"
```

```text
send messages to kafka
```

```text
Send Messages To Kafka (4 words)
```

### Expressions

Evaluated against this message:

```json
{"body": "hello", "headers": {"amount": 250, "name": "Ada"}, "properties": {"region": "eu"}, "variables": {"user": "ada"}}
```

| expression | result |
|---|---|
| `body.toUpperCase()` | `HELLO` |
| `headers.get('amount') > 100` | `true` |
| `request.headers.name + '!'` | `Ada!` |
| `exchange.getIn().getHeader('name')` | `Ada` |
| `` `Hi ${headers.get('name')}` `` | `Hi Ada` |
| `[1, 2, 3].map(x => x * 2).join(',')` | `2,4,6` |
| `properties.region` | `eu` |
| `variables.user` | `ada` |
| `typeof body` | `string` |

## Options

| option | default | description |
|---|---|---|
| `resultType` | (none) | Convert the result to this type (`int`, `String`, `boolean`...). |
| `scriptDir` | (none) | Directory that relative ES module imports resolve against. |

## Rust DSL

```rust
b.from("direct:js-rust")
    .set_header("len", cameleer_script::js("body.length"))
    .set_body(cameleer_script::js("body.toUpperCase()"));
```

## Common questions

### How do I parse a JSON body in JavaScript?

A JSON text body is a string, so call `JSON.parse(body)`. If an earlier step already
unmarshalled the body (for example `unmarshal: json`), `body` is an object and `body.field` works
directly.

### How do I change headers from a script?

Use a `script` step and call `request.setHeader('name', value)` or
`exchange.getIn().setHeader(...)`. In `setBody` or `setHeader` the script runs on a copy, so
other changes are discarded.

### Can I use npm packages or Node.js modules?

No. The interpreter has no Node.js runtime. Local ES modules can be imported relative to
`scriptDir`.

## Related

- [Groovy](https://pmsudhi.github.io/cameleer/docs/languages/groovy.html), [Python](https://pmsudhi.github.io/cameleer/docs/languages/python.html) and [Java](https://pmsudhi.github.io/cameleer/docs/languages/java.html) script languages.
- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) for one-line templates, [JSONPath](https://pmsudhi.github.io/cameleer/docs/languages/jsonpath.html) and [jq](https://pmsudhi.github.io/cameleer/docs/languages/jq.html)
  for picking fields from JSON.
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html).
- [Apache Camel JavaScript language](https://camel.apache.org/components/next/languages/js-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/jq.html

# jq language

> The `jq` language queries and transforms JSON with jq 1.7 programs such as `.items | map(.price) | add`.

**Name:** `jq` · **Crate:** `cameleer-core` · **Cargo feature:** [`jq`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Apache Camel:** [JQ](https://camel.apache.org/components/next/languages/jq-language.html)

## When to use it

- Reshape JSON in one expression: pick fields, rename them, build a new object for the next API.
- Clean up an LLM's JSON answer: parse the tool-call `arguments` string with `fromjson`, apply
  defaults with `//`, keep only the fields the next step accepts.
- Compute values: sums, counts, grouping, sorting.
- Filter and route with a predicate such as `.priority == "P1"`.

## Syntax

Cameleer contains its own implementation of the jq 1.7 language (Apache Camel uses
jackson-jq). Supported:

- paths `.`, `..`, `.foo`, `."foo"`, `.[e]`, `.[a:b]`, `.[]`, optional `?`
- pipes `|`, comma `,`, alternative `//`, arithmetic, comparison and boolean operators
- assignment `=`, `|=`, `+=`, `-=`, `*=`, `/=`, `%=`, `//=`
- array and object construction, string interpolation `"\(.x)"`
- formats `@text @json @html @uri @csv @tsv @sh @base64 @base64d @base32 @base32d`
- `if/elif/else/end`, `try/catch`, `reduce`, `foreach`, `label`/`break`, variables and
  destructuring, `?//`, function definitions with recursion, `$ENV`, `$__loc__`, comments
- the jq 1.7 builtins except module and I/O functions: `length keys has in map map_values
  path paths getpath setpath del to_entries from_entries with_entries select empty error add
  any all flatten range floor sqrt pow log tostring tonumber type sort sort_by group_by unique
  unique_by min max min_by max_by reverse contains indices index startswith endswith ltrimstr
  rtrimstr trim explode implode split join ascii_downcase ascii_upcase recurse transpose first
  last nth until while repeat limit walk tojson fromjson test match capture scan splits sub
  gsub todate fromdate now mktime gmtime strftime strptime abs toarray IN INDEX`, math
  functions and more

Camel functions (as in camel-jq): `header(name)`, `header(name; default)`,
`property(name)`, `property(name; default)`, `variable(name)`.

**Result.** One output gives that value, no output gives null, several outputs give an
array of all outputs. `input` and `inputs` fail: there is one input per exchange.

**Input.** A structured body is used as is. A text or bytes body is parsed as JSON, so a
plain text body that is not JSON fails with a parse error.

### Syntax reference, tested

```json
{"body": {"store": {"book": [
  {"category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95},
  {"category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99},
  {"category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99}],
  "bicycle": {"color": "red", "price": 19.95}}},
 "headers": {"tenant": "acme"}, "properties": {"region": "eu"}, "variables": {"user": "ada"}}
```

| expression | result |
|---|---|
| `.store.book[0].title` | `Sayings of the Century` |
| `.store.book[].author` | `["Nigel Rees","Evelyn Waugh","Herman Melville"]` |
| `.store.book \| length` | `3` |
| `[.store.book[] \| select(.price < 10) \| .title]` | `["Sayings of the Century","Moby Dick"]` |
| `.store.book \| map(.price) \| add` | `30.93` |
| `{color: .store.bicycle.color, books: (.store.book \| length)}` | `{"color":"red","books":3}` |
| `.store.book \| group_by(.category) \| map({(.[0].category): length}) \| add` | `{"fiction":2,"reference":1}` |
| `.store.book \| sort_by(.price) \| .[0].title` | `Sayings of the Century` |
| `[.store.book[].category] \| unique` | `["fiction","reference"]` |
| `.store.bicycle \| keys` | `["color","price"]` |
| `.store.bicycle \| to_entries \| map("\(.key)=\(.value)") \| join("&")` | `color=red&price=19.95` |
| `.store.book[0].isbn // "n/a"` | `n/a` |
| `if .store.bicycle.price > 15 then "pricey" else "cheap" end` | `pricey` |
| `[.store.book[].title \| ascii_upcase \| .[0:4]]` | `["SAYI","SWOR","MOBY"]` |
| `reduce .store.book[] as $b (0; . + $b.price) \| floor` | `30` |
| `.store.book[1].title \| test("honou?r"; "i")` | `true` |
| `.store.book[2].author \| sub("Herman "; "H. ")` | `H. Melville` |
| `.store.bicycle \| del(.price)` | `{"color":"red"}` |
| `.store.bicycle.price \|= . * 2 \| .store.bicycle` | `{"color":"red","price":39.9}` |
| `.store.bicycle \| tojson` | `{"color":"red","price":19.95}` |
| `.store.book[0] \| [.author, .price] \| @csv` | `"Nigel Rees",8.95` |
| `[paths(type == "number")] \| length` | `4` |
| `.store.bicycle.color, .store.bicycle.price` | `["red",19.95]` |
| `.store.missing` | (empty) |
| `header("tenant")` | `acme` |
| `header("missing"; "none")` | `none` |
| `property("region")` | `eu` |
| `variable("user")` | `ada` |

As predicates, the expression is true when any output is truthy (not `false` or `null`):

| expression | result |
|---|---|
| `.store.bicycle.price > 15` | `true` |
| `any(.store.book[]; .price > 20)` | `false` |
| `.store.book[2] \| has("isbn")` | `true` |
| `.store.missing` | `false` |

## Examples

### Parse tool-call arguments from an LLM answer

The `arguments` field of an OpenAI-style tool call is a JSON string; `fromjson` parses it.

```yaml
- route:
    id: jq-tool-call
    from:
      uri: direct:jq-tool-call
      steps:
        - setHeader:
            name: tool
            jq: ".choices[0].message.tool_calls[0].function.name"
        - setBody:
            jq: '.choices[0].message.tool_calls[0].function.arguments | fromjson | {city, units: (.units // "metric")}'
```

```json
{"choices":[{"message":{"tool_calls":[{"id":"c1","type":"function","function":{"name":"get_weather","arguments":"{\"city\":\"Paris\"}"}}]}}]}
```

```text
{"city":"Paris","units":"metric"}
```

### Reshape an order and route on the result

```yaml
- route:
    id: jq-reshape
    from:
      uri: direct:jq-reshape
      steps:
        - setBody:
            jq: '{id: .orderId, total: (.lines | map(.qty * .price) | add), customer: .customer.name}'
        - choice:
            when:
              - jq: ".total > 100"
                steps:
                  - setHeader:
                      name: lane
                      constant: review
            otherwise:
              steps:
                - setHeader:
                    name: lane
                    constant: auto
        - setBody:
            simple: "${header.lane}: ${body}"
```

```json
{"orderId":"A-7","customer":{"name":"Ada"},"lines":[{"sku":"x","qty":2,"price":30},{"sku":"y","qty":1,"price":50}]}
```

```text
review: {"id":"A-7","total":110,"customer":"Ada"}
```

## Options

| option | default | description |
|---|---|---|
| `resultType` | (none) | Convert the result, e.g. `String`, `Integer`, `Boolean`. |
| `headerName` | (none) | Evaluate the header with this name instead of the body. |
| `propertyName` | (none) | Evaluate this exchange property. |
| `variableName` | (none) | Evaluate this variable. |
| `source` | (none) | `header:name`, `property:name`, `variable:name` or `body`. |

## Rust DSL

```rust
b.from("direct:jq-rust")
    .filter(jq(".total > 100"))
    .set_body(jq("{id, total}"));
```

## Common questions

### How do I parse a JSON string that sits inside JSON?

Use `fromjson`, for example `.function.arguments | fromjson`. The reverse is `tojson`.

### How do I give a default when a field is missing?

Use the alternative operator: `.units // "metric"`.

### Can jq read headers?

Yes: `header("name")`, or `header("name"; "default")`. Use `property(...)` and `variable(...)`
for exchange properties and variables.

### Is it real jq?

It is an independent implementation of the jq 1.7 language in Rust, with no `jq` binary
involved. Module (`import`, `include`) and I/O functions are not available.

## Related

- [JSONPath language](https://pmsudhi.github.io/cameleer/docs/languages/jsonpath.html): simpler path queries
- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) and its `jq(...)` function
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html), [json-validator component](https://pmsudhi.github.io/cameleer/docs/components/json-validator.html)
- [Apache Camel JQ language](https://camel.apache.org/components/next/languages/jq-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/jsonpath.html

# JSONPath language

> The `jsonpath` language selects values from a JSON document with JSONPath expressions such as `$.choices[0].message.content`.

**Name:** `jsonpath` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) · **Apache Camel:** [JSONPath](https://camel.apache.org/components/next/languages/jsonpath-language.html)

## When to use it

- Pick a field out of a JSON message: an order id, a status, a price.
- Read the answer of an LLM API: `$.choices[0].message.content` of an OpenAI-style chat
  completion, or the arguments of a tool call.
- Filter or route JSON messages with a predicate (`[?(@.price < 10)]`, or "does this path
  exist").
- Split a JSON array into one message per element.

## Syntax

Cameleer implements the Jayway JsonPath syntax that Apache Camel uses, written from scratch.

| syntax | meaning |
|---|---|
| `$` | the root (the body) |
| `.name`, `['name']`, `["name"]` | a child by name |
| `['a','b']` | several children (union) |
| `[n]`, `[-n]` | array element; negative counts from the end |
| `[a,b]` | several elements |
| `[start:end:step]` | slice |
| `[*]`, `.*` | all elements or children |
| `..name`, `..*`, `..[n]` | recursive descent |
| `[?(<filter>)]` | filter: `@` is the current item, `$` the root |
| `.length()` `.size()` `.min()` `.max()` `.avg()` `.sum()` `.stddev()` `.keys()` `.first()` `.last()` | trailing functions |

Filter operators: `==`, `!=`, `<`, `<=`, `>`, `>=`, `=~` (regex, `/.../` or `/.../i`), `in`,
`nin`, `contains`, `size`, `empty`, `anyof`, `noneof`, `subsetof`, combined with `&&`, `||`,
`!` and parentheses. A bare path (`[?(@.isbn)]`) tests that the field exists.

**Result shape.** A definite path (no wildcard, recursion, slice, filter or union) returns a
single value. Any other path returns an array, possibly empty. A definite path that does not
exist raises `PathNotFoundException` unless `suppressExceptions` is true; as a predicate it is
simply false.

**Input.** The body can be a structured value or JSON text (a string or bytes); text is parsed
first.

### Syntax reference, tested

```json
{"body": {"store": {"book": [
  {"category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95},
  {"category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99},
  {"category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99}],
  "bicycle": {"color": "red", "price": 19.95}}}}
```

| expression | result |
|---|---|
| `$.store.book[0].title` | `Sayings of the Century` |
| `$['store']['bicycle']['color']` | `red` |
| `$.store.book[-1].title` | `Moby Dick` |
| `$.store.book[*].author` | `["Nigel Rees","Evelyn Waugh","Herman Melville"]` |
| `$.store.book[0,2].title` | `["Sayings of the Century","Moby Dick"]` |
| `$.store.book[0:2].title` | `["Sayings of the Century","Sword of Honour"]` |
| `$.store.bicycle['color','price']` | `["red",19.95]` |
| `$.store.*.color` | `["red"]` |
| `$..price` | `[8.95,12.99,8.99,19.95]` |
| `$.store.book[?(@.price < 10)].title` | `["Sayings of the Century","Moby Dick"]` |
| `$.store.book[?(@.isbn)].title` | `["Moby Dick"]` |
| `$.store.book[?(@.category == 'fiction' && @.price > 10)].author` | `["Evelyn Waugh"]` |
| `$.store.book[?(!(@.price < 10))].title` | `["Sword of Honour"]` |
| `$.store.book[?(@.author =~ /.*Melville/)].title` | `["Moby Dick"]` |
| `$.store.book[?(@.category in ['reference'])].title` | `["Sayings of the Century"]` |
| `$.store.book[?(@.category nin ['reference'])].title` | `["Sword of Honour","Moby Dick"]` |
| `$..book[?(@.title size 9)].title` | `["Moby Dick"]` |
| `$.store.book[?(@.price < $.store.bicycle.price)].category` | `["reference","fiction","fiction"]` |
| `$.store.book.length()` | `3` |
| `$.store.book[*].price.sum()` | `30.93` |
| `$.store.book[*].price.avg()` | `10.31` |
| `$..price.max()` | `19.95` |
| `$.store.bicycle.keys()` | `["color","price"]` |
| `$.store.book[*].title.first()` | `Sayings of the Century` |
| `$.store.missing` | `error: PathNotFoundException` |

As predicates (used by `filter`, `choice`, `validate`): a non-empty result is true, a missing
path is false.

| expression | result |
|---|---|
| `$.store.book[?(@.price > 10)]` | `true` |
| `$.store.book[?(@.price > 100)]` | `false` |
| `$.store.bicycle.color` | `true` |
| `$.store.missing` | `false` |

## Examples

### Read the answer of an LLM chat completion

```yaml
- route:
    id: jsonpath-llm-answer
    from:
      uri: direct:llm-answer
      steps:
        - setHeader:
            name: finishReason
            jsonpath: "$.choices[0].finish_reason"
        - setBody:
            jsonpath: "$.choices[0].message.content"
        - setBody:
            simple: "${body} (${header.finishReason})"
```

```json
{"id":"chatcmpl-1","choices":[{"index":0,"finish_reason":"stop","message":{"role":"assistant","content":"Refund approved"}}]}
```

```text
Refund approved (stop)
```

### Route on a field, with a default when it is missing

```yaml
- route:
    id: jsonpath-route
    from:
      uri: direct:jsonpath-route
      steps:
        - choice:
            when:
              - jsonpath: "$.order[?(@.total > 100)]"
                steps:
                  - setBody:
                      constant: review
              - jsonpath:
                  expression: "$.order.express"
                  suppressExceptions: true
                steps:
                  - setBody:
                      constant: express
            otherwise:
              steps:
                - setBody:
                    constant: standard
```

```json
{"order":{"id":1,"total":250}}
```

```text
review
```

```json
{"order":{"id":2,"total":20,"express":true}}
```

```text
express
```

```json
{"order":{"id":3,"total":20}}
```

```text
standard
```

### Split tool calls into one message each

```yaml
- route:
    id: jsonpath-split
    from:
      uri: direct:tool-calls
      steps:
        - split:
            jsonpath: "$.choices[0].message.tool_calls[*]"
            aggregationStrategy: GroupedBodyAggregationStrategy
            steps:
              - setBody:
                  simple: "${body.function.name}(${body.function.arguments})"
```

```json
{"choices":[{"message":{"tool_calls":[
  {"id":"c1","function":{"name":"get_weather","arguments":"{\"city\":\"Paris\"}"}},
  {"id":"c2","function":{"name":"get_time","arguments":"{\"tz\":\"CET\"}"}}]}}]}
```

```text
["get_weather({\"city\":\"Paris\"})","get_time({\"tz\":\"CET\"})"]
```

### Read from a header instead of the body

```yaml
- route:
    id: jsonpath-header-source
    from:
      uri: direct:jsonpath-header
      steps:
        - setHeader:
            name: user
            simple: '{"name":"Ada","roles":["admin","dev"]}'
        - setBody:
            jsonpath:
              expression: "$.roles.length()"
              headerName: user
              resultType: String
```

```text
ignored
```

```text
2
```

## Options

| option | default | description |
|---|---|---|
| `resultType` | (none) | Convert the result, e.g. `String`, `Integer`, `Double`, `Boolean`. |
| `suppressExceptions` | `false` | Return null instead of failing when a definite path does not exist or the input is null. |
| `headerName` | (none) | Evaluate the header with this name instead of the body. |
| `propertyName` | (none) | Evaluate this exchange property. |
| `variableName` | (none) | Evaluate this variable. |
| `source` | (none) | `header:name`, `property:name` (or `exchangeProperty:name`), `variable:name` or `body`. |
| `unpackArray` | `false` | A one-element array result becomes the element itself. |
| `writeAsString` | `false` | Object and array results become JSON text. |
| `allowSimple` | `false` | Accepted; with it a null input gives null instead of an error. |

## Rust DSL

```rust
b.from("direct:jsonpath-rust")
    .set_header("finishReason", jsonpath("$.choices[0].finish_reason"))
    .set_body(jsonpath_as("$.choices[0].message.content", "String"));
```

## Common questions

### How do I get the text of an OpenAI chat completion?

`jsonpath: "$.choices[0].message.content"`. For tool calls use
`$.choices[0].message.tool_calls[*]` and split on it.

### Why do I get an array when I expected one value?

Wildcards, filters, slices, unions and `..` always return an array. Add `unpackArray: true`,
take an element in a later step, or end the path with `.first()`.

### How do I avoid an exception when a field is missing?

Set `suppressExceptions: true` to get null. In a `filter` or `choice` a missing path is already
false.

### Can I use JSONPath inside a Simple template?

Yes: `${jsonpath('$.order.id')}` evaluates against the body inside [Simple](https://pmsudhi.github.io/cameleer/docs/languages/simple.html).

## Related

- [jq language](https://pmsudhi.github.io/cameleer/docs/languages/jq.html): transformations as well as queries
- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) and its `jsonpath(...)` function
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html), [json-validator component](https://pmsudhi.github.io/cameleer/docs/components/json-validator.html)
- [Apache Camel JSONPath language](https://camel.apache.org/components/next/languages/jsonpath-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/mvel.html

# MVEL language

> The `mvel` language evaluates MVEL 2 expressions against the exchange, with `request`, `headers`, `body` and `exchange` as the root object's properties.

**Name:** `mvel` · **Crate:** `cameleer-script` · **Cargo feature:** [`script`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [MVEL](https://camel.apache.org/components/next/languages/mvel-language.html)

## When to use it

- Port Camel routes that use MVEL predicates and expressions.
- Write compact property-navigation expressions (`request.headers.amount * 2`) with Java-like
  method calls.
- For MVEL templates (`@{...}` orb tags), use the [mvel component](https://pmsudhi.github.io/cameleer/docs/components/mvel.html).

## Syntax

Cameleer interprets MVEL itself, without the MVEL library or a JVM. Supported: property
navigation, method calls, inline lists `['a', 'b']`, maps and arrays, `contains`, `is`, `empty`,
`nil`, projections `(name in list)`, `;`-separated statements, assignments, typed declarations
(`int x = 5`), `with (obj) {...}`, `if`/`else`, `foreach`, `while`, `def` functions and
interceptors (`@Name statement`, registered from Rust). Arbitrary Java classes are not
available.

The root object has these properties:

| property | what it is |
|---|---|
| `request`, `in` | the message: `request.body`, `request.headers.name` |
| `response`, `out` | the message (Camel's out message) |
| `exchange` | the exchange: `exchange.in.body`, `exchange.properties` |
| `body`, `headers` | the body and headers directly |
| `properties` | the exchange properties |
| `context`, `camelContext` | the context |

## Examples

```yaml
- route:
    id: mvel-demo
    from:
      uri: direct:mvel
      steps:
        - setHeader:
            name: doubled
            mvel: "request.headers.amount * 2"
        - filter:
            mvel: "request.headers.doubled > 100"
            steps:
              - setBody:
                  mvel: "request.body.toUpperCase() + ' ' + request.headers.doubled"
```

```text
priority
```

```text
PRIORITY 120
```

```json
{"body": "hello", "headers": {"amount": 250, "name": "Ada"}}
```

| expression | result |
|---|---|
| `request.body.toUpperCase()` | `HELLO` |
| `request.headers.amount > 100` | `true` |
| `headers.name + '!'` | `Ada!` |
| `exchange.in.body` | `hello` |
| `body.length()` | `5` |
| `['a', 'b'].size()` | `2` |
| `int x = 5; x * request.headers.amount` | `1250` |

## Options

| option | default | description |
|---|---|---|
| `resultType` | (none) | Convert the result to this type. |

## Rust DSL

```rust
b.from("direct:mvel-rust")
    .set_header("next", cameleer_script::mvel("request.headers.n + 1"));
```

## Common questions

### What is the difference between the mvel language and the mvel component?

The language evaluates one expression inside a route step. The
[mvel component](https://pmsudhi.github.io/cameleer/docs/components/mvel.html) renders a template file (`mvel:template.mvel`) into the
body.

### Can MVEL call my Java classes?

No. There is no JVM; only the Camel root object, values and common JDK-like methods work.

## Related

- [OGNL](https://pmsudhi.github.io/cameleer/docs/languages/ognl.html) and [SpEL](https://pmsudhi.github.io/cameleer/docs/languages/spel.html): similar Java expression languages.
- [mvel component](https://pmsudhi.github.io/cameleer/docs/components/mvel.html) for templates.
- [Apache Camel MVEL language](https://camel.apache.org/components/next/languages/mvel-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/ognl.html

# OGNL language

> The `ognl` language evaluates OGNL expressions against the exchange, with `request`, `headers`, `body` and `exchange` as the root object's properties.

**Name:** `ognl` · **Crate:** `cameleer-script` · **Cargo feature:** [`script`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [OGNL](https://camel.apache.org/components/next/languages/ognl-language.html)

## When to use it

- Port Camel routes that use OGNL predicates and expressions.
- Navigate properties and call methods in one line, with OGNL's projection and selection on
  lists.

## Syntax

Cameleer interprets OGNL itself, without the OGNL library or a JVM. Supported: property and
index navigation, method calls, static members of known JDK classes
(`@java.lang.Math@max(1, 2)`), `#this`, `#root` and `#var`, list literals `{a, b}`, map
literals `#{k: v}`, projection `.{expr}`, selection `.{? expr}`, `in`/`not in`, word operators
(`eq`, `gt`, `and`...), the ternary operator and `,` sequences. Arbitrary Java classes are not
available.

The root object has these properties:

| property | what it is |
|---|---|
| `request` | the message: `request.body`, `request.headers.name` |
| `response` | the message (Camel's out message) |
| `exchange` | the exchange: `exchange.in.body` |
| `body`, `headers` | the body and headers directly |
| `properties`, `property(name)` | the exchange properties |
| `context` | the context |

## Examples

```yaml
- route:
    id: ognl-demo
    from:
      uri: direct:ognl
      steps:
        - choice:
            when:
              - ognl: "request.headers.n > 10"
                steps:
                  - setBody:
                      ognl: "'large: ' + request.headers.n"
            otherwise:
              steps:
                - setBody:
                    ognl: "request.headers.n > 2 ? 'medium' : 'small'"
```

```text
x
```

```text
large: 42
```

```text
x
```

```text
medium
```

```json
{"body": "hello", "headers": {"amount": 250, "name": "Ada"}}
```

| expression | result |
|---|---|
| `request.body.toUpperCase()` | `HELLO` |
| `request.headers.amount > 100` | `true` |
| `request.headers.name + '!'` | `Ada!` |
| `exchange.in.body` | `hello` |
| `body.length()` | `5` |
| `request.headers.amount > 100 ? 'big' : 'small'` | `big` |
| `@java.lang.Math@max(3, 7)` | `7` |

## Options

| option | default | description |
|---|---|---|
| `resultType` | (none) | Convert the result to this type. |

## Rust DSL

```rust
b.from("direct:ognl-rust")
    .set_header("twice", cameleer_script::ognl("request.body.length() * 2"));
```

## Common questions

### Does OGNL support calling static methods?

Yes for the JDK classes the interpreter knows (`Math`, `Integer`, `String`...), with the
`@class@member` syntax. Other classes are not available.

## Related

- [MVEL](https://pmsudhi.github.io/cameleer/docs/languages/mvel.html) and [SpEL](https://pmsudhi.github.io/cameleer/docs/languages/spel.html).
- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html), which covers most of the same needs.
- [Apache Camel OGNL language](https://camel.apache.org/components/next/languages/ognl-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/python.html

# Python language

> The `python` language evaluates Python 3 expressions and scripts against the message, with `body`, `headers`, `request` and `exchange` available as variables.

**Name:** `python` · **Crate:** `cameleer-script` · **Cargo feature:** [`script`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [Python](https://camel.apache.org/components/next/languages/python-language.html)

## When to use it

- Post-process an LLM's JSON answer with familiar Python: `json.loads`, comprehensions,
  f-strings.
- Let data people who know Python write routing conditions and small transformations.
- Run on edge devices where installing CPython is not an option: the interpreter is part of the
  Cameleer binary.

## Syntax

Cameleer runs Python in its own interpreter, written in Rust. It is not CPython and has no
`pip`: C extensions and third-party packages (`requests`, `numpy`...) are not available. It
covers Python 3 as used in route scripts: indentation blocks, functions, lambdas, closures,
comprehensions, f-strings, slicing, `try`/`except`, classes, generators, `match`/`case`,
`async`/`await`, and the bundled modules `json`, `math`, `re`, `collections`, `functools`,
`itertools`, `dataclasses` and a few more. `json` is available without an import. User modules
can be imported relative to the script directory (`scriptDir` option) or the working directory.

Variables available to the script:

| variable | what it is |
|---|---|
| `body` | the message body |
| `headers` | the message headers (`headers['name']`, `headers.get('name', default)`) |
| `request`, `message` | the message: `request.body`, `request.headers` |
| `exchange` | the exchange: `exchange.getIn().setHeader(...)`, `exchange.setProperty(...)` |
| `properties`, `exchangeProperties` | the exchange properties |
| `variables` | the exchange variables |
| `camelContext` | the context |
| `log` | a logger |

The value of the last expression statement is the result. Used as an expression the script
works on a copy of the message; in a `script` step its changes are kept.

## Examples

### Extract fields from an LLM answer

```yaml
- route:
    id: python-llm
    from:
      uri: direct:python-llm
      steps:
        - setBody:
            python: |
              answer = json.loads(body)
              actions = [a['tool'] for a in answer['actions'] if a['confidence'] > 0.6]
              f"run {', '.join(actions)} for {answer['user']}"
```

```json
{"user":"ada","actions":[{"tool":"refund","confidence":0.9},{"tool":"escalate","confidence":0.3},{"tool":"email","confidence":0.8}]}
```

```text
run refund, email for ada
```

### Route with a Python predicate

```yaml
- route:
    id: python-choice
    from:
      uri: direct:python-choice
      steps:
        - choice:
            when:
              - python: "len(body) > 20"
                steps:
                  - setBody:
                      python: "body[:20] + '...'"
            otherwise:
              steps:
                - setBody:
                    python: "body.upper()"
```

```text
a sensor reading that is far too long
```

```text
a sensor reading tha...
```

```text
short
```

```text
SHORT
```

### A script step

```yaml
- route:
    id: python-script
    from:
      uri: direct:python-script
      steps:
        - script:
            python: |
              readings = [float(x) for x in body.split(',')]
              exchange.getIn().setHeader('max', max(readings))
              exchange.getIn().setBody(round(sum(readings) / len(readings), 2))
        - setBody:
            simple: "avg ${body}, max ${header.max}"
```

```text
21.5,22.25,20.0
```

```text
avg 21.25, max 22.25
```

### Expressions

```json
{"body": "a,b,c", "headers": {"amount": 250, "name": "Ada"}}
```

| expression | result |
|---|---|
| `body.upper()` | `A,B,C` |
| `headers['amount'] > 100` | `true` |
| `f"Hi {headers['name']}"` | `Hi Ada` |
| `len(body)` | `5` |
| `'\|'.join(reversed(body.split(',')))` | `c\|b\|a` |
| `[x * 2 for x in range(3)]` | `[0,2,4]` |
| `request.headers.get('missing', 'none')` | `none` |

## Options

| option | default | description |
|---|---|---|
| `resultType` | (none) | Convert the result to this type (`int`, `String`, `boolean`...). |
| `scriptDir` | (none) | Directory that `import` of user modules resolves against. |

## Rust DSL

```rust
b.from("direct:python-rust")
    .set_body(cameleer_script::python("body[::-1]"));
```

## Common questions

### Can I use pip packages?

No. Only the bundled standard modules (`json`, `math`, `re`, `collections`, `itertools`,
`functools`, `dataclasses`...) and your own `.py` modules are available.

### How do I return a value from a multi-line script?

End the script with an expression: its value is the result. A `return` at top level is not
needed.

### How do I set a header from Python?

In a `script` step call `exchange.getIn().setHeader('name', value)`.

## Related

- [JavaScript](https://pmsudhi.github.io/cameleer/docs/languages/js.html), [Groovy](https://pmsudhi.github.io/cameleer/docs/languages/groovy.html) script languages.
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html), [jq](https://pmsudhi.github.io/cameleer/docs/languages/jq.html), [JSONPath](https://pmsudhi.github.io/cameleer/docs/languages/jsonpath.html).
- [Apache Camel Python language](https://camel.apache.org/components/next/languages/python-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/ref.html

# Ref language

> The `ref` language looks up an expression or predicate by name in the registry and evaluates it, so routes can reuse logic written in Rust.

**Name:** `ref` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) · **Apache Camel:** [Ref](https://camel.apache.org/components/next/languages/ref-language.html)

## When to use it

- Keep a routing rule in Rust code (a scoring function, a feature flag, a policy check) and use
  it by name from YAML routes.
- Share one expression between many routes.

## Syntax

The expression text is the registry name. At evaluation time Cameleer looks up, in order:

1. an `Arc<dyn Expression>` bound under that name: it is evaluated;
2. an `Arc<dyn Predicate>`: as an expression it returns `true` or `false`;
3. any other bound value (for example a bean method or a plain value).

When nothing is bound under the name, the evaluation fails with `NoSuchBeanException`. When
used as a predicate, a bound predicate is called directly; otherwise the expression result is
tested for truth.

## Examples

The examples below use two registry entries bound in Rust (see [Rust DSL](#rust-dsl)): an
expression `shippingCost` and a predicate `isVip`.

```yaml
- route:
    id: ref-demo
    from:
      uri: direct:ref
      steps:
        - setHeader:
            name: shipping
            ref: shippingCost
        - choice:
            when:
              - ref: isVip
                steps:
                  - setBody:
                      simple: "VIP order, shipping ${header.shipping}"
            otherwise:
              steps:
                - setBody:
                    simple: "order, shipping ${header.shipping}"
```

```text
order
```

```text
VIP order, shipping 0
```

```text
order
```

```text
order, shipping 15
```

## Options

The ref language has no options.

## Rust DSL

Bind the expression and the predicate, then refer to them by name:

```rust
let reg = ctx.registry();
let shipping: Arc<dyn Expression> = Arc::new(|ex: &Exchange| -> Result<Value> {
    let vip = ex.header("customerTier").map(|t| t.to_string() == "gold").unwrap_or(false);
    let kg = ex.header("weightKg").and_then(|w| w.as_i64()).unwrap_or(0);
    Ok(Value::Int(if vip { 0 } else { 5 * kg }))
});
reg.bind("shippingCost", shipping);
let vip: Arc<dyn Predicate> = Arc::new(cameleer_core::spi::FnPredicate(|ex: &Exchange| {
    Ok(ex.header("customerTier").map(|t| t.to_string() == "gold").unwrap_or(false))
}));
reg.bind("isVip", vip);
```

```rust
b.from("direct:ref-rust")
    .filter(ref_expression("isVip"))
    .set_body(ref_expression("shippingCost"));
```

## Common questions

### How do I call my own Rust code from a YAML route?

Bind an `Arc<dyn Expression>` or `Arc<dyn Predicate>` in the registry and use `ref: name`. For
functions that compute a value from the exchange, the [bean language](https://pmsudhi.github.io/cameleer/docs/languages/bean.html) with
`bind_bean_method` is an alternative.

### What happens if the name is not bound?

Evaluation fails with `NoSuchBeanException`.

## Related

- [Bean language](https://pmsudhi.github.io/cameleer/docs/languages/bean.html), [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) (`${ref:name}`)
- [Apache Camel Ref language](https://camel.apache.org/components/next/languages/ref-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/simple.html

# Simple language

> Simple is Camel's built-in expression language: text templates with `${...}` functions that read the body, headers, properties and variables, plus predicates with operators such as `==`, `contains`, `regex` and `in`.

**Name:** `simple` · **Also:** `csimple` (same implementation, see [csimple](https://pmsudhi.github.io/cameleer/docs/languages/csimple.html)) · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Apache Camel:** [Simple](https://camel.apache.org/components/next/languages/simple-language.html)

Simple is what you use most in Cameleer routes: to build a message body or a prompt, set a
header, name a file, filter messages and route them. A plain string in a YAML expression
position is Simple, so `setBody: {expression: "Hello ${body}"}` and `setBody: {simple: "Hello ${body}"}`
are the same.

Every expression and result in the tables on this page is checked by the test suite
(`crates/cameleer-main/tests/docs_languages_formats.rs`) against the message shown above the table.

## Contents

- [When to use it](#when-to-use-it)
- [Syntax in one minute](#syntax-in-one-minute)
- [Examples: routes](#examples-routes)
- [Message functions](#message-functions): body, headers, properties, variables
- [Navigating JSON and objects (OGNL)](#navigating-json-and-objects-ognl)
- [Method calls on values](#method-calls-on-values)
- [String functions](#string-functions)
- [Collection functions](#collection-functions)
- [Math functions](#math-functions)
- [Conditionals: ternary, Elvis, iif, not](#conditionals-ternary-elvis-iif-not)
- [JSON, XML and other languages inside Simple](#json-xml-and-other-languages-inside-simple)
- [Exchange, context and environment functions](#exchange-context-and-environment-functions)
- [Dates](#dates)
- [Random values and ids](#random-values-and-ids)
- [File language](#file-language)
- [Predicates and operators](#predicates-and-operators)
- [Escaping and literal text](#escaping-and-literal-text)
- [Differences from Apache Camel](#differences-from-apache-camel)
- [Common questions](#common-questions)

## When to use it

- Build a body from parts of the message: `Hello ${header.name}, your order ${body.id} shipped`.
- Build an LLM prompt from a JSON request and pick fields out of the model's JSON answer.
- Route and filter: `${header.priority} == 'high' && ${body.amount} > 1000`.
- Name files and keys: `orders/${date:now:yyyy/MM/dd}/${file:onlyname.noext}.json`.
- Small transformations without code: trim, replace, split, join, sum, hash, base64.

For heavier JSON work use [JSONPath](https://pmsudhi.github.io/cameleer/docs/languages/jsonpath.html) or [jq](https://pmsudhi.github.io/cameleer/docs/languages/jq.html) (both callable from Simple), for
XML use [XPath](https://pmsudhi.github.io/cameleer/docs/languages/xpath.html), and for real logic a script language such as [JavaScript](https://pmsudhi.github.io/cameleer/docs/languages/js.html).

## Syntax in one minute

| you write | meaning |
|---|---|
| `Hello ${body}` | a template: literal text plus functions |
| `${header.name}` | a function inside `${...}` |
| `$simple{header.name}` | the same, for places where `${` is taken (Spring-style config) |
| `${body.order.id}` | navigation into a JSON object or map (OGNL) |
| `${body.toUpperCase()}` | a method call on the value |
| `${substring(1,3)}` | a function call, applied to the body when no value is given |
| `${header.a} == 'x' && ${body} contains 'y'` | a predicate (used by `filter`, `choice`, `validate`...) |
| `${header.n > 5 ? 'big' : 'small'}` | a ternary inside one function |

A template that is one function only (`${body.order.id}`) keeps the type of the value: a number
stays a number, a list stays a list. A template with any literal text around it gives a string.

## Examples: routes

### Build a prompt for a model from a JSON request

The body is parsed with the [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html), so Simple can navigate
into it. The prompt goes to the model (here it is just returned).

```yaml
- route:
    id: build-prompt
    from:
      uri: direct:prompt
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: tone
            simple: "${body.tone ?: 'friendly'}"
        - setBody:
            simple: |-
              You are a support agent for ${body.product}. Answer in a ${header.tone} tone.
              Customer ${body.customer.name} asks: ${body.question.trim()}
              Known order ids: ${join(', ', '#', ${body.orders})}
```

```json
{"product":"Acme Router","customer":{"name":"Ada"},"question":"  Why is the light red?  ","orders":[1001,1002]}
```

```text
You are a support agent for Acme Router. Answer in a friendly tone.
Customer Ada asks: Why is the light red?
Known order ids: #1001, #1002
```

### Route on the model's answer

A model was asked to answer with JSON such as `{"category":"billing","confidence":0.93}`.
Low-confidence answers go to a human queue.

```yaml
- route:
    id: route-on-answer
    from:
      uri: direct:answer
      steps:
        - unmarshal:
            json: {}
        - choice:
            when:
              - simple: "${body.confidence} < 0.6"
                steps:
                  - setBody:
                      simple: "human review: ${body.category}"
              - simple: "${body.category} in 'billing,refund'"
                steps:
                  - setBody:
                      simple: "billing queue (${body.confidence})"
            otherwise:
              steps:
                - setBody:
                    simple: "general queue: ${body.category.toUpperCase()}"
```

```json
{"category":"billing","confidence":0.93}
```

```text
billing queue (0.93)
```

```json
{"category":"refund","confidence":0.41}
```

```text
human review: refund
```

```json
{"category":"shipping","confidence":0.88}
```

```text
general queue: SHIPPING
```

### Filter with headers and a typed header

```yaml
- route:
    id: simple-filter
    from:
      uri: direct:filter
      steps:
        - setBody:
            constant: dropped
        - filter:
            simple: "${header.priority} =~ 'HIGH' && ${headerAs(amount, Integer)} range '100..10000'"
            steps:
              - setBody:
                  simple: "kept: ${header.priority} ${header.amount}"
```

```text
x
```

```text
kept: high 250
```

```text
x
```

```text
dropped
```

### Name a file with the file language and a date

The `CamelFileName` header is what the [file](https://pmsudhi.github.io/cameleer/docs/components/file.html) consumer sets; here it is
set by hand so the example runs without a directory.

```yaml
- route:
    id: simple-file-name
    from:
      uri: direct:file-name
      steps:
        - setHeader:
            name: CamelFileName
            constant: inbox/2024-06-orders.csv
        - setHeader:
            name: CamelFileLastModified
            constant:
              expression: "1718000000000"
              resultType: long
        - setBody:
            simple: "archive/${date:file:yyyy/MM}/${file:onlyname.noext}.json (${file:ext}, from ${file:parent})"
```

```text
a,b
```

```text
archive/2024/06/2024-06-orders.json (csv, from inbox)
```

### Increment a counter header and read the route id

```yaml
- route:
    id: counter-route
    from:
      uri: direct:counter
      steps:
        - setHeader:
            name: attempt
            simple: "${header.attempt}++"
        - setBody:
            simple: "route ${routeId}, attempt ${header.attempt}, body type ${bodyType}"
```

```text
x
```

```text
route counter-route, attempt 3, body type java.lang.String
```

### Use the exception message in an error handler

```yaml
- route:
    id: simple-exception
    from:
      uri: direct:exception
      steps:
        - doTry:
            steps:
              - setBody:
                  simple: "${mandatoryBodyAs(Integer)}"
            doCatch:
              - exception:
                  - java.lang.Exception
                steps:
                  - setBody:
                      simple: "failed (${exception.class}): not a number: ${body}"
```

```text
abc
```

```text
failed (NoTypeConversionAvailableException): not a number: abc
```

## Message functions

All tables in this section use this message (`body` is a string, `headers`, exchange
`properties` and `variables` are maps):

```json
{
  "body": "Hello World",
  "headers": {"name": "Ada", "amount": "250", "tags": "a,b,c", "n": 5, "priority": "high", "my-header": "dash"},
  "properties": {"region": "eu"},
  "variables": {"user": "ada"}
}
```

| expression | result | notes |
|---|---|---|
| `${body}` | `Hello World` | also `${in.body}`, `${message.body}` |
| `${bodyOneLine}` | `Hello World` | the body with line breaks removed |
| `${bodyType}` | `java.lang.String` | Java-style type name of the body |
| `${bodyAs(String)}` | `Hello World` | convert the body; `mandatoryBodyAs` fails when it cannot |
| `${header.name}` | `Ada` | also `${headers.name}`, `${in.header.name}` |
| `${header[name]}` | `Ada` | bracket form |
| `${header:name}` | `Ada` | colon form |
| `${header.my-header}` | `dash` | names may contain `-` |
| `${header.missing}` | (empty) | a missing header is null, rendered as empty text |
| `${headerAs(amount,Integer)}` | `250` | header converted to a type |
| `${headers}` | `{"amount":"250","my-header":"dash","n":5,"name":"Ada","priority":"high","tags":"a,b,c"}` | all headers as a map |
| `${exchangeProperty.region}` | `eu` | also `${exchangeProperty[region]}`, `${property.region}` |
| `${exchangePropertyAs(region,String)}` | `eu` | |
| `${variable.user}` | `ada` | also `${variables.user}`, `${variable:user}` |
| `${variableAs(user,String)}` | `ada` | |
| `${variables}` | `{"user":"ada"}` | all variables as a map |
| `Dear ${header.name}, you owe ${header.amount}.` | `Dear Ada, you owe 250.` | a template |

## Navigating JSON and objects (OGNL)

When the body (or a header) is a JSON object, a map or a list, `.` and `[...]` navigate into
it. A JSON text body is parsed on the fly for navigation, so `${body.a.b}` works on the string
`{"a":{"b":7}}` too. `?.` stops at null instead of failing.

```json
{
  "body": {
    "order": {"id": 42, "items": [{"sku": "A1", "qty": 2, "price": 9.5}, {"sku": "B2", "qty": 1, "price": 20}]},
    "customer": {"name": "Ada", "email": null}
  }
}
```

| expression | result | notes |
|---|---|---|
| `${body.order.id}` | `42` | keeps the number type |
| `${body.order.items[0].sku}` | `A1` | list index |
| `${body.order.items[last].price}` | `20` | `last` is the last element |
| `${body[customer][name]}` | `Ada` | bracket keys |
| `${body.customer?.email}` | (empty) | null-safe |
| `${body.missing?.email}` | (empty) | null-safe on a missing key |
| `${body.order.items.size()}` | `2` | methods work after navigation |
| `${body.customer.keySet()}` | `["name","email"]` | |
| `${body.customer.containsKey('name')}` | `true` | |
| `Order ${body.order.id} for ${body.customer.name}` | `Order 42 for Ada` | |

```json
{"bodyText": "{\"answer\":{\"label\":\"spam\",\"score\":0.97}}"}
```

| expression | result |
|---|---|
| `${body.answer.label}` | `spam` |
| `${body.answer.score}` | `0.97` |

## Method calls on values

Values support the common Java `String`, `List` and `Map` methods.

| expression | result |
|---|---|
| `${body.length()}` | `11` |
| `${body.toUpperCase()}` | `HELLO WORLD` |
| `${body.toLowerCase()}` | `hello world` |
| `${body.substring(6)}` | `World` |
| `${body.substring(0,5)}` | `Hello` |
| `${body.replace('World','Camel')}` | `Hello Camel` |
| `${body.replaceAll('[aeiou]','*')}` | `H*ll* W*rld` |
| `${body.replaceFirst('l','L')}` | `HeLlo World` |
| `${body.split(' ')}` | `["Hello","World"]` |
| `${body.startsWith('Hello')}` | `true` |
| `${body.endsWith('World')}` | `true` |
| `${body.contains('lo W')}` | `true` |
| `${body.indexOf('o')}` | `4` |
| `${body.charAt(4)}` | `o` |
| `${body.matches('H.*d')}` | `true` |
| `${body.equals('Hello World')}` | `true` |
| `${body.equalsIgnoreCase('hello world')}` | `true` |
| `${body.isEmpty()}` | `false` |
| `${header.name.trim()}` | `Ada` |
| `${header.n.getClass()}` | `java.lang.Integer` |
| `${header.amount.intValue()}` | `250` |
| `${header.tags.split(',')[1]}` | `b` |

## String functions

Most functions work on the body when no value is passed, or on the last argument (which can be
any expression, such as `${header.name}`). Arguments are quoted with `'` or `"`; inside function
arguments `&comma;`, `&space;`, `&empty;`, `&quot;` and `&apos;` stand for those characters.

| expression | result | notes |
|---|---|---|
| `${uppercase()}` | `HELLO WORLD` | |
| `${lowercase(${header.name})}` | `ada` | on another value |
| `${trim('  padded  ')}` | `padded` | |
| `${normalizeWhitespace('a   b  c')}` | `a b c` | collapse runs of whitespace |
| `${substring(6)}` | `World` | drop the first n characters |
| `${substring(-6)}` | `Hello` | drop the last n characters |
| `${substring(1,1)}` | `ello Worl` | drop n from the head and m from the tail |
| `${substringBefore(' ')}` | `Hello` | |
| `${substringAfter(' ')}` | `World` | |
| `${substringBetween('H','o')}` | `ell` | |
| `${replace('World','Camel')}` | `Hello Camel` | plain text replace (all) |
| `${replace(&space;,_)}` | `Hello_World` | entity for a space |
| `${concat('a','b')}` | `ab` | |
| `${concat(${header.name},'x','-')}` | `Ada-x` | third argument is a separator |
| `${length()}` | `11` | characters (bytes for binary bodies) |
| `${split(${header.tags},',')}` | `["a","b","c"]` | string to list |
| `${hash()}` | `a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e` | SHA-256 hex by default |
| `${hash('abc','SHA-1')}` | `a9993e364706816aba3e25717850c26c9cd0d89d` | |
| `${hash('abc','MD5')}` | `900150983cd24fb0d6963f7d28e17f72` | |
| `${base64Encode()}` | `SGVsbG8gV29ybGQ=` | |
| `${base64Decode('SGVsbG8=')}` | `Hello` | |
| `${isEmpty()}` | `false` | true for null, blank text, empty list or map |
| `${isEmpty('   ')}` | `true` | |
| `${isAlpha('abc')}` | `true` | |
| `${isNumeric(${header.amount})}` | `true` | digits only |
| `${isAlphaNumeric('a1')}` | `true` | |
| `${empty(string)}` | (empty) | an empty string, list (`list`) or map (`map`) |
| `${empty(list)}` | `[]` | |
| `${empty(map)}` | `{}` | |

## Collection functions

```json
{"body": [3, 1, 4, 1, 5]}
```

| expression | result | notes |
|---|---|---|
| `${body[1]}` | `1` | |
| `${size()}` | `5` | elements of a list or map (1 for a single value, 0 for null) |
| `${join(',')}` | `3,1,4,1,5` | |
| `${join(', ','id-')}` | `id-3, id-1, id-4, id-1, id-5` | separator and prefix |
| `${collate(2)}` | `[[3,1],[4,1],[5]]` | groups of n, handy with `split` |
| `${skip(3)}` | `[1,5]` | |
| `${sum()}` | `14` | |
| `${max()}` | `5` | |
| `${min()}` | `1` | |
| `${average()}` | `2.8` | |
| `${list('a','b','c')}` | `["a","b","c"]` | build a list |
| `${map('model','gpt-4o-mini','temperature',0)}` | `{"model":"gpt-4o-mini","temperature":"0"}` | build a map (values are text unless they are expressions) |
| `${bodyType}` | `java.util.ArrayList` | |

## Math functions

| expression | result |
|---|---|
| `${abs(-5)}` | `5` |
| `${floor(2.7)}` | `2` |
| `${ceil(2.1)}` | `3` |
| `${round(2.5)}` | `3` |
| `${sum(1,2,3)}` | `6` |
| `${sum(${header.n},${header.amount})}` | `255` |
| `${max(1,7,3)}` | `7` |
| `${min(4,2,9)}` | `2` |
| `${average(1,2,3,4)}` | `2.5` |
| `${increment(${header.n})}` | `6` |
| `${decrement(${header.n})}` | `4` |
| `${header.n}++` | `6` |
| `${header.n}--` | `4` |

`${header.n}++` and `--` return the changed number; to store it, use them in a `setHeader`
(see [the counter example](#increment-a-counter-header-and-read-the-route-id)).

## Conditionals: ternary, Elvis, iif, not

| expression | result | notes |
|---|---|---|
| `${header.amount > 100 ? 'big' : 'small'}` | `big` | ternary: spaces around `?` and `:` are required |
| `${header.missing ?: 'default'}` | `default` | Elvis: the right side when the left is null or empty |
| `${header.name ?: 'default'}` | `Ada` | |
| `${iif(${header.amount} > 100,'big','small')}` | `big` | function form of the ternary |
| `${iif(${header.priority} == 'low',${header.name},'n/a')}` | `n/a` | |
| `${not(${header.amount} > 100)}` | `false` | negate a predicate |

## JSON, XML and other languages inside Simple

`jsonpath(...)`, `jq(...)` and `xpath(...)` run those languages on the body, or on another value
given as the first argument.

| expression | result |
|---|---|
| `${jsonpath('$.order.items[*].sku')}` | `["A1","B2"]` |
| `${jsonpath('$.order.items[?(@.qty > 1)].sku')}` | `["A1"]` |
| `${jq('.order.items \| map(.qty) \| add')}` | `3` |
| `${jq('[.order.items[] \| .qty * .price] \| add')}` | `39` |
| `${jsonpath(${body.customer},'$.name')}` | `Ada` |

`${prettyBody}` and `${pretty(value)}` print JSON indented on several lines;
`${pretty(${body.customer})}` gives:

```json
{
  "name": "Ada",
  "email": null
}
```

```json
{"body": "<order id=\"7\"><item>pen</item><item>ink</item></order>"}
```

| expression | result |
|---|---|
| `${xpath('/order/@id')}` | `7` |
| `${xpath('count(/order/item)')}` | `2.0` |

## Exchange, context and environment functions

| expression | result | notes |
|---|---|---|
| `${properties:app.greeting}` | `Hi` | a property from application.properties or `--property`; fails if missing |
| `${properties:app.missing:fallback}` | `fallback` | with a default |
| `${properties-exist:app.greeting}` | `true` | |
| `${properties-exist:app.missing}` | `false` | |
| `${env.CAMELEER_DOCS_UNSET}` | (empty) | an environment variable (also `${env:NAME}`, `${sysenv.NAME}`) |
| `${null}` | (empty) | null |
| `${type:org.apache.camel.Exchange.FILE_NAME}` | `CamelFileName` | Exchange constants (also `Integer.MAX_VALUE`, `Boolean.TRUE`...) |
| `${exception}` | (empty) | the caught exception, null when there is none |

More functions of this group, whose values change per run:

| function | value |
|---|---|
| `${exchangeId}` | the exchange id |
| `${id}`, `${messageId}` | the message id |
| `${messageTimestamp}` | the message timestamp (ms) when the consumer set one |
| `${routeId}` | id of the current route (see [the counter example](#increment-a-counter-header-and-read-the-route-id)) |
| `${fromRouteId}` | id of the route the exchange was created in |
| `${exception.message}`, `${exception.class}`, `${exception.stacktrace}` | the caught exception (see [the error handler example](#use-the-exception-message-in-an-error-handler)); `${exception.kind}` is the Cameleer error kind |
| `${sys.os.name}`, `${sys.user.dir}`, `${sys.java.io.tmpdir}`... | system properties (Java names mapped to the OS) |
| `${messageHistory}`, `${messageHistory(false)}` | the route steps the message passed (with and without exchange details) |
| `${ref:name}` | a bean or value from the registry |
| `${bean:name.method}`, `${bean:name?method=m}`, `${bean:name::m}` | call a registered bean method (see [bean](https://pmsudhi.github.io/cameleer/docs/languages/bean.html)) |

## Dates

`${date:<command>:<pattern>}` formats a date with a Java `SimpleDateFormat` pattern (`yyyy`, `MM`,
`dd`, `HH`, `mm`, `ss`, `SSS`, `EEE`, `MMM`, `Z`, `'T'`...). Commands:

- `now`, `now-1h`, `now+2d` (offsets in `ms`, `s`, `m`, `h`, `d`)
- `millis` (the current time in ms, without a pattern)
- `header.<name>`, `exchangeProperty.<name>`, `variable.<name>`: a date, a timestamp in ms, or
  an ISO-8601 text in that header, property or variable, with optional offsets
- `exchangeCreated`, `file` (the `CamelFileLastModified` header)

`${date-with-timezone:<command>:<zone>:<pattern>}` formats in a time zone (`UTC`, `Europe/Paris`,
`GMT+02:00`...). Without it dates format in the process default zone (UTC unless `TZ` is set).

```json
{"headers": {"CamelFileName": "in/orders/2024-06.csv.gz", "CamelFileLastModified": 1718000000000, "due": "2024-06-10T06:13:20Z"}}
```

| expression | result |
|---|---|
| `${date:header.CamelFileLastModified:yyyy-MM-dd'T'HH:mm}` | `2024-06-10T06:13` |
| `${date:header.CamelFileLastModified+1d:yyyy-MM-dd}` | `2024-06-11` |
| `${date:header.CamelFileLastModified-90m:HH:mm}` | `04:43` |
| `${date:file:yyyy/MM}` | `2024/06` |
| `${date:header.due:dd MMM yyyy}` | `10 Jun 2024` |
| `${date-with-timezone:header.CamelFileLastModified:Asia/Kolkata:HH:mm}` | `11:43` |
| `${date-with-timezone:header.CamelFileLastModified:GMT+02:00:HH:mm}` | `08:13` |

The current time, checked by pattern:

| predicate | result |
|---|---|
| `${date:now:yyyy-MM-dd} regex '\d{4}-\d{2}-\d{2}'` | `true` |
| `${date:millis} > 1700000000000` | `true` |
| `${date:now-1h:HH} regex '\d{2}'` | `true` |

## Random values and ids

| predicate | result | notes |
|---|---|---|
| `${random(10)} range '0..9'` | `true` | 0 to max-1 |
| `${random(5,8)} range '5..7'` | `true` | min to max-1 |
| `${uuid} regex '[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}'` | `true` | random UUID v4 |
| `${uuid(short)} regex '[0-9a-f]{16}'` | `true` | 16 hex digits |
| `${uuid(classic)} startsWith 'ID-'` | `true` | Camel-style id |
| `${camelId} startsWith 'camel-'` | `true` | the context name (`camel-1`...), also `${camelContext.name}` |

## File language

`${file:...}` functions read the `CamelFile*` headers set by the [file](https://pmsudhi.github.io/cameleer/docs/components/file.html),
[ftp](https://pmsudhi.github.io/cameleer/docs/components/ftp.html) and similar consumers. They are used in `fileName`, `move`,
`preMove`, `doneFileName` and similar options, and anywhere in Simple.

| expression | result | meaning |
|---|---|---|
| `${file:name}` | `in/orders/2024-06.csv.gz` | file name relative to the endpoint directory |
| `${file:name.noext}` | `in/orders/2024-06` | without any extension |
| `${file:name.noext.single}` | `in/orders/2024-06.csv` | without the last extension |
| `${file:name.ext}` | `csv.gz` | all extensions (also `${file:ext}`) |
| `${file:name.ext.single}` | `gz` | the last extension |
| `${file:onlyname}` | `2024-06.csv.gz` | name without directories |
| `${file:onlyname.noext}` | `2024-06` | |
| `${file:onlyname.noext.single}` | `2024-06.csv` | |
| `${file:ext}` | `csv.gz` | |
| `${file:parent}` | `in/orders` | parent directory |
| `${file:path}` | `in/orders/2024-06.csv.gz` | the path (`CamelFilePath`) |
| `${file:absolute}` | `false` | whether the path is absolute |
| `${file:absolute.path}` | `in/orders/2024-06.csv.gz` | the absolute path (`CamelFileAbsolutePath` when set) |
| `${file:length}` | `0` | size in bytes (`CamelFileLength`, also `${file:size}`) |
| `${file:modified}` | `1718000000000` | last modified, ms |
| `${date:file:yyyyMMdd}` | `20240610` | last modified, formatted |

Typical uses:

- `move: "done/${date:now:yyyy/MM/dd}/${file:name}"`: archive by day.
- `fileName: "${file:onlyname.noext}.json"`: same name, new extension.
- `moveFailed: "error/${file:name}.${exchangeId}"`.

## Predicates and operators

A predicate is `left operator right`, combined with `&&` / `and` and `||` / `or` (`&&` binds
tighter). The left side is usually a `${...}` function; the right side a quoted literal, a number,
`null`, `true`/`false` or another function. When one side is a number (an unquoted literal
such as `100`, or a numeric header), a numeric text on the other side is compared as a number:
`${header.amount} > 100` is true for the text `250`. When both sides are text, they are compared
as text, and `range 'a..b'` bounds are always text: convert first with
`${headerAs(amount,Integer)}`. A predicate without an operator is true when the value is
`true` (or the text `true`) and false for null, `false` and empty values.

| predicate | result | operator |
|---|---|---|
| `${header.name} == 'Ada'` | `true` | equals |
| `${header.name} != 'Bob'` | `true` | not equals |
| `${header.name} =~ 'ADA'` | `true` | equals, ignoring case |
| `${header.name} !=~ 'ADA'` | `false` | not equals, ignoring case |
| `${header.amount} > 100` | `true` | numeric when both sides are numbers |
| `${header.amount} >= 250` | `true` | |
| `${header.n} < 10` | `true` | |
| `${header.n} <= 4` | `false` | |
| `${body} contains 'World'` | `true` | substring, list element or map key |
| `${body} !contains 'Moon'` | `true` | also `not contains` |
| `${body} ~~ 'world'` | `true` | contains, ignoring case |
| `${body} !~~ 'WORLD'` | `false` | |
| `${body} regex 'Hello \w+'` | `true` | the whole value must match |
| `${body} !regex '\d+'` | `true` | also `not regex` |
| `${header.priority} in 'high,urgent'` | `true` | comma-separated list |
| `${header.priority} !in 'low,normal'` | `true` | also `not in` |
| `${headerAs(amount,Integer)} range '100..500'` | `true` | inclusive range (convert text to a number first, see below) |
| `${headerAs(amount,Integer)} !range '1..99'` | `true` | also `not range` |
| `${header.amount} range '1..99'` | `true` | pitfall: the text `250` compared as text |
| `${header.n} is Integer` | `true` | type check: `String`, `Integer`, `Number`, `Boolean`, `List`, `Map`... |
| `${header.name} !is Integer` | `true` | also `not is` |
| `${body} startsWith 'Hello'` | `true` | also `starts with` |
| `${body} endsWith 'World'` | `true` | also `ends with` |
| `${body} !startsWith 'World'` | `true` | |
| `${header.missing} == null` | `true` | |
| `${header.name} == ${variable.user}` | `false` | function on both sides (case matters) |
| `${header.name} =~ ${variable.user}` | `true` | |
| `${header.name} == 'Ada' && ${header.n} > 3` | `true` | and |
| `${header.name} == 'Bob' \|\| ${header.n} > 3` | `true` | or |
| `${header.name} == 'Bob' or ${header.n} > 3 and ${header.priority} == 'high'` | `true` | `and` binds tighter |
| `${header.missing}` | `false` | null is false |
| `${isEmpty(${header.missing})}` | `true` | a boolean function |
| `${body.length()} > 5` | `true` | |

## Escaping and literal text

| expression | result | notes |
|---|---|---|
| `\${body}` | `${body}` | a literal `${` |
| `$${body}` | `${body}` | the same |
| `$simple{body}` | `Hello World` | alternative function syntax |
| `price: 10\}` | `price: 10}` | a literal `}` |

`\n`, `\t` and `\r` in a Simple text become a newline, tab and carriage return, so
`Line1\nLine2` gives two lines.

In route files, `{{name}}` is a property placeholder resolved when the route loads, before
Simple runs. Use `${properties:name}` to read a property at run time.

## Options

Simple has no language options. `resultType` given on a `simple:` expression in YAML converts
the result, as for any language.

## Rust DSL

```rust
b.from("direct:simple-rust")
    .set_header("greeting", simple("Hello ${body}"))
    .filter(simple("${header.greeting} contains 'World'"))
    .set_body(simple("${header.greeting.toUpperCase()}!"))
    .end();
```

## Differences from Apache Camel

- No Java objects: values are JSON-like (string, number, boolean, list, map, bytes), so OGNL
  calls are limited to the common `String`, `List` and `Map` methods listed above, and
  `${bodyType}` reports the Java type name that matches the value.
- `${body.a.b}` on a JSON text body navigates into the parsed JSON; Camel needs a converted body
  for that.
- `${sys.*}` maps the common Java system property names (`os.name`, `user.dir`, `user.home`,
  `java.io.tmpdir`, `line.separator`...) to the operating system.
- `${type:...}` knows the `org.apache.camel.Exchange` constants and a few `java.lang` ones only.
- `${exception.class}` is the Cameleer error kind (for example `NoTypeConversionAvailableException`),
  not a Java class name.
- `csimple` is the same interpreter, not compiled Java.

## Common questions

### How do I read a JSON field in Simple?

Unmarshal the body with the [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html) and use `${body.field.sub}`,
or call `${jsonpath('$.field.sub')}` directly on the JSON text. A JSON text body also works with
`${body.field}` for simple navigation.

### How do I give a default when a header is missing?

Use the Elvis operator: `${header.region ?: 'eu'}`. It also replaces an empty string.

### Why does my comparison of two numbers behave like text?

Both sides are text. `${header.amount} > 100` compares numbers (the literal `100` is a number),
but `${header.amount} > '99'` and `${header.amount} range '1..99'` compare text, so `250` sorts
before `99`. Write numbers unquoted, or convert the header with `${headerAs(amount,Integer)}`.
Apache Camel converts the range bounds to the type of the left side, so this differs.

### How do I get the current date in a file name?

`${date:now:yyyyMMdd}`, for example `fileName: "report-${date:now:yyyy-MM-dd}.csv"`. Add
`date-with-timezone:now:Europe/Paris:` to format in another zone.

### How do I write `${` literally, for example in a template sent to another system?

Write `\${` or `$${`. To avoid Simple completely, use the [constant](https://pmsudhi.github.io/cameleer/docs/languages/constant.html) language.

## Related

- [csimple](https://pmsudhi.github.io/cameleer/docs/languages/csimple.html), [constant](https://pmsudhi.github.io/cameleer/docs/languages/constant.html), [header](https://pmsudhi.github.io/cameleer/docs/languages/header.html),
  [exchangeProperty](https://pmsudhi.github.io/cameleer/docs/languages/exchangeProperty.html), [variable](https://pmsudhi.github.io/cameleer/docs/languages/variable.html)
- [JSONPath](https://pmsudhi.github.io/cameleer/docs/languages/jsonpath.html), [jq](https://pmsudhi.github.io/cameleer/docs/languages/jq.html), [XPath](https://pmsudhi.github.io/cameleer/docs/languages/xpath.html): structured data
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html)
- [File component](https://pmsudhi.github.io/cameleer/docs/components/file.html): where the file language is used most
- [Apache Camel Simple language](https://camel.apache.org/components/next/languages/simple-language.html)
- [Apache Camel File language](https://camel.apache.org/components/next/languages/file-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/spel.html

# SpEL language

> The `spel` language evaluates Spring Expression Language expressions and `#{...}` templates against the exchange.

**Name:** `spel` · **Crate:** `cameleer-script` · **Cargo feature:** [`script`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [SpEL](https://camel.apache.org/components/next/languages/spel-language.html)

## When to use it

- Port Spring-based Camel routes that use SpEL.
- Build a string with embedded expressions: `Hello #{request.body}`.

## Syntax

Cameleer interprets SpEL itself, without Spring or a JVM. Text with `#{...}` blocks is a
template; a lone `#{expr}` returns the typed value (a number stays a number); text without
`#{` is one plain expression. Supported: property and index navigation, method calls, `#root`,
`#this` and `#variables`, `@bean` references from the Camel registry, `T(Type)` static calls for
known JDK types, `new` for JDK collections, `?.`, `?:`, the ternary operator, list `{1, 2}` and
map `{k: v}` literals, selection `.?[]`, projection `.![]`, `matches`, `between`, `instanceof`
and word operators (`eq`, `div`, `mod`...). Arbitrary Java classes are not available.

The root object has `request`, `response`, `message`, `exchange`, `body`, `headers` and
`properties`.

## Examples

```yaml
- route:
    id: spel-demo
    from:
      uri: direct:spel
      steps:
        - setHeader:
            name: tier
            spel: "#{request.headers.amount > 100 ? 'gold' : 'standard'}"
        - setBody:
            spel: "Hello #{request.body}, you are #{request.headers.tier}"
```

```text
Ada
```

```text
Hello Ada, you are gold
```

```json
{"body": "hello", "headers": {"amount": 250, "name": "Ada"}}
```

| expression | result |
|---|---|
| `#{request.body.toUpperCase()}` | `HELLO` |
| `#{request.headers.amount > 100}` | `true` |
| `Hello #{request.headers.name}` | `Hello Ada` |
| `#{request.headers['name']}` | `Ada` |
| `#{headers.missing ?: 'none'}` | `none` |
| `#{exchange.in.body}` | `hello` |
| `#{{1, 2, 3, 4}.?[#this > 2]}` | `[3,4]` |

## Options

| option | default | description |
|---|---|---|
| `resultType` | (none) | Convert the result to this type. |

## Rust DSL

```rust
b.from("direct:spel-rust")
    .set_body(cameleer_script::spel("Hello #{request.body}"));
```

## Common questions

### Do I need `#{...}` around the expression?

No. Without `#{` the whole text is one expression. Use `#{...}` to mix literal text and
expressions.

### Can I call Spring beans?

`@name` resolves a bean from the Camel registry: plain values and bean methods bound with
`bind_bean_method`. There is no Spring application context.

## Related

- [OGNL](https://pmsudhi.github.io/cameleer/docs/languages/ognl.html), [MVEL](https://pmsudhi.github.io/cameleer/docs/languages/mvel.html).
- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html).
- [Apache Camel SpEL language](https://camel.apache.org/components/next/languages/spel-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/tokenize.html

# Tokenize language

> The `tokenize` language cuts text into a list of pieces (by a token, a regular expression, a start and end token, or an XML element name), mostly to drive the `split` EIP.

**Name:** `tokenize` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) · **Apache Camel:** [Tokenize](https://camel.apache.org/components/next/languages/tokenize-language.html)

## When to use it

- Process a file line by line: `split` with `tokenize: "\n"`.
- Send records in batches, for example 100 lines per request to an embedding API, with `group`.
- Skip a CSV header line with `skipFirst`.
- Cut repeated XML elements out of a large document (`xml: true`) without parsing it as a whole.

## Syntax

The expression text, if any, is the name of a header to tokenize; otherwise the body is used.
Everything else is set with options. In YAML, `tokenize: ","` is short for
`tokenize: {token: ","}`.

| mode | options | result for the input |
|---|---|---|
| token (default) | `token` (default `,`) | text split on the token; a trailing empty piece is dropped |
| regex | `token` + `regex: true` | text split on the regular expression |
| pair | `token` + `endToken` (+ `includeTokens`) | the text between each start and end token |
| xml | `token: <item>` + `xml: true` | each whole `<item>...</item>` element, nesting aware |

`group: N` joins every N pieces with `groupDelimiter` (default: the token in token mode,
nothing in pair and xml mode). `skipFirst: true` drops the first piece. `\n`, `\r` and `\t`
in `token`, `endToken` and `groupDelimiter` are unescaped. A body that is already a list is
passed through (only `skipFirst` applies).

## Examples

### Lines in groups, skipping a header

```yaml
- route:
    id: tokenize-lines
    from:
      uri: direct:tokenize-lines
      steps:
        - split:
            tokenize:
              token: "\\n"
              skipFirst: true
              group: 2
            aggregationStrategy: GroupedBodyAggregationStrategy
            steps:
              - setBody:
                  simple: "batch[${body.replace('\n', '|')}]"
```

```text
id,name
1,Ada
2,Grace
3,Linus
```

```text
["batch[1,Ada|2,Grace]","batch[3,Linus]"]
```

### Regular expression

```yaml
- route:
    id: tokenize-regex
    from:
      uri: direct:tokenize-regex
      steps:
        - setBody:
            tokenize:
              token: "\\s*[;,]\\s*"
              regex: true
```

```text
red ; green,blue  ,  black
```

```text
["red","green","blue","black"]
```

### Text between start and end tokens

Pull the code blocks out of a model's Markdown answer:

```yaml
- route:
    id: tokenize-pair
    from:
      uri: direct:tokenize-pair
      steps:
        - setBody:
            tokenize:
              token: "<sql>"
              endToken: "</sql>"
```

```text
First run <sql>SELECT 1</sql>, then <sql>SELECT 2</sql>.
```

```text
["SELECT 1","SELECT 2"]
```

### XML elements

```yaml
- route:
    id: tokenize-xml
    from:
      uri: direct:tokenize-xml
      steps:
        - split:
            tokenize:
              token: "<order>"
              xml: true
            aggregationStrategy: GroupedBodyAggregationStrategy
            steps:
              - setBody:
                  xpath:
                    expression: /order/@id
                    resultType: String
```

```xml
<orders><order id="1"><line/></order><order id="2"/><order id="3">x</order></orders>
```

```text
["1","2","3"]
```

### Tokenize a header

```yaml
- route:
    id: tokenize-header
    from:
      uri: direct:tokenize-header
      steps:
        - setBody:
            tokenize:
              expression: recipients
              token: ";"
```

```text
ignored
```

```text
["ada@example.com","grace@example.com"]
```

## Options

| option | default | description |
|---|---|---|
| `token` | `,` | The separator, regex, start token or element name. |
| `endToken` | (none) | End token: pair mode. |
| `includeTokens` | `false` | In pair mode, keep the start and end tokens in each piece. |
| `regex` | `false` | `token` is a regular expression. |
| `xml` | `false` | `token` is an element name (`<order>` or `order`); whole elements are returned. |
| `group` | `0` | Join every N pieces into one. |
| `groupDelimiter` | the token | Separator used when grouping. |
| `skipFirst` | `false` | Drop the first piece (a header line). |
| `headerName` / `source` | (none) | Tokenize this header instead of the body. |
| `inheritNamespaceTagName` | | Accepted and ignored. |

## Rust DSL

```rust
b.from("direct:tokenize-rust")
    .split(tokenize("\n"))
    .to("mock:tokenize-line")
    .end()
    .set_body(tokenize_pair("[", "]", false));
```

Also `tokenize_regex(regex)` and `tokenize_xml(tag)`; add `group`/`skipFirst` with
`LanguageOptions::with_option`.

## Common questions

### How do I split a file into lines?

`split: {tokenize: "\n"}`. Add `group: 100` to process 100 lines per exchange, and
`skipFirst: true` to skip a header line.

### How do I split a big XML file into records?

`tokenize: {token: "<record>", xml: true}` returns each `<record>` element as text, which you
can then query with [XPath](https://pmsudhi.github.io/cameleer/docs/languages/xpath.html).

### Does Cameleer stream the tokens?

No. The tokens of one body are computed as a list, so the whole body is held in memory. This
differs from Apache Camel, where tokenize can scan a stream lazily.

## Related

- [Split EIP](https://pmsudhi.github.io/cameleer/docs/guides/eips.html), [XPath language](https://pmsudhi.github.io/cameleer/docs/languages/xpath.html), [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html)
  (`${split(...)}`, `${collate(n)}`)
- [CSV data format](https://pmsudhi.github.io/cameleer/docs/dataformats/csv.html)
- [Apache Camel Tokenize language](https://camel.apache.org/components/next/languages/tokenize-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/variable.html

# Variable language

> The `variable` language returns the value of one exchange variable (set with `setVariable`), or null when it is not set.

**Name:** `variable` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) · **Apache Camel:** [Variable](https://camel.apache.org/components/next/languages/variable-language.html)

## When to use it

- Store intermediate results under a name (Camel 4 variables) without adding headers that
  would be sent to the next endpoint.
- Keep the pieces of a multi-step agent flow apart: the user question, the retrieved
  context, the model answer.

## Syntax

The expression text is the variable name. In [Simple](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) the same value is
`${variable.name}`, and `${variables}` returns all of them. Variables are stored per exchange.

## Examples

```yaml
- route:
    id: variable-demo
    from:
      uri: direct:variable
      steps:
        - setVariable:
            name: question
            simple: "${body}"
        - setVariable:
            name: context
            constant: "Orders ship within 2 days."
        - setBody:
            simple: "Context: ${variable.context}\nQuestion: ${variable.question}"
        - setHeader:
            name: asked
            variable: question
```

```text
When will my order ship?
```

```text
Context: Orders ship within 2 days.
Question: When will my order ship?
```

```json
{"body": "x", "variables": {"question": "When?", "score": 0.82}}
```

| expression | result |
|---|---|
| `question` | `When?` |
| `score` | `0.82` |
| `missing` | (empty) |

## Options

The variable language has no options. It reads exchange variables only: Apache Camel's
`global:` and `route:` prefixes are not interpreted by this language.

## Rust DSL

```rust
b.from("direct:variable-rust")
    .set_body(language("variable", "question"));
```

## Common questions

### How do I set a variable in YAML?

Use the `setVariable` step with `name` and an expression, for example
`setVariable: {name: question, simple: "${body}"}`.

### Are variables sent to endpoints?

No. Unlike headers, variables stay inside the exchange.

## Related

- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) (`${variable.name}`, `${variables}`)
- [Header language](https://pmsudhi.github.io/cameleer/docs/languages/header.html), [exchangeProperty language](https://pmsudhi.github.io/cameleer/docs/languages/exchangeProperty.html)
- [Apache Camel Variable language](https://camel.apache.org/components/next/languages/variable-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/xpath.html

# XPath language

> The `xpath` language selects values from an XML message with XPath 1.0 expressions such as `/order/@id` or `count(//item)`.

**Name:** `xpath` · **Crate:** `cameleer-xml` (a smaller subset in `cameleer-core`) · **Cargo feature:** [`xml`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) for XPath 1.0 in full, or [`xpath`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) for the core subset · **Apache Camel:** [XPath](https://camel.apache.org/components/next/languages/xpath-language.html)

## When to use it

- Read a field from an XML document: an id attribute, a customer name, a status.
- Route or filter XML messages (`/order/@status = 'new'`).
- Split an XML document into one message per element (`//item`).
- Pull values out of SOAP responses or legacy XML feeds before handing them to a JSON API or
  an AI agent tool.

## Syntax

With `cameleer_main::new_main()` (and in the container image) the `xpath` language is the full
XPath 1.0 engine of `cameleer-xml`. It replaces the subset in `cameleer-core`, which ignores
namespaces and is only used when `cameleer-xml` is not registered.

Supported: location paths with all XPath 1.0 axes, predicates, unions `|`, `and`/`or`,
comparisons, arithmetic (`+ - * div mod`), the XPath 1.0 function library (`count`, `sum`,
`concat`, `contains`, `starts-with`, `substring-before`, `translate`, `normalize-space`,
`string-length`, `number`, `round`, `name`, `local-name`, ...) plus `upper-case`,
`lower-case`, `ends-with` and `matches`.

Camel functions and variables:

| syntax | value |
|---|---|
| `$name` | header `name`, else exchange property, else variable |
| `in:body()`, `in:header('name')` | the body, a header |
| `function:properties('key')` | a property placeholder value |
| `function:simple('${...}')` | a [Simple](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) expression |
| `$env:NAME`, `$system:NAME` | an environment variable |
| `$exchangeProperty:NAME` | an exchange property |

**Namespaces.** Name tests match namespace URIs, so a prefixed document needs a `namespace`
binding (`p=uri`) or `local-name()` tests.

**Result.** Without `resultType`, a node-set with one node becomes a string (elements are
serialized as XML, attributes and text as their value), a larger node-set becomes an array,
and numbers, strings and booleans keep their type (XPath numbers are doubles, so `count(...)`
is `2.0`). Use `resultType: String` for the trimmed string value.

### Syntax reference, tested

```json
{"body": "<order id=\"42\" status=\"new\"><customer>Ada</customer><item sku=\"A1\" qty=\"2\" price=\"9.50\"/><item sku=\"B2\" qty=\"1\" price=\"20\"/></order>",
 "headers": {"region": "eu"}}
```

| expression | result |
|---|---|
| `/order/@id` | `42` |
| `/order/customer/text()` | `Ada` |
| `/order/customer` | `<customer>Ada</customer>` |
| `//item/@sku` | `["A1","B2"]` |
| `//item[1]` | `<item sku="A1" qty="2" price="9.50"/>` |
| `//item[last()]/@sku` | `B2` |
| `//item[@price > 10]/@sku` | `B2` |
| `//item/following-sibling::item/@sku` | `B2` |
| `count(//item)` | `2.0` |
| `sum(//item/@qty)` | `3.0` |
| `//item[@sku='A1']/@qty * //item[@sku='A1']/@price` | `19.0` |
| `concat(/order/customer, '-', /order/@id)` | `Ada-42` |
| `translate(/order/customer, 'a', 'A')` | `AdA` |
| `upper-case(/order/customer)` | `ADA` |
| `name(/*)` | `order` |
| `$region` | `eu` |
| `in:header('region')` | `eu` |
| `function:simple('${header.region}')` | `eu` |

| expression | result |
|---|---|
| `/order/@status = 'new'` | `true` |
| `count(//item) > 2` | `false` |
| `//item[@sku='B2']` | `true` |
| `//refund` | `false` |

## Examples

### Route XML orders by status

```yaml
- route:
    id: xpath-route
    from:
      uri: direct:xpath-route
      steps:
        - setHeader:
            name: orderId
            xpath:
              expression: /order/@id
              resultType: String
        - choice:
            when:
              - xpath: "/order/@status = 'new'"
                steps:
                  - setBody:
                      simple: "new order ${header.orderId}"
            otherwise:
              steps:
                - setBody:
                    simple: "ignored order ${header.orderId}"
```

```xml
<order id="42" status="new"><customer>Ada</customer></order>
```

```text
new order 42
```

```xml
<order id="43" status="shipped"><customer>Bob</customer></order>
```

```text
ignored order 43
```

### Namespaces

```yaml
- route:
    id: xpath-ns
    from:
      uri: direct:xpath-ns
      steps:
        - setBody:
            xpath:
              expression: /o:order/o:total
              namespace: o=urn:example:orders
              resultType: Double
```

```xml
<order xmlns="urn:example:orders"><total>12.5</total></order>
```

```text
12.5
```

### Split an XML document into items

```yaml
- route:
    id: xpath-split
    from:
      uri: direct:xpath-split
      steps:
        - split:
            xpath: //item
            aggregationStrategy: GroupedBodyAggregationStrategy
            steps:
              - setBody:
                  xpath:
                    expression: /item/@sku
                    resultType: String
```

```xml
<order><item sku="A1"/><item sku="B2"/><item sku="C3"/></order>
```

```text
["A1","B2","C3"]
```

## Options

| option | default | description |
|---|---|---|
| `resultType` | (none) | `String` (trimmed string value), `NodeList`/`nodeset` (array), `Node` (first node), `Number`/`Double`, `Integer`/`Long`, `Boolean`. Java class names and `XPathConstants` names are accepted. |
| `namespace` / `namespaces` | (none) | Prefix bindings: `p=uri,q=uri2` (also `;` or newline separated), a JSON object, or a list of `{key, value}`. Options named `namespace.<prefix>` also bind a prefix. |
| `headerName` | (none) | Evaluate this header instead of the body. |
| `propertyName`, `variableName` | (none) | Evaluate this exchange property or variable. |
| `source` | (none) | `header:x`, `exchangeProperty:x`, `variable:x` or `body`. |
| `trim` | `true` | Trim the `String` result. |
| `saxon` | `false` | `true` fails: there is no Saxon or XPath 2.0 engine. |
| `threadSafety`, `preCompile`, `logNamespaces`, `documentType`, `factoryRef`, `objectModel` | | Accepted for compatibility, no effect. |

## Rust DSL

```rust
b.from("direct:xpath-rust")
    .filter(xpath("/order/@status = 'new'"))
    .set_body(xpath_as("/order/@id", "String"));
```

With namespaces, use `cameleer_xml::language::xpath_ns("/c:order/@id", &[("c", "urn:orders")])`.

## Common questions

### Why does my XPath return nothing for a document with a default namespace?

Name tests match the namespace URI. Bind a prefix (`namespace: o=urn:...`) and use it in the
expression, or match with `*[local-name()='order']`.

### Why is `count(//item)` `2.0` and not `2`?

XPath numbers are doubles. Use `resultType: Integer` to get `2`.

### Does Cameleer support XPath 2.0 or 3.1?

No. The `xpath` language is XPath 1.0 with a few 2.0 string functions (`upper-case`,
`lower-case`, `ends-with`, `matches`). For FLWOR and sequences use the
[XQuery language](https://pmsudhi.github.io/cameleer/docs/languages/xquery.html).

## Related

- [XQuery language](https://pmsudhi.github.io/cameleer/docs/languages/xquery.html), [xslt component](https://pmsudhi.github.io/cameleer/docs/components/xslt.html),
  [xj component](https://pmsudhi.github.io/cameleer/docs/components/xj.html), [validator component](https://pmsudhi.github.io/cameleer/docs/components/validator.html)
- [tokenize language](https://pmsudhi.github.io/cameleer/docs/languages/tokenize.html) (`xml: true` streams large XML files element by element)
- [JacksonXML data format](https://pmsudhi.github.io/cameleer/docs/dataformats/jacksonxml.html)
- [Apache Camel XPath language](https://camel.apache.org/components/next/languages/xpath-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/languages/xquery.html

# XQuery language

> The `xquery` language evaluates an XQuery expression (FLWOR, constructors, XPath) against an XML message and returns the result.

**Name:** `xquery` · **Crate:** `cameleer-xml` · **Cargo feature:** [`xml`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) · **Apache Camel:** [XQuery](https://camel.apache.org/components/next/languages/xquery-language.html)

## When to use it

- Compute a value from XML that XPath 1.0 cannot express easily: `for ... order by ... return`,
  `string-join`, sums over computed values.
- Build a small XML fragment from an incoming document in a single expression.
- Filter or route XML messages with an XQuery predicate.

For a query kept in a file and run as a step, use the [xquery component](https://pmsudhi.github.io/cameleer/docs/components/xquery.html).

## Syntax

Cameleer has its own XQuery processor (Apache Camel uses Saxon). The body, or the input named
by `headerName`/`source`, is parsed as the context document.

External variables are bound like camel-saxon does:

| declaration | value |
|---|---|
| `declare variable $in.body external;` | the body |
| `declare variable $in.headers.NAME external;` | header `NAME` |
| `declare variable $NAME external;` | exchange property `NAME`, else header, else variable |

A declared atomic type casts the value (`as xs:integer`); a node type (`as element()`) parses
it as XML.

**Result.** By default (`resultType` `DOM`) the result is serialized as XML text, with atomic
values separated by spaces. Predicates use the effective boolean value.

### Syntax reference, tested

```json
{"body": "<order id=\"42\"><customer>Ada</customer><item sku=\"A1\" qty=\"2\" price=\"9.50\"/><item sku=\"B2\" qty=\"1\" price=\"20\"/></order>",
 "headers": {"region": "eu"}}
```

| expression | result |
|---|---|
| `/order/customer/text()` | `Ada` |
| `for $i in //item return string($i/@sku)` | `A1 B2` |
| `string-join(//item/@sku, ',')` | `A1,B2` |
| `sum(for $i in //item return $i/@qty * $i/@price)` | `39` |
| `<skus>{for $i in //item order by $i/@sku descending return <sku>{string($i/@sku)}</sku>}</skus>` | `<skus><sku>B2</sku><sku>A1</sku></skus>` |
| `declare variable $in.headers.region external; concat(/order/customer, '@', $in.headers.region)` | `Ada@eu` |

| expression | result |
|---|---|
| `count(//item) > 1` | `true` |
| `some $i in //item satisfies $i/@price > 100` | `false` |

## Examples

### Build a summary with FLWOR

```yaml
- route:
    id: xquery-summary
    from:
      uri: direct:xquery-summary
      steps:
        - setBody:
            xquery:
              expression: >-
                declare variable $in.headers.currency external;
                <summary customer="{/order/customer}" currency="{$in.headers.currency}">{
                  for $i in //item
                  let $line := $i/@qty * $i/@price
                  order by $line descending
                  return <line sku="{$i/@sku}">{$line}</line>
                }</summary>
```

```xml
<order><customer>Ada</customer><item sku="A1" qty="2" price="9.50"/><item sku="B2" qty="3" price="20"/></order>
```

```xml
<summary customer="Ada" currency="EUR"><line sku="B2">60</line><line sku="A1">19</line></summary>
```

### Filter with an XQuery predicate

```yaml
- route:
    id: xquery-filter
    from:
      uri: direct:xquery-filter
      steps:
        - setHeader:
            name: big
            constant: "no"
        - filter:
            xquery: "sum(//item/@qty) >= 10"
            steps:
              - setHeader:
                  name: big
                  constant: "yes"
        - setBody:
            xquery:
              expression: "sum(//item/@qty)"
              resultType: Integer
        - setBody:
            simple: "qty=${body} big=${header.big}"
```

```xml
<order><item qty="4"/><item qty="7"/></order>
```

```text
qty=11 big=yes
```

## Options

| option | default | description |
|---|---|---|
| `resultType` | `DOM` | `DOM` (XML text), `String` (string values concatenated), `List`/`NodeList` (array), `Node`/`Element` (first item), `Bytes`, `Integer`/`Long`, `Double`, `Boolean`. Java class names are accepted. |
| `namespace` / `namespaces` | (none) | Prefix bindings, same syntax as the [xpath language](https://pmsudhi.github.io/cameleer/docs/languages/xpath.html). |
| `stripsAllWhiteSpace` | `true` | Drop whitespace-only text nodes of the input, as Saxon does for Camel. |
| `headerName` | (none) | Evaluate this header instead of the body. |
| `source` | (none) | `header:x`, `property:x`, `variable:x` or `body`. |

## Rust DSL

```rust
b.from("direct:xquery-rust")
    .set_body(cameleer_xml::xquery_component::xquery_expr("string-join(//item/@sku, ',')"));
```

## Common questions

### How do I pass a header into an XQuery?

Declare it: `declare variable $in.headers.currency external;` and use `$in.headers.currency`.

### What is the difference between the xquery language and the xquery component?

The language evaluates an inline expression wherever an expression fits (`setBody`,
`filter`, `split`...). The component runs a query file as a producer step:
`to: xquery:file:summary.xq`.

### Which XQuery version is supported?

The commonly used XQuery 1.0 features (FLWOR, constructors, quantified expressions,
external variables) with XPath 2.0 functions; there is no Saxon, schema awareness or XQuery
Update.

## Related

- [xquery component](https://pmsudhi.github.io/cameleer/docs/components/xquery.html), [XPath language](https://pmsudhi.github.io/cameleer/docs/languages/xpath.html),
  [xslt component](https://pmsudhi.github.io/cameleer/docs/components/xslt.html)
- [Apache Camel XQuery language](https://camel.apache.org/components/next/languages/xquery-language.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/asn1.html

# ASN.1 data format

> The `asn1` data format encodes values as ASN.1 BER/DER and decodes BER/DER back into values, either as a generic tree or typed by an ASN.1 module compiled at runtime; it can also split a stream of BER records.

**Name:** `asn1` · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [ASN.1 File](https://camel.apache.org/components/next/dataformats/asn1-dataformat.html)

## When to use it

- Read telecom files: call detail records (CDRs), 3GPP charging data and SS7/MAP traces are
  streams of BER records.
- Look inside X.509 certificates, PKCS structures, SNMP or LDAP messages without a dedicated
  parser.
- Exchange typed records with systems that publish an ASN.1 module, without generating code
  with jASN1 or ASN1bean.

## Marshal and unmarshal

Three modes, chosen by the options:

| mode | marshal | unmarshal |
|---|---|---|
| `usingIterator=true` (no schema) | an array of records (bytes or values) → the records concatenated | a stream of BER records → an array with the bytes of each top-level element (for `split`) |
| generic (no schema) | a value tree → DER bytes | BER/DER bytes → a value tree |
| typed (`schema` or `moduleFile` plus `clazzName`) | an object (or JSON text) of the named type → DER bytes | BER/DER bytes → an object of the named type; with `usingIterator=true` an array of them |

A body that is already bytes is passed through unchanged by marshal.

**Generic tree.** `SEQUENCE` and `SET` become arrays, `INTEGER`/`ENUMERATED` integers,
`BOOLEAN`, `NULL`, `OCTET STRING` bytes, character strings strings, `OBJECT IDENTIFIER` a
dotted string, times strings. Other tags become `{"tag": "[0]", "value": ...}` (constructed)
or `{"tag": "[APPLICATION 1]", "bytes": ...}` (primitive). On marshal, strings are written as
`UTF8String`, and `{"oid": "1.2.3"}`, `{"set": [...]}`, `{"printable": ".."}`, `{"ia5": ".."}`,
`{"utcTime": ".."}` and `{"generalizedTime": ".."}` select other universal types.

**Typed mode.** The module compiler supports `DEFINITIONS [EXPLICIT|IMPLICIT|AUTOMATIC TAGS]`,
type and value assignments, `BOOLEAN`, `INTEGER`, `ENUMERATED`, `REAL`, `NULL`,
`OCTET STRING`, `BIT STRING`, `OBJECT IDENTIFIER`, `RELATIVE-OID`, character strings, times,
`SEQUENCE`/`SET` (with `OPTIONAL`, `DEFAULT`, `COMPONENTS OF`, extension markers),
`SEQUENCE OF`/`SET OF`, `CHOICE`, `ANY` and tagged types. Constraints are parsed and ignored.
`SEQUENCE` values are objects keyed by component name, `CHOICE` is `{"alternative": value}`,
`ENUMERATED` is the item name.

## Example

A typed record: a module inline in the route, JSON in, DER out (shown as hex), and back.

```yaml
- route:
    id: asn1-typed
    from:
      uri: direct:asn1-typed
      steps:
        - marshal:
            asn1:
              clazzName: Reading
              schema: |
                Telemetry DEFINITIONS AUTOMATIC TAGS ::= BEGIN
                  Reading ::= SEQUENCE {
                    sensor  UTF8String,
                    celsius INTEGER,
                    status  ENUMERATED { ok(0), warn(1), fail(2) } DEFAULT ok
                  }
                END
        - marshal:
            hex: {}
        - setHeader:
            name: der
            simple: "${body}"
        - unmarshal:
            hex: {}
        - unmarshal:
            asn1:
              clazzName: Reading
              schema: |
                Telemetry DEFINITIONS AUTOMATIC TAGS ::= BEGIN
                  Reading ::= SEQUENCE {
                    sensor  UTF8String,
                    celsius INTEGER,
                    status  ENUMERATED { ok(0), warn(1), fail(2) } DEFAULT ok
                  }
                END
        - setBody:
            simple: "${header.der}\n${body}"
```

```json
{"sensor": "t1", "celsius": -5, "status": "warn"}
```

```text
300a800274318101fb820101
{"sensor":"t1","celsius":-5,"status":"warn"}
```

With automatic tagging each component gets a context tag: `80 02 7431` is `[0]` `t1`,
`81 01 fb` is `[1]` -5 and `82 01 01` is `[2]` `warn` (1), all inside a `SEQUENCE` (`30 0a`).

The generic tree needs no module. Here a JSON array becomes a DER `SEQUENCE` with an
`INTEGER`, an `OBJECT IDENTIFIER` and a context-tagged string:

```yaml
- route:
    id: asn1-generic
    from:
      uri: direct:asn1-generic
      steps:
        - unmarshal:
            json: {}
        - marshal:
            asn1: {}
        - marshal:
            hex: {}
```

```json
[5, {"oid": "1.2.840.113549.1.1.11"}, {"tag": "[0]", "value": "x"}]
```

```text
301302010506092a864886f70d01010ba0030c0178
```

Split a file of concatenated BER records (for example a CDR file) into one exchange per
record:

```yaml
- route:
    id: asn1-split
    from:
      uri: direct:asn1-split
      steps:
        - unmarshal:
            hex: {}
        - unmarshal:
            asn1:
              usingIterator: true
        - split:
            simple: "${body}"
            aggregationStrategy: GroupedBodyAggregationStrategy
            steps:
              - marshal:
                  hex: {}
        - setBody:
            simple: "${body}"
```

```text
3003020101300302010230030201033003020104
```

```text
["3003020101","3003020102","3003020103","3003020104"]
```

## Rust DSL

```rust
b.from("direct:asn1-rust")
    .unmarshal(DataFormatDefinition::new("asn1").option("usingIterator", "true"))
    .split(simple("${body}"))
    .to("mock:asn1-record")
    .end();
```

## Options

| option | default | description |
|---|---|---|
| `usingIterator` | `false` | Unmarshal a stream of records into an array (bytes per record, or typed values with a schema); marshal concatenates an array. |
| `schema` | (none) | ASN.1 module text inline. Aliases `module`, `asn1Module`. |
| `moduleFile` | (none) | Path of an ASN.1 module file. Aliases `schemaFile`, `asn1File`. |
| `clazzName` | (none) | The ASN.1 type to encode/decode (optionally `Module.Type`); required with a schema. Aliases `className`, `typeName`. |

## Differences from Apache Camel

Camel's `asn1` data format splits record streams and otherwise needs classes generated by
jASN1/ASN1bean (`clazzName` is a Java class). Here `clazzName` names a type in a module that
is compiled when the route starts, and without a module you get a generic value tree.

## Common questions

### How do I decode a BER file without the ASN.1 module?

Use `unmarshal: asn1: {}`. You get the generic tree: arrays for sequences and tag objects for
context-specific fields. It is enough to inspect a file or pick a few known positions.

### How do I process a CDR file record by record?

`unmarshal: asn1: {usingIterator: true}` and then `split: simple: "${body}"`; decode each
record with a typed `asn1` step inside the split if you have the module.

### Are definite and indefinite lengths supported?

Both are read. Marshal always writes DER (definite lengths, sorted `SET OF` per the
canonical rules for the generic tree).

## Related

- [Hex data format](https://pmsudhi.github.io/cameleer/docs/dataformats/hex.html), [Split EIP](https://pmsudhi.github.io/cameleer/docs/guides/eips.html)
- [Protobuf data format](https://pmsudhi.github.io/cameleer/docs/dataformats/protobuf.html), [Thrift data format](https://pmsudhi.github.io/cameleer/docs/dataformats/thrift.html)
- [Apache Camel ASN.1 data format](https://camel.apache.org/components/next/dataformats/asn1-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/avro.html

# Avro data format

> The `avro` data format encodes the message body as Apache Avro (binary, JSON or Object Container File) using an Avro schema, and decodes Avro data back into a structured body.

**Name:** `avro` · **Also:** `avroJackson` (`avro-jackson`, `avrojackson`, `jacksonAvro`) ·
**Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [Avro](https://camel.apache.org/components/next/dataformats/avro-dataformat.html),
[Avro Jackson](https://camel.apache.org/components/next/dataformats/avroJackson-dataformat.html)

## When to use it

- Produce and consume Avro records on Kafka topics shared with Java, Python or Spark services.
- Read and write Avro container files (`.avro`) in data lakes.
- Keep sensor or event payloads small and schema-checked on edge links.

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `marshal` | a structured value matching the schema (`avroJackson` also accepts JSON text) | `encoding: binary` (default): a bare Avro datum, like Camel. `json`: Avro JSON encoding text. `container`: an Object Container File with the schema in its header (a list body writes one record per item). |
| `unmarshal` | Avro data | a structured value: records and maps become objects, enums strings, `bytes`/`fixed` bytes, unions the selected branch. Container files are detected and need no schema; they give a list of records. |

With `logicalTypeConversions` (default on), `date`, `time-*` and `timestamp-*` values decode to
ISO-8601 strings, `decimal` to decimal strings and `duration` to `{months, days, millis}`; marshal
accepts these forms as well as the raw numbers.

**Difference from Apache Camel:** no generated classes. The schema comes from `schema`,
`schemaFile` or a registry bean named by `instanceClassName`, and values are generic.

## Example

The schema used by the examples:

```json
{"type":"record","name":"Reading","namespace":"edge","fields":[
  {"name":"id","type":"string"},
  {"name":"temp","type":"double"},
  {"name":"ok","type":"boolean"}]}
```

Encode a JSON reading as binary Avro and show the bytes. The 13 bytes are the string length and
text, the 8-byte double and the boolean; field names are not sent:

```yaml
- route:
    id: avro-encode
    from:
      uri: direct:avro-encode
      steps:
        - unmarshal:
            json: {}
        - marshal:
            avro:
              schemaFile: sensor.avsc
        - marshal:
            hex: {}
```

```json
{"id":"s-1","temp":21.5,"ok":true}
```

```text
06732d31000000000080354001
```

Decode binary Avro (for example a Kafka record value) to JSON:

```yaml
- route:
    id: avro-decode
    from:
      uri: direct:avro-decode
      steps:
        - unmarshal:
            hex: {}
        - unmarshal:
            avro:
              schemaFile: sensor.avsc
        - marshal:
            json: {}
```

```text
06732d31000000000080354001
```

```json
{"id":"s-1","temp":21.5,"ok":true}
```

`avroJackson` works on JSON text directly. Here it writes a container file and reads it back
without any schema option, since the file carries its schema:

```yaml
- route:
    id: avro-container
    from:
      uri: direct:avro-container
      steps:
        - marshal:
            avroJackson:
              schemaFile: sensor.avsc
              encoding: container
        - unmarshal:
            avroJackson:
              jsonView: true
```

```json
[{"id":"s-1","temp":21.5,"ok":true},{"id":"s-2","temp":19.0,"ok":false}]
```

```json
[{"id":"s-1","temp":21.5,"ok":true},{"id":"s-2","temp":19.0,"ok":false}]
```

## Rust DSL

```rust
b.from("direct:avro-rust")
    .unmarshal(DataFormatDefinition::json())
    .marshal(DataFormatDefinition::new("avro").option("schemaFile", "sensor.avsc"))
    .unmarshal(DataFormatDefinition::new("avro").option("schemaFile", "sensor.avsc"));
```

## Options

| option | default | description |
|---|---|---|
| `schema` | (none) | The schema as inline JSON. |
| `schemaFile` (`schemaLocation`) | (none) | Path of an `.avsc` file (`file:` and `classpath:` prefixes accepted). |
| `instanceClassName` | (none) | Full name of the type to use from the schema, or the name of a registry bean holding the schema. |
| `encoding` | `binary` | `binary`, `json` or `container` (Object Container File). |
| `codec` | `null` | Container compression: `null` or `deflate`. |
| `syncInterval` | `64000` | Container block size in bytes. |
| `contentTypeHeader` | `true` | Set `Content-Type` (`avro/binary` or `application/json`). |
| `logicalTypeConversions` | `true` | Convert logical types to and from readable strings. |
| `jsonView` | `false` | Unmarshal to JSON text instead of a structured value. |
| `library` | (none) | `Jackson` gives the `avroJackson` behaviour (marshal accepts JSON text). |

## Common questions

### How do I decode Avro messages from Kafka?

Consume with the [kafka](https://pmsudhi.github.io/cameleer/docs/components/kafka.html) component and `unmarshal: {avro: {schemaFile: x.avsc}}`.
The value must be a bare datum; Confluent's 5-byte schema-registry prefix is not stripped.

### Do I need the schema to read an .avro file?

No. Container files embed their schema; `unmarshal` reads it from the header.

### Why does marshal fail with my JSON text body?

The plain `avro` format expects a structured value: add `unmarshal: {json: {}}` first, or use
`avroJackson`, which parses JSON text itself.

## Related

- [Protobuf data format](https://pmsudhi.github.io/cameleer/docs/dataformats/protobuf.html), [Thrift data format](https://pmsudhi.github.io/cameleer/docs/dataformats/thrift.html), [CBOR data format](https://pmsudhi.github.io/cameleer/docs/dataformats/cbor.html)
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html), [Hex data format](https://pmsudhi.github.io/cameleer/docs/dataformats/hex.html)
- [Apache Camel Avro data format](https://camel.apache.org/components/next/dataformats/avro-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/barcode.html

# Barcode data format

> The `barcode` data format turns text into a barcode image (QR Code, Data Matrix, PDF417, Aztec, Code 128, EAN and more) on marshal, and reads the text back from a barcode image on unmarshal.

**Name:** `barcode` · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [Barcode](https://camel.apache.org/components/next/dataformats/barcode-dataformat.html)

## When to use it

- Print QR codes or Data Matrix codes on shipping labels, tickets or asset tags straight
  from a route (for example with a link to the order).
- Read barcodes from scanned documents or camera images on an edge device (a warehouse
  gateway, a kiosk) without a cloud vision service.
- Let an AI agent attach a scannable code to what it produces, such as a QR code with a
  tracking URL in a generated email.

## Marshal and unmarshal

| direction | input body | output body |
|---|---|---|
| marshal | text | image bytes (PNG by default, also GIF or JPG) |
| unmarshal | a PNG, GIF or baseline JPEG image | the decoded text; headers `BarcodeFormat` and, for QR codes, `ERROR_CORRECTION_LEVEL` |
| unmarshal with `multiple=true` | an image with several symbols | an array of `{text, BarcodeFormat, ...}` objects; headers `BarcodeFormat` (array) and `BarcodeCount` |

Symbologies (`barcodeFormat`):

| format | marshal (encode) | unmarshal (decode) |
|---|---|---|
| `QR_CODE` (default) | yes, versions 1-40, error correction L/M/Q/H | yes |
| `DATA_MATRIX` | yes, square and rectangular | yes |
| `PDF_417` | yes, error correction 0-8 | yes |
| `AZTEC` | yes | yes |
| `CODE_128`, `CODE_39`, `CODE_93`, `CODABAR`, `ITF` | yes | yes |
| `EAN_13`, `EAN_8`, `UPC_A`, `UPC_E` | yes (check digit computed or verified) | yes |
| `MAXICODE`, `UPC_EAN_EXTENSION`, `RSS_14`, `RSS_EXPANDED` | no (ZXing has no writer either) | yes |

With the default `barcodeFormat` (QR_CODE), unmarshal tries every format. Setting another
format restricts decoding to it. The codecs are written from scratch (no ZXing) but follow
ZXing's rendering and option names, and decode photographs (rotation, perspective, noise) as
well as clean generated images.

## Example

Make a QR code for a tracking link, then read it back. A real route would write the PNG to a
file or attach it to an email instead of decoding it.

```yaml
- route:
    id: barcode-qr
    from:
      uri: direct:barcode-qr
      steps:
        - marshal:
            barcode:
              barcodeFormat: QR_CODE
              errorCorrectionLevel: M
              width: 200
              height: 200
        - setHeader:
            name: pngSignature
            simple: "${body.substring(1, 4)}"
        - unmarshal:
            barcode: {}
        - setBody:
            simple: "${header.pngSignature} ${header.BarcodeFormat} ${header.ERROR_CORRECTION_LEVEL}: ${body}"
```

```text
https://example.com/track/ORD-1042
```

```text
PNG QR_CODE M: https://example.com/track/ORD-1042
```

A linear barcode for a product label:

```yaml
- route:
    id: barcode-ean
    from:
      uri: direct:barcode-ean
      steps:
        - marshal:
            barcode:
              barcodeFormat: EAN_13
              width: 300
              height: 100
        - unmarshal:
            barcode:
              barcodeFormat: EAN_13
        - setBody:
            simple: "${header.BarcodeFormat} ${body}"
```

```text
590123412345
```

```text
EAN_13 5901234123457
```

The 12 digits get their check digit (7) computed on marshal.

## Rust DSL

```rust
b.from("direct:barcode-rust")
    .marshal(DataFormatDefinition::new("barcode").option("barcodeFormat", "DATA_MATRIX").option("imageType", "PNG"))
    .unmarshal(DataFormatDefinition::new("barcode").option("barcodeFormat", "DATA_MATRIX"));
```

## Options

| option | default | description |
|---|---|---|
| `barcodeFormat` | `QR_CODE` | The symbology (see the table above). |
| `width` | `100` | Image width in pixels. The symbol is scaled by the largest whole factor that fits, with a quiet zone. |
| `height` | `100` | Image height in pixels. |
| `imageType` | `PNG` | `PNG`, `GIF` or `JPG`. |
| `errorCorrectionLevel` | `L` (QR), `2` (PDF417) | QR: `L`, `M`, `Q`, `H`. PDF417: `0` to `8`. |
| `dataMatrixShape` | `NONE` | Data Matrix shape: `NONE`, `SQUARE` or `RECTANGLE`. Alias `shape`. |
| `pdf417Compaction` | `AUTO` | PDF417 compaction: `AUTO`, `TEXT`, `BYTE`, `NUMERIC`. Alias `compaction`. |
| `multiple` | `false` | Unmarshal every symbol in the image into a list. |

## Message headers

| header | direction | description |
|---|---|---|
| `BarcodeFormat` | out (unmarshal) | The format found, for example `QR_CODE`; an array with `multiple=true`. |
| `ERROR_CORRECTION_LEVEL` | out (unmarshal) | QR error correction level of the symbol read. |
| `BarcodeCount` | out (unmarshal) | Number of symbols with `multiple=true`. |

## Common questions

### How do I generate a QR code PNG in a route?

`marshal: barcode: {width: 300, height: 300}` on a text body, then `to: file:labels` with a
`CamelFileName` ending in `.png`.

### How do I read a barcode from an uploaded image?

`unmarshal: barcode: {}` on the image bytes. Every format is tried when `barcodeFormat` is
not set; the format found is in the `BarcodeFormat` header.

### Which error correction level should I use for QR codes?

`L` (the default) gives the smallest code. Use `M` or `Q` for printed labels that may get
scratched, `H` when a logo covers part of the code.

## Related

- [Base64 data format](https://pmsudhi.github.io/cameleer/docs/dataformats/base64.html): embed the image in JSON or HTML
- [File component](https://pmsudhi.github.io/cameleer/docs/components/file.html), [Mail (SMTP) component](https://pmsudhi.github.io/cameleer/docs/components/smtp.html)
- [Apache Camel Barcode data format](https://camel.apache.org/components/next/dataformats/barcode-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/base64.html

# Base64 data format

> The `base64` data format encodes the message body as Base64 text (marshal) and decodes Base64 text back to bytes (unmarshal).

**Name:** `base64` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Apache Camel:** [Base64](https://camel.apache.org/components/next/dataformats/base64-dataformat.html)

## When to use it

- Put binary data (an image, a PDF, a compressed payload) into a JSON field, an email body or an
  HTTP header that only carries text.
- Send an image to a multimodal model API that expects Base64 content.
- Decode Base64 attachments or tokens received from another system.

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `marshal` | any body (text is taken as UTF-8 bytes) | Base64 text, wrapped every `lineLength` characters |
| `unmarshal` | Base64 text (standard or URL-safe alphabet; line breaks ignored) | bytes |

## Example

Encode a body, then decode it again:

```yaml
- route:
    id: base64-encode
    from:
      uri: direct:base64-encode
      steps:
        - marshal:
            base64: {}
```

```text
Hello, Cameleer!
```

```text
SGVsbG8sIENhbWVsZWVyIQ==
```

```yaml
- route:
    id: base64-decode
    from:
      uri: direct:base64-decode
      steps:
        - unmarshal:
            base64: {}
        - convertBodyTo:
            type: String
```

```text
SGVsbG8sIENhbWVsZWVyIQ==
```

```text
Hello, Cameleer!
```

URL-safe output (no `+`, `/` or padding), handy for tokens in URLs:

```yaml
- route:
    id: base64-url-safe
    from:
      uri: direct:base64-url-safe
      steps:
        - marshal:
            base64:
              urlSafe: true
```

```text
??>>
```

```text
Pz8-Pg
```

## Rust DSL

```rust
b.from("direct:base64-rust")
    .marshal(DataFormatDefinition::base64().line_length(0));
```

## Options

| option | default | description |
|---|---|---|
| `lineLength` | `76` | Wrap the output after this many characters; `0` disables wrapping. |
| `lineSeparator` | CRLF | Separator inserted when wrapping (`\n`, `\r\n`). |
| `urlSafe` | `false` | Use the URL-safe alphabet (`-` and `_`) without padding. |

## Common questions

### How do I Base64-encode a file for an API request?

Read the file, `marshal: {base64: {lineLength: 0}}`, then put `${body}` into the JSON request. Use
`lineLength: 0` so the text has no line breaks.

### How do I encode a single header instead of the body?

Use the Simple functions `${base64Encode(${header.x})}` and `${base64Decode(...)}`; see the
[Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html).

### Why does the decoded body look like bytes?

`unmarshal` returns bytes. Add `convertBodyTo: {type: String}` when the content is text.

## Related

- [Hex data format](https://pmsudhi.github.io/cameleer/docs/dataformats/hex.html), [String data format](https://pmsudhi.github.io/cameleer/docs/dataformats/string.html), [GZip data format](https://pmsudhi.github.io/cameleer/docs/dataformats/gzip.html)
- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html) `base64Encode` / `base64Decode` functions
- [Apache Camel Base64 data format](https://camel.apache.org/components/next/dataformats/base64-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/bindy.html

# Bindy data formats

> The Bindy data formats (`bindyCsv`, `bindyFixed`, `bindyKvp`) map delimited, fixed-length and key-value records to typed fields described by a record descriptor, in both directions.

**Name:** `bindyCsv` · **Also:** `bindy` (with `type: Csv`, `Fixed` or `KeyValue`), `bindyFixed`,
`bindyKvp` (and the `bindy-csv`, `bindycsv`... spellings) · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [Bindy](https://camel.apache.org/components/next/dataformats/bindyCsv-dataformat.html)

## When to use it

- Read and write fixed-width mainframe and banking files, where every field has a position and a
  width.
- Parse CSV with typed columns (integers, decimals, dates in a given pattern) instead of strings.
- Read FIX-style key-value messages (`8=FIX.4.1<SOH>35=0...`).

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `unmarshal` | record text | a list of objects (field name -> typed value; dates as ISO-8601 strings). A single record gives one object unless `unwrapSingleInstance: false`. |
| `marshal` | a list of objects or one object | record text (padded, aligned and formatted per the descriptor) |

**Difference from Apache Camel:** Rust has no annotations. The `@CsvRecord`, `@FixedLengthRecord`,
`@Message`, `@DataField` and `@KeyValuePairField` settings are written in a YAML or JSON
*descriptor* instead (`descriptor`, `descriptorFile`, or a registry entry named by `classType`).

## Descriptor

```text
className: com.acme.Order   # informational
separator: ","              # CSV: field separator (default ",")
skipFirstLine: true         # CSV: skip a header line
generateHeaderColumns: true # CSV: write a header line on marshal
crlf: UNIX                  # WINDOWS (default), UNIX, MAC or a literal
length: 30                  # fixed: record length check (0 = none)
paddingChar: " "            # fixed: record padding
keyValuePairSeparator: "="  # kvp
pairSeparator: "\u0001"     # kvp
fields:
  - name: orderNr
    pos: 1                  # CSV column or fixed start position (1 based)
    type: int               # string, int, long, double, float, decimal, boolean, char, date
    pattern: dd-MM-yyyy     # date or decimal pattern
    precision: 2            # decimals written for double/decimal
    length: 10              # fixed: width
    align: R                # fixed: R (default) or L
    trim: true
    defaultValue: "0"
    required: true
    columnName: Order Nr    # header text (default: name)
    tag: 8                  # kvp: the key
```

Other field and record settings: `paddingChar` per field, `delimiter` and `clip` (fixed),
`quote`, `quoting`, `removeQuotes`, `endWithLineBreak` (CSV), `ignoreTrailingChars`,
`ignoreMissingChars`, `skipHeader`, `skipFooter` (fixed).

## Example

A CSV order file with typed columns:

```text
className: com.acme.Order
separator: ","
skipFirstLine: true
fields:
  - name: orderNr
    pos: 1
    type: int
  - name: customer
    pos: 2
  - name: amount
    pos: 3
    type: decimal
    precision: 2
  - name: orderDate
    pos: 4
    type: date
    pattern: dd-MM-yyyy
```

```yaml
- route:
    id: bindy-csv
    from:
      uri: direct:bindy-csv
      steps:
        - unmarshal:
            bindyCsv:
              descriptorFile: order-csv.yaml
        - marshal:
            json: {}
```

```text
nr,customer,amount,date
1,Ada,49.5,02-01-2024
2,Grace,120,15-03-2024
```

```json
[{"orderNr":1,"customer":"Ada","amount":49.5,"orderDate":"2024-01-02"},{"orderNr":2,"customer":"Grace","amount":120.0,"orderDate":"2024-03-15"}]
```

Write fixed-length records, the classic mainframe layout:

```text
className: com.acme.FixedOrder
crlf: UNIX
fields:
  - name: orderNr
    pos: 1
    length: 5
    type: int
    paddingChar: "0"
  - name: customer
    pos: 6
    length: 10
    align: L
  - name: amount
    pos: 16
    length: 8
    type: decimal
    precision: 2
```

```yaml
- route:
    id: bindy-fixed
    from:
      uri: direct:bindy-fixed
      steps:
        - unmarshal:
            json: {}
        - marshal:
            bindyFixed:
              descriptorFile: order-fixed.yaml
```

```json
[{"orderNr":1,"customer":"Ada","amount":49.5},{"orderNr":42,"customer":"Grace","amount":120}]
```

```text
00001Ada          49.50
00042Grace       120.00
```

## Rust DSL

```rust
b.from("direct:bindy-rust")
    .unmarshal(DataFormatDefinition::new("bindyCsv").option("descriptorFile", "order-csv.yaml"))
    .marshal(DataFormatDefinition::json());
```

Descriptors can also be built in Rust with `cameleer_dataformats::bindy::BindyDescriptor` and
bound in the registry, then referenced with `classType`.

## Options

| option | default | description |
|---|---|---|
| `descriptor` | (none) | Inline descriptor text (YAML or JSON). |
| `descriptorFile` | (none) | Path of a descriptor file. |
| `classType` (`className`) | (none) | A descriptor bound in the registry, a registry string holding descriptor text, or a `.yaml`/`.yml`/`.json` path. |
| `type` | `Csv` | For the generic `bindy` name: `Csv`, `Fixed` or `KeyValue`. |
| `unwrapSingleInstance` | `true` | A single record unmarshals to an object instead of a one-element list. |
| `allowEmptyStream` | `false` | An empty body unmarshals to an empty list instead of failing. |

`locale` is accepted and ignored.

## Common questions

### How do I parse a fixed-width file?

Write a descriptor with `pos` and `length` for each field and `unmarshal: {bindyFixed: {descriptorFile: layout.yaml}}`.

### How do I convert dates while parsing CSV?

Give the field `type: date` and a `pattern` such as `dd-MM-yyyy`. The value becomes an ISO-8601
date string, and `marshal` writes it back in the pattern.

### Should I use bindyCsv or csv?

Use [csv](https://pmsudhi.github.io/cameleer/docs/dataformats/csv.html) when strings are enough. Use Bindy for typed fields, fixed widths or key-value
records.

## Related

- [CSV data format](https://pmsudhi.github.io/cameleer/docs/dataformats/csv.html), [uniVocity data formats](https://pmsudhi.github.io/cameleer/docs/dataformats/univocity.html)
- [Apache Camel Bindy](https://camel.apache.org/components/next/dataformats/bindyCsv-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/cbor.html

# CBOR data format

> The `cbor` data format encodes the message body as CBOR, a compact binary form of JSON (RFC 8949), and decodes CBOR back into a structured body.

**Name:** `cbor` · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [CBOR](https://camel.apache.org/components/next/dataformats/cbor-dataformat.html)

## When to use it

- Send sensor readings from constrained devices: CBOR is smaller than JSON and is the payload
  format of CoAP, LwM2M and many IoT stacks.
- Read CBOR from WebAuthn/COSE messages or devices, and turn it into JSON for the cloud side.
- Shrink JSON-like payloads on edge links without a schema.

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `marshal` | any value (objects, lists, strings, numbers, booleans, null, bytes) | CBOR bytes, preferred serialization (shortest integers; floats as half, single or double precision, whichever is exact) |
| `unmarshal` | CBOR bytes (empty gives null) | a structured value. Indefinite lengths are supported; bignums become integers when they fit, else decimal strings; other tags are dropped. |

`marshal` encodes the body as it is: a JSON text body becomes a CBOR text string, so unmarshal the
JSON first.

## Example

Encode a reading and show the CBOR bytes (13 bytes, against 23 for the JSON text):

```yaml
- route:
    id: cbor-encode
    from:
      uri: direct:cbor-encode
      steps:
        - unmarshal:
            json: {}
        - marshal:
            cbor: {}
        - marshal:
            hex: {}
```

```json
{"temp":21.5,"ok":true}
```

```text
a26474656d70f94d60626f6bf5
```

Decode CBOR from a device back to JSON:

```yaml
- route:
    id: cbor-decode
    from:
      uri: direct:cbor-decode
      steps:
        - unmarshal:
            hex: {}
        - unmarshal:
            cbor: {}
        - marshal:
            json: {}
```

```text
a26474656d70f94d60626f6bf5
```

```json
{"temp":21.5,"ok":true}
```

## Rust DSL

```rust
b.from("direct:cbor-rust")
    .marshal(DataFormatDefinition::new("cbor"))
    .unmarshal(DataFormatDefinition::new("cbor"));
```

## Options

None. Camel's options (`unmarshalType`, `useList`, `allowJmsType`...) are accepted and ignored:
CBOR always maps to a generic value.

## Common questions

### How much smaller is CBOR than JSON?

Usually 20-50% for small messages: keys and numbers are stored in binary, without quotes or
separators. Compress it as well for large payloads.

### How do I convert CBOR to JSON?

`unmarshal: {cbor: {}}` then `marshal: {json: {}}`.

## Related

- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html), [Avro data format](https://pmsudhi.github.io/cameleer/docs/dataformats/avro.html), [Protobuf data format](https://pmsudhi.github.io/cameleer/docs/dataformats/protobuf.html)
- [Hex data format](https://pmsudhi.github.io/cameleer/docs/dataformats/hex.html)
- [Apache Camel CBOR data format](https://camel.apache.org/components/next/dataformats/cbor-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/crypto.html

# Crypto data format

> The `crypto` data format encrypts a message body with a symmetric key (AES, DES or Triple DES) on marshal and decrypts it on unmarshal, with an optional HMAC to detect tampering.

**Name:** `crypto` · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [Crypto (Java Cryptographic Extension)](https://camel.apache.org/components/next/dataformats/crypto-dataformat.html)

## When to use it

- Encrypt payloads on an edge device before they leave it (to a broker, a bucket or a
  gateway you do not fully trust), and decrypt them in the back end with the same key.
- Store sensitive message bodies (prompts, transcripts, personal data) encrypted at rest.
- Exchange data with a Java Camel application that uses `CryptoDataFormat`: the wire format
  (inline IV and appended HMAC) is the same.

For public-key encryption and signatures use the [PGP data format](https://pmsudhi.github.io/cameleer/docs/dataformats/pgp.html) instead.

## Marshal and unmarshal

| direction | input body | output body |
|---|---|---|
| marshal | text or bytes | ciphertext bytes: `[4-byte IV length + IV]` when `inline=true`, then the ciphertext, then the HMAC when `shouldAppendHMAC=true` |
| unmarshal | ciphertext bytes in the same layout | plaintext bytes |

Without an IV (`initVector`, `initVectorRef` or the `CamelCryptoInitVector` header) a random
IV is generated for each message; decrypting it then needs `inline=true` so the IV travels
with the data. `AES/GCM/NoPadding` uses a 12-byte IV and appends a 16-byte tag.

## Example

AES-256-GCM with a random IV carried inline. The ciphertext is base64-encoded so it can be
printed or put into JSON; the second half of the route reverses everything.

```yaml
- route:
    id: crypto-gcm
    from:
      uri: direct:crypto-gcm
      steps:
        - marshal:
            crypto:
              algorithm: AES/GCM/NoPadding
              key: "{{env:PAYLOAD_KEY:hex:000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f}}"
              inline: true
        - marshal:
            base64:
              lineLength: 0
        - setHeader:
            name: encrypted
            simple: "${body}"
        - unmarshal:
            base64: {}
        - unmarshal:
            crypto:
              algorithm: AES/GCM/NoPadding
              key: "{{env:PAYLOAD_KEY:hex:000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f}}"
              inline: true
        - convertBodyTo: String
```

```text
patient 4711: blood pressure 120/80
```

```text
patient 4711: blood pressure 120/80
```

With a fixed IV and no HMAC the output is deterministic, which makes it easy to check against
another implementation (here AES-128-CBC with PKCS#5 padding, the same as
`openssl enc -aes-128-cbc -K 2b7e151628aed2a6abf7158809cf4f3c -iv 000102030405060708090a0b0c0d0e0f`).
Use a random IV in production.

```yaml
- route:
    id: crypto-cbc
    from:
      uri: direct:crypto-cbc
      steps:
        - marshal:
            crypto:
              algorithm: AES/CBC/PKCS5Padding
              key: hex:2b7e151628aed2a6abf7158809cf4f3c
              initVector: hex:000102030405060708090a0b0c0d0e0f
              shouldAppendHMAC: false
        - marshal:
            base64:
              lineLength: 0
```

```text
hello edge
```

```text
nplqU6Egyd3gr5/mxqpKZg==
```

## Rust DSL

```rust
let aes = DataFormatDefinition::new("crypto")
    .option("algorithm", "AES/GCM/NoPadding")
    .option("key", "hex:000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f")
    .option("inline", "true");
b.from("direct:crypto-rust")
    .marshal(aes.clone())
    .unmarshal(aes)
    .convert_body_to("String");
```

## Options

| option | default | description |
|---|---|---|
| `algorithm` | `DES/CBC/PKCS5Padding` | `AES`, `DES` or `DESede` (`TripleDES`), with mode `ECB`, `CBC`, `CTR`, `CFB`, `OFB` or `GCM` (AES only) and padding `PKCS5Padding`, `PKCS7Padding` or `NoPadding`. A bare `AES` means `AES/ECB/PKCS5Padding`, as in the JCE. |
| `key` | (none) | The key inline: `hex:...`, `base64:...` or raw text. AES keys are 16, 24 or 32 bytes. |
| `keyRef` | (none) | Registry bean holding the key (bytes, or a string in the `key` syntax). |
| `initVector` | (none) | The IV inline, same syntax as `key`. Alias `initializationVector`. |
| `initVectorRef` | (none) | Registry bean holding the IV. |
| `inline` | `false` | Write the IV in front of the ciphertext (4-byte big-endian length, then the IV) and read it from there on unmarshal. |
| `shouldAppendHMAC` | `true` | Append `HMAC(key, ciphertext)` on marshal and verify it on unmarshal. |
| `macAlgorithm` | `HmacSHA1` | `HmacSHA1`, `HmacSHA256`, `HmacSHA384` or `HmacSHA512`. |

`buffersize`, `cryptoProvider` and `algorithmParameterRef` are accepted for compatibility and
ignored.

## Message headers

| header | direction | description |
|---|---|---|
| `CamelCryptoKey` | in | Key for this message (overrides `key` / `keyRef`). |
| `CamelCryptoInitVector` | in | IV for this message (overrides `initVector` / `initVectorRef`). |

## Common questions

### How do I encrypt a message with AES in a Camel route?

`marshal: crypto: {algorithm: AES/GCM/NoPadding, key: "hex:...", inline: true}`. Decrypt
with the same options under `unmarshal`. Keep the key in an environment variable through a
`{{env:NAME}}` placeholder rather than in the route file.

### Why does decryption fail with "An initialization vector is required"?

The message was encrypted with a random IV that was not stored. Use `inline: true` on both
sides, or give the same `initVector` to both.

### What does "Input stream was tampered with" mean?

The appended HMAC does not match: the data was changed, the key differs, or one side has
`shouldAppendHMAC: false`. Both sides must use the same HMAC settings.

### Is it compatible with Apache Camel's CryptoDataFormat?

Yes for the supported algorithms: the inline IV layout and the appended HMAC follow Camel.
Algorithms outside AES, DES and Triple DES (for example Blowfish) are not implemented.

## Related

- [PGP data format](https://pmsudhi.github.io/cameleer/docs/dataformats/pgp.html): public-key encryption and signing
- [Base64 data format](https://pmsudhi.github.io/cameleer/docs/dataformats/base64.html): to carry ciphertext in text formats
- [Apache Camel Crypto data format](https://camel.apache.org/components/next/dataformats/crypto-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/csv.html

# CSV data format

> The `csv` data format parses CSV text into rows (lists or maps) and writes rows back as CSV, following RFC 4180.

**Name:** `csv` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Apache Camel:** [CSV](https://camel.apache.org/components/next/dataformats/csv-dataformat.html)

## When to use it

- Read CSV exports (orders, sensor logs, CRM dumps) and process each row: split it, filter it,
  insert it into a database or send it to a model as a prompt.
- Turn JSON or a list of maps into a CSV report or a spreadsheet upload.
- Change the delimiter or quoting of a file (semicolon-separated European exports, TSV).

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `unmarshal` | CSV text (string or bytes; a UTF-8 BOM is skipped) | a list of rows. Each row is a list of strings, or a map keyed by the header with `useMaps: true`. |
| `marshal` | a list of rows (lists or maps), one map, one list of values, or JSON text holding those | CSV text. Lines end with CRLF by default. |

Quoted fields may contain the delimiter, quotes (`""`) and line breaks. With maps, the columns
are the `header` option or the keys of the maps in order of first appearance; the header line is
written when `header` is set or `useMaps: true`.

## Example

Turn a CSV export into JSON records. With `useMaps`, the first line names the fields.

```yaml
- route:
    id: csv-to-json
    from:
      uri: direct:csv-to-json
      steps:
        - unmarshal:
            csv:
              useMaps: true
        - marshal:
            json: {}
```

```text
sku,qty,note
A1,2,"red, large"
B2,1,
```

```json
[{"sku":"A1","qty":"2","note":"red, large"},{"sku":"B2","qty":"1","note":""}]
```

Write JSON records as a semicolon-separated file with a header line:

```yaml
- route:
    id: json-to-csv
    from:
      uri: direct:json-to-csv
      steps:
        - marshal:
            csv:
              delimiter: ";"
              header: sku,qty
              recordSeparator: "\\n"
```

```json
[{"sku":"A1","qty":2,"price":9.5},{"sku":"B2","qty":1,"price":20}]
```

```text
sku;qty
A1;2
B2;1
```

Columns not listed in `header` (here `price`) are left out.

## Rust DSL

```rust
b.from("direct:csv-rust")
    .unmarshal(DataFormatDefinition::csv().use_maps(true))
    .marshal(DataFormatDefinition::json());
```

## Options

| option | default | description |
|---|---|---|
| `delimiter` | `,` | Field separator. `\t`, `TAB` and `SPACE` are accepted. |
| `quote` | `"` | Quote character. |
| `quoteDisabled` | `false` | No quoting at all. |
| `escape` | (none) | Escape character inside fields. |
| `recordSeparator` | CRLF | Line ending written by `marshal` (`\n`, `\r\n`). |
| `header` | (none) | Comma separated column names: the map keys on unmarshal (the first line is then data unless `skipHeaderRecord`), the columns and header line on marshal. |
| `skipHeaderRecord` | `false` | Unmarshal: drop the first line. Marshal: do not write the header line. |
| `useMaps` | `false` | Unmarshal each row to a map keyed by the header. |
| `useOrderedMaps` | `false` | Same as `useMaps` (maps keep the column order). |
| `ignoreEmptyLines` | `true` | Skip blank lines. |
| `ignoreSurroundingSpaces` (`trim`) | `false` | Trim spaces around fields. |
| `quoteMode` | `MINIMAL` | When to quote on marshal: `MINIMAL`, `ALL`, `NON_NUMERIC`, `NONE`. |
| `nullString` | (none) | Text written for null and read back as null. |
| `commentMarker` | (none) | Lines starting with this character are skipped. |

## Common questions

### How do I read a CSV file with a header row into maps?

Use `unmarshal: {csv: {useMaps: true}}`. Each row becomes a map such as
`{"sku":"A1","qty":"2"}`. Values are strings; convert them where you need numbers.

### How do I process a CSV file row by row?

Unmarshal it, then `split: {simple: "${body}"}` over the list. Each split exchange carries one row,
which you can turn into an LLM prompt with a [template](https://pmsudhi.github.io/cameleer/docs/components/freemarker.html) or insert
into a table.

### How do I write a semicolon-separated file?

Set `delimiter: ";"` on `marshal`. Add `header: a,b,c` to choose and order the columns.

### What is the difference between csv, univocityCsv and bindyCsv?

They read the same text. [univocityCsv](https://pmsudhi.github.io/cameleer/docs/dataformats/univocity.html) is `csv` with uniVocity option names, and
[bindyCsv](https://pmsudhi.github.io/cameleer/docs/dataformats/bindy.html) maps columns to typed fields from a record descriptor.

## Related

- [uniVocity data formats](https://pmsudhi.github.io/cameleer/docs/dataformats/univocity.html), [Bindy data formats](https://pmsudhi.github.io/cameleer/docs/dataformats/bindy.html),
  [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html)
- [Split EIP](https://pmsudhi.github.io/cameleer/docs/guides/eips.html) to process rows one at a time
- [Apache Camel CSV data format](https://camel.apache.org/components/next/dataformats/csv-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/fhir.html

# FHIR data formats

> The `fhirJson` and `fhirXml` data formats parse HL7 FHIR resources from JSON or XML into a value and serialize resources back, which also converts between the two FHIR encodings.

**Name:** `fhirJson`, `fhirXml` · **Crate:** `cameleer-soap` · **Cargo feature:** [`soap`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [FHIR JSon](https://camel.apache.org/components/next/dataformats/fhirJson-dataformat.html),
[FHIR XML](https://camel.apache.org/components/next/dataformats/fhirXml-dataformat.html)

## When to use it

- Accept FHIR resources (Patient, Observation, Bundle...) from apps and EHRs and route on
  their content.
- Convert FHIR XML from older systems to FHIR JSON for modern APIs, or the other way round.
- Strip narratives or selected elements before passing a resource to an analytics job or an
  LLM, so it only sees the fields it needs.

## Marshal and unmarshal

| direction | input body | output body |
|---|---|---|
| unmarshal (`fhirJson` / `fhirXml`) | FHIR JSON / FHIR XML text | a resource value in the FHIR JSON model: `resourceType`, arrays for repeating elements, `_name` for primitive extensions, typed numbers and booleans |
| marshal (`fhirJson` / `fhirXml`) | a resource value, or FHIR JSON / XML text | FHIR JSON / XML text; sets `Content-Type` to `application/fhir+json` / `application/fhir+xml` |

Because marshal also accepts FHIR text in either encoding, `marshal: fhirXml` directly on a
JSON body converts it to XML (and `marshal: fhirJson` on XML converts to JSON). XML output
follows the specification's element order. Decimals keep their lexical form (`1.50` stays
`1.50`).

## Example

Convert a FHIR JSON Patient to FHIR XML.

```yaml
- route:
    id: fhir-json-to-xml
    from:
      uri: direct:fhir-xml
      steps:
        - marshal:
            fhirXml:
              prettyPrint: false
```

```json
{"resourceType": "Patient", "id": "p1", "active": true,
 "name": [{"family": "Doe", "given": ["Jane"]}], "birthDate": "1980-01-01"}
```

```xml
<Patient xmlns="http://hl7.org/fhir"><id value="p1"/><active value="true"/><name><family value="Doe"/><given value="Jane"/></name><birthDate value="1980-01-01"/></Patient>
```

Unmarshal an Observation, route on its value, and drop the narrative before forwarding:

```yaml
- route:
    id: fhir-observation
    from:
      uri: direct:fhir-observation
      steps:
        - unmarshal:
            fhirJson: {}
        - setHeader:
            name: glucose
            simple: "${body.valueQuantity.value}"
        - marshal:
            fhirJson:
              suppressNarratives: true
        - setBody:
            simple: "${header.glucose} -> ${body}"
```

```json
{"resourceType": "Observation", "status": "final",
 "text": {"status": "generated", "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Glucose 5.4</div>"},
 "code": {"coding": [{"system": "http://loinc.org", "code": "15074-8"}]},
 "valueQuantity": {"value": 5.4, "unit": "mmol/L"}}
```

```text
5.4 -> {"resourceType":"Observation","status":"final","code":{"coding":[{"system":"http://loinc.org","code":"15074-8"}]},"valueQuantity":{"value":5.4,"unit":"mmol/L"}}
```

## Rust DSL

```rust
b.from("direct:fhir-rust")
    .unmarshal(DataFormatDefinition::new("fhirXml"))
    .marshal(DataFormatDefinition::new("fhirJson"));
```

## Options

| option | default | description |
|---|---|---|
| `fhirVersion` | `R4` | `R4`, `R4B`, `R5` or `DSTU3`: selects the type registry (element order, types). |
| `prettyPrint` | `false` | Indent the output. |
| `suppressNarratives` | `false` | Drop the `text` narrative. |
| `omitResourceId` | `false` | Leave out the resource `id`. |
| `encodeElements` | (none) | Only encode these elements, comma separated (`Patient.name` or `name`). |
| `dontEncodeElements` | (none) | Leave out these elements. |
| `stripVersionsFromReferences` | `false` | Remove `/_history/n` from references. |
| `contentTypeHeader` | `true` | Set `Content-Type` on marshal. |

`summaryMode`, `serverBaseUrl`, `parserOptions`, `preferTypes`, `forceResourceId`,
`overrideResourceIdWithBundleEntryFullUrl`, `encodeElementsAppliesToChildResourcesOnly` and
`dontStripVersionsFromReferencesAtPaths` are accepted for compatibility.

**Known limitation:** `suppressNarratives` currently removes every element named `text` at
any depth, not only the resource narrative. That also drops `CodeableConcept.text`,
`Annotation.text` and similar fields, so do not enable it when you need those (HAPI only
removes the `Narrative`).

## Differences from Apache Camel

Camel uses HAPI FHIR and produces HAPI model classes. Here resources are plain values in the
FHIR JSON shape, so Simple paths like `${body.name[0].family}` read them, and there is no
HAPI validation (the [FHIR component](https://pmsudhi.github.io/cameleer/docs/components/fhir.html) offers validation against the
base profiles).

## Common questions

### How do I convert FHIR XML to JSON?

`marshal: fhirJson: {}` on the XML text (or `unmarshal: fhirXml` then `marshal: fhirJson`).

### How do I read a field of a FHIR resource in a route?

Unmarshal with `fhirJson` (or `fhirXml`) and use Simple: `${body.name[0].given[0]}`,
`${body.valueQuantity.value}`.

### Which FHIR versions are supported?

DSTU3, R4 (default), R4B and R5 serialization rules, chosen with `fhirVersion`.

## Related

- [HL7 data format](https://pmsudhi.github.io/cameleer/docs/dataformats/hl7.html): HL7 v2 messages
- [FHIR component](https://pmsudhi.github.io/cameleer/docs/components/fhir.html)
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html), [Jackson XML data format](https://pmsudhi.github.io/cameleer/docs/dataformats/jacksonxml.html)
- [Apache Camel FHIR JSON](https://camel.apache.org/components/next/dataformats/fhirJson-dataformat.html)
  and [FHIR XML](https://camel.apache.org/components/next/dataformats/fhirXml-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/fory.html

# Fory data format

> The `fory` data format serializes values to and from the Apache Fory (formerly Fury) cross-language binary format, so Rust, Java, Python, Go and JavaScript services can share compact payloads.

**Name:** `fory` · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [Fory](https://camel.apache.org/components/next/dataformats/fory-dataformat.html)

## When to use it

- Exchange compact binary payloads with services that already use Apache Fory's xlang mode.
- Replace JSON on a hot path (queues, caches) with a faster, smaller binary encoding while
  keeping dynamic, schema-less values.
- Read Fory records produced by a Java Camel route that uses `fory` with xlang enabled.

## Marshal and unmarshal

| direction | input body | output body |
|---|---|---|
| marshal | any value: null, boolean, integer, float, string, bytes, array, object | Fory xlang bytes |
| unmarshal | Fory xlang bytes | the value |

Mapping: integers are written as `VAR_INT64` and every integer type reads back as an integer;
floats as `FLOAT64`; strings as `STRING` (Latin-1 when every character fits, UTF-8
otherwise); bytes as `BINARY`; arrays as `LIST`; objects as `MAP`. An object with an `@type`
key (`"namespace.TypeName"`) is written as a named struct; reading such a struct needs its
field list (`structTypes`) unless it was written in compatible mode, which carries the field
names.

Marshal a string body as-is and you get a Fory `STRING`; to send a JSON document as a map,
`unmarshal: json` first, as in the example.

## Example

JSON to Fory and back. The `byteCount` header shows the binary size: 49 bytes for a
58-byte JSON document.

```yaml
- route:
    id: fory-round-trip
    from:
      uri: direct:fory
      steps:
        - unmarshal:
            json: {}
        - marshal:
            fory: {}
        - setHeader:
            name: byteCount
            simple: "${body.length()}"
        - unmarshal:
            fory: {}
        - marshal:
            json: {}
        - setBody:
            simple: "${header.byteCount} bytes: ${body}"
```

```json
{"device": "edge-7", "readings": [21, 22, 23], "ok": true}
```

```text
49 bytes: {"device":"edge-7","readings":[21,22,23],"ok":true}
```

Named structs in compatible mode: the type definition with field names travels with the
data, so the reader needs no `structTypes`.

```yaml
- route:
    id: fory-struct
    from:
      uri: direct:fory-struct
      steps:
        - unmarshal:
            json: {}
        - marshal:
            fory:
              compatible: true
        - unmarshal:
            fory:
              compatible: true
        - marshal:
            json: {}
```

```json
{"@type": "example.Person", "name": "Ada", "age": 36}
```

```text
{"@type":"example.Person","age":36,"name":"Ada"}
```

Struct fields are written in snake_case-sorted order, so they come back sorted.

## Rust DSL

```rust
b.from("direct:fory-rust")
    .unmarshal_json()
    .marshal(DataFormatDefinition::new("fory"))
    .unmarshal(DataFormatDefinition::new("fory"))
    .marshal_json();
```

## Options

| option | default | description |
|---|---|---|
| `refTracking` | `false` | Write reference flags so repeated strings and containers become back references. Alias `trackingRef`. |
| `compatible` | `false` | Write `@type` objects as compatible structs with a shared type definition (field names included). `compatibleMode: COMPATIBLE` does the same. |
| `structTypes` | (none) | Field lists of named structs for reading non-compatible structs: `example.Person=name,age;example.Address=city`. |
| `requireClassRegistration` | `false` | With `true`, marshalling an `@type` not listed in `structTypes` fails. |
| `xlangSpec` | `CURRENT` | Protocol edition: `CURRENT` (current xlang specification) or `LEGACY` (Fory 0.10/0.11 layout). Readers detect the edition from the header. |
| `threadSafe`, `allowAutoWiredFory`, `unmarshalType` | | Accepted for Camel compatibility; no effect. |

## Differences from Apache Camel

Camel's `fory` format serializes Java objects (Java native mode by default, classes
registered with Fory). This implementation speaks only the cross-language (xlang) protocol and
works with dynamic values; Java native payloads are rejected on unmarshal. Configure the Java
side with xlang enabled to interoperate.

## Common questions

### Is Fory smaller than JSON?

Usually: numbers are varints, there are no quotes or field names for lists, and strings are
length-prefixed. Measure with your own payloads; small maps with long keys gain less.

### Why does reading a struct fail with an unknown type?

A struct written without compatible mode has no field names in the data. Add
`structTypes: example.Person=name,age` (field order as the writer sorted them), or write
with `compatible: true`.

## Related

- [CBOR data format](https://pmsudhi.github.io/cameleer/docs/dataformats/cbor.html), [Avro data format](https://pmsudhi.github.io/cameleer/docs/dataformats/avro.html), [Protobuf data format](https://pmsudhi.github.io/cameleer/docs/dataformats/protobuf.html)
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html)
- [Apache Camel Fory data format](https://camel.apache.org/components/next/dataformats/fory-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/gzip.html

# GZip data format

> The `gzipDeflater` data format compresses the message body to gzip (marshal) and decompresses gzip data (unmarshal).

**Name:** `gzipDeflater` · **Also:** `gzip`, `gzipdeflater` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Apache Camel:** [GZip Deflater](https://camel.apache.org/components/next/dataformats/gzipDeflater-dataformat.html)

## When to use it

- Shrink payloads before sending them over slow or metered links, for example from an edge
  gateway to the cloud.
- Read `.gz` files, or gzip-compressed messages from Kafka, S3 or HTTP.
- Archive logs and exports in a format every tool understands (`gunzip`, `zcat`).

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `marshal` | any body (text is taken as UTF-8 bytes) | gzip bytes (RFC 1952) |
| `unmarshal` | gzip bytes | the decompressed bytes |

Compression uses Cameleer's built-in DEFLATE implementation (no zlib library). Decompression reads
every DEFLATE block type, so files written by `gzip`, Java or Python decompress fine.

## Example

Compress a body, record the compressed size, and decompress it again:

```yaml
- route:
    id: gzip-round-trip
    from:
      uri: direct:gzip-round-trip
      steps:
        - marshal:
            gzipDeflater: {}
        - setHeader:
            name: compressedSize
            simple: "${body.length()}"
        - unmarshal:
            gzip: {}
        - convertBodyTo:
            type: String
        - setBody:
            simple: "${body} (${header.compressedSize} bytes compressed)"
```

```text
sensor=42;sensor=42;sensor=42;sensor=42;sensor=42;sensor=42;sensor=42;sensor=42
```

```text
sensor=42;sensor=42;sensor=42;sensor=42;sensor=42;sensor=42;sensor=42;sensor=42 (32 bytes compressed)
```

The 79-byte body compresses to 32 bytes, including the 18 bytes of gzip header and trailer.

## Rust DSL

```rust
b.from("direct:gzip-rust")
    .marshal(DataFormatDefinition::gzip().compression_level(9))
    .unmarshal(DataFormatDefinition::gzip());
```

## Options

| option | default | description |
|---|---|---|
| `compressionLevel` (`level`) | `6` | `0` stores the data uncompressed; `1`-`9` compress (higher values search harder). |

## Common questions

### How do I read a .gz file?

Read it with the `file` component and `unmarshal: {gzip: {}}`. Add `convertBodyTo: {type: String}`
if the content is text.

### What is the difference between gzip and zipDeflater?

Both use DEFLATE. `gzipDeflater` writes the gzip container (`.gz` files, HTTP
`Content-Encoding: gzip`); [`zipDeflater`](https://pmsudhi.github.io/cameleer/docs/dataformats/zip-deflater.html) writes the zlib container
(`java.util.zip.Deflater`). For `.zip` archives use [`zipFile`](https://pmsudhi.github.io/cameleer/docs/dataformats/zipfile.html).

### Does compression make sense for small messages?

Not below about 100 bytes: the gzip header and trailer alone take 18 bytes.

## Related

- [Zip Deflater data format](https://pmsudhi.github.io/cameleer/docs/dataformats/zip-deflater.html), [Zip File data format](https://pmsudhi.github.io/cameleer/docs/dataformats/zipfile.html),
  [Tar File data format](https://pmsudhi.github.io/cameleer/docs/dataformats/tarfile.html)
- [Base64 data format](https://pmsudhi.github.io/cameleer/docs/dataformats/base64.html) to carry compressed data in text
- [Apache Camel GZip Deflater data format](https://camel.apache.org/components/next/dataformats/gzipDeflater-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/hex.html

# Hex data format

> The `hex` data format writes the message body as hexadecimal text (marshal) and reads hexadecimal text back into bytes (unmarshal).

**Name:** `hex` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) · **Apache Camel:** no direct equivalent (Camel uses
`base64` or a type converter)

## When to use it

- Log or display binary payloads (sensor frames, Modbus or CAN messages from edge devices) in a
  readable form.
- Exchange binary data with systems that use hex strings, such as hashes, keys or device IDs.
- Check the exact bytes another data format produced.

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `marshal` | any body (text is taken as UTF-8 bytes) | lowercase hex text (uppercase with `upperCase: true`) |
| `unmarshal` | hex text (whitespace ignored, even length) | bytes |

## Example

```yaml
- route:
    id: hex-encode
    from:
      uri: direct:hex-encode
      steps:
        - marshal:
            hex:
              upperCase: true
```

```text
Hi!
```

```text
486921
```

Decode a frame received as hex:

```yaml
- route:
    id: hex-decode
    from:
      uri: direct:hex-decode
      steps:
        - unmarshal:
            hex: {}
        - convertBodyTo:
            type: String
```

```text
48 65 6c 6c 6f
```

```text
Hello
```

## Rust DSL

```rust
b.from("direct:hex-rust")
    .marshal(DataFormatDefinition::hex());
```

## Options

| option | default | description |
|---|---|---|
| `upperCase` | `false` | Write `A`-`F` instead of `a`-`f`. |

## Common questions

### How do I see the bytes another data format produced?

Add `marshal: {hex: {}}` after it. The [GZip](https://pmsudhi.github.io/cameleer/docs/dataformats/gzip.html), [Avro](https://pmsudhi.github.io/cameleer/docs/dataformats/avro.html) and
[Protobuf](https://pmsudhi.github.io/cameleer/docs/dataformats/protobuf.html) pages use this to show their output.

### What happens with an odd number of hex digits?

`unmarshal` fails with a `DataFormatException` ("Hex string has odd length").

## Related

- [Base64 data format](https://pmsudhi.github.io/cameleer/docs/dataformats/base64.html), [String data format](https://pmsudhi.github.io/cameleer/docs/dataformats/string.html)
- [Apache Camel data formats](https://camel.apache.org/components/next/dataformats/index.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/hl7.html

# HL7 data format

> The `hl7` data format parses HL7 v2 messages (ER7, the pipe-delimited text) into a structured value with the `CamelHL7*` headers, and encodes such values back to ER7 text.

**Name:** `hl7` · **Crate:** `cameleer-protocols` · **Cargo feature:** [`protocols`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [HL7](https://camel.apache.org/components/next/dataformats/hl7-dataformat.html)

## When to use it

- Integrate hospital systems: admissions (ADT), orders (ORM), results (ORU) and scheduling
  (SIU) feeds arrive as HL7 v2 over MLLP.
- Route messages by type and trigger event (`ADT^A01` to one system, `ORU^R01` to another).
- Turn lab results into JSON for an analytics pipeline or an assistant that summarizes them
  for clinicians.

## Marshal and unmarshal

| direction | input body | output body |
|---|---|---|
| unmarshal | ER7 text (segments separated by CR, LF or CRLF) | an object: `messageType`, `triggerEvent`, `messageControlId`, `versionId` and `segments` (each `{name, fields}`); sets the `CamelHL7*` headers |
| marshal | such an object, or ER7 text | ER7 text with CR segment separators (text bodies are parsed first, so invalid messages fail) |

Field values are kept as raw ER7 strings (components joined with `^`). To read single fields
or components use the [hl7terser language](https://pmsudhi.github.io/cameleer/docs/languages/hl7terser.html) (`PID-5-1`,
`OBX(1)-5`), which works on the ER7 text as well as on the unmarshalled value.

The data format is registered in the registry as `hl7` by `cameleer-protocols` (included in
`cameleer_main::new_main()` and the container image). It has no options.

## Example

Unmarshal an admission message and route on the headers.

```yaml
- route:
    id: hl7-adt
    from:
      uri: direct:hl7
      steps:
        - unmarshal:
            hl7: {}
        - choice:
            when:
              - simple: "${header.CamelHL7MessageType} == 'ADT' && ${header.CamelHL7TriggerEvent} == 'A01'"
                steps:
                  - setBody:
                      simple: "admit ${header.CamelHL7MessageControl} from ${header.CamelHL7SendingApplication}: ${body.segments[2].fields[4]}"
            otherwise:
              steps:
                - setBody:
                    simple: "ignored ${header.CamelHL7MessageType}^${header.CamelHL7TriggerEvent}"
```

```text
MSH|^~\&|ADMIT|WARD7|EHR|HOSP|20261105120000||ADT^A01^ADT_A01|MSG00042|P|2.5
EVN|A01|20261105120000
PID|1||12345^^^MRN||Doe^Jane||19800101|F
```

```text
admit MSG00042 from ADMIT: Doe^Jane
```

Marshal builds ER7 from the structured value, for example a result produced by an AI
summarizer that must go back to the EHR as an `ORU^R01`. MSH field 1 is the field separator
itself, as in HL7. The route replaces the CR segment separators with ` / ` only so the
result fits on one line here.

```yaml
- route:
    id: hl7-marshal
    from:
      uri: direct:hl7-marshal
      steps:
        - unmarshal:
            json: {}
        - marshal:
            hl7: {}
        - setBody:
            simple: '${body.replace("\r", " / ")}'
```

```json
{"segments": [
  {"name": "MSH", "fields": ["|", "^~\\&", "SUMMARIZER", "AI", "EHR", "HOSP", "20261105120000", "", "ORU^R01", "MSG8", "P", "2.5"]},
  {"name": "PID", "fields": ["1", "", "12345^^^MRN", "", "Doe^Jane"]},
  {"name": "OBX", "fields": ["1", "TX", "SUMMARY", "", "Glucose within normal range"]}
]}
```

```text
MSH|^~\&|SUMMARIZER|AI|EHR|HOSP|20261105120000||ORU^R01|MSG8|P|2.5 / PID|1||12345^^^MRN||Doe^Jane / OBX|1|TX|SUMMARY||Glucose within normal range /
```

## Rust DSL

```rust
b.from("direct:hl7-rust")
    .unmarshal(DataFormatDefinition::named("hl7"))
    .set_body(simple("${header.CamelHL7MessageType}^${header.CamelHL7TriggerEvent}"));
```

## Message headers

Set by unmarshal from the MSH segment:

| header | MSH field |
|---|---|
| `CamelHL7SendingApplication` | MSH-3 |
| `CamelHL7SendingFacility` | MSH-4 |
| `CamelHL7ReceivingApplication` | MSH-5 |
| `CamelHL7ReceivingFacility` | MSH-6 |
| `CamelHL7Timestamp` | MSH-7 |
| `CamelHL7Security` | MSH-8 |
| `CamelHL7MessageType` | MSH-9-1 |
| `CamelHL7TriggerEvent` | MSH-9-2 |
| `CamelHL7MessageControl` | MSH-10 |
| `CamelHL7ProcessingId` | MSH-11 |
| `CamelHL7VersionId` | MSH-12 |
| `CamelHL7Charset` | MSH-18 |

## Differences from Apache Camel

Camel's `hl7` data format produces HAPI `Message` objects with typed segment classes per HL7
version. Here the value is a generic structure (segments and raw fields) and there is no
version-specific validation; use terser paths to read fields. Acknowledgements (`AA`, `AE`)
are generated by the [MLLP component](https://pmsudhi.github.io/cameleer/docs/components/mllp.html) (`autoAck`).

## Common questions

### How do I receive HL7 messages over MLLP?

Use `from: mllp:0.0.0.0:2575` and `unmarshal: hl7: {}`; the MLLP consumer handles framing and
sends the ACK. See the [MLLP component](https://pmsudhi.github.io/cameleer/docs/components/mllp.html).

### How do I get the patient name from an HL7 message?

`hl7terser: PID-5` gives the whole name field (`Doe^Jane`), `PID-5-1` the family name and
`PID-5-2` the given name.

### Why do my segments run together?

HL7 separates segments with a carriage return (`\r`). Unmarshal also accepts LF and CRLF;
marshal always writes CR, which some viewers show as one line.

## Related

- [hl7terser language](https://pmsudhi.github.io/cameleer/docs/languages/hl7terser.html)
- [MLLP component](https://pmsudhi.github.io/cameleer/docs/components/mllp.html)
- [FHIR data format](https://pmsudhi.github.io/cameleer/docs/dataformats/fhir.html): the newer HL7 standard
- [Apache Camel HL7 data format](https://camel.apache.org/components/next/dataformats/hl7-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/ical.html

# iCal data format

> The `iCal` data format parses iCalendar (RFC 5545, `.ics`) text into a structured value and writes such values back as iCalendar text.

**Name:** `iCal` · **Also:** `ical` · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [iCal](https://camel.apache.org/components/next/dataformats/ical-dataformat.html)

## When to use it

- Read meeting invitations that arrive by mail and route them by organizer, date or subject.
- Let an AI scheduling agent turn its decision (a JSON object) into a calendar invite that any
  calendar app accepts.
- Sync events between calendar feeds (`.ics` URLs) and other systems.

## Marshal and unmarshal

| direction | input body | output body |
|---|---|---|
| unmarshal | iCalendar text | a component object; an array when the text holds several `VCALENDAR`s |
| marshal | a component object (or an array of them) | iCalendar text with CRLF line endings, lines folded at 75 octets; sets `Content-Type: text/calendar` |

A component is `{"type": "VEVENT", "properties": {...}, "components": [...]}`. Properties are
keyed by name in document order. A property without parameters is its value string; with
parameters it is `{"value": "...", "params": {"TZID": "Europe/Paris"}}`; a repeated property
is an array. Values stay in their RFC 5545 text form, except that TEXT escapes (`\n`, `\,`,
`\;`) are decoded on unmarshal and encoded on marshal for `SUMMARY`, `DESCRIPTION`,
`LOCATION`, `COMMENT`, `CONTACT`, `CATEGORIES` and `RESOURCES`.

## Example

Read an invitation and pick out the event fields.

```yaml
- route:
    id: ical-read
    from:
      uri: direct:ical-read
      steps:
        - unmarshal:
            iCal: {}
        - setBody:
            simple: "${body.components[0].properties.SUMMARY} at ${body.components[0].properties.DTSTART.value} (${body.components[0].properties.DTSTART.params.TZID})"
```

```text
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example//Docs//EN
BEGIN:VEVENT
UID:42@example.com
DTSTAMP:20261105T090000Z
DTSTART;TZID=Europe/Berlin:20261112T100000
SUMMARY:Design review\, round 2
END:VEVENT
END:VCALENDAR
```

```text
Design review, round 2 at 20261112T100000 (Europe/Berlin)
```

Build an invite from a JSON decision (for example an agent's tool call result):

```yaml
- route:
    id: ical-build
    from:
      uri: direct:ical-build
      steps:
        - unmarshal:
            json: {}
        - marshal:
            iCal:
              validating: true
```

```json
{"type": "VCALENDAR",
 "properties": {"VERSION": "2.0", "PRODID": "-//Example//Agent//EN"},
 "components": [{"type": "VEVENT",
   "properties": {"UID": "call-7@example.com", "DTSTAMP": "20261105T090000Z",
                  "DTSTART": "20261110T140000Z", "DTEND": "20261110T143000Z",
                  "SUMMARY": "Follow-up call; budget, timeline"}}]}
```

```text
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example//Agent//EN
BEGIN:VEVENT
UID:call-7@example.com
DTSTAMP:20261105T090000Z
DTSTART:20261110T140000Z
DTEND:20261110T143000Z
SUMMARY:Follow-up call\; budget\, timeline
END:VEVENT
END:VCALENDAR
```

## Rust DSL

```rust
b.from("direct:ical-rust")
    .unmarshal(DataFormatDefinition::new("iCal"))
    .set_body(simple("${body.components[0].properties.SUMMARY}"));
```

## Options

| option | default | description |
|---|---|---|
| `validating` | `false` | Check that every `VCALENDAR` has `PRODID` and `VERSION` (on marshal and unmarshal). |

## Differences from Apache Camel

Camel's `iCal` data format maps to ical4j `Calendar` objects. Here the value is a plain
object, so you can read and build it with Simple, JSONPath or a JSON body, and recurrence
rules, time zones and dates stay as text (no ical4j calculations).

## Common questions

### How do I get the start time of an event from an .ics file?

`unmarshal: iCal: {}` and then `${body.components[0].properties.DTSTART}` (or `.value` when
the property has parameters such as `TZID`).

### How do I create a calendar invite to send by email?

Build the object (JSON, Simple `${map(...)}` or a template), `marshal: iCal`, and send it as
an attachment or with `Content-Type: text/calendar; method=REQUEST` through the mail
component.

## Related

- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html), [MIME multipart data format](https://pmsudhi.github.io/cameleer/docs/dataformats/mime-multipart.html)
- [Mail (SMTP) component](https://pmsudhi.github.io/cameleer/docs/components/smtp.html)
- [Apache Camel iCal data format](https://camel.apache.org/components/next/dataformats/ical-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/jaxb.html

# JAXB data format

> The `jaxb` data format converts XML to structured values and back, typed and optionally validated by an XML Schema (XSD), without generated Java classes.

**Name:** `jaxb` · **Crate:** `cameleer-soap` · **Cargo feature:** [`soap`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [JAXB](https://camel.apache.org/components/next/dataformats/jaxb-dataformat.html)

## When to use it

- Read and write XML documents that have an XSD: orders, invoices (UBL), bank statements
  (ISO 20022), SOAP payloads.
- Get typed values from XML: numbers, booleans and dates come out typed according to the
  schema, and repeated elements are always arrays even when only one is present.
- Validate XML on the way in or out and reject documents that break the contract, for
  example XML generated by an AI agent before it reaches a partner.

With `cameleer_main::new_main()` and the container image (which register `cameleer-soap`),
`jaxb` is this schema-typed binding. With `cameleer-core` alone, `jaxb` is an alias of the
schema-less [Jackson XML data format](https://pmsudhi.github.io/cameleer/docs/dataformats/jacksonxml.html).

## Marshal and unmarshal

| direction | input body | output body |
|---|---|---|
| unmarshal | XML text or bytes | an object: element content keyed by child name, attributes as `@name` keys, values typed by the schema; with `schema` set the document is validated first |
| marshal | an object (or a single-key object naming the root element) | XML text, indented by default, with an XML declaration unless `fragment=true` |

The root element on marshal is `partClass`, else the single key of the body object if it
names a global element, else the single global element of the schema. Without any schema the
mapping is structural: text-only elements become strings, repeated siblings arrays,
attributes `@`-prefixed keys. Validation errors raise `UnmarshalException` or
`MarshalException` (both `JAXBException`).

## Example

```xml
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="order">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="customer" type="xs:string"/>
        <xs:element name="line" maxOccurs="unbounded">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="sku" type="xs:string"/>
              <xs:element name="qty" type="xs:int"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="express" type="xs:boolean" minOccurs="0"/>
      </xs:sequence>
      <xs:attribute name="id" type="xs:int" use="required"/>
    </xs:complexType>
  </xs:element>
</xs:schema>
```

Unmarshal and validate an order. `qty` is an integer and `line` an array even with one line,
so the JSON is ready for an API or a prompt.

```yaml
- route:
    id: jaxb-unmarshal
    from:
      uri: direct:jaxb-unmarshal
      steps:
        - unmarshal:
            jaxb:
              contextPath: schemas/order.xsd
              schema: schemas/order.xsd
        - marshal:
            json: {}
```

```xml
<order id="7"><customer>ACME</customer><line><sku>A1</sku><qty>3</qty></line><express>true</express></order>
```

```json
{"@id":7,"customer":"ACME","line":[{"sku":"A1","qty":3}],"express":true}
```

An invalid document fails with `UnmarshalException`. Catch it to answer the sender instead
of failing the exchange:

```yaml
- route:
    id: jaxb-reject
    from:
      uri: direct:jaxb-reject
      steps:
        - doTry:
            steps:
              - unmarshal:
                  jaxb:
                    contextPath: schemas/order.xsd
                    schema: schemas/order.xsd
              - setBody:
                  simple: "accepted order ${body[@id]}"
            doCatch:
              - exception:
                  - UnmarshalException
                steps:
                  - setBody:
                      simple: "rejected: ${exception.message}"
```

```xml
<order id="8"><customer>ACME</customer><line><sku>A1</sku><qty>many</qty></line></order>
```

```text
rejected:
'many' is not a valid value for 'int'
```

A valid order takes the other branch:

```xml
<order id="9"><customer>ACME</customer><line><sku>A1</sku><qty>2</qty></line></order>
```

```text
accepted order 9
```

Marshal JSON into XML with the root element from the schema:

```yaml
- route:
    id: jaxb-marshal
    from:
      uri: direct:jaxb-marshal
      steps:
        - unmarshal:
            json: {}
        - marshal:
            jaxb:
              contextPath: schemas/order.xsd
              prettyPrint: false
              fragment: true
```

```json
{"@id": 9, "customer": "Globex", "line": [{"sku": "B2", "qty": 1}, {"sku": "C3", "qty": 4}]}
```

```xml
<order id="9"><customer>Globex</customer><line><sku>B2</sku><qty>1</qty></line><line><sku>C3</sku><qty>4</qty></line></order>
```

## Rust DSL

```rust
b.from("direct:jaxb-rust")
    .unmarshal(DataFormatDefinition::new("jaxb").option("contextPath", "schemas/order.xsd"))
    .marshal_json();
```

## Options

| option | default | description |
|---|---|---|
| `contextPath` | (none) | Schema(s) used for typing: XSD locations separated by `,` or `;` (path, `file:`, `classpath:`, `#bean`, or inline XSD), or a `.properties` descriptor with `schema=` and `prefix.<p>=<namespace>` lines. |
| `schema` | (none) | XSD used to validate on unmarshal and marshal (also used for typing when `contextPath` gives none). |
| `partClass` | (none) | Root element for marshal: `{namespace}local` or `local` (with `partNamespace`). |
| `partNamespace` | (none) | Namespace of `partClass`. |
| `ignoreJAXBElement` | `true` | Unmarshal returns the root element's content; `false` wraps it as `{root: content}`. |
| `prettyPrint` | `true` | Indent the output, as Camel does. |
| `fragment` | `false` | Omit the XML declaration. |
| `encoding` | `UTF-8` | Encoding of the declaration and output (`ISO-8859-1` supported for bytes). |
| `namespacePrefix` | (none) | Preferred prefixes: `uri=prefix,uri2=prefix2` or a `#bean` map. |
| `attributePrefix` | `@` | Key prefix for attributes; `plainAttributes=true` uses plain keys. |
| `typedDates` | `false` | Map `date`, `dateTime`, `time` and `duration` to calendar-like objects instead of strings. |
| `filterNonXmlChars` | `false` | Remove characters that are illegal in XML. |
| `contentTypeHeader` | `true` | Set `Content-Type` on marshal. |

`mustBeJAXBElement`, `objectFactory`, `noNamespaceSchemaLocation`, `schemaLocation`,
`schemaSeverityLevel`, `jaxbProviderProperties` and `xmlStreamWriterWrapper` are accepted for
compatibility.

## Differences from Apache Camel

Camel binds XML to classes generated by `xjc` (`contextPath` is a Java package). Here
`contextPath` points at the XSD itself and the result is a plain object. Polymorphism follows
the schema: `xsi:type` selects the derived type (kept as `@xsi:type`), and substitution group
members bind where their head element is declared.

## Common questions

### How do I validate XML against an XSD while parsing it?

Set `schema: path/to.xsd` on the `jaxb` unmarshal (as in the example). For validation alone,
without conversion, use the [validator component](https://pmsudhi.github.io/cameleer/docs/components/validator.html).

### How do I convert XML to JSON with correct number types?

`unmarshal: jaxb: {contextPath: my.xsd}` then `marshal: json: {}`. Without a schema every
value is a string, because XML has no types of its own.

### Why is a single element still an array?

The schema says `maxOccurs="unbounded"`, so the binding always produces an array. That keeps
code that reads the value simple.

## Related

- [Jackson XML data format](https://pmsudhi.github.io/cameleer/docs/dataformats/jacksonxml.html): schema-less XML mapping
- [Validator component](https://pmsudhi.github.io/cameleer/docs/components/validator.html), [XSLT component](https://pmsudhi.github.io/cameleer/docs/components/xslt.html)
- [Apache Camel JAXB data format](https://camel.apache.org/components/next/dataformats/jaxb-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/json.html

# JSON data format

> The `json` data format turns JSON text into a structured message body (unmarshal) and any body back into JSON text (marshal).

**Name:** `json` · **Also:** `jackson`, `gson`, `jsonb`, `fastjson`, `johnzon` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Apache Camel:** [Jackson](https://camel.apache.org/components/next/dataformats/jackson-dataformat.html)

## When to use it

- Parse the JSON answer of an LLM or a REST API so later steps can read fields with
  `${body.intent}`, [JSONPath](https://pmsudhi.github.io/cameleer/docs/languages/jsonpath.html) or [jq](https://pmsudhi.github.io/cameleer/docs/languages/jq.html).
- Turn a map or list built in the route (by `setBody`, an aggregation or a script) into JSON
  text before you send it over HTTP, Kafka or a file.
- Pretty print JSON for logs and human review.

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `unmarshal` | JSON text (string or bytes) | an object, array, string, number, boolean or null. Blank text gives null. A body that is already structured is left alone. |
| `marshal` | any value | JSON text (a string). Sets `Content-Type: application/json` unless `contentTypeHeader: false`. |

All the alias names (`jackson`, `gson`, `jsonb`, `fastjson`, `johnzon`) are the same data format,
so routes written for any of those Camel libraries run unchanged.

**Difference from Apache Camel:** there is no POJO binding. `unmarshalType` and similar class
options have no effect: JSON always maps to Cameleer's generic `Value` (objects, arrays and
scalars), which Simple, JSONPath, jq and the script languages navigate directly.

## Example

Parse a model's JSON answer and route on one of its fields. The answer is unmarshalled once;
after that the fields are plain map lookups.

```yaml
- route:
    id: json-llm-answer
    from:
      uri: direct:llm-answer
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: intent
            simple: "${body.intent}"
        - setBody:
            simple: "intent=${body.intent} order=${body.order.id} confidence=${body.confidence}"
```

```json
{"intent":"refund","confidence":0.92,"order":{"id":"A-17","total":49.5}}
```

```text
intent=refund order=A-17 confidence=0.92
```

Build a structure and write it out as pretty-printed JSON:

```yaml
- route:
    id: json-pretty
    from:
      uri: direct:json-pretty
      steps:
        - unmarshal:
            jackson: {}
        - marshal:
            json:
              prettyPrint: true
```

```json
{"name":"Ada","skills":["math","engines"]}
```

```json
{
  "name": "Ada",
  "skills": [
    "math",
    "engines"
  ]
}
```

## Rust DSL

```rust
b.from("direct:json-rust")
    .unmarshal(DataFormatDefinition::json())
    .set_body(simple("${body.intent}"));
```

## Options

| option | default | description |
|---|---|---|
| `prettyPrint` | `false` | Indent the JSON written by `marshal`. |
| `contentTypeHeader` | `true` | Set `Content-Type: application/json` on `marshal`. |

## Common questions

### How do I parse a JSON string into an object?

Use `unmarshal: {json: {}}`. After it, read fields with `${body.field}`, `${body.items[0].sku}`
or a [JSONPath](https://pmsudhi.github.io/cameleer/docs/languages/jsonpath.html) expression.

### Do I need to unmarshal before using JSONPath or jq?

No. The JSONPath and jq languages parse a JSON text body themselves. Unmarshal when several steps
read the body, so it is parsed only once.

### How do I convert a map to JSON text?

Use `marshal: {json: {}}`. Any body (map, list, string, number) becomes JSON text.

### Can I bind JSON to a typed class?

No, Cameleer has no Java classes. JSON maps to a generic value. Validate its shape with the
[json-validator](https://pmsudhi.github.io/cameleer/docs/components/json-validator.html) component if you need a contract.

## Related

- [JSONPath language](https://pmsudhi.github.io/cameleer/docs/languages/jsonpath.html), [jq language](https://pmsudhi.github.io/cameleer/docs/languages/jq.html),
  [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html)
- [json-validator component](https://pmsudhi.github.io/cameleer/docs/components/json-validator.html): check JSON (for example an LLM's
  output) against a JSON Schema.
- [YAML data format](https://pmsudhi.github.io/cameleer/docs/dataformats/yaml.html), [CBOR data format](https://pmsudhi.github.io/cameleer/docs/dataformats/cbor.html), [XML data format](https://pmsudhi.github.io/cameleer/docs/dataformats/jacksonxml.html)
- [Apache Camel Jackson data format](https://camel.apache.org/components/next/dataformats/jackson-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/mime-multipart.html

# MIME multipart data format

> The `mimeMultipart` data format writes a message body and its attachments as one MIME multipart document, and splits a multipart document back into a body and attachments.

**Name:** `mimeMultipart` · **Also:** `mime-multipart` · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [MIME Multipart](https://camel.apache.org/components/next/dataformats/mimeMultipart-dataformat.html)

## When to use it

- Send a document together with its attachments over HTTP, JMS or a queue as one payload
  (the format email uses).
- Receive `multipart/mixed` or `multipart/related` payloads (SOAP with attachments, AS2-like
  exchanges, email bodies) and work with the parts.
- Package a generated report and its data files for a downstream system in one message.

## Marshal and unmarshal

Attachments live in the `CamelAttachments` exchange property, an object mapping a file name
to its content (the convention of the mail component).

| direction | input | output |
|---|---|---|
| marshal | body plus `CamelAttachments` | multipart body: the body is the first part (type from the `Content-Type` header, default `text/plain; charset=UTF-8` for text, `application/octet-stream` for bytes), each attachment a further part with `Content-Disposition: attachment; filename=...` and a type guessed from the extension |
| unmarshal | multipart body (MIME headers inline, or the boundary in the `Content-Type` header) | the first part as body (with its `Content-Type` header), the other parts in `CamelAttachments` |

Without attachments marshal leaves the body unchanged unless `multipartWithoutAttachment=true`.
Non-text parts are base64 encoded unless `binaryContent=true`. With `headersInline=false`
(the default) `MIME-Version` and `Content-Type` (with the boundary) become message headers;
with `headersInline=true` they are written at the top of the body. Unmarshal leaves
non-multipart content unchanged.

## Example

Attach a CSV file to a short text, write one multipart document with inline headers, then
read it back.

```yaml
- route:
    id: mime-round-trip
    from:
      uri: direct:mime
      steps:
        - setProperty:
            name: CamelAttachments
            simple: "${map('totals.csv','region;sum')}"
        - marshal:
            mimeMultipart:
              headersInline: true
        - setHeader:
            name: firstLine
            simple: "${body.split('\r\n')[0]}"
        - removeProperty:
            name: CamelAttachments
        - unmarshal:
            mimeMultipart:
              headersInline: true
        - setBody:
            simple: "${header.firstLine} | body: ${body} | attachments: ${exchangeProperty.CamelAttachments.keySet()}"
```

```text
Weekly totals attached.
```

```text
MIME-Version: 1.0 | body: Weekly totals attached. | attachments: ["totals.csv"]
```

## Rust DSL

```rust
b.from("direct:mime-rust")
    .marshal(DataFormatDefinition::new("mimeMultipart").option("headersInline", "true").option("multipartWithoutAttachment", "true"))
    .unmarshal(DataFormatDefinition::new("mimeMultipart").option("headersInline", "true"));
```

## Options

| option | default | description |
|---|---|---|
| `multipartSubType` | `mixed` | The subtype: `multipart/mixed`, `related`, `alternative`... |
| `multipartWithoutAttachment` | `false` | Also wrap a body that has no attachments. |
| `headersInline` | `false` | Write (marshal) and read (unmarshal) the MIME headers in the body instead of message headers. |
| `includeHeaders` | (none) | With `headersInline=true`, a regex: message headers whose names match are written into the MIME headers. |
| `binaryContent` | `false` | Write non-text parts as raw bytes instead of base64. |

## Message headers and properties

| name | kind | description |
|---|---|---|
| `CamelAttachments` | exchange property | Attachments: `{file name: content}`. Read on marshal, set on unmarshal. |
| `Content-Type` | header | Type of the body part on marshal; with `headersInline=false` it carries the multipart type and boundary after marshal and is read on unmarshal. |
| `MIME-Version` | header | Set on marshal when `headersInline=false`. |

## Differences from Apache Camel

Camel keeps attachments in `AttachmentMessage` (`DataHandler`s). Here they are a plain object
in the `CamelAttachments` property, shared with the mail component, so you can set them with
Simple (`${map(...)}`) or read them with `${exchangeProperty.CamelAttachments}`.

## Common questions

### How do I add an attachment before marshalling?

Set the `CamelAttachments` property to an object, for example
`setProperty: {name: CamelAttachments, simple: "${map('report.pdf', ${header.pdf})}"}`.

### Why is my body unchanged after marshal?

There were no attachments. Set `multipartWithoutAttachment: true` to always produce a
multipart document.

## Related

- [Mail (SMTP) component](https://pmsudhi.github.io/cameleer/docs/components/smtp.html), [HTTP component](https://pmsudhi.github.io/cameleer/docs/components/http.html)
- [Base64 data format](https://pmsudhi.github.io/cameleer/docs/dataformats/base64.html)
- [Apache Camel MIME Multipart data format](https://camel.apache.org/components/next/dataformats/mimeMultipart-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/pgp.html

# PGP data format

> The `pgp` data format encrypts and signs message bodies with OpenPGP public keys on marshal, and decrypts and verifies them on unmarshal, compatible with GnuPG.

**Name:** `pgp` · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [PGP](https://camel.apache.org/components/next/dataformats/pgp-dataformat.html)

## When to use it

- Send files to a partner who publishes a PGP public key (banks, payroll and EDI exchanges
  often require it), and decrypt the files they send you.
- Encrypt data on an edge device with only the public key on the device: a stolen device
  cannot read what it already sent.
- Sign messages so the receiver can verify who produced them, for example reports generated
  by an AI agent that a human approves downstream.

## Marshal and unmarshal

| direction | input body | output body |
|---|---|---|
| marshal | text or bytes | an OpenPGP message (binary, or ASCII armored with `armored=true`), encrypted to every key selected by `keyUserid(s)`; signed too when a signature key is configured |
| unmarshal | an OpenPGP message (binary or armored) | the decrypted literal data as bytes; signatures are verified as `signatureVerificationOption` says |

Supported: v4 keys with RSA, Ed25519 (EdDSA), ECDSA and ECDH (Curve25519, P-256, P-384);
armored or binary keyrings with several keys; secret keys protected with S2K and AES or
Triple DES; SEIPD with MDC (`integrity=true`) or legacy SED; AES-128/192/256 and Triple DES
session keys; ZIP, ZLIB or no compression; one-pass signatures with SHA-1/256/384/512; and
decryption of GnuPG's OCB packets.

Not supported (differences from Apache Camel's Bouncy Castle based format): CAST5, IDEA,
Blowfish, Twofish and Camellia ciphers, BZip2, v5/v6 keys, AEAD encryption, password-only
(symmetric) messages, cleartext signatures, DSA and ElGamal keys.

## Example

The keys below were generated for this page only (user id `Docs Example <docs@example.com>`,
passphrase `docs-only`). Never use them for real data; export your own with
`gpg --armor --export` and `gpg --armor --export-secret-keys`.

```text
-----BEGIN PGP PUBLIC KEY BLOCK-----
xjMEauxXFBYJKwYBBAHaRw8BAQdA1ourTLIXH/gvewCFoEk+Zeluy9g5QtTUD2d7
jTQZnkvNH0RvY3MgRXhhbXBsZSA8ZG9jc0BleGFtcGxlLmNvbT7CiQQTFggAMQUC
auxXUBYhBC5W5U4q6l3GlHxQWpoY/ccB7VZSAhsDBAsJCAcDFQoIBBYCAQACHgEA
CgkQmhj9xwHtVlLN+QD/S6dEFukTVVGHktFz54g8umX64hMm3VaoLCRm6IKCSmIB
ANsjzFVSfydkrSeXqY0hSNi90YGGcVsLUHXlGoNCMp8JzjgEauxXFBIKKwYBBAGX
VQEFAQEHQNeft5uDzzZM0ty6J/8WaidH2WFLtu0bYhwXrKeyVIYbAwEIB8J4BBgW
CAAgBQJq7FdQFiEELlblTirqXcaUfFBamhj9xwHtVlICGwwACgkQmhj9xwHtVlJH
twEAqGFdYQ0F93Tf2etQ+eaRDzDqjv81PlMM10KQtA4PbrEA/jUbGyTjVX4nGrOd
q8mqcquoB/xaXFevJET2PddE/AgH
=cSUI
-----END PGP PUBLIC KEY BLOCK-----
```

```text
-----BEGIN PGP PRIVATE KEY BLOCK-----
xYYEauxXFBYJKwYBBAHaRw8BAQdA1ourTLIXH/gvewCFoEk+Zeluy9g5QtTUD2d7
jTQZnkv+CQMISJFaVaoY7xTAmcEZrgXrBWzxny3f4PtuP7AzqU2HesMC7VsHsu3u
Qqluxdr7M3wjuCAR60wBJb8JQykPK3CPENu1LXB0gXm2sqMlLwi4bs0fRG9jcyBF
eGFtcGxlIDxkb2NzQGV4YW1wbGUuY29tPsKJBBMWCAAxBQJq7FdQFiEELlblTirq
XcaUfFBamhj9xwHtVlICGwMECwkIBwMVCggEFgIBAAIeAQAKCRCaGP3HAe1WUs35
AP9Lp0QW6RNVUYeS0XPniDy6ZfriEybdVqgsJGbogoJKYgEA2yPMVVJ/J2StJ5ep
jSFI2L3RgYZxWwtQdeUag0IynwnHiwRq7FcUEgorBgEEAZdVAQUBAQdA15+3m4PP
NkzS3Lon/xZqJ0fZYUu27RtiHBesp7JUhhsDAQgH/gkDCEIXTf2HaNcOwJ3qRFDB
n0hyzw04BGCfHj6NRflCFOcQFVH8q/8vKHMfIhJEQzHbe8u42rCJxSU+vniy0YjA
qpgPuDT2C2ncvkjQp9me+5vCeAQYFggAIAUCauxXUBYhBC5W5U4q6l3GlHxQWpoY
/ccB7VZSAhsMAAoJEJoY/ccB7VZSR7cBAKhhXWENBfd039nrUPnmkQ8w6o7/NT5T
DNdCkLQOD26xAP41Gxsk41V+JxqznavJqnKrqAf8WlxXryRE9j3XRPwIBw==
=i1KD
-----END PGP PRIVATE KEY BLOCK-----
```

Encrypt to the public key as ASCII armor, then decrypt with the secret key. In practice the
two halves run in different places: the sender only needs `docs-pub.asc`.

```yaml
- route:
    id: pgp-round-trip
    from:
      uri: direct:pgp-round-trip
      steps:
        - marshal:
            pgp:
              keyFileName: keys/docs-pub.asc
              keyUserid: docs@example.com
              armored: true
        - setHeader:
            name: armoredStart
            simple: "${body.substring(0, 27)}"
        - unmarshal:
            pgp:
              keyFileName: keys/docs-sec.asc
              keyUserid: docs@example.com
              password: "{{env:PGP_PASSWORD:docs-only}}"
        - setBody:
            simple: "${header.armoredStart} -> ${bodyAs(String)}"
```

```text
quarterly payroll batch
```

```text
-----BEGIN PGP MESSAGE----- -> quarterly payroll batch
```

Sign and encrypt, then decrypt and require a valid signature. A message that is not signed
by an accepted key fails on unmarshal.

```yaml
- route:
    id: pgp-signed
    from:
      uri: direct:pgp-signed
      steps:
        - marshal:
            pgp:
              keyFileName: keys/docs-pub.asc
              keyUserid: docs@example.com
              signatureKeyFileName: keys/docs-sec.asc
              signatureKeyUserid: docs@example.com
              signaturePassword: "{{env:PGP_PASSWORD:docs-only}}"
        - setHeader:
            name: signers
            simple: "${header.CamelPGPDataFormatNumberOfSigningKeys}"
        - unmarshal:
            pgp:
              keyFileName: keys/docs-sec.asc
              password: "{{env:PGP_PASSWORD:docs-only}}"
              signatureKeyFileName: keys/docs-pub.asc
              signatureVerificationOption: required
        - setBody:
            simple: "signed by ${header.signers} key(s): ${bodyAs(String)}"
```

```text
approved by the review agent
```

```text
signed by 1 key(s): approved by the review agent
```

## Rust DSL

```rust
b.from("direct:pgp-rust")
    .marshal(DataFormatDefinition::new("pgp").option("keyFileName", "keys/docs-pub.asc").option("armored", "true"))
    .unmarshal(DataFormatDefinition::new("pgp").option("keyFileName", "keys/docs-sec.asc").option("password", "docs-only"))
    .convert_body_to("String");
```

## Options

| option | default | description |
|---|---|---|
| `keyFileName` | (none) | Keyring file: public keyring on marshal, secret keyring on unmarshal (armored or binary). |
| `encryptionKeyRing` | (none) | The keyring inline (armored text) or `#bean`, instead of `keyFileName`. Alias `keyring`. |
| `keyUserid` | (all keys) | Part of a user id selecting the encryption keys (marshal) or the decryption keys (unmarshal). |
| `keyUserids` | (none) | Several user id parts, comma separated, to encrypt to several recipients. |
| `password` | (none) | Passphrase of the secret key on unmarshal. |
| `armored` | `false` | Write ASCII armor instead of binary on marshal. |
| `integrity` | `true` | Use SEIPD with a modification detection code; `false` writes legacy SED packets. |
| `algorithm` | `9` (AES-256) | Session cipher: `9`/`AES256`, `8`/`AES192`, `7`/`AES128`, `2`/`TRIPLEDES`. |
| `compressionAlgorithm` | `1` (ZIP) | `1` ZIP, `2` ZLIB, `0` none. |
| `hashAlgorithm` | `8` (SHA-256) | Signature hash: `2` SHA-1, `8` SHA-256, `9` SHA-384, `10` SHA-512. |
| `fileName` | `CamelFileName` or `_CONSOLE` | Name stored in the literal data packet. |
| `signatureKeyFileName` | (none) | Secret keyring to sign with (marshal) or public keyring to verify with (unmarshal). |
| `signatureKeyRing` | (none) | The signature keyring inline or `#bean`. |
| `signatureKeyUserid` / `signatureKeyUserids` | (all keys) | User ids of the signing keys (marshal) or of the accepted signers (unmarshal). |
| `signaturePassword` | (none) | Passphrase of the signing key. |
| `signatureVerificationOption` | `optional` | `optional` (verify when signed), `required`, `no_signature_allowed`, `ignore`. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelPGPDataFormatKeyUserid`, `CamelPGPDataFormatKeyUserids`, `CamelPGPDataFormatKeyPassword` | in | Per-message recipient selection and passphrase. |
| `CamelPGPDataFormatSignatureKeyUserid`, `CamelPGPDataFormatSignatureKeyUserids`, `CamelPGPDataFormatSignatureKeyPassword` | in | Per-message signer selection and passphrase. |
| `CamelPGPDataFormatKeyFileName`, `CamelPGPDataFormatSignatureKeyFileName`, `CamelPGPDataFormatEncryptionKeyRing`, `CamelPGPDataFormatSignatureKeyRing` | in | Per-message keyrings. |
| `CamelPGPDataFormatEncryptionAlgorithm`, `CamelPGPDataFormatSignatureAlgorithm`, `CamelPGPDataFormatCompressionAlgorithm` | in | Per-message algorithms. |
| `CamelPGPDataFormatNumberOfEncryptionKeys`, `CamelPGPDataFormatNumberOfSigningKeys` | out (marshal) | How many keys the message was encrypted to and signed with. |

## Common questions

### How do I decrypt a file encrypted with gpg?

Point `keyFileName` at your exported secret keyring and give the passphrase:
`unmarshal: pgp: {keyFileName: secring.asc, password: "{{env:PGP_PASSWORD}}"}`. Messages from
GnuPG 2.4 that use OCB packets are decrypted too.

### How do I encrypt for several recipients?

Put all public keys in one keyring and either omit `keyUserid` (every key is used) or list
them in `keyUserids: alice@example.com,bob@example.com`.

### Can I use the keys from Apache Camel's Bouncy Castle setup?

Yes, if they are RSA, Ed25519 or ECDSA/ECDH v4 keys exported as armored or binary keyrings.
DSA and ElGamal keys are not supported.

## Related

- [Crypto data format](https://pmsudhi.github.io/cameleer/docs/dataformats/crypto.html): symmetric encryption with a shared key
- [File component](https://pmsudhi.github.io/cameleer/docs/components/file.html), [SFTP component](https://pmsudhi.github.io/cameleer/docs/components/sftp.html)
- [Apache Camel PGP data format](https://camel.apache.org/components/next/dataformats/pgp-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/protobuf.html

# Protobuf data format

> The `protobuf` data format encodes the message body as Protocol Buffers bytes (or proto3 JSON) using a `.proto` file, and decodes protobuf data back into a structured body.

**Name:** `protobuf` · **Crate:** `cameleer-grpc` · **Cargo feature:** [`grpc`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [Protobuf](https://camel.apache.org/components/next/dataformats/protobuf-dataformat.html)

## When to use it

- Exchange protobuf messages over Kafka, MQTT or HTTP with services generated by `protoc`.
- Decode device telemetry sent as protobuf from edge hardware.
- Convert between protobuf and JSON at an API gateway.

For gRPC calls, the [grpc component](https://pmsudhi.github.io/cameleer/docs/components/grpc.html) uses the same `.proto` support.

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `marshal`, `contentTypeFormat: native` (default) | an object, JSON text, or bytes that are already encoded | protobuf bytes. Sets `Content-Type: application/octet-stream`. |
| `marshal`, `contentTypeFormat: json` | an object, JSON text or protobuf bytes | proto3 JSON text (lowerCamelCase names). Sets `Content-Type: application/json`. |
| `unmarshal`, `native` | protobuf bytes | an object keyed by field name |
| `unmarshal`, `json` | proto3 JSON text | an object |

The `.proto` file is parsed at runtime: proto3 and basic proto2, imports from the same directory,
nested types, enums, `repeated` (packed), `map`, `oneof` and the well-known types.

**Difference from Apache Camel:** no generated Java classes. `instanceClass` names the protobuf
message (`edge.Reading`; a Java name such as `org.acme.Outer$Reading` is reduced to `Reading`), and
`protoFile` points at the `.proto` file.

## Example

The message type used by the examples:

```text
syntax = "proto3";
package edge;

message Reading {
  string id = 1;
  double temp = 2;
  bool ok = 3;
}
```

Encode a JSON reading as protobuf and show the 16 bytes:

```yaml
- route:
    id: protobuf-encode
    from:
      uri: direct:protobuf-encode
      steps:
        - marshal:
            protobuf:
              instanceClass: edge.Reading
              protoFile: reading.proto
        - marshal:
            hex: {}
```

```json
{"id":"s-1","temp":21.5,"ok":true}
```

```text
0a03732d311100000000008035401801
```

Decode protobuf bytes and read a field:

```yaml
- route:
    id: protobuf-decode
    from:
      uri: direct:protobuf-decode
      steps:
        - unmarshal:
            hex: {}
        - unmarshal:
            protobuf:
              instanceClass: edge.Reading
              protoFile: reading.proto
        - setBody:
            simple: "${body.id} reports ${body.temp}"
```

```text
0a03732d311100000000008035401801
```

```text
s-1 reports 21.5
```

## Rust DSL

```rust
b.from("direct:protobuf-rust")
    .marshal(
        DataFormatDefinition::new("protobuf")
            .option("instanceClass", "edge.Reading")
            .option("protoFile", "reading.proto"),
    );
```

`cameleer_grpc::protobuf("reading.proto", "edge.Reading")?` builds the same definition and fails
early if the file does not parse.

## Options

| option | default | description |
|---|---|---|
| `instanceClass` | (none) | The protobuf message name, e.g. `edge.Reading`. Required with `protoFile`. |
| `protoFile` | (none) | Path of the `.proto` file. |
| `contentTypeFormat` | `native` | `native` (binary) or `json` (proto3 JSON). |
| `contentTypeHeader` | `true` | Set the `Content-Type` header on marshal. |

Without `instanceClass` and `protoFile`, the format is configured per message by the headers
`CamelProtobufInstanceClass`, `CamelProtobufProtoFile` and `CamelProtobufContentTypeFormat`, or the
properties `camel.dataformat.protobuf.instanceClass`, `.protoFile` and `.contentTypeFormat`.

## Common questions

### Do I need to run protoc?

No. The `.proto` file is read at runtime; there is no code generation step.

### How do I convert protobuf to JSON?

`unmarshal` with the native format, then `marshal: {json: {}}`; or `marshal` with
`contentTypeFormat: json`, which writes proto3 JSON (lowerCamelCase names, enums as names).

## Related

- [grpc component](https://pmsudhi.github.io/cameleer/docs/components/grpc.html)
- [Avro data format](https://pmsudhi.github.io/cameleer/docs/dataformats/avro.html), [Thrift data format](https://pmsudhi.github.io/cameleer/docs/dataformats/thrift.html), [CBOR data format](https://pmsudhi.github.io/cameleer/docs/dataformats/cbor.html)
- [Apache Camel Protobuf data format](https://camel.apache.org/components/next/dataformats/protobuf-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/string.html

# String data format

> The `string` data format converts the body to bytes in a chosen charset (marshal) and bytes back to text (unmarshal).

**Name:** `string` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Apache Camel:** [String](https://camel.apache.org/components/next/dataformats/string-dataformat.html)

## When to use it

- Talk to legacy systems that expect Latin-1 (ISO-8859-1) or ASCII instead of UTF-8.
- Decode bytes from a socket, a file or a message queue into text before parsing it.
- Make the byte encoding of a payload explicit.

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `marshal` | text (bytes pass through unchanged) | bytes in `charset`. Characters the charset cannot hold become `?`. |
| `unmarshal` | bytes | text decoded from `charset` (invalid UTF-8 sequences are replaced) |

Supported charsets: `UTF-8` (default), `ISO-8859-1` (also `latin1`) and `US-ASCII` (`ASCII`).
Other names are treated as UTF-8.

## Example

Encode text as Latin-1 and show the bytes. `é` is the single byte `e9` in Latin-1 (it would be
`c3 a9` in UTF-8):

```yaml
- route:
    id: string-latin1
    from:
      uri: direct:string-latin1
      steps:
        - marshal:
            string:
              charset: ISO-8859-1
        - marshal:
            hex: {}
```

```text
café
```

```text
636166e9
```

Decode Latin-1 bytes back into text:

```yaml
- route:
    id: string-decode-latin1
    from:
      uri: direct:string-decode-latin1
      steps:
        - unmarshal:
            hex: {}
        - unmarshal:
            string:
              charset: ISO-8859-1
```

```text
636166e9
```

```text
café
```

## Rust DSL

```rust
b.from("direct:string-rust")
    .marshal(DataFormatDefinition::string().charset("ISO-8859-1"));
```

## Options

| option | default | description |
|---|---|---|
| `charset` | `UTF-8` | `UTF-8`, `ISO-8859-1` / `latin1` or `US-ASCII`. |

## Common questions

### How do I convert bytes to a string?

`unmarshal: {string: {}}` decodes UTF-8. `convertBodyTo: {type: String}` does the same.

### Which charsets are supported?

UTF-8, ISO-8859-1 and US-ASCII. Apache Camel accepts any Java charset; Cameleer treats other names
as UTF-8.

## Related

- [Hex data format](https://pmsudhi.github.io/cameleer/docs/dataformats/hex.html), [Base64 data format](https://pmsudhi.github.io/cameleer/docs/dataformats/base64.html)
- [Apache Camel String data format](https://camel.apache.org/components/next/dataformats/string-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/syslog.html

# Syslog data format

> The `syslog` data format parses RFC 5424 and RFC 3164 syslog lines into a structured value with the `CamelSyslog*` headers, and formats such values back into syslog lines.

**Name:** `syslog` · **Crate:** `cameleer-protocols` · **Cargo feature:** [`protocols`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [Syslog](https://camel.apache.org/components/next/dataformats/syslog-dataformat.html)

## When to use it

- Collect logs from network gear, Linux hosts and appliances, and forward only what matters
  (for example severity `ERR` and worse) to Slack, a ticket system or an LLM that explains the
  error.
- Normalize syslog into JSON for Elasticsearch, OpenSearch or a data lake.
- Emit syslog lines from a route to an existing SIEM.

Pair it with the `syslog` component (`syslog:udp://0.0.0.0:514`, `tcp`, `tls`) or with
`netty`/file sources that deliver raw lines.

## Marshal and unmarshal

| direction | input body | output body |
|---|---|---|
| unmarshal | a syslog line (text or bytes), RFC 5424 or RFC 3164 | an object with the fields below; sets `CamelSyslogFacility`, `CamelSyslogSeverity`, `CamelSyslogHostname`, `CamelSyslogTimestamp` |
| marshal | such an object | a syslog line in the format named by its `format` field; other bodies are passed through as text |

Fields: `format` (`RFC5424` or `RFC3164`), `priority`, `facility` (name such as `AUTH`),
`facilityCode`, `severity` (name such as `CRIT`), `severityCode`, `version` (RFC 5424),
`timestamp` (as written in the message), `timestampMillis` (when it can be parsed),
`hostname`, `appName`, `procId`, `msgId`, `structuredData` (`{"sdId": {"param": "value"}}`)
and `logMessage`. Nil values (`-`) are `null`.

## Example

Parse an RFC 5424 line and keep only errors and worse (severity code 3 or lower).

```yaml
- route:
    id: syslog-errors
    from:
      uri: direct:syslog
      steps:
        - unmarshal:
            syslog: {}
        - choice:
            when:
              - simple: "${body.severityCode} <= 3"
                steps:
                  - setBody:
                      simple: "${header.CamelSyslogSeverity} on ${header.CamelSyslogHostname} (${body.appName}): ${body.logMessage} [region=${body.structuredData[origin][region]}]"
            otherwise:
              steps:
                - setBody:
                    constant: dropped
```

```text
<34>1 2026-11-05T10:15:00.000Z gw-01 sshd 4321 ID47 [origin region="eu-west"] Failed password for root
```

```text
CRIT on gw-01 (sshd): Failed password for root [region=eu-west]
```

```text
<13>Nov  5 10:15:00 web-3 cron[99]: job finished
```

```text
dropped
```

Format a value as an RFC 5424 line:

```yaml
- route:
    id: syslog-marshal
    from:
      uri: direct:syslog-marshal
      steps:
        - unmarshal:
            json: {}
        - marshal:
            syslog: {}
```

```json
{"format": "RFC5424", "facility": "LOCAL0", "severity": "WARNING", "timestamp": "2026-11-05T10:15:00Z",
 "hostname": "edge-7", "appName": "cameleer", "procId": null, "msgId": "TEMP", "logMessage": "sensor t1 above 80C"}
```

```text
<132>1 2026-11-05T10:15:00Z edge-7 cameleer - TEMP - sensor t1 above 80C
```

The priority is `facility * 8 + severity`: LOCAL0 (16) and WARNING (4) give 132. Null
fields (here `procId` and the structured data) are written as `-`.

## Rust DSL

```rust
b.from("direct:syslog-rust")
    .unmarshal(DataFormatDefinition::named("syslog"))
    .set_body(simple("${header.CamelSyslogSeverity}: ${body.logMessage}"));
```

## Message headers

| header | direction | description |
|---|---|---|
| `CamelSyslogFacility` | out (unmarshal) | Facility name, for example `AUTH`, `LOCAL0`. |
| `CamelSyslogSeverity` | out (unmarshal) | Severity name: `EMERG`, `ALERT`, `CRIT`, `ERR`, `WARNING`, `NOTICE`, `INFO`, `DEBUG`. |
| `CamelSyslogHostname` | out (unmarshal) | Host name from the message. |
| `CamelSyslogTimestamp` | out (unmarshal) | Timestamp from the message. |

The data format has no options. It is registered in the registry as `syslog` by
`cameleer-protocols` (included in `cameleer_main::new_main()` and the container image).

## Differences from Apache Camel

Camel unmarshals into `SyslogMessage` / `Rfc5424SyslogMessage` objects. Here the result is a
plain object with the same information (field names follow the Java getters), so Simple,
JSONPath and `marshal: json` work on it directly.

## Common questions

### How do I receive syslog over UDP and parse it?

`from: syslog:udp://0.0.0.0:514` already unmarshals by default (component option
`unmarshal=true`). Use the data format when lines come from elsewhere, such as a file or a
Kafka topic.

### How do I parse old BSD-style syslog lines?

Nothing to configure: lines without the version number after the priority are parsed as RFC
3164 (`format: RFC3164`), as the second input of the first example shows. RFC 3164
timestamps have no year; the original text is kept in `timestamp`.

## Related

- [Syslog component](https://pmsudhi.github.io/cameleer/docs/components/syslog.html)
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html)
- [Apache Camel Syslog data format](https://camel.apache.org/components/next/dataformats/syslog-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/tarfile.html

# Tar file data format

> The `tarFile` data format packs a message body into a tar archive and unpacks tar archives back into one body or a list of entries.

**Name:** `tarFile` · **Also:** `tar`, `tarfile` · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [Tar File](https://camel.apache.org/components/next/dataformats/tarFile-dataformat.html)

## When to use it

- Bundle the files a route produces (reports, logs, model outputs) into one `.tar` before
  uploading them to S3, SFTP or an artifact store.
- Unpack a tar archive that arrives by file, FTP or HTTP and process each entry.
- Ship a batch of sensor readings from an edge device as one archive instead of many small
  files.

## Marshal and unmarshal

| direction | input body | output body |
|---|---|---|
| marshal | text or bytes: one entry named after the `CamelFileName` header (the exchange id when the header is missing) | tar archive bytes; `CamelFileName` gets a `.tar` suffix |
| marshal | an object `{name: content, ...}` | tar archive with one entry per key |
| unmarshal | tar archive bytes | the single entry's content as bytes, its name in `CamelFileName` (an archive with more than one file fails with `IllegalStateException`, as in Camel) |
| unmarshal with `usingIterator=true` | tar archive bytes | an array with the content of every entry, the names in the `CamelTarFileEntryNames` header (same order) |

The archive is POSIX ustar with pax extended headers for long names; GNU long names are read
too. Entry names keep only the file name unless `preservePathElements=true`.

## Example

Pack one file and unpack it again. In a real route the archive bytes would go to a file,
S3 or SFTP endpoint between the two steps.

```yaml
- route:
    id: tar-single
    from:
      uri: direct:tar-single
      steps:
        - setHeader:
            name: CamelFileName
            constant: reports/daily.txt
        - marshal:
            tarFile: {}
        - setHeader:
            name: archiveName
            simple: "${header.CamelFileName}"
        - unmarshal:
            tarFile: {}
        - setBody:
            simple: "${header.archiveName} contained ${header.CamelFileName}: ${bodyAs(String)}"
```

```text
all systems nominal
```

```text
reports/daily.txt.tar contained daily.txt: all systems nominal
```

Several entries: an object body becomes one entry per key, and `usingIterator=true` gives
every entry back with its name. The route splits the entries and joins one line per file.

```yaml
- route:
    id: tar-many
    from:
      uri: direct:tar-many
      steps:
        - unmarshal:
            json: {}
        - marshal:
            tarFile: {}
        - unmarshal:
            tarFile:
              usingIterator: true
        - setHeader:
            name: names
            simple: "${header.CamelTarFileEntryNames}"
        - setBody:
            simple: "${header.names} -> ${body[0]} / ${body[1]}"
        - convertBodyTo: String
```

```json
{"a.csv": "id,qty\n1,2", "b.csv": "id,qty\n3,4"}
```

```text
["a.csv","b.csv"] -> id,qty
1,2 / id,qty
3,4
```

## Rust DSL

```rust
b.from("direct:tar-rust")
    .set_header("CamelFileName", constant("notes.txt"))
    .marshal(DataFormatDefinition::new("tarFile"))
    .unmarshal(DataFormatDefinition::new("tarFile"))
    .convert_body_to("String");
```

## Options

| option | default | description |
|---|---|---|
| `usingIterator` | `false` | Unmarshal every entry into an array (names in `CamelTarFileEntryNames`) instead of a single body. |
| `allowEmptyDirectory` | `false` | With `usingIterator`, include directory entries as empty bodies. |
| `preservePathElements` | `false` | Keep the directory part of `CamelFileName` (and object keys) as the entry name. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelFileName` | in (marshal) / out | Entry name on marshal; `.tar` is appended to it. Set to the entry name on unmarshal. |
| `CamelTarFileEntryNames` | out (unmarshal) | Entry names when `usingIterator=true`. |

## Common questions

### How do I tar several files into one archive?

Build an object body whose keys are file names and values are contents (for example with
`unmarshal: json` or an aggregation), then `marshal: tarFile`. Each key becomes an entry.

### How do I process every file in a tar archive?

Use `unmarshal: tarFile: {usingIterator: true}` and then `split: simple: "${body}"`; the
names are in the `CamelTarFileEntryNames` header at the same index.

### Does it compress?

No. Tar only bundles. Add `marshal: gzipDeflater` after it for a `.tar.gz`, and
`unmarshal: gzipDeflater` before unpacking one.

## Related

- [Zip file data format](https://pmsudhi.github.io/cameleer/docs/dataformats/zipfile.html), [GZip data format](https://pmsudhi.github.io/cameleer/docs/dataformats/gzip.html)
- [Split EIP](https://pmsudhi.github.io/cameleer/docs/guides/eips.html)
- [Apache Camel Tar File data format](https://camel.apache.org/components/next/dataformats/tarFile-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/thrift.html

# Thrift data format

> The `thrift` data format converts structured values to and from Apache Thrift binary, compact or JSON encodings, using a Thrift IDL file read at runtime instead of generated classes.

**Name:** `thrift` · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [Thrift](https://camel.apache.org/components/next/dataformats/thrift-dataformat.html)

## When to use it

- Talk to services and queues that carry Thrift-encoded payloads (common in older big-data
  stacks: Scribe, HBase, Cassandra Thrift, internal RPC).
- Turn compact binary Thrift records from Kafka into JSON for a dashboard, a search index or
  an LLM prompt.
- Keep one `.thrift` file as the contract and change it without recompiling anything.

For Thrift RPC calls (client and server) see the `thrift` component, which uses the same IDL
parser.

## Marshal and unmarshal

| direction | input body | output body |
|---|---|---|
| marshal | an object keyed by field name (for `json`/`sjson` also a JSON string) | Thrift bytes (`binary`, `compact`) or a JSON string (`json`, `sjson`); sets `Content-Type` |
| unmarshal | Thrift bytes or JSON text | an object keyed by field name |

Value mapping: structs, unions and exceptions are objects; enums are their names; `binary`
fields are bytes; `list` and `set` are arrays; `map` is an object. Missing fields that have a
default in the IDL get it; missing `required` fields fail with `TException`.

The IDL parser understands `struct`, `union`, `exception`, `enum`, `typedef`, `const`,
`service` and the base types `bool byte i8 i16 i32 i64 double string binary uuid`, plus
`list<T>`, `set<T>` and `map<K,V>`. `namespace`, `include`, annotations and comments are
ignored, so the same file a Java build uses works unchanged.

## Example

```text
namespace java com.example.telemetry

enum Status { OK = 1, WARN = 2, FAIL = 3 }

struct Reading {
  1: required string sensor,
  2: i32 celsius,
  3: Status status = Status.OK,
  4: optional list<string> tags,
}
```

JSON in, Thrift binary out (shown as hex), and back. Field 3 is filled from its default.

```yaml
- route:
    id: thrift-binary
    from:
      uri: direct:thrift-binary
      steps:
        - unmarshal:
            json: {}
        - marshal:
            thrift:
              idlFile: idl/telemetry.thrift
              instanceClass: com.example.telemetry.Reading
        - marshal:
            hex: {}
        - setHeader:
            name: hex
            simple: "${body}"
        - unmarshal:
            hex: {}
        - unmarshal:
            thrift:
              idlFile: idl/telemetry.thrift
              instanceClass: Reading
        - setBody:
            simple: "${header.hex}\n${body}"
```

```json
{"sensor": "t1", "celsius": 21}
```

```text
0b0001000000027431080002000000150800030000000100
{"sensor":"t1","celsius":21,"status":"OK"}
```

Read the hex as Thrift binary fields: `0b 0001 00000002 7431` is field 1, a string of length
2 (`t1`); `08 0002 00000015` is field 2, an i32 (21); `08 0003 00000001` is field 3, the enum
default `OK` (1); `00` ends the struct.

The `json` content type is Thrift's own JSON protocol (field ids and type tags), what a
Thrift `TJSONProtocol` client sends:

```yaml
- route:
    id: thrift-tjson
    from:
      uri: direct:thrift-tjson
      steps:
        - marshal:
            thrift:
              idlFile: idl/telemetry.thrift
              instanceClass: Reading
              contentTypeFormat: json
```

```json
{"sensor": "t1", "celsius": 21, "status": "WARN", "tags": ["roof"]}
```

```text
{"1":{"str":"t1"},"2":{"i32":21},"3":{"i32":2},"4":{"lst":["str",1,"roof"]}}
```

## Rust DSL

```rust
let reading = DataFormatDefinition::new("thrift")
    .option("idlFile", "idl/telemetry.thrift")
    .option("instanceClass", "Reading")
    .option("contentTypeFormat", "compact");
b.from("direct:thrift-rust")
    .unmarshal_json()
    .marshal(reading.clone())
    .unmarshal(reading)
    .marshal_json();
```

## Options

| option | default | description |
|---|---|---|
| `instanceClass` | the only struct | Struct to encode/decode, plain or qualified (`com.example.Reading`); required when the IDL has more than one struct. |
| `schema` | (none) | The IDL inline. Alias `idl`. |
| `idlFile` | (none) | Path of the `.thrift` file (also `file:` and `classpath:`). Alias `schemaFile`. |
| `contentTypeFormat` | `binary` | `binary` (TBinaryProtocol), `compact` (TCompactProtocol), `json` (TJSONProtocol) or `sjson` (plain JSON, like TSimpleJSONProtocol; validated against the IDL on marshal). |
| `contentTypeHeader` | `true` | Set `Content-Type` (`application/octet-stream` or `application/json`) on marshal. |

## Differences from Apache Camel

Camel needs classes generated by the Thrift compiler (`instanceClass` is a Java class name).
Here the IDL is parsed at runtime and the value is a plain object, so `schema` or `idlFile`
is required and `instanceClass` names the struct in it.

## Common questions

### How do I convert Thrift binary to JSON?

`unmarshal: thrift: {idlFile: x.thrift, instanceClass: T}` followed by `marshal: json: {}`.

### Which protocol does my service use?

Most services use binary (`TBinaryProtocol`). If the bytes start with field headers like
`0x15` or `0x18` rather than `0x08`/`0x0b`, it is probably compact. Try `compact`.

### Can I use the same IDL that my Java project compiles?

Yes. Namespaces, includes and annotations are ignored; included files are not loaded, so put
the types you need in the file you reference.

## Related

- [Protobuf data format](https://pmsudhi.github.io/cameleer/docs/dataformats/protobuf.html), [Avro data format](https://pmsudhi.github.io/cameleer/docs/dataformats/avro.html)
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html), [Hex data format](https://pmsudhi.github.io/cameleer/docs/dataformats/hex.html)
- [Apache Camel Thrift data format](https://camel.apache.org/components/next/dataformats/thrift-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/univocity.html

# uniVocity data formats

> The uniVocity data formats (`univocityCsv`, `univocityTsv`, `univocityFixed`) parse and write CSV, tab-separated and fixed-width files as rows or maps, with uniVocity's option names.

**Name:** `univocityCsv` · **Also:** `univocityTsv`, `univocityFixed` (and the `univocity-csv`,
`univocitycsv`... spellings) · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [uniVocity CSV](https://camel.apache.org/components/next/dataformats/univocityCsv-dataformat.html)

## When to use it

- Run Camel routes that already use `univocityCsv`, `univocityTsv` or `univocityFixed` unchanged.
- Read TSV exports (spreadsheets, bioinformatics, log tools) with escapes such as `\t` and `\n`.
- Read fixed-width files by field lengths without writing a record descriptor.

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `unmarshal` | text | a list of rows: lists of strings, or maps with `asMap: true` (keys from `headers`, or the first line with `headerExtractionEnabled: true`) |
| `marshal` | a list of lists or of maps (`headers` selects and orders the columns) | text, one line per row |

`univocityCsv` is the [csv](https://pmsudhi.github.io/cameleer/docs/dataformats/csv.html) data format with the option names translated. `univocityTsv`
and `univocityFixed` are separate implementations with the same row options.

## Example

Read a TSV file with a header line into maps:

```yaml
- route:
    id: tsv-to-json
    from:
      uri: direct:tsv-to-json
      steps:
        - unmarshal:
            univocityTsv:
              headerExtractionEnabled: true
              asMap: true
        - marshal:
            json: {}
```

```text
host	status	note
web-1	up	ok
web-2	down	disk\tfull
```

```json
[{"host":"web-1","status":"up","note":"ok"},{"host":"web-2","status":"down","note":"disk\tfull"}]
```

The `\t` in the last field is an escaped tab, decoded to a real tab character.

Read fixed-width records by field lengths:

```yaml
- route:
    id: fixed-width
    from:
      uri: direct:fixed-width
      steps:
        - unmarshal:
            univocityFixed:
              fieldLengths: 5,8,4
              headers: code,city,temp
              asMap: true
              ignoreTrailingWhitespaces: true
        - marshal:
            json: {}
```

```text
AMS01Amsterdam12
BLR02Bangalor31
```

```json
[{"code":"AMS01","city":"Amsterda","temp":"m12"},{"code":"BLR02","city":"Bangalor","temp":"31"}]
```

Fields are cut strictly by length, as uniVocity does: `Amsterdam` is 9 characters, so its last
letter spills into the next field. Make the field wide enough for your longest value.

Write CSV with the columns chosen by `headers`:

```yaml
- route:
    id: univocity-csv-out
    from:
      uri: direct:univocity-csv-out
      steps:
        - unmarshal:
            json: {}
        - marshal:
            univocityCsv:
              headers: host,status
              lineSeparator: "\\n"
              quoteAllFields: true
```

```json
[{"host":"web-1","status":"up","cpu":12},{"host":"web-2","status":"down","cpu":0}]
```

```text
"host","status"
"web-1","up"
"web-2","down"
```

## Rust DSL

```rust
b.from("direct:univocity-rust")
    .unmarshal(DataFormatDefinition::new("univocityTsv").option("headerExtractionEnabled", true).option("asMap", true))
    .marshal(DataFormatDefinition::json());
```

## Options

| option | applies to | description |
|---|---|---|
| `headers` | all | Comma separated column names (map keys on unmarshal, column selection on marshal). |
| `headerExtractionEnabled` | all | Read the header names from the first line (the line is skipped). |
| `asMap` | all | Unmarshal rows to maps instead of lists. |
| `headersDisabled` | all | Ignore header names: map keys become `column1`, `column2`... |
| `lineSeparator` | all | Line separator written by marshal (default `\n` for TSV and fixed, CRLF for CSV). |
| `skipEmptyLines` | all | Skip blank lines (default true). |
| `nullValue` | all | Text written for null (CSV: also read as null). |
| `emptyValue` | all | Value of empty fields on unmarshal. |
| `comment` | all | Lines starting with this character are skipped. |
| `ignoreLeadingWhitespaces`, `ignoreTrailingWhitespaces` | all | Trim fields. |
| `numberOfRecordsToRead` | all | Stop after this many records. |
| `lazyLoad`, `normalizedLineSeparator` | all | Accepted; rows are always returned as a list. |
| `delimiter`, `quote`, `quoteEscape`, `quoteAllFields` | CSV | Delimiter, quote character, quote escape, quote every field on marshal. |
| `escapeChar` | TSV | Escape character (default `\`). |
| `fieldLengths` | fixed | Comma separated field widths (required). |
| `padding` | fixed | Padding character written by marshal (default space). |
| `skipTrailingCharsUntilNewline` | fixed | Drop the rest of the line after the last field. |
| `recordEndsOnNewline` | fixed | End a record at a newline even if fields are missing (they become null). |

## Common questions

### How do I parse a tab-separated file?

`unmarshal: {univocityTsv: {headerExtractionEnabled: true, asMap: true}}` gives one map per line.

### How do I read a fixed-width file without a descriptor?

Use `univocityFixed` with `fieldLengths`. For typed fields (numbers, dates) use
[bindyFixed](https://pmsudhi.github.io/cameleer/docs/dataformats/bindy.html).

## Related

- [CSV data format](https://pmsudhi.github.io/cameleer/docs/dataformats/csv.html), [Bindy data formats](https://pmsudhi.github.io/cameleer/docs/dataformats/bindy.html)
- [Apache Camel uniVocity CSV](https://camel.apache.org/components/next/dataformats/univocityCsv-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/urlencoded.html

# URL-encoded form data format

> The `urlencoded` data format parses `application/x-www-form-urlencoded` text into a map (unmarshal) and writes a map as form text (marshal).

**Name:** `urlencoded` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) · **Apache Camel:** no direct equivalent (Camel
handles forms in the HTTP components)

## When to use it

- Read HTML form posts and webhook callbacks that arrive as `a=1&b=2` (Slack slash commands,
  Twilio, payment providers).
- Build the body of an OAuth token request or any form POST.

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `unmarshal` | form text | a map. `+` and `%XX` are decoded; a repeated key becomes a list. |
| `marshal` | a map (null gives an empty string) | form text. List values repeat the key. |

## Example

Parse a form post and turn it into JSON:

```yaml
- route:
    id: form-to-json
    from:
      uri: direct:form-to-json
      steps:
        - unmarshal:
            urlencoded: {}
        - marshal:
            json: {}
```

```text
name=Ada+Lovelace&topic=math&topic=engines&note=50%25+off
```

```json
{"name":"Ada Lovelace","topic":["math","engines"],"note":"50% off"}
```

Build a form body from JSON, for example for an OAuth client-credentials request:

```yaml
- route:
    id: json-to-form
    from:
      uri: direct:json-to-form
      steps:
        - unmarshal:
            json: {}
        - marshal:
            urlencoded: {}
```

```json
{"grant_type":"client_credentials","scope":"read write"}
```

```text
grant_type=client_credentials&scope=read%20write
```

## Rust DSL

```rust
b.from("direct:urlencoded-rust")
    .unmarshal(DataFormatDefinition::urlencoded())
    .set_body(simple("${body[name]}"));
```

## Options

None.

## Common questions

### How do I read a form field from a POST body?

`unmarshal: {urlencoded: {}}`, then `${body[field]}` in Simple. Repeated fields are lists.

### Are spaces written as + or %20?

`marshal` writes `%20`. `unmarshal` accepts both.

## Related

- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html)
- [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/jacksonxml.html

# XML data format (Jackson XML)

> The `jacksonXml` data format converts between XML text and a structured body: object keys become elements, lists repeat the element, and options map keys to attributes, text and namespaces.

**Name:** `jacksonXml` · **Also:** `xml`, `jacksonxml` (and `jaxb` when `cameleer-soap` is not
registered) · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Apache Camel:** [Jackson XML](https://camel.apache.org/components/next/dataformats/jacksonXml-dataformat.html)

## When to use it

- Convert JSON from a REST API or an LLM into XML for a legacy or SOAP-style system, and back.
- Read XML documents into a map so Simple, JSONPath or jq can pick fields without XPath.
- Produce XML with attributes, namespaces and wrapper elements without writing a template.

With `cameleer_main::new_main` (the `cameleer` CLI), `jaxb` is the schema-typed
[JAXB data format](https://pmsudhi.github.io/cameleer/docs/dataformats/jaxb.html) from `cameleer-soap`; use `jacksonXml` or `xml` for this generic
mapping.

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `marshal` | an object (or JSON text of one) | XML text with the root element `rootName`. Sets `Content-Type: application/xml` unless `contentTypeHeader: false`. |
| `unmarshal` | XML text | an object: child elements become keys (repeated elements become lists), attributes become keys too, text-only elements become strings. Namespace prefixes are dropped. |

Values are not typed on unmarshal: `<qty>2</qty>` gives the string `"2"`.

**Difference from Apache Camel:** there is no class binding. Jackson annotations are replaced
by the options `attributes`, `textProperty`, `properties`, `namespaces` and `wrappers`.

## Example

Turn a JSON order into XML, with `id` as an attribute:

```yaml
- route:
    id: json-to-xml
    from:
      uri: direct:json-to-xml
      steps:
        - unmarshal:
            json: {}
        - marshal:
            jacksonXml:
              rootName: order
              attributes: id
```

```json
{"id":42,"customer":"Ada","item":[{"sku":"A1","qty":2},{"sku":"B2","qty":1}]}
```

```xml
<order id="42"><customer>Ada</customer><item><sku>A1</sku><qty>2</qty></item><item><sku>B2</sku><qty>1</qty></item></order>
```

Read XML into a structure and write it as JSON:

```yaml
- route:
    id: xml-to-json
    from:
      uri: direct:xml-to-json
      steps:
        - unmarshal:
            xml: {}
        - marshal:
            json: {}
```

```xml
<order id="42"><customer>Ada</customer><item><sku>A1</sku></item><item><sku>B2</sku></item></order>
```

```json
{"id":"42","customer":"Ada","item":[{"sku":"A1"},{"sku":"B2"}]}
```

Wrap a list in a parent element and declare a namespace:

```yaml
- route:
    id: xml-wrappers
    from:
      uri: direct:xml-wrappers
      steps:
        - unmarshal:
            json: {}
        - marshal:
            jacksonXml:
              rootName: catalog
              namespace: urn:acme:catalog
              wrappers: "books:book"
```

```json
{"books":["Dune","Emma"]}
```

```xml
<catalog xmlns="urn:acme:catalog"><books><book>Dune</book><book>Emma</book></books></catalog>
```

## Rust DSL

```rust
b.from("direct:xml-rust")
    .unmarshal(DataFormatDefinition::json())
    .marshal(DataFormatDefinition::xml().root_name("order"));
```

## Options

| option | default | description |
|---|---|---|
| `rootName` | `root` | Root element name; may be `p:name` or `{uri}name`. |
| `prettyPrint` | `false` | Indent the XML. |
| `xmlDeclaration` | `false` | Start with `<?xml version="1.0" encoding="UTF-8"?>`. |
| `contentTypeHeader` | `true` | Set `Content-Type: application/xml` on marshal. |
| `attributePrefix` | `@` | Keys starting with it are written as attributes. When set explicitly, unmarshal also prefixes attribute keys with it. |
| `attributes` | (none) | Comma separated keys always written as attributes. |
| `textProperty` | `""` | Key holding the element's own text (`#text` and `$` are always accepted on marshal). |
| `properties` | (none) | `key:xmlName,...` renames; `xmlName` may be `p:local` or `{uri}local`. |
| `namespace` | (none) | Default namespace of the root element (`xmlns="..."`). |
| `namespaces` | (none) | `prefix=uri,...` declared on the root element. |
| `wrappers` | (none) | `key:itemName,...`: write the list `key` inside a `<key>` wrapper with `<itemName>` items; unwrapped again on unmarshal. |

## Common questions

### How do I convert JSON to XML?

`unmarshal: {json: {}}` then `marshal: {jacksonXml: {rootName: order}}`. For XML that must match
an XSD, use the [JAXB data format](https://pmsudhi.github.io/cameleer/docs/dataformats/jaxb.html) or an [XSLT](https://pmsudhi.github.io/cameleer/docs/components/xslt.html) template instead.

### How do I write an attribute instead of an element?

List the key in `attributes: id,version`, or prefix the key with `@` (`{"@id": 42}`).

### Why are numbers strings after unmarshal?

XML has no types. Convert the fields you need, or use the schema-typed [JAXB](https://pmsudhi.github.io/cameleer/docs/dataformats/jaxb.html) format.

## Related

- [JAXB data format](https://pmsudhi.github.io/cameleer/docs/dataformats/jaxb.html), [XJ component](https://pmsudhi.github.io/cameleer/docs/components/xj.html),
  [XSLT component](https://pmsudhi.github.io/cameleer/docs/components/xslt.html), [XPath language](https://pmsudhi.github.io/cameleer/docs/languages/xpath.html)
- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html)
- [Apache Camel Jackson XML data format](https://camel.apache.org/components/next/dataformats/jacksonXml-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/yaml.html

# YAML data format

> The `yaml` data format parses YAML text into a structured body (unmarshal) and writes any body as YAML (marshal), like Camel's SnakeYAML data format.

**Name:** `yaml` · **Also:** `snakeYaml`, `snakeyaml`, `snake-yaml` · **Crate:** `cameleer-dataformats` · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [YAML SnakeYAML](https://camel.apache.org/components/next/dataformats/yaml-snakeyaml-dataformat.html)

## When to use it

- Read configuration, Kubernetes manifests or OpenAPI documents in a route.
- Ask an LLM to answer in YAML (often fewer tokens than JSON) and parse its answer.
- Turn JSON into readable YAML for people or GitOps repositories.

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `unmarshal` | YAML text (one document) | an object, list or scalar. Anchors and aliases are resolved. |
| `marshal` | any value | YAML text. In the default `AUTO` style, collections holding only scalars use flow style (`{a: 1}`, `[1, 2]`), the others block style. |

Unmarshal is safe by default: documents with application tags such as `!!com.acme.Pojo` are
rejected, and no type is ever constructed from a tag.

## Example

Parse a YAML answer from a model and route on a field:

```yaml
- route:
    id: yaml-answer
    from:
      uri: direct:yaml-answer
      steps:
        - unmarshal:
            yaml: {}
        - setBody:
            simple: "${body.action} on ${body.targets.size()} hosts, first ${body.targets[0]}"
```

```text
action: restart
reason: memory leak
targets:
  - web-1
  - web-2
```

```text
restart on 2 hosts, first web-1
```

Write JSON as YAML in block style:

```yaml
- route:
    id: json-to-yaml
    from:
      uri: direct:json-to-yaml
      steps:
        - unmarshal:
            json: {}
        - marshal:
            yaml:
              defaultFlowStyle: BLOCK
```

```json
{"service":"orders","replicas":3,"ports":[8080,9090]}
```

```text
service: orders
replicas: 3
ports:
- 8080
- 9090
```

## Rust DSL

```rust
b.from("direct:yaml-rust")
    .unmarshal(DataFormatDefinition::new("yaml"))
    .marshal(DataFormatDefinition::json());
```

## Options

| option | default | description |
|---|---|---|
| `defaultFlowStyle` (`flowStyle`) | `AUTO` | `AUTO`, `BLOCK` or `FLOW`. |
| `prettyFlow` | `false` | Write flow collections over several indented lines. |
| `allowAnyType` | `false` | Accept documents with application tags (the tag is ignored and the node read as plain data). |
| `typeFilter` | (none) | Comma separated tag names (or `prefix.*`) accepted without `allowAnyType`. |
| `maxAliasesForCollections` | `50` | Maximum number of aliases in one document (protects against alias bombs). |

`unmarshalType` is accepted and ignored: YAML always maps to a generic value.

## Common questions

### How do I convert YAML to JSON?

`unmarshal: {yaml: {}}` then `marshal: {json: {}}`.

### Is it safe to parse untrusted YAML?

Yes, by default. Tags that name types are rejected, nothing is instantiated, and aliases are
limited by `maxAliasesForCollections`.

## Related

- [JSON data format](https://pmsudhi.github.io/cameleer/docs/dataformats/json.html), [Simple language](https://pmsudhi.github.io/cameleer/docs/languages/simple.html)
- [Apache Camel YAML SnakeYAML data format](https://camel.apache.org/components/next/dataformats/yaml-snakeyaml-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/zip-deflater.html

# Zip Deflater data format

> The `zipDeflater` data format compresses the message body with zlib/DEFLATE (marshal) and decompresses it (unmarshal), like Java's `java.util.zip.Deflater`.

**Name:** `zipDeflater` · **Also:** `zip`, `deflate`, `zlib`, `zipdeflater` · **Crate:** `cameleer-core` · **Cargo feature:** none, always included ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) ·
**Apache Camel:** [Zip Deflater](https://camel.apache.org/components/next/dataformats/zipDeflater-dataformat.html)

## When to use it

- Exchange compressed messages with Java Camel routes that use `zipDeflater`.
- Compress payloads stored in a database column, a cache or a queue where the zlib format is
  expected (`zlib.decompress` in Python, `Inflater` in Java).
- Cut bandwidth on edge links when both ends are under your control.

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `marshal` | any body (text is taken as UTF-8 bytes) | zlib bytes (RFC 1950: 2-byte header, DEFLATE data, Adler-32 checksum) |
| `unmarshal` | zlib bytes | the decompressed bytes |

This is not a `.zip` archive: for archives with file entries use [`zipFile`](https://pmsudhi.github.io/cameleer/docs/dataformats/zipfile.html).

## Example

Compress a body and show it as Base64, so it fits in a JSON field:

```yaml
- route:
    id: zlib-compress
    from:
      uri: direct:zlib-compress
      steps:
        - marshal:
            zipDeflater: {}
        - marshal:
            base64: {}
```

```text
hello hello hello hello
```

```text
eJzLSM3JyVfAIAFoAwix
```

And decompress it again:

```yaml
- route:
    id: zlib-decompress
    from:
      uri: direct:zlib-decompress
      steps:
        - unmarshal:
            base64: {}
        - unmarshal:
            zipDeflater: {}
        - convertBodyTo:
            type: String
```

```text
eJzLSM3JyVfAIAFoAwix
```

```text
hello hello hello hello
```

## Rust DSL

```rust
b.from("direct:zlib-rust")
    .marshal(DataFormatDefinition::zip_deflater())
    .unmarshal(DataFormatDefinition::zip_deflater());
```

## Options

| option | default | description |
|---|---|---|
| `compressionLevel` (`level`) | `6` | `0` stores the data uncompressed; `1`-`9` compress. |

## Common questions

### Is the output compatible with Python's zlib module?

Yes. `zlib.decompress(data)` reads it, and `zlib.compress(...)` output unmarshals here.

### Why is the name zip if it does not make a .zip file?

Apache Camel named it after `java.util.zip.Deflater`. Use [`zipFile`](https://pmsudhi.github.io/cameleer/docs/dataformats/zipfile.html) for archives.

## Related

- [GZip data format](https://pmsudhi.github.io/cameleer/docs/dataformats/gzip.html), [Zip File data format](https://pmsudhi.github.io/cameleer/docs/dataformats/zipfile.html)
- [Apache Camel Zip Deflater data format](https://camel.apache.org/components/next/dataformats/zipDeflater-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/dataformats/zipfile.html

# Zip File data format

> The `zipFile` data format packs the message body into a `.zip` archive (marshal) and unpacks entries from a `.zip` archive (unmarshal).

**Name:** `zipFile` · **Also:** `zipfile` · **Crate:** `cameleer-dataformats` (replaces the
single-entry version in `cameleer-core` when registered, as `cameleer_main::new_main` does) · **Cargo feature:** [`dataformats`](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) ·
**Apache Camel:** [Zip File](https://camel.apache.org/components/next/dataformats/zipFile-dataformat.html)

## When to use it

- Zip a file before uploading it to S3, FTP or email.
- Read the files inside an uploaded `.zip`, one by one, and route each entry.
- Bundle several generated documents (reports, invoices) into one archive.

## Marshal and unmarshal

| direction | body in | body out |
|---|---|---|
| `marshal` | any body: one entry named after the `CamelFileName` header (default: the exchange id). A map body makes one entry per key (name -> content). | zip bytes. `CamelFileName` gets a `.zip` suffix. |
| `unmarshal` | zip bytes with one entry | the entry content as bytes; `CamelFileName` is set to the entry name. An archive with more than one entry fails unless `usingIterator` is set. |
| `unmarshal` with `usingIterator: true` | zip bytes | a list with the content of every entry; the names are in the `CamelZipFileEntryNames` header |

Directory entries are skipped unless `allowEmptyDirectory: true`. Entry names keep only the file
name unless `preservePathElements: true`.

## Example

Zip a report and unzip it again. The file name travels in `CamelFileName`:

```yaml
- route:
    id: zipfile-round-trip
    from:
      uri: direct:zipfile-round-trip
      steps:
        - setHeader:
            name: CamelFileName
            constant: report.txt
        - marshal:
            zipFile: {}
        - setHeader:
            name: archive
            simple: "${header.CamelFileName}"
        - unmarshal:
            zipFile: {}
        - convertBodyTo:
            type: String
        - setBody:
            simple: "${header.archive} holds ${header.CamelFileName}: ${body}"
```

```text
Q3 revenue up 12%
```

```text
report.txt.zip holds report.txt: Q3 revenue up 12%
```

Build a multi-entry archive from a map, then list the entries with `usingIterator`:

```yaml
- route:
    id: zipfile-entries
    from:
      uri: direct:zipfile-entries
      steps:
        - unmarshal:
            json: {}
        - marshal:
            zipFile: {}
        - unmarshal:
            zipFile:
              usingIterator: true
        - setBody:
            simple: "${header.CamelZipFileEntryNames}"
```

```json
{"invoice-1.txt":"total 10","invoice-2.txt":"total 20"}
```

```json
["invoice-1.txt","invoice-2.txt"]
```

To route each entry on its own, follow the `usingIterator` unmarshal with a `split` over `${body}`.

## Rust DSL

```rust
b.from("direct:zipfile-rust")
    .set_header("CamelFileName", constant("data.csv"))
    .marshal(DataFormatDefinition::zip_file());
```

## Options

| option | default | description |
|---|---|---|
| `usingIterator` | `false` | Unmarshal all entries into a list (names in `CamelZipFileEntryNames`). |
| `allowEmptyDirectory` | `false` | Include directory entries when iterating. |
| `preservePathElements` | `false` | Keep directories in entry names (`a/b/c.txt`) instead of only `c.txt`. |
| `compressionLevel` (`level`) | `6` | `0` stores entries uncompressed; `1`-`9` compress. |

## Message headers

| header | direction | description |
|---|---|---|
| `CamelFileName` | in / out | Marshal: the entry name (and the archive name plus `.zip`). Unmarshal: set to the entry name. |
| `CamelZipFileEntryNames` | out | Unmarshal with `usingIterator`: the entry names, in archive order. |

## Common questions

### How do I unzip a file with several entries?

Use `unmarshal: {zipFile: {usingIterator: true}}` and then `split: {simple: "${body}"}`. The
names are in the `CamelZipFileEntryNames` header.

### How do I zip several files into one archive?

Put a map of `name -> content` in the body (for example by aggregating files into a map) and
`marshal: {zipFile: {}}`.

### Is this the same as zipDeflater?

No. [`zipDeflater`](https://pmsudhi.github.io/cameleer/docs/dataformats/zip-deflater.html) compresses one payload without any archive structure.

## Related

- [Tar File data format](https://pmsudhi.github.io/cameleer/docs/dataformats/tarfile.html), [GZip data format](https://pmsudhi.github.io/cameleer/docs/dataformats/gzip.html),
  [Zip Deflater data format](https://pmsudhi.github.io/cameleer/docs/dataformats/zip-deflater.html)
- [Apache Camel Zip File data format](https://camel.apache.org/components/next/dataformats/zipFile-dataformat.html)

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html

# Benchmarks: Apache Camel vs Cameleer

> Measured with the same routes on separate cloud machines, Cameleer starts in milliseconds
> instead of about a second, uses a fraction of Apache Camel's memory, and moves more messages
> per second on the same CPUs, in routing, REST APIs, Kafka, PostgreSQL and batch jobs.

This is the full report behind the
[Apache Camel vs Cameleer comparison](https://pmsudhi.github.io/cameleer/compare/apache-camel-vs-cameleer/).
It compares three runtimes on the same routes:

- **Cameleer** 0.4.0, the native Rust binary;
- **Apache Camel on the JVM**: Camel 4.23.0 on Java 21, the way most Camel runs today;
- **Apache Camel on Quarkus, native**: Camel 4.22.1 compiled ahead of time with Quarkus 3.40.0
  and Mandrel, the fastest-starting way to run Camel.

Every number below is generated from the raw results in
[`benchmarks/results/`](https://github.com/pmsudhi/cameleer/tree/main/benchmarks/results) by `scripts/cloud-bench/summarize.py`; none is
typed by hand. Each figure is the mean of two runs on two identical servers.

## Results

### Throughput (higher is better)

| scenario | Cameleer | Apache Camel (JVM) | Apache Camel (Quarkus native) | Cameleer vs Camel JVM | Cameleer vs Camel native |
|---|---:|---:|---:|---:|---:|
| Direct call through a route | 2,230,208 msg/s | 663,701 msg/s | 243,522 msg/s | 3.3x | 9.1x |
| In-memory queue (seda), one-way | 1,644,186 msg/s | 603,426 msg/s | 316,442 msg/s | 2.7x | 5.1x |
| In-memory queue (seda), request-reply | 719,433 msg/s | 117,442 msg/s | 72,113 msg/s | 6.1x | 9.9x |
| Content-based router | 1,144,857 msg/s | 375,212 msg/s | 119,416 msg/s | 3.0x | 9.5x |
| Split and aggregate a JSON order | 70,926 orders/s | 26,622 orders/s | 9,274 orders/s | 2.6x | 7.6x |
| CSV batch (1,000-row files) | 998 files/s | 468 files/s | 163 files/s | 2.1x | 6.1x |
| Kafka stream processing | 6,081 records/s | 698 records/s | 694 records/s | 8.7x | 8.7x |
| HTTP, fixed reply | 99,012 req/s | 56,735 req/s | 28,584 req/s | 1.7x | 3.4x |
| REST API with JSON | 80,367 req/s | 37,814 req/s | 17,860 req/s | 2.1x | 4.4x |
| HTTP into Kafka | 17,854 req/s | 10,052 req/s | 9,267 req/s | 1.7x | 1.9x |
| HTTP into PostgreSQL | 11,007 req/s | 4,710 req/s | 3,540 req/s | 2.3x | 3.1x |

### Latency, p99 (lower is better)

| scenario | Cameleer | Apache Camel (JVM) | Apache Camel (Quarkus native) |
|---|---:|---:|---:|
| Direct call through a route | 1 µs | 3 µs | 10 µs |
| In-memory queue (seda), request-reply | 38 µs | 85 µs | 137 µs |
| Content-based router | 2 µs | 6 µs | 22 µs |
| Split and aggregate a JSON order | 30 µs | 70 µs | 382 µs |
| CSV batch (1,000-row files) | 1.7 ms | 3.2 ms | 12.5 ms |
| HTTP, fixed reply | 2.9 ms | 3.8 ms | 7.4 ms |
| REST API with JSON | 2.6 ms | 6.3 ms | 12.3 ms |
| HTTP into Kafka | 8.6 ms | 7.8 ms | 12.6 ms |
| HTTP into PostgreSQL | 10.6 ms | 19.8 ms | 27.7 ms |

### Memory and CPU

| scenario | Cameleer: peak memory | Apache Camel (JVM): peak memory | Apache Camel (Quarkus native): peak memory | Cameleer: CPU | Apache Camel (JVM): CPU | Apache Camel (Quarkus native): CPU |
|---|---:|---:|---:|---:|---:|---:|
| Direct call through a route | 7 MB | 399 MB | 113 MB | - | - | - |
| In-memory queue (seda), one-way | 9 MB | 440 MB | 199 MB | - | - | - |
| In-memory queue (seda), request-reply | 9 MB | 257 MB | 113 MB | - | - | - |
| Content-based router | 7 MB | 332 MB | 113 MB | - | - | - |
| Split and aggregate a JSON order | 8 MB | 299 MB | 114 MB | - | - | - |
| CSV batch (1,000-row files) | 8 MB | 337 MB | 126 MB | - | - | - |
| Kafka stream processing | 36 MB | 214 MB | 130 MB | - | - | - |
| HTTP, fixed reply | 18 MB | 244 MB | 121 MB | 318% | 315% | 306% |
| REST API with JSON | 19 MB | 402 MB | 129 MB | 318% | 313% | 302% |
| HTTP into Kafka | 67 MB | 328 MB | 129 MB | 108% | 148% | 168% |
| HTTP into PostgreSQL | 25 MB | 273 MB | 133 MB | 80% | 176% | 208% |

### Startup

| | Cameleer | Apache Camel (JVM) | Apache Camel (Quarkus native) |
|---|---:|---:|---:|
| time to a started context | 2.5 ms | 1106.1 ms | 30.4 ms |
| memory at startup | 8 MB | 114 MB | 69 MB |


## What the results show

- **Startup.** Cameleer has its routes running in a few milliseconds. Apache Camel on the JVM takes
  about a second; compiled natively with Quarkus it takes tens of milliseconds.
- **Memory.** Cameleer runs these routes in tens of megabytes. Camel on the JVM uses hundreds;
  native Camel sits in between.
- **Throughput.** Cameleer handles more messages per second than Camel on the JVM in every
  scenario, and more than native Camel by a wider margin: native Camel has no JIT compiler, so
  it trades throughput for startup.
- **Latency.** Cameleer's p99 latency is lower in every scenario but one. In HTTP into Kafka it
  is slightly higher than Camel on the JVM (8.6 ms against 7.8 ms) while serving 1.7 times the
  requests: Cameleer batches the sends of concurrent requests, which raises the slowest
  requests' wait a little.

## The scenarios

The routes are defined once per runtime from one specification:
[`crates/cameleer-bench/src/scenarios.rs`](https://github.com/pmsudhi/cameleer/blob/main/crates/cameleer-bench/src/scenarios.rs) and
[`realworld.rs`](https://github.com/pmsudhi/cameleer/blob/main/crates/cameleer-bench/src/realworld.rs) for Cameleer,
[`Bench.java`](https://github.com/pmsudhi/cameleer/blob/main/benchmarks/java-camel/src/main/java/bench/Bench.java) for Apache Camel (the
Quarkus build compiles the same class from
[`benchmarks/camel-quarkus`](https://github.com/pmsudhi/cameleer/tree/main/benchmarks/camel-quarkus)).

| scenario | where it runs | what the route does |
|---|---|---|
| Direct call through a route | in process | `direct:` route that sets a header and counts the message |
| In-memory queue, one-way | in process | 4 producers into `seda:` with 4 concurrent consumers |
| In-memory queue, request-reply | in process | the same queue with a reply for every message |
| Content-based router | in process | `choice` on a header, `filter` on an amount, `transform` with Simple |
| Split and aggregate a JSON order | in process | `split` an order's 10 items by JSONPath and `aggregate` them back |
| CSV batch | in process | `split` a 1,000-row file into lines, keep the EU rows, reshape, aggregate batches of 100 |
| HTTP, fixed reply | over the network | `netty-http` consumer that answers with a constant JSON document |
| REST API with JSON | over the network | read `orderId` and `customer` with JSONPath, answer with a JSON confirmation |
| HTTP into Kafka | over the network | publish each order to Kafka keyed by order id, then answer |
| HTTP into PostgreSQL | over the network | insert each order with the `sql` component through a pool of 16 connections |
| Kafka stream processing | Kafka on the load machine | consume orders with 4 consumers, filter by amount, reshape, publish to another topic |
| Startup | in process | start a context with every in-process route and an HTTP route |

## How we tested

**Machines.** Three DigitalOcean CPU-optimized droplets (`c-4`) in region `blr1`: 4 dedicated
vCPUs (Intel Xeon Platinum 8168 at 2.7 GHz), 8 GB RAM, Ubuntu 24.04, on one private network. Two
of them are servers that take turns running each runtime; the third runs the HTTP load
generator, Apache Kafka 4.3.2 (KRaft, one broker, 4 partitions per topic) and PostgreSQL 16. All
three get the same kernel settings
([`scripts/cloud-bench/setup-node.sh`](https://github.com/pmsudhi/cameleer/blob/main/scripts/cloud-bench/setup-node.sh)).

**Runtimes.** Temurin 21.0.13 for Apache Camel 4.23.0, with no JVM flags. Camel Quarkus 3.40.0
(Apache Camel 4.22.1) compiled with Mandrel 25.0.4.1. Cameleer 0.4.0 built with Rust 1.99.1 in
release mode. Every download is pinned and checksum-verified.

**Method.**
- Each scenario runs in a fresh process: 15 s of warmup, then five timed 5-second iterations.
- The two servers swap roles halfway, so every runtime runs on both machines and each figure is
  the mean of the two. Only one runtime runs at a time.
- The HTTP scenarios use 64 concurrent keep-alive connections from the load machine; the load
  generator ([`loadgen.rs`](https://github.com/pmsudhi/cameleer/blob/main/crates/cameleer-bench/src/loadgen.rs)) is the same for every
  runtime and sends a different order id with every request.
- Default settings everywhere: no GC or thread-pool tuning on either side, and the same
  PostgreSQL pool size (16; HikariCP on the JVM, Agroal on Quarkus).
- Peak memory and CPU of each server process come from `/usr/bin/time`; startup is the time from
  spawning the process to its `READY` line, median of five.

**Reproduce it.** A run costs about one US dollar of cloud time:

```sh
export DO_TOKEN_FILE=~/do-token.txt     # a DigitalOcean API token
scripts/cloud-bench/droplets.sh up      # three c-4 droplets
scripts/cloud-bench/run.sh all          # build, fill Kafka, run every scenario
scripts/cloud-bench/droplets.sh down    # delete the droplets
```

See [`scripts/cloud-bench/README.md`](https://github.com/pmsudhi/cameleer/blob/main/scripts/cloud-bench/README.md).

## Results that need context

- **Kafka stream processing** waits for every record's acknowledgement (`acks=all`) before the
  next one, on every runtime: that is the default behaviour of both Camel's and Cameleer's Kafka
  producer. The ratio is fair; the absolute numbers are far below what Kafka can do with
  batching or asynchronous sends.
- **HTTP** is measured with one load machine of the same size as the server. It drives every
  runtime the same way, but the absolute requests per second are not a ceiling.
- **Apache Camel on Quarkus** runs Camel 4.22.1, one minor version behind the JVM side, because
  that is what the latest Camel Quarkus release ships.

## Bugs this benchmark found and fixed

Running real workloads on separate machines found three problems in Cameleer, fixed before the
numbers above were taken. Each fix has a regression test.

- **HTTP keep-alive.** The HTTP server had 32 worker threads and closed keep-alive connections
  when all were busy, so more than 32 concurrent clients reconnected on every request. The
  default is now 200 workers, started on demand.
- **Kafka producer.** Concurrent sends waited in line one record at a time. They are now batched
  into one produce request per broker, as Kafka's own producer does.
- **PostgreSQL pool.** `poolSize` only limited idle connections, so a burst opened extra
  connections. It is now a hard maximum, like HikariCP's, with callers waiting up to
  `poolTimeout`.

## FaaS cold start and size

Startup and size of the `cameleer` command itself, measured with `cameleer-bench coldstart`
(spawn to the `Routes startup` log line, 40 runs, medians) on Linux x86-64 (WSL2 Ubuntu 24.04 on
a Ryzen 5 5600X):

| build (Linux x86-64) | binary | HTTP route ready | run-once job done | memory, HTTP route |
|---|---:|---:|---:|---:|
| all components, glibc | 23.9 MB | 1.17 ms | 2.15 ms | 10.4 MB |
| `--features cloud`, static musl | 11.8 MB | 0.75 ms | 1.48 ms | 5.3 MB |
| `--features core`, static musl | 7.5 MB | 0.69 ms | 1.41 ms | 4.2 MB |

Container images (linux/amd64, distroless, compressed): about 20 MB with every component, 14.5 MB
with `FEATURES=cloud`, 12.5 MB with `FEATURES=core`. In AWS's `provided:al2023` image with the
Lambda Runtime Interface Emulator, init took 3.5–5.2 ms and warm invocations 0.7–1.3 ms. The
detailed measurements, the Windows numbers and the tuning history are in
[`benchmarks/local.md`](https://github.com/pmsudhi/cameleer/blob/main/benchmarks/local.md) and
[`benchmarks/analysis.md`](https://github.com/pmsudhi/cameleer/blob/main/benchmarks/analysis.md); the build options are in
[build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html).

## Found a problem?

If a number here doesn't match what you measure, please
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) with your setup and results, or
fork the repository, fix the harness, and open a pull request.

---

Source: https://pmsudhi.github.io/cameleer/docs/FEATURES.html

# Cameleer feature matrix

This page compares Cameleer with [Apache Camel 4](https://camel.apache.org/). It was written
by reading the code and the conformance test suite (`crates/cameleer-core/tests/conformance_*.rs`,
`crates/cameleer-http/tests/conformance_http.rs`), not from the wishlist.

Legend: ✅ implemented, ⚠️ partial (see notes), ❌ not implemented.

Cameleer uses only the Rust standard library, so anything that needs a database driver,
a broker client or a JVM library is out of scope unless it can be written from scratch. TLS is
provided by the from-scratch `cameleer-tls` crate and is wired into every network component
(see "TLS / SSL context parameters" below).

## Interop verified against real servers

Besides the embedded test servers, these components are verified end-to-end against real,
independent server software by the opt-in live suite (`CAMEL_LIVE_INTEROP=1`, servers set up by
`scripts/live-interop.sh`); details, broker limitations and the bugs it found are in
[INTEROP.md](https://pmsudhi.github.io/cameleer/docs/INTEROP.html). The emulator-only areas (embedded Kafka broker and datastores, the
AWS / Azure / GCP mocks, the Azure flavour of the AMQP 1.0 broker) and the TLS, HTTP/2 and gRPC
stacks are additionally driven by officially published clients (librdkafka, pymongo, the
DataStax driver, elasticsearch-py, redis-py, boto3, the Azure SDK for Python, gcloud / gsutil /
bq, grpcio, Go's crypto/tls and net/http) in the opt-in `CAMEL_OFFICIAL_CLIENTS=1` suite
(`scripts/official-clients.sh`); see "Official clients" in [INTEROP.md](https://pmsudhi.github.io/cameleer/docs/INTEROP.html).

| Components | Interop verified against |
|---|---|
| `sql`, `jdbc`, `sql-stored`, JDBC idempotent / aggregation repositories, transactions | PostgreSQL 16.15 (SCRAM-SHA-256, `sslmode=verify-full`, PL/pgSQL) |
| `spring-redis` (producer, pub/sub consumer), Redis idempotent / aggregation repositories | Redis 7.0.15 (AUTH, RESP3, TLS) |
| `paho`, `paho-mqtt5` | Eclipse Mosquitto 2.0.18 (QoS 0/1/2, retained, wildcards, credentials, TLS, persistent sessions); RabbitMQ 3.12 MQTT plugin |
| `spring-rabbitmq`, `rabbitmq` | RabbitMQ 3.12.1 (exchanges, ack/reject, DLX, request/reply, confirms, AMQPS) |
| `stomp`, `jms`, `activemq` | RabbitMQ 3.12.1 STOMP plugin (queues, topics, temp-queue request/reply, transactions, durable subscriptions, TLS) |
| `amqp` (AMQP 1.0) | RabbitMQ 3.12.1 AMQP 1.0 plugin (queues, topics, request/reply, client ack, AMQPS) |
| `ftp`, `ftps` | vsftpd 3.0.5 (passive/active, explicit/implicit FTPS, `require_ssl_reuse=YES`) |
| `smtp`/`smtps`, `imap`/`imaps`, `pop3`/`pop3s` | Postfix 3.8.6 + Dovecot 2.3.21 (STARTTLS/STLS, implicit TLS, SASL, attachments) |
| `http`/`https` producer | nginx 1.24.0 (HTTP/1.1, gzip, keep-alive, HTTPS, HTTP/2 via ALPN, h2c); OpenJDK 21 JSSE `HttpsServer` (TLS 1.3 / 1.2) |
| `jetty:https` consumer | OpenJDK 21 `java.net.http.HttpClient` |
| `stomp`, `jms`, `activemq` | Apache ActiveMQ 5.17.6 STOMP (JMS selectors, temp-queue request/reply, durable subscriptions, transactions with redelivery and DLQ, priority / TTL, persistent / non-persistent, map / object messages, virtual topics, authentication, STOMP+SSL) |
| `paho` | Apache ActiveMQ 5.17.6 MQTT (QoS 0/1/2, retained, wildcards, persistent sessions, authentication, TLS, MQTT ↔ STOMP bridging) |
| `amqp` (AMQP 1.0) | Apache ActiveMQ 5.17.6 AMQP transport (`queue://` / `topic://` prefixed addressing, topic fan-out, JMS selectors, AMQP transactions with redelivery, dynamic reply queues, durable subscriptions, JMS mapping through the JMS transformer, multi-frame messages, SASL PLAIN, AMQPS; shared subscriptions refused) |

### Third-party simulators

Cloud services, Kafka and MongoDB are additionally verified against independent simulators run
locally by the opt-in `CAMEL_SIMULATORS=1` suite (`scripts/simulators.sh`); see "Third-party
simulators" in [INTEROP.md](https://pmsudhi.github.io/cameleer/docs/INTEROP.html) for what passed, the bugs it found and what could not run
(Elasticsearch / OpenSearch, Cassandra, real Kafka, LocalStack, Cosmos DB / Service Bus and the
gcloud emulators).

| Components | Verified against |
|---|---|
| AWS: `aws2-s3`, `aws2-sqs`, `aws2-sns`, `aws2-ddb`, `aws2-ddbstream`, `aws2-kinesis`, `aws2-kinesis-firehose`, `aws2-eventbridge`, `aws-secrets-manager`, `aws2-kms`, `aws2-sts`, `aws2-iam`, `aws2-ec2`, `aws2-cw`, `aws2-ses`, `aws2-step-functions`, `aws2-lambda` (management), `aws2-athena` | moto 5.2.5 (incl. IAM-enforced SigV4, HTTPS) |
| `azure-storage-blob`, `azure-storage-queue` | Azurite 3.37.0 (Shared Key, account / service SAS, HTTPS) |
| `google-storage` | fake-gcs-server 1.53.1 (HTTP, HTTPS) |
| `google-pubsub` streaming-pull consumer | pstest (cloud.google.com/go/pubsub 1.50.1) |
| `mongodb`, `mongodb-gridfs` | FerretDB 1.24.2 on PostgreSQL 16 (SCRAM, TLS) |
| `kafka` | franz-go kfake, 3 brokers (groups, SASL PLAIN / SCRAM, TLS) |

## Core concepts

| Feature | Status | Notes |
|---|---|---|
| CamelContext lifecycle (start/stop/restart) | ✅ | Routes start by `startupOrder` and stop in reverse order. Default shutdown timeout is 45 s (`set_shutdown_timeout`). |
| Graceful shutdown | ✅ | Waits for in-flight exchanges. Exchanges still queued on a seda consumer are completed first unless `purgeWhenStopping=true`. |
| Adding/removing routes at runtime | ✅ | Routes added after start begin at once. `remove_route` returns `false` until the route is stopped, as in Camel. |
| Route ids, auto-generated ids (`route1`...) | ✅ | |
| `autoStartup`, `startupOrder`, route groups/descriptions | ✅ | |
| Suspend/resume | ✅ | `SuspendableService` (`Service::as_suspendable`): the seda, timer, scheduler, file, cron/quartz and platform-http consumers are suspended in place — seda leaves messages queued, timer/scheduler/cron skip fires, the file consumer skips polls, HTTP answers `503 Service Unavailable` — and in-flight exchanges complete; other consumers are stopped (as Camel does for non-suspendable consumers). `suspend_route`/`resume_route` (`start_route` resumes a suspended route), context-level `suspend()`/`resume()`, `RouteSuspended`/`RouteResumed`/`ContextSuspended`/`ContextResumed` events, `is_route_suspended_in_place`. |
| Exchange / Message / headers | ✅ | Headers are case-insensitive and keep the original key spelling. |
| Exchange patterns InOnly/InOut, `inOnly()`/`inOut()`/`setExchangePattern` | ✅ | |
| Exchange properties, variables (`setVariable`, `${variable.x}`) | ✅ | Variables are stored as exchange properties (`CamelVariable.<name>`), not in a separate variable repository. |
| `Exchange.correlated_copy` (`CamelCorrelationId`) | ✅ | |
| Type conversion (`convertBodyTo`, `bodyAs`) | ✅ | `cameleer_core::typeconverter`: a per-context `TypeConverterRegistry` (`ctx.type_converter()`) used by `convertBodyTo`/`convertHeaderTo`, Simple `bodyAs`/`headerAs`/`mandatoryBodyAs` and languages' `resultType`. Custom converters per (from, to) type (`add_converter`, `Object` = any source), fallback converters, `TypeConverterExists` policy (Override/Ignore/Fail), statistics (attempts/hits/misses/failures). Built-in conversions modelled on Camel's core converters: String (charset from `CamelCharsetName`), Character, Integer/Short/Byte (range checked), Long/BigInteger, Double/Float/BigDecimal/Number, Boolean, byte[]/InputStream/ByteBuffer, Map (JSON, `Properties` text), List/Collection/Iterator/Set/Object[]/String[], Date/Timestamp/Calendar (epoch millis), Instant/OffsetDateTime/ZonedDateTime/LocalDate/LocalDateTime/LocalTime, Duration (ISO-8601 or `1m30s`), UUID, URI/URL/File/Path, Reader/XML Document/Source (text), JsonNode. Values stay dynamic `Value`s, so a "type" is a name (`com.acme.Order` keys custom converters). |
| Unit of work, on-completion synchronizations | ✅ | `useOriginalMessage` follows Camel's unit-of-work scope: it spans direct/seda routes, and split/multicast/recipientList start a child unit of work unless `shareUnitOfWork`. |
| Property placeholders `{{key}}`, `{{key:default}}`, `{{env:X}}` | ✅ | Resolved in uris, endpoint options and Simple expressions when the route is created. |
| Registry / beans | ✅ | A typed registry (`bind`, `lookup`, processors, aggregation strategies, bean methods). |
| Event notifiers | ✅ | Context, route and exchange events. |
| Endpoint uri normalization | ✅ | Like Camel's `URISupport.normalizeUri`: `Endpoint::uri()`, route endpoints, `CamelToEndpoint`, `CamelRecipientListEndpoint`, `CamelSlipEndpoint`, `CamelFailureEndpoint`, `CamelInterceptedEndpoint` and endpoint errors use `scheme://path?sorted-params` (`mock://result`, `seda://foo?blockWhenFull=true&size=10`, values encoded like `URLEncoder`). Lookups and `interceptSendToEndpoint` patterns work with either form. `RAW(...)` values are shown encoded rather than as `RAW(...)`. |
| Value predicate truthiness | ✅ | `ObjectHelper.evaluateValuePredicate` (`Value::is_predicate_true`): a boolean is its value, a string is false only for `"false"` (trimmed, any case), an array is true when not empty, null is false and anything else (`0`, `""`, maps, bytes) is true. Used by Simple, `header`/`constant`/... languages used as predicates and JSONPath. |
| SSL context parameters (`SSLContextParameters`) | ✅ | `cameleer_tls::SslContextParameters`: key and trust stores as PEM (combined or separate certificate/key files, `ENCRYPTED PRIVATE KEY` with PBES2 or PKCS#12 PBE), PKCS#12 (`.p12`/`.pfx`: PBES2/PBKDF2-HMAC-SHA1/256 + AES-128/256-CBC, legacy 3DES and RC2-40, HMAC-SHA1/256 MAC), Java JKS and JCEKS (format detected or `keyStoreType`/`trustStoreType`; `keystorePassword`, `keyPassword`, `certAlias`, `trustStorePassword`), optional system trust store, `insecure_skip_verify`, host name verification switch, ALPN, min/max TLS version, SNI override, client authentication (`clientAuthentication=NONE\|WANT\|REQUIRE`, also `serverParameters.clientAuthentication`; the client presents its key store when asked), CRL files (`crlFile`), session resumption (`sessionResumption`, `sessionTimeout`). Bind as a bean and reference with `sslContextParameters=#name` (also `camel.component.<scheme>.sslContextParameters`), or configure the global parameters with `camel.ssl.*` properties (`camel.ssl.enabled=true`, `keyStore`/`certFile`+`keyFile`, `keystorePassword`, `keyPassword`, `keyStoreType`, `certAlias`, `trustStore`, `trustStorePassword`, `trustStoreType`, `trustAllCertificates`, `hostnameVerification`, `secureSocketProtocol(s)`, `clientAuthentication`, `crlFile`, `sessionTimeout`) or the bean `CamelGlobalSSLContextParameters`, used with `useGlobalSslContextParameters=true` and as the default trust for TLS endpoints when `camel.ssl.enabled=true`. Embedded HTTP server: `camel.server.ssl.*` / `camel.server.sslEnabled` / `camel.server.useGlobalSslContextParameters`. TLS failures are `SSLHandshakeException`/`SSLPeerUnverifiedException` (subclasses of `IOException`). Not supported: OCSP, JCEKS secret-key entries, PKCS#12 public-key integrity/privacy modes, key managers selecting among several key entries by SNI. |

## Enterprise Integration Patterns

| EIP | Status | Notes |
|---|---|---|
| Pipeline, `to`, `toD` (Simple uri), `step` | ✅ | |
| Message Filter (+ `CamelFilterMatched`) | ✅ | |
| Content-Based Router (`choice/when/otherwise`, `endChoice`, nested) | ✅ | A choice with no `otherwise` continues after the choice. |
| Splitter (tokenize, arrays, delimiter, streaming, parallel, timeout, stopOnException, shareUnitOfWork, aggregation strategy) | ✅ | Without a strategy the original message continues. `stop()` in a split part stops only that part. Sequential `streaming` is lazy: a string body is split one part at a time and sub-exchanges are created on demand; `CamelSplitSize` is set on the last part only, as in Camel. The tokenize language itself still returns all tokens at once. |
| Aggregator (completionSize/Timeout/Interval/Predicate/FromBatchConsumer/OnNewCorrelationGroup, eager check, forceCompletionOnStop, discardOnCompletionTimeout, closeCorrelationKeyOnCompletion, custom repository) | ✅ | `completionTimeout` is an inactivity timeout. `CamelAggregatedCompletedBy` takes the values `size`, `timeout`, `predicate`, `interval`, `force`... Repositories are in memory only (no JDBC/LevelDB). |
| Multicast (parallel, strategy, stopOnException, timeout) | ✅ | Without a strategy the last reply wins, as in Camel. |
| Recipient List (delimiter, ignoreInvalidEndpoints, parallel, strategy) | ✅ | |
| Routing Slip, Dynamic Router | ✅ | |
| Wire Tap (copy, `newExchangeBody/Header`, `onPrepare`) | ✅ | Asynchronous, on a separate exchange. |
| Content Enricher `enrich` / `pollEnrich` (strategy, timeout, aggregateOnException, dynamic uri) | ✅ | |
| Loop (count, `doWhile`, `copy`) | ✅ | |
| Idempotent Consumer (eager, skipDuplicate, removeOnFailure, completionEager) | ✅ | Memory LRU repository only. Duplicates skip only the idempotent block, as in Camel. |
| Load Balancer (round robin, random, sticky, weighted, topic, failover, custom) | ✅ | |
| Resequencer (batch, stream) | ✅ | |
| Sort, Claim Check, Sampling, Delay, Throttle (incl. correlated) | ✅ | `asyncDelayed` (default true for delay, false for throttle, as in Camel; `sync_delayed()`) releases the consumer thread of asynchronous consumers (seda, timer) while the exchange waits, see `cameleer_core::async_delay`. Synchronous callers (direct, `ProducerTemplate`) still wait. |
| Validate | ✅ | Throws `PredicateValidationException`. |
| Circuit Breaker (`onFallback`) | ✅ | A resilience4j-style state machine built in. No Resilience4j/MicroProfile integrations. |
| Stop, Rollback, markRollbackOnly(Last), throwException | ✅ | `throwException` messages are Simple expressions. |
| Threads, Policy, Transacted | ✅ | **Threads**: `threads(n)`/`threads_with(ThreadsOptions)`/YAML `threads` with `poolSize`, `maxPoolSize`, `keepAliveTime` (+`timeUnit`), `maxQueueSize` (0 = hand-off, -1 = unbounded), `allowCoreThreadTimeOut`, `rejectedPolicy` (Abort, CallerRuns, Discard, DiscardOldest), `callerRunsWhenRejected`, `threadName`, `executorService` (shared `BoundedThreadPool` or `ThreadPoolProfile` bean) on `executor::BoundedThreadPool` (ThreadPoolExecutor semantics, Camel's default profile). **Policy**: `policy(Arc<dyn Policy>)`/`policy_ref` (also resolves `TransactionPolicy` beans). **Transacted**: `cameleer_core::transaction` — `TransactionManager` SPI (begin/commit/rollback, savepoints, suspend/resume; `FnTransactionManager`), `TransactionPolicy` with propagation REQUIRED, REQUIRES_NEW, MANDATORY, SUPPORTS, NOT_SUPPORTED, NEVER, NESTED, isolation/timeout/read-only, `TransactionSynchronization` callbacks, `TransactionPolicy::execute` (TransactionTemplate). `transacted()`/`transacted_ref(name)`/YAML `transacted` wrap the rest of the route and resolve the policy as Camel does (bean named `PROPAGATION_REQUIRED`, single policy, `PROPAGATION_*` names, `transactionManager` bean); exceptions and `markRollbackOnly` roll back, participating scopes mark the shared transaction rollback-only, `markRollbackOnlyLast` rolls back only the innermost one. Transactions are thread-bound like Spring's (synchronous `direct:` calls join). |
| Route Policy | ✅ | |
| Intercept, interceptFrom, interceptSendToEndpoint (skip, afterUri, onWhen) | ✅ | |
| Process / bean / method | ✅ | Processors are closures or registry beans. There is no reflection-based bean binding. |
| Kamelets, Pipes / KameletBindings | ✅ | `cameleer-yaml::kamelet`: YAML Kamelets (`spec.definition.properties`, `required`, defaults, `spec.template`/`spec.flow`, `spec.dataTypes`), `kamelet:name?prop=x` as source (`from`) and sink/action (`to`), `{{prop}}`/`{{?prop}}` from uri parameters, `camel.kamelet.<name>[.<routeId>].<prop>` properties and defaults, `add_kamelet`, `load_kamelets_from_dir`, built-in `timer-source`, `log-sink`, `log-action`, `insert-header-action`, `set-body-action`. Template local beans (`spec.template.beans`, created per Kamelet route with the registered bean factories, `{{beanName}}` resolves to the route's bean). Pipes/KameletBindings become routes: Kamelet refs, uris and non-Kamelet refs (Strimzi `KafkaTopic` → `kafka:`, Knative `Channel`/`Broker` → in-process `vm:` channels, Kubernetes `Service` → `http://`, `Endpoint`, custom kinds via `register_pipe_ref_resolver`); endpoint `dataTypes` (`in`/`out` `format`, validated against the Kamelet's declared types, applied with `transformDataType` + `Content-Type`); `spec.errorHandler` `sink` (dead letter channel with redelivery parameters), `log`, `none`. cameleer-main loads Kamelets from `camel.main.kamelet-locations` (default `classpath:kamelets` = `./kamelets`; remote `github:` locations are skipped since there is no network access). |
| Saga (`saga()`: propagation REQUIRED/REQUIRES_NEW/MANDATORY/SUPPORTS/NOT_SUPPORTED/NEVER, completionMode AUTO/MANUAL, timeout, compensation/completion endpoints, options, `saga:complete`/`saga:compensate`) | ✅ | `processor::saga`. `CamelSagaService` trait; `InMemorySagaService` (default; compensation/completion endpoints called in reverse step order with the options and `Long-Running-Action` as headers, retried `maxRetryAttempts` times; timeout compensates a still running saga) and `LraSagaService` (Narayana-LRA compatible REST client: `start`, join with `Link`, `close`/`cancel`, embedded participant HTTP server; `lra::testing::MockLraCoordinator`). Plain `http://` coordinators only (no TLS), not durable. Rust DSL `saga().propagation(..).completion_mode(..).saga_timeout(..).compensation(uri).completion(uri).option(k, e)`; YAML `saga`. |
| Transformer / Validator (data types), `transformDataType` | ✅ | `processor::transformer`: `ctx.add_transformer(from, to, t)` (`json:Order`, `xml:Order`, `java:...` urns; `from = None` = any), `add_scheme_transformer`, `add_named_transformer`, `add_validator`; `data_format_transformer`, `endpoint_transformer`, `processor_transformer`, `predicate_validator`, `endpoint_validator`. Route `input_type(urn, validate)`/`output_type(urn, validate)` (YAML `inputType`/`outputType` `{urn, validate}`): the message data type (property `CamelMessageDataType`) is transformed automatically when it reaches a route declaring another type (e.g. `to("direct:x")`), with one-hop transformer chains; `ValidationException` on validation failure or missing validator, `IllegalArgumentException` when no transformer exists. Built-in data type transformers `text-plain`, `application-json`, `application-octet-stream`, `application-x-struct`. No Pipe/Kamelet data types, no transformers declared in YAML. |
| Service Call | ✅ | `service_call("name[/path]")` with static (`[name@]host:port,...`), custom or registry service discovery, healthy/blacklist/pass-through/custom filters, round-robin or random load balancer, `uri` template (`{host}`, `{port}`, `{name}`, `{path}`, or the service name replaced by `host:port`), `expression`, default `http://host:port/path`; `CamelServiceCall*` headers. YAML `serviceCall`. No DNS-SRV/Consul/Kubernetes discovery. |
| Script | ✅ | Rust DSL `.script(expr)` and YAML `script`: any registered language (simple, constant, jq, jsonpath, xpath, ...); the result is discarded. With `cameleer-script`, the YAML `script` step also runs `groovy`, `js`, `python`, `java`/`joor`, `mvel`... scripts as processors whose changes to the message, headers, properties and variables are kept. |
| Poll (Camel 4), Kamelet EIP, `removeVariables` | ✅ | `.poll(uri, timeout_ms)` / YAML `poll` (default timeout 20s, dynamic uri with `${..}`); `.kamelet("name?p=v")` / YAML `kamelet` (sends to `kamelet:`, component from `cameleer-yaml`); Rust DSL `.remove_variables(pattern)`. |
| Route templates | ✅ | Rust DSL (`add_route_template`, `TemplatedRouteBuilder`) and YAML/XML (`routeTemplate`, `templatedRoute`, `{{param:default}}`, `prefixId`, template beans via registered bean factories). Kamelets: see above. |
| Message history, tracer, route supervising | ✅ | `set_message_history` (also printed in the exhausted-failure log), `set_tracing` + backlog tracer, supervising route controller with back-off. |

## Error handling

| Feature | Status | Notes |
|---|---|---|
| DefaultErrorHandler, DeadLetterChannel, NoErrorHandler | ✅ | Redelivery headers `CamelRedelivered`, `CamelRedeliveryCounter` and `CamelRedeliveryMaxCounter`. Redelivery happens at the point of failure. |
| Redelivery policy (delay, back-off, collision avoidance, delayPattern, max delay, retryWhile, onRedelivery, onExceptionOccurred, onPrepareFailure, log levels, asyncDelayedRedelivery) | ✅ | With `asyncDelayedRedelivery` (Rust DSL and YAML `redeliveryPolicy`) the consumer thread of asynchronous consumers (seda, timer) is released during the delay: a replacement consumer thread takes over and the waiting exchange finishes on the released thread (Cameleer processors are synchronous, so this is a thread hand-off rather than a scheduler continuation). Otherwise, and for synchronous callers, the delay blocks the calling thread. |
| `onException` (hierarchy matching, cause chain, onWhen, handled, continued, useOriginalMessage/Body, route, builder and route configuration scope) | ✅ | Exception "classes" are string kinds with a registered parent hierarchy (`register_kind_parent`). Route configurations for Rust DSL routes: `ctx.add_route_configuration(Some("id") / None, \|c\| ...)` with `on_exception`, `on_completion`, `intercept*` and `error_handler`, selected with `route_configuration_id("a,b*")`; a configuration without id applies to every route that names none (context-wide `onException`). |
| Error handler scope across direct sub-routes | ✅ | The failing route's error handler applies. A handled exchange stops the caller too (`CamelErrorHandlerHandled`). An exhausted exchange is not redelivered again by the caller. |
| deadLetterHandleNewException | ✅ | |
| doTry / doCatch (onWhen) / doFinally | ✅ | No error-handler redelivery inside doTry. |
| onCompletion (onCompleteOnly, onFailureOnly, onWhen, mode before/after consumer, route/global scope) | ✅ | |
| ProducerTemplate failures | ✅ | Returned as `CamelExecutionException` with the original exception as the cause. |

## Languages

| Language | Status | Notes |
|---|---|---|
| Simple | ✅ | Operators (`==`, `=~`, `!=`, `>`..., `contains`, `~~`, `regex`, `in`, `range`, `is`, `startsWith`, `endsWith`, `&&`, `||`), ternary, elvis, OGNL navigation and method calls, `bodyAs`/`headerAs`, `date`/`date-with-timezone`, `properties`, `env`/`sys`, `file:*` functions, string/math/collection functions, `jsonpath`/`jq`/`xpath` inline, `bean`, `ref`. `${bodyType}` returns the Java class name Camel would report (`java.lang.String`, `java.lang.Integer`/`Long`, `java.lang.Double`, `java.lang.Boolean`, `byte[]`, `java.util.ArrayList`, `java.util.LinkedHashMap`). `${type:org.apache.camel.Exchange.FILE_NAME}` gives the `Exchange` constants (and `java.lang.Integer/Long.MIN_VALUE/MAX_VALUE`, `Boolean.TRUE/FALSE`). `${messageHistory}` / `${messageHistory(false)}`. `date-with-timezone` accepts region ids (`Europe/Paris`); `${date:...}` uses the default time zone (`TZ`). |
| Constant, Header, ExchangeProperty, Variable, Ref, Bean/Method | ✅ | |
| Tokenize (token, regex, pair, xml) | ✅ | |
| JSONPath | ✅ | A built-in implementation (Jayway-style syntax). |
| XPath | ✅ | `cameleer-xml` (registered by `cameleer-main`; cameleer-core alone keeps a small subset): complete, namespace-aware XPath 1.0 — all 13 axes, node tests, positional predicates, unions, variables and the 27 core functions — over a full XML 1.0 parser (namespaces, DTD internal subset entities and attribute defaults, CDATA, PIs, comments, UTF-8 / ISO-8859-1 / UTF-16, XXE and entity-expansion protection). `resultType` `String` (trimmed unless `trim=false`) / `nodeset` / `node` / `number` / `Integer` / `boolean`, `namespace` prefix bindings (`p=uri,...`, JSON, YAML `[{key, value}]`, Rust DSL `cameleer_xml::xpath_ns`), `headerName`/`source`, `saxon=false` (`saxon=true` fails: no XPath 2.0). Camel functions `in:body()`, `in:header()`, `out:*`, `function:properties()`, `function:simple()` and variables `$header` (header, property, variable), `$env:X`, `$system:X`. Unprefixed names match no-namespace nodes only, as in JAXP. |
| XQuery | ✅ | `cameleer-xml` (`xquery` module): XQuery 1.0 main modules without schema support, plus common 3.x conveniences. Prolog (`declare namespace`, default element/function namespace, `declare variable ... [external [:= default]]`, recursive `declare function local:f($a as T) as T`, boundary-space, default order), FLWOR (`for ... at`, `let`, `where`, `[stable] order by ... descending empty greatest`, 3.0 `group by` / `count`), `some`/`every`, `if`, `typeswitch`, 3.0 `try`/`catch`, the XPath 2.0 expression language on the cameleer-xml DOM (sequences, `to`, general/value/node comparisons, integer/decimal/double arithmetic with `div`/`idiv`/`mod`, `union`/`intersect`/`except`, `instance of`/`treat as`/`castable as`/`cast as` for `xs:string`, `integer` (+ subtypes), `decimal`, `double`, `float`, `boolean`, `date`, `dateTime`, `time`, `anyURI`, `untypedAtomic`; all 13 axes, wildcards and kind tests, predicates), 3.x `||` and `!`, direct and computed element/attribute/text/comment/PI/document constructors, ~90 F&O functions (strings, regex `matches`/`replace`/`tokenize` via the built-in engine, aggregates, sequences, `doc()` for local files, `current-dateTime`, date accessors, `deep-equal`, `serialize`, `parse-xml`, `math:*`...). `xquery` language (`resultType` DOM (default, serialized XML) / String / List / Node / Bytes / Integer / Double / Boolean, `namespace(s)`, `headerName`/`source`, `stripsAllWhiteSpace`) and `xquery:` component (`xquery:file:q.xq?resultsFormat=DOM|String|Bytes|List`, `classpath:`/`ref:`, `contentCache`, `namespacePrefixes`; Saxon `configuration*`/`staticQueryContext`/`moduleURIResolver`/`parameters`/`properties` accepted and ignored). External variables as in camel-saxon: `$in.body`, `$in.headers.NAME`, `$NAME` (exchange property, then header, then variable); declared atomic types cast string values, declared node types parse XML. XQuery 3.1 maps (`map{}`, `map:*`), arrays (`[]`, `array{}`, `array:*`), lookups (`?key`, `?*`), inline functions, named function references (`f#1`), dynamic calls, partial application, `=>`, `for-each`/`filter`/`fold-left`/`fold-right`/`for-each-pair`/`sort`/`apply`/`function-lookup`; library modules (`module namespace`, `import module ... at` relative to the query file, or `register_module`); arbitrary-precision `xs:decimal`; date/time/duration arithmetic (`dateTime - dateTime`, `date + yearMonthDuration`, `duration * n`, `duration div duration`), duration accessors, `adjust-*-to-timezone`, `dateTime()`; Update Facility basics (`insert`/`delete`/`replace [value of]`/`rename node`, `copy ... modify ... return`; an updating query returns the updated document). Not implemented: schema import/validation and user-defined types, full-text, XQuery consumer. |
| jq | ✅ | `language::jq`: the jq 1.7 language — full grammar (paths, slices, optional `?`, pipes, comma, alternative `//`, arithmetic, comparisons, all assignment operators, object/array construction, string interpolation and `@format` strings, `if/elif/else`, `try/catch`, `reduce`, `foreach`, `label/break`, variables and destructuring with `?//`, function definitions with filter/`$` parameters and recursion, `$__loc__`, `$ENV`) and the builtins of the jq 1.7 manual (paths, `getpath/setpath/delpaths/pick`, `to_entries/with_entries`, math, `sort_by/group_by/unique_by/min_by/max_by`, strings, regex `test/match/capture/scan/splits/sub/gsub` with jq flags, `@base32d` and the other formats, dates `strftime/strptime/mktime/gmtime/todate/fromdate`, streaming `tostream/fromstream/truncate_stream`, `limit/first/last/nth/until/while/repeat/combinations/walk`, `ltrimstr/rtrimstr/trim`, `abs`, `toarray` ...) plus camel-jq's `header()`, `property()`, `variable()`. Modules (`import`/`include`) and `input`/`inputs` streams are not applicable to one exchange. |
| File language | ✅ | Available in file component options and as Simple `${file:...}` functions. |
| JavaScript (`js`, `javascript`) | ✅ | `cameleer-script`: built-in tree-walking interpreter (no GraalJS), evaluated on the caller's thread (deep recursion continues on an extra stack segment; call depth limit 900, `RangeError` beyond). ES5.1 plus ES2015-2023 as used in route scripts: `var`/`let`/`const`, functions, closures, arrow functions, default/rest parameters, spread, destructuring, template literals and tagged templates (`strings.raw`, `String.raw`), classes (`extends`/`super`, static members, getters/setters, private `#fields`, computed and `[Symbol.iterator]` members), object-literal and `Object.defineProperty` accessors, prototypes, `this`/`call`/`apply`/`bind`, optional chaining, `??`, optional catch binding, labels, `switch`, `try`/`catch`/`finally`, generators (`function*`, `yield`, `yield*`, `next`/`return`/`throw`), iterators and `for...of` over any iterable, `Promise` (`then`/`catch`/`finally`, `all`/`allSettled`/`race`/`any`), `async`/`await` with a microtask queue and virtual-time `setTimeout`/`setInterval`/`queueMicrotask` (all drained before the result is returned), async generators whose `await`s suspend through the microtask queue (`next()` returns promises, requests are queued) and `for await` (async iterables, `Symbol.asyncIterator`, sync iterables of promises), `Map`/`Set`/`WeakMap`/`WeakSet`, `Symbol` (`Symbol.for`, `description`, well-known symbols), `Proxy` (`get`/`set`/`has`/`deleteProperty`/`ownKeys`/`apply`/`construct` traps, `Proxy.revocable`) and `Reflect` (`get`/`set`/`has`/`ownKeys`/`apply`/`construct`/`defineProperty`/`deleteProperty`/`getPrototypeOf`...), `BigInt` (literals `10n`/`0xffn`, arithmetic, comparisons, bitwise ops, `BigInt.asIntN`/`asUintN`, mixing errors), `ArrayBuffer`, typed arrays (`Int8`...`Float64Array`, `BigInt64Array`/`BigUint64Array`, `Uint8ClampedArray`; shared buffers, `subarray`/`slice`/`set`/`fill`/`sort`/`map`/`filter`/`from`/`of` and the read-only array methods; `Uint8Array` results become byte bodies) and `DataView` (all getters/setters, endianness), `TextEncoder`/`TextDecoder`, `Intl` for en-US, en-GB, de-DE and fr-FR (`NumberFormat` decimal/currency/percent/unit/compact, fraction and significant digits, grouping, `formatToParts`; `DateTimeFormat` dateStyle/timeStyle and component options, `timeZone` via `cameleer_core::tz`; `toLocaleString`/`toLocaleDateString`/`toLocaleTimeString`; `PluralRules`, `Collator` (accents, `numeric`), `ListFormat`, `RelativeTimeFormat`), `globalThis`, `structuredClone` (cycles, `Map`/`Set`/`Date`/typed arrays, `DataCloneError` for functions), regular expressions via the built-in engine (named groups `(?<name>)` with `match.groups`, `$<name>` replacements and replacer `groups` argument, lookbehind, `index`/`input` on matches, `matchAll`, global `exec` with `lastIndex`), ES modules (`import`/`export` incl. default, namespace, renamed, `export * from`, JSON modules, dynamic `import()`; paths relative to the importing module, the script (`scriptDir` option), the working directory or `classpath:`; modules are evaluated once per evaluation). Builtins: `Math`, `JSON`, `Object` (incl. `fromEntries`), `Array`, `String`, `Number`, `Date` (UTC), `parseInt`/`parseFloat`/`isNaN`, URI functions, `console`, `Java.type` for safe JDK classes (`java.lang.Integer`/`Long`/`Double`/`Boolean`/`String`/`Math`, `java.util.ArrayList`/`HashMap`/`LinkedHashMap`/`HashSet`/...; others are refused). Bindings: `exchange` (Java-like accessors `getIn()`, `getMessage()`, `getBody()`, `getHeader()`, `setHeader()`, `getProperty()`, `setProperty()`, `getVariable()`...), `request`/`message`, `body`, `headers`, `properties`/`exchangeProperties`, `variables`, `camelContext`, `log`. Out of scope by design: Node/browser host APIs (`fs`, `require`, `fetch`, DOM), `SharedArrayBuffer`/`Atomics`, WebAssembly, `Temporal`, `Intl` locales other than the four listed (they fall back to en-US formatting), and JVM interop beyond the `Java.type` classes listed. |
| Groovy | ✅ | `cameleer-script` interpreter for Groovy as used in route scripts: `def`/typed declarations, methods, closures (`it`, trailing closures, `delegate` in `with`), GStrings, `?.`, `?:`, `*.`, GPath (`list.name`), list/map literals, spread map entries / named arguments `[*:m, k: v]` / `f(*:m)`, safe index `list?[i]` / `map?['k']`, ranges and range indexing, `as` conversions, `=~`/`==~`/`~/re/`, `<<`, `in`, `<=>`, `switch` statements and Groovy 4 switch expressions (`case 1..3 ->`, `case String ->`, `case { it > 3 } ->`, regexes, lists, enum constants, `yield`) with `isCase`, command expressions (`println x`), varargs (`int... xs`), methods and constructors overloaded by parameter type (runtime multi-dispatch picking the most specific candidate: exact types, subclasses, interfaces, boxing/widening, `null`, varargs; `MissingMethodException` when none applies), classes (fields and properties with generated getters/setters, `this.@field`, constructors incl. named-argument ones, instance and static methods/fields, `static {}` blocks, inheritance with `super`, abstract classes, interfaces with default methods, traits, nested classes, operator overloading `plus`/`minus`/`leftShift`/`compareTo`..., `equals`/`toString`/`hashCode`, `getClass()`, `properties`, `hasProperty`, `propertyMissing`/`methodMissing`), metaprogramming (`Type.metaClass.m = {..}`, `Type.metaClass.static.m`, per-instance `obj.metaClass.m`, `Expando`, categories with `use(Category) {..}`), enums (constants with constructor arguments, fields, methods, `values()`/`valueOf()`/`name()`/`ordinal()`), AST transforms `@ToString`, `@EqualsAndHashCode`, `@TupleConstructor`, `@Canonical`, `@Immutable` (read-only instances, `ReadOnlyPropertyException`), `@Builder` (`Type.builder().x(..).build()`), `@Singleton` (`Type.instance`), `@Sortable`, `@AutoClone`, `@Slf4j`/`@Log`/`@Log4j`/`@CommonsLog` (`log`), `@Field`; `@CompileStatic`/`@TypeChecked` are accepted; `JsonSlurper`/`JsonOutput`, `StringBuilder`, GDK methods (`each`, `collect`, `findAll`, `find`, `inject`, `sum`, `groupBy`, `collectEntries`, `times`, `upto`...). Same bindings as JavaScript; `request.headers.foo = 'x'` / `exchange.in.body = ..` mutate the exchange in `script`. `@Grab`/`@Grapes` fail with a clear error (no JVM, dependencies cannot be loaded). Out of scope by design: static type checking (`@CompileStatic`/`@TypeChecked` and generics are not checked — the dynamic semantics apply), compile-time AST transforms beyond the listed ones, and JVM/third-party classes beyond the bundled GDK subset. |
| Python | ✅ | `cameleer-script` interpreter for Python 3 as used in route scripts: indentation-based blocks, `if`/`elif`/`else`, `for`/`while` (+`else`), `def` (defaults, `*args`, keyword-only parameters, `**kwargs`, positional-only `/`), `lambda`, closures, `global`/`nonlocal`, decorators (functions and classes), tuple unpacking, list/dict/set comprehensions and generator arguments, slicing, f-strings with format specs and the self-documenting `{x=}`, `%` and `str.format`, assignment expressions (`:=`), `try`/`except`/`else`/`finally`, `raise` (also bare `raise`), chained comparisons, structural pattern matching (`match`/`case` with literal, capture, wildcard, value, sequence (`*rest`), mapping (`**rest`), class (positional via `__match_args__`, keyword), or-, as- patterns and guards), classes (`__init__`, methods, class attributes, inheritance incl. several bases, `super()`, `@staticmethod`, `@classmethod`, `@property` + `@x.setter`, special methods `__str__`/`__repr__`/`__eq__`/`__lt__`/`__add__`.../`__len__`/`__getitem__`/`__setitem__`/`__contains__`/`__iter__`/`__call__`, user exception classes), metaclasses (`metaclass=` with `__new__`/`__init__`/`__call__`, inherited metaclasses, metaclass methods on the class, `type(name, bases, ns)`), generators (`yield`, `yield from`, `send`, `next(it, default)`, `StopIteration`), `with` (context managers, exception suppression, several items), `async def`/`await` coroutines with an event loop (`asyncio.run`, `gather`, `sleep` (virtual time), `create_task`, `wait_for`), async generators with `async for`, `async with`; imports of user modules (`import a.b [as c]`, `from m import x [as y]`, `from m import *`, relative `from .m import x`, packages with `__init__.py`; resolved relative to the importing module, the script (`scriptDir` option), the working directory, `src/main/resources`, `PYTHONPATH` or `classpath:`) and of the bundled modules `json`, `math`, `re`, `collections` (`Counter`, `defaultdict`, `OrderedDict`, `namedtuple`, `deque`, `ChainMap`), `functools` (`reduce`, `partial`, `lru_cache`/`cache`, `wraps`, `cmp_to_key`, `singledispatch`), `itertools` (`count`, `cycle`, `repeat`, `islice`, `chain`, `accumulate`, `takewhile`/`dropwhile`, `product`, `permutations`, `combinations`, `groupby`, `zip_longest`, `starmap`, `pairwise`, `batched`...), `contextlib` (`contextmanager`, `asynccontextmanager`, `suppress`, `closing`, `nullcontext`, `ExitStack`), `dataclasses` (`@dataclass(frozen, order, eq, repr, init)`, `field(default, default_factory, init, repr, compare)`, `__post_init__`, `asdict`, `astuple`, `replace`, `fields`, `FrozenInstanceError`), `asyncio`, `typing`, `abc`, `operator`, `copy`, `sys`, `string`, `time`, `random`; common builtins (`len`, `str`, `int`, `float`, `range`, `sum`, `min`, `max`, `sorted`, `enumerate`, `zip`, `map`, `filter`, `isinstance`, `getattr`/`hasattr`, `iter`/`next`...). Out of scope by design: C extensions and third-party packages (no pip), OS / process / network / threading modules (`os`, `subprocess`, `socket`, `threading`), dict keys are strings (non-string keys are converted), call depth beyond 900. |
| OGNL | ✅ | `cameleer-script`: Camel root object (`request`, `response`, `exchange`, `properties`, `property(name)`, `headers`, `body`, `context`), property/index navigation, method calls, static member access `@java.lang.Math@max(1, 2)` / `@Integer@MAX_VALUE` (JDK classes known to the interpreter), `#var`/`#this`/`#root`, `{a, b}` lists, `#{k: v}` maps, projection `.{expr}`, selection `.{? expr}`/`.{^ }`/`.{$ }`, `in`/`not in`, `eq`/`gt`/`and`/`bor`/`band`/`xor`/... word operators, ternary, `,` sequences. Arbitrary Java classes are not available (no JVM). |
| MVEL | ✅ | `cameleer-script`: Camel root object, property navigation, method calls, inline lists/maps/arrays, `contains`, `is`, `empty`, `nil`, projections `(name in list)`, `;`-separated statements, assignments, typed declarations (`int x = 5`, `java.util.List l = ...`), `with (obj) { a = 1, b += 2 }` blocks, `if`/`else`, `foreach`/`for (x : list)`, `while`, `def` functions; interceptors (`@Name statement`: `cameleer_script::mvel::MvelInterceptor` with `before` (reads/changes the script variables) and `after` (sees / replaces the statement value) hooks, bound in the Camel registry under the name or registered process-wide with `register_interceptor`); MVEL 2 templates (`render_template`): `@{expr}`, `@if{}`/`@elseif{}`/`@else{}`/`@end{}`, `@foreach{x : list, y : list2}..@end{sep}`, `@code{}`, `@comment{}`, `@include{'file'}` (relative to the template), `@declare{'name'}` + `@includeNamed{'name'}`, `@@` escapes — also as the `mvel:` component (see below). |
| SpEL | ✅ | `cameleer-script`: `#{...}` templates (a lone `#{expr}` returns the typed value) or plain expressions; Camel root object (`request`, `response`, `exchange`, `message`, `body`, `headers`, `properties`), `#root`/`#this`/`#var`, `@bean` references resolved from the Camel registry (plain values, and bean methods bound as `name.method` via `bind_bean_method`: `@calc.twice(21)`), `T(Type)` static calls, `new` for JDK collection types, `?.`, `?:`, ternary, `{1, 2}` lists, `{k: v}` maps, selection `.?[]`/`.^[]`/`.$[]`, projection `.![]`, `matches`, `between`, `instanceof`, word operators (`eq`, `div`, `mod`...). Arbitrary Java classes/constructors are not available (no JVM). |
| DataSonnet | ✅ | `cameleer-script`: a Jsonnet interpreter (objects with late binding: `self`, `super`, `$`, hidden `::` and forced-visible `:::` fields, `+:` merges, object inheritance with `+`, method fields, object `local`s and `assert`s, lazy fields that resolve after a later `+`; arrays, `local`, functions with defaults/named arguments, `if`/`then`/`else`, array/object comprehensions, slices, `%` formatting, `error`, `assert`, text blocks, local `import`/`importstr`/`importbin` (absolute, working-directory relative or `classpath:` paths)) with `payload`, `cml.header()`, `cml.exchangeProperty()`, `cml.variable()`, `cml.properties()`, `std.extVar(name)` (script option `extVar.<name>` (JSON or text), else the exchange variable / header / property of that name) and top-level arguments (a program evaluating to a function is called with `tla.<name>` options, exchange variables / headers, `payload` or the parameter defaults), the complete `ds` library: the top-level functions (`map`/`filter`/`flatMap`/`foldLeft`/`reduce`/`groupBy`/`orderBy`/`distinctBy`/`mapObject`/`mapEntries`/`filterObject`/`entriesOf`/`combine`/`contains`/`find`/`match`/`matches`/`scan`/`replace`/`splitBy`/`joinBy`/`select`/`remove`/`removeMatch`/`read`/`write`/`readUrl`/`zip`/`unzip`/`range`/`parse*`/`uuid`/`is*`/`max(By)`/`min(By)`/`sizeOf`/`typeOf`...), `ds.arrays`, `ds.binaries`, `ds.crypto` (`hash` MD5/SHA-1/SHA-256/384/512, `hmac`, AES `encrypt`/`decrypt` (CBC with a random IV prefix, or ECB) via cameleer-tls), `ds.datetime` (`now`, `today`, `format`, `parse` with Java patterns or `unix`, `changeTimeZone` with zoneinfo region ids or offsets via `cameleer_core::tz`, `plus`/`minus` ISO periods, `compare`, `daysBetween`, `toLocalDate`/`toLocalTime`/`toLocalDateTime`, `atBeginningOf*`, `isLeapYear`), `ds.jsonpath.select`, `ds.math`, `ds.numbers`, `ds.objects`, `ds.period`, `ds.strings`, `ds.url`, `ds.xml.flattenContents`; and the common `std` functions (`map`, `filter`, `foldl`, `length`, `join`, `split`, `objectFields(All)`, `objectHas(All)`, `toString`, `parseJson`, `manifestJsonEx`, `format`, `sort`, `uniq`, `mergePatch`...). Media types (`bodyMediaType` / `outputMediaType`, with parameters such as `application/csv; separator=;`): `application/json` (default; output with sorted keys, sjsonnet's default), `text/plain`, `application/xml` (BadgerFish-style `@attr` / `$` text with the DataSonnet XML plugin options `TextValueKey`, `AttributeCharacterKey`, `CDataValueKey` (output), `NamespaceSeparator`, `NamespaceDeclarations.<prefix>` (read: namespace URIs mapped to the declared prefixes, `@xmlns` declarations; write: declared on the root), `RootElement`, `OmitXmlDeclaration`, `XmlVersion`, `Encoding`, `AutoEmptyElements`, `NullAsEmptyElement`, `indent`), `application/csv` (header row or `header=false`), `application/x-www-form-urlencoded`, `application/x-java-object` (returns the value); `resultType` converts. Out of scope by design: CDATA sections and mixed-content ordering keys when reading XML (text is merged into the text key), Java classes/libraries plugged into DataSonnet. |
| CSimple | ✅ | `csimple` is an alias of the Simple language (Simple is already evaluated natively). |
| jOOR / Java (`joor`, `java`) | ✅ | `cameleer-script`: Java snippets are interpreted (no JDK compiler): bindings `exchange`, `message`, `body`, `optionalBody`, `bodyAs(Type.class)`, `optionalBodyAs`, `header`/`headerAs(name[, default], Type.class)`, `exchangeProperty(As)`, `variable(As)`; class / record / enum / interface declarations and methods in the snippet (fields, constructors overloaded by parameter types, static members and static methods, inheritance, abstract classes, interfaces with default methods, generic classes and methods (erased: type arguments are not checked), records with canonical / compact constructors, accessors, `toString`/`equals`/`hashCode`, enums with fields, constructors and methods, `switch` on enum constants), typed locals and `var`, `final`, `if`/`for`/enhanced `for`/`while`/`do`, labeled `break`/`continue`, `switch` statements (colon and arrow forms) and switch expressions (`case A, B ->`, `yield`, type patterns `case String s ->`), ternary, string concatenation, Java integer division and `ArithmeticException`, `char` as a numeric type (char literals, `c + 1`, `c - '0'`, `c++`, `(char)`/`(int)` casts, char arithmetic into arrays), casts, `instanceof` with pattern binding, overload resolution by static type where the snippet declares it (`List.remove(Integer)`/`remove((Object) x)` remove the element, `remove(int)` the index), lambdas and method references, `new ArrayList<>()`/`HashMap`/`LinkedHashMap`/`HashSet`/`StringBuilder`, sorted `TreeMap`/`TreeSet` (ordered on every change, natural order or a `Comparator`, `firstKey`/`floorKey`/`ceilingKey`/`headMap`/`tailMap`/`subMap`/`pollFirst`/`descendingMap`...), arrays (`new int[3]`, `new int[]{..}`, `{..}` initializers, multi-dimensional literals), text blocks, `return`, `throw`/`try`/`catch` (multi-catch)/`finally`, and the common JDK API (`String`, `String.format`, `String.join`, `Integer`/`Long`/`Double`/`Boolean`/`Character`, `Math`, `List`/`Map`/`Set`/`Arrays`/`Collections`/`Objects`/`Optional`, streams (`stream().filter().map().collect(Collectors.toList()/joining/groupingBy/...)`, `IntStream`), `Comparator`, functional interfaces, `java.time` (`LocalDate`, `LocalDateTime`, `LocalTime`, `Duration`, `Period`, `ChronoUnit`, `DayOfWeek`, `Month`, `DateTimeFormatter.ofPattern` / ISO formatters, parsing and formatting)). Out of scope by design: compile-time checks (generics, checked exceptions, missing returns), reflection, threads, and JDK / third-party classes beyond the listed API (no JVM interop). |

## Data formats

| Data format | Status | Notes |
|---|---|---|
| JSON (`json`, aliases `jackson`, `gson`...) | ✅ | Pretty print. No POJO binding: values map to `Value`. |
| CSV | ✅ | RFC 4180. |
| Base64, Hex, String (charset) | ✅ | |
| GZip, Zip/Deflate, ZipFile | ✅ | Built-in deflate implementation. |
| XML (`jacksonXml`, aliases `xml`, `jaxb`) | ✅ | A generic Jackson `XmlMapper`-style value ⇄ XML mapping (no schema binding): keys → elements, arrays repeat, `rootName`, `prettyPrint`, `xmlDeclaration`, `contentTypeHeader`. Annotation equivalents as options: `attributes=a,b` / `@`-prefixed keys (`attributePrefix`, also applied on unmarshal when set) → attributes (`@JacksonXmlProperty(isAttribute=true)`), `textProperty` (`@JacksonXmlText`), `properties=key:xmlName` with `p:local` / `{uri}local` names (`localName`/`namespace`), `namespace` (default) + `namespaces=p=uri` declared on the root, generated prefixes for other `{uri}` names, `wrappers=key:item` (`@JacksonXmlElementWrapper`, unwrapped on unmarshal). With `cameleer-soap` registered (as in `cameleer_main::new_main`), `jaxb` is the schema-typed binding below. |
| URL-encoded form | ✅ | |
| Custom data formats (registry) | ✅ | |
| Protobuf (`protobuf`) | ✅ | `cameleer-grpc`. Runtime `.proto` parsing (proto3 + basic proto2, imports from the same directory, nested types, enums, `repeated`/packed, `map`, `oneof`, well-known types Empty/Timestamp/Duration/Struct/Value/ListValue/wrappers/Any) instead of generated classes: `instanceClass` names the message type, `protoFile` the schema. Bodies are `Value` objects keyed by field name; `contentTypeFormat=native` (wire bytes) or `json` (proto3 JSON mapping, lowerCamelCase names). Rust DSL: `cameleer_grpc::protobuf(file, type)`; name-based references with options (YAML `marshal: {protobuf: {instanceClass, protoFile}}`, `dataformat:protobuf:marshal?...`) are resolved through the core data format factory; without options it reads `CamelProtobuf*` headers or `camel.dataformat.protobuf.*` properties. No extensions, no proto2 groups. |
| Custom data format factories | ✅ | `cameleer_core::dataformat::register_data_format_factory`: crates contribute formats by name so options on name references work (Rust DSL `DataFormatDefinition::new(name).option(..)`, YAML `marshal: {name: {...}}`, `dataformat:name:marshal?...`). |
| Avro (`avro`, `avroJackson`) | ✅ | `cameleer-dataformats`. JSON schema parser (records/errors, enums, arrays, maps, unions, fixed, namespaces, aliases, defaults; logical types date, time/timestamp millis/micros, local-timestamp, decimal (bytes/fixed), uuid, duration), binary encoding (a bare datum like Camel), Avro JSON encoding (`encoding=json`) and Object Container Files (`encoding=container`, `codec=null`/`deflate`, `syncInterval`; unmarshal reads the writer schema). Options `schema`, `schemaFile`, `instanceClassName` (selects a named type, or a registry schema), `contentTypeHeader`, `logicalTypeConversions` (ISO-8601 dates / decimal strings, default true). `avroJackson` marshals JSON text, `jsonView=true` unmarshals to JSON text. No snappy/zstd codecs, no reader/writer schema resolution. |
| Bindy (`bindyCsv`/`bindy`, `bindyFixed`, `bindyKvp`) | ✅ | `cameleer-dataformats`. Record layouts are descriptors instead of annotations: YAML/JSON (`descriptor`, `descriptorFile`, or `classType` naming a registry bean / descriptor file) or the `BindyDescriptor`/`BindyField` builder (`bindy::bind_descriptor`). CSV `separator`, `skipFirstLine`, `generateHeaderColumns`, `quote`/`quoting`/`removeQuotes`, `crlf`; fixed `length`, `paddingChar`, `align`, `delimited` fields, `clip`, `ignoreTrailingChars`/`ignoreMissingChars`, `skipHeader`/`skipFooter`; kvp `keyValuePairSeparator`, `pairSeparator`, `tag`; fields `pos`, `type` (int, decimal, date with `pattern`, boolean...), `precision`, `trim`, `defaultValue`, `required`, `columnName`. Unmarshal gives objects (`unwrapSingleInstance`). No `@Link`/`@OneToMany` sections, header/footer records. |
| YAML (`yaml`, `snakeYaml`) | ✅ | `cameleer-dataformats`, cameleer-yaml's parser. SnakeYAML-like output (`defaultFlowStyle` AUTO/BLOCK/FLOW, `prettyFlow`), safe constructor (application tags rejected unless `allowAnyType` or `typeFilter`; tags never construct types), `maxAliasesForCollections`. |
| Tar (`tarFile`), ZipFile multi-entry | ✅ | `cameleer-dataformats`. ustar + pax (long names, GNU long names on read), `usingIterator` (body = array of entry contents, names in `CamelTarFileEntryNames`/`CamelZipFileEntryNames`), `allowEmptyDirectory`, `preservePathElements`, `CamelFileName`; an object body marshals one entry per key. Replaces core's single-entry `zipFile`. No aggregation strategies. |
| Crypto (`crypto`) | ✅ | `cameleer-dataformats`. AES/DES/DESede with ECB, CBC, CTR, CFB, OFB, GCM and PKCS5/No padding, `keyRef`/`key`/`CamelCryptoKey`, `initVectorRef`/`initVector`, `inline` IV (Camel's length-prefixed layout), `shouldAppendHMAC` with `macAlgorithm` HmacSHA1/256/384/512. |
| PGP (`pgp`) | ✅ | `cameleer-dataformats`. OpenPGP v4: RSA, Ed25519 (EdDSA), ECDSA/ECDH (Curve25519, P-256, P-384) keys from armored/binary keyrings (`keyFileName`, `encryptionKeyRing`, `#bean`); S2K-protected secret keys (AES/3DES); PKESK + SEIPD v1 with MDC (`integrity`), legacy SED, decryption of GnuPG's OCB packets; ZIP/ZLIB; one-pass signatures and verification (`signatureKeyFileName`, `signatureKeyUserid(s)`, `signaturePassword`, `signatureVerificationOption`), `keyUserid(s)`, `password`, `armored`, `algorithm`, `hashAlgorithm`, `compressionAlgorithm`, `CamelPGPDataFormat*` headers. Verified against GnuPG 2.4 both ways. No CAST5/IDEA, BZip2, v6 keys, SEIPD v2, password (SKESK) messages, cleartext signatures. |
| CBOR (`cbor`) | ✅ | `cameleer-dataformats`. RFC 8949 (preferred serialization, indefinite lengths, bignums, tags dropped). |
| Thrift (`thrift`) | ✅ | `cameleer-dataformats`. Runtime IDL (`schema`/`idlFile` + `instanceClass`) instead of generated classes: structs, unions, exceptions, enums, typedefs, `const` (evaluated: numbers, strings, lists, sets, maps, struct literals, constant / `Enum.VALUE` references), field defaults (applied on marshal and unmarshal), `service` definitions (methods, `throws`, `oneway`, `extends`); `contentTypeFormat` binary (TBinaryProtocol), compact (TCompactProtocol), json (TJSONProtocol) or sjson (TSimpleJSONProtocol-style plain JSON). |
| ASN.1 (`asn1`) | ✅ | `cameleer-dataformats`. `usingIterator` splits BER record streams; generic BER/DER ⇄ `Value` tree; typed mode with a runtime ASN.1 module compiler instead of jASN1/ASN1bean classes (`schema` / `moduleFile` + `clazzName`): X.680 modules with EXPLICIT/IMPLICIT/AUTOMATIC tag defaults, type and value assignments (INTEGER, OID with named components), BOOLEAN, INTEGER (named numbers), ENUMERATED, REAL (X.690 binary/decimal/special), NULL, OCTET/BIT STRING (named bits), OBJECT IDENTIFIER, RELATIVE-OID, all character string and time types, SEQUENCE/SET (OPTIONAL, DEFAULT omitted in DER and filled on decode, COMPONENTS OF, extension markers, version groups, DER SET ordering), SEQUENCE OF / SET OF, CHOICE, ANY, tagged types and references; BER input (indefinite lengths, constructed strings). Verified against the X.690 Annex A PersonnelRecord encoding. Constraints are parsed but not checked; information object classes / parameterized types are skipped. |
| iCal (`iCal`) | ✅ | `cameleer-dataformats`. RFC 5545 parse/emit (folding, parameters, TEXT escaping), `validating`. |
| MIME multipart (`mimeMultipart`) | ✅ | `cameleer-dataformats`. Attachments in the `CamelAttachments` property; `multipartSubType`, `multipartWithoutAttachment`, `headersInline`, `includeHeaders`, `binaryContent`. |
| uniVocity (`univocityCsv`, `univocityTsv`, `univocityFixed`) | ✅ | `cameleer-dataformats`. CSV aliases core `csv` with translated options (`delimiter`, `quote`, `quoteEscape`, `quoteAllFields`, `lineSeparator`/`normalizedLineSeparator`, `nullValue`, `comment`, `skipEmptyLines`, whitespace trimming) plus `numberOfRecordsToRead` and `emptyValue`; TSV (`escapeChar`) and fixed width (`fieldLengths`, `padding`, character-stream records with `skipTrailingCharsUntilNewline` and `recordEndsOnNewline`); all with `headers`, `headersDisabled`, `headerExtractionEnabled`, `asMap`, `numberOfRecordsToRead`, `emptyValue`, `lazyLoad` (rows are returned as a list). |
| Fory (`fory`) | ✅ | `cameleer-dataformats`. Apache Fory **xlang** protocol for dynamic values: header bitmap + language, reference flags (`refTracking`, back references), xlang type ids (bool, int8..64, var/zigzag/SLI int64, float16/32/64, string with Latin-1/UTF-16/UTF-8 coders, enum, list/set with element headers, chunked maps, named/numeric structs, binary, local date, timestamp, duration, primitive arrays), meta strings (LOWER_SPECIAL / LOWER_UPPER_DIGIT_SPECIAL / FIRST_TO_LOWER / ALL_TO_LOWER / UTF-8, murmur3 hash header, back references). Objects with a `@type` key are `NAMED_STRUCT`s; field names for reading come from `structTypes` (`ns.Type=f1,f2;...`). `requireClassRegistration` (default false), `threadSafe`/`allowAutoWiredFory`/`unmarshalType` accepted. Compatible mode (`compatible=true` / `compatibleMode=COMPATIBLE`): `NAMED_COMPATIBLE_STRUCT` with shared TypeDef meta (meta-share index markers, 8-byte global header with size + murmur3 hash, field infos with name encodings / nullable flags / field types), readers match fields by name without `structTypes`. `DECIMAL` (`{"@decimal": "1.25"}`, small and big unscaled encodings; read as decimal text). Extension types (`NAMED_EXT`) via registered `ExtSerializer`s (`{"@ext": "ns.Name", ...}`). Protocol edition `xlangSpec`: `CURRENT` (default) writes the current xlang specification — one-byte header (xlang / out-of-band bits), the renumbered internal type-id table (incl. reading `UINT8`..`TAGGED_UINT64`, `BFLOAT16`, `NONE`, unsigned / bfloat16 arrays) and numeric user type ids as a separate varuint after the internal id, also inside TypeDefs; `LEGACY` writes the Fory 0.10/0.11 layout (bitmap + language byte, `(user_id << 8) | internal_id`). Readers detect the edition from the header. Remaining gaps: Java native mode and out-of-band buffers are not applicable to dynamic values (rejected); `FLOAT8` and the union types of the current spec are rejected. |
| Barcode (`barcode`) | ✅ | `cameleer-dataformats`, own codecs instead of ZXing, covering every `barcodeFormat` value (ZXing's `BarcodeFormat`). **Encode** (the formats ZXing writes): QR Code (versions 1-40, `errorCorrectionLevel` L/M/Q/H, numeric/alphanumeric/Kanji (JIS X 0208 via the Shift_JIS mapping)/byte modes with UTF-8 ECI, Reed-Solomon, mask selection by the four penalty rules), Data Matrix ECC 200 (square 10x10..144x144 and rectangular 8x18..16x48, `dataMatrixShape` NONE/SQUARE/RECTANGLE with ZXing's size order) through a port of ZXing's `HighLevelEncoder` (ASCII with digit pairs and upper shift, C40, Text, ANSI X12, EDIFACT and Base 256 with the ISO/IEC 16022 Annex P look-ahead, ZXing's capacity-dependent end-of-data handling, macro 05/06 headers, 253-state padding), Aztec (compact and full-range up to 32 layers, ZXing-style 33% EC, ZXing's optimal high-level encoder: all non-dominated states per character with latches, shifts, the four punctuation pairs and binary shift, ties broken in ZXing's order, ECI 26), PDF417 (`PDF_417`: ZXing's AUTO/TEXT/BYTE/NUMERIC compaction (`pdf417Compaction`) including its sub-mode rules, UTF-8 via ECI 927/26, error correction levels 0-8 (`errorCorrectionLevel`, default 2) with Reed-Solomon over GF(929), ZXing dimension choice (2-30 columns, rows up to 90), row indicators, start/stop patterns and the three cluster tables, ZXing rendering incl. 90° rotation for portrait requests), Code 128 (sets A/B/C), Code 39, Code 93 (full ASCII via the shift characters, two check characters, termination bar), Codabar (start/stop A-D or T/N/*/E, default A), ITF, EAN-13, EAN-8, UPC-A, UPC-E (number system 0/1, check digit via the UPC-A expansion); ZXing-style rendering (`width`/`height`, integer scaling, quiet zones) to PNG (own encoder over cameleer-core zlib + CRC-32), GIF (own LZW encoder, gray palette) or JPG (own baseline JPEG encoder), `imageType`. MAXICODE, RSS_14, RSS_EXPANDED and UPC_EAN_EXTENSION are decode-only, as in ZXing (marshalling them fails like ZXing's `MultiFormatWriter`). **Decode** (unmarshal, header `BarcodeFormat`, `ERROR_CORRECTION_LEVEL` for QR, `UPC_EAN_EXTENSION` + `SUGGESTED_PRICE`/`ISSUE_NUMBER` for add-ons) from PNG (all color types / bit depths / filters, Adam7), GIF (87a/89a, interlace, transparency) and baseline JPEG (SOF0/SOF1, subsampled YCbCr, restart intervals); `multiple=true` decodes every symbol of an image (the image, then overlapping halves of it recursively, like ZXing's `GenericMultipleBarcodeReader` searches beside each result; distinct results as a list of `{text, BarcodeFormat, ...}` maps, headers `BarcodeFormat` (list) and `BarcodeCount`). Camera-like images (photographs): luminance from gray/RGB/palette, noise-adaptive smoothing, ZXing's `HybridBinarizer` (8x8 block black points, 5x5 neighbourhood averaging, global-histogram fallback for small images), a copy deskewed by the dominant edge orientation for linear/stacked symbols; QR via ZXing's `FinderPatternFinder` (1:1:3:1:1 runs cross-checked vertically, horizontally and diagonally, best-triangle selection), alignment-pattern search for version >= 2 and a perspective transform for grid sampling, mirrored symbols, version information, Shift_JIS guessing for byte segments without ECI; Data Matrix via `WhiteRectangleDetector`, sides fitted as lines through the outermost dark edge points, size and orientation chosen by scoring the L finder/timing pattern under perspective (square and rectangular), every encodation (incl. EDIFACT unlatch alignment and implicit end) and macro 05/06; Aztec via the bull's-eye (ring runs, blob-checked centre, ring rotation from a polar profile, least-squares perspective fit refined at the predicted ring corners, the fitted outer sides and the reference grid) in all eight orientations; MaxiCode with ZXing's pure-image reader (`extractPureBits` over the dark bounding box, ZXing's bit-number table, GF(64) Reed-Solomon of the primary and even/odd secondary blocks, modes 2-5 with the structured carrier message, code sets A-E with shifts/latches/lock/NS) plus, beyond ZXing, a photograph detector (bull's-eye confirmed on eight rays, orientation-module and module-fit search with a refined projective map); linear symbols (Code 128, Code 39, Code 93, Codabar, ITF, EAN-13/UPC-A, EAN-8, UPC-E with 2/5-digit add-ons, RSS-14 incl. stacked via pairs collected over rows, RSS Expanded with ZXing's finder sequences, checksum and AI decoders/`FieldParser`) on band-averaged, locally thresholded scan lines (rows and columns, both directions) with ZXing's variance limits and quiet zones; PDF417 rows with chained codeword slots following perspective foreshortening and per-codeword row tracking by cluster, per-row voting, RS errors + erasures, text/byte/numeric/ECI decoding, Macro PDF417 blocks skipped. **Tested** with synthetic photographs (perspective warp, arbitrary rotations incl. a 14-angle sweep, scaling, Gaussian and box blur, lighting gradients, additive noise up to sigma 18, our JPEG encoder at quality 60, and all combined) for QR (incl. version 10), Data Matrix (incl. 4 regions), Aztec (compact and full-range), PDF417, Code 128, Code 93, Codabar, ITF, EAN-13, EAN-8, UPC-E, EAN-13 with a 5-digit add-on, RSS-14 and RSS Expanded (every combination decodes) and MaxiCode (all but the strong-keystone cases, which ZXing cannot read from photographs at all); multiple-symbol images (a 2x2 grid of QR/Data Matrix/Code 128/EAN-13, a photographed row of three); images from ZXing's blackbox suite (embedded as fixtures with attribution: qrcode-1/2/3, datamatrix-1/2, aztec-2, pdf417-2/3, code128-1, ean13-1, codabar-1, code93-1, ean8-1, itf-1, upce-1, upcean-extension-1 (incl. a phone photograph), maxicode-1 (modes 2, 3, 4, mixed code sets), rss14-1 (incl. stacked), rssexpanded-1 — all decode). Verified against ZXing's writer test vectors for Code 93 (incl. full ASCII), Codabar, ITF, EAN-8 and UPC-E (module strings), ZXing's Data Matrix `HighLevelEncodeTestCase` (48 codeword vectors for every encodation, incl. Base 256 lengths up to 277), ZXing's Aztec `EncoderTest` (high-level bit strings, binary-shift length rules and the complete compact 3-layer Wikipedia symbol, module-exact), full QR symbols from ZXing's encoder tests (module-exact), the ZXing Aztec reference symbols, the PDF417 cluster tables and ZXing's PDF417 high-level vectors, ISO/IEC 18004 Annex I, ISO/IEC 16022 codewords, ZXing's six rectangular Data Matrix blackbox symbols (module-exact) and `SymbolInfo` vectors, ZXing's RSS width tables (every character value round-trips through the ISO/IEC 24724 width routines), Pillow-written PNG/GIF/JPEG files. Differences from ZXing: the PDF417 text encoder resets to Alpha after a final pad in Punctuation sub-mode (ZXing keeps Punctuation, which misencodes text after a following byte shift); the multiple-symbol search splits the image into overlapping halves instead of using result points; Data Matrix's optional `MinimalEncoder` (ZXing's `DATA_MATRIX_COMPACT` hint, not a Camel option) is not ported. |
| JAXB binding (`jaxb`) | ✅ | `cameleer-soap`. No generated classes: XML ⇄ `Value` typed by an XML Schema (`contextPath` = XSD location(s) or a `.properties` descriptor with `schema=` / `prefix.<p>=<ns>`; ints/longs → `Int`, decimal/float/double → `Float`, boolean → `Bool`, base64/hex → `Bytes`, dates as lexical strings, `maxOccurs>1` → arrays, `xs:list` → arrays, simple content + attributes → `{value, @attr}`, `xsi:nil` → null, extensions/groups/attribute groups resolved), `schema` validation on unmarshal and marshal (`UnmarshalException`/`MarshalException` with Xerces-style messages), `prettyPrint` (default true), `fragment`, `encoding`, `namespacePrefix` (`uri=prefix,...`), `partClass`/`partNamespace` (root element), `ignoreJAXBElement`, `attributePrefix` (`@`) or `plainAttributes`, `filterNonXmlChars`. Without a schema: structural mapping (text-only elements → strings, repeated siblings → arrays). Overrides core's `jaxb` alias of `jacksonXml`. Polymorphism: `xsi:type` selects the derived type on unmarshal (recorded as `@xsi:type`) and marshal (writes `xsi:type`), substitution group members (transitive, typeless members inherit the head's type) bind where the head is declared. `typedDates=true` maps `date`/`dateTime`/`time` to `XMLGregorianCalendar`-like objects (`year`...`millisecond`, `timezone` minutes) and `duration` to an object; marshal also takes epoch millis. Schemas from registry beans: `contextPath`/`schema` = `#bean` / `ref:` / `bean:` naming a `String`/`Value::String` XSD, a `cameleer_soap::xsdmodel::SchemaSet` or a compiled `cameleer_xml::xsd::Schema` (the factory holds a weak context reference). No generated classes, so `ObjectFactory`/`@XmlRootElement` map to the schema's global elements. |
| FHIR (`fhirJson`, `fhirXml`) | ✅ | `cameleer-soap`. FHIR R4 serialization rules without HAPI: `resourceType` ⇄ root element, primitives `<x value=""/>` with `_x` id/extensions (aligned arrays for repeating primitives), repeating elements → arrays, boolean/integer/decimal JSON types, `Element.id`/`Extension.url` attributes, nested resources (`contained`, `Bundle.entry.resource`...) wrapped, narrative `div` XHTML passthrough. An embedded type registry (names, types, cardinality, spec order) covers the common data types (incl. Dosage, ElementDefinition) and Patient, Practitioner, Organization, Observation, Encounter, Condition, Procedure, Medication, MedicationRequest, AllergyIntolerance, DiagnosticReport, Immunization, Location, Device, ServiceRequest, Appointment, Binary, Basic, StructureDefinition, Bundle, OperationOutcome, CapabilityStatement, Parameters (other resources: heuristics); `fhirVersion=DSTU3` / `R5` switch to per-release definitions of the resources that changed shape (Observation, Encounter, Condition, AllergyIntolerance, MedicationRequest, Patient, Dosage; R5 `CodeableReference`), R4B = R4. XML output is written in the specification's element order (unknown elements last). Decimals keep their lexeme: exact `f64`s unmarshal to `Float`, others (`185.00`) to `String` and are written back as numbers; hand-built values are retyped by the registry (numeric/boolean strings → JSON numbers/booleans). Unmarshal → resource `Value`; marshal accepts a value or FHIR JSON/XML text (so the pair converts between encodings). Options `fhirVersion`, `prettyPrint`, `suppressNarratives`, `omitResourceId`, `encodeElements`, `dontEncodeElements`, `stripVersionsFromReferences`. Profile validation (`cameleer_soap::fhir::validation`, also the fhir component's `validate/resource?profile=`): registry checks (unknown elements, single vs repeating, primitive JSON types and lexical forms) plus `StructureDefinition` snapshot/differential `min`/`max`, `type` (choice suffixes, primitive kinds, `Reference.targetProfile`), `fixed[x]`, `pattern[x]`, `maxLength`, profile `type`; slices and FHIRPath invariants are not evaluated. |

## Components

| Component | Status | Key options / notes |
|---|---|---|
| ftp | ✅ | `cameleer-protocols`. Polling consumer (noop/delete/move/preMove/moveFailed, include/exclude/ant, recursive, sortBy, idempotent) and producer (fileExist strategies, tempFileName, doneFileName); passive/active mode, MLSD/LIST parsing; `readLock` = `changed` (SIZE/MDTM stable across `readLockCheckInterval`, `readLockTimeout`, `readLockMinLength`, `readLockMinAge`), `rename` (exclusive rename probe), `idempotent`, `idempotent-changed`, `idempotent-rename`. `localWorkDirectory` (downloads streamed to a local file, header `CamelFileLocalWorkPath`, removed after the exchange), `resumeDownload` (a partial `<name>.inprogress` local work file is continued with `REST <size>`; the embedded `FtpServer` implements `REST`), `streamDownload` (body = a one-shot stream handle from `cameleer_tls::stream_body` backed by a temp/local work file — `Value` has no stream variant — consumed chunked by the `http` producer or materialised on demand, released after the exchange). `ftps` ✅: explicit (`AUTH TLS`) and implicit (`isImplicit=true`) mode, `PBSZ`/`PROT P` protected data connections (`execPbsz`, `execProt`, `disableSecureDataChannelDefaults`), `securityProtocol`, `sslContextParameters`; data connections resume the control connection's TLS session (works with vsftpd `require_ssl_reuse=YES`-style servers; the embedded `FtpServer::set_require_ssl_reuse` enforces it). `sftp` ❌ (no SSH here). |
| smtp / pop3 / imap (mail) | ✅ | `cameleer-protocols`. SMTP AUTH PLAIN/LOGIN, headers override options, attachments via `CamelAttachments`; POP3/IMAP polling with MIME decoding, delete/copyTo/moveTo. `smtps`/`pop3s`/`imaps` (implicit TLS, ports 465/995/993) and STARTTLS/STLS on the plain schemes (`mail.<protocol>.starttls.enable` / `.required`), `sslContextParameters`. |
| websocket / vertx-websocket / ws | ✅ | `cameleer-protocols`. RFC 6455 server and client, fragmentation, ping/pong, `sendToAll`, connection-key routing. No compression extensions. `wss://` client endpoints and `wss` servers (`sslContextParameters` on `websocket`/`vertx-websocket`). |
| mllp + hl7 data format | ✅ | `cameleer-protocols`. MLLP framing, auto-ACK (AA/AE), producer ACK validation and exceptions, `CamelMllp*` headers; HL7 v2 parsing with terser paths (`hl7terser` language). TLS with `sslContextParameters` (consumer and producer). No typed HAPI model. |
| syslog | ✅ | `cameleer-protocols`. RFC 5424/3164 data format, UDP/TCP component; TLS (RFC 5425) with `syslog:tls://` or `ssl=true` + `sslContextParameters` (octet-counted framing). |
| kafka | ✅ | `cameleer-kafka-mqtt`. Built-in Kafka wire protocol client (ApiVersions, Metadata v5, Produce v3 with v2 record batches/CRC32C/headers, Fetch v4, ListOffsets v1, FindCoordinator, JoinGroup/SyncGroup/Heartbeat/LeaveGroup, OffsetCommit/OffsetFetch, CreateTopics). Producer: `kafka.KEY`/`key`, `kafka.PARTITION_KEY`/`partitionKey`, murmur2 partitioner, `kafka.OVERRIDE_TOPIC`, `requestRequiredAcks`, record headers, `kafka.RECORD_META`. Consumer: `groupId` with range assignor and rebalancing, `consumersCount`, committed offsets (`autoCommitEnable`, `autoCommitIntervalMs`, `allowManualCommit` via `kafka::manual_commit`), `autoOffsetReset`, `seekTo`, `topicIsPattern`, `breakOnFirstError`, `maxPollRecords`; `kafka.TOPIC/PARTITION/OFFSET/KEY/TIMESTAMP` headers. Security: `securityProtocol` `SSL`, `SASL_PLAINTEXT`, `SASL_SSL` with `saslMechanism` `PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512` (`saslJaasConfig` credentials), `AWS_MSK_IAM` (registered by `cameleer-cloud`, see aws2-msk; custom one-step mechanisms via `kafka::client::register_sasl_mechanism`), `sslContextParameters`, `sslTruststoreLocation`/`sslTruststorePassword`/`sslTruststoreType` and client certificates with `sslKeystoreLocation`/`sslKeystorePassword`/`sslKeyPassword`/`sslKeystoreType` (PKCS12, JKS or PEM), `sslEndpointIdentificationAlgorithm`, `sslProtocol`. Embedded test broker `testing::KafkaBroker` (with TLS and SASL modes). No GSSAPI/OAUTHBEARER, transactions, idempotent producer, compression on send (gzip batches are decoded), or Avro/schema registry. |
| paho / paho-mqtt5 (MQTT) | ✅ | `cameleer-kafka-mqtt`. MQTT 3.1.1 and 5.0 client: username/password, keep-alive, QoS 0/1/2 flows, `+`/`#` wildcards, retained, clean/persistent sessions, will (`willTopic`...), automatic reconnect with re-subscription. Headers `CamelMqttTopic`, `CamelMqttQoS`, `CamelMqttRetained`, `CamelPahoOverrideTopic` (+ `CamelPahoQos`/`CamelPahoRetained` on the producer). `ssl://`/`mqtts://` broker urls (TLS, `sslContextParameters` - client certificates from its key material, `httpsHostnameVerificationEnabled`). Embedded test broker `testing::MqttBroker` (optionally TLS). No `ws://`/`wss://` transports, no MQTT 5 topic aliases, enhanced auth or shared subscriptions. |
| direct | ✅ | Synchronous. Fails with `DirectConsumerNotAvailableException` when no consumer is running. |
| seda / vm / stub | ✅ | `size`, `concurrentConsumers`, `waitForTaskToComplete`, `timeout`, `multipleConsumers`, `blockWhenFull`, `discardWhenFull`, `offerTimeout`, `purgeWhenStopping`, `failIfNoConsumers`, `discardIfNoConsumers`. Supports polling consumers. |
| timer | ✅ | `period`, `delay`, `repeatCount`, `fixedRate`, `includeMetadata`, `time` (local time of the default time zone; a trailing `Z`, offset or `[Europe/Paris]` selects another zone). Sets the `CamelTimerCounter` property. |
| scheduler | ✅ | Scheduled poll consumer options, including `scheduler=quartz&scheduler.cron=...` (also for the file consumer). |
| cron, quartz | ✅ | Built-in cron engine (`component/cron_expr.rs`): Quartz 6/7-field and Unix 5-field syntax, `L`, `W`, `#`, names, macros (`@daily`...), time zones (`timeZone=GMT+02:00` or region ids such as `Europe/Paris` read from the system zoneinfo database, TZif v1-v3 with POSIX footer rules; default: the process time zone). DST gaps and overlaps behave like Quartz: a fire time in a spring-forward gap fires once, shifted forward; one in a fall-back overlap fires once (standard time). `quartz:` cron and simple triggers (`trigger.repeatInterval`/`repeatCount`, `fireNow`, `triggerStartDelay`). Quartz headers (`fireTime`, `scheduledFireTime`, ...) carry epoch millis. No job store, clustering or calendars; missed fires are skipped. |
| mustache | ✅ | Variables, sections, inverted sections, comments, partials, set-delimiter, standalone lines; `allowTemplateFromHeader`, `contentCache`, `startDelimiter`/`endDelimiter`. No lambdas. |
| string-template, velocity, freemarker | ✅ | Real engines in cameleer-core. **Velocity** (VTL 2): references with properties/methods/indexes, quiet refs, `#set`, `#if/#elseif/#else`, `#foreach` (`$foreach.*`), `#break`, `#stop`, `#macro` (+ block macros), `#include`, `#parse`, `#evaluate`, `#define`, comments, escapes, Velocity arithmetic/logic. **FreeMarker** (FTL 2.3): interpolations, `if/list/items/sep/assign/global/local/macro/nested/function/return/include/import/switch/attempt/recover/compress/noparse/escape/outputformat/autoesc/setting`, user directives, lambdas, ranges, slices, defaults `!`/`??`, the string/number/boolean/sequence/hash/loop built-ins, square-bracket syntax; FreeMarker's strict missing-value errors (no date/time built-ins). **StringTemplate 4**: attributes, properties, anonymous sub-templates with `it`/`i`/`i0`, zipped/chained application, separators, `if/elseif/else`, functions `first last rest trunc strip length reverse trim strlen`, custom delimiters (`delimiterStart`/`delimiterStop`; template groups are not supported). Data model as in Camel (`body`, `headers`, `exchange`, `variables`, `request`/`in`, `camelContext` with `allowContextMapAll`), Java method calls on values, `allowTemplateFromHeader` headers, `CamelVelocityContext`/`CamelVelocitySupplementalContext`, `CamelFreemarkerDataModel`, `contentCache`. |
| mvel | ✅ | `cameleer-script` (`mvel:template.mvel`, registered by `cameleer_script::register`): renders MVEL 2 templates (orb tags, see the MVEL language row) against Camel's template data model (`body`, `headers`, `exchange`, `request`/`in`, `variables`; Java-like exchange accessors), with `allowTemplateFromHeader` (`CamelMvelTemplate` / `CamelMvelResourceUri`), `contentCache`, `allowContextMapAll`; literal `@include{}`s resolve relative to the template. |
| json-validator | ✅ | Built-in JSON Schema validator (draft-04 to 07 subset incl. `$ref` to local definitions, combinators, formats); `JsonValidationException` lists all errors. No remote `$ref`. |
| validator (XML) | ✅ | `cameleer-xml` (cameleer-core alone: well-formedness only): XML Schema subset — global/local elements, `ref`, `minOccurs`/`maxOccurs`, `sequence`/`choice`/`all`, model groups, `any`, mixed and empty content, `simpleContent`/`complexContent` extension and restriction, attributes (`use=required`, fixed, `anyAttribute`, attribute groups), simple types with `enumeration`, `pattern`, (min/max)`Length`, min/max `Inclusive`/`Exclusive`, `totalDigits`, `fractionDigits`, `list`, `union`, built-in types (string family, boolean, decimal, integer family, float/double, date, dateTime, time, duration, g*, binary), `include`/`import`, `xsi:nil`, identity constraints (`unique`/`key`/`keyref` with the restricted selector/field XPath: `.//`, `child::`, `@`/`attribute::`, `*`, `p:*`, `.`, `|`; keyrefs resolved against the referenced key on an ancestor-or-self or descendant scope; `cvc-identity-constraint.*` messages), substitution groups (transitive, `abstract` elements, typeless members take the head's type), `xsi:type` (QName in the instance's namespace context, derivation from the declared type checked — `cvc-elt.4.*`, abstract complex types require it — `cvc-type.2`), `redefine` (types, groups and attribute groups replaced, self references bound to the original). `SchemaValidationException` lists every error with Xerces codes and line/column (`cvc-complex-type.2.4.a: Invalid content was found starting with element 'x'. One of '{a, b}' is expected.`), also in the `CamelValidationErrors` property. Not checked: `block`/`final`, ID/IDREF uniqueness. |
| xslt, xslt-saxon | ✅ | `cameleer-xml`: XSLT 1.0 processor — templates with match patterns and priorities, modes, built-in rules, `apply-templates`/`call-template` with params, `value-of`, `for-each`, `if`/`choose`, `sort` (text/number, order, case-order, `lang` (accent folding, Nordic alphabets) and `collation` (codepoint, UCA/Saxon `strength=primary\|secondary\|tertiary`)), `copy`/`copy-of`, `element`/`attribute`/`text`/`comment`/`processing-instruction`, attribute sets, variables (RTFs usable as node-sets, `exsl:node-set`), `key()`, `number` (incl. `letter-value` alphabetic/traditional and `lang`: Greek, Cyrillic, Hebrew alphabets, Greek/Hebrew traditional numerals), `format-number` + `decimal-format`, `document()`, `include`/`import`/`apply-imports`, `strip-space`, `namespace-alias`, `message`, `xsl:output` method xml/html/text (html adds the `<META http-equiv="Content-Type">` after `<head>`; `include-content-type="no"`), indent (`xalan:indent-amount`), cdata-section-elements, doctype, `disable-output-escaping`. `version="2.0"` stylesheets (`xslt-saxon`) are compiled with XPath 2.0 (`if`/`for`/`some`/`every`, sequences, `to`, value comparisons, `intersect`/`except`, `||`, regex/string/sequence/date functions, `format-date`, `xs:*` constructors) and get the XSLT 2.0 core: `for-each-group` (`group-by`/`group-adjacent`/`group-starting-with`/`group-ending-with`, sorting, `current-group()`/`current-grouping-key()`), `xsl:function`, `xsl:sequence`, sequence-typed variables (`as`), `analyze-string` + `regex-group()`, tunnel parameters, `result-document` (files + `TransformResult::secondary`), `next-match`, `namespace`, `perform-sort`, `value-of separator`, `unparsed-text()`. Endpoint: `xslt:file:a.xsl` (also `classpath:`, `ref:`), `output=string\|bytes\|DOM\|file` (`CamelXsltFileName`, `deleteOutputFile`), `contentCache`, `failOnNullBody`, `allowTemplateFromHeader` (`CamelXsltStylesheet`/`CamelXsltResourceUri`); exchange properties and headers are passed as `xsl:param`s; transformer-factory options are ignored. Not implemented: schema-aware XSLT, XSLT 3.0 (`iterate`, `try`, maps, streaming — rejected with a `TransformerConfigurationException` unless an `xsl:fallback` is present). |
| xj | ✅ | `cameleer-xml`: `xj:identity` or `xj:file:x.xsl` with `transformDirection=XML2JSON\|JSON2XML`. JSON → XML uses Camel's xj representation (`<object xj:name=".." xj:type="object\|array\|string\|int\|float\|boolean\|null">`); XML → JSON honours xj annotations, otherwise element names become keys (repeated names → arrays, attributes `@name`, mixed text `#text`), keeping document order. |
| xmlsecurity-sign, xmlsecurity-verify | ✅ | `cameleer-xml`: XML Signature with RSA-SHA256 or ECDSA-SHA256 (cameleer-tls crypto), SHA-256 digests (SHA-1/512 accepted on verify), exclusive (default) or inclusive C14N. Signature types as in Camel: enveloped (`parentLocalName`/`parentNamespace` or `parentXpath`; default: the document element), detached (`xpathsToIdAttributes`: one reference per selected `Id`, signature after the last signed element or in the given parent) and enveloping (`contentObjectId` / `envelopingSignature=true`: content in `ds:Object`; verify returns the object content). Transforms: enveloped, C14N variants, XPath Filter (`xpathFilter`) and XPath Filter 2.0 (`xpath2Filter=intersect:expr;subtract:expr`, `xpathNamespaces`) via node-set canonicalization. `KeyInfo`: `X509Data` (`certificate` or the key store entry chain), `KeyValue` (`addKeyValue`: `RSAKeyValue` / `dsig11:ECKeyValue`), `KeyName` (`keyName`); `signatureId`, `prefixForXmlSignatureNamespace`, `omitXmlDeclaration`. Keys: PEM `privateKey`/`certificate`/`publicKey` (file, `ref:` bean, inline) or key stores via cameleer-tls `keystore` (`keyStore` = PKCS#12/JKS/JCEKS file or `#bean` `KeyStore`, `keyStorePassword`, `keyPassword`, `alias`; also `keyAccessor`/`keySelector`): verify matches the `X509Certificate` against the store, `KeyName` against aliases, else tries every key; `trustKeyInfoCertificate` trusts the embedded certificate or key value. Errors `XmlSignatureFormatException`, `XmlSignatureInvalidContentHashException`, `XmlSignatureInvalidValueException`, `XmlSignatureInvalidKeyException`. Not supported: `ds:Manifest`, external references, XSLT transforms. |
| slack | ✅ | `cameleer-saas`: producer via incoming webhook (`webhookUrl`, `username`, `iconUrl`, `iconEmoji`) or Web API `chat.postMessage` (`token`; object bodies are sent as the payload, `ok:false` → `ApiException`); consumer polling `conversations.history` (channel resolved by name, `maxResults`, `naturalOrder`, `conversationType`). `serverUrl` overrides the API. Mock: `testing::SlackMock`. |
| telegram | ✅ | `cameleer-saas`: `telegram:bots?authorizationToken=..`: `sendMessage` (`chatId` / `CamelTelegramChatId`, `parseMode`), multipart `sendPhoto`/`sendAudio`/`sendVideo`/`sendDocument` (`CamelTelegramMediaType`, caption header), object bodies; `getUpdates` long-poll consumer (`timeout`, `limit`, offsets confirmed); webhook support (`setWebhook`/`deleteWebhook`). `baseUri` overrides the API. Mock: `testing::TelegramMock`. |
| github | ✅ | `cameleer-saas`: consumers `pullRequest`, `issue`, `commit/<branch>` (`startingSha`), `tag`, `event` (repository events; body = event type, headers `CamelGitHubEventPayload`, `GitHubEvent`, `GitHubEventId`); producers `createIssue` (`GitHubIssueTitle`), `pullRequestComment` (`GitHubPullRequest`, `GitHubInResponseTo`), `issueComment`, `pullRequestState`, `pullRequestFiles` (list of changed file objects), `getCommitFile` (body = commit file / blob sha → decoded content, `encoding=base64` keeps base64), `closePullRequest`; `oauthToken`; repository webhooks via `webhook:github:...`. `serverUrl` overrides the API. Mock: `testing::GithubMock`. |
| twilio | ✅ | `cameleer-saas`: all REST 2010-04-01 resources of Camel's `twilio` component as `twilio:<api>/<method>` — account, address (+ dependent phone numbers), application, available-phone-number-country (+ local/mobile/toll-free), call (+ feedback, feedback summary, notifications, recordings), conference (+ participants), connect-app, incoming-phone-number (+ local/mobile/toll-free), key, new-key, message (+ feedback, media), notification, outgoing-caller-id, queue (+ members), recording (+ add-on results, payloads, transcriptions), short-code, signing-key, new-signing-key, sip credential lists / credentials / domains / mappings / IP access control lists / IP addresses, token, transcription, usage-record (all time / daily / last month / monthly / this month / today / yearly / yesterday), usage-trigger, validation-request — with methods `create`/`read`/`fetch`/`update`/`delete` (and the `creator`/`reader`/... aliases; unsupported combinations rejected). Parameters from endpoint options or `CamelTwilio.<param>` headers, `path*` parameters (`pathSid`, `pathAccountSid`, `pathCallSid`, `pathQueueSid`...) build the resource path, the rest become capitalised form fields (lists repeat), `inBody`; Basic auth (`username`/`password`, `accountSid`). `serverUrl` overrides the API. Mock: `testing::TwilioMock` (generic resource store). |
| jira | ✅ | `cameleer-saas`: REST v2 producers `addIssue` (Camel `ProjectKey`/`IssueTypeName`/`IssueSummary`/... headers), `updateIssue`, `addComment`, `deleteIssue`, `fetchIssue`, `fetchComments`, `searchIssues` (JQL), `transitionIssue` (`IssueTransitionId`, body = comment), `attach` (multipart upload, `CamelFileName`), `watchers` (`IssueWatchersAdd`/`IssueWatchersRemove`), `addIssueLink` (`ParentIssueKey`/`ChildIssueKey`/`linkType`), `addWorkLog` (`minutesSpent`); polling consumers `newIssues`, `newComments`, `watchUpdates` (`watchedFields`, `sendOnlyUpdatedField`, headers `IssueChanged`, `IssueWatchedIssues`); Basic (`username`/`password`) or bearer (`accessToken`) auth. OAuth 1.0a (`consumerKey`/`privateKey`) is accepted but not used. Mock: `testing::JiraMock`. |
| openai | ✅ | `cameleer-saas` (counterpart of `langchain4j-chat`/`-embeddings`): `openai:chat-completion?model=..` (text, message-list or request-object bodies, `systemMessage`, `temperature`, `maxTokens`, `topP`, `outputType=full`, usage/finish-reason headers) and `openai:embeddings`, any OpenAI-compatible server via `baseUrl`, `apiKey` (or `OPENAI_API_KEY`). No streaming or tool calls. Mock: `testing::OpenAiMock`. |
| webhook | ✅ | `cameleer-saas`: `webhook:<delegate uri>` exposes telegram / github endpoints on `platform-http` (`webhookPath`, `webhookBasePath`, `webhookComponentName`) and registers / unregisters the hook (`webhookExternalUrl`, `webhookAutoRegister`). |
| graphql | ✅ | `cameleer-saas`: `graphql://http(s)://host/path` with `query`, `queryFile`, `queryHeader`, `operationName`, `variables` (JSON or `#bean`), `variablesHeader`, `accessToken` + `jwtAuthorizationType`, Basic auth, `throwExceptionOnFailure`; body = response JSON text. Mock: `testing::GraphqlMock`. |
| rss, atom | ✅ | `cameleer-saas`: polling feed consumers for RSS 2.0, RSS 1.0 and Atom 1.0 (cameleer-xml parser): `splitEntries`, `filter` + `lastUpdate`, `sortEntries`, `throttleEntries`, `feedHeader` (`CamelRssFeed`/`CamelAtomFeed`); feeds/entries are maps (title, link, uri, description, contents, author, dates, categories); unknown options go to the feed url. Mock: `testing::FeedMock`. `weather` ❌. |
| log | ✅ | `level`, `showAll`/`showXxx`, `multiline`, `maxChars`, `groupSize`/`groupInterval`, masking. `BodyType:` shows the Java class name Camel would show (`java.lang.String`...). Log timestamps use the default time zone (`TZ`). |
| mock | ✅ | Expectations (count, minimum count, bodies in order or any order, headers, properties, no duplicates, custom), `assertPeriod`, `resultWaitTime`, `whenAnyExchangeReceived`, `returnReplyBody`, reset. |
| file | ✅ | Consumer: `noop` (idempotent), `delete`, `move`/`moveFailed`/`preMove` with file-language expressions, include/exclude/ant filters, `recursive`, depth, sorting, read locks (`changed` follows Camel: marker file, two equal checks or `readLockMinAge`, `readLockMinLength`, `readLockTimeout`), idempotent repositories, done files. Producer: `fileName` expressions, `fileExist` (Override/Append/Fail/Ignore/Move/TryRename), temp files, done files, `CamelFileNameProduced`. |
| controlbus | ✅ | Route actions (start/stop/suspend/resume/restart/status/stats/fail) and `language:` scripts. |
| bean / class, ref, language, browse, exec, stream, dataset/dataset-test/test, dataformat | ✅ | `exec` runs local processes. `stream` handles stdin/stdout/stderr/files. |
| platform-http (aliases jetty, undertow, netty-http) | ✅ | HTTP/1.1 server: path parameters, `matchOnUriPrefix`, `httpMethodRestrict` (405), chunked encoding, keep-alive, `muteException`. Streaming: stream-handle (`cameleer_tls::stream_body`) response bodies are sent chunked without buffering; `disableStreamCache=true` passes request bodies as stream handles read lazily off the connection. `CamelHttpResponseCode` sets the status. A failure is a 500 carrying the exception text. A handled exception is a 200 with the handled body. HTTPS: `jetty:https://`/`undertow:https://`/`netty-http:https://`, and `platform-http` with `ssl=true`, `sslContextParameters` or `camel.server.ssl*` properties. Mutual TLS with `needClientAuth=true` / `clientAuth=NONE|WANT|REQUIRE` (or `clientAuthentication` in the parameters); the verified client certificate is exposed as headers `CamelHttpSslClientCert` (leaf PEM), `CamelHttpSslClientCertSubjectName`, `CamelHttpSslClientCertIssuerName`, `CamelHttpSslClientCertSerialNo`, `CamelHttpSslClientCertNotBefore`, `CamelHttpSslClientCertNotAfter`. |
| http | ✅ | HTTP/1.1 and HTTP/2 client (`httpVersion=HTTP/2`: cameleer-grpc's HTTP/2 stack, TLS + ALPN `h2` or h2c prior knowledge, one multiplexed connection per target); pooled keep-alive HTTP/1.1 connections (`connectionsPerRoute`, `connectionClose`, stale connections retried); content coding (`Accept-Encoding: gzip, deflate` and transparent response decoding unless `contentCompressionDisabled=true`, request bodies compressed when `Content-Encoding` is gzip/deflate); `httpMethod`, `throwExceptionOnFailure`, `okStatusCodeRange`, timeouts, redirects, Basic auth, `bridgeEndpoint`, `CamelHttpMethod/Path/Query/Uri` headers, `HttpOperationFailedException` with status code and response body. `https` with SNI and host name verification (`sslContextParameters`, `useGlobalSslContextParameters`; client certificates from the parameters' key store), TLS session resumption per host:port, proxies (`proxyHost`/`proxyPort`/`proxyAuthUsername`, `useSystemProperties=true` for `HTTPS_PROXY`/`HTTP_PROXY`/`NO_PROXY`) with `CONNECT` tunnelling for https. Streaming bodies (`cameleer_tls::stream_body` handles, as `Value` has no stream variant): a stream-handle body is sent with chunked transfer coding straight from its reader (e.g. an `ftp` `streamDownload` file), `disableStreamCache=true` returns the response as a lazily decoded stream handle (Content-Length / chunked / until-close) instead of a byte array; consumers (`platform-http` & co.) send stream-handle response bodies chunked and, with `disableStreamCache=true`, pass request bodies as stream handles read off the connection. Remaining gaps: streamed bodies are not content-(de)compressed and HTTP/2 materialises them. |
| https / TLS | ✅ | `cameleer-tls`: std-only TLS 1.3/1.2 client and server (interop-tested against OpenSSL, incl. the `https` producer against `openssl s_server`), `NetStream` (cloneable plain/TLS socket for full-duplex components), SASL PLAIN/SCRAM helpers. Used by http/https, platform-http, netty, ftps, smtps/pop3s/imaps + STARTTLS, wss, mllp, syslog, kafka, paho, rabbitmq (amqps), stomp/jms and PostgreSQL. Mutual TLS in TLS 1.3 and 1.2 (client and server, interop-tested with `openssl s_server -Verify` / `s_client -cert`), TLS 1.3 PSK resumption and TLS 1.2 session tickets/IDs (interop-tested with `s_client -sess_out/-sess_in` and `s_server`), Ed25519 certificates, CRL revocation checks, PKCS#12/JKS/JCEKS key stores (fixtures from `openssl pkcs12` and `keytool`). Side-channel hardening: AES SubBytes is bitsliced (GF(2^8) inversion + affine map on eight 16-bit planes, no secret-indexed tables, also in the key schedule and the inverse cipher), branch-free GF multiplications; RSA private operations use base blinding (r^e / r^-1 pair squared per use), the CRT when PKCS#1 parameters are present, and verify every result before release. OCSP (`cameleer_tls::ocsp`): response parsing and validation (issuer or delegated OCSPSigning responder signature, SHA-1/SHA-256 CertID, thisUpdate/nextUpdate with skew, good/revoked/unknown) and stapling via `status_request`: clients request it with `OcspMode::Request` (validate when stapled) / `Require` (fail without a good response; `TlsStream::ocsp_response()`), servers staple `ocsp_response(der)` in the TLS 1.3 leaf certificate entry or a TLS 1.2 CertificateStatus — interop-tested with `openssl ocsp` responses, `s_server -status_file` and `s_client -status`. TLS 1.3 0-RTT (opt-in): servers advertise `early_data(max)` in tickets and accept early data only for the first PSK identity without HelloRetryRequest, with a ticket age inside the anti-replay window (`early_data_window`, default 10 s) and a PSK binder not seen before in that window (rejected early data is skipped); clients send it with `TlsStream::connect_with_early_data` (EndOfEarlyData, automatic resend after the handshake when rejected, `early_data_accepted()`) — interop-tested with `openssl s_client -early_data`. Remaining gaps: no OCSP fetching from responders (stapled responses only; servers must refresh theirs via `set_ocsp_response`), the 0-RTT replay cache is per server configuration (not shared across processes), our client is not interop-tested against `s_server -early_data`; no DTLS. |
| rest (REST DSL) | ✅ | Verbs, path/query parameters, `bindingMode` off/auto/json, CORS, OpenAPI 3 document, `scheme("https")` / `scheme: https` (TLS consumers), rest producer to `https://` hosts. No XML binding, no `clientRequestValidation`. |
| netty (tcp/udp) | ✅ | Text line and raw codecs, sync request/reply. TCP TLS with `ssl=true` (`sslContextParameters`, `keyStoreFile`/`trustStoreFile` as PEM, PKCS#12 or JKS with `passphrase` and `keyStoreFormat`, `hostnameVerification`), `needClientAuth=true` with the client certificate as `CamelNettySSLClientCertSubjectName`/`IssuerName`/`SerialNo`/`NotBefore`/`NotAfter` headers; no DTLS. |
| sql | ✅ | `cameleer-sql`. Producer: `:#name` (body map, headers, properties), `:#${simple}`, `:#in:name`, `?`/`#` positional (body array or `separator`-split string), `outputType` SelectList/SelectOne/StreamList, `outputHeader`, `noop`, `batch`, `useMessageBodyForSql`, `parametersCount`, `placeholder`, `CamelSqlQuery`, generated keys (`CamelSqlRetrieveGeneratedKeys` → `CamelSqlGeneratedKeysRows`), `file:`/`classpath:` queries. Consumer: one exchange per row or a list (`useIterator`), `onConsume`/`onConsumeFailed`/`onConsumeBatchComplete`, `maxMessagesPerPoll`, `routeEmptyResultSet`, `transacted`, scheduled poll options. StreamList is materialized as a list; `outputClass` is ignored (rows are maps). |
| jdbc | ✅ | `cameleer-sql`. SQL from the body, `outputType`, `useHeadersAsParameters` (`:?name`), `readSize`/`statement.maxRows`, `CamelJdbcRowCount`/`UpdateCount`/`ColumnNames`, `CamelGeneratedKeysRows`. `resetAutoCommit=false` is accepted but statements outside a JDBC transaction policy still auto-commit. |
| DataSources: embedded `rustsql` engine, PostgreSQL client | ✅ | `cameleer-sql`. `jdbc:rustsql:mem:<name>`: in-memory SQL engine (DDL incl. `ALTER TABLE` ADD/DROP/RENAME COLUMN, RENAME TO, SET/DROP DEFAULT, SET/DROP NOT NULL, TYPE, ADD/DROP CONSTRAINT (primary key / unique), multi-row INSERT/RETURNING, INNER/LEFT/RIGHT/FULL OUTER/CROSS joins, GROUP BY/HAVING, subqueries, UNION, `WITH [RECURSIVE]` common table expressions (column lists, chained CTEs, UNION / UNION ALL recursion), window functions (`ROW_NUMBER`, `RANK`, `DENSE_RANK`, `PERCENT_RANK`, `CUME_DIST`, `NTILE`, `LAG`, `LEAD`, `FIRST_VALUE`, `LAST_VALUE`, `NTH_VALUE` and aggregates `OVER (PARTITION BY .. ORDER BY ..)` with the default RANGE frame; ranking over grouped rows; explicit frame clauses are accepted and ignored), transactions with undo-log rollback, read-uncommitted isolation, stored procedures and functions: `CREATE [OR REPLACE] PROCEDURE/FUNCTION` with IN/OUT/INOUT parameters and defaults, `RETURNS` scalar/`SETOF`/`TABLE(...)`/`void`/`record`, `LANGUAGE sql` bodies or a PL/pgSQL subset — `DECLARE`, `:=`, `IF/ELSIF/ELSE`, `WHILE`, `LOOP`, `FOR` over ranges and query results, labels, `EXIT`/`CONTINUE`, `RETURN`/`RETURN NEXT`/`RETURN QUERY`, `RAISE ... USING ERRCODE`, `SELECT ... INTO [STRICT]`, `RETURNING ... INTO`, `PERFORM`, `FOUND`, `GET DIAGNOSTICS`, `EXCEPTION WHEN` handlers — `CALL` (OUT values as a row), `SELECT fn(...)`, `SELECT * FROM fn(...)`, `DO` blocks, `generate_series`; no overloading, cursors, triggers or transaction control inside procedures). The embedded PostgreSQL test server exposes procedures and functions over the wire. `jdbc:postgresql://host:port/db`: wire protocol v3 client (cleartext/MD5/SCRAM-SHA-256, simple + extended query, text format, pooled, TLS via SSLRequest with `sslmode=prefer|require|verify-ca|verify-full`, `ssl=true`, `sslrootcert`, client certificates with `sslcert`/`sslkey` (PEM or DER PKCS#8, encrypted with `sslpassword`) or a PKCS#12 `sslkey`); no COPY or binary format. `camel.datasource[.<name>].url` properties in cameleer-main. Transactions: `JdbcTransactionPolicy` via `.policy(...)` (the core `transacted()` uses `cameleer_core::transaction` managers; cameleer-sql does not register one). |
| JDBC idempotent / aggregation repositories | ✅ | `cameleer-sql`. `JdbcIdempotentRepository` (`CAMEL_MESSAGEPROCESSED`), `JdbcAggregationRepository` (JSON exchange snapshots, `<name>_completed` table, manual `scan`/`recover`, no background recovery). |
| sql-stored | ✅ | `cameleer-sql` (`sql_stored`). Camel template syntax `NAME(INTEGER ${headers.num1}, INTEGER :#num2, INOUT INTEGER ${header.x} x, OUT INTEGER resultofsub)` (optional `IN`, quoted parameter / type names, `DECIMAL(10)` scale, dotted or numeric `java.sql.Types`; value sources: Simple expressions, `:#name` (body map, header, property, variable), `:#${simple}`, literals; IN values converted to the SQL type). Calls `CALL name(?, ?, NULL)` or, with `function=true`, `SELECT * FROM name(?, ?)` (the first OUT template parameter names the return value). Result: OUT/INOUT values as a map body (or `outputHeader`), result sets (set-returning functions, procedures selecting rows on the embedded engine) per `outputType` SelectList/SelectOne (`#result-set-1` in the map when both), header `CamelSqlStoredUpdateCount`, `CamelSqlStoredTemplate` header override. Options `dataSource`, `function`, `outputType`, `outputHeader`, `noop`, `batch` (one call per body element, one transaction), `useMessageBodyForTemplate`, `templateOptions.*`, `file:`/`classpath:` templates; honours JDBC transaction policies. Works with the embedded engine and over the PostgreSQL protocol. Over the wire, `CALL` command tags carry no row count (update count 0 for procedures without OUT parameters). |
| spring-rabbitmq / rabbitmq (AMQP 0-9-1) | ✅ | `cameleer-amqp`, own AMQP 0-9-1 client: PLAIN auth, vhosts, heartbeats, frame-max, publisher confirms, `basic.qos`, ack/nack/reject. Options `routingKey`, `queues`/`queue`, `autoDeclare`/`declare`, `exchangeType` (direct/topic/fanout/headers), `concurrentConsumers`, `acknowledgeMode` (AUTO with `maximumRetryAttempts`/`retryDelay`, MANUAL, NONE) / `autoAck`, `prefetchCount`, `deadLetterExchange`/`Queue`/`RoutingKey`, `rejectAndDontRequeue`, `confirm`/`publisherAcknowledgements`, `guaranteedDeliveries`, `arg.queue.*` args; InOut request/reply over a temporary reply queue (`replyTimeout`/`requestTimeout`). Headers `CamelRabbitmqRoutingKey`, `CamelRabbitmqExchangeName`, `CamelRabbitmqDeliveryTag`, `CamelRabbitmqRequeue`, `CamelSpringRabbitmqRoutingOverrideKey`, properties as `CamelRabbitmq*`. Connection from uri/`camel.component.*`/`spring.rabbitmq.*` properties instead of a `connectionFactory` bean. TLS (`amqps://` addresses, `sslProtocol`, `spring.rabbitmq.ssl.enabled`, `spring.rabbitmq.ssl.key-store`/`key-store-password`/`key-store-type`/`trust-store`/`trust-store-password`/`trust-store-type` for client certificates and trust, `sslContextParameters`). Embedded test broker `testing::AmqpBroker` (optionally TLS). No tx class, no streams/quorum-queue features. |
| stomp | ✅ | `cameleer-amqp`, own STOMP 1.2 client: `brokerURL`, `login`/`passcode`, `host`, receipts, heart-beats; STOMP headers map to Camel headers. TLS with `ssl://`/`stomp+ssl://`/`stomps://` broker urls or `sslContextParameters`. Embedded test broker `testing::StompBroker` (optionally TLS). |
| jms / activemq / amqp-stomp (JMS over STOMP) | ✅ | `cameleer-amqp` (the STOMP flavour formerly registered as `amqp`; `amqp` is now AMQP 1.0, see below). JMS semantics on STOMP 1.2 (ActiveMQ/Artemis/RabbitMQ STOMP): `jms:queue:`/`topic:`/`temp-queue:`, `brokerURL` (or `camel.component.<scheme>.brokerUrl`), `concurrentConsumers`, `selector` (SQL-92 JMS selector, evaluated by the broker), `replyTo`, `replyToType` (`Temporary` temporary queue per producer, `Shared` per-request `JMSCorrelationID` selector on the shared queue - the default with `replyTo` -, `Exclusive` one router on the fixed queue), `useMessageIDAsCorrelationID` (consumers answer with the request's `JMSMessageID`; producers wait on a private temporary queue since STOMP brokers assign message ids), `requestTimeout`, `disableReplyTo`, `deliveryPersistent`/`deliveryMode`, `timeToLive`, `priority`, `preserveMessageQos`, `transacted` (STOMP BEGIN/COMMIT/ABORT, rollback redelivers with `JMSRedelivered=true`), `acknowledgementModeName`; durable topic subscriptions (`durableSubscriptionName`, or `subscriptionName` + `subscriptionDurable`, with `clientId`: ActiveMQ `activemq.subscriptionName` / Artemis `durable-subscription-name` headers; stopping detaches, messages are kept), JMS 2.0 shared subscriptions (`subscriptionShared=true` + `subscriptionName`, durable or not), MapMessage (map bodies or `jmsMessageType=Map`) and ObjectMessage (`jmsMessageType=Object`) as JSON with ActiveMQ's `transformation: jms-map-json` / `jms-object-json` header, mapped back to structured bodies on receipt; InOut request/reply with `JMSCorrelationID`; `JMS*` headers. XA cannot be done over STOMP (no two-phase commit): `transactionManager` is accepted and ignored, local `transacted` transactions plus idempotent consumers are the emulation. Embedded `testing::StompBroker`: durable and shared subscriptions, and a file journal (`persistence(dir)`) that recovers persistent queue messages, durable subscriptions and their messages after a restart (unacknowledged deliveries come back with `redelivered:true`). Not the OpenWire or AMQP 1.0 wire protocols. On Apache ActiveMQ 5 (which neither redelivers after an aborted transaction nor after a NACK - a poison ack) failed transacted / `CLIENT_ACKNOWLEDGE` messages are redelivered by the consumer like ActiveMQ's JMS client (`jms.redeliveryPolicy.maximumRedeliveries` / `initialRedeliveryDelay` / `redeliveryDelay` broker-url options, `JMSXDeliveryCount`, then NACK → DLQ); InOnly sends from a transacted consumer to the same broker join its transaction (all brokers); `subscriptionShared` is refused on ActiveMQ 5 (use virtual topics). Interop-verified against ActiveMQ 5.17.6 and the RabbitMQ 3.12 STOMP plugin ([INTEROP.md](https://pmsudhi.github.io/cameleer/docs/INTEROP.html)); embedded broker flavours `StompBrokerBuilder::activemq()` / `rabbitmq()`. |
| amqp (AMQP 1.0 client) | ✅ | `cameleer-amqp10`, own OASIS AMQP 1.0 stack: full type system (all primitives, described types, list/map/array encodings), protocol header negotiation, SASL ANONYMOUS/PLAIN/EXTERNAL/SCRAM-SHA-256/512 (cameleer-tls `sasl`), open/begin/attach/flow/transfer/disposition/detach/end/close, sessions with incoming/outgoing windows, sender/receiver links with credit (auto top-up or manual, drain), at-most-once (pre-settled) and at-least-once settlement, outcomes accepted/rejected/released/modified, multi-frame transfers split by max-frame-size, all message sections (header, delivery/message annotations, properties, application-properties, data/amqp-value/amqp-sequence, footer), idle timeout + heartbeats, dynamic nodes, TLS (`amqps`), CBS `put-token` and management request/response. Not implemented: transactions (coordinator), `rcv-settle-mode=second` (accepted but settled as first), link resume/unsettled-state recovery, peer-initiated sessions/links, the AMQP TLS-layer header (`AMQP 2`, use `amqps`), WebSockets. |
| amqp | ✅ | `cameleer-amqp10`, Camel's AMQP component (JMS over AMQP 1.0 for Artemis/ActiveMQ/Qpid): `amqp:queue:`/`topic:`/`temp-queue:`, connection from `remoteAddress` (aliases `remoteURI`/`brokerURL`/`connectionFactory.remoteURI`, or `host`+`port`, also as `camel.component.amqp.*`) or a connection-factory bean (`connectionFactory=#bean` / `camel.component.amqp.connectionFactory`, `jms::AmqpConnectionFactory` with remote URI, credentials, client id, SASL mechanism, idle timeout and `SslContextParameters`), `amqps://` or `sslContextParameters`, `amqpws://`/`amqpwss://` (AMQP over WebSockets), `username`/`password`, `saslMechanism`, `clientId`, `concurrentConsumers`, `prefetchSize`, `selector` (`apache.org:selector-filter:string`), `replyTo`, `requestTimeout`, `disableReplyTo`, `deliveryPersistent`/`deliveryMode`, `timeToLive`, `priority`, `preserveMessageQos`, `acknowledgementModeName` (CLIENT: failures are returned with `modified(delivery-failed)` → `JMSRedelivered`), `transacted`/`SESSION_TRANSACTED` with real AMQP local transactions (coordinator link, declare/discharge, transactional dispositions and transfers: acknowledgement and reply commit together, a failure rolls back and the broker redelivers; transacted producers send in a transaction), `jmsMessageType` (Text/Bytes/Map/Object - ObjectMessage as an AMQP typed value, `x-opt-jms-msg-type=1`, so structured bodies round-trip), durable topic subscriptions (`durableSubscriptionName`/`subscriptionDurable`), JMS 2.0 shared subscriptions (`subscriptionShared` + `subscriptionName`, Qpid JMS link naming with the `shared`/`global` capabilities), `includeAmqpAnnotations` (`JMS_AMQP_MA_*`), `CamelJmsDestinationName`; InOut over a dynamic temporary queue or fixed `replyTo`. AMQP JMS mapping: `JMSMessageID`/`JMSCorrelationID`/`JMSDestination`/`JMSReplyTo`/`JMSType`/`JMSTimestamp`/`JMSExpiration`/`JMSDeliveryMode`/`JMSPriority`/`JMSRedelivered`/`JMSXDeliveryCount`/`JMSXUserID`/`JMSXGroupID`/`JMSXGroupSeq`, `x-opt-jms-msg-type`/`-dest`/`-reply-to`, properties with `_DOT_`/`_HYPHEN_` keys. Client also offers `rcv-settle-mode=second` and AMQP over WebSockets (RFC 6455, `AMQPWSB10`). Embedded test broker `testing::Amqp10Broker` (queues, topics, selectors, credit, dispositions, transactions, shared subscriptions, settle mode second, WebSockets, SASL, TLS). Node address prefixes announced by the broker (`queue-prefix` / `topic-prefix`, ActiveMQ 5: `queue://` / `topic://`) are applied as Qpid JMS does and stripped from `JMSDestination` / `JMSReplyTo` (topics as `topic:name`); `subscriptionShared` is refused on ActiveMQ 5; `CAMEL_AMQP10_TRACE=1` traces every frame to stderr. Interop-verified against the RabbitMQ 3.12 AMQP 1.0 plugin and Apache ActiveMQ 5.17.6's AMQP transport by the live suite ([INTEROP.md](https://pmsudhi.github.io/cameleer/docs/INTEROP.html)); an extra `#[ignore]`d test targets any broker via `AMQP10_INTEROP_URL`. Not implemented (outside Camel's option set): link recovery with unsettled-state resume and peer-initiated links. |
| azure-servicebus | ✅ | `cameleer-amqp10`, over AMQP 1.0 with tokens put on `$cbs` (refreshed at 80 % of their lifetime). `connectionString` (incl. `UseDevelopmentEmulator=true` → plain AMQP like the Service Bus emulator; `amqps` otherwise) or `fullyQualifiedNamespace` + `sharedAccessName`/`sharedAccessKey`; `credentialType` `CONNECTION_STRING`, `AZURE_IDENTITY` (client secret from `tenantId`/`clientId`/`clientSecret`/`authorityHost` - Cameleer options - or the `AZURE_*` environment, managed identity via IMDS / `IDENTITY_ENDPOINT`+`IDENTITY_HEADER` or `managedIdentityEndpoint`; Azure AD `jwt` tokens) or `TOKEN_CREDENTIAL` (`tokenCredential=#bean`, `identity::TokenCredential`); `amqpTransportType=AMQP_WEB_SOCKETS` (AMQP over WebSockets on 443, `/$servicebus/websocket`); `serviceBusType` queue/topic, `subscriptionName`, `receiveMode` PEEK_LOCK (complete on success, abandon → redelivery with delivery count / MaxDeliveryCount dead-lettering on failure, `enableDeadLettering` dead-letters with reason `ProcessingError`, `disableAutoComplete`) or RECEIVE_AND_DELETE, `subQueue=DEAD_LETTER_QUEUE`, `consumerOperation` receiveMessages/peekMessages (`peekNumMaxMessages`), sessions (`sessionEnabled`, `sessionId`, `maxConcurrentCalls` session workers accepting the next available session, Cameleer `sessionIdleTimeout`; session state through the Cameleer producer operations `getSessionState`/`setSessionState`), automatic message and session lock renewal while processing (`maxAutoLockRenewDuration`, `com.microsoft:renew-lock` / `renew-session-lock`), deferral (Cameleer header `CamelAzureServiceBusDisposition` = complete/abandon/deadLetter/defer; producer operation `receiveDeferredMessages` by sequence number), `producerOperation` sendMessages (list bodies → one message per element; Cameleer `transacted=true` sends them in one AMQP transaction)/scheduleMessages (`scheduledEnqueueTime`, `com.microsoft:schedule-message`), `prefetchCount`, `binary`. Headers `CamelAzureServiceBusMessageId`, `...CorrelationId`, `...ContentType`, `...Subject`, `...To`, `...ReplyTo`, `...SessionId`, `...PartitionKey`, `...ApplicationProperties`, `...EnqueuedTime`, `...SequenceNumber`, `...DeliveryCount`, `...LockToken`, `...LockedUntil`, `...ExpiresAt`, `...TimeToLive`, `...DeadLetterReason`/`ErrorDescription`/`Source`, `...ScheduledEnqueueTime`, `...ProducerOperation`, `...SessionState` (times as epoch millis). Embedded emulator: `Amqp10Broker::builder().azure(keyName, key)` (+ `azure_jwt`, `session_entity`). Java-only objects (`processorClient`, `serviceBusTransactionContext`...) are not applicable. |
| azure-eventhubs | ✅ | `cameleer-amqp10`, over AMQP 1.0 with SAS or Azure AD tokens on `$cbs` (same `credentialType` / `tokenCredential` / `amqpTransportType` options and token refresh as azure-servicebus, scope `https://eventhubs.azure.net/.default`). `azure-eventhubs:namespace/eventHubName` with `sharedAccessName`/`sharedAccessKey` or `connectionString` (`EntityPath`), `consumerGroupName`, `partitionId`, `partitionKey` (header overrides `CamelAzureEventHubsPartitionId`/`...PartitionKey`), `prefetchCount`. Consumer discovers partitions via `$management` READ; checkpoints (offset + sequence number) to a `CheckpointStore` (`checkpointStore=#bean`; in-memory default, `FileCheckpointStore` with the blob checkpoint layout) every `checkpointBatchSize` events / `checkpointBatchTimeout`, resume from the last checkpoint, else `eventPosition` (per-partition map: `0=earliest,1=offset:42,2=sequenceNumber:7:inclusive,3=enqueuedTime:<millis>` or `#bean`), else `initialPosition` earliest/latest (Cameleer). Load balancing between processor instances through the checkpoint store's ownership records (`PartitionOwnership` with optimistic etags; balanced strategy: renew, relinquish surplus, claim unowned/expired, steal from instances above their share; Cameleer `loadBalancingUpdateInterval`, `partitionOwnershipExpirationInterval`, `ownerId`, `loadBalancing`), receivers with epochs (`com.microsoft:epoch`, `ownerLevel`, 0 for balanced receivers, so a new owner disconnects the old one; the emulator enforces epochs with `amqp:link:stolen`). Headers `CamelAzureEventHubsPartitionId`, `...Offset`, `...SequenceNumber`, `...EnqueuedTime`, `CamelMessageTimestamp`; application properties ↔ headers. Azure Blob checkpoint store: `blobAccountName` + `blobContainerName` + `blobAccessKey` (+ Cameleer `blobEndpoint`) select `cameleer_cloud::azure::blob_checkpoint::BlobCheckpointStore` when `cameleer_cloud::register` ran (factory looked up in the registry; an error otherwise); that store also keeps partition ownership like the Azure SDK (`<ns>/<hub>/<group>/ownership/<partition>` blobs with `ownerid` metadata, listed with `include=metadata`, claimed with `If-None-Match: *` / `If-Match: <etag>` so contested claims fail with 412/409), so blob-backed instances balance partitions between them (verified against the Azurite emulator, `cameleer-cloud/tests/azure_tail.rs`). |
| grpc | ✅ | `cameleer-grpc`, own HTTP/2 (RFC 9113, HPACK, flow control, h2c prior knowledge and TLS + ALPN `h2` via cameleer-tls) and gRPC stack; services and messages come from `protoFile` at runtime (raw bytes without it). Producer: `method`, `producerStrategy` SIMPLE (unary → response object, server streaming → array, client streaming/bidi from an array body) or STREAMING (long-lived call, `CamelGrpcEventType=onCompleted` half-closes), `streamRepliesTo`, `deadline` (grpc-timeout), headers → metadata, response metadata → headers, failures as `StatusRuntimeException` (`CODE: message`). Consumer: hosts the service, `consumerStrategy` AGGREGATION/PROPAGATION (DELEGATION ≈ PROPAGATION), `forwardOnCompleted`/`forwardOnError`, `CamelGrpcMethodName`/`CamelGrpcEventType`/`CamelGrpcUserAgent` headers, metadata → headers, exceptions → status codes (IllegalArgument → INVALID_ARGUMENT, Timeout → DEADLINE_EXCEEDED, UnsupportedOperation → UNIMPLEMENTED, other → INTERNAL), server-side deadline enforcement, gzip/deflate request decompression. TLS: `usePlainText=false`/`negotiationType=TLS` with `keyCertChainResource`/`keyResource` (consumer) and `trustCertCollectionResource` (producer). Also `maxMessageSize`, `maxConcurrentCallsPerConnection`, `flowControlWindow`. Interop-tested with curl (nghttp2) and Go `net/http`. Mutual TLS (producer `keyCertChainResource`/`keyResource` client certificate, consumer `trustCertCollectionResource` requires client certificates), interceptors (`clientInterceptors`/`serverInterceptors` beans, `autoDiscoverClientInterceptors`/`autoDiscoverServerInterceptors`: add/inspect metadata, reject calls with a status), `compression=gzip|deflate` for requests (producer) and responses (consumer, when accepted by the client). Authentication (`authenticationType`): `JWT` (producer sends an HMAC256/384/512-signed bearer JWT from `jwtSecret` / `jwtIssuer` / `jwtSubject`; the consumer verifies signature, algorithm, expiry and issuer/subject, else UNAUTHENTICATED) and `GOOGLE` (service-account JWT access tokens: RS256 self-signed JWT with audience `https://<host>/<service>` from the `serviceAccountResource` JSON key, cached until 5 minutes before expiry). `routeControlledStreamObserver=true`: routes answer through a `ResponseObserver` (`cameleer_grpc::component::response_observer(&exchange)`, property `CamelGrpcResponseObserver`) with `on_next` / `on_completed` / `on_error`. HTTP/1.1 `Upgrade: h2c` (RFC 7540 3.2): consumers accept upgrade requests (101, `HTTP2-Settings` applied, the request served as stream 1) besides prior knowledge; producers with `negotiationType=PLAINTEXT_UPGRADE` upgrade (`H2Connection::connect_upgrade`). Remaining gaps: Google auth uses self-signed JWT access tokens only (no OAuth2 token exchange / scopes); no JWT verification for `GOOGLE` on the consumer side. The HTTP/2 client/server (`cameleer_grpc::h2`) are public for reuse. |
| thrift | ✅ | `cameleer-dataformats` (`thrift_rpc`), driven by the runtime IDL (`idlFile`/`schema`) instead of generated classes: `thrift://host:port/[pkg.]Service?method=..`. Producer: body = argument list (or object by name / single value), `CamelThriftMethodName` header, result = return value, declared exceptions fail with the exception struct name (struct in `CamelThriftException`), `TApplicationException`s, `oneway` calls, inherited service methods, `clientTimeout`, persistent connection with reconnect. Consumer: Thrift server, body = argument list + `CamelThriftMethodName`, return value from the body, declared exceptions from the exception kind or an `@exception` body, `INTERNAL_ERROR`/`UNKNOWN_METHOD`/`PROTOCOL_ERROR` application exceptions. `exchangeProtocol` BINARY (strict messages; old-style accepted) / COMPACT / JSON, `transport` FRAMED or BUFFERED (servers detect both), `compressionType` NONE/ZLIB (TZlibTransport sync-flushed stream), `negotiationType` PLAINTEXT/SSL (`sslContextParameters`). |
| Other cloud components | ✅ | All of Apache Camel's AWS / Azure / GCP components are implemented, including `google-pubsub-lite` (see its row); services without a Camel component (AWS Glue, SageMaker, Lex, Cognito, Neptune, Azure Cognitive Services / Monitor / Data Explorer, GCP Dataflow / Dataproc / Spanner / Bigtable...) are out of scope, as is the long tail of the 300+ non-cloud vendor connectors. Remaining gaps inside implemented components are listed in their rows. Implemented in `cameleer-cloud` (rows below): S3, SQS (JSON + Query protocol), SNS, DynamoDB (+ expressions) and DynamoDB Streams, Lambda, Kinesis, Firehose, EventBridge, Secrets Manager (+ refresh / context reload), SES, CloudWatch, STS, Step Functions, IAM, EC2, MSK (+ Kafka `AWS_MSK_IAM`), Athena, Textract, Translate, Comprehend, Polly, Rekognition, Transcribe, Bedrock (+ Agent Runtime), MQ, ECS, EKS, KMS, Timestream, CloudTrail, Config, Redshift Data; Azure Blob (+ change feed, Event Hubs blob checkpoint store) / Queue / Data Lake / Files, Key Vault (secrets, keys, certificates), Cosmos DB, Functions, Event Grid, Schema Registry, OpenAI; Cloud Storage (+ V4 signed URLs), Pub/Sub (REST + gRPC streaming pull, dead-letter policies, exactly-once acks), Pub/Sub Lite (gRPC), BigQuery (+ load / extract jobs), Secret Manager, Cloud Functions, Firestore, Sheets (+ `google-sheets-stream`), Gmail (+ `google-mail-stream`), Calendar (+ `google-calendar-stream`), Drive (+ file-change consumer), Vertex AI, Speech-to-Text, Text-to-Speech, OAuth refresh-token user credentials; Service Bus / Event Hubs live in `cameleer-amqp10`; elsewhere Kafka, JMS/AMQP, SQL/JDBC, FTP, Mail, MQTT, WebSocket, gRPC and SFTP/SSH. |
| aws2-s3 | ✅ | `cameleer-cloud`, S3 REST API over the std-only HTTPS client, SigV4-signed. Producer operations (`operation` / `CamelAwsS3Operation`, default putObject): putObject, getObject, getObjectRange, headObject, listObjects, deleteObject, copyObject, listBuckets, createBucket, deleteBucket, headBucket, createDownloadLink (presigned URL). `multiPartUpload=true` + `partSize` (default 25 MiB): multipart upload (aborted on failure). Streaming (Cameleer headers): `CamelAwsS3SourceFile` uploads a local file without loading it (streamed `UNSIGNED-PAYLOAD` PUT, or multipart reading one part at a time), `CamelAwsS3DownloadFile` streams getObject into a file. `streamingUploadMode` (aggregates exchanges into multipart objects; `batchMessageNumber`, `batchSize`, `streamingUploadTimeout`, `namingStrategy` progressive/random, `restartingPolicy` override/lastPart; pending object completed on stop). Polling consumer (`prefix`, `delimiter`, `fileName`, `maxMessagesPerPoll`, `includeBody`, `includeFolders`, `deleteAfterRead` default true, `moveAfterRead` + `destinationBucket[Prefix/Suffix]`) with `CamelAwsS3Key`/`BucketName`/`ETag`/`ContentLength`/`LastModified`/`ContentType`/`VersionId`/`Metadata` headers. `autoCreateBucket`, `keyName`, `storageClass`, `forcePathStyle` (virtual-host style otherwise). Common AWS options: `accessKey`/`secretKey`/`sessionToken`/`region`, `useDefaultCredentialsProvider` (env vars, `~/.aws/credentials` profiles, ECS/EKS container credentials endpoint, EC2 instance metadata IMDSv2/v1; cached until expiry), `uriEndpointOverride` + `overrideEndpoint`, `proxyHost`/`proxyPort`/`proxyProtocol` (or `HTTPS_PROXY`/`NO_PROXY`), `trustAllCertificates`. Also deleteObjects, createUploadLink, restoreObject, object tagging / ACL operations, object lock (retention, legal hold), versioning (putBucketVersioning, getBucketVersioning, listObjectVersions, `CamelAwsS3VersionId`), SSE-KMS (`useAwsKMS`/`awsKMSKeyId`), SSE-S3 (`useSSES3`) and SSE-C (`useCustomerKey`/`customerKeyId`/`customerKeyMD5`/`customerAlgorithm`), canned ACLs / content headers / tags / `conditionalWritesEnabled` on putObject; consumer `ignoreBody` (HEAD only) and Cameleer `localDirectory` (objects streamed to disk, not buffered). Web identity credentials (`AWS_WEB_IDENTITY_TOKEN_FILE` + `AWS_ROLE_ARN` via STS AssumeRoleWithWebIdentity) for all AWS components. Verified against the SigV4-verifying emulator (`tests/aws_gaps.rs`). |
| aws2-sqs | ✅ | `cameleer-cloud`, SQS AWS JSON 1.0 protocol. Producer: sendMessage (user headers → message attributes, `delaySeconds`, FIFO `messageGroupIdStrategy`/`messageDeduplicationIdStrategy`), sendBatchMessage, deleteMessage, listQueues, purgeQueue, deleteQueue. Consumer: `maxMessagesPerPoll`, `waitTimeSeconds` (long polling), `visibilityTimeout`, `messageAttributeNames`, `attributeNames`, `deleteAfterRead` (failed messages are redelivered after the visibility timeout); headers `CamelAwsSqsMessageId`, `CamelAwsSqsReceiptHandle`, `CamelAwsSqsMD5OfBody`, `CamelAwsSqsAttributes`, `CamelAwsSqsMessageAttributes` + one header per attribute. `queueUrl`, `autoCreateQueue`, `queueOwnerAWSAccountId`. `extendMessageVisibility=true` (with `visibilityTimeout`) extends in-flight messages to 1.5× the timeout every timeout/2. `protocol` (Cameleer): `auto` (default: JSON, switching to the legacy Query protocol — form `Action=...&Version=2012-11-05`, XML responses — when the server rejects JSON), `json`, `query`. Also changeMessageVisibility, deleteMessageBatch, getQueueAttributes / setQueueAttributes, receiveMessage; queue attribute options (`defaultVisibilityTimeout`, `messageRetentionPeriod`, `maximumMessageSize`, `policy`, `redrivePolicy` dead-letter queues, `receiveMessageWaitTimeSeconds`, `delayQueue`, `serverSideEncryptionEnabled` + `kmsMasterKeyId` / `kmsDataKeyReusePeriodSeconds`); consumer `concurrentConsumers`, `maxMessagesPerPoll` > 10 (parallel receives, `concurrentRequestLimit`), `sortAttributeName`, `deleteIfFiltered`, `sendEmptyMessageWhenIdle`. |
| aws2-sns | ✅ | `cameleer-cloud`, SNS Query API, producer only: Publish with `subject`/`CamelAwsSnsSubject`, `messageStructure`, user headers as message attributes, FIFO group/dedup ids; `CamelAwsSnsMessageId`. Topic by ARN, `autoCreateTopic`, or ListTopics lookup. `subscribeSNStoSQS` + `queueArn` (SQS subscription at start, emulator delivers to the queue), `policy`, `serverSideEncryptionEnabled` + `kmsMasterKeyId`, FIFO topics with content-based deduplication, `batchEnabled` (PublishBatch). |
| aws2-ddb, aws2-ddbstream | ✅ | `cameleer-cloud`, DynamoDB JSON 1.0 producer: PutItem, GetItem, UpdateItem (AttributeUpdates PUT/DELETE or `CamelAwsDdbUpdateExpression`), DeleteItem, Query (KeyConditions or `CamelAwsDdbKeyConditionExpression`), Scan (ScanFilter), `CamelAwsDdbFilterExpression`, `...ConditionExpression`, `...ProjectionExpression` with `...ExpressionAttributeNames` / `...ExpressionAttributeValues` (plain values, marshalled), BatchGetItems (`CamelAwsDdbBatchItems` → `CamelAwsDdbBatchResponse`, `...UnprocessedKeys`), UpdateTable (`...ReadCapacity` / `...WriteCapacity`, Cameleer `CamelAwsDdbStreamViewType`), DescribeTable, DeleteTable with Camel `CamelAwsDdb*` headers and automatic attribute-value marshalling of plain maps; table created on start from `keyAttributeName`/`keyAttributeType`. `aws2-ddbstream://table` consumer over DynamoDB Streams (DescribeTable → stream ARN, DescribeStream incl. new child shards, GetShardIterator `streamIteratorType` FROM_LATEST / FROM_START / FROM_SEQUENCE_NUMBER + `sequenceNumberProvider`, GetRecords `maxResultsPerRequest`, expired iterator recovery); body = the record with unmarshalled Keys / NewImage / OldImage. The emulator evaluates the expression language (comparisons, BETWEEN, IN, AND/OR/NOT, attribute_exists/not_exists/type, begins_with, contains, size; SET with + / - / if_not_exists / list_append, REMOVE, ADD, DELETE). |
| aws2-lambda | ✅ | `cameleer-cloud`, Lambda REST producer with Camel's operation list: invokeFunction (default; `CamelAwsLambdaInvocationType`, function errors in `CamelAwsLambdaFunctionError`), listFunctions, getFunction, deleteFunction, createFunction (zip body or `CamelAwsLambdaS3Bucket`/`S3Key`, role, runtime, handler, memory, timeout, environment, tags, VPC, dead letter, tracing, KMS, publish), updateFunction (code), createEventSourceMapping / deleteEventSourceMapping / listEventSourceMapping, listTags / tagResource / untagResource, publishVersion / listVersions, createAlias / deleteAlias / getAlias / listAliases. |
| azure-storage-blob | ✅ | `cameleer-cloud`, Blob REST API with Shared Key signing (`accessKey`, `credentialType=SHARED_ACCOUNT_KEY`) or SAS (`credentialType=AZURE_SAS`, `sasToken`). Producer: listBlobContainers (default), createBlobContainer, deleteBlobContainer, listBlobs (`prefix`), uploadBlockBlob, getBlob, deleteBlob, append blobs (createAppendBlob, commitAppendBlob with `createAppendBlob`), page blobs (createPageBlob `pageBlobSize`, uploadPageBlob / clearPageBlob with `CamelAzureStorageBlobPageBlobRange`, resizePageBlob, getPageBlobRanges, `createPageBlob`), leases (Cameleer operations acquireBlobLease / renewBlobLease / releaseBlobLease / breakBlobLease, `CamelAzureStorageBlobLeaseId` sent on writes, `leaseBlob=true` + `leaseDurationInSeconds` lease around writes); consumer polling one blob (`blobName`) or the container, with `deleteAfterRead` (Cameleer extension). Headers `CamelAzureStorageBlobBlobName`, `...ContainerName`, `...ETag`, `...LastModified`, `...ContentType`, `...BlobSize`, `...Metadata`. Azurite-style `uriEndpointOverride`. Change feed: `getChangeFeed` (body = events, `changeFeedStartTime`/`EndTime` options or headers) and a change feed consumer (`changeFeed=true`, Cameleer; each event once, `CamelAzureStorageBlobChangeFeedEventType` / `...EventTime` / blob and container headers), reading `$blobchangefeed` segments and Avro chunk files (cameleer-dataformats). `credentialType=AZURE_IDENTITY`: Entra ID bearer tokens from a client secret, workload identity federation (`federatedTokenFile` / `AZURE_FEDERATED_TOKEN_FILE`) or managed identity (IMDS or App Service endpoint, user-assigned `managedIdentityClientId`), verified by the emulated token endpoints + Azurite. Block lists: stageBlockBlobList (`commitBlockListLater`), commitBlobBlockList, getBlobBlockList (`blockListType`); downloadLink (read-only service SAS, `downloadLinkExpiration`), downloadBlobToFile (`fileDir`), copyBlob (same account or `sourceBlobAccessKey`). |
| azure-storage-queue | ✅ | `cameleer-cloud`, Queue REST API (Shared Key or SAS). Producer: sendMessage (default; `visibilityTimeout`, `timeToLive`, `createQueue`), receiveMessages, peekMessages, deleteMessage, updateMessage, clearQueue, createQueue, deleteQueue, listQueues; consumer receives `maxMessages` and deletes processed messages. Headers `CamelAzureStorageQueueMessageId`, `...PopReceipt`, `...InsertionTime`, `...ExpirationTime`, `...TimeNextVisible`, `...DequeueCount`. Text sent as is (no base64), like the Azure SDK's default `QueueMessageEncoding.NONE`. `credentialType=AZURE_IDENTITY` (Entra ID client secret / workload identity / managed identity bearer tokens, verified against the emulated App Service identity endpoint + Azurite). `azure-servicebus`: see its row (`cameleer-amqp10`). |
| google-storage | ✅ | `cameleer-cloud`, Cloud Storage JSON API. Service account key (`serviceAccountKey` or `GOOGLE_APPLICATION_CREDENTIALS`) → RS256 JWT → OAuth2 token (cached until expiry, refreshed on 401). Producer: putObject (default upload), getObject, listObjects, deleteObject, copyObject, listBuckets, createBucket, deleteBucket; consumer with `deleteAfterRead` (default true), `moveAfterRead`/`destinationBucket`, `includeBody`, `prefix`; `autoCreateBucket` (default true). `CamelGoogleCloudStorage*` headers. createDownloadLink: V4 signed URLs (`GOOG4-RSA-SHA256`, `CamelGoogleCloudStorageDownloadLinkExpirationTime`). Resumable uploads (Cameleer `resumableUploadThreshold` default 16 MiB, `resumableChunkSize` in 256 KiB multiples; failed chunks resumed from the committed size). Credentials for all Google components: authorized-user files, workload identity federation (`external_account` files: file / url subject token sources, STS token exchange, optional service account impersonation via IAM Credentials `generateAccessToken`) and the metadata server (`useMetadataServer` / `GCE_METADATA_HOST` / Cameleer `metadataServerUrl`), all emulated. |
| google-pubsub | ✅ | `cameleer-cloud`, Pub/Sub REST (`google-pubsub://project:destination`). Producer publishes body (base64) with `CamelGooglePubsubAttributes` and `CamelGooglePubsubOrderingKey`, sets `CamelGooglePubsubMessageId` (list bodies → one message each). Consumer: synchronous pull (`maxMessagesPerPoll`), `ackMode` AUTO (ack on success, nack via modifyAckDeadline 0) or NONE; headers `CamelGooglePubsubMessageId`, `...Attributes`, `...AckId`, `...PublishTime`, `...OrderingKey`, `...DeliveryAttempt`. `authenticate=false` + `endpoint` for the emulator. That is the synchronous pull consumer (`synchronousPull=true`); by default (`synchronousPull=false`, as in Camel) the consumer uses **gRPC streaming pull** over cameleer-grpc HTTP/2 (`google.pubsub.v1.Subscriber/StreamingPull`, bearer token in metadata, `concurrentConsumers` streams, `ackDeadlineSeconds`, flow control `maxOutstandingMessages`/`maxOutstandingBytes`, ack / nack on the stream, lease extension up to `maxAckExtensionPeriod`, reconnect with backoff, `pubsubEndpoint` target). Dead-letter policies and exactly-once delivery: Cameleer producer operations `createTopic`, `deleteTopic`, `createSubscription` (`topic`, `deadLetterTopic` + `maxDeliveryAttempts` 5..100, `enableExactlyOnceDelivery`, `ackDeadlineSeconds`), `getSubscription`, `deleteSubscription`; the synchronous pull consumer extends leases while processing (`ackDeadlineSeconds / 3`, up to `maxAckExtensionPeriod`) and checks acknowledgements (transient `EXACTLY_ONCE_ACKID_FAILURE`s retried, permanent ones logged). The emulator forwards messages to the dead-letter topic after `maxDeliveryAttempts` deliveries and rejects expired ack ids on exactly-once subscriptions. On the gRPC streaming path exactly-once subscriptions (announced by `subscription_properties`) have their acks tracked until the stream's `acknowledge_confirmation`: temporarily failed ack ids are re-acknowledged, invalid (expired) ones logged and redelivered (counters: `pubsub_stream::exactly_once_stats`); the emulator sends the confirmations and forwards nacked streaming deliveries to the dead-letter topic after `maxDeliveryAttempts`. |
| google-pubsub-lite | ✅ | `cameleer-cloud`, Pub/Sub Lite gRPC over cameleer-grpc HTTP/2 (`google-pubsub-lite:projectId:location:destination`, bearer tokens of the common Google credentials, `pubsubEndpoint` for emulators, `{region}-pubsublite.googleapis.com` otherwise). Producer: `PublisherService/Publish` streams (partition by `CamelGooglePubsubLiteOrderingKey` hash or round robin over `AdminService/GetTopicPartitions`), attributes / event time headers, `CamelGooglePubsubLiteMessageId` = `partition:offset` (list bodies → several messages); Cameleer admin operations createTopic (`partitionCount`), createSubscription (`topic`), deleteTopic, deleteSubscription, getTopicPartitions. Consumer: per partition a `SubscriberService/Subscribe` stream from the committed cursor with flow control (`maxMessagesPerPoll`, `perPartitionBytes`, `streamIdleTimeout`), `ackMode` AUTO commits each processed offset with `CursorService/StreamingCommitCursor` (failures redelivered from the committed cursor) or NONE; `CamelGooglePubsubLite*` headers (message id, attributes, ordering key, publish time, partition, offset). Verified against the GcpMock gRPC emulator (`tests/gcp_gaps.rs`). Consumers poll (a stream per partition and poll) rather than keeping long-lived streams. |
| aws2-kinesis | ✅ | `cameleer-cloud`, Kinesis Data Streams AWS JSON 1.1. Producer: PutRecord (`CamelAwsKinesisPartitionKey` required, `CamelAwsKinesisSequenceNumber` for ordering; sets `CamelAwsKinesisSequenceNumber` / `CamelAwsKinesisShardId`), array bodies via PutRecords (`CamelAwsKinesisFailedRecordCount`); Cameleer `operation`: createStream (`shardCount`), describeStream, listShards, deleteStream. Consumer: ListShards each poll (picks up resharding), one shard iterator per shard (`iteratorType` TRIM_HORIZON / LATEST / AT_ / AFTER_SEQUENCE_NUMBER with `sequenceNumber` / AT_TIMESTAMP with `messageTimestamp`), `shardId`, `maxResultsPerRequest`, `shardClosed` ignore/silent/fail; headers `CamelAwsKinesisSequenceNumber`, `...PartitionKey`, `...ShardId`, `...ApproximateArrivalTimestamp`. KCL-style consumers (`useKclConsumers`, `applicationName`, `workerIdentifier`, `failoverTimeMillis`): DynamoDB lease table with conditional lease taking / renewal / failover, fair-share balancing between live workers, per-record checkpoints, parent-before-child resharding; enhanced fan-out (`enhancedFanOut`, `consumerName`: RegisterStreamConsumer + `SubscribeToShard` HTTP/2 event streams with continuation and child shards); `resumeStrategy` beans; `cborEnabled` (CBOR protocol). |
| aws2-kinesis-firehose | ✅ | `cameleer-cloud`, Firehose AWS JSON 1.1 producer: sendRecord (default, `CamelAwsKinesisFirehoseRecordId`), putRecordBatch (array bodies), createDeliveryStream (DirectPut), describeDeliveryStream, deleteDeliveryStream. No updateDestination. |
| aws2-eventbridge | ✅ | `cameleer-cloud`, EventBridge AWS JSON 1.1 producer: putRule (`CamelAwsEventbridgeEventPattern` or `eventPatternFile`), putTargets (`CamelAwsEventbridgeTargets` list of `{id, arn, input}`), removeTargets, deleteRule, enableRule, disableRule, describeRule, listRules (`...RuleNamePrefix`), listTargetsByRule, listRuleNamesByTarget, putEvent (`...EventSource`, `...EventDetailType`, `...EventResources`; body = entry ids). |
| aws-secrets-manager + `{{aws:...}}` | ✅ | `cameleer-cloud`, Secrets Manager AWS JSON 1.1 producer: getSecret (default; `CamelAwsSecretsManagerSecretId`, version id), createSecret (`...SecretName`, `binaryPayload`), describeSecret, listSecrets, deleteSecret (+ force), restoreSecret, updateSecret, rotateSecret (stub against the emulator), replicateSecretToRegions. Properties function `{{aws:name}}`, `{{aws:name/field}}`, `{{aws:name@version}}`, `{{aws:name:default}}` configured with `camel.vault.aws.*` (`accessKey`, `secretKey`, `region`, `defaultCredentialsProvider`, `profileCredentialsProvider`, `profileName`, `uriEndpointOverride`). Secret refresh (Camel's CloudTrail reload trigger): `camel.vault.aws.refreshEnabled`, `refreshPeriod`, `secrets` (names / patterns; default: the secrets resolved through `{{aws:...}}`) poll CloudTrail LookupEvents for PutSecretValue / UpdateSecret / RotateSecret / UpdateSecretVersionStage / RestoreSecret and trigger a context reload (reload listeners + restart of the started routes); `secretsmanager::refresh_task(ctx)`. No SQS-notification (`useSqsNotification`) variant. |
| aws2-ses | ✅ | `cameleer-cloud`, SES v1 Query API: SendEmail (text or `CamelAwsSesHtmlEmail`; `to`/`cc`/`bcc`/`subject`/`returnPath`/`replyToAddresses`/`configurationSet` options or `CamelAwsSes*` headers; `CamelAwsSesMessageId`), SendRawEmail for bytes bodies (MIME). |
| aws2-cw | ✅ | `cameleer-cloud`, CloudWatch Query API PutMetricData: `name`/`value`/`unit`/`timestamp` options or `CamelAwsCwMetricName`/`...Value`/`...Unit`/`...Timestamp`/`...Namespace`, dimensions from `CamelAwsCwMetricDimensions` (map) or `...DimensionName`/`...DimensionValue`; array bodies send several data. |
| aws2-sts | ✅ | `cameleer-cloud`, STS Query API: assumeRole (`CamelAwsStsRoleArn`, `...RoleSessionName`), getSessionToken, getFederationToken (`...FederatedName`), getCallerIdentity; body = `{accessKeyId, secretAccessKey, sessionToken, expiration}`. |
| aws2-step-functions | ✅ | `cameleer-cloud`, Step Functions AWS JSON 1.0: createStateMachine, deleteStateMachine, describeStateMachine, listStateMachines, startExecution, startSyncExecution, stopExecution, describeExecution, listExecutions, getExecutionHistory (`CamelAwsStepFunctions*` headers). Also updateStateMachine and activities: createActivity, deleteActivity, describeActivity, listActivities, getActivityTask (`CamelAwsStepFunctionsTaskToken`), sendTaskSuccess / sendTaskFailure / sendTaskHeartbeat (the emulator suspends executions on activity Task states). |
| aws2-iam | ✅ | `cameleer-cloud`, IAM Query API subset (global endpoint): createUser, getUser, deleteUser, listUsers, createGroup, deleteGroup, listGroups, addUserToGroup, removeUserFromGroup, createAccessKey, listAccessKeys, deleteAccessKey. Also updateAccessKey (inactive keys stop signing in the emulator), getGroup, roles (createRole, getRole, deleteRole, listRoles), managed policies (createPolicy, getPolicy, deletePolicy, listPolicies), attach / detach / listAttached user / group / role policies, instance profiles (create, get, delete, list, add / remove role). |
| aws2-ec2 | ✅ | `cameleer-cloud`, EC2 Query API (XML) subset: describeInstances (`CamelAwsEC2InstancesIds`), describeInstancesStatus, createAndRunInstances (`...ImageId`, `...InstanceType`, `...InstanceMinCount`/`MaxCount`, `...InstanceKeyPair`), start/stop/terminate/rebootInstances. Also monitorInstances / unmonitorInstances, createTags / deleteTags, and createAndRunInstances options `...InstanceMonitoring`, `...InstanceKernelId`, `...InstanceEbsOptimized`, `...InstanceSecurityGroups`, `...InstancesClientToken` (idempotent), `...InstancesPlacement`, `...SubnetId`, `...InstancesTags`. |
| azure-storage-datalake | ✅ | `cameleer-cloud`, ADLS Gen2 DFS REST (Shared Key `accountKey`/`accessKey` or SAS): listFileSystem, createFileSystem, deleteFileSystem, listPaths (`path`, `recursive`), createFile, createDirectory, upload (create + append + flush), appendToFile / flushToFile (`CamelAzureStorageDataLakeFileOffset` / `...Position`), getFile, deleteFile, deleteDirectory (`CamelAzureStorageDataLake*` headers). Also downloadToFile (`fileDir`), downloadLink (read-only service SAS, `downloadLinkExpiration`), uploadFromFile, openQueryInputStream (query acceleration: SQL `expression` over CSV / JSON, Avro result stream decoded; the emulator implements a SELECT / WHERE / COUNT / LIMIT subset), ACLs (`permission` / `umask` on createFile, Cameleer getAccessControl / setAccessControl with ACL, permissions, owner, group; `userPrincipalNameReturned`), Entra ID credentials (`clientId` / `clientSecret` / `tenantId`, `credentialType=AZURE_IDENTITY` workload / managed identity), and the consumer (the `fileName` file or the files under `path` / `directoryName`, `recursive`, `regex`; Cameleer `deleteAfterRead`). |
| azure-key-vault + `{{azure:...}}` | ✅ | `cameleer-cloud`, Key Vault secrets REST (`api-version=7.4`) with Azure AD client credentials (`clientId`/`clientSecret`/`tenantId`, `credentialType=AZURE_IDENTITY` from `AZURE_*` env vars, `authorityHost`; token cached, refreshed after 401): getSecret (default; version header), createSecret, deleteSecret, purgeDeletedSecret, plus recoverDeletedSecret / listSecrets. Properties function `{{azure:name}}`, `/field`, `@version`, `:default` (`camel.vault.azure.vaultName`, `clientId`, `clientSecret`, `tenantId`, `azureIdentityEnabled`). Keys and certificates (Cameleer operations): createKey (EC/RSA, curve, size, key_ops), getKey, listKeys, deleteKey, signData / verifyData (body hashed for ES256/384/512, RS*, PS*; signature over the vault), createCertificate (self-issued policy, pending operation polled), getCertificate, importCertificate (PEM / PKCS#12), listCertificates, deleteCertificate; the emulator creates EC keys and P-256 certificates with cameleer-tls. Key cryptography (Azure SDK `CryptographyClient` operations): importKey (RSA / oct JWK), encrypt / decrypt (RSA-OAEP, RSA-OAEP-256, RSA1_5; A128/192/256GCM with IV / tag / AAD headers for `oct-HSM` keys) and wrapKey / unwrapKey (RSA-OAEP(-256), RSA1_5, A128/192/256KW); the emulator implements OAEP / PKCS#1 v1.5 / AES-GCM / RFC 3394 with cameleer-tls primitives (generated RSA keys share one fixed key pair). `credentialType=AZURE_IDENTITY` also covers workload identity federation and managed identity (IMDS / App Service endpoints, emulated). Secret refresh like Camel's `EventhubsReloadTriggerTask`: `camel.vault.azure.refreshEnabled`, `refreshPeriod`, `secrets` (patterns), `eventhubConnectionString` (+ `blobAccountName` / `blobContainerName` / `blobAccessKey` checkpoints): Key Vault `SecretNewVersionCreated` Event Grid events consumed with cameleer-amqp10's Event Hubs consumer trigger a reload (listeners + route restarts). |
| azure-cosmosdb | ✅ | `cameleer-cloud`, Cosmos DB SQL REST with master-key HMAC signing (`databaseEndpoint`, `accountKey`): listDatabases, createDatabase, queryDatabases, deleteDatabase, createContainer (`containerPartitionKeyPath`), listContainers, queryContainers, deleteContainer, createItem, upsertItem, replaceItem, readItem, deleteItem, readAllItems, queryItems (`query`, parameters map, all pages); partition keys from `itemPartitionKey` or derived from the item; `createDatabaseIfNotExists` / `createContainerIfNotExists`; `CamelAzureCosmosDb*` headers. Consumer: change feed per partition key range (continuations in memory, `changeFeedStartFromBeginning`). Change feed processor with a lease container (`leaseContainerName`, `leaseDatabaseName`, `createLeaseContainerIfNotExists`, `createLeaseDatabaseIfNotExists`, `hostName`, Cameleer `leaseExpirationInterval`): one etag-checked lease per partition key range with checkpointed continuations, fair-share balancing / stealing between hosts, release on stop. Throughput: `throughputProperties` / `CamelAzureCosmosDbThroughputProperties` (manual or autoscale) on creation, replaceDatabaseThroughput / replaceContainerThroughput (Offers API; Cameleer read*Throughput). `credentialType=AZURE_IDENTITY` (Entra ID `type=aad` tokens: client secret, workload or managed identity). `consistencyLevel`, `contentResponseOnWriteEnabled`. Cameleer always uses the REST gateway, so the SDK's direct (TCP) connection mode has no equivalent. |
| google-bigquery / google-bigquery-sql | ✅ | `cameleer-cloud`, BigQuery v2 REST. `google-bigquery://project:dataset[:table]`: insertAll streaming insert (map or list bodies, `useAsInsertId`, `CamelGoogleBigQueryTableId`, `...TableSuffix`, `...PartitionDecorator`, `...InsertId`; insert errors raise `BigQueryException`). `google-bigquery-sql://project:query` (or `file:`): jobs.query in standard SQL with named `@params` from headers/body, `${header.x}` substitution (`CamelGoogleBigQueryTranslatedQuery`), polls getQueryResults and reads all pages; body = affected rows (DML) or typed row maps; `CamelGoogleBigQueryJobId`. Load / extract jobs (Cameleer `operation=load|extract`): jobs.insert + jobs.get polling (`jobPollInterval`, `jobTimeout`), `sourceUris` / `CamelGoogleBigQuerySourceUris` (or a list body), `sourceFormat` (CSV, NEWLINE_DELIMITED_JSON...), `skipLeadingRows`, `fieldDelimiter`, `writeDisposition`, `createDisposition`, `autodetect`; `destinationUris`, `destinationFormat`, `printHeader`, `compression`; job errors raise `BigQueryException`. Tables and datasets (Cameleer operations): createTable (`tableSchema` / `CamelGoogleBigQueryTableSchema` list / JSON / `name:TYPE`, `timePartitioningField` / `timePartitioningType`, `clusteringFields`, `tableDescription`, `expirationMs`), getTable, listTables, deleteTable, createDataset (`datasetLocation`), listDatasets, deleteDataset (`deleteContents`); `createTableIfNotExists` on streaming inserts. |
| google-secret-manager + `{{gcp:...}}` | ✅ | `cameleer-cloud`, Secret Manager REST: createSecret (+ first version), addSecretVersion, getSecretVersion (default; `CamelGoogleSecretManagerVersionId`, default latest), deleteSecret, listSecrets. Properties function `{{gcp:name}}`, `/field`, `@version`, `:default` (`camel.vault.gcp.serviceAccountKey` / `useDefaultInstance`, `projectId`). |
| google-functions | ✅ | `cameleer-cloud`, Cloud Functions v1 REST: callFunction (default; result body, `CamelGoogleCloudFunctionsExecutionId`, function errors raise `ApiException`), listFunctions, getFunction, deleteFunction (`project`, `location`). Also generateUploadUrl (optionally uploading a zip body to the signed URL), generateDownloadUrl, createFunction / updateFunction (`CamelGoogleCloudFunctionsEntryPoint`, `...Runtime`, `...SourceArchiveUrl` / `...SourceUploadUrl` or a CloudFunction map body; long-running operation polled; body = the function). |
| google-firestore (Cameleer) | ✅ | `cameleer-cloud`, Firestore REST (no Camel equivalent): getDocument, listDocuments, createDocument (generated or `CamelGoogleFirestoreDocumentId`), setDocument, updateDocument (merge, must exist), deleteDocument, runQuery (structuredQuery passthrough or equality map + `orderBy`/`descending`/`limit`), sub-collections; plain maps converted to and from typed Firestore values. Batched writes: `commit` (atomic, preconditions for update / create) and `batchWrite` (independent writes, per-write status) from `{op, collection, id, data}` maps; transactions: beginTransaction (read-write / read-only), transactional getDocument, commit (`ABORTED` on a conflicting change, emulated with optimistic concurrency), rollback; snapshot-listener consumer (ADDED / MODIFIED / REMOVED changes per poll, `skipInitialSnapshot`; polled, not the gRPC `Listen` stream). |
| google-sheets | ✅ | `cameleer-cloud`, Sheets v4 REST with a service account (spreadsheets scope): `data/get`, `data/update`, `data/append`, `data/clear`, `data/batchGet`, `spreadsheets/get`, `spreadsheets/create`; options or `CamelGoogleSheets.<option>` headers (`spreadsheetId`, `range`, `values`, `valueInputOption`, `majorDimension`). OAuth refresh-token user credentials (`clientId`/`clientSecret`/`refreshToken`). `google-sheets-stream://spreadsheetId?range=...` consumer emitting appended rows (`splitResults`, `majorDimension`, `valueRenderOption`; Camel re-emits the whole range each poll). Also `spreadsheets/batchUpdate` (request list / `BatchUpdateSpreadsheetRequest` passed through; emulated atomically: addSheet, deleteSheet, duplicateSheet, updateSpreadsheetProperties, updateSheetProperties, findReplace, insert / deleteDimension), `data/batchUpdate` and `data/batchClear`. |
| aws2-msk + kafka `AWS_MSK_IAM` | ✅ | `cameleer-cloud`, MSK REST (signing name `kafka`): listClusters (`CamelAwsMSKClusterFilter`, all pages), createCluster (`CamelAwsMSKClusterName`, `...ClusterKafkaVersion`, `...BrokerNodesNumber`, `...BrokerNodesGroupInfo`), describeCluster, deleteCluster (`CamelAwsMSKClusterArn`), getBootstrapBrokers (Cameleer). `cameleer_cloud::register` adds the `AWS_MSK_IAM` SASL mechanism to the `kafka` component (`securityProtocol=SASL_SSL&saslMechanism=AWS_MSK_IAM&saslJaasConfig=software.amazon.msk.auth.iam.IAMLoginModule required;`): the SASL message is the `aws-msk-iam-auth` JSON payload of a SigV4-presigned `kafka-cluster:Connect` request (default credential chain, `awsProfileName`, or Cameleer `awsAccessKeyId`/`awsSecretAccessKey`/`awsSessionToken`/`awsRegion` JAAS options). No `awsRoleArn` (assume role); the test broker verifies the signature. |
| aws2-athena | ✅ | `cameleer-cloud`, Athena JSON 1.1: startQueryExecution (default; `queryString`/header/body, `database`, `outputLocation`, `workGroup`, `encryptionOption`/`kmsKey`, `clientRequestToken`; `waitTimeout` polling with `initialDelay`/`delay`, `maxAttempts` + `retry` = never/always/retryable/exhausted/generic), getQueryExecution, getQueryResults (`outputType` StreamList = all pages as rows, SelectList = one page + `CamelAwsAthenaNextToken`, S3Pointer), listQueryExecutions; `CamelAwsAthena*` headers. |
| aws2-textract | ✅ | `cameleer-cloud`, Textract JSON 1.1: detectDocumentText (default), analyzeDocument (`CamelAwsTextractFeatureTypes`), analyzeExpense on body bytes or `s3Bucket`/`s3Object`(`/s3ObjectVersion`); startDocumentTextDetection / startDocumentAnalysis / startExpenseAnalysis (`CamelAwsTextractJobId`) and the matching get* operations (`...MaxResults`, `...NextToken`). |
| aws2-translate | ✅ | `cameleer-cloud`, Translate JSON 1.1 translateText: `sourceLanguage`/`targetLanguage` (or `CamelAwsTranslateSourceLanguage`/`...TargetLanguage`), `autodetectSourceLanguage` (detected language returned in the header), `CamelAwsTranslateTerminologyNames`. |
| aws2-comprehend / aws-comprehend | ✅ | `cameleer-cloud`, Comprehend JSON 1.1 on the body text: detectDominantLanguage (`CamelAwsComprehendDetectedLanguage`), detectEntities, detectKeyPhrases, detectSentiment (`CamelAwsComprehendSentimentScore`), detectSyntax, detectPiiEntities, containsPiiEntities, detectToxicContent, classifyDocument (`endpointArn`); `languageCode`. |
| aws2-polly | ✅ | `cameleer-cloud`, Polly REST: synthesizeSpeech (default; `voiceId`, `outputFormat`, `textType`, `engine`, `sampleRate`, `languageCode`, `lexiconNames`; audio bytes, `CamelAwsPollyContentType`, `...RequestCharacters`), describeVoices, listLexicons/getLexicon/putLexicon/deleteLexicon, startSpeechSynthesisTask/getSpeechSynthesisTask. |
| aws2-rekognition (Cameleer) | ✅ | `cameleer-cloud`, Rekognition JSON 1.1 on body bytes or an S3 object: detectLabels (`maxLabels`, `minConfidence`), detectText, detectFaces, detectModerationLabels, recognizeCelebrities. Face collections (createCollection, deleteCollection, describeCollection, listCollections, indexFaces, listFaces, deleteFaces), face search (searchFaces, searchFacesByImage, compareFaces) and stored video analysis (start/get LabelDetection, FaceDetection, TextDetection, FaceSearch; all result pages). |
| aws2-transcribe | ✅ | `cameleer-cloud`, Transcribe JSON 1.1: startTranscriptionJob (`CamelAwsTranscribeTranscriptionJobName`, `...MediaUri` or body, `...LanguageCode` / `...IdentifyLanguage`, `...MediaFormat`, `...MediaSampleRateHertz`, `...OutputBucketName`), getTranscriptionJob, deleteTranscriptionJob, listTranscriptionJobs (all pages). Also medical transcription jobs (start/get/delete/listMedicalTranscriptionJob(s)), call analytics jobs and categories, custom vocabularies and medical vocabularies (create/get/update/delete/list), custom language models (create/describe/delete/list) and tagResource / untagResource / listTagsForResource. |
| aws-bedrock (alias aws2-bedrock), aws-bedrock-agent-runtime | ✅ | `cameleer-cloud`, Bedrock Runtime REST: invokeTextModel / invokeImageModel / invokeEmbeddingsModel (InvokeModel with `modelId`, `CamelAwsBedrockContentType`/`...AcceptContentType`; JSON bodies parsed), converse (messages from `CamelAwsBedrockConverseMessages` or the body, `...ConverseSystem`, `...ConverseInferenceConfig`; body = text, stop reason / usage / output message headers). Agent Runtime: retrieve (`knowledgeBaseId`, `...NumberOfResults`), retrieveAndGenerate (`modelId`, session id, citations). Streaming: invokeTextModelStreaming / invokeImageModelStreaming / invokeEmbeddingsModelStreaming (InvokeModelWithResponseStream) and converseStream, AWS event stream framing decoded incrementally with prelude + message CRC32 checks; `streamOutputMode` complete / chunks, `streamingChunkProcessor` per-chunk callback, `CamelAwsBedrockStreaming*` headers. applyGuardrail (+ guardrails on invoke / converse). Agent Runtime invokeAgent (event stream of chunks / traces / citations / returnControl, session attributes, `endSession`). |
| aws2-mq | ✅ | `cameleer-cloud`, Amazon MQ REST: listBrokers (all pages), createBroker (`CamelAwsMQBrokerName`, `...BrokerEngine`, `...BrokerEngineVersion`, `...BrokerInstanceType`, `...BrokerDeploymentMode`, `...BrokerPubliclyAccessible`, `...BrokerUsers`), describeBroker, deleteBroker, rebootBroker (`CamelAwsMQBrokerId`). No updateBroker. |
| aws2-ecs / aws2-eks | ✅ | `cameleer-cloud`, ECS JSON 1.1 and EKS REST: listClusters (all pages), createCluster, describeCluster, deleteCluster (`CamelAwsECSClusterName`; EKS `CamelAwsEKSClusterName`, `...RoleARN`, `...VPCConfig`). |
| aws2-kms | ✅ | `cameleer-cloud`, KMS JSON 1.1: listKeys (`CamelAwsKMSLimit`, follows NextMarker), createKey (`...Description`), describeKey, enableKey, disableKey, scheduleKeyDeletion (`...PendingWindowInDays`); Cameleer encrypt / decrypt (body bytes ↔ ciphertext blob). |
| aws2-timestream | ✅ | `cameleer-cloud`, Timestream Write/Query JSON 1.0 with endpoint discovery (`DescribeEndpoints`, cached; skipped with an endpoint override). `aws2-timestream://write:x`: describeEndpoints, create/delete/describe/listDatabases, create/delete/describe/listTables (retention headers), writeRecords (`CamelAwsTimestreamRecordList` / `...Record` / body, `...CommonAttributes`). `query:x`: query (all pages, rows as maps; `CamelAwsTimestreamQueryId`), cancelQuery. No scheduled queries or batch load tasks. |
| aws-cloudtrail | ✅ | `cameleer-cloud`, polling consumer over LookupEvents (`eventSource`, `maxResults`): events after the newest one seen, oldest first, never twice; body = CloudTrail event JSON, `CamelAwsCloudTrailEventId`/`...EventSource`/`...EventName`/`...EventUsername`/`...EventTime`. |
| aws-config | ✅ | `cameleer-cloud`, AWS Config JSON 1.1: putConfigRule (`CamelAwsConfigRuleName`, `...RuleSourceIdentifier`, `...RuleSourceOwner`, input parameters, scope), removeConfigRule, describeConfigRules, describeRuleCompliance, putConformancePack / removeConformancePack / describeConformancePackCompliance. |
| aws2-redshift-data | ✅ | `cameleer-cloud`, Redshift Data API JSON 1.1: executeStatement (SQL header/body, parameters; Cameleer `waitTimeout` polling, failures raise), batchExecuteStatement, describeStatement, getStatementResult (all pages, rows as maps of typed values), cancelStatement, listStatements, listDatabases, listSchemas, listTables, describeTable; cluster (`clusterIdentifier`) or serverless (`workgroupName`), `secretArn`/`dbUser`. |
| azure-storage-files (Cameleer) | ✅ | `cameleer-cloud`, Azure Files REST (Shared Key / SAS): listShares, createShare, deleteShare, listDirectoriesAndFiles (default), createDirectory, deleteDirectory, uploadFile (create + 4 MiB Put Range), downloadFile, getFileProperties, deleteFile (`directoryName`, `fileName`, `CamelAzureStorageFiles*` headers); polling consumer of a directory (`delete`, `maxMessagesPerPoll`, ETag de-duplication). Camel `azure-files` (FTP-like) semantics: consumer `recursive` (`minDepth` / `maxDepth`), `include` / `exclude`, `noop` + `idempotent` / `idempotentRepository` / `idempotentKey`, `preMove` / `move` / `moveFailed` via the Rename File API, `CamelFile*` headers; producer `fileExist` (Override / Append / Fail / Ignore / Move + `moveExisting`), `tempPrefix` (upload then rename), `autoCreate` directories from `CamelFileName`, `flatten`, and a `renameFile` operation (emulator: Rename File, Set File Properties). |
| azure-functions (Cameleer) | ✅ | `cameleer-cloud`: invokes HTTP-triggered functions (`azure-functions://app/function`, `httpMethod`, `functionKey` / `masterKey` in `x-functions-key` or `keyInQuery=true` → `code`, Entra ID tokens with `scope`, `CamelAzureFunctionsQuery`); body = response (`parseJson`), `CamelAzureFunctionsStatusCode`; non-2xx → `HttpResponseException`. |
| azure-eventgrid | ✅ | `cameleer-cloud`, publishes to a topic endpoint (`azure-eventgrid:https://topic.../api/events`): `eventSchema` CloudEvent (default, CloudEvents 1.0 batch) or EventGrid; list bodies = several events; `CamelAzureEventGridEventType`/`...Subject`/`...Source`/`...EventId`/`...DataVersion`. Auth: `accessKey` (`aeg-sas-key`), `credentialType=AZURE_SAS` (`sharedAccessSignature` or generated `aeg-sas-token`), Entra ID client credentials. No consumer (Event Grid pushes to webhooks: use `platform-http`). |
| azure-schema-registry (Cameleer) | ✅ | `cameleer-cloud`, Event Hubs Schema Registry REST (2022-10, Entra ID): registerSchema, getSchemaProperties (id of a definition), getSchema (by id), getSchemaByVersion, listVersions, listGroups; `format` Avro / Json / Custom. No Kafka serializer integration. |
| azure-openai (Cameleer) | ✅ | `cameleer-cloud`, Azure OpenAI REST (`apiKey` or Entra ID, `apiVersion`): chatCompletion (text / message list / raw request body, `systemMessage`, `temperature`, `maxTokens`, `topP`; finish reason, usage, tool calls headers), embeddings. Streaming chat (`streaming=true` / `chatCompletionStream`): SSE decoded incrementally, `streamOutputMode` complete / chunks, `streamingChunkProcessor`, chunk count / finish reason / usage headers. imageGeneration (`imageSize`, `imageCount`, `imageQuality`, `imageResponseFormat` url / b64_json, revised prompts). Assistants API: create / get / list / deleteAssistant, createThread, createMessage, listMessages, createRun, getRun, runAssistant (polls until a terminal status). (Camel itself offers Azure OpenAI through LangChain4j.) |
| google-mail, google-calendar, google-drive | ✅ | `cameleer-cloud`, Gmail v1 / Calendar v3 / Drive v3 REST with a service account and domain-wide delegation (`delegate`/`subject`, `scopes`); options as URI options or `CamelGoogleMail.*`/`CamelGoogleCalendar.*`/`CamelGoogleDrive.*` headers. Mail: messages/send (map → MIME, text + `to`, or raw), messages/list/get (decoded subject/from/to/text headers)/delete/trash/untrash/modify, labels/list, threads/get. Calendar: events/list/insert/get/update/patch/delete/quickAdd, calendarList/list, calendars/get. Drive: drive-files/list/get/download/create (multipart upload)/update/copy/delete. OAuth refresh-token user credentials (`clientId` / `clientSecret` / `refreshToken`, `authorized_user` credential files, fixed `accessToken`; token cached and refreshed after a 401). Consumers: `google-mail-stream` (`query` default `is:unread`, `labels`, `maxResults`, `markAsRead`, `raw`; `CamelGoogleMailStream*` headers), `google-calendar-stream` (`calendarId`, `query`, `consumeFromNow`, `considerLastUpdate`; new and changed events), and the Drive file-change consumer on `drive-files/list` (created / modified / removed, `consumeExisting`). The remaining API names as a REST table: Gmail drafts (create / list / get / update / send / delete), history/list, attachments/get, users (getProfile, watch → Pub/Sub `{emailAddress, historyId}` notifications, stop), labels CRUD, threads (list / modify / trash / untrash / delete); Calendar acl CRUD, colors/get, freebusy/query, settings, calendars insert / update / delete / clear, calendarList get / insert / delete, events instances / move / import; Drive about, changes (getStartPageToken / list), permissions / comments / replies / revisions / drives (teamdrives) operations, files emptyTrash / generateIds. Push notifications: `events/watch`, `acl/watch`, `calendarList/watch`, `settings/watch`, `drive-changes/watch`, `drive-files/watch` channels (`channelId` / `address` / `token` or a channel map) and `channels/stop` / `drive-channels/stop`; the emulator POSTs `X-Goog-Channel-*` / `X-Goog-Resource-State` notifications. `google-calendar-stream` `syncFlow=true`: incremental `syncToken` polling with deleted (`cancelled`) events and a full resync on `410 GONE`. |
| google-vertexai | ✅ | `cameleer-cloud`, Vertex AI Gemini REST (`google-vertexai:project:location:model`): generateText / generateChat / generateCode / generateMultimodal (inline bytes or `gs://` URI) / countTokens; `temperature`, `maxOutputTokens`, `topP`, `topK`, `candidateCount`, `systemInstruction`; finish reason, token counts, safety ratings headers. Streaming (generateText/Chat/CodeStreaming: `streamGenerateContent?alt=sse` decoded incrementally, `streamOutputMode`, `streamingChunkProcessor`), generateEmbeddings (`taskType`, `outputDimensionality`), generateImage (Imagen, `sampleCount`, `aspectRatio`), partner models via rawPredict / streamRawPredict (`publisher=anthropic`/`meta`/...; text bodies wrapped into Anthropic Messages requests, Anthropic SSE deltas or OpenAI-style chunks decoded). |
| google-speech-to-text / google-text-to-speech (Cameleer) | ✅ | `cameleer-cloud`, Speech v1: recognize (bytes or `gs://`; `encoding`, `sampleRateHertz`, `languageCode`, `model`; transcript + confidence/results headers), longRunningRecognize + getOperation. Text-to-Speech v1: synthesize (text or SSML, `voiceName`, `languageCode`, `ssmlGender`, `audioEncoding`, `speakingRate`, `pitch`; audio bytes), listVoices. |
| Cloud emulators for tests | ✅ | `cameleer_cloud::testing`: `AwsMock` (S3 incl. multipart, SQS, SNS, DynamoDB subset, Lambda closures, Kinesis, Firehose, EventBridge with pattern matching to SQS targets, Secrets Manager, Step Functions Pass/Succeed/Fail machines, SES, CloudWatch, STS issuing temporary credentials, IAM, EC2, MSK, Athena with polling / failures / paging, Textract, Translate, Comprehend, Polly, Rekognition, Transcribe, Bedrock + knowledge bases, MQ, ECS, EKS, KMS envelope encryption, Timestream write/query, CloudTrail, Config, Redshift Data) and the Kafka test broker verifying `AWS_MSK_IAM` payloads, `ImdsMock` (EC2 instance metadata IMDSv2/v1 + ECS container credentials), `AzuriteMock` (Blob incl. append/page blobs and leases, Queue, ADLS Gen2 DFS, Azure Files), `AzureMock` (Azure AD client-credentials token endpoint, Key Vault, Cosmos DB SQL subset + change feed, Functions with function / master keys, Event Grid topics verifying keys / SAS tokens / bearer tokens and event schemas, Schema Registry, Azure OpenAI), `GcpMock` (OAuth token endpoint recording delegated subjects, Cloud Storage + V4 signed URL downloads, Pub/Sub REST and a StreamingPull gRPC server over cameleer-grpc HTTP/2 with leases / acks / nacks / redelivery / flow control, BigQuery insertAll + SQL subset with async jobs/paging, Secret Manager, Cloud Functions closures, Firestore + runQuery, Sheets values, Gmail mailboxes, Calendar, Drive with multipart uploads, Vertex AI / Speech / Text-to-Speech stand-ins) in memory on ephemeral ports; they verify SigV4 signatures (and session tokens of temporary credentials), Shared Key signatures / account SAS tokens, Azure AD bearer tokens, Cosmos DB master-key HMAC signatures and RS256 JWT assertions + bearer tokens (with scopes for Sheets). |
| sftp | ✅ | `cameleer-ssh` (own SSH-2 + SFTP v3 stack, interop-tested against OpenSSH 9.6). Same consumer/producer options and `CamelFile*` headers as `ftp` (noop/delete/move/preMove/moveFailed, include/exclude/ant, recursive, sortBy, idempotent, maxMessagesPerPoll, fileExist strategies, tempFileName, doneFileName, scheduler options) plus `password`, `privateKeyFile`/`privateKeyUri`/`privateKey`, `knownHostsFile`/`knownHostsUri`/`knownHosts`, `useUserKnownHostsFile`, `strictHostKeyChecking` (default `no` as in Camel, but changed/revoked host keys are always rejected), `preferredAuthentications`, `ciphers`/`keyExchangeProtocols`/`serverHostKeys`, `bulkRequests` (pipelining), `chmod`/`chmodDirectory`. Algorithms: curve25519-sha256, ecdh-sha2-nistp256; ssh-ed25519, ecdsa-sha2-nistp256/384, rsa-sha2-256/512; chacha20-poly1305@openssh.com, aes128/256-gcm@openssh.com, aes128/192/256-ctr + hmac-sha2-256/512(-etm); strict KEX, rekeying. SSH agent identities (`useAgent`, `agentSocket`). Passphrase-protected keys (`privateKeyPassphrase`): OpenSSH `openssh-key-v1` with bcrypt-pbkdf (own Blowfish) and aes-ctr/cbc/gcm, chacha20-poly1305 or 3des-cbc, PKCS#8 `ENCRYPTED PRIVATE KEY`, legacy OpenSSL PEM (AES-CBC / DES-EDE3-CBC) — fixtures from `ssh-keygen`. `compression` (level > 0 negotiates `zlib@openssh.com` / `zlib`), OpenSSH user certificates (`certificateFile`) and `@cert-authority` host certificates (see the `ssh` row). Remaining gaps: no `readLock`, proxies. |
| ssh | ✅ | `cameleer-ssh`. Producer runs the body as a command (`exec` or `channelType=shell`): body = stdout, headers `CamelSshStderr`, `CamelSshExitValue`; `CamelSshUsername`/`CamelSshPassword` override credentials; pooled connection. Consumer runs `pollCommand` on a schedule. Options `username`, `password`, `certResource`/`privateKeyFile` (+ `certResourcePassword` / `privateKeyPassphrase` for encrypted keys), `knownHostsResource`, `failOnUnknownHost`, `timeout`, `kex`/`ciphers`/`macs`/`signatures`. Embedded test server `cameleer_ssh::testing::SshServer` (password/publickey/keyboard-interactive auth, built-in `echo`/`cat`/`ls`/`pwd`/`exit` commands, SFTP subsystem). SSH agent authentication (`useAgent=true` → `SSH_AUTH_SOCK`, or `agentSocket`; tested with OpenSSH `ssh-agent`), passphrase-protected keys. Port forwarding: `SshClient::open_direct_tcpip`, `start_local_forward` (`ssh -L`) and `request_remote_forward` / `start_remote_forward` (`tcpip-forward` + `forwarded-tcpip`, `ssh -R`); the embedded server accepts `direct-tcpip` and `tcpip-forward` (`allow_tcp_forwarding`). Compression `zlib@openssh.com` (delayed) and `zlib` (own streaming deflate/inflate keeping the window and leftover bits across packets, `compressionAlgorithms`). OpenSSH certificates: user certificate authentication (`ClientConfig::certificates`, `certificateFile`), host certificates verified against `@cert-authority` known_hosts lines (certificate host key algorithms preferred automatically), server-side `trusted_user_ca_keys` and host certificates. All interop-tested both ways with OpenSSH (`ssh -C`, `ssh -L/-R`, `ssh-keygen -s`, `sshd` with `TrustedUserCAKeys` / `HostCertificate`). Remaining gaps: no `shellPrompt` handling or `keyPairProvider` beans; certificate critical options other than `force-command` / `source-address` are rejected (those two are accepted but not enforced); no KRL revocation lists. |
| spring-redis | ✅ | `cameleer-datastores`, own RESP2/RESP3 client (`AUTH` incl. ACL users, `SELECT`, `HELLO 3`, pipelining, `MULTI`/`EXEC`, TLS via `ssl=true`/`sslContextParameters`). Producer runs `command` (header `CamelRedis.Command`) with arguments from `CamelRedis.Key/Keys/Field/Fields/Value/Values/Timeout/Start/End/Index/Offset/Destination/Channel/Message/Pivot/Position/Count/Timestamp/Pattern/Db/Score/Min/Max/Increment/WithScore/Longitude/Latitude/Radius`: key, string, hash, list (incl. blocking pops), set, sorted-set, geo (`GEOADD`, `GEODIST`, `GEOHASH`, `GEOPOS`, `GEORADIUS`, `GEORADIUSBYMEMBER`; Redis-identical 52-bit geohash scores), `PUBLISH` and transaction commands; unknown commands are sent generically. Consumer: `SUBSCRIBE`/`PSUBSCRIBE` on `channels` (headers `CamelRedis.Channel`, `CamelRedis.Pattern`). `serializer`: `string` (`StringRedisSerializer`), `json` (`GenericJackson2JsonRedisSerializer`), `bytes` (`ByteArrayRedisSerializer`), default text, or a `#bean` (`RedisSerializerBean`) — Java serialization (`JdkSerializationRedisSerializer`) is rejected. `redisTemplate`/`connectionFactory` = `#bean` of type `RedisClient`. Topologies: Redis Sentinel master discovery (`sentinels`, `sentinelMaster`; re-resolved after connection failures) and Redis Cluster (`cluster=true`: CRC16 key slots, slot cache, `MOVED`/`ASK` redirections); the embedded server can act as sentinel or cluster node. |
| Redis idempotent / aggregation repositories | ✅ | `cameleer-datastores`. `RedisIdempotentRepository` (a set per processor: `SADD`/`SISMEMBER`/`SREM`), `RedisAggregationRepository` (hash `<name>` + ordered keys + `<name>-completed`, `scan`/`recover`). |
| mongodb | ✅ | `cameleer-datastores`, own BSON codec (ObjectId, dates, Decimal128, binary, regex, timestamps; Extended JSON/shell syntax bodies) and `OP_MSG` client with SCRAM-SHA-256, SCRAM-SHA-1 (MD5 password digest) and MONGODB-X509 (TLS client certificate, `$external`) authentication and TLS (`tls=true`, `sslContextParameters`). Connection: `mongodb:<bean>` (`MongoClient`), `connectionUriString` (`mongodb://` or `mongodb+srv://` — SRV/TXT records resolved by the own UDP DNS client in `cameleer_datastores::dns` with TCP fallback, domain checks, TXT `authSource`/`replicaSet`, `srvServiceName`, `srvMaxHosts`, `dnsServer`) or `hosts`/`username`/`password`/`authSource`. Replica sets: `replicaSet`, `hello` topology discovery (follows `primary`, remembers `hosts`), re-discovery and retry after `NotWritablePrimary`, `directConnection`. Operations findById, findOneByQuery, findAll, findDistinct, count, insert, save, update, remove, bulkWrite (insertOne/updateOne/updateMany/replaceOne/deleteOne/deleteMany models, `CamelMongoDbBulkOrdered`, `MongoBulkWriteException`), aggregate, getDbStats, getColStats, command; headers `CamelMongoDbCriteria`, `...FieldsProjection`, `...SortBy`, `...Limit`, `...NumToSkip`, `...BatchSize`, `...MultiUpdate`, `...Upsert`, `...RecordsAffected`, `...RecordsMatched`, `...ResultTotalSize`, `...ResultPageSize`, `CamelMongoOid`, `dynamicity`, `writeResultAsHeader`, `createCollection`. Consumers `consumerType=tailable` (in-memory tail tracking only) and `changeStreams` (`streamFilter`, `fullDocument`, resume after errors). `mongodb-gridfs` ✅: GridFS buckets (`bucket`, chunked `files`/`chunks` per the GridFS spec), operations create (`CamelFileName`, `gridfs.chunksize`, `gridfs.metadata`, `Content-Type` → `gridfs.fileid`), remove, findOne, listAll, count; polling consumer with `queryStrategy` TimeStamp / FileAttribute (`fileAttributeName`) / TimeStampAndFileAttribute and `query`. The embedded server implements SCRAM-SHA-1, X.509 and replica set roles. |
| elasticsearch, opensearch | ✅ | `cameleer-datastores`, REST/JSON over `cameleer-http` (HTTPS with `enableSSL`/`sslContextParameters`, `user`/`password`, `apiKey`, `hostAddresses` failover). Operations Index, Update, Bulk, GetById, MultiGet, Delete, DeleteIndex, Exists, Search, MultiSearch, Ping; headers `operation`, `indexName`, `indexId`, `size`, `from`, `documentClass`; `enableDocumentOnlyMode`. Scroll searches (`useScroll`, `scrollKeepAliveMs`: every page fetched with `_search/scroll`, context cleared, property `CamelElasticsearchScrollQueryCount`), sniffing (`enableSniffing`, `sniffInterval`, `sniffAfterFailureDelay`: hosts replaced by the `GET /_nodes/http` publish addresses), typed `documentClass` (an `EsDocumentClass` bean or inline `field:type,...` spec mapping `_source` documents to declared fields and types; Java map class names keep generic documents). The embedded server implements scroll contexts and node info. |
| cql | ✅ | `cameleer-datastores`, own CQL native protocol v4 client (PasswordAuthenticator, prepared statements with re-prepare, paging via `fetchSize`, consistency/serial consistency, TLS, multiple contact points, LZ4 / Snappy frame compression with own codecs (`compression`), token-aware routing (`tokenAware`, default on: Murmur3 tokens of the partition key bind values from the PREPARED pk indexes, ring from `system.local` + `system.peers_v2`/`system.peers`, per-node connections; `tokenAware=false` uses the contact points in order)). `cql://host1,host2:port/keyspace?cql=...` or `cql:bean:<CqlSession>`; body = bind values, header `CamelCqlQuery`; `resultSetConversionStrategy` ALL/ONE/LIMIT_n; polling consumer (one exchange per poll). Values map to text/numbers/bytes/arrays/objects (timestamps as ISO-8601 text, durations as Cassandra duration text with vint codec, UDTs as objects). The embedded server supports compression, `CREATE TYPE` / UDT columns and literals, `CREATE INDEX` (indexed equality without `ALLOW FILTERING`), duration columns and a configurable token ring (`set_ring`). `loadBalancingPolicyClass`/`datacenter` are accepted (no DC-aware policy). |
| couchdb | ✅ | `cameleer-datastores`, REST API over `cameleer-http` (`couchdb:http(s)://host:port/db`, `createDatabase`, `username`/`password`). Producer saves (POST/PUT, `_rev` updates; array bodies in one `_bulk_docs` request with per-document results), `CouchDbMethod=GET`/`DELETE`; headers `CouchDbId`, `CouchDbRev`; `DocumentConflictException` / `NoDocumentException`. Consumer follows the `_changes` longpoll feed from the current sequence (`since`, `updates`, `deletes`, `heartbeat`, `style`, `maxMessagesPerPoll`) with headers `CouchDbDatabase`, `CouchDbSeq`, `CouchDbId`, `CouchDbRev`, `CouchDbMethod`. `couchbase` ❌ (binary KV protocol out of scope). |
| cxf (SOAP web services) | ✅ | `cameleer-soap`. WSDL 1.1 parser (XSD types, messages, portTypes, SOAP 1.1 and 1.2 bindings, document/literal (wrapped and bare), rpc/literal and rpc/encoded basics (`xsi:type` accessors, `href` multi-refs), `soap:header` parts (bound in POJO mode: extra positional / named parameters, result object entries), services/ports, `soapAction`, WSDL/XSD imports), SOAP 1.1/1.2 envelopes and faults (`faultcode`/`faultstring`/`faultactor`/`detail`, `Code`/`Subcode`/`Reason`/`Role`/`Detail`). `cxf://http(s)://host:port/path?wsdlURL=...&serviceName={ns}Svc&portName={ns}Port&dataFormat=POJO\|PAYLOAD\|RAW\|CXF_MESSAGE&defaultOperationName=...` (`cxf:/path` = platform port). Producer: headers `operationName`, `operationNamespace`, `SOAPAction`, `CamelCxfSoapHeaders`; POJO maps an array (positional) / object (named) / scalar to the wrapper per WSDL+XSD with typed values and back (return value, or an object for several out parts; without WSDL a JAX-WS style `arg0..n` wrapper); PAYLOAD = body element XML; RAW/CXF_MESSAGE = whole envelope. Faults → `SoapFault` error + `CamelCxfFault{Code,String,Detail}` headers. Consumer: on cameleer-http's server, SOAP 1.1 and 1.2, dispatch by SOAP action (header or 1.2 `action` parameter) or body element, `operationName`/`operationNamespace` headers, exceptions → faults (`SoapFault::into_error` keeps code/detail), one-way → 202, `?wsdl` with rewritten address (`publishedEndpointUrl`), `schemaValidationEnabled`. WS-Security: UsernameToken text/digest (`wsSecurityUsername`/`wsSecurityPassword`/`wsSecurityPasswordType`, consumer `wsSecurityUsers`) with nonce replay and freshness checks, `wsu:Timestamp`, enveloped envelope signature (`wsSecuritySignatureKey`/`...Certificate`, consumer `wsSecuritySignatureVerifyCertificate`, cameleer-xml xmlsecurity). HTTP basic auth, `sslContextParameters`, timeouts. MTOM/XOP (`mtomEnabled`, `mtomThreshold`) and SwA attachments (`CamelAttachments` property) both ways; XML Encryption of the body (AES-128/256-CBC/GCM, RSA-OAEP key transport via cameleer-tls: `wsSecurityEncryptionCertificate`/`Key`, `wsSecurityEncryptionAlgorithm`, `wsSecurityDecryptionKey`); X.509 BinarySecurityToken signatures (`wsSecuritySignatureKeyIdentifier`, consumer `wsSecuritySignatureTrustedCertificates`); SAML 2.0 assertions (`wsSecuritySamlSubject`/`Issuer`/`Attributes`, consumer `wsSecuritySamlRequired`/`TrustedIssuers`, `CamelCxfSaml*` headers); WS-Addressing (`wsAddressingEnabled`/`features=wsa`, RelatesTo checks, decoupled ReplyTo) and WS-RM basics (`wsrmEnabled`: CreateSequence/TerminateSequence, acknowledgements, duplicate suppression); `cxf:bean:` (options from an object/map bean); code-first `serviceClass=#ServiceDescriptor` with WSDL generation. Not implemented: WS-Policy, WS-SecureConversation, signed SAML / holder-of-key, WS-RM persistence and resend. |
| cxfrs (JAX-RS) | ✅ | `cameleer-soap`: resource model from `ResourceDescriptor` beans (`resourceClasses=#bean,...`: class path, methods with HTTP method, path template, `consumes`/`produces`; Java class names ignored) or inline `operations=name:METHOD:/path/{param};...`; `415` for unsupported request media, `406` for unacceptable `Accept`; entity providers (`providers=#bean`, `EntityProvider` = MessageBodyReader/Writer for media types) on consumer and producer, JSON built in. Consumer sets `operationName`, `CamelHttpMethod`, `CamelHttpPath` (relative), `CamelHttpUri`, `CamelHttpQuery`, path/query parameters as headers; replies JSON/text/bytes or provider output, `CamelHttpResponseCode`; unmatched operation → 404. Producer (`httpClientAPI` style): `CamelHttpMethod`/`CamelHttpPath`/`CamelHttpQuery`, JSON or provider bodies, `parseJson`, `throwExceptionOnFailure`. Not implemented: JAX-RS proxy-client API, sub-resource locators. |
| spring-ws | ✅ | `cameleer-soap`. Consumers `rootqname:`, `soapaction:`, `uri:`, `xpathresult:` (`expression`), `action:`/`to:` (WS-Addressing), `beanname:` (a `SpringWsMapping` registry bean — predicate or root-QName/SOAP-action/WSA-action mapping — or a String bean holding another endpoint spec) sharing one dispatcher per `address` (default `/ws` on the platform port; unmatched → 404); payload XML body, `CamelSpringWebserviceSoapAction`/`SoapHeader`/`AddressingAction` headers, exceptions → faults, null reply → 202. Producer `spring-ws:http://...` with `soapAction`, `wsAddressingAction`, `soapVersion`, `timeout`, header overrides (`CamelSpringWebserviceEndpointUri`...), faults → `SoapFaultClientException`; WS-Security options as in cxf. Spring message factories/interceptors are accepted and ignored; no SOAP attachments. |
| fhir | ✅ | `cameleer-soap`. `fhir://<api>/<method>?serverUrl=...&fhirVersion=R4&encoding=JSON\|XML`: `create/resource`, `read/resourceById`/`resourceByUrl`, `update/resource`, `delete/resource`/`resourceById`/`resourceConditionalByUrl`, `search/searchByUrl`, `history/onInstance`/`onType`/`onServer`, `transaction/withBundle`/`withResources`, `capabilities/ofType`, `load-page/next`/`previous`/`byUrl`, `operation/onServer`/`onType`/`onInstance`/`onInstanceVersion` (`name`, `parameters` as a `Parameters` resource or a name → value object, `useHttpGet`) and `operation/processMessage`, `patch/withBody`/`withUrl` (JSON Patch, XML Patch, FHIRPath Patch `Parameters`), `meta/getFromServer`/`getFromType`/`getFromResource`/`add`/`delete`, `validate/resource` (server `$validate`, or local validation against a `profile` StructureDefinition from a file / `#bean` / text; `CamelFhirValidationSuccessful` header); `fhirVersion` DSTU3/R4/R4B/R5 selects the type registry; parameters from options or `CamelFhir.<name>` headers, the body supplies the main one (`inBody`); resources as values or JSON/XML text; basic (`username`/`password`) and bearer (`accessToken`) auth; HTTP errors → HAPI exception kinds (`ResourceNotFoundException`, `ResourceGoneException`, `AuthenticationException`...). `cameleer_soap::testing::FhirMock`: in-memory R4 server (CRUD, versioning, vread, search with token/reference/prefix matching and paging, history, transaction/batch with `urn:uuid` rewriting, JSON+XML, auth, `$meta`/`$meta-add`/`$meta-delete`, `$validate`, `Patient/$everything`, `$process-message`, `$echo`, PATCH with JSON Patch and FHIRPath Patch). No HAPI typed client builders (Camel's API surface only). |
| Datastore servers for tests | ✅ | `cameleer_datastores::testing`: `RedisServer` (RESP2/3, auth, pub/sub, TLS), `MongoServer` (OP_MSG, SCRAM, TLS, query engine with `$eq $gt $gte $lt $lte $ne $in $nin $and $or $nor $not $exists $regex $size $all $elemMatch $type`, update operators, aggregation `$match $group $sort $limit $skip $project $addFields $count $unwind`, capped collections/tailable cursors, change streams), `ElasticsearchServer` (inverted index, match/term/bool/range/... queries, `_bulk`, auth, TLS), `CassandraServer` (CQL v4, CQL subset engine, auth, paging, TLS), `CouchDbServer` (revisions, `_changes`, auth). |

## DSLs

| DSL | Status | Notes |
|---|---|---|
| Rust fluent DSL (equivalent of the Java DSL) | ✅ | `end()` with no open block is tolerated, as in the Java DSL. Route configurations: `ctx.add_route_configuration(...)` + `route_configuration_id(...)`. |
| YAML DSL | ✅ | All EIPs of the Rust DSL incl. marshal/unmarshal, `routeConfiguration` (onException, onCompletion, intercepts, errorHandler), top-level `errorHandler`, beans via registered factories, line/column error messages. Throttle needs a constant maximum; Kamelet, Pipe and KameletBinding resources (and `kamelet:` uris) are supported; options the core does not model (e.g. `executorService`) are ignored. |
| XML DSL | ✅ | `cameleer-yaml/src/xml.rs` converts XML to the YAML model and reuses the YAML step handlers, so coverage follows the YAML DSL. |
| REST DSL (Rust) | ✅ | See the rest component. |
| REST DSL in YAML | ✅ | `rest`/`restConfiguration` in YAML and XML (registered by `cameleer-main`), OpenAPI document. `rest` elements loaded before the context starts become routes at startup, so a `restConfiguration` from any file (earlier or later) applies. |

## Management and tooling

| Feature | Status | Notes |
|---|---|---|
| Route statistics, in-flight repository | ✅ | `RouteStats`, `inflight_count`, controlbus `stats`. |
| JMX-style management, health checks, dev console | ✅ | `managed_context()` (route/processor statistics, operations, JSON + Prometheus export), health check registry (context/routes/consumers, readiness/liveness), dev console `/q/health`, `/q/metrics`, `/q/dev/*` with route start/stop/suspend/resume. No JMX (not applicable). |
| `cameleer-main` runner (`application.properties`, route discovery, `duration-max-*`) | ✅ | |
| CLI `cameleer` (Camel JBang equivalent) | ✅ | `cameleer_main::cli` / `cameleer` binary: `init` (route `.yaml`/`.xml`, `.kamelet.yaml`, `.pipe.yaml`, `.integration.yaml`, `.properties` templates), `run` (files or the current directory, `application.properties/yaml`, `--profile`, `--dev` hot reload of changed route files, `--background`, `--name`, `--prop`, `--console`, `--port`, `--trace`, `--max-*`), `export` (standalone Cargo project embedding the routes and configuration with `include_str!`, depending on cameleer-main by path — crates.io is not reachable), `bind` (Pipe from Kamelets/uris with steps, `--property source.k=v`, `--error-handler`), `ps`, `stop` (`--all`), `get routes/context/health/endpoints`, `cmd start-route/stop-route/suspend-route/resume-route/reset-stats/reload`, `log` (`--follow`, `--tail`), `trace`, `catalog components/languages/kamelets`, `version`. Like JBang, running integrations publish `$CAMEL_HOME/<pid>.json` status files, log to `<pid>.log` and take commands from `<pid>-action.json` (`cameleer_main::local`); `get --url` queries a management server instead. No Maven/Gradle export, `jbang` plugins or Kubernetes deployment. |
| Spring Boot / Quarkus integration, Camel K | ✅ | There is no JVM, so the frameworks themselves do not apply; cameleer-main provides what they provide to Camel. **Spring Boot / Quarkus**: `application.properties` and `application.yaml` (nested keys flattened, multi-document), profiles (`camel.main.profile`, `spring.profiles.active`, `quarkus.profile`, env `SPRING_PROFILES_ACTIVE`/`QUARKUS_PROFILE`/`CAMEL_MAIN_PROFILE`; `application-<profile>.*`, `%profile.key`, YAML `spring.config.activate.on-profile`), `camel.springboot.*`/`quarkus.camel.*` aliases of `camel.main.*`, `server.port`/`quarkus.http.port`, relaxed binding (case, dashes, underscores) including `CAMEL_*` environment variables (`CAMEL_COMPONENT_SEDA_QUEUE_SIZE`), generic `camel.component.<scheme>.<option>` component options (core: defaults for the endpoint options of that scheme, `ctx.set_component_option`), `camel.beans.<name>=#class:<type>` beans via registered bean factories (the auto-configured beans/DI of Spring), health/metrics/dev consoles (`camel.server.*`, the Actuator/Quarkus `/q/*` endpoints). **Camel K**: `kind: Integration` resources run in-process by cameleer-main (`spec.flows`, inline `spec.sources` yaml/xml, `spec.configuration` properties, `traits.camel.properties`, `traits.environment.vars`, `metadata.name` as the name; Kubernetes-only traits are ignored with a log line; `dependencies` are informational since every component is built in); Pipes/Kamelets as above; `cameleer run`/`cameleer ps`/`cameleer log` replace `kamel run/get/logs`. No operator, Kubernetes deployment or image build. |

## Known deviations found by the conformance suite

These differences are kept on purpose (documented, not fixed):

1. In Simple text, `$${` is an escape that produces a literal `${`.
2. TLS comes from the in-house `cameleer-tls` crate (unaudited; see its limitations), not a mature library.
3. Asynchronous delays (`asyncDelayed`, `asyncDelayedRedelivery`) hand the waiting exchange to its (released) thread and start a replacement consumer thread, instead of scheduling a continuation on a scheduler pool.

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html

# Deploying Cameleer

Cameleer runs anywhere a container or a single Linux, macOS or Windows binary runs. This guide
covers the container image: Docker, Docker Compose, Kubernetes and serverless platforms.

## The image

| | |
|---|---|
| Name | `pmsudhi/cameleer` on Docker Hub, also `ghcr.io/pmsudhi/cameleer` |
| Platforms | `linux/amd64`, `linux/arm64` |
| Contents | one native binary (glibc) on `gcr.io/distroless/cc-debian12:nonroot`: CA certificates, tzdata, no shell |
| Size | about 20 MB to download; under 12.5 MB built with `FEATURES=core` ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) |
| Entrypoint | `cameleer` (the CLI): `run`, `version`, `get health`, `--help` |
| Working directory | `/routes`: mount route files here, read-only is fine |
| Port | `8080`: the REST DSL, `platform-http` and the health endpoints share it |
| User | `65532` (nonroot); any other `--user` works |
| Filesystem | nothing is written: `CAMEL_LOCAL_STATUS=false`, logs go to stdout; works with a read-only root filesystem |
| Stop | `SIGTERM` stops the routes gracefully (about half a second for a REST route) |
| Tags | `latest`, `0.3.0`, `0.3`, `edge` (manual builds of `main`), `sha-<commit>` |
| Supply chain | SBOM, max-mode build provenance and a GitHub attestation on every push |

Verify an image's provenance:

```sh
gh attestation verify oci://ghcr.io/pmsudhi/cameleer:latest --owner pmsudhi
```

## Configuration

Settings come from, in increasing priority:

1. `application.properties` or `application.yaml`, passed with `--properties /config/application.properties`
2. environment variables: `CAMEL_SERVER_PORT=9090` sets `camel.server.port`, and so on
3. `--prop key=value` on the command line

Routes read environment values with `{{env:NAME:default}}`, as in Apache Camel. Settings can
use them too: `camel.server.port={{env:PORT:8080}}`.

Health endpoints need the management server on:

```sh
--prop camel.server.enabled=true --prop camel.server.healthCheckEnabled=true
```

This serves `/q/health`, `/q/health/live` and `/q/health/ready` on port 8080. Readiness is
`DOWN` (HTTP 503) while a route is stopped. `cameleer get health --url http://localhost:8080`
exits with status 1 when it is DOWN, so it can serve as a Docker health check.

Don't turn on `camel.server.devConsoleEnabled` (or `cameleer run --console`) in production
without a network policy in front: the dev console has unauthenticated endpoints that stop
and start routes.

## Docker

```sh
docker run --rm -p 8080:8080 --read-only \
  -v "$PWD/routes:/routes:ro" \
  -e OPENAI_API_KEY \
  pmsudhi/cameleer run /routes/my-route.camel.yaml
```

- Mount route folders read-only (`:ro`) unless a route writes there. For a route that writes
  into a mounted folder (the file component's `move`, for example), run as your own user so the
  files are yours: `--user "$(id -u):$(id -g)"`.
- Reach services on the host with `--network host` on Linux. With Docker Desktop on macOS or
  Windows, use `host.docker.internal` instead. Kafka brokers must also advertise an address the
  container can reach.

### Baking routes into your own image

For production, ship an image that contains the routes:

```dockerfile
FROM pmsudhi/cameleer:0.3.0
COPY routes/ /routes/
CMD ["run", "/routes/my-route.camel.yaml", "--prop", "camel.server.enabled=true", "--prop", "camel.server.healthCheckEnabled=true"]
```

## Docker Compose

```yaml
services:
  orders:
    image: pmsudhi/cameleer:0.3.0
    command: ["run", "/routes/rest-api.camel.yaml",
              "--prop", "camel.server.enabled=true", "--prop", "camel.server.healthCheckEnabled=true"]
    ports: ["8080:8080"]
    volumes: ["./routes:/routes:ro"]
    read_only: true
    healthcheck:
      test: ["CMD", "/usr/local/bin/cameleer", "get", "health", "--url", "http://localhost:8080"]
      interval: 10s
      timeout: 3s
      retries: 3
```

## Kubernetes

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: orders-routes
data:
  rest-api.camel.yaml: |
    # paste examples/rest-api.camel.yaml here
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: orders
spec:
  replicas: 2
  selector:
    matchLabels: { app: orders }
  template:
    metadata:
      labels: { app: orders }
    spec:
      terminationGracePeriodSeconds: 30
      securityContext:
        runAsNonRoot: true
        seccompProfile: { type: RuntimeDefault }
      containers:
        - name: cameleer
          image: pmsudhi/cameleer:0.3.0
          args: ["run", "/routes/rest-api.camel.yaml",
                 "--prop", "camel.server.enabled=true",
                 "--prop", "camel.server.healthCheckEnabled=true"]
          ports:
            - { name: http, containerPort: 8080 }
          env:
            - name: OPENAI_API_KEY
              valueFrom: { secretKeyRef: { name: openai, key: api-key, optional: true } }
          resources:
            requests: { cpu: 50m, memory: 32Mi }
            limits: { memory: 256Mi }
          readinessProbe:
            httpGet: { path: /q/health/ready, port: http }
            periodSeconds: 5
          livenessProbe:
            httpGet: { path: /q/health/live, port: http }
            periodSeconds: 10
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities: { drop: ["ALL"] }
          volumeMounts:
            - { name: routes, mountPath: /routes, readOnly: true }
      volumes:
        - name: routes
          configMap: { name: orders-routes }
```

A route uses about 10 MB at rest, most of it pages of the binary itself; the private memory of
a running route is 1–2 MB. Size the memory limit for your message sizes and concurrency, not
for a JVM.

## Serverless

- **Google Cloud Run, Knative, Azure Container Apps, Fly.io:** these run the image as it is. Cloud Run sends
  requests to `PORT`, which is 8080 unless you change it. If you do change it, add
  `--prop camel.server.port={{env:PORT:8080}}`. Startup takes milliseconds, so scale-to-zero
  has no practical cold-start cost from Cameleer itself.
- **AWS Lambda:** see [below](#aws-lambda). `cameleer` is its own Lambda custom runtime.

## AWS Lambda

`cameleer` serves Lambda invocations itself on the `provided.al2023` runtime: no runtime
library, adapter or layer. When Lambda sets `AWS_LAMBDA_RUNTIME_API`, `cameleer run` starts the
routes and then loops over the
[Runtime API](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-api.html) instead of
waiting for a signal.

- **HTTP events** (API Gateway REST and HTTP APIs, function URLs, ALB) go to your
  `platform-http` routes as if they had come over a socket, and the HTTP response becomes the
  proxy-integration response. The same route file runs on Lambda and in a container.
- **Other events** (S3, SQS, EventBridge, a direct invoke) are sent request-reply to the
  handler endpoint with the event JSON as the body; the reply body is the function result. The
  handler endpoint is the function's **Handler** setting when it is an endpoint URI (for example
  `direct:orders`), else `camel.main.lambda-handler`, else `direct:lambda`.
- A failed exchange is reported to the invocation's `/error` endpoint (`errorType` is the
  exception kind); a startup failure (a bad route file, an unknown component) to `/init/error`.
- Exchange headers: `CamelAwsLambdaRequestId`, `CamelAwsLambdaDeadlineMs`,
  `CamelAwsLambdaFunctionArn`, `CamelAwsLambdaTraceId`, and when Lambda sends them
  `CamelAwsLambdaClientContext` and `CamelAwsLambdaCognitoIdentity`.
- Status files for `cameleer ps` are off on Lambda (the file system is read-only); logs go to
  CloudWatch through stderr.

```yaml
# orders.camel.yaml: an S3 or EventBridge event in, a JSON summary out
- route:
    from:
      uri: direct:lambda
      steps:
        - setBody:
            simple: '{"bucket":"${jsonpath($.Records[0].s3.bucket.name)}","ok":true}'
```

Package and deploy (the binary must be a static musl build: AL2023 has glibc 2.34, older than
what current build machines link against):

```sh
scripts/package-lambda.sh --arch x86_64 --features cloud --out function.zip orders.camel.yaml
aws lambda create-function --function-name orders --runtime provided.al2023 \
  --architectures x86_64 --handler direct:lambda --zip-file fileb://function.zip \
  --role arn:aws:iam::<account>:role/<role>
```

The zip holds `bootstrap` (the `cameleer` binary under the name Lambda starts; with no
arguments it runs the route files in `$LAMBDA_TASK_ROOT`) and your route files. `--features`
keeps only the component families the routes use (see [build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)), which
makes the zip and the cold start smaller. Measured init times are in
[BENCHMARKS.md](https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html#faas-cold-start-and-size).

`camel.main.duration-max-messages` stops after that many invocations (useful in tests). Lambda
sends SIGTERM before it shuts a sandbox down; routes are stopped gracefully then.

## Smaller builds

The default build and image contain every component family. A function, an edge device or a
slim image can leave the rest out with the cargo features of `cameleer-main`. The
[build features guide](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html) lists every feature and what it adds, shows how
to choose them for your routes, and has the commands for each kind of build. In short:

```sh
docker build --build-arg FEATURES=cloud,sql,jq -t my-cameleer .
cargo install cameleer-main --no-default-features --features cloud,sql,jq
scripts/package-lambda.sh --features cloud,jq --out function.zip orders.camel.yaml
```

- A feature list **replaces** the default: name every family you use. The template engines,
  `jq`, the core XPath subset, `http2` and `validate` (`cameleer validate`, `cameleer schema`)
  are features too.
- A route that uses something left out fails at startup with the feature to add, for example
  ``No component found with scheme: kafka (this cameleer binary was built without the
  `kafka-mqtt` feature; rebuild cameleer-main with `--features kafka-mqtt`)``.
- `cameleer version` lists the features of a build.
- `FEATURES=core` is the smallest: 5.8 MB (glibc) or 6.0 MB (static musl) on Linux x86-64,
  against 23.9 MB with every component. More sizes and cold-start times are in
  [BENCHMARKS.md](https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html#faas-cold-start-and-size).

## Without a container

```sh
cargo install cameleer-main
cameleer run my-route.camel.yaml
```

Camel JBang habits carry over with the `cameleer` command: `cameleer ps`, `cameleer log`,
`cameleer stop`. Those commands use status files under `~/.camel` (`CAMEL_HOME`). Set
`CAMEL_LOCAL_STATUS=false` to run without them.

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/INTEROP.html

# Interop verification against real servers

Most Cameleer components are tested against embedded test servers written in this workspace
(`crates/*/src/testing`). Those can only prove that client and server agree with each other.
The **live interop suite** runs Cameleer routes against real, independent server software
installed from the Ubuntu 24.04 archive, so wire-level misunderstandings show up.

## Running it

```sh
sudo scripts/live-interop.sh all          # apt-get install, configure, start (idempotent)
CAMEL_LIVE_INTEROP=1 cargo test --workspace live_
scripts/live-interop.sh status            # which ports answer
sudo scripts/live-interop.sh stop
```

The suites live in `crates/<crate>/tests/live_*.rs` and do nothing unless
`CAMEL_LIVE_INTEROP=1` is set, so the normal `cargo test` stays hermetic and fast. Shared
helpers (`cameleer_tls::testing::live`) give the state directory (`CAMEL_INTEROP_DIR`, default
`/var/lib/camel-interop`), the test password and TLS parameters trusting the interop CA.

`scripts/live-interop.sh` keeps everything under the state directory: a test PKI made with
`openssl` (an RSA CA, a `localhost`/`127.0.0.1` server certificate, a client certificate, plus
PKCS#12 stores for Java), a private PostgreSQL cluster, and configuration files for every
server, all listening on 127.0.0.1 on non-default ports (the port table is at the top of the
script). Every account uses the password `camelpw` (system users `camelftp` and `camelmail`).

## Results

Run on 2026-11-01. All 72 live tests pass (`CAMEL_LIVE_INTEROP=1 cargo test --workspace live_`), including
27 against Apache ActiveMQ 5.17 (12 STOMP, 5 MQTT and 10 AMQP 1.0, the latter with the
`activemq-amqp` module added, see below).

| Server (version) | Components | What was verified | Result |
|---|---|---|---|
| PostgreSQL 16.15 | `sql`, `jdbc`, `sql-stored`, `JdbcIdempotentRepository`, `JdbcAggregationRepository`, transaction policy, PG wire client | the shared producer suite (named / positional / IN-list parameters, generated keys, SelectOne / StreamList / outputHeader / noop, batch atomicity, `useMessageBodyForSql`, SQLSTATE → exception kinds, `jdbc` with `readSize` and headers as parameters), `sql-stored` with real PL/pgSQL procedures and functions (OUT / INOUT, `RETURNS TABLE`, `RAISE EXCEPTION`, file templates, batch rollback), polling consumer with `onConsume` + JDBC idempotent repository, aggregation repository with recovery, local transactions (isolation, rollback, aborted-transaction state, server-side rollback of dropped connections), route `policy` / `rollback`, pooled connections reusing the backend, SCRAM-SHA-256 (wrong password → 28P01), types (smallint, char padding, numeric, real, bytea, jsonb, uuid, date, timestamp, UTF-8), 5000-row results, NOTICEs, `sslmode=require` / `verify-ca` / `verify-full` (host name and IP SAN; wrong CA refused) | pass |
| Redis 7.0.15 | `spring-redis` producer and consumer, `RedisIdempotentRepository`, `RedisAggregationRepository`, `RedisClient` | strings / hashes / lists / sets / sorted sets / keys / expiry commands, JSON and binary values, `WRONGTYPE`, `requirepass` (NOAUTH, WRONGPASS), `AUTH default` over RESP3 (`HELLO 3`) with map replies, database selection, 200-command pipelines, MULTI/EXEC, 1 MiB values, SUBSCRIBE / PSUBSCRIBE consumers fed by the server, both repositories, TLS port verified against the CA (untrusted CA refused) incl. a TLS subscriber | pass |
| Eclipse Mosquitto 2.0.18 | `paho`, `paho-mqtt5`, `MqttClient` | QoS 0/1/2 round trips with both protocol versions, broker-side QoS downgrade, 256 KiB payloads, `+` / `#` wildcards, `CamelPahoOverrideTopic`, retained messages to late subscribers and clearing them, username/password listener (bad credentials and anonymous refused), TLS listener verified against the CA, will messages, persistent sessions queueing QoS 1 messages while offline (3.1.1 clean-session=false and 5.0 session expiry), unsubscribe | pass |
| RabbitMQ 3.12.1 (Erlang 25.3) — AMQP 0-9-1 | `spring-rabbitmq`, `rabbitmq`, AMQP client | direct / topic / fanout exchanges, AMQP headers and properties (correlation id, priority, message id, expiration, delivery mode, typed header values), JSON bodies, manual ack with reject + requeue (redelivered flag), retries then dead-lettering through a real DLX with `x-death` / `x-first-death-*`, `prefetchCount` (2 unacked, 3 ready), InOut request/reply over exclusive reply queues with competing consumers, remote failures, reply timeouts, publisher confirms, mandatory returns (312 NO_ROUTE), authentication failure, AMQPS (TLS 1.3 and forced TLS 1.2) verified against the CA | pass |
| RabbitMQ 3.12.1 — STOMP plugin | `stomp`, `jms`, `activemq` | queues with competing / concurrent consumers, topics fan-out, JMS headers and properties (`_DOT_` / `_HYPHEN_` keys), NUL-containing byte bodies, InOut over RabbitMQ temporary queues, fixed `replyTo`, remote failures and timeouts, `transacted=true` redelivery, `CLIENT_ACKNOWLEDGE` NACK redelivery, AUTO acknowledging failures, durable topic subscriptions keeping messages while the route is stopped, bad credentials, STOMP over TLS. RabbitMQ needs `host=/` (the STOMP `host` header names the virtual host) and has no JMS selectors (not tested) | pass |
| RabbitMQ 3.12.1 — AMQP 1.0 plugin | `amqp` (JMS over AMQP 1.0) | RabbitMQ addresses (`amqp:queue:/queue/x`, `amqp:topic:/topic/key`), JMS header mapping, text / bytes / map bodies, competing consumers, topic fan-out, request/reply with fixed `replyTo` queues, remote failures, timeouts, `CLIENT_ACKNOWLEDGE` redelivery with `JMSRedelivered`, bad credentials, AMQPS. Broker limitations (asserted as clear errors): no dynamic reply nodes (`Dynamic sources not supported`), no transactions (`amqp:not-implemented`), no selectors | pass |
| RabbitMQ 3.12.1 — MQTT plugin | `paho` | QoS 0/1 publish and wildcard subscription with credentials | pass |
| vsftpd 3.0.5 | `ftp`, `ftps`, FTP client | passive and active mode, mkdirs / STOR / APPE / RETR (200 KB binary) / SIZE / MDTM / LIST / NLST / RNFR-RNTO / DELE / RMD, ASCII mode, wrong password; consumer with `move`, `antInclude`, `sortBy`, recursive `delete` (active mode), `noop` idempotency; producer `fileExist` Fail / Ignore / Append / Override with `tempPrefix` / Move with `moveExisting`, `fileName` expressions, `disconnect`; explicit FTPS (AUTH TLS, PROT P), implicit FTPS, and a `require_ssl_reuse=YES` server (data connections resume the control session; without resumption the transfer is refused with 522) for the client and the `ftps` component; untrusted CA refused | pass |
| Postfix 3.8.6 + Dovecot 2.3.21 | `smtp`, `smtps`, `imap`, `imaps`, `pop3`, `pop3s` | SMTP into Postfix local delivery (Maildir) with custom headers, Cc, UTF-8 subject, dot-stuffing; POP3 consume with delete; SMTP AUTH through Dovecot SASL over STARTTLS (required) with binary and UTF-8 attachments, wrong password → `AuthenticationFailedException`; IMAP consume with `moveTo=Archive`; SMTPS (implicit TLS) → IMAPS with `\Seen` marking and failed exchanges left unseen (checked in Dovecot's Maildir flags); POP3 STLS and POP3S | pass |
| nginx 1.24.0 | `http`, `https` producer | GET / POST / PUT / PATCH / DELETE, forwarded query, custom headers, 1 MiB binary POST, 404 with and without `throwExceptionOnFailure`, 302 with and without `followRedirects`, gzip content coding decoded (compression proven from nginx's access log), keep-alive pooling (nginx `$connection` stays the same; `connectionClose=true` opens new ones), HTTPS verified against the CA by host name and IP SAN, TLS keep-alive, untrusted CA refused; HTTP/2 over TLS via ALPN (`$server_protocol` = HTTP/2.0) with POST, 300 KB request bodies across flow-control windows, gzip, multiplexing on one connection, 404; h2c with prior knowledge | pass |
| Apache ActiveMQ 5.17.6 — STOMP | `stomp`, `jms`, `activemq` | see [Apache ActiveMQ 5.17](#apache-activemq-517): JMS selectors on queues, topics and durable subscriptions, `/temp-queue/` request/reply (also shared `replyTo` queues read with broker-side `JMSCorrelationID` selectors), durable subscriptions, transactions with client-side redelivery and dead-lettering, priority and expiry, persistent / non-persistent, map / object messages, virtual topics, simple authentication, STOMP+SSL | pass |
| Apache ActiveMQ 5.17.6 — MQTT | `paho` | QoS 0/1/2, broker-side QoS downgrade, 256 KiB payloads, wildcards, retained messages, persistent sessions, simple authentication, MQTT+SSL, MQTT ↔ STOMP topic bridging; MQTT 5 refused (ActiveMQ 5 speaks 3.1.1) | pass |
| Apache ActiveMQ 5.17.6 — AMQP 1.0 (`activemq-amqp` 5.17.6, proton-j 0.34) | `amqp` (JMS over AMQP 1.0) | see [AMQP 1.0](#amqp-10-transport): queues, topic fan-out to several non-durable subscribers (`queue://` / `topic://` address prefixes), JMS selectors, AMQP 1.0 transactions with redelivery, dynamic temporary reply queues, durable subscriptions, the JMS mapping through ActiveMQ's JMS transformer (text / bytes / map / object bodies, typed properties, `JMSReplyTo` topics, message annotations), 3 MB multi-frame messages, `CLIENT_ACKNOWLEDGE` / rollback redelivery counts, SASL PLAIN, AMQPS; JMS 2.0 shared subscriptions refused (ActiveMQ 5 has none) | pass |
| OpenJDK 21 JSSE (`java` single-file launcher, keytool stores) | `https` producer, `jetty:https` consumer | the https producer against `com.sun.net.httpserver.HttpsServer` restricted to TLS 1.3 and to TLS 1.2 (PKCS#12 key store from openssl, negotiated protocol and cipher echoed back), 300 KB bodies, untrusted CA refused; Java's `HttpClient` (offering HTTP/2 via ALPN, and HTTP/1.1) against a Cameleer `jetty:https` route with a keytool trust store, GET and UTF-8 POST (ALPN falls back to HTTP/1.1, which the camel server speaks) | pass |

Not installable / not verified: nothing from the requested list was missing from the archive.
Apache ActiveMQ 5.17.6 *is* packaged (universe) and is covered over STOMP and MQTT (see
[Apache ActiveMQ 5.17](#apache-activemq-517) below), which now verifies JMS selectors,
`/temp-queue/` request/reply, ActiveMQ durable subscriptions and ActiveMQ's transaction and
redelivery semantics against the real broker. Ubuntu's package leaves out the `activemq-amqp`
module; `scripts/live-interop.sh install` adds it from Maven Central (SHA-1 pinned, or copied
by hand when Maven Central is not reachable), so AMQP 1.0 selectors, dynamic temporary nodes
and transactions are verified against ActiveMQ too. Artemis is not packaged.

## Bugs found and fixed

Every fix has a regression test in the hermetic suite as well.

| # | Component | Bug (found against) | Fix | Regression test |
|---|---|---|---|---|
| 1 | `sql-stored` | INTEGER template parameters were bound as `int8`, and PostgreSQL resolves routines by argument type: `procedure subnumbers(bigint, bigint, unknown) does not exist` (PostgreSQL 16) | narrow declared types (INTEGER, SMALLINT, REAL, NUMERIC) are bound as `CAST(? AS type)`, like pgJDBC's `setInt` (`crates/cameleer-sql/src/sql_stored.rs` `call_sql`) | `sql_stored::tests::templates`, `tests/postgres.rs` |
| 2 | `spring-rabbitmq`, `rabbitmq` | a component-wide host/port overrode an endpoint's `addresses=amqps://...`, so the endpoint connected to the plain port (RabbitMQ) | `addresses` takes precedence over host/port (Spring Boot / Camel semantics) (`crates/cameleer-amqp/src/amqp/component.rs`) | `tests/rabbitmq.rs` `endpoint_addresses_take_precedence_over_component_host_and_port` |
| 3 | `stomp`, `jms` | RabbitMQ's `ERROR` for a bad login (`message:Bad CONNECT`, reason in the body) became `StompException` instead of `AuthenticationFailureException` | the frame body is checked too (`crates/cameleer-amqp/src/stomp/client.rs`) | `tests/jms.rs` `rabbitmq_flavoured_broker_conventions` |
| 4 | `jms` (STOMP) | InOut SUBSCRIBEd to `/temp-queue/...`, which RabbitMQ refuses (`not a valid destination for 'SUBSCRIBE'`) | on RabbitMQ (`server:RabbitMQ/...`) the reply queue is only named in `reply-to` and replies are routed by their `subscription:/temp-queue/...` header (`StompConnection::subscribe_reply_queue`) | same |
| 5 | `jms` (STOMP) | NON_PERSISTENT sends carried `persistent:false`, which RabbitMQ reads as the queue's `durable` flag and refuses for the existing durable queue (`RESOURCE_LOCKED` / precondition failure) | the header is only sent for persistent messages (absence = non-persistent for ActiveMQ, Artemis and RabbitMQ) (`crates/cameleer-amqp/src/stomp/component.rs`) | same |
| 6 | `jms` (STOMP) | durable topic subscriptions were not durable on RabbitMQ (ActiveMQ / Artemis headers only) | also `durable:true`, `auto-delete:false` and a stable subscription id (`clientId:name`) | same |
| 7 | `jms` (STOMP) | `transacted=true`: after a failed exchange the aborted transactional ACK left the message unacknowledged on RabbitMQ — never redelivered | on RabbitMQ the message is NACKed (requeued) after the ABORT; ActiveMQ redelivers by itself | same |
| 8 | `amqp` | `amqp:queue:/queue/x` lost its leading slash (`queue:/` was trimmed like `queue://`), so RabbitMQ answered `unknown_destination` | only the `//` of the URL form is stripped (`crates/cameleer-amqp10/src/jms.rs` `parse_destination`) | `jms::tests::destinations_and_keys` |
| 9 | `amqp` | consumers always attached an anonymous-relay reply link; RabbitMQ 3.x does not offer `ANONYMOUS-RELAY` and refused the attach (`address_not_utf8_string`), so no consumer could start | anonymous relay only when the broker offers it, else one reply link per reply address (`ReplySenders`) | `tests/amqp_component.rs` `consumers_work_without_anonymous_relay` (embedded broker option `anonymous_relay(false)`) |
| 10 | `amqp` | redeliveries had `JMSRedelivered=false`: RabbitMQ marks them with `first-acquirer=false` and keeps `delivery-count` at 0 | an explicit `first-acquirer=false` also means redelivered (`Header::acquired_before`, `crates/cameleer-amqp10/src/message.rs`) | `message::tests::explicit_first_acquirer_false_marks_redelivery` |
| 11 | `stomp`, `jms`, `activemq` | ActiveMQ's refused login (`User name [camel] or password is invalid.`, repeated in the body) became a `StompException` with the text twice (ActiveMQ 5.17) | recognised as `AuthenticationFailureException`; a body repeating `message` is not appended (`crates/cameleer-amqp/src/stomp/client.rs` `error_frame_to_error`) | `tests/jms.rs` `activemq_flavoured_broker_conventions` |
| 12 | `jms` (STOMP) | `transacted=true`: after a failure the consumer sent `ABORT` and expected the broker to redeliver; ActiveMQ only restores the pending ack, so the message was never redelivered and blocked the subscription's prefetch window (ActiveMQ 5.17) | on ActiveMQ 5 (`server:ActiveMQ/...`) the consumer redelivers locally like ActiveMQ's JMS client: `RedeliveryPolicy` (`jms.redeliveryPolicy.maximumRedeliveries` (6) / `initialRedeliveryDelay` / `redeliveryDelay` broker-url options), `JMSRedelivered=true`, `JMSXDeliveryCount`, then a `NACK` (poison ack → DLQ) (`crates/cameleer-amqp/src/stomp/component.rs` `Worker::handle`) | same, `redelivery_policy_from_broker_url` |
| 13 | `jms` (STOMP) | `CLIENT_ACKNOWLEDGE`: a failed message was `NACK`ed for redelivery; ActiveMQ treats `NACK` as a poison ack and dead-letters it at once (non-persistent messages are dropped) (ActiveMQ 5.17) | same client-side redelivery; `NACK` only once the policy is exhausted | same |
| 14 | `jms` (STOMP) | sends made by a route consuming with `transacted=true` were committed on their own, so every failed attempt left a duplicate (found against ActiveMQ 5.17, affected every broker) | InOnly sends to the same broker (address and login) from inside a transacted consumer join its STOMP transaction (exchange property `CamelJmsStompTransaction`), as with Spring's thread-bound JMS session: committed or rolled back with the consumed message | same, and `transacted_rollback_redelivers_with_jms_redelivered` |
| 15 | `jms` (STOMP) | `subscriptionShared=true` silently duplicated messages on ActiveMQ 5, whose STOMP adapter ignores the shared subscription headers (every member got every message) (ActiveMQ 5.17) | refused at route start with `UnsupportedOperationException` naming ActiveMQ's virtual topics, as ActiveMQ's (JMS 1.1) client refuses shared consumers | same; live test with virtual topics |
| 16 | `amqp` | two non-durable `amqp:topic:x` routes: a message published to the topic reached only one of them. ActiveMQ 5 ignores the `topic` terminus capability and takes a bare address for a **queue**, so the "subscribers" were competing consumers of queue `x` (and durable subscriptions were queues too) (ActiveMQ 5.17) | the broker's `queue-prefix` / `topic-prefix` open-frame properties (`queue://`, `topic://`) are applied to link and `to` / `reply-to` addresses, as Qpid JMS does, and stripped again for `JMSDestination` / `JMSReplyTo` (a topic becomes `topic:name`, which can be sent to again) (`crates/cameleer-amqp10/src/jms.rs` `AddressPrefixes`) | `tests/amqp_component.rs` `activemq_flavoured_broker_address_prefixes`, `jms::tests::broker_address_prefixes` |
| 17 | `amqp` | `subscriptionShared=true` on ActiveMQ 5: the `shared` capability is ignored, so every member would receive every message (ActiveMQ 5.17) | refused at route start with `UnsupportedOperationException` naming virtual topics when the broker announces `product=ActiveMQ`, `version=5.x` (as with bug 15) | same; live `live_activemq_amqp_shared_subscriptions_refused` |
| 18 | `cameleer-tls` servers (`NetStream::server`, gRPC/HTTP2, the cloud mock servers) | a rejected TLS 1.3 client certificate could reach the client as "connection reset" instead of the alert (`certificate_required`, `unknown_ca`): the client writes application data right after its Finished, the server dropped the socket right after sending the alert, the late data drew a TCP reset, and on Windows a reset discards the unread alert in the receive buffer (Linux returns it first). Seen as a rare flake (1 in 300 under CPU load) of `mutual_tls_rejects_missing_and_untrusted_certificates` on Windows 11 | after a fatal alert the server closes gracefully: FIN after the alert, then it reads and discards until the peer closes (at most 2 s or 256 KiB), like a lingering HTTP close (`crates/cameleer-tls/src/net.rs` `lingering_close`, `accept_tls`, used by `NetStream::server`) | `mtls_resumption.rs` `alert_survives_a_client_that_reads_late` (the client waits 300 ms before reading; it saw `ConnectionReset` before the fix) |

The embedded STOMP broker gained a RabbitMQ flavour (`StompBrokerBuilder::rabbitmq()`) that
reproduces the conventions behind bugs 3-7, and the embedded AMQP 1.0 broker can run without
`ANONYMOUS-RELAY`. An ActiveMQ flavour (`StompBrokerBuilder::activemq()`) reproduces what bugs
11-15 depend on: `server:ActiveMQ/5.17.6`, ActiveMQ's login error, `ABORT` restoring the pending
ack without redelivery and `NACK` as a poison ack. The embedded AMQP 1.0 broker has an ActiveMQ
flavour too (`BrokerBuilder::activemq()`, bugs 16-17): ActiveMQ's open-frame properties, nodes
typed only by the `queue://` / `topic://` prefixes (capabilities ignored, a bare address is a
queue) and no shared subscriptions. `CAMEL_AMQP10_TRACE=1` makes the AMQP 1.0 client (and the
embedded broker) print every frame to stderr, which is how bug 16 was diagnosed.

## Server-side notes

* Mosquitto 2.0 drops messages queued for offline persistent sessions when
  `per_listener_settings true` is used, so the script runs the anonymous and the authenticated
  listeners as two broker processes.
* RabbitMQ's STOMP adapter needs the `host` header to be an existing virtual host (`host=/`
  on Cameleer endpoints or `camel.component.jms.host=/`); Cameleer sends the broker host
  name by default, as Spring's STOMP relay does.
* With RabbitMQ (no selectors) several producers must not share one fixed AMQP 1.0 `replyTo`
  queue: they would compete for each other's replies.

## Apache ActiveMQ 5.17

Apache ActiveMQ 5.17.6 from Ubuntu 24.04 (`activemq`, universe; OpenJDK 21), run on 2026-11-01.
`scripts/live-interop.sh` runs a dedicated instance under `$CAMEL_INTEROP_DIR/activemq` (the
package's `activemq.jar` with its own `activemq.xml`; the Debian init script and instances are
not used):

| Port | Transport connector |
|---|---|
| 16615 / 16616 | STOMP / STOMP+SSL |
| 11886 / 18886 | MQTT / MQTT+SSL |
| 16617 | OpenWire (not used by Cameleer) |
| 15675 / 15676 | AMQP / AMQPS (`transport.transformer=jms`) — only when the `activemq-amqp` module is present (see below) |

* `simpleAuthenticationPlugin` with user `camel` / `camelpw`, anonymous access refused;
* TLS with the interop CA: the openssl PKCS#12 server store converted to a JKS key store by
  `keytool -importkeystore`, plus a JKS trust store with the CA (`<sslContext>`);
* per-destination dead letter queues (`individualDeadLetterStrategy`, `DLQ.<queue>`) so tests
  can inspect them, `prioritizedMessages` on queues, KahaDB persistence;
* Ubuntu's package leaves libraries out of the broker's class path, which the script links
  into the instance's `lib/`: the MQTT codec (`libmqtt-client-java`, without it every MQTT
  connection fails with `NoClassDefFoundError: org/fusesource/mqtt/codec/PINGRESP`), and
  XStream / Jettison (`libxstream-java`, `libjettison-java`, needed for STOMP
  `transformation: jms-map-json` / `jms-object-json`, without them the broker drops the
  connection);
* the package does not include the `activemq-amqp` module at all. `scripts/live-interop.sh
  install` downloads `activemq-amqp-5.17.6.jar` from Maven Central into
  `$CAMEL_INTEROP_DIR/activemq/lib` and keeps it only if its SHA-1 is the pinned
  `cdb7bb9009d36a2d00de970a515976a20cc8ad8e` (a jar already there with another checksum is
  moved aside); its dependency proton-j is linked from `libapache-qpid-proton-j-java` (0.34).
  When Maven Central is not reachable (as from the test environment's proxy) the step prints
  the manual instruction: copy the verified jar there. `setup` + `restart` then add the AMQP
  connectors (`amqp_has_amqp` looks in the package's `lib/`, `lib/optional/` and the instance's
  `lib/`).

Suites: `crates/cameleer-amqp/tests/live_activemq_stomp.rs` (12 tests),
`crates/cameleer-kafka-mqtt/tests/live_activemq_mqtt.rs` (5),
`crates/cameleer-amqp10/tests/live_activemq_amqp.rs` (10, skipped without the AMQP module).

What the STOMP suite verifies with `stomp`, `jms` and `activemq` endpoints:

* the `stomp` component; bad and missing credentials → `AuthenticationFailureException`;
* competing consumers, topic fan-out, `JMSDestination` `queue://` / `topic://`, ActiveMQ
  message ids, `JMSCorrelationID`, `JMSType`, priority, `timeToLive` (`JMSExpiration` -
  `JMSTimestamp`), persistent (default, `JMSDeliveryMode=2`) vs `deliveryPersistent=false`
  (1), dotted / hyphenated property keys, NUL-containing bytes and UTF-8 bodies, MapMessage
  and ObjectMessage through ActiveMQ's JSON transformations;
* **JMS selectors evaluated by ActiveMQ**: on queues (unmatched messages stay on the queue),
  on topics (`JMSPriority >= 7 OR severity IN (...)`) and on a durable subscription while it is
  offline;
* request/reply over ActiveMQ temporary queues (4 concurrent requesters), a fixed shared
  `replyTo` queue read with per-request `JMSCorrelationID` selectors by concurrent producers,
  `replyToType=Exclusive`, `useMessageIDAsCorrelationID`, remote exceptions, timeouts, and no
  stray replies left behind;
* `transacted=true`: redelivery with `JMSRedelivered=true`, a send made inside the transaction
  committed only with the successful attempt, an always-failing message dead-lettered to
  `DLQ.<queue>` with its transactional send rolled back; `CLIENT_ACKNOWLEDGE` redelivery;
  `AUTO_ACKNOWLEDGE` acknowledging failures; `jms.redeliveryPolicy.*` options (maximum
  redeliveries, delays, `JMSXDeliveryCount`);
* the raw broker semantics the emulation relies on: an aborted transactional `ACK` only
  restores the pending ack, `NACK` is a poison ack (DLQ for persistent messages), a disconnect
  redelivers with `redelivered:true` (ActiveMQ sends the header only when true);
* durable subscriptions (`durableSubscriptionName` + `clientId`, and `subscriptionDurable` +
  `subscriptionName` with a selector) keeping messages while the route is stopped;
* priority ordering of waiting messages and expiry of messages whose TTL passed;
* virtual topics (`VirtualTopic.x` → `Consumer.<sub>.VirtualTopic.x` with concurrent
  consumers), and `subscriptionShared=true` refused (ActiveMQ 5 has no shared subscriptions);
* STOMP+SSL by host name and IP SAN, untrusted CA refused.

### AMQP 1.0 transport

Run on 2026-11-01 against the AMQP connector with `activemq-amqp` 5.17.6 (the jar's SHA-1
verified against Maven Central) and proton-j 0.34.0 from Ubuntu: all 10 tests of
`live_activemq_amqp.rs` pass. They were first run here: 5 of the original 6 passed, the
topic fan-out test failed (bug 16; the durable subscription test only passed because the
"subscription" was a queue). What the suite verifies with `amqp` endpoints:

* queues with JMS headers (`priority`, `JMSCorrelationID`, properties), topic fan-out to two
  non-durable subscribers on separate connections, SASL PLAIN with a wrong password →
  `AuthenticationFailureException`;
* JMS selectors (`apache.org:selector-filter:string`) evaluated by ActiveMQ;
* request/reply over dynamic temporary reply queues (`temp-queue://ID:...` addresses), remote
  exceptions, timeouts;
* AMQP 1.0 transactions (`transacted=true`): a failed exchange rolls back and ActiveMQ
  redelivers with `JMSRedelivered=true`, `JMSXDeliveryCount=2`; `CLIENT_ACKNOWLEDGE`
  (`modified(delivery-failed)`) redelivered with counts 1, 2, 3;
* a durable subscription (`clientId` + `durableSubscriptionName`) keeping a message published
  while its route is stopped;
* the JMS mapping through ActiveMQ's JMS transformer (AMQP → ActiveMQ JMS message → AMQP):
  UTF-8 text, bytes, map and object (`jmsMessageType=Object`) bodies, `JMSType`,
  `JMSCorrelationID`, `JMSXGroupID`, priority, `timeToLive` (`JMSExpiration` - `JMSTimestamp`),
  non-persistent `JMSDeliveryMode=1`, ActiveMQ `ID:` message ids, int / boolean / double /
  dotted / hyphenated properties, the `x-opt-jms-msg-type` / `x-opt-jms-dest` /
  `x-opt-jms-reply-to` annotations (`includeAmqpAnnotations=true`), a `JMSReplyTo` topic
  answered by the consumer and re-used as `CamelJmsDestinationName`;
* a 3 MB bytes and a 600 KB text message (ActiveMQ's max-frame-size is 128 KiB; the consumer
  asks for 16 KiB frames), split into many transfer frames in both directions;
* `subscriptionShared=true` refused (bug 17); AMQPS with the interop CA.

ActiveMQ notes:

* ActiveMQ 5 does not redeliver after an aborted transaction or a NACK; Cameleer emulates its
  JMS client's redelivery policy on the consumer (bugs 12 and 13). Its defaults are ActiveMQ's
  (6 redeliveries, 1 s delays); set `jms.redeliveryPolicy.*` options on the broker url
  (`camel.component.jms.brokerUrl=tcp://host:61613?jms.redeliveryPolicy.redeliveryDelay=100`).
  Exponential back-off options are not emulated.
* ActiveMQ dead-letters only persistent messages (`processNonPersistent=false`); a poisoned
  non-persistent message is discarded.
* ActiveMQ 5's STOMP adapter has no JMS 2.0 shared subscriptions; use virtual topics. Its
  AMQP transport has none either (the `shared` capability is ignored).
* ActiveMQ's AMQP transport types nodes by address prefix only (`queue://`, `topic://`,
  announced as `queue-prefix` / `topic-prefix` in its open frame); the `topic` / `queue`
  terminus capabilities are echoed but ignored, and a bare address is a queue. Received
  messages carry prefixed `to` / `reply-to` addresses.
* ActiveMQ bridges protocols: the MQTT topic `a/b/c` is the STOMP / JMS topic `a.b.c` (verified
  both ways).

## Official clients

The live suite checks Cameleer *clients* against real servers. Many areas, though, are only
served by Cameleer's own emulators and embedded servers (Kafka broker, MongoDB / Cassandra /
Elasticsearch / Redis servers, the AWS / Azure / GCP mocks, the Azure flavour of the AMQP 1.0
broker), or are protocol stacks written from scratch (TLS, HTTP/2, gRPC). The **official-client
suite** drives those with independently written, officially published clients, so emulator and
client cannot simply agree with each other.

```sh
sudo scripts/official-clients.sh install      # apt-get the clients (Ubuntu 24.04 python3-*, kcat)
scripts/official-clients.sh versions
scripts/official-clients.sh test              # CAMEL_OFFICIAL_CLIENTS=1 cargo test --workspace --test 'official_*'
```

The suites are `crates/<crate>/tests/official_*.rs`; they do nothing unless
`CAMEL_OFFICIAL_CLIENTS=1` is set. The client programs (Python scripts, a bash driver for the
Google Cloud CLIs, a Go program) are in `scripts/official-clients/`; helpers are in
`cameleer_tls::testing::official`. Each test starts the Cameleer side on an ephemeral port, runs
the client as a subprocess and checks the client's `key: value` output. The Google Cloud SDK and
a Go toolchain come from outside apt (see the script header). Every bug fixed along the way also
has a hermetic regression test: `official_regressions.rs` / `official_*_regressions.rs`,
`kafka_wire_compat.rs`, and unit tests.

### Results

Run on 2026-11-01. All 34 official-client tests pass
(`CAMEL_OFFICIAL_CLIENTS=1 cargo test --workspace --test 'official_*'`), together with the 24 hermetic regression tests in the same targets.

| Area | Client (version) | What was exercised | Result |
|---|---|---|---|
| Kafka broker (`testing::KafkaBroker`), `kafka` component | confluent-kafka 1.7.0 on librdkafka 2.3.0, kcat 1.7.1 | produce/consume with headers and keys; murmur2 partitioning matching the Java client; gzip, snappy and lz4 batches from librdkafka decoded by Cameleer, and Cameleer's compressed batches decoded by librdkafka; zstd falling back cleanly; a consumer group mixing librdkafka and Cameleer members (join/sync/heartbeat, rebalance, committed offsets); the admin client (create/describe/delete topics); kcat round trip; SASL PLAIN and SCRAM-SHA-256/512, TLS and mutual TLS | pass |
| MongoDB server | pymongo 3.11.0 | CRUD, bulk writes, aggregation pipelines, indexes (create/list/drop, unique violations → `DuplicateKeyError`), change streams, cursors and `getMore`; SCRAM-SHA-256, TLS and X.509 authentication; documents shared with the `mongodb` component | pass |
| Cassandra server | DataStax cassandra-driver 3.29.0 (protocol v4) | cluster metadata (`system.local`, `system.peers`, `system_schema` keyspaces/tables/columns), prepared and batch statements, paging, typed values, PlainText auth, TLS, data shared with the `cql` component | pass |
| Elasticsearch server | elasticsearch-py 7.17.6 | product check, index/get/update/delete, bulk, search with queries and aggregations (terms, avg/sum/min/max, value_count, cardinality, stats), paging, `_delete_by_query`, error mapping | pass |
| Redis server | redis-py 4.3.4 | strings/hashes/lists/sets/zsets, TTLs, BLPOP, `WRONGTYPE`, SCAN/HSCAN/SSCAN/ZSCAN, pipelines, MULTI/EXEC with WATCH (aborted transactions), pub/sub, username/password AUTH (failures refused), values shared with the `spring-redis` component | pass |
| AWS mock (`AwsMock`), AWS components | boto3 / botocore 1.34.46 | SigV4 (botocore's own signatures compared byte for byte, unknown keys and bad signatures rejected with the services' error codes); S3 incl. multipart (ListParts, ListMultipartUploads), presigned URLs, HTTPS; SQS in botocore's Query protocol and the JSON protocol (message attributes with MD5, FIFO deduplication, batches, error codes); SNS incl. `MessageStructure=json` to SQS; DynamoDB (tables, items, queries, batch write, transactions); Kinesis; Lambda; KMS (encrypt/decrypt with encryption context, aliases, data keys, random); Secrets Manager; STS; data exchanged with Cameleer's AWS components | pass |
| Azure mocks (`AzuriteMock`, `AzureMock`), Azure components | azure-core 1.28.0, azure-storage-blob 12.17.0, -queue 12.7.0b1, -file-datalake 12.12.0, -file-share 12.13.0, azure-identity 1.14.0b2, azure-keyvault-secrets 4.8.0b2, -keys 4.9.0b2, azure-cosmos 3.1.1 | Shared Key and account / service / container SAS; blobs (ranges, content type, case-preserving metadata, delimiter walk, block lists, chunked uploads, append blobs, leases, snapshots, Blob Batch); queues (peek, receive, update, metadata, SAS); Data Lake (paths, renames); file shares; client-credential tokens from the mock's Entra endpoint, Key Vault secrets (versions, properties, soft delete) and keys over HTTPS; Cosmos; data exchanged with the storage components | pass |
| AMQP 1.0 broker in Azure mode, Service Bus / Event Hubs components | azure-servicebus 7.11.1, azure-eventhub 5.11.3 (pyamqp) | CBS SAS authentication; Service Bus peek-lock and receive-and-delete, abandon with delivery counts, peek, scheduled messages, dead-lettering, batches, binary bodies, application properties, sessions with session state; Event Hubs properties and partition management requests, batched sends, partition receive; messages exchanged with Cameleer's components | pass |
| GCP mock (`GcpMock`) | Google Cloud SDK 570.0.0 (gcloud, gsutil), bq 2.1.32 | service-account JWT login against the mock's token endpoint over HTTPS; `gcloud storage` (buckets, multipart and resumable uploads, cat, ls/-r, describe, custom metadata, cp/mv/rm, missing objects); gsutil (JSON API over HTTPS, md5/crc32c verification); `gcloud pubsub` (topics, subscriptions, publish with attributes, pull/ack, describe, delete); bq (datasets, tables, insert, show, standard-SQL query jobs, head, rm) | pass |
| GCP mock Pub/Sub gRPC | grpcio 1.51.1, protobuf 4.21.12 | StreamingPull with a bearer token from the service-account JWT grant (unauthenticated streams refused), attributes, acks over the stream | pass |
| gRPC (`grpc` consumer and producer) | grpcio 1.51.1 | grpcio calling a Cameleer consumer route: unary with metadata, server-, client- and bidirectional streaming, status codes (NOT_FOUND with details), deadlines, 300 KB messages; plaintext h2c, gzip, TLS and mutual TLS (untrusted / missing client certificates refused). The Cameleer producer calling a grpcio server: all four call kinds, headers as metadata, PERMISSION_DENIED, 200 KB messages, plaintext, gzip and TLS (untrusted server certificate refused) | pass |
| TLS (`cameleer-tls`) | Go 1.24.7 crypto/tls | both directions: TLS 1.3 with each of AES-128-GCM, AES-256-GCM, ChaCha20-Poly1305; TLS 1.2 with all six ECDHE-ECDSA / ECDHE-RSA AEAD suites; x25519, P-256 and P-384 in both versions, Go's default hybrid X25519MLKEM768 key share (camel picks x25519); RSA certificates (PSS in 1.3); ALPN; session resumption (TLS 1.3 PSK tickets, TLS 1.2 tickets) seen by both sides; mutual TLS incl. resumed sessions keeping the client identity, missing and untrusted client certificates refused; untrusted server and host name mismatch refused | pass |
| HTTP/2 and HTTPS (cameleer-grpc `h2`, `cameleer-http`) | Go 1.24.7 net/http (bundled x/net/http2) | Go's HTTP/2 client against camel's H2 server over TLS (ALPN h2, 1 MiB upload across flow-control windows, 16 concurrent streams on one connection, 404; an HTTP/1.1-only client gets 505), Go's client against a `jetty:https` route (ALPN falls back to HTTP/1.1; echo, 404); camel's HTTP/2 client (3 MB echo, streamed responses, 12 concurrent streams) and the `https` producer with `httpVersion=HTTP/2` (headers sent) against Go's HTTP/2 server, plus HTTP/1.1 | pass |

Not verified: CouchDB (no packaged official client); Kafka zstd (librdkafka uses it only with
Produce v7+, which the embedded broker does not advertise, so librdkafka falls back to
uncompressed batches, verified); the Google Cloud Python client libraries (not packaged; the
CLIs and grpcio stand in); the Azure Cosmos SDK's newer versions (only 3.1.1 is packaged).

### Bugs found and fixed

| # | Area | Bug (found with) | Fix | Regression test |
|---|---|---|---|---|
| 1 | Kafka broker | librdkafka never joined consumer groups or compressed: its ApiVersions feature probes need the v0 ranges of FindCoordinator/JoinGroup/SyncGroup/Heartbeat/LeaveGroup and Produce v0-v2 / Fetch v0-v2 (librdkafka 2.3.0) | v0 ranges advertised, legacy request/response shims and magic 0/1 message sets (`crates/cameleer-kafka-mqtt/src/testing/kafka_broker.rs`, `kafka/protocol.rs`) | `kafka_wire_compat.rs` `api_versions_cover_librdkafka_feature_probes`, `group_coordination_v0`, `legacy_message_sets_produce_and_fetch` |
| 2 | Kafka broker | produced batches were re-encoded, losing the producer's compression and CRC | batches are stored and served verbatim (`RawBatch`) | `producer_compression_and_verbatim_batches` |
| 3 | `kafka` component | snappy and lz4 batches could not be decoded or produced (no codecs) | LZ4 frame format with xxHash32 and xerial snappy-java framing (`crates/cameleer-core/src/dataformat/codecs.rs`), `compressionCodec` option (zstd refused) | `compressed_record_batches_round_trip`, codec unit tests |
| 4 | Kafka broker | SASL after SaslHandshake v0 sends bare tokens; the broker expected SaslAuthenticate frames | bare length-prefixed tokens supported | `sasl_handshake_v0_with_bare_tokens` |
| 5 | SCRAM server | librdkafka's client-final nonce is client nonce + server nonce; Kafka accepts a suffix match, the broker refused it | `ScramServer::accept_nonce_suffix` (`crates/cameleer-tls/src/sasl.rs`) | `sasl::tests::kafka_style_nonce_suffix` |
| 6 | MongoDB server | `createIndexes` / `listIndexes` / `dropIndexes` missing, unique indexes not enforced (pymongo) | index commands and unique enforcement (`crates/cameleer-datastores/src/mongodb/server.rs`) | `official_regressions.rs` `mongo_indexes_are_listed_dropped_and_unique` |
| 7 | Cassandra server | the driver failed on `Keyspace system_schema does not exist`, then on missing `schema_version` / `host_id` columns | `system_schema` tables kept in sync with the schema, full `system.local` / `system.peers(_v2)` (`cassandra/engine.rs`, `cassandra/server.rs`) | `cassandra_system_schema_and_peer_metadata` |
| 8 | Elasticsearch server | elasticsearch-py raised `UnsupportedProductError` (no `X-Elastic-Product` header); aggregations and `_delete_by_query` missing; scroll responses without `_shards` | header (not in OpenSearch mode), aggregations, delete-by-query (`elasticsearch/server.rs`) | `elasticsearch_product_header_aggregations_and_delete_by_query` |
| 9 | Redis server | SCAN family and WATCH missing (redis-py) | cursors over keys/hashes/sets/zsets, WATCH with key versions aborting EXEC (`redis/server.rs`) | `redis_scan_family_and_watch` |
| 10 | AWS mock | botocore speaks SQS's Query protocol: JSON error bodies broke it; unknown keys answered with the wrong code | protocol-aware errors (`x-amzn-query-error`, `InvalidClientTokenId` / `UnrecognizedClientException`) (`crates/cameleer-cloud/src/testing/aws.rs`) | `official_regressions.rs` `sqs_attribute_md5_fifo_dedup_and_error_codes`, `tests/aws.rs` |
| 11 | AWS mock | SQS `MD5OfMessageAttributes`, FIFO deduplication, `SequenceNumber` missing; S3 ListParts / ListMultipartUploads missing; SNS `MessageStructure=json` delivered the whole JSON; DynamoDB ListTables / BatchWrite / TransactWrite gaps; KMS ignored the encryption context and lacked aliases and data keys | implemented (`aws.rs`, `aws_gaps.rs`, `aws_more.rs`; KMS blobs are AES-GCM with the context as AAD) | `s3_list_parts_and_multipart_uploads`, `sns_message_structure_json_delivers_the_sqs_entry`, `dynamodb_list_tables_batch_write_and_transactions`, `kms_context_aliases_and_data_keys` |
| 12 | `aws-secrets-manager` | `updateSecret` called PutSecretValue; Camel (and boto3 users) expect UpdateSecret | `UpdateSecret` in component and mock (`crates/cameleer-cloud/src/aws/secretsmanager.rs`, `aws_ext.rs`) | `secrets_manager_update_secret` |
| 13 | HTTP server helper | `Response::with_header("Content-Type")` added a second Content-Type | replaces the existing one (`crates/cameleer-cloud/src/http.rs`) | covered by the above |
| 14 | Azure mocks | blob ranges (206/416), `x-ms-blob-content-type`, metadata case, delimiter listings, snapshots, Blob Batch, container and queue SAS, queue metadata, DFS endpoint serving the Blob API, file ranges, Key Vault properties / versions / soft delete / deleted keys, OpenID discovery, HTTPS Key Vault ids | implemented (`crates/cameleer-cloud/src/testing/azure*.rs`); the `azure-storage-blob` component now sends `x-ms-blob-content-type` (`azure/blob.rs`) | `official_azure_regressions.rs` (5 tests) |
| 15 | AMQP 1.0 codec | performatives were sent with trailing nulls trimmed; pyamqp indexes fields positionally (`IndexError`), and a null `handle_max` broke it | all fields kept, limits explicit (`crates/cameleer-amqp10/src/codec.rs`, `types.rs`, `message.rs`) | `amqp10 official_regressions.rs` `performatives_keep_all_fields_and_explicit_limits` |
| 16 | AMQP 1.0 broker (Azure mode) | SAS tokens sent with CBS type `jwt`, absolute-URL link addresses, rcv-settle-mode second from producers, batch message format `0x80013700`, plain-value session filters, `locked-until-utc` in .NET ticks, management requests without `reply-to` | all accepted / produced as Service Bus does (`testing/broker.rs`, `azure.rs`, `servicebus.rs`; `Sender::send_azure_batch`) | `cbs_jwt_typed_sas_tokens_absolute_addresses_and_settlement`, `plain_session_filters_and_tick_lock_expiry`, `management_replies_without_reply_to` |
| 17 | GCP mock | gsutil only speaks HTTPS; gcloud signs JWTs for Google's token audience; multipart uploads with single-quoted boundaries and LF line endings; objects lacked `crc32c` / `metadata` / `mediaLink` (gcloud crashed), no metadata PATCH/PUT, delimiter listings, ranged downloads, `moveTo` / `rewriteTo`, `storageLayout`; Pub/Sub list endpoints; BigQuery `datasets.get`, `tabledata.list`, query jobs, and error bodies without the `errors` list bq reads | `GcpMock::start_tls`, all of the above (`crates/cameleer-cloud/src/testing/gcp.rs`, `gcp_ext.rs`), checksum verification of uploads | `official_gcp_regressions.rs` (4 tests) |
| 18 | Google components | exceptions dropped BigQuery's `errors[].reason` (`invalidQuery`, `notFound`) once the status is canonical | the reason is appended to the message (`crates/cameleer-cloud/src/gcp/mod.rs` `google_error`) | `tests/gcp_more.rs` `bigquery_sql_queries_dml_parameters_and_paging` |
| 19 | `cameleer-tls` client | TLS 1.3 sessions never resumed against Go's crypto/tls: full-handshake ClientHellos lacked `psk_key_exchange_modes`, and Go (like BoringSSL) issues NewSessionTickets only to clients listing psk_dhe_ke | listed whenever resumption is enabled (`crates/cameleer-tls/src/tls/client.rs` `client_hello`) | `cameleer-tls official_regressions.rs` `first_client_hello_lists_psk_modes_when_resumption_is_enabled` |

Notes:

* TLS 1.2 with ECDSA certificates: RFC 8422 lets the client's supported groups constrain the
  certificate's curve too, so a Go client restricted to x25519 is refused by a P-256 certificate
  (Go and OpenSSL servers behave the same); the suite checks this explicitly.
* pyamqp (azure-servicebus 7.11) mis-encodes two-character session ids; the script uses longer
  ones.

## Third-party simulators

Real AWS / Azure / Google Cloud accounts, Kafka, MongoDB, Cassandra and Elasticsearch are not
reachable from the test environment. The live suite above covers real servers from the Ubuntu
archive and the official-client suite drives Cameleer's own emulators with official clients;
the **simulator suite** closes the remaining gap from the other side: Cameleer's *components*
run against independent, widely used simulators and wire-compatible servers, installed and run
locally.

```sh
scripts/simulators.sh install     # pip (moto), npm (Azurite), Go builds (fake-gcs-server, pstest, FerretDB, kfake)
scripts/live-interop.sh start     # FerretDB needs the live PostgreSQL 16; TLS listeners use its PKI
scripts/simulators.sh start       # idempotent; `status`, `versions`, `stop`
scripts/simulators.sh test        # CAMEL_SIMULATORS=1 cargo test --workspace --test 'sim_*'
```

The suites are `crates/<crate>/tests/sim_*.rs` and do nothing unless `CAMEL_SIMULATORS=1` is
set (helpers: `cameleer_tls::testing::sim`). Every test uses unique bucket / queue / topic /
database names, because the simulators keep their state between runs. Tools live under
`$CAMEL_SIM_HOME` (default `/opt/camel-sim`), state and logs in `$CAMEL_SIM_HOME/state`; the
port table is at the top of the script. TLS listeners serve the live-interop `localhost`
certificate.

Installing offline. pypi.org, registry.npmjs.org and proxy.golang.org are reachable, but
sum.golang.org is not, and proxy.golang.org redirects large module zips to
storage.googleapis.com, which is blocked. The script therefore builds each Go program inside its
own module (`-mod=readonly`, so every dependency is checked against the upstream `go.sum`),
fetches GitHub-hosted modules straight from git (`GONOPROXY=github.com`; hashes still checked),
and packs `google.golang.org/api` from its git tag with `scripts/simulators/modzip` into a file
`GOPROXY`, which the go command accepts only if the zip's hash equals the one in `go.sum`. Only
the top-level modules (fake-gcs-server, FerretDB, kfake, the pubsub module and
`golang.org/x/mod`) cannot be checked against the checksum database: they come from
proxy.golang.org / GitHub over TLS at pinned versions / commits.

### Results

Run on 2026-11-01. All 31 simulator tests pass
(`CAMEL_SIMULATORS=1 cargo test --workspace --test 'sim_*'`), together with the 4 hermetic
regression tests in `sim_regressions.rs`; the hermetic workspace suite (`cargo test --workspace`)
stays green, and `official_kafka.rs` (librdkafka, now joining groups with JoinGroup v4) passes.

| Simulator (version) | Components | What was verified | Result |
|---|---|---|---|
| moto 5.2.5 (server mode, pip `moto[server]`) | `aws2-s3`, `aws2-sqs`, `aws2-sns`, `aws2-ddb`, `aws2-ddbstream`, `aws2-kinesis`, `aws2-kinesis-firehose`, `aws2-eventbridge`, `aws-secrets-manager` (+ `{{aws:...}}`), `aws2-kms`, `aws2-sts`, `aws2-iam`, `aws2-ec2`, `aws2-cw`, `aws2-ses`, `aws2-step-functions`, `aws2-lambda`, `aws2-athena` | S3: buckets, objects with UTF-8 / `+` / space keys, metadata, ranges, prefix listings, copy, delete, `NoSuchKey` / `BucketNotEmpty` / `NoSuchBucket`, presigned download links, multipart uploads with 5 MiB parts (3 parts, `-3` ETag) and moto's `EntityTooSmall` (upload aborted), streamed multipart upload from a file and streamed download into a file, streaming upload mode, consumer with `moveAfterRead`; SQS: send with message attributes and MD5, batches, prefix listing, consumer with attributes, redelivery after the visibility timeout, FIFO with content-based deduplication, purge / delete, errors; SNS: auto-created topic subscribed to SQS (`subscribeSNStoSQS`), subject and attributes in the SNS envelope, `MessageStructure=json`; DynamoDB: table created on first use, typed items (lists, sets), Update / Condition / Filter / Projection expressions with attribute names and values (moto enforces DynamoDB's reserved words), `ConditionalCheckFailedException`, Query, Scan (also legacy `ScanFilter`), BatchGetItems, UpdateTable enabling a stream, the `aws2-ddbstream` consumer reading INSERT / MODIFY / REMOVE with old and new images, DeleteTable; Kinesis: two-shard stream, PutRecord / PutRecords, a consumer per shard; Firehose: delivery stream with an extended S3 destination, single and batch records landing in S3; EventBridge: rule with an event pattern and an SQS target, only matching events delivered, describe / list / disable / remove / delete; Secrets Manager: create / get by name and ARN / update / describe / list / binary secrets / delete / restore, `{{aws:secret/field}}` placeholders; KMS: create / list / describe / disable / enable keys, encrypt and decrypt, schedule deletion; STS: AssumeRole, GetSessionToken, GetFederationToken; IAM: users, groups, access keys, `EntityAlreadyExists`, `NoSuchEntity`; EC2: run / describe / stop / start / tag / terminate instances, `InvalidInstanceID.NotFound`; CloudWatch: PutMetricData (single, dimensions, timestamps, lists) read back with ListMetrics; SES: moto's verified-sender rule (`MessageRejected` until verified), plain, HTML with Cc / Reply-To, raw messages; Step Functions: state machines, executions, `ExecutionAlreadyExists`; Lambda management API (create from a zip, versions, aliases, tags, get / list / delete); Athena: start / get / list query executions. A second moto server enforces IAM authentication and SigV4 verification: header-signed S3 (keys with spaces and `+`), SQS, DynamoDB and IAM requests from Cameleer are accepted; a wrong secret gets `SignatureDoesNotMatch`, an unknown key `InvalidAccessKeyId` / `UnrecognizedClientException`. HTTPS server verified by host name and IP SAN (untrusted certificate refused unless `trustAllCertificates=true`) | pass |
| Azurite 3.37.0 (npm `azurite`) | `azure-storage-blob`, `azure-storage-queue` | containers, block blobs with content type and metadata, names with spaces / `+` / UTF-8 content, paged listings, `BlobNotFound` / `ContainerAlreadyExists` / `ContainerNotFound`, wrong account key refused (403); block lists (stage, uncommitted / committed lists, recommit, `InvalidBlockList`), append blobs, page blobs (ranges, resize, clear), leases (acquire, `LeaseIdMissing` 412, renew, release, `leaseBlob=true`, break), server-side copy, download links (service SAS) checked by Azurite incl. tampering (403); consumer with prefix and `deleteAfterRead`; account SAS made by Cameleer (full, read-only → `AuthorizationPermissionMismatch`, forged, expired); queues: send (XML-special and UTF-8 text), peek, receive with visibility timeout, update (new pop receipt, `PopReceiptMismatch` for the old one), delete, clear, consumer deleting processed messages and redelivering a failing one with a growing dequeue count, SAS, `QueueNotFound`; Blob and Queue over HTTPS | pass |
| fake-gcs-server 1.53.1 | `google-storage` | `authenticate=false` against the emulator; bucket auto-creation, objects with UTF-8 / `+` names and content type, get, list, copy to a created bucket, list / delete buckets, a resumable upload session in 256 KiB chunks, delete, 404; consumer with `moveAfterRead`; HTTPS | pass |
| pstest (cloud.google.com/go/pubsub 1.50.1) | `google-pubsub` streaming-pull consumer | gRPC StreamingPull without authentication: message id, ack id, publish time and attributes, every message acknowledged once (as pstest counts acks), a failing message nacked and redelivered (3 deliveries). pstest has no REST API, so topics, subscriptions and messages are created through a small HTTP control API around pstest's Go methods (`scripts/simulators/pstest`) | pass |
| FerretDB 1.24.2 on PostgreSQL 16.15 | `mongodb`, `mongodb-gridfs` | insert (single / many), `E11000` duplicate key, findById / findOneByQuery / findAll with criteria, sort, limit, skip, projection, `$or` / `$regex`, getMore batches, count, distinct, multi / upsert / `$unset` updates, invalid update operators, save, aggregation (`$match`, `$unwind`, `$group`, `$sort`, `$count`), remove, db / collection stats, commands (`NotImplemented` / unknown command errors), Extended JSON dates, longs and binaries, bulkWrite (ordered / unordered, upserts), dynamicity, `createCollection=false`; SCRAM-SHA-256 and SCRAM-SHA-1 (FerretDB's new authentication), wrong password → `MongoSecurityException`; TLS verified against the interop CA (untrusted CA refused); tailable consumer on a capped collection; GridFS create / findOne / count / listAll / remove of a 600 KB file and the GridFS consumer | pass |
| kfake (franz-go, commit of v1.20.6) | `kafka` | a three-broker cluster: topic creation, murmur2 partitioning, keys, string / long headers, offsets per partition, commits on stop as reported by kfake's OffsetFetch; auto-created topics, explicit / header partitions, `kafka.OVERRIDE_TOPIC`, acks 0 / 1 / all, array bodies, round robin; gzip, snappy and lz4 batches decoded by franz-go; a consumer group of two routes splitting four partitions and rebalancing when one leaves; committed offsets surviving a restart; manual commits; SASL PLAIN, SCRAM-SHA-256 and SCRAM-SHA-512, over plaintext and TLS; TLS by `sslContextParameters` and by `sslTruststoreLocation`; wrong passwords and an untrusted certificate refused | pass |

### Bugs found and fixed

| # | Component | Bug (found against) | Fix | Regression test |
|---|---|---|---|---|
| 1 | `kafka` client | `create_topics` sent CreateTopics to any broker; kfake (like ZooKeeper-mode Kafka) answers `NOT_CONTROLLER` (41, shown as `UNKNOWN_ERROR_CODE`) from the others | sent to the controller named by Metadata (`crates/cameleer-kafka-mqtt/src/kafka/client.rs`); error names for 29, 30, 38, 41, 79 (`protocol.rs`) | `cameleer-kafka-mqtt` `sim_regressions.rs` `create_topics_is_sent_to_the_controller` (fake two-node cluster) |
| 2 | `kafka` consumer groups | consumers joined with JoinGroup v2 and never received records from kfake, which (for v0-v3 joins) answers a first join with an empty member id; modern clients join with v4 and KIP-394's `MEMBER_ID_REQUIRED` | JoinGroup v4: on `MEMBER_ID_REQUIRED` the member rejoins with the assigned id (`kafka/consumer.rs`); the embedded broker answers v4 joins the same way, like Kafka 2.2+ (`testing/kafka_broker.rs`) | `join_group_v4_member_id_required`; `official_kafka.rs` (librdkafka now joins with v4) still passes |
| 3 | `azure-storage-blob` | `listBlobs` with `maxResultsPerPage` returned only the first page (Azurite) | the option is the page size and every page is read, as Camel collects the SDK's PagedIterable (`crates/cameleer-cloud/src/azure/blob.rs`) | `cameleer-cloud` `sim_regressions.rs` `list_blobs_reads_every_page` |
| 4 | `google-storage` (and other Google components) | with `authenticate=false` (emulators) there is no key, so bucket operations failed with "A project id ... is required" (fake-gcs-server) | the default project comes from `GOOGLE_CLOUD_PROJECT` / `GCLOUD_PROJECT`, as in the Google client libraries (`crates/cameleer-cloud/src/gcp/mod.rs` `project_id`) | `storage_bucket_operations_use_the_default_project_without_a_key` |

### Simulator limitations (asserted around, not Cameleer bugs)

* moto: presigned URLs are not checked (any signature is accepted) unless IAM authentication is
  on, and with IAM authentication on a presigned GET fails with a 500 (`KeyError:
  HTTP_AUTHORIZATION`), so presigned links are only checked for content; Lambda invocations need
  Docker; separate moto servers do not share state. moto enforces DynamoDB's reserved words
  (`total`, `status`, ...) where Cameleer's own emulator accepted them.
* Azurite: no Data Lake (DFS), Files, change feed or Entra ID tokens without a real tenant
  (`--oauth basic` validates issuers); its Table endpoint runs but no Cameleer component uses
  it.
* fake-gcs-server does not verify OAuth tokens or V4 signed URLs, so the authenticated paths stay
  covered by the official-client suite (gcloud / gsutil against `GcpMock`).
* pstest speaks gRPC only, so the REST producer and the synchronous-pull consumer are not
  verified against it.
* FerretDB 1.24: no change streams (`$changeStream` is `NotImplemented`), no `$max` group
  accumulator, and `$sum` of a field path after `$unwind` returns 0 (pymongo sees the same);
  the tests avoid these.
* kfake answers JoinGroup v0-v3 first joins with an empty member id (see bug 2).

### Could not run

| Simulator / server | Why |
|---|---|
| Apache Kafka (KRaft), Redpanda | archive.apache.org is reachable only through the WebFetch tool, which refuses downloads over 10 MB (the Kafka 4.3.2 tarball is far larger); dlcdn / downloads.apache.org and Redpanda's hosts are blocked. franz-go's kfake stands in. |
| Elasticsearch, OpenSearch | the official tarballs (also OpenSearch's minimal distribution) are hundreds of MB, far over the 10 MB limit, artifacts.opensearch.org / elastic.co are blocked, nothing is packaged in Ubuntu. ZincSearch (Go) serves its partial ES-compatible API under `/es/`, a path prefix `hostAddresses` cannot express. |
| Apache Cassandra, ScyllaDB | the Cassandra 5.0 tarball exceeds the 10 MB limit (and the Apache CDN is blocked); ScyllaDB is not available offline. |
| LocalStack | needs Docker (host mode was removed in LocalStack 2). |
| Azure Cosmos DB emulator, Service Bus emulator | Windows-only / Docker-only. |
| gcloud Pub/Sub, Firestore and Datastore emulators | `gcloud components install` needs dl.google.com (blocked), the Firebase emulator jars come from storage.googleapis.com (blocked, > 10 MB). pstest replaces the Pub/Sub emulator for the gRPC consumer; Firestore has no offline alternative. |

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/ROADMAP.html

# Roadmap: what you can build today, and what comes next

Cameleer ships an integration engine: routes, about 230 connectors, the Enterprise Integration
Patterns and the languages. Some things agent and serverless teams want don't exist as packaged
components yet. This page covers two things:

1. **[Build it on the engine today](#1-build-it-on-the-engine-today):** how to assemble each missing
   piece from what already ships. These are patterns, not shipped features; the sketches show the
   route shape, and you fill in names, URIs and credentials.
2. **[Enhancement opportunities](#2-enhancement-opportunities):** what we intend to package or
   improve, with the evidence behind each item.

Status labels: ✅ available · 🧩 build it from existing components (pattern below) · 🚧 not yet.

---

## 1. Build it on the engine today

### 1.1 Agent tool server (MCP-style) 🧩

**Goal:** an agent calls named tools over HTTP, and each tool is a route with retries, timeouts
and idempotency.

**How:** one `platform-http` route receives tool calls and dispatches them by name to a `direct:`
route per tool with `toD`. Each tool route is ordinary Camel: error handling, idempotent consumer,
circuit breaker. A second endpoint returns the tool list (a static JSON body, or one built from route
descriptions). Full MCP protocol support (JSON-RPC sessions, `tools/list` schemas) is the packaged
version on the roadmap ([2.1](#21-agents-and-ai)).

```yaml
# sketch: a tool endpoint dispatching to one route per tool
- route:
    id: agent-tools
    from:
      uri: platform-http:/tools/call
      steps:
        - setHeader:
            name: tool
            jsonpath: "$.name"
        - setBody:
            jsonpath: "$.arguments"
        - toD: "direct:tool-${header.tool}"
- route:
    id: tool-refund
    from:
      uri: direct:tool-refund
      steps:
        - idempotentConsumer:
            jsonpath: "$.orderId"
            steps:
              - to: "http://payments.internal/refunds?httpMethod=POST"
```

### 1.2 Tool-calling agent loop 🧩

**Goal:** let the model choose tools until it has an answer.

**How:**
- `azure-openai` returns the model's tool calls in headers.
- A `loop` (with `doWhile`) calls the model, uses `choice` to stop when there are no more tool calls,
  and runs the requested tools with `recipientList` or `toD` to their `direct:` routes.
- An aggregation strategy appends each tool result to the message list for the next turn.

Keep the turn count bounded with the loop's count limit, and the cost bounded with `throttle`. The
`openai` and `aws-bedrock` components don't pass tool definitions yet ([2.1](#21-agents-and-ai)).

### 1.3 Vector store ingestion and retrieval 🧩

**Goal:** store embeddings and query them for RAG.

**How:**
- Embed with `openai:embeddings`, `aws-bedrock` (`invokeEmbeddingsModel`) or `google-vertexai`
  (`generateEmbeddings`).
- Store them with what already ships:
  - **PostgreSQL with pgvector** through the `sql` component: plain SQL with a vector literal
    (`INSERT ... VALUES (:#id, :#embedding::vector)`, and for retrieval
    `ORDER BY embedding <-> :#query::vector LIMIT 5`). The vector operators run in PostgreSQL.
  - **OpenSearch or Elasticsearch** through the `elasticsearch` component: index documents with a
    vector field; k-NN queries go through the search operation.
  - **Qdrant, Pinecone, Weaviate or Milvus** through their REST APIs with the `http` component
    and the `json` data format.
- Bedrock knowledge bases are ✅ through `aws-bedrock-agent-runtime` (`retrieve`,
  `retrieveAndGenerate`).

Dedicated vector components are on the roadmap ([2.1](#21-agents-and-ai)).

### 1.4 AWS Lambda function ✅

**Goal:** run routes as a Lambda function rather than a container.

**How:** `cameleer` is its own Lambda custom runtime (`provided.al2023`). Package the routes with
`scripts/package-lambda.sh`: API Gateway and function URL events go to the `platform-http`
routes, other events to `direct:lambda` (or the endpoint in the function's Handler setting).
See [AWS Lambda](https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html#aws-lambda). Containers on Cloud Run, Fargate, Azure Container
Apps or Knative work as before.

### 1.5 Streaming model output to users 🧩

**Goal:** forward tokens to a browser or client as they arrive.

**How:**
- `aws-bedrock`, `azure-openai` and `google-vertexai` support streaming with
  `streamOutputMode=chunks` and a `streamingChunkProcessor` called per chunk.
- In that processor, send each chunk to a `websocket` endpoint, or write it to a seda queue that a
  server-sent-events endpoint drains.

### 1.6 Token and cost budgets 🧩

**Goal:** cap spend per tenant or per agent.

**How:**
- Read the usage headers the model components set (prompt and completion tokens).
- Add them to a counter in `spring-redis` or `sql`, keyed by tenant.
- Put a `filter` or `choice` before the model call that rejects or downgrades the model once the
  budget is spent.
- Use `throttle` for a hard requests-per-second cap.

### 1.7 Human in the loop 🧩

**Goal:** an agent's risky action waits for a person.

**How:**
- Route the proposed action to `slack`, `telegram` or `mail` with an approval link that hits a
  `platform-http` route.
- Park the pending action in a repository (`sql` or `spring-redis`) keyed by an id.
- On approval, continue the action route. A `claimCheck` or the aggregator with
  `completionTimeout` handles expiry.

---

## 2. Enhancement opportunities

### 2.1 Agents and AI

| Item | Why | Status |
|---|---|---|
| **MCP server component**: expose routes as MCP tools (JSON-RPC, `tools/list` with JSON schemas, `tools/call`) | the standard way agents discover and call tools; today it's the pattern in 1.1 | 🚧 |
| **Tool calls in `openai` and `aws-bedrock`**: pass tool definitions and return tool calls (as `azure-openai` already does) | removes the main gap for the agent loop in 1.2 | 🚧 |
| **An agent EIP / DSL step**: model call → tool dispatch → loop, with turn and token limits | packages 1.2 so it's one step in a route | 🚧 |
| **Vector store components**: pgvector, Qdrant, OpenSearch k-NN, Pinecone | first-class retrieval instead of SQL/REST in 1.3 | 🚧 |
| **Streaming in `openai`** | parity with the Bedrock, Azure and Vertex components | 🚧 |
| **Prompt templates and response caching** | cut cost and latency for repeated prompts; reuse the templating languages | 🚧 |
| **Anthropic API component** | direct access without Bedrock or Vertex | 🚧 (reachable today through `aws-bedrock` and `google-vertexai`) |

### 2.2 Serverless and edge

| Item | Why | Status |
|---|---|---|
| **AWS Lambda runtime adapter**: route as a Lambda handler, with events mapped to exchanges | packages 1.4; Lambda is the largest serverless platform | ✅ built into `cameleer run` ([AWS Lambda](https://pmsudhi.github.io/cameleer/docs/DEPLOYMENT.html#aws-lambda)) |
| **Published container images and deployment examples** (Cloud Run, Fargate, Azure Container Apps, Knative) | shows scale-to-zero end to end | 🚧 |
| **Static and ARM64 builds tested** (musl, aarch64 Linux) | edge gateways and Graviton or Ampere hosts; today the hermetic suite runs on Windows and Linux x86-64 | 🚧 |
| **Binary size budget and feature flags per crate** | smaller images for functions that need only a few connectors | ✅ a feature per component family, plus `templates`, `jq`, `xpath`, `http2` and `validate` ([build features](https://pmsudhi.github.io/cameleer/docs/guides/build-features.html)) |

### 2.3 Performance

Current results: [BENCHMARKS.md](https://pmsudhi.github.io/cameleer/docs/BENCHMARKS.html); analysis: [../benchmarks/analysis.md](https://github.com/pmsudhi/cameleer/blob/main/benchmarks/analysis.md).

| Item | Why | Status |
|---|---|---|
| **HTTP benchmark with the load generator on a second machine** | on one machine even a do-nothing server tops out near 400k req/s (3.6x Java), so 4x can't be shown there | 🚧 |
| **Event-driven HTTP server** (IOCP on Windows, epoll on Linux), opt-in, with the blocking server as fallback | scalability with many idle connections; on one machine it measured no faster than threads | 🚧 decision pending |
| **Shared JSON object keys** (`ObjectMap` API change) | JSON parsing is the largest cost in split/aggregate (3.18x today) | 🚧 |
| **A smaller `Exchange`** (box `exception`, group `from_*`) | fewer bytes copied per split part and per seda hand-off | 🚧 |
| **Kafka benchmark scenario** | needs a real broker on both sides | 🚧 |

### 2.4 Operations

| Item | Why | Status |
|---|---|---|
| **OpenTelemetry tracing export** | trace a request across agents, routes and services; today there are Prometheus metrics, tracing and message history | 🚧 |
| **Windows default time zone** (CLDR `windowsZones` map) | `TimeZone::local` is UTC on Windows unless `TZ` is set | 🚧 |
| **Graceful stop for the remaining direct `TcpStream::shutdown` calls** | so `stop()` never hangs on idle peers on Windows | 🚧 |

### 2.5 Verification and trust

| Item | Why | Status |
|---|---|---|
| **Real cloud accounts tier** (AWS, Azure, GCP) | today the cloud components are verified against emulators and official SDKs | 🚧 needs the owner's credentials |
| **Docker-based real servers** (Kafka, Elasticsearch, Cassandra, CouchDB, MongoDB, Artemis) | beyond the protocol emulators | 🚧 |
| **Independent security audit and fuzzing** of the from-scratch TLS, SSH, XML security and protocol parsers | the price of having no dependencies is owning that code | 🚧 |

The verification and operations items are also tracked in [STATUS.md](https://pmsudhi.github.io/cameleer/docs/STATUS.html).

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.

---

Source: https://pmsudhi.github.io/cameleer/docs/STATUS.html

# Status and pending work

_Last updated: 2026-11-06. Branch `main`. The verified head before this file
was added is `7de6166`._

## Name, packaging and release (2026-11-05)

- **Renamed rust-camel to Cameleer** after v0.1.0. Another active project, kennycallado/rust-camel,
  uses the same name and owns `camel-core` and most `camel-*` names on crates.io; "CAMEL" is also
  the CAMEL-AI agent framework. Crates are now `cameleer-*` (module paths `cameleer_*`), the repo
  is `pmsudhi/cameleer` (GitHub redirects the old URL), the site is
  https://pmsudhi.github.io/cameleer/. The CLI is `cameleer` (no `camel` binary: that is Apache Camel's CLI name).
- **Container image:** `pmsudhi/cameleer` on Docker Hub and `ghcr.io/pmsudhi/cameleer`
  (linux/amd64, linux/arm64), a glibc binary on distroless/cc (static musl measured 3-17% slower:
  direct -3%, seda InOut -10%, cbr -8%, splitagg -17%, same container, 2 rounds), built by `.github/workflows/container.yml` on `v*` tags (manual runs publish
  `edge`).
- **crates.io:** 19 `cameleer-*` crates, published with `scripts/publish-crates.sh` (dependency
  order, skips versions already there, waits out crates.io's new-crate rate limit of about one
  per 10 minutes). `cameleer-bench` is `publish = false`. The account needs a verified email.
- **Docker Hub:** `pmsudhi/cameleer`. CI pushes there when the `DOCKERHUB_TOKEN` secret is set;
  `.github/workflows/dockerhub-description.yml` syncs `docker/README.dockerhub.md` as the overview.
- **Deployment guide:** `docs/DEPLOYMENT.md` (Docker, Compose, Kubernetes, Cloud Run, AWS Lambda,
  smaller builds). Images run
  with `CAMEL_LOCAL_STATUS=false` (no status or log files) and work with a read-only root filesystem.

- **0.3.0: `cameleer validate` and `cameleer schema`** (`crates/cameleer-main/src/validate.rs`,
  `schema.rs`, DSL tables in `crates/cameleer-yaml/src/model.rs`, `CamelContext::check_endpoint`).
  Codes: yaml-syntax, xml-syntax, dsl-structure, endpoint, expression, unresolved-placeholder,
  dangling-endpoint, duplicate-route-id; text or JSON output; exit 0/1/2. A test validates every
  doc example and every file in `examples/`. Guides: `docs/guides/yaml-dsl.md`,
  `docs/guides/yaml-for-coding-agents.md`, `docs/guides/validate.md`, and `AGENTS.md`.
- **0.4.0: serverless and smaller builds** (2026-11-06). AWS Lambda custom runtime in
  `cameleer run`; every component family plus `templates`, `jq`, `xpath`, `http2` and `validate`
  as cargo features of `cameleer-main`; fewer idle threads (on-demand pool workers, one timer
  thread per timer name, XQuery/XSLT on the caller); the TLS alert fix. Release notes are in
  `CHANGELOG.md`. Feature docs: `docs/guides/build-features.md`, and every component, language
  and data format page names its feature in its header (`**Cargo feature:**`, checked by
  `crates/cameleer-main/tests/features.rs` `reference_pages_name_their_cargo_feature`).
- **Open findings from the documentation pass** are GitHub issues #2-#15 (Simple numeric string
  comparison, http producer overwriting the message on failure, S3 bucket header, webhook
  signatures, vault env vars, YAML `dataFormats`, `cameleer run <directory>`, ...).

## Where things stand

The implementation is complete against the feature list: `docs/FEATURES.md` has 228 rows, all
✅. Results of the last full run, all in one container session:

| check | result |
|---|---|
| `cargo build --workspace` | 0 warnings |
| hermetic `cargo test --workspace` | **2249 passed, 0 failed** |
| live real servers (`CAMEL_LIVE_INTEROP=1`) | **74 / 0** |
| official clients (`CAMEL_OFFICIAL_CLIENTS=1`) | **58 / 0** |
| third-party simulators (`CAMEL_SIMULATORS=1`) | **35 / 0** |

The hermetic suite has grown since that run: **2697 passed, 0 failed** on Windows 11 and on
Linux (WSL2) at the end of the FaaS round (2026-11-05), with zero warnings.

Independent verification found and fixed about 30 interoperability bugs. They're listed in
`docs/INTEROP.md`, and each has a hermetic regression test.

### What each area was verified against

- **Real servers:**
  - PostgreSQL 16, Redis 7, Mosquitto
  - RabbitMQ with AMQP 0-9-1, STOMP, AMQP 1.0 and MQTT
  - ActiveMQ 5.17.6 with STOMP, MQTT and AMQP 1.0
  - vsftpd (FTP and FTPS), Postfix + Dovecot (SMTP, IMAP, POP3), nginx, OpenSSL `s_client`
    and `s_server`, JDK JSSE
- **Official clients against Cameleer servers and emulators:**
  - librdkafka and kcat, pymongo, the DataStax Cassandra driver, elasticsearch-py, redis-py
  - boto3, the Azure SDK (storage and AMQP), gcloud, gsutil and bq
  - grpcio, Go `crypto/tls` and `net/http` (HTTP/2)
- **Third-party simulators:**
  - moto 5.2.5 (AWS), Azurite 3.37.0
  - fake-gcs-server 1.53.1, pstest (Pub/Sub over gRPC)
  - FerretDB 1.24.2 on PostgreSQL (MongoDB wire), kfake (Kafka wire)

## FaaS and efficiency round (2026-11-05, branch `performance-improvement`)

Research in `benchmarks/perf-research.md`, review with baselines in `benchmarks/perf-review.md`,
results in `docs/BENCHMARKS.md` (section "FaaS cold start and size") and
`benchmarks/analysis.md`. Linux, `dist` builds, against `main`:

- **Cold start:** HTTP route ready 3.27 → 1.17 ms (all components) and 0.69 ms (static musl,
  `core`); timer route 1.52 → 0.66 ms (musl `core`); a run-once job exits in 1.4–2.2 ms instead
  of 22 ms. Windows: HTTP route 12.1 → 10.3 ms, most of it process creation (a hello-world takes
  4.7 ms there).
- **Size:** 24.9 → 23.9 MB with every component; 11.7 MB with `--features cloud`, 7.3 MB with
  `core` (cargo features per component family in `cameleer-main`; `FEATURES` build arg in the
  Dockerfile). Then (2026-11-06, review finding 15) the template components, jq, the core XPath
  subset, HTTP/2 (and with it `cameleer-grpc`) and `validate`/`schema` became features too
  (`templates`, `jq`, `xpath`, `http2`, `validate`, all in `full`): `core` is now 5.82 MB glibc
  and 5.95 MB static musl (was 7.33 / 7.49 MB, −21%); `full` is unchanged in size and
  throughput. Details in `benchmarks/analysis.md`. Tests on Windows: `cargo test --workspace`
  2697 passed, 1 failed (the known TLS 1.3 alert-timing flake below, 5/5 on rerun);
  `cargo test -p cameleer-main --no-default-features` 29 passed (one test per gate).
- **Memory:** HTTP route RSS 15.2 → 10.4 MB (all components) and 4.2 MB (musl `core`); private
  memory 1.71 → 0.72 MB; idle HTTP threads 34 → 2.
- **Container image:** 20.5 → 20.4 MB compressed with every component, 14.5 MB with
  `FEATURES=cloud`, 12.5 MB with `FEATURES=core`; a running HTTP route uses 2.6 MiB and 3 threads
  (was 4.5 MiB and 34).
- **AWS Lambda:** built-in custom runtime (`cameleer_main::lambda`, `scripts/package-lambda.sh`),
  checked end to end in AWS's `provided:al2023` image with the Runtime Interface Emulator (init
  3.5–5.2 ms there). Not yet measured on the Lambda service itself (needs an AWS account).
- **Throughput:** unchanged within noise after fixing two regressions a bisect found (log macro
  level check, allocator bin size). Static musl is 3–22% slower, so the image stays glibc.
- **DT_RELR (2026-11-06):** the amd64 container build links with `-z pack-relative-relocs`:
  binary −400 KB (core −171 KB), peak RSS −0.48 MiB (core −0.13 MiB), start-up unchanged
  (measured inside the images, 4×40 interleaved runs), compressed image −33 KB. Needs glibc ≥ 2.36,
  so it is set only in the Dockerfile (Debian 12 runtime), never for the musl Lambda zip.
- **Tests:** hermetic suite 2697 passed, 0 failed on Linux (WSL2) and on Windows, zero warnings;
  `cargo test -p cameleer-main --no-default-features`: 24 passed. One earlier Windows run under
  heavy load failed `cameleer-tls` `mutual_tls_rejects_missing_and_untrusted_certificates` once
  (untouched by this branch; 15/15 on rerun, green in the final run). Fixed since: a library bug,
  see the TLS alert fix below.

Follow-ups: `-z pack-relative-relocs` for the arm64 image (Debian 12's
aarch64 ld ignores it; needs a newer binutils or lld in the builder); measuring
on the Lambda service across memory sizes and arm64.

**TLS alert lost to a TCP reset (2026-11-06, fixed).** The flake above was a library bug. A TLS 1.3
client sends application data right after its Finished; when the server rejected the client
certificate it sent the alert and dropped the socket, the late data drew a TCP reset, and on Windows
a reset discards the unread alert, so the client saw "connection reset" instead of
`certificate_required`. Servers now close gracefully after a fatal alert (FIN, then drain until the
peer closes, at most 2 s): `cameleer_tls::net::lingering_close` and `accept_tls`, used by
`NetStream::server`, the gRPC server and the cloud mock servers. Code that calls `TlsStream::accept`
on a raw `TcpStream` should use `accept_tls`. Regression test
`alert_survives_a_client_that_reads_late`; details in `docs/INTEROP.md` bug 18.

## Idle threads round (2026-11-06, branch `claude/mystifying-swartz-034e67`)

Perf-review finding 16, details and tables in `benchmarks/analysis.md` (section "Idle threads and
per-evaluation threads"); measured with the `idle_threads` example (`scripts/idle-threads.sh` on
Linux), old and new builds alternately on Windows 11 and WSL2 Ubuntu 24.04:

- **XQuery/XSLT** evaluate on the caller's thread and move to a new stack segment only when less
  than 512 KiB of stack is left (`cameleer_core::stack::maybe_grow`). Per evaluation: XQuery
  110 → 10 µs (Windows), 142 → 6.5 µs (Linux); XSLT 103 → 6.3 µs, 138 → 4.0 µs. Deep recursion
  still works from a 2 MiB thread; XQuery recursion 2000 deep is about 30% slower on Linux
  (unchanged on Windows), not traced further.
- **timer:** one thread per timer name (Camel's `java.util.Timer` per name): 20 routes on one
  name use 1 thread instead of 20; the thread exits after the last consumer.
- **Supervising route controller:** its thread exits when nothing is left to retry (1 → 0 threads
  after a recovery).
- **Local status file:** written only when the content changes (10 → 1 writes in 5 s idle);
  readers refresh uptimes from `updated`, and liveness comes from the operating system.
- **Tests:** hermetic suite 2712 passed, 0 failed, zero warnings, twice on Windows 11 and once on
  WSL2 Ubuntu 24.04 (Linux caught a unix-only compile error in the first build).

## Pending / todo

Everything below is extra verification of an implementation that's already done. None of it
is a missing feature. Each item was blocked in the cloud container by network policy, missing
Docker, or the lack of real accounts.

1. **Real cloud accounts.** Run the AWS (S3, SQS, SNS, DynamoDB, Lambda), Azure (Blob, Queue,
   Service Bus, Event Hubs, Cosmos) and GCP (Storage, Pub/Sub, BigQuery) components against
   real services.
   - Credentials must come from the owner. Never sign up automatically.
   - Add a new tier gated by `CAMEL_REAL_CLOUD=1` (`crates/cameleer-cloud/tests/real_*.rs`).
   - Use uniquely named, short-lived resources and delete them in teardown.
2. **Docker-based real servers**, which need Docker plus the ability to pull images:
   - Apache Kafka (KRaft) or Redpanda
   - Elasticsearch and OpenSearch
   - Apache Cassandra or ScyllaDB
   - CouchDB, real MongoDB (including change streams, which FerretDB lacks), ActiveMQ Artemis

   Extend `scripts/live-interop.sh` (or add `scripts/docker-interop.sh`) and add `live_*`
   tests.
3. **Emulators that need Docker or Windows:** LocalStack, the Azure Cosmos DB emulator, the
   Azure Service Bus emulator, and the gcloud Pub/Sub, Firestore and Datastore emulators.
4. **Windows: hermetic tier done (2026-11-03).** On Windows 11 with Rust 1.99.1 MSVC,
   `cargo build --workspace` gives 0 warnings and `cargo test --workspace` gives
   **2252 passed, 0 failed**. Fixes made along the way:
   - `cameleer-tls` RNG: seeds from `BCryptGenRandom` on Windows (it only had `/dev/urandom`).
   - `NetStream`: clones and TLS halves share one `Arc<TcpStream>`. On Windows read
     timeouts belong to the handle, so `try_clone`d handles ignored `set_read_timeout`.
   - `net::shutdown_socket`: Windows `shutdown` doesn't wake a blocked `recv`, so it also
     calls `CancelIoEx`. Used by `NetStream::shutdown`, `HttpServer::stop` and the three
     `TcpServer::stop`s. Before this, stopping MLLP took minutes.
   - `net::bind_listener`: binds IPv4 first, like Java. On Windows `localhost` resolves to
     `::1` first. Used by the protocols, amqp and kafka-mqtt `TcpServer`s and `HttpServer`.
   - `cameleer_core::stack` (Linux and Windows stack bounds), shared by `cameleer-script` and a
     new PL/pgSQL `54001` stack check.
   - `.gitattributes` `eol=lf`, because Git for Windows defaults to `core.autocrlf=true`
     and that broke the byte-exact fixtures.
   - Unix-only tests are `cfg(unix)`: SSH agent sockets, `exec` with `echo`/`sh`, file
     modes. Windows variants were added where they make sense.

   - **Bundled IANA time-zone database (2026-11-04).** `cameleer-core/tzdata/zones.bin` has
     IANA 2026f, 598 zones in about 350 KB, compiled into `cameleer-core`. `tz.rs` uses it after
     `$TZDIR` and the system zoneinfo directories, so named zones work on Windows and in
     minimal containers. Zone tests no longer skip. To refresh it, bump the pinned
     version and SHA-256 in `scripts/update-tzdata.py` (source: PyPI `tzdata`, which is
     IANA compiled by `zic`) and rerun it; the script checks the digest. IANA publishes
     several releases a year, so check at every release.

   - The test IMAP server resolved a bare login (`ann`) to a random mailbox starting with
     `ann@`, sometimes a `moveTo` folder. That made `imap_consumer_with_attachments_and_move`
     fail about half the time. Folders are now excluded and the choice is deterministic.

   Still open on Windows:
   - The process default zone (`TimeZone::local`) is UTC unless `TZ` is set. Java uses the
     Windows zone; matching that needs the Windows-to-IANA name map (CLDR `windowsZones`).
   - About 50 other direct `TcpStream::shutdown` calls, mostly client readers and test
     brokers, should move to `net::shutdown_socket` so `stop()` doesn't hang on idle peers.
   - The live, official-client and simulator scripts are bash and Ubuntu-only. Run them
     under WSL2.
5. **Independent security audit** of the from-scratch crypto and protocol code in
   `cameleer-tls` (TLS state machine, X.509 path validation, constant-time code), `cameleer-ssh`,
   `cameleer-xml` xmlsecurity, and the PGP and crypto data formats. Fuzz the parsers (HTTP/1,
   HTTP/2/HPACK, TLS records, BSON, CQL, AMQP frames, YAML, XML).
6. **Optional cleanup.** Run `cargo clippy --workspace`: `cameleer-script` has about 70 lints, and
   there are older lints elsewhere. Builds are already warning-free.
7. **Performance.** **Published comparison (2026-11-06):** `scripts/cloud-bench` on three
   DigitalOcean `c-4` droplets (two servers that swap roles, one load node with Kafka 4.3.2 and
   PostgreSQL 16) against Apache Camel 4.23.0 on Java 21 and Camel Quarkus 3.40.0 native (Camel
   4.22.1, Mandrel 25.0.4.1). Cameleer is ahead in every scenario: 1.7–8.7x Camel JVM throughput,
   3 ms startup vs 1.1 s (native 30 ms), up to 54x less memory. Report: `docs/BENCHMARKS.md`
   (tables generated by `scripts/cloud-bench/summarize.py` from `benchmarks/results/`); landing
   page `site/compare/apache-camel-vs-cameleer/`. The run found and fixed three bugs: HTTP server
   32-worker keep-alive churn (now 200 workers), Kafka producer serializing concurrent sends (now
   batched per broker), PostgreSQL `poolSize` not capping open connections (now a hard maximum
   with `poolTimeout`). Droplets are deleted after each run.

   **Local suite (history):** three tuning rounds against a 4x target on one Windows machine.
   `scripts/bench.sh` (Linux or Git Bash; `scripts/bench.ps1` on Windows) builds and
   runs `crates/cameleer-bench` and `benchmarks/java-camel`, then writes `benchmarks/local.md`. The Java
   side uses Apache Camel 4.23.0 on Temurin 21.0.13 with Maven 3.9.16, pinned and checksum-verified.
   Throughput on a Ryzen 5 5600X under Windows 11, idle machine (rust ÷ java, first round → final):
   - direct 0.68x → **4.27x**, seda InOnly 1.09x → **4.18x**, seda InOut 0.77x → **8.37x**
   - cbr 0.56x → 3.48x, splitagg 0.64x → 3.18x, HTTP 2.02x → 2.45x
   - memory: 25–46x less peak RSS; startup: 77x faster (10 ms vs 751 ms)

   What changed (details in `benchmarks/analysis.md`): a std-only thread-caching allocator
   (`cameleer_core::alloc`, opt-in, installed by the `cameleer` CLI and the benchmark), lazy exchange
   and message ids, vector-backed headers (with shared names) and properties (interned Camel
   names), a copy-on-write `ObjectMap`, a TSC tick clock and striped counters for the statistics,
   Camel's `ManagementStatisticsLevel` with **`RoutesOnly` as Cameleer's default** (per-step
   timing is opt-in; Camel collects nothing without `camel-management`), a two-lock seda queue with
   spin-then-park and a reusable InOut reply slot, a borrowing producer cache, faster Simple
   comparisons, a JsonPath parse cache, in-place aggregation and moving split parts into an
   aggregate, lazy HTTP read timeouts. `cameleer-bench profile <scenario> <secs>` is a std-only
   sampling profiler for Windows; `cameleer-bench raw-http <port> threads|iocp8|poll` measures the HTTP
   ceiling. Tests: `crates/cameleer-core/tests/perf_semantics.rs`, `mgmt_stats.rs` (each statistics
   level), plus unit tests in the changed modules.

   Still under 4x (why, and next steps, in `benchmarks/analysis.md`):
   - HTTP: a do-nothing server (threads or IOCP) reaches only about 400k req/s with the shared load
     generator on this machine, 3.6x Java, so 4x cannot be shown here; Cameleer reaches about 70%
     of that. Needs the load generator on another machine. An event-driven cameleer-http server is
     not built (it measured no faster here); the decision is with the owner.
   - splitagg: JSON parsing and per-part exchange copies; next are shared JSON keys (an `ObjectMap`
     API change) and a smaller `Exchange` (public field changes).
   - cbr: the remaining cost is spread over many small steps.
   - Kafka scenario (optional) not done: it needs a real broker on both sides.

## Resuming in a new session

1. `git checkout main && cargo test --workspace`. Expect 2712 passing
   on Windows and on Linux.
2. Pick an item above.
3. Follow the workflow in `CLAUDE.md`.
4. Update this file, and `docs/INTEROP.md` or `docs/FEATURES.md` where relevant, as part of
   the same change.

## Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building
with it, please help fix it, whether you are a person or a coding agent:
[open an issue](https://github.com/pmsudhi/cameleer/issues/new) that describes what you saw,
then fork the repository, fix it, add or update a test, run `cargo test --workspace`, and open
a pull request. [CONTRIBUTING.md](https://github.com/pmsudhi/cameleer/blob/main/CONTRIBUTING.md)
explains the ground rules.