Merge remote-tracking branch 'origin/dev' into feature/2350-confirm-action-observation-space-conforms-to-CAOS-0.7

docs/source/request_system.rst

@@ -3,7 +3,7 @@
     © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
 
 Request System
-==============
+**************
 
 ``SimComponent`` objects in the simulation are decoupled from the agent training logic. However, they still need a managed means of accepting requests to perform actions. For this, they use ``RequestManager`` and ``RequestType``.
 
@@ -12,26 +12,37 @@ Just like other aspects of SimComponent, the request types are not managed centr
 - API
     When requesting an action within the simulation, these two arguments must be provided:
 
-    1. ``request`` - selects which action you want to take on this ``SimComponent``. This is formatted as a list of strings such as `['network', 'node', '<node-name>', 'service', '<service-name>', 'restart']`.
+    1. ``request`` - selects which action you want to take on this ``SimComponent``. This is formatted as a list of strings such as ``['network', 'node', '<node-name>', 'service', '<service-name>', 'restart']``.
     2. ``context`` - optional extra information that can be used to decide how to process the request. This is formatted as a dictionary. For example, if the request requires authentication, the context can include information about the user that initiated the request to decide if their permissions are sufficient.
 
+    When a request is resolved, it returns a success status, and optional additional data about the request.
+
+    ``status`` can be one of:
+
+    * ``success``: the request was executed
+    * ``failure``: the request could not be executed
+    * ``unreachable``: the target for the request was not found
+    * ``pending``: the request was initiated, but has not finished during this step
+
+    ``data`` can be a dictionary with any arbitrary JSON-like data to describe the outcome of the request.
+
 - ``request`` detail
     The request is a list of strings which help specify who should handle the request. The strings in the request list help RequestManagers traverse the 'ownership tree' of SimComponent. The example given above would be handled in the following way:
 
-    1. ``Simulation`` receives `['network', 'node', '<node-name>', 'service', '<service-name>', 'restart']`.
+    1. ``Simulation`` receives ``['network', 'node', 'computer_1', 'service', 'DNSService', 'restart']``.
         The first element of the request is ``network``, therefore it passes the request down to its network.
-    2. ``Network`` receives `['node', '<node-name>', 'service', '<service-name>', 'restart']`.
+    2. ``Network`` receives ``['node', 'computer_1', 'service', 'DNSService', 'restart']``.
         The first element of the request is ``node``, therefore the network looks at the node name and passes the request down to the node with that name.
-    3. ``Node`` receives `['service', '<service-name>', 'restart']`.
+    3. ``computer_1`` receives ``['service', 'DNSService', 'restart']``.
         The first element of the request is ``service``, therefore the node looks at the service name and passes the rest of the request to the service with that name.
-    4. ``Service`` receives ``['restart']``.
+    4. ``DNSService`` receives ``['restart']``.
         Since ``restart`` is a defined request type in the service's own RequestManager, the service performs a restart.
 
 - ``context`` detail
     The context is not used by any of the currently implemented components or requests.
 
 Technical Detail
-----------------
+================
 
 This system was achieved by implementing two classes, :py:class:`primaite.simulator.core.RequestType`, and :py:class:`primaite.simulator.core.RequestManager`.
 
@@ -93,3 +104,19 @@ An example of how this works is in the :py:class:`primaite.simulator.network.har
             self._service_request_manager.add_request(service.name, RequestType(func=service._request_manager))
 
 This process is repeated until the request word corresponds to a callable function rather than another ``RequestManager`` .
+
+Request Validation
+------------------
+
+There are times when a request should be rejected. For instance, if an agent attempts to run an application on a node that is currently off. For this purpose, requests are filtered by an object called a validator. :py:class:`primaite.simulator.core.RequestPermissionValidator` is a basic class whose ``__call__()`` method returns ``True`` if the request should be permitted or ``False`` if it cannot be permitted. For example, the Node class has a validator called :py:class:`primaite.simulator.network.hardware.base.Node._NodeIsOnValidator<_NodeIsOnValidator>` which allows requests only when the operating status of the node is ``ON``.
+
+Requests that are specified without a validator automatically get assigned an ``AllowAllValidator`` which allows requests no matter what.
+
+Request Response
+----------------
+
+The :py:class:`primaite.interface.request.RequestResponse<RequestResponse>` is a data transfer object that carries response data between the simulator and the game layer. The ``status`` field reports on the success or failure, and the ``data`` field is for any additional data. The most common way that this class is initiated is by its ``from_bool`` method. This way, given a True or False, a successful or failed request response is generated, respectively (with an empty data field).
+
+For instance, the ``execute`` action on a :py:class:`primaite.simulator.system.applications.web_browser.WebBrowser<WebBrowser>` calls the ``get_webpage()`` method of the ``WebBrowser``. ``get_webpage()`` returns a True if the webpage was successfully retrieved, and False if unsuccessful for any reason, such as being blocked by an ACL, or if the database server is unresponsive. The boolean returned from ``get_webpage()`` is used to create the request response.
+
+Just as the requests themselves were passed from owner to component, the request response is bubbled back up from component to owner until it arrives at the game layer.

docs/source/state_system.rst

@@ -5,9 +5,9 @@
 Simulation State
 ================
 
-``SimComponent`` objects in the simulation have a method called ``describe_state`` which return a dictionary of the state of the component. This is used to report pertinent data that could impact an agent's actions or rewards. For instance, the name and health status of a node is reported, which can be used by a reward function to punish corrupted or compromised nodes and reward healthy nodes. Each ``SimComponent`` object reports not only its own attributes in the state but also those of its child components. I.e. a computer node will report the state of its ``FileSystem`` and the ``FileSystem`` will report the state of its files and folders. This happens by recursively calling the childrens' own ``describe_state`` methods.
+``SimComponent`` objects in the simulation have a method called ``describe_state`` which return a dictionary of the state of the component. This is used to report pertinent data that could impact an agent's actions or rewards. For instance, the name and health status of a node is reported, which can be used by a reward function to punish corrupted or compromised nodes and reward healthy nodes. Each ``SimComponent`` object reports not only its own attributes in the state but also those of its child components. I.e. a computer node will report the state of its ``FileSystem`` and the ``FileSystem`` will report the state of its files and folders. This happens by recursively calling the children's own ``describe_state`` methods.
 
-The game layer calls ``describe_state`` on the trunk ``SimComponent`` (the top-level parent) and then passes the state to the agents once per simulation step. For this reason, all ``SimComponent`` objetcs must have a ``describe_state`` method, and they must all be linked to the trunk ``SimComponent``.
+The game layer calls ``describe_state`` on the trunk ``SimComponent`` (the top-level parent) and then passes the state to the agents once per simulation step. For this reason, all ``SimComponent`` objects must have a ``describe_state`` method, and they must all be linked to the trunk ``SimComponent``.
 
 This code snippet demonstrates how the state information is defined within the ``SimComponent`` class: