grow-graylog 0.2.0

Rust SDK for Graylog Open by Grow Codes
Documentation
// Generated by sdk-kit 0.3.0 — do not edit; change sdk-kit and run "sdk-kit sync"
//! Log query model (SPEC §4 `LogQueryClient`) and polling helpers.

use std::fmt;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
use std::time::{Duration, SystemTime};

use async_trait::async_trait;
use serde::Serialize;
use tokio::sync::Notify;

use super::LogRecord;
use crate::core::{poll_until, Error, PollOptions, Result};

/// Result ordering.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SortOrder {
    /// Newest first (default).
    #[default]
    Desc,
    /// Oldest first.
    Asc,
}

/// Options for [`LogQueryClient::search`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SearchOptions {
    /// Earliest timestamp (inclusive).
    pub start: Option<SystemTime>,
    /// Latest timestamp (inclusive).
    pub end: Option<SystemTime>,
    /// Maximum records (default 100).
    pub limit: usize,
    /// Ordering (default newest first).
    pub order: SortOrder,
    /// Cursor from a previous [`LogSearchResult::next_cursor`].
    pub cursor: Option<String>,
}

impl Default for SearchOptions {
    fn default() -> Self {
        SearchOptions {
            start: None,
            end: None,
            limit: 100,
            order: SortOrder::Desc,
            cursor: None,
        }
    }
}

impl SearchOptions {
    /// Sets the limit.
    pub fn limit(mut self, limit: usize) -> Self {
        self.limit = limit;
        self
    }
    /// Sets the time range.
    pub fn range(mut self, start: Option<SystemTime>, end: Option<SystemTime>) -> Self {
        self.start = start;
        self.end = end;
        self
    }
    /// Sets the order.
    pub fn order(mut self, order: SortOrder) -> Self {
        self.order = order;
        self
    }
    /// Sets the cursor.
    pub fn cursor(mut self, cursor: impl Into<String>) -> Self {
        self.cursor = Some(cursor.into());
        self
    }
}

/// One page of search results (SPEC §4 `LogSearchResult`).
#[derive(Debug, Clone, Default, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct LogSearchResult {
    /// Matching records.
    pub records: Vec<LogRecord>,
    /// Cursor for the next page.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub next_cursor: Option<String>,
    /// Total matches when the service reports it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub total: Option<u64>,
}

/// Callback receiving tailed records.
pub type RecordCallback = Arc<dyn Fn(LogRecord) + Send + Sync>;

/// Filter for [`WaitOptions::predicate`].
pub type RecordPredicate = Arc<dyn Fn(&LogRecord) -> bool + Send + Sync>;

/// Options for [`LogQueryClient::tail`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TailOptions {
    /// Poll interval for polling implementations (default 1 s).
    pub interval: Duration,
    /// Only records at or after this time (default now).
    pub start: Option<SystemTime>,
}

impl Default for TailOptions {
    fn default() -> Self {
        TailOptions {
            interval: TailOptions::DEFAULT_INTERVAL,
            start: None,
        }
    }
}

impl TailOptions {
    /// The template default poll interval (1 s).
    pub const DEFAULT_INTERVAL: Duration = Duration::from_secs(1);

    /// The poll interval, with `service_default` in place of the template default: an
    /// `interval` equal to [`DEFAULT_INTERVAL`](Self::DEFAULT_INTERVAL) (or zero) counts as
    /// unset. For services whose API needs a different polling pace.
    pub fn interval_or(&self, service_default: Duration) -> Duration {
        if self.interval.is_zero() || self.interval == Self::DEFAULT_INTERVAL {
            service_default
        } else {
            self.interval
        }
    }
}

/// Stops a running tail; `stop` is idempotent and dropping the handle does **not** stop it.
#[derive(Clone)]
pub struct TailHandle {
    stopped: Arc<AtomicBool>,
    notify: Arc<Notify>,
}

impl fmt::Debug for TailHandle {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("TailHandle")
            .field("stopped", &self.is_stopped())
            .finish()
    }
}

impl Default for TailHandle {
    fn default() -> Self {
        Self::new()
    }
}

impl TailHandle {
    /// A fresh, running handle (for service implementations).
    pub fn new() -> Self {
        TailHandle {
            stopped: Arc::new(AtomicBool::new(false)),
            notify: Arc::new(Notify::new()),
        }
    }

    /// Stops the tail.
    pub fn stop(&self) {
        self.stopped.store(true, Ordering::SeqCst);
        self.notify.notify_waiters();
    }

    /// Whether `stop` was called.
    pub fn is_stopped(&self) -> bool {
        self.stopped.load(Ordering::SeqCst)
    }

    /// Resolves once `stop` was called (for service implementations).
    pub async fn stopped(&self) {
        loop {
            let notified = self.notify.notified();
            tokio::pin!(notified);
            notified.as_mut().enable();
            if self.is_stopped() {
                return;
            }
            notified.await;
        }
    }
}

