IpAddressString scalar should accept CIDR notation for PostgreSQL INET compatibility

[evoludigit]

Context

FraiseQL provides tight Python/PostgreSQL integration. PostgreSQL has native INET and CIDR types that store IP addresses with optional prefix length (e.g., 192.168.1.1/24).

Problem

The IpAddressString scalar currently rejects CIDR notation:

# Current implementation in parse_ip_address_value()
return ip_address(value)  # ip_address() doesn't accept "192.168.1.1/24"

When GraphQL receives:

mutation {
  updateNetworkConfig(ipAddress: "192.168.1.1/24") { ... }
}

It fails with:

Variable '$ipAddress' got invalid value '192.168.1.1/24'; 
Invalid IP address string: '192.168.1.1/24'

PostgreSQL Context

When data is stored as PostgreSQL INET/CIDR:

CREATE TABLE network_config (
  ip_address_cidr INET  -- Stores "192.168.1.1/24"
);

Views can expose both representations:

CREATE VIEW v_network_config AS
SELECT
  host(ip_address_cidr) AS ip_address,    -- "192.168.1.1"
  netmask(ip_address_cidr) AS subnet_mask -- "255.255.255.0"
FROM network_config;

Proposed Solution

Make IpAddressString accept CIDR notation using ip_interface():

def parse_ip_address_value(value: Any) -> IPv4Address | IPv6Address:
    if isinstance(value, str):
        try:
            # Accept both "192.168.1.1" and "192.168.1.1/24"
            interface = ip_interface(value)
            return interface.ip  # Extract just the IP part
        except ValueError as e:
            msg = f"Invalid IP address string: {value!r}"
            raise GraphQLError(msg) from e

This maintains backward compatibility (plain IPs still work) while supporting CIDR input for PostgreSQL INET compatibility.

Use Case

Network configuration APIs commonly accept CIDR notation. Users can input:

• 192.168.1.1/24 (CIDR) → parsed to IP + subnet
• 192.168.1.1 (plain) → still works

This aligns with PostgreSQL's native INET type behavior and reduces API friction.

Files

• Implementation: src/fraiseql/types/scalars/ip_address.py:50-59
• Tests: tests/unit/core/type_system/test_ip_address_scalar.py

[evoludigit]

✅ Fixed in Latest Commit

The IpAddressString scalar now accepts CIDR notation! The implementation has been updated to use ip_interface() instead of ip_address(), which extracts just the IP address from CIDR input.

Changes Made

File: src/fraiseql/types/scalars/ip_address.py

• Updated parse_ip_address_value() to accept both formats:
  • "192.168.1.1" → returns 192.168.1.1 (backward compatible)
  • "192.168.1.1/24" → extracts and returns 192.168.1.1 (new)
  • "2001:db8::1/64" → extracts and returns 2001:db8::1 (new)

Tests Added:

• IPv4 with CIDR notation parsing
• IPv6 with CIDR notation parsing
• GraphQL literal parsing with CIDR

All tests pass ✅

PostgreSQL INET Use Case - Best Practices

For frontend forms that store CIDR in PostgreSQL INET columns, here are recommended input type patterns:

Option A: Mutually Exclusive Fields (Recommended)

from fraiseql import UNSET
from fraiseql.types import IpAddress, SubnetMask, CIDR

@fraise_input
class NetworkConfigInput:
    # Pattern 1: Traditional IP + Subnet Mask
    ip_address: IpAddress | None = UNSET          # "192.168.1.1"
    subnet_mask: SubnetMask | None = UNSET        # "255.255.255.0"
    
    # Pattern 2: CIDR notation
    ip_address_cidr: CIDR | None = UNSET          # "192.168.1.0/24"

Resolver validation:

@mutation
async def create_network_config(input: NetworkConfigInput) -> NetworkConfigResult:
    # Validate exactly one pattern is provided
    has_ip_subnet = (input.ip_address is not UNSET and input.subnet_mask is not UNSET)
    has_cidr = input.ip_address_cidr is not UNSET
    
    if not (has_ip_subnet ^ has_cidr):  # XOR
        raise ValidationError("Provide either (ip_address + subnet_mask) OR ip_address_cidr")
    
    # Convert to CIDR for PostgreSQL INET
    if has_ip_subnet:
        from ipaddress import IPv4Network
        network = IPv4Network(f"{input.ip_address}/{input.subnet_mask}", strict=False)
        cidr = str(network)
    else:
        cidr = input.ip_address_cidr
    
    # Store cidr in PostgreSQL INET column...

Frontend UX:

• Radio buttons: "Single IP + Subnet Mask" vs "CIDR Notation"
• Clear separation for technical vs. non-technical users

Option B: Single CIDR Field (Simplest)

@fraise_input
class NetworkConfigInput:
    network_cidr: CIDR  # Always require CIDR format

Frontend appends /32 if user only enters an IP address.

Future: @oneOf Directive

GraphQL's @oneOf directive would be perfect for mutually exclusive fields, but it's not yet available:

• Current status: Not supported in graphql-core 3.2.6 (tracking issue #219)
• Future: When available, FraiseQL can add native @fraise_one_of_input decorator

For now, manual XOR validation in resolvers (as shown above) is the recommended approach.

Summary

✅ Issue resolved: IpAddressString now accepts CIDR notation
✅ Backward compatible: Plain IPs still work
✅ PostgreSQL INET ready: Supports all use cases
✅ Production-ready: Fully tested with comprehensive test coverage

Let me know if you need any clarification or have additional use cases to discuss!