apache-iggy

discord-badge

Apache Iggy is the persistent message streaming platform written in Rust, supporting QUIC, TCP and HTTP transport protocols, capable of processing millions of messages per second.

Apache Iggy (Incubating) is an effort undergoing incubation at the Apache Software Foundation (ASF), sponsored by the Apache Incubator PMC.

Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects.

While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.

Installation

Basic Installation

# Using uv
uv add apache-iggy

# Using pip
python3 -m venv .venv
source .venv/bin/activate
pip install apache-iggy

Supported Python Versions

  • Python 3.10+

Local Development

# Start server for testing using docker
docker compose -f docker-compose.test.yml up --build

# Or use cargo
cargo run --bin iggy-server -- --with-default-root-credentials --fresh

# Using uv:
uv sync --all-extras
uv run maturin develop
uv run pytest tests/ -v # Run tests (requires iggy-server running)

# Using pip:
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[all]"
maturin develop
pytest tests/ -v # Run tests (requires iggy-server running)

VSR builds

The Python extension uses the Rust SDK's compile-time framing mode. The default build speaks classic framing. Build a VSR extension explicitly:

uv run maturin develop --features vsr

A built wheel contains one framing mode; it cannot switch between classic and VSR at runtime.

Raw requests require an explicit replication declaration:

from apache_iggy import BinaryRequestKind

response = await client.send_binary_request(
    BinaryRequestKind.NonReplicated,
    code,
    payload,
)

With VSR framing, standard command tables remain authoritative. Unknown non-replicated codes are forwarded for the server to judge. Unknown replicated codes are unavailable until the protocol has a replicated extension registry.

Examples

Refer to the examples/python/ directory for usage examples.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Licensed under the Apache License 2.0. See LICENSE for details.