feat: S21.01 build-time tunables mechanism via SOLIDSYSLOG_MAX_MESSAGE_SIZE

.github/workflows/ci.yml

@@ -60,6 +60,16 @@ jobs:
           retention-days: 1
           compression-level: 0
 
+      # BDD-side mirror of build-time tunables, generated by configure_file.
+      # bdd-linux-syslog-ng downloads this into Bdd/features/steps/ so behave
+      # can `import solidsyslog_tunables` (the file is gitignored, not in checkout).
+      - name: Upload BDD Python tunables (Linux)
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: bdd-tunables-linux
+          path: Bdd/features/steps/solidsyslog_tunables.py
+          retention-days: 1
+
   integration-linux-openssl:
     runs-on: ubuntu-latest
     permissions:
@@ -165,6 +175,44 @@ jobs:
           path: build/msvc-debug/Tests/OpenSslIntegration/Debug/cpputest_*.xml
           retention-days: 1
 
+  build-linux-tunable-override:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: write
+    container:
+      image: ghcr.io/davidcozens/cpputest:sha-18f19e1
+      options: --user root
+    env:
+      GIT_CONFIG_COUNT: 1
+      GIT_CONFIG_KEY_0: safe.directory
+      GIT_CONFIG_VALUE_0: '*'
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Configure with tunable override
+        run: cmake --preset tunable-override-debug
+
+      - name: Build and test
+        run: cmake --build --preset tunable-override-debug --target junit
+
+      - name: Test Report
+        uses: dorny/test-reporter@v3
+        if: success() || failure()
+        with:
+          name: Test Results (Tunable Override)
+          path: build/tunable-override-debug/cpputest_*.xml
+          reporter: java-junit
+
+      - name: Upload JUnit XML
+        if: success() || failure()
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: junit-build-linux-tunable-override
+          path: build/tunable-override-debug/cpputest_*.xml
+          retention-days: 1
+
   build-linux-clang:
     runs-on: ubuntu-latest
     permissions:
@@ -498,6 +546,13 @@ jobs:
           retention-days: 1
           compression-level: 0
 
+      - name: Upload BDD Python tunables (Windows)
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: bdd-tunables-windows
+          path: Bdd/features/steps/solidsyslog_tunables.py
+          retention-days: 1
+
   bdd-windows-otel:
     needs: build-windows-msvc
     runs-on: windows-2025
@@ -516,6 +571,11 @@ jobs:
           name: solid-syslog-bdd-target-windows
           path: build/msvc-debug/Bdd/Targets/Debug/
 
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
+        with:
+          name: bdd-tunables-windows
+          path: Bdd/features/steps/
+
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
@@ -621,6 +681,11 @@ jobs:
           name: solid-syslog-bdd-targets
           path: build/debug/Bdd/Targets/
 
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
+        with:
+          name: bdd-tunables-linux
+          path: Bdd/features/steps/
+
       - name: Make example binary executable
         run: chmod +x build/debug/Bdd/Targets/SolidSyslogBddTarget
 
@@ -727,6 +792,13 @@ jobs:
           retention-days: 1
           compression-level: 0
 
+      - name: Upload BDD Python tunables (FreeRTOS)
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: bdd-tunables-freertos
+          path: Bdd/features/steps/solidsyslog_tunables.py
+          retention-days: 1
+
   bdd-freertos-qemu:
     needs: build-freertos-target
     runs-on: ubuntu-latest
@@ -742,6 +814,11 @@ jobs:
           name: solid-syslog-bdd-target-freertos
           path: build/freertos-cross/Bdd/Targets/FreeRtos/
 
+      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
+        with:
+          name: bdd-tunables-freertos
+          path: Bdd/features/steps/
+
       - name: Make ELF readable
         run: chmod +r build/freertos-cross/Bdd/Targets/FreeRtos/SolidSyslogBddTarget.elf
 
@@ -776,7 +853,7 @@ jobs:
 
   summary:
     if: always() && github.event_name == 'pull_request'
-    needs: [build-linux-gcc, build-linux-clang, sanitize-linux-gcc, coverage-linux-gcc, analyze-tidy, analyze-cppcheck, analyze-format, analyze-iwyu, bdd-linux-syslog-ng, build-windows-msvc, bdd-windows-otel, integration-linux-openssl, integration-windows-openssl, build-freertos-host-tdd, build-freertos-target, bdd-freertos-qemu]
+    needs: [build-linux-gcc, build-linux-tunable-override, build-linux-clang, sanitize-linux-gcc, coverage-linux-gcc, analyze-tidy, analyze-cppcheck, analyze-format, analyze-iwyu, bdd-linux-syslog-ng, build-windows-msvc, bdd-windows-otel, integration-linux-openssl, integration-windows-openssl, build-freertos-host-tdd, build-freertos-target, bdd-freertos-qemu]
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -873,6 +950,11 @@ jobs:
                     "id": "junit",
                     "name": "build-windows-msvc",
                     "pattern": "**/junit-build-windows-msvc/cpputest_*.xml"
