pesto/lib.rs
1//! Public API of `pesto`, intended for integration with `upapasta`, `penne`
2//! and `sugo`.
3//!
4//! `pesto` is a fast, lean Usenet poster: it yEnc-encodes files, posts the
5//! resulting articles over NNTP and emits an `.nzb` file. See ROADMAP.md for
6//! the development plan.
7//!
8//! # Embedding
9//!
10//! The minimal surface for embedding callers is [`post`]: pass a resolved
11//! [`config::Config`] and the list of [`walk::InputFile`]s; get back a
12//! [`poster::PostOutcome`]. Progress events are delivered on the
13//! [`progress::ProgressReceiver`] returned alongside the outcome; drop it to
14//! silence reporting.
15//!
16//! ```ignore
17//! # async fn example() -> anyhow::Result<()> {
18//! use pesto::{config::Config, walk::InputFile};
19//!
20//! let config = Config { /* ... */ };
21//! let files = vec![InputFile { path: "movie.mkv".into(), real_name: None }];
22//! let (outcome, _events) = pesto::post(config, files).await?;
23//! println!("posted {} segments", outcome.segments.len());
24//! # Ok(())
25//! # }
26//! ```
27//!
28//! The supported embedding surface and its compatibility tiers are documented
29//! in `docs/pesto-embedding-api.md` in the workspace repository. Child modules
30//! that only organize an implementation are private; use the items re-exported
31//! by their domain facade (for example, [`config`] and [`yenc`]).
32
33/// Shown by `--version` and the startup banner.
34pub const DISPLAY_VERSION: &str = env!("CARGO_PKG_VERSION");
35
36pub mod article;
37pub mod cancel;
38pub mod compress;
39pub mod config;
40pub mod history;
41pub mod hooks;
42pub mod logging;
43pub mod memory;
44pub mod nfo;
45pub mod nntp;
46pub mod notify;
47pub mod nzb;
48pub use parmesan as par2;
49pub mod poster;
50pub mod progress;
51pub mod resume;
52pub mod spool;
53pub mod ui;
54pub mod update;
55pub mod upload;
56pub mod walk;
57pub mod yenc;
58
59/// Post `files` to Usenet using `config` and return the outcome together with
60/// a [`progress::ProgressReceiver`] the caller can drain for live updates.
61///
62/// Dropping the receiver is safe: the poster continues unimpeded.
63pub async fn post(
64 config: config::Config,
65 files: Vec<walk::InputFile>,
66) -> anyhow::Result<(poster::PostOutcome, progress::ProgressReceiver)> {
67 let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
68 let flag = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
69 cancel::spawn_listener(flag.clone());
70 let outcome = poster::post_files_with_progress_and_cancel(
71 &config,
72 &files,
73 Some(tx),
74 None,
75 Some(flag),
76 None,
77 )
78 .await?;
79 Ok((outcome, rx))
80}
81
82/// Like [`post`] but accepts an external cancel flag.
83///
84/// Set `cancel` to `true` at any point to abort the upload at the next segment
85/// boundary. The outcome returned reflects the partial run (cancelled flag is
86/// available on [`poster::PostOutcome`]).
87pub async fn post_cancelable(
88 config: config::Config,
89 files: Vec<walk::InputFile>,
90 cancel: std::sync::Arc<std::sync::atomic::AtomicBool>,
91) -> anyhow::Result<(poster::PostOutcome, progress::ProgressReceiver)> {
92 let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
93 let outcome = poster::post_files_with_progress_and_cancel(
94 &config,
95 &files,
96 Some(tx),
97 None,
98 Some(cancel),
99 None,
100 )
101 .await?;
102 Ok((outcome, rx))
103}
104
105/// Like [`post_cancelable`] but also accepts an external pause flag.
106///
107/// Set `pause` to `true` at any point to suspend every posting worker at the
108/// next segment-batch boundary — connections are kept open (and kept alive)
109/// rather than torn down, so setting it back to `false` resumes immediately
110/// without paying a reconnect. Only the posting phase is pausable; PAR2
111/// generation, compression and the final check/repost passes run to
112/// completion regardless — the same phase scoping `cancel` already has.
113pub async fn post_pausable(
114 config: config::Config,
115 files: Vec<walk::InputFile>,
116 cancel: Option<std::sync::Arc<std::sync::atomic::AtomicBool>>,
117 pause: std::sync::Arc<std::sync::atomic::AtomicBool>,
118) -> anyhow::Result<(poster::PostOutcome, progress::ProgressReceiver)> {
119 let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
120 let outcome = poster::post_files_inner(
121 &config,
122 &files,
123 Some(tx),
124 None,
125 cancel,
126 None,
127 None,
128 Some(pause),
129 )
130 .await?;
131 Ok((outcome, rx))
132}