Canonical form for IP addresses

[tegefaulkes]

Specification

There are multiple ways to represent IP addresses. IPv4 specifically has 3 ways, IPv6 mapped form ::ffff:127.0.0.1, normal form, 127.0.0.1 and the hex form ::ffff:7f00:1. Theses 3 forms represent the same IPv4 address.

If we need to store this address in the database we can't use all 3 representations although they are equivalent. We need a canonical form for storing and manipulating the address.

To this end we need to create a helper class that stores the address as the canonical form, we can use the raw byte form representing an A address for IPv4 and an AAAA address for IPv6. Theses are 4 and 16 bytes respectively.

From the canonical byte form we can map the address to all supported formats.

Additional context

• Related Create QUIC library that can be exposed to JS and uses the Node dgram module #1

Tasks

1. Create a canonical format for IP addresses for comparing and storing in a database.
2. Create mapping functions for converting between formats using the canonical form as the in-between.

[tegefaulkes]

As far as implementation for this goes. I'm thinking we have a Host class that extends a Uint8Array and a formatting transform methods to it.

The host address will be stored in the raw byte form, IPv4 will be 4 bytes while IPv6 is 16. From here we can map to and from the following formats. IPv4, IPv6 mapped IPv4, IPv6 and there was a hex format for IPv4 I think? Each of these formats will have a from and to method for them.

We can call this CanonicalHost?

[CMCDragonkai]

I thought the ip-num library we are using already have classes for this.

I want to maintain a distinction between Host and Hostname. And the types should be kept simple.

This is because downstream systems will take only strings. And we need these opaque types to classify the different strings. Any class used for advanced operations is more of a transformer to and from these different forms.

[CMCDragonkai]

Honestly I prefer mapping functions. Do not use classes or objects here. It will get confusing when doing serialisation or deserialisation.

[tegefaulkes]

For IPv4 and IPv6 mapped IPv4 the canonical form will be the IPv4 dot decimal format. Comparisons should be done in this decimal format. For IPv4 the only format is the IPv6 hex format, IPv6 should be stored in that format.

As for the conversion methods we need ones for

1. generic helper all -> canonical
2. mapped hex -> IPv4 dec
3. mapped dec -> IPv4 dec
4. IPv4 dec -> mapped hex
5. IPv4 dec -> mapped dec

[tegefaulkes]

I've expanded the transforms. Mostly added ipv4 -> ipv6 mapped hex and dec form, and isX checkers for the IPv6 mapped hex and dec form.

I also added a function that transforms all formats to the canonical format. It's pretty simple in that it converts all the mapped forms to IPv4 dec, and all normal IPv6 and IPv4 are left unchanged

I've updated the tests with the changes, adding new tests where needed,

I don't know if this fully covers this issue so I haven't resolved it yet. Let me know if I'm missing anything or mis-interpreted something. @CMCDragonkai

[tegefaulkes]

I'm going to merge the changes and resolve this. Anything more should be addressed in polykey with respect to the node graph. I'll make a new issue in Polykey repo for this?

[CMCDragonkai]

These functions may be more useful in PK than in js-quic. It all depends on integration. Which is why we must start now in order to iron out any problems.