Skip to main content

interloper_server/
lib.rs

1//! HTTP API over interloper.
2//!
3//! | route | |
4//! |---|---|
5//! | `GET /health` | liveness, no auth, not rate limited |
6//! | `GET /v1/providers` | measured health matrix |
7//! | `DELETE /v1/providers/{name}/quarantine` | return a quarantined provider to routing |
8//! | `POST /v1/inboxes` | issue an address |
9//! | `GET /v1/inboxes/{addr}/messages` | list |
10//! | `GET /v1/inboxes/{addr}/messages/{id}` | read one, with its OTP |
11//! | `DELETE /v1/inboxes/{addr}/messages/{id}` | delete |
12//! | `GET /v1/inboxes/{addr}/wait` | long-poll for the next (matching) message |
13//! | `GET /v1/inboxes/{addr}/events` | Server-Sent Events: every message as it lands |
14//! | `POST/GET /v1/webhooks`, `DELETE /v1/webhooks/{id}` | one-shot outbound webhooks |
15//!
16//! Every response is `{"success", "data", "error"}`. Auth is `X-API-Key`.
17//! With a Postgres URL, instances share addresses and health: see [`fleet`].
18
19pub 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
55/// The one response shape. `success` is derived from `error`, so a body can
56/// never claim success while carrying one.
57pub 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
65/// The one shape a message takes on the wire: `.../messages/{id}`, `wait`,
66/// SSE and webhook payloads alike.
67pub 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        // Constant-time against every configured key, so timing cannot
111        // recover a key byte by byte.
112        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            // Routable by this instance's own measurements, but taken out by
169            // a majority of its peers (fleet mode only).
170            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    // `state` is deliberately absent: a provider credential the server holds
227    // so the client never has to.
228    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            // Bounded: a caller-supplied regex must not be able to build an
277            // enormous automaton on the server.
278            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
310/// Every message as it lands, as Server-Sent Events. Long-poll `wait`
311/// answers one message per request; this holds one connection for a stream.
312async 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    // Resolve first, so an address this server never issued fails now with a
346    // 404 rather than later as a silent timeout.
347    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    // The one place a raw error reaches a client: it is about the caller's
353    // own URL, which they already have.
354    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
415/// Run the server until Ctrl-C/SIGTERM. Refuses to start without API keys.
416pub 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        // A silent fall back to memory while an operator believes state is
422        // durable would be invisible until reads start missing.
423        (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    // Never fatal: a database blip leaves this instance routing on its own
464    // measurements until the next round succeeds.
465    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    // Measurements taken while serving are worth keeping; a read-only disk
492    // must not fail shutdown.
493    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;