rsproperties 0.4.0

// Copyright 2024 Jeff Kim <hiking90@gmail.com>
// SPDX-License-Identifier: Apache-2.0

//! # Android System Properties for Linux and Android both.
//!
//! This crate provides a way to access system properties on Linux and Android.
//!
//! ## Features
//!
//! - Get system properties.
//! - Set system properties.
//! - Wait for system properties.
//! - Serialize system properties.
//! - Deserialize system properties.
//!
//! ## Usage
//!
//! ```rust,no_run
//! #[cfg(target_os = "android")]
//! {
//!     // Get a value of the property.
//!     let value: String = rsproperties::get_or("ro.build.version.sdk", "0".to_owned());
//!     println!("ro.build.version.sdk: {}", value);
//!
//!     // Set a value of the property - use string literals for compatibility
//!     rsproperties::set("test.property", "test.value").unwrap();
//!
//!     // For Android system properties, prefer string format used by the system
//!     rsproperties::set("ro.debuggable", "1").unwrap();  // Not &true
//! }
//! ```

// Forward-compat with Rust 2024 edition: `unsafe fn` bodies must wrap
// individual unsafe ops in their own `unsafe {}` blocks rather than
// inheriting the function's effect. Enabling this lint as a warning today
// keeps the codebase ready and surfaces regressions in PRs.
#![warn(unsafe_op_in_unsafe_fn)]

use std::{
    path::{Path, PathBuf},
    sync::OnceLock,
};

/// Configuration for initializing the property system
#[derive(Debug, Clone, Default)]
pub struct PropertyConfig {
    /// Directory for reading system properties (default: "/dev/__properties__")
    pub properties_dir: Option<PathBuf>,
    /// Directory for property service sockets (default: "/dev/socket")
    pub socket_dir: Option<PathBuf>,
}

// Implement From traits for backward compatibility and convenience
impl From<PathBuf> for PropertyConfig {
    fn from(path: PathBuf) -> Self {
        Self {
            properties_dir: Some(path),
            socket_dir: None,
        }
    }
}

impl From<String> for PropertyConfig {
    fn from(path: String) -> Self {
        Self {
            properties_dir: Some(PathBuf::from(path)),
            socket_dir: None,
        }
    }
}

impl From<&str> for PropertyConfig {
    fn from(path: &str) -> Self {
        Self {
            properties_dir: Some(PathBuf::from(path)),
            socket_dir: None,
        }
    }
}

impl PropertyConfig {
    /// Create config from optional PathBuf (for backward compatibility)
    pub fn from_optional_path(path: Option<PathBuf>) -> Self {
        match path {
            Some(path) => Self::from(path),
            None => Self::default(),
        }
    }

    /// Create config with only properties directory
    pub fn with_properties_dir<P: Into<PathBuf>>(dir: P) -> Self {
        Self {
            properties_dir: Some(dir.into()),
            socket_dir: None,
        }
    }

    /// Create config with only socket directory
    pub fn with_socket_dir<P: Into<PathBuf>>(dir: P) -> Self {
        Self {
            properties_dir: None,
            socket_dir: Some(dir.into()),
        }
    }

    /// Create config with both directories
    pub fn with_both_dirs<P1: Into<PathBuf>, P2: Into<PathBuf>>(
        properties_dir: P1,
        socket_dir: P2,
    ) -> Self {
        Self {
            properties_dir: Some(properties_dir.into()),
            socket_dir: Some(socket_dir.into()),
        }
    }

    /// Create a new builder for PropertyConfig
    pub fn builder() -> PropertyConfigBuilder {
        PropertyConfigBuilder::default()
    }
}

/// Builder for PropertyConfig with validation
#[derive(Debug, Clone, Default)]
pub struct PropertyConfigBuilder {
    properties_dir: Option<PathBuf>,
    socket_dir: Option<PathBuf>,
}

impl PropertyConfigBuilder {
    /// Set the properties directory
    pub fn properties_dir<P: Into<PathBuf>>(mut self, dir: P) -> Self {
        self.properties_dir = Some(dir.into());
        self
    }

