koprs_external/lib.rs
1//! # koprs-external
2//!
3//! Generic polling watchers for external sources such as HTTP REST APIs and
4//! S3 buckets, designed as a companion to `koprs` Kubernetes operators.
5//!
6//! Kubernetes operators often need to reconcile cluster state with resources
7//! that live outside the cluster — a configuration endpoint, an object store,
8//! or a remote registry. `koprs-external` provides a lightweight polling
9//! abstraction that fits naturally alongside `koprs` controllers.
10//!
11//! ## Core model
12//!
13//! The [`watcher::ExternalSource`] trait represents any source that can be
14//! polled for changes. Implementations return [`ExternalEvent`] values that
15//! distinguish
16//! between items being added, modified, or removed. The source tracks its own
17//! state between polls so callers do not need to diff results themselves.
18//!
19//! [`watch_external`] spawns a background task that ticks on a configurable
20//! interval and forwards events to an [`tokio::sync::mpsc`] channel, mirroring
21//! the pattern used by `koprs::watcher`.
22//!
23//! ## Quick start
24//!
25//! ```no_run
26//! use std::time::Duration;
27//! use koprs_external::http::HttpPoller;
28//! use koprs_external::watcher::{watch_external, ExternalEvent};
29//! use tokio::sync::mpsc;
30//!
31//! #[tokio::main]
32//! async fn main() {
33//! let (tx, mut rx) = mpsc::channel(16);
34//! let poller = HttpPoller::new("https://api.example.com/config")
35//! .with_bearer_token("my-token")
36//! .with_name("config-api");
37//!
38//! let _handle = watch_external(poller, Duration::from_secs(30), tx);
39//!
40//! while let Some(event) = rx.recv().await {
41//! match event {
42//! ExternalEvent::Added(r) => println!("config appeared: {} bytes", r.body.len()),
43//! ExternalEvent::Modified(r) => println!("config changed: {} bytes", r.body.len()),
44//! ExternalEvent::Removed(_) => println!("config endpoint gone"),
45//! }
46//! }
47//! }
48//! ```
49
50pub mod error;
51pub mod http;
52pub mod watcher;
53
54#[cfg(feature = "object-store")]
55pub mod store;
56
57pub use error::ExternalError;
58pub use watcher::{ExternalEvent, WatchConfig, watch_external, watch_external_with_config};
59
60#[cfg(test)]
61mod tests;