Merge pull request #4 from Bas-Man/dev

Bring 0.3.0 code into master branch.

Author: Bas-Man

CHANGELOG.md

@@ -1,22 +1,54 @@
+0.3.0 2024-12-03
+================
+
+- Breaking Changes
+    - `Spf` struct renamed to `SpfBuilder` and placed behind a `builder` flag.
+    - New simplified `Spf<T>` struct defined.
+    - New Spf<String> Implementation.
+
+___
+
+- Add
+
+    - `iter()` functionality for `Spf` & `SpfBuilder`
+    - `From` implementations
+        - From `Mechanism<IpNetwork>` for `Mechanism<String>`
+        - From `Mechanism<All>` for `Mechanism<String>`
+        - From `Spf<String>` for `SpfBuilder`
+    - `trait Appendable`
+        - This provides a dynamically dispatched `append()` function that accepts
+          either a `Mechanism<String>` or `Mechanism<IpNetwork>`
+    - `validate()` for `Spf<String>`
+        - This function returns either `()` or a `SpfErrors`
+
+- Fix
+
+    - `Mechanism<IpNetwork>`
+        - This Mechanism now correctly returns IP Addresses and Networks.
+          Previously `ip4:192.168.1.10` would later be returned as `ip4:192.168.1.10/32`.
+          This has now been corrected for both ip4 and ip6.
+
+___
+
 0.2.6 2023-12-18
 ================
 
 - Add Serialize and Deserialize Support
-  - Requires the serde feature to be enabled.
+    - Requires the serde feature to be enabled.
 
 0.2.5 2023-11-04
 ================
 
 - Add support to Mechanism `exist` for Macro Expansion. Strings starting with `%` will now be matched.
