esphome-native-api 3.0.0

//! High-level ESPHome server implementation with entity management.
//!
//! This module provides the [`EspHomeServer`] abstraction, which simplifies working with
//! ESPHome devices by managing entities. It builds on top of the
//! lower-level [`crate::esphomeapi::EspHomeApi`] and handles entity registration and
//! message routing automatically.
//!
//! # Examples
//!
//! ```rust,no_run
//! use esphome_native_api::esphomeserver::{EspHomeServer, Entity, BinarySensor};
//! use tokio::net::TcpStream;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let stream = TcpStream::connect("192.168.1.100:6053").await?;
//!     
//!     let mut server = EspHomeServer::builder()
//!         .name("my-server".to_string())
//!         .build();
//!     
//!     // Add entities
//!     let sensor = Entity::BinarySensor(BinarySensor {
//!         object_id: "door_sensor".to_string(),
//!     });
//!     server.add_entity("door_sensor", sensor);
//!     
//!     let connection = server.start(stream).await?;
//!     let tx = connection.sender();
//!     let mut rx = connection.receiver();
//!     # let _ = (tx, &mut rx);
//!
//!     Ok(())
//! }
//! ```

#![allow(dead_code)]

use log::debug;
use log::warn;
use noise_protocol::CipherState;
use noise_protocol::HandshakeState;
use noise_rust_crypto::ChaCha20Poly1305;
use noise_rust_crypto::Sha256;
use noise_rust_crypto::X25519;
use std::collections::HashMap;
use std::str;
use std::sync::Arc;
use std::sync::atomic::AtomicBool;
use tokio::net::TcpStream;
use tokio::sync::Mutex;
use tokio::sync::broadcast;
use tokio::sync::broadcast::error::RecvError;
use typed_builder::TypedBuilder;

use crate::connection::Connection;
use crate::error::Error;
use crate::esphomeapi::EspHomeApi;
use crate::parser::ProtoMessage;
use crate::proto::ListEntitiesDoneResponse;

/// High-level ESPHome server implementation.
///
/// `EspHomeServer` provides an easier-to-use abstraction over the ESPHome native API
/// by managing entity keys internally. It handles entity registration, message routing,
/// and maintains state for all registered entities.
///
/// This struct uses the builder pattern via the [`TypedBuilder`] derive macro,
/// allowing for flexible configuration.
///
/// # Examples
///
/// ```rust
/// use esphome_native_api::esphomeserver::EspHomeServer;
///
/// let server = EspHomeServer::builder()
///     .name("my-device".to_string())
///     .api_version_major(1)
///     .api_version_minor(10)
///     .encryption_key("your-base64-key".to_string())
///     .build();
/// ```
#[derive(TypedBuilder)]
pub struct EspHomeServer {
    // Private fields
    #[builder(default=HashMap::new(), setter(skip))]
    pub(crate) components_by_key: HashMap<u32, Entity>,
    #[builder(default=HashMap::new(), setter(skip))]
    pub(crate) components_key_id: HashMap<String, u32>,
    #[builder(default = 0, setter(skip))]
    pub(crate) current_key: u32,

    #[builder(via_mutators, default=Arc::new(AtomicBool::new(false)))]
    pub(crate) encrypted_api: Arc<AtomicBool>,

    #[builder(via_mutators)]
    pub(crate) noise_psk: Vec<u8>,

    #[builder(default=Arc::new(Mutex::new(None)), setter(skip))]
    pub(crate) handshake_state:
        Arc<Mutex<Option<HandshakeState<X25519, ChaCha20Poly1305, Sha256>>>>,
    #[builder(default=Arc::new(Mutex::new(None)), setter(skip))]
    pub(crate) encrypt_cypher: Arc<Mutex<Option<CipherState<ChaCha20Poly1305>>>>,
    #[builder(default=Arc::new(Mutex::new(None)), setter(skip))]
    pub(crate) decrypt_cypher: Arc<Mutex<Option<CipherState<ChaCha20Poly1305>>>>,

    name: String,

    #[builder(default = None, setter(strip_option))]
    #[deprecated(note = "https://esphome.io/components/api.html#configuration-variables")]
    password: Option<String>,
    #[builder(default = None, setter(strip_option))]
    encryption_key: Option<String>,

    #[builder(default = 1)]
    api_version_major: u32,
    #[builder(default = 10)]
    api_version_minor: u32,
    #[builder(default="Rust: esphome-native-api".to_string())]
    server_info: String,

    #[builder(default = None, setter(strip_option))]
    friendly_name: Option<String>,

    #[builder(default = None, setter(strip_option))]
    mac: Option<String>,

    #[builder(default = None, setter(strip_option))]
    model: Option<String>,

    #[builder(default = None, setter(strip_option))]
    manufacturer: Option<String>,
    #[builder(default = None, setter(strip_option))]
    suggested_area: Option<String>,
    #[builder(default = None, setter(strip_option))]
    bluetooth_mac_address: Option<String>,
}

