:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
use anyhow::Context;
use assignment_coordination::store::{EtcdStore, StoreConfig};
use etcd_client::{Client, GetOptions, SortOrder, SortTarget};
use serde::Serialize;
use tokio::sync::Mutex;
use crate::config::Config;
/// Lazily connected etcd client shared by the explorer and the personhog
/// topology tools. Connecting lazily keeps the service starting (and its
/// other tools working) when etcd is unreachable; the first request that
/// needs etcd pays the connect and surfaces the error.
pub struct EtcdHandle {
endpoints: Vec<String>,
client: Mutex<Option<Client>>,
}
impl EtcdHandle {
/// `None` when `ETCD_ENDPOINTS` is unset, which disables the etcd tools.
pub fn from_config(config: &Config) -> Option<Self> {
let endpoints = config.etcd_endpoint_list();
if endpoints.is_empty() {
return None;
}
Some(Self {
endpoints,
client: Mutex::new(None),
})
}
/// `Client` clones share one gRPC channel, and the channel reconnects on
/// its own, so a connection established once is reused for the process
/// lifetime.
pub async fn client(&self) -> anyhow::Result<Client> {
let mut guard = self.client.lock().await;
if let Some(client) = guard.as_ref() {
return Ok(client.clone());
}
// Connect through EtcdStore so its transport tuning (connect
// timeout, HTTP/2 keepalive) stays defined in one place.
let store = EtcdStore::connect(StoreConfig {
endpoints: self.endpoints.clone(),
prefix: String::new(),
})
.await
.with_context(|| format!("connecting to etcd at {:?}", self.endpoints))?;
let client = store.client().clone();
*guard = Some(client.clone());
Ok(client)
}
}
/// The exclusive upper bound of the key range sharing `prefix`: the prefix
/// with its last non-0xff byte incremented (trailing 0xff bytes dropped).
/// Falls back to etcd's "all keys from here" sentinel (`[0]`) when every
/// byte is 0xff.
fn prefix_range_end(prefix: &[u8]) -> Vec<u8> {
let mut end = prefix.to_vec();
while let Some(last) = end.last_mut() {
if *last < 0xff {
*last += 1;
return end;
}
end.pop();
}
vec![0]
}
#[derive(Serialize)]
pub struct KeyMeta {
pub key: String,
pub create_revision: i64,
pub mod_revision: i64,
pub version: i64,
/// 0 when no lease is attached.
pub lease: i64,
pub value_bytes: usize,
}
#[derive(Serialize)]
pub struct KeyList {
pub keys: Vec<KeyMeta>,
/// More keys exist under the prefix beyond this page.
pub more: bool,
/// Total keys under the prefix (not just this page).
pub count: i64,
pub revision: i64,
/// Cursor for the next page; pass as `from_key`.
pub next_from_key: Option<String>,
}
#[derive(Serialize)]
pub struct KeyDetail {
pub key: String,
/// Lossy UTF-8 rendering of the value; check `value_is_utf8` before
/// editing and writing it back.
pub value: String,
pub value_is_utf8: bool,
pub value_bytes: usize,
pub create_revision: i64,
pub mod_revision: i64,
pub version: i64,
pub lease: i64,
/// Remaining seconds on the attached lease, when one exists and the
/// lookup succeeded.
pub lease_ttl_secs: Option<i64>,
pub lease_granted_ttl_secs: Option<i64>,
}
pub async fn list_keys(
client: &Client,
prefix: &str,
from_key: Option<&str>,
limit: i64,
) -> anyhow::Result<KeyList> {
let start = from_key.filter(|k| k.as_bytes() > prefix.as_bytes());
let options = GetOptions::new()
.with_range(prefix_range_end(prefix.as_bytes()))
.with_limit(limit)
.with_sort(SortTarget::Key, SortOrder::Ascend);
let resp = client
.clone()
.get(start.unwrap_or(prefix), Some(options))
.await
.context("etcd range read")?;
let keys: Vec<KeyMeta> = resp
.kvs()
.iter()
.map(|kv| KeyMeta {
key: String::from_utf8_lossy(kv.key()).into_owned(),
create_revision: kv.create_revision(),
mod_revision: kv.mod_revision(),
version: kv.version(),
lease: kv.lease(),
value_bytes: kv.value().len(),
})
.collect();
// The next page starts just after the last key: its bytes plus a zero
// byte is the smallest possible successor.
let next_from_key = if resp.more() {
keys.last().map(|meta| format!("{}\0", meta.key))
} else {
None
};
Ok(KeyList {
more: resp.more(),
count: resp.count(),
revision: resp.header().map(|h| h.revision()).unwrap_or(0),
next_from_key,
keys,
})
}
pub async fn get_key(client: &Client, key: &str) -> anyhow::Result<Option<KeyDetail>> {
let resp = client
.clone()
.get(key, None)
.await
.context("etcd key read")?;
let Some(kv) = resp.kvs().first() else {
return Ok(None);
};
let (lease_ttl_secs, lease_granted_ttl_secs) = if kv.lease() != 0 {
match client.clone().lease_time_to_live(kv.lease(), None).await {
Ok(lease) => (Some(lease.ttl()), Some(lease.granted_ttl())),
// The lease can expire between the key read and this lookup;
// the key detail is still useful without it.
Err(_) => (None, None),
}
} else {
(None, None)
};
Ok(Some(KeyDetail {
key: String::from_utf8_lossy(kv.key()).into_owned(),
value: String::from_utf8_lossy(kv.value()).into_owned(),
value_is_utf8: std::str::from_utf8(kv.value()).is_ok(),
value_bytes: kv.value().len(),
create_revision: kv.create_revision(),
mod_revision: kv.mod_revision(),
version: kv.version(),
lease: kv.lease(),
lease_ttl_secs,
lease_granted_ttl_secs,
}))
}
/// Plain put, never attaching a lease: writing a value to a lease-backed
/// key detaches it from its lease, which the UI warns about before saving.
pub async fn put_key(client: &Client, key: &str, value: &str) -> anyhow::Result<i64> {
let resp = client
.clone()
.put(key, value, None)
.await
.context("etcd put")?;
Ok(resp.header().map(|h| h.revision()).unwrap_or(0))
}
/// Single-key delete only; the explorer deliberately has no prefix delete.
pub async fn delete_key(client: &Client, key: &str) -> anyhow::Result<bool> {
let resp = client
.clone()
.delete(key, None)
.await
.context("etcd delete")?;
Ok(resp.deleted() > 0)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn prefix_range_end_increments_the_last_byte() {
assert_eq!(prefix_range_end(b"/personhog/"), b"/personhog0".to_vec());
assert_eq!(prefix_range_end(b"/"), b"0".to_vec());
}
#[test]
fn prefix_range_end_handles_trailing_0xff() {
assert_eq!(prefix_range_end(&[b'a', 0xff]), vec![b'b']);
assert_eq!(prefix_range_end(&[0xff, 0xff]), vec![0]);
}
}