docs: S23.22 hold the lwIP page to what the adapters do (#744)

* docs: S23.22 hold the lwIP page to what the adapters do

An over-large record has three fates here, decided by IP_FRAG rather than by the
adapter, and the page described none of them. Keepalive is enabled but never
tuned, so a silent peer goes unnoticed for lwIP's default two hours; #743 tracks
giving the library its own tunable.

The two resolvers now say which to choose and link each other, rather than
leaving the reader to infer it from the setup page's advice to wire both.

Part of #708.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs: correct the lwIP fragmentation and NULL-Sleep claims

IP_FRAG=1 attempts fragmentation and submits best-effort; ip4_frag can fail on
allocation and does not propagate output errors, so "fragmented and delivered"
overstated it.

A NULL Sleep does not fail the Create — it returns the shared Null object, and
reports nothing at all, which is the more useful thing to say.

The resolver choice now links both API pages.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: DavidCozens

Platform/LwipRaw/Interface/SolidSyslogLwipRawDnsResolver.h

@@ -1,7 +1,12 @@
 /** @file
- *  A by-name DNS resolver for lwIP Raw targets — a superset of the numeric
- *  resolver (literals, DNS-cache hits, and local-hostlist entries also
- *  resolve).
+ *  The lwIP Raw resolver for a collector named by name, resolving names and
+ *  numeric addresses alike.
+ *
+ *  Choosing between the two: this one where the endpoint may be a name, since a
+ *  literal, a DNS-cache hit and a local-hostlist entry all resolve through it
+ *  too; SolidSyslogLwipRawResolver.h where the endpoint is always an address,
+ *  which needs neither LWIP_DNS nor a Sleep and takes no marshal hop. A build
+ *  wires whichever one its deployment needs.
  *
  *  Resolve wraps lwIP's asynchronous dns_gethostbyname, which touches lwIP core
  *  state and so runs under the SolidSyslogLwipRaw_Marshal hop (unlike the

Platform/LwipRaw/Interface/SolidSyslogLwipRawResolver.h

@@ -1,12 +1,18 @@
 /** @file
- *  A numeric-only resolver for lwIP Raw targets with no DNS.
+ *  The lwIP Raw resolver for a collector named by address: it resolves nothing,
+ *  it parses the numeric literal you configured.
  *
  *  Resolve delegates to lwIP's ipaddr_aton to parse the endpoint host as a
  *  numeric IP literal, writing it into the destination SolidSyslogAddress;
  *  whatever ipaddr_aton accepts is accepted, whatever it rejects (DNS names,
  *  the empty string, and other non-address text) fails the Resolve, so the caller's
  *  unresolved-host error path runs. The transport is ignored. The parse touches
- *  no lwIP core state, so unlike the DNS sibling it takes no marshal hop. */
+ *  no lwIP core state, so it takes no marshal hop.
+ *
+ *  Choosing between the two: this one where the endpoint is always an address,
+ *  since it needs neither LWIP_DNS nor a Sleep;
+ *  SolidSyslogLwipRawDnsResolver.h where it may be a name, which resolves names
+ *  and addresses alike. A build wires whichever one its deployment needs. */
 #ifndef SOLIDSYSLOGLWIPRAWRESOLVER_H
 #define SOLIDSYSLOGLWIPRAWRESOLVER_H
 

docs/platforms/lwipraw/index.md

@@ -33,7 +33,10 @@ callback runs, so a mailbox marshal has to wait for completion itself.
 ## Requirements
 
 The source calls lwIP only — no direct OS calls. The TCP stream's synchronous
-Open needs a bounded sleep, injected as a `SolidSyslogSleepFunction`.
+Open and the DNS resolver's bounded wait both need a sleep, injected as a
+`SolidSyslogSleepFunction`. Create it without one and you get the shared Null
+object back, with nothing reported: the wiring looks like it worked and no record
+is ever delivered.
 
 Your `lwipopts.h` must enable the features the adapter wraps:
 
@@ -46,7 +49,10 @@ Your `lwipopts.h` must enable the features the adapter wraps:
 
 Also set `ARP_QUEUEING=1` (else the first datagram to an unresolved peer is
 dropped) and `LWIP_TCP_KEEPALIVE=1`, and size `PBUF_POOL_SIZE` /
-`MEMP_NUM_TCP_PCB` / `MEMP_NUM_UDP_PCB` to your instance counts.
+`MEMP_NUM_TCP_PCB` / `MEMP_NUM_UDP_PCB` to your instance counts. `IP_FRAG`
+decides what becomes of a record too large for the path — see
+[an over-large record has three possible fates](#an-over-large-record-has-three-possible-fates)
+below.
 
 ## Security behaviour and obligations
 
@@ -65,6 +71,49 @@ are read the moment the hop returns. An asynchronous marshal, or none at all,
 corrupts lwIP's internal state rather than failing cleanly. Install it once at
 boot, before any adapter is created.
 
+### An over-large record has three possible fates
+
+The datagram reports the IPv6-safe payload of 1232 bytes from `MaxPayload` and
+cannot tell an over-large datagram from any other send failure, which the
+[Datagram](../../api/structSolidSyslogDatagram.md) contract permits. Because the
+sender only trims a record after being told it was too large, one over that size
+reaches lwIP whole, and what happens next is `IP_FRAG`'s decision rather than the
+adapter's:
+
+- **`IP_FRAG=1`**, lwIP's default: lwIP attempts to fragment the datagram and
+  submits the fragments to your interface. Allocating them can fail, and
+  submission is not delivery — this is the case RFC 5426 §3.2 warns about, where
+  a lost fragment costs the whole record and some collectors and middleboxes
+  drop fragments outright.
+- **`IP_FRAG=0`**: lwIP compiles the length check out of its send path
+  altogether and hands the over-length packet to your driver. A driver that drops
+  it and answers `ERR_OK` loses the record while the store counts it delivered; a
+  driver that answers an error fails the send, and a failed send is treated as
+  transient, so the store re-offers the same record on every pass and nothing
+  behind it is delivered.
+
+`SOLIDSYSLOG_MAX_MESSAGE_SIZE` defaults to 2048, so this reaches any record over
+about 1.2 KB rather than only unusual ones. Keep records on this UDP path inside
+the payload it carries — noting that the limit is library-wide rather than
+per-transport, so lowering it truncates records on every transport the instance
+uses.
+
+### Dead-peer detection runs at lwIP's defaults
+
+The stream enables keepalive and leaves the timings to the stack, so a silent
+peer is first probed after lwIP's default two hours and the connection is
+declared dead around eleven minutes after that. Those defaults are compile-time
+and stack-wide, so changing them means `TCP_KEEPIDLE_DEFAULT` and its siblings in
+your `lwipopts.h` — which moves every TCP connection in your system, not only
+this one. `LWIP_TCP_KEEPALIVE=1` does not alter the timings; it makes the
+interval and probe count per-connection fields, which is what
+[#743](https://github.com/cososo-ltd/solid-syslog/issues/743) needs to give the
+library its own setting and apply it here.
+
+This governs the idle case only. A connection actually carrying records notices
+a dead peer sooner: lwIP's send buffer fills, the write fails, and the stream
+closes itself so the sender reconnects.
+
 ### Resolution is trusted as the stack returns it
 
 The DNS resolver forwards what lwIP answers. A deployment that cannot trust its
@@ -74,5 +123,7 @@ exists to be poisoned.
 ### Pool sizing is yours, and exhaustion is silent at the stack
 
 `PBUF_POOL_SIZE`, `MEMP_NUM_TCP_PCB` and `MEMP_NUM_UDP_PCB` must cover the
-instances you create alongside everything else using the stack. Under-sizing
-shows as dropped records rather than as an error from lwIP.
+instances you create alongside everything else using the stack. lwIP reports
+nothing when it runs out; what you see is the send failing, which reaches you as
+a delivery failure through the error handler rather than as anything naming the
+pool that was exhausted.

docs/platforms/lwipraw/setup.md

@@ -149,10 +149,12 @@ resolves entirely on-device:
     { DNS_LOCAL_HOSTLIST_ELEM("collector", IPADDR4_INIT_BYTES(10, 0, 2, 2)) }
 ```
 
-Both resolvers draw from one pool, so wiring the numeric and the DNS resolver
-together needs `SOLIDSYSLOG_RESOLVER_POOL_SIZE` raised to 2. The pool sizes and
-timeouts are in
-[Adding it to your build](../../build-integration.md#tunables).
+Wire whichever resolver your deployment needs:
+[`SolidSyslogLwipRawResolver`](../../api/SolidSyslogLwipRawResolver_8h.md) for an
+endpoint given as an address, or
+[`SolidSyslogLwipRawDnsResolver`](../../api/SolidSyslogLwipRawDnsResolver_8h.md)
+for one that may be a name. Each says which fits. The pool sizes and timeouts are
+in [Adding it to your build](../../build-integration.md#tunables).
 
 ## Limits