phrona-api 0.3.0

REST API for the phrona library: search, suggestions, AI grounding, Tavily-compatible endpoint
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

//! Page extraction and engine-test endpoints.

use std::sync::Arc;

use axum::Json;
use axum::extract::State;
use axum::response::IntoResponse;
use serde::Deserialize;
use serde_json::{Value, json};

use phrona::models::Category;

use crate::{AppError, AppResult, AppState, HeaderAuth, JsonBody, JsonQuery};

/// GET /v1/extract?url=...&max_chars=...&query=... - readable-text
/// extraction of a page (the same feature as `phrona extract`). Auth is
/// header-only: query-string credentials are rejected.
#[derive(Deserialize)]
pub struct ExtractGetParams {
    url: String,
    #[serde(default)]
    max_chars: Option<usize>,
    #[serde(default)]
    query: Option<String>,
}

/// POST /v1/extract - same feature, credentials via headers or body.
#[derive(Deserialize)]
pub struct ExtractPostParams {
    url: String,
    #[serde(default)]
    max_chars: Option<usize>,
    #[serde(default)]
    query: Option<String>,
    #[serde(default)]
    api_key: Option<String>,
}

/// GET /v1/test?query=...&category=...&max_results=... - availability probe
/// across every category (the same feature as `phrona test`).
#[derive(Deserialize)]
pub struct TestParams {
    #[serde(default)]
    query: Option<String>,
    #[serde(default)]
    category: Option<String>,
    #[serde(default)]
    max_results: Option<usize>,
}

/// `GET /v1/extract?url=...`: header-auth variant of the page extraction
/// endpoint.
pub async fn extract_get(
    State(state): State<Arc<AppState>>,
    auth: HeaderAuth,
    JsonQuery(p): JsonQuery<ExtractGetParams>,
) -> AppResult<impl IntoResponse> {
    if !state.authorized(auth.key()) {
        return Err(AppError::unauthorized());
    }
    run_extract(&state, &p.url, p.max_chars, p.query.as_deref()).await
}

/// `POST /v1/extract`: body variant of the page extraction endpoint.
pub async fn extract_post(
    State(state): State<Arc<AppState>>,
    headers: axum::http::HeaderMap,
    JsonBody(p): JsonBody<ExtractPostParams>,
) -> AppResult<impl IntoResponse> {
    if !state.authorized(crate::auth_key(&headers, p.api_key.as_deref()).as_deref()) {
        return Err(AppError::unauthorized());
    }
    run_extract(&state, &p.url, p.max_chars, p.query.as_deref()).await
}

async fn run_extract(
    state: &AppState,
    url: &str,
    max_chars: Option<usize>,
    query: Option<&str>,
) -> AppResult<Json<phrona::ExtractedPage>> {
    let max_chars = max_chars.unwrap_or(5000).clamp(1, 100_000);
    let page = phrona::extract(state.client.http(), url, max_chars, query).await?;
    Ok(Json(page))
}

/// `GET /v1/test`: probe engine availability across every category (or a
/// single one) and return a per-category/per-engine report.
pub async fn test(
    State(state): State<Arc<AppState>>,
    auth: HeaderAuth,
    JsonQuery(p): JsonQuery<TestParams>,
) -> AppResult<Json<Value>> {
    if !state.authorized(auth.key()) {
        return Err(AppError::unauthorized());
    }
    let cats: Vec<Category> = match p.category.as_deref() {
        Some(c) => vec![c.parse::<Category>().map_err(|_| {
            AppError::bad_request(format!(
                "invalid category, expected one of: {}",
                Category::list_str()
            ))
        })?],
        None => Category::ALL.to_vec(),
    };
    let query = p.query.unwrap_or_else(|| "rust programming".to_string());
    let max_results = p.max_results.unwrap_or(5).clamp(1, 10);

    // categories probe concurrently: sequential probing stacks 8
    // per-category deadlines into a minute-plus response (`join_all`
    // preserves input order, so the report stays stable)
    let client = &state.client;
    let probes = cats.into_iter().map(|cat| {
        let mut opts = phrona::SearchOptions::new(query.clone());
        opts.category = cat;
        opts.max_results = max_results;
        // availability probing must observe every engine, not stop at the
        // first ones that fill max_results
        opts.probe_all = true;
        async move {
            match client.search(opts).await {
                Ok(resp) => json!({
                    "category": cat.as_str(),
                    "total": resp.total,
                    "elapsed_ms": resp.elapsed_ms,
                    "answer": resp.answer,
                    "engines": resp.engines,
                }),
                Err(e) => json!({
                    "category": cat.as_str(),
                    "total": 0,
                    "elapsed_ms": 0,
                    "answer": null,
                    "engines": [],
                    "error": e.to_string(),
                }),
            }
        }
    });
    let out: Vec<Value> = futures::future::join_all(probes).await;
    Ok(Json(Value::Array(out)))
}