    /// Set the socket directory
    pub fn socket_dir<P: Into<PathBuf>>(mut self, dir: P) -> Self {
        self.socket_dir = Some(dir.into());
        self
    }

    /// Build the PropertyConfig
    pub fn build(self) -> PropertyConfig {
        PropertyConfig {
            properties_dir: self.properties_dir,
            socket_dir: self.socket_dir,
        }
    }
}

pub mod errors;
pub mod wire;
pub use errors::{ContextWithLocation, Error, Result};

#[cfg(feature = "builder")]
mod build_property_parser;
mod context_node;
mod contexts_serialized;
mod property_area;
mod property_info;
mod property_info_parser;
#[cfg(feature = "builder")]
mod property_info_serializer;
mod system_properties;
mod system_property_set;
#[cfg(feature = "builder")]
mod trie_builder;
#[cfg(feature = "builder")]
mod trie_node_arena;
#[cfg(feature = "builder")]
mod trie_serializer;

#[cfg(feature = "builder")]
pub use build_property_parser::*;
#[cfg(feature = "builder")]
pub use property_info_serializer::*;
pub use system_properties::SystemProperties;
pub use system_property_set::socket_dir;

pub use system_property_set::{
    PROPERTY_SERVICE_FOR_SYSTEM_SOCKET_NAME, PROPERTY_SERVICE_SOCKET_NAME,
};

pub const PROP_VALUE_MAX: usize = 92;
pub const PROP_DIRNAME: &str = "/dev/__properties__";

// System properties directory.
static SYSTEM_PROPERTIES_DIR: OnceLock<PathBuf> = OnceLock::new();
// Global system properties. Stores Result so initialization failure does not
// poison the OnceLock and callers can observe the error.
static SYSTEM_PROPERTIES: OnceLock<Result<system_properties::SystemProperties>> = OnceLock::new();

/// Initialize system properties with flexible configuration options.
///
/// # Arguments
/// * `config` - Can be:
///   - `None` - Use default directories
///   - `Some(PathBuf)` - Set only properties directory (backward compatibility)
///   - `Some(PropertyConfig)` - Full configuration
///
/// # Examples
/// ```rust,no_run
/// use rsproperties::{init, PropertyConfig};
/// use std::path::PathBuf;
///
/// // Set only properties directory (backward compatible)
/// init(PropertyConfig::from(PathBuf::from("/custom/properties")));
///
/// // Full configuration
/// let config = PropertyConfig {
///     properties_dir: Some(PathBuf::from("/custom/properties")),
///     socket_dir: Some(PathBuf::from("/custom/socket")),
/// };
/// init(config);
/// ```
pub fn init(config: PropertyConfig) {
    // The `Result` form (`try_init`) is preferred for new code; this wrapper
    // exists for backward compatibility and logs failures instead of returning
    // them.
    if let Err(e) = try_init(config) {
        log::warn!("init: {e}");
    }
}

/// Initialize system properties, returning an error when an option cannot be
/// applied (typically because it was already set on a previous call).
pub fn try_init(config: PropertyConfig) -> Result<()> {
    let props_dir = config.properties_dir.unwrap_or_else(|| {
        log::info!("Using default properties directory: {PROP_DIRNAME}");
        PathBuf::from(PROP_DIRNAME)
    });

    // Both `SYSTEM_PROPERTIES_DIR` and the socket-dir cell are first-write-
    // wins. Pre-check both *before* committing either to avoid leaving the
    // global state in a half-applied form (properties_dir locked, socket_dir
    // unset) when the caller's intent was an atomic init.
    if SYSTEM_PROPERTIES_DIR.get().is_some() {
        return Err(Error::FileValidation(
            "System properties directory already initialized".into(),
        ));
    }
    if config.socket_dir.is_some() && system_property_set::socket_dir_is_set() {
        return Err(Error::FileValidation(
            "Socket directory already initialized".into(),
        ));
    }

    log::info!("Setting system properties directory to: {props_dir:?}");
    SYSTEM_PROPERTIES_DIR.set(props_dir).map_err(|_| {
        Error::FileValidation("System properties directory already initialized".into())
    })?;

    if let Some(socket_dir) = config.socket_dir {
        if !system_property_set::set_socket_dir(&socket_dir) {
            // Lost a race between the pre-check and the set; properties_dir
            // is now committed but socket_dir is owned by another caller.
            // Cannot un-set a `OnceLock`, so surface the inconsistency.
            return Err(Error::FileValidation(
                "Socket directory already initialized (race after pre-check)".into(),
            ));
        }
        log::info!("Successfully set socket directory to: {socket_dir:?}");
    }
    Ok(())
}

