rename nettypes fields

Some field names are confusing. Change them so that they make more sense to the reader. I also added comments to the types to provide more context. also see containers/podman#12319 Signed-off-by: Paul Holzinger <[email protected]>
Luap99 · Nov 16, 2021 · aa4edab · aa4edab
1 parent 43aeb3b
commit aa4edab
Show file tree

Hide file tree

Showing 4 changed files with 124 additions and 74 deletions.
diff --git a/src/network/core.rs b/src/network/core.rs
@@ -24,8 +24,6 @@ impl Core {
     ) -> Result<types::StatusBlock, std::io::Error> {
         //  StatusBlock response
         let mut response = types::StatusBlock {
-            dns_search_domains: Some(Vec::new()),
-            dns_server_ips: Some(Vec::new()),
             interfaces: Some(HashMap::new()),
         };
         // get bridge name
@@ -89,7 +87,7 @@ impl Core {
             address_vector.push(container_address);
             response_net_addresses.push(types::NetAddress {
                 gateway: subnet.gateway,
-                subnet: container_address,
+                ipnet: container_address,
             });
         }
         debug!("Container veth name: {:?}", container_veth_name);
@@ -115,7 +113,7 @@ impl Core {
         debug!("Container veth mac: {:?}", container_veth_mac);
         let interface = types::NetInterface {
             mac_address: container_veth_mac,
-            networks: Option::from(response_net_addresses),
+            subnets: Option::from(response_net_addresses),
         };
         // Add interface to interfaces (part of StatusBlock)
         interfaces.insert(container_veth_name, interface);

diff --git a/src/network/types.rs b/src/network/types.rs
@@ -4,96 +4,135 @@ use ipnet::IpNet;
 use std::collections::HashMap;
 use std::net::IpAddr;
 
-// Network describes the Network attributes.
+/// Network describes the Network attributes.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct Network {
-    #[serde(rename = "created")]
-    pub created: Option<String>,
-
+    /// Set up dns for this network
     #[serde(rename = "dns_enabled")]
     pub dns_enabled: bool,
 
+    /// Driver for this Network, e.g. bridge, macvlan...
     #[serde(rename = "driver")]
     pub driver: String,
 
+    /// ID of the Network.
     #[serde(rename = "id")]
     pub id: String,
 
+    /// Internal is whether the Network should not have external routes
+    /// to public or other Networks.
     #[serde(rename = "internal")]
     pub internal: bool,
 
-    #[serde(rename = "ipam_options")]
-    pub ipam_options: Option<HashMap<String, String>>,
-
+    /// This network contains at least one ipv6 subnet.
     #[serde(rename = "ipv6_enabled")]
     pub ipv6_enabled: bool,
 
-    #[serde(rename = "labels")]
-    pub labels: Option<HashMap<String, String>>,
-
+    /// Name of the Network.
     #[serde(rename = "name")]
     pub name: String,
 
+    /// NetworkInterface is the network interface name on the host.
     #[serde(rename = "network_interface")]
     pub network_interface: Option<String>,
 
+    /// Options is a set of key-value options that have been applied to
+    /// the Network.
     #[serde(rename = "options")]
     pub options: Option<HashMap<String, String>>,
 
+    /// Subnets to use for this network.
     #[serde(rename = "subnets")]
     pub subnets: Option<Vec<Subnet>>,
 }
 
-// NetworkOptions for a given container.
+/// NetworkOptions for a given container.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct NetworkOptions {
+    /// The container id, used for iptables comments and ipam allocation.
     #[serde(rename = "container_id")]
     pub container_id: String,
 
+    /// The container name, used as dns name.
     #[serde(rename = "container_name")]
     pub container_name: String,
 
+    /// The options used to create the interfaces with.
+    /// The networks listed in "network_info" have to match this,
+    /// both use the network name as key for the map.
     #[serde(rename = "networks")]
     pub networks: HashMap<String, PerNetworkOptions>,
 
+    /// The networks which are needed to run this.
+    /// It has to match the networks listed in "networks",
+    /// both use the network name as key for the map.
     #[serde(rename = "network_info")]
     pub network_info: HashMap<String, Network>,
 
+    /// The port mappings for this container.
     #[serde(rename = "port_mappings")]
     pub port_mappings: Option<Vec<PortMapping>>,
 }
 
 // PerNetworkOptions are options which should be set on a per network basis
 #[derive(Debug, Serialize, Deserialize)]
 pub struct PerNetworkOptions {
-    #[serde(rename = "aliases")]
-    pub aliases: Option<Vec<String>>,
+    /// Aliases contains a list of names which the dns server should resolve
+    /// to this container. Should only be set when DNSEnabled is true on the Network.
+    /// If aliases are set but there is no dns support for this network the
+    /// network interface implementation should ignore this and NOT error.
+
+    // DNS is not yet implemented
+
+    // #[serde(rename = "aliases")]
+    // pub aliases: Option<Vec<String>>,
 
+    /// InterfaceName for this container. Required.
     #[serde(rename = "interface_name")]
     pub interface_name: String,
 
+    /// StaticIPs for this container.
     #[serde(rename = "static_ips")]
     pub static_ips: Option<Vec<IpAddr>>,
 
+    /// MAC address for the container interface.
     #[serde(rename = "static_mac")]
     pub static_mac: Option<String>,
 }
 
 // PortMapping is one or more ports that will be mapped into the container.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct PortMapping {
