Experimental branch: add reliable topics

.clang-tidy

@@ -22,18 +22,18 @@ Checks: >-
   -boost-use-ranges,
   -hicpp-static-assert,
   -misc-static-assert,
-  -modernize-macro-to-enum,
-  -cppcoreguidelines-macro-to-enum,
+  -*-macro-to-enum,
   -*-macro-usage,
   -*-enum-size,
   -*-use-using,
-  -bugprone-casting-through-void,
+  -*-casting-through-void,
   -misc-include-cleaner,
   -cppcoreguidelines-avoid-do-while,
   -*-magic-numbers,
   -*-use-enum-class,
   -*-use-trailing-return-type,
   -*-deprecated-headers,
+  -*-avoid-c-arrays,
 CheckOptions:
   - key:   readability-function-cognitive-complexity.Threshold
     value: '99'

.github/workflows/main.yml

@@ -9,7 +9,7 @@ jobs:
     container: ghcr.io/opencyphal/toolshed:ts24.4.3
     strategy:
       matrix:
-        toolchain: [ 'clang', 'gcc' ]
+        toolchain: [ "clang", "gcc" ]
         include:
           - toolchain: gcc
             c-compiler: gcc
@@ -24,23 +24,28 @@ jobs:
       # language=bash
       - run: >
           cmake
-          -B ${{ github.workspace }}/build
+          -B $GITHUB_WORKSPACE/build
           -DCMAKE_BUILD_TYPE=Debug
           -DCMAKE_C_COMPILER=${{ matrix.c-compiler }}
           -DCMAKE_CXX_COMPILER=${{ matrix.cxx-compiler }}
           .
       # language=bash
       - run: |
-          cd ${{ github.workspace }}/build
+          cd $GITHUB_WORKSPACE/build
           make VERBOSE=1 -j$(nproc)
           make test ARGS="--verbose"
+      - name: Archive workspace
+        if: always()
+        run: |
+          cd $GITHUB_WORKSPACE
+          tar --use-compress-program="gzip -9" -cf $RUNNER_TEMP/workspace.tar.gz .
       - uses: actions/upload-artifact@v4
         if: always()
         with:
           # The matrix is shown for convenience but this is fragile because the values may not be string-convertible.
           # Shall it break one day, feel free to remove the matrix from here.
           name: ${{github.job}}-#${{strategy.job-index}}-${{job.status}}-${{join(matrix.*, ',')}}
-          path: ${{github.workspace}}/**/*
+          path: ${{runner.temp}}/workspace.tar.gz
           retention-days: 2
 
   optimizations:
@@ -49,13 +54,13 @@ jobs:
     container: ghcr.io/opencyphal/toolshed:ts24.4.3
     strategy:
       matrix:
-        toolchain: [ 'clang', 'gcc' ]
+        toolchain: [ "clang", "gcc" ]
         build_type: [ Release, MinSizeRel ]
         include:
           - toolchain: gcc
             c-compiler: gcc
             cxx-compiler: g++
-            cxx-flags: -fno-strict-aliasing # GCC in MinSizeRel C++20 mode misoptimizes the Cavl test.
+            cxx-flags: ""
           - toolchain: clang
             c-compiler: clang
             cxx-compiler: clang++
@@ -66,7 +71,7 @@ jobs:
       # language=bash
       - run: >
           cmake
-          -B ${{ github.workspace }}/build
+          -B $GITHUB_WORKSPACE/build
           -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
           -DCMAKE_C_COMPILER=${{ matrix.c-compiler }}
           -DCMAKE_CXX_COMPILER=${{ matrix.cxx-compiler }}
@@ -75,36 +80,68 @@ jobs:
           .
       # language=bash
       - run: |
-          cd ${{ github.workspace }}/build
+          cd $GITHUB_WORKSPACE/build
           make VERBOSE=1 -j$(nproc)
           make test ARGS="--verbose"
+      - name: Archive workspace
+        if: always()
+        run: |
+          cd $GITHUB_WORKSPACE
+          tar --use-compress-program="gzip -9" -cf $RUNNER_TEMP/workspace.tar.gz .
       - uses: actions/upload-artifact@v4
         if: always()
         with:
           # The matrix is shown for convenience but this is fragile because the values may not be string-convertible.
           # Shall it break one day, feel free to remove the matrix from here.
           name: ${{github.job}}-#${{strategy.job-index}}-${{job.status}}-${{join(matrix.*, ',')}}
-          path: ${{github.workspace}}/**/*
+          path: ${{runner.temp}}/workspace.tar.gz
           retention-days: 2
 