/// Get the system properties directory.
/// Returns the configured directory if init() was called,
/// otherwise returns the default PROP_DIRNAME (/dev/__properties__).
pub fn properties_dir() -> &'static Path {
    SYSTEM_PROPERTIES_DIR
        .get_or_init(|| {
            log::info!("Using default properties directory: {PROP_DIRNAME}");
            PathBuf::from(PROP_DIRNAME)
        })
        .as_path()
}

/// Get the system properties, returning an error if initialization fails.
///
/// This is the panic-free variant; `init()` should typically be called first
/// to choose the properties directory. The initialization is cached, so
/// subsequent calls reuse the same result (success or failure).
pub fn try_system_properties() -> Result<&'static system_properties::SystemProperties> {
    SYSTEM_PROPERTIES
        .get_or_init(|| {
            let dir = properties_dir();
            log::debug!("Initializing global SystemProperties instance from: {dir:?}");

            system_properties::SystemProperties::new(dir).inspect_err(|e| {
                log::error!("Failed to initialize SystemProperties from {dir:?}: {e}");
            })
        })
        .as_ref()
        .map_err(|e| {
            // We only have `&Error` from the cache, and `Error` isn't
            // `Clone` (it transitively wraps `std::io::Error`). To avoid
            // losing the failure context we walk `Error::source()` and
            // flatten the chain into the Display string. Programmatic
            // `source()` traversal is sacrificed here — preserving it
            // would require caching `Arc<Error>` and changing the public
            // return type.
            Error::FileValidation(format_error_chain("SystemProperties init failed", e))
        })
}

/// Formats `err` and its `source()` chain as `"<prefix>: <e0>: <e1>: ..."`.
/// Used to surface root-cause info when we hold only `&Error` and can't
/// build a `Error::Context` (which needs an owned source).
fn format_error_chain(prefix: &str, err: &dyn std::error::Error) -> String {
    use std::fmt::Write;
    let mut out = format!("{prefix}: {err}");
    let mut source = err.source();
    while let Some(s) = source {
        // ignore write! errors — String never fails to write
        let _ = write!(&mut out, ": {s}");
        source = s.source();
    }
    out
}

/// Get the system properties.
/// Before calling this function, init() must be called.
/// It panics if init() is not called or the system properties cannot be opened.
///
/// Prefer [`try_system_properties`] in code that must not panic.
pub fn system_properties() -> &'static system_properties::SystemProperties {
    match try_system_properties() {
        Ok(props) => props,
        Err(e) => panic!("Failed to initialize SystemProperties: {e}"),
    }
}

/// Aligns size to the specified alignment (bionic style)
///
/// # Panics
/// Panics if alignment is not a power of 2
pub(crate) fn bionic_align(value: usize, alignment: usize) -> usize {
    assert!(
        alignment.is_power_of_two(),
        "Alignment must be a power of 2"
    );

    // Use saturating_add to prevent overflow
    // (value + alignment - 1) & !(alignment - 1)
    value.saturating_add(alignment - 1) & !(alignment - 1)
}

