Skip to content

docs(dtls,resilient): add DTLS socket and resilient client guide#691

Merged
kcenon merged 1 commit into
mainfrom
docs/issue-687-document-dtls-socket-and-resilient-client
Feb 9, 2026
Merged

docs(dtls,resilient): add DTLS socket and resilient client guide#691
kcenon merged 1 commit into
mainfrom
docs/issue-687-document-dtls-socket-and-resilient-client

Conversation

@kcenon

@kcenon kcenon commented Feb 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Summary

  • Add docs/DTLS_RESILIENT_GUIDE.md documenting two internal utility components
  • DTLS Socket (dtls_socket): TLS encryption over UDP with OpenSSL memory BIOs
    • Memory BIO architecture diagram (rbio/wbio async I/O decoupling)
    • DTLS handshake flow (client and server sides)
    • Async send/receive API with endpoint management
    • Thread safety model (3 mutexes + 3 atomics)
  • Resilient Client (resilient_client): Auto-reconnection wrapper for messaging_client
    • Exponential backoff algorithm: initial_backoff * 2^(attempt-1), capped at 30s
    • Circuit breaker integration (WITH_COMMON_SYSTEM conditional compilation)
    • send_with_retry() flow diagram (disconnect → reconnect → resend)
    • Callback notifications for reconnection and disconnection events
  • Combined usage patterns for IoT and real-time communication
  • Production deployment patterns with recommended settings tables
  • OpenSSL 3.x requirement documentation

Resolves #687

Test Plan

  • All code examples match actual API signatures in source headers
  • All API tables are complete (no missing public methods or fields)
  • All documentation cross-references link to valid files
  • Exponential backoff formula matches implementation in resilient_client.cpp
  • Circuit breaker state diagram matches conditional compilation guards

Verification Results

All 5 test plan items PASSED with 0 discrepancies:

# Item Result Details
1 Code examples vs API signatures PASS 23 code examples verified across DTLS socket (13 methods) and resilient client (10 methods)
2 API table completeness PASS All 23 public methods documented (dtls_socket: 13, resilient_client: 10)
3 Cross-reference links PASS FACADE_GUIDE.md, UNIFIED_API_GUIDE.md, HTTP2_GUIDE.md all exist
4 Backoff formula vs implementation PASS initial_backoff * (1 << (attempt-1)) with std::min(backoff, 30s) matches exactly
5 Circuit breaker + conditional compilation PASS All #ifdef WITH_COMMON_SYSTEM guards correctly described, 3-state diagram accurate

@kcenon
docs(dtls,resilient): add DTLS socket and resilient client guide
55ffae3 
Document two internal utility components critical for production
reliability: DTLS socket (TLS over UDP with OpenSSL memory BIOs)
and resilient client (auto-reconnection with exponential backoff
and circuit breaker integration).

Resolves #687
@kcenon kcenon mentioned this pull request Feb 9, 2026
Closed
6 tasks
@github-actions

github-actions Bot commented Feb 9, 2026

Copy link
Copy Markdown
Contributor

Performance Comparison

Base Branch Results

No base results

PR Branch Results

No PR results

@kcenon kcenon merged commit 1876675 into main Feb 9, 2026
41 checks passed
@kcenon kcenon deleted the docs/issue-687-document-dtls-socket-and-resilient-client branch February 9, 2026 07:45
kcenon added a commit that referenced this pull request Apr 13, 2026
@kcenon
docs(dtls,resilient): add DTLS socket and resilient client guide (#691)
96cb43e 
Document two internal utility components critical for production
reliability: DTLS socket (TLS over UDP with OpenSSL memory BIOs)
and resilient client (auto-reconnection with exponential backoff
and circuit breaker integration).

Resolves #687
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Task] docs: Document DTLS socket and resilient client auto-reconnection

1 participant

@kcenon