Add API's from core_jobs.c (#85)

* Add API's from core_jobs.c. 

* Include stdbool.h.

* add coreJSON as dependency, new API's need it for parsing.

* CBMC proofs for API's added.

*Unit Tests for API's added.

Co-authored-by: GitHub Action <[email protected]>

.github/memory_statistics_config.json

@@ -1,9 +1,11 @@
 {
     "lib_name": "AWS IoT Jobs",
     "src": [
-        "source/jobs.c"
+        "source/jobs.c",
+        "coreJSON/source/core_json.c"
     ],
     "include": [
-        "source/include"
+        "source/include",
+        "coreJSON/source/include"
     ]
 }

.github/workflows/ci.yml

@@ -88,8 +88,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-        with:
-          submodules: "recursive"
+      - name: Clone coreJSON
+        run: git clone https://github.com/FreeRTOS/coreJSON.git --depth 1 --branch v3.2.0
       - name: Install Python3
         uses: actions/setup-python@v3
         with:
@@ -132,4 +132,5 @@ jobs:
       - name: Run CBMC
         uses: FreeRTOS/CI-CD-Github-Actions/run_cbmc@main
         with:
-          proofs_dir: test/cbmc/proofs
+          proofs_dir: test/cbmc
+          run_cbmc_proofs_command: ./run_proofs.sh

.gitmodules

@@ -1,4 +1,4 @@
 [submodule "test/unit-test/Unity"]
 	path = test/unit-test/Unity
 	url = https://github.com/ThrowTheSwitch/Unity
-	update = none
+	update = none

README.md

@@ -40,27 +40,32 @@ release.**
 
 ## Building the Jobs library
 
-A compiler that supports **C90 or later** such as _gcc_ is required to build the
+A compiler that supports **C99 or later** such as _gcc_ is required to build the
 library.
 
