Merge branch 'master_community' into seeds

Author: breznak

.gitignore

@@ -13,7 +13,10 @@ __pycache__
 .coverage
 htmlcov/
 
-# IDE project files
+# IDE Visual Studio files
+.vs
+
+# IDE VSCode project files
 /nbproject/
 .vscode
 .ycm_extra_conf.py

docs/NetworkAPI_REST.md

@@ -30,15 +30,15 @@ Network                   (key is id)
           Parameters      (key is parameter name)
           Inputs          (key is input name)
           Outputs         (key is output name)
-     Links                (key is link name)
+     Links                (key is "from_region.from_output", "to_region.to_input")
 ```
 
 So a full key structure would look like:
 ```
 /network/<id>/region/<region name>/param/<param name>
-/network/<id>/region/<region name>/Input/<param name>
+/network/<id>/region/<region name>/input/<param name>
 /network/<id>/region/<region name>/output/<param name>
-/network/<id>/link/<link name>
+/network/<id>/link/<from>/<to>
 ```
 
 ## REST Operators
@@ -76,6 +76,15 @@ Protocol for the NetworkAPI REST feature for all operations currently implemente
 
   GET  /network/<id>/region/<region name>/output/<output name>
        Get the value of a region's output. Returns a JSON encoded Array object.
+       
+  DELETE  /network/<id>/region/<region name>
+       Delete the specified region
+       
+  DELETE  /network/<id>/link/<source name>/<dest_name>
+       Delete the specified link
+       
+  DELETE  /network/<id>/ALL
+       Delete the entire Network object.
 
   GET  /network/<id>/run?iterations=<iterations>
        Execute all regions in phase order. Repeat <iterations> times. Returns OK.
@@ -129,4 +138,4 @@ JSON example:
        {addLink:   {src: "encoder.encoded", dest: "sp.bottomUpIn"}},
        {addLink:   {src: "sp.bottomUpOut", dest: "tm.bottomUpIn"}}
     ]}
-```
+```

src/examples/rest/server_core.hpp

@@ -16,7 +16,9 @@
 //   /network/<id>/region/<name>/param/<name>
 //   /network/<id>/region/<name>/input/<name>
 //   /network/<id>/region/<name>/output/<name>
-//   /network/<id>/link/<name>
+//   /network/<id>/link/<source_name>/<dest_name>
+//      Note: source_name syntax is "region_name.output_name"
+//            dest_name   syntax is "region_name.input_name"
 //
 // The expected protocol for the NetworkAPI application is as follows:
 //
@@ -35,6 +37,12 @@
 //       Get the value of a region's input. Returns a JSON encoded array.
 //  GET  /network/<id>/region/<region name>/output/<output name>
 //       Get the value of a region's output. Returns a JSON encoded array.
+//  DELETE /network/<id>/region/<region name>
+//       Deletes a region. Must not be in any links.
+//  DELETE /network/<id>/link/<source_name>/<dest_name>
+//       Deletes a link.
+//  DELETE /network/<id>/ALL
+//       Deletes the entire Network object
 //  GET  /network/<id>/run?iterations=<iterations>
 //       Execute all regions in phase order. Repeat <iterations> times.
 //  GET  /network/<id>/region/<region name>/command?data=<command>
@@ -165,6 +173,42 @@ class RESTserver {
       std::string result = interface->get_output_request(id, region_name, output_name);
       res.set_content(result + "\n", "text/plain");
     });
+    
+    //  DELETE /network/<id>/region/<region name>
+    //       Deletes a region. Must not be in any links.
+    svr.Delete("/network/.*/region/.*", [](const Request &req, Response &res) {
+      std::vector<std::string> flds = split(req.path, '/');
+      std::string id = flds[2];
+      std::string region_name = flds[4];
+
+      RESTapi *interface = RESTapi::getInstance();
+      std::string result = interface->delete_region_request(id, region_name);
+      res.set_content(result + "\n", "text/plain");
+    });
+
+    //  DELETE /network/<id>/link/<name>
+    //       Deletes a link.
+    svr.Delete("/network/.*/link/.*/.*", [](const Request &req, Response &res) {
+      std::vector<std::string> flds = split(req.path, '/');
+      std::string id = flds[2];
+      std::string source_name = flds[4];
+      std::string dest_name = flds[5];
+
+      RESTapi *interface = RESTapi::getInstance();
+      std::string result = interface->delete_link_request(id, source_name, dest_name);
+      res.set_content(result + "\n", "text/plain");
+    });
+    
+    //  DELETE /network/<id>/ALL
+    //       Deletes the entire Network object
+    svr.Delete("/network/.*/ALL", [](const Request &req, Response &res) {
+      std::vector<std::string> flds = split(req.path, '/');
+      std::string id = flds[2];
+
+      RESTapi *interface = RESTapi::getInstance();
+      std::string result = interface->delete_network_request(id);
+      res.set_content(result + "\n", "text/plain");
+    });
 
 
     // GET /network/<id>/run?iterations=<iterations>

src/htm/engine/RESTapi.cpp

@@ -174,6 +174,58 @@ std::string RESTapi::get_param_request(const std::string &id,
   }
 }
 
+std::string RESTapi::delete_region_request(const std::string &id, const std::string &region_name) {
+  try {
+    auto itr = resource_.find(id);
+    NTA_CHECK(itr != resource_.end()) << "Context for resource '" + id + "' not found.";
+    itr->second.t = time(0);
+
+    std::string response = "OK";
+    itr->second.net->removeRegion(region_name);
+
+    return response;
+  } catch (Exception &e) {
+    return std::string("ERROR: ") + e.getMessage();
+  }
+}
+
+std::string RESTapi::delete_link_request(const std::string &id, 
+                                         const std::string &source_name,
+                                         const std::string &dest_name) {
+  try {
+    auto itr = resource_.find(id);
+    NTA_CHECK(itr != resource_.end()) << "Context for resource '" + id + "' not found.";
+    itr->second.t = time(0);
+
+    std::vector<std::string> args;
+    args = split(source_name, '.');
+    NTA_CHECK(args.size() == 2) << "Expected syntax <region>.<output> for source name. Found " << source_name;
+    std::string source_region = args[0];
+    std::string source_output = args[1];
+
+    args = split(dest_name, '.');
+    NTA_CHECK(args.size() == 2) << "Expected syntax <region>.<input> for destination name. Found " << dest_name;
+    std::string dest_region = args[0];
+    std::string dest_input = args[1];
+
+    std::string response = "OK";
+    itr->second.net->removeLink(source_region, dest_region, source_output, dest_input);
+    return response;
+
+  } catch (Exception &e) {
+    return std::string("ERROR: ") + e.getMessage();
+  }
+}
+
+std::string RESTapi::delete_network_request(const std::string &id) {
+    auto itr = resource_.find(id);
+    NTA_CHECK(itr != resource_.end()) << "Context for resource '" + id + "' not found.";
+    
+    resource_.erase(itr);
+    return "OK";
+}
+
+
 std::string RESTapi::run_request(const std::string &id, const std::string &iterations) {
   try {
     auto itr = resource_.find(id);

src/htm/engine/RESTapi.hpp

@@ -42,6 +42,10 @@
  *       There is a maximum of 65535 active Network class resources.
  *       A Network resource will timeout without activity in 24 hrs.
  *
+ *       The methods in the class are called from examples/rest/server_core.hpp
+ *       which is compiled with the rest server.  An application can use the server
+ *       AS-IS or replace the server and server_core.hpp to sute its needs.
+ *
  * LIMITATIONS:
  *       1) Only built-in C++ regions can be used.  There are plans to
  *          eventually allow connecting to Python regions and dynamically 
@@ -247,6 +251,62 @@ class RESTapi
                                 const std::string &region_name, 
                                 const std::string &param_name);
 
+
+  /**
+   * @b Description:
+   * Handler for a DELETE "link" request message.
+   * This will remove the link with matching source and destination names.
+   *
+   * @param id  Identifier for the resource context (a Network class instance).
+   *            Client should pass the id returned by the previous "configure"
+   *            request message.
+   *
+   *
+   * @param source_name The name of the region that is the source of data.
+   *
+   * @param dest_name   The name of the region that is destination of data.
+   *
+   * @retval            If success returns Ok.
+   *                    Otherwise returns error message starting with "ERROR: ".
+   */
+  std::string delete_link_request(const std::string &id, 
+                                  const std::string &source_name, 
+                                  const std::string &dest_name);
+
+
+  /**
+   * @b Description:
+   * Handler for a DELETE "region" request message.
+   * This will remove the region with matching name.
+   *
+   * @param id  Identifier for the resource context (a Network class instance).
+   *            Client should pass the id returned by the previous "configure"
+   *            request message.
+   *
+   *
+   * @param region_name The name of the region that is to be removed.
+   *
+   * @retval            If success returns Ok.
+   *                    Otherwise returns error message starting with "ERROR: ".
+   */
+  std::string delete_region_request(const std::string &id, const std::string &region_name);
+
+    /**
+   * @b Description:
+   * Handler for a DELETE "network" request message.
+   * This will remove the entire Network object.
+   *
+   * @param id  Identifier for the resource context (a Network class instance).
+   *            Client should pass the id returned by the previous "configure"
+   *            request message.
+   *
+   *
+   * @retval            If success returns Ok.
+   *                    Otherwise returns error message starting with "ERROR: ".
+   */
+  std::string delete_network_request(const std::string &id);
+
+
   /**
    * @b Description:
    * Handler for a "run" request message.

src/test/unit/engine/RESTapiTest.cpp

@@ -129,7 +129,7 @@ TEST(RESTapiTest, example) {
        {addLink:   {src: "sp.bottomUpOut", dest: "tm.bottomUpIn"}}
     ]})";
 
-
+  // create the network object
   res = client.Post("/network", config, "application/json");
   ASSERT_TRUE(res && res->status/100 == 2 && res->body.size() == 5) << "Failed Response to POST /network request.";
   std::string id = res->body.substr(0,4);
@@ -170,4 +170,59 @@ TEST(RESTapiTest, example) {
 
   threadObj.join(); // wait until server thread has stopped.
 }
+
+TEST(RESTapiTest, test_delete) {
+  std::thread threadObj(serverThread);                  // start REST server
+  std::this_thread::sleep_for(std::chrono::seconds(1)); // give server time to start
+
+  // Client thread.
+  const httplib::Params noParams;
+  char message[1000];
+
+  httplib::Client client("127.0.0.1", port);
+  client.set_timeout_sec(30);
+
+  // Configure a NetworkAPI example
+  // See Network.configure() for syntax.
+  //     Simple situation    Encoder  ==>  SP  ==>  TM
+  //     Compare this to the napi_sine example.
+  std::string config = R"(
+   {network: [
+       {addRegion: {name: "encoder", type: "RDSEEncoderRegion", params: {size: 1000, sparsity: 0.2, radius: 0.03, seed: 2019, noise: 0.01}}},
+       {addRegion: {name: "sp", type: "SPRegion", params: {columnCount: 2048, globalInhibition: true}}},
+       {addRegion: {name: "tm", type: "TMRegion", params: {cellsPerColumn: 8, orColumnOutputs: true}}},
+       {addLink:   {src: "encoder.encoded", dest: "sp.bottomUpIn"}},
+       {addLink:   {src: "sp.bottomUpOut", dest: "tm.bottomUpIn"}}
+    ]})";
+
+  // create the network object
+  auto res = client.Post("/network", config, "application/json");
+  ASSERT_TRUE(res && res->status / 100 == 2 && res->body.size() == 5) << "Failed Response to POST /network request.";
+  std::string id = res->body.substr(0, 4);
+
+  // Now delete the second link.
+  snprintf(message, sizeof(message), "/network/%s/link/sp.bottomUpOut/tm.bottomUpIn", id.c_str());
+  res = client.Delete(message);
+  ASSERT_TRUE(res && res->status / 100 == 2) << " DELETE link message failed.";
+  EXPECT_STREQ(trim(res->body).c_str(), "OK") << "Response to DELETE Link request";
+
+  // Delete a region
+  snprintf(message, sizeof(message), "/network/%s/region/tm", id.c_str());
+  res = client.Delete(message);
+  ASSERT_TRUE(res && res->status / 100 == 2) << " DELETE region message failed.";
+  EXPECT_STREQ(trim(res->body).c_str(), "OK") << "Response to DELETE Link request";
+  
+  // Delete a Network
+  snprintf(message, sizeof(message), "/network/%s/ALL", id.c_str());
+  res = client.Delete(message);
+  ASSERT_TRUE(res && res->status / 100 == 2) << " DELETE region message failed.";
+  EXPECT_STREQ(trim(res->body).c_str(), "OK") << "Response to DELETE Link request";
+  
+  
+
+  // wrap up
+  res = client.Get("/stop"); // stop the server.
+  threadObj.join();          // wait until server thread has stopped.
+}
+
 } // namespace testing