refactor: code cleanup and refactoring to resolve warnings and check issues

Signed-off-by: Nick Gerakines <[e-mail]>

src/bin/blahg.rs

···
     };
 
     // Setup markdown render manager
-    let render_manager: Arc<dyn RenderManager> = Arc::new(ComrakRenderManager::new(&config.external_base));
+    let render_manager: Arc<dyn RenderManager> = Arc::new(ComrakRenderManager::with_theme(&config.syntect_theme, &config.external_base));
 
     // Setup template engine
     let template_env = {

src/config.rs

···
 /// Application configuration loaded from environment variables.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Config {
+    /// HTTP server configuration
     pub http: HttpConfig,
+    /// Base URL for external links and content
     pub external_base: String,
+    /// Certificate bundles for TLS verification
     pub certificate_bundles: Vec<String>,
+    /// User agent string for HTTP requests
     pub user_agent: String,
+    /// Hostname for PLC directory lookups
     pub plc_hostname: String,
+    /// DNS nameservers for resolution
     pub dns_nameservers: Vec<std::net::IpAddr>,
+    /// HTTP client timeout duration
     pub http_client_timeout: Duration,
+    /// Author name for the blog
     pub author: String,
+    /// Storage path for attachments
     pub attachment_storage: String,
+    /// Database connection URL
     pub database_url: String,
+    /// Path to jetstream cursor file
     pub jetstream_cursor_path: Option<String>,
+    /// Whether to enable jetstream event consumption
     pub enable_jetstream: bool,
+    /// Syntect theme for syntax highlighting
+    pub syntect_theme: String,
 }
 
+/// HTTP server configuration options.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct HttpConfig {
+    /// Port to bind the HTTP server to
     pub port: u16,
+    /// Path to static assets
     pub static_path: String,
+    /// Path to template files
     pub templates_path: String,
 }
 
···
             database_url: "sqlite://blahg.db".to_string(),
             jetstream_cursor_path: None,
             enable_jetstream: true,
+            syntect_theme: std::env::var("SYNTECT_THEME").unwrap_or_else(|_| "base16-ocean.dark".to_string()),
         }
     }
 }
···
 
         if let Ok(enable_jetstream) = std::env::var("ENABLE_JETSTREAM") {
             config.enable_jetstream = enable_jetstream.parse().unwrap_or(true);
+        }
+
+        if let Ok(syntect_theme) = std::env::var("SYNTECT_THEME") {
+            config.syntect_theme = syntect_theme;
         }
 
         Ok(config)

src/consumer.rs

···
 use tokio::sync::Mutex;
 use tokio::sync::mpsc;
 
+/// Receiver for `BlahgEvent` instances from the jetstream consumer.
 pub type BlahgEventReceiver = mpsc::UnboundedReceiver<BlahgEvent>;
 
+/// ATProtocol events relevant to the blog application.
 #[derive(Debug, Clone)]
 pub enum BlahgEvent {
+    /// A record was committed to the ATProtocol network.
     Commit {
+        /// The DID of the record author
         did: String,
+        /// The collection name
         collection: String,
+        /// The record key
         rkey: String,
+        /// The content identifier
         cid: String,
+        /// The record data
         record: serde_json::Value,
     },
+    /// A record was deleted from the ATProtocol network.
     Delete {
+        /// The DID of the record author
         did: String,
+        /// The collection name
         collection: String,
+        /// The record key
         rkey: String,
     },
 }
 
+/// Handler for processing ATProtocol events and converting them to `BlahgEvent` instances.
 pub struct BlahgEventHandler {
     id: String,
     event_sender: mpsc::UnboundedSender<BlahgEvent>,
···
     }
 }
 
