Feature/observable callback coverage

.github/workflows/host-tests.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches:
       - main
-      - feature/command-socket-integration
+      - feature/observable-callback-coverage
   pull_request:
 
 jobs:
@@ -14,13 +14,20 @@ jobs:
       - name: Checkout Sockets
         uses: actions/checkout@v4
 
-      - name: Checkout ESPressio Command 0.2.0
+      - name: Checkout ESPressio Command 0.3.0
         uses: actions/checkout@v4
         with:
           repository: Flowduino/ESPressio-Command
-          ref: 0.2.0
+          ref: 0.3.0
           path: deps/ESPressio-Command
 
+      - name: Checkout ESPressio Security 0.2.0
+        uses: actions/checkout@v4
+        with:
+          repository: Flowduino/ESPressio-Security
+          ref: 0.2.0
+          path: deps/ESPressio-Security
+
       - name: Checkout ESPressio Timing 2.2.2
         uses: actions/checkout@v4
         with:
@@ -46,6 +53,7 @@ jobs:
         run: >-
           cmake -S tests -B build
           -DESPRESSIO_COMMAND_INCLUDE_DIR="$GITHUB_WORKSPACE/deps/ESPressio-Command/src"
+          -DESPRESSIO_SECURITY_INCLUDE_DIR="$GITHUB_WORKSPACE/deps/ESPressio-Security/src"
           -DESPRESSIO_TIMING_INCLUDE_DIR="$GITHUB_WORKSPACE/deps/ESPressio-Timing/src"
           -DESPRESSIO_UNITS_INCLUDE_DIR="$GITHUB_WORKSPACE/deps/ESPressio-Units/src"
           -DESPRESSIO_OBSERVABLE_INCLUDE_DIR="$GITHUB_WORKSPACE/deps/ESPressio-Observable/src"

.github/workflows/security-integration-tests.yml

@@ -2,7 +2,7 @@ name: Security Integration
 
 on:
   push:
-    branches: [feature/security-integration, main]
+    branches: [feature/security-integration, feature/observable-callback-coverage, main]
   pull_request:
     branches: [main]
 
@@ -14,12 +14,12 @@ jobs:
       - uses: actions/checkout@v4
         with:
           repository: Flowduino/ESPressio-Command
-          ref: 0.2.0
+          ref: 0.3.0
           path: deps/ESPressio-Command
       - uses: actions/checkout@v4
         with:
           repository: Flowduino/ESPressio-Security
-          ref: 0.1.0
+          ref: 0.2.0
           path: deps/ESPressio-Security
       - uses: actions/checkout@v4
         with:
@@ -56,13 +56,18 @@ jobs:
       - uses: actions/checkout@v4
         with:
           repository: Flowduino/ESPressio-Security
-          ref: 0.1.0
+          ref: 0.2.0
           path: deps/ESPressio-Security
+      - uses: actions/checkout@v4
+        with:
+          repository: Flowduino/ESPressio-Observable
+          ref: 3.0.1
+          path: deps/ESPressio-Observable
       - name: Install PlatformIO
         run: pip install platformio
       - name: Compile SecureTCPClient
         run: >-
           pio ci examples/SecureTCPClient/SecureTCPClient.ino
-          --board esp32dev --lib . --lib deps/ESPressio-Security
-          --project-option="build_flags=-std=gnu++17"
+          --board esp32dev --lib . --lib deps/ESPressio-Security --lib deps/ESPressio-Observable
+          --project-option="build_flags=-std=gnu++17 -frtti"
           --project-option="build_unflags=-std=gnu++11 -fno-rtti"

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.5.0 — 2026-08-20
+
+### Added
+- Added `ISocketWorkerObserver` and observable socket-worker lifecycle notifications for start, start failure, and stop transitions.
+- Added `ISocketSecuritySessionObserver` and observable secure-session fault/reset notifications.
+- Added ESPressio Observable >= 3.0.1 < 4.0.0 as the common lifecycle-observer dependency.
+- Added optional ESPressio Event bridge support through ESPressio Event 5.8.0.
+
+### Changed
+- Updated the validated optional ESPressio Security baseline to Security >= 0.2.0 < 1.0.0.
+- Security session send/unprotect/frame-limit failures now publish lifecycle observations while preserving existing result and callback behavior.
+- Bumped package/component/public version metadata to 0.5.0.
+- Event, Timing, Command and Security integrations remain opt-in.
+
 ## 0.4.0 — 2026-08-20
 
 ### Added

README.md

@@ -6,6 +6,35 @@ Socket-based ESPressio transports, Command adapters, transport-security sessions
 
 The latest Stable Version is **0.4.0**.
 