/// Get a property value parsed to specified type
/// Returns Err if property not found, system error, or parse error occurs
///
/// # Examples
/// ```rust,no_run
/// use rsproperties::get;
///
/// let sdk_version: i32 = get("ro.build.version.sdk").unwrap();
/// let is_debuggable: bool = get("ro.debuggable").unwrap();
/// let version: String = get("ro.build.version.release").unwrap();
///
/// // With fallback
/// let sdk_version: i32 = get("ro.build.version.sdk").unwrap_or(0);
/// let version: String = get("ro.build.version.release").unwrap_or_default();
/// ```
pub fn get<T>(name: &str) -> Result<T>
where
    T: std::str::FromStr,
    T::Err: std::fmt::Display,
{
    // Route through `read_with` so the parse-and-discard path never
    // allocates a `String` — the value bytes are handed to `FromStr` as
    // `&str` borrowed from the seqlock buffer (short variant) or the mmap
    // (long variant).
    try_system_properties()?.read_with(name, |value| {
        value.parse().map_err(|e| {
            Error::Parse(format!(
                "Failed to parse '{value}' for property '{name}': {e}"
            ))
        })
    })?
}

/// Get a property value with default fallback
/// Never fails - always returns a valid value
///
/// # Examples
/// ```rust,no_run
/// use rsproperties::get_or;
///
/// let sdk_version: i32 = get_or("ro.build.version.sdk", 0);
/// let is_debuggable: bool = get_or("ro.debuggable", false);
/// let version: String = get_or("ro.build.version.release", "unknown".to_owned());
/// ```
pub fn get_or<T>(name: &str, default: T) -> T
where
    T: std::str::FromStr,
{
    let Ok(props) = try_system_properties() else {
        return default;
    };
    // Two-stage closure: the inner `Result<T, T>` carries either the
    // parsed value or the default back out of `read_with` without ever
    // allocating a `String`. `Err(default)` is used to signal "use the
    // default" because the callback can't capture-and-move it twice.
    match props.read_with(name, |value| {
        if value.is_empty() {
            return Err(());
        }
        value.parse::<T>().map_err(|_| ())
    }) {
        Ok(Ok(v)) => v,
        _ => default,
    }
}

/// Set a value of the property with any Display type.
///
/// **Important**: All values are converted to strings using the `Display` trait before being stored.
/// This means that when reading properties set by other applications or systems, you should be aware
/// of potential format differences. For example:
/// - Boolean values are stored as "true"/"false" (Rust format)
/// - Numbers may have different precision or formatting
/// - Different applications may use different string representations for the same logical value
///
/// For maximum compatibility with existing Android properties, consider using string literals
/// when setting well-known system properties that may be read by other applications.
///
/// If an error occurs, it returns Err.
/// It uses socket communication to set the property. Because it is designed for client applications.
///
/// # Examples
/// ```rust,no_run
/// use rsproperties::set;
///
/// // Setting various types (all converted to strings)
/// set("test.int.property", &42).unwrap();           // Stored as "42"
/// set("test.bool.property", &true).unwrap();        // Stored as "true"
/// set("test.float.property", &3.14).unwrap();       // Stored as "3.14"
/// set("test.string.property", &"hello").unwrap();   // Stored as "hello"
///
/// // For Android system properties, prefer string literals for compatibility
/// set("ro.debuggable", "1").unwrap();               // Better than set("ro.debuggable", &1)
/// set("persist.sys.timezone", "Asia/Seoul").unwrap();
/// ```
///
/// # Compatibility Notes
/// - Android system properties typically use "0"/"1" for boolean values, not "true"/"false"
/// - Numeric properties may have specific formatting requirements
/// - Always test compatibility when setting properties that will be read by other applications
pub fn set<T: std::fmt::Display + ?Sized>(name: &str, value: &T) -> Result<()> {
    system_property_set::set(name, &value.to_string())
}

#[cfg(test)]
mod tests {
    #![allow(unused_imports)]
    use super::*;
    #[cfg(target_os = "android")]
    use android_system_properties::AndroidSystemProperties;
    use std::collections::HashMap;
    use std::fs::{create_dir, remove_dir_all, File};
    use std::io::Write;
    use std::path::Path;
    use std::sync::{Mutex, MutexGuard};

    #[cfg(all(feature = "builder", not(target_os = "android")))]
    const TEST_PROPERTY_DIR: &str = "__properties__";

