feat: S35.02 lwIP Sockets Datagram and TcpStream by DavidCozens · Pull Request #887 · cososo-ltd/solid-syslog

DavidCozens · 2026-09-21T13:50:46Z

Purpose

The transport classes of the lwIP Sockets pack, so a build on that tier can
send as well as resolve. E35 is 2/3 after this; only the BDD target swap
(#860) remains.

Closes #859

Change Description

SolidSyslogLwipSocketDatagram fills the Datagram role over lwip_sendto, and
SolidSyslogLwipSocketTcpStream fills the Stream role over lwip_socket,
lwip_connect, lwip_send and lwip_recv, usable beneath a TLS stream. Both
use the existing role-named pools and carry no detail codes of their own.

Decisions worth the reader's time:

A refused socket option is not silent. Core gains
SOLIDSYSLOG_CAT_STREAM_OPTION_REFUSED at SOLIDSYSLOG_CAT_STREAM_BASE + 2
and one shared detail code, raised WARNING once per Open however many
options the stack declined: the connection stands, and the engineer's next
step is the same whichever one it was. It is its own category rather than
BAD_CONFIG because the BAD_CONFIG rows are Create-time verdicts reached
through the did-Create-fall-back-to-Null discriminator, and this is raised per
attempt. docs/error-severity.md gains the row.
errno is the port's job. With LWIP_PROVIDE_ERRNO unset, lwip/errno.h
includes nothing and lwip/arch.h puts errno and its codes on the port's
arch/cc.h. The adapters include lwip/errno.h as upstream intends; the host
fakes' cc.h now supplies <errno.h> beside the <sys/time.h> it already
had, and the setup page states the same obligation for a target port.
The bounded connect needs no sleep. lwip_fcntl(F_SETFL, O_NONBLOCK),
lwip_select, then lwip_getsockopt(SOL_SOCKET, SO_ERROR). The config
carries GetConnectTimeoutMs and nothing else, and the pack never raises
SOLIDSYSLOG_TCP_STREAM_ERROR_NULL_SLEEP.
One seam, whole-file gated. SolidSyslogLwipSocketTcpStream_ApplyKeepalive
has two translation units: the LWIP_TCP_KEEPALIVE build sets idle, interval
and probe count in seconds; the other sets the idle period alone, in
milliseconds, because TCP_KEEPALIVE takes a different unit from
TCP_KEEPIDLE. Only one compiles per build, so each has its own executable.
No path MTU. lwIP's sockets layer exposes no IP_MTU, so the Datagram
answers SolidSyslogUdpPayload_UnknownPath(false) and maps the stack's
EMSGSIZE to OVERSIZE so the sender retries the record trimmed rather than
whole.
Version is 0 for the stream's lifetime. Nothing about a plain socket's own
configuration moves at runtime; the destination axis travels on the sender's
endpoint version, which it polls independently.

Test Evidence

59 new tests, all driven red first against a new LwipSocketsFake
(lwip_socket, lwip_connect, lwip_send, lwip_recv, lwip_sendto,
lwip_close, lwip_fcntl, lwip_select, lwip_setsockopt,
lwip_getsockopt): 19 in SolidSyslogLwipSocketDatagramTest, 38 in
SolidSyslogLwipSocketTcpStreamTest, 2 in SolidSyslogLwipSocketTcpKeepaliveTest
(the LWIP_TCP_KEEPALIVE=1 half of the pair). All three are registered for the
junit target. Local suite: 35/35 executables pass.

Guard tests, each mutation-checked by breaking the code and watching the named
test fail:

Mutation	Test that failed
Drop the close from the Datagram's Cleanup	`DestroyClosesASocketTheDatagramStillHoldsOpen`
Drop the Null vtable swap from the Datagram's Cleanup	`SendingAfterDestroyIsASafeNoOp`
Return 0 from the Datagram's MaxPayload	`MaxPayloadIsTheUnknownPathAnswerBecauseTheStackCannotReportAPathMtu`
Drop the close from the stream's failed-connect path	all three of `AConnectThatFails` / `AConnectBudgetThatExpires` / `ADeferredError` `LeavesNoSocketOpen`
Drop the close from the stream's Cleanup	`DestroyClosesASocketTheStreamStillHoldsOpen`
Return 1 from the stream's Version	`VersionIsZeroBecauseAPlainSocketHasNothingThatMoves`
Set the gated keepalive variant's idle period in milliseconds	`AStackWithProbeTimingsTakesAllThreeInSeconds`

Two tests passed on arrival and are kept as regression guards rather than
drivers: the report-once check on refused options, and the remaining
leaves-nothing-open paths, which the table above covers by mutation.

One trap worth recording: a pool slot keeps the vtable Cleanup left behind, so
a test for an operation the pack has not filled can pass on residue from a
previous Destroy. That masked the MaxPayload red. Initialise now fills the
vtable slot by slot, the way the sibling packs do.

Gates run locally: debug suite, check_spdx_headers.py, manifest regeneration
plus check_manifest.py, clang-format over the touched sources,
misra_renumber.py (new 11.3 and 5.7 findings added to
misra_suppressions.txt; the remaining ambiguities match main), markdownlint
v0.22.1 over the changed pages, and clang-tidy over the pack, which found one
modernize-use-nodiscard on a test fixture helper.

Areas Affected

Platform/LwipSocket/ (two new classes plus the keepalive pair),
Core/Interface/SolidSyslogStreamCategories.h and
SolidSyslogTcpStreamErrors.h (additive), Tests/LwipSocket/,
Tests/Support/LwipSocketFakes/, docs/platforms/lwipsocket/,
docs/error-severity.md, docs/generated/LwipSocket-manifest.txt and
misra_suppressions.txt.

The Core additions are additive: a new category value and a new enum member
before MAX, so no existing handler changes behaviour.

Review round one

CodeRabbit posted eight comments; every one was checked against the code before
acting, and the outcomes were agreed first.

Fixed:

The stream left Fd uninitialised, so Close or Destroy on a stream that
never opened closed whatever descriptor zero belonged to. Only visible on a
pristine pool, because a released slot already carries the invalid value:
-n CloseWithNothingOpenClosesNoDescriptor on its own shows the red.
Open on a transport that was already open lost the descriptor it held. Fixed
in both classes here; chore: close the handle a transport already holds when Open is called again #889 audits every other pack for the same shape.
The stream discarded lwip_fcntl's return and would have proceeded with a
blocking socket, which is what the bounded connect rests on. It now gives the
socket back and reports ENDPOINT_UNAVAILABLE.
Socket options were applied before the connect, so a failed attempt raised
both an option refusal and a connect failure. They now go on once the
connection stands, which is what the option-refused contract says.
The platform page claimed both transports take non-blocking sockets. Only the
stream does; the page now says what each one waits on.
The repeated close-count assertion became CHECK_SOCKET_CLOSED_ONCE across
twelve sites, a stale fake comment names the setter that exists, and the recv
fake bounds its payload and reports the bytes it actually copied.

Also done, beyond the review: each keepalive variant now has a test application
of its own rather than the idle-only one riding inside the stream test, both
registered for junit. #890 does the same for the Raw tier, which took the same
shortcut first.

Declined, with reasons:

The empty-translation-unit typedef on the keepalive pair. The inactive unit
compiles clean under -Wpedantic -Werror - lwip/opt.h leaves it non-empty -
and adding the typedef earned the project its first MISRA 2.3 finding, so it
cost more than it bought. CodeRabbit withdrew the finding on that evidence.

CodeRabbit's linked-issue check also warned that the idle-only translation unit
had no executable of its own. That is now literally true as well as in spirit.

Review round two

Copilot found three, all of them documentation rather than behaviour, and all
three are fixed: two fake comments that said the opposite of what the fake does
(SetSendToFailure holds until Reset, and there is no default receive
payload), and LWIP_SOCKET_SELECT missing from the requirements. That last one
matters to an integrator: lwip_select is defined inside #if LWIP_SOCKET_SELECT, so a build with it off satisfied everything we documented
and still could not link the stream.

The connect-deadline bound was declined in round one on scope, then taken
anyway, because the fix is smaller than the argument. The deadline is bounded to
2147483 ms before the conversion - the largest that carries on every target C99
describes - so the arithmetic stays defined and the bound does not move with the
width of long. #891 asks the scope question for the sibling packs and for the
shared callback contract.

🤖 Generated with Claude Code

Summary by CodeRabbit

New Features
- Added lwIP-based IPv4 UDP datagram and non-blocking TCP stream transports.
- Added configurable connection timeouts and TCP keepalive support.
- Added connection diagnostics for refused socket options, while continuing delivery in a degraded state where possible.
Documentation
- Expanded lwIP setup, configuration, transport behaviour, error handling and severity guidance.
Tests
- Added comprehensive coverage for datagram, TCP stream, keepalive and socket-option handling.

The E11 pool plumbing copied from the pack's Resolver and renamed, with the class seam a stub, so the vtable operations can be driven test by test on top of proven allocation. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>