Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! Shared HTTP-client glue for thin-client CLI subcommands.
//!
//! Every state-touching subcommand (status, search, bootstrap, …) goes
//! through these helpers so URL resolution + bearer-auth handling stays
//! consistent in one place.
//!
//! ## Configuration
//!
//! [`crate::config::Config`] captures `AI_MEMORY_SERVER_URL` and
//! `AI_MEMORY_AUTH_TOKEN` exactly once; this module consumes those values
//! and can fall back to the stored OIDC device-flow token used by native hooks.
use std::fmt;
use std::io::{BufWriter, Write as _};
use std::path::Path;
use std::time::Duration;
use anyhow::{Context, Result};
use serde::Serialize;
use serde::de::DeserializeOwned;
use crate::config::{Config, DEFAULT_SERVER_URL};
use ai_memory_web::normalize_prefix;
/// [`ai_memory_hooks::CLIENT_MARKER_HEADER`] value for CLI subcommands.
const CLI_CLIENT_KIND: &str = "cli";
/// Non-success response returned by the configured ai-memory server.
#[derive(Debug)]
pub(crate) struct ServerResponseError {
method: reqwest::Method,
path: String,
status: reqwest::StatusCode,
body: String,
}
impl ServerResponseError {
#[must_use]
pub(crate) const fn status(&self) -> reqwest::StatusCode {
self.status
}
#[must_use]
pub(crate) fn body(&self) -> &str {
&self.body
}
}
impl fmt::Display for ServerResponseError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
formatter,
"{} {}: server returned {}: {}",
self.method, self.path, self.status, self.body
)
}
}
impl std::error::Error for ServerResponseError {}
fn server_response_error(
method: reqwest::Method,
url: &reqwest::Url,
status: reqwest::StatusCode,
body: String,
) -> anyhow::Error {
ServerResponseError {
method,
path: url.path().to_owned(),
status,
body,
}
.into()
}
#[cfg(test)]
pub(crate) fn server_response_error_for_test(
method: reqwest::Method,
path: &str,
status: reqwest::StatusCode,
body: String,
) -> anyhow::Error {
ServerResponseError {
method,
path: path.to_owned(),
status,
body,
}
.into()
}
/// Pass a 2xx response through, else consume the body into a
/// [`ServerResponseError`].
///
/// Only the request path reaches the error, so userinfo and query
/// credentials in the URL never land in a message. `reqwest` does not carry
/// the request method on the response, so callers supply it.
async fn require_success(
method: reqwest::Method,
resp: reqwest::Response,
) -> Result<reqwest::Response> {
let status = resp.status();
if status.is_success() {
return Ok(resp);
}
let url = resp.url().clone();
let body = resp.text().await.unwrap_or_default();
Err(server_response_error(method, &url, status, body))
}
/// Resolved server target — origin URL + base-path prefix + optional bearer token.
#[derive(Debug, Clone)]
pub struct ServerEndpoint {
/// Origin only (scheme + authority), any trailing slash and path
/// stripped, e.g. `http://127.0.0.1:49374` or `http://192.168.0.90:49374`.
pub url: String,
/// Normalised base-path prefix the server is mounted under, e.g.
/// `/wiki`, or empty when serving at the root. Always either empty or
/// `/`-prefixed with no trailing slash (normalised by `normalize_prefix`).
pub base_path: String,
/// Bearer token when present, else `None`.
pub auth_token: Option<String>,
url_configured: bool,
}
impl ServerEndpoint {
/// Build the endpoint from config, resolving bearer auth and base path.
///
/// Bearer precedence matches hooks: static config/env token first, stored
/// OIDC device token second, no token last.
///
/// The base-path prefix the server is mounted under, so client routes
/// resolve as `<origin><base><path>` instead of 404ing) is resolved
/// from, in order of precedence:
/// 1. the **path component of `AI_MEMORY_SERVER_URL`** (the remote-client
/// case — `http://host:49374/wiki` → origin `http://host:49374`,
/// base `/wiki`), then
/// 2. **`Config::base_path`** (the in-pod case — figment populates the
/// field from `AI_MEMORY_BASE_PATH` inside `Config::load`, keeping the
/// "one config-read path" invariant; the CLI runs in the same
/// container as `serve`, which already reads the same env var via
/// clap to nest its router).
pub async fn from_config_resolving_auth(config: &Config) -> Self {
let client = reqwest::Client::new();
let token = crate::auth_bearer::resolve_bearer(
&client,
&config.oidc_device_token_path(),
config.auth.bearer_token.as_deref(),
)
.await;
Self::build(
Some(config.server_url.clone()),
token,
config.server_url_configured(),
Some(config.base_path.clone()).filter(|s| !s.is_empty()),
)
}
/// Build for a target the spawning hook already resolved: its URL
/// (including any mount path, as `install-hooks` rendered it) and the
/// bearer it authenticates with. No config or environment is consulted.
#[must_use]
pub(crate) fn for_hook_target(url: String, token: Option<String>) -> Self {
Self::build(Some(url), token, true, None)
}
/// Build from an explicit URL + token pair (useful for tests that
/// cannot safely mutate the process environment).
///
/// `url` defaults to `http://127.0.0.1:49374` when `None` or empty;
/// trailing slashes are stripped. `token` is treated as absent when
/// `None` or empty. No environment is read — the env base-path fallback
/// is `None`; use [`from_pair_with_base`] to exercise that path.
#[must_use]
#[cfg(test)]
pub(crate) fn from_pair(url: Option<String>, token: Option<String>) -> Self {
let url_configured = url.as_deref().is_some_and(|s| !s.is_empty());
Self::build(url, token, url_configured, None)
}
/// Like [`from_pair`] but with an explicit `AI_MEMORY_BASE_PATH` env
/// fallback value, so the env-fallback branch is testable hermetically.
#[must_use]
#[cfg(test)]
pub(crate) fn from_pair_with_base(
url: Option<String>,
token: Option<String>,
env_base: Option<String>,
) -> Self {
let url_configured = url.as_deref().is_some_and(|s| !s.is_empty());
Self::build(url, token, url_configured, env_base)
}
fn build(
url: Option<String>,
token: Option<String>,
url_configured: bool,
env_base: Option<String>,
) -> Self {
let raw = url
.filter(|s| !s.is_empty())
.unwrap_or_else(|| DEFAULT_SERVER_URL.to_string());
let (origin, url_path) = split_origin_and_path(&raw);
// The URL path component wins over the env var: it is the more
// explicit, request-target-level statement of where the server is.
let base_path = if url_path.is_empty() {
env_base.map_or_else(String::new, |s| normalize_prefix(&s))
} else {
normalize_prefix(&url_path)
};
Self {
url: origin,
base_path,
auth_token: token.filter(|s| !s.is_empty()),
url_configured,
}
}
/// Join the resolved origin + base-path prefix + a root-absolute route
/// `path` (e.g. `/admin/status`) into the full request URL. When no base
/// path is configured this is byte-identical to the old
/// `format!("{origin}{path}")`.
pub(crate) fn build_url(&self, path: &str) -> String {
format!("{}{}{path}", self.url, self.base_path)
}
/// Stable, credential-free identity for client-local state tied to this
/// server. The normalized mount path is part of the identity; bearer
/// material deliberately is not.
pub(crate) fn identity(&self) -> String {
let raw = format!("{}{}", self.url.trim_end_matches('/'), self.base_path);
let Ok(mut parsed) = reqwest::Url::parse(&raw) else {
return "<invalid-server-url>".to_owned();
};
let _ = parsed.set_username("");
let _ = parsed.set_password(None);
parsed.set_query(None);
parsed.set_fragment(None);
parsed.as_str().trim_end_matches('/').to_owned()
}
/// Mark a request to this server as first-party
/// ([`ai_memory_hooks::CLIENT_MARKER_HEADER`]) and attach the bearer when a
/// token is set.
pub(crate) fn authenticate(&self, req: reqwest::RequestBuilder) -> reqwest::RequestBuilder {
let req = req.header(ai_memory_hooks::CLIENT_MARKER_HEADER, CLI_CLIENT_KIND);
match &self.auth_token {
Some(t) => req.bearer_auth(t),
None => req,
}
}
}
/// Split a server URL into `(origin, path)` where `origin` is
/// scheme+authority (`http://host:port`) and `path` is everything from the
/// first `/` after the authority (`/wiki`, possibly empty). Trailing slashes
/// are trimmed from both. A URL with no scheme separator is treated as an
/// opaque origin with no path.
pub(crate) fn split_origin_and_path(raw: &str) -> (String, String) {
let trimmed = raw.trim_end_matches('/');
if let Some(scheme_end) = trimmed.find("://") {
let after_scheme = scheme_end + 3;
if let Some(rel_slash) = trimmed[after_scheme..].find('/') {
let split = after_scheme + rel_slash;
return (
trimmed[..split].to_string(),
trimmed[split..].trim_end_matches('/').to_string(),
);
}
}
(trimmed.to_string(), String::new())
}
/// Whether `url` names a server on this machine: an `http`/`https` URL whose
/// host is `localhost`, an address in `127.0.0.0/8`, or `[::1]`, carrying no
/// user information.
///
/// Parsed the way the HTTP client parses it, so the host checked here is the
/// host a request would reach. Text before an `@` is user information, not
/// the host, and a URL that has any is refused outright rather than
/// interpreted. `localhost.` (trailing dot) is refused too: a fully qualified
/// name can be answered by a DNS server instead of the local resolver. This
/// gates the install's own root token (`config.rs`, `mcp-bridge`), so an
/// unparsable or ambiguous URL is never treated as local.
pub(crate) fn is_loopback_url(url: &str) -> bool {
let Ok(parsed) = reqwest::Url::parse(url) else {
return false;
};
if !matches!(parsed.scheme(), "http" | "https")
|| !parsed.username().is_empty()
|| parsed.password().is_some()
{
return false;
}
let Some(host) = parsed.host_str() else {
return false;
};
if let Some(v6) = host.strip_prefix('[').and_then(|h| h.strip_suffix(']')) {
return v6
.parse::<std::net::Ipv6Addr>()
.is_ok_and(|ip| ip.is_loopback());
}
host.parse::<std::net::Ipv4Addr>()
.map_or(host == "localhost", |ip| ip.is_loopback())
}
/// GET `<endpoint>{path}` with optional query params, deserialise JSON.
///
/// # Errors
/// Returns an error when the connection fails, the response is non-2xx,
/// or the body can't be deserialised into `T`.
pub async fn get_json<T: DeserializeOwned>(
endpoint: &ServerEndpoint,
path: &str,
query: &[(&str, &str)],
) -> Result<T> {
let client = reqwest::Client::new();
let url = endpoint.build_url(path);
let mut req = client.get(&url);
if !query.is_empty() {
req = req.query(query);
}
req = endpoint.authenticate(req);
let resp = req
.send()
.await
.map_err(|e| augment_connect_error(e, endpoint, &url))?;
let resp = require_success(reqwest::Method::GET, resp).await?;
resp.json::<T>()
.await
.with_context(|| format!("parsing JSON body from GET {url}"))
}
/// PATCH JSON body to `<endpoint>{path}`, deserialise JSON response.
///
/// # Errors
/// Same as [`get_json`].
pub async fn patch_json<B: Serialize, T: DeserializeOwned>(
endpoint: &ServerEndpoint,
path: &str,
body: &B,
) -> Result<T> {
let client = reqwest::Client::new();
let url = endpoint.build_url(path);
let req = endpoint.authenticate(client.patch(&url).json(body));
let resp = req
.send()
.await
.map_err(|e| augment_connect_error(e, endpoint, &url))?;
let resp = require_success(reqwest::Method::PATCH, resp).await?;
resp.json::<T>()
.await
.with_context(|| format!("parsing JSON body from PATCH {url}"))
}
/// POST JSON body to `<endpoint>{path}`, deserialise JSON response.
///
/// # Errors
/// Same as [`get_json`].
pub async fn post_json<B: Serialize, T: DeserializeOwned>(
endpoint: &ServerEndpoint,
path: &str,
body: &B,
) -> Result<T> {
post_json_with_query(endpoint, path, &[], body).await
}
/// POST JSON and require a successful response without decoding its body.
pub async fn post_json_no_content<B: Serialize>(
endpoint: &ServerEndpoint,
path: &str,
body: &B,
) -> Result<()> {
let client = reqwest::Client::new();
let url = endpoint.build_url(path);
let req = endpoint.authenticate(client.post(&url).json(body));
let resp = req
.send()
.await
.map_err(|e| augment_connect_error(e, endpoint, &url))?;
require_success(reqwest::Method::POST, resp).await?;
Ok(())
}
/// POST an empty body and require a successful response.
pub async fn post_empty(endpoint: &ServerEndpoint, path: &str) -> Result<()> {
let client = reqwest::Client::new();
let url = endpoint.build_url(path);
let req = endpoint.authenticate(client.post(&url));
let resp = req
.send()
.await
.map_err(|e| augment_connect_error(e, endpoint, &url))?;
require_success(reqwest::Method::POST, resp).await?;
Ok(())
}
/// POST JSON body to `<endpoint>{path}` with URL-encoded query params.
///
/// # Errors
/// Same as [`post_json`].
pub async fn post_json_with_query<B: Serialize, T: DeserializeOwned>(
endpoint: &ServerEndpoint,
path: &str,
query: &[(&str, &str)],
body: &B,
) -> Result<T> {
let client = reqwest::Client::new();
let url = build_url_with_query(endpoint, path, query)?;
let req = client.post(&url);
let req = endpoint.authenticate(req.json(body));
let resp = req
.send()
.await
.map_err(|e| augment_connect_error(e, endpoint, &url))?;
let resp = require_success(reqwest::Method::POST, resp).await?;
resp.json::<T>()
.await
.with_context(|| format!("parsing JSON body from POST {url}"))
}
fn build_url_with_query(
endpoint: &ServerEndpoint,
path: &str,
query: &[(&str, &str)],
) -> Result<String> {
let mut url = reqwest::Url::parse(&endpoint.build_url(path))?;
if !query.is_empty() {
url.query_pairs_mut().extend_pairs(query.iter().copied());
}
Ok(url.to_string())
}
/// Turn a low-level reqwest connect/timeout error into a friendlier
/// message that surfaces the resolved server URL. The common cases are
/// "Connection refused", a connect that never completes, and a peer that
/// closes before sending an HTTP response. They all mean the same operator
/// problem: the CLI was pointed at an endpoint where no server answered.
pub(crate) fn augment_connect_error(
err: reqwest::Error,
endpoint: &ServerEndpoint,
url: &str,
) -> anyhow::Error {
if error_chain_indicates_no_answer(&err) {
let hint = if endpoint.url_configured {
format!(
"\nAI_MEMORY_SERVER_URL is set to {} but nothing answered \
(refused or timed out). Check the server is running, the \
port is reachable from this host, and (if remote) any \
firewall + bearer-token config matches.",
endpoint.url
)
} else {
format!(
"\nAI_MEMORY_SERVER_URL is NOT set; the CLI defaulted to \
{} and nothing answered (refused or timed out). If your \
server lives on another machine (e.g. a homelab), `export \
AI_MEMORY_SERVER_URL=http://<server>:49374` and (if auth \
is on) `export AI_MEMORY_AUTH_TOKEN=<token>` before \
re-running.",
endpoint.url
)
};
anyhow::Error::new(err).context(format!("could not reach {url}.{hint}"))
} else {
anyhow::Error::new(err).context(format!("HTTP request to {url} failed"))
}
}
/// Whether a request failed because nothing answered — a refused connection
/// or a timeout — rather than because the server answered with an error.
pub(crate) fn server_unreachable(err: &anyhow::Error) -> bool {
let answered = err
.chain()
.any(|cause| cause.downcast_ref::<ServerResponseError>().is_some());
!answered && err.chain().any(error_chain_indicates_no_answer)
}
/// Whether an error chain means "nothing answered at the transport layer".
/// reqwest may classify this as a connect/timeout failure or wrap the socket
/// error deeply. A peer can also accept and close before the HTTP response,
/// which is equally unreachable from the caller's perspective.
fn error_chain_indicates_no_answer(err: &(dyn std::error::Error + 'static)) -> bool {
if let Some(req) = err.downcast_ref::<reqwest::Error>()
&& (req.is_connect() || req.is_timeout())
{
return true;
}
let mut src: Option<&dyn std::error::Error> = Some(err);
while let Some(e) = src {
if let Some(io) = e.downcast_ref::<std::io::Error>()
&& matches!(
io.kind(),
std::io::ErrorKind::ConnectionRefused
| std::io::ErrorKind::ConnectionReset
| std::io::ErrorKind::ConnectionAborted
| std::io::ErrorKind::BrokenPipe
| std::io::ErrorKind::UnexpectedEof
| std::io::ErrorKind::TimedOut
)
{
return true;
}
let wording = e.to_string().to_ascii_lowercase();
if wording.contains("connection refused")
|| wording.contains("connection reset")
|| wording.contains("connection aborted")
|| wording.contains("connection closed before message completed")
|| wording.contains("unexpected eof")
|| wording.contains("broken pipe")
|| wording.contains("timed out")
{
return true;
}
src = e.source();
}
false
}
/// Outcome of a server reachability probe: did anything answer on the
/// configured endpoint?
#[derive(Debug)]
pub(crate) enum ServerProbe {
/// The server answered. Any HTTP status counts — a build older than
/// `/healthz` still answers 404/405, and what the probe needs to know is
/// that something is listening, not that it is healthy.
Reachable,
/// Nothing answered (connect error or timeout). Carries the underlying
/// reqwest error so callers can reuse [`augment_connect_error`]'s
/// diagnosis verbatim.
Unreachable(reqwest::Error),
}
/// How long a reachability probe waits for an answer. Short on purpose: the
/// probe sits on the launch hot path, so an unresponsive host (a homelab down
/// for maintenance) must be classified in ~2s rather than the OS-level TCP
/// timeout a plain request would pay.
const PROBE_TIMEOUT: Duration = Duration::from_secs(2);
/// GET `{origin}{base}/healthz` with a short timeout to decide whether a
/// managed launch may proceed without the server.
///
/// Any HTTP response — 200 or 404/405 from a pre-`/healthz` server — means
/// `Reachable`; only connect errors and timeouts mean `Unreachable`. The
/// probe never inspects the body, so it cannot be wrong about health vs
/// absence, only about presence.
pub(crate) async fn probe_server(endpoint: &ServerEndpoint) -> ServerProbe {
probe_server_with_timeout(endpoint, PROBE_TIMEOUT).await
}
async fn probe_server_with_timeout(endpoint: &ServerEndpoint, timeout: Duration) -> ServerProbe {
let client = reqwest::Client::new();
let url = endpoint.build_url("/healthz");
match client.get(&url).timeout(timeout).send().await {
Ok(_) => ServerProbe::Reachable,
Err(error) => ServerProbe::Unreachable(error),
}
}
/// POST an empty body to `<endpoint>{path}`, streaming the response to `dest`.
///
/// Intended for routes whose response is binary (e.g. `POST /admin/backup`
/// returns an `application/gzip` tarball). On non-2xx the response body is
/// consumed and returned as an error string. Returns bytes written. A completed
/// download atomically replaces the destination path; a destination symlink is
/// replaced rather than modifying the file it points to. Replacement symlinks
/// and new destinations use private permissions; only existing regular files
/// retain their permissions.
///
/// # Errors
/// Returns an error when the connection fails, the response is non-2xx,
/// or the body cannot be read or written.
pub async fn post_to_file(endpoint: &ServerEndpoint, path: &str, dest: &Path) -> Result<u64> {
let client = reqwest::Client::new();
let url = endpoint.build_url(path);
let req = endpoint.authenticate(client.post(&url));
let resp = req
.send()
.await
.map_err(|e| augment_connect_error(e, endpoint, &url))?;
let mut resp = require_success(reqwest::Method::POST, resp).await?;
let permissions = checked_output_permissions(dest)?;
let mut temporary = private_output_file(dest)
.with_context(|| format!("creating temporary output beside {}", dest.display()))?;
let mut writer = BufWriter::new(temporary.as_file_mut());
let mut written = 0_u64;
while let Some(chunk) = resp
.chunk()
.await
.with_context(|| format!("reading response chunk from POST {url}"))?
{
writer
.write_all(&chunk)
.with_context(|| format!("writing response chunk to {}", dest.display()))?;
written += chunk.len() as u64;
}
writer
.flush()
.with_context(|| format!("flushing {}", dest.display()))?;
drop(writer);
// A failed response must leave the previous archive usable. The temporary
// file stays private until the entire response has arrived.
if let Some(permissions) = permissions {
temporary
.as_file()
.set_permissions(permissions)
.with_context(|| format!("preserving permissions for {}", dest.display()))?;
}
temporary
.as_file()
.sync_all()
.with_context(|| format!("syncing temporary output beside {}", dest.display()))?;
let persisted = temporary
.persist(dest)
.map_err(|error| error.error)
.with_context(|| format!("replacing output file {}", dest.display()))?;
persisted
.sync_all()
.with_context(|| format!("syncing output file {}", dest.display()))?;
if let Ok(directory) = std::fs::File::open(output_parent(dest)) {
let _ = directory.sync_all();
}
Ok(written)
}
/// Atomic replacement still requires permission to write an existing regular
/// file. Opening without create or truncate checks OS permissions and ACLs
/// without changing the archive before the response is complete.
fn checked_output_permissions(dest: &Path) -> Result<Option<std::fs::Permissions>> {
match std::fs::symlink_metadata(dest) {
Ok(metadata) if metadata.file_type().is_symlink() => Ok(None),
Ok(metadata) if metadata.is_file() => {
let probe = std::fs::OpenOptions::new()
.write(true)
.open(dest)
.with_context(|| {
format!(
"checking output file write permission for {}",
dest.display()
)
})?;
drop(probe);
Ok(Some(metadata.permissions()))
}
Ok(metadata) if metadata.is_dir() => {
anyhow::bail!("output path is a directory: {}", dest.display());
}
Ok(_) => anyhow::bail!("output path is not a regular file: {}", dest.display()),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
Err(error) => Err(error).context("reading output file permissions"),
}
}
/// Download beside the destination so publication is an atomic rename on the
/// same filesystem. NamedTempFile removes an incomplete response on every exit.
fn private_output_file(path: &Path) -> std::io::Result<tempfile::NamedTempFile> {
tempfile::Builder::new()
.prefix(".ai-memory-download.")
.tempfile_in(output_parent(path))
}
fn output_parent(path: &Path) -> &Path {
path.parent()
.filter(|parent| !parent.as_os_str().is_empty())
.unwrap_or_else(|| Path::new("."))
}
#[cfg(test)]
mod tests {
use std::time::Instant;
use super::*;
/// The host checked must be the host a request reaches: user
/// information before an `@` is refused, never read as the host.
#[test]
fn loopback_url_is_decided_by_the_parsed_host() {
for url in [
"http://127.0.0.1:49374",
"http://localhost:49374/mcp",
"http://LOCALHOST:1",
"https://localhost",
"http://[::1]:49374",
"http://[::1]",
"http://127.0.0.2:1",
"http://127.255.255.254/",
] {
assert!(is_loopback_url(url), "{url} is loopback");
}
for url in [
"http://localhost:[email protected]/",
"http://127.0.0.1:[email protected]/",
"http://u:p@[::1]:[email protected]/",
"http://user@localhost:49374",
"http://user:[email protected]:49374",
"http://evil.example#@localhost:1",
"http://evil.example/?@localhost:1",
"http://localhost.evil.example",
"http://127.0.0.1.evil.example",
"http://localhost.:49374",
"http://0.0.0.0:49374",
"http://192.168.1.10:49374",
"http://[::ffff:127.0.0.1]:49374",
"ftp://localhost/",
"localhost:49374",
"not a url",
"",
] {
assert!(!is_loopback_url(url), "{url} is not loopback");
}
}
#[test]
fn only_an_unanswered_request_is_unreachable() {
let refused =
anyhow::Error::new(std::io::Error::from(std::io::ErrorKind::ConnectionRefused))
.context("HTTP request to http://127.0.0.1:1/admin/status failed");
assert!(server_unreachable(&refused));
let answered = server_response_error_for_test(
reqwest::Method::GET,
"/admin/status",
reqwest::StatusCode::SERVICE_UNAVAILABLE,
"down for maintenance".to_owned(),
);
assert!(!server_unreachable(&answered));
assert!(!server_unreachable(&anyhow::anyhow!(
"malformed response body"
)));
}
#[test]
fn output_write_permission_probe_never_truncates_existing_bytes() {
let temp = tempfile::tempdir().unwrap();
let output = temp.path().join("backup.tar.gz");
std::fs::write(&output, b"previous usable archive").unwrap();
assert!(
super::checked_output_permissions(&output)
.unwrap()
.is_some()
);
assert_eq!(std::fs::read(&output).unwrap(), b"previous usable archive");
}
#[cfg(unix)]
#[test]
fn downloaded_backup_output_is_private_when_created() {
use std::os::unix::fs::PermissionsExt as _;
let temp = tempfile::tempdir().unwrap();
let output = temp.path().join("backup.tar.gz");
let temporary = private_output_file(&output).unwrap();
assert!(
!output.exists(),
"download is not published before completion"
);
assert_eq!(
temporary.as_file().metadata().unwrap().permissions().mode() & 0o777,
0o600
);
}
#[test]
fn response_errors_include_method_and_credential_free_path() {
let url = reqwest::Url::parse(
"https://username:[email protected]/workstream/runs?access_token=secret",
)
.expect("test URL parses");
let error = server_response_error(
reqwest::Method::POST,
&url,
reqwest::StatusCode::NOT_FOUND,
"missing".to_owned(),
);
assert_eq!(
error.to_string(),
"POST /workstream/runs: server returned 404 Not Found: missing"
);
let structured = error
.downcast_ref::<ServerResponseError>()
.expect("response errors retain their structured type");
assert_eq!(structured.status(), reqwest::StatusCode::NOT_FOUND);
assert_eq!(structured.body(), "missing");
assert!(!error.to_string().contains("username"));
assert!(!error.to_string().contains("password"));
assert!(!error.to_string().contains("access_token"));
assert!(!error.to_string().contains("secret"));
}
// ----------------------------------------------------------------
// ServerEndpoint::from_pair
// ----------------------------------------------------------------
#[test]
fn from_pair_defaults_to_loopback_when_none() {
let ep = ServerEndpoint::from_pair(None, None);
assert_eq!(ep.url, "http://127.0.0.1:49374");
assert!(ep.auth_token.is_none());
}
#[test]
fn from_pair_defaults_to_loopback_when_empty() {
let ep = ServerEndpoint::from_pair(Some(String::new()), None);
assert_eq!(ep.url, "http://127.0.0.1:49374");
}
#[test]
fn from_pair_strips_trailing_slash() {
let ep = ServerEndpoint::from_pair(Some("http://10.0.0.1:8080/".to_string()), None);
assert_eq!(ep.url, "http://10.0.0.1:8080");
}
#[test]
fn from_pair_strips_multiple_trailing_slashes() {
let ep = ServerEndpoint::from_pair(Some("http://10.0.0.1:8080///".to_string()), None);
assert_eq!(ep.url, "http://10.0.0.1:8080");
}
#[test]
fn from_pair_empty_token_treated_as_none() {
let ep = ServerEndpoint::from_pair(None, Some(String::new()));
assert!(ep.auth_token.is_none());
}
#[test]
fn from_pair_non_empty_token_preserved() {
let ep = ServerEndpoint::from_pair(None, Some("secret".to_string()));
assert_eq!(ep.auth_token.as_deref(), Some("secret"));
}
#[test]
fn client_state_identity_normalizes_mounts_and_never_contains_credentials() {
let first = ServerEndpoint::from_pair(
Some("http://alice:[email protected]:49374/wiki/".to_owned()),
None,
);
let second = ServerEndpoint::from_pair(
Some("http://memory.example:49374/wiki".to_owned()),
Some("bearer-secret".to_owned()),
);
assert_eq!(first.identity(), second.identity());
assert!(!first.identity().contains("alice"));
assert!(!first.identity().contains("secret"));
}
// ----------------------------------------------------------------
// Base-path awareness — graduated from the Docker live exploration of
// the CLI-client-under-AI_MEMORY_BASE_PATH bug. The server nests every
// route under `--base-path` (`/wiki/admin/status`), but the thin client
// baked root-absolute paths (`/admin/status`) → 404. Each test below
// pins one hypothesis that the live run validated end-to-end.
// ----------------------------------------------------------------
/// H1 — no base path configured: the joined URL is byte-identical to the
/// old `format!("{origin}{path}")`. The regression guard for the OFF-by-
/// default promise.
#[test]
fn build_url_without_base_is_byte_identical() {
let ep = ServerEndpoint::from_pair(Some("http://h:49374".to_string()), None);
assert_eq!(ep.base_path, "");
assert_eq!(ep.build_url("/admin/status"), "http://h:49374/admin/status");
}
/// H4/H9 — remote client: the base path comes from the **path component
/// of the server URL**, which is split off the origin and normalised
/// (trailing slash trimmed).
#[test]
fn server_url_path_becomes_base_path() {
let ep = ServerEndpoint::from_pair(Some("http://h:49374/wiki".to_string()), None);
assert_eq!(ep.url, "http://h:49374");
assert_eq!(ep.base_path, "/wiki");
assert_eq!(
ep.build_url("/admin/status"),
"http://h:49374/wiki/admin/status"
);
// Trailing slash on the URL path normalises away (H9).
let ep = ServerEndpoint::from_pair(Some("http://h:49374/wiki/".to_string()), None);
assert_eq!(ep.url, "http://h:49374");
assert_eq!(ep.base_path, "/wiki");
}
/// H3 — in-pod client: no path on the server URL, base path falls back to
/// the `AI_MEMORY_BASE_PATH` env value (passed explicitly here to stay
/// hermetic).
#[test]
fn env_base_path_used_when_url_has_no_path() {
let ep = ServerEndpoint::from_pair_with_base(None, None, Some("/wiki".to_string()));
assert_eq!(ep.url, "http://127.0.0.1:49374");
assert_eq!(ep.base_path, "/wiki");
assert_eq!(
ep.build_url("/admin/write-page"),
"http://127.0.0.1:49374/wiki/admin/write-page"
);
}
/// H8 — precedence: when BOTH a URL path and an env base are present, the
/// URL path wins (it is the more explicit, request-target-level value).
#[test]
fn url_path_wins_over_env_base() {
let ep = ServerEndpoint::from_pair_with_base(
Some("http://h:49374/url-base".to_string()),
None,
Some("/env-base".to_string()),
);
assert_eq!(ep.base_path, "/url-base");
}
/// H11 — multi-segment base path is preserved verbatim.
#[test]
fn multi_segment_base_path_is_preserved() {
let ep = ServerEndpoint::from_pair_with_base(None, None, Some("/a/b".to_string()));
assert_eq!(ep.base_path, "/a/b");
assert_eq!(
ep.build_url("/admin/status"),
"http://127.0.0.1:49374/a/b/admin/status"
);
}
/// H10 — a traversal-y base (`/wiki/../etc`) is neutralised by
/// `normalize_prefix` to empty (it rejects dot-segments), so the client
/// falls back to the root rather than emitting `/wiki/../etc/...`. The
/// client then 404s consistently instead of walking out of the prefix.
#[test]
fn traversal_base_path_is_neutralised_to_root() {
let ep = ServerEndpoint::from_pair_with_base(None, None, Some("/wiki/../etc".to_string()));
assert_eq!(ep.base_path, "");
let joined = ep.build_url("/admin/status");
assert!(
!joined.contains("/../") && !joined.contains("/etc/admin"),
"traversal must not leak into the request URL; got {joined}"
);
assert_eq!(joined, "http://127.0.0.1:49374/admin/status");
}
/// A bare base value without a leading slash is normalised to `/<core>`,
/// matching the server's own `normalize_prefix` so the two agree.
#[test]
fn bare_env_base_gets_leading_slash() {
let ep = ServerEndpoint::from_pair_with_base(None, None, Some("wiki".to_string()));
assert_eq!(ep.base_path, "/wiki");
}
/// `/` and empty both mean "root" — no prefix added.
#[test]
fn root_like_base_values_mean_no_prefix() {
for raw in ["", "/", "//", " / "] {
let ep = ServerEndpoint::from_pair_with_base(None, None, Some(raw.to_string()));
assert_eq!(ep.base_path, "", "{raw:?} should normalise to no prefix");
assert_eq!(
ep.build_url("/admin/status"),
"http://127.0.0.1:49374/admin/status"
);
}
}
#[test]
fn build_url_with_query_url_encodes_values() {
let ep = ServerEndpoint::from_pair(Some("http://h:49374/wiki".to_string()), None);
let url = super::build_url_with_query(
&ep,
"/admin/pending-writes/id/approve",
&[("workspace", "default workspace"), ("project", "a/b & c")],
)
.unwrap();
assert_eq!(
url,
"http://h:49374/wiki/admin/pending-writes/id/approve?workspace=default+workspace&project=a%2Fb+%26+c"
);
}
// ----------------------------------------------------------------
// split_origin_and_path
// ----------------------------------------------------------------
#[test]
fn split_origin_and_path_cases() {
assert_eq!(
split_origin_and_path("http://h:49374"),
("http://h:49374".to_string(), String::new())
);
assert_eq!(
split_origin_and_path("http://h:49374/"),
("http://h:49374".to_string(), String::new())
);
assert_eq!(
split_origin_and_path("http://h:49374/wiki"),
("http://h:49374".to_string(), "/wiki".to_string())
);
assert_eq!(
split_origin_and_path("http://h:49374/wiki/"),
("http://h:49374".to_string(), "/wiki".to_string())
);
assert_eq!(
split_origin_and_path("https://h:49374/a/b"),
("https://h:49374".to_string(), "/a/b".to_string())
);
// No scheme separator → opaque origin, no path split.
assert_eq!(
split_origin_and_path("127.0.0.1:49374"),
("127.0.0.1:49374".to_string(), String::new())
);
}
// ----------------------------------------------------------------
// ServerEndpoint::authenticate
// ----------------------------------------------------------------
#[test]
fn authenticate_no_token_sets_only_the_client_marker() {
let ep = ServerEndpoint::from_pair(None, None);
let client = reqwest::Client::new();
// Build a request, authenticate it, then build to inspect.
let req = ep
.authenticate(client.get("http://localhost"))
.build()
.unwrap();
// No Authorization header should be present.
assert!(
req.headers().get("authorization").is_none(),
"no Authorization header expected"
);
// An unauthenticated server reached by a LAN name refuses a handoff
// fetch without the marker, so every CLI request carries it.
assert_eq!(
req.headers()
.get(ai_memory_hooks::CLIENT_MARKER_HEADER)
.and_then(|v| v.to_str().ok()),
Some("cli")
);
}
#[test]
fn authenticate_with_token_sets_bearer_header() {
let ep = ServerEndpoint::from_pair(None, Some("tok123".to_string()));
let client = reqwest::Client::new();
let req = ep
.authenticate(client.get("http://localhost"))
.build()
.unwrap();
let auth = req
.headers()
.get("authorization")
.expect("Authorization header must be set")
.to_str()
.unwrap();
assert_eq!(auth, "Bearer tok123");
}
// ----------------------------------------------------------------
// Server reachability probe
// ----------------------------------------------------------------
/// Keep a listener bound and close every accepted connection so parallel
/// tests cannot reuse an allegedly closed ephemeral port.
fn no_answer_endpoint() -> ServerEndpoint {
ServerEndpoint::from_pair(Some(ai_memory_test_support::dead_http_endpoint()), None)
}
#[tokio::test]
async fn probe_reports_an_accept_then_close_peer_as_unreachable_with_the_diagnosis() {
let endpoint = no_answer_endpoint();
let ServerProbe::Unreachable(error) = probe_server(&endpoint).await else {
panic!("a peer that closes before responding must be Unreachable");
};
let url = endpoint.build_url("/workstream/runs");
let augmented = augment_connect_error(error, &endpoint, &url);
let message = format!("{augmented:#}");
assert!(
message.contains("could not reach"),
"the probe error must feed augment_connect_error: {message}"
);
assert!(
message.contains(&endpoint.url),
"the diagnosis names the resolved server URL: {message}"
);
}
/// A connect that is accepted but never answered ends as a reqwest
/// timeout — the variant windows-latest produces when its firewall
/// drops a loopback connect instead of refusing it. The operator
/// problem ("nothing at this URL") is identical to a refusal, so the
/// diagnosis must be too.
#[tokio::test]
async fn probe_timeout_error_carries_the_same_reachability_diagnosis() {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
tokio::spawn(async move {
// Accept connections and hold them open without answering: the
// client's only way out is its own timeout.
let mut held = Vec::new();
while let Ok((stream, _)) = listener.accept().await {
held.push(stream);
}
});
let endpoint = ServerEndpoint::from_pair(Some(format!("http://{address}")), None);
let ServerProbe::Unreachable(error) =
probe_server_with_timeout(&endpoint, Duration::from_millis(150)).await
else {
panic!("an accept-and-hold socket must end Unreachable via the probe timeout");
};
assert!(
error.is_timeout(),
"accept-and-hold must produce the timeout variant, got: {error}"
);
let url = endpoint.build_url("/workstream/runs");
let augmented = augment_connect_error(error, &endpoint, &url);
let message = format!("{augmented:#}");
assert!(
message.contains("could not reach"),
"the timeout variant must keep the reachability diagnosis: {message}"
);
assert!(
message.contains(&endpoint.url),
"the diagnosis names the resolved server URL: {message}"
);
}
/// The no-answer detection must recognize every platform's wording of
/// "nothing answered": the typed io kinds, and the free-text variants
/// hyper buries below reqwest on each OS. windows-latest says
/// "operation timed out (os error 10060)" where Linux says
/// "Connection refused (os error 111)".
#[test]
fn no_answer_detection_covers_refused_and_timeout_wording() {
#[derive(Debug)]
struct Wrapped(&'static str);
impl std::fmt::Display for Wrapped {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(self.0)
}
}
impl std::error::Error for Wrapped {}
assert!(error_chain_indicates_no_answer(&std::io::Error::from(
std::io::ErrorKind::ConnectionRefused
)));
assert!(error_chain_indicates_no_answer(&std::io::Error::from(
std::io::ErrorKind::TimedOut
)));
assert!(error_chain_indicates_no_answer(&Wrapped(
"error sending request for url (http://127.0.0.1:49374/healthz): operation timed \
out (os error 10060)"
)));
assert!(error_chain_indicates_no_answer(&Wrapped(
"error sending request for url (http://127.0.0.1:49374/healthz): Connection refused \
(os error 111)"
)));
// Unrelated transport failures keep the generic HTTP-failure
// message: a decode error answered, it did not go unanswered.
assert!(!error_chain_indicates_no_answer(&Wrapped(
"error decoding response body"
)));
}
/// A server that answers 404 for `/healthz` (older than the route) is
/// still reachable: presence, not health, is what the probe decides.
#[tokio::test]
async fn probe_reports_any_http_answer_as_reachable() {
for status in [
axum::http::StatusCode::OK,
axum::http::StatusCode::NOT_FOUND,
axum::http::StatusCode::METHOD_NOT_ALLOWED,
] {
let app =
axum::Router::new().fallback(axum::routing::get(move || async move { status }));
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
let endpoint = ServerEndpoint::from_pair(Some(format!("http://{address}")), None);
assert!(matches!(
probe_server(&endpoint).await,
ServerProbe::Reachable
));
server.abort();
}
}
/// A listener that accepts but never answers must be given up on within
/// the probe timeout, not a TCP or default-client timeout.
#[tokio::test]
async fn probe_gives_up_within_its_own_timeout() {
async fn accept_and_hold() -> std::net::SocketAddr {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
tokio::spawn(async move {
// Accept connections, hold them open, and answer nothing —
// the streams must outlive the accept so the client's only
// way out is its own timeout.
let mut held = Vec::new();
while let Ok((stream, _)) = listener.accept().await {
held.push(stream);
}
});
address
}
let address = accept_and_hold().await;
let endpoint = ServerEndpoint::from_pair(Some(format!("http://{address}")), None);
let started = Instant::now();
assert!(matches!(
probe_server_with_timeout(&endpoint, Duration::from_millis(150)).await,
ServerProbe::Unreachable(_)
));
let elapsed = started.elapsed();
assert!(elapsed >= Duration::from_millis(150), "gave up too early");
assert!(
elapsed < Duration::from_secs(2),
"the probe timeout, not a transport default, bounds the wait ({elapsed:?})"
);
}
/// The production probe stays bounded by design: a homelab down for
/// maintenance must be classified in ~2s, never by an OS TCP timeout.
#[test]
fn probe_timeout_is_bounded_to_about_two_seconds() {
assert!(PROBE_TIMEOUT <= Duration::from_secs(2));
assert!(!PROBE_TIMEOUT.is_zero());
}
#[tokio::test]
async fn from_config_resolving_auth_uses_stored_oidc_for_authorization_header() {
let tmp = tempfile::tempdir().unwrap();
let mut config = Config {
data_dir: tmp.path().to_path_buf(),
..Config::default()
};
config.auth.bearer_token = None;
ai_memory_llm::OidcToken {
access: secrecy::SecretString::from("oidc-access".to_string()),
refresh: secrecy::SecretString::from("refresh-token".to_string()),
expires_at_ms: u64::MAX,
extra: ai_memory_llm::OidcExtras {
issuer: "https://issuer.example.com/realms/team".to_string(),
client_id: "ai-memory-cli".to_string(),
token_endpoint: "https://issuer.example.com/token".to_string(),
},
}
.save(&config.oidc_device_token_path())
.expect("save test OIDC token");
let ep = ServerEndpoint::from_config_resolving_auth(&config).await;
let client = reqwest::Client::new();
let req = ep
.authenticate(client.get("http://localhost"))
.build()
.unwrap();
let auth = req
.headers()
.get("authorization")
.expect("Authorization header must be set")
.to_str()
.unwrap();
assert_eq!(auth, "Bearer oidc-access");
}
}