: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
mod diff;
mod get;
mod list;
mod open;
mod pull;
mod push;
mod run;
use anyhow::{Context, Result};
use clap::{Args, Subcommand};
use colored::Colorize;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use similar::{ChangeTag, TextDiff};
use std::collections::HashMap;
pub use diff::diff_endpoints;
pub use get::get_endpoint;
pub use list::list_endpoints;
pub use open::open_endpoint;
pub use pull::pull_endpoints;
pub use push::push_endpoints;
pub use run::run_endpoint;
use crate::invocation_context::context;
// ============================================================================
// Debug logging utilities
// ============================================================================
/// Log a debug message for API requests. Only prints if debug is true.
#[inline]
pub fn debug_request(debug: bool, method: &str, path: &str) {
if debug {
crate::safe_eprintln!(" {} {} {}", "DEBUG".cyan().bold(), method, path);
}
}
/// Log a debug response body. Only prints if debug is true.
#[inline]
pub fn debug_response_body<T: serde::Serialize>(debug: bool, body: &T) {
if debug {
if let Ok(json) = serde_json::to_string_pretty(body) {
crate::safe_eprintln!(" Response:\n{}", json.dimmed());
}
}
}
/// Log a debug error. Only prints if debug is true.
#[inline]
pub fn debug_error<E: std::fmt::Display>(debug: bool, error: &E) {
if debug {
crate::safe_eprintln!(" {} {}", "Error:".red(), error);
}
}
/// YAML representation of an endpoint for local file storage.
/// This mirrors the API endpoint format but in a simpler YAML-friendly structure.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct EndpointYaml {
/// URL-safe name for the endpoint (required)
pub name: String,
/// Human-readable description of what this endpoint does
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
/// The HogQL query to execute (for simple HogQL queries)
#[serde(default, skip_serializing_if = "Option::is_none")]
pub query: Option<String>,
/// Full query object for complex queries (TrendsQuery, FunnelsQuery, etc.)
/// This takes precedence over the `query` field if both are specified.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub query_definition: Option<Value>,
/// Query variables for parameterized queries
#[serde(default, skip_serializing_if = "Option::is_none")]
pub variables: Option<Vec<EndpointVariable>>,
/// Materialization configuration
#[serde(default, skip_serializing_if = "Option::is_none")]
pub materialization: Option<MaterializationConfig>,
}
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct EndpointVariable {
pub name: String,
#[serde(rename = "type")]
pub var_type: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub default: Option<Value>,
}
/// Materialization configuration for an endpoint.
///
/// When enabled, PostHog will pre-compute and cache the query results
/// according to the specified schedule.
///
/// Valid schedule values: "15min", "30min", "1hour", "6hour", "12hour", "24hour", "7day"
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct MaterializationConfig {
#[serde(default)]
pub enabled: bool,
/// Schedule string. Valid values: 15min, 30min, 1hour, 6hour, 12hour, 24hour, 7day
#[serde(default, skip_serializing_if = "Option::is_none")]
pub schedule: Option<String>,
}
/// Convert a local YAML schedule string to data_freshness_seconds.
/// Returns None if the schedule string is unrecognized.
pub fn schedule_to_data_freshness_seconds(schedule: &str) -> Option<i64> {
match schedule {
"15min" => Some(900),
"30min" => Some(1800),
"1hour" => Some(3600),
"6hour" => Some(21600),
"12hour" => Some(43200),
"24hour" => Some(86400),
"7day" => Some(604800),
_ => None,
}
}
/// Convert a data_freshness_seconds value to its canonical schedule string.
/// Returns None if the value is not a recognized bucket.
pub fn data_freshness_seconds_to_schedule(seconds: i64) -> Option<&'static str> {
match seconds {
900 => Some("15min"),
1800 => Some("30min"),
3600 => Some("1hour"),
21600 => Some("6hour"),
43200 => Some("12hour"),
86400 => Some("24hour"),
604800 => Some("7day"),
_ => None,
}
}
/// API response for an endpoint from PostHog
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct EndpointResponse {
pub id: String,
pub name: String,
#[serde(default)]
pub description: String,
pub query: Value,
#[serde(default)]
pub parameters: HashMap<String, Value>,
pub is_active: bool,
#[serde(default)]
pub data_freshness_seconds: Option<i64>,
pub endpoint_path: String,
#[serde(default)]
pub url: Option<String>,
#[serde(default)]
pub ui_url: Option<String>,
pub created_at: String,
pub updated_at: String,
pub is_materialized: bool,
#[serde(default)]
pub current_version: i32,
#[serde(default)]
pub versions_count: i32,
#[serde(default)]
pub materialization: Option<MaterializationStatus>,
}
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct MaterializationStatus {
#[serde(default)]
pub status: Option<String>,
#[serde(default)]
pub can_materialize: bool,
#[serde(default)]
pub last_materialized_at: Option<String>,
#[serde(default)]
pub error: Option<String>,
#[serde(default)]
pub reason: Option<String>,
}
#[derive(Debug, Serialize, Deserialize)]
pub struct EndpointListResponse {
pub results: Vec<EndpointResponse>,
}
#[derive(Subcommand)]
pub enum EndpointCommand {
/// List all PostHog endpoints
List(ListArgs),
/// Get details of a specific PostHog endpoint
Get(GetArgs),
/// Open an endpoint in the browser
Open(OpenArgs),
/// Run an endpoint and see the results
Run(RunArgs),
/// Push local endpoint YAML files to PostHog
Push(PushArgs),
/// Pull PostHog endpoints to local endpoint YAML files
Pull(PullArgs),
/// Show differences between local YAML files and remote endpoints
Diff(DiffArgs),
}
#[derive(Args, Clone)]
pub struct ListArgs {
/// Show detailed API request/response information
#[arg(long)]
pub debug: bool,
}
#[derive(Args, Clone)]
pub struct OpenArgs {
/// Name of the endpoint to open
pub name: String,
/// Show detailed API request/response information
#[arg(long)]
pub debug: bool,
}
#[derive(Args, Clone)]
pub struct GetArgs {
/// Name of the endpoint to get
pub name: String,
/// Show detailed API request/response information
#[arg(long)]
pub debug: bool,
}
#[derive(Args, Clone)]
pub struct RunArgs {
/// Name of the endpoint to run
#[arg(conflicts_with = "file")]
pub name: Option<String>,
/// Run query from a local YAML file (without creating endpoint)
#[arg(long, short = 'f')]
pub file: Option<String>,
/// Pass a variable (can be used multiple times, format: name=value)
#[arg(long = "var", short = 'v')]
pub var: Vec<String>,
/// Output raw JSON
#[arg(long)]
pub json: bool,
/// Output format (table, json)
#[arg(long)]
pub format: Option<String>,
/// Suppress status messages
#[arg(long, short = 'q')]
pub quiet: bool,
/// Show detailed API request/response information
#[arg(long)]
pub debug: bool,
}
#[derive(Args, Clone)]
pub struct PushArgs {
/// Local PostHog YAML files or directories to push to PostHog
#[arg(required = true)]
pub paths: Vec<String>,
/// Preview changes without applying
#[arg(long)]
pub dry_run: bool,
/// Skip confirmation prompt
#[arg(long, short = 'y')]
pub yes: bool,
/// Show detailed API request/response information
#[arg(long)]
pub debug: bool,
}
#[derive(Args, Clone)]
pub struct PullArgs {
/// Endpoint name(s) to pull
#[arg()]
pub names: Vec<String>,
/// Pull all endpoints
#[arg(long)]
pub all: bool,
/// Output path (directory for multiple endpoints, or .yaml/.yml file for single endpoint)
#[arg(long, short = 'o', default_value = ".")]
pub output: String,
/// Preview changes without writing to YAML files
#[arg(long)]
pub dry_run: bool,
/// Skip confirmation prompt
#[arg(long, short = 'y')]
pub yes: bool,
/// Show detailed API request/response information
#[arg(long)]
pub debug: bool,
}
#[derive(Args, Clone)]
pub struct DiffArgs {
/// Local YAML files or directories to compare
#[arg(required = true)]
pub paths: Vec<String>,
/// Show unchanged endpoints too
#[arg(long, short = 'v')]
pub verbose: bool,
/// Show detailed API request/response information
#[arg(long)]
pub debug: bool,
}
impl EndpointCommand {
pub fn run(&self) -> Result<()> {
match self {
EndpointCommand::List(args) => list_endpoints(args),
EndpointCommand::Get(args) => get_endpoint(args),
EndpointCommand::Open(args) => open_endpoint(args),
EndpointCommand::Run(args) => run_endpoint(args),
EndpointCommand::Push(args) => push_endpoints(args),
EndpointCommand::Pull(args) => pull_endpoints(args),
EndpointCommand::Diff(args) => diff_endpoints(args),
}
}
}
/// Resolved variable mapping: code_name -> (variableId, InsightVariable)
pub type ResolvedVariables = HashMap<String, (String, InsightVariable)>;
impl EndpointYaml {
/// Convert this YAML representation to an API request body.
/// If resolved_variables is provided, includes the variables in the query.
pub fn to_api_request(&self, resolved_variables: Option<&ResolvedVariables>) -> Value {
let mut request = serde_json::Map::new();
request.insert("name".to_string(), Value::String(self.name.clone()));
if let Some(desc) = &self.description {
request.insert("description".to_string(), Value::String(desc.clone()));
}
// Build the query object
let mut query = if let Some(query_def) = &self.query_definition {
// Use the full query definition if provided
query_def.clone()
} else if let Some(hogql) = &self.query {
// Build a HogQLQuery from the simple query string
let mut q = serde_json::Map::new();
q.insert("kind".to_string(), Value::String("HogQLQuery".to_string()));
q.insert("query".to_string(), Value::String(hogql.clone()));
Value::Object(q)
} else {
// No query specified - this should be caught during validation
Value::Null
};
// Add resolved variables to the query object
if let (Some(resolved), Some(local_vars)) = (resolved_variables, &self.variables) {
if !local_vars.is_empty() {
let mut vars_obj = serde_json::Map::new();
for local_var in local_vars {
if let Some((var_id, insight_var)) = resolved.get(&local_var.name) {
let mut var_entry = serde_json::Map::new();
var_entry.insert("variableId".to_string(), Value::String(var_id.clone()));
var_entry.insert(
"code_name".to_string(),
Value::String(insight_var.code_name.clone()),
);
if let Some(default) = &local_var.default {
var_entry.insert("value".to_string(), default.clone());
}
vars_obj.insert(var_id.clone(), Value::Object(var_entry));
}
}
if !vars_obj.is_empty() {
if let Value::Object(ref mut q) = query {
q.insert("variables".to_string(), Value::Object(vars_obj));
}
}
}
}
request.insert("query".to_string(), query);
// Handle materialization
if let Some(mat) = &self.materialization {
request.insert("is_materialized".to_string(), Value::Bool(mat.enabled));
if let Some(schedule) = &mat.schedule {
if let Some(seconds) = schedule_to_data_freshness_seconds(schedule) {
request.insert(
"data_freshness_seconds".to_string(),
Value::Number(seconds.into()),
);
}
}
}
Value::Object(request)
}
/// Extract variable references from the query string.
/// Looks for patterns like {variables.code_name}
pub fn get_variable_references(&self) -> Vec<String> {
let query_str = self.query.as_deref().unwrap_or("");
extract_variable_references(query_str)
}
/// Create an EndpointYaml from an API response
pub fn from_api_response(response: &EndpointResponse) -> Self {
let (query, query_definition) = if let Some(kind) = response.query.get("kind") {
if kind == "HogQLQuery" {
// Simple HogQL query - extract just the query string
let query_str = response
.query
.get("query")
.and_then(|q| q.as_str())
.map(|s| s.replace("\r\n", "\n").replace("\r", "\n"));
(query_str, None)
} else {
// Complex query - store the full definition
(None, Some(response.query.clone()))
}
} else {
(None, Some(response.query.clone()))
};
// Extract variables from the query object
let variables = response
.query
.get("variables")
.and_then(|v| v.as_object())
.map(|vars_map| {
vars_map
.values()
.filter_map(|var| {
let code_name = var.get("code_name")?.as_str()?.to_string();
let default = var.get("value").cloned();
// Infer type from the default value
let var_type = match &default {
Some(Value::Number(n)) => {
if n.is_i64() || n.is_u64() {
"integer"
} else {
"number"
}
}
Some(Value::Bool(_)) => "boolean",
Some(Value::String(_)) => "string",
Some(Value::Array(_)) => "array",
Some(Value::Object(_)) => "object",
Some(Value::Null) | None => "string",
};
Some(EndpointVariable {
name: code_name,
var_type: var_type.to_string(),
default,
})
})
.collect::<Vec<_>>()
})
.filter(|v: &Vec<EndpointVariable>| !v.is_empty());
let materialization = if response.is_materialized {
let schedule = response
.data_freshness_seconds
.and_then(data_freshness_seconds_to_schedule)
.map(|s| s.to_string());
Some(MaterializationConfig {
enabled: true,
schedule,
})
} else {
None
};
EndpointYaml {
name: response.name.clone(),
description: if response.description.is_empty() {
None
} else {
Some(response.description.clone())
},
query,
query_definition,
variables,
materialization,
}
}
/// Validate the endpoint YAML (basic structural checks only, backend validates the rest)
pub fn validate(&self) -> Result<()> {
if self.name.is_empty() {
anyhow::bail!("Endpoint name is required");
}
if self.query.is_none() && self.query_definition.is_none() {
anyhow::bail!(
"Either 'query' or 'query_definition' is required for endpoint '{}'",
self.name
);
}
if let Some(mat) = &self.materialization {
if let Some(schedule) = &mat.schedule {
if schedule_to_data_freshness_seconds(schedule).is_none() {
anyhow::bail!(
"Invalid materialization.schedule '{}' for endpoint '{}'. Must be one of: 15min, 30min, 1hour, 6hour, 12hour, 24hour, 7day",
schedule,
self.name
);
}
}
}
Ok(())
}
}
// ============================================================================
// Shared utilities for push/pull change tracking
// ============================================================================
/// Represents a change between local and remote endpoint state
#[derive(Debug, Clone)]
pub enum Change {
Description { from: String, to: String },
Query { from: String, to: String },
QueryDefinition { from: String, to: String },
Materialization { from: bool, to: bool },
Schedule { from: String, to: String },
Variables { from: Vec<String>, to: Vec<String> },
}
/// Format a change for human-readable display
pub fn format_change_summary(change: &Change) -> String {
match change {
Change::Description { from, to } => {
format!(
"Description: {} → {}",
if from.is_empty() {
"(empty)"
} else {
from.as_str()
},
if to.is_empty() {
"(empty)"
} else {
to.as_str()
}
)
}
Change::Query { .. } => "Query".to_string(),
Change::QueryDefinition { .. } => "Query definition".to_string(),
Change::Materialization { from, to } => {
format!(
"Materialization: {} → {}",
if *from { "enabled" } else { "disabled" },
if *to { "enabled" } else { "disabled" }
)
}
Change::Schedule { from, to } => {
format!(
"Schedule: {} → {}",
if from.is_empty() {
"(none)"
} else {
from.as_str()
},
if to.is_empty() { "(none)" } else { to.as_str() }
)
}
Change::Variables { from, to } => {
let from_str = if from.is_empty() {
"(none)".to_string()
} else {
from.join(", ")
};
let to_str = if to.is_empty() {
"(none)".to_string()
} else {
to.join(", ")
};
format!("Variables: [{from_str}] → [{to_str}]")
}
}
}
/// Print a unified diff of two strings with colored output
pub fn print_diff(from: &str, to: &str, indent: &str) {
let diff = TextDiff::from_lines(from, to);
for change in diff.iter_all_changes() {
let (sign, color_fn): (&str, fn(&str) -> colored::ColoredString) = match change.tag() {
ChangeTag::Delete => ("-", |s: &str| s.red()),
ChangeTag::Insert => ("+", |s: &str| s.green()),
ChangeTag::Equal => (" ", |s: &str| s.dimmed()),
};
let line = change.to_string_lossy();
let line_trimmed = line.trim_end_matches('\n');
crate::safe_println!("{indent}{} {}", color_fn(sign), color_fn(line_trimmed));
}
}
// ============================================================================
// Shared comparison helpers
// ============================================================================
/// Extract variable code_names from a remote endpoint response
pub fn get_remote_variable_names(remote: &EndpointResponse) -> Vec<String> {
remote
.query
.get("variables")
.and_then(|v| v.as_object())
.map(|vars_map| {
vars_map
.values()
.filter_map(|var| var.get("code_name")?.as_str().map(|s| s.to_string()))
.collect()
})
.unwrap_or_default()
}
/// Get the schedule from local YAML (empty string if none)
pub fn get_local_schedule(local: &EndpointYaml) -> String {
local
.materialization
.as_ref()
.and_then(|m| m.schedule.clone())
.unwrap_or_default()
}
/// Get the schedule from remote endpoint (empty string if none)
pub fn get_remote_schedule(remote: &EndpointResponse) -> String {
remote
.data_freshness_seconds
.and_then(data_freshness_seconds_to_schedule)
.map(|s| s.to_string())
.unwrap_or_default()
}
/// Compute changes between local and remote endpoints (for push/diff direction).
/// Returns changes where `from` is the remote state and `to` is the local state.
pub fn compute_changes_for_push(local: &EndpointYaml, remote: &EndpointResponse) -> Vec<Change> {
let mut changes = Vec::new();
// Description
let local_desc = local.description.as_deref().unwrap_or("");
if local_desc != remote.description {
changes.push(Change::Description {
from: remote.description.clone(),
to: local_desc.to_string(),
});
}
// Query (for HogQL queries)
let local_query = local.query.as_deref().unwrap_or("");
let remote_query = remote
.query
.get("query")
.and_then(|q| q.as_str())
.unwrap_or("");
if !local_query.is_empty() && local_query != remote_query {
changes.push(Change::Query {
from: remote_query.to_string(),
to: local_query.to_string(),
});
} else if let Some(local_def) = &local.query_definition {
let local_json = serde_json::to_string_pretty(local_def).unwrap_or_default();
let remote_json = serde_json::to_string_pretty(&remote.query).unwrap_or_default();
if local_json != remote_json {
changes.push(Change::QueryDefinition {
from: remote_json,
to: local_json,
});
}
}
// Materialization enabled/disabled
let local_mat = local
.materialization
.as_ref()
.map(|m| m.enabled)
.unwrap_or(false);
if local_mat != remote.is_materialized {
changes.push(Change::Materialization {
from: remote.is_materialized,
to: local_mat,
});
}
// Schedule
let local_schedule = get_local_schedule(local);
let remote_schedule = get_remote_schedule(remote);
if local_schedule != remote_schedule {
changes.push(Change::Schedule {
from: remote_schedule,
to: local_schedule,
});
}
// Variables
let local_vars: Vec<String> = local
.variables
.as_ref()
.map(|vars| vars.iter().map(|v| v.name.clone()).collect())
.unwrap_or_default();
let remote_vars = get_remote_variable_names(remote);
let mut local_sorted = local_vars.clone();
let mut remote_sorted = remote_vars.clone();
local_sorted.sort();
remote_sorted.sort();
if local_sorted != remote_sorted {
changes.push(Change::Variables {
from: remote_vars,
to: local_vars,
});
}
changes
}
// ============================================================================
// InsightVariable API types
// ============================================================================
/// PostHog InsightVariable from the API
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct InsightVariable {
pub id: String,
pub name: String,
pub code_name: String,
#[serde(rename = "type")]
pub var_type: String,
#[serde(default)]
pub default_value: Option<Value>,
}
#[derive(Debug, Serialize, Deserialize)]
pub struct InsightVariableListResponse {
pub results: Vec<InsightVariable>,
}
/// Request body for creating an InsightVariable
#[derive(Debug, Serialize)]
pub struct CreateInsightVariableRequest {
pub name: String,
pub code_name: String,
#[serde(rename = "type")]
pub var_type: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub default_value: Option<Value>,
}
// ============================================================================
// Shared API helpers
// ============================================================================
/// Fetch all insight variables for the current environment
pub fn fetch_insight_variables(debug: bool) -> Result<Vec<InsightVariable>> {
let client = &context().client;
debug_request(debug, "GET", "insight_variables/");
let result = client.send_get(client.env_url("insight_variables/")?, |req| req);
match result {
Ok(response) => {
let list: InsightVariableListResponse = response
.json()
.context("Failed to parse insight variables response")?;
if debug {
crate::safe_eprintln!(
" Response: {} variable{}",
list.results.len(),
if list.results.len() == 1 { "" } else { "s" }
);
}
Ok(list.results)
}
Err(e) => {
debug_error(debug, &e);
Err(e).context("Failed to fetch insight variables")
}
}
}
/// Create a new insight variable
/// If debug is true, prints the request body and any error response
pub fn create_insight_variable(
request: &CreateInsightVariableRequest,
debug: bool,
) -> Result<InsightVariable> {
let client = &context().client;
if debug {
crate::safe_eprintln!(" {} POST insight_variables/", "DEBUG".cyan().bold());
if let Ok(json) = serde_json::to_string_pretty(request) {
crate::safe_eprintln!(" Request body:\n{}", json.dimmed());
}
}
let result = client.send_post(client.env_url("insight_variables/")?, |req| {
req.json(request)
});
match result {
Ok(response) => response.json().context("Failed to parse variable response"),
Err(e) => {
if debug {
crate::safe_eprintln!(" {} {}", "Error:".red(), e);
}
Err(e).with_context(|| format!("Failed to create variable '{}'", request.code_name))
}
}
}
/// Fetch a single endpoint by name from PostHog
pub fn fetch_endpoint(name: &str, debug: bool) -> Result<EndpointResponse> {
let client = &context().client;
let path = format!("endpoints/{name}/");
debug_request(debug, "GET", &path);
let url = client.env_url(&path)?;
let result = client.send_get(url, |req| req);
match result {
Ok(response) => {
let endpoint: EndpointResponse = response
.json()
.context("Failed to parse endpoint response")?;
debug_response_body(debug, &endpoint);
Ok(endpoint)
}
Err(e) => {
debug_error(debug, &e);
Err(e).with_context(|| format!("Failed to fetch endpoint '{name}'"))
}
}
}
/// Fetch all endpoints from PostHog
pub fn fetch_all_endpoints(debug: bool) -> Result<EndpointListResponse> {
let client = &context().client;
debug_request(debug, "GET", "endpoints/");
let result = client.send_get(client.env_url("endpoints/")?, |req| req);
match result {
Ok(response) => {
let list: EndpointListResponse = response
.json()
.context("Failed to parse endpoints response")?;
if debug {
crate::safe_eprintln!(
" Response: {} endpoint{}",
list.results.len(),
if list.results.len() == 1 { "" } else { "s" }
);
}
Ok(list)
}
Err(e) => {
debug_error(debug, &e);
Err(e).context("Failed to fetch endpoints")
}
}
}
// ============================================================================
// Variable reference extraction
// ============================================================================
/// Extract variable references from a HogQL query string.
/// Looks for patterns like {variables.code_name}
pub fn extract_variable_references(query: &str) -> Vec<String> {
let re = regex::Regex::new(r"\{variables\.([a-zA-Z_][a-zA-Z0-9_]*)\}")
.expect("valid regex pattern for variable references");
re.captures_iter(query)
.filter_map(|cap| cap.get(1).map(|m| m.as_str().to_string()))
.collect()
}
// ============================================================================
// Schedule/frequency conversion helpers
// ============================================================================
/// Valid sync frequency values for materialization schedules.
///
/// These values map directly to what the PostHog API accepts:
/// - Minutes: "5min", "15min", "30min"
/// - Hours: "1hour", "2hour", "4hour", "6hour", "12hour", "24hour"
/// - Days: "7day", "30day"
pub const VALID_SYNC_FREQUENCIES: &[&str] = &[
"5min", "15min", "30min", "1hour", "2hour", "4hour", "6hour", "12hour", "24hour", "7day",
"30day",
];
#[cfg(test)]
mod tests {
use super::*;
// =========================================================================
// YAML parsing tests
// =========================================================================
#[test]
fn test_parse_simple_endpoint_yaml() {
let yaml = r#"
name: my-endpoint
description: A test endpoint
query: SELECT count() FROM events
"#;
let endpoint: EndpointYaml = serde_yaml::from_str(yaml).unwrap();
assert_eq!(endpoint.name, "my-endpoint");
assert_eq!(endpoint.description, Some("A test endpoint".to_string()));
assert_eq!(
endpoint.query,
Some("SELECT count() FROM events".to_string())
);
assert!(endpoint.query_definition.is_none());
assert!(endpoint.variables.is_none());
assert!(endpoint.materialization.is_none());
}
#[test]
fn test_parse_endpoint_with_variables() {
let yaml = r#"
name: events-by-type
query: SELECT count() FROM events WHERE event = {variables.event_type}
variables:
- name: event_type
type: string
default: "$pageview"
"#;
let endpoint: EndpointYaml = serde_yaml::from_str(yaml).unwrap();
assert_eq!(endpoint.name, "events-by-type");
let vars = endpoint.variables.unwrap();
assert_eq!(vars.len(), 1);
assert_eq!(vars[0].name, "event_type");
assert_eq!(vars[0].var_type, "string");
}
#[test]
fn test_parse_endpoint_with_materialization() {
let yaml = r#"
name: materialized-endpoint
query: SELECT count() FROM events
materialization:
enabled: true
schedule: "1hour"
"#;
let endpoint: EndpointYaml = serde_yaml::from_str(yaml).unwrap();
let mat = endpoint.materialization.unwrap();
assert!(mat.enabled);
assert_eq!(mat.schedule, Some("1hour".to_string()));
}
// =========================================================================
// Variable extraction tests
// =========================================================================
#[test]
fn test_extract_single_variable() {
let query = "SELECT * FROM events WHERE event = {variables.event_name}";
let vars = extract_variable_references(query);
assert_eq!(vars, vec!["event_name"]);
}
#[test]
fn test_extract_multiple_variables() {
let query = "SELECT * FROM events WHERE event = {variables.event_name} AND timestamp > {variables.start_date}";
let vars = extract_variable_references(query);
assert_eq!(vars.len(), 2);
assert!(vars.contains(&"event_name".to_string()));
assert!(vars.contains(&"start_date".to_string()));
}
#[test]
fn test_extract_no_variables() {
let query = "SELECT count() FROM events";
let vars = extract_variable_references(query);
assert!(vars.is_empty());
}
#[test]
fn test_extract_variable_with_underscores() {
let query = "SELECT * FROM events WHERE prop = {variables.my_long_var_name}";
let vars = extract_variable_references(query);
assert_eq!(vars, vec!["my_long_var_name"]);
}
#[test]
fn test_get_variable_references_from_endpoint() {
let endpoint = EndpointYaml {
name: "test".to_string(),
description: None,
query: Some("SELECT * FROM events WHERE type = {variables.event_type}".to_string()),
query_definition: None,
variables: Some(vec![
EndpointVariable {
name: "event_type".to_string(),
var_type: "string".to_string(),
default: None,
},
EndpointVariable {
name: "unused_var".to_string(),
var_type: "string".to_string(),
default: None,
},
]),
materialization: None,
};
let refs = endpoint.get_variable_references();
assert_eq!(refs, vec!["event_type"]);
// This shows unused_var is NOT in query - push command will reject this
let defined: Vec<_> = endpoint
.variables
.unwrap()
.iter()
.map(|v| v.name.clone())
.collect();
let unused: Vec<_> = defined.iter().filter(|v| !refs.contains(v)).collect();
assert_eq!(unused, vec![&"unused_var".to_string()]);
}
// =========================================================================
// Schedule validation tests
// =========================================================================
#[test]
fn test_valid_sync_frequencies() {
// Ensure all expected frequencies are in the list
assert!(VALID_SYNC_FREQUENCIES.contains(&"5min"));
assert!(VALID_SYNC_FREQUENCIES.contains(&"1hour"));
assert!(VALID_SYNC_FREQUENCIES.contains(&"24hour"));
assert!(VALID_SYNC_FREQUENCIES.contains(&"7day"));
}
#[test]
fn test_invalid_sync_frequencies() {
assert!(!VALID_SYNC_FREQUENCIES.contains(&"invalid"));
assert!(!VALID_SYNC_FREQUENCIES.contains(&"*/5 * * * *")); // cron not supported
assert!(!VALID_SYNC_FREQUENCIES.contains(&"3hour")); // not a valid option
}
// =========================================================================
// API request building tests
// =========================================================================
#[test]
fn test_to_api_request_simple() {
let endpoint = EndpointYaml {
name: "test".to_string(),
description: Some("Test endpoint".to_string()),
query: Some("SELECT 1".to_string()),
query_definition: None,
variables: None,
materialization: None,
};
let request = endpoint.to_api_request(None);
assert_eq!(request["name"], "test");
assert_eq!(request["description"], "Test endpoint");
assert_eq!(request["query"]["kind"], "HogQLQuery");
assert_eq!(request["query"]["query"], "SELECT 1");
}
#[test]
fn test_to_api_request_with_materialization() {
let endpoint = EndpointYaml {
name: "mat-test".to_string(),
description: None,
query: Some("SELECT 1".to_string()),
query_definition: None,
variables: None,
materialization: Some(MaterializationConfig {
enabled: true,
schedule: Some("1hour".to_string()),
}),
};
let request = endpoint.to_api_request(None);
assert_eq!(request["is_materialized"], true);
assert_eq!(request["data_freshness_seconds"], 3600);
}
// =========================================================================
// Validation tests
// =========================================================================
#[test]
fn test_validate_requires_name() {
let endpoint = EndpointYaml {
name: "".to_string(),
description: None,
query: Some("SELECT 1".to_string()),
query_definition: None,
variables: None,
materialization: None,
};
assert!(endpoint.validate().is_err());
}
#[test]
fn test_validate_requires_query() {
let endpoint = EndpointYaml {
name: "test".to_string(),
description: None,
query: None,
query_definition: None,
variables: None,
materialization: None,
};
assert!(endpoint.validate().is_err());
}
#[test]
fn test_validate_accepts_query_definition() {
let endpoint = EndpointYaml {
name: "test".to_string(),
description: None,
query: None,
query_definition: Some(serde_json::json!({"kind": "TrendsQuery"})),
variables: None,
materialization: None,
};
assert!(endpoint.validate().is_ok());
}
#[test]
fn test_validate_rejects_off_bucket_schedule() {
let endpoint = EndpointYaml {
name: "test".to_string(),
description: None,
query: Some("SELECT 1".to_string()),
query_definition: None,
variables: None,
materialization: Some(MaterializationConfig {
enabled: true,
schedule: Some("2hour".to_string()),
}),
};
let err = endpoint.validate().unwrap_err();
assert!(err.to_string().contains("Invalid materialization.schedule"));
}
#[test]
fn test_validate_accepts_valid_bucket_schedule() {
let endpoint = EndpointYaml {
name: "test".to_string(),
description: None,
query: Some("SELECT 1".to_string()),
query_definition: None,
variables: None,
materialization: Some(MaterializationConfig {
enabled: true,
schedule: Some("6hour".to_string()),
}),
};
assert!(endpoint.validate().is_ok());
}
// =========================================================================
// Change detection tests
// =========================================================================
#[test]
fn test_format_change_summary_description() {
let change = Change::Description {
from: "Old".to_string(),
to: "New".to_string(),
};
let summary = format_change_summary(&change);
assert!(summary.contains("Old"));
assert!(summary.contains("New"));
}
#[test]
fn test_from_api_response_normalizes_crlf() {
let response = EndpointResponse {
id: "123".to_string(),
name: "test".to_string(),
description: String::new(),
query: serde_json::json!({
"kind": "HogQLQuery",
"query": "SELECT\r\n count()\r\nFROM events\r\nWHERE event = '$pageview'"
}),
parameters: HashMap::new(),
is_active: true,
data_freshness_seconds: None,
endpoint_path: "test".to_string(),
url: None,
ui_url: None,
created_at: "2024-01-01".to_string(),
updated_at: "2024-01-01".to_string(),
is_materialized: false,
current_version: 1,
versions_count: 1,
materialization: None,
};
let yaml = EndpointYaml::from_api_response(&response);
let query = yaml.query.unwrap();
assert!(!query.contains("\r\n"), "query should not contain \\r\\n");
assert!(query.contains('\n'), "query should contain \\n");
assert_eq!(
query,
"SELECT\n count()\nFROM events\nWHERE event = '$pageview'"
);
}
#[test]
fn test_format_change_summary_materialization() {
let change = Change::Materialization {
from: false,
to: true,
};
let summary = format_change_summary(&change);
assert!(summary.contains("disabled"));
assert!(summary.contains("enabled"));
}
}