/// Options for [`wait_for_log`].
#[derive(Clone)]
pub struct WaitOptions {
    /// Give up after this long (default 30 s) with `TIMEOUT`.
    pub timeout: Duration,
    /// Delay between searches (default 1 s).
    pub interval: Duration,
    /// Extra filter on candidate records.
    pub predicate: Option<RecordPredicate>,
}

impl Default for WaitOptions {
    fn default() -> Self {
        WaitOptions {
            timeout: Duration::from_secs(30),
            interval: Duration::from_secs(1),
            predicate: None,
        }
    }
}

impl fmt::Debug for WaitOptions {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("WaitOptions")
            .field("timeout", &self.timeout)
            .field("interval", &self.interval)
            .field("predicate", &self.predicate.is_some())
            .finish()
    }
}

impl WaitOptions {
    /// Sets the timeout.
    pub fn timeout(mut self, d: Duration) -> Self {
        self.timeout = d;
        self
    }
    /// Sets the interval.
    pub fn interval(mut self, d: Duration) -> Self {
        self.interval = d;
        self
    }
    /// Sets the predicate.
    pub fn predicate(mut self, f: impl Fn(&LogRecord) -> bool + Send + Sync + 'static) -> Self {
        self.predicate = Some(Arc::new(f));
        self
    }
}

/// Queries a logging service (SPEC §4). Methods a service cannot serve return `UNSUPPORTED`.
#[async_trait]
pub trait LogQueryClient: Send + Sync {
    /// Searches with the service's query language.
    async fn search(&self, query: &str, opts: SearchOptions) -> Result<LogSearchResult>;

    /// Streams matching records to `on_record` until the handle is stopped.
    async fn tail(
        &self,
        query: &str,
        on_record: RecordCallback,
        opts: TailOptions,
    ) -> Result<TailHandle> {
        let _ = (query, on_record, opts);
        Err(Error::unsupported(
            "logs.tail: not supported by this service",
        ))
    }

    /// Streams / indexes known to the service.
    async fn list_streams(&self) -> Result<Vec<String>> {
        Err(Error::unsupported(
            "logs.listStreams: not supported by this service",
        ))
    }

    /// Labels / fields known to the service.
    async fn list_labels(&self) -> Result<Vec<String>> {
        Err(Error::unsupported(
            "logs.listLabels: not supported by this service",
        ))
    }

    /// Polls [`search`](Self::search) until a record matches; see [`wait_for_log`].
    async fn wait_for_log(&self, query: &str, opts: WaitOptions) -> Result<LogRecord> {
        wait_for_log(self, query, opts).await
    }
}

/// Polls `client.search(query)` until a record matches `opts.predicate` (or any record).
pub async fn wait_for_log<C>(client: &C, query: &str, opts: WaitOptions) -> Result<LogRecord>
where
    C: LogQueryClient + ?Sized,
{
    let predicate = opts.predicate.clone();
    let poll = PollOptions {
        timeout: opts.timeout,
        interval: opts.interval,
    };
    poll_until("logs.waitForLog", poll, || async {
        let page = client.search(query, SearchOptions::default()).await?;
        Ok(page
            .records
            .into_iter()
            .find(|r| predicate.as_ref().is_none_or(|p| p(r))))
    })
    .await
}

/// Generic `tail` on top of `search`: polls oldest-first from `opts.start` (default now) and
/// delivers each record once (by timestamp). Services without streaming can return this.
pub fn poll_tail(
    client: Arc<dyn LogQueryClient>,
    query: &str,
    on_record: RecordCallback,
    opts: TailOptions,
) -> TailHandle {
    let handle = TailHandle::new();
    let h = handle.clone();
    let query = query.to_string();
    tokio::spawn(async move {
        let mut since = opts.start.unwrap_or_else(SystemTime::now);
        let mut seen_at_since: Vec<String> = Vec::new();
        while !h.is_stopped() {
            let search = SearchOptions::default()
                .range(Some(since), None)
                .order(SortOrder::Asc)
                .limit(1000);
            let page = tokio::select! {
                _ = h.stopped() => break,
                page = client.search(&query, search) => page,
            };
            if let Ok(page) = page {
                for r in page.records {
                    if h.is_stopped() {
                        break;
                    }
                    let key = r.to_json();
                    if r.timestamp < since || (r.timestamp == since && seen_at_since.contains(&key))
                    {
                        continue;
                    }
                    if r.timestamp > since {
                        since = r.timestamp;
                        seen_at_since.clear();
                    }
                    seen_at_since.push(key);
                    on_record(r);
                }
            }
            tokio::select! {
                _ = h.stopped() => break,
                _ = tokio::time::sleep(opts.interval) => {}
            }
        }
    });
    handle
}