Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
11.2 KB
Raw Blame
//! Read-only `/api/v1` client.
//!
//! Only the documented frontend endpoints are used: incremental `recent`
//! paging for the page listing (with the legacy bare-array response accepted
//! as a fallback) and single-page reads with `ETag` / `If-None-Match`
//! revalidation. No MCP, no admin routes, no writes. The bearer token is
//! only ever attached as a request header — it never reaches an error
//! message, a URL, or the state file.

use std::time::Duration;

use anyhow::{Result, anyhow, bail};
use reqwest::StatusCode;
use serde::Deserialize;
use url::Url;

pub const DEFAULT_SERVER_URL: &str = "http://127.0.0.1:49374";

/// Listing anchor: everything strictly after the epoch. `updated_since` is
/// exclusive, so no page is missed.
const EPOCH: &str = "1970-01-01T00:00:00Z";
const RECENT_LIMIT: usize = 100;
/// Bound on cursor rounds so a hostile server cannot loop the client.
const MAX_LIST_ROUNDS: usize = 1_000;
const REQUEST_TIMEOUT: Duration = Duration::from_secs(30);

/// One row of the pages listing (`PageSummary` in `docs/frontend-api.md`).
#[derive(Debug, Clone, Deserialize)]
pub struct PageSummary {
    pub path: String,
    pub title: String,
    #[serde(default)]
    pub kind: String,
    #[serde(default)]
    pub tier: String,
    #[serde(default)]
    pub updated_at: String,
}

/// The canonical single-page projection. Only the fields this tool
/// transports, or checks before an import, are decoded; everything else the
/// server returns is ignored rather than stored, and nothing is forged
/// locally.
#[derive(Debug, Clone, Deserialize)]
pub struct ApiPage {
    /// Latest version id, the token a conditional MCP write or delete
    /// passes back. Servers older than 3.0 do not send it.
    #[serde(default)]
    pub id: Option<String>,
    pub path: String,
    pub body_markdown: String,
    #[serde(default)]
    pub title: String,
    #[serde(default)]
    pub tier: String,
    #[serde(default)]
    pub pinned: bool,
    /// The page's parsed frontmatter: `tags` live here, and so does any
    /// metadata an import would clear.
    #[serde(default)]
    pub frontmatter: serde_json::Value,
}

/// Result of one page read: the body on `200`, or `None` on `304 Not
/// Modified` when the supplied `If-None-Match` still matches.
#[derive(Debug)]
pub struct PageRead {
    pub page: Option<ApiPage>,
    pub etag: Option<String>,
}

pub struct ApiClient {
    http: reqwest::Client,
    base: Url,
    token: Option<String>,
}

#[derive(Deserialize)]
struct RecentIncremental {
    pages: Vec<PageSummary>,
    next_cursor: Option<String>,
}

impl ApiClient {
    pub fn new(server_url: &str, token: Option<String>) -> Result<Self> {
        let mut base =
            Url::parse(server_url).map_err(|e| anyhow!("invalid --server {server_url:?}: {e}"))?;
        if !base.username().is_empty() || base.password().is_some() {
            bail!(
                "server URL must not embed credentials; pass the token via --token \
                 or AI_MEMORY_AUTH_TOKEN instead"
            );
        }
        if base.path() != "/" && !base.path().is_empty() {
            bail!(
                "server URL must be an origin (scheme://host[:port]); base-path \
                 deployments are not supported by this companion"
            );
        }
        if base.query().is_some() || base.fragment().is_some() {
            bail!("server URL must not carry a query or fragment");
        }
        base.set_path("");
        let http = reqwest::Client::builder()
            .timeout(REQUEST_TIMEOUT)
            .build()
            .context_build()?;
        Ok(Self { http, base, token })
    }

    fn api_url(
        &self,
        workspace: &str,
        project: &str,
        tail: &[&str],
        query: &[(&str, String)],
    ) -> Result<Url> {
        let mut url = self.base.clone();
        {
            let mut segments = url
                .path_segments_mut()
                .map_err(|_| anyhow!("server URL cannot serve as a base"))?;
            segments
                .push("api")
                .push("v1")
                .push("workspaces")
                .push(workspace)
                .push("projects")
                .push(project);
            for segment in tail {
                segments.push(segment);
            }
        }
        if !query.is_empty() {
            let mut pairs = url.query_pairs_mut();
            for (key, value) in query {
                pairs.append_pair(key, value);
            }
        }
        Ok(url)
    }

    async fn send(
        &self,
        url: &Url,
        if_none_match: Option<&str>,
        not_found_hint: &str,
    ) -> Result<reqwest::Response> {
        let mut request = self
            .http
            .get(url.clone())
            .header(reqwest::header::ACCEPT, "application/json");
        if let Some(token) = &self.token {
            request = request.bearer_auth(token);
        }
        if let Some(etag) = if_none_match {
            request = request.header(reqwest::header::IF_NONE_MATCH, etag);
        }
        let response = request
            .send()
            .await
            .map_err(|e| anyhow!("request to {} failed: {e}", url.as_str()))?;
        check_status(response, url, not_found_hint)
    }

