Subject: [Dime] Review of "Diameter Applications Design Guidelines Document"

From: Alexis Hildebrandt <[email-masked]>
Date: Wed, 18 Apr 2007 15:21:49 +0200

Dear gentlepeople,
please find attached a quick and more editorial review of the
draft-fajardo-dime-app-design-guide-01.txt.

For your convenience I attached an edited version of the document, as
well as a diff.

The change suggestions around line 414 include a '(?)' where I'd like to
indicate, that I wasn't quite sure if I understood the text correctly
myself.

1) Either as I suggested an "application server is provisioned to use
    a different protocol to access the accounting server" or the
    difference between the two accounting servers as it is in the
    document at the moment should be explained in detail.

2) Is the intention to say: In
    a) all
    b) most
    of the cases above... ?

Feedback on the suggestions is greatly appreciated.  Best regards,
Alexis.
-- 
Alexis Hildebrandt, Software Development
Voice: +49.30.590080-1172
 
Netzwert AG, An den Treptowers 1, 12435 Berlin, Germany
Fax: +49.30.5900800700, http://www.netzwert.ag
Vorstand: Ralf U. Holighaus, Ralf Moritz
Aufsichtsrat: Clemens Schrimpe (Vorsitzender)
Steuernr.: 37/491/20570 Ust-IdNr.: DE 813 06 78 94
Sitz: Berlin Handelsregister: Amtsgericht Charlottenburg HRB 72960
--- /tmp/draft-fajardo-dime-app-design-guide-01.txt	2007-04-16 15:45:00.429554626 +0200
+++ /tmp/draft-fajardo-dime-app-design-guide-01-review.txt	2007-04-16 15:42:11.510997880 +0200
@@ -146,7 +146,7 @@
    o  Present tradeoffs of design choices.
 
    Note that it is not always possible to offer a complete and concise
-   answer to certain design choices.  There is, however, the believe
+   answer to certain design choices.  There is, however, the belief
    that at a minimum, this document can be used as a guide to Diameter
    extensibility.
 
@@ -174,12 +174,12 @@
    having an application layer and a peer-to-peer delivery layer.  The
    Diameter Base protocol document completely defines the architecture
    and behavior of the message delivery layer and then provides the
-   framework for designing Diameter applications for the application
+   framework for designing Diameter applications on the application
    layer.  This framework includes definitions of application sessions
    and accounting support (see Section 8 and 9 of [1]).  The remainder
-   of this document also treats a Diameter node a single instance of a
+   of this document also treats a Diameter node as a single instance of a
    Diameter message delivery layer and one or more Diameter applications
-   that uses it.
+   using it.

 4.  Rules on Diameter Extensibility
@@ -193,28 +193,28 @@
 
    Defining a completely new application
 
-      This case applies to applications which has requirements that
+      This case applies to applications which have requirements that
       cannot be filled by existing applications and would require
       definition of new command(s), AVPs and AVP values.  Typically,
       there is little ambiguity about the decision to create these types
       of applications.  Some examples are the interfaces defined for the
       IP Multimedia Subsystem of 3GPP, i.e.; Cx/Dx ([2] and [3]), Sh
-      ([4] and [5]) etc .  Though some decisions maybe clear, designers
+      ([4] and [5]) etc .  Though some decisions may be clear, designers
       should also consider certain aspects of the application itself.
       Some of these are described in Section 5.  Applications design
       should also follow the theme of Diameter extensibility which
       advocates reuse of AVPs and AVP values as much as possible even in
       newly defined commands.  In certain cases where accounting will be
-      used, models described in Section 5.1 should be considered.
+      used, the models described in Section 5.1 should be considered.
 
    Extending an existing application
 
-      In this case, the requirements of the new applications are not
+      In this case, the requirements for the new applications are not
       completely unique and there are existing applications that can be
-      reused to solve some or all of the application requirements.
-      Therefore, there is a greater likelihood of ambiguity on how much
-      of the existing application can be reused, to what extent and what
-      are the implications for both the new and existing application.
+      reused to solve some or all of the application's requirements.
+      Thus there is a greater likelihood of ambiguity on how much and to
+      what extend the existing application can be reused, and what
+      the implications for both the new and existing application are.
       Section 4.1 discusses some of the issues in this case.