+## Current Development Version — 0.5.0
+
+The `feature/observable-callback-coverage` branch targets **0.5.0** and adds native Observable lifecycle coverage while preserving the existing socket/data callback model.
+
+For this development branch, the dependency model is:
+
+```text
+Required
+    ESPressio Observable >= 3.0.1 < 4.0.0
+
+Optional Command integration
+    ESPressio Command >= 0.3.0 < 1.0.0
+
+Optional Transport Security
+    ESPressio Security >= 0.2.0 < 1.0.0
+
+Optional Event integration
+    ESPressio Event >= 5.8.0 < 6.0.0
+
+Optional Timing synchronization
+    ESPressio Timing >= 2.2.2 < 3.0.0
+```
+
+Observable coverage is owned by Sockets itself. `SocketWorker` exposes start/start-failure/stop lifecycle observation, and `SocketSecuritySession` exposes secure-session fault/reset observation. Existing receive, write, Command, Event Transport, and security-processing callbacks remain authoritative for their original responsibilities.
+
+ESPressio Event remains **opt-in**. Event 5.8 provides `SocketWorkerEventBridge` and `SocketSecuritySessionEventBridge`; Sockets does not depend upward on Event. ESPressio Serial 0.5 can consume the same observer contracts directly for diagnostics without requiring Event.
+
+The stable-release documentation below remains intact so existing 0.4.0 users retain accurate historical guidance.
+
 ## Compatibility
 
 ESPressio Sockets `0.4.0` targets ESP32/Arduino-ESP32 and C++17. Individual facilities may depend on Arduino networking classes, WebSockets, MQTT, or optional ESPressio libraries according to the adapter selected.
@@ -20,9 +49,9 @@ Apache License 2.0. See [LICENSE](LICENSE).
 
 ## ESPressio Library Dependencies
 
-Core ESPressio Sockets has no mandatory ESPressio dependency.
+Core ESPressio Sockets has no mandatory ESPressio dependency in the stable 0.4.0 release. The 0.5.0 development branch adds the required Observable dependency documented above.
 
-Optional integrations:
+Optional integrations for stable 0.4.0:
 
 ```text
 Event transports
@@ -74,6 +103,8 @@ lib_deps =
 
 Add Event, Command, or Timing only when selecting those integrations.
 
+For the 0.5.0 development branch, also include ESPressio Observable 3.0.1 or newer within the 3.x line, and use the Command/Security floors listed in the development-version section above.
+
 ## Header Structure
 
 The normal umbrella is:
@@ -174,7 +205,7 @@ The incoming datagram is passed to `Receive()` and is delivered upward only afte
 
 ### Security Guarantees
 
-The adapters inherit Security 0.1.x semantics:
+The stable 0.4.0 adapters inherit Security 0.1.x semantics:
 
 ```text
 AEAD encryption/authentication
@@ -207,7 +238,9 @@ The same architecture applies to Event or future application protocols.
 
 ## Failure Observation
 
-Both Security adapters expose a failure callback carrying `SecurityResult`. This provides error classification for authentication, replay, key, algorithm, protocol, and frame-limit failures without exposing secret key material.
+Stable 0.4.0 Security adapters expose a failure callback carrying `SecurityResult`. This provides error classification for authentication, replay, key, algorithm, protocol, and frame-limit failures without exposing secret key material.
+
+The 0.5.0 development branch additionally exposes the corresponding `ISocketSecuritySessionObserver` lifecycle contract and the general `ISocketWorkerObserver` lifecycle contract. These observer notifications complement rather than replace existing operational callbacks.
 
 ## Examples
 
