1//! D-Bus address handling.
2//!
3//! Server addresses consist of a transport name followed by a colon, and then an optional,
4//! comma-separated list of keys and values in the form key=value.
5//!
6//! See also:
7//!
8//! * [Server addresses] in the D-Bus specification.
9//!
10//! [Server addresses]: https://dbus.freedesktop.org/doc/dbus-specification.html#addresses
11
12pub mod transport;
13
14use crate::{Error, Guid, OwnedGuid, Result};
15#[cfg(all(unix, not(target_os = "macos")))]
16use nix::unistd::Uid;
17use std::{collections::HashMap, env, str::FromStr};
18
19use std::fmt::{Display, Formatter};
20
21use self::transport::Stream;
22pub use self::transport::Transport;
23
24/// A bus address
25#[derive(Clone, Debug, PartialEq, Eq)]
26#[non_exhaustive]
27pub struct Address {
28 guid: Option<OwnedGuid>,
29 transport: Transport,
30}
31
32impl Address {
33 /// Create a new `Address` from a `Transport`.
34 pub fn new(transport: Transport) -> Self {
35 Self {
36 transport,
37 guid: None,
38 }
39 }
40
41 /// Set the GUID for this address.
42 pub fn set_guid<G>(mut self, guid: G) -> Result<Self>
43 where
44 G: TryInto<OwnedGuid>,
45 G::Error: Into<crate::Error>,
46 {
47 self.guid = Some(guid.try_into().map_err(Into::into)?);
48
49 Ok(self)
50 }
51
52 /// The transport details for this address.
53 pub fn transport(&self) -> &Transport {
54 &self.transport
55 }
56
57 #[cfg_attr(any(target_os = "macos", windows), async_recursion::async_recursion)]
58 pub(crate) async fn connect(self) -> Result<Stream> {
59 self.transport.connect().await
60 }
61
62 /// Get the address for session socket respecting the DBUS_SESSION_BUS_ADDRESS environment
63 /// variable. If we don't recognize the value (or it's not set) we fall back to
64 /// $XDG_RUNTIME_DIR/bus
65 pub fn session() -> Result<Self> {
66 match env::var("DBUS_SESSION_BUS_ADDRESS") {
67 Ok(val) => Self::from_str(&val),
68 _ => {
69 #[cfg(windows)]
70 return Self::from_str("autolaunch:");
71
72 #[cfg(all(unix, not(target_os = "macos")))]
73 {
74 let runtime_dir = env::var("XDG_RUNTIME_DIR")
75 .unwrap_or_else(|_| format!("/run/user/{}", Uid::effective()));
76 let path = format!("unix:path={runtime_dir}/bus");
77
78 Self::from_str(&path)
79 }
80
81 #[cfg(target_os = "macos")]
82 return Self::from_str("launchd:env=DBUS_LAUNCHD_SESSION_BUS_SOCKET");
83 }
84 }
85 }
86
87 /// Get the address for system bus respecting the DBUS_SYSTEM_BUS_ADDRESS environment
88 /// variable. If we don't recognize the value (or it's not set) we fall back to
89 /// /var/run/dbus/system_bus_socket
90 pub fn system() -> Result<Self> {
91 match env::var("DBUS_SYSTEM_BUS_ADDRESS") {
92 Ok(val) => Self::from_str(&val),
93 _ => {
94 #[cfg(all(unix, not(target_os = "macos")))]
95 return Self::from_str("unix:path=/var/run/dbus/system_bus_socket");
96
97 #[cfg(windows)]
98 return Self::from_str("autolaunch:");
99
100 #[cfg(target_os = "macos")]
101 return Self::from_str("launchd:env=DBUS_LAUNCHD_SESSION_BUS_SOCKET");
102 }
103 }
104 }
105
106 /// The GUID for this address, if known.
107 pub fn guid(&self) -> Option<&Guid<'_>> {
108 self.guid.as_ref().map(|guid| guid.inner())
109 }
110}
111
112impl Display for Address {
113 fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
114 self.transport.fmt(f)?;
115
116 if let Some(guid: &OwnedGuid) = &self.guid {
117 write!(f, ",guid={}", guid)?;
118 }
119
120 Ok(())
121 }
122}
123
124impl FromStr for Address {
125 type Err = Error;
126
127 /// Parse the transport part of a D-Bus address into a `Transport`.
128 fn from_str(address: &str) -> Result<Self> {
129 let col = address
130 .find(':')
131 .ok_or_else(|| Error::Address("address has no colon".to_owned()))?;
132 let transport = &address[..col];
133 let mut options = HashMap::new();
134
135 if address.len() > col + 1 {
136 for kv in address[col + 1..].split(',') {
137 let (k, v) = match kv.find('=') {
138 Some(eq) => (&kv[..eq], &kv[eq + 1..]),
139 None => {
140 return Err(Error::Address(
141 "missing = when parsing key/value".to_owned(),
142 ))
143 }
144 };
145 if options.insert(k, v).is_some() {
146 return Err(Error::Address(format!(
147 "Key `{k}` specified multiple times"
148 )));
149 }
150 }
151 }
152
153 Ok(Self {
154 guid: options
155 .remove("guid")
156 .map(|s| Guid::from_str(s).map(|guid| OwnedGuid::from(guid).to_owned()))
157 .transpose()?,
158 transport: Transport::from_options(transport, options)?,
159 })
160 }
161}
162
163impl TryFrom<&str> for Address {
164 type Error = Error;
165
166 fn try_from(value: &str) -> Result<Self> {
167 Self::from_str(value)
168 }
169}
170
171impl From<Transport> for Address {
172 fn from(transport: Transport) -> Self {
173 Self::new(transport)
174 }
175}
176
177#[cfg(test)]
178mod tests {
179 use super::{
180 transport::{Tcp, TcpTransportFamily, Transport},
181 Address,
182 };
183 #[cfg(target_os = "macos")]
184 use crate::address::transport::Launchd;
185 #[cfg(windows)]
186 use crate::address::transport::{Autolaunch, AutolaunchScope};
187 use crate::{
188 address::transport::{Unix, UnixSocket},
189 Error,
190 };
191 use std::str::FromStr;
192 use test_log::test;
193
194 #[test]
195 fn parse_dbus_addresses() {
196 match Address::from_str("").unwrap_err() {
197 Error::Address(e) => assert_eq!(e, "address has no colon"),
198 _ => panic!(),
199 }
200 match Address::from_str("foo").unwrap_err() {
201 Error::Address(e) => assert_eq!(e, "address has no colon"),
202 _ => panic!(),
203 }
204 match Address::from_str("foo:opt").unwrap_err() {
205 Error::Address(e) => assert_eq!(e, "missing = when parsing key/value"),
206 _ => panic!(),
207 }
208 match Address::from_str("foo:opt=1,opt=2").unwrap_err() {
209 Error::Address(e) => assert_eq!(e, "Key `opt` specified multiple times"),
210 _ => panic!(),
211 }
212 match Address::from_str("tcp:host=localhost").unwrap_err() {
213 Error::Address(e) => assert_eq!(e, "tcp address is missing `port`"),
214 _ => panic!(),
215 }
216 match Address::from_str("tcp:host=localhost,port=32f").unwrap_err() {
217 Error::Address(e) => assert_eq!(e, "invalid tcp `port`"),
218 _ => panic!(),
219 }
220 match Address::from_str("tcp:host=localhost,port=123,family=ipv7").unwrap_err() {
221 Error::Address(e) => assert_eq!(e, "invalid tcp address `family`: ipv7"),
222 _ => panic!(),
223 }
224 match Address::from_str("unix:foo=blah").unwrap_err() {
225 Error::Address(e) => assert_eq!(e, "unix: address is invalid"),
226 _ => panic!(),
227 }
228 #[cfg(target_os = "linux")]
229 match Address::from_str("unix:path=/tmp,abstract=foo").unwrap_err() {
230 Error::Address(e) => {
231 assert_eq!(e, "unix: address is invalid")
232 }
233 _ => panic!(),
234 }
235 assert_eq!(
236 Address::from_str("unix:path=/tmp/dbus-foo").unwrap(),
237 Transport::Unix(Unix::new(UnixSocket::File("/tmp/dbus-foo".into()))).into(),
238 );
239 #[cfg(target_os = "linux")]
240 assert_eq!(
241 Address::from_str("unix:abstract=/tmp/dbus-foo").unwrap(),
242 Transport::Unix(Unix::new(UnixSocket::Abstract("/tmp/dbus-foo".into()))).into(),
243 );
244 let guid = crate::Guid::generate();
245 assert_eq!(
246 Address::from_str(&format!("unix:path=/tmp/dbus-foo,guid={guid}")).unwrap(),
247 Address::from(Transport::Unix(Unix::new(UnixSocket::File(
248 "/tmp/dbus-foo".into()
249 ))))
250 .set_guid(guid.clone())
251 .unwrap(),
252 );
253 assert_eq!(
254 Address::from_str("tcp:host=localhost,port=4142").unwrap(),
255 Transport::Tcp(Tcp::new("localhost", 4142)).into(),
256 );
257 assert_eq!(
258 Address::from_str("tcp:host=localhost,port=4142,family=ipv4").unwrap(),
259 Transport::Tcp(Tcp::new("localhost", 4142).set_family(Some(TcpTransportFamily::Ipv4)))
260 .into(),
261 );
262 assert_eq!(
263 Address::from_str("tcp:host=localhost,port=4142,family=ipv6").unwrap(),
264 Transport::Tcp(Tcp::new("localhost", 4142).set_family(Some(TcpTransportFamily::Ipv6)))
265 .into(),
266 );
267 assert_eq!(
268 Address::from_str("tcp:host=localhost,port=4142,family=ipv6,noncefile=/a/file/path")
269 .unwrap(),
270 Transport::Tcp(
271 Tcp::new("localhost", 4142)
272 .set_family(Some(TcpTransportFamily::Ipv6))
273 .set_nonce_file(Some(b"/a/file/path".to_vec()))
274 )
275 .into(),
276 );
277 assert_eq!(
278 Address::from_str(
279 "nonce-tcp:host=localhost,port=4142,family=ipv6,noncefile=/a/file/path%20to%20file%201234"
280 )
281 .unwrap(),
282 Transport::Tcp(
283 Tcp::new("localhost", 4142)
284 .set_family(Some(TcpTransportFamily::Ipv6))
285 .set_nonce_file(Some(b"/a/file/path to file 1234".to_vec()))
286 ).into()
287 );
288 #[cfg(windows)]
289 assert_eq!(
290 Address::from_str("autolaunch:").unwrap(),
291 Transport::Autolaunch(Autolaunch::new()).into(),
292 );
293 #[cfg(windows)]
294 assert_eq!(
295 Address::from_str("autolaunch:scope=*my_cool_scope*").unwrap(),
296 Transport::Autolaunch(
297 Autolaunch::new()
298 .set_scope(Some(AutolaunchScope::Other("*my_cool_scope*".to_string())))
299 )
300 .into(),
301 );
302 #[cfg(target_os = "macos")]
303 assert_eq!(
304 Address::from_str("launchd:env=my_cool_env_key").unwrap(),
305 Transport::Launchd(Launchd::new("my_cool_env_key")).into(),
306 );
307
308 #[cfg(all(feature = "vsock", not(feature = "tokio")))]
309 assert_eq!(
310 Address::from_str(&format!("vsock:cid=98,port=2934,guid={guid}")).unwrap(),
311 Address::from(Transport::Vsock(super::transport::Vsock::new(98, 2934)))
312 .set_guid(guid)
313 .unwrap(),
314 );
315 assert_eq!(
316 Address::from_str("unix:dir=/some/dir").unwrap(),
317 Transport::Unix(Unix::new(UnixSocket::Dir("/some/dir".into()))).into(),
318 );
319 assert_eq!(
320 Address::from_str("unix:tmpdir=/some/dir").unwrap(),
321 Transport::Unix(Unix::new(UnixSocket::TmpDir("/some/dir".into()))).into(),
322 );
323 }
324
325 #[test]
326 fn stringify_dbus_addresses() {
327 assert_eq!(
328 Address::from(Transport::Unix(Unix::new(UnixSocket::File(
329 "/tmp/dbus-foo".into()
330 ))))
331 .to_string(),
332 "unix:path=/tmp/dbus-foo",
333 );
334 assert_eq!(
335 Address::from(Transport::Unix(Unix::new(UnixSocket::Dir(
336 "/tmp/dbus-foo".into()
337 ))))
338 .to_string(),
339 "unix:dir=/tmp/dbus-foo",
340 );
341 assert_eq!(
342 Address::from(Transport::Unix(Unix::new(UnixSocket::TmpDir(
343 "/tmp/dbus-foo".into()
344 ))))
345 .to_string(),
346 "unix:tmpdir=/tmp/dbus-foo"
347 );
348 // FIXME: figure out how to handle abstract on Windows
349 #[cfg(target_os = "linux")]
350 assert_eq!(
351 Address::from(Transport::Unix(Unix::new(UnixSocket::Abstract(
352 "/tmp/dbus-foo".into()
353 ))))
354 .to_string(),
355 "unix:abstract=/tmp/dbus-foo"
356 );
357 assert_eq!(
358 Address::from(Transport::Tcp(Tcp::new("localhost", 4142))).to_string(),
359 "tcp:host=localhost,port=4142"
360 );
361 assert_eq!(
362 Address::from(Transport::Tcp(
363 Tcp::new("localhost", 4142).set_family(Some(TcpTransportFamily::Ipv4))
364 ))
365 .to_string(),
366 "tcp:host=localhost,port=4142,family=ipv4"
367 );
368 assert_eq!(
369 Address::from(Transport::Tcp(
370 Tcp::new("localhost", 4142).set_family(Some(TcpTransportFamily::Ipv6))
371 ))
372 .to_string(),
373 "tcp:host=localhost,port=4142,family=ipv6"
374 );
375 assert_eq!(
376 Address::from(Transport::Tcp(Tcp::new("localhost", 4142)
377 .set_family(Some(TcpTransportFamily::Ipv6))
378 .set_nonce_file(Some(b"/a/file/path to file 1234".to_vec())
379 )))
380 .to_string(),
381 "nonce-tcp:noncefile=/a/file/path%20to%20file%201234,host=localhost,port=4142,family=ipv6"
382 );
383 #[cfg(windows)]
384 assert_eq!(
385 Address::from(Transport::Autolaunch(Autolaunch::new())).to_string(),
386 "autolaunch:"
387 );
388 #[cfg(windows)]
389 assert_eq!(
390 Address::from(Transport::Autolaunch(Autolaunch::new().set_scope(Some(
391 AutolaunchScope::Other("*my_cool_scope*".to_string())
392 ))))
393 .to_string(),
394 "autolaunch:scope=*my_cool_scope*"
395 );
396 #[cfg(target_os = "macos")]
397 assert_eq!(
398 Address::from(Transport::Launchd(Launchd::new("my_cool_key"))).to_string(),
399 "launchd:env=my_cool_key"
400 );
401
402 #[cfg(all(feature = "vsock", not(feature = "tokio")))]
403 {
404 let guid = crate::Guid::generate();
405 assert_eq!(
406 Address::from(Transport::Vsock(super::transport::Vsock::new(98, 2934)))
407 .set_guid(guid.clone())
408 .unwrap()
409 .to_string(),
410 format!("vsock:cid=98,port=2934,guid={guid}"),
411 );
412 }
413 }
414
415 #[test]
416 fn connect_tcp() {
417 let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
418 let port = listener.local_addr().unwrap().port();
419 let addr = Address::from_str(&format!("tcp:host=localhost,port={port}")).unwrap();
420 crate::utils::block_on(async { addr.connect().await }).unwrap();
421 }
422
423 #[test]
424 fn connect_nonce_tcp() {
425 struct PercentEncoded<'a>(&'a [u8]);
426
427 impl std::fmt::Display for PercentEncoded<'_> {
428 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
429 super::transport::encode_percents(f, self.0)
430 }
431 }
432
433 use std::io::Write;
434
435 const TEST_COOKIE: &[u8] = b"VERILY SECRETIVE";
436
437 let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
438 let port = listener.local_addr().unwrap().port();
439
440 let mut cookie = tempfile::NamedTempFile::new().unwrap();
441 cookie.as_file_mut().write_all(TEST_COOKIE).unwrap();
442
443 let encoded_path = format!(
444 "{}",
445 PercentEncoded(cookie.path().to_str().unwrap().as_ref())
446 );
447
448 let addr = Address::from_str(&format!(
449 "nonce-tcp:host=localhost,port={port},noncefile={encoded_path}"
450 ))
451 .unwrap();
452
453 let (sender, receiver) = std::sync::mpsc::sync_channel(1);
454
455 std::thread::spawn(move || {
456 use std::io::Read;
457
458 let mut client = listener.incoming().next().unwrap().unwrap();
459
460 let mut buf = [0u8; 16];
461 client.read_exact(&mut buf).unwrap();
462
463 sender.send(buf == TEST_COOKIE).unwrap();
464 });
465
466 crate::utils::block_on(addr.connect()).unwrap();
467
468 let saw_cookie = receiver
469 .recv_timeout(std::time::Duration::from_millis(100))
470 .expect("nonce file content hasn't been received by server thread in time");
471
472 assert!(
473 saw_cookie,
474 "nonce file content has been received, but was invalid"
475 );
476 }
477}
478