add shared forge-client crate; hive-forge and hive-forge-notify use it
This commit is contained in:
parent
687683a4f0
commit
e59e41ec90
4 changed files with 502 additions and 214 deletions
30
forge-client/Cargo.toml
Normal file
30
forge-client/Cargo.toml
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
# `forge-client` — the one place hyperhive builds a Forgejo client and
|
||||
# parses a Forgejo notification. Shared by `hive-forge` (blocking CLI) and
|
||||
# `hive-forge-notify` (async poller) so that forgejo-api schema drift is
|
||||
# handled once.
|
||||
[package]
|
||||
name = "forge-client"
|
||||
edition.workspace = true
|
||||
version.workspace = true
|
||||
readme = "README.md"
|
||||
|
||||
[lints]
|
||||
workspace = true
|
||||
|
||||
[features]
|
||||
# The blocking `forgejo_api::sync` client and the blocking raw reqwest
|
||||
# client. Only the CLI wants these.
|
||||
sync = ["forgejo-api/sync", "reqwest/blocking"]
|
||||
|
||||
[dependencies]
|
||||
forgejo-api.workspace = true
|
||||
reqwest.workspace = true
|
||||
serde.workspace = true
|
||||
serde_json.workspace = true
|
||||
time.workspace = true
|
||||
tokio = { workspace = true, features = ["time"] }
|
||||
url.workspace = true
|
||||
|
||||
[dev-dependencies]
|
||||
serde_json.workspace = true
|
||||
tokio = { workspace = true, features = ["test-util", "macros", "rt"] }
|
||||
26
forge-client/README.md
Normal file
26
forge-client/README.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
# forge-client
|
||||
|
||||
The one place hyperhive builds a Forgejo client and reads a Forgejo
|
||||
notification. `hive-forge` (the blocking CLI) and `hive-forge-notify` (the
|
||||
async poller) share it, so a Forgejo schema change that `forgejo-api` does not
|
||||
yet model is fixed here once.
|
||||
|
||||
## When to use it
|
||||
|
||||
- Building a `forgejo_api` client from a base URL and a token: `async_client`,
|
||||
and with the `sync` feature `sync_client`.
|
||||
- Building the raw `reqwest` client for Forgejo's web-router-only routes (the
|
||||
`sync` feature): `raw_blocking_client`.
|
||||
- Deciding how long a forge call may take: `TimeoutPolicy`. A caller names its
|
||||
policy (`TimeoutPolicy::CLI`, or its own value) and reads its bounds from it.
|
||||
- Parsing a notification thread from the forge: `NotificationThread`. Every
|
||||
field is optional and lenient, so an unknown or reshaped field cannot fail
|
||||
the page the way `forgejo_api::structs::NotificationThread` does.
|
||||
- Supplying the token: `TokenSource`. `StaticToken` is a fixed string; a
|
||||
caller whose token can change implements the trait and rebuilds its client
|
||||
when `current()` returns a different value.
|
||||
|
||||
## Not here
|
||||
|
||||
Anything that decides what a notification means (delivery, read-state,
|
||||
filtering): that stays in `hive-forge-notify` and `hive-forge`.
|
||||
214
forge-client/src/lib.rs
Normal file
214
forge-client/src/lib.rs
Normal file
|
|
@ -0,0 +1,214 @@
|
|||
//! Forgejo client construction, timeout policy and the drift-tolerant
|
||||
//! notification thread, shared by `hive-forge` and `hive-forge-notify`.
|
||||
//!
|
||||
//! Construction takes a base URL and a [`TokenSource`]; the bounds on how
|
||||
//! long a call may take come from a [`TimeoutPolicy`] the caller names.
|
||||
|
||||
mod notification;
|
||||
|
||||
#[cfg(feature = "sync")]
|
||||
use std::fmt;
|
||||
use std::future::Future;
|
||||
use std::time::Duration;
|
||||
|
||||
use forgejo_api::{Auth, Forgejo, ForgejoError};
|
||||
|
||||
pub use notification::{NotificationRepo, NotificationSubject, NotificationThread, parse_rfc3339};
|
||||
|
||||
/// Where a client's token comes from.
|
||||
///
|
||||
/// [`current`](TokenSource::current) is read each time a client is built. A
|
||||
/// source whose token can change (re-read from a secret store after the
|
||||
/// forge answers 401) rebuilds its client when `current()` returns a value
|
||||
/// different from the one the client was built with; building is cheap and
|
||||
/// pure, so a rebuild is a second call to [`async_client`].
|
||||
pub trait TokenSource {
|
||||
/// The token to send now.
|
||||
fn current(&self) -> String;
|
||||
}
|
||||
|
||||
/// A token that never changes.
|
||||
#[derive(Clone)]
|
||||
pub struct StaticToken(String);
|
||||
|
||||
impl StaticToken {
|
||||
#[must_use]
|
||||
pub fn new(token: impl Into<String>) -> Self {
|
||||
Self(token.into())
|
||||
}
|
||||
}
|
||||
|
||||
impl TokenSource for StaticToken {
|
||||
fn current(&self) -> String {
|
||||
self.0.clone()
|
||||
}
|
||||
}
|
||||
|
||||
/// How long a caller lets forge calls take. Each caller picks one policy and
|
||||
/// keeps it; the `forgejo_api` clients carry no timeout of their own, so a
|
||||
/// bound exists only where the caller applies it from here.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct TimeoutPolicy {
|
||||
/// Bound on reaching the forge, applied to the raw client. `None`: unbounded.
|
||||
pub connect: Option<Duration>,
|
||||
/// Whole-request budget for a small JSON call.
|
||||
pub json: Duration,
|
||||
/// Whole-request budget for a call that downloads a file body.
|
||||
pub download: Duration,
|
||||
}
|
||||
|
||||
impl TimeoutPolicy {
|
||||
/// The `hive-forge` CLI: 5 s to connect, 15 s per JSON call, 10 minutes
|
||||
/// for a download. `reqwest::blocking` has no idle timeout, so the
|
||||
/// download figure bounds the whole transfer.
|
||||
pub const CLI: Self = Self {
|
||||
connect: Some(Duration::from_secs(5)),
|
||||
json: Duration::from_secs(15),
|
||||
download: Duration::from_mins(10),
|
||||
};
|
||||
|
||||
/// A policy bounding JSON calls only (the notifier: no connect bound, no
|
||||
/// downloads).
|
||||
#[must_use]
|
||||
pub const fn json_only(json: Duration) -> Self {
|
||||
Self {
|
||||
connect: None,
|
||||
json,
|
||||
download: json,
|
||||
}
|
||||
}
|
||||
|
||||
/// Run `call`, giving up after [`json`](Self::json).
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// `Elapsed` when the budget ran out first.
|
||||
pub async fn bound_json<F: Future>(
|
||||
&self,
|
||||
call: F,
|
||||
) -> Result<F::Output, tokio::time::error::Elapsed> {
|
||||
tokio::time::timeout(self.json, call).await
|
||||
}
|
||||
}
|
||||
|
||||
/// The async typed client for the forge at `url`, sending `token`'s current
|
||||
/// value. No timeout is set on it: bound each call with
|
||||
/// [`TimeoutPolicy::bound_json`].
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// `url` is not http(s), or the token is not ASCII.
|
||||
pub fn async_client(url: url::Url, token: &impl TokenSource) -> Result<Forgejo, ForgejoError> {
|
||||
Forgejo::new(Auth::Token(&token.current()), url)
|
||||
}
|
||||
|
||||
/// The blocking typed client for the forge at `url`. No timeout is set on it.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// `url` is not http(s), or the token is not ASCII.
|
||||
#[cfg(feature = "sync")]
|
||||
pub fn sync_client(
|
||||
url: url::Url,
|
||||
token: &impl TokenSource,
|
||||
) -> Result<forgejo_api::sync::Forgejo, ForgejoError> {
|
||||
forgejo_api::sync::Forgejo::new(Auth::Token(&token.current()), url)
|
||||
}
|
||||
|
||||
/// Why [`raw_blocking_client`] failed.
|
||||
#[cfg(feature = "sync")]
|
||||
#[derive(Debug)]
|
||||
pub enum RawClientError {
|
||||
/// The token cannot be sent as a header value.
|
||||
AuthHeader(reqwest::header::InvalidHeaderValue),
|
||||
/// `reqwest` refused to build the client.
|
||||
Build(reqwest::Error),
|
||||
}
|
||||
|
||||
#[cfg(feature = "sync")]
|
||||
impl fmt::Display for RawClientError {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
match self {
|
||||
Self::AuthHeader(e) => write!(f, "auth header: {e}"),
|
||||
Self::Build(e) => write!(f, "build reqwest client: {e}"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(feature = "sync")]
|
||||
impl std::error::Error for RawClientError {
|
||||
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
|
||||
match self {
|
||||
Self::AuthHeader(e) => Some(e),
|
||||
Self::Build(e) => Some(e),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// A blocking `reqwest` client carrying the forge token and asking for JSON,
|
||||
/// with `policy.connect` as its connect timeout. For the routes Forgejo
|
||||
/// serves only through its web router, which `forgejo_api` cannot reach.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// [`RawClientError`] when the token is not a valid header value or the
|
||||
/// client cannot be built.
|
||||
#[cfg(feature = "sync")]
|
||||
pub fn raw_blocking_client(
|
||||
token: &impl TokenSource,
|
||||
policy: &TimeoutPolicy,
|
||||
) -> Result<reqwest::blocking::Client, RawClientError> {
|
||||
use reqwest::header::{ACCEPT, AUTHORIZATION, HeaderMap, HeaderValue};
|
||||
|
||||
let mut headers = HeaderMap::new();
|
||||
let mut auth = HeaderValue::from_str(&format!("token {}", token.current()))
|
||||
.map_err(RawClientError::AuthHeader)?;
|
||||
auth.set_sensitive(true);
|
||||
headers.insert(AUTHORIZATION, auth);
|
||||
headers.insert(ACCEPT, HeaderValue::from_static("application/json"));
|
||||
let mut builder = reqwest::blocking::Client::builder().default_headers(headers);
|
||||
if let Some(connect) = policy.connect {
|
||||
builder = builder.connect_timeout(connect);
|
||||
}
|
||||
builder.build().map_err(RawClientError::Build)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn cli_policy_keeps_the_hive_forge_bounds() {
|
||||
assert_eq!(TimeoutPolicy::CLI.connect, Some(Duration::from_secs(5)));
|
||||
assert_eq!(TimeoutPolicy::CLI.json, Duration::from_secs(15));
|
||||
assert_eq!(TimeoutPolicy::CLI.download, Duration::from_mins(10));
|
||||
}
|
||||
|
||||
#[tokio::test(start_paused = true)]
|
||||
async fn bound_json_gives_up_after_the_json_budget() {
|
||||
let policy = TimeoutPolicy {
|
||||
download: Duration::from_hours(1),
|
||||
..TimeoutPolicy::json_only(Duration::from_secs(10))
|
||||
};
|
||||
let slow = policy.bound_json(tokio::time::sleep(Duration::from_secs(11)));
|
||||
assert!(slow.await.is_err());
|
||||
let quick = policy.bound_json(tokio::time::sleep(Duration::from_secs(9)));
|
||||
assert!(quick.await.is_ok());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn async_client_sends_the_token_source_value_and_rejects_non_http() {
|
||||
let ok = url::Url::parse("http://forge.example/").unwrap();
|
||||
assert!(async_client(ok, &StaticToken::new("t")).is_ok());
|
||||
let bad = url::Url::parse("ftp://forge.example/").unwrap();
|
||||
assert!(async_client(bad, &StaticToken::new("t")).is_err());
|
||||
}
|
||||
|
||||
#[cfg(feature = "sync")]
|
||||
#[test]
|
||||
fn raw_client_builds_and_rejects_an_unsendable_token() {
|
||||
assert!(raw_blocking_client(&StaticToken::new("t"), &TimeoutPolicy::CLI).is_ok());
|
||||
let err = raw_blocking_client(&StaticToken::new("a\nb"), &TimeoutPolicy::CLI).unwrap_err();
|
||||
assert!(matches!(err, RawClientError::AuthHeader(_)));
|
||||
}
|
||||
}
|
||||
179
forge-client/src/notification.rs
Normal file
179
forge-client/src/notification.rs
Normal file
|
|
@ -0,0 +1,179 @@
|
|||
//! The drift-tolerant notification thread.
|
||||
//!
|
||||
//! Deliberately NOT `forgejo_api::structs::NotificationThread`: that struct
|
||||
//! lags the running Forgejo, and one reshaped field fails the whole parse, so
|
||||
//! every notification on the page is dropped. Every field here is optional
|
||||
//! and degrades to `None` on an unknown or reshaped value, so a schema change
|
||||
//! cannot break a notification call. Fields are the union of what
|
||||
//! `hive-forge` and `hive-forge-notify` read.
|
||||
|
||||
use forgejo_api::structs::NotifySubjectType;
|
||||
use serde::{Deserialize, Deserializer};
|
||||
use time::OffsetDateTime;
|
||||
use time::format_description::well_known::Rfc3339;
|
||||
|
||||
/// One notification thread.
|
||||
#[derive(Debug, Deserialize)]
|
||||
pub struct NotificationThread {
|
||||
/// Thread id as a string, whichever host sent it: Forgejo sends a JSON
|
||||
/// number, GitHub a quoted string. Only ever an opaque key.
|
||||
#[serde(default, deserialize_with = "de_opt_id")]
|
||||
pub id: Option<String>,
|
||||
#[serde(default, deserialize_with = "de_opt_rfc3339")]
|
||||
pub updated_at: Option<OffsetDateTime>,
|
||||
#[serde(default)]
|
||||
pub subject: Option<NotificationSubject>,
|
||||
#[serde(default)]
|
||||
pub repository: Option<NotificationRepo>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Deserialize)]
|
||||
pub struct NotificationSubject {
|
||||
#[serde(default)]
|
||||
pub title: Option<String>,
|
||||
/// `Pull` and GitHub's `PullRequest` both map to
|
||||
/// [`NotifySubjectType::Pull`]; an unknown type is `None`.
|
||||
#[serde(rename = "type", default, deserialize_with = "de_opt_subject_type")]
|
||||
pub r#type: Option<NotifySubjectType>,
|
||||
#[serde(default, deserialize_with = "de_opt_url")]
|
||||
pub html_url: Option<url::Url>,
|
||||
/// The API URL; ends in the issue/PR number.
|
||||
#[serde(default, deserialize_with = "de_opt_url")]
|
||||
pub url: Option<url::Url>,
|
||||
#[serde(default, deserialize_with = "de_opt_url")]
|
||||
pub latest_comment_url: Option<url::Url>,
|
||||
#[serde(default, deserialize_with = "de_opt_url")]
|
||||
pub latest_comment_html_url: Option<url::Url>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Deserialize)]
|
||||
pub struct NotificationRepo {
|
||||
#[serde(default)]
|
||||
pub full_name: Option<String>,
|
||||
}
|
||||
|
||||
/// Parse an RFC 3339 timestamp as Forgejo emits them (`+02:00` or `Z`,
|
||||
/// optionally with fractional seconds). `None` on any shape `time` does not
|
||||
/// recognise.
|
||||
#[must_use]
|
||||
pub fn parse_rfc3339(s: &str) -> Option<OffsetDateTime> {
|
||||
OffsetDateTime::parse(s, &Rfc3339).ok()
|
||||
}
|
||||
|
||||
fn de_opt_subject_type<'de, D>(d: D) -> Result<Option<NotifySubjectType>, D::Error>
|
||||
where
|
||||
D: Deserializer<'de>,
|
||||
{
|
||||
Ok(
|
||||
Option::<String>::deserialize(d)?.and_then(|s| match s.as_str() {
|
||||
"Pull" | "PullRequest" => Some(NotifySubjectType::Pull),
|
||||
"Issue" => Some(NotifySubjectType::Issue),
|
||||
"Commit" => Some(NotifySubjectType::Commit),
|
||||
"Repository" => Some(NotifySubjectType::Repository),
|
||||
_ => None,
|
||||
}),
|
||||
)
|
||||
}
|
||||
|
||||
/// A JSON number or a non-empty JSON string, as a `String`; anything else is
|
||||
/// `None`.
|
||||
fn de_opt_id<'de, D>(d: D) -> Result<Option<String>, D::Error>
|
||||
where
|
||||
D: Deserializer<'de>,
|
||||
{
|
||||
Ok(match Option::<serde_json::Value>::deserialize(d)? {
|
||||
Some(serde_json::Value::String(s)) if !s.is_empty() => Some(s),
|
||||
Some(serde_json::Value::Number(n)) => Some(n.to_string()),
|
||||
_ => None,
|
||||
})
|
||||
}
|
||||
|
||||
/// A blank or unparseable URL is `None` (Forgejo marshals empty strings for
|
||||
/// absent URLs).
|
||||
fn de_opt_url<'de, D>(d: D) -> Result<Option<url::Url>, D::Error>
|
||||
where
|
||||
D: Deserializer<'de>,
|
||||
{
|
||||
Ok(Option::<String>::deserialize(d)?
|
||||
.filter(|s| !s.is_empty())
|
||||
.and_then(|s| url::Url::parse(&s).ok()))
|
||||
}
|
||||
|
||||
fn de_opt_rfc3339<'de, D>(d: D) -> Result<Option<OffsetDateTime>, D::Error>
|
||||
where
|
||||
D: Deserializer<'de>,
|
||||
{
|
||||
Ok(Option::<String>::deserialize(d)?
|
||||
.as_deref()
|
||||
.and_then(parse_rfc3339))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use serde_json::json;
|
||||
|
||||
#[test]
|
||||
fn full_payload_parses_every_field() {
|
||||
let t: NotificationThread = serde_json::from_value(json!({
|
||||
"id": 42,
|
||||
"updated_at": "2026-06-13T11:18:42+02:00",
|
||||
"subject": {
|
||||
"title": "t",
|
||||
"type": "Pull",
|
||||
"html_url": "http://f/o/r/pulls/7",
|
||||
"url": "http://f/api/v1/repos/o/r/pulls/7",
|
||||
"latest_comment_url": "http://f/api/v1/repos/o/r/issues/comments/1",
|
||||
"latest_comment_html_url": "http://f/o/r/pulls/7/files",
|
||||
},
|
||||
"repository": { "full_name": "o/r" },
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(t.id.as_deref(), Some("42"));
|
||||
assert!(t.updated_at.is_some());
|
||||
let s = t.subject.unwrap();
|
||||
assert_eq!(s.r#type, Some(NotifySubjectType::Pull));
|
||||
assert_eq!(s.url.unwrap().path(), "/api/v1/repos/o/r/pulls/7");
|
||||
assert!(s.latest_comment_html_url.is_some());
|
||||
assert_eq!(t.repository.unwrap().full_name.as_deref(), Some("o/r"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn drifted_payload_still_parses_with_the_fields_it_can() {
|
||||
// Reshaped values the struct tolerates: blank or malformed URLs, nulls, a new
|
||||
// subject type, unparseable timestamp, extra keys, GitHub-style string id.
|
||||
let t: NotificationThread = serde_json::from_value(json!({
|
||||
"id": "abc",
|
||||
"updated_at": "yesterday",
|
||||
"unread": "maybe",
|
||||
"subject": {
|
||||
"title": null,
|
||||
"type": "Discussion",
|
||||
"state": "merged",
|
||||
"url": "",
|
||||
"html_url": "not a url",
|
||||
"latest_comment_url": null,
|
||||
},
|
||||
"repository": { "full_name": null, "new_field": {} },
|
||||
"new_top_level": [1, 2],
|
||||
}))
|
||||
.unwrap();
|
||||
assert_eq!(t.id.as_deref(), Some("abc"));
|
||||
assert!(t.updated_at.is_none());
|
||||
let s = t.subject.unwrap();
|
||||
assert!(s.r#type.is_none() && s.url.is_none() && s.html_url.is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn empty_object_parses() {
|
||||
let t: NotificationThread = serde_json::from_value(json!({})).unwrap();
|
||||
assert!(t.id.is_none() && t.subject.is_none() && t.repository.is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn github_pull_request_type_maps_to_pull() {
|
||||
let s: NotificationSubject =
|
||||
serde_json::from_value(json!({ "type": "PullRequest" })).unwrap();
|
||||
assert_eq!(s.r#type, Some(NotifySubjectType::Pull));
|
||||
}
|
||||
}
|
||||
Loading…
Reference in a new issue