diff --git a/.github/.cSpellWords.txt b/.github/.cSpellWords.txt new file mode 100644 index 00000000..1a4c8cb9 --- /dev/null +++ b/.github/.cSpellWords.txt @@ -0,0 +1,28 @@ +CBMC +CBOR +CMOCK +CMock +Cmock +Coverity +DCMOCK +DNDEBUG +DUNITY +Doesnt +LLHTTP +MISRA +MQTT +Misra +Wunused +abcdefghijk +abcdefghijklmnopqrstuvwxyzabcdefghijklmnopq +cbmc +cbor +cmock +coverity +ctest +lcov +llhttp +lmnopqrstuvw +misra +sinclude +utest diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e2d51615..4590f56b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,7 +12,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Build run: | sudo apt-get install -y lcov @@ -21,11 +21,10 @@ jobs: -DCMAKE_BUILD_TYPE=Debug \ -DCMAKE_C_FLAGS='--coverage -Wall -Wextra -DNDEBUG' make -C build/ all - - name: Test - run: | - cd build/ - ctest -E system --output-on-failure - cd .. + + - name: Run CTests + run: ctest --test-dir build -E system --output-on-failure + - name: Run Coverage run: | make -C build/ coverage @@ -35,49 +34,54 @@ jobs: - name: Check Coverage uses: FreeRTOS/CI-CD-Github-Actions/coverage-cop@main with: - path: ./build/coverage.info + coverage-file: ./build/coverage.info + complexity: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Check complexity uses: FreeRTOS/CI-CD-Github-Actions/complexity@main with: path: ./ + doxygen: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Run doxygen build uses: FreeRTOS/CI-CD-Github-Actions/doxygen@main with: path: ./ + spell-check: runs-on: ubuntu-latest steps: - name: Clone This Repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Run spellings check uses: FreeRTOS/CI-CD-Github-Actions/spellings@main with: path: ./ + formatting: runs-on: ubuntu-20.04 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Check formatting uses: FreeRTOS/CI-CD-Github-Actions/formatting@main with: path: ./ + ssot-check: runs-on: ubuntu-latest steps: - name: Checkout this repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: path: current - name: Checkout coreMQTT - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: ref: main repository: FreeRTOS/coreMQTT @@ -93,12 +97,13 @@ jobs: else exit 0 fi + git-secrets: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Checkout awslabs/git-secrets - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: repository: awslabs/git-secrets ref: master @@ -109,22 +114,57 @@ jobs: run: | git-secrets --register-aws git-secrets --scan + memory_statistics: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 with: - submodules: 'recursive' + submodules: "recursive" - name: Install Python3 - uses: actions/setup-python@v2 + uses: actions/setup-python@v3 with: - python-version: '3.11.0' + python-version: "3.11.0" - name: Measure sizes uses: FreeRTOS/CI-CD-Github-Actions/memory_statistics@main with: - config: .github/memory_statistics_config.json - check_against: docs/doxygen/include/size_table.md + config: .github/memory_statistics_config.json + check_against: docs/doxygen/include/size_table.md + + link-verifier: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Check Links + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + uses: FreeRTOS/CI-CD-Github-Actions/link-verifier@main + with: + path: ./ + + verify-manifest: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + submodules: true + fetch-depth: 0 + + # At time of writing the gitmodules are set not to pull + # Even when using fetch submodules. Need to run this command + # To force it to grab them. + - name: Perform Recursive Clone + shell: bash + run: git submodule update --checkout --init --recursive + + - name: Run manifest verifier + uses: FreeRTOS/CI-CD-GitHub-Actions/manifest-verifier@main + with: + path: ./ + fail-on-incorrect-version: true + proof_ci: + if: ${{ github.event.pull_request }} runs-on: cbmc_ubuntu-latest_64-core steps: - name: Set up CBMC runner diff --git a/.github/workflows/formatting.yml b/.github/workflows/formatting.yml new file mode 100644 index 00000000..8257adda --- /dev/null +++ b/.github/workflows/formatting.yml @@ -0,0 +1,23 @@ +name: Format Pull Request Files + +on: + issue_comment: + types: [created] + +env: + bashPass: \033[32;1mPASSED - + bashInfo: \033[33;1mINFO - + bashFail: \033[31;1mFAILED - + bashEnd: \033[0m + +jobs: + Formatting: + name: Run Formatting Check + if: ${{ github.event.issue.pull_request }} && + ( ( github.event.comment.body == '/bot run uncrustify' ) || + ( github.event.comment.body == '/bot run formatting' ) ) + runs-on: ubuntu-20.04 + steps: + - name: Apply Formatting Fix + uses: FreeRTOS/CI-CD-Github-Actions/formatting-bot@main + id: check-formatting diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 43c033c4..c1802545 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -16,7 +16,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: ref: ${{ github.event.inputs.commit_id }} - name: Configure git identity @@ -53,7 +53,7 @@ jobs: - name: Install ZIP tools run: sudo apt-get install zip unzip - name: Checkout code - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: ref: ${{ github.event.inputs.commit_id }} path: coreHTTP diff --git a/MISRA.md b/MISRA.md index 296b961f..f2b350de 100644 --- a/MISRA.md +++ b/MISRA.md @@ -92,4 +92,4 @@ _Ref 21.13.1_ - MISRA Rule 21.13 flags any value passed into a ctype.h function that isn't cast as an unsigned char. Thorough testing by use of our CBMC proofs shows that adding the cast to ( unsigned char ) inside of the toupper() call has potential to lead - to errors. Due to this we supress this warning for our use case. + to errors. Due to this we suppress this warning for our use case. diff --git a/README.md b/README.md index a950f89f..1dce2004 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,45 @@ # coreHTTP Client Library +**[API Documentation Pages for current and previous releases of this library can be found here](https://freertos.github.io/coreHTTP/)** + + This repository contains a C language HTTP client library designed for embedded platforms. It has no dependencies on any additional libraries other than the -standard C library, [llhttp](https://github.com/nodejs/llhttp), and -a customer-implemented transport interface. This library is distributed under -the [MIT Open Source License](LICENSE). +standard C library, [llhttp](https://github.com/nodejs/llhttp), and a +customer-implemented transport interface. This library is distributed under the +[MIT Open Source License](LICENSE). This library has gone through code quality checks including verification that no -function has a [GNU Complexity](https://www.gnu.org/software/complexity/manual/complexity.html) +function has a +[GNU Complexity](https://www.gnu.org/software/complexity/manual/complexity.html) score over 8. This library has also undergone both static code analysis from [Coverity static analysis](https://scan.coverity.com/), and validation of memory safety and data structure invariance through the [CBMC automated reasoning tool](https://www.cprover.org/cbmc/). -See memory requirements for this library [here](./docs/doxygen/include/size_table.md). +See memory requirements for this library +[here](./docs/doxygen/include/size_table.md). -**coreHTTP v3.0.0 [source code](https://github.com/FreeRTOS/coreHTTP/tree/v3.0.0/source) is part of the [FreeRTOS 202210.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202210.00-LTS) release.** +**coreHTTP v3.0.0 +[source code](https://github.com/FreeRTOS/coreHTTP/tree/v3.0.0/source) is part +of the +[FreeRTOS 202210.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202210.00-LTS) +release.** -**coreHTTP v2.0.0 [source code](https://github.com/FreeRTOS/coreHTTP/tree/v2.0.0/source) is part of the [FreeRTOS 202012.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202012.00-LTS) release.** +**coreHTTP v2.0.0 +[source code](https://github.com/FreeRTOS/coreHTTP/tree/v2.0.0/source) is part +of the +[FreeRTOS 202012.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202012.00-LTS) +release.** ## coreHTTP Config File The HTTP client library exposes configuration macros that are required for building the library. A list of all the configurations and their default values -are defined in [core_http_config_defaults.h](source/include/core_http_config_defaults.h). -To provide custom values for the configuration macros, a custom config file -named `core_http_config.h` can be provided by the user application to the library. +are defined in +[core_http_config_defaults.h](source/include/core_http_config_defaults.h). To +provide custom values for the configuration macros, a custom config file named +`core_http_config.h` can be provided by the user application to the library. By default, a `core_http_config.h` custom config is required to build the library. To disable this requirement and build the library with default @@ -33,11 +47,11 @@ configuration values, provide `HTTP_DO_NOT_USE_CUSTOM_CONFIG` as a compile time preprocessor macro. **The HTTP client library can be built by either**: -* Defining a `core_http_config.h` file in the application, and adding it to the -include directories for the library build. -**OR** -* Defining the `HTTP_DO_NOT_USE_CUSTOM_CONFIG` preprocessor macro for the -library build. + +- Defining a `core_http_config.h` file in the application, and adding it to the + include directories for the library build. **OR** +- Defining the `HTTP_DO_NOT_USE_CUSTOM_CONFIG` preprocessor macro for the + library build. ## Building the Library @@ -58,19 +72,20 @@ file, refer to the `coverity_analysis` library target in ### Platform Prerequisites - For running unit tests, the following are required: - - **C90 compiler** like gcc - - **CMake 3.13.0 or later** - - **Ruby 2.0.0 or later** is required for this repository's - [CMock test framework](https://github.com/ThrowTheSwitch/CMock). + - **C90 compiler** like gcc + - **CMake 3.13.0 or later** + - **Ruby 2.0.0 or later** is required for this repository's + [CMock test framework](https://github.com/ThrowTheSwitch/CMock). - For running the coverage target, the following are required: - - **gcov** - - **lcov** + - **gcov** + - **lcov** ### Steps to build **Unit Tests** 1. Go to the root directory of this repository. -1. Run the *cmake* command: `cmake -S test -B build -DBUILD_CLONE_SUBMODULES=ON ` +1. Run the _cmake_ command: + `cmake -S test -B build -DBUILD_CLONE_SUBMODULES=ON ` 1. Run this command to build the library and unit tests: `make -C build all` @@ -80,33 +95,43 @@ file, refer to the `coverity_analysis` library target in ## CBMC - To learn more about CBMC and proofs specifically, review the training material [here](https://model-checking.github.io/cbmc-training). +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. -In order to run these proofs you will need to install CBMC and other tools by following the instructions [here](https://model-checking.github.io/cbmc-training/installation.html). +In order to run these proofs you will need to install CBMC and other tools by +following the instructions +[here](https://model-checking.github.io/cbmc-training/installation.html). ## Reference examples -The AWS IoT Device SDK for Embedded C repository contains demos of using the HTTP client -library [here](https://github.com/aws/aws-iot-device-sdk-embedded-C/tree/main/demos/http) -on a POSIX platform. These can be used as reference examples for the library API. +The AWS IoT Device SDK for Embedded C repository contains demos of using the +HTTP client library +[here](https://github.com/aws/aws-iot-device-sdk-embedded-C/tree/main/demos/http) +on a POSIX platform. These can be used as reference examples for the library +API. ## Documentation ### Existing Documentation -For pre-generated documentation, please see the documentation linked in the locations below: -| Location | -| :-: | +For pre-generated documentation, please see the documentation linked in the +locations below: + +| Location | +| :------------------------------------------------------------------------------------------------------------------: | | [AWS IoT Device SDK for Embedded C](https://github.com/aws/aws-iot-device-sdk-embedded-C#releases-and-documentation) | -| [FreeRTOS.org](https://freertos.org/Documentation/api-ref/coreHTTP/docs/doxygen/output/html/index.html) | +| [FreeRTOS.org](https://freertos.org/Documentation/api-ref/coreHTTP/docs/doxygen/output/html/index.html) | -Note that the latest included version of coreHTTP may differ across repositories. +Note that the latest included version of coreHTTP may differ across +repositories. ### Generating Documentation + The Doxygen references were created using Doxygen version 1.9.2. To generate the -Doxygen pages, please run the following command from the root of this repository: +Doxygen pages, please run the following command from the root of this +repository: ```shell doxygen docs/doxygen/config.doxyfile @@ -114,4 +139,5 @@ doxygen docs/doxygen/config.doxyfile ## Contributing -See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on contributing. +See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on +contributing. diff --git a/cspell.config.yaml b/cspell.config.yaml new file mode 100644 index 00000000..911ce1d8 --- /dev/null +++ b/cspell.config.yaml @@ -0,0 +1,31 @@ +--- +$schema: https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json +version: '0.2' +# Allows things like stringLength +allowCompoundWords: true + +# Read files not to spell check from the git ignore +useGitignore: true + +# Language settings for C +languageSettings: + - caseSensitive: false + enabled: true + languageId: c + locale: "*" + +# Add a dictionary, and the path to the word list +dictionaryDefinitions: + - name: freertos-words + path: '.github/.cSpellWords.txt' + addWords: true + +dictionaries: + - freertos-words + +# Paths and files to ignore +ignorePaths: + - 'dependency' + - 'docs' + - 'ThirdParty' + - 'History.txt' diff --git a/lexicon.txt b/lexicon.txt deleted file mode 100644 index a8aa0a01..00000000 --- a/lexicon.txt +++ /dev/null @@ -1,288 +0,0 @@ -absolutevalue -addheader -addrangeheader -addrangeheaders -addrangerequest -addtogroup -aggregator -api -apis -ascii -aws -bool -br -bufferlen -bufferlength -bytesreceived -bytesremaining -bytessent -bytestorecv -bytestosend -calltlsrecvfunc -cb -cbmc -chk -chunked -colspan -com -cond -config -configpagestyle -const -contentlength -convertint -copybrief -copydoc -corehttp -coverity -cprover -css -datalen -datelen -defgroup -doesn -doxygen -endcode -endcond -endif -enums -eof -errno -expectedheader -fieldfound -fieldlen -fieldlentoreturn -fieldloc -findheadercontext -findheaderfieldparsercallback -findheaderinresponse -findheaderonheadercompletecallback -findheadervalueparsercallback -firstpartbytes -freertos -gcc -getfinalresponsestatus -gettime -gettimestampms -github -headercount -headerslen -hostlen -hpe -html -http -httpclient -httpheadernotfound -httpheaderstrncpy -httpinsufficientmemory -httpinvalidparameter -httpinvalidresponse -httplibrarystatus -httpnetworkerror -httpnoresponse -httpparseonstatusfieldcallback -httpparser -httpparserinternalerror -httpparseronbodycallback -httpparseronheaderfieldcallback -httpparseronheaderscompletecallback -httpparseronheadervaluecallback -httpparseronmessagebegincallback -httpparseronmessagecompletecallback -httpparseronstatuscallback -httpparserxxxxcallback -httpparserxxxxcallbacks -httpparsingcontext -httpparsingstate -httppartialresponse -httprequestheaders -httprequestinfo -httpresponse -https -httpsecurityalertextraneousresponsedata -httpsecurityalertinvalidcontentlength -httpsecurityalertinvalidcharacter -httpsecurityalertinvalidchunkheader -httpsecurityalertinvalidprotocolversion -httpsecurityalertinvalidstatuscode -httpstatus -httpsuccess -ietf -ifndef -inbetween -inc -ingroup -init -initializerequestheaders -int -iot -ioveccount -ip -isfield -isheaderresponse -isheadresponse -iso -lastheaderfieldlen -lastheadervaluelen -latin -len -linux -llhttp -llhttpparser -llhttpsettings -logdebug -logerror -loginfo -logwarn -mainpage -malloc -md -memcpy -memmove -methodlen -min -misra -mit -mqtt -msg -mynetworkrecvimplementation -mynetworksendimplementation -myplatformnetworkcontext -myplatformtransportreceive -myplatformtransportsend -mytcpsocketcontext -mytlscontext -networkcontext -nodejs -noninfringement -ok -onbody -onheadercallback -onheaderfield -onheaderscomplete -onheadervalue -onmessagebegin -onmessagecomplete -onstatus -ored -org -os -param -parsehttpresponse -parselen -parsersettings -parsingstate -pathlen -pbuffer -pbuffercur -pbytesreceived -pcontext -pdata -pdateloc -pdest -pfield -pfieldloc -pfindheadercontext -pheaderparsingcallback -pheaders -phost -phttpparser -phttpparsingcontext -piovec -plaintext -plastheaderfield -plastheadervalue -ploc -psrc -pmethod -pname -pnetworkcontext -pnetworkdata -pnext -pnextwriteloc -png -posix -pparsingcontext -pparsingstate -ppath -pre -prefill -prequestbodybuf -prequestheaders -prequestinfo -presponse -processllhttperror -ptransport -ptransportinterface -pvalue -pvaluelen -pvalueloc -rangeend -rangestart -rangestartorlastnbytes -readheader -receivehttpdata -recv -recvcurrentcall -recvstopcall -recvtimeoutcall -reponse -reqbodybuflen -reqbodylen -reqflags -requestbody -requestheaderbuffer -requestheaders -requestinfo -respflags -responsebufferlen -rfc -rm -sdk -senderrorcall -sendflags -sendhttpbody -sendhttpheaders -sendpartialcall -sensitivity -sizeof -snprintf -spdx -statuscode -strchr -strerror -strncpy -struct -structs -sublicense -tcp -tcpsocketcontext -td -tls -tlscontext -tlsrecv -tlsrecvcount -tlssend -toascii -toolchain -totalreceived -tr -transportcallback -transportinterface -transportpage -transportrecv -transportsectionimplementation -transportsectionoverview -transportsend -transportstatus -transportstruct -tx -txt -uint -uri -url -valuefound -valuelen -valueloc -writev -xxxx diff --git a/manifest.yml b/manifest.yml index 580eae02..3a0c6ce2 100644 --- a/manifest.yml +++ b/manifest.yml @@ -1,11 +1,22 @@ -name : "coreHTTP" +name: "coreHTTP" version: "v3.0.0" -description: "Client implementation of the HTTP/1.1 specification for embedded devices." +description: + "Client implementation of the HTTP/1.1 specification for embedded devices." license: "MIT" + dependencies: - - name : "llhttp" + - name: "llhttp" version: "release/v6.0.5" license: "MIT" repository: type: "git" url: "https://github.com/nodejs/llhttp.git" + path: source/dependency/3rdparty/llhttp + + - name: "CMock" + version: v2.5.2 + license: "MIT" + repository: + type: "git" + url: "https://github.com/ThrowTheSwitch/CMock.git" + path: test/unit-test/CMock diff --git a/source/core_http_client.c b/source/core_http_client.c index 666e1f43..2ea4d04d 100644 --- a/source/core_http_client.c +++ b/source/core_http_client.c @@ -574,7 +574,7 @@ static int8_t caseInsensitiveStringCmp( const char * str1, size_t n ) { size_t i = 0U; - /* Inclusion of inbetween variables for MISRA rule 13.2 compliance */ + /* Inclusion of temporary variables for MISRA rule 13.2 compliance */ char firstChar; char secondChar; /* Get the offset from a lowercase to capital character in a MISRA compliant way */ diff --git a/source/include/core_http_client_private.h b/source/include/core_http_client_private.h index b2c83de4..d53e5d61 100644 --- a/source/include/core_http_client_private.h +++ b/source/include/core_http_client_private.h @@ -204,7 +204,7 @@ typedef enum HTTPParsingState_t { HTTP_PARSING_NONE = 0, /**< The parser has not started reading any response. */ - HTTP_PARSING_INCOMPLETE, /**< The parser found a partial reponse. */ + HTTP_PARSING_INCOMPLETE, /**< The parser found a partial response. */ HTTP_PARSING_COMPLETE /**< The parser found the entire response. */ } HTTPParsingState_t; diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt index 6d27d46f..4710c701 100644 --- a/test/CMakeLists.txt +++ b/test/CMakeLists.txt @@ -49,7 +49,7 @@ target_include_directories( coverity_analysis PUBLIC ${HTTP_INCLUDE_PUBLIC_DIRS} target_compile_options(coverity_analysis PUBLIC -DNDEBUG ) # ===================== Clone needed third-party libraries ====================== -# Define an llhttp paser resource path. +# Define an llhttp parser resource path. set( LLHTTP_DIR ${MODULE_ROOT_DIR}/source/dependency/3rdparty/llhttp CACHE INTERNAL "llhttp library source directory." ) include( llhttp_build.cmake )