link.go RawHistoryFolder

1package ports
2
3import "time"
4
5// LinkState reports best-effort transport health without changing Transport.
6// Implementations may distinguish authenticated path contact from useful
7// stream progress when classifying the link.
8type LinkState int
9
10const (
11	// LinkStateConnected means a complete record or meaningful acknowledgement
12	// progress was observed recently.
13	LinkStateConnected LinkState = iota
14	// LinkStateDegraded means authenticated packets still reach the path, but
15	// complete records and acknowledgement progress have stalled.
16	LinkStateDegraded
17	// LinkStateProbing means packet contact is silent or pending data has made no
18	// round-trip progress long enough for path recovery to begin.
19	LinkStateProbing
20	// LinkStateOffline means authenticated packet contact has been absent long
21	// enough for the client to resume over its fallback transport.
22	LinkStateOffline
23	// LinkStateDead means prolonged authenticated-packet silence has made the
24	// transport terminal.
25	LinkStateDead
26)
27
28func (s LinkState) String() string {
29	switch s {
30	case LinkStateConnected:
31		return "connected"
32	case LinkStateDegraded:
33		return "degraded"
34	case LinkStateProbing:
35		return "probing"
36	case LinkStateOffline:
37		return "offline"
38	case LinkStateDead:
39		return "dead"
40	default:
41		return "unknown"
42	}
43}
44
45// LinkEvent is emitted when a transport's observed link state changes.
46type LinkEvent struct {
47	State LinkState
48	At    time.Time
49	Err   error
50}
51
52// LinkStateReporter is an optional boundary-safe port implemented by transports
53// that can report link degradation before Transport fails terminally.
54//
55// LinkEvents returns a best-effort event stream. Implementations must not block
56// transport progress while publishing events; use a buffered channel and drop
57// events when the consumer is slow. The channel is not required to close on
58// transport shutdown, so consumers should also watch their own context or the
59// underlying Transport result.
60type LinkStateReporter interface {
61	LinkState() LinkState
62	LinkEvents() <-chan LinkEvent
63}