Struct UnknownPhaseToken 

pub struct UnknownPhaseToken(/* private fields */);

A phase token this build does not recognise, held so it cannot be confused with one it does.

Why the payload is a type and not a bare String

WalletSyncPhase::Unrecognized serializes whatever it holds. With a public String inside, Unrecognized("synced".to_owned()) was constructible by any consumer, reported is_recognized() == false locally, went onto the wire as the bare token "synced", and arrived at the far side as a confident WalletSyncPhase::Synced — a value that claims the wallet is caught up while calling itself unrecognised. It was also the one value in the type that did not round-trip, contradicting the verbatim-carriage guarantee the variant exists to provide.

The field is private and this type has no public constructor, so the only way to reach Unrecognized from outside the crate is WalletSyncPhase::from, which is TOTAL: hand it a known spelling and it returns that known variant instead. The dishonest value is therefore not merely discouraged — it cannot be built.

This is deliberately a type-level guard rather than a documented rule. The whole family exists because a wire-level mismatch went unnoticed until someone built a probe, and a rule that only a doc comment enforces is the same shape of mistake one layer up.

The seal is guarded by a test that can actually see it removed

The ordinary unit tests cannot. They reach Unrecognized only through WalletSyncPhase::from, and the seal is precisely what determines which values that route can produce — so making this field pub again leaves every one of them green while the forged value becomes constructible. Measured: the whole suite passed with the field public.

A doctest is the instrument that works, because doctests compile as a SEPARATE CRATE and therefore see this type exactly as a consumer does. The one below must FAIL to compile; if the field is ever made public it starts compiling, and cargo test reports the doctest as failed.

use dig_node_control_interface::results::{UnknownPhaseToken, WalletSyncPhase};
// A value that calls itself unrecognised while spelling itself `synced` on the wire.
let forged = WalletSyncPhase::Unrecognized(UnknownPhaseToken("synced".to_owned()));

The honest route returns the KNOWN variant instead, which is the whole point:

use dig_node_control_interface::results::WalletSyncPhase;
assert_eq!(WalletSyncPhase::from("synced"), WalletSyncPhase::Synced);
assert!(WalletSyncPhase::from("synced").is_recognized());

Implementations

impl UnknownPhaseToken

pub fn as_str(&self) -> &str

The token’s RAW bytes, exactly as the node sent them — the relay path.

This is the escape hatch, not the default. It exists so a proxy can hand the token on byte-identically, and it is the ONE accessor that returns unescaped node-supplied text. Do not route it to a terminal, a log line, or a UI: use Display or display_bounded, which escape.

use dig_node_control_interface::results::WalletSyncPhase;
let phase = WalletSyncPhase::from("a_newer_token");
assert_eq!(phase.unrecognized_token(), Some("a_newer_token"));

pub fn display_bounded(&self, max_len: usize) -> String

The token escaped for display and truncated to max_len bytes of escaped output.

What Display does, plus a length bound — for a log line or a UI label that must not be handed an unbounded string. Nothing bounds a token’s length on the wire (the contract is transport-agnostic, and rejecting an over-long token would reintroduce the fail-closed parse this type exists to remove), so the bound belongs at the point of display.

The escaped content is at most max_len bytes. A single … is appended when anything was dropped, so a truncated rendering is never mistaken for the whole token.

use dig_node_control_interface::results::WalletSyncPhase;
let phase = WalletSyncPhase::from("a_very_long_token_from_a_newer_node");
let token = phase.unrecognized_token_value().unwrap();
assert_eq!(token.display_bounded(10), "a_very_lon…");

Trait Implementations

impl Clone for UnknownPhaseToken

fn clone(&self) -> UnknownPhaseToken

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UnknownPhaseToken

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for UnknownPhaseToken

fn fmt(&self, f: &mut Formatter<'_>) -> Result

The token ESCAPED — the safe default, because this is the accessor a log line reaches for.

Why the default escapes rather than the opposite

The raw token is attacker-influenced text that is designed to be logged, and a node emitting "\u{1b}[2K\rsynced" turns format!("unknown phase: {token}") into a terminal line reading synced — the erase-line and carriage-return wipe the prefix that said it was unknown. A right-to-left override does the same to a UI label. Making the ergonomic path raw and the safe path opt-in gets that backwards: every consumer would have to remember, and one forgetting reproduces the exact false-reassurance this family exists to prevent.

char::escape_debug is the escaper because it is the standard library’s own, covering C0/C1 controls, DEL, and the format characters that carry bidi overrides. A hand-rolled table here would be a second implementation of a security-relevant rule, and would drift.

as_str remains raw for relaying; display_bounded adds a length bound.

use dig_node_control_interface::results::WalletSyncPhase;
let phase = WalletSyncPhase::from("\u{1b}[2K\rsynced");
let token = phase.unrecognized_token_value().unwrap();
assert_eq!(token.to_string(), "\\u{1b}[2K\\rsynced");

impl Eq for UnknownPhaseToken

impl Hash for UnknownPhaseToken

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for UnknownPhaseToken

fn eq(&self, other: &UnknownPhaseToken) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for UnknownPhaseToken