chore(infra): add gRPC layer, update protobufs, remove immediate module

- Add gRPC service modules: auth, channel, channel settings, member,
  permission
- Update protobuf definitions and generated code
- Remove immediate/ real-time module (superseded by IM service)
- Update etcd discovery and registration
- Update cache, error, config, and build infrastructure
- Add ADR documentation
- Update OpenAPI spec

etcd/discovery.rs

@@ -5,18 +5,151 @@ use uuid::Uuid;
 use crate::error::{AppError, AppResult};
 use crate::pb::{EmailClient, RepoClient};
 
-use super::types::ServiceInstance;
-use super::{EtcdRegistry, EtcdRegistryInner};
+use super::types::{GitksPeerInfo, ServiceInstance};
+use super::{EtcdRegistry, EtcdRegistryInner, storage_name_to_uuid};
+
+/// etcd prefix where gitks nodes register themselves (gitks::cluster::ClusterManager).
+const GITKS_NODES_PREFIX: &str = "/gitks/nodes/";
 
 impl EtcdRegistry {
     pub async fn start_discovery(&self) -> AppResult<()> {
-        self.load_initial("git").await?;
-        self.load_initial("mail").await?;
-        self.spawn_watch("git");
-        self.spawn_watch("mail");
+        // Discover gitks nodes from gitks's own etcd prefix.
+        self.load_gitks_nodes().await?;
+        self.spawn_gitks_watch();
+
+        // Discover mail services from appks's service prefix.
+        if self.email_client.is_none() {
+            self.load_initial("mail").await?;
+            self.spawn_watch("mail");
+        }
         Ok(())
     }
 
+    // Section: gitks node discovery (from /gitks/nodes/)
+
+    async fn load_gitks_nodes(&self) -> AppResult<()> {
+        let resp = {
+            let mut client = self.inner.client.lock().await;
+            client
+                .get(GITKS_NODES_PREFIX, Some(GetOptions::new().with_prefix()))
+                .await
+                .map_err(|e| {
+                    AppError::Config(format!("etcd get {GITKS_NODES_PREFIX} failed: {e}"))
+                })?
+        };
+
+        for kv in resp.kvs() {
+            let key = kv.key_str().unwrap_or_default();
+            let value = kv.value_str().unwrap_or_default();
+            if let Ok(peer) = serde_json::from_str::<GitksPeerInfo>(value) {
+                Self::upsert_gitks_node(&self.inner, key, &peer);
+            } else {
+                tracing::warn!(key = key, "failed to parse gitks peer info from etcd");
+            }
+        }
+
+        tracing::info!(
+            prefix = GITKS_NODES_PREFIX,
+            count = self.inner.git_nodes.len(),
+            "gitks node discovery complete"
+        );
+        Ok(())
+    }
+
+    fn spawn_gitks_watch(&self) {
+        let inner = self.inner.clone();
+
+        tokio::spawn(async move {
+            loop {
+                match Self::gitks_watch_loop(&inner).await {
+                    Ok(()) => break,
+                    Err(e) => {
+                        tracing::warn!(error = %e, "gitks etcd watch disconnected, retrying in 3s");
+                        tokio::time::sleep(std::time::Duration::from_secs(3)).await;
+                    }
+                }
+            }
+        });
+    }
+
+    async fn gitks_watch_loop(inner: &EtcdRegistryInner) -> AppResult<()> {
+        let mut stream = {
+            let mut client = inner.client.lock().await;
+            client
+                .watch(GITKS_NODES_PREFIX, Some(WatchOptions::new().with_prefix()))
+                .await
+                .map_err(|e| {
+                    AppError::Config(format!("etcd watch {GITKS_NODES_PREFIX} failed: {e}"))
+                })?
+        };
+
+        while let Some(resp) = stream.next().await {
+            let resp =
+                resp.map_err(|e| AppError::Config(format!("gitks watch stream error: {e}")))?;
+
+            for event in resp.events() {
+                let Some(kv) = event.kv() else { continue };
+                let key = kv.key_str().unwrap_or_default();
+
+                match event.event_type() {
+                    etcd_client::EventType::Put => {
+                        let value = kv.value_str().unwrap_or_default();
+                        if let Ok(peer) = serde_json::from_str::<GitksPeerInfo>(value) {
+                            Self::upsert_gitks_node(inner, key, &peer);
+                            tracing::info!(
+                                storage_name = %peer.storage_name,
+                                grpc_addr = %peer.grpc_addr,
+                                "gitks node upserted"
+                            );
+                        }
+                    }
+                    etcd_client::EventType::Delete => {
+                        let storage_name = key.strip_prefix(GITKS_NODES_PREFIX).unwrap_or(&key);
+                        let node_id = storage_name_to_uuid(storage_name);
+                        inner.git_nodes.remove(&node_id);
+                        tracing::info!(storage_name = storage_name, "gitks node removed");
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+
+    fn upsert_gitks_node(inner: &EtcdRegistryInner, key: &str, peer: &GitksPeerInfo) {
+        let node_id = storage_name_to_uuid(&peer.storage_name);
+
+        if peer.grpc_addr.is_empty() {
+            tracing::warn!(
+                storage_name = %peer.storage_name,
+                key = key,
+                "gitks peer has empty grpc_addr, skipping"
+            );
+            return;
+        }
+
+        match RepoClient::lazy_connect(&peer.grpc_addr) {
+            Ok(client) => {
+                inner.git_nodes.insert(node_id, client);
+                tracing::debug!(
+                    storage_name = %peer.storage_name,
+                    node_id = %node_id,
+                    grpc_addr = %peer.grpc_addr,
+                    "gitks node connected"
+                );
+            }
+            Err(e) => {
+                tracing::error!(
+                    storage_name = %peer.storage_name,
+                    grpc_addr = %peer.grpc_addr,
+                    error = %e,
+                    "gitks node connect failed"
+                );
+            }
+        }
+    }
+
+    // Section: mail service discovery (from appks's own etcd prefix)
+
     async fn load_initial(&self, service: &str) -> AppResult<()> {
         let prefix = self.service_prefix(service);
         let resp = {
@@ -38,7 +171,7 @@ impl EtcdRegistry {
         tracing::info!(
             service = service,
             prefix = prefix.as_str(),
-            "etcd initial discovery complete"
+            "etcd mail discovery complete"
         );
         Ok(())
     }
@@ -66,7 +199,7 @@ impl EtcdRegistry {
     }
 
     async fn watch_loop(inner: &EtcdRegistryInner, prefix: &str, service: &str) -> AppResult<()> {
-        let (mut watcher, mut stream) = {
+        let mut stream = {
             let mut client = inner.client.lock().await;
             client
                 .watch(prefix, Some(WatchOptions::new().with_prefix()))
@@ -74,8 +207,6 @@ impl EtcdRegistry {
                 .map_err(|e| AppError::Config(format!("etcd watch {prefix} failed: {e}")))?
         };
 
-        let _keep = &mut watcher;
-
         while let Some(resp) = stream.next().await {
             let resp =
                 resp.map_err(|e| AppError::Config(format!("etcd watch stream error: {e}")))?;
@@ -89,12 +220,12 @@ impl EtcdRegistry {
                         let value = kv.value_str().unwrap_or_default();
                         if let Ok(instance) = serde_json::from_str::<ServiceInstance>(value) {
                             Self::upsert_instance(inner, service, key, &instance);
-                            tracing::info!(service = service, key = key, "etcd service upserted");
+                            tracing::info!(service = service, key = key, "mail service upserted");
                         }
                     }
                     etcd_client::EventType::Delete => {
                         Self::remove_instance(inner, service, key);
-                        tracing::info!(service = service, key = key, "etcd service removed");
+                        tracing::info!(service = service, key = key, "mail service removed");
                     }
                 }
             }
@@ -123,20 +254,17 @@ impl EtcdRegistry {
         let addr = instance.addr.clone();
 
         match service {
-            "git" => match RepoClient::lazy_connect(&addr) {
-                Ok(client) => {
-                    inner.git_nodes.insert(node_id, client);
-                }
-                Err(e) => {
-                    tracing::error!(key = key, addr = addr.as_str(), error = %e, "git client connect failed");
-                }
-            },
             "mail" => match EmailClient::lazy_connect(&addr) {
                 Ok(client) => {
                     inner.mail_nodes.insert(node_id, client);
                 }
                 Err(e) => {
-                    tracing::error!(key = key, addr = addr.as_str(), error = %e, "mail client connect failed");
+                    tracing::error!(
+                        key = key,
+                        addr = addr.as_str(),
+                        error = %e,
+                        "mail client connect failed"
+                    );
                 }
             },
             _ => {}
@@ -148,9 +276,6 @@ impl EtcdRegistry {
             return;
         };
         match service {
-            "git" => {
-                inner.git_nodes.remove(&node_id);
-            }
             "mail" => {
                 inner.mail_nodes.remove(&node_id);
             }

etcd/mod.rs

@@ -2,7 +2,7 @@ mod discovery;
 mod register;
 mod types;
 
-pub use types::ServiceInstance;
+pub use types::{GitksPeerInfo, ServiceInstance};
 
 use std::sync::Arc;
 use std::sync::atomic::AtomicI64;
@@ -19,6 +19,7 @@ use crate::pb::{EmailClient, RepoClient};
 #[derive(Clone)]
 pub struct EtcdRegistry {
     pub(crate) inner: Arc<EtcdRegistryInner>,
+    email_client: Option<EmailClient>,
 }
 
 pub(crate) struct EtcdRegistryInner {
@@ -38,7 +39,7 @@ impl EtcdRegistry {
         let opts = etcd_client::ConnectOptions::new()
             .with_connect_timeout(std::time::Duration::from_secs(timeout));
 
-        let client = Client::connect(&endpoints, Some(opts))
+        let client = Client::connect(endpoints, Some(opts))
             .await
             .map_err(|e| AppError::Config(format!("etcd connect failed: {e}")))?;
 
@@ -54,6 +55,25 @@ impl EtcdRegistry {
 
         let key_prefix = config.etcd_key_prefix()?;
 
+        let email_client = match config.email_rpc_addr()? {
+            Some(addr) if !addr.is_empty() => match EmailClient::lazy_connect(&addr) {
+                Ok(client) => {
+                    tracing::info!(addr = %addr, "email client connected via APP_EMAIL_RPC_ADDR");
+                    Some(client)
+                }
+                Err(e) => {
+                    tracing::error!(addr = %addr, error = %e, "email client connect via APP_EMAIL_RPC_ADDR failed");
+                    None
+                }
+            },
+            _ => {
+                tracing::info!(
+                    "APP_EMAIL_RPC_ADDR not set, will fall back to etcd discovery for email"
+                );
+                None
+            }
+        };
+
         Ok(Self {
             inner: Arc::new(EtcdRegistryInner {
                 client: Mutex::new(client),
@@ -63,6 +83,7 @@ impl EtcdRegistry {
                 mail_nodes: DashMap::new(),
                 lease_id: AtomicI64::new(0),
             }),
+            email_client,
         })
     }
 
@@ -75,6 +96,9 @@ impl EtcdRegistry {
     }
 
     pub fn get_email_client(&self) -> Option<EmailClient> {
+        if let Some(ref client) = self.email_client {
+            return Some(client.clone());
+        }
         self.inner
             .mail_nodes
             .iter()
@@ -85,4 +109,18 @@ impl EtcdRegistry {
     pub fn has_git_nodes(&self) -> bool {
         !self.inner.git_nodes.is_empty()
     }
+
+    /// Sort available gitks node UUIDs for deterministic selection.
+    pub fn git_node_ids_sorted(&self) -> Vec<Uuid> {
+        let mut ids: Vec<Uuid> = self.git_node_ids();
+        ids.sort();
+        ids
+    }
+}
+
+/// Derive a deterministic UUID from a gitks storage_name.
+/// Uses UUID v5 with DNS namespace so the same storage_name always
+/// maps to the same UUID across all appks instances.
+pub fn storage_name_to_uuid(storage_name: &str) -> Uuid {
+    Uuid::new_v5(&Uuid::NAMESPACE_DNS, storage_name.as_bytes())
 }

etcd/types.rs

@@ -8,3 +8,19 @@ pub struct ServiceInstance {
     #[serde(default)]
     pub metadata: HashMap<String, String>,
 }
+
+/// Information about a gitks peer node, registered in etcd under /gitks/nodes/.
+/// Mirrors gitks::cluster::types::PeerInfo.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GitksPeerInfo {
+    /// Logical storage name (e.g. "node-a", "default")
+    pub storage_name: String,
+    /// ractor_cluster TCP address (e.g. "10.0.1.4:4697")
+    #[serde(default)]
+    pub cluster_addr: String,
+    /// gRPC service address (e.g. "http://10.0.1.4:50051")
+    pub grpc_addr: String,
+    /// Software version
+    #[serde(default)]
+    pub version: String,
+}