[lws]: Add initial support for libwebsockets

.github/workflows/lws_build.yml

@@ -0,0 +1,82 @@
+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"]
+    runs-on: ubuntu-22.04
+    container: espressif/idf:${{ matrix.idf_ver }}
+    env:
+      TEST_DIR: components/libwebsockets/examples/client-echo
+      TARGET_TEST_DIR: build_esp32_default
+    steps:
+      - name: Checkout esp-protocols
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Build with IDF-${{ matrix.idf_ver }}
+        shell: bash
+        run: |
+          . ${IDF_PATH}/export.sh
+          pip install idf-component-manager idf-build-apps --upgrade
+          python ci/build_apps.py ${TEST_DIR}
+          cd ${TEST_DIR}
+          ${GITHUB_WORKSPACE}/ci/clean_build_artifacts.sh `pwd`/${TARGET_TEST_DIR}
+          zip -qur artifacts.zip ${TARGET_TEST_DIR}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: lws_target_esp32_${{ matrix.idf_ver }}
+          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"]
+    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 }}
+          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.idf_ver }}_${dir#"ci/build_"}.xml
+          done
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: results_$${{ 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. When setting this, you also may need to specify LWS_MBEDTLS_LIBRARIES and LWS_MBEDTLS_INCLUDE_DIRS" 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,35 @@
+# ESP32 libwebsockets Port
+
+This is a lightweight port of the libwebsockets library designed to run on the ESP32. It provides WebSocket client and server functionalities.
+
+## Supported Options
+
+The ESP32 port of libwebsockets supports a set of common WebSocket configurations, including both server and client modes. These options can be configured through a structure passed to the `lws_create_context()` function.
+
+Key features supported:
+- WebSocket server with optional SSL/TLS
+- WebSocket client support
+- HTTP/1.1 server and client support
+
+## Mandatory Use of mbedTLS
+
+For secure WebSocket communication (WSS) and SSL/TLS support, **mbedTLS** is mandatory. mbedTLS provides the cryptographic functions required for establishing secure connections and is included as part of the ESP32 toolchain.
+
+- **mbedTLS** is required for all encrypted WebSocket (WSS) and HTTPS connections.
+- Ensure that mbedTLS is properly configured in your ESP32 project, as it is essential for enabling SSL/TLS functionality.
+
+## Memory Footprint Considerations
+
+libwebsockets on the ESP32 has been optimized for minimal memory usage. The memory consumption primarily depends on the number of concurrent connections and the selected options for WebSocket frames, protocol handling, and SSL/TLS features.
+
+- **Initial Memory Usage**: TBD
+- **Per Client Memory Usage**: TBD
+- **Per Server Memory Usage**: TBD
+
+### Memory Management Tips:
+- When configuring a WebSocket server, 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.
+
+## Testing
+
+TBD

components/libwebsockets/examples/client-echo/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_echo_example)