+                  },
+                  {
+                    "id": "junit",
+                    "name": "build-linux-tunable-override",
+                    "pattern": "**/junit-build-linux-tunable-override/cpputest_*.xml"
                   }
                 ]
               },

.gitignore

@@ -60,6 +60,10 @@ Bdd/otel/bin/
 __pycache__/
 *.pyc
 
+# BDD-side mirror of build-time tunables, generated by CMake configure_file
+# from Bdd/features/steps/solidsyslog_tunables.py.in
+Bdd/features/steps/solidsyslog_tunables.py
+
 # Claude Code local config
 .claude/
 pr*-comments.json

Bdd/Targets/Common/BddTargetInteractive.c

@@ -6,6 +6,7 @@
 #include <string.h>
 
 #include "SolidSyslog.h"
+#include "SolidSyslogTunables.h"
 
 static const char* const PROMPT = "SolidSyslog> ";
 

Bdd/Targets/FreeRtos/main.c

@@ -25,6 +25,7 @@
 #include "BddTargetSwitchConfig.h"
 #include "SolidSyslog.h"
 #include "SolidSyslogAtomicCounter.h"
+#include "SolidSyslogTunables.h"
 #include "SolidSyslogCircularBuffer.h"
 #include "SolidSyslogConfig.h"
 #include "SolidSyslogEndpoint.h"

Bdd/Targets/Linux/main.c

@@ -21,6 +21,7 @@
 #include "BddTargetUdpConfig.h"
 #include "SolidSyslog.h"
 #include "SolidSyslogAtomicCounter.h"
+#include "SolidSyslogTunables.h"
 #include "SolidSyslogConfig.h"
 #include "SolidSyslogCrc16Policy.h"
 #include "SolidSyslogFileBlockDevice.h"

Bdd/features/steps/solidsyslog_tunables.py.in

@@ -0,0 +1,7 @@
+# Auto-generated by CMake from Bdd/features/steps/solidsyslog_tunables.py.in.
+# Mirrors the build-time tunable values used in CMakeLists.txt and parsed
+# from Core/Interface/SolidSyslogTunablesDefaults.h (or the user-supplied
+# override file if SOLIDSYSLOG_USER_TUNABLES_FILE is set). Reconfigure CMake
+# to refresh. Do not edit; do not commit (see .gitignore).
+
+SOLIDSYSLOG_MAX_MESSAGE_SIZE = @SOLIDSYSLOG_BDD_MAX_MESSAGE_SIZE@

Bdd/features/steps/syslog_steps.py

@@ -61,12 +61,15 @@ def per_transport_log(context, transport):
 SYSLOG_NG_FULL_CONF = "Bdd/syslog-ng/syslog-ng-full.conf"
 SYSLOG_NG_UDP_ONLY_CONF = "Bdd/syslog-ng/syslog-ng-udp-only.conf"
 
-# Mirrors SOLIDSYSLOG_MAX_MESSAGE_SIZE from Core/Interface/SolidSyslog.h. Bump
-# the two together. The store_capacity scenarios depend on it because production
-# clamps max-block-size up to MAX + RECORD_OVERHEAD + integritySize at runtime,
-# so the block size used by the block store is MAX-coupled even when the feature
-# file specifies a smaller value.
-SOLIDSYSLOG_MAX_MESSAGE_SIZE = 2048
+# Sourced from the build's configured tunables via the CMake-generated
+# solidsyslog_tunables module (configure_file in top-level CMakeLists.txt
+# parses Core/Interface/SolidSyslogTunablesDefaults.h, or the user override
+# if SOLIDSYSLOG_USER_TUNABLES_FILE is set). The store_capacity scenarios
+# depend on this value because production clamps max-block-size up to
+# MAX + RECORD_OVERHEAD + integritySize at runtime, so the block size used
+# by the block store is MAX-coupled even when the feature file specifies a
+# smaller value.
+from solidsyslog_tunables import SOLIDSYSLOG_MAX_MESSAGE_SIZE
 
 # RFC 5424 §6.2.4 IP fallback for the FreeRTOS reference example. With no
 # FQDN (no DNS resolver), no integrator-supplied hostname, and no DHCP, the

CMakeLists.txt

@@ -104,6 +104,40 @@ if(SOLIDSYSLOG_OPENSSL)
     endif()
 endif()
 
