Mercurial

annotate seobeo/README.md @ 279:b3b547563ec7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add Google connector service and agent wiki Implement the C/Seobeo Google Drive and Gmail connector with encrypted OAuth storage, Zenbu authentication, browser testing, AI tool discovery, chunked HTTP decoding, and Bazel coverage. Consolidate repository guidance into progressive wiki documentation and enforce arena-first allocation for new first-party C code. Co-authored-by: Copilot <[email protected]> Copilot-Session: 84c338fd-0939-4bb3-b7f3-1062eb213e5d
author MrJuneJune <me@mrjunejune.com>
date Mon, 17 Aug 2026 22:22:36 -0700
parents 609d3c6aff4e
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
1 # seobeo
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
2
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
3 HTTP client and networking library for C.
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
4
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
5 ## Features
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
6
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
7 - HTTP/HTTPS client
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
8 - SSL/TLS support
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
9 - Async networking with libuv
250
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
10 - Joinable/detached tasks and bounded worker pools
257
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
11 - Server-Sent Events routes and event framing
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
12 - Snapshot testing utilities
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
13
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
14 ## Files
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
15
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
16 | File | Description |
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
17 |------|-------------|
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
18 | `seobeo.h` | Public API header |
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
19 | `seobeo_internal.h` | Internal declarations |
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
20 | `s_http_client.c` | HTTP client implementation |
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
21 | `s_network.c` | Network utilities |
257
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
22 | `s_sse.c` | Server-Sent Events framing and stream lifecycle |
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
23 | `s_ssl.c` | SSL/TLS handling |
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
24 | `s_logging.c` | Logging utilities |
250
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
25 | `s_worker.c` | Thread and worker-pool implementation |
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
26 | `seobeo_worker.h` | Public worker API |
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
27 | `snapshot_creator.c/h` | Snapshot testing |
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
28 | `docs/` | Documentation |
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
29 | `examples/` | Usage examples |
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
30 | `tests/` | Unit tests |
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
31 | `os/` | OS-specific code |
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
32
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
33 ## Usage
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
34
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
35 ```c
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
36 #include "seobeo/seobeo.h"
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
37
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
38 // Make HTTP request
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
39 HttpResponse* resp = http_get("https://example.com");
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
40 // handle response...
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
41 http_response_free(resp);
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
42 ```
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
43
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
44 ## Building
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
45
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
46 ```bash
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
47 bazel build //seobeo:seobeo
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
48 bazel test //seobeo:seobeo_test
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
49 ```
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
50
250
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
51 ## Background workers
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
52
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
53 Use a detached task for simple fire-and-forget work:
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
54
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
55 ```c
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
56 void Convert_Image(void *p_context)
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
57 {
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
58 Conversion *p_conversion = p_context;
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
59 Run_FFmpeg(p_conversion);
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
60 }
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
61
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
62 Seobeo_Worker_Result result =
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
63 Seobeo_Thread_Start_Detached(
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
64 Convert_Image,
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
65 p_conversion,
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
66 free);
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
67 if (result != SEOBEO_WORKER_OK)
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
68 free(p_conversion);
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
69 ```
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
70
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
71 Use a bounded pool when requests can enqueue expensive work:
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
72
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
73 ```c
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
74 Seobeo_Worker_Pool *p_pool =
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
75 Seobeo_Worker_Pool_Create(2, 16);
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
76
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
77 Seobeo_Worker_Result result =
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
78 Seobeo_Worker_Pool_Submit(
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
79 p_pool,
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
80 Convert_Image,
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
81 p_conversion,
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
82 free);
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
83
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
84 Seobeo_Worker_Pool_Shutdown(p_pool, TRUE);
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
85 Seobeo_Worker_Pool_Destroy(p_pool);
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
86 ```
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
87
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
88 Submitting transfers context ownership only when it returns
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
89 `SEOBEO_WORKER_OK`. Cleanup runs after successful work and for queued tasks
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
90 discarded by a non-draining shutdown. User callbacks never run while the pool
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
91 mutex is held.
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 192
diff changeset
92
257
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
93 ## Server-Sent Events
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
94
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
95 Register an SSE route separately from ordinary response and stream handlers:
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
96
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
97 ```c
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
98 static void Build_Events(
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
99 Seobeo_SSE_Stream *p_stream,
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
100 Seobeo_Request_Entry *p_request,
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
101 Dowa_Arena *p_arena)
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
102 {
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
103 (void)p_request;
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
104 (void)p_arena;
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
105 Seobeo_SSE_Event event = {
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
106 .event = "build",
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
107 .id = "42",
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
108 .data = "started\ncompiling",
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
109 .retry_ms = 2000,
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
110 };
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
111 Seobeo_SSE_Send(p_stream, &event);
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
112 Seobeo_SSE_Send_Comment(p_stream, "heartbeat");
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
113 }
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
114
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
115 Seobeo_Router_Register_SSE("/events/builds", Build_Events);
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
116 ```
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
117
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
118 SSE handlers run once when a client connects and must return promptly so edge
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
119 workers remain available. Call `Seobeo_SSE_Retain` before storing a stream for
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
120 later work and pair it with `Seobeo_SSE_Release`; use
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
121 `Seobeo_SSE_Is_Open` before sending. Do not retain the request map or arena
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
122 after the handler returns. A return value of `1` means the record was retained
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
123 behind socket backpressure and `Seobeo_SSE_Flush` should be retried later.
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
124 `SEOBEO_SSE_BACKPRESSURE` means the bounded pending queue is full and the new
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
125 record was not accepted. Events are bounded by the handle write-buffer
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
126 capacity so one record is queued atomically; larger records return
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
127 `SEOBEO_SSE_EVENT_TOO_LARGE`.
609d3c6aff4e [seobeo] Add persistent SSE streams
MrJuneJune <me@mrjunejune.com>
parents: 250
diff changeset
128
192
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
129 ## Dependencies
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
130
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
131 - libuv (via //third_party/libuv)
b818a4561a3c Added AI genreated README.md. Needed to be read.
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
132 - OpenSSL