Merge pull request #7 from lancalc/special-ipv4-ranges

wachawo · web-flow · commit cfe768b2006d · 2025-08-18T18:31:02.000+02:00
Add support for special IPv4 range detection and handling
diff --git a/.flake8 b/.flake8
@@ -1,2 +1,9 @@
 [flake8]
-max-line-length = 180
+max-line-length = 180
+# extend-ignore = E501
+exclude =
+    .git,
+    __pycache__,
+    *.egg-info,
+    build,
+    dist
diff --git a/README.md b/README.md
@@ -94,22 +94,17 @@ Hosts: 254
 **JSON mode** (`--json`):
 ```json
 {
-  "Network": "192.168.1.0",
-  "Prefix": "/24",
-  "Netmask": "255.255.255.0",
-  "Broadcast": "192.168.1.255",
-  "Hostmin": "192.168.1.1",
-  "Hostmax": "192.168.1.254",
-  "Hosts": "254"
+  "network": "192.168.1.0",
+  "prefix": "/24",
+  "netmask": "255.255.255.0",
+  "broadcast": "192.168.1.255",
+  "hostmin": "192.168.1.1",
+  "hostmax": "192.168.1.254",
+  "hosts": "254",
+  "comment": ""
 }
 ```
 
-### Special Cases
-
-- **/31 networks**: Show `2*` in Hosts field - both addresses are usable (RFC 3021)
-- **/32 networks**: Show `1*` in Hosts field - single host network
-- The asterisk (*) indicates special network types where all addresses are usable
-
 ### Uninstall
 
 ```bash
@@ -197,18 +192,88 @@ Distributed under the MIT License. See LICENSE for more information.
 ## Notes
 
 A /31 mask allows the use of 2 addresses. The first will be the network address, the last the broadcast address, and for connecting hosts we use these same addresses.
-
 Limitations when using a /31 prefix:
-
 Protocols that use L3 broadcast stop working.
 In fact, at present there are almost no protocols left that rely on L3 broadcast in their operation. The main currently relevant protocols, such as OSPF, IS-IS, EIGRP, and BGP, use multicast or unicast addresses instead.
 This limitation can even be seen as an advantage, because it increases resistance to DoS attacks based on broadcast traffic distribution.
-
-Not all devices support /31 prefixes.
+But not all devices support /31 prefixes.
 On Juniper and Cisco devices, you can safely use a /31 mask, although Cisco will issue a warning (% Warning: use /31 mask on non point-to-point interface cautiously).
 ZyXEL, however, does not allow you to select a /31 mask at all.
 As a result, there are additional limitations in network operation — from using equipment of different manufacturers to even using equipment from the same vendor but with different firmware versions.
-
 If you are not concerned by the above limitations, you can confidently save addresses by using the /31 prefix.
 
 The use of the /31 prefix is described in detail in RFC 3021 — Using 31-Bit Prefixes on IPv4 Point-to-Point Links.
+
+
+## Special IPv4 Ranges and Cases
+
+### Special Network Types
+
+- **/31 networks**: Show `2*` in Hosts field - both addresses are usable (RFC 3021)
+- **/32 networks**: Show `1*` in Hosts field - single host network
+- The asterisk (*) indicates special network types where all addresses are usable
+
+### Special IPv4 Address Ranges
+
+LanCalc automatically detects and handles special IPv4 address ranges according to RFC specifications. For these ranges, host-related fields show "*" and a message field indicates the range type with RFC reference.
+
+#### Supported Special Ranges
+
+| Range | Type | RFC | Description |
+|-------|------|-----|-------------|
+| **127.0.0.0/8** | Loopback | [RFC 3330](docs/RFC.md#rfc-3330---loopback-addresses) | Loopback addresses - not routable on the Internet |
+| **169.254.0.0/16** | Link-local | [RFC 3927](docs/RFC.md#rfc-3927---link-local-addresses) | Link-local addresses - not routable |
+| **224.0.0.0/4** | Multicast | [RFC 5771](docs/RFC.md#rfc-5771---multicast-addresses) | Multicast addresses - not for host addressing |
+| **0.0.0.0/8** | Unspecified | [RFC 1122](docs/RFC.md#rfc-1122---unspecified-addresses) | Unspecified addresses - not for host addressing |
+| **255.255.255.255/32** | Broadcast | [RFC 919](docs/RFC.md#rfc-919---broadcast-address) | Limited broadcast address - not for host addressing |
+
+#### Special Range Behavior
+
+When you enter an address from a special range:
+
+**CLI Text Mode:**
+```bash
+lancalc 127.0.0.1/8
+```
+```
+Network: 127.0.0.0
+Prefix: /8
+Netmask: 255.0.0.0
+Broadcast: *
+Hostmin: 127.0.0.1
+Hostmax: 127.255.255.254
+Hosts: 16777214
+Comment: RFC 3330 Loopback (https://github.com/lancalc/lancalc/blob/main/docs/RFC.md#rfc-3330---loopback-addresses)
+```
+
+**CLI JSON Mode:**
+```bash
+lancalc 224.0.0.1/4 --json
+```
+```json
+{
+  "network": "224.0.0.0",
+  "prefix": "/4",
+  "netmask": "240.0.0.0",
+  "broadcast": "*",
+  "hostmin": "*",
+  "hostmax": "*",
+  "hosts": "*",
+  "comment": "RFC 5771 Multicast (https://github.com/lancalc/lancalc/blob/main/docs/RFC.md#rfc-5771---multicast-addresses)"
+}
+```
+
+**GUI Mode:**
+- Host fields (Hostmin, Hostmax, Broadcast, Hosts) show "*"
+- Status bar displays the special range message instead of version
+- No special styling or warnings needed
+
+#### JSON Fields
+
+The JSON output includes the following fields:
+
+- **`comment`**: Description and RFC reference for special ranges (empty for normal unicast addresses)
+- **`comment`**: Description and RFC reference for special ranges (empty for normal unicast addresses)
+- **`hosts`**: Number of available host addresses in the specified subnet
+
+These fields are always present, making the JSON output format consistent regardless of address type.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -0,0 +1,26 @@
+# CHANGELOG
+
+All notable changes to LanCalc will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.8] - 2024-12-19
+
+### Added
+- Special IPv4 network detection and handling (loopback, link-local, multicast, unspecified, broadcast)
+- Comprehensive tests for special network ranges and edge cases
+- RFC documentation links for special networks
+
+### Changed
+- Renamed output keys changed in JSON output (network, prefix, netmask, broadcast, hostmin, hostmax, hosts, comment)
+- Refactored tests classes to top-level functions
+
+### Fixed
+- JSON output filtering: empty comment fields omitted when using -j flag
+- Documentation examples updated to match actual API output
+
+### Technical
+- Improved test organization and maintainability
+- Enhanced GUI error handling with red status for invalid addresses
+- Simplified special range display logic
diff --git a/docs/RFC.md b/docs/RFC.md
@@ -0,0 +1,182 @@
+# RFC Documentation for Special IPv4 Address Ranges
+
+This document describes the special IPv4 address ranges that LanCalc automatically detects and handles according to RFC specifications.
+
+## Table of Contents
+
+- [RFC 3330 - Loopback Addresses](#rfc-3330---loopback-addresses)
+- [RFC 3927 - Link-Local Addresses](#rfc-3927---link-local-addresses)
+- [RFC 5771 - Multicast Addresses](#rfc-5771---multicast-addresses)
+- [RFC 1122 - Unspecified Addresses](#rfc-1122---unspecified-addresses)
+- [RFC 919 - Broadcast Address](#rfc-919---broadcast-address)
+
+---
+
+## RFC 3330 - Loopback Addresses
+
+### Official IETF Document
+
+[RFC 3330 - Special-Use IPv4 Addresses](https://tools.ietf.org/html/rfc3330)
+
+### Description
+
+The loopback address range 127.0.0.0/8 is reserved for communication within the same host. These addresses are not routable on the Internet and are used for internal host-to-host communication, typically for testing and diagnostics.
+
+### Example CLI Output
+
+```bash
+$ lancalc 127.0.0.1/8 --json
+{
+  "network": "127.0.0.0",
+  "prefix": "/8",
+  "netmask": "255.0.0.0",
+  "broadcast": "*",
+  "hostmin": "127.0.0.1",
+  "hostmax": "127.255.255.254",
+  "hosts": "16777214",
+  "comment": "RFC 3330 Loopback (https://github.com/lancalc/lancalc/blob/main/docs/RFC.md#rfc-3330---loopback-addresses)"
+}
+```
+
+### Notes
+
+- Loopback addresses show actual host range calculations for subnet analysis
+- The entire 127.0.0.0/8 range is reserved, not just 127.0.0.1
+- Commonly used for localhost communication and application testing
+
+
+---
+
+## RFC 3927 - Link-Local Addresses
+
+### Official IETF Document
+
+[RFC 3927 - Dynamic Configuration of IPv4 Link-Local Addresses](https://tools.ietf.org/html/rfc3927)
+
+### Description
+
+The link-local address range 169.254.0.0/16 is used for automatic IP address configuration when no DHCP server is available. These addresses are not routable beyond the local network segment and are typically assigned automatically by the operating system.
+
+### Example CLI Output
+
+```bash
+$ lancalc 169.254.1.1/16 --json
+{
+  "network": "169.254.0.0",
+  "prefix": "/16",
+  "netmask": "255.255.0.0",
+  "broadcast": "*",
+  "hostmin": "*",
+  "hostmax": "*",
+  "hosts": "*",
+  "comment": "RFC 3927 Link-local (https://github.com/lancalc/lancalc/blob/main/docs/RFC.md#rfc-3927---link-local-addresses)"
+}
+```
+
+### Notes
+
+- Host-related fields show "*" because link-local addresses have special automatic assignment behavior
+- Commonly seen on Windows systems when DHCP fails (APIPA - Automatic Private IP Addressing)
+- Used for local communication only, not routable through gateways
+
+---
+
+## RFC 5771 - Multicast Addresses
+
+### Official IETF Document
+
+[RFC 5771 - IANA Guidelines for IPv4 Multicast Address Assignments](https://tools.ietf.org/html/rfc5771)
+
+### Description
+
+The multicast address range 224.0.0.0/4 (224.0.0.0 - 239.255.255.255) is reserved for IP multicast communication. These addresses are used to send data to multiple hosts simultaneously and are not intended for traditional unicast host addressing.
+
+### Example CLI Output
+
+```bash
+$ lancalc 224.0.0.1/4 --json
+{
+  "network": "224.0.0.0",
+  "prefix": "/4",
+  "netmask": "240.0.0.0",
+  "broadcast": "*",
+  "hostmin": "*",
+  "hostmax": "*",
+  "hosts": "*",
+  "comment": "RFC 5771 Multicast (https://github.com/lancalc/lancalc/blob/main/docs/RFC.md#rfc-5771---multicast-addresses)"
+}
+```
+
+### Notes
+
+- Host-related fields show "*" because multicast addresses are not used for individual host identification
+- Used for protocols like IGMP, streaming media, and group communication
+- Different from broadcast as they require explicit group membership
+
+---
+
+## RFC 1122 - Unspecified Addresses
+
+### Official IETF Document
+
+[RFC 1122 - Requirements for Internet Hosts -- Communication Layers](https://tools.ietf.org/html/rfc1122)
+
+### Description
+
+The unspecified address range 0.0.0.0/8 contains addresses that have special meaning in network protocols. The address 0.0.0.0 is used to indicate "this host on this network" and should not be used for regular host addressing. Note that 0.0.0.0/0 (the default route) is treated as normal unicast.
+
+### Example CLI Output
+
+```bash
+$ lancalc 0.0.0.1/8 --json
+{
+  "network": "0.0.0.0",
+  "prefix": "/8",
+  "netmask": "255.0.0.0",
+  "broadcast": "*",
+  "hostmin": "*",
+  "hostmax": "*",
+  "hosts": "*",
+  "comment": "RFC 1122 Unspecified (https://github.com/lancalc/lancalc/blob/main/docs/RFC.md#rfc-1122---unspecified-addresses)"
+}
+```
+
+### Notes
+
+- Host-related fields show "*" because these addresses have special protocol meanings
+- 0.0.0.0 is used in DHCP and routing protocols to indicate "this network"
+- The default route 0.0.0.0/0 is treated as normal unicast, not unspecified
+
+---
+
+## RFC 919 - Broadcast Address
+
+### Official IETF Document
+
+[RFC 919 - Broadcasting Internet Datagrams](https://tools.ietf.org/html/rfc919)
+
+### Description
+
+The limited broadcast address 255.255.255.255 is used to send packets to all hosts on the local network segment. This address is never forwarded by routers and is used for network-wide announcements and discovery protocols.
+
+### Example CLI Output
+
+```bash
+$ lancalc 255.255.255.255/32 --json
+{
+  "network": "255.255.255.255",
+  "prefix": "/32",
+  "netmask": "255.255.255.255",
+  "broadcast": "*",
+  "hostmin": "*",
+  "hostmax": "*",
+  "hosts": "*",
+  "comment": "RFC 919 Broadcast (https://github.com/lancalc/lancalc/blob/main/docs/RFC.md#rfc-919---broadcast-address)"
+}
+```
+
+### Notes
+
+- Host-related fields show "*" because the broadcast address is not used for individual host addressing
+- Different from directed broadcast (network broadcast address) as this is the limited broadcast
+- Used by protocols like DHCP, ARP, and Wake-on-LAN
diff --git a/lancalc/__init__.py b/lancalc/__init__.py
@@ -5,10 +5,16 @@
 LanCalc - A desktop application for calculating network configurations
 """
 
-__version__ = '0.1.7'
+__version__ = '0.1.8'
 __author__ = 'Aleksandr Pimenov'
 __email__ = 'wachawo@gmail.com'
 
-from .main import main, LanCalc
+from .main import main
 
-__all__ = ['main', 'LanCalc', '__version__']
+# Try to import LanCalc only if GUI is available
+try:
+    from .main import LanCalc  # noqa: F401
+    __all__ = ['main', 'LanCalc', '__version__']
+except ImportError:
+    # GUI not available, only export main function
+    __all__ = ['main', '__version__']
diff --git a/lancalc/main.py b/lancalc/main.py
diff --git a/test_lancalc.py b/test_lancalc.py