+    /// ContainerPort is the port number that will be exposed from the
+    /// container.
     #[serde(rename = "container_port")]
     pub container_port: u16,
 
+    /// HostIP is the IP that we will bind to on the host.
+    /// If unset, assumed to be 0.0.0.0 (all interfaces).
     #[serde(rename = "host_ip")]
     pub host_ip: String,
 
+    /// HostPort is the port number that will be forwarded from the host into
+    /// the container.
     #[serde(rename = "host_port")]
     pub host_port: u16,
 
+    /// Protocol is the protocol forward.
+    /// Must be either "tcp", "udp", and "sctp", or some combination of these
+    /// separated by commas.
+    /// If unset, assumed to be TCP.
     #[serde(rename = "protocol")]
     pub protocol: String,
 
+    /// Range is the number of ports that will be forwarded, starting at
+    /// HostPort and ContainerPort and counting up.
+    /// This is 1-indexed, so 1 is assumed to be a single port (only the
+    /// Hostport:Containerport mapping will be added), 2 is two ports (both
+    /// Hostport:Containerport and Hostport+1:Containerport+1), etc.
+    /// If unset, assumed to be 1 (a single port).
+    /// Both hostport + range and containerport + range must be less than
+    /// 65536.
     #[serde(rename = "range")]
     pub range: u16,
 }
@@ -102,55 +141,68 @@ pub struct PortMapping {
 // connected to one Network.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct StatusBlock {
-    #[serde(rename = "dns_search_domains")]
-    pub dns_search_domains: Option<Vec<String>>,
+    // DNS is not needed at the moment
 
-    #[serde(rename = "dns_server_ips")]
-    pub dns_server_ips: Option<Vec<String>>,
+    // #[serde(rename = "dns_search_domains")]
+    // pub dns_search_domains: Option<Vec<String>>,
 
+    // #[serde(rename = "dns_server_ips")]
+    // pub dns_server_ips: Option<Vec<String>>,
+    /// Interfaces contains the created network interface in the container.
+    /// The map key is the interface name.
     #[serde(rename = "interfaces")]
     pub interfaces: Option<HashMap<String, NetInterface>>,
 }
 
-// NetInterface contains the settings for a given network interface.
+/// NetInterface contains the settings for a given network interface.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct NetInterface {
+    /// MacAddress for this Interface.
     #[serde(rename = "mac_address")]
     pub mac_address: String,
 
-    #[serde(rename = "networks")]
-    pub networks: Option<Vec<NetAddress>>,
+    /// Subnets list of assigned subnets with their gateway.
+    #[serde(rename = "subnets")]
+    pub subnets: Option<Vec<NetAddress>>,
 }
 
-// NetAddress contains the subnet and gatway.
+/// NetAddress contains the ip address, subnet and gateway.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct NetAddress {
+    /// Gateway for the network. This can be empty if there is no gateway, e.g. internal network.
     #[serde(rename = "gateway")]
     pub gateway: Option<IpAddr>,
 
-    #[serde(rename = "subnet")]
-    pub subnet: IpNet,
+    /// IPNet of this NetAddress. Note that this is a subnet but it has to contain the
+    /// actual ip of the network interface and not the network address.
+    #[serde(rename = "ipnet")]
+    pub ipnet: IpNet,
 }
 
+/// Subnet for a network.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct Subnet {
+    /// Subnet for this Network in CIDR form.
     #[serde(rename = "gateway")]
     pub gateway: Option<IpAddr>,
 
