1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
// Copyright (c) 2026 Erik Lening (hollowpointer) and Contributors
//
// This file is part of Zond Engine, licensed under the GNU Affero General
// Public License, version 3 or later. See the LICENSE file for details, or
// <https://www.gnu.org/licenses/agpl-3.0.html>.
//
// SPDX-License-Identifier: AGPL-3.0-or-later
//! # Reading a string a stranger wrote
//!
//! The three announcement protocols here carry human-readable fields inside
//! length-delimited records: a switch's system name, a printer's hostname, a
//! vendor's model string. They all need the same two things done to those bytes
//! before anything downstream sees them, and doing it three times is how the
//! three came to disagree.
/// A length-delimited field as text, or `None` if it is not text.
///
/// Two things happen here, and both are about a field whose width is fixed and
/// whose contents are not.
///
/// Padding is trimmed. Equipment that NUL-terminates its strings routinely
/// pads past the terminator to the width of the field, so `printer\0\0\0\0` is
/// how a device with a seven-character name fills an eleven-byte record. Every
/// trailing NUL goes, not just the last one: a hostname carrying three of them
/// into a report is a hostname nobody can search for.
///
/// Bytes that are not UTF-8 are declined. These fields are specified as
/// text, and a device that disagrees has produced something to report as
/// unreadable rather than to render with replacement characters. That is the
/// rule every reader in this module follows.
///
/// A field that is empty, or empty once its padding is gone, is `None` as well:
/// a device that sent the record and left it blank has said nothing, and an
/// empty string on a host record reads as a name rather than as an absence.
pub
// ╔════════════════════════════════════════════╗
// ║ ████████╗███████╗███████╗████████╗███████╗ ║
// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
// ║ ██║ █████╗ ███████╗ ██║ ███████╗ ║
// ║ ██║ ██╔══╝ ╚════██║ ██║ ╚════██║ ║
// ║ ██║ ███████╗███████║ ██║ ███████║ ║
// ║ ╚═╝ ╚══════╝╚══════╝ ╚═╝ ╚══════╝ ║
// ╚════════════════════════════════════════════╝