+/// Consumer for creating ATProtocol event handlers.
 pub struct Consumer {}
 
 impl Consumer {
+    /// Create a new Blahg event handler that processes ATProtocol events.
     pub fn create_blahg_handler(&self) -> (Arc<BlahgEventHandler>, BlahgEventReceiver) {
         let (sender, receiver) = mpsc::unbounded_channel();
         let handler = Arc::new(BlahgEventHandler::new(
···
         (handler, receiver)
     }
 
+    /// Create a new cursor writer handler that persists jetstream cursor position.
     pub fn create_cursor_writer_handler(&self, cursor_path: String) -> Arc<CursorWriterHandler> {
         Arc::new(CursorWriterHandler::new(
             "cursor-writer".to_string(),

src/identity.rs

···
 use atproto_identity::model::Document;
 use atproto_identity::resolve::IdentityResolver;
-use atproto_identity::storage::DidDocumentStorage;
 use chrono::Utc;
 use std::sync::Arc;
 
···
         Ok(())
     }
 }
-
-/// A variant that works with DidDocumentStorage instead of IdentityStorage
-pub(crate) struct CachingDidDocumentResolver<T: DidDocumentStorage + ?Sized> {
-    /// The underlying identity resolver to use when cache misses occur
-    resolver: IdentityResolver,
-    /// The storage implementation to use for caching
-    storage: Arc<T>,
-}
-
-impl<T: DidDocumentStorage + ?Sized> CachingDidDocumentResolver<T> {
-    /// Create a new caching identity resolver with the given resolver and storage.
-    pub(crate) fn new(resolver: IdentityResolver, storage: Arc<T>) -> Self {
-        Self { resolver, storage }
-    }
-
-    /// Resolve a DID to a Document, using the cache when possible.
-    pub(crate) async fn resolve(&self, did: &str) -> Result<Document> {
-        // First, try to get the document from storage
-        if let Some(document) = self.storage.get_document_by_did(did).await? {
-            return Ok(document);
-        }
-
-        // If not in storage, resolve using the underlying resolver
-        let document = self.resolver.resolve(did).await?;
-
-        // Store the resolved document for future lookups
-        self.storage.store_document(document.clone()).await?;
-
-        Ok(document)
-    }
-
-    /// Resolve a handle to a Document, using the cache when possible.
-    pub(crate) async fn resolve_handle(&self, handle: &str) -> Result<Document> {
-        // For handle resolution, we need to resolve first since DidDocumentStorage
-        // doesn't have a get_by_handle method
-        let document = self.resolver.resolve(handle).await?;
-
-        // Store the resolved document for future lookups
-        self.storage.store_document(document.clone()).await?;
-
-        Ok(document)
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::storage::sqlite::SqliteStorage;
-    use atproto_identity::resolve::{InnerIdentityResolver, create_resolver};
-    use sqlx::SqlitePool;
-    use std::sync::Arc;
-
-    #[tokio::test]
-    async fn test_caching_identity_resolver() -> Result<()> {
-        // Create an in-memory SQLite database for testing
-        let pool = SqlitePool::connect("sqlite::memory:").await?;
-        let storage = Arc::new(SqliteStorage::new(pool));
-
-        // Run migrations using the Storage trait
-        use crate::storage::Storage;
-        storage.migrate().await?;
-
-        // Create a mock resolver (this would normally resolve from the network)
-        let dns_resolver = create_resolver(&[]);
-        let http_client = reqwest::Client::new();
-        let inner_resolver = InnerIdentityResolver {
-            dns_resolver,
-            http_client,
-            plc_hostname: "plc.directory".to_string(),
-        };
-        let resolver = IdentityResolver(Arc::new(inner_resolver));
-
-        // Create the caching resolver
-        let caching_resolver = CachingIdentityResolver::new(resolver, storage.clone());
-
-        // Test would go here - this is just a skeleton since we'd need real DIDs
-        // and network access to properly test the resolution
-
-        Ok(())
-    }
-}

src/lexicon.rs

···
 use chrono::{DateTime, Utc};
 use serde::Deserialize;
 
+/// A blob record containing binary data metadata.
 #[derive(Debug, Clone, Deserialize)]
 pub struct BlobRecord {
+    /// The record type
     #[serde(rename = "$type")]
     pub r#type: String,
 
+    /// MIME type of the blob
     #[serde(rename = "mimeType")]
     pub mime_type: String,
+    /// Size of the blob in bytes
     pub size: i64,
 
+    /// Reference to the blob content
     #[serde(rename = "ref")]
     pub r#ref: BlobRef,
 }
 
+/// A reference to blob content via CID link.
 #[derive(Debug, Clone, Deserialize)]
 pub struct BlobRef {
+    /// The CID link to the blob content
     #[serde(rename = "$link")]
     pub link: String,
 }
 
+/// An attachment to a blog post.
 #[derive(Debug, Clone, Deserialize)]
 pub struct PostAttachment {
+    /// The attachment type
     #[serde(rename = "$type")]
     pub r#type: String,
 
+    /// The blob content of the attachment
     pub content: BlobRecord,
 }
 
+/// A blog post record from the ATProtocol lexicon.
 #[derive(Debug, Clone, Deserialize)]
 pub struct PostRecord {
+    /// The record type
     #[serde(rename = "$type")]
     pub r#type: String,
 
+    /// Title of the blog post
     pub title: String,
+    /// Main content of the blog post
     pub content: BlobRecord,
 
+    /// Publication timestamp
     #[serde(rename = "publishedAt")]
     pub published_at: DateTime<Utc>,
 
+    /// List of attachments to the post
     #[serde(default = "empty_attachments")]
     pub attachments: Vec<PostAttachment>,
 
+    /// Languages used in the post
     pub langs: Vec<String>,
 }
 

src/lib.rs

···
+//! # Blahg - ATProtocol Blog AppView
+//!
+//! Blahg is a Rust-based ATProtocol AppView that renders personal blog content.
+//! It consumes ATProtocol records to create a blog-like experience by discovering
+//! and displaying relevant posts.
+//!
+//! ## Architecture
+//!
+//! - **ATProtocol Integration**: Uses the atproto ecosystem crates for identity resolution and record processing
+//! - **Storage Layer**: Flexible storage backends including SQLite, PostgreSQL, and content storage
+//! - **Rendering**: Markdown rendering with syntax highlighting
+//! - **Event Processing**: Real-time consumption of ATProtocol events via jetstream
+//!
+//! ## Key Components
+//!
+//! - [`config`] - Configuration management
+//! - [`consumer`] - ATProtocol event consumption
+//! - [`process`] - Event processing and record handling
+//! - [`storage`] - Data persistence layer
+//! - [`render`] - Markdown rendering
+//! - [`http`] - Web server and API endpoints
+//! - [`identity`] - ATProtocol identity resolution
+//! - [`lexicon`] - ATProtocol record type definitions
+
 #![warn(missing_docs)]
 
+/// Configuration management for the Blahg application.
 pub mod config;
+/// ATProtocol event consumption and handling.
 pub mod consumer;
+/// Error types and handling for the Blahg application.
 pub mod errors;
+/// HTTP server and web API endpoints.
 pub mod http;
+/// ATProtocol identity resolution and caching.
 pub mod identity;
+/// ATProtocol record type definitions and lexicon.
 pub mod lexicon;
+/// Event processing and record handling logic.
 pub mod process;
+/// Markdown rendering with syntax highlighting.
 pub mod render;
+/// Data persistence layer with multiple backend support.
 pub mod storage;
+/// Template management and rendering.
 pub mod templates;

src/process.rs

···
 #[derive(Debug, Deserialize, Serialize, Default)]
 struct StrongRef {
     #[serde(rename = "$type")]
-    pub type_: Option<String>,
-    pub uri: String,
-    pub cid: String,
+    type_: Option<String>,
+    uri: String,
+    cid: String,
 }
 
 /// app.bsky.feed.post record structure
 #[derive(Debug, Deserialize)]
 struct FeedPostRecord {
     #[serde(rename = "$type")]
-    pub type_: Option<String>,
+    type_: Option<String>,
 
     #[serde(default)]
     facets: Vec<Facet>,
···
         }
 
         Ok(())
-    }
-
-    /// Check if an AT-URI references a post from a known author
-    fn is_known_author_post(&self, uri: &str) -> bool {
-        if let Ok(aturi) = ATURI::from_str(uri) {
-            return aturi.collection == "tools.smokesignal.blahg.content.post"
-                && self.config.author == aturi.authority;
-        }
-        false
     }
 
     /// Creates a post prefix lookup hashmap with external URL prefixes mapped to AT-URIs

src/render.rs

···
 use std::sync::Arc;
 
 
+/// Trait for rendering markdown content to HTML.
 #[async_trait]
 pub trait RenderManager: Send + Sync {
+    /// Render markdown content to HTML.
     async fn render_markdown(&self, markdown: &str) -> Result<String>;
 }
 
+/// A markdown renderer using the Comrak library with syntax highlighting.
 pub struct ComrakRenderManager<'a> {
     syntect_adapter: Arc<SyntectAdapter>,
     options: Options<'a>,
···
 }
 
 impl ComrakRenderManager<'static> {
+
+    #[cfg(test)]
+    /// Create a new Comrak render manager with the given external base URL.
     pub fn new(external_base: &str) -> Self {
+        Self::with_theme("base16-ocean.dark", external_base)
+    }
+
+    /// Create a new Comrak render manager with the given theme and external base URL.
+    pub fn with_theme(theme: &str, external_base: &str) -> Self {
         let syntect_adapter = Arc::new(
             SyntectAdapterBuilder::new()
-                .theme("base16-ocean.dark")
+                .theme(theme)
                 .build(),
         );
-
-        let mut options = Options::default();
-        options.extension.strikethrough = true;
-        options.extension.table = true;
-        options.extension.autolink = true;
-        options.extension.tasklist = true;
-        options.extension.superscript = true;
-        options.extension.footnotes = true;
-        options.extension.description_lists = true;
-        options.render.unsafe_ = false;
-
-        Self {
-            syntect_adapter,
-            options,
-            external_base: external_base.to_string(),
-        }
-    }
-
-    fn with_theme(theme: &str, external_base: &str) -> Self {
-        let syntect_adapter = Arc::new(SyntectAdapterBuilder::new().theme(theme).build());
-
-        let mut options = Options::default();
-        options.extension.strikethrough = true;
-        options.extension.table = true;
-        options.extension.autolink = true;
-        options.extension.tasklist = true;
-        options.extension.superscript = true;
-        options.extension.footnotes = true;
-        options.extension.description_lists = true;
-        options.render.unsafe_ = false;
-
-        Self {
-            syntect_adapter,
-            options,
-            external_base: external_base.to_string(),
-        }
-    }
-
-    fn with_css(external_base: &str) -> Self {
-        let syntect_adapter = Arc::new(SyntectAdapterBuilder::new().css().build());
 
         let mut options = Options::default();
         options.extension.strikethrough = true;

src/storage/cached.rs

···
 
 use super::{ContentStorage, Identity, IdentityStorage, Post, PostReference, PostStorage, Storage};
 
+/// A caching layer for post storage that keeps posts in memory.
 pub struct CachedPostStorage<T: Storage> {
     underlying_storage: Arc<T>,
     post_cache: Arc<RwLock<Option<HashMap<String, Post>>>>,
 }
 
 impl<T: Storage> CachedPostStorage<T> {
+    /// Create a new cached post storage with the given underlying storage.
     pub fn new(underlying_storage: Arc<T>) -> Self {
         Self {
             underlying_storage,
···
         }
 
         *cache = Some(post_map);
-        Ok(())
-    }
-
-    async fn invalidate_cache(&self) -> Result<()> {
-        let mut cache = self.post_cache.write().await;
-        *cache = None;
         Ok(())
     }
 

src/storage/content.rs

···
 }
 
 #[cfg(feature = "s3")]
+/// S3-compatible object storage implementation for content storage.
 pub struct S3FileStorage {
     client: MinioClient,
     bucket: String,

src/storage/mod.rs

···
 use serde_json::Value;
 use std::collections::HashMap;
 
+/// An ATProtocol identity record.
 #[derive(Clone, Serialize, Deserialize, sqlx::FromRow)]
 pub struct Identity {
-    pub did: String,
-    pub handle: String,
-    pub record: Value,
-    pub created_at: DateTime<Utc>,
-    pub updated_at: DateTime<Utc>,
+    /// The decentralized identifier (DID) of the identity
+    pub (crate) did: String,
+    /// The handle associated with the identity
+    pub (crate) handle: String,
+    /// The identity document as JSON
+    pub (crate) record: Value,
+    /// When the identity was first created
+    pub (crate) created_at: DateTime<Utc>,
+    /// When the identity was last updated
+    pub (crate) updated_at: DateTime<Utc>,
 }
 
-// tools.smokesignal.blahg.content.post
+/// A blog post record from the `tools.smokesignal.blahg.content.post` collection.
 #[derive(Clone, Serialize, Deserialize, sqlx::FromRow)]
 pub struct Post {
+    /// The AT-URI of the post record
     pub aturi: String,
+    /// The content identifier (CID) of the post
     pub cid: String,
+    /// The title of the blog post
     pub title: String,
+    /// The URL slug for the post
     pub slug: String,
+    /// The markdown content of the post
     pub content: String,
+    /// The record key within the collection
     pub record_key: String,
+    /// When the post was first created
     pub created_at: DateTime<Utc>,
+    /// When the post was last updated
     pub updated_at: DateTime<Utc>,
+    /// The original ATProtocol record as JSON
     pub record: Value,
 }
 
+/// A reference to a blog post from another ATProtocol record.
 #[derive(Clone, Serialize, Deserialize, sqlx::FromRow)]
 pub struct PostReference {
+    /// The AT-URI of the reference record
     pub aturi: String,
+    /// The content identifier (CID) of the reference
     pub cid: String,
+    /// The DID of the author who created the reference
     pub did: String,
+    /// The collection containing the reference
     pub collection: String,
+    /// The AT-URI of the post being referenced
     pub post_aturi: String,
+    /// When the reference was discovered
     pub discovered_at: DateTime<Utc>,
+    /// The original reference record as JSON
     pub record: Value,
 }
 
+/// Trait for storing and retrieving blog posts and post references.
 #[async_trait]
 pub trait PostStorage: Send + Sync {
+    /// Insert or update a blog post.
     async fn upsert_post(&self, post: &Post) -> Result<()>;
 
+    /// Get a blog post by its AT-URI.
     async fn get_post(&self, aturi: &str) -> Result<Option<Post>>;
 
+    /// Get all blog posts.
     async fn get_posts(&self) -> Result<Vec<Post>>;
 
+    /// Delete a blog post by its AT-URI.
     async fn delete_post(&self, aturi: &str) -> Result<Option<Post>>;
 
+    /// Insert or update a post reference.
     async fn upsert_post_reference(&self, post_reference: &PostReference) -> Result<bool>;
 
+    /// Delete a post reference by its AT-URI.
     async fn delete_post_reference(&self, aturi: &str) -> Result<()>;
 
+    /// Get the count of references to a post grouped by collection.
     async fn get_post_reference_count(&self, post_aturi: &str) -> Result<HashMap<String, i64>>;
 
+    /// Get all references to a specific post.
     async fn get_post_references_for_post(&self, post_aturi: &str) -> Result<Vec<PostReference>>;
 
+    /// Get references to a post from a specific collection.
     async fn get_post_references_for_post_for_collection(
         &self,
         post_aturi: &str,
···
     ) -> Result<Vec<PostReference>>;
 }
 
+/// Trait for storing and retrieving ATProtocol identities.
 #[async_trait]
 pub trait IdentityStorage: Send + Sync {
+    /// Insert or update an identity record.
     async fn upsert_identity(&self, identity: &Identity) -> Result<()>;
 
+    /// Get an identity by its DID.
     async fn get_identity_by_did(&self, did: &str) -> Result<Option<Identity>>;
 
+    /// Get an identity by its handle.
     async fn get_identity_by_handle(&self, handle: &str) -> Result<Option<Identity>>;
 
+    /// Delete an identity by its AT-URI.
     async fn delete_identity(&self, aturi: &str) -> Result<Option<Identity>>;
 }
 
+/// Trait for storing and retrieving content by CID.
 #[async_trait]
 pub trait ContentStorage: Send + Sync {
+    /// Check if content exists for a given CID.
     async fn content_exists(&self, cid: &str) -> Result<bool>;
 
+    /// Write content data for a given CID.
     async fn write_content(&self, cid: &str, data: &[u8]) -> Result<()>;
 
+    /// Read content data for a given CID.
     async fn read_content(&self, cid: &str) -> Result<Vec<u8>>;
 }
 
+/// Combined trait for all storage operations.
 #[async_trait]
 pub trait Storage: PostStorage + IdentityStorage + Send + Sync {
+    /// Run database migrations.
     async fn migrate(&self) -> Result<()>;
 }
 
+/// Cached storage implementations.
 pub mod cached;
+/// Content storage implementations.
 pub mod content;
+/// PostgreSQL storage implementation.
 pub mod postgres;
+/// SQLite storage implementation.
 #[cfg(feature = "sqlite")]
 pub mod sqlite;