Several improvements around parameters

[azerupi]

This PR has 3 changes that improve parameter handling.

1. Prevent panic for parameter values that can't be represented in the Rust type

Problem

Right now on main, users of rclrs can implement the public ParameterVariant trait for arbitrary Rust types. This is for example very useful to implement string-backed enums.

However the code in rclrs that writes the parameter only checks that the kind is correct before storing the value. However the functions that read the value (MandatoryParameter::get, OptionalParameter::get, ReadOnlyParameter::get, both subscribe() closures, and both on_change wrappers) assume it can infallibly convert to the Rust type.

pub fn get(&self) -> T {
    self.value.read().unwrap().clone().try_into().ok().unwrap()
}

So let's imagine we have this user code

    #[derive(Clone, Debug, PartialEq)]
    enum Switch {
        On,
        Off,
    }

    impl From<Switch> for ParameterValue {
        fn from(value: Switch) -> Self {
            ParameterValue::String(
                match value {
                    Switch::On => "on",
                    Switch::Off => "off",
                }
                .into(),
            )
        }
    }

    impl TryFrom<ParameterValue> for Switch {
        type Error = ParameterValueError;

        fn try_from(value: ParameterValue) -> Result<Self, Self::Error> {
            match value {
                ParameterValue::String(s) => match s.as_ref() {
                    "on" => Ok(Switch::On),
                    "off" => Ok(Switch::Off),
                    other => Err(ParameterValueError::Invalid(format!(
                        "unknown Switch '{other}', expected one of: on, off"
                    ))),
                },
                _ => Err(ParameterValueError::TypeMismatch),
            }
        }
    }

    impl ParameterVariant for Switch {
        type Range = ();

        fn kind() -> ParameterKind {
            ParameterKind::String
        }
    }

It will only work if the string value is "on" or "off", anything else will result in a panic since we are only validating the kind. Any string can be stored in the parameter.

$ ros2 param set /my_node switch banana
Set parameter successful

This is pretty bad because any remote client on the ROS graph could crash a node that implements this.

Fix 7c9cac1

To fix this, we are now checking the conversion before storing the value. Any value that doesn't pass the conversion is does not get stored. In the same way other built-in checks run (e.g. ranges).

$ ros2 param set /my_node switch banana
Setting parameter failed: Parameter value is not valid for this parameter's type: unknown Switch 'banana', expected one of: on, off

and param.get() still returns the previous value because the new value was never stored.

2. Define constraints at ParameterVariant implementation

Gap

ROS 2 parameter descriptors carry constraints in IntegerRange, FloatingPointRange or additional_constraints (free text).

Right now, for custom fields, for example the previously defined Switch enum the constraints have to be passed at each declaration of a parameter using this type. There is also nothing that keeps those multiple constraint declarations in sync with the type, adding a new enum variant will silently make the declared constraints drift unless all of them are updated. And if you forget to declare the constraints, ros2 param describe gives you no information.

Fix 3f27dcc

We add a new method on ParameterVariant that allows the the constraints to be declared where the type is defined as a ROS parameter. It has a default implementation that returns None.

This allows a type to specify its constraints. If the user declaring the parameter adds explicit constraints they will be used otherwise we default to the type's constraints.

3. Support common Rust types as parameters

Gap

A parameter could only be declared with the Rust type that most directly represents one of the nine ROS 2 types: bool, i64, f64, Arc, Arc<[u8]>, Arc<[bool]>, Arc<[i64]>, Arc<[f64]>, Arc<[Arc]>. This is convenient for the parameter machinery (rclrs) but inconvenient for the application (user).

Fix 4f098d4

We implement ParameterVariant for many common Rust types to allow them to be used as parameters.

Category	Types	ROS 2 kind
Strings	String, PathBuf	String
Narrow integers	i8, i16, i32, u8, u16, u32	Integer
Narrow float	f32	Double
Durations	DurationSecs, DurationMillis (new types around Duration)	Double / Integer
Arrays	Vec<T> of every scalar above, plus Vec<i64>, Vec<f64>, Vec<bool>, Vec<u8>, Vec<String>	matching array kind

Note:

• Vec<u8> is a byte array, not an integer array. ROS 2 has a dedicated byte array type. It's the one Rust array type that doesn't follow its scalar (u8 alone is an Integer).
• u64, usize, i128 and u128 are deliberately absent. ROS 2's integer type is i64 and conversions from those types could silently produce values that did not match the intent.
• I decided to create newtypes around Duration to be able to differentiate between seconds (Float) and milliseconds (Integer).

This was only possible after fix n°1 because now we have many Rust types that can't represent all values that could be stored in the ROS type. But since we now check the conversion before storing, this is totally fine!

The narrow integers define an IntegerRange that allow to describe the parameter constraints.

Before:

let wheels: MandatoryParameter<Arc<[Arc<str>]>> = node
    .declare_parameter("wheels")
    .default_string_array(["left", "right"])
    .mandatory()?;
let timeout_s: MandatoryParameter<f64> = /* ... and convert by hand at every use */;

After:

let wheels:  MandatoryParameter<Vec<String>>  = node.declare_parameter("wheels")
    .default(vec!["left".to_string(), "right".to_string()]).mandatory()?;
let device:  MandatoryParameter<PathBuf>      = node.declare_parameter("device")
    .default(PathBuf::from("/dev/ttyUSB0")).mandatory()?;
let timeout: MandatoryParameter<DurationSecs> = node.declare_parameter("timeout")
    .default(DurationSecs(Duration::from_millis(2500))).mandatory()?;
let port:    MandatoryParameter<u16>          = node.declare_parameter("port")
    .default(8080).mandatory()?;

Beyond the ergonomics provided here, this is the groundwork for future PRs that provide a derive proc-macro based API similar to clap.