DOCSEARCHbyAlgolia
Submit Docs

Eclipse Zenoh Documentation

repository·main·Indexed 25 days ago

https://github.com/eclipse-zenoh/zenoh

A high-performance, unified protocol for data in motion (pub/sub), data at rest (storage/queries), and computation, designed for efficiency across distributed environments. The documentation covers the core zenoh and zenoh-ext crates, Rust 1.75 compatibility via zenoh-pinned-deps-1-75, and internal components such as zenoh-protocol, zenoh-buffers, and zenoh-test for integration testing.

Tokens
31.6K
Snippets
75
Records
203
Agent score
84%

What's inside Eclipse Zenoh

  1. Overview of the Zenoh Storage Manager Plugin

    main

    The storage_manager plugin for the zenohd router allows connecting Zenoh to various external storage backends (e.g., databases). It acts as a plugin manager that loads specific backends to implement storage APIs.

    Available backends include:

    • memory: Stores data in an in-memory hashmap (statically linked).
    • zenoh-backend-filesystem: Uses the host file system.
    • zenoh-backend-s3: Uses Amazon S3 or MinIO.
    • zenoh-backend-rocksdb: Uses RocksDB.
    • zenoh-backend-influxdb: Uses InfluxDB.

  2. Overview of Zenoh language support

    main

    Zenoh provides implementations and bindings for multiple languages:

    • Rust: The primary reference implementation (available in this repository).
    • C: Two options: zenoh-c (Rust library binding) and zenoh-pico (pure C implementation).
    • C++: zenoh-cpp (C++ wrapper over C libraries).
    • Python: zenoh-python.
    • Kotlin: zenoh-kotlin.
    • Java: zenoh-java.
    • TypeScript: zenoh-ts (WebSocket client for the zenohd plugin).
    • Go: zenoh-go.

  3. Overview of Eclipse Zenoh

    main
    Eclipse Zenoh is a high-performance protocol that unifies data in motion (pub/sub), data at rest (storage/query), and computations. It supports arbitrary network topologies, hierarchical keys with glob support (key expressions), zero-copy data buffers, and shared memory. It is designed for high efficiency in time and space across various network protocols.

  4. Use public APIs instead of zenoh-protocol

    main

    ⚠️ WARNING ⚠️

    The zenoh-protocol crate is intended for Zenoh's internal use only. Its API is not stable and may change without notice, even in patch updates.

    To ensure stability in your application, it is highly recommended to depend solely on the zenoh and zenoh-ext crates and utilize their public APIs instead of interacting with zenoh-protocol directly.

  6. Compile Zenoh with Rust 1.75

    main

    While the zenoh crate can be compiled with Rust 1.75.0, some dependencies may require higher versions. To ensure compatibility, add the zenoh-pinned-deps-1-75 crate to your Cargo.toml.

    zenoh = "1.5.1"
zenoh-pinned-deps-1-75 = "1.5.1"

  7. Fuzz the endpoint_from_str target

    main

    The zenoh-protocol crate includes a cargo-fuzz target for the endpoint_from_str function. You can manage the fuzzing lifecycle using the following commands from the commons/zenoh-protocol/fuzz directory:

    Corpus Management

    • Generate deterministic seed corpus: cargo run --bin gen_endpoint_corpus
    • Verify corpus matches parser behavior: cargo run --bin verify_endpoint_corpus

    Running Fuzzers

    • Run the fuzz target: cargo +nightly fuzz run endpoint_from_str
    • Rerun a specific crash input: cargo +nightly fuzz run endpoint_from_str artifacts/endpoint_from_str/crash-xxxx
    • Analyze a single input without the fuzz loop: cargo run --bin analyze_endpoint_from_str -- "<input_string>" (e.g., cargo run --bin analyze_endpoint_from_str -- "tcp/127.0.0.1:7447?b=2;a=1#B=2;A=1")
    # Generate the deterministic seed corpus
cargo run --bin gen_endpoint_corpus

# Optional: verify the generated corpus matches the current parser behavior
cargo run --bin verify_endpoint_corpus

# Run the fuzz target
cargo +nightly fuzz run endpoint_from_str

# Only rerun a certain input
cargo +nightly fuzz run endpoint_from_str artifacts/endpoint_from_str/crash-xxxx

# Analyze one input without running the fuzz loop
cargo run --bin analyze_endpoint_from_str -- "tcp/127.0.0.1:7447?b=2;a=1#B=2;A=1"

  8. Use zenoh-pinned-deps-1-75 for Rust 1.75 compatibility

    main
    If your project needs to support Rust version 1.75, use the zenoh-pinned-deps-1-75 crate. All other crates in the commons/ directory are internal components of Zenoh, are not intended for direct use, and have unstable public APIs that may change without notice.

  9. Run the Zenoh router (zenohd)

    main
    zenohd is the Zenoh daemon router used to build Zenoh infrastructure. It acts as the Zenoh runtime with a plugin manager. You can run it as a standalone process to manage pub/sub, storage, and queries across your network. For installation instructions, visit zenoh.io.

  10. Run Zenoh Rust examples

    main

    To run the compiled Zenoh Rust examples in release mode, use the path to the binary in the target directory:

    ./target/release/example/<example_name>

    Each example supports the -h or --help flag to view available arguments and default values.

    Note for Docker users: If running tests against a Zenoh router inside a Docker container, you must add the -e tcp/localhost:7447 option. Docker does not support UDP multicast, which is required for Zenoh's default scouting and discovery mechanisms.

    ./target/release/example/<example_name>

  11. Activate the REST plugin for `zenohd`

    main

    The REST plugin is statically linked to the zenohd router and does not require separate installation. You can activate it using one of two methods:

    1. CLI Argument: Pass the --rest-http-port=<port> flag when running zenohd.
    2. Configuration File: Specify the port in the plugins section of your config.json file.

    This plugin maps REST operations to Zenoh operations as follows:

    • PUT and DELETE $\rightarrow$ Pub/Sub API
    • GET $\rightarrow$ Query/Reply API
    "plugins": {
  "rest": {
    "http_port": 8000,
  }
}

  12. Enable Rust 1.75 compatibility for Zenoh

    main

    The zenoh crate requires a minimum Rust version of 1.75. However, because zenoh's transitive dependencies may require newer Rust versions, simply adding zenoh to your project may cause compilation failures when using Rust 1.75.

    To ensure compatibility with Rust 1.75, you must add the zenoh-pinned-deps-1-75 crate to your Cargo.toml alongside the zenoh crate. This crate provides locked versions of dependencies that are compatible with Rust 1.75 without causing version conflicts in your dependency graph.

    zenoh = "1.5.1"
zenoh-pinned-deps-1-75 = "1.5.1"