Requirements for IP address and port APIs

Development Networking
13

Following yesterday's work group meeting, here are my thoughts:

macOS version Requirements

InlineArray or UInt_ as the underlying storage?

  • As mentioned, we don't need to expose the underlying storage of the IP types.
    • If we can't easily come to a conclusion, we can postpone the decision to when the other parts of the library are clear, so we have an easier type making a decision.
    • Currently this is the case. We expose the storage via ip.address which would yield UInt32/UInt128.
      • However, this is not "unfixable" in a future version, even if we commit to just simply exposing the underlying storage.
      • In Swift you can simply replace the var address: UInt_ (stored storage/property) with var address: UInt_ { get { /*get from new storage*/ } set { /*set in the new storage*/ } } and it would be pretty fine.
      • Since we already know this can be an issue, I'd say we can plan to not having to expose the underlying storage so in the future we don't need to work around it at all.
      • Instead, I'll likely experiment with protocol IP[v4/v6]AddressConvertible then we can have functions such as myIP.as(UInt_.self) /*returns UInt_*/ where UInt_ conforms to IP[v4/v6]AddressConvertible. Or perhaps just with simple asUInt_() and asInlineArray() funcs. I'll have to see.

What macOS version then to require?

I realize not every single library will have to have the same availability, specifically to be able to be used in swift-nio or such.

A library like swift-endpoint will need to be available on macOS 12 so it can possibly replace swift-nio's SocketAddress guts whenever Swift 6.6 comes out (swift-nio supports 3 minor versions back, so at 6.6, it can drop support for 6.3 which defaults to macOS 10.13, which would be incompatible with swift-endpoint or any library primarily built on Spans).

For other networking libraries, we can also decide on a 1-by-1 basis based on what is available and what is not. I'd say requiring macOS 13 should be the default as that comes with Clock/Duration types. See [Networking Workgroup] Public meeting — Monday, August 3, 2026 — Agenda and call for topics - #3 by MahdiBM for more info.

What about DomainName?

swift-endpoint implements DomainName and "DomainName+IP Integration" in 2 extra separate modules. This means that they are both completely deduplicated and DomainName can somewhat easily be moved to another package or such, if needs be.

However, that needs answering a question.
What is the point of having IP address and port APIs? How much modularity we want to have?
Basically, what should be the scope of APIs that should be included in the same package as the one containing these IP address / Port APIs?

If the answer to these questions is too hard, we could simply go the safer route, which is to say to spread the implementation across multiple repos. Meaning DomainName ends up in its own repo (alongside its swift-idna dependency), then a possible third repo for ConnectionTarget which is an enum of where to connect to, which needs DomainName so users can name a domain for resolution (this is what other scattered types also contain right now).

The choices are basically:

IP address + DomainName + idna dependencies + Port/CIDR + "ConnectionTarget" in 1 package
vs IP address + Port/CIDR in 1, DomainName + idna dependencies in another, and "ConnectionTarget" in a third.

Having them in different repos does add overheard but it could be acceptable.

Little endian / big endian issues?

I'll try to experiment and see if we can find some kind of clear way of making sure users can choose any endianness on demand perhaps? For example via endianness function arguments? I'll have to see.

I think this is only a negligible performance issue, and that's not what I'd be looking solve with this experiment, as I don't see it as a big issue.
myInt.bigEndian which is currently required, should ultimately compile down to 1 instruction, which has a reasonable throughput on most systems and takes 1 cycle, sometimes 2 depending on the CPU. withUnsafeByte(of:) function should also do almost no work if any, other than acting as an interface to access the underlying bytes. One could confirm via godbolt (or via swiftc -O -emit-assembly $my_file) if needs be; I haven't tried.