    #[cfg(any(feature = "builder", target_os = "android"))]
    fn enable_logger() {
        let _ = env_logger::builder().is_test(true).try_init();
    }

    #[cfg(target_os = "android")]
    #[test]
    fn test_get() {
        const PROPERTIES: [&str; 40] = [
            "ro.build.version.sdk",
            "ro.build.version.release",
            "ro.product.model",
            "ro.product.manufacturer",
            "ro.product.name",
            "ro.serialno",
            "ro.bootloader",
            "ro.hardware",
            "ro.revision",
            "ro.kernel.qemu",
            "dalvik.vm.heapsize",
            "dalvik.vm.heapgrowthlimit",
            "dalvik.vm.heapstartsize",
            "dalvik.vm.heaptargetutilization",
            "dalvik.vm.heapminfree",
            "dalvik.vm.heapmaxfree",
            "net.bt.name",
            "net.change",
            "net.dns1",
            "net.dns2",
            "net.hostname",
            "net.tcp.default_init_rwnd",
            "persist.sys.timezone",
            "persist.sys.locale",
            "persist.sys.dalvik.vm.lib.2",
            "persist.sys.profiler_ms",
            "persist.sys.usb.config",
            "persist.service.acm.enable",
            "ril.ecclist",
            "ril.subscription.types",
            "service.adb.tcp.port",
            "service.bootanim.exit",
            "service.camera.running",
            "service.media.powersnd",
            "sys.boot_completed",
            "sys.usb.config",
            "sys.usb.state",
            "vold.post_fs_data_done",
            "wifi.interface",
            "wifi.supplicant_scan_interval",
        ];

        enable_logger();
        for prop in PROPERTIES.iter() {
            let value1: String = get_or(prop, "".to_owned());
            let value2 = AndroidSystemProperties::new().get(prop).unwrap_or_default();

            println!("{}: [{}], [{}]", prop, value1, value2);
            assert_eq!(value1, value2);
        }
    }

    #[cfg(all(feature = "builder", not(target_os = "android")))]
    fn load_properties() -> HashMap<String, String> {
        let build_prop_files = vec![
            "tests/android/product_build.prop",
            "tests/android/system_build.prop",
            "tests/android/system_dlkm_build.prop",
            "tests/android/system_ext_build.prop",
            "tests/android/vendor_build.prop",
            "tests/android/vendor_dlkm_build.prop",
            "tests/android/vendor_odm_build.prop",
            "tests/android/vendor_odm_dlkm_build.prop",
        ];

        let mut properties = HashMap::new();
        for file in build_prop_files {
            load_properties_from_file(Path::new(file), None, "u:r:init:s0", &mut properties)
                .unwrap();
        }

        properties
    }

    #[cfg(all(feature = "builder", not(target_os = "android")))]
    fn system_properties_area() -> MutexGuard<'static, Option<SystemProperties>> {
        static SYSTEM_PROPERTIES: Mutex<Option<SystemProperties>> = Mutex::new(None);
        let mut system_properties_guard = SYSTEM_PROPERTIES.lock().unwrap();

