nifi_rust_client/
lib.rs

1//! An idiomatic Rust client for the [Apache NiFi](https://nifi.apache.org) 2.x
2//! REST API.
3//!
4//! This crate provides two usage modes that trade off compile-time determinism
5//! against runtime flexibility:
6//!
7//! ## Static mode (default)
8//!
9//! Compile against exactly one NiFi version via a Cargo feature flag. The API
10//! surface is fully typed, every endpoint is statically resolved, and the
11//! compiler catches any version drift between your code and the server.
12//!
13//! ```no_run
14//! use nifi_rust_client::NifiClientBuilder;
15//!
16//! # async fn example() -> Result<(), nifi_rust_client::NifiError> {
17//! let client = NifiClientBuilder::new("https://nifi.example.com:8443")?.build()?;
18//! client.login("admin", "adminpassword123").await?;
19//!
20//! # #[cfg(not(feature = "dynamic"))]
21//! let about = client.flow_api().get_about_info().await?;
22//! # #[cfg(not(feature = "dynamic"))]
23//! println!("Connected to NiFi {:?}", about.version);
24//! # Ok(())
25//! # }
26//! ```
27//!
28//! Enable a specific version via Cargo features:
29//!
30//! ```toml
31//! [dependencies]
32//! nifi-rust-client = { version = "0.5", features = ["nifi-2-8-0"] }
33//! ```
34//!
35//! ## Dynamic mode (`dynamic` feature)
36//!
37//! Compile all supported versions and detect the NiFi server version at
38//! runtime via `/flow/about`. Use this when your code must talk to multiple
39//! server versions without recompilation.
40//!
41//! ```no_run
42//! # #[cfg(feature = "dynamic")]
43//! # async fn example() -> Result<(), nifi_rust_client::NifiError> {
44//! use nifi_rust_client::NifiClientBuilder;
45//! use nifi_rust_client::dynamic::VersionResolutionStrategy;
46//!
47//! let client = NifiClientBuilder::new("https://nifi.example.com:8443")?
48//!     .version_strategy(VersionResolutionStrategy::Closest)
49//!     .build_dynamic()?;
50//!
51//! // login() authenticates AND auto-detects the NiFi version.
52//! client.login("admin", "adminpassword123").await?;
53//! # Ok(())
54//! # }
55//! ```
56//!
57//! Enable via:
58//!
59//! ```toml
60//! [dependencies]
61//! nifi-rust-client = { version = "0.5", features = ["dynamic"] }
62//! ```
63//!
64//! ## Entry points
65//!
66//! - [`NifiClientBuilder`] — construct a client with timeouts, proxies, TLS
67//!   options, credential providers, and retry policy.
68//! - [`NifiClient`] — the client handle itself; resource accessors like
69//!   `.flow_api()`, `.processors_api()`, etc. return borrowed resource structs.
70//! - [`NifiError`] — `#[non_exhaustive]` error type with typed variants
71//!   (`Unauthorized`, `Forbidden`, `NotFound`, `Conflict`,
72//!   `UnsupportedEndpoint`, etc.) and helpers like `status_code()` and
73//!   `is_retryable()`.
74//! - [`CredentialProvider`] and its impls (`StaticCredentials`,
75//!   `EnvCredentials`) in the [`config::credentials`] module — used with
76//!   [`NifiClientBuilder::credential_provider`] to enable auto-refresh on 401.
77//! - [`config::retry::RetryPolicy`] — exponential-backoff retry on transient
78//!   errors, configured via [`NifiClientBuilder::retry_policy`].
79//!
80//! ## Running examples
81//!
82//! ```bash
83//! NIFI_URL=https://localhost:8443 \
84//! NIFI_USERNAME=admin NIFI_PASSWORD=adminpassword123 \
85//! cargo run --example basic_static
86//! ```
87//!
88//! All examples accept the same environment variables. See `examples/` in
89//! the repository for the full set.
90//!
91//! ## Feature flags
92//!
93//! | Feature | Purpose |
94//! |---|---|
95//! <!-- NIFI_FEATURE_FLAGS_START -->
96//! | `nifi-2-6-0`, `nifi-2-7-2`, `nifi-2-8-0`, `nifi-2-9-0` | Compile against a specific NiFi version. The semver-latest is the default. |
97
98//! <!-- NIFI_FEATURE_FLAGS_END -->
99//! | `dynamic` | Compile all versions and enable runtime version detection. Pulls in every version feature. |
100//!
101//! At least one version feature (or `dynamic`) must be enabled — builds with
102//! none fail at both build-script time and compile time.
103
104// `has_any_version` is a rustc-cfg emitted by build.rs whenever it runs
105// successfully with at least one NiFi version feature enabled (or the
106// `dynamic` feature, which pulls in all versions). The flag is invisible
107// to users — it isn't a Cargo feature and can't be set externally. If
108// build.rs is ever bypassed entirely (some `cargo doc` / rust-analyzer
109// configurations), the flag is unset and this compile_error! fires with
110// an actionable message. The primary zero-features guard is the runtime
111// check in build.rs itself; this is defence in depth.
112#[cfg(not(has_any_version))]
113compile_error!(
114    "nifi-rust-client requires at least one version feature to be enabled. \
115     Enable one of `nifi-2-6-0`, `nifi-2-7-2`, `nifi-2-8-0`, or the `dynamic` \
116     feature in your Cargo.toml."
117);
118
119/// Client builder: configure timeouts, TLS, credentials, and retry before connecting.
120pub mod builder;
121/// The connected client handle and resource accessor methods.
122pub mod client;
123/// Configuration types: credential providers and retry policy.
124pub mod config;
125/// Error type returned by all client operations.
126pub mod error;
127pub use builder::NifiClientBuilder;
128pub use client::NifiClient;
129pub use config::credentials::CredentialProvider;
130pub use error::NifiError;
131
132// Generated: version modules, re-exports, dynamic module
133include!(concat!(env!("OUT_DIR"), "/generated_lib.rs"));
nifi_rust_client/lib.rs

nifi_rust_client/
lib.rs
