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}