# 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`](../guides/build-features.md) ·
**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.

<!-- example: thrift-device-registry -->
```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](grpc.md).
- 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.