    /// List the project's latest pages via incremental `recent` paging from
    /// the epoch. Incremental results already exclude superseded and expired
    /// pages, which is exactly the latest-only projection an export wants.
    /// A server without incremental support answers the legacy bare array;
    /// that is accepted as the full listing.
    pub async fn list_pages(&self, workspace: &str, project: &str) -> Result<Vec<PageSummary>> {
        let mut all: Vec<PageSummary> = Vec::new();
        let mut cursor: Option<String> = None;
        for _ in 0..MAX_LIST_ROUNDS {
            let mut query = vec![
                ("updated_since", EPOCH.to_string()),
                ("limit", RECENT_LIMIT.to_string()),
            ];
            if let Some(value) = &cursor {
                query.push(("cursor", value.clone()));
            }
            let url = self.api_url(workspace, project, &["recent"], &query)?;
            let response = self.send(&url, None, "check --workspace/--project").await?;
            let bytes = response
                .bytes()
                .await
                .map_err(|e| anyhow!("reading {} failed: {e}", url.as_str()))?;
            let first = bytes
                .iter()
                .find(|byte| !byte.is_ascii_whitespace())
                .copied()
                .unwrap_or(b'{');
            if first == b'[' {
                let pages: Vec<PageSummary> = serde_json::from_slice(&bytes).map_err(|e| {
                    anyhow!(
                        "legacy page listing from {} is malformed: {e}",
                        url.as_str()
                    )
                })?;
                all.extend(pages);
                return Ok(all);
            }
            let page: RecentIncremental = serde_json::from_slice(&bytes)
                .map_err(|e| anyhow!("page listing from {} is malformed: {e}", url.as_str()))?;
            all.extend(page.pages);
            match page.next_cursor {
                Some(next) => {
                    if Some(&next) == cursor.as_ref() {
                        bail!(
                            "server repeated the same listing cursor; aborting to avoid \
                             an infinite loop"
                        );
                    }
                    cursor = Some(next);
                }
                None => return Ok(all),
            }
        }
        bail!("page listing did not finish within {MAX_LIST_ROUNDS} cursor rounds; aborting");
    }

    /// Read one full page, revalidating a stored ETag with `If-None-Match`.
    /// A `404` here means the listing and the read raced (the page was
    /// deleted or expired mid-run), which fails loudly instead of silently
    /// skipping.
    pub async fn read_page(
        &self,
        workspace: &str,
        project: &str,
        path: &str,
        if_none_match: Option<&str>,
    ) -> Result<PageRead> {
        // Each path segment stays its own path component so the wiki path's
        // '/' separators are preserved in the request URL.
        let tail: Vec<&str> = path.split('/').collect();
        let url = self.build_page_url(workspace, project, &tail)?;
        let response = self
            .send(
                &url,
                if_none_match,
                &format!("page {path:?} was not found (deleted or expired mid-run?)"),
            )
            .await?;
        let etag = response
            .headers()
            .get(reqwest::header::ETAG)
            .and_then(|value| value.to_str().ok())
            .map(str::to_owned)
            .or_else(|| if_none_match.map(str::to_owned));
        if response.status() == StatusCode::NOT_MODIFIED {
            return Ok(PageRead { page: None, etag });
        }
        let page: ApiPage = response.json().await.map_err(|e| {
            anyhow!(
                "page read from {} returned malformed JSON: {e}",
                url.as_str()
            )
        })?;
        if page.path != path {
            bail!(
                "server answered a read of {path:?} with page {:?}; refusing the mismatch",
                page.path
            );
        }
        Ok(PageRead {
            page: Some(page),
            etag,
        })
    }

    fn build_page_url(&self, workspace: &str, project: &str, tail: &[&str]) -> Result<Url> {
        let mut url = self.base.clone();
        {
            let mut segments = url
                .path_segments_mut()
                .map_err(|_| anyhow!("server URL cannot serve as a base"))?;
            segments
                .push("api")
                .push("v1")
                .push("workspaces")
                .push(workspace)
                .push("projects")
                .push(project)
                .push("pages");
            for segment in tail {
                segments.push(segment);
            }
        }
        Ok(url)
    }
}

fn check_status(
    response: reqwest::Response,
    url: &Url,
    not_found_hint: &str,
) -> Result<reqwest::Response> {
    match response.status() {
        StatusCode::OK | StatusCode::NOT_MODIFIED => Ok(response),
        StatusCode::UNAUTHORIZED => bail!(
            "GET {} returned 401 Unauthorized — the server requires a bearer token \
             (pass --token or set AI_MEMORY_AUTH_TOKEN)",
            url.as_str()
        ),
        StatusCode::FORBIDDEN => bail!(
            "GET {} returned 403 Forbidden — the token was rejected, the caller lacks \
             access to this scope, or the server's host allowlist refused the request",
            url.as_str()
        ),
        StatusCode::NOT_FOUND => bail!(
            "GET {} returned 404 Not Found — {not_found_hint}",
            url.as_str()
        ),
        status => bail!("GET {} returned unexpected status {status}", url.as_str()),
    }
}

/// Small helper so the client builder error reads like the others.
trait ContextBuild {
    fn context_build(self) -> Result<reqwest::Client>;
}

impl ContextBuild for Result<reqwest::Client, reqwest::Error> {
    fn context_build(self) -> Result<reqwest::Client> {
        self.map_err(|e| anyhow!("cannot build HTTP client: {e}"))
    }
}