+Additionally, coreJSON is required for parsing. To build the library, first run:
+```bash
+git clone https://github.com/FreeRTOS/coreJSON.git --depth 1 --branch v3.2.0
+```
+
 Given an application in a file named `example.c`, _gcc_ can be used like so:
 
 ```bash
-gcc -I source/include example.c source/jobs.c -o example
+gcc -I source/include -I coreJSON/source/include example.c coreJSON/source/core_json.c source/jobs.c -o example
 ```
 
 _gcc_ can also produce an object file to be linked later:
 
 ```bash
-gcc -I source/include -c source/jobs.c
+gcc -I source/include -I coreJSON/source/include -c source/jobs.c
 ```
 
 ## CBMC
 
 To learn more about CBMC and proofs specifically, review the training material
 [here](https://model-checking.github.io/cbmc-training).
 
-The `test/cbmc/proofs` directory contains CBMC proofs.
+The `test/cbmc` directory contains CBMC proofs.
 
 In order to run these proofs you will need to install CBMC and other tools by
 following the instructions
@@ -115,7 +120,7 @@ git submodule update --checkout --init --recursive --test/unit-test/Unity
 ### Platform Prerequisites
 
 - For running unit tests
-  - C90 compiler like gcc
+  - C99 compiler like gcc
   - CMake 3.13.0 or later
   - Ruby 2.0.0 or later is additionally required for the Unity test framework
     (that we use).

docs/doxygen/include/size_table.md

@@ -9,12 +9,17 @@
     </tr>
     <tr>
         <td>jobs.c</td>
-        <td><center>1.9K</center></td>
-        <td><center>1.6K</center></td>
+        <td><center>2.8K</center></td>
+        <td><center>2.5K</center></td>
+    </tr>
+    <tr>
+        <td>core_json.c</td>
+        <td><center>2.9K</center></td>
+        <td><center>2.4K</center></td>
     </tr>
     <tr>
         <td><b>Total estimates</b></td>
-        <td><b><center>1.9K</center></b></td>
-        <td><b><center>1.6K</center></b></td>
+        <td><b><center>5.7K</center></b></td>
+        <td><b><center>4.9K</center></b></td>
     </tr>
 </table>

source/include/jobs.h

@@ -32,6 +32,7 @@
 #ifndef JOBS_H_
 #define JOBS_H_
 
+#include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
 
@@ -41,6 +42,13 @@
 #endif
 /* *INDENT-ON* */
 
+/**
+ * @ingroup jobs_constants
+ * @brief  Size of Topic Buffer
+ */
+#define TOPIC_BUFFER_SIZE    256U
+
+
 /**
  * @ingroup jobs_constants
  * @brief Maximum length of a thing name for the AWS IoT Jobs Service.
@@ -86,41 +94,50 @@
  * Doxygen should ignore these macros as they are private.
  */
 
-#define JOBS_API_PREFIX                   "$aws/things/"
-#define JOBS_API_PREFIX_LENGTH            ( sizeof( JOBS_API_PREFIX ) - 1U )
+#define JOBS_API_PREFIX                     "$aws/things/"
+#define JOBS_API_PREFIX_LENGTH              ( sizeof( JOBS_API_PREFIX ) - 1U )
+
+#define JOBS_API_BRIDGE                     "/jobs/"
+#define JOBS_API_BRIDGE_LENGTH              ( sizeof( JOBS_API_BRIDGE ) - 1U )
 
-#define JOBS_API_BRIDGE                   "/jobs/"
-#define JOBS_API_BRIDGE_LENGTH            ( sizeof( JOBS_API_BRIDGE ) - 1U )
+#define JOBS_API_SUCCESS                    "/accepted"
+#define JOBS_API_SUCCESS_LENGTH             ( sizeof( JOBS_API_SUCCESS ) - 1U )
 
-#define JOBS_API_SUCCESS                  "/accepted"
-#define JOBS_API_SUCCESS_LENGTH           ( sizeof( JOBS_API_SUCCESS ) - 1U )
+#define JOBS_API_FAILURE                    "/rejected"
+#define JOBS_API_FAILURE_LENGTH             ( sizeof( JOBS_API_FAILURE ) - 1U )
 
-#define JOBS_API_FAILURE                  "/rejected"
-#define JOBS_API_FAILURE_LENGTH           ( sizeof( JOBS_API_FAILURE ) - 1U )
+#define JOBS_API_JOBSCHANGED                "notify"
+#define JOBS_API_JOBSCHANGED_LENGTH         ( sizeof( JOBS_API_JOBSCHANGED ) - 1U )
 
-#define JOBS_API_JOBSCHANGED              "notify"
-#define JOBS_API_JOBSCHANGED_LENGTH       ( sizeof( JOBS_API_JOBSCHANGED ) - 1U )
+#define JOBS_API_NEXTJOBCHANGED             "notify-next"
+#define JOBS_API_NEXTJOBCHANGED_LENGTH      ( sizeof( JOBS_API_NEXTJOBCHANGED ) - 1U )
 
-#define JOBS_API_NEXTJOBCHANGED           "notify-next"
-#define JOBS_API_NEXTJOBCHANGED_LENGTH    ( sizeof( JOBS_API_NEXTJOBCHANGED ) - 1U )
+#define JOBS_API_GETPENDING                 "get"
+#define JOBS_API_GETPENDING_LENGTH          ( sizeof( JOBS_API_GETPENDING ) - 1U )
 
-#define JOBS_API_GETPENDING               "get"
-#define JOBS_API_GETPENDING_LENGTH        ( sizeof( JOBS_API_GETPENDING ) - 1U )
+#define JOBS_API_STARTNEXT                  "start-next"
+#define JOBS_API_STARTNEXT_LENGTH           ( sizeof( JOBS_API_STARTNEXT ) - 1U )
 
-#define JOBS_API_STARTNEXT                "start-next"
-#define JOBS_API_STARTNEXT_LENGTH         ( sizeof( JOBS_API_STARTNEXT ) - 1U )
+#define JOBS_API_DESCRIBE                   "get"
+#define JOBS_API_DESCRIBE_LENGTH            ( sizeof( JOBS_API_DESCRIBE ) - 1U )
 
-#define JOBS_API_DESCRIBE                 "get"
-#define JOBS_API_DESCRIBE_LENGTH          ( sizeof( JOBS_API_DESCRIBE ) - 1U )
+#define JOBS_API_UPDATE                     "update"
+#define JOBS_API_UPDATE_LENGTH              ( sizeof( JOBS_API_UPDATE ) - 1U )
 
-#define JOBS_API_UPDATE                   "update"
-#define JOBS_API_UPDATE_LENGTH            ( sizeof( JOBS_API_UPDATE ) - 1U )
+#define JOBS_API_JOBID_NEXT                 "$next"
+#define JOBS_API_JOBID_NEXT_LENGTH          ( sizeof( JOBS_API_JOBID_NEXT ) - 1U )
 
-#define JOBS_API_JOBID_NEXT               "$next"
-#define JOBS_API_JOBID_NEXT_LENGTH        ( sizeof( JOBS_API_JOBID_NEXT ) - 1U )
+#define JOBS_API_JOBID_NULL                 ""
+#define JOBS_API_LEVEL_SEPARATOR            "/"
 
-#define JOBS_API_JOBID_NULL               ""
-#define JOBS_API_LEVEL_SEPARATOR          "/"
+#define JOBS_API_CLIENTTOKEN                "{\"clientToken\":\""
+#define JOBS_API_CLIENTTOKEN_LENGTH         ( sizeof( JOBS_API_CLIENTTOKEN ) - 1U )
+
+#define JOBS_API_STATUS                     "{\"status\":\""
+#define JOBS_API_STATUS_LENGTH              ( sizeof( JOBS_API_STATUS ) - 1U )
+
+#define JOBS_API_EXPECTED_VERSION           "\",\"expectedVersion\":\""
+#define JOBS_API_EXPECTED_VERSION_LENGTH    ( sizeof( JOBS_API_EXPECTED_VERSION ) - 1U )
 
 #define JOBS_API_COMMON_LENGTH( thingNameLength ) \
     ( JOBS_API_PREFIX_LENGTH + ( thingNameLength ) + JOBS_API_BRIDGE_LENGTH )
@@ -232,6 +249,27 @@ typedef enum
     JobsBufferTooSmall /**< @brief The buffer write was truncated. */
 } JobsStatus_t;
 