+    /// LeaseRange contains the range where IP are leased. Optional.
     #[serde(rename = "lease_range")]
     pub lease_range: Option<LeaseRange>,
 
+    /// Gateway IP for this Network.
     #[serde(rename = "subnet")]
-    //TODO: Cast this to IpNet
     pub subnet: IpNet,
 }
 
 // LeaseRange contains the range where IP are leased.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct LeaseRange {
+    /// EndIP last IP in the subnet which should be used to assign ips.
     #[serde(rename = "end_ip")]
     pub end_ip: Option<String>,
 
+    /// StartIP first IP in the subnet which should be used to assign ips.
     #[serde(rename = "start_ip")]
     pub start_ip: Option<String>,
 }
diff --git a/src/test/config/setupopts.test.json b/src/test/config/setupopts.test.json
@@ -1,35 +1,35 @@
 {
-   "container_id":"6ce776ea58b5",
-   "container_name":"testcontainer",
-   "port_mappings":[
+   "container_id": "6ce776ea58b5",
+   "container_name": "testcontainer",
+   "port_mappings": [
       {
-         "host_ip":"127.0.0.1",
-         "container_port":5000,
-         "host_port":5001,
-         "range":3,
-         "protocol":"tcp"
+         "host_ip": "127.0.0.1",
+         "container_port": 5000,
+         "host_port": 5001,
+         "range": 3,
+         "protocol": "tcp"
       }
    ],
-   "networks":{
-      "defaultNetwork":{
-         "interface_name":"eth0"
+   "networks": {
+      "defaultNetwork": {
+         "interface_name": "eth0"
       }
    },
-   "network_info":{
-      "defaultNetwork":{
-         "dns_enabled":true,
-         "driver":"bridge",
-         "id":"53ce4390f2adb1681eb1a90ec8b48c49c015e0a8d336c197637e7f65e365fa9e",
-         "internal":false,
-         "ipv6_enabled":true,
-         "name":"defaultNetwork",
-	 "network_interface": "podman0",
- 	 "subnets": [
-	    {
-	      "gateway":"192.168.43.1",
-	      "subnet": "192.168.43.0/24"
+   "network_info": {
+      "defaultNetwork": {
+         "dns_enabled": true,
+         "driver": "bridge",
+         "id": "53ce4390f2adb1681eb1a90ec8b48c49c015e0a8d336c197637e7f65e365fa9e",
+         "internal": false,
+         "ipv6_enabled": true,
+         "name": "defaultNetwork",
+         "network_interface": "podman0",
+         "subnets": [
+            {
+               "gateway": "192.168.43.1",
+               "subnet": "192.168.43.0/24"
             }
-	 ]
+         ]
       }
    }
 }
diff --git a/src/test/config/setupopts2.test.json b/src/test/config/setupopts2.test.json
@@ -1,32 +1,32 @@
 {
-   "container_id":"someID",
-   "container_name":"someName",
-   "networks":{
-      "podman":{
-         "static_ips":[
+   "container_id": "someID",
+   "container_name": "someName",
+   "networks": {
+      "podman": {
+         "static_ips": [
             "10.88.0.2"
          ],
-         "interface_name":"ethsomething0"
+         "interface_name": "ethsomething0"
       }
    },
-   "network_info":{
-      "podman":{
-         "name":"podman",
-         "id":"2f259bab93aaaaa2542ba43ef33eb990d0999ee1b9924b557b7be53c0b7a1bb9",
-         "driver":"bridge",
-         "network_interface":"podman0",
-         "created":"2021-10-26T16:42:48.769170534+02:00",
-         "subnets":[
+   "network_info": {
+      "podman": {
+         "name": "podman",
+         "id": "2f259bab93aaaaa2542ba43ef33eb990d0999ee1b9924b557b7be53c0b7a1bb9",
+         "driver": "bridge",
+         "network_interface": "podman0",
+         "created": "2021-10-26T16:42:48.769170534+02:00",
+         "subnets": [
             {
-               "subnet":"10.88.0.0/16",
-               "gateway":"10.88.0.1"
+               "subnet": "10.88.0.0/16",
+               "gateway": "10.88.0.1"
             }
          ],
-         "ipv6_enabled":false,
-         "internal":false,
-         "dns_enabled":false,
-         "ipam_options":{
-            "driver":"host-local"
+         "ipv6_enabled": false,
+         "internal": false,
+         "dns_enabled": false,
+         "ipam_options": {
+            "driver": "host-local"
          }
       }
    }