[5495] Checkpoint: added doc/examples, todo: unit tests

doc/Makefile.am

@@ -8,7 +8,9 @@ EXTRA_DIST += devel/mainpage.dox
 EXTRA_DIST += devel/terminology.dox
 EXTRA_DIST += devel/unit-tests.dox
 
-nobase_dist_doc_DATA  = examples/agent/simple.json
+nobase_dist_doc_DATA  = examples/agent/comments.json
+nobase_dist_doc_DATA += examples/agent/simple.json
+nobase_dist_doc_DATA += examples/ddns/comments.json
 nobase_dist_doc_DATA += examples/ddns/sample1.json
 nobase_dist_doc_DATA += examples/ddns/template.json
 nobase_dist_doc_DATA += examples/https/httpd2/kea-httpd2.conf

doc/examples/agent/comments.json

@@ -0,0 +1,37 @@
+// This is a example of a configuration for Control-Agent (CA) or simply Agent.
+// It uses embedded (i.e., which will be included in configuration objects
+// and not stripped by at lexical analysis) comments.
+
+{
+    "Control-agent":
+    {
+        // Global scope
+        "comment": "A Control Agent",
+
+        "http-host": "127.0.0.1",
+        "http-port": 8000,
+
+        // In control socket
+        "control-sockets":
+        {
+            "dhcp4":
+            {
+                "comment": "control socket for DHCP4 server",
+                "socket-type": "unix",
+                "socket-name": "/path/to/the/unix/socket-v4"
+            }
+        }
+
+    },
+
+    "Logging":
+    {
+        // In loggers
+        "loggers": [
+            {
+                "comment": "A logger",
+                "name": "kea-ctrl-agent"
+            }
+        ]
+    }
+}

doc/guide/agent.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash  "&#x2017;" >
+<!ENTITY mdash  "&#x2018;" >
 ]>
 
 <chapter id="kea-ctrl-agent">
@@ -66,12 +66,14 @@
 
         "control-sockets": {
             "dhcp4": {
+                "comment": "main server",
                 "socket-type": "unix",
                 "socket-name": "/path/to/the/unix/socket-v4"
             },
             "dhcp6": {
                 "socket-type": "unix",
-                "socket-name": "/path/to/the/unix/socket-v4"
+                "socket-name": "/path/to/the/unix/socket-v4",
+                "user-context": { "version": 3 }
             }
         },
 
@@ -145,6 +147,22 @@
       </simpara>
     </warning>
 
+    <para>
+      User contexts can store arbitrary data as long as it is valid JSON
+      syntax and its top level element is a map (i.e. the data must be
+      enclosed in curly brackets). Some hook libraries may expect specific
+      formatting, though.  Please consult specific hook library
+      documentation for details.
+    </para>
+
+    <para>
+      User contexts can be specified on either global scope, control
+      socket and loggers. One other useful usage is the ability to
+      store comments or descriptions: the parser translates a
+      "comment" entry into a user-context with the entry, this allows
+      to attach a comment inside the configuration itself.
+    </para>
+
     <para>
       Hooks libraries can be attached to the Control Agent just like to
       DHCPv4 and DHCPv6 servers. It currently supports one hook point

doc/guide/ddns.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash  "&#x2014;" >
+<!ENTITY mdash  "&#x2018;" >
 ]>
 
   <chapter id="dhcp-ddns-server">
@@ -768,6 +768,30 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
 
       </section> <!-- "d2-reverse-ddns-config" -->
 
+      <section id="d2-user-contexts">
+        <title>User context in DDNS</title>
+
+        <note>
+          <para>User contexts were designed for hook libraries which
+          are not yet supported for DHCP-DDNS server configuration.</para>
+        </note>
+
+        <para>
+          User contexts can store arbitrary data as long as it is valid JSON
+          syntax and its top level element is a map (i.e. the data must be
+          enclosed in curly brackets).
+        </para>
+
+        <para>
+          User contexts can be specified on either global scope, ddns
+          domain, dns server, tsig key and loggers. One other useful
+          usage is the ability to store comments or descriptions: the
+          parser translates a "comment" entry into a user-context with
+          the entry, this allows to attach a comment inside the
+          configuration itself.
+        </para>
+      </section> <!-- "d2-user-contexts" -->
+
       <section id="d2-example-config">
         <title>Example DHCP-DDNS Server Configuration</title>
         <para>
