Merge pull request #14 from Mrt134/master

Additional dispatcher work
2026-01-27 10:20:26 +00:00 · 2016-04-12 17:04:15 -04:00
parent fc55d22a9f 81c4e91905
commit 2860152c04
6 changed files with 79 additions and 136 deletions
--- a/api/classes/iohyve.rst
+++ b/api/classes/iohyve.rst
@@ -159,15 +159,17 @@ The "fetchiso" action is used to retrieve the installation ISO. It is used with
  "id" : "none",
  "args" : {
    "event_system" : "sysadm"/"iohyve",
-    "state" : "running" OR "finished",
+    "state" : "finished",
    "filename" : "<filename>",
    "percent_done" : "<number>%",
    "download_rate" : "<rate>",
    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
+      "time_finished" : "<ISO 8601 time date string>",
      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
+      "return_codes/<command 1>" : "<code 1>",
+      "return_codes/<command 2>" : "<code 2>",
+      "process_id" : "<random>",
+      "state" : "finished"
      }
   }
 }
--- a/api/classes/pkg.rst
+++ b/api/classes/pkg.rst
@@ -224,28 +224,6 @@ The "pkg_info" action reads the pkg database directly and returns any relevant i
  "namespace": "sysadm"
 }

-**Dispatcher Events System Reply**
-
-.. code-block:: json
-
- {
-  "namespace" : "events",
-  "name" : "dispatcher",
-  "id" : "none",
-  "args" : {
-    "event_system" : "sysadm"/"pkg",
-    "state" : "running" OR "finished",
-    "pkg_log" : "<process log>",
-    "action" : "pkg_info",
-    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
-      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
-      }
-    }
- } 
-
 .. index:: pkg_search, pkg

 .. _Search Packages:
@@ -268,7 +246,8 @@ The "pkg_search" action searches the package database for pkgs which match the g
   "repo" : "pcbsd-major",
   "category" : "www",
   "action" : "pkg_search",
-   "search_term" : "fire"
+   "search_term" : "fire",
+   "search_excludes" : ["<phrase1>", "<phrase2>"]
 }

 **WebSocket Request**
@@ -282,6 +261,7 @@ The "pkg_search" action searches the package database for pkgs which match the g
   "args" : {
      "action" : "pkg_search",
      "search_term" : "fire",
+      "search_excludes" : ["<phrase1>", "<phrase2>"],
      "category" : "www",
      "repo" : "pcbsd-major"
   }
@@ -294,6 +274,7 @@ The "pkg_search" action searches the package database for pkgs which match the g
 {
  "args": {
    "pkg_search": {
+      "results_order" : ["www/firefox", "www/firefox-esr", "www/firefox-esr-i18n", "www/firefox-pulse"],
      "www/firefox": {
        "arch": "FreeBSD:11:amd64",
        "cksum": "cc72c379afbd66d152cf06b7d2a14ada413f338071ecb9b084899c94d39f951e",
@@ -424,28 +405,6 @@ The "pkg_search" action searches the package database for pkgs which match the g
  "namespace": "sysadm"
 }

-**Dispatcher Events System Reply**
-
-.. code-block:: json
-
- {
-  "namespace" : "events",
-  "name" : "dispatcher",
-  "id" : "none",
-  "args" : {
-    "event_system" : "sysadm"/"pkg",
-    "state" : "running" OR "finished",
-    "pkg_log": "<process log>",
-    "action" : "pkg_search",
-    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
-      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
-      }
-    }
- }  
-
 .. index:: list_categories, pkg

 .. _List Categories:
@@ -545,28 +504,6 @@ The "list_categories" action lists all the known, non-empty categories within th
  "namespace": "sysadm"
 }

-**Dispatcher Events System Reply**
-
-.. code-block:: json
-
- {
-  "namespace" : "events",
-  "name" : "dispatcher",
-  "id" : "none",
-  "args" : {
-    "event_system" : "sysadm"/"pkg",
-    "state" : "running" OR "finished",
-    "pkg_log" : "<process log>",
-    "action" : "list_categories",
-    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
-      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
-      }
-    }
- }  
- 
 .. index:: list_repos, pkg

 .. _List Repositories:
