# Architecture Decision Record: Using yaserde for OPNsense Config Parsing

- Status : Proposed
- Author : Jean-Gabriel Gill-Couture

## Context

We need to parse and manipulate the OPNsense config.xml file in our Rust crate. We considered several XML parsing libraries, including quick-xml, xml-dom, minidom and yaserde. Each library has its own strengths and trade-offs in terms of performance, ease of use, and robustness.

## Decision

We have decided to use yaserde for parsing and manipulating the OPNsense config.xml file.

## Rationale

1. Type Safety: yaserde allows us to define a complete Rust representation of the config.xml structure. This provides strong type safety and makes it easier to catch errors at compile-time rather than runtime.

2. Robustness: By mapping the entire config structure to Rust types, we ensure that our code interacts with the config in a well-defined manner. This reduces the risk of runtime errors due to unexpected XML structures.

3. Ease of Use: Working with native Rust types is more intuitive and less error-prone than manipulating XML directly. This can lead to more maintainable and readable code.

4. Memory Usage: While yaserde may use more memory than streaming parsers like quick-xml, the OPNsense config files are typically not large enough for this to be a significant concern. We prioritize robustness and ease of use over minimal memory usage in this context.

5. Serialization/Deserialization: yaserde provides both deserialization (XML to Rust structs) and serialization (Rust structs to XML) out of the box, which simplifies our implementation.

## Consequences

Positive:
- Increased type safety and robustness in handling the config.xml structure.
- More intuitive API for developers working with the config.
- Easier to extend and maintain the code that interacts with different parts of the config.

Negative:
- It will be harder to maintain when there are breaking changes in the config.xml format. Any structural changes in the XML will require corresponding updates to our Rust struct definitions.
- Slightly higher memory usage compared to streaming parsers.
- Initial development time may be longer due to the need to define the entire config structure upfront.

We accept the trade-off of potentially more difficult maintenance in the face of breaking config.xml changes, as we believe the benefits of increased robustness and type safety outweigh this drawback. When OPNsense releases updates that change the config.xml structure, we will need to update our Rust struct definitions accordingly.