@@ -230,9 +263,7 @@ SocketSecurity
 ClockSynchronizationProtocol
 ```
 
-`SocketSecurity` covers fragmented stream input, coalesced stream frames, declared-size limits, stream reset behavior, datagram protection and replay rejection.
-
-Permanent CI checks out released ESPressio Security 0.1.0 and compiles the real ESP32 secure TCP example in addition to host tests.
+`SocketSecurity` covers fragmented stream input, coalesced stream frames, declared-size limits, stream reset behavior, datagram protection and replay rejection. The 0.5.0 development branch extends host validation to the new observer lifecycle surface and tests against the refreshed Command/Security/Observable dependency generation.
 
 ## Compatibility
 
@@ -245,6 +276,8 @@ Sockets 0.4.0 is a backward-compatible minor release:
 - Security integration is opt-in;
 - the normal umbrella remains independent of Security.
 
+The 0.5.0 development branch is also designed as a backward-compatible minor extension. Observable becomes a core dependency because core worker lifecycle is now observable; Event itself remains optional.
+
 ## Contributing
 
 Issues and contributions are welcome through GitHub. New socket mechanisms should keep application semantics and cryptography outside their concrete I/O responsibility wherever possible.

component.mk

@@ -4,6 +4,6 @@ CXXFLAGS += -std=gnu++17
 CPPFLAGS += \
     -DESPRESSIO_SOCKETS \
     -DESPRESSIO_SOCKETS_VERSION_MAJOR=0 \
-    -DESPRESSIO_SOCKETS_VERSION_MINOR=4 \
+    -DESPRESSIO_SOCKETS_VERSION_MINOR=5 \
     -DESPRESSIO_SOCKETS_VERSION_PATCH=0 \
-    -DESPRESSIO_SOCKETS_VERSION_STRING=\"0.4.0\"
+    -DESPRESSIO_SOCKETS_VERSION_STRING=\"0.5.0\"

library.json

@@ -1,7 +1,7 @@
 {
     "name": "ESPressio-Sockets",
     "description": "Socket-based ESPressio transports, Command invocation adapters, Security sessions, and Timing synchronization providers for ESP32.",
-    "keywords": "esp32,sockets,udp,tcp,tls,websocket,mqtt,event,command,security,encryption,transport,network,timing,clock,synchronization,espressio",
+    "keywords": "esp32,sockets,udp,tcp,tls,websocket,mqtt,event,command,security,encryption,transport,network,timing,clock,synchronization,observable,espressio",
     "authors": {
         "name": "Flowduino",
         "maintainer": true,
@@ -16,11 +16,16 @@
         "type": "git",
         "url": "https://github.com/Flowduino/ESPressio-Sockets.git"
     },
-    "version": "0.4.0",
+    "version": "0.5.0",
     "license": "Apache-2.0",
     "frameworks": "arduino",
     "platforms": "espressif32",
     "dependencies": [
+        {
+            "name": "Flowduino ESPressio-Observable",
+            "version": ">=3.0.1 <4.0.0",
+            "url": "https://github.com/Flowduino/ESPressio-Observable.git"
+        },
         {
             "owner": "links2004",
             "name": "WebSockets",

library.properties

@@ -1,11 +1,11 @@
 name=ESPressio-Sockets
-version=0.4.0
+version=0.5.0
 author=Flowduino
 maintainer=Flowduino
 sentence=Socket-based Event Transport, Command invocation, Security sessions, and System Clock synchronization for the ESPressio ecosystem.
-paragraph=Provides UDP, TCP, TLS, WebSocket and MQTT Event transports, opt-in TCP ESPressio Command invocation, opt-in ESPressio Security stream/datagram protection, and opt-in Timing synchronization.
+paragraph=Provides UDP, TCP, TLS, WebSocket and MQTT Event transports, opt-in TCP ESPressio Command invocation, opt-in ESPressio Security stream/datagram protection, observable worker/session lifecycle notifications, and opt-in Timing synchronization.
 category=Communication
 url=https://github.com/Flowduino/ESPressio-Sockets
 architectures=esp32
 includes=ESPressio_Sockets.hpp
-depends=WebSockets,PubSubClient
+depends=Flowduino ESPressio-Observable (>=3.0.1),WebSockets,PubSubClient

src/ESPressio_ISocketSecuritySessionObserver.hpp

@@ -0,0 +1,20 @@
+#pragma once
+
+#include <ESPressio_IObserver.hpp>
+#include <ESPressio_Security.hpp>
+
+namespace ESPressio::Sockets {
+
+class ISocketSecuritySessionObserver :
+    public virtual Observable::IObserver {
+public:
+    virtual ~ISocketSecuritySessionObserver() = default;
+
+    virtual void OnSocketSecuritySessionFaulted(
+        const Security::SecurityResult&
+    ) {}
+
+    virtual void OnSocketSecuritySessionReset() {}
+};
+
+} // namespace ESPressio::Sockets

src/ESPressio_ISocketWorkerObserver.hpp

@@ -0,0 +1,25 @@
+#pragma once
+
+#include <string>
+
+#include <ESPressio_IObserver.hpp>
+
+namespace ESPressio::Sockets {
+
+class ISocketWorkerObserver :
+    public virtual Observable::IObserver {
+public:
+    virtual ~ISocketWorkerObserver() = default;
+
+    virtual void OnSocketWorkerStarted(
+        const char*
+    ) {}
+
+    virtual void OnSocketWorkerStartFailed(
+        const char*
+    ) {}
+
+    virtual void OnSocketWorkerStopped() {}
+};
+
+} // namespace ESPressio::Sockets