Requirements for IP address and port APIs

[camunro (Craig Munro)]

Thanks @MahdiBM for the long prior-art survey and the draft API shape. Cross-language inventories are useful. They do not, by themselves, define the requirements boundary for a Swift currency surface that claims to support classless addressing.

I want to pin a few definitional points so the workgroup does not settle on the lowest common denominator of host-stack APIs and call that “CIDR.”

1. What CIDR means (again), and what that forces in the type system

Internet networking, at Layer 3, is built on routing currency: prefixes.
Without a first-class canonical network / prefix value—call it IPNetwork, IPv4Prefix, or YANG’s ip-prefix—there is no shared way to name what is assigned, aggregated, filtered, or installed. Host addresses and ports matter enormously for endpoints; they do not replace prefix-shaped currency. That is not a niche ops preference. It is how the Internet is structured.

I have already put the CIDR definition on this thread; restating it again so the workgroup keeps one load-bearing why for any “CIDR-compliant” or classless story:

@camunro

This is where the full meaning of CIDR matters.

RFC 4632 is not merely a specification for parsing text containing a slash. Its title is Classless Inter-domain Routing: The Internet Address Assignment and Aggregation Plan:

• Classless means that a network boundary is represented by an explicit prefix length rather than inferred from the former IPv4 Class A/B/C divisions. For IPv4, this is the variable-length prefix model associated with VLSM. IPv6 was designed around prefixes from the outset: its routing architecture supports prefix lengths from /0 through /128, although /64 is conventional for subnets using SLAAC. In both families, prefixes provide boundaries for routing and aggregation.
• Inter-domain places these values in the context of independently administered networks, commonly Autonomous Systems, with different operational and policy boundaries.
• Routing makes prefixes and their aggregation Layer 3 control-plane concepts, not merely presentation formats for host addresses.

The native unit of that plan is prefix-shaped address space: a canonical network / prefix (host bits cleared for identity). That is the unit of assignment and aggregation under CIDR. It is required currency for any design that claims classless / CIDR grounding.

So:

Any design that claims CIDR compliance must treat a first-class canonical network/prefix type as required currency—not as an afterthought, not as “maybe later,” and not as something you only get by calling .networkAddress on a host-shaped hybrid.

That is compatible with progressive disclosure (many apps start at address + port). Progressive disclosure must not erase the plan’s native unit—or we design a “networking” surface that cannot name a route.

2. RFC 9911 as vocabulary ally—not the foundational “why”

RFC 9911 YANG types are useful labels for interchange. They do not replace the architectural grounding of RFC 4632 (and IPv6 prefix construction in RFC 4291). YANG describes how modules name strings; CIDR explains why prefix-shaped currency exists.

Used properly:

Grounding	Role
RFC 4632 / classless plan	Why canonical prefixes exist (assignment, aggregation, inter-domain routing math)
RFC 9911 ip-prefix	Same form as a canonical network type (IPNetwork / family-specific prefix)—host bits not part of identity in canonical form
RFC 9911 ip-address-and-prefix	Different form: address + associated length (host bits may matter)—interface/config-shaped

So: YANG ip-prefix ≈ the IPNetwork / canonical network currency we need.
YANG ip-address-and-prefix ≈ address-with-prefix-context—necessary, not a substitute for ip-prefix.

Your table already states that 192.168.1.98/24 is not a canonical ip-prefix. That is correct.

What must not happen next is the reverse error: elevating ip-address-and-prefix as the primary public model because it is “lossless” and “just works” for a general audience, while ip-prefix / network currency remains second-class or optional.

For control-plane and Internet-scale use (RIB keys, IRR route/route6, RPKI ROA base prefixes, many filters, aggregation):

• 192.168.1.98/24 is not a valid canonical network value.
• Accepting host bits on input is fine only if the result is an explicit, lossy projection to another type—the canonical network/prefix type (e.g. address-with-context → IPNetwork / ip-prefix representing 192.168.1.0/24 as a value, not a string round-trip)—or the network type strictly rejects non-canonical input.
• Equality and hashing of network currency must respect form—no silent host-bit identity, no silent drop without a named typed projection.

