rungbot_notify/lib.rs
1//! `rungbot-notify` — getting a message to a person, shared by the `rungbot` and
2//! `rungbot-exec` binaries.
3//!
4//! Three channels, each a plain HTTPS POST:
5//!
6//! * [`email`] — the Resend HTTP API, text with an optional HTML part.
7//! * [`telegram`] — a bot `sendMessage`, plain text.
8//! * [`webhook`] — a JSON POST to any URL.
9//!
10//! [`Notifier`] is the config block that names them, deserializable from YAML. Secrets
11//! are never part of it: the config names the **environment variable** that holds a
12//! token, so a config file stays safe to paste into an issue, and no `Debug` output or
13//! error message in this crate carries a token.
14//!
15//! [`signal_notices`] is the dedupe that decides which ladder signals are worth a mail.
16//!
17//! Every send honours `RUNGBOT_OFFLINE=1`: the request is built, then refused before it
18//! leaves the process. That is what lets tests assert the exact bytes of a request
19//! without ever sending one.
20//!
21//! This crate holds no venue key and signs nothing. A failed send is a value, never a
22//! panic: a notification that cannot go out must not take the run down with it.
23
24#![forbid(unsafe_code)]
25#![deny(clippy::all)]
26
27use std::fmt;
28
29pub mod config;
30pub mod email;
31#[cfg(test)]
32mod golden_tests;
33pub mod http;
34pub mod pyjson;
35pub mod signal_notices;
36pub mod telegram;
37#[cfg(test)]
38mod testenv;
39pub mod webhook;
40
41pub use config::{Delivery, Notifier};
42pub use email::{EmailConfig, EmailMessage};
43pub use http::{HttpRequest, HttpResponse};
44pub use telegram::TelegramConfig;
45pub use webhook::WebhookConfig;
46
47/// The User-Agent every request sends unless its channel config names another.
48pub const USER_AGENT: &str = concat!(
49 "rungbot/",
50 env!("CARGO_PKG_VERSION"),
51 " (+https://github.com/renezander030/rungbot)"
52);
53
54/// The switch that keeps tests and dry runs from reaching the network.
55pub const OFFLINE_ENV: &str = "RUNGBOT_OFFLINE";
56
57/// True when `RUNGBOT_OFFLINE=1`, the project-wide convention.
58pub fn offline() -> bool {
59 std::env::var(OFFLINE_ENV).as_deref() == Ok("1")
60}
61
62#[derive(Debug, Clone, PartialEq)]
63pub enum NotifyError {
64 /// `RUNGBOT_OFFLINE=1` refused the send.
65 Offline(String),
66 /// The request went out and failed, or could not go out.
67 Failed(String),
68 /// The channel cannot send as configured (no token, no key, no text).
69 Misconfigured(String),
70}
71
72impl fmt::Display for NotifyError {
73 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
74 match self {
75 NotifyError::Offline(m) | NotifyError::Failed(m) | NotifyError::Misconfigured(m) => {
76 write!(f, "{m}")
77 }
78 }
79 }
80}
81
82impl std::error::Error for NotifyError {}
83
84/// JSON-encode one string the way `serde_json` does (UTF-8 kept as is).
85pub fn json_escape(s: &str) -> String {
86 serde_json::to_string(s).unwrap_or_else(|_| "\"\"".into())
87}