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
-------------------------------------+-------------------------------------
Changes (by vorner):

 * owner:  vorner => jinmei


Comment:

 Hello

 I tried to rewrite the document. It is probably less formal and detailed
 then the example of yours, but I tried to adopt the structure. I also
 added some examples.

 It might be slightly more convenient to read if you run it through
 asciidoc.

 Replying to [comment:14 jinmei]:
 > 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?

 The connect() call is blocking, it waits until the other side calls
 accept(). Also, the getting of lname needs a round-trip to the other
 process. So there are at least 4 context switches in between and msgq
 might be busy.

 The session establishment can be IMO considered a fast operation, but I
 don't think we can consider it non-blocking. Creating a new session for
 each query answered would be a bad idea, but it makes no different if you
 create one session on startup or four.

 > >  * 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.

 No, I meant synchronous receive. You said it can be considered non-
 blocking if the other side of communication is msgq.

 I don't think we can say that, for the same reasons as above. It is OK to
 do such things in xfrout, for example, but trying to subscribe and
 unsubscribe once per auth query would be too slow.

 > >  * 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.

 Yes, but the callback is never called in such case, so it makes no sense
 to say the user must consider it fatal in the context of asynchronous
 read. The error is never reported through that interface.

 > >  * 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.

 Well, we explain what operations the session can do. What protocol is
 behind is described in the cc-protocol.txt.

 > >  * 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:

 OK, I differentiated them in the terminology and noted they are
 implemented the same way in the protocol.

 Speaking about that, where do we want to put the enforcement of
 singularity? I guess we could put it in the send ‒ if there's a message
 sent with `"want_answer": true` to a group containing multiple recipients,
 return `[-2, "Multiple recipients"]`. Do you think that would work?

 > > 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.

 Yes, the 4th could be used to know a session I talked to is gone. Also, I
 want to know when a session I sent a command to (and didn't get a reply
 yet) disconnected.

 The 1st one is mostly for completeness, if we have subscription to group
 as well as unsubscription, it makes sense to have connection as well as
 disconnection.

 > 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.

 I hope I made it better at that, the higher-level ones are a separate
 chapter.

 > > 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.

 I call it a session ID in the document, noting it is also called lname in
 the code (so the readers of code are not confused if they find it).

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