1# `lws_retry_bo_t` client connection management 2 3This struct sets the policy for delays between retries, and for 4how long a connection may be 'idle' before it first tries to 5ping / pong on it to confirm it's up, or drops the connection 6if still idle. 7 8## Retry rate limiting 9 10You can define a table of ms-resolution delays indexed by which 11connection attempt number is ongoing, this is pointed to by 12`.retry_ms_table` with `.retry_ms_table_count` containing the 13count of table entries. 14 15`.conceal_count` is the number of retries that should be allowed 16before informing the parent that the connection has failed. If it's 17greater than the number of entries in the table, the last entry is 18reused for the additional attempts. 19 20`.jitter_percent` controls how much additional random delay is 21added to the actual interval to be used... this stops a lot of 22devices all synchronizing when they try to connect after a single 23trigger event and DDoS-ing the server. 24 25The struct and apis are provided for user implementations, lws does 26not offer reconnection itself. 27 28## Connection validity management 29 30Lws has a sophisticated idea of connection validity and the need to 31reconfirm that a connection is still operable if proof of validity 32has not been seen for some time. It concerns itself only with network 33connections rather than streams, for example, it only checks h2 34network connections rather than the individual streams inside (which 35is consistent with h2 PING frames only working at the network stream 36level itself). 37 38Connections may fail in a variety of ways, these include that no traffic 39at all is passing, or, eg, incoming traffic may be received but no 40outbound traffic is making it to the network, and vice versa. In the 41case that tx is not failing at any point but just isn't getting sent, 42endpoints can potentially kid themselves that since "they are sending" 43and they are seeing RX, the combination means the connection is valid. 44This can potentially continue for a long time if the peer is not 45performing keepalives. 46 47"Connection validity" is proven when one side sends something and later 48receives a response that can only have been generated by the peer 49receiving what was just sent. This can happen for some kinds of user 50transactions on any stream using the connection, or by sending PING / 51PONG protocol packets where the PONG is only returned for a received PING. 52 53To ensure that the generated traffic is only sent when necessary, user 54code can report for any stream that it has observed a transaction amounting 55to a proof of connection validity using an api. This resets the timer for 56the associated network connection before the validity is considered 57expired. 58 59`.secs_since_valid_ping` in the retry struct sets the number of seconds since 60the last validity after which lws will issue a protocol-specific PING of some 61kind on the connection. `.secs_since_valid_hangup` specifies how long lws 62will allow the connection to go without a confirmation of validity before 63simply hanging up on it. 64 65## Defaults 66 67The context defaults to having a 5m valid ping interval and 5m10s hangup interval, 68ie, it'll send a ping at 5m idle if the protocol supports it, and if no response 69validating the connection arrives in another 10s, hang up the connection. 70 71User code can set this in the context creation info and can individually set the 72retry policy per vhost for server connections. Client connections can set it 73per connection in the client creation info `.retry_and_idle_policy`. 74 75## Checking for h2 and ws 76 77Check using paired minimal examples with the -v flag on one or both sides to get a 78small validity check period set of 3s / 10s 79 80Also give, eg, -d1039 to see info level debug logging 81 82### h2 83 84``` 85$ lws-minimal-http-server-h2-long-poll -v 86 87$ lws-minimal-http-client -l -v 88``` 89 90### ws 91 92``` 93$ lws-minimal-ws-server-h2 -s -v 94 95$ lws-minimal-ws-client-ping -n --server 127.0.0.1 --port 7681 -v 96``` 97 98 99