-# TODO: re-enable this
-#  avr:
-#    if: github.event_name == 'push'
-#    runs-on: ubuntu-latest
-#    env:
-#      mcu: at90can64
-#      flags: -Wall -Wextra -Werror -pedantic -Wconversion -Wtype-limits
-#    strategy:
-#      matrix:
-#        std: [ 'c99', 'c11', 'gnu99', 'gnu11' ]
-#    steps:
-#      - uses: actions/checkout@v4
-#      # language=bash
-#      - run: |
-#          sudo apt update -y && sudo apt upgrade -y
-#          sudo apt install gcc-avr avr-libc
-#          avr-gcc --version
-#      - run: avr-gcc -Ilib/cavl/ libudpard/*.c -c -std=${{matrix.std}} -mmcu=${{env.mcu}} ${{env.flags}}
+  coverage:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    container: ghcr.io/opencyphal/toolshed:ts24.4.3
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+      # language=bash
+      - run: >
+          cmake -B $GITHUB_WORKSPACE/build -DCMAKE_BUILD_TYPE=Debug -DNO_STATIC_ANALYSIS=ON -DENABLE_COVERAGE=ON .
+      # language=bash
+      - run: |
+          cd $GITHUB_WORKSPACE/build
+          make -j$(nproc) && make test && make coverage
+      - name: Archive workspace
+        if: always()
+        run: |
+          cd $GITHUB_WORKSPACE
+          tar --use-compress-program="gzip -9" -cf $RUNNER_TEMP/workspace.tar.gz .
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: ${{github.job}}-#${{strategy.job-index}}-${{job.status}}
+          path: ${{runner.temp}}/workspace.tar.gz
+          retention-days: 30
+
+  # TODO: re-enable this
+  #  avr:
+  #    if: github.event_name == 'push'
+  #    runs-on: ubuntu-latest
+  #    env:
+  #      mcu: at90can64
+  #      flags: -Wall -Wextra -Werror -pedantic -Wconversion -Wtype-limits
+  #    strategy:
+  #      matrix:
+  #        std: [ 'c99', 'c11', 'gnu99', 'gnu11' ]
+  #    steps:
+  #      - uses: actions/checkout@v4
+  #      # language=bash
+  #      - run: |
+  #          sudo apt update -y && sudo apt upgrade -y
+  #          sudo apt install gcc-avr avr-libc
+  #          avr-gcc --version
+  #      - run: avr-gcc -Ilib/cavl/ libudpard/*.c -c -std=${{matrix.std}} -mmcu=${{env.mcu}} ${{env.flags}}
 
   arm:
     if: github.event_name == 'push'
@@ -113,7 +150,7 @@ jobs:
       flags: -Wall -Wextra -Werror -pedantic -Wconversion -Wtype-limits -Wcast-align -Wfatal-errors
     strategy:
       matrix:
-        std: [ 'c99', 'c11', 'gnu99', 'gnu11' ]
+        std: [ "c99", "c11", "gnu99", "gnu11" ]
     steps:
       - uses: actions/checkout@v4
       # language=bash
@@ -139,12 +176,12 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
+          fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis
           submodules: true
       - uses: actions/setup-java@v4
         with:
           java-version: 17
-          distribution: 'zulu'
+          distribution: "zulu"
       # language=bash
       - run: |
           clang --version
@@ -179,6 +216,6 @@ jobs:
       - uses: actions/checkout@v4
       - uses: DoozyX/clang-format-lint-action@v0.20
         with:
-          source: './libudpard ./tests'
-          extensions: 'c,h,cpp,hpp'
+          source: "./libudpard ./tests"
+          extensions: "c,h,cpp,hpp"
           clangFormatVersion: ${{ env.LLVM_VERSION }}

AGENTS.md

@@ -1,8 +1,9 @@
-# LibUDPard instructions for agents
+# LibUDPard instructions for AI agents
 
-Please read README.md for general information about LibUDPard.
-The library source files are just two: `libudpard/udpard.c` and `libudpard/udpard.h`.
+Please read `README.md` for general information about LibUDPard, and `CONTRIBUTING.md` for development-related notes.
 
 Keep the code and comments very brief. Be sure every significant code block is preceded with a brief comment.
 
 When building the code, don't hesitate to use multiple jobs to use all CPU cores.
+
+Run all tests in debug build to ensure that all assertion checks are enabled.

README.md

@@ -21,18 +21,22 @@ next-generation intelligent vehicles: manned and unmanned aircraft, spacecraft,
 ## Features
 
 - Zero-copy RX pipeline -- payload is moved from the NIC driver all the way to the application without copying.
+- ≤1-copy TX pipeline with deduplication across multiple interfaces and scattered input buffer support.
 - Support for redundant network interfaces with seamless interface aggregation and zero fail-over delay.
-- Robust message reassembler tolerant to highly distorted datagram streams (out-of-order, duplication, distinct MTU).
-- Message ordering recovery for ordering-sensitive applications (e.g., state estimators, control loops).
+- Robust message reassembler supporting highly distorted datagram streams:
+  out-of-order fragments, message ordering recovery, fragment/message deduplication, interleaving, variable MTU, ...
+- Robust message ordering recovery for ordering-sensitive applications (e.g., state estimators, control loops)
+  with well-defined deterministic recovery in the event of lost messages.
 - Packet loss mitigation via:
-  - repetition-coding FEC (transparent to the application);
   - redundant interfaces (packet lost on one interface may be received on another, transparent to the application);
-  - positive acknowledgment with retransmission (retransmission not handled by the library).
+  - reliable topics (retransmit until acknowledged; callback notifications for successful/failed deliveries).
 - Heap not required; the library can be used with fixed-size block pool allocators.
 - Detailed time complexity and memory requirement models for the benefit of real-time high-integrity applications.
-- Runs on any 8/16/32/64-bit platform and extremely resource-constrained baremetal environments with ~100K ROM/RAM.
-- MISRA C compliance (reach out to <https://forum.opencyphal.org>).
-- Full implementation in a single C file with less than 2k lines of straightforward code!
+- Runs anywhere out of the box, including extremely resource-constrained baremetal environments with ~100K ROM/RAM.
+  No porting required.
+- Partial MISRA C compliance (reach out to <https://forum.opencyphal.org>).
+- Full implementation in a single C file with only 2k lines of straightforward C99!
+- Extensive test coverage.
 
 ## Usage
 
@@ -72,7 +76,9 @@ standards-compliant C99 compiler is available.
 
 ### v3.0
 
-WIP --- adding support for Cyphal v1.1.
+The library has been redesigned from scratch to support Cyphal v1.1, named topics, and reliable transfers.
+No porting guide is provided since the changes are too significant;
+please refer to the new API docs in `libudpard/udpard.h`.
 
 ### v2.0