feat(lws): Add initial support libwebsockets component

.github/workflows/lws_build.yml

@@ -0,0 +1,86 @@
+name: "lws: build-tests"
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    types: [opened, synchronize, reopened, labeled]
+
+jobs:
+  build_lws:
+    if: contains(github.event.pull_request.labels.*.name, 'lws') || github.event_name == 'push'
+    name: Libwebsockets build
+    strategy:
+      matrix:
+        idf_ver: ["latest", "release-v5.3"]
+        test: [ { app: example, path: "examples/client" }]
+    runs-on: ubuntu-22.04
+    container: espressif/idf:${{ matrix.idf_ver }}
+    env:
+      TEST_DIR: components/libwebsockets/${{ matrix.test.path }}
+    steps:
+      - name: Checkout esp-protocols
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Build ${{ matrix.example }} with IDF-${{ matrix.idf_ver }}
+        shell: bash
+        run: |
+          . ${IDF_PATH}/export.sh
+          python -m pip install idf-build-apps
+          python ./ci/build_apps.py ${TEST_DIR}
+          cd ${TEST_DIR}
+          for dir in `ls -d build_esp32_*`; do
+          $GITHUB_WORKSPACE/ci/clean_build_artifacts.sh `pwd`/$dir
+          zip -qur artifacts.zip $dir
+          done
+      - uses: actions/upload-artifact@v4
+        with:
+          name: lws_target_esp32_${{ matrix.idf_ver }}_${{ matrix.test.app }}
+          path: ${{ env.TEST_DIR }}/artifacts.zip
+          if-no-files-found: error
+
+  run-target-lws:
+    # Skip running on forks since it won't have access to secrets
+    if: |
+      github.repository == 'espressif/esp-protocols' &&
+      ( contains(github.event.pull_request.labels.*.name, 'lws') || github.event_name == 'push' )
+    name: Target test
+    needs: build_lws
+    strategy:
+      fail-fast: false
+      matrix:
+        idf_ver: ["latest", "release-v5.3"]
+        idf_target: ["esp32"]
+        test: [ { app: example, path: "examples/client" }]
+    runs-on:
+      - self-hosted
+      - ESP32-ETHERNET-KIT
+    env:
+      TEST_DIR: components/libwebsockets/${{ matrix.test.path }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: lws_target_esp32_${{ matrix.idf_ver }}_${{ matrix.test.app }}
+          path: ${{ env.TEST_DIR }}/ci/
+      - name: Install Python packages
+        env:
+          PIP_EXTRA_INDEX_URL: "https://www.piwheels.org/simple"
+        run: |
+          pip install --only-binary cryptography --extra-index-url https://dl.espressif.com/pypi/ -r $GITHUB_WORKSPACE/ci/requirements.txt
+      - name: Run Example Test on target
+        working-directory: ${{ env.TEST_DIR }}
+        run: |
+          unzip ci/artifacts.zip -d ci
+          for dir in `ls -d ci/build_*`; do
+          rm -rf build sdkconfig.defaults
+          mv $dir build
+          python -m pytest --log-cli-level DEBUG --junit-xml=./results_${{ matrix.test.app }}_${{ matrix.idf_target }}_${{ matrix.idf_ver }}_${dir#"ci/build_"}.xml --target=${{ matrix.idf_target }}
+          done
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: results_${{ matrix.test.app }}_${{ matrix.idf_target }}_${{ matrix.idf_ver }}.xml
+          path: components/libwebsockets/${{ matrix.test.path }}/*.xml

.github/workflows/publish-docs-component.yml

@@ -102,5 +102,6 @@ jobs:
             components/mbedtls_cxx;
             components/mosquitto;
             components/sock_utils;
+            components/libwebsockets;
           namespace: "espressif"
           api_token: ${{ secrets.IDF_COMPONENT_API_TOKEN }}

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "components/mosquitto/mosquitto"]
 	path = components/mosquitto/mosquitto
 	url = https://github.com/eclipse/mosquitto
+[submodule "components/libwebsockets/libwebsockets"]
+	path = components/libwebsockets/libwebsockets
+	url = https://github.com/warmcat/libwebsockets.git

.pre-commit-config.yaml

@@ -61,8 +61,8 @@ repos:
   - repo: local
     hooks:
       - id: commit message scopes
-        name: "commit message must be scoped with: mdns, modem, websocket, asio, mqtt_cxx, console, common, eppp, tls_cxx, mosq, sockutls"
-        entry: '\A(?!(feat|fix|ci|bump|test|docs|chore)\((mdns|modem|common|console|websocket|asio|mqtt_cxx|examples|eppp|tls_cxx|mosq|sockutls)\)\:)'
+        name: "commit message must be scoped with: mdns, modem, websocket, asio, mqtt_cxx, console, common, eppp, tls_cxx, mosq, sockutls, lws"
+        entry: '\A(?!(feat|fix|ci|bump|test|docs|chore)\((mdns|modem|common|console|websocket|asio|mqtt_cxx|examples|eppp|tls_cxx|mosq|sockutls|lws)\)\:)'
         language: pygrep
         args: [--multiline]
         stages: [commit-msg]

README.md

@@ -66,3 +66,7 @@ Please refer to instructions in [ESP-IDF](https://github.com/espressif/esp-idf)
 ### Socket helpers (sock-utils)
 
 * Brief introduction [README](components/sock_utils/README.md)
+
+### libwebsockets
+
+* Brief introduction [README](components/libwebsockets/README.md)

components/libwebsockets/CMakeLists.txt

@@ -0,0 +1,21 @@
+idf_component_register(REQUIRES esp-tls)
+
+option(LWS_WITH_EXPORT_LWSTARGETS "Export libwebsockets CMake targets.  Disable if they conflict with an outer cmake project." OFF)
+set(LWS_WITH_EXPORT_LWSTARGETS OFF)
+
+option(LWS_WITH_MBEDTLS "Use mbedTLS (>=2.0) replacement for OpenSSL." ON)
+set(LWS_WITH_MBEDTLS ON)
+
+set(WRAP_FUNCTIONS mbedtls_ssl_handshake_step
+                   lws_adopt_descriptor_vhost)
+
+foreach(wrap ${WRAP_FUNCTIONS})
+    target_link_libraries(${COMPONENT_LIB} INTERFACE "-Wl,--wrap=${wrap}")
+endforeach()
+
+target_link_libraries(${COMPONENT_LIB} INTERFACE websockets)
+
+target_sources(${COMPONENT_LIB} INTERFACE "port/lws_port.c")
+
+
+add_subdirectory(libwebsockets)

components/libwebsockets/README.md

@@ -0,0 +1,22 @@
+# ESP32 libwebsockets Port
+
+This is a lightweight port of the libwebsockets library designed to run on the ESP32. It provides WebSocket client functionalities.
+
+## Supported Options
+
+The ESP32 port of libwebsockets supports a set of common WebSocket configurations for clients. These options can be configured through a structure passed to the `lws_create_context()` function.
+
+Key features supported:
+- WebSocket with optional SSL/TLS
+- HTTP/1.1 client support
+
+## Memory Footprint Considerations
+
+The memory consumption primarily depends on the number of concurrent connections and the selected options for WebSocket frames, protocol handling, and SSL/TLS features. It consumes approximately 300 kB of program memory.
+
+### Client:
+- **Initial Memory Usage**: ~8 kB of heap on startup
+- **Connected Memory Usage**: ~31 kB of heap after connected to a server
+
+- When configuring a WebSocket client, ensure that you have enough heap space to handle the desired number of concurrent client connections.
+- SSL/TLS configurations may require additional memory overhead, depending on the certificate size and cryptographic settings.

components/libwebsockets/examples/client/CMakeLists.txt

@@ -0,0 +1,6 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(client_example)