@@ -235,10 +235,10 @@
 
       The rules are strict in the case where the AVP(s) to be added is
       mandatory to be understood and interpreted.  This means that the
-      M-bit is set and the AVP(s) is required to exists in command ABNF.
-      Note that this mandatory AVP rules applies to AVP(s) that either
+      M-bit is set and the AVP(s) is required to exist in the command ABNF.
+      Note that this mandatory AVP rule applies to AVP(s) that either
       already exist in the same or in another application or the AVP(s)
-      are yet to be defined.  In this case, the ambiguity arises when
+      are yet to be defined.  In the latter case, the ambiguity arises when
       trying to decide whether the AVP(s) should be mandatory or not.
       There are several questions that application designers should
       contemplate when trying to decide:
@@ -258,13 +258,13 @@
          application related information as well as be used to indicate
          that the message is for a new application ?
 
-      These questions are not comprehensive in anyway but in all cases
+      These questions are not comprehensive in any way but in all cases
       the semantics of the application must change to justify the use of
       mandatory AVPs.
 
       However, care should also be taken when opting for optional AVPs
       instead of mandatory AVPs simply to avoid allocating new
-      applications.  Optional AVPs that falls into any of the
+      applications.  Optional AVPs that fall into any of the
       categorical questions above would have consequences.  See
       Section 5.4 for details.
 
@@ -282,8 +282,8 @@

       significantly affects the behavior of the application.  Although
-      this case maybe less common or seem more subtle, the exact same
-      considerations given in the first scenario above applies here as
+      this case may be less common or seem more subtle, the exact same
+      considerations given in the first scenario above apply here as
       well.
 
    Add a command to an existing application
@@ -296,7 +296,7 @@
       functionality that does not yet exist.  The latter case would
       result in a new application but it has a more subtle issue such as
       deciding whether importing of commands and functionality is really
