Mercurial

annotate .claude/skills/zenbu-seobeo-networking/SKILL.md @ 250:745fd127b2a1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[seobeo] Add bounded worker interface Co-authored-by: Copilot <[email protected]>
author MrJuneJune <me@mrjunejune.com>
date Tue, 04 Aug 2026 06:23:37 -0700
parents b8b6e726964a
children 609d3c6aff4e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
248
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
1 ---
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
2 name: zenbu-seobeo-networking
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
3 description: Use this skill when changing or extending seobeo, the C networking layer for HTTP clients, HTTP/static servers, routing, streaming, TLS, or WebSockets.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
4 ---
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
5
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
6 # Seobeo Networking
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
7
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
8 Use this skill for the `seobeo/` networking library and any server code built on top of it.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
9
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
10 ## Mental model
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
11
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
12 `seobeo` is the shared C networking layer. It provides:
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
13
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
14 - TCP server/client handles in `s_network.c`.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
15 - TLS helpers in `s_ssl.c`.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
16 - Static file and HTTP routing in `s_web.c`.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
17 - Curl-like HTTP client APIs in `s_http_client.c`.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
18 - WebSocket client/server support in `s_websocket*.c`.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
19 - Snapshot/test utilities in `snapshot_creator.c`.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
20 - Public API declarations in `seobeo/seobeo.h`.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
21 - Internal types in `seobeo/seobeo_internal.h`.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
22
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
23 Prefer using public APIs from `seobeo.h` in applications. Only reach into internals when modifying seobeo itself.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
24
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
25 ## Common APIs
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
26
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
27 HTTP client:
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
28
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
29 ```c
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
30 Seobeo_Client_Request *p_req = Seobeo_Client_Request_Create("https://example.com/path");
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
31 Seobeo_Client_Request_Set_Method(p_req, "GET");
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
32 Seobeo_Client_Request_Add_Header_Array(p_req, "Accept: application/json");
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
33 Seobeo_Client_Response *p_resp = Seobeo_Client_Request_Execute(p_req);
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
34 Seobeo_Client_Request_Destroy(p_req);
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
35 Seobeo_Client_Response_Destroy(p_resp);
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
36 ```
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
37
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
38 HTTP routes:
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
39
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
40 ```c
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
41 Seobeo_Router_Init();
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
42 Seobeo_Router_Register("GET", "/api/example/:id", Handler);
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
43 Seobeo_Web_Server_Start("site/src", "8080", SEOBEO_MODE_EDGE, 1);
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
44 Seobeo_Router_Destroy();
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
45 ```
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
46
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
47 Route handler shape:
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
48
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
49 ```c
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
50 Seobeo_Request_Entry *Handler(Seobeo_Request_Entry *req, Dowa_Arena *arena)
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
51 {
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
52 Seobeo_Request_Entry *resp = NULL;
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
53 Dowa_HashMap_Push_Arena(resp, "status", "200", arena);
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
54 Dowa_HashMap_Push_Arena(resp, "content-type", "application/json", arena);
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
55 Dowa_HashMap_Push_Arena(resp, "body", "{\"ok\":true}", arena);
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
56 return resp;
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
57 }
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
58 ```
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
59
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
60 WebSocket server:
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
61
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
62 ```c
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
63 Seobeo_WebSocket_Server_Init();
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
64 Seobeo_WebSocket_Server_Register("/chat", Chat_Handler, NULL);
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
65 ```
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
66
250
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
67 Background work:
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
68
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
69 ```c
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
70 Seobeo_Worker_Pool *pool = Seobeo_Worker_Pool_Create(2, 16);
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
71 Seobeo_Worker_Pool_Submit(pool, Process_File, context, free);
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
72 Seobeo_Worker_Pool_Shutdown(pool, TRUE);
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
73 Seobeo_Worker_Pool_Destroy(pool);
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
74 ```
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
75
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
76 Use `Seobeo_Thread_Start` + `Seobeo_Thread_Join` for one joinable task, or
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
77 `Seobeo_Thread_Start_Detached` for fire-and-forget work. Prefer a bounded pool
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
78 for request-triggered FFmpeg, upload, or other expensive jobs.
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
79
248
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
80 ## Build targets
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
81
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
82 Choose the smallest library variant that matches the feature:
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
83
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
84 - `//seobeo:seobeo_min`: TCP/SSL basics.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
85 - `//seobeo:seobeo_tcp_server`: HTTP server, no WebSocket, no SSL.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
86 - `//seobeo:seobeo_tcp_server_ws`: HTTP server with WebSocket.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
87 - `//seobeo:seobeo_tcp_client`: HTTP client.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
88 - `//seobeo:seobeo_tcp_client_ws`: HTTP client with WebSocket.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
89 - `//seobeo:seobeo`: full combined library.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
90 - `//seobeo:seobeo_debug`: full library with debug logging.
250
745fd127b2a1 [seobeo] Add bounded worker interface
MrJuneJune <me@mrjunejune.com>
parents: 248
diff changeset
91 - `//seobeo:seobeo_worker`: standalone thread/worker-pool API.
248
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
92
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
93 ## Tests
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
94
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
95 Run the narrowest relevant tests first:
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
96
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
97 ```bash
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
98 bazel test //seobeo:seobeo_client_test
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
99 bazel test //seobeo:seobeo_websocket_test
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
100 bazel test //seobeo:seobeo_websocket_server_test
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
101 ```
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
102
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
103 For API changes, also build downstream users:
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
104
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
105 ```bash
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
106 bazel build //mrjunejune:mrjunejune_server //hg-web:hg_web_server
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
107 ```
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
108
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
109 ## Safety checklist
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
110
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
111 - Use Dowa aliases such as `uint8`, `uint32`, and `boolean` with
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
112 `TRUE`/`FALSE`; avoid adding `<stdint.h>` `_t` types or `<stdbool.h>` `bool`
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
113 to first-party C when the Dowa equivalent exists.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
114 - Keep binary bodies binary-safe: use explicit lengths and `Dowa_Arena_Copy`/`memcpy`, not `strlen`, when forwarding arbitrary bytes.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
115 - Destroy `Seobeo_Client_Request`, `Seobeo_Client_Response`, `Seobeo_Handle`, and WebSocket messages on owned paths.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
116 - Do not swallow network errors. Return explicit HTTP 4xx/5xx responses or propagate error codes.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
117 - Preserve keep-alive, content-length, and response header behavior when touching routing or streaming.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
118 - Be careful with request map keys: existing code uses keys such as `Body`, `Content-Length`, `Authorization`, `HTTP_Method`, `QueryString`, route params like `:filename`, and query-derived keys like `query_path`.
b8b6e726964a [style] Use Dowa type aliases in C
MrJuneJune <me@mrjunejune.com>
parents:
diff changeset
119 - For WebSockets, respect RFC 6455 requirements: client frames masked, fragmentation handled, control frames handled, and close paths cleaned up.