-    Support contributed by [22ca54d00f05391d6ffee4bc23a5ba60](phttps://github.com/22ca54d00f05391d6ffeoe4bc23a5ba60)
-    
+  Support contributed by [22ca54d00f05391d6ffee4bc23a5ba60](phttps://github.com/22ca54d00f05391d6ffeoe4bc23a5ba60)
+
 0.2.4 2022-01-19
 ================
 
 - Remove code which has been deprecated since 0.2.0
 - Implement `strict-dns` feature
-  - Use crate `addr` to validate *domain* information for `a`, `mx`, `ptr`, `include`, and `exists`
-  - See: `examples/build-spf-strict.rs`
+    - Use crate `addr` to validate *domain* information for `a`, `mx`, `ptr`, `include`, and `exists`
+    - See: `examples/build-spf-strict.rs`
 - Deprecate `Mechanism::new_` functions.
 - Breaking Change: Rename some `MechanismError::` messages.
 
@@ -29,15 +61,15 @@
 ================
 
 - Add Feature (warn-dns)  
-  With this feature enabled any malformed DNS records will cause `has_warnings()` to be set to `true`. Their values can then be accessed using `warnings()`. Even though they are invalid. No error will be generated.
-  
+  With this feature enabled any malformed DNS records will cause `has_warnings()` to be set to `true`. Their values can
+  then be accessed using `warnings()`. Even though they are invalid. No error will be generated.
+
 0.2.1 2021-11-03
 ================
 
 - Documentation Update
 
-
-0.2.0 2021-11-02 
+0.2.0 2021-11-02
 ================
 
 Breaking Changes.
@@ -52,13 +84,14 @@ Changes
 - Bump Version to 0.2.0
 - Add this CHANGELOG.md file.
 - Complete re-orginisation of the crate's module layout.
-  - Note that spf::{qualifier::Qualifier, kinds::MechanismKind, mechanism::Mechanism} no longer exist. These can now be accessed more simply as: 
-    -  mechanism::{Qualifer, Kind, Mechanism} 
+    - Note that spf::{qualifier::Qualifier, kinds::MechanismKind, mechanism::Mechanism} no longer exist. These can now
+      be accessed more simply as:
+        - mechanism::{Qualifer, Kind, Mechanism}
 - Correct license reference to correctly show as MIT license
-- Introduced ability to build SPF records programmatically. 
-  - See examples/build-new-spf.rs
+- Introduced ability to build SPF records programmatically.
+    - See examples/build-new-spf.rs
 - Implemented **Display** trait for structs *Spf* and *Mechanism*
-  - This also depreciates the previously implemented *as_spf()* and *string()* methods.
+    - This also depreciates the previously implemented *as_spf()* and *string()* methods.
 - implemented **FromStr** trait for Struct *Spf*
 - Implemented Errors for `Mechanism`
 - Improved regular expressions to handle more strings when parsing.

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing
+Contributing
 --------------
 
 - All commits must be digitally signed

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "decon-spf"
-version = "0.2.6"
+version = "0.3.0"
 authors = ["Adam.S <[email protected]>"]
 edition = "2018"
 
@@ -28,39 +28,47 @@ name = "decon_spf"
 path = "src/lib.rs"
 
 [[example]]
-name = "trust-dns-demo"
-path = "examples/trust-dns-demo.rs"
+name = "trust-dns-builder"
+path = "examples/trust-dns-demo-builder.rs"
+required-features = ["builder"]
+
+[[example]]
+name = "trust-dns-spf"
+path = "examples/trust-dns-demo-spf.rs"
 
 [[example]]
 name = "build-spf"
 path = "examples/build-spf.rs"
+required-features = ["builder", "spf2"]
 
 [[example]]
 name = "build-spf-strict"
 path = "examples/build-spf-strict.rs"
-required-features = ["strict-dns"]
+required-features = ["builder", "strict-dns", "spf2"]
 
 [[example]]
 name = "serde-demo"
 path = "examples/serde-demo.rs"
-required-features = ["serde"]
+required-features = ["serde", "spf2"]
 
 [dependencies]
 ipnetwork = "0.20.0"
-regex = "1.10.2"
-lazy_static = "1.4.0"
-addr = { version = "0.15.0", optional = true }
-serde = { version = "1.0.193", features = ["derive"], optional = true }
-#serde_json = { version = "1.0.108", optional = true }
+regex = "1.11.1"
+lazy_static = "1.5.0"
+addr = { version = "0.15.6", optional = true }
+serde = { version = "1.0.215", features = ["derive"], optional = true }
 
 [dev-dependencies]
 trust-dns-resolver = "0.23.2"
-serde_json = { version = "1.0.108" }
+serde_json = { version = "1.0.133" }
 
 [features]
-warn-dns = ["addr"]
-strict-dns = ["addr"]
+default = ["ptr"]
+builder = []
+strict-dns = ["dep:addr"]
 serde = ["dep:serde"]
+spf2 = ["builder"]
+ptr = []
 
 [package.metadata.docs.rs]
 all-features = true

README.md

@@ -2,17 +2,19 @@
 
 # Overview
 
-This crate allows you to deconstruct an existing SPF record that might be retrieved with a dns query of type TXT.  
+This crate allows you to deconstruct an existing SPF record that might be retrieved with a dns query of type TXT.
 
-With 0.2.0. You now have the ability to create SPF records programmatically. 
+With 0.2.0. You now have the ability to create SPF records programmatically.
 Check the **Examples** directory for sample code.
 
 ### See Example Code
 
 Lookup and deconstruct Spf record.
 
-- [trust-dns-resolver](https://github.com/Bas-Man/rust-decon-spf/blob/master/examples/trust-dns-demo.rs)
+- [trust-dns-resolver-builder](https://github.com/Bas-Man/rust-decon-spf/blob/master/examples/trust-dns-demo-builder.rs)
+- [trust-dns-resolver-spf](https://github.com/Bas-Man/rust-decon-spf/blob/master/examples/trust-dns-demo-spf.rs)
 - [build-spf](https://github.com/Bas-Man/rust-decon-spf/blob/master/examples/build-spf.rs)
+- [build-spf-strict](https://github.com/Bas-Man/rust-decon-spf/blob/master/examples/build-spf-strict.rs)
 - [serde-demo](https://github.com/Bas-Man/rust-decon-spf/blob/master/examples/serde-demo.rs)
 
 ### Run example
@@ -24,16 +26,18 @@ $ cargo run --example
 ```
 
 ```bash
-$ cargo run --example trust-dns-demo
+$ cargo run --example trust-dns-builder
+$ cargo run --example trust-dns-spf
 $ cargo run --example build-spf
 $ cargo run -F strict-dns --example build-spf-strict
 $ cargo run -F serde --example serde-demo
 ```
 
 ## Syntax Validation
 
-This crate is not intended to provide syntax validation.  
-If you are looking to validate your SPF record. I would suggest you use one of 
+Whilst this crate is not intended to provide syntax validation, some validation has been added as
+of Version **0.3.0**.  
+If you are looking to validate your SPF record. I would suggest you use one of
 the following:
 
 1. [VamSoft.com](https://vamsoft.com/support/tools/spf-syntax-validator)

examples/build-spf-strict.rs

@@ -1,24 +1,24 @@
 use decon_spf::mechanism::{Kind, Mechanism, ParsedMechanism, Qualifier};
-use decon_spf::Spf;
+use decon_spf::SpfBuilder;
 
 fn main() {
-    let mut spf1 = Spf::new();
+    let mut spf1 = SpfBuilder::new();
     spf1.set_v1();
     let ip_m_1 = ParsedMechanism::new("+ip4:203.32.160.0/24");
     let ip_m_2 = ParsedMechanism::new("+ip4:203.32.166.0/24");
     if let Ok(ip1) = ip_m_1 {
-        spf1.append_ip_mechanism(ip1.network());
+        spf1.append_mechanism(ip1.network());
     }
     if let Ok(ip2) = ip_m_2 {
-        spf1.append_ip_mechanism(ip2.network());
+        spf1.append_mechanism(ip2.network());
     }
 
     if let Ok(mx) = ParsedMechanism::new("mx") {
         spf1.append_mechanism(mx.txt());
     }
 
     // example.xx is not a valid domain. There is no TLD of xx
-    if let Ok(m) = "a:test.xx".parse() {
+    if let Ok(m) = "a:test.xx".parse::<Mechanism<String>>() {
         // Append does not occur
         spf1.append_mechanism(m);
     }
@@ -29,10 +29,10 @@ fn main() {
         "v=spf1 mx ip4:203.32.160.0/24 ip4:203.32.166.0/24"
     );
 
-    let mut spf2 = Spf::new();
+    let mut spf2 = SpfBuilder::new();
     spf2.set_v1();
     let ip = "203.32.166.0/24".parse().unwrap();
-    spf2.append_ip_mechanism(Mechanism::ip(Qualifier::Pass, ip));
+    spf2.append_mechanism(Mechanism::ip(Qualifier::Pass, ip));
 
     println!("\nNew spf 2: >{}<", spf2);
     println!("Attempt to create invalid mx to spf2");
@@ -51,13 +51,13 @@ fn main() {
     spf2.clear_mechanism(Kind::MX);
     println!("Altered spf 2: >{}<", spf2);
 
-    let mut spf3 = Spf::new();
+    let mut spf3 = SpfBuilder::new();
     spf3.set_v2_pra();
     spf3.append_mechanism(Mechanism::a(Qualifier::Pass));
-    spf3.append_mechanism(Mechanism::all(Qualifier::Neutral));
+    spf3.append_mechanism(Mechanism::all_with_qualifier(Qualifier::Neutral));
 
     println!("\nNew spf 3: >{}<", spf3);
     println!("Change spf3 all to Fail");
-    spf3.append_mechanism(Mechanism::all(Qualifier::Fail));
+    spf3.append_mechanism(Mechanism::all_default());
     println!("Altered spf 3: >{}<", spf3);
 }

examples/build-spf.rs

@@ -1,33 +1,33 @@
 use decon_spf::mechanism::{Kind, Mechanism, ParsedMechanism, Qualifier};
-use decon_spf::Spf;
+use decon_spf::SpfBuilder;
 
 fn main() {
-    let mut spf1 = Spf::new();
+    let mut spf1 = SpfBuilder::new();
     spf1.set_v1();
     let ip_m_1 = ParsedMechanism::new("ip4:203.32.160.0/24");
     let ip_m_2 = ParsedMechanism::new("+ip4:203.32.166.0/24");
     let mx = ParsedMechanism::new("mx").unwrap();
     if let Ok(ip1) = ip_m_1 {
-        spf1.append_ip_mechanism(ip1.network());
+        spf1.append_mechanism(ip1.network());
     }
     if let Ok(ip2) = ip_m_2 {
-        spf1.append_ip_mechanism(ip2.network());
+        spf1.append_mechanism(ip2.network());
     }
     spf1.append_mechanism(mx.txt());
 
-    spf1.append_mechanism("a:test.com".parse().unwrap());
+    spf1.append_mechanism("a:test.com".parse::<Mechanism<String>>().unwrap());
 
     println!("New spf 1: >{}<", spf1);
     assert_eq!(
         spf1.to_string(),
         "v=spf1 a:test.com mx ip4:203.32.160.0/24 ip4:203.32.166.0/24"
     );
 
-    let mut spf2 = Spf::new();
+    let mut spf2 = SpfBuilder::new();
     spf2.set_v1();
     let ip = "203.32.166.0/24".parse().unwrap();
     let m = Mechanism::ip(Qualifier::Pass, ip);
-    spf2.append_ip_mechanism(m);
+    spf2.append_mechanism(m);
 
     println!("\nNew spf 2: >{}<", spf2);
     println!("Add mx to spf2");
@@ -37,13 +37,13 @@ fn main() {
     spf2.clear_mechanism(Kind::MX);
     println!("Altered spf 2: >{}<", spf2);
 
-    let mut spf3 = Spf::new();
+    let mut spf3 = SpfBuilder::new();
     spf3.set_v2_pra();
     spf3.append_mechanism(Mechanism::a(Qualifier::Pass));
-    spf3.append_mechanism(Mechanism::all(Qualifier::Neutral));
+    spf3.append_mechanism(Mechanism::all_with_qualifier(Qualifier::Neutral));
 
     println!("\nNew spf 3: >{}<", spf3);
     println!("Change spf3 all to Fail");
-    spf3.append_mechanism(Mechanism::all(Qualifier::Fail));
+    spf3.append_mechanism(Mechanism::all_default());
     println!("Altered spf 3: >{}<", spf3);
 }

examples/serde-demo.rs

@@ -1,22 +1,22 @@
 use decon_spf::mechanism::{Mechanism, ParsedMechanism, Qualifier};
-use decon_spf::Spf;
+use decon_spf::SpfBuilder;
 use serde_json;
 
 fn main() {
-    let mut spf1 = Spf::new();
+    let mut spf1 = SpfBuilder::new();
     spf1.set_v1();
     let ip_m_1 = ParsedMechanism::new("ip4:203.32.160.0/24");
     let ip_m_2 = ParsedMechanism::new("+ip4:203.32.166.0/24");
     let mx = ParsedMechanism::new("mx").unwrap();
     if let Ok(ip1) = ip_m_1 {
-        spf1.append_ip_mechanism(ip1.network());
+        spf1.append_mechanism(ip1.network());
     }
     if let Ok(ip2) = ip_m_2 {
-        spf1.append_ip_mechanism(ip2.network());
+        spf1.append_mechanism(ip2.network());
     }
     spf1.append_mechanism(mx.txt());
 
-    spf1.append_mechanism("a:test.com".parse().unwrap());
+    spf1.append_mechanism("a:test.com".parse::<Mechanism<String>>().unwrap());
 
     println!("New spf 1: >{}<", spf1);
     assert_eq!(
@@ -27,13 +27,12 @@ fn main() {
     let spf_as_json = serde_json::to_string_pretty(&spf1).unwrap();
     println!("JSON:\n{}", spf_as_json);
 
-    let mut spf2 = Spf::new();
+    let mut spf2 = SpfBuilder::new();
     spf2.set_v2_pra();
     spf2.append_mechanism(Mechanism::a(Qualifier::Pass));
-    spf2.append_mechanism(Mechanism::all(Qualifier::Neutral));
+    spf2.append_mechanism(Mechanism::all_with_qualifier(Qualifier::Neutral));
 
     println!("\nNew spf 2: >{}<", spf2);
     let spf_as_json = serde_json::to_string_pretty(&spf2).unwrap();
     println!("JSON:\n{}", spf_as_json);
-
 }