asp/keep
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Add Rustdoc examples to server common types and compression engine

Browse Source 
Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) <aider@aider.chat>
This commit is contained in:
Andrew Phillips
2025-09-10 14:05:24 -03:00
parent 46a245a59a
commit 6cff3bd165
2 changed files with 144 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
src/modes/server/common.rs
View File

@@ -3,6 +3,14 @@
/// This module provides shared structures, functions, and middleware used across
/// different parts of the server implementation, including configuration, state
/// management, API responses, authentication, and logging.
///
/// # Usage
///
/// ```rust
/// use keep::modes::server::common::{ServerConfig, AppState};
/// let config = ServerConfig { address: "127.0.0.1".to_string(), ..Default::default() };
/// let state = AppState { /* ... */ };
/// ```
use anyhow::Result;
use axum::{
extract::{Request, ConnectInfo},
@@ -26,6 +34,17 @@ use crate::services::item_service::ItemService;
///
/// This struct holds the configuration parameters for the HTTP server, including
/// binding address, port, and authentication settings.
///
/// # Examples
///
/// ```
/// let config = ServerConfig {
/// address: "127.0.0.1".to_string(),
/// port: Some(8080),
/// password: None,
/// password_hash: None,
/// };
/// ```
#[derive(Debug, Clone)]
pub struct ServerConfig {
/// Server bind address.
@@ -50,11 +69,6 @@ pub struct ServerConfig {
pub password_hash: Option<String>,
}
/// Application state shared across all routes.
///
/// This struct encapsulates the shared state that is accessible to all request handlers,
/// including database connections, file paths, services, and configuration.
#[derive(Clone)]
/// Application state shared across all routes.
///
/// This struct encapsulates the shared state that is accessible to all request handlers,
@@ -62,7 +76,10 @@ pub struct ServerConfig {
///
/// # Examples
///
/// ```
/// ```rust
/// use keep::modes::server::common::AppState;
/// use std::sync::Arc;
/// use tokio::sync::Mutex;
/// let state = AppState {
/// db: Arc::new(Mutex::new(conn)),
/// data_dir: PathBuf::from("/data"),
@@ -71,6 +88,7 @@ pub struct ServerConfig {
/// settings: Arc::new(settings),
/// };
/// ```
#[derive(Clone)]
pub struct AppState {
/// Database connection wrapped in Arc<Mutex>.
///
@@ -95,11 +113,6 @@ pub struct AppState {
pub settings: Arc<crate::config::Settings>,
}
/// Standard API response wrapper containing success status, data payload, and error information.
///
/// This generic type is used for all API responses to provide a consistent structure across
/// different endpoints.
#[derive(Debug, Serialize, Deserialize, ToSchema)]
/// Standard API response wrapper containing success status, data payload, and error information.
///
/// This generic type is used for all API responses to provide a consistent structure across
@@ -111,13 +124,15 @@ pub struct AppState {
///
/// # Examples
///
/// ```
/// ```rust
/// use keep::modes::server::common::ApiResponse;
/// let response: ApiResponse<Vec<ItemInfo>> = ApiResponse {
/// success: true,
/// data: Some(items),
/// error: None,
/// };
/// ```
#[derive(Debug, Serialize, Deserialize, ToSchema)]
#[schema(description = "Standard API response wrapper containing success status, data payload, and error information")]
pub struct ApiResponse<T> {
/// Success indicator.
@@ -134,23 +149,21 @@ pub struct ApiResponse<T> {
pub error: Option<String>,
}
/// Response type for list of item information.
///
/// Specialized response for endpoints that return multiple items.
#[derive(Serialize, Deserialize, ToSchema)]
/// Response type for list of item information.
///
/// Specialized response for endpoints that return multiple items.
///
/// # Examples
///
/// ```
/// ```rust
/// use keep::modes::server::common::ItemInfoListResponse;
/// let response = ItemInfoListResponse {
/// success: true,
/// data: Some(vec![item_info]),
/// error: None,
/// };
/// ```
#[derive(Serialize, Deserialize, ToSchema)]
pub struct ItemInfoListResponse {
/// Success indicator.
///
@@ -166,23 +179,21 @@ pub struct ItemInfoListResponse {
pub error: Option<String>,
}
/// Response type for single item information.
///
/// Specialized response for endpoints that return a single item's details.
#[derive(Serialize, Deserialize, ToSchema)]
/// Response type for single item information.
///
/// Specialized response for endpoints that return a single item's details.
///
/// # Examples
///
/// ```
/// ```rust
/// use keep::modes::server::common::ItemInfoResponse;
/// let response = ItemInfoResponse {
/// success: true,
/// data: Some(item_info),
/// error: None,
/// };
/// ```
#[derive(Serialize, Deserialize, ToSchema)]
pub struct ItemInfoResponse {
/// Success indicator.
///
@@ -198,23 +209,21 @@ pub struct ItemInfoResponse {
pub error: Option<String>,
}
/// Response type for item content information.
///
/// Specialized response for endpoints that return item content and related metadata.
#[derive(Serialize, Deserialize, ToSchema)]
/// Response type for item content information.
///
/// Specialized response for endpoints that return item content and related metadata.
///
/// # Examples
///
/// ```
/// ```rust
/// use keep::modes::server::common::ItemContentInfoResponse;
/// let response = ItemContentInfoResponse {
/// success: true,
/// data: Some(content_info),
/// error: None,
/// };
/// ```
#[derive(Serialize, Deserialize, ToSchema)]
pub struct ItemContentInfoResponse {
/// Success indicator.
///
@@ -230,23 +239,21 @@ pub struct ItemContentInfoResponse {
pub error: Option<String>,
}
/// Response type for metadata.
///
/// Specialized response for metadata-only endpoints.
#[derive(Serialize, Deserialize, ToSchema)]
/// Response type for metadata.
///
/// Specialized response for metadata-only endpoints.
///
/// # Examples
///
/// ```
/// ```rust
/// use keep::modes::server::common::MetadataResponse;
/// let response = MetadataResponse {
/// success: true,
/// data: Some(meta_map),
/// error: None,
/// };
/// ```
#[derive(Serialize, Deserialize, ToSchema)]
pub struct MetadataResponse {
/// Success indicator.
///
@@ -262,23 +269,21 @@ pub struct MetadataResponse {
pub error: Option<String>,
}
/// Response type for status information.
///
/// Specialized response for system status endpoints.
#[derive(Serialize, Deserialize, ToSchema)]
/// Response type for status information.
///
/// Specialized response for system status endpoints.
///
/// # Examples
///
/// ```
/// ```rust
/// use keep::modes::server::common::StatusInfoResponse;
/// let response = StatusInfoResponse {
/// success: true,
/// data: Some(status_info),
/// error: None,
/// };
/// ```
#[derive(Serialize, Deserialize, ToSchema)]
pub struct StatusInfoResponse {
/// Success indicator.
///
@@ -294,11 +299,6 @@ pub struct StatusInfoResponse {
pub error: Option<String>,
}
/// Complete information about a stored item including metadata and tags.
///
/// This structure represents the full details of an item, combining basic item
/// properties with associated tags and metadata.
#[derive(Serialize, Deserialize, ToSchema)]
/// Complete information about a stored item including metadata and tags.
///
/// This structure represents the full details of an item, combining basic item
@@ -306,7 +306,9 @@ pub struct StatusInfoResponse {
///
/// # Examples
///
/// ```
/// ```rust
/// use keep::modes::server::common::ItemInfo;
/// use std::collections::HashMap;
/// let item_info = ItemInfo {
/// id: 42,
/// ts: "2023-12-01T15:30:45Z".to_string(),
@@ -316,6 +318,7 @@ pub struct StatusInfoResponse {
/// metadata: HashMap::from([("mime_type".to_string(), "text/plain".to_string())]),
/// };
/// ```
#[derive(Serialize, Deserialize, ToSchema)]
#[schema(description = "Complete information about a stored item including metadata and tags")]
pub struct ItemInfo {
/// Item ID.
@@ -350,17 +353,6 @@ pub struct ItemInfo {
pub metadata: HashMap<String, String>,
}
/// Item information including content and metadata, with binary detection.
///
/// This structure provides item details along with its content, handling binary
/// content detection and safe string representation.
///
/// # Fields
///
/// * `metadata` - Flattened metadata HashMap.
/// * `content` - Optional string content (text only).
/// * `binary` - True if binary content.
#[derive(Serialize, Deserialize, ToSchema)]
/// Item information including content and metadata, with binary detection.
///
/// This structure provides item details along with its content, handling binary
@@ -368,13 +360,16 @@ pub struct ItemInfo {
///
/// # Examples
///
/// ```
/// ```rust
/// use keep::modes::server::common::ItemContentInfo;
/// use std::collections::HashMap;
/// let content_info = ItemContentInfo {
/// metadata: HashMap::from([("mime_type".to_string(), "text/plain".to_string())]),
/// content: Some("Hello, world!".to_string()),
/// binary: false,
/// };
/// ```
#[derive(Serialize, Deserialize, ToSchema)]
#[schema(description = "Item information including content and metadata, with binary detection")]
pub struct ItemContentInfo {
/// Metadata hashmap.
@@ -395,23 +390,17 @@ pub struct ItemContentInfo {
pub binary: bool,
}
/// Query parameters for tags.
///
/// Structure for handling tag-based query parameters in API requests.
///
/// # Fields
///
/// * `tags` - Optional comma-separated tags for filtering.
#[derive(Debug, Deserialize)]
/// Query parameters for tags.
///
/// Structure for handling tag-based query parameters in API requests.
///
/// # Examples
///
/// ```
/// ```rust
/// use keep::modes::server::common::TagsQuery;
/// let query = TagsQuery { tags: Some("tag1,tag2".to_string()) };
/// ```
#[derive(Debug, Deserialize)]
pub struct TagsQuery {
/// Optional comma-separated tags.
///
@@ -419,24 +408,14 @@ pub struct TagsQuery {
pub tags: Option<String>,
}
/// Query parameters for listing items.
///
/// Structure for pagination and sorting parameters in item listing endpoints.
///
/// # Fields
///
/// * `tags` - Optional tags for filtering.
/// * `order` - Optional sort: "newest" or "oldest".
/// * `start` - Optional start index.
/// * `count` - Optional item limit.
#[derive(Debug, Deserialize)]
/// Query parameters for listing items.
///
/// Structure for pagination and sorting parameters in item listing endpoints.
///
/// # Examples
///
/// ```
/// ```rust
/// use keep::modes::server::common::ListItemsQuery;
/// let query = ListItemsQuery {
/// tags: Some("important".to_string()),
/// order: Some("newest".to_string()),
@@ -444,6 +423,7 @@ pub struct TagsQuery {
/// count: Some(10),
/// };
/// ```
#[derive(Debug, Deserialize)]
pub struct ListItemsQuery {
/// Optional comma-separated tags for filtering.
///
@@ -463,25 +443,14 @@ pub struct ListItemsQuery {
pub count: Option<u32>,
}
/// Query parameters for item retrieval.
///
/// Structure for content retrieval parameters, including binary handling and streaming options.
///
/// # Fields
///
/// * `allow_binary` - Allow binary (default true).
/// * `offset` - Byte offset (default 0).
/// * `length` - Byte length (default 0 = all).
/// * `stream` - Enable streaming (default false).
/// * `as_meta` - Return as JSON metadata (default false).
#[derive(Debug, Deserialize, utoipa::ToSchema)]
/// Query parameters for item retrieval.
///
/// Structure for content retrieval parameters, including binary handling and streaming options.
///
/// # Examples
///
/// ```
/// ```rust
/// use keep::modes::server::common::ItemQuery;
/// let query = ItemQuery {
/// allow_binary: true,
/// offset: 0,
@@ -490,6 +459,7 @@ pub struct ListItemsQuery {
/// as_meta: false,
/// };
/// ```
#[derive(Debug, Deserialize, utoipa::ToSchema)]
pub struct ItemQuery {
/// Allow binary content (default: true).
///
@@ -518,26 +488,14 @@ pub struct ItemQuery {
pub as_meta: bool,
}
/// Query parameters for item content retrieval.
///
/// Extended query parameters for content-specific operations, including tag filtering.
///
/// # Fields
///
/// * `tags` - Optional tags for filtering.
/// * `allow_binary` - Allow binary (default true).
/// * `offset` - Byte offset (default 0).
/// * `length` - Byte length (default 0 = all).
/// * `stream` - Enable streaming (default false).
/// * `as_meta` - Return as JSON metadata (default false).
#[derive(Debug, Deserialize, utoipa::ToSchema)]
/// Query parameters for item content retrieval.
///
/// Extended query parameters for content-specific operations, including tag filtering.
///
/// # Examples
///
/// ```
/// ```rust
/// use keep::modes::server::common::ItemContentQuery;
/// let query = ItemContentQuery {
/// tags: Some("important".to_string()),
/// allow_binary: true,
@@ -547,6 +505,7 @@ pub struct ItemQuery {
/// as_meta: false,
/// };
/// ```
#[derive(Debug, Deserialize, utoipa::ToSchema)]
pub struct ItemContentQuery {
/// Optional comma-separated tags for filtering.
///