/// Easier version of the API abstraction.
///
/// Manages entity keys internally.
impl EspHomeServer {
    /// Starts the ESPHome server and begins communication over the provided TCP stream.
    ///
    /// This method initializes the underlying [`EspHomeApi`], establishes the connection,
    /// and spawns a background task to handle message routing between the API and
    /// registered entities.
    ///
    /// # Arguments
    ///
    /// * `tcp_stream` - An established TCP connection to an ESPHome device
    ///
    /// # Returns
    ///
    /// Returns a [`Connection`] handle. Use [`Connection::sender`] to send
    /// messages to the ESPHome device, [`Connection::receiver`] to receive
    /// messages from it, and [`Connection::wait`] to observe when — and why —
    /// the connection ends.
    ///
    /// # Errors
    ///
    /// Returns an error if the connection cannot be established or if the initial
    /// handshake fails.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// # use esphome_native_api::esphomeserver::EspHomeServer;
    /// # use tokio::net::TcpStream;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let stream = TcpStream::connect("192.168.1.100:6053").await?;
    /// let mut server = EspHomeServer::builder().name("client".to_string()).build();
    /// let connection = server.start(stream).await?;
    /// let tx = connection.sender();
    /// let mut rx = connection.receiver();
    /// # let _ = (tx, &mut rx);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn start(&mut self, tcp_stream: TcpStream) -> Result<Connection, Error> {
        let server = EspHomeApi::builder()
            .api_version_major(self.api_version_major)
            .api_version_minor(self.api_version_minor)
            // .password(self.password.or_else())
            .server_info(self.server_info.clone())
            .name(self.name.clone())
            // .friendly_name(self.friendly_name)
            // .bluetooth_mac_address(self.bluetooth_mac_address)
            // .mac(self.mac)
            // .manufacturer(self.manufacturer)
            // .model(self.model)
            // .suggested_area(self.suggested_area)
            .build()?;
        let api_connection = server.start(tcp_stream).await?;
        let messages_tx = api_connection.sender();
        let mut messages_rx = api_connection.receiver();
        let (outgoing_messages_tx, outgoing_messages_rx) = broadcast::channel::<ProtoMessage>(16);
        let (done_tx, done_rx) = tokio::sync::oneshot::channel::<Result<(), Error>>();
        let api_components_clone = self.components_by_key.clone();

        tokio::spawn(async move {
            loop {
                let message = match messages_rx.recv().await {
                    Ok(message) => message,
                    // Lagging only skips messages; the connection is still alive.
                    Err(RecvError::Lagged(skipped)) => {
                        warn!("Message routing lagged, {skipped} messages skipped");
                        continue;
                    }
                    // The underlying connection closed; stop routing.
                    Err(RecvError::Closed) => break,
                };
                debug!("Received message: {:?}", message);

                match message {
                    ProtoMessage::ListEntitiesRequest(list_entities_request) => {
                        debug!("ListEntitiesRequest: {:?}", list_entities_request);

                        for _sensor in api_components_clone.values() {
                            // TODO: Handle the different entity types
                            // let _ = outgoing_messages_tx.send(sensor.clone());
                        }
                        // No active receivers is fine (consumer dropped its handle).
                        let _ = outgoing_messages_tx.send(ProtoMessage::ListEntitiesDoneResponse(
                            ListEntitiesDoneResponse {},
                        ));
                    }
                    other_message => {
                        let _ = outgoing_messages_tx.send(other_message);
                    }
                }
            }

            // Propagate the underlying connection's terminal outcome.
            let _ = done_tx.send(api_connection.wait().await);
        });

        Ok(Connection::new(messages_tx, outgoing_messages_rx, done_rx))
    }

    /// Adds an entity to the server's internal registry.
    ///
    /// Each entity is assigned a unique key that is managed internally. The entity
    /// can be referenced by its string identifier in subsequent operations.
    ///
    /// # Arguments
    ///
    /// * `entity_id` - A unique string identifier for the entity
    /// * `entity` - The entity to register
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use esphome_native_api::esphomeserver::{EspHomeServer, Entity, BinarySensor};
    /// let mut server = EspHomeServer::builder().name("server".to_string()).build();
    /// let sensor = Entity::BinarySensor(BinarySensor {
    ///     object_id: "motion_sensor".to_string(),
    /// });
    /// server.add_entity("motion", sensor);
    /// ```
    pub fn add_entity(&mut self, entity_id: &str, entity: Entity) {
        self.components_key_id
            .insert(entity_id.to_string(), self.current_key);
        self.components_by_key.insert(self.current_key, entity);

        self.current_key += 1;
    }
}

/// Represents different types of entities supported by ESPHome.
///
/// This enum contains all entity types that can be registered with the server.
/// Currently, only binary sensors are implemented, but this will expand to include
/// other entity types like switches, lights, sensors, etc.
#[derive(Clone, Debug)]
pub enum Entity {
    /// A binary sensor entity (on/off state)
    BinarySensor(BinarySensor),
}

/// Represents a binary sensor entity.
///
/// Binary sensors report a simple on/off or true/false state, such as
/// door/window sensors, motion detectors, or binary switches.
#[derive(Clone, Debug)]
pub struct BinarySensor {
    /// The unique object identifier for this binary sensor
    pub object_id: String,
}