+# Build-time tunables (E21: Port-Time Configurability). Integrators override
+# library defaults by setting SOLIDSYSLOG_USER_TUNABLES_FILE to the absolute
+# path of their own header containing #define lines for whichever tunables
+# they want to change. Defaults live in Core/Interface/SolidSyslogTunablesDefaults.h.
+add_library(SolidSyslogTunables INTERFACE)
+target_include_directories(SolidSyslogTunables INTERFACE
+    ${CMAKE_SOURCE_DIR}/Core/Interface)
+if(SOLIDSYSLOG_USER_TUNABLES_FILE)
+    target_compile_definitions(SolidSyslogTunables INTERFACE
+        SOLIDSYSLOG_USER_TUNABLES_FILE="${SOLIDSYSLOG_USER_TUNABLES_FILE}")
+endif()
+
+# BDD-side mirror of the configured tunables — eliminates the hardcoded
+# "remember to bump this" mirror that used to live in syslog_steps.py.
+# Parse the default from SolidSyslogTunablesDefaults.h; if a user override
+# is in effect and defines the macro, use its value instead. The generated
+# file is written to the source tree because behave's import discovery
+# expects modules under Bdd/features/steps/; it is gitignored.
+file(READ "${CMAKE_SOURCE_DIR}/Core/Interface/SolidSyslogTunablesDefaults.h" _solidsyslog_defaults)
+string(REGEX MATCH "#define[ \t]+SOLIDSYSLOG_MAX_MESSAGE_SIZE[ \t]+([0-9]+)" _ "${_solidsyslog_defaults}")
+set(SOLIDSYSLOG_BDD_MAX_MESSAGE_SIZE "${CMAKE_MATCH_1}")
+if(SOLIDSYSLOG_USER_TUNABLES_FILE AND EXISTS "${SOLIDSYSLOG_USER_TUNABLES_FILE}")
+    file(READ "${SOLIDSYSLOG_USER_TUNABLES_FILE}" _solidsyslog_user_tunables)
+    string(REGEX MATCH "#define[ \t]+SOLIDSYSLOG_MAX_MESSAGE_SIZE[ \t]+([0-9]+)" _ "${_solidsyslog_user_tunables}")
+    if(CMAKE_MATCH_1)
+        set(SOLIDSYSLOG_BDD_MAX_MESSAGE_SIZE "${CMAKE_MATCH_1}")
+    endif()
+endif()
+configure_file(
+    "${CMAKE_SOURCE_DIR}/Bdd/features/steps/solidsyslog_tunables.py.in"
+    "${CMAKE_SOURCE_DIR}/Bdd/features/steps/solidsyslog_tunables.py"
+    @ONLY
+)
+
 add_subdirectory(Core/Source)
 
 if(HAVE_STDATOMIC_H)

CMakePresets.json

@@ -36,6 +36,15 @@
                 "SANITIZE": "ON"
             }
         },
