: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 std::{
fmt::Display,
io::{self, BufRead},
num::NonZeroUsize,
path::PathBuf,
};
use anyhow::{bail, Result};
use crate::{
api::{releases::ReleaseBuilder, symbol_sets::DEFAULT_UPLOAD_CONCURRENCY},
utils::{files::FileSelection, xcode::PlistInfo},
};
pub const SOURCEMAP_UPLOAD_CONCURRENCY_ENV: &str = "POSTHOG_CLI_SOURCEMAP_UPLOAD_CONCURRENCY";
#[derive(clap::Args, Clone, Debug)]
pub struct UploadConcurrencyArgs {
/// The number of sourcemap files to upload concurrently
#[arg(
long,
env = SOURCEMAP_UPLOAD_CONCURRENCY_ENV,
default_value_t = DEFAULT_UPLOAD_CONCURRENCY
)]
pub concurrency: NonZeroUsize,
}
#[derive(clap::Args, Clone)]
pub struct FileSelectionArgs {
/// The directory containing the bundled chunks
#[arg(short, long, alias = "file")]
pub directory: Vec<PathBuf>,
/// Read additional file/directory paths from stdin (one per line) [default: false]
#[arg(long, default_value = "false")]
pub stdin: bool,
/// One or more directory glob patterns to exclude from selection
#[arg(short, long, alias = "ignore")]
pub exclude: Vec<String>,
/// One or more directory glob patterns to include in selection
#[arg(short, long)]
pub include: Vec<String>,
}
impl TryFrom<FileSelectionArgs> for FileSelection {
type Error = anyhow::Error;
fn try_from(args: FileSelectionArgs) -> Result<Self> {
let args = args.resolve_stdin()?;
FileSelection::from_roots(args.directory)
.include(args.include)?
.exclude(args.exclude)
}
}
/// Caps on the selection roots Display renders. A stdin-provided selection can hold
/// thousands of paths, and printing them all produces a log line larger than the pipe
/// buffer (16-64 KiB depending on the platform), which kills the process with EAGAIN
/// when stderr is a non-blocking pipe (e.g. inherited from a Node.js parent, as the
/// PostHog bundler plugins do). The count cap keeps the line readable; the byte budget
/// bounds it even when the individual paths are long.
const MAX_DISPLAYED_ROOTS: usize = 8;
const MAX_DISPLAY_BYTES: usize = 1024;
impl Display for FileSelectionArgs {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let mut rendered = String::from("[");
let mut shown = 0usize;
for path in self.directory.iter().take(MAX_DISPLAYED_ROOTS) {
let mut formatted = format!("{path:?}");
// Truncate rather than skip, so even a single pathological path stays inside
// the budget: Debug escaping can inflate a path well past PATH_MAX.
if formatted.len() > MAX_DISPLAY_BYTES {
let mut cut = MAX_DISPLAY_BYTES;
while !formatted.is_char_boundary(cut) {
cut -= 1;
}
formatted.truncate(cut);
formatted.push_str("...");
}
if shown > 0 && rendered.len() + formatted.len() + 2 > MAX_DISPLAY_BYTES {
break;
}
if shown > 0 {
rendered.push_str(", ");
}
rendered.push_str(&formatted);
shown += 1;
}
rendered.push(']');
let omitted = self.directory.len() - shown;
if omitted > 0 {
write!(f, "{rendered} and {omitted} more")
} else {
write!(f, "{rendered}")
}
}
}
impl FileSelectionArgs {
pub fn validate(&self) -> Result<()> {
if self.directory.is_empty() && !self.stdin {
bail!("No --directory provided")
}
for dir in &self.directory {
if !dir.exists() {
bail!("{dir:?} does not exist");
}
}
Ok(())
}
/// Read stdin paths (if `--stdin` was set) and fold them into `directory`,
/// returning a new `FileSelectionArgs` that no longer needs stdin.
/// This allows the resolved args to be cloned and reused by multiple
/// downstream consumers (e.g. inject + upload in the `process` command).
pub fn resolve_stdin(mut self) -> Result<Self> {
if self.stdin {
let stdin = io::stdin();
for line in stdin.lock().lines() {
let line = line?;
let trimmed = line.trim();
if !trimmed.is_empty() {
self.directory.push(PathBuf::from(trimmed));
}
}
self.stdin = false;
}
Ok(self)
}
}
/// How exceptions get associated with a release.
#[derive(clap::ValueEnum, Clone, Copy, Debug, PartialEq, Eq)]
pub enum ReleaseMode {
/// Bind the release to the uploaded symbol sets
SymbolSet,
/// Resolve the release per event (the default). A web build reads an id injected into the
/// chunk. A Hermes build injects nothing, and resolves the release from the app version and
/// namespace the SDK already sends
Event,
}
#[derive(clap::Args, Clone)]
pub struct ReleaseArgs {
/// The project name associated with the uploaded chunks. Required to have the uploaded chunks associated with
/// a specific release. We will try to auto-derive this from git information if not provided. Strongly recommended
/// to be set explicitly during release CD workflows
#[arg(long = "release-name", alias = "project")]
// deprecated alias for backwards compatibility
pub name: Option<String>,
/// The version of the project - this can be a version number, semantic version, or a git commit hash. Required
/// to have the uploaded chunks associated with a specific release. We will try to auto-derive this from git information
/// if not provided.
#[arg(long = "release-version", alias = "version")]
// deprecated alias for backwards compatibility
pub version: Option<String>,
/// The build number (e.g., 42, CFBundleVersion on iOS, versionCode on Android).
/// Stored as release metadata. When omitted, no build info is recorded.
#[arg(long)]
pub build: Option<String>,
/// Read missing release fields from an iOS Info.plist file.
#[arg(long, value_name = "PATH")]
pub info_plist: Option<PathBuf>,
/// If the server returns a release_id_mismatch error (symbol set already exists with a different release),
/// retry the upload without associating a release instead of failing. [default: true]
#[arg(long, default_value = "true")]
pub skip_release_on_fail: bool,
}
#[derive(clap::Args, Clone, Default)]
pub struct UploadConflictArgs {
/// Allow overwriting an existing symbol set whose content has changed. The sourcemap and
/// hermes uploads always overwrite in `event` release mode. [default: false]
#[arg(long, default_value_t = false, conflicts_with = "skip_on_conflict")]
pub force: bool,
/// Skip symbol sets that already exist with different content instead of failing.
/// Existing symbol sets are left unchanged. The sourcemap and hermes uploads ignore this in
/// `event` release mode. [default: false]
#[arg(long, default_value_t = false, conflicts_with = "force")]
pub skip_on_conflict: bool,
}
/// How the server should treat a symbol set that already exists under the chunk id being uploaded
/// with different content.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ConflictBehavior {
/// Overwrite the stored symbol set.
pub force: bool,
/// Leave the stored symbol set alone and carry on rather than failing the run.
pub skip_on_conflict: bool,
}
impl UploadConflictArgs {
/// Resolve what to do about changed content, given the release mode.
///
/// Event mode always overwrites, and neither flag changes that. A chunk's id and its uploaded
/// bytes move independently there. The id comes from content that survives a new release,
/// while the release id travels inside the payload. Every change to that release id makes the
/// chunk conflict under an unchanged id. A web bundle carries it in the injected snippet, so
/// it conflicts on every release. A Hermes map conflicts once, on the build that changes mode.
/// To honor `--skip-on-conflict` would keep the stored payload, so the newer one never lands.
pub fn resolve(&self, release_mode: ReleaseMode) -> ConflictBehavior {
match release_mode {
ReleaseMode::Event => ConflictBehavior {
force: true,
skip_on_conflict: false,
},
ReleaseMode::SymbolSet => ConflictBehavior {
force: self.force,
skip_on_conflict: self.skip_on_conflict,
},
}
}
/// Whether the run asked to skip conflicts but the release mode cannot honor it.
pub fn skip_on_conflict_ignored(&self, release_mode: ReleaseMode) -> bool {
self.skip_on_conflict && release_mode == ReleaseMode::Event
}
}
impl ReleaseArgs {
pub fn resolve_info_plist(&self) -> Result<Self> {
self.resolve_info_plist_with_environment(|name| std::env::var(name).ok())
}
/// Whether the coordinates identify a release an event can resolve.
///
/// An event carries its own app metadata, and the server keys a release on the name and the
/// packed version. It packs the build into that version, so a release without a build matches
/// no event that sends `$app_build`. Call this on resolved args, because `--info-plist` fills
/// the same three fields.
pub fn event_coordinates_complete(&self) -> bool {
self.name.is_some() && self.version.is_some() && self.build.is_some()
}
fn resolve_info_plist_with_environment<F>(&self, environment: F) -> Result<Self>
where
F: Fn(&str) -> Option<String>,
{
let Some(info_plist) = &self.info_plist else {
return Ok(self.clone());
};
let plist = PlistInfo::from_plist(info_plist)?.resolve_release_fields(environment);
let mut resolved = self.clone();
resolved.name = resolved.name.or(plist.bundle_identifier);
resolved.version = resolved.version.or(plist.short_version);
resolved.build = resolved.build.or(plist.bundle_version);
Ok(resolved)
}
}
/// Pack version and build into a single string for release uniqueness.
/// Releases are keyed on (name, version), so "1.0+42" and "1.0+43" are
/// distinct releases. The UI splits on "+" to display them separately.
pub fn pack_version(version: &Option<String>, build: &Option<String>) -> Option<String> {
match (version, build) {
(Some(v), Some(b)) => Some(format!("{v}+{b}")),
(Some(v), None) => Some(v.clone()),
(None, Some(b)) => Some(b.clone()),
(None, None) => None,
}
}
impl From<ReleaseArgs> for ReleaseBuilder {
fn from(args: ReleaseArgs) -> Self {
let mut builder = ReleaseBuilder::default();
args.name.as_ref().map(|project| builder.with_name(project));
pack_version(&args.version, &args.build)
.as_ref()
.map(|version| builder.with_version(version));
builder
}
}
#[cfg(test)]
mod tests {
use super::*;
use clap::Parser;
use std::{collections::HashMap, fs, sync::Mutex};
static CONCURRENCY_ENV_LOCK: Mutex<()> = Mutex::new(());
#[derive(Debug, Parser)]
struct ConcurrencyCli {
#[command(flatten)]
upload: UploadConcurrencyArgs,
}
fn parse_concurrency(args: &[&str], env: Option<&str>) -> clap::error::Result<ConcurrencyCli> {
let _guard = CONCURRENCY_ENV_LOCK.lock().unwrap();
let original = std::env::var_os(SOURCEMAP_UPLOAD_CONCURRENCY_ENV);
match env {
Some(value) => std::env::set_var(SOURCEMAP_UPLOAD_CONCURRENCY_ENV, value),
None => std::env::remove_var(SOURCEMAP_UPLOAD_CONCURRENCY_ENV),
}
let parsed = ConcurrencyCli::try_parse_from(args);
match original {
Some(value) => std::env::set_var(SOURCEMAP_UPLOAD_CONCURRENCY_ENV, value),
None => std::env::remove_var(SOURCEMAP_UPLOAD_CONCURRENCY_ENV),
}
parsed
}
#[test]
fn display_is_bounded_for_large_selections() {
let args = FileSelectionArgs {
directory: (0..10_000)
.map(|i| PathBuf::from(format!("static/chunks/chunk-{i}.js")))
.collect(),
stdin: false,
include: Vec::new(),
exclude: Vec::new(),
};
let rendered = args.to_string();
// Keep the rendered selection far under the smallest pipe buffer (16 KiB): a
// single oversized log line kills the CLI when stderr is a non-blocking pipe.
assert!(rendered.len() < 2048, "rendered {} bytes", rendered.len());
assert!(rendered.ends_with("and 9992 more"), "rendered: {rendered}");
}
#[test]
fn display_truncates_a_single_oversized_path() {
let args = FileSelectionArgs {
directory: vec![PathBuf::from("a".repeat(50_000))],
stdin: false,
include: Vec::new(),
exclude: Vec::new(),
};
let rendered = args.to_string();
assert!(rendered.len() < 2048, "rendered {} bytes", rendered.len());
assert!(rendered.contains("..."), "rendered: {rendered}");
}
#[test]
fn display_is_bounded_for_long_paths() {
let long_segment = "a".repeat(300);
let args = FileSelectionArgs {
directory: (0..10_000)
.map(|i| PathBuf::from(format!("{long_segment}/chunk-{i}.js")))
.collect(),
stdin: false,
include: Vec::new(),
exclude: Vec::new(),
};
let rendered = args.to_string();
assert!(rendered.len() < 2048, "rendered {} bytes", rendered.len());
assert!(rendered.ends_with("more"), "rendered: {rendered}");
}
fn make_args(name: Option<&str>, version: Option<&str>, build: Option<&str>) -> ReleaseArgs {
ReleaseArgs {
name: name.map(String::from),
version: version.map(String::from),
build: build.map(String::from),
info_plist: None,
skip_release_on_fail: true,
}
}
#[test]
fn event_mode_needs_every_release_coordinate() {
// The server packs the build into the version it keys a release on, so a release without
// one matches no event that sends `$app_build`.
let cases = [
// name, version, build, complete
(Some("com.app"), Some("1.0"), Some("42"), true),
(Some("com.app"), Some("1.0"), None, false),
(Some("com.app"), None, Some("42"), false),
(None, Some("1.0"), Some("42"), false),
(None, None, None, false),
];
for (name, version, build, complete) in cases {
assert_eq!(
make_args(name, version, build).event_coordinates_complete(),
complete,
"name={name:?} version={version:?} build={build:?}"
);
}
}
#[test]
fn release_args_to_builder() {
let cases: Vec<(Option<&str>, Option<&str>, bool)> = vec![
// (version, build, has_version)
(Some("1.0"), None, true), // version only
(Some("1.0"), Some("42"), true), // version+build packed into "1.0+42"
(None, Some("42"), true), // build-only → version="42"
(None, None, false), // neither
];
for (version, build, expect_version) in cases {
let builder: ReleaseBuilder = make_args(Some("com.app"), version, build).into();
assert!(builder.has_name(), "name should always be set");
assert_eq!(
builder.has_version(),
expect_version,
"version={version:?} build={build:?}"
);
}
}
#[test]
fn info_plist_fills_only_missing_release_fields() {
let directory = tempfile::tempdir().expect("failed to create temporary directory");
let info_plist = directory.path().join("Info.plist");
fs::write(
&info_plist,
r#"<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
<key>CFBundleIdentifier</key>
<string>com.plist.app</string>
<key>CFBundleShortVersionString</key>
<string>$(APP_VERSION)</string>
<key>CFBundleVersion</key>
<string>42</string>
</dict>
</plist>"#,
)
.expect("failed to write Info.plist");
let environment = HashMap::from([("APP_VERSION".to_string(), "1.2.3".to_string())]);
let args = ReleaseArgs {
name: Some("com.explicit.app".to_string()),
version: None,
build: None,
info_plist: Some(info_plist),
skip_release_on_fail: true,
};
let resolved = args
.resolve_info_plist_with_environment(|name| environment.get(name).cloned())
.expect("Info.plist should resolve");
assert_eq!(resolved.name.as_deref(), Some("com.explicit.app"));
assert_eq!(resolved.version.as_deref(), Some("1.2.3"));
assert_eq!(resolved.build.as_deref(), Some("42"));
}
#[test]
fn event_mode_always_overwrites() {
let cases = [
// (force, skip_on_conflict, release_mode, expected force, expected skip)
(false, false, ReleaseMode::Event, true, false),
// Skipping every chunk would strand the server on the previous release id.
(false, true, ReleaseMode::Event, true, false),
(true, false, ReleaseMode::Event, true, false),
(false, false, ReleaseMode::SymbolSet, false, false),
(false, true, ReleaseMode::SymbolSet, false, true),
(true, false, ReleaseMode::SymbolSet, true, false),
];
for (force, skip_on_conflict, release_mode, expected_force, expected_skip) in cases {
let conflict = UploadConflictArgs {
force,
skip_on_conflict,
};
assert_eq!(
conflict.resolve(release_mode),
ConflictBehavior {
force: expected_force,
skip_on_conflict: expected_skip,
},
"force={force} skip_on_conflict={skip_on_conflict} release_mode={release_mode:?}"
);
}
}
#[test]
fn skip_on_conflict_is_reported_as_ignored_only_in_event_mode() {
let cases = [
// (skip_on_conflict, release_mode, expected)
(true, ReleaseMode::Event, true),
(false, ReleaseMode::Event, false),
(true, ReleaseMode::SymbolSet, false),
(false, ReleaseMode::SymbolSet, false),
];
for (skip_on_conflict, release_mode, expected) in cases {
let conflict = UploadConflictArgs {
force: false,
skip_on_conflict,
};
assert_eq!(
conflict.skip_on_conflict_ignored(release_mode),
expected,
"skip_on_conflict={skip_on_conflict} release_mode={release_mode:?}"
);
}
}
#[test]
fn upload_concurrency_defaults_to_ten() {
let parsed = parse_concurrency(&["test"], None).unwrap();
assert_eq!(parsed.upload.concurrency.get(), 10);
}
#[test]
fn upload_concurrency_accepts_cli_override() {
let parsed = parse_concurrency(&["test", "--concurrency", "32"], None).unwrap();
assert_eq!(parsed.upload.concurrency.get(), 32);
}
#[test]
fn upload_concurrency_accepts_environment_override() {
let parsed = parse_concurrency(&["test"], Some("48")).unwrap();
assert_eq!(parsed.upload.concurrency.get(), 48);
}
#[test]
fn upload_concurrency_prefers_cli_override() {
let parsed = parse_concurrency(&["test", "--concurrency", "32"], Some("48")).unwrap();
assert_eq!(parsed.upload.concurrency.get(), 32);
}
#[test]
fn upload_concurrency_rejects_zero_cli_value() {
let error = parse_concurrency(&["test", "--concurrency", "0"], None).unwrap_err();
assert!(error.to_string().contains("invalid value '0'"));
}
#[test]
fn upload_concurrency_rejects_invalid_environment_values() {
for value in ["0", "many"] {
let error = parse_concurrency(&["test"], Some(value)).unwrap_err();
let message = error.to_string();
assert!(
message.contains(&format!("invalid value '{value}'"))
&& message.contains("--concurrency"),
"unexpected error for {value:?}: {message}"
);
}
}
/// Golden vectors pinning the release `hash_id` the CLI writes: `content_hash([name, version])`
/// with `version = pack_version(version, build)` (see `api::releases::create_release`). Cymbal
/// reconstructs the same hash from a mobile event's app metadata (`mobile_release_hash_id` in
/// `rust/cymbal/src/core/types/frames/releases.rs`), so these literals must stay identical on
/// both sides or mobile releases silently stop resolving. Keep in sync with the matching golden
/// test in cymbal.
#[test]
fn release_hash_id_golden_vectors() {
use crate::utils::files::content_hash;
// (name, version, build, expected hash_id)
let cases: [(&str, Option<&str>, Option<&str>, &str); 4] = [
(
"com.posthog.iosraw",
Some("1.0"),
Some("1"),
"75605cac5268ba4bdc57b4c8336f6686802e88236ae4026418a18cabcde854d1015f18734489b8ec4c71c68773a027e5b880f7278b8ba6864a5334d76ef9eba6",
),
(
"com.example.app",
Some("1.0"),
Some("42"),
"5a7f7b504d81759fa4e15f8b3bbc77c694a9dc222cfcd06c801fae9619076e97909edf651087106af331aea76463449f015ccc41ccacbf19148329b1c2c35aa7",
),
(
"com.example.app",
Some("2.3"),
None,
"09aeeb69b914985562d4aa39d13033abf0f90c753ef90b0148cb06b8aeadca7dd1dd853fa24c7cc51d18cf251bb7348eae58906347a217a98d74ba7ca5673b66",
),
(
"com.example.app",
None,
Some("99"),
"5e925a3f2e9349f64ab88eede466b641a7332dc79d6f1901d931fb659704a0475fa77a3ca25c0a60b2919547de8d94117fbcc52448e83aa72787a3fe35f725ae",
),
];
for (name, version, build, expected) in cases {
let version = version.map(String::from);
let build = build.map(String::from);
let packed = pack_version(&version, &build).expect("these cases always pack a version");
let hash_id = content_hash([name.as_bytes(), packed.as_bytes()]);
assert_eq!(
hash_id, expected,
"release hash_id drift for {name} {version:?}+{build:?}"
);
}
}
}