kumo_prometheus/
lib.rs

1pub use crate::counter::*;
2use crate::labels::MetricLabel;
3use crate::registry::StreamingCollector;
4pub use crate::sharded::{CountAndSize, ShardedCountAndSize};
5use async_stream::stream;
6use futures::stream::BoxStream;
7use futures::StreamExt;
8use parking_lot::{RwLock, RwLockUpgradableReadGuard};
9pub use pastey as paste;
10use serde::Serialize;
11use std::borrow::Borrow;
12use std::collections::HashMap;
13use std::hash::Hash;
14use std::sync::{Arc, LazyLock};
15
16mod counter;
17pub mod counter_bundle;
18
19#[macro_use]
20pub mod labels;
21pub mod parser;
22pub mod registry;
23mod sharded;
24pub use prometheus;
25
26struct CounterRegistryInner<K, V: AtomicCounterEntry> {
27    map: RwLock<HashMap<K, V>>,
28    name: &'static str,
29    help: String,
30    metric_type: MetricType,
31}
32
33/// Keep up to 4k at a time of pending text or json data
34/// when streaming out the serialized counter values
35const CHUNK_SIZE: usize = 4 * 1024;
36
37impl<K: Clone + MetricLabel + Send + Sync, V: AtomicCounterEntry> StreamingCollector
38    for CounterRegistryInner<K, V>
39{
40    fn stream_text(&'_ self, prefix: &Option<String>) -> BoxStream<'_, String> {
41        /*
42        # HELP tokio_total_overflow_count The number of times worker threads saturated their local queues.
43        # TYPE tokio_total_overflow_count counter
44        tokio_total_overflow_count 0
45        total_connection_count{service="smtp_client:source2->loopback.dummy-mx.wezfurlong.org@smtp_client"} 25
46        */
47
48        let mut buffer = String::with_capacity(CHUNK_SIZE);
49        buffer.push_str("# HELP ");
50        let prefix = prefix.as_deref().unwrap_or("").to_string();
51        buffer.push_str(&prefix);
52        buffer.push_str(self.name);
53        buffer.push(' ');
54        buffer.push_str(&self.help);
55        buffer.push_str("\n# TYPE ");
56        buffer.push_str(&prefix);
57        buffer.push_str(self.name);
58        buffer.push(' ');
59        buffer.push_str(self.metric_type.label());
60        buffer.push('\n');
61
62        let mut buffer = Some(buffer);
63
64        let counters = {
65            let map = self.map.read();
66            let mut pairs = Vec::with_capacity(map.len());
67            for (key, weak) in map.iter() {
68                if let Some(strong) = weak.resolve() {
69                    pairs.push((key.clone(), strong));
70                }
71            }
72            pairs
73        };
74
75        stream! {
76            for (key, counter) in counters {
77                let Some(buf) = buffer.as_mut() else {break;};
78
79                buf.push_str(&prefix);
80                buf.push_str(self.name);
81                key.emit_text_value(buf, &counter.get().to_string());
82                buf.push('\n');
83
84                let need_flush = buf.len() >= CHUNK_SIZE;
85
86                if need_flush {
87                    yield buffer.take().expect("always have buffer");
88                    buffer.replace(String::with_capacity(CHUNK_SIZE));
89                }
90            }
91
92            if let Some(buf) = buffer.take() {
93                if !buf.is_empty(){
94                    yield buf;
95                }
96            }
97
98        }
99        .boxed()
100    }
101
102    fn stream_json(&'_ self) -> BoxStream<'_, String> {
103        let mut target = String::with_capacity(CHUNK_SIZE);
104        target.push_str(",\n\"");
105        target.push_str(self.name);
106        target.push_str("\":{");
107        if !self.help.is_empty() {
108            target.push_str("\"help\":\"");
109            target.push_str(&self.help);
110            target.push_str("\",");
111        }
112        target.push_str("\"type\":\"");
113        target.push_str(self.metric_type.label());
114        target.push_str("\",\"value\":");
115
116        let counters = {
117            let map = self.map.read();
118            let mut pairs = Vec::with_capacity(map.len());
119            for (key, weak) in map.iter() {
120                if let Some(strong) = weak.resolve() {
121                    pairs.push((key.clone(), strong));
122                }
123            }
124            pairs
125        };
126
127        stream! {
128            if counters.is_empty() {
129                target.push_str("null}");
130                yield target;
131                return;
132            }
133
134            let labels = K::label_names();
135
136            if labels.len() == 1 {
137                target.push_str("{\"");
138                target.push_str(labels[0]);
139                target.push_str("\":{");
140            } else {
141                target.push('[');
142            }
143
144            let mut buffer = Some(target);
145
146            for (i, (key, counter)) in counters.iter().enumerate() {
147                let Some(target) = buffer.as_mut() else {break;};
148                if i > 0 {
149                    target.push_str(",\n");
150                }
151
152                let value = counter.get().to_string();
153                key.emit_json_value(target,&value);
154
155                let need_flush = target.len() >= CHUNK_SIZE;
156
157                if need_flush {
158                    yield buffer.take().expect("always have buffer");
159                    buffer.replace(String::with_capacity(CHUNK_SIZE));
160                }
161            }
162
163            let Some(mut target) = buffer.take() else {return;};
164            if labels.len() == 1 {
165                target.push_str("}}}");
166            } else {
167                target.push_str("]}");
168            }
169
170            yield target;
171        }
172        .boxed()
173    }
174
175    fn prune(&self) {
176        if !V::needs_pruning() {
177            return;
178        }
179
180        let mut map = self.map.write();
181        map.retain(|_key, entry| entry.resolve().is_some());
182    }
183}
184
185/// Either a Counter or Gauge with a specific name, where there can
186/// be multiple labelled counter instances.
187///
188/// CounterRegistry has a PruningCounterRegistry variant which will
189/// drop unreferenced counter instances when they fall out of scope.
190///
191/// The key type K must be created via the label_key! macro provided
192/// by this crate. It allows making type-safe keys and resolving
193/// counter instances without making extraneous copies of the keys.
194///
195/// CounterRegistry implements the StreamingCollector trait which
196/// allows for efficient streaming serialization of its set of
197/// counters in either text or json format.
198pub struct CounterRegistry<K, V: AtomicCounterEntry = AtomicCounter> {
199    inner: Arc<CounterRegistryInner<K, V>>,
200}
201
202impl<K, V: AtomicCounterEntry> CounterRegistry<K, V> {
203    pub fn metric_type(&self) -> MetricType {
204        self.inner.metric_type
205    }
206}
207
208pub type PruningCounterRegistry<K> = CounterRegistry<K, WeakAtomicCounter>;
209
210#[derive(Serialize, Clone, Copy)]
211pub enum MetricType {
212    Counter,
213    Gauge,
214    Histogram,
215}
216
217impl MetricType {
218    pub fn label(&self) -> &'static str {
219        match self {
220            Self::Counter => "counter",
221            Self::Gauge => "gauge",
222            Self::Histogram => "histogram",
223        }
224    }
225}
226
227#[derive(Serialize, Clone, Copy)]
228pub enum MetricPrune {
229    Pruning,
230    NonPruning,
231}
232
233#[derive(Serialize, Clone)]
234pub struct CounterDescription {
235    /// The name of the counter, as it appears in the metric export
236    pub name: String,
237    /// Help description, preserving the author's line wrapping.
238    pub help: String,
239    /// Any documentation paragraphs following the first, preserved verbatim.
240    pub doc: Option<String>,
241    /// What sort of metric this is
242    pub metric_type: MetricType,
243    /// If the metric has labels, this lists them out
244    pub label_names: Vec<String>,
245    /// If the metric is a histogram, this holds the bucket thresholds
246    pub buckets: Vec<f64>,
247    /// True if the metric is subject to pruning
248    pub pruning: MetricPrune,
249}
250
251/// Accumulates metric metadata
252#[linkme::distributed_slice]
253pub static COUNTER_METADATA: [fn() -> CounterDescription];
254
255fn compute_metadata() -> Vec<CounterDescription> {
256    let mut metadata = vec![];
257
258    for func in COUNTER_METADATA.iter() {
259        let desc = (func)();
260        metadata.push(desc);
261    }
262
263    metadata.sort_by(|a, b| a.name.cmp(&b.name));
264    metadata
265}
266
267static METADATA: LazyLock<Vec<CounterDescription>> = LazyLock::new(compute_metadata);
268
269pub fn export_metadata() -> Vec<CounterDescription> {
270    // We're generally called early in a process lifecycle, and Registry
271    // requires a running tokio environment otherwise it will panic,
272    // so we make a little one just for this call.
273    let rt = tokio::runtime::Builder::new_current_thread()
274        .build()
275        .expect("failed to make single thread runtime for export_metadata call");
276    let _guard = rt.enter();
277    METADATA.clone()
278}
279
280/// This macro matches a series of doc comment attributes.
281/// Multi-line doc comments appear as a sequence of doc
282/// comment attributes, so we need to be able to match
283/// both the individual case and the sequence, and map
284/// them back to a single string.
285///
286/// While this macro accepts the no-doc-comment case,
287/// we require that every metric have a doc comment,
288/// so we will emit a compile error if none were present.
289#[macro_export]
290macro_rules! mandatory_doc {
291    ($doc:expr) => {
292        $doc
293    };
294    ($($doc:expr)+) => {
295        // Join the sequence into a multi-line string
296        concat!($($doc, "\n",)+)
297    };
298    () => {
299        compile_error!("doc comments are mandatory")
300    };
301}
302
303/// Collapse a multi-line string into a space-separated line.
304pub fn one_line(s: &str) -> String {
305    s.replace("\n", " ").trim().to_string()
306}
307
308/// Splits doc comment metadata. Look for two successive line breaks. If they
309/// are present, they denote the break between the first paragraph and a longer
310/// descriptive exposition. Returns that first paragraph, preserving the
311/// author's line wrapping, and the optional exposition.
312pub fn split_help(help: &str) -> (String, Option<String>) {
313    // The input will be a series of lines each with a space
314    // at the start because "/// something" -> " something".
315    // Normalize those away.
316    let normalized = help.trim().replace("\n ", "\n");
317
318    match normalized.split_once("\n\n") {
319        Some((a, b)) => (a.to_string(), Some(b.to_string())),
320        None => (normalized, None),
321    }
322}
323
324#[doc(hidden)]
325#[macro_export]
326macro_rules! __histogram_buckets {
327    () => {
328        $crate::prometheus::DEFAULT_BUCKETS.to_vec()
329    };
330    ($buckets:expr) => {
331        $buckets
332    };
333}
334
335#[doc(hidden)]
336#[macro_export]
337macro_rules! __register_metric {
338    (
339        $sym:ident,
340        $name:expr,
341        $($doc:expr)+,
342        $metric:expr,
343        $labels:expr,
344        $pruning:expr
345    ) => {
346        $crate::__register_metric!($sym, $name, $($doc)+, $metric, $labels, $pruning, vec![]);
347    };
348
349    (
350        $sym:ident,
351        $name:expr,
352        $($doc:expr)+,
353        $metric:expr,
354        $labels:expr,
355        $pruning:expr,
356        $buckets:expr
357    ) => {
358        // Link into COUNTER_METADATA
359        $crate::paste::paste! {
360            #[linkme::distributed_slice($crate::COUNTER_METADATA)]
361            static [<VIVIFY_ $sym>]: fn() -> $crate::CounterDescription = || {
362                ::std::sync::LazyLock::force(&$sym);
363                let (help, doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
364                let labels : &[&str] = $labels;
365                $crate::CounterDescription {
366                    name: $name.to_string(),
367                    help,
368                    doc,
369                    metric_type: $metric,
370                    label_names: labels.iter().map(|s| s.to_string()).collect(),
371                    buckets: $buckets,
372                    pruning: $pruning,
373                }
374            };
375        }
376    }
377}
378
379/// This macro aids in declaring metrics.  Usage looks like:
380///
381/// ```rust
382/// declare_metric! {
383/// /// The number of active outgoing connections in the system,
384/// /// keyed by the service name.
385/// pub static CONN_GAUGE: PruningGaugeRegistry<ServiceKey>("connection_count");
386/// }
387/// ```
388///
389/// This will wrap the declaration of the global into a LazyLock as
390/// well as capture metadata about the metric in a way that allows
391/// it to be retrieved via the `export_metadata()` function.
392///
393/// Doc comments are required for every metric declared by this
394/// macro.
395///
396/// Different types of metric collector are supported, not just
397/// the `PruningGaugeRegistry` shown above.
398///
399/// `PruningGaugeRegistry` is not actually a real type, it is
400/// some sugar allowed here to enable setting up a Gauge
401/// rather than a Counter.
402#[macro_export]
403macro_rules! declare_metric {
404    (
405        $(#[doc = $doc:expr])*
406        $vis:vis
407        static $sym:ident:
408        CounterRegistry<$key:ty>(
409            $name:expr $(,)?
410        );
411    ) => {
412        $(#[doc = $doc])*
413        $vis static $sym: ::std::sync::LazyLock<$crate::CounterRegistry<$key>> =
414            ::std::sync::LazyLock::new(
415                || {
416                    let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
417                    let help = $crate::one_line(&help);
418                    $crate::CounterRegistry::register($name, help)
419                });
420
421        $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Counter,
422            <$key as $crate::labels::MetricLabel>::label_names(),
423            $crate::MetricPrune::NonPruning
424        );
425    };
426
427    (
428        $(#[doc = $doc:expr])*
429        $vis:vis
430        static $sym:ident:
431        PruningCounterRegistry<$key:ty>(
432            $name:expr $(,)?
433        );
434    ) => {
435        $(#[doc = $doc])*
436        $vis static $sym: ::std::sync::LazyLock<$crate::PruningCounterRegistry<$key>> =
437            ::std::sync::LazyLock::new(
438                || {
439                    let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
440                    let help = $crate::one_line(&help);
441                    $crate::PruningCounterRegistry::register($name, help)
442                });
443
444        $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Counter,
445            <$key as $crate::labels::MetricLabel>::label_names(),
446            $crate::MetricPrune::Pruning
447        );
448    };
449
450    (
451        $(#[doc = $doc:expr])*
452        $vis:vis
453        static $sym:ident:
454        PruningGaugeRegistry<$key:ty>(
455            $name:expr $(,)?
456        );
457    ) => {
458        $(#[doc = $doc])*
459        $vis static $sym: ::std::sync::LazyLock<$crate::PruningCounterRegistry<$key>> =
460            ::std::sync::LazyLock::new(
461                || {
462                    let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
463                    let help = $crate::one_line(&help);
464                    $crate::PruningCounterRegistry::register_gauge($name, help)
465                });
466
467        $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Gauge,
468            <$key as $crate::labels::MetricLabel>::label_names(),
469            $crate::MetricPrune::Pruning
470        );
471    };
472
473
474    (
475        $(#[doc = $doc:expr])*
476        $vis:vis
477        static $sym:ident:
478        IntGaugeVec(
479            $name:expr,
480            $labels:expr $(,)*
481        );
482    ) => {
483        $(#[doc = $doc])*
484        $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::IntGaugeVec> =
485            ::std::sync::LazyLock::new(
486                || {
487                    let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
488                    let help = $crate::one_line(&help);
489
490                    $crate::prometheus::register_int_gauge_vec!(
491                        $name,
492                        help,
493                        $labels
494                    ).unwrap()
495                });
496
497        $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Gauge,
498            $labels, $crate::MetricPrune::NonPruning);
499    };
500    (
501        $(#[doc = $doc:expr])*
502        $vis:vis
503        static $sym:ident:
504        IntCounterVec(
505            $name:expr,
506            $labels:expr $(,)*
507        );
508    ) => {
509        $(#[doc = $doc])*
510        $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::IntCounterVec> =
511            ::std::sync::LazyLock::new(
512                || {
513                    let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
514                    let help = $crate::one_line(&help);
515
516                    $crate::prometheus::register_int_counter_vec!(
517                        $name,
518                        help,
519                        $labels
520                    ).unwrap()
521                });
522
523        $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Counter,
524            &$labels[..], $crate::MetricPrune::NonPruning);
525    };
526    (
527        $(#[doc = $doc:expr])*
528        $vis:vis
529        static $sym:ident:
530        CounterVec(
531            $name:expr,
532            $labels:expr $(,)*
533        );
534    ) => {
535        $(#[doc = $doc])*
536        $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::CounterVec> =
537            ::std::sync::LazyLock::new(
538                || {
539                    let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
540                    let help = $crate::one_line(&help);
541
542                    $crate::prometheus::register_counter_vec!(
543                        $name,
544                        help,
545                        $labels
546                    ).unwrap()
547                });
548
549        $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Counter,
550            &$labels[..], $crate::MetricPrune::NonPruning);
551    };
552    (
553        $(#[doc = $doc:expr])*
554        $vis:vis
555        static $sym:ident:
556        HistogramVec(
557            $name:expr,
558            $labels:expr
559            $(, $buckets:expr)?
560            $(,)*
561        );
562    ) => {
563        $(#[doc = $doc])*
564        $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::HistogramVec> =
565            ::std::sync::LazyLock::new(
566                || {
567                    let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
568                    let help = $crate::one_line(&help);
569
570                    $crate::prometheus::register_histogram_vec!(
571                        $name,
572                        help,
573                        $labels
574                        $(,$buckets)?
575                    ).unwrap()
576                });
577
578        $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Histogram,
579            &$labels[..],
580            $crate::MetricPrune::NonPruning,
581            $crate::__histogram_buckets!($($buckets)?)
582        );
583    };
584
585    (
586        $(#[doc = $doc:expr])*
587        $vis:vis
588        static $sym:ident:
589        Histogram($name:expr $(, $buckets:expr)?);
590    ) => {
591        $(#[doc = $doc])*
592        $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::Histogram> =
593            ::std::sync::LazyLock::new(
594                || {
595                    let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
596                    let help = $crate::one_line(&help);
597
598                    $crate::prometheus::register_histogram!(
599                        $name,
600                        help,
601                        $($buckets)?
602                    ).unwrap()
603                });
604
605        $crate::__register_metric!($sym, $name, $($doc)*, $crate::MetricType::Histogram, &[],
606            $crate::MetricPrune::NonPruning,
607            $crate::__histogram_buckets!($($buckets)?)
608        );
609    };
610
611    (
612        $(#[doc = $doc:expr])*
613        $vis:vis
614        static $sym:ident:
615        IntCounter($name:expr);
616    ) => {
617        $(#[doc = $doc])*
618        $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::IntCounter> =
619            ::std::sync::LazyLock::new(
620                || {
621                    let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
622                    let help = $crate::one_line(&help);
623
624                    $crate::prometheus::register_int_counter!(
625                        $name,
626                        help,
627                    ).unwrap()
628                });
629
630        $crate::__register_metric!($sym, $name, $($doc)*,
631            $crate::MetricType::Counter, &[], $crate::MetricPrune::NonPruning);
632    };
633
634    (
635        $(#[doc = $doc:expr])*
636        $vis:vis
637        static $sym:ident:
638        IntGauge($name:expr);
639    ) => {
640        $(#[doc = $doc])*
641        $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::IntGauge> =
642            ::std::sync::LazyLock::new(
643                || {
644                    let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
645                    let help = $crate::one_line(&help);
646
647                    $crate::prometheus::register_int_gauge!(
648                        $name,
649                        help,
650                    ).unwrap()
651                });
652
653        $crate::__register_metric!($sym, $name, $($doc)*,
654            $crate::MetricType::Gauge, &[], $crate::MetricPrune::NonPruning);
655    };
656    (
657        $(#[doc = $doc:expr])*
658        $vis:vis
659        static $sym:ident:
660        Gauge($name:expr);
661    ) => {
662        $(#[doc = $doc])*
663        $vis static $sym: ::std::sync::LazyLock<$crate::prometheus::Gauge> =
664            ::std::sync::LazyLock::new(
665                || {
666                    let (help, _doc) = $crate::split_help($crate::mandatory_doc!($($doc)*));
667                    let help = $crate::one_line(&help);
668
669                    $crate::prometheus::register_gauge!(
670                        $name,
671                        help,
672                    ).unwrap()
673                });
674
675        $crate::__register_metric!($sym, $name, $($doc)*,
676            $crate::MetricType::Gauge, &[], $crate::MetricPrune::NonPruning);
677    };
678}
679
680impl<K, V: AtomicCounterEntry> Clone for CounterRegistry<K, V> {
681    fn clone(&self) -> Self {
682        Self {
683            inner: Arc::clone(&self.inner),
684        }
685    }
686}
687
688impl<K: Clone + Send + Sync + MetricLabel + 'static, V: AtomicCounterEntry + 'static>
689    CounterRegistry<K, V>
690{
691    /// Register a set of Counters, values that are only allowed
692    /// to increment.
693    pub fn register(name: &'static str, help: String) -> Self {
694        Self::register_impl(name, help, MetricType::Counter)
695    }
696
697    /// Register a set of Gauges, values that are allowed to increase and decrease.
698    pub fn register_gauge(name: &'static str, help: String) -> Self {
699        Self::register_impl(name, help, MetricType::Gauge)
700    }
701
702    fn register_impl(name: &'static str, help: String, metric_type: MetricType) -> Self {
703        let me = Self {
704            inner: Arc::new(CounterRegistryInner {
705                map: Default::default(),
706                name,
707                help,
708                metric_type,
709            }),
710        };
711
712        crate::registry::Registry::register(me.inner.clone());
713
714        me
715    }
716}
717
718impl<K, V> CounterRegistry<K, V>
719where
720    V: AtomicCounterEntry,
721    K: Eq + Hash + MetricLabel,
722{
723    /// Resolve an already-existing counter for the given key, or None
724    /// if there either has never been such a value, or if it was pruned.
725    pub fn get<Q: ?Sized>(&self, key: &Q) -> Option<AtomicCounter>
726    where
727        K: Borrow<Q>,
728        Q: Hash + Eq,
729    {
730        let map = self.inner.map.read();
731        map.get(key).and_then(|weak| weak.resolve())
732    }
733
734    /// Resolve an already-existing counter for the given key, creating
735    /// a new one if it didn't already exist, or was previously pruned.
736    pub fn get_or_create<'a, Q: ?Sized>(&self, key: &'a Q) -> AtomicCounter
737    where
738        K: Borrow<Q> + From<&'a Q>,
739        Q: Hash + Eq,
740    {
741        let map = self.inner.map.upgradable_read();
742        if let Some(weak) = map.get(key) {
743            if let Some(strong) = weak.resolve() {
744                return strong;
745            }
746        }
747
748        let mut map = RwLockUpgradableReadGuard::upgrade(map);
749
750        // Check again, as we may have lost a race
751        if let Some(weak) = map.get(key) {
752            if let Some(strong) = weak.resolve() {
753                return strong;
754            }
755        }
756
757        let result = AtomicCounter::new();
758        map.insert(key.into(), V::make_storable(&result));
759
760        result
761    }
762}
763
764#[cfg(test)]
765mod tests {
766    use super::*;
767
768    #[test]
769    fn split_help_single_line() {
770        let (help, doc) = split_help(" A single line of help.");
771        k9::assert_equal!(help, "A single line of help.");
772        k9::assert_equal!(doc, None);
773    }
774
775    #[test]
776    fn split_help_multi_line_first_paragraph() {
777        let (help, doc) = split_help(" First line,\n second line.");
778        k9::assert_equal!(help, "First line,\nsecond line.");
779        k9::assert_equal!(doc, None);
780        k9::assert_equal!(one_line(&help), "First line, second line.");
781    }
782
783    #[test]
784    fn split_help_with_exposition() {
785        let (help, doc) = split_help(
786            " First line,\n second line.\n\n Exposition line one.\n Exposition line two.",
787        );
788        k9::assert_equal!(help, "First line,\nsecond line.");
789        k9::assert_equal!(
790            doc,
791            Some("Exposition line one.\nExposition line two.".to_string())
792        );
793    }
794
795    #[test]
796    fn split_help_preserves_internal_blank_lines_in_doc() {
797        let (help, doc) = split_help(" Help.\n\n Para one.\n\n Para two.");
798        k9::assert_equal!(help, "Help.");
799        k9::assert_equal!(doc, Some("Para one.\n\nPara two.".to_string()));
800    }
801}