1pub mod config;
20pub mod error;
21pub mod fleet;
22pub mod ratelimit;
23pub mod service;
24pub mod store;
25pub mod webhooks;
26
27use std::convert::Infallible;
28use std::net::SocketAddr;
29use std::sync::Arc;
30use std::time::Duration;
31
32use axum::extract::{ConnectInfo, Path, Query, Request as HttpRequest, State};
33use axum::http::{HeaderValue, Method};
34use axum::middleware::{self, Next};
35use axum::response::sse::{Event, KeepAlive, Sse};
36use axum::response::{IntoResponse, Response};
37use axum::routing::{delete, get, post};
38use axum::{Json, Router};
39use futures::StreamExt;
40use interloper::health::Status;
41use interloper::regex::Regex;
42use interloper::{Interloper, Kind, MailFilter, Message, Request};
43use serde::Deserialize;
44use serde_json::{Value, json};
45use subtle::ConstantTimeEq;
46use tower_http::cors::{AllowOrigin, CorsLayer};
47
48use crate::config::Config;
49use crate::error::ApiError;
50use crate::ratelimit::Limiter;
51use crate::service::Service;
52use crate::store::Store;
53use crate::webhooks::Webhooks;
54
55pub fn envelope(data: Value) -> Value {
58 json!({"success": true, "data": data, "error": null})
59}
60
61pub fn envelope_err(msg: &str) -> Value {
62 json!({"success": false, "data": null, "error": msg})
63}
64
65pub fn message_json(m: &Message, otp: Option<&str>) -> Value {
68 json!({
69 "id": m.id,
70 "sender": m.sender,
71 "subject": m.subject,
72 "received_at": m.received_at.map(|t| t.to_string()),
73 "html": m.html,
74 "text": m.text,
75 "links": m.links,
76 "otp": otp,
77 })
78}
79
80pub struct AppState {
81 pub config: Config,
82 pub service: Arc<Service>,
83 pub webhooks: Arc<Webhooks>,
84 limiter: Limiter,
85}
86
87type St = State<Arc<AppState>>;
88
89impl AppState {
90 pub fn new(config: Config, il: Interloper, store: Store) -> Arc<Self> {
91 Self::from_service(config, Service::new(il, store))
92 }
93
94 pub fn from_service(config: Config, service: Arc<Service>) -> Arc<Self> {
95 let webhooks = Webhooks::new(
96 service.clone(),
97 config.webhook_allow_private,
98 config.webhook_secret.clone(),
99 );
100 let limiter = Limiter::new(config.rate_limit.0, config.rate_limit.1);
101 Arc::new(AppState {
102 config,
103 service,
104 webhooks,
105 limiter,
106 })
107 }
108
109 fn key_valid(&self, candidate: &str) -> bool {
110 let mut ok = 0u8;
113 for k in &self.config.api_keys {
114 ok |= u8::from(bool::from(candidate.as_bytes().ct_eq(k.as_bytes())));
115 }
116 ok == 1
117 }
118}
119
120async fn auth(State(s): St, req: HttpRequest, next: Next) -> Result<Response, ApiError> {
121 let key = req
122 .headers()
123 .get("x-api-key")
124 .and_then(|v| v.to_str().ok())
125 .unwrap_or("");
126 if key.is_empty() || !s.key_valid(key) {
127 return Err(ApiError::Unauthorized);
128 }
129 Ok(next.run(req).await)
130}
131
132async fn rate_limit(State(s): St, req: HttpRequest, next: Next) -> Result<Response, ApiError> {
133 let ip = req
134 .extensions()
135 .get::<ConnectInfo<SocketAddr>>()
136 .map_or_else(|| "unknown".to_string(), |c| c.0.ip().to_string());
137 let key = req
138 .headers()
139 .get("x-api-key")
140 .and_then(|v| v.to_str().ok())
141 .unwrap_or("");
142 let bucket = if !key.is_empty() && s.key_valid(key) {
143 format!("{ip}|{key}")
144 } else {
145 ip
146 };
147 if !s.limiter.allow(&bucket) {
148 return Err(ApiError::RateLimited);
149 }
150 Ok(next.run(req).await)
151}
152
153async fn health() -> Json<Value> {
154 Json(envelope(json!({"status": "ok"})))
155}
156
157async fn providers(State(s): St) -> Json<Value> {
158 let il = &s.service.il;
159 let rows: Vec<Value> = il
160 .registry()
161 .specs()
162 .map(|spec| {
163 let h = il.health();
164 let mut status = h.status(spec.name).to_string();
165 if h.status(spec.name) == Status::Down && h.tier(spec.name).is_some() {
166 status = "probation".into();
167 }
168 let fleet_down = s.service.fleet.as_ref().is_some_and(|f| {
171 h.status(spec.name) != Status::Quarantined
172 && f.view()
173 .vetoes(spec.name, h.get(spec.name).as_ref(), jiff::Timestamp::now())
174 });
175 json!({
176 "provider": spec.name,
177 "status": status,
178 "fleet_down": fleet_down,
179 "p50": h.p50(spec.name),
180 "kind": spec.caps.kind.iter().map(|k| k.as_str()).collect::<Vec<_>>(),
181 "sites": spec.caps.sites,
182 "needs_solver": spec.caps.needs_solver,
183 })
184 })
185 .collect();
186 Json(envelope(Value::Array(rows)))
187}
188
189async fn clear_quarantine(State(s): St, Path(name): Path<String>) -> Result<Json<Value>, ApiError> {
190 if !s.service.il.registry().contains(&name) {
191 return Err(ApiError::NotFound);
192 }
193 let was = s.service.clear_quarantine(&name).await?;
194 Ok(Json(envelope(json!({"cleared": was}))))
195}
196
197#[derive(Deserialize, Default)]
198#[serde(deny_unknown_fields)]
199struct CreateInbox {
200 provider: Option<String>,
201 kind: Option<Kind>,
202 local: Option<String>,
203 domain: Option<String>,
204 #[serde(default)]
205 domain_not_in: Vec<String>,
206 address_ttl_seconds: Option<u64>,
207 message_ttl_seconds: Option<u64>,
208}
209
210async fn create_inbox(
211 State(s): St,
212 body: Option<Json<CreateInbox>>,
213) -> Result<Json<Value>, ApiError> {
214 let b = body.map(|Json(b)| b).unwrap_or_default();
215 let req = Request {
216 provider: b.provider,
217 kind: b.kind,
218 local: b.local,
219 domain: b.domain,
220 domain_not_in: b.domain_not_in,
221 address_ttl: b.address_ttl_seconds.map(Duration::from_secs),
222 message_ttl: b.message_ttl_seconds.map(Duration::from_secs),
223 ..Default::default()
224 };
225 let a = s.service.create(&req).await?;
226 Ok(Json(envelope(json!({
229 "address": a.value,
230 "provider": a.provider,
231 "expires_at": a.expires_at.map(|t| t.to_string()),
232 }))))
233}
234
235async fn list_messages(State(s): St, Path(addr): Path<String>) -> Result<Json<Value>, ApiError> {
236 let rows = s.service.inbox(&addr).await?.messages().await?;
237 let data: Vec<Value> = rows
238 .iter()
239 .map(|r| {
240 json!({"id": r.id, "sender": r.sender, "subject": r.subject,
241 "received_at": r.received_at.map(|t| t.to_string()), "locked": r.locked})
242 })
243 .collect();
244 Ok(Json(envelope(Value::Array(data))))
245}
246
247async fn get_message(
248 State(s): St,
249 Path((addr, id)): Path<(String, String)>,
250) -> Result<Json<Value>, ApiError> {
251 let (m, code) = s.service.get_message(&addr, &id).await?;
252 Ok(Json(envelope(message_json(&m, code.as_deref()))))
253}
254
255async fn delete_message(
256 State(s): St,
257 Path((addr, id)): Path<(String, String)>,
258) -> Result<Json<Value>, ApiError> {
259 s.service.inbox(&addr).await?.delete(&id).await?;
260 Ok(Json(envelope(json!({"deleted": id}))))
261}
262
263#[derive(Deserialize)]
264struct WaitQuery {
265 timeout: Option<u64>,
266 #[serde(default)]
267 otp: bool,
268 pattern: Option<String>,
269 from: Option<String>,
270 subject: Option<String>,
271}
272
273fn compile(pattern: Option<&str>) -> Result<Option<Regex>, ApiError> {
274 pattern
275 .map(|p| {
276 interloper::regex::RegexBuilder::new(p)
279 .size_limit(1 << 20)
280 .build()
281 .map_err(|_| ApiError::BadRequest("invalid pattern".into()))
282 })
283 .transpose()
284}
285
286async fn wait(
287 State(s): St,
288 Path(addr): Path<String>,
289 Query(q): Query<WaitQuery>,
290) -> Result<Json<Value>, ApiError> {
291 if q.timeout == Some(0) {
292 return Err(ApiError::BadRequest("timeout must be at least 1".into()));
293 }
294 let held = s.config.clamp_wait(q.timeout);
295 let pattern = compile(q.pattern.as_deref())?;
296 let filter = MailFilter {
297 from: q.from,
298 subject: q.subject,
299 };
300 let found = s
301 .service
302 .wait(&addr, held, pattern.as_ref(), q.otp, &filter)
303 .await?;
304 Ok(Json(envelope(match found {
305 Some((m, code)) => message_json(&m, code.as_deref()),
306 None => Value::Null,
307 })))
308}
309
310async fn events(State(s): St, Path(addr): Path<String>) -> Result<impl IntoResponse, ApiError> {
313 let inbox = s.service.inbox(&addr).await?;
314 let stream = async_stream::stream! {
315 let mut mail = inbox.watch(None);
316 while let Some(m) = mail.next().await {
317 match m {
318 Ok(m) => {
319 let code = interloper::parse::extract_otp(&m.subject, &m.text, None);
320 yield Ok::<_, Infallible>(Event::default().event("message").json_data(message_json(&m, code.as_deref())).expect("json"));
321 }
322 Err(e) => {
323 let (_, msg) = error::status_for(&e);
324 yield Ok(Event::default().event("error").data(msg));
325 break;
326 }
327 }
328 }
329 };
330 Ok(Sse::new(stream).keep_alive(KeepAlive::default()))
331}
332
333#[derive(Deserialize)]
334#[serde(deny_unknown_fields)]
335struct CreateWebhook {
336 address: String,
337 url: String,
338 timeout: Option<u64>,
339}
340
341async fn create_webhook(
342 State(s): St,
343 Json(b): Json<CreateWebhook>,
344) -> Result<Json<Value>, ApiError> {
345 s.service.inbox(&b.address).await?;
348 if b.timeout == Some(0) {
349 return Err(ApiError::BadRequest("timeout must be at least 1".into()));
350 }
351 let timeout = s.config.clamp_webhook(b.timeout);
352 let id = s
355 .webhooks
356 .create(b.address.to_lowercase(), &b.url, timeout)
357 .await
358 .map_err(ApiError::BadRequest)?;
359 Ok(Json(envelope(json!({"id": id}))))
360}
361
362async fn list_webhooks(State(s): St) -> Json<Value> {
363 Json(envelope(serde_json::to_value(s.webhooks.list()).unwrap()))
364}
365
366async fn delete_webhook(State(s): St, Path(id): Path<String>) -> Json<Value> {
367 Json(envelope(json!({"cancelled": s.webhooks.cancel(&id)})))
368}
369
370async fn fallback() -> ApiError {
371 ApiError::NotFound
372}
373
374pub fn router(state: Arc<AppState>) -> Router {
375 let v1 = Router::new()
376 .route("/providers", get(providers))
377 .route("/providers/{name}/quarantine", delete(clear_quarantine))
378 .route("/inboxes", post(create_inbox))
379 .route("/inboxes/{addr}/messages", get(list_messages))
380 .route(
381 "/inboxes/{addr}/messages/{id}",
382 get(get_message).delete(delete_message),
383 )
384 .route("/inboxes/{addr}/wait", get(wait))
385 .route("/inboxes/{addr}/events", get(events))
386 .route("/webhooks", post(create_webhook).get(list_webhooks))
387 .route("/webhooks/{id}", delete(delete_webhook))
388 .route_layer(middleware::from_fn_with_state(state.clone(), auth))
389 .layer(middleware::from_fn_with_state(state.clone(), rate_limit));
390 let mut app = Router::new()
391 .route("/health", get(health))
392 .nest("/v1", v1)
393 .fallback(fallback)
394 .with_state(state.clone());
395 if !state.config.allowed_origins.is_empty() {
396 let origins: Vec<HeaderValue> = state
397 .config
398 .allowed_origins
399 .iter()
400 .filter_map(|o| o.parse().ok())
401 .collect();
402 app = app.layer(
403 CorsLayer::new()
404 .allow_origin(AllowOrigin::list(origins))
405 .allow_methods([Method::GET, Method::POST, Method::DELETE])
406 .allow_headers([
407 axum::http::header::CONTENT_TYPE,
408 "x-api-key".parse().unwrap(),
409 ]),
410 );
411 }
412 app
413}
414
415pub async fn serve(config: Config, il: Interloper) -> Result<(), String> {
417 if config.api_keys.is_empty() {
418 return Err("INTERLOPER_API_KEYS is empty; refusing to start an open server".into());
419 }
420 let store = match (&config.database_url, &config.database) {
421 (Some(url), _) => Store::postgres(url)
424 .await
425 .map_err(|e| format!("postgres database: {e}"))?,
426 (None, Some(p)) => {
427 Store::sqlite(p).map_err(|e| format!("database {}: {e}", p.display()))?
428 }
429 (None, None) => Store::memory(),
430 };
431 let fleet = match store.pg_pool() {
432 Some(pool) => {
433 let sync = fleet::HealthSync::new(
434 pool.clone(),
435 il.health().clone(),
436 config.instance_id.clone(),
437 config.health_sync_every * 3,
438 );
439 sync.load()
440 .await
441 .map_err(|e| format!("loading fleet health: {e}"))?;
442 tracing::info!(instance = %config.instance_id, "fleet mode: health shared via postgres");
443 Some(sync)
444 }
445 None => None,
446 };
447 let bind = config.bind;
448 let every = config.maintenance_every;
449 let sync_every = config.health_sync_every;
450 let state = AppState::from_service(config, Service::with_fleet(il, store, fleet.clone()));
451 let maint = state.clone();
452 let maintenance = tokio::spawn(async move {
453 loop {
454 tokio::time::sleep(every).await;
455 let _ = maint.service.il.save_health();
456 if let Ok(n) = maint.service.store.sweep().await
457 && n > 0
458 {
459 tracing::info!(reaped = n, "expired addresses swept");
460 }
461 }
462 });
463 let syncer = fleet.clone().map(|f| {
466 tokio::spawn(async move {
467 loop {
468 tokio::time::sleep(sync_every).await;
469 if let Err(e) = f.sync().await {
470 tracing::warn!(error = %e, "fleet health sync failed; routing on local health");
471 }
472 }
473 })
474 });
475 let listener = tokio::net::TcpListener::bind(bind)
476 .await
477 .map_err(|e| format!("bind {bind}: {e}"))?;
478 tracing::info!(%bind, "interloper server listening");
479 let app = router(state.clone()).into_make_service_with_connect_info::<SocketAddr>();
480 let result = axum::serve(listener, app)
481 .with_graceful_shutdown(shutdown_signal())
482 .await;
483 maintenance.abort();
484 if let Some(t) = syncer {
485 t.abort();
486 }
487 if let Some(f) = &fleet {
488 let _ = f.sync().await;
489 }
490 state.webhooks.shutdown();
491 let _ = state.service.il.save_health();
494 result.map_err(|e| e.to_string())
495}
496
497async fn shutdown_signal() {
498 let ctrl_c = async {
499 let _ = tokio::signal::ctrl_c().await;
500 };
501 #[cfg(unix)]
502 let term = async {
503 if let Ok(mut s) = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
504 {
505 s.recv().await;
506 }
507 };
508 #[cfg(not(unix))]
509 let term = std::future::pending::<()>();
510 tokio::select! { _ = ctrl_c => {}, _ = term => {} }
511}
512
513#[cfg(test)]
514mod tests;
515
516#[cfg(test)]
517mod fleet_tests;