-      better than simply using the existing application as is in
+      better than simply using the existing application as it is in
       conjunction with any new application.
 
       A typical example would be the Diameter MIPv6 split scenario (see
@@ -313,7 +313,7 @@
 
       In general, it is difficult to come to a hard and fast guideline
       for this scenario so a case by case study of each application
-      requirements should be applied.  Before importing a command,
+      requirement should be applied.  Before importing a command,
       application designers should consider whether:
 
       *  The existing application can be reused as is without
@@ -321,7 +321,7 @@
          indicate support for new optional functionality if any.  There
          are pitfalls to this as well.  See Section 5.4
 
-      *  Reuse of existing applications as is would result in a
+      *  Reuse of existing applications would result in a
          distributed environment which may not be conducive to certain
          requirements of the applications; i.e. security and or
          deployment difficulties - because of Diameter routing, messages
@@ -352,7 +352,7 @@
    Accounting can be treated as an auxiliary application which is used
    in support of other applications.  In most cases, accounting support
    is required when defining new applications.  However, the lack of
-   clarity in the base protocol document have prevented easy use the
+   clarity in the base protocol document has prevented easy use of the
    base accounting messages (ACR/ACA).  This document provides two(2)
    possible models for using accounting:
 
@@ -362,7 +362,7 @@
       accounting application ID (value of 3).  The design implication
       for this is that the accounting is treated as an independent
       application, especially during routing.  This means that
-      accounting commands emanating from an application maybe routed
+      accounting commands emanating from an application may be routed
       separately from the rest of the other application messages.  This
       also implies that the messages generally end up in a central
       accounting server.  A split accounting model is a good design
@@ -414,22 +414,22 @@
          accounting for the specific application should be handled by
          the application itself.
 
-      *  The accounting server is provisioned to use a different
+      *  The application(?) server is provisioned to use a different
          protocol to access the accounting server; i.e., via LDAP, XML
          etc.  This includes attempting to supporting older accounting
          systems that are not Diameter aware.
 
-      In all most above, there will generally be no direct Diameter
+      In all/most cases(?) above, there will generally be no direct Diameter
       access to the accounting server.
 
    These models provide a basis for using accounting messages.
    Application designers may obviously deviate from these models
    provided that the factors being addressed here have also been taken
-   into account.  Though its not recommended, examples of other methods
-   would be defining a new set of command to carry application specific
+   into account.  Though it is not recommended, examples of other methods
+   would be defining a new set of commands to carry application specific
    accounting records.
 
-   Additionally, application ID in the message header and Accounting-
+   Additionally, the application ID in the message header and the Acct-
    Application-Id AVP are populated depending on the accounting model
    used for a specific application, as described in [1].  Therefore,
    application designers have to specify the accounting model used to
@@ -459,7 +459,7 @@
 
    o  Backward compatibility: Dealing with existing applications that do
       not understand the new extension.  Designers also have to make
-      sure that new extensions does not break expected message delivery
+      sure that new extensions do not break the expected message delivery
       layer behavior.
 
    o  Forward compatibility: Making sure that the design will not
@@ -468,7 +468,7 @@
       go through great lengths to implement any new extensions.
 
    o  Tradeoffs in signaling: Designers may have to choose between the
-      use of optional AVPs piggybacked into existing commands versus
+      use of optional AVPs piggybacked onto existing commands versus
       defining new commands and applications.  Optional AVPs are simpler
       to implement and may not need changes to existing applications;
       i.e., use of proxy agents.  However, the drawback is that the
@@ -477,15 +477,15 @@
       the application and the extensions have different timing
       requirements.  The use of commands and applications solves this
       issue but the tradeoff is the additional complexity of defining
-      and deploying a new application.  It is left up to the designer to
+      and deploying a new application.  It is the designer's choice to
       find a good balance among these tradeoffs based on the
       requirements of the extension.

 5.3.  Updating an existing Application
 
-   An application that is being upgraded must follow the same rules in
-   Section 4.  Even if the new version is fundamentally the same
+   An application that is being upgraded must follow the same rules mentioned
+   in Section 4.  Even if the new version is fundamentally the same
    application, allocation of a new application ID is possible if it
    meets those criteria.
 
@@ -511,10 +511,10 @@
 
 5.4.  Use of optional AVPs
 
-   Problems arises when there is a tendency by applications designers to
+   Problems arise when there is a tendency by application designers to
    keep adding optional AVPs to an existing command so they can
    circumvent the extension rules in Section 4.  Some of the pitfalls
-   that application designers should avoid is as follows:
+   that application designers should avoid are:
 
    o  Use of optional AVPs with intersecting meaning; one AVP has
       partially the same usage and/or meaning as another AVP.  The
@@ -529,13 +529,13 @@
       designers should not use this scheme to circumvent definition of
       mandatory AVPs.
 
-   All of these practices generally results in interoperability problems
+   Any of these practices generally result in interoperability problems
    so they should be avoided as much as possible.
 
 5.5.  Deleting AVPs from a Command ABNF
 
    Although this scenario is not as common, the deletion of AVPs from a
-   command ABNF is significant to when trying to extend an existing
+   command ABNF is significant when trying to extend an existing
    application.  Deletion can be categorized between deletion of
    mandatory and optional AVPs.
 
@@ -648,11 +648,11 @@
    o  Application design should segregate message delivery layer
       processing from application level processing.  An example is the
       use of timers to detect lack of a response for a previously sent
-      requests.  Although Diameter base protocol defines a watchdog
+      requests.  Although the Diameter base protocol defines a watchdog
       timer Tw, its use on application level is discouraged since Tw is
-      a hop-by-hop timer and its use would not be relevant for end-to-
+      a hop-by-hop timer and it would not be relevant for end-to-
       end message delivery error detection.  In such a case, it is
-      recommended that applications should define its own set of timers
+      recommended that applications should define their own set of timers
       for such purpose.

_______________________________________________
DiME mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/dime

---

From: Victor Fajardo <[email-masked]>
Date: Wed, 18 Apr 2007 10:05:40 -0400

Hi Alexis,

Thanks for the review. Since you have a lot of editorial comments, I 

>     document at the moment should be explained in detail.

The intent of the text is what you have suggested.

> 2) Is the intention to say: In

The intent is 'all'.

thanks,
victor