Mercurial

annotate seobeo/README.md @ 268:f7b1188d5fb1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
support repo rules Copilot bundle path Match both +_repo_rules2+ and +http_archive+ Copilot CLI repository layouts during deployment and production startup. Co-authored-by: Copilot <[email protected]>
author MrJuneJune <me@mrjunejune.com>
date Fri, 07 Aug 2026 13:02:41 -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