+        {
+            "name": "tunable-override-debug",
+            "displayName": "Tunable Override (mechanism end-to-end)",
+            "inherits": "debug",
+            "cacheVariables": {
+                "SOLIDSYSLOG_USER_TUNABLES_FILE": "${sourceDir}/Tests/Fixtures/SmallMessageSizeTunables.h",
+                "SOLIDSYSLOG_TEST_EXPECTED_MAX_MESSAGE_SIZE": "512"
+            }
+        },
         {
             "name": "coverage",
             "displayName": "Coverage",
@@ -112,6 +121,7 @@
         { "name": "debug",          "configurePreset": "debug" },
         { "name": "release",        "configurePreset": "release" },
         { "name": "sanitize",       "configurePreset": "sanitize" },
+        { "name": "tunable-override-debug", "configurePreset": "tunable-override-debug" },
         { "name": "coverage",       "configurePreset": "coverage" },
         { "name": "tidy",           "configurePreset": "tidy" },
         { "name": "cppcheck",       "configurePreset": "cppcheck" },

Core/Interface/SolidSyslog.h

@@ -6,11 +6,6 @@
 
 EXTERN_C_BEGIN
 
-    enum
-    {
-        SOLIDSYSLOG_MAX_MESSAGE_SIZE = 2048
-    };
-
     struct SolidSyslogMessage
     {
         enum SolidSyslog_Facility facility;

Core/Interface/SolidSyslogBlockStore.h

@@ -4,8 +4,8 @@
 #include <stddef.h>
 #include <stdint.h>
 
-#include "SolidSyslog.h"
 #include "SolidSyslogSecurityPolicyDefinition.h"
+#include "SolidSyslogTunables.h"
 #include "ExternC.h"
 
 struct SolidSyslogStore;

Core/Interface/SolidSyslogCircularBuffer.h

@@ -6,7 +6,7 @@
 #include <stddef.h>
 #include <stdint.h>
 
-#include "SolidSyslog.h" // IWYU pragma: keep -- macro body references SOLIDSYSLOG_MAX_MESSAGE_SIZE
+#include "SolidSyslogTunables.h"
 
 EXTERN_C_BEGIN
 

Core/Interface/SolidSyslogTunables.h

@@ -0,0 +1,10 @@
+#ifndef SOLIDSYSLOG_TUNABLES_H
+#define SOLIDSYSLOG_TUNABLES_H
+
+#if defined(SOLIDSYSLOG_USER_TUNABLES_FILE)
+/* cppcheck-suppress preprocessorErrorDirective -- macro expands to a header path supplied via -D at build time; the #if guard makes it active only then. */
+#include SOLIDSYSLOG_USER_TUNABLES_FILE
+#endif
+#include "SolidSyslogTunablesDefaults.h" // IWYU pragma: export
+
+#endif /* SOLIDSYSLOG_TUNABLES_H */

Core/Interface/SolidSyslogTunablesDefaults.h

@@ -0,0 +1,31 @@
+#ifndef SOLIDSYSLOG_TUNABLES_DEFAULTS_H
+#define SOLIDSYSLOG_TUNABLES_DEFAULTS_H
+
+// IWYU pragma: private, include "SolidSyslogTunables.h"
+// Defaults are reached through the SolidSyslogTunables.h umbrella so the optional
+// SOLIDSYSLOG_USER_TUNABLES_FILE override gets a chance to win first.
+
+/*
+ * Maximum bytes the library will format for a single syslog message.
+ *
+ * Caps the per-Log Formatter buffer (stack-allocated inside SolidSyslog_Log),
+ * the FileStore record size, and the minimum BlockStore block size. Per
+ * RFC 5424 section 6.1, receivers SHOULD accept up to 2048 bytes; transports
+ * may impose lower limits beyond which truncation kicks in. Lower values save
+ * stack and store footprint; higher values reduce truncation.
+ *
+ * Floor: smallest size that can hold a meaningful RFC 5424 security event.
+ * A legal all-NILVALUE message is 16 bytes; this allows enough headroom
+ * for a real PRI, hostname, MSGID, and short payload.
+ * Sub-floor values rejected at compile time.
+ */
+#ifndef SOLIDSYSLOG_MAX_MESSAGE_SIZE
+/* NOLINTNEXTLINE(cppcoreguidelines-macro-usage) -- macro form required for preprocessor visibility (floor #if) and C array-size const-expr. */
+#define SOLIDSYSLOG_MAX_MESSAGE_SIZE 2048 /* RFC 5424 section 6.1 SHOULD value */
+#endif
+
+#if SOLIDSYSLOG_MAX_MESSAGE_SIZE < 64
+#error "SOLIDSYSLOG_MAX_MESSAGE_SIZE must be >= 64"
+#endif
+
+#endif /* SOLIDSYSLOG_TUNABLES_DEFAULTS_H */

Core/Source/CMakeLists.txt

@@ -48,6 +48,8 @@ target_include_directories(${PROJECT_NAME}
     PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}
 )
 
+target_link_libraries(${PROJECT_NAME} PUBLIC SolidSyslogTunables)
+
 if(SOLIDSYSLOG_POSIX)
     target_link_libraries(${PROJECT_NAME} PUBLIC rt)
 endif()

Core/Source/RecordStore.c

@@ -1,6 +1,7 @@
 #include "RecordStore.h"
 
 #include "SolidSyslogBlockDevice.h"
+#include "SolidSyslogTunables.h"
 
 #include <string.h>
 

Core/Source/RecordStore.h

@@ -1,8 +1,8 @@
 #ifndef SOLIDSYSLOG_RECORDSTORE_H
 #define SOLIDSYSLOG_RECORDSTORE_H
 
-#include "SolidSyslog.h"
 #include "SolidSyslogSecurityPolicyDefinition.h"
+#include "SolidSyslogTunables.h"
 
 #include <stdbool.h>
 #include <stddef.h>

Core/Source/SolidSyslog.c

@@ -17,6 +17,7 @@
 #include "SolidSyslogStringFunction.h"
 #include "SolidSyslogStructuredData.h"
 #include "SolidSyslogTimestamp.h"
+#include "SolidSyslogTunables.h"
 
 struct SolidSyslogFormatter;
 struct SolidSyslogStructuredData;

Core/Source/SolidSyslogBlockStore.c

@@ -4,7 +4,7 @@
 
 #include "BlockSequence.h"
 #include "RecordStore.h"
-#include "SolidSyslog.h"
+#include "SolidSyslogTunables.h"
 #include "SolidSyslogBlockDevice.h"
 #include "SolidSyslogMacros.h"
 #include "SolidSyslogNullSecurityPolicy.h"