Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
use serde::de::DeserializeOwned;
use serde_json::{Map, Value, json};
use std::env;
use std::path::Path;
use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64_STANDARD};
pub use crate::base_client::{BaseClient, FileUploader, TimeoutConfig};
use crate::base_client::ProgressGuard;
use crate::error::{Error, Result};
/// Drop null-valued keys (and an empty `args` object) from a request body before
/// sending it. Older, stricter servers use `extra="forbid"` and reject any field
/// they do not yet define, so unconditionally attaching optional fields (even as
/// `null`/`{}`) breaks against instances that predate that field. Omitting them is
/// safe for read/create routes where a missing optional field and an explicit
/// `null` are equivalent — do NOT use this for update/PATCH bodies where `null`
/// may mean "clear this field".
fn compact_request_body(body: &mut Value) {
let Some(obj) = body.as_object_mut() else {
return;
};
obj.retain(|key, value| {
if value.is_null() {
return false;
}
// `args` is always attached by the CLI but absent from pre-#2549 models;
// only forward it when the caller actually provided arguments.
if key == "args" {
if let Some(map) = value.as_object() {
return !map.is_empty();
}
}
if key == "processing_mode" {
return value != "semantic_and_vectors";
}
if key == "search_type" {
return value != "semantic";
}
true
});
}
fn add_resource_tag_fields(body: &mut Value, tags: &[String], tag_mode: &str) {
if tags.is_empty() && tag_mode != "clear" {
return;
}
let obj = body
.as_object_mut()
.expect("add_resource request body must be an object");
if !tags.is_empty() {
obj.insert("tags".to_string(), serde_json::json!(tags));
}
obj.insert("tag_mode".to_string(), serde_json::json!(tag_mode));
}
fn normalize_image_input(image: Option<String>) -> Result<Option<String>> {
let Some(value) = image else {
return Ok(None);
};
if value.starts_with("data:image/")
|| value.starts_with("http://")
|| value.starts_with("https://")
|| value.starts_with("viking://")
{
return Ok(Some(value));
}
let path = Path::new(&value);
if path.is_file() {
let bytes = std::fs::read(path)?;
let mime = mime_guess::from_path(path).first_or_octet_stream();
return Ok(Some(format!(
"data:{};base64,{}",
mime,
BASE64_STANDARD.encode(bytes)
)));
}
Ok(Some(value))
}
#[derive(serde::Serialize)]
pub struct SnapshotCommitReq {
pub message: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub paths: Option<Vec<String>>,
pub branch: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub author_name: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub author_email: Option<String>,
}
#[derive(serde::Serialize)]
pub struct SnapshotRestoreReq {
#[serde(skip_serializing_if = "Option::is_none")]
pub project_dir: Option<String>,
pub source_commit: String,
pub branch: String,
pub dry_run: bool,
#[serde(skip_serializing_if = "Option::is_none")]
pub message: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub author_name: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub author_email: Option<String>,
}
pub enum SnapshotShowResult {
Metadata(Value),
Blob {
oid: String,
size: u64,
bytes: Vec<u8>,
},
}
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct CompileAccepted {
pub task_id: String,
pub status: String,
#[serde(default)]
pub to: Option<String>,
#[serde(default)]
pub task_type: Option<String>,
#[serde(default)]
pub stage: Option<String>,
#[serde(default)]
pub resource_id: Option<String>,
}
#[derive(serde::Serialize)]
struct CompileCreateRequest<'a> {
#[serde(rename = "from")]
from_uris: &'a [String],
to: &'a str,
skill: &'a str,
#[serde(skip_serializing_if = "Option::is_none")]
instruction: Option<&'a str>,
#[serde(skip_serializing_if = "Option::is_none")]
args: Option<&'a serde_json::Map<String, Value>>,
}
// ============ HttpClient ============
/// High-level HTTP client for OpenViking API
#[derive(Clone)]
pub struct HttpClient {
base: BaseClient,
}
impl HttpClient {
pub fn new(
base_url: impl Into<String>,
api_key: Option<String>,
account: Option<String>,
user: Option<String>,
actor_peer_id: Option<String>,
timeout_secs: f64,
profile_enabled: bool,
extra_headers: Option<std::collections::HashMap<String, String>>,
) -> Self {
Self {
base: BaseClient::new(
base_url,
api_key,
account,
user,
actor_peer_id,
timeout_secs,
profile_enabled,
extra_headers,
),
}
}
pub fn with_gateway_token(mut self, gateway_token: Option<String>) -> Self {
self.base = self.base.with_gateway_token(gateway_token);
self
}
pub fn with_auth_mode(mut self, auth_mode: Option<String>) -> Self {
self.base = self.base.with_auth_mode(auth_mode);
self
}
pub fn with_ldap_username(mut self, username: Option<String>) -> Self {
self.base = self.base.with_ldap_username(username);
self
}
pub fn with_ldap_password(mut self, password: Option<String>) -> Self {
self.base = self.base.with_ldap_password(password);
self
}
pub fn with_oidc_token(mut self, token: Option<String>) -> Self {
self.base = self.base.with_oidc_token(token);
self
}
pub fn user_id(&self) -> Option<&str> {
self.base.user_id()
}
pub fn actor_peer_id(&self) -> Option<&str> {
self.base.actor_peer_id()
}
pub fn api_key(&self) -> Option<&str> {
self.base.api_key()
}
/// Match the server's credential selection after custom headers are applied.
pub(crate) fn request_api_key(&self) -> Option<String> {
let headers = self.base.build_headers();
headers
.get("X-API-Key")
.and_then(|value| value.to_str().ok())
.filter(|value| !value.is_empty())
.or_else(|| {
headers
.get(reqwest::header::AUTHORIZATION)
.and_then(|value| value.to_str().ok())
.and_then(|value| value.strip_prefix("Bearer "))
})
.map(str::to_owned)
}
fn upload_mode(&self) -> Option<String> {
match env::var("OPENVIKING_UPLOAD_MODE") {
Ok(value) => {
let normalized = value.trim().to_ascii_lowercase();
if normalized == "shared" || normalized == "local" {
Some(normalized)
} else {
None
}
}
Err(_) => None,
}
}
// ============ HTTP Methods ============
pub async fn get<T: DeserializeOwned + 'static>(
&self,
path: &str,
params: &[(String, String)],
) -> Result<T> {
self.base.get(path, params).await
}
pub async fn post<B: serde::Serialize, T: DeserializeOwned + 'static>(
&self,
path: &str,
body: &B,
) -> Result<T> {
self.base.post(path, body).await
}
pub async fn put<B: serde::Serialize, T: DeserializeOwned + 'static>(
&self,
path: &str,
body: &B,
) -> Result<T> {
self.base.put(path, body).await
}
pub async fn delete<T: DeserializeOwned + 'static>(
&self,
path: &str,
params: &[(String, String)],
) -> Result<T> {
self.base.delete(path, params).await
}
pub async fn delete_with_body<B: serde::Serialize, T: DeserializeOwned + 'static>(
&self,
path: &str,
body: &B,
) -> Result<T> {
self.base.delete_with_body(path, body).await
}
pub async fn patch<B: serde::Serialize, T: DeserializeOwned + 'static>(
&self,
path: &str,
body: &B,
params: &[(String, String)],
) -> Result<T> {
self.base.patch(path, body, params).await
}
pub async fn post_with_query<B: serde::Serialize, T: DeserializeOwned + 'static>(
&self,
path: &str,
body: &B,
params: &[(String, String)],
) -> Result<T> {
self.base.post_with_query(path, body, params).await
}
// ============ File Helper Methods ============
fn create_uploader(&self) -> FileUploader<'_> {
FileUploader::new(&self.base).with_upload_mode(self.upload_mode())
}
fn zip_directory(
&self,
dir_path: &Path,
ignore_dirs: Option<&str>,
) -> Result<tempfile::NamedTempFile> {
self.create_uploader().zip_directory(dir_path, ignore_dirs)
}
fn zip_directory_with_progress(
&self,
dir_path: &Path,
verbose: bool,
ignore_dirs: Option<&str>,
) -> Result<tempfile::NamedTempFile> {
self.create_uploader()
.zip_directory_with_progress(dir_path, verbose, ignore_dirs)
}
async fn upload_temp_file(&self, file_path: &Path) -> Result<String> {
self.create_uploader().upload_temp_file(file_path).await
}
async fn upload_temp_file_with_progress(
&self,
file_path: &Path,
verbose: bool,
) -> Result<String> {
self.create_uploader()
.upload_temp_file_with_progress(file_path, verbose)
.await
}
// ============ Content Methods ============
pub async fn create_compile(
&self,
from_uris: &[String],
to: &str,
skill: &str,
instruction: Option<&str>,
args: Option<&serde_json::Map<String, Value>>,
) -> Result<CompileAccepted> {
let body = CompileCreateRequest {
from_uris,
to,
skill,
instruction,
args,
};
self.post("/api/v1/compile", &body).await
}
pub async fn read(&self, uri: &str) -> Result<String> {
let params = vec![("uri".to_string(), uri.to_string())];
self.get("/api/v1/content/read", ¶ms).await
}
/// Read content and optional profiling data, propagating HTTP errors.
/// `offset` is zero-based and nonnegative; `limit` is a line count or -1 for EOF.
pub async fn read_profiled(&self, uri: &str, offset: i64, limit: i64) -> Result<Value> {
let params = vec![
("uri".to_string(), uri.to_string()),
("offset".to_string(), offset.to_string()),
("limit".to_string(), limit.to_string()),
];
self.get("/api/v1/content/read", ¶ms).await
}
pub async fn abstract_content(&self, uri: &str) -> Result<String> {
let params = vec![("uri".to_string(), uri.to_string())];
self.get("/api/v1/content/abstract", ¶ms).await
}
pub async fn abstract_content_profiled(&self, uri: &str) -> Result<Value> {
let params = vec![("uri".to_string(), uri.to_string())];
self.get("/api/v1/content/abstract", ¶ms).await
}
pub async fn overview(&self, uri: &str) -> Result<String> {
let params = vec![("uri".to_string(), uri.to_string())];
self.get("/api/v1/content/overview", ¶ms).await
}
pub async fn overview_profiled(&self, uri: &str) -> Result<Value> {
let params = vec![("uri".to_string(), uri.to_string())];
self.get("/api/v1/content/overview", ¶ms).await
}
pub async fn write(
&self,
uri: &str,
content: &str,
mode: &str,
wait: bool,
processing_mode: &str,
tags: Vec<String>,
tag_mode: &str,
acl: Option<Value>,
edit_source: &str,
) -> Result<serde_json::Value> {
let mut body = Self::build_write_body(uri, content, mode, wait, processing_mode);
add_resource_tag_fields(&mut body, &tags, tag_mode);
if let Some(acl) = acl {
body["acl"] = acl;
}
// Omit the default so the request stays valid for servers without edit_source.
if edit_source != "agent" {
body["edit_source"] = Value::from(edit_source);
}
self.post("/api/v1/content/write", &body).await
}
pub async fn set_tags(
&self,
uri: &str,
tags: Vec<String>,
mode: &str,
recursive: bool,
) -> Result<serde_json::Value> {
let body = serde_json::json!({
"uri": uri,
"tags": tags,
"mode": mode,
"recursive": recursive,
});
self.post("/api/v1/fs/attrs/set_tags", &body).await
}
pub async fn acl_get(&self, uri: &str) -> Result<Value> {
self.get("/api/v1/acl", &[("uri".to_string(), uri.to_string())])
.await
}
pub async fn acl_set(
&self,
uri: &str,
entries: Vec<Value>,
acl_mode: Option<String>,
) -> Result<Value> {
let mut body = serde_json::json!({"uri": uri});
if !entries.is_empty() {
body["entries"] = serde_json::Value::Array(entries);
}
if let Some(acl_mode) = acl_mode {
body["acl_mode"] = serde_json::Value::String(acl_mode);
}
self.put("/api/v1/acl", &body).await
}
pub async fn acl_grant(&self, uri: &str, principal: &str, level: &str) -> Result<Value> {
self.post(
"/api/v1/acl/grant",
&serde_json::json!({"uri": uri, "principal": principal, "level": level}),
)
.await
}
pub async fn acl_revoke(&self, uri: &str, principal: &str) -> Result<Value> {
self.post(
"/api/v1/acl/revoke",
&serde_json::json!({"uri": uri, "principal": principal}),
)
.await
}
pub async fn acl_delete(&self, uri: &str) -> Result<Value> {
self.delete("/api/v1/acl", &[("uri".to_string(), uri.to_string())])
.await
}
fn build_write_body(
uri: &str,
content: &str,
mode: &str,
wait: bool,
processing_mode: &str,
) -> Value {
let mut body = serde_json::json!({
"uri": uri,
"content": content,
"mode": mode,
"wait": wait,
"processing_mode": processing_mode,
});
compact_request_body(&mut body);
body
}
pub async fn reindex(
&self,
uri: &str,
mode: &str,
wait: bool,
force: bool,
tags: Vec<String>,
tag_mode: &str,
recursive: bool,
) -> Result<serde_json::Value> {
let mut body = serde_json::json!({
"uri": uri,
"mode": mode,
"wait": wait,
});
if force {
body["force"] = serde_json::json!(true);
}
if !recursive {
body["recursive"] = serde_json::json!(false);
}
add_resource_tag_fields(&mut body, &tags, tag_mode);
self.post("/api/v1/content/reindex", &body).await
}
pub async fn consistency(&self, uri: &str) -> Result<serde_json::Value> {
let body = serde_json::json!({
"uri": uri,
});
self.post("/api/v1/system/consistency", &body).await
}
/// Download file as raw bytes
pub async fn get_bytes(&self, uri: &str) -> Result<Vec<u8>> {
let url = format!("{}/api/v1/content/download", self.base.base_url);
let params = vec![
("uri".to_string(), uri.to_string()),
("profile".to_string(), "0".to_string()),
];
let request = self
.base
.http
.get(&url)
.headers(self.base.build_headers())
.query(¶ms);
let response = self
.base
.send_request(request, "HTTP request failed")
.await?;
let status = response.status();
if !status.is_success() {
let bytes = response
.bytes()
.await
.map_err(|e| Error::from_reqwest("Failed to read error response", e))?;
return Err(crate::base_client::api_error_from_body(&bytes, status));
}
response
.bytes()
.await
.map(|b| b.to_vec())
.map_err(|e| Error::from_reqwest("Failed to read response bytes", e))
}
// ============ Filesystem Methods ============
pub async fn ls(
&self,
uri: &str,
simple: bool,
recursive: bool,
output: &str,
abs_limit: i32,
include_abstract: Option<bool>,
include_overview: Option<bool>,
overview_limit: i32,
show_all_hidden: bool,
node_limit: i32,
offset: i32,
limit: Option<i32>,
sort_by: Option<&str>,
sort_order: Option<&str>,
extra_fields: &[String],
tags: &[String],
include_tags: bool,
) -> Result<serde_json::Value> {
let mut params = vec![
("uri".to_string(), uri.to_string()),
("simple".to_string(), simple.to_string()),
("recursive".to_string(), recursive.to_string()),
("output".to_string(), output.to_string()),
("abs_limit".to_string(), abs_limit.to_string()),
("overview_limit".to_string(), overview_limit.to_string()),
("show_all_hidden".to_string(), show_all_hidden.to_string()),
("node_limit".to_string(), node_limit.to_string()),
];
if let Some(value) = include_abstract {
params.push(("include_abstract".to_string(), value.to_string()));
}
if let Some(value) = include_overview {
params.push(("include_overview".to_string(), value.to_string()));
}
if offset != 0 {
params.push(("offset".to_string(), offset.to_string()));
}
if let Some(limit) = limit {
params.push(("limit".to_string(), limit.to_string()));
}
if let Some(sort_by) = sort_by {
params.push(("sort_by".to_string(), sort_by.to_string()));
if let Some(sort_order) = sort_order {
params.push(("sort_order".to_string(), sort_order.to_string()));
}
}
for field in extra_fields {
params.push(("extra_fields".to_string(), field.clone()));
}
for tag in tags {
params.push(("tags".to_string(), tag.clone()));
}
if include_tags {
params.push(("include_tags".to_string(), "true".to_string()));
}
self.get("/api/v1/fs/ls", ¶ms).await
}
pub async fn tree(
&self,
uri: &str,
output: &str,
abs_limit: i32,
include_abstract: Option<bool>,
include_overview: Option<bool>,
overview_limit: i32,
show_all_hidden: bool,
directories_only: bool,
node_limit: i32,
level_limit: i32,
offset: i32,
limit: Option<i32>,
extra_fields: &[String],
tags: &[String],
include_tags: bool,
) -> Result<serde_json::Value> {
let mut params = vec![
("uri".to_string(), uri.to_string()),
("output".to_string(), output.to_string()),
("abs_limit".to_string(), abs_limit.to_string()),
("show_all_hidden".to_string(), show_all_hidden.to_string()),
("node_limit".to_string(), node_limit.to_string()),
("level_limit".to_string(), level_limit.to_string()),
("overview_limit".to_string(), overview_limit.to_string()),
];
if let Some(value) = include_abstract {
params.push(("include_abstract".to_string(), value.to_string()));
}
if let Some(value) = include_overview {
params.push(("include_overview".to_string(), value.to_string()));
}
if directories_only {
params.push(("directories_only".to_string(), "true".to_string()));
}
if offset != 0 {
params.push(("offset".to_string(), offset.to_string()));
}
if let Some(limit) = limit {
params.push(("limit".to_string(), limit.to_string()));
}
for field in extra_fields {
params.push(("extra_fields".to_string(), field.clone()));
}
for tag in tags {
params.push(("tags".to_string(), tag.clone()));
}
if include_tags {
params.push(("include_tags".to_string(), "true".to_string()));
}
self.get("/api/v1/fs/tree", ¶ms).await
}
pub async fn mkdir(
&self,
uri: &str,
description: Option<&str>,
acl: Option<Value>,
) -> Result<serde_json::Value> {
let mut body = match description {
Some(description) => serde_json::json!({ "uri": uri, "description": description }),
None => serde_json::json!({ "uri": uri }),
};
if let Some(acl) = acl {
body["acl"] = acl;
}
self.post("/api/v1/fs/mkdir", &body).await
}
pub async fn rm(
&self,
uri: &str,
recursive: bool,
wait: bool,
) -> Result<serde_json::Value> {
let params = vec![
("uri".to_string(), uri.to_string()),
("recursive".to_string(), recursive.to_string()),
("wait".to_string(), wait.to_string()),
];
self.delete("/api/v1/fs", ¶ms).await
}
pub async fn mv(&self, from_uri: &str, to_uri: &str) -> Result<serde_json::Value> {
let body = serde_json::json!({
"from_uri": from_uri,
"to_uri": to_uri,
});
self.post("/api/v1/fs/mv", &body).await
}
pub async fn cp(
&self,
from_uri: &str,
to_uri: &str,
recursive: bool,
) -> Result<serde_json::Value> {
let body = serde_json::json!({
"from_uri": from_uri,
"to_uri": to_uri,
"recursive": recursive,
});
self.post("/api/v1/fs/cp", &body).await
}
pub async fn stat(&self, uri: &str) -> Result<serde_json::Value> {
let params = vec![("uri".to_string(), uri.to_string())];
self.get("/api/v1/fs/stat", ¶ms).await
}
pub async fn attrs(&self, uri: &str) -> Result<serde_json::Value> {
let params = vec![("uri".to_string(), uri.to_string())];
self.get("/api/v1/fs/attrs", ¶ms).await
}
// ============ Search Methods ============
pub async fn find(
&self,
query: String,
uri: String,
image: Option<String>,
node_limit: i32,
threshold: Option<f64>,
since: Option<String>,
until: Option<String>,
time_field: Option<String>,
level: Option<Vec<i32>>,
context_type: Option<Vec<String>>,
tags: Option<Vec<String>>,
read_content: bool,
events_time_decay_protection: Option<String>,
) -> Result<serde_json::Value> {
let image_url = normalize_image_input(image)?;
let mut body = serde_json::json!({
"query": query,
"image_url": image_url,
"target_uri": uri,
"limit": node_limit,
"score_threshold": threshold,
"since": since,
"until": until,
"time_field": time_field,
"level": level,
"context_type": context_type,
"tags": tags,
"read_content": read_content.then_some(true),
"events_time_decay_protection": events_time_decay_protection,
});
compact_request_body(&mut body);
self.post("/api/v1/search/find", &body).await
}
pub async fn search(
&self,
query: String,
uri: String,
image: Option<String>,
search_type: String,
mode: String,
session_id: Option<String>,
node_limit: i32,
threshold: Option<f64>,
since: Option<String>,
until: Option<String>,
time_field: Option<String>,
level: Option<Vec<i32>>,
context_type: Option<Vec<String>>,
tags: Option<Vec<String>>,
read_content: bool,
events_time_decay_protection: Option<String>,
) -> Result<serde_json::Value> {
let image_url = normalize_image_input(image)?;
let mut body = serde_json::json!({
"query": query,
"image_url": image_url,
"search_type": search_type,
// Preserve the legacy request shape for servers without context mode.
"mode": (mode != "list").then_some(mode),
"target_uri": uri,
"session_id": session_id,
"limit": node_limit,
"score_threshold": threshold,
"since": since,
"until": until,
"time_field": time_field,
"level": level,
"context_type": context_type,
"tags": tags,
"read_content": read_content.then_some(true),
"events_time_decay_protection": events_time_decay_protection,
});
compact_request_body(&mut body);
self.post("/api/v1/search/search", &body).await
}
pub async fn grep(
&self,
uri: &str,
exclude_uri: Option<String>,
pattern: &str,
ignore_case: bool,
after_context: i32,
before_context: i32,
node_limit: i32,
level_limit: i32,
tags: &[String],
include_tags: bool,
) -> Result<serde_json::Value> {
let mut body = serde_json::json!({
"uri": uri,
"exclude_uri": exclude_uri,
"pattern": pattern,
"case_insensitive": ignore_case,
"after_context": (after_context > 0).then_some(after_context),
"before_context": (before_context > 0).then_some(before_context),
"node_limit": node_limit,
"level_limit": level_limit,
"tags": (!tags.is_empty()).then(|| tags),
"include_tags": include_tags.then_some(true),
});
compact_request_body(&mut body);
self.post("/api/v1/search/grep", &body).await
}
pub async fn glob(
&self,
pattern: &str,
uri: &str,
node_limit: i32,
extra_fields: Option<&[String]>,
tags: &[String],
include_tags: bool,
) -> Result<serde_json::Value> {
let mut body = serde_json::json!({
"pattern": pattern,
"uri": uri,
"node_limit": node_limit,
"tags": (!tags.is_empty()).then(|| tags),
"include_tags": include_tags.then_some(true),
});
if let Some(fields) = extra_fields {
body["extra_fields"] = serde_json::json!(fields);
}
compact_request_body(&mut body);
self.post("/api/v1/search/glob", &body).await
}
// ============ Resource Methods ============
pub async fn add_resource(
&self,
path: &str,
add_type: Option<String>,
to: Option<String>,
parent: Option<String>,
parent_auto_create: Option<String>,
reason: &str,
instruction: &str,
wait: bool,
strict: bool,
ignore_dirs: Option<String>,
include: Option<String>,
exclude: Option<String>,
directly_upload_media: bool,
watch_interval: f64,
processing_mode: String,
resource_args: Option<Map<String, Value>>,
tags: Vec<String>,
tag_mode: String,
acl: Option<Value>,
show_progress: bool,
verbose: bool,
) -> Result<serde_json::Value> {
let path_obj = Path::new(path);
let args = Value::Object(resource_args.unwrap_or_default());
// Determine effective parent and create_parent flag.
// Only send create_parent when the user explicitly selected
// --parent-auto-create, so older servers that do not support the
// field still accept the request.
let (effective_parent, create_parent) = match (parent, parent_auto_create) {
(Some(p), None) => (Some(p), false),
(None, Some(p)) => (Some(p), true),
(None, None) => (None, false),
(Some(_), Some(_)) => unreachable!("handled in cli"),
};
let build_body = |base: serde_json::Value| {
let mut body = base;
if let Some(acl) = &acl {
body["acl"] = acl.clone();
}
add_resource_tag_fields(&mut body, &tags, &tag_mode);
if create_parent {
body.as_object_mut()
.expect("add_resource request body must be an object")
.insert("create_parent".to_string(), serde_json::Value::Bool(true));
}
compact_request_body(&mut body);
body
};
// A declared Connector add_type sends the path verbatim as a remote
// source; never interpret it as a local file to upload.
let submitted: Value = if add_type.is_none() && path_obj.exists() {
if path_obj.is_dir() {
let source_name = path_obj
.file_name()
.and_then(|n| n.to_str())
.map(|s| s.to_string());
let zip_file = if show_progress {
self.zip_directory_with_progress(path_obj, verbose, ignore_dirs.as_deref())?
} else {
self.zip_directory(path_obj, ignore_dirs.as_deref())?
};
let temp_file_id = if show_progress {
self.upload_temp_file_with_progress(zip_file.path(), verbose)
.await?
} else {
self.upload_temp_file(zip_file.path()).await?
};
let body = build_body(serde_json::json!({
"temp_file_id": temp_file_id,
"source_name": source_name,
"to": to,
"parent": effective_parent,
"reason": reason,
"instruction": instruction,
"wait": false,
"strict": strict,
"ignore_dirs": ignore_dirs,
"include": include,
"exclude": exclude,
"directly_upload_media": directly_upload_media,
"watch_interval": watch_interval,
"processing_mode": processing_mode.as_str(),
"args": args.clone(),
}));
let dynamic_timeout =
TimeoutConfig::for_resource_processing().calculate(zip_file.path())?;
self.base
.post_with_timeout("/api/v1/resources", &body, dynamic_timeout)
.await
} else if path_obj.is_file() {
let source_name = path_obj
.file_name()
.and_then(|n| n.to_str())
.map(|s| s.to_string());
let temp_file_id = if show_progress {
self.upload_temp_file_with_progress(path_obj, verbose)
.await?
} else {
self.upload_temp_file(path_obj).await?
};
let body = build_body(serde_json::json!({
"temp_file_id": temp_file_id,
"source_name": source_name,
"to": to,
"parent": effective_parent,
"reason": reason,
"instruction": instruction,
"wait": false,
"strict": strict,
"ignore_dirs": ignore_dirs,
"include": include,
"exclude": exclude,
"directly_upload_media": directly_upload_media,
"watch_interval": watch_interval,
"processing_mode": processing_mode.as_str(),
"args": args.clone(),
}));
let dynamic_timeout =
TimeoutConfig::for_resource_processing().calculate(path_obj)?;
self.base
.post_with_timeout("/api/v1/resources", &body, dynamic_timeout)
.await
} else {
let body = build_body(serde_json::json!({
"path": path,
"to": to,
"parent": effective_parent,
"reason": reason,
"instruction": instruction,
"wait": false,
"strict": strict,
"ignore_dirs": ignore_dirs,
"include": include,
"exclude": exclude,
"directly_upload_media": directly_upload_media,
"watch_interval": watch_interval,
"processing_mode": processing_mode.as_str(),
"args": args.clone(),
}));
self.post("/api/v1/resources", &body).await
}
} else {
let body = build_body(serde_json::json!({
"path": path,
"add_type": add_type,
"to": to,
"parent": effective_parent,
"reason": reason,
"instruction": instruction,
"wait": false,
"strict": strict,
"ignore_dirs": ignore_dirs,
"include": include,
"exclude": exclude,
"directly_upload_media": directly_upload_media,
"watch_interval": watch_interval,
"processing_mode": processing_mode.as_str(),
"args": args,
}));
self.post("/api/v1/resources", &body).await
}?;
if !wait {
return Ok(submitted);
}
let task_id = submitted
.get("task_id")
.and_then(Value::as_str)
.filter(|id| !id.is_empty())
.ok_or_else(|| {
Error::Client(
"Import response has no task_id; cannot wait for completion. \
Check 'ov task list' before submitting again."
.to_string(),
)
})?;
self.wait_for_resource_task(
task_id,
tokio::signal::ctrl_c(),
std::time::Duration::from_secs(1),
)
.await
}
/// Wait without an overall deadline. Each status GET retains the ordinary
/// HTTP timeout. Consecutive observation failures are bounded, and retries
/// never resubmit the import.
async fn wait_for_resource_task(
&self,
task_id: &str,
interrupted: impl std::future::Future<Output = std::io::Result<()>>,
interval: std::time::Duration,
) -> Result<Value> {
tokio::pin!(interrupted);
let observation_error = |error: Error| {
let code = Some(error.code().to_string());
let (message, details, status) = match error {
Error::Api {
message,
details,
status,
..
} => (message, details, status),
other => (other.to_string(), None, None),
};
Error::Api {
code,
message: format!(
"{message}; task continues on the server; check with: ov task status {task_id}"
),
details: Some(json!({"task_id": task_id, "details": details})),
status,
}
};
let poll = async {
let mut retry_delay = interval;
let mut failures = 0;
loop {
let task = match self.get_task(task_id).await {
Ok(task) => {
retry_delay = interval;
failures = 0;
task
}
Err(err)
if matches!(
err,
Error::Timeout(_)
| Error::Network(_)
| Error::Api {
status: Some(429 | 502 | 503 | 504),
..
}
) =>
{
failures += 1;
if failures >= 10 {
return Err(observation_error(err));
}
tokio::time::sleep(retry_delay).await;
retry_delay = (retry_delay * 2).min(interval * 5);
continue;
}
Err(err) => return Err(observation_error(err)),
};
match task.get("status").and_then(Value::as_str) {
Some("completed") => {
let mut result = task.get("result").cloned().ok_or_else(|| {
observation_error(Error::Parse(format!(
"Completed task {task_id} has no result"
)))
})?;
if !result.is_object() {
return Err(observation_error(Error::Parse(format!(
"Completed task {task_id} has an invalid result"
))));
}
// Return the task result plus task_id for inspection.
// The server's wait=true response omits this extra field.
result["task_id"] = json!(task_id);
return Ok(result);
}
Some("cancelled") => {
// 服务端取消任务时会清空 result 和 error,需显式保留取消语义。
return Err(Error::Api {
code: Some("CANCELLED".into()),
message: format!(
"Task {task_id} cancelled; check with: ov task status {task_id}"
),
details: Some(json!({"task_id": task_id, "status": "cancelled"})),
status: None,
});
}
Some("failed") => {
let result = &task["result"];
return Err(Error::Api {
code: result["code"].as_str().map(str::to_string),
message: format!(
"Task {task_id} failed: {}",
task["error"]
.as_str()
.unwrap_or("resource processing failed")
),
details: Some(json!({
"task_id": task_id,
"status": "failed",
"details": result.get("details"),
})),
status: None,
});
}
Some("pending" | "running" | "cancelling") => {}
_ => {
return Err(observation_error(Error::Parse(format!(
"Task {task_id} returned an invalid status"
))));
}
}
tokio::time::sleep(interval).await;
}
};
tokio::select! {
result = poll => result,
signal = &mut interrupted => {
signal.map_err(|error| observation_error(Error::Io(error)))?;
Err(Error::Api {
code: Some("INTERRUPTED".into()),
message: format!("Stopped waiting. The server task was not cancelled. Check progress with: ov task status {task_id}"),
details: Some(json!({"task_id": task_id})),
status: None,
})
}
}
}
pub async fn add_skill(
&self,
data: &str,
wait: bool,
show_progress: bool,
verbose: bool,
source_metadata: Option<Value>,
target_uri: Option<&str>,
skills: &[String],
list_only: bool,
) -> Result<serde_json::Value> {
let path = Path::new(data);
let mut body = json!({"wait": wait});
if !skills.is_empty() {
body["skills"] = json!(skills);
}
if list_only {
body["list_only"] = json!(true);
}
if let Some(target_uri) = target_uri {
body["target_uri"] = json!(target_uri);
}
if let Some(metadata) = source_metadata {
body["source_metadata"] = metadata;
} else if path.exists() {
body["source_metadata"] = json!({"type": "local", "source": data, "path": data});
}
if path.is_dir() || path.is_file() {
let archive = if path.is_dir() {
Some(if show_progress {
self.zip_directory_with_progress(path, verbose, None)?
} else {
self.zip_directory(path, None)?
})
} else {
None
};
let upload = archive.as_ref().map(|file| file.path()).unwrap_or(path);
let id = if show_progress {
self.upload_temp_file_with_progress(upload, verbose).await?
} else {
self.upload_temp_file(upload).await?
};
body["temp_file_id"] = json!(id);
let dynamic_timeout = TimeoutConfig::for_resource_processing().calculate(upload)?;
self.base
.post_with_timeout("/api/v1/skills", &body, dynamic_timeout)
.await
} else {
body["data"] = json!(data);
self.post("/api/v1/skills", &body).await
}
}
pub async fn skills_list(
&self,
node_limit: i32,
target_uri: Option<&str>,
) -> Result<serde_json::Value> {
let mut params = vec![("node_limit".to_string(), node_limit.to_string())];
if let Some(target_uri) = target_uri {
params.push(("target_uri".to_string(), target_uri.to_string()));
}
self.get("/api/v1/skills", ¶ms).await
}
pub async fn skill_show(
&self,
name: &str,
include_content: bool,
include_files: bool,
include_source: bool,
level: Option<i32>,
target_uri: Option<&str>,
) -> Result<serde_json::Value> {
let path = format!("/api/v1/skills/{}", name);
let mut params = vec![
("include_content".to_string(), include_content.to_string()),
("include_files".to_string(), include_files.to_string()),
("include_source".to_string(), include_source.to_string()),
];
if let Some(level) = level {
params.push(("level".to_string(), level.to_string()));
}
if let Some(target_uri) = target_uri {
params.push(("target_uri".to_string(), target_uri.to_string()));
}
self.get(&path, ¶ms).await
}
pub async fn skill_find(
&self,
query: &str,
node_limit: i32,
threshold: Option<f64>,
level: Option<Vec<i32>>,
target_uri: Option<&str>,
) -> Result<serde_json::Value> {
let mut body = serde_json::json!({
"query": query,
"limit": node_limit,
"score_threshold": threshold,
"level": level,
});
if let Some(target_uri) = target_uri {
body["target_uri"] = serde_json::Value::String(target_uri.to_string());
}
self.post("/api/v1/skills/find", &body).await
}
pub async fn skill_validate(&self, path: &str, strict: bool) -> Result<serde_json::Value> {
let path_obj = Path::new(path);
if !path_obj.exists() {
return Err(Error::Client(format!(
"Skill path '{}' does not exist.",
path
)));
}
let skill_file = if path_obj.is_dir() {
let skill_file = path_obj.join("SKILL.md");
if !skill_file.is_file() {
return Err(Error::Client(format!(
"SKILL.md not found in '{}'.",
path_obj.display()
)));
}
skill_file
} else if path_obj.is_file() {
if path_obj.file_name().and_then(|name| name.to_str()) != Some("SKILL.md") {
return Err(Error::Client(
"Validate expects a SKILL.md file or a skill directory.".to_string(),
));
}
path_obj.to_path_buf()
} else {
return Err(Error::Client(format!(
"Skill path '{}' is not a file or directory.",
path
)));
};
let content = std::fs::read_to_string(&skill_file).map_err(|e| {
Error::Client(format!(
"Failed to read skill file '{}': {}",
skill_file.display(),
e
))
})?;
let skill_dir_name = skill_file
.parent()
.and_then(|parent| parent.file_name())
.and_then(|name| name.to_str())
.unwrap_or("")
.to_string();
let body = serde_json::json!({
"data": content,
"strict": strict,
"source_path": skill_file.to_string_lossy(),
"skill_dir_name": skill_dir_name,
});
self.post("/api/v1/skills/validate", &body).await
}
pub async fn skill_update(
&self,
name: &str,
data: &str,
wait: bool,
show_progress: bool,
verbose: bool,
source_metadata: Option<Value>,
target_uri: Option<&str>,
) -> Result<serde_json::Value> {
let endpoint = format!("/api/v1/skills/{}", name);
let path_obj = Path::new(data);
let attach_target_uri = |body: &mut Value| {
if let Some(target_uri) = target_uri {
body["target_uri"] = serde_json::Value::String(target_uri.to_string());
}
};
if path_obj.exists() {
if path_obj.is_dir() {
let zip_file = if show_progress {
self.zip_directory_with_progress(path_obj, verbose, None)?
} else {
self.zip_directory(path_obj, None)?
};
let temp_file_id = if show_progress {
self.upload_temp_file_with_progress(zip_file.path(), verbose)
.await?
} else {
self.upload_temp_file(zip_file.path()).await?
};
let mut body = serde_json::json!({
"temp_file_id": temp_file_id,
"wait": wait,
});
if let Some(source_metadata) = source_metadata.clone() {
body["source_metadata"] = source_metadata;
}
attach_target_uri(&mut body);
self.put(&endpoint, &body).await
} else if path_obj.is_file() {
let temp_file_id = if show_progress {
self.upload_temp_file_with_progress(path_obj, verbose)
.await?
} else {
self.upload_temp_file(path_obj).await?
};
let mut body = serde_json::json!({
"temp_file_id": temp_file_id,
"wait": wait,
});
if let Some(source_metadata) = source_metadata.clone() {
body["source_metadata"] = source_metadata;
}
attach_target_uri(&mut body);
self.put(&endpoint, &body).await
} else {
let mut body = serde_json::json!({
"data": data,
"wait": wait,
});
if let Some(source_metadata) = source_metadata.clone() {
body["source_metadata"] = source_metadata;
}
attach_target_uri(&mut body);
self.put(&endpoint, &body).await
}
} else {
let mut body = serde_json::json!({
"data": data,
"wait": wait,
});
if let Some(source_metadata) = source_metadata {
body["source_metadata"] = source_metadata;
}
attach_target_uri(&mut body);
self.put(&endpoint, &body).await
}
}
pub async fn skill_remove(
&self,
name: &str,
target_uri: Option<&str>,
) -> Result<serde_json::Value> {
let path = format!("/api/v1/skills/{}", name);
let params: Vec<(String, String)> = if let Some(target_uri) = target_uri {
vec![("target_uri".to_string(), target_uri.to_string())]
} else {
Vec::new()
};
self.delete(&path, ¶ms).await
}
// ============ Task Methods ============
pub async fn get_task(&self, task_id: &str) -> Result<serde_json::Value> {
let path = format!("/api/v1/tasks/{task_id}");
self.get(&path, &[]).await
}
pub async fn cancel_task(&self, task_id: &str) -> Result<serde_json::Value> {
let path = format!("/api/v1/tasks/{task_id}/cancel");
self.post(&path, &serde_json::json!({})).await
}
pub async fn list_tasks(
&self,
task_type: Option<&str>,
status: Option<&str>,
) -> Result<serde_json::Value> {
let mut params: Vec<(String, String)> = Vec::new();
if let Some(t) = task_type {
params.push(("task_type".to_string(), t.to_string()));
}
if let Some(s) = status {
params.push(("status".to_string(), s.to_string()));
}
self.get("/api/v1/tasks", ¶ms).await
}
// ============ Pack Methods ============
async fn download_pack(
&self,
endpoint: &str,
body: serde_json::Value,
to: &str,
default_name: &str,
show_progress: bool,
) -> Result<String> {
let url = format!("{}{}", self.base.base_url, endpoint);
let request = self
.base
.http
.post(&url)
.headers(self.base.build_headers())
.json(&body)
.query(&[("profile", "0")]);
let progress = show_progress.then(|| {
ProgressGuard::new("Preparing OVPack on server", "OVPack download failed")
});
let response = self
.base
.send_request(request, "HTTP request failed")
.await?;
let status = response.status();
if !status.is_success() {
let bytes = response
.bytes()
.await
.map_err(|e| Error::from_reqwest("Failed to read error response", e))?;
return Err(crate::base_client::api_error_from_body(&bytes, status));
}
if let Some(progress) = &progress {
progress.set_message("Downloading OVPack");
}
let bytes = response
.bytes()
.await
.map_err(|e| Error::from_reqwest("Failed to read response bytes", e))?;
let to_path = Path::new(to);
let final_path = if to_path.is_dir() {
to_path.join(format!("{}.ovpack", default_name))
} else if !to.ends_with(".ovpack") {
Path::new(&format!("{}.ovpack", to)).to_path_buf()
} else {
to_path.to_path_buf()
};
if let Some(parent) = final_path.parent() {
std::fs::create_dir_all(parent)?;
}
std::fs::write(&final_path, bytes)?;
if let Some(progress) = progress {
progress.finish("OVPack download complete");
}
Ok(final_path.to_string_lossy().to_string())
}
async fn post_pack_operation(
&self,
endpoint: &str,
body: &serde_json::Value,
show_progress: bool,
message: &str,
) -> Result<serde_json::Value> {
let processing = show_progress
.then(|| ProgressGuard::new(message, "OVPack processing failed"));
let result = self.post(endpoint, body).await?;
if let Some(processing) = processing {
processing.finish("OVPack processing complete");
}
Ok(result)
}
pub async fn export_ovpack(
&self,
uri: &str,
to: &str,
include_vectors: bool,
show_progress: bool,
) -> Result<String> {
let body = serde_json::json!({
"uri": uri,
"include_vectors": include_vectors,
});
let base_name = uri
.trim_end_matches('/')
.split('/')
.last()
.unwrap_or("export");
self.download_pack("/api/v1/pack/export", body, to, base_name, show_progress)
.await
}
pub async fn backup_ovpack(
&self,
to: &str,
include_vectors: bool,
show_progress: bool,
) -> Result<String> {
self.download_pack(
"/api/v1/pack/backup",
serde_json::json!({"include_vectors": include_vectors}),
to,
"openviking-backup",
show_progress,
)
.await
}
pub async fn import_ovpack(
&self,
file_path: &str,
parent: &str,
on_conflict: Option<&str>,
vector_mode: Option<&str>,
show_progress: bool,
) -> Result<serde_json::Value> {
let file_path_obj = Path::new(file_path);
if !file_path_obj.exists() {
return Err(Error::Client(format!(
"Local ovpack file not found: {}",
file_path
)));
}
if !file_path_obj.is_file() {
return Err(Error::Client(format!("Path is not a file: {}", file_path)));
}
let temp_file_id = if show_progress {
self.upload_temp_file_with_progress(file_path_obj, false)
.await?
} else {
self.upload_temp_file(file_path_obj).await?
};
let conflict_policy = on_conflict.unwrap_or("fail");
let body = serde_json::json!({
"temp_file_id": temp_file_id,
"parent": parent,
"on_conflict": conflict_policy,
"vector_mode": vector_mode.unwrap_or("auto"),
});
self.post_pack_operation(
"/api/v1/pack/import",
&body,
show_progress,
"Validating and importing OVPack on server",
)
.await
}
pub async fn restore_ovpack(
&self,
file_path: &str,
on_conflict: Option<&str>,
vector_mode: Option<&str>,
show_progress: bool,
) -> Result<serde_json::Value> {
let file_path_obj = Path::new(file_path);
if !file_path_obj.exists() {
return Err(Error::Client(format!(
"Local ovpack file not found: {}",
file_path
)));
}
if !file_path_obj.is_file() {
return Err(Error::Client(format!("Path is not a file: {}", file_path)));
}
let temp_file_id = if show_progress {
self.upload_temp_file_with_progress(file_path_obj, false)
.await?
} else {
self.upload_temp_file(file_path_obj).await?
};
let conflict_policy = on_conflict.unwrap_or("fail");
let body = serde_json::json!({
"temp_file_id": temp_file_id,
"on_conflict": conflict_policy,
"vector_mode": vector_mode.unwrap_or("auto"),
});
self.post_pack_operation(
"/api/v1/pack/restore",
&body,
show_progress,
"Validating and restoring OVPack on server",
)
.await
}
// ============ Admin Methods ============
pub async fn admin_create_account(
&self,
account_id: &str,
admin_user_id: &str,
seed: Option<&str>,
user_config: Option<&Value>,
) -> Result<Value> {
let mut body = Map::new();
body.insert(
"account_id".to_string(),
Value::String(account_id.to_string()),
);
body.insert(
"admin_user_id".to_string(),
Value::String(admin_user_id.to_string()),
);
if let Some(config) = user_config {
body.insert("user_config".to_string(), config.clone());
}
if let Some(seed) = seed {
body.insert("seed".to_string(), Value::String(seed.to_string()));
}
self.post("/api/v1/admin/accounts", &Value::Object(body))
.await
}
pub async fn admin_list_accounts(
&self,
name: Option<String>,
limit: Option<u32>,
page: u32,
) -> Result<Value> {
let mut params = vec![];
if let Some(n) = name {
params.push(("name".to_string(), n));
}
if let Some(l) = limit {
params.push(("limit".to_string(), l.to_string()));
params.push(("page".to_string(), page.to_string()));
}
self.get("/api/v1/admin/accounts", ¶ms).await
}
pub async fn admin_delete_account(&self, account_id: &str) -> Result<Value> {
let path = format!("/api/v1/admin/accounts/{}", account_id);
self.delete(&path, &[]).await
}
pub async fn admin_set_account_acl_enabled(
&self,
account_id: &str,
enabled: bool,
) -> Result<Value> {
let path = format!("/api/v1/admin/accounts/{}/settings", account_id);
self.patch(
&path,
&serde_json::json!({
"acl": {
"enabled": enabled,
}
}),
&[],
)
.await
}
pub async fn admin_register_user(
&self,
account_id: &str,
user_id: &str,
role: &str,
seed: Option<&str>,
user_config: Option<&Value>,
) -> Result<Value> {
let path = format!("/api/v1/admin/accounts/{}/users", account_id);
let mut body = Map::new();
body.insert("user_id".to_string(), Value::String(user_id.to_string()));
body.insert("role".to_string(), Value::String(role.to_string()));
if let Some(config) = user_config {
body.insert("user_config".to_string(), config.clone());
}
if let Some(seed) = seed {
body.insert("seed".to_string(), Value::String(seed.to_string()));
}
self.post(&path, &Value::Object(body)).await
}
pub async fn admin_list_users(
&self,
account_id: &str,
limit: Option<u32>,
name: Option<String>,
role: Option<String>,
page: u32,
) -> Result<Value> {
let path = format!("/api/v1/admin/accounts/{}/users", account_id);
let mut params = vec![];
if let Some(l) = limit {
params.push(("limit".to_string(), l.to_string()));
params.push(("page".to_string(), page.to_string()));
}
if let Some(n) = name {
params.push(("name".to_string(), n));
}
if let Some(r) = role {
params.push(("role".to_string(), r));
}
self.get(&path, ¶ms).await
}
pub async fn admin_remove_user(&self, account_id: &str, user_id: &str) -> Result<Value> {
let path = format!("/api/v1/admin/accounts/{}/users/{}", account_id, user_id);
self.delete(&path, &[]).await
}
pub async fn admin_set_role(
&self,
account_id: &str,
user_id: &str,
role: &str,
) -> Result<Value> {
let path = format!(
"/api/v1/admin/accounts/{}/users/{}/role",
account_id, user_id
);
let body = serde_json::json!({ "role": role });
self.put(&path, &body).await
}
pub async fn admin_regenerate_key(
&self,
account_id: &str,
user_id: &str,
seed: Option<&str>,
) -> Result<Value> {
let path = format!(
"/api/v1/admin/accounts/{}/users/{}/key",
account_id, user_id
);
let body = match seed {
Some(seed) => serde_json::json!({ "seed": seed }),
None => serde_json::json!({}),
};
self.post(&path, &body).await
}
pub async fn admin_create_group(&self, account_id: &str, group_id: &str) -> Result<Value> {
let path = format!("/api/v1/admin/accounts/{}/groups", account_id);
self.post(&path, &serde_json::json!({"group_id": group_id}))
.await
}
pub async fn admin_list_groups(&self, account_id: &str) -> Result<Value> {
let path = format!("/api/v1/admin/accounts/{}/groups", account_id);
self.get(&path, &[]).await
}
pub async fn admin_delete_group(&self, account_id: &str, group_id: &str) -> Result<Value> {
let path = format!("/api/v1/admin/accounts/{}/groups/{}", account_id, group_id);
self.delete(&path, &[]).await
}
pub async fn admin_list_group_members(
&self,
account_id: &str,
group_id: &str,
) -> Result<Value> {
let path = format!(
"/api/v1/admin/accounts/{}/groups/{}/members",
account_id, group_id
);
self.get(&path, &[]).await
}
pub async fn admin_add_group_member(
&self,
account_id: &str,
group_id: &str,
user_id: &str,
) -> Result<Value> {
let path = format!(
"/api/v1/admin/accounts/{}/groups/{}/members/{}",
account_id, group_id, user_id
);
self.put(&path, &serde_json::json!({})).await
}
pub async fn admin_remove_group_member(
&self,
account_id: &str,
group_id: &str,
user_id: &str,
) -> Result<Value> {
let path = format!(
"/api/v1/admin/accounts/{}/groups/{}/members/{}",
account_id, group_id, user_id
);
self.delete(&path, &[]).await
}
// ============ Debug Vector Methods ============
/// Get paginated vector records
pub async fn debug_vector_scroll(
&self,
limit: Option<u32>,
cursor: Option<String>,
uri_prefix: Option<String>,
) -> Result<(Vec<serde_json::Value>, Option<String>)> {
let mut params = Vec::new();
if let Some(l) = limit {
params.push(("limit".to_string(), l.to_string()));
}
if let Some(c) = cursor {
params.push(("cursor".to_string(), c));
}
if let Some(u) = uri_prefix {
params.push(("uri".to_string(), u));
}
let result: serde_json::Value = self.get("/api/v1/debug/vector/scroll", ¶ms).await?;
let records = result["records"]
.as_array()
.ok_or_else(|| Error::Parse("Missing records in response".to_string()))?
.clone();
let next_cursor = result["next_cursor"].as_str().map(|s| s.to_string());
Ok((records, next_cursor))
}
/// Get count of vector records
pub async fn debug_vector_count(
&self,
filter: Option<&serde_json::Value>,
uri_prefix: Option<String>,
) -> Result<u64> {
let mut params = Vec::new();
if let Some(f) = filter {
params.push(("filter".to_string(), serde_json::to_string(f)?));
}
if let Some(u) = uri_prefix {
params.push(("uri".to_string(), u));
}
let result: serde_json::Value = self.get("/api/v1/debug/vector/count", ¶ms).await?;
let count = result["count"]
.as_u64()
.ok_or_else(|| Error::Parse("Missing count in response".to_string()))?;
Ok(count)
}
// ============ Privacy Config Methods ============
pub async fn privacy_list_categories(&self) -> Result<serde_json::Value> {
self.get("/api/v1/privacy-configs", &[]).await
}
pub async fn privacy_tree(&self, category: Option<&str>) -> Result<serde_json::Value> {
let params = category
.map(|value| vec![("category".to_string(), value.to_string())])
.unwrap_or_default();
self.get("/api/v1/privacy-configs/tree", ¶ms).await
}
pub async fn privacy_list_targets(&self, category: &str) -> Result<serde_json::Value> {
let path = format!("/api/v1/privacy-configs/{}", category);
self.get(&path, &[]).await
}
pub async fn privacy_get_current(
&self,
category: &str,
target_key: &str,
) -> Result<serde_json::Value> {
let path = format!("/api/v1/privacy-configs/{}/{}", category, target_key);
self.get(&path, &[]).await
}
pub async fn privacy_get_field(
&self,
category: &str,
target_key: &str,
field: &str,
reveal: bool,
) -> Result<serde_json::Value> {
let path = format!("/api/v1/privacy-configs/{}/{}/field", category, target_key);
let mut params = vec![("field".to_string(), field.to_string())];
if reveal {
params.push(("reveal".to_string(), "true".to_string()));
}
self.get(&path, ¶ms).await
}
pub async fn privacy_list_fields(
&self,
category: &str,
target_key: &str,
) -> Result<serde_json::Value> {
let path = format!("/api/v1/privacy-configs/{}/{}/fields", category, target_key);
self.get(&path, &[]).await
}
pub async fn privacy_resolve_selector(
&self,
selector: &str,
) -> Result<serde_json::Value> {
self.post(
"/api/v1/privacy-configs/resolve",
&serde_json::json!({"selector": selector}),
)
.await
}
pub async fn privacy_upsert(
&self,
category: &str,
target_key: &str,
body: &serde_json::Value,
) -> Result<serde_json::Value> {
let path = format!("/api/v1/privacy-configs/{}/{}", category, target_key);
self.post(&path, body).await
}
pub async fn privacy_patch(
&self,
category: &str,
target_key: &str,
body: &serde_json::Value,
) -> Result<serde_json::Value> {
let path = format!("/api/v1/privacy-configs/{}/{}", category, target_key);
self.patch(&path, body, &[]).await
}
pub async fn privacy_list_versions(
&self,
category: &str,
target_key: &str,
) -> Result<serde_json::Value> {
let path = format!(
"/api/v1/privacy-configs/{}/{}/versions",
category, target_key
);
self.get(&path, &[]).await
}
pub async fn privacy_get_version(
&self,
category: &str,
target_key: &str,
version: i32,
) -> Result<serde_json::Value> {
let path = format!(
"/api/v1/privacy-configs/{}/{}/versions/{}",
category, target_key, version
);
self.get(&path, &[]).await
}
pub async fn privacy_activate(
&self,
category: &str,
target_key: &str,
version: i32,
) -> Result<serde_json::Value> {
let path = format!(
"/api/v1/privacy-configs/{}/{}/activate",
category, target_key
);
let body = serde_json::json!({ "version": version });
self.post(&path, &body).await
}
pub async fn privacy_delete(
&self,
category: &str,
target_key: &str,
) -> Result<serde_json::Value> {
let path = format!("/api/v1/privacy-configs/{}/{}", category, target_key);
self.delete(&path, &[]).await
}
pub async fn privacy_delete_field(
&self,
category: &str,
target_key: &str,
field: &str,
) -> Result<serde_json::Value> {
let path = format!("/api/v1/privacy-configs/{}/{}/field", category, target_key);
self.delete(&path, &[("field".to_string(), field.to_string())])
.await
}
pub async fn privacy_delete_selector(
&self,
selector: &str,
) -> Result<serde_json::Value> {
self.delete_with_body(
"/api/v1/privacy-configs/selector",
&serde_json::json!({"selector": selector}),
)
.await
}
pub async fn privacy_scan(
&self,
body: &serde_json::Value,
) -> Result<serde_json::Value> {
self.post("/api/v1/privacy-configs/scan", body).await
}
// ============ Watch Management (RFC #2104) ============
pub async fn list_watches(&self, active_only: bool) -> Result<serde_json::Value> {
let mut params = vec![];
if active_only {
params.push(("active_only".to_string(), "true".to_string()));
}
self.get("/api/v1/watches", ¶ms).await
}
pub async fn get_watch_by_id(&self, task_id: &str) -> Result<serde_json::Value> {
let path = format!("/api/v1/watches/{}", task_id);
self.get(&path, &[]).await
}
pub async fn get_watch_by_uri(&self, to_uri: &str) -> Result<serde_json::Value> {
let params = vec![("to_uri".to_string(), to_uri.to_string())];
self.get("/api/v1/watches", ¶ms).await
}
pub async fn patch_watch_by_id(
&self,
task_id: &str,
body: &serde_json::Value,
) -> Result<serde_json::Value> {
let path = format!("/api/v1/watches/{}", task_id);
self.patch(&path, body, &[]).await
}
pub async fn patch_watch_by_uri(
&self,
to_uri: &str,
body: &serde_json::Value,
) -> Result<serde_json::Value> {
let params = vec![("to_uri".to_string(), to_uri.to_string())];
self.patch("/api/v1/watches", body, ¶ms).await
}
pub async fn delete_watch_by_id(&self, task_id: &str) -> Result<serde_json::Value> {
let path = format!("/api/v1/watches/{}", task_id);
self.delete(&path, &[]).await
}
pub async fn delete_watch_by_uri(&self, to_uri: &str) -> Result<serde_json::Value> {
let params = vec![("to_uri".to_string(), to_uri.to_string())];
self.delete("/api/v1/watches", ¶ms).await
}
pub async fn trigger_watch_by_id(&self, task_id: &str) -> Result<serde_json::Value> {
let path = format!("/api/v1/watches/{}/trigger", task_id);
let empty = serde_json::json!({});
self.post(&path, &empty).await
}
pub async fn trigger_watch_by_uri(&self, to_uri: &str) -> Result<serde_json::Value> {
let params = vec![("to_uri".to_string(), to_uri.to_string())];
let empty = serde_json::json!({});
self.post_with_query("/api/v1/watches/trigger", &empty, ¶ms)
.await
}
// ============= Snapshot =============
pub async fn snapshot_commit(&self, req: &SnapshotCommitReq) -> Result<Value> {
self.post("/api/v1/snapshot/commit", req).await
}
pub async fn snapshot_restore(&self, req: &SnapshotRestoreReq) -> Result<Value> {
self.post("/api/v1/snapshot/restore", req).await
}
pub async fn snapshot_log(
&self,
branch: &str,
limit: u32,
paths: Option<&[String]>,
) -> Result<Value> {
let mut params = vec![
("branch".to_string(), branch.to_string()),
("limit".to_string(), limit.to_string()),
];
if let Some(paths) = paths {
for path in paths {
params.push(("paths".to_string(), path.to_string()));
}
}
self.get("/api/v1/snapshot/log", ¶ms).await
}
pub async fn snapshot_diff(
&self,
path: &str,
from_ref: Option<&str>,
to_ref: &str,
) -> Result<Value> {
let mut params = vec![
("path".to_string(), path.to_string()),
("to".to_string(), to_ref.to_string()),
];
if let Some(from_ref) = from_ref {
params.push(("from".to_string(), from_ref.to_string()));
}
self.get("/api/v1/snapshot/diff", ¶ms).await
}
/// Return one stable page of source-file changes; no base compares an empty tree.
pub async fn snapshot_diff_paths(
&self,
paths: &[String],
from_ref: Option<&str>,
to_ref: &str,
offset: u32,
limit: u32,
) -> Result<Value> {
let mut params = vec![
("to".to_string(), to_ref.to_string()),
("offset".to_string(), offset.to_string()),
("limit".to_string(), limit.to_string()),
];
params.extend(paths.iter().map(|path| ("paths".to_string(), path.clone())));
if let Some(from_ref) = from_ref {
params.push(("from".to_string(), from_ref.to_string()));
}
self.get("/api/v1/snapshot/diff-paths", ¶ms).await
}
pub async fn snapshot_ignore_get(&self) -> Result<Value> {
self.get("/api/v1/snapshot/ignore", &[]).await
}
pub async fn snapshot_ignore_set(&self, content: &str) -> Result<Value> {
self.put(
"/api/v1/snapshot/ignore",
&serde_json::json!({ "content": content }),
)
.await
}
pub async fn snapshot_ignore_delete(&self) -> Result<Value> {
self.delete("/api/v1/snapshot/ignore", &[]).await
}
pub async fn snapshot_show(
&self,
target_ref: &str,
path: Option<&str>,
) -> Result<SnapshotShowResult> {
let url = format!("{}/api/v1/snapshot/show", self.base.base_url);
let mut query: Vec<(String, String)> =
vec![("target_ref".to_string(), target_ref.to_string())];
if let Some(p) = path {
query.push(("path".to_string(), p.to_string()));
}
let request = self
.base
.http
.get(&url)
.headers(self.base.build_headers())
.query(&query);
let response = self
.base
.send_request(request, "HTTP request failed")
.await?;
let status = response.status();
let content_type = response
.headers()
.get(reqwest::header::CONTENT_TYPE)
.and_then(|v| v.to_str().ok())
.unwrap_or("")
.to_string();
if path.is_some()
&& status.is_success()
&& content_type.starts_with("application/octet-stream")
{
let oid = response
.headers()
.get("x-snapshot-oid")
.and_then(|v| v.to_str().ok())
.unwrap_or("")
.to_string();
let size: u64 = response
.headers()
.get("x-snapshot-size")
.and_then(|v| v.to_str().ok())
.and_then(|s| s.parse().ok())
.unwrap_or(0);
let bytes = response
.bytes()
.await
.map_err(|e| Error::from_reqwest("Failed to read blob bytes", e))?
.to_vec();
return Ok(SnapshotShowResult::Blob { oid, size, bytes });
}
let bytes = response
.bytes()
.await
.map_err(|e| Error::from_reqwest("Failed to read response body", e))?;
if !status.is_success() {
return Err(crate::base_client::api_error_from_body(&bytes, status));
}
let json: Value = match serde_json::from_slice(&bytes) {
Ok(v) => v,
Err(e) => {
let body_str = String::from_utf8_lossy(&bytes);
return Err(Error::Parse(format!(
"Failed to parse JSON response: {}\n\nRaw response body:\n{}",
e, body_str
)));
}
};
if let Some(error) = json.get("error") {
if !error.is_null() {
return Err(crate::base_client::api_error_from_envelope(&json, status));
}
}
let result = json.get("result").cloned().unwrap_or(Value::Null);
Ok(SnapshotShowResult::Metadata(result))
}
}
#[cfg(test)]
mod resource_wait_tests;
#[cfg(test)]
mod tests {
use super::{BaseClient, HttpClient, TimeoutConfig};
use crate::base_client::{
api_error_from_envelope, spawn_test_response, take_test_progress,
};
use reqwest::StatusCode;
use serde_json::{Map, json};
use std::collections::HashMap;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;
use tokio::sync::oneshot;
#[test]
fn compact_request_body_drops_null_and_empty_args() {
let mut body = json!({
"query": "hi",
"score_threshold": null,
"tags": null,
"args": {},
"wait": false,
"create_parent": true,
"filter": {"k": "v"},
});
super::compact_request_body(&mut body);
let obj = body.as_object().unwrap();
// Non-null values are kept, including `false` and non-empty objects.
assert!(obj.contains_key("query"));
assert!(obj.contains_key("wait"));
assert!(obj.contains_key("create_parent"));
assert!(obj.contains_key("filter"));
// Null fields and an empty `args` are dropped so pre-field servers accept it.
assert!(!obj.contains_key("score_threshold"));
assert!(!obj.contains_key("tags"));
assert!(!obj.contains_key("args"));
}
#[test]
fn compact_request_body_keeps_non_empty_args() {
let mut body = json!({"path": "x", "args": {"feishu_access_token": "u-x"}});
super::compact_request_body(&mut body);
assert!(body.as_object().unwrap().contains_key("args"));
}
#[tokio::test]
async fn add_resource_sends_parse_mode_through_args() {
let (default_url, default_request_rx) = spawn_request_capture_server().await;
let default_client = HttpClient::new(default_url, None, None, None, None, 5.0, false, None);
default_client
.add_resource(
"https://example.com/default.md",
None,
None,
None,
None,
"",
"",
false,
false,
None,
None,
None,
true,
0.0,
"semantic_and_vectors".to_string(),
None,
Vec::new(),
"replace".to_string(),
None,
false,
false,
)
.await
.expect("default add-resource request should succeed");
let default_request = default_request_rx
.await
.expect("request should be captured");
assert!(!default_request.contains("parse_mode"));
let (no_split_url, no_split_request_rx) = spawn_request_capture_server().await;
let no_split_client =
HttpClient::new(no_split_url, None, None, None, None, 5.0, false, None);
let mut no_split_args = Map::new();
no_split_args.insert("parse_mode".to_string(), json!("no_split"));
no_split_client
.add_resource(
"https://example.com/manual.pdf",
None,
None,
None,
None,
"",
"",
false,
false,
None,
None,
None,
true,
0.0,
"semantic_and_vectors".to_string(),
Some(no_split_args),
Vec::new(),
"replace".to_string(),
None,
false,
false,
)
.await
.expect("no_split add-resource request should succeed");
let no_split_request = no_split_request_rx
.await
.expect("request should be captured");
assert!(no_split_request.contains(r#""args":{"parse_mode":"no_split"}"#));
}
#[test]
fn compact_request_body_drops_default_processing_mode_for_legacy_servers() {
let mut body = json!({
"path": "https://example.com/guide.md",
"processing_mode": "semantic_and_vectors",
});
super::compact_request_body(&mut body);
assert!(!body.as_object().unwrap().contains_key("processing_mode"));
}
#[test]
fn compact_request_body_keeps_non_default_processing_mode() {
let mut body = json!({
"path": "https://example.com/guide.md",
"processing_mode": "vectors_only",
});
super::compact_request_body(&mut body);
assert_eq!(body["processing_mode"], "vectors_only");
}
#[tokio::test]
async fn search_list_request_preserves_legacy_server_compatibility() {
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.search(
"OAuth token".to_string(),
String::new(),
None,
"semantic".to_string(),
"list".to_string(),
None,
10,
None,
None,
None,
None,
None,
None,
None,
false,
None,
)
.await
.expect("list search should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("POST /api/v1/search/search "));
let (_, body) = request.split_once("\r\n\r\n").expect("request body");
assert_eq!(
serde_json::from_str::<serde_json::Value>(body).unwrap(),
json!({"query": "OAuth token", "target_uri": "", "limit": 10})
);
}
#[tokio::test]
async fn search_context_request_preserves_keywords_and_session_options() {
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.search(
"OAuth token".to_string(),
String::new(),
None,
"keywords".to_string(),
"context".to_string(),
Some("session-1".to_string()),
3,
None,
None,
None,
None,
None,
Some(vec!["memory".to_string()]),
Some(vec!["project=openviking".to_string()]),
false,
Some("7d".to_string()),
)
.await
.expect("context search should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("POST /api/v1/search/search "));
let (_, body) = request.split_once("\r\n\r\n").expect("request body");
assert_eq!(
serde_json::from_str::<serde_json::Value>(body).unwrap(),
json!({
"query": "OAuth token",
"target_uri": "",
"search_type": "keywords",
"mode": "context",
"session_id": "session-1",
"limit": 3,
"context_type": ["memory"],
"tags": ["project=openviking"],
"events_time_decay_protection": "7d"
})
);
}
#[test]
fn add_resource_tag_fields_adds_tags_and_tag_mode() {
let mut body = json!({"path": "https://example.com/demo.md"});
let tags = vec!["team=search".to_string(), "env=test".to_string()];
super::add_resource_tag_fields(&mut body, &tags, "append");
assert_eq!(body["tags"], json!(["team=search", "env=test"]));
assert_eq!(body["tag_mode"], json!("append"));
}
#[test]
fn add_resource_tag_fields_omits_empty_tags_for_compatibility() {
let mut body = json!({"path": "https://example.com/demo.md"});
super::add_resource_tag_fields(&mut body, &[], "replace");
let obj = body.as_object().unwrap();
assert!(!obj.contains_key("tags"));
assert!(!obj.contains_key("tag_mode"));
}
#[test]
fn add_resource_tag_fields_sends_clear_without_tags() {
let mut body = json!({"path": "https://example.com/demo.md"});
super::add_resource_tag_fields(&mut body, &[], "clear");
let obj = body.as_object().unwrap();
assert!(!obj.contains_key("tags"));
assert_eq!(body["tag_mode"], json!("clear"));
}
#[test]
fn timeout_config_calculation() {
let config = TimeoutConfig::new(60, 2.0);
let temp_file = tempfile::NamedTempFile::new().unwrap();
std::fs::write(temp_file.path(), vec![0u8; 1024 * 1024]).unwrap();
let timeout = config.calculate(temp_file.path()).unwrap();
assert_eq!(timeout, std::time::Duration::from_secs(60));
std::fs::write(temp_file.path(), vec![0u8; 40 * 1024 * 1024]).unwrap();
let timeout = config.calculate(temp_file.path()).unwrap();
assert_eq!(timeout, std::time::Duration::from_secs(80));
}
#[test]
fn build_headers_includes_extra_headers_for_base_client() {
let mut extra_headers = HashMap::new();
extra_headers.insert("X-Custom-Header".to_string(), "custom-value".to_string());
let client = BaseClient::new(
"http://localhost:1933",
Some("test-key".to_string()),
Some("acme".to_string()),
Some("alice".to_string()),
Some("peer-a".to_string()),
5.0,
true,
Some(extra_headers),
);
let headers = client.build_headers();
assert_eq!(
headers
.get("X-API-Key")
.and_then(|value| value.to_str().ok()),
Some("test-key")
);
assert_eq!(
headers
.get("X-OpenViking-Account")
.and_then(|value| value.to_str().ok()),
Some("acme")
);
assert_eq!(
headers
.get("X-OpenViking-User")
.and_then(|value| value.to_str().ok()),
Some("alice")
);
assert_eq!(
headers
.get("X-OpenViking-Actor-Peer")
.and_then(|value| value.to_str().ok()),
Some("peer-a")
);
assert_eq!(
headers
.get("X-Custom-Header")
.and_then(|value| value.to_str().ok()),
Some("custom-value")
);
}
#[test]
fn build_write_body_omits_removed_semantic_flags() {
let body = HttpClient::build_write_body(
"viking://resources/demo.md",
"updated",
"replace",
true,
"semantic_and_vectors",
);
assert_eq!(
body,
json!({
"uri": "viking://resources/demo.md",
"content": "updated",
"mode": "replace",
"wait": true,
})
);
assert!(body.get("regenerate_semantics").is_none());
assert!(body.get("revectorize").is_none());
}
#[test]
fn build_write_body_drops_default_processing_mode_for_legacy_servers() {
let body = HttpClient::build_write_body(
"viking://resources/demo.md",
"updated",
"replace",
true,
"semantic_and_vectors",
);
assert!(body.get("processing_mode").is_none());
}
#[test]
fn build_write_body_keeps_vectors_only_processing_mode() {
let body = HttpClient::build_write_body(
"viking://resources/demo.md",
"updated",
"replace",
true,
"vectors_only",
);
assert_eq!(body["processing_mode"], "vectors_only");
}
#[tokio::test]
async fn ls_does_not_send_display_time_query() {
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.ls(
"viking://resources",
false,
false,
"agent",
256,
Some(false),
Some(true),
512,
false,
20,
4,
Some(5),
Some("mtime"),
Some("desc"),
&[],
&[],
false,
)
.await
.expect("ls request should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("GET /api/v1/fs/ls?"));
assert!(request.contains("node_limit=20"));
assert!(request.contains("offset=4"));
assert!(request.contains("limit=5"));
assert!(request.contains("sort_by=mtime"));
assert!(request.contains("sort_order=desc"));
assert!(request.contains("include_abstract=false"));
assert!(request.contains("include_overview=true"));
assert!(request.contains("overview_limit=512"));
assert!(!request.contains("tz="));
assert!(!request.contains("include_mod_time_iso="));
let (default_url, default_request_rx) = spawn_request_capture_server().await;
let default_client = HttpClient::new(default_url, None, None, None, None, 5.0, false, None);
default_client
.ls(
"viking://resources",
false,
false,
"agent",
256,
None,
None,
4000,
false,
20,
0,
None,
None,
None,
&[],
&[],
false,
)
.await
.expect("default ls request should succeed");
let default_request = default_request_rx
.await
.expect("default request should be captured");
assert!(!default_request.contains("offset="));
assert!(!default_request.contains("include_abstract="));
assert!(!default_request.contains("include_overview="));
assert!(default_request.contains("overview_limit=4000"));
assert!(!default_request.contains("&limit="));
assert!(!default_request.contains("sort_by="));
assert!(!default_request.contains("sort_order="));
}
#[tokio::test]
async fn cp_posts_recursive_request_body() {
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.cp(
"viking://resources/source",
"viking://resources/target",
true,
)
.await
.expect("cp request should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("POST /api/v1/fs/cp "));
assert!(request.contains(r#""from_uri":"viking://resources/source""#));
assert!(request.contains(r#""to_uri":"viking://resources/target""#));
assert!(request.contains(r#""recursive":true"#));
}
#[tokio::test]
async fn gateway_token_is_not_sent_without_a_gateway_challenge() {
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None)
.with_gateway_token(Some("gateway-secret".to_string()));
let _: serde_json::Value = client
.get("/health", &[])
.await
.expect("direct OpenViking request should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(!request.to_ascii_lowercase().contains("x-gateway-token"));
}
#[tokio::test]
async fn gateway_token_is_retried_for_marked_gateway_challenge() {
let (base_url, requests_rx) = spawn_gateway_challenge_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None)
.with_gateway_token(Some("gateway-secret".to_string()));
let _: serde_json::Value = client
.get("/health", &[])
.await
.expect("gateway retry should succeed");
let requests = requests_rx.await.expect("requests should be captured");
assert_gateway_token_retry(&requests);
}
#[tokio::test]
async fn file_download_retries_marked_gateway_challenge() {
let (base_url, requests_rx) = spawn_gateway_challenge_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None)
.with_gateway_token(Some("gateway-secret".to_string()));
client
.get_bytes("viking://resources/file.bin")
.await
.expect("file download should retry through gateway");
let requests = requests_rx.await.expect("requests should be captured");
assert_gateway_token_retry(&requests);
}
#[tokio::test]
async fn pack_download_retries_marked_gateway_challenge() {
let (base_url, requests_rx) = spawn_gateway_challenge_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None)
.with_gateway_token(Some("gateway-secret".to_string()));
let output = tempfile::tempdir().expect("tempdir should be created");
client
.export_ovpack(
"viking://resources",
output
.path()
.to_str()
.expect("tempdir path should be valid"),
false,
false,
)
.await
.expect("pack export should retry through gateway");
let requests = requests_rx.await.expect("requests should be captured");
assert_gateway_token_retry(&requests);
}
#[tokio::test]
async fn snapshot_show_retries_marked_gateway_challenge() {
let (base_url, requests_rx) = spawn_gateway_challenge_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None)
.with_gateway_token(Some("gateway-secret".to_string()));
client
.snapshot_show("HEAD", None)
.await
.expect("snapshot show should retry through gateway");
let requests = requests_rx.await.expect("requests should be captured");
assert_gateway_token_retry(&requests);
}
#[tokio::test]
async fn snapshot_diff_sends_path_and_refs() {
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.snapshot_diff("viking://resources/a.md", Some("old"), "new")
.await
.expect("snapshot diff should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("GET /api/v1/snapshot/diff?"));
assert!(request.contains("path=viking%3A%2F%2Fresources%2Fa.md"));
assert!(request.contains("from=old"));
assert!(request.contains("to=new"));
}
fn assert_gateway_token_retry(requests: &[String]) {
assert_eq!(requests.len(), 2);
assert!(!requests[0].to_ascii_lowercase().contains("x-gateway-token"));
assert!(
requests[1]
.to_ascii_lowercase()
.contains("x-gateway-token: gateway-secret")
);
}
#[tokio::test]
async fn tree_does_not_send_display_time_query() {
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.tree(
"viking://resources",
"agent",
256,
Some(false),
Some(true),
512,
false,
true,
20,
3,
4,
Some(5),
&[],
&[],
false,
)
.await
.expect("tree request should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("GET /api/v1/fs/tree?"));
assert!(request.contains("node_limit=20"));
assert!(request.contains("offset=4"));
assert!(request.contains("limit=5"));
assert!(request.contains("include_abstract=false"));
assert!(request.contains("include_overview=true"));
assert!(request.contains("overview_limit=512"));
assert!(request.contains("directories_only=true"));
assert!(!request.contains("tz="));
assert!(!request.contains("include_mod_time_iso="));
let (default_url, default_request_rx) = spawn_request_capture_server().await;
let default_client = HttpClient::new(default_url, None, None, None, None, 5.0, false, None);
default_client
.tree(
"viking://resources",
"agent",
256,
None,
None,
4000,
false,
false,
20,
3,
0,
None,
&[],
&[],
false,
)
.await
.expect("default tree request should succeed");
let default_request = default_request_rx
.await
.expect("default request should be captured");
assert!(!default_request.contains("offset="));
assert!(!default_request.contains("include_abstract="));
assert!(!default_request.contains("include_overview="));
assert!(!default_request.contains("directories_only="));
assert!(!default_request.contains("&limit="));
}
#[tokio::test]
async fn grep_omits_optional_tags_fields_when_not_requested() {
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.grep(
"viking://resources",
None,
"needle",
false,
0,
0,
10,
3,
&[],
false,
)
.await
.expect("plain grep request should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("POST /api/v1/search/grep "));
assert!(!request.contains(r#""tags""#));
assert!(!request.contains(r#""include_tags""#));
assert!(!request.contains(r#""after_context""#));
assert!(!request.contains(r#""before_context""#));
}
#[tokio::test]
async fn grep_sends_include_tags_only_when_requested() {
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.grep(
"viking://resources",
None,
"needle",
false,
2,
3,
10,
3,
&[],
true,
)
.await
.expect("grep tags projection request should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.contains(r#""include_tags":true"#));
assert!(request.contains(r#""after_context":2"#));
assert!(request.contains(r#""before_context":3"#));
}
#[tokio::test]
async fn glob_omits_tags_when_not_requested() {
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.glob("**/*.md", "viking://resources", 10, None, &[], false)
.await
.expect("plain glob request should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("POST /api/v1/search/glob "));
assert!(!request.contains(r#""tags"#));
assert!(!request.contains(r#""include_tags"#));
}
#[tokio::test]
async fn glob_sends_tags_and_projection_when_requested() {
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.glob(
"**/*.md",
"viking://resources",
10,
Some(&["tags".to_string()]),
&["team=search".to_string(), "env=prod".to_string()],
true,
)
.await
.expect("tagged glob request should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.contains(r#""tags":["team=search","env=prod"]"#));
assert!(request.contains(r#""include_tags":true"#));
}
#[tokio::test]
async fn compile_create_deserializes_http_202_body() {
let listener = TcpListener::bind("127.0.0.1:0")
.await
.expect("test server should bind");
let address = listener.local_addr().expect("listener should have address");
tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.expect("request should arrive");
let mut buffer = vec![0; 4096];
let read = stream.read(&mut buffer).await.expect("request should read");
let request = String::from_utf8_lossy(&buffer[..read]);
assert!(request.contains(r#""skill":"viking://agent/skills/wiki""#));
assert!(request.contains(r#""instruction":"Keep supporting evidence.""#));
assert!(request.contains(r#""args":{"model_name":"endpoint-1"}"#));
let body = r#"{"status":"ok","result":{"task_id":"cmp_1","status":"accepted","to":"viking://resources/wiki"}}"#;
let response = format!(
"HTTP/1.1 202 Accepted\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
body.len(),
body
);
stream
.write_all(response.as_bytes())
.await
.expect("response should write");
});
let client = HttpClient::new(
format!("http://{address}"),
None,
None,
None,
None,
5.0,
false,
None,
);
let args = serde_json::json!({"model_name": "endpoint-1"});
let accepted = client
.create_compile(
&["viking://resources/source".into()],
"viking://resources/wiki",
"viking://agent/skills/wiki",
Some("Keep supporting evidence."),
args.as_object(),
)
.await
.expect("202 response body should deserialize");
assert_eq!(accepted.task_id, "cmp_1");
}
#[tokio::test]
async fn task_methods_use_generic_task_endpoints_for_compile_ids() {
let (base_url, status_request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.get_task("cmp_1")
.await
.expect("compile status request should succeed");
let status_request = status_request_rx
.await
.expect("status request should be captured");
assert!(status_request.starts_with("GET /api/v1/tasks/cmp_1 "));
let (base_url, cancel_request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.cancel_task("cmp_1")
.await
.expect("compile cancellation request should succeed");
let cancel_request = cancel_request_rx
.await
.expect("cancel request should be captured");
assert!(cancel_request.starts_with("POST /api/v1/tasks/cmp_1/cancel "));
}
#[tokio::test]
async fn ovpack_download_progress_reports_failure_for_http_error() {
let base_url = spawn_test_response(
"500 Internal Server Error",
r#"{"error":{"code":"INTERNAL_ERROR","message":"export failed"}}"#,
)
.await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
let destination = tempfile::tempdir().expect("download directory should be created");
let _ = take_test_progress();
let error = client
.export_ovpack(
"viking://resources/demo",
destination.path().to_str().unwrap(),
false,
true,
)
.await
.expect_err("HTTP error should fail download");
let progress = take_test_progress().expect("download progress should be recorded");
assert!(matches!(error, crate::error::Error::Api { status: Some(500), .. }));
assert!(progress.is_finished());
assert_eq!(progress.message(), "OVPack download failed");
}
#[tokio::test]
async fn admin_request_payloads_are_sent() {
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.admin_create_account("acct", "admin", Some("admin-seed"), None)
.await
.expect("create account should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("POST /api/v1/admin/accounts "));
assert!(request.contains(r#""seed":"admin-seed""#));
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.admin_register_user("acct", "alice", "admin", Some("alice-seed"), None)
.await
.expect("register user should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("POST /api/v1/admin/accounts/acct/users "));
assert!(request.contains(r#""seed":"alice-seed""#));
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.admin_regenerate_key("acct", "alice", Some("new-seed"))
.await
.expect("regenerate key should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("POST /api/v1/admin/accounts/acct/users/alice/key "));
assert!(request.contains(r#""seed":"new-seed""#));
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.admin_set_account_acl_enabled("acct", true)
.await
.expect("set account settings should succeed");
let request = request_rx.await.expect("request should be captured");
assert!(request.starts_with("PATCH /api/v1/admin/accounts/acct/settings "));
assert!(request.contains(r#""acl":{"enabled":true}"#));
}
#[test]
fn standard_error_envelope_formats_api_error() {
let body = json!({
"status": "error",
"error": {
"code": "PROCESSING_ERROR",
"message": "Parse error: boom"
}
});
let error = api_error_from_envelope(&body, StatusCode::INTERNAL_SERVER_ERROR);
assert!(matches!(
error,
crate::error::Error::Api {
code: Some(code),
message,
status: Some(500),
..
} if code == "PROCESSING_ERROR" && message == "Parse error: boom"
));
}
#[test]
fn unwrap_result_preserves_profile_for_non_object_results() {
let body = json!({
"status": "ok",
"result": [
{"id": "1"}
],
"profile": [
"line one",
"line two"
]
});
let result = crate::base_client::unwrap_success_envelope(body, true);
assert_eq!(
result,
json!({
"result": [
{"id": "1"}
],
"profile": [
"line one",
"line two"
]
})
);
}
#[test]
fn unwrap_result_drops_profile_for_scalar_typed_results() {
let body = json!({
"status": "ok",
"result": "content",
"profile": [
"line one"
]
});
let result = crate::base_client::unwrap_success_envelope(body, false);
assert_eq!(result, json!("content"));
}
#[tokio::test]
async fn read_profiled_sends_line_ranges() {
for (offset, limit) in [(0, -1), (10, 5), (10, -1), (0, 0)] {
let (base_url, request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
.read_profiled("viking://resources/example.md", offset, limit)
.await
.expect("read request should succeed");
let request = request_rx.await.expect("request should be captured");
let target = request.split_whitespace().nth(1).expect("request target");
let url = url::Url::parse(&format!("http://localhost{target}")).unwrap();
assert_eq!(url.path(), "/api/v1/content/read");
let params = url
.query_pairs()
.collect::<std::collections::HashMap<_, _>>();
assert_eq!(params.get("uri").unwrap(), "viking://resources/example.md");
assert_eq!(params.get("offset").unwrap(), &offset.to_string());
assert_eq!(params.get("limit").unwrap(), &limit.to_string());
}
}
async fn spawn_request_capture_server() -> (String, oneshot::Receiver<String>) {
let listener = TcpListener::bind("127.0.0.1:0")
.await
.expect("test server should bind");
let addr = listener.local_addr().expect("test server should have addr");
let (request_tx, request_rx) = oneshot::channel();
tokio::spawn(async move {
let Ok((mut stream, _)) = listener.accept().await else {
return;
};
let mut buffer = vec![0; 4096];
let Ok(read) = stream.read(&mut buffer).await else {
return;
};
let request = String::from_utf8_lossy(&buffer[..read]).to_string();
let _ = request_tx.send(request);
let body = r#"{"status":"ok","result":[]}"#;
let response = format!(
"HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
body.len(),
body
);
let _ = stream.write_all(response.as_bytes()).await;
});
(format!("http://{addr}"), request_rx)
}
async fn spawn_gateway_challenge_server() -> (String, oneshot::Receiver<Vec<String>>) {
let listener = TcpListener::bind("127.0.0.1:0")
.await
.expect("test server should bind");
let addr = listener.local_addr().expect("test server should have addr");
let (request_tx, request_rx) = oneshot::channel();
tokio::spawn(async move {
let mut requests = Vec::new();
for attempt in 0..2 {
let Ok((mut stream, _)) = listener.accept().await else {
return;
};
let mut buffer = vec![0; 4096];
let Ok(read) = stream.read(&mut buffer).await else {
return;
};
requests.push(String::from_utf8_lossy(&buffer[..read]).to_string());
let (status, marker, body) = if attempt == 0 {
(
"401 Unauthorized",
"X-VikingBot-Gateway: true\r\n",
r#"{"detail":"X-Gateway-Token header required"}"#,
)
} else {
("200 OK", "", r#"{"status":"ok","result":{"ok":true}}"#)
};
let response = format!(
"HTTP/1.1 {status}\r\ncontent-type: application/json\r\n{marker}content-length: {}\r\nconnection: close\r\n\r\n{body}",
body.len()
);
let _ = stream.write_all(response.as_bytes()).await;
}
let _ = request_tx.send(requests);
});
(format!("http://{addr}"), request_rx)
}
}