+/**
+ * @brief Status codes for jobs
+ */
+typedef enum JobCurrentStatus
+{
+    Queued,
+    InProgress,
+    Failed,
+    Succeeded,
+    Rejected
+} JobCurrentStatus_t;
+
+/**
+ * @brief Status codes for job update status
+ */
+typedef enum JobUpdateStatus
+{
+    JobUpdateStatus_Accepted,
+    JobUpdateStatus_Rejected
+} JobUpdateStatus_t;
+
 /**
  * @ingroup jobs_enum_types
  * @brief Topic values for subscription requests.
@@ -585,6 +623,22 @@ JobsStatus_t Jobs_StartNext( char * buffer,
                              size_t * outLength );
 /* @[declare_jobs_startnext] */
 
+/**
+ * @brief Populate a message string for a StartNextPendingJobExecution request.
+ *
+ * @param clientToken The device's token
+ * @param clientTokenLength The expected length of the clientToken
+ * @param buffer The buffer to be written to
+ * @param bufferSize The size of the buffer
+ *
+ * @return 0 if write to buffer fails
+ * @return The message length if the write is successful
+ */
+size_t Jobs_StartNextMsg( const char * clientToken,
+                          size_t clientTokenLength,
+                          char * buffer,
+                          size_t bufferSize );
+
 /**
  * @brief Populate a topic string for a DescribeJobExecution request.
  *
@@ -742,6 +796,85 @@ JobsStatus_t Jobs_Update( char * buffer,
                           size_t * outLength );
 /* @[declare_jobs_update] */
 
+/**
+ * @brief Populate a message string for an UpdateJobExecution request.
+ *
+ * @param status Current status of the job
+ * @param expectedVersion The version that is expected
+ * @param expectedVersionLength The length of the expectedVersion string
+ * @param buffer The buffer to be written to
+ * @param bufferSize the size of the buffer
+ *
+ * @return 0 if write to buffer fails
+ * @return messageLength if the write is successful
+ */
+size_t Jobs_UpdateMsg( JobCurrentStatus_t status,
+                       char * expectedVersion,
+                       size_t expectedVersionLength,
+                       char * buffer,
+                       size_t bufferSize );
+
+/**
+ * @brief Retrieves the job ID from a given message (if applicable)
+ *
+ * @param message [In] A JSON formatted message which
+ * @param messageLength [In] The length of the message
+ * @param jobId [Out] The job ID
+ * @return size_t The job ID length
+ */
+size_t Jobs_GetJobId( const char * message,
+                      size_t messageLength,
+                      char ** jobId );
+
+/**
+ * @brief Retrieves the job document from a given message (if applicable)
+ *
+ * @param message [In] A JSON formatted message which
+ * @param messageLength [In] The length of the message
+ * @param jobDoc [Out] The job document
+ * @return size_t The length of the job document
+ */
+size_t Jobs_GetJobDocument( const char * message,
+                            size_t messageLength,
+                            char ** jobDoc );
+
+/**
+ * @brief Checks if a message comes from the start-next/accepted reserved topic
+ *
+ * @param topic The topic to check against
+ * @param topicLength The expected topic length
+ * @param thingName The device's thingName as registered with AWS IoT.
+ * @param thingNameLength The length of the thingName.
+ * @return true If the topic is the start-next/accepted topic
+ * @return false If the topic is not the start-next/accepted topic
+ */
+bool Jobs_IsStartNextAccepted( const char * topic,
+                               const size_t topicLength,
+                               const char * thingName,
+                               const size_t thingNameLength );
+
+/**
+ * @brief Checks if a message comes from the update/accepted reserved topic
+ *
+ * @param topic The topic to check against
+ * @param topicLength The expected topic length
+ * @param jobId Corresponding Job ID which the update was accepted for
+ * @param jobIdLength The Job ID length
+ * @param thingName The device's thingName as registered with AWS IoT.
+ * @param thingNameLength The length of the thingName.
+ * @param expectedStatus The job update status reported by AWS IoT Jobs
+ * @return true If the topic is the update/\<expectedStatus\> topic
+ * @return false If the topic is not the update/\<expectedStatus\> topic
+ */
+bool Jobs_IsJobUpdateStatus( const char * topic,
+                             const size_t topicLength,
+                             const char * jobId,
+                             const size_t jobIdLength,
+                             const char * thingName,
+                             const size_t thingNameLength,
+                             JobUpdateStatus_t expectedStatus );
+
+
 /* *INDENT-OFF* */
 #ifdef __cplusplus
     }