That list is not arbitrary product vocabulary. It is the everyday object set of Internet operations and control-plane protocols. A standards-grounded currency surface should be checked against the RFCs and registries those systems cite—not only against host std::net-style inventories. Filter and policy practice (prefix-lists, more-specifics, vendor ACL/prefix objects) is where operators learn that canonical prefix identity is non-negotiable; that experience is hard to extract from a language survey alone.

Naming IPv4AddressAndPrefix / IPv6AddressAndPrefix can track YANG for the context form, but that naming obfuscates the main point if it becomes the centerpiece of the proposal while the required ip-prefix / IPNetwork form stays secondary or optional. Context form is real; network form is not optional.

3. “The library should not concern itself with routing” is backwards for prefix currency

The proposal suggests (paraphrasing) that CIDR is a poor name because the library would “likely want to not concern itself with routing.”

Networking currency is routing-shaped at Layer 3. The library need not implement BGP, OSPF, or a RIB. It must provide the prefix/network values those systems exchange—or every higher library invents incompatible ones. I made the same requirements point earlier; it still holds:

@camunro

If the standard model stops at individual addresses and ports, every routing, firewall, IPAM, policy, and infrastructure library will still need to invent its own incompatible representation of networks and prefixes. That would solve endpoint interoperability while leaving the network-infrastructure problem unresolved.

Classless addressing is not a “core-only” specialty. The same plan and math run from core to edge—backbone and IX policy, enterprise routing and ACLs, host and interface configuration, automation and diagnostics. When that is taken seriously, several currency types fall out naturally; they are not a grab bag of extras. I sketched that direction last May:

@camunro

For many applications, an address is the obvious primitive. But in routing, ACLs, interface configuration, RPKI validation, IPAM, DNS operations, peer configuration, summarization, diagnostics, multicast handling, and network automation, the unit of work is often not just “an address”. It is frequently an address with prefix context, a canonical network prefix, a delegated block, or a neutral CIDR range.

A useful IP currency model for those domains likely needs concepts along these lines:

AddressFamily
IPAddress<Family>
PrefixLength<Family>
IPNetwork<Family>
CIDRBlock<Family>
IPMulticastGroup<Family>

That list is progressive—not “ship everything on day one”—but it is also coherent: once canonical network currency exists, length, address-with-context, blocks, and multicast stop looking like unrelated niches and start looking like one architecture.

Currency types are not a full control plane. They are the shared numbers and forms the control plane and host stack use. A surface that only optimizes sockets while treating canonical prefixes as optional is not a complete foundation for Internet software—on server or on end hosts that still speak the same address architecture.

4. Prior-art survey ≠ requirements minimum

A survey of std::net, POSIX, Go netip, etc. correctly shows many ecosystems ship a host-shaped core (address, sometimes port, sometimes a single prefix-ish type).

That is the status quo of host APIs. It is not automatically the right ceiling for Swift if the workgroup also cares about:

• multiplatform Server-Side Swift infrastructure,
• control-plane and policy consumers,
• and not forcing every IRR/RPKI/IPAM tool to invent incompatible network types.

“Other languages don’t have X” is useful data. It is not a proof that X is out of scope when Internet standards and operational practice use X daily.

5. Progressive disclosure of forms (requirements-oriented type list)

Without arguing for any one package, here is a disclosure-ordered currency surface the workgroup can reason about. Day-one apps need only the top rows; infrastructure needs the middle; library authors need the bottom.

Host / common path

1. IPv4Address / IPv6Address (and mixed-family boundary if needed)
2. Port
3. Endpoint composition (IP + port; scope/zone as host/context—later)

Classless math (required for any honest “CIDR” claim)

4. PrefixLength (family-valid length currency—not only a field on one struct)
5. Canonical network / prefix (IPNetwork / ip-prefix form)—required
6. Address-with-prefix-context (ip-address-and-prefix form)—required as a distinct form, not as a substitute for (5)
7. Explicit lossy projection to another type: address-with-context → canonical network (value types, not strings)

Infrastructure depth (progressive, not day-one for every app)

8. Neutral allocation-shaped blocks (set math without “LAN gateway” ceremony)
9. Prefix selectors / length ranges (RPSL-style more-specifics; related to ROA maxLength ideas)
10. Multicast group and group-range identity (not unicast subnet semantics)
11. Autonomous System number as numeric currency (with routes, ROAs, IRR—not BGP-only)
12. Mixed-family collections at API boundaries

Protocols (later disclosure for generic algorithms)

13. Shared structure for “storage + length” across forms (protocol, not one hybrid value type)
14. Aligned-prefix operations (containment, subnets, summarize) as a refinement for network forms

This is the same spirit as progressive disclosure the NWG has discussed: start small, but do not design the small surface so the large surface is impossible.

Working CLI tools already exercise several of these forms in real workflows (IRR origin → canonical networks, coverage/merge of prefix sets, admission-style checks, walks). Those are good acceptance scenarios for any proposed currency library—independent of branding.

Context inventory (where the same slash string is not the same form):

Requirements for IP address and port APIs

The requirements discussion so far is strong on host-facing needs (string parse, scope, classification predicates, client stacks). I want to add one framing requirement: that scope is only part of the job. The thread’s property and “subnet/CIDR” discussion is mostly host and interface thinking. Prefix and address values show up far wider, and this is where a single CIDR-style wrapper around an address usually falls short. Concise inventory: Host / link Interface address assignment Link-local…

6. Specific gaps / mis-scopes in the proposal

PrefixLength “undecided.”
Please treat length currency as required, not optional. Family bounds (0…32 / 0…128) matter. Length also appears as a standalone control-plane field—for example ROA maxLength in RFC 9582—not only glued to a host address. That point has been discussed on the Forums and in more detail on the networking Slack storage/math walkthrough. Ignoring length-as-currency is ignoring a real control-plane requirement.

Multicast.
Unicast “network” ceremony is the wrong model for multicast group destinations and ranges. If the surface only thinks in hybrid CIDR + socket address, multicast identity is easy to mishandle. A progressive path should at least reserve group / range forms (or explicitly defer them without pretending unicast types cover them).

NAT64.
Agree it need not live in the core IP+port package. Clarify taxonomy: NAT64 is address translation / transition, not a routing protocol. Scoping it “to routing” confuses categories. Translation helpers can live elsewhere; they should not drive the prefix form model.

Domain / hostname.
Agree with pulling DNS/IDN out of the early IP+port currency deliverable. Domain names are a separate system. Progressive disclosure: address + port first; name resolution beside or above—not inside—the currency core.

Socket-shaped expansion.
UnixDomainSocketAddress, rich *SocketAddress with flow-info, etc., may be valuable adapter / host types. They should not crowd out or delay canonical network/prefix currency. The workgroup’s networking vision has been moving toward clearer layering (currency and composition vs historical socket bags)—not toward recreating sockaddr as the only ontology.

Storage / InlineArray.
Representation experiments (hide storage, expose withSpan / byte views) are fine after the domain model is fixed. They do not replace the integer bit-string + length story for classless math. Detail remains on Slack for those who want the full walkthrough; the requirements point is domain-led, not feature-led.

7. What I am asking the workgroup to treat as non-negotiable

1. Internet L3 currency includes canonical prefixes. Without ip-prefix / IPNetwork (or equivalent), there is no shared name for what is assigned, aggregated, or installed.
2. Ground the “why” in RFC 4632 (and RFC 4291 for IPv6 construction); use RFC 9911 as vocabulary (ip-prefix ≈ network, ip-address-and-prefix ≈ address+context)—not as a substitute for the plan.
3. Two forms, both first-class, with explicit lossy projection; equality/hashing respect form.
4. PrefixLength (or equivalent) as currency, including standalone control-plane uses (e.g. ROA maxLength).
5. Progressive disclosure that starts at address/port without deleting infrastructure forms.
6. Prior-art LCD is not the requirements ceiling for Server-Side Swift + multiplatform currency.
7. DNS, NAT64 translation, and full socket ceremony are adjacent scopes—not substitutes for prefix math.

I appreciate the survey effort. I will keep pushing on definitions and forms, because getting those wrong is far more expensive than adding a type later.

Happy to iterate on naming (IPNetwork vs IPv4Prefix vs YANG-style names) once the NWG firms direction on the requirements above—as shared workgroup requirements, not as optional package preferences.