@@ -615,28 +552,6 @@ action are valid as the optional "repo" argument for the other pkg API actions.
  "namespace": "sysadm"
 }

-**Dispatcher Events System Reply**
-
-.. code-block:: json
-
- {
-  "namespace" : "events",
-  "name" : "dispatcher",
-  "id" : "none",
-  "args" : {
-    "event_system" : "sysadm"/"pkg",
-    "state" : "running" OR "finished",
-    "pkg_log" : "<process log>",
-    "action" : "list_repos",
-    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
-      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
-      }
-    }
- }  
-
 .. index:: pkg_audit, pkg

 .. _Audit Packages:
@@ -698,19 +613,19 @@ The "pkg_audit" action performs an audit of all installed packages and reports a
  "id" : "none",
  "args" : {
    "event_system" : "sysadm"/"pkg",
-    "state" : "running" OR "finished",
+    "state" : "finished",
    "pkg_log" : "<process log>",
    "action" : "pkg_audit",
-    "vulnerable_pkgs" : ["pkg 1", "pkg 2"],
-    "impacts_pkgs" : ["pkg 1", "pkg 2"],
    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
+      "time_finished" : "<ISO 8601 time date string>",
      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
+      "return_codes/<command 1>" : "<code 1>",
+      "return_codes/<command 2>" : "<code 2>",
+      "process_id" : "<random>",
+      "state" : "finished"
      }
    }
- } 
+ }  

 .. index:: pkg_upgrade, pkg

@@ -771,14 +686,16 @@ instructions on how to subscribe to and query dispatcher events.
  "id" : "none",
  "args" : {
    "event_system" : "sysadm"/"pkg",
-    "state" : "running" OR "finished",
+    "state" : "finished",
    "pkg_log" : "<process log>",
    "action" : "pkg_upgrade",
    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
+      "time_finished" : "<ISO 8601 time date string>",
      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
+      "return_codes/<command 1>" : "<code 1>",
+      "return_codes/<command 2>" : "<code 2>",
+      "process_id" : "<random>",
+      "state" : "finished"
      }
    }
 }  
@@ -842,15 +759,17 @@ instructions on how to subscribe to and query dispatcher events.
  "id" : "none",
  "args" : {
    "event_system" : "sysadm/pkg",
-    "state" : "running" OR "finished",
+    "state" : "finished",
    "pkg_log" : "<process log>",
    "action" : "pkg_check_upgrade",
    "updates_available" : "true" OR "false",
    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
+      "time_finished" : "<ISO 8601 time date string>",
      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
+      "return_codes/<command 1>" : "<code 1>",
+      "return_codes/<command 2>" : "<code 2>",
+      "process_id" : "<random>",
+      "state" : "finished"
      }
    }
 }
@@ -918,14 +837,16 @@ If you include "force" = "true", it forces :command:`pkg` to completely resync a
  "id" : "none",
  "args" : {
    "event_system" : "sysadm"/"pkg",
-    "state" : "running" OR "finished",
+    "state" : "finished",
    "pkg_log" : "<process log>",
    "action" : "pkg_update",
    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
+      "time_finished" : "<ISO 8601 time date string>",
      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
+      "return_codes/<command 1>" : "<code 1>",
+      "return_codes/<command 2>" : "<code 2>",
+      "process_id" : "<random>",
+      "state" : "finished"
      }
    }
 }  
@@ -999,14 +920,16 @@ Both actions return any information as a dispatcher event. Refer to the :ref:`Di
  "id" : "none",
  "args" : {
    "event_system" : "sysadm"/"pkg",
-    "state" : "running" OR "finished",
+    "state" : "finished",
    "pkg_log" : "<process log>",
    "action" : "pkg_lock",
    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
+      "time_finished" : "<ISO 8601 time date string>",
      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
+      "return_codes/<command 1>" : "<code 1>",
+      "return_codes/<command 2>" : "<code 2>",
+      "process_id" : "<random>",
+      "state" : "finished"
      }
    }
 } 
@@ -1062,14 +985,16 @@ Both actions return any information as a dispatcher event. Refer to the :ref:`Di
  "id" : "none",
  "args" : {
    "event_system" : "sysadm"/"pkg",
-    "state" : "running" OR "finished",
+    "state" : "finished",
    "pkg_log" : "<process log>",
    "action" : "pkg_unlock",
    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
+      "time_finished" : "<ISO 8601 time date string>",
      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
+      "return_codes/<command 1>" : "<code 1>",
+      "return_codes/<command 2>" : "<code 2>",
+      "process_id" : "<random>",
+      "state" : "finished"
      }
    }
 } 