        if system_properties_guard.is_none() {
            *system_properties_guard = Some(build_property_dir(TEST_PROPERTY_DIR));
        }
        system_properties_guard
    }

    #[cfg(all(feature = "builder", not(target_os = "android")))]
    fn build_property_dir(dir: &str) -> SystemProperties {
        crate::init(PropertyConfig::from(PathBuf::from(dir)));

        let property_contexts_files = vec![
            "tests/android/plat_property_contexts",
            "tests/android/system_ext_property_contexts",
            "tests/android/vendor_property_contexts",
        ];

        let mut property_infos = Vec::new();
        for file in property_contexts_files {
            let (mut property_info, errors) =
                PropertyInfoEntry::parse_from_file(Path::new(file), false).unwrap();
            if !errors.is_empty() {
                log::error!("{errors:?}");
            }
            property_infos.append(&mut property_info);
        }

        let data: Vec<u8> =
            build_trie(&property_infos, "u:object_r:build_prop:s0", "string").unwrap();

        let dir = properties_dir();
        remove_dir_all(dir).unwrap_or_default();
        create_dir(dir).unwrap_or_default();
        File::create(dir.join("property_info"))
            .unwrap()
            .write_all(&data)
            .unwrap();

        let properties = load_properties();

        let dir = properties_dir();
        let mut system_properties = SystemProperties::new_area(dir).unwrap_or_else(|e| {
            panic!("Cannot create system properties: {e}. Please check if {dir:?} exists.")
        });
        for (key, value) in properties.iter() {
            match system_properties.find(key.as_str()).unwrap() {
                Some(prop_ref) => {
                    system_properties.update(&prop_ref, value.as_str()).unwrap();
                }
                None => {
                    system_properties.add(key.as_str(), value.as_str()).unwrap();
                }
            }
        }

        system_properties
    }

    #[cfg(all(feature = "builder", not(target_os = "android")))]
    #[test]
    fn test_property_info() {
        enable_logger();

        let _guard = system_properties_area();

        let system_properties = system_properties();

        let properties = load_properties();

        for (key, value) in properties.iter() {
            let prop_value = system_properties
                .get_with_result(key.as_str())
                .unwrap_or_default();
            assert_eq!(prop_value, value.as_str());
        }
    }

    #[cfg(all(feature = "builder", not(target_os = "android")))]
    #[test]
    fn test_wait() {
        enable_logger();

        let mut guard = system_properties_area();

        let system_properties_area = guard.as_mut().unwrap();

        let test_prop = "test.property";

        let wait_any = || {
            std::thread::spawn(move || {
                let system_properties = system_properties();
                system_properties.wait_any();
            })
        };

        let handle = wait_any();
        std::thread::sleep(std::time::Duration::from_millis(100));

        system_properties_area.add(test_prop, "true").unwrap();
        handle.join().unwrap();

        let handle = std::thread::spawn(move || {
            let system_properties = system_properties();
            let index = system_properties.find(test_prop).unwrap();
            // let serial = system_properties.serial(index.as_ref().unwrap());
            system_properties.wait(index.as_ref(), None);
        });

        let handle_any = wait_any();
        std::thread::sleep(std::time::Duration::from_millis(100));

        let index = system_properties_area.find(test_prop).unwrap();
        system_properties_area
            .update(&index.unwrap(), "false")
            .unwrap();

        handle.join().unwrap();
        handle_any.join().unwrap();
    }

    #[test]
    fn test_bionic_align_normal() {
        // Test normal alignment
        assert_eq!(bionic_align(0, 4), 0);
        assert_eq!(bionic_align(1, 4), 4);
        assert_eq!(bionic_align(4, 4), 4);
        assert_eq!(bionic_align(5, 4), 8);
        assert_eq!(bionic_align(7, 4), 8);
        assert_eq!(bionic_align(8, 4), 8);

        // Test with 8-byte alignment
        assert_eq!(bionic_align(0, 8), 0);
        assert_eq!(bionic_align(1, 8), 8);
        assert_eq!(bionic_align(8, 8), 8);
        assert_eq!(bionic_align(9, 8), 16);
    }

    #[test]
    fn test_bionic_align_overflow_safety() {
        // Test that bionic_align doesn't overflow with large values
        let size = usize::MAX - 10;
        let align = 16;
        let result = bionic_align(size, align);

        // Should saturate and then align down
        // Result should be aligned and not panic
        assert_eq!(result % align, 0);
    }

    #[test]
    #[should_panic(expected = "Alignment must be a power of 2")]
    fn test_bionic_align_invalid_alignment() {
        // Test that non-power-of-2 alignment panics
        bionic_align(100, 3);
    }

    #[test]
    fn test_bionic_align_edge_cases() {
        // Test with alignment of 1 (trivial case)
        assert_eq!(bionic_align(5, 1), 5);
        assert_eq!(bionic_align(0, 1), 0);

        // Test with larger alignment
        assert_eq!(bionic_align(100, 64), 128);
        assert_eq!(bionic_align(64, 64), 64);
        assert_eq!(bionic_align(65, 64), 128);
    }
}