Skip to main content

s2_kit/connect/client/
lan.rs

1//! The operations only LAN endpoints implement.
2//!
3//! The wire types and the reasoning are in [`proto::lan`](crate::connect::proto::lan);
4//! this is the HTTP that carries them.
5
6use alloc::vec::Vec;
7
8use crate::connect::proto::{
9    CancelPreparePairing, EndpointDescription, LONG_POLL_TIMEOUT, NodeDescription, PreparePairing,
10    WaitForPairing, WaitInstruction,
11};
12use crate::connect::tls::TlsPolicy;
13
14use super::http::{Error, Http};
15
16/// Asks a LAN endpoint what it is, before anyone has decided to pair with it.
17#[derive(Debug)]
18pub struct LanClient {
19    http: Http,
20    /// A second connection, for the one operation that is meant to block.
21    ///
22    /// `waitForPairing` is held open by the server for up to
23    /// [`LONG_POLL_HOLD`](crate::connect::proto::LONG_POLL_HOLD); a client whose timeout
24    /// is the ordinary one would abandon every request a fraction before the answer it
25    /// asked for arrived, and would look to its user like an endpoint that never responds.
26    long_poll: Http,
27}
28
29impl LanClient {
30    /// Point at an endpoint's versioned base URL.
31    ///
32    /// The certificate is self-signed and unverified, exactly as during pairing — and
33    /// nothing this client returns is authenticated. It is material for a user interface,
34    /// not a basis for a decision. See [`proto::lan`](crate::connect::proto::lan).
35    pub fn new(base_url: &str) -> Result<Self, Error> {
36        Ok(Self {
37            http: Http::new(
38                base_url,
39                &TlsPolicy::LanPairingOnly,
40                super::Pairing::REQUEST_TIMEOUT,
41            )?,
42            long_poll: Http::new(
43                base_url,
44                &TlsPolicy::LanPairingOnly,
45                core::time::Duration::from(LONG_POLL_TIMEOUT),
46            )?,
47        })
48    }
49
50    /// `GET /v1/endpoint` — the endpoint's own description.
51    pub async fn endpoint(&self) -> Result<EndpointDescription, Error> {
52        self.http.get("getEndpoint", "endpoint").await
53    }
54
55    /// `GET /v1/nodes` — every node this endpoint hosts.
56    ///
57    /// Note that the schema returns bare [`NodeDescription`]s, with no
58    /// [`NodeIdAlias`](crate::connect::proto::NodeIdAlias) — so a user interface can show
59    /// a list but cannot tell which entry a pairing code's alias names
60    /// (erratum E21).
61    pub async fn nodes(&self) -> Result<Vec<NodeDescription>, Error> {
62        self.http.get("getNodes", "nodes").await
63    }
64
65    /// `POST /v1/preparePairing` — "the end user has started the process on the client".
66    ///
67    /// A hint that lets the server show the pairing code at the moment the user is looking
68    /// for it. Best effort by design: "When a preparePairing is called, it is not
69    /// guaranteed that a call to pairingRequest or cancelPreparePairing will follow."
70    pub async fn prepare_pairing(&self, body: &PreparePairing) -> Result<(), Error> {
71        self.http
72            .post_empty("preparePairing", "preparePairing", None, Some(body))
73            .await
74    }
75
76    /// `POST /v1/cancelPreparePairing` — the user changed their mind.
77    pub async fn cancel_prepare_pairing(&self, body: &CancelPreparePairing) -> Result<(), Error> {
78        self.http
79            .post_empty(
80                "cancelPreparePairing",
81                "cancelPreparePairing",
82                None,
83                Some(body),
84            )
85            .await
86    }
87
88    /// `POST /v1/waitForPairing` — hold a request open until the endpoint has something
89    /// to say.
90    ///
91    /// This is how a Resource Manager that is "purely an HTTPS client" — no listening
92    /// socket, nothing for a CEM to dial — takes part in a pairing at all: it asks the
93    /// other endpoint what to do, and the answer arrives whenever a person presses a
94    /// button there. The server holds the request for up to
95    /// [`LONG_POLL_HOLD`](crate::connect::proto::LONG_POLL_HOLD) and then answers with an
96    /// empty list; that is not an error, it is "nothing yet, ask again".
97    ///
98    /// `S2C §Long-polling`: "the client can represent multiple nodes so the request body
99    /// and the response contains a list", and the server "may only provide at most one
100    /// item for each clientNodeId". Call it in a loop:
101    ///
102    /// ```no_run
103    /// # use s2_kit::connect::client::LanClient;
104    /// # use s2_kit::connect::proto::{WaitAction, WaitForPairing};
105    /// # async fn poll(client: &LanClient, mine: Vec<WaitForPairing>) -> Result<(), Box<dyn std::error::Error>> {
106    /// loop {
107    ///     for instruction in client.wait_for_pairing(&mine).await? {
108    ///         match instruction.action {
109    ///             WaitAction::RequestPairing => { /* start `Pairing::run` now */ }
110    ///             WaitAction::SendNodeDescription => { /* answer with descriptions */ }
111    ///             _ => {}
112    ///         }
113    ///     }
114    /// }
115    /// # }
116    /// ```
117    pub async fn wait_for_pairing(
118        &self,
119        nodes: &[WaitForPairing],
120    ) -> Result<Vec<WaitInstruction>, Error> {
121        self.long_poll
122            .post("waitForPairing", "waitForPairing", None, &nodes)
123            .await
124    }
125}