@@ -1138,14 +1063,16 @@ Unless the "repo" is specified, :command:`pkg` will automatically determine the
  "id" : "none",
  "args" : {
    "event_system" : "sysadm"/"pkg",
-    "state" : "running" OR "finished",
+    "state" : "finished",
    "pkg_log" : "<process log>",
    "action" : "pkg_install",
    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
+      "time_finished" : "<ISO 8601 time date string>",
      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
+      "return_codes/<command 1>" : "<code 1>",
+      "return_codes/<command 2>" : "<code 2>",
+      "process_id" : "<random>",
+      "state" : "finished"
      }
    }
 } 
@@ -1217,14 +1144,16 @@ The uninstall messages will be returned as a dispatcher event. Refer to the :ref
  "id" : "none",
  "args" : {
    "event_system" : "sysadm"/"pkg",
-    "state" : "running" OR "finished",
+    "state" : "finished",
    "pkg_log" : "<process log>",
    "action" : "pkg_remove",
    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
+      "time_finished" : "<ISO 8601 time date string>",
      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
+      "return_codes/<command 1>" : "<code 1>",
+      "return_codes/<command 2>" : "<code 2>",
+      "process_id" : "<random>",
+      "state" : "finished"
      }
    }
 } 
--- a/api/classes/updates.rst
+++ b/api/classes/updates.rst
@@ -229,13 +229,15 @@ The "startupdate" action starts the specified update. You must specify a "target
  "id" : "none",
  "args" : {
    "event_system" : "sysadm"/"update",
-    "state" : "running" OR "finished",
+    "state" : "finished",
    "update_log" : "<update log>",
    "process_details" : {
-      "time_started" : "<ISO 8601 time date string>",
+      "time_finished" : "<ISO 8601 time date string>",
      "cmd_list" : ["<command 1>", "<command 2>"],
-      "process_id" : "<some id string>",
-      "state" : "running"
+      "return_codes/<command 1>" : "<code 1>",
+      "return_codes/<command 2>" : "<code 2>",
+      "process_id" : "<random>",
+      "state" : "finished"
      }
    }
 }
--- a/api/connection.rst
+++ b/api/connection.rst
@@ -3,10 +3,17 @@
 Getting Started
 ***************

-Some intro text here...
+.. Some intro text here...

+Welcome to the SysAdm™ API (application programming interface) documentation handbook!
+SysAdm™ is a complex utility with many integral subsystems and classes, and this handbook will attempt to 
+guide a new user through the initialization, core features, and intricacies of the utility.

-Add some links to docs on websockets and json....
+.. Add some links to docs on websockets and json
+
+This handbook will be heavily utilizing the Websocket specification and JSON (JavaScript Object Notation) format.
+For detailed descriptions of these items,
+please refer to their respective websites at http://www.websocket.org and http://json.org/. 

 .. _Authentication:

@@ -287,7 +294,7 @@ This response indicates that a dispatcher event occurred:
  "id" : "",
  "args" : {
    "name" : "dispatcher",
-    "args" : "<message"
+    "args" : "<message>"
    }
  }

--- a/api/events.rst
+++ b/api/events.rst
@@ -130,7 +130,9 @@ The following sample logs will reflect the differences between these states:
 "args" : {
   "state" : "finished",
   "time_finished" : "<ISO 8601 time date string>",
-   "return_codes" : ["<code 1>", "<code 2>"],
+   "cmd_list" : ["<command 1>", "<command 2>"],
+   "return_codes/<command 1>" : "<code 1>",
+   "return_codes/<command 2>" : "<code 2>",
   "process_id" : "<random>"
   }
 }
--- a/api/index.rst
+++ b/api/index.rst
@@ -6,6 +6,7 @@ PC-BSD® API Reference
   :maxdepth: 4

   connection
+   events
   classes/index

 Indices and tables