navcore_signalk_client/

anchor.rs

//! Setting the anchor watch, on the wire.
//!
//! `navigation.anchor.position` and `navigation.anchor.maxRadius` are
//! ordinary Signal K data-model paths, not Resources-API items: there
//! is no list to fetch and no id the server mints. A client watches the
//! delta stream for their current values, the same way it already
//! watches `navigation.position`/`design.draft`/wind; this module
//! provides only the write half, setting or clearing them.
//!
//! Confirmed against a `signalk-server` running
//! `signalk-anchoralarm-plugin` (the ecosystem's reference anchor-alarm
//! plugin): it registers real `PUT` action handlers for both paths
//! (`app.registerPutHandler`), so a plain
//! `PUT /signalk/v1/api/vessels/self/navigation/anchor/{path}` works,
//! unlike a path nothing has claimed, which the server's generic
//! handler refuses with `405 PUT not supported`. Setting
//! `navigation.anchor.position` to `null` also nulls `maxRadius`: the
//! plugin's own `getAnchorDelta` nulls both together whenever no
//! position is given. The read side's whole contract is that
//! "anchored" means `navigation.anchor.position` is currently
//! non-null, nothing more.
//!
//! The reply to one of these `PUT`s is the server's plain
//! `requestResponse` shape (`state`/`statusCode`/`requestId`/...), not
//! the Resources API's `ActionResult` (`id`/`message` on success);
//! [`resources::read_action_response`](crate::resources) is the wrong
//! reader for it. A captured reply:
//! `{"state":"COMPLETED","requestId":"...","statusCode":202,...}`.

use std::time::Duration;

use nav_math::Position;

use crate::access::agent;
use crate::{ClientError, Trust};

/// Same figure [`crate::resources::TIMEOUT`] uses, for the same reason:
/// these are calls on a boat's own LAN.
const TIMEOUT: Duration = Duration::from_secs(10);

/// A client for setting one server's own anchor watch.
///
/// Built from what [`crate::stream::Connection`] and
/// [`crate::access::request_access`] already needed, the same shape
/// [`crate::resources::Client`] already takes for the identical reason.
pub struct Client {
    http_base: String,
    trust: Trust,
    token: Option<String>,
}

impl Client {
    /// A client for the server at `http_base`, using `trust` to decide
    /// which server may answer and `token` (once one exists) to
    /// authenticate the write.
    #[must_use]
    pub fn new(http_base: String, trust: Trust, token: Option<String>) -> Self {
        Self { http_base, trust, token }
    }

    /// Sets the anchor position and swing radius, starting the plugin's
    /// own drift monitoring once both are known.
    ///
    /// Two separate `PUT`s -- there is no combined endpoint -- sent
    /// radius first. Either order leaves the plugin watching once both
    /// are set, but sending the position last means the plugin's own
    /// "radius already known" branch starts monitoring, rather than
    /// racing whichever call happens to land second.
    ///
    /// # Errors
    ///
    /// If there is no token -- a write always needs one -- if the server
    /// cannot be reached, or if it refuses the write.
    pub fn set_anchor(&self, position: Position, max_radius_m: f64) -> Result<(), ClientError> {
        self.put("maxRadius", &serde_json::json!(max_radius_m))?;
        self.put(
            "position",
            &serde_json::json!({ "latitude": position.lat_deg, "longitude": position.lon_deg }),
        )
    }

    /// Raises the anchor. Clears `navigation.anchor.position`, which the
    /// plugin answers by nulling `maxRadius` (and everything else it
    /// derives) along with it -- see this module's own doc -- so
    /// nothing further needs clearing from here.
    ///
    /// # Errors
    ///
    /// The same as [`Self::set_anchor`].
    pub fn clear_anchor(&self) -> Result<(), ClientError> {
        self.put("position", &serde_json::Value::Null)
    }

    /// One `PUT vessels/self/navigation/anchor/{path}`, reading the
    /// server's plain `requestResponse` reply for whether it actually
    /// took -- see this module's own doc for why that is a different
    /// shape from the Resources API's `ActionResult`.
    fn put(&self, path: &str, value: &serde_json::Value) -> Result<(), ClientError> {
        let Some(token) = &self.token else {
            return Err(ClientError::Http(
                "no token: setting the anchor watch needs one, the same as any other write".to_owned(),
            ));
        };

        let mut response = agent(&self.trust)?
            .put(format!("{}/signalk/v1/api/vessels/self/navigation/anchor/{path}", self.http_base))
            .header("Authorization", format!("Bearer {token}"))
            .config()
            .timeout_global(Some(TIMEOUT))
            .http_status_as_error(false)
            .build()
            .send_json(serde_json::json!({ "value": value }))
            .map_err(|error| ClientError::Http(error.to_string()))?;

        let answer: serde_json::Value = response
            .body_mut()
            .read_json()
            .map_err(|error| ClientError::Http(error.to_string()))?;
        read_request_response(&answer)
    }
}

/// Reads a plain `PUT /signalk/v1/api/...` reply -- `state`/`statusCode`,
/// not the Resources API's `id`/`message` `ActionResult` shape
/// [`crate::resources::read_action_response`] reads. `state: "COMPLETED"`
/// with a `2xx` `statusCode` is success; anything else, including a
/// `PENDING` state this crate has no way to wait out (no action handler
/// this client knows of ever answers asynchronously), is reported as the
/// protocol error it is for this client's purposes.
///
/// `pub(crate)` rather than private: [`crate::course`] answers to the
/// identical reply shape (confirmed live against the same server's own
/// Course API, whose handlers reply with the exact `Responses.ok`/
/// `Responses.invalid` shape this reads) and has no reason to read it
/// differently.
pub(crate) fn read_request_response(answer: &serde_json::Value) -> Result<(), ClientError> {
    let state = answer.get("state").and_then(serde_json::Value::as_str);
    let status_code = answer.get("statusCode").and_then(serde_json::Value::as_u64);
    match (state, status_code) {
        (Some("COMPLETED"), Some(200..=299)) => Ok(()),
        _ => {
            let message = answer
                .get("message")
                .and_then(serde_json::Value::as_str)
                .map_or_else(|| answer.to_string(), str::to_owned);
            Err(ClientError::Protocol(message))
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_completed_reply_is_success() {
        let answer = serde_json::json!({"state": "COMPLETED", "statusCode": 200, "requestId": "x"});
        assert!(read_request_response(&answer).is_ok());
    }

    #[test]
    fn a_completed_reply_with_202_is_still_success() {
        // The live server answered exactly this shape for both PUTs this
        // module made against the real plugin.
        let answer = serde_json::json!({"state": "COMPLETED", "statusCode": 202, "requestId": "x"});
        assert!(read_request_response(&answer).is_ok());
    }

    #[test]
    fn a_refused_put_is_reported_with_its_own_message() {
        let answer = serde_json::json!({
            "state": "COMPLETED",
            "statusCode": 405,
            "message": "PUT not supported for navigation.anchor.position",
        });
        let error = read_request_response(&answer).unwrap_err();
        assert!(matches!(error, ClientError::Protocol(message) if message.contains("not supported")));
    }

    #[test]
    fn a_pending_reply_is_not_treated_as_success() {
        let answer = serde_json::json!({"state": "PENDING", "statusCode": 202, "requestId": "x"});
        assert!(read_request_response(&answer).is_err());
    }
}