BIND 10 #2738: Clarify high-level design of the CC protocol

[BIND 10 Development]

#2738: Clarify high-level design of the CC protocol
-------------------------------------+-------------------------------------
            Reporter:  vorner        |                        Owner:
                Type:  task          |  jinmei
            Priority:  medium        |                       Status:
           Component:  Inter-module  |  reviewing
  communication                      |                    Milestone:
            Keywords:                |  Sprint-20130423
           Sensitive:  0             |                   Resolution:
         Sub-Project:  DNS           |                 CVSS Scoring:
Estimated Difficulty:  5             |              Defect Severity:  N/A
         Total Hours:  0             |  Feature Depending on Ticket:
                                     |          Add Hours to Ticket:  0
                                     |                    Internal?:  0
-------------------------------------+-------------------------------------

Comment (by jinmei):

 Replying to [comment:13 vorner]:

 > > First, please be careful about the status of the branch: I

 > I examined the branch, concluded the history doesn't look nice (and the
 branch included some non-reverted changes, I believe you managed to revert
 the other side of the merge than you wanted) and rebuilt it completely.
 So, update the branch by:
 >
 > {{{
 > git fetch
 > git reset --hard origin/trac2738
 > }}}
 >
 > instead of `git pull`.

 Done.  Sorry for the mess.

 > > Secondly, after thinking over details I realized I had a higher level
 > > concern and/or perhaps I really didn't understand what was expected in
 > > this task.  [...]
 >
 > Actually, I believe it was me who didn't understand the goal properly;
 after all, the ticket was created because you asked for it in some review.
 >
 > On the other hand, I don't really understand the reason for this
 > > kind of document. Is it clarification for us, how we should use it
 > > (which was my original impression), or documentation for others?

 My idea was it's primarily for us.  But this "us" would include
 relatively newer team members who are not so familiar with basic
 concepts or implementation details or even future developers.  So the
 difference is somewhat vague.

 > > If it's the first, do we really need to formally define what a
 > > session is? Everybody of us know. If the second, how low-level do

 The level of formality may be a matter of taste to some extent, so I
 don't insist it be very formal such as RFCs, IEEE standard documents,
 etc.  But I personally believe it still helps to provide some level of
 formal definitions even among us, because it's not so uncommon that
 different developers use the same term with slightly different
 definitions (based on what they *think* it is), resulting in
 confusion.

 > Anyway, I'd like to discuss the goal and also the details in your
 version first, before trying to merge them, so I didn't update anything on
 the branch.
 >
 > Is the content meant to be an example only, or really what you envision?
 Because I don't think I can agree with all of the things there:

 Not necessarily example "only" but the focus was more about the
 organizational aspect.  Regarding specific technical details, I know
 something may be controversial, some may be due to my misunderstanding
 (in which case it's actually a reason why we need such documentation),
 some are mostly a guess (another reason why we need the doc, as it
 indicates we need clarifications there).

 So, in general, I'm not pushing the idea of the details written there,
 but I'll briefly answer the points below.

 >  * I don't think the session establishment is non-blocking.

 But how would it block?

 >  * Is it OK to consider the synchronous read non-blocking, even in the
 case of talking to msgq? I'm OK with calling it fast, but I don't think we
 can call it non-blocking.

 Do you mean (synchronous) send?  In any case whether it's "fast" or
 "non-blocking", I admit the definition is a bit vague.

 >  * What error can be reported by asynchronous read (I mean low-level
 error, not a payload signifying an error response)? Would there be error
 reading the message, it is impossible to decide which callback to pick, so
 it would be handled somewhere else than the callback.

 I thought "Error reading the message" would be considered fatal and
 terminate the client anyway.

 >  * Also, I believe currently the asynchronous read does not have any
 timeout. Being it asynchronous, it is possible to implement timeout on the
 client side, with synchronous it is not possible.
 >  * The concept of watch you describe seems different than what I though,
 on several levels:

 This is quite open, mostly example only.

 >  * As mentioned above, the message types seem very low level. On other
 hand, I think we should document the higher-level (JSON) somewhere too ‒
 format of command, reply, etc.

 I didn't mean high level things are not necessary.  That would simply
 belong to a different level of conceptual layer.  Low level message
 types may not be necessary if we can explain the system properties
 without them.

 >  * How can the system know the difference between close and termination?
 It just gets EOF in both cases.

 True.  I realized the last bullet of "Session Management" wasn't
 really accurate.

 >  * I don't think we should forbid sending a command (eg. message that
 wants a response) to a group. As I mentioned, there are „singleton groups“
 ‒ more like aliases than actual groups.

 I'm okay with allowing such exchanges with a real "group" (one with
 multiple receivers) if we can give clear definition and specification.
 I also see the point for the concept of the so called "singleton
 group".  But on thinking over it now, I guess it might be clearer if
 we define message destinations as follows:

 - receiver's session ID (lname).  this is obviously unicast
 - an alias of receiver's session ID.  this is also unicast.  the user
   tells the system alias (in our current implementation, it's done by
   "subscribing to a group", and the group name is the alias).  the
   system manages the mapping from an alias to the session ID, and also
   ensures the uniqueness of the aliases (there will be no more than
   one session ID for an alias).
 - group of session IDs.  this is (possibly) multicast

 The first two can request a response.  And, again, if we can give
 a reasonable definition of response to the third one, I'm not
 necessarily opposed to it.  But it doesn't seem to be easy, and unless
 we really need such usage I'd rather explicitly prohibit it in that
 case.

 Through the discussion so far, I'm personally feeling one source of
 confusion or difficulty in clarifying the concept is that we use the
 notion of "group" for these two purposes.  I think we can define it
 more cleanly if we separate them at the concept level (the underlying
 implementation may still use the same "group" field for "alias").

 > > > I don't really agree here it's only optimisation. There are modules
 that are
 > > > not expected to take long to answer. For example the statistics
 daemon doesn't
 > > > do anything but collect and answer statistics. But it doesn't have
 to be there.
 > >
 > > On working on another version of doc, I now actually feel it optional
 > > more strongly.  [...]
 >
 > Only if you really insists on forbidding the singleton groups (eg.
 groups where it's expected to be at most 1 client large).

 See above.  If we introduce it for "alias of receiver's session ID"
 (unicast only), I see the point of it.

 > > - I still don't understand how these would be used:
 > > {{{
 > >   * Client connected (sent with the lname of the client)
 > >   * Client disconnected (sent with the lname of the client)
 > > }}}
 >
 > Well, I imagined these four kinds of notifications can happen
 (examples):
 > * Notification: A new client with lname = '12345' connected to the
 system.
 > * Notification: Client with lname = '12345' subscribed to group named
 'Group'.
 > * Notification: Client with lname = '12345' unsubscribed from group
 named 'Group'.
 > * Notification: Client with lname = '12345' disconnected from the
 system.
 >
 > These would be sent to whoever would be subscribed to a group
 'SessionManagement' (or any other well-known name).

 And how would the user use the 1st and 4th notification?  Hmm, maybe
 the 4th one may be of some use - if a user has received a message from
 some arbitrary "lname" (session ID) and needs to remember it to send a
 message to that ID for some other reason.  But, whether this guess is
 the intended one or not, it didn't/doesn't seem so obvious, so I want
 to see some explanation in the doc.

 > > - On writing my own version, I realized the RPC call is rather
 > >   considered an application and API sugar on top of the IPC system,
 > >   rather than the part of the system itself.  [...]
 >
 > Well, RPC is one part of IPC, from the application level. It's true the
 „system“ itself (msgq, the isc.cc.session library) doesn't have to care
 about it, but the higher level (from the isc.config.Session), the
 applications do care. It's part of what we do with the system and it makes
 sense to mention it. I think it is worth, at least, note that such
 functions exists so clients don't reinvent the wheel (preferably with
 description of how each type of communication works).

 I don't oppose to describing the RPC spec per se, as long as we
 clarify the layers.  The main problem in the original doc regarding
 this is that concepts of different levels of conceptual layer
 (different, at least in my understanding) are described in a flat
 organization.

 > And, I believe `lname` means „link name“.

 I'm not opposed to that interpretation, but at least I never had any
 idea of what "l" meant in lname.  I'd still be inclined to renaming it
 for this reason, but if we want to avoid that because of the resulting
 changes to the existing implementation considered too, it's better to
 clarify it somewhere.

-- 
Ticket URL: <http://bind10.isc.org/ticket/2738#comment:14>
BIND 10 Development <http://bind10.isc.org>
BIND 10 Development