use async_trait::async_trait;
use chrono::{DateTime, Utc};
use std::fmt;
use std::str::FromStr;
use thiserror::Error;
use url::Url;
use super::task_repository::RepositoryError;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum SearxngInstanceSource {
SearxSpace,
Seed,
}
impl SearxngInstanceSource {
pub fn as_str(&self) -> &'static str {
match self {
SearxngInstanceSource::SearxSpace => "searx_space",
SearxngInstanceSource::Seed => "seed",
}
}
}
impl fmt::Display for SearxngInstanceSource {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
impl FromStr for SearxngInstanceSource {
type Err = InstanceUrlError;
fn from_str(value: &str) -> Result<Self, Self::Err> {
match value {
"searx_space" => Ok(SearxngInstanceSource::SearxSpace),
"seed" => Ok(SearxngInstanceSource::Seed),
other => Err(InstanceUrlError::UnknownVariant(format!(
"unknown instance source: {other}"
))),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum SearxngInstanceState {
Candidate,
Active,
Cooldown,
Retired,
}
impl SearxngInstanceState {
pub fn as_str(&self) -> &'static str {
match self {
SearxngInstanceState::Candidate => "candidate",
SearxngInstanceState::Active => "active",
SearxngInstanceState::Cooldown => "cooldown",
SearxngInstanceState::Retired => "retired",
}
}
pub fn can_transition_to(&self, to: SearxngInstanceState) -> bool {
use SearxngInstanceState::*;
if *self == to {
return true;
}
matches!(
(self, to),
(Candidate, Active)
| (Candidate, Cooldown)
| (Candidate, Retired)
| (Active, Cooldown)
| (Cooldown, Active)
| (Cooldown, Retired)
| (Retired, Active)
)
}
}
impl fmt::Display for SearxngInstanceState {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
impl FromStr for SearxngInstanceState {
type Err = InstanceUrlError;
fn from_str(value: &str) -> Result<Self, Self::Err> {
match value {
"candidate" => Ok(SearxngInstanceState::Candidate),
"active" => Ok(SearxngInstanceState::Active),
"cooldown" => Ok(SearxngInstanceState::Cooldown),
"retired" => Ok(SearxngInstanceState::Retired),
other => Err(InstanceUrlError::UnknownVariant(format!(
"unknown instance state: {other}"
))),
}
}
}
#[derive(Debug, Error, PartialEq, Eq)]
pub enum InstanceUrlError {
#[error("invalid instance url: {0}")]
Invalid(String),
#[error("unsafe instance url (internal address): {0}")]
Unsafe(String),
#[error("unknown variant: {0}")]
UnknownVariant(String),
}
pub fn normalize_instance_url(raw: &str) -> Result<String, InstanceUrlError> {
let trimmed = raw.trim();
if trimmed.is_empty() {
return Err(InstanceUrlError::Invalid("empty url".to_string()));
}
let mut parsed =
Url::parse(trimmed).map_err(|e| InstanceUrlError::Invalid(format!("{trimmed}: {e}")))?;
match parsed.scheme() {
"http" => {
parsed.set_scheme("https").map_err(|_| {
InstanceUrlError::Invalid(format!("{trimmed}: cannot upgrade to https"))
})?;
}
"https" => {}
other => {
return Err(InstanceUrlError::Invalid(format!(
"{trimmed}: unsupported scheme {other}"
)));
}
}
let host = parsed
.host_str()
.ok_or_else(|| InstanceUrlError::Invalid(format!("{trimmed}: missing host")))?;
if host.is_empty() {
return Err(InstanceUrlError::Invalid(format!(
"{trimmed}: missing host"
)));
}
parsed
.set_host(Some(&host.to_ascii_lowercase()))
.map_err(|_| InstanceUrlError::Invalid(format!("{trimmed}: host cannot be normalized")))?;
let normalized = parsed.as_str().trim_end_matches('/').to_string();
if normalized.is_empty() {
return Err(InstanceUrlError::Invalid(format!(
"{trimmed}: empty after normalize"
)));
}
if crate::infrastructure::security::ssrf::is_internal_url(&normalized) {
return Err(InstanceUrlError::Unsafe(normalized));
}
Ok(normalized)
}
#[derive(Debug, Clone, PartialEq)]
pub struct SearxngInstance {
pub url: String,
pub source: SearxngInstanceSource,
pub state: SearxngInstanceState,
pub network_type: Option<String>,
pub version: Option<String>,
pub api_grade: Option<String>,
pub http_grade: Option<String>,
pub tls_grade: Option<String>,
pub cdn_grade: Option<String>,
pub uptime_day: Option<f64>,
pub uptime_month: Option<f64>,
pub latency_ms: Option<i64>,
pub consecutive_failures: i32,
pub last_success_at: Option<DateTime<Utc>>,
pub last_failure_at: Option<DateTime<Utc>>,
pub last_error: Option<String>,
pub dataset_miss_count: i32,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
impl SearxngInstance {
pub fn new(
url: impl Into<String>,
source: SearxngInstanceSource,
state: SearxngInstanceState,
) -> Self {
Self {
url: url.into(),
source,
state,
network_type: None,
version: None,
api_grade: None,
http_grade: None,
tls_grade: None,
cdn_grade: None,
uptime_day: None,
uptime_month: None,
latency_ms: None,
consecutive_failures: 0,
last_success_at: None,
last_failure_at: None,
last_error: None,
dataset_miss_count: 0,
created_at: DateTime::<Utc>::default(),
updated_at: DateTime::<Utc>::default(),
}
}
pub fn breaker_key(&self) -> String {
format!("searxng:{}", self.url)
}
}
#[derive(Debug, Clone, PartialEq, Default)]
pub struct AdmittedInstance {
pub url: String,
pub network_type: Option<String>,
pub version: Option<String>,
pub api_grade: Option<String>,
pub http_grade: Option<String>,
pub tls_grade: Option<String>,
pub cdn_grade: Option<String>,
pub uptime_day: Option<f64>,
pub uptime_month: Option<f64>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum UpsertOutcome {
Inserted,
Updated,
}
#[async_trait]
pub trait CollectLockGuard: Send + Sync {
async fn release(&self) -> Result<(), RepositoryError>;
}
#[async_trait]
pub trait SearxngInstanceRepository: Send + Sync {
async fn try_acquire_collect_lock(
&self,
key: i64,
) -> Result<Option<Box<dyn CollectLockGuard>>, RepositoryError>;
async fn upsert_from_dataset(
&self,
instance: &AdmittedInstance,
) -> Result<UpsertOutcome, RepositoryError>;
async fn upsert_seed(&self, url: &str) -> Result<UpsertOutcome, RepositoryError>;
async fn list_candidates(&self, limit: u64) -> Result<Vec<SearxngInstance>, RepositoryError>;
async fn list_by_state(
&self,
state: SearxngInstanceState,
limit: u64,
) -> Result<Vec<SearxngInstance>, RepositoryError>;
async fn list_paginated(
&self,
limit: u64,
offset: u64,
) -> Result<Vec<SearxngInstance>, RepositoryError>;
async fn record_probe_result(
&self,
url: &str,
ok: bool,
latency_ms: Option<i64>,
error: Option<&str>,
) -> Result<(), RepositoryError>;
async fn transition_state(
&self,
url: &str,
to: SearxngInstanceState,
) -> Result<(), RepositoryError>;
async fn record_dataset_miss(
&self,
url: &str,
retire_after: i32,
) -> Result<bool, RepositoryError>;
async fn get_by_url(&self, url: &str) -> Result<Option<SearxngInstance>, RepositoryError>;
async fn count_by_state(&self, state: SearxngInstanceState) -> Result<u64, RepositoryError>;
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_state_display_from_str_roundtrip() {
for state in [
SearxngInstanceState::Candidate,
SearxngInstanceState::Active,
SearxngInstanceState::Cooldown,
SearxngInstanceState::Retired,
] {
let text = state.to_string();
let back: SearxngInstanceState = text.parse().expect("state roundtrip");
assert_eq!(back, state, "roundtrip failed for {text}");
}
}
#[test]
fn test_state_as_str_canonical() {
assert_eq!(SearxngInstanceState::Candidate.as_str(), "candidate");
assert_eq!(SearxngInstanceState::Active.as_str(), "active");
assert_eq!(SearxngInstanceState::Cooldown.as_str(), "cooldown");
assert_eq!(SearxngInstanceState::Retired.as_str(), "retired");
}
#[test]
fn test_state_from_str_rejects_unknown() {
assert!(SearxngInstanceState::from_str("zombie").is_err());
}
#[test]
fn test_source_roundtrip() {
for source in [
SearxngInstanceSource::SearxSpace,
SearxngInstanceSource::Seed,
] {
let back: SearxngInstanceSource = source.to_string().parse().expect("source roundtrip");
assert_eq!(back, source);
}
assert!(SearxngInstanceSource::from_str("manual").is_err());
}
#[test]
fn test_legal_transitions() {
use SearxngInstanceState::*;
let legal = [
(Candidate, Active),
(Candidate, Cooldown),
(Candidate, Retired),
(Active, Cooldown),
(Cooldown, Active),
(Cooldown, Retired),
(Retired, Active),
(Candidate, Candidate),
(Active, Active),
(Cooldown, Cooldown),
(Retired, Retired),
];
for (from, to) in legal {
assert!(from.can_transition_to(to), "{from} -> {to} should be legal");
}
}
#[test]
fn test_illegal_transitions() {
use SearxngInstanceState::*;
let illegal = [
(Retired, Candidate),
(Active, Candidate),
(Active, Retired),
(Retired, Cooldown),
];
for (from, to) in illegal {
assert!(
!from.can_transition_to(to),
"{from} -> {to} should be illegal"
);
}
}
#[test]
fn test_normalize_upgrades_http_and_lowercases_host() {
assert_eq!(
normalize_instance_url("HTTP://Example.com/").expect("normalize"),
"https://example.com"
);
}
#[test]
fn test_normalize_strips_trailing_slash() {
assert_eq!(
normalize_instance_url("https://searx.example.org/").expect("normalize"),
"https://searx.example.org"
);
}
#[test]
fn test_normalize_keeps_path_but_strips_trailing_slash() {
assert_eq!(
normalize_instance_url("https://EXAMPLE.com/searx/").expect("normalize"),
"https://example.com/searx"
);
}
#[test]
fn test_normalize_keeps_port() {
assert_eq!(
normalize_instance_url("http://Search.Example.org:8080").expect("normalize"),
"https://search.example.org:8080"
);
}
#[test]
fn test_normalize_rejects_internal_address() {
let err = normalize_instance_url("http://127.0.0.1:8080/").expect_err("loopback rejected");
assert!(matches!(err, InstanceUrlError::Unsafe(_)), "got: {err:?}");
}
#[test]
fn test_normalize_rejects_private_hostname() {
let err = normalize_instance_url("https://localhost:8888").expect_err("localhost rejected");
assert!(matches!(err, InstanceUrlError::Unsafe(_)), "got: {err:?}");
}
#[test]
fn test_normalize_rejects_non_http_scheme() {
let err = normalize_instance_url("ftp://example.com").expect_err("ftp rejected");
assert!(matches!(err, InstanceUrlError::Invalid(_)), "got: {err:?}");
}
#[test]
fn test_normalize_rejects_garbage_and_empty() {
assert!(normalize_instance_url("not-a-url").is_err());
assert!(normalize_instance_url(" ").is_err());
assert!(normalize_instance_url("https://").is_err());
}
#[test]
fn test_enum_from_str_uses_unknown_variant_error() {
use std::str::FromStr;
let state_err = SearxngInstanceState::from_str("bogus").expect_err("unknown state");
assert!(
matches!(state_err, InstanceUrlError::UnknownVariant(_)),
"got: {state_err:?}"
);
let source_err = SearxngInstanceSource::from_str("bogus").expect_err("unknown source");
assert!(
matches!(source_err, InstanceUrlError::UnknownVariant(_)),
"got: {source_err:?}"
);
assert_eq!(
state_err.to_string(),
"unknown variant: unknown instance state: bogus"
);
}
#[test]
fn test_breaker_key_prefixes_url() {
let instance = SearxngInstance::new(
"https://searx.example.org",
SearxngInstanceSource::Seed,
SearxngInstanceState::Candidate,
);
assert_eq!(instance.breaker_key(), "searxng:https://searx.example.org");
}
}