Endpoints and Endpoint Identifiers. Closes #1278.

[mwelzl]

Closes #1278.

Please take a close look even though it's long and painful; this isn't actually trivial.

For example: multipath protocols deal with adding or removing addresses, which are Endpoint Identifiers. However, the API specifies an "Endpoint", not an "Endpoint Identifier", because the Endpoint can be represented in various ways (IP address, name, ... - these things are "Endpoint Identifiers"). So, in the API, the text about adding or removing endpoints should indeed talk about endpoints (and it does!), not endpoint identifiers.

Then again, all the racing stuff in the implementation draft is really about Endpoint Identifiers, right?

See... not trivial.

NOTE: the changes to -arch are just capitalization.

[philsbln]

Before giving a review here, let's make sure that we are on the same page with definitions and don't mess up the terminology:

1. An Endpoint is an Object representing a thingy I want to talk to (ignoring whether this is just one IoT-device, a container on a single host or a CND tenant hosting some content)
2. An Endpoint Identifier is a hostname or address representing that Endpoint in order to initiate a communication.
3. There is not such a thing as "adding endpoints" to a connection … I can just add additional identifiers
4. When Multi-path protocols add addresses internally, they are actually adding alternative means to reach same endpoint that might or might not be usable as an endpoint identifier, but adding them through the API is identical to adding an additional identifier for the same endpoint (sic!).
5. Racing is not about endpoint identifiers, but about candidates instances of the same Endpoint where each endpoint identifier may actually represent several instances of that endpoint. In the end, typically one of these instances will be chosen.

So that means candidate instance of an Endpoint != Endpoint?

[mwelzl]

Thanks @philsbln ! I changed your item list into a numbered list so it's easier to talk about.

I agree with items 1 (but I think that this definition needs to be broader) and 2.

Item 3 is already where things become complicated... at first, when doing this update, I changed "NewRemoteEndpoint" to "NewRemoteEndPointIdentifier" etc. etc. ... but then I realized, the identifier is: a name+port, or an IPv4 address + port, or an IPv6 address + port... so, in a sense, with the way we use "EndPoint" in the API it's a slightly more abstract thing.

So, I think, the way we've been using it, an "endpoint" is really: a) what you say in item 1 (a "thingy" that we talk to), but also b) a representation of that thing in our interface (just a tiny bit more abstract than an address).

Let's see if we agree about this first, or if this should change.

[philsbln]

Hi @mwelzl,

I agree with your assessment so far.

In my opinion, based on a stringent, terminology, NewRemoteEndpoint() creates an Endpoint Identifier. Now comes the trade-off between a stringent terminology and a usable API – no one likes Java-Style MyFooWindowDecoratorAdpterProxy like names).

Therefore I think it is justifiable to call the Endpoint Identifier Object just "Endpoint" as the real Endpoint is an abstract thingy somewhat within the Preconnection/Connection.

Is it fine ti review based on that?

[gorryfair]

How about EndpointID ... that is not much longer than Endpoint?

[philsbln]

@gorryfair In principle 👍🏻 but I fear most developers associate ID with something uniq / that has a bijective association which isn't true for the Endpoint Identifier

[mwelzl]

@philsbln it seems we agree... yes, reviewing with this as a basis would be fine, thanks!

Just for clarification, with the understanding that we agree that an "Endpoint" can either be a thing that we talk to, or really what should probably be called the "Endpoint Identifier Object", regarding the other points above:

3. no, we add "Endpoints".
4. multipath protocols also add "Endpoints", which can be specified by various types of Endpoint Identifiers (e.g., an IPv4 address or a name),
5. racing is another tricky thing in this context.... of course, when we talk about sending packets to an "Endpoint", we send them to the "thingy", not the address, but most of the text on racing in the implementation draft is about building tables and how to sort them... where, really, the tables have to contain something quite concrete: Endpoint Identifiers! So I changed many of these occurrences into "Endpoint Identifier".

[philsbln]

So for 5) … would not be "Endpoints Candidate" the better term here?

[mwelzl]

I don't know... it adds another term? E.g., just to take an example from the text:

Aggregate [Endpoint Identifier: www.example.com:80] [Interface: Any]   [Protocol: TCP]
 |-> [Endpoint Identifier: 192.0.2.1:80]       [Interface: Wi-Fi] [Protocol: TCP]
 |-> [Endpoint Identifier: 192.0.2.1:80]       [Interface: LTE]   [Protocol: TCP]
 |-> [Endpoint Identifier: 2001:DB8::1.80]     [Interface: LTE]   [Protocol: TCP]

We could replace all these with "Endpoint Candidate" - but they ARE all Endpoint Identifiers at the same time, so ... it won't make things clearer to use an extra term here?

Please, if you look through this and you find occurrences where "Endpoint candidate" (perhaps not with capital C, as it's not a new term that we define - we do talk about candidates, and Endpoint candidates in this text already) would be a better fit, make a change suggestion. It really wasn't easy to always know precisely what the right term should be - I did my best.

[philsbln]

I will try my very best … but unsure whether I can make it tomorrow or on Wednesday after my vacation

[mwelzl]

Many thanks @philsbln ! I accepted all your suggestions. To nitpick, I'm a little bit unsure about this "resolving" thing, since one does resolve addresses, and I think in racing we do deal with the actual addresses and not more abstract entities? but maybe it's my misunderstanding... but I'm ok with it, I think it's understandable either way.

[mwelzl]

Many thanks @tfpauly for fixing all my exaggerated capitalizations! I approved all your suggestions.

All reviewers - are we good now??? Has this converged?

[tfpauly]

Fixed conflicts, merging now