include/punk_observe/po_live.h

filter: Statementstmt 100% 147 / 147 Branchbran 82.0% 82 / 100 Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 92.7% 229 / 247 CC 0 SCAR 0
CC
0
Cov
0%
CRAP 0
« include/punk_observe/po_span.h ↑ Summary include/punk_observe/po_parse.h »
1 /* po_live.h - the live tail: what it sends, and what it admits losing.
2 *
3 * A browser tailing logs is connected to ONE worker. The lines it wants are
4 * being ingested by ALL of them. So an ingesting worker publishes matching
5 * records on a per-tenant topic and whichever worker holds the connection
6 * forwards them.
7 *
8 * THE TRANSPORT REFUSES OVERSIZE RATHER THAN TRUNCATING.
9 *
10 * The ring fixes a slot and REFUSES a record that does not fit one, and the
11 * old bus before it returned HM_BUS_OVERSIZE for
12 * anything larger - refused, never shortened. Handing it a long log line
13 * therefore does not produce a short line, it produces NO line, and the tail
14 * would silently skip exactly the interesting ones: a stack trace, a
15 * serialised payload, the thing somebody is tailing to find.
16 *
17 * So the record is truncated HERE, deliberately, with a flag saying so. A
18 * truncation the reader can see is a different thing from a line that never
19 * arrived, and the difference is the entire point of this file.
20 *
21 * The same honesty runs through the rest of it. A lapped consumer, a resume
22 * past the end of the buffer and a client that stopped reading are all
23 * REPORTED with a number rather than papered over: a silently short stream is
24 * indistinguishable from a quiet one.
25 */
26 #ifndef PO_LIVE_H
27 #define PO_LIVE_H
28  
29 #include "punk_observe/po_compat.h"
30 #include "punk_observe/po_store.h"
31  
32 /* Matches HM_BUS_SLOT_SIZE. Defined independently so this header does not
33 * require the bus to exist, and asserted equal where it does. */
34 #define PO_TAIL_SLOT 2048
35  
36 /* The framing a slot carries besides the body: the fixed header below, plus
37 * headroom for the topic the bus stores alongside it. A body sized to the
38 * whole slot is a body that will be refused. */
39 #define PO_TAIL_OVERHEAD 128
40 #define PO_TAIL_BODY_MAX (PO_TAIL_SLOT - PO_TAIL_OVERHEAD)
41  
42 #define PO_TAIL_TRUNCATED 1u
43  
44 #define PO_TAIL_TOPIC_MAX (PO_TENANT_MAX + 16)
45  
46 /* ---- the topic, which is the tenant boundary ------------------------------
47 *
48 * A tail is a query and carries a tenant, so the topic contains the tenant id
49 * and a connection can subscribe only to its own. Built through the same
50 * allowlist that guards every path, because a topic that accepts arbitrary
51 * bytes is a way to subscribe to somebody else's stream. */
52 13 static size_t po_tail_topic(const char *tenant, size_t tlen,
53 char *out, size_t cap) {
54 static const char pre[] = "po.tail.";
55 13 size_t n = sizeof(pre) - 1;
56 13 ▶ if (!po_tenant_ok(tenant, tlen)) return 0;
Branch: 1 branch
BranchTrueFalseTotal
if (!po_tenant_ok(tenant, tlen)) return 0; 7 6 13
57 6 ▶ if (n + tlen >= cap) return 0;
Branch: 1 branch
BranchTrueFalseTotal
if (n + tlen >= cap) return 0; 0 6 6
58 6 memcpy(out, pre, n);
59 6 memcpy(out + n, tenant, tlen);
60 6 out[n + tlen] = '\0';
61 6 return n + tlen;
62 }
63  
64 /* ---- one record on the wire ------------------------------------------------
65 *
66 * [t_unix_nano][stream][severity][flags][service_len][body_len] bytes...
67 *
68 * Fixed fields first so a reader can size the rest before touching it. */
69 typedef struct {
70 po_u64 t_unix_nano;
71 po_u64 stream;
72 uint32_t severity;
73 uint32_t flags;
74 const char *service; size_t service_len;
75 const char *body; size_t body_len;
76 } po_tail_rec;
77  
78 /* Encode into `out`, which must hold PO_TAIL_SLOT bytes. Returns the length.
79 *
80 * THE BODY IS CUT TO FIT AND THE FLAG IS SET. Never a refusal, never a silent
81 * drop, and never a length the transport will reject. */
82 12 static size_t po_tail_encode(const po_tail_rec *r, char *out, int *truncated) {
83 12 size_t n = 0, svc = r->service_len, body = r->body_len, room;
84 uint32_t u32;
85 po_u64 u64;
86 12 int cut = 0;
87  
88 12 ▶ if (svc > 128) { svc = 128; cut = 1; }
Branch: 1 branch
BranchTrueFalseTotal
if (svc > 128) { svc = 128; cut = 1; } 1 11 12
89  
90 /* What is left for the body once the fixed fields and the service name
91 * have taken their share. Computed by subtraction, never as a sum that
92 * could overflow past the slot. */
93 12 room = PO_TAIL_BODY_MAX;
94 12 room = room > (8 + 8 + 4 + 4 + 4 + 4) ? room - (8 + 8 + 4 + 4 + 4 + 4) : 0;
95 12 ▶ room = room > svc ? room - svc : 0;
Branch: 1 branch
BranchTrueFalseTotal
room = room > svc ? room - svc : 0; 12 0 12
96 12 ▶ if (body > room) { body = room; cut = 1; }
Branch: 1 branch
BranchTrueFalseTotal
if (body > room) { body = room; cut = 1; } 3 9 12
97  
98 12 u64 = po_le64(r->t_unix_nano); memcpy(out + n, &u64, 8); n += 8;
99 12 u64 = po_le64(r->stream); memcpy(out + n, &u64, 8); n += 8;
100 12 u32 = po_le32(r->severity); memcpy(out + n, &u32, 4); n += 4;
101 12 ▶ u32 = po_le32(r->flags | (cut ? PO_TAIL_TRUNCATED : 0u));
Branch: 1 branch
BranchTrueFalseTotal
u32 = po_le32(r->flags | (cut ? PO_TAIL_TRUNCATED : 0u)); 4 8 12
102 12 memcpy(out + n, &u32, 4); n += 4;
103 12 u32 = po_le32((uint32_t)svc); memcpy(out + n, &u32, 4); n += 4;
104 12 u32 = po_le32((uint32_t)body); memcpy(out + n, &u32, 4); n += 4;
105 12 ▶ if (svc) memcpy(out + n, r->service, svc); n += svc;
Branch: 1 branch
BranchTrueFalseTotal
if (svc) memcpy(out + n, r->service, svc); n += svc; 11 1 12
106 12 ▶ if (body) memcpy(out + n, r->body, body); n += body;
Branch: 1 branch
BranchTrueFalseTotal
if (body) memcpy(out + n, r->body, body); n += body; 11 1 12
107  
108 12 ▶ if (truncated) *truncated = cut;
Branch: 1 branch
BranchTrueFalseTotal
if (truncated) *truncated = cut; 12 0 12
109 12 return n;
110 }
111  
112 /* Decode, borrowing into the buffer. Returns 0 on anything that does not add
113 * up - a slot is untrusted input the moment another process wrote it. */
114 19 static int po_tail_decode(const char *p, size_t len, po_tail_rec *r) {
115 uint32_t svc, body;
116 19 ▶ if (len < 32) return 0;
Branch: 1 branch
BranchTrueFalseTotal
if (len < 32) return 0; 3 16 19
117 16 memset(r, 0, sizeof(*r));
118 16 memcpy(&r->t_unix_nano, p, 8); r->t_unix_nano = po_le64(r->t_unix_nano);
119 16 memcpy(&r->stream, p + 8, 8); r->stream = po_le64(r->stream);
120 16 memcpy(&r->severity, p + 16, 4); r->severity = po_le32(r->severity);
121 16 memcpy(&r->flags, p + 20, 4); r->flags = po_le32(r->flags);
122 16 memcpy(&svc, p + 24, 4); svc = po_le32(svc);
123 16 memcpy(&body, p + 28, 4); body = po_le32(body);
124 /* Subtraction, not addition: `32 + svc + body > len` wraps. */
125 16 ▶ if (svc > len - 32) return 0;
Branch: 1 branch
BranchTrueFalseTotal
if (svc > len - 32) return 0; 2 14 16
126 14 ▶ if (body > len - 32 - svc) return 0;
Branch: 1 branch
BranchTrueFalseTotal
if (body > len - 32 - svc) return 0; 1 13 14
127 13 ▶ r->service = svc ? p + 32 : NULL;
Branch: 1 branch
BranchTrueFalseTotal
r->service = svc ? p + 32 : NULL; 11 2 13
128 13 r->service_len = svc;
129 13 ▶ r->body = body ? p + 32 + svc : NULL;
Branch: 1 branch
BranchTrueFalseTotal
r->body = body ? p + 32 + svc : NULL; 11 2 13
130 13 r->body_len = body;
131 13 return 1;
132 }
133  
134 12 static int po_tail_is_truncated(const po_tail_rec *r) {
135 12 return (r->flags & PO_TAIL_TRUNCATED) != 0;
136 }
137  
138 /* ---- the per-connection ring -----------------------------------------------
139 *
140 * A busy tail appends thousands of rows a minute. Unbounded, the browser tab
141 * consumes a gigabyte and stops responding within the hour, and the user's
142 * conclusion is that the product is broken. So the server-side buffer that
143 * backs Last-Event-ID is bounded too, and what falls off the end is COUNTED.
144 *
145 * Event ids are monotonic from 1. Zero means "no id", which is what a fresh
146 * connection sends. */
147 #define PO_RING_ROWS 512 /* rows held for a resume */
148 #define PO_RING_BYTES ((po_u64)512 * 1024) /* and the ceiling in bytes */
149  
150 typedef struct { po_u64 id; char *p; size_t len; } po_ring_ent;
151  
152 typedef struct {
153 po_ring_ent *e;
154 uint32_t cap, n, head;
155 po_u64 next_id; /* the id the next push will carry */
156 po_u64 evicted; /* rows that scrolled off the back */
157 po_u64 bytes, bytes_max;
158 } po_tail_ring;
159  
160 /* Bounded by BOTH rows and bytes, and the second bound is the one that
161 * matters: 512 slots at the full 2048 would be a megabyte per connection held
162 * for a resume nobody may ever ask for. Rows are stored at their real length,
163 * not at the slot size. */
164 6 static int po_tail_ring_init(po_tail_ring *r, uint32_t rows, po_u64 bytes) {
165 6 memset(r, 0, sizeof(*r));
166 6 ▶ r->cap = rows ? rows : PO_RING_ROWS;
Branch: 1 branch
BranchTrueFalseTotal
r->cap = rows ? rows : PO_RING_ROWS; 6 0 6
167 6 ▶ r->bytes_max = bytes ? bytes : PO_RING_BYTES;
Branch: 1 branch
BranchTrueFalseTotal
r->bytes_max = bytes ? bytes : PO_RING_BYTES; 1 5 6
168 6 r->next_id = 1;
169 6 r->e = (po_ring_ent *)calloc(r->cap, sizeof(po_ring_ent));
170 6 return r->e != NULL;
171 }
172  
173 6 static void po_tail_ring_free(po_tail_ring *r) {
174 uint32_t i;
175 138 ▶ if (r->e) for (i = 0; i < r->cap; i++) free(r->e[i].p);
Branch: 2 branches
BranchTrueFalseTotal
if (r->e) for (i = 0; i < r->cap; i++) free(r->e[i].p); 6 0 6
if (r->e) for (i = 0; i < r->cap; i++) free(r->e[i].p); 132 6 138
176 6 free(r->e);
177 6 r->e = NULL; r->n = 0;
178 6 }
179  
180 57 static uint32_t po_ring_tail_idx(const po_tail_ring *r) {
181 57 return (r->head + r->cap - r->n) % r->cap;
182 }
183  
184 22 static void po_ring_evict_one(po_tail_ring *r) {
185 22 uint32_t idx = po_ring_tail_idx(r);
186 22 r->bytes -= (po_u64)r->e[idx].len;
187 22 free(r->e[idx].p);
188 22 r->e[idx].p = NULL; r->e[idx].len = 0;
189 22 r->n--;
190 22 r->evicted++;
191 22 }
192  
193 /* Returns the id, or 0 if the row could not be stored. */
194 45 static po_u64 po_tail_ring_push(po_tail_ring *r, const char *p, size_t len) {
195 char *copy;
196 uint32_t idx;
197  
198 45 ▶ if (len > PO_TAIL_SLOT) len = PO_TAIL_SLOT;
Branch: 1 branch
BranchTrueFalseTotal
if (len > PO_TAIL_SLOT) len = PO_TAIL_SLOT; 0 45 45
199 45 ▶ copy = (char *)malloc(len ? len : 1);
Branch: 1 branch
BranchTrueFalseTotal
copy = (char *)malloc(len ? len : 1); 45 0 45
200 45 ▶ if (!copy) return 0;
Branch: 1 branch
BranchTrueFalseTotal
if (!copy) return 0; 0 45 45
201 45 memcpy(copy, p, len);
202  
203 45 while (r->n == r->cap
204 67 ▶ || (r->n && r->bytes + (po_u64)len > r->bytes_max))
Branch: 3 branches
BranchTrueFalseTotal
|| (r->n && r->bytes + (po_u64)len > r->bytes_max)) 6 61 67
|| (r->n && r->bytes + (po_u64)len > r->bytes_max)) 56 5 61
|| (r->n && r->bytes + (po_u64)len > r->bytes_max)) 16 40 56
205 22 po_ring_evict_one(r);
206  
207 45 idx = r->head;
208 45 free(r->e[idx].p);
209 45 r->e[idx].id = r->next_id;
210 45 r->e[idx].p = copy;
211 45 r->e[idx].len = len;
212 45 r->bytes += (po_u64)len;
213 45 r->head = (r->head + 1) % r->cap;
214 45 r->n++;
215 45 return r->next_id++;
216 }
217  
218 /* The oldest id still held, or 0 when the ring is empty. */
219 12 static po_u64 po_tail_ring_oldest(const po_tail_ring *r) {
220 12 ▶ if (!r->n) return 0;
Branch: 1 branch
BranchTrueFalseTotal
if (!r->n) return 0; 2 10 12
221 10 return r->e[po_ring_tail_idx(r)].id;
222 }
223  
224 /* Entry i of the resume window, counting from the oldest kept. */
225 25 static const po_ring_ent *po_tail_ring_at(const po_tail_ring *r, uint32_t i) {
226 25 ▶ if (i >= r->n) return NULL;
Branch: 1 branch
BranchTrueFalseTotal
if (i >= r->n) return NULL; 0 25 25
227 25 return &r->e[(po_ring_tail_idx(r) + i) % r->cap];
228 }
229  
230 /* Resume after `since`.
231 *
232 * Returns how many entries follow it and, through `missed`, HOW MANY WERE
233 * LOST between what the client last saw and the oldest thing still held. A
234 * reconnection that quietly starts from the oldest available row hides a gap,
235 * and a gap the reader cannot see is the failure this whole file exists to
236 * prevent.
237 *
238 * `since == 0` is a fresh connection: everything held, nothing missed,
239 * because it never saw anything to miss. */
240 6 static uint32_t po_tail_ring_since(const po_tail_ring *r, po_u64 since,
241 uint32_t *first, po_u64 *missed) {
242 6 po_u64 oldest = po_tail_ring_oldest(r);
243 uint32_t i;
244  
245 6 ▶ if (missed) *missed = 0;
Branch: 1 branch
BranchTrueFalseTotal
if (missed) *missed = 0; 6 0 6
246 6 ▶ if (first) *first = 0;
Branch: 1 branch
BranchTrueFalseTotal
if (first) *first = 0; 6 0 6
247 6 ▶ if (!r->n) return 0;
Branch: 1 branch
BranchTrueFalseTotal
if (!r->n) return 0; 1 5 6
248  
249 5 ▶ if (since == 0) return r->n;
Branch: 1 branch
BranchTrueFalseTotal
if (since == 0) return r->n; 2 3 5
250  
251 3 ▶ if (missed && since + 1 < oldest) *missed = oldest - since - 1;
Branch: 2 branches
BranchTrueFalseTotal
if (missed && since + 1 < oldest) *missed = oldest - since - 1; 3 0 3
if (missed && since + 1 < oldest) *missed = oldest - since - 1; 1 2 3
252 11 ▶ for (i = 0; i < r->n; i++) {
Branch: 1 branch
BranchTrueFalseTotal
for (i = 0; i < r->n; i++) { 10 1 11
253 10 const po_ring_ent *e = po_tail_ring_at(r, i);
254 10 ▶ if (e->id > since) { if (first) *first = i; return r->n - i; }
Branch: 2 branches
BranchTrueFalseTotal
if (e->id > since) { if (first) *first = i; return r->n - i; } 2 8 10
if (e->id > since) { if (first) *first = i; return r->n - i; } 2 0 2
255 }
256 1 return 0;
257 }
258  
259 /* ---- backpressure ----------------------------------------------------------
260 *
261 * A browser that has stopped reading must not become an unbounded queue in
262 * the server. Over the threshold the connection is CLOSED WITH A REASON,
263 * which the client can act on, rather than the worker growing a buffer until
264 * something else fails. */
265 typedef struct {
266 po_u64 pending; /* bytes written but not yet drained */
267 po_u64 limit;
268 po_u64 dropped; /* rows never queued because the client was behind */
269 int closed;
270 } po_tail_flow;
271  
272 3 static void po_tail_flow_init(po_tail_flow *f, po_u64 limit) {
273 3 memset(f, 0, sizeof(*f));
274 3 ▶ f->limit = limit ? limit : (po_u64)1024 * 1024;
Branch: 1 branch
BranchTrueFalseTotal
f->limit = limit ? limit : (po_u64)1024 * 1024; 3 0 3
275 3 }
276  
277 /* Returns 1 when the row may be queued, 0 when the connection has been closed
278 * for falling too far behind. */
279 101 static int po_tail_flow_admit(po_tail_flow *f, size_t bytes) {
280 101 ▶ if (f->closed) return 0;
Branch: 1 branch
BranchTrueFalseTotal
if (f->closed) return 0; 39 62 101
281 62 ▶ if (f->pending + (po_u64)bytes > f->limit) {
Branch: 1 branch
BranchTrueFalseTotal
if (f->pending + (po_u64)bytes > f->limit) { 2 60 62
282 2 f->closed = 1;
283 2 f->dropped++;
284 2 return 0;
285 }
286 60 f->pending += (po_u64)bytes;
287 60 return 1;
288 }
289  
290 50 static void po_tail_flow_drained(po_tail_flow *f, size_t bytes) {
291 50 ▶ f->pending = f->pending > (po_u64)bytes ? f->pending - (po_u64)bytes : 0;
Branch: 1 branch
BranchTrueFalseTotal
f->pending = f->pending > (po_u64)bytes ? f->pending - (po_u64)bytes : 0; 0 50 50
292 50 }
293  
294 /* ---- the SSE frame ---------------------------------------------------------
295 *
296 * `id:` is what makes Last-Event-ID work at all, so it is never omitted. A
297 * frame ends with a blank line, and a body containing a newline has to be
298 * split across `data:` lines or the frame ends early and the rest of the line
299 * becomes the next event. */
300 4 static size_t po_sse_frame(po_u64 id, const char *ev, size_t evlen,
301 const char *data, size_t dlen,
302 char *out, size_t cap) {
303 4 size_t n = 0, i, start;
304 char idbuf[24];
305 4 size_t idn = 0;
306 4 po_u64 v = id;
307  
308 4 ▶ if (v == 0) idbuf[idn++] = '0';
Branch: 1 branch
BranchTrueFalseTotal
if (v == 0) idbuf[idn++] = '0'; 1 3 4
309 3 else { char t[24]; size_t k = 0;
310 6 ▶ while (v) { t[k++] = (char)('0' + (int)(v % 10)); v /= 10; }
Branch: 1 branch
BranchTrueFalseTotal
while (v) { t[k++] = (char)('0' + (int)(v % 10)); v /= 10; } 3 3 6
311 6 ▶ while (k) idbuf[idn++] = t[--k]; }
Branch: 1 branch
BranchTrueFalseTotal
while (k) idbuf[idn++] = t[--k]; } 3 3 6
312  
313 4 ▶ if (cap < idn + evlen + dlen + 32) return 0;
Branch: 1 branch
BranchTrueFalseTotal
if (cap < idn + evlen + dlen + 32) return 0; 0 4 4
314  
315 4 memcpy(out + n, "id: ", 4); n += 4;
316 4 memcpy(out + n, idbuf, idn); n += idn;
317 4 out[n++] = '\n';
318  
319 4 ▶ if (evlen) {
Branch: 1 branch
BranchTrueFalseTotal
if (evlen) { 3 1 4
320 3 memcpy(out + n, "event: ", 7); n += 7;
321 3 memcpy(out + n, ev, evlen); n += evlen;
322 3 out[n++] = '\n';
323 }
324  
325 4 start = 0;
326 36 ▶ for (i = 0; i <= dlen; i++) {
Branch: 1 branch
BranchTrueFalseTotal
for (i = 0; i <= dlen; i++) { 36 0 36
327 36 ▶ if (i == dlen || data[i] == '\n') {
Branch: 2 branches
BranchTrueFalseTotal
if (i == dlen || data[i] == '\n') { 32 4 36
if (i == dlen || data[i] == '\n') { 2 30 32
328 6 memcpy(out + n, "data: ", 6); n += 6;
329 6 ▶ if (i > start) memcpy(out + n, data + start, i - start);
Branch: 1 branch
BranchTrueFalseTotal
if (i > start) memcpy(out + n, data + start, i - start); 5 1 6
330 6 n += i - start;
331 6 out[n++] = '\n';
332 6 start = i + 1;
333 6 ▶ if (i == dlen) break;
Branch: 1 branch
BranchTrueFalseTotal
if (i == dlen) break; 4 2 6
334 }
335 }
336 4 out[n++] = '\n';
337 4 return n;
338 }
339  
340 /* An idle stream is closed by intermediaries, so a heartbeat is not optional.
341 * A comment frame carries no event and no id, which is exactly right: it must
342 * not advance a client's Last-Event-ID. */
343 1 static size_t po_sse_heartbeat(char *out, size_t cap) {
344 1 ▶ if (cap < 3) return 0;
Branch: 1 branch
BranchTrueFalseTotal
if (cap < 3) return 0; 0 1 1
345 1 memcpy(out, ":\n\n", 3);
346 1 return 3;
347 }
348  
349 #endif /* PO_LIVE_H */
« include/punk_observe/po_span.h ↑ Summary include/punk_observe/po_parse.h »