@@ -858,6 +882,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
         The following example configuration specified the Forward DDNS Domains.
 <screen><userinput>
 "DhcpDdns": {
+    "comment": "example configuration: forward part",
     "forward-ddns": {
         "ddns-domains": [
             {
@@ -880,7 +905,8 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
                 "key-name": "",
                 "dns-servers": [
                     { "ip-address": "172.16.2.5" }
-                ]
+                ],
+                "user-context": { "backup": false }
             },
 
         ]
@@ -932,6 +958,7 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
 
 <screen><userinput>
 "DhcpDdns": {
+    "comment": "example configuration: reverse part",
     "reverse-ddns": {
         "ddns-domains": [
             {

src/bin/agent/tests/parser_unittests.cc

@@ -1,4 +1,4 @@
-// Copyright (C) 2017 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2017-2018 Internet Systems Consortium, Inc. ("ISC")
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -9,6 +9,7 @@
 #include <agent/parser_context.h>
 #include <cc/dhcp_config_error.h>
 #include <testutils/io_utils.h>
+#include <testutils/user_context_utils.h>
 
 using namespace isc::data;
 using namespace isc::test;
@@ -311,6 +312,7 @@ TEST(ParserTest, multilineComments) {
 ///
 /// @param fname name of the file to be loaded
 void testFile(const std::string& fname) {
+    ElementPtr json;
     ElementPtr reference_json;
     ConstElementPtr test_json;
 
@@ -318,7 +320,8 @@ void testFile(const std::string& fname) {
 
     cout << "Parsing file " << fname << "(" << decommented << ")" << endl;
 
-    EXPECT_NO_THROW(reference_json = Element::fromJSONFile(decommented, true));
+    EXPECT_NO_THROW(json = Element::fromJSONFile(decommented, true));
+    reference_json = moveComments(json);
 
     // remove the temporary file
     EXPECT_NO_THROW(::remove(decommented.c_str()));
@@ -344,6 +347,7 @@ void testFile(const std::string& fname) {
 // Hopefully the list of example configs will grow over time.
 TEST(ParserTest, file) {
     vector<string> configs;
+    configs.push_back("comments.json");
     configs.push_back("simple.json");
 
     for (int i = 0; i<configs.size(); i++) {

src/bin/d2/tests/parser_unittest.cc

@@ -1,4 +1,4 @@
-// Copyright (C) 2017 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2017-2018 Internet Systems Consortium, Inc. ("ISC")
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -8,8 +8,10 @@
 #include <d2/parser_context.h>
 #include <d2/tests/parser_unittest.h>
 #include <testutils/io_utils.h>
+#include <testutils/user_context_utils.h>
 
 using namespace isc::data;
+using namespace isc::test;
 using namespace std;
 
 namespace isc {
@@ -265,11 +267,16 @@ TEST(ParserTest, multilineComments) {
 ///
 /// @param fname name of the file to be loaded
 void testFile(const std::string& fname) {
+    ElementPtr json;
     ElementPtr reference_json;
     ConstElementPtr test_json;
 
-    string decommented = isc::test::decommentJSONfile(fname);
+    string decommented = decommentJSONfile(fname);
-    EXPECT_NO_THROW(reference_json = Element::fromJSONFile(decommented, true));
+
+    cout << "Parsing file " << fname << " (" << decommented << ")" << endl;
+
+    EXPECT_NO_THROW(json = Element::fromJSONFile(decommented, true));
+    reference_json = moveComments(json);
 
     // remove the temporary file
     EXPECT_NO_THROW(::remove(decommented.c_str()));
@@ -294,6 +301,7 @@ void testFile(const std::string& fname) {
 // the second time with D2Parser. Both JSON trees are then compared.
 TEST(ParserTest, file) {
     vector<string> configs;
+    configs.push_back("comments.json");
     configs.push_back("sample1.json");
     configs.push_back("template.json");