Mercurial

comparison .claude/skills/zenbu-seobeo-networking/SKILL.md @ 248:b8b6e726964a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[style] Use Dowa type aliases in C Co-authored-by: Copilot <[email protected]>
author MrJuneJune <me@mrjunejune.com>
date Tue, 04 Aug 2026 02:44:06 -0700
parents
children 745fd127b2a1
comparison
equal deleted inserted replaced
247:70f2a3dafc1c 248:b8b6e726964a
1 ---
2 name: zenbu-seobeo-networking
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.
4 ---
5
6 # Seobeo Networking
7
8 Use this skill for the `seobeo/` networking library and any server code built on top of it.
9
10 ## Mental model
11
12 `seobeo` is the shared C networking layer. It provides:
13
14 - TCP server/client handles in `s_network.c`.
15 - TLS helpers in `s_ssl.c`.
16 - Static file and HTTP routing in `s_web.c`.
17 - Curl-like HTTP client APIs in `s_http_client.c`.
18 - WebSocket client/server support in `s_websocket*.c`.
19 - Snapshot/test utilities in `snapshot_creator.c`.
20 - Public API declarations in `seobeo/seobeo.h`.
21 - Internal types in `seobeo/seobeo_internal.h`.
22
23 Prefer using public APIs from `seobeo.h` in applications. Only reach into internals when modifying seobeo itself.
24
25 ## Common APIs
26
27 HTTP client:
28
29 ```c
30 Seobeo_Client_Request *p_req = Seobeo_Client_Request_Create("https://example.com/path");
31 Seobeo_Client_Request_Set_Method(p_req, "GET");
32 Seobeo_Client_Request_Add_Header_Array(p_req, "Accept: application/json");
33 Seobeo_Client_Response *p_resp = Seobeo_Client_Request_Execute(p_req);
34 Seobeo_Client_Request_Destroy(p_req);
35 Seobeo_Client_Response_Destroy(p_resp);
36 ```
37
38 HTTP routes:
39
40 ```c
41 Seobeo_Router_Init();
42 Seobeo_Router_Register("GET", "/api/example/:id", Handler);
43 Seobeo_Web_Server_Start("site/src", "8080", SEOBEO_MODE_EDGE, 1);
44 Seobeo_Router_Destroy();
45 ```
46
47 Route handler shape:
48
49 ```c
50 Seobeo_Request_Entry *Handler(Seobeo_Request_Entry *req, Dowa_Arena *arena)
51 {
52 Seobeo_Request_Entry *resp = NULL;
53 Dowa_HashMap_Push_Arena(resp, "status", "200", arena);
54 Dowa_HashMap_Push_Arena(resp, "content-type", "application/json", arena);
55 Dowa_HashMap_Push_Arena(resp, "body", "{\"ok\":true}", arena);
56 return resp;
57 }
58 ```
59
60 WebSocket server:
61
62 ```c
63 Seobeo_WebSocket_Server_Init();
64 Seobeo_WebSocket_Server_Register("/chat", Chat_Handler, NULL);
65 ```
66
67 ## Build targets
68
69 Choose the smallest library variant that matches the feature:
70
71 - `//seobeo:seobeo_min`: TCP/SSL basics.
72 - `//seobeo:seobeo_tcp_server`: HTTP server, no WebSocket, no SSL.
73 - `//seobeo:seobeo_tcp_server_ws`: HTTP server with WebSocket.
74 - `//seobeo:seobeo_tcp_client`: HTTP client.
75 - `//seobeo:seobeo_tcp_client_ws`: HTTP client with WebSocket.
76 - `//seobeo:seobeo`: full combined library.
77 - `//seobeo:seobeo_debug`: full library with debug logging.
78
79 ## Tests
80
81 Run the narrowest relevant tests first:
82
83 ```bash
84 bazel test //seobeo:seobeo_client_test
85 bazel test //seobeo:seobeo_websocket_test
86 bazel test //seobeo:seobeo_websocket_server_test
87 ```
88
89 For API changes, also build downstream users:
90
91 ```bash
92 bazel build //mrjunejune:mrjunejune_server //hg-web:hg_web_server
93 ```
94
95 ## Safety checklist
96
97 - Use Dowa aliases such as `uint8`, `uint32`, and `boolean` with
98 `TRUE`/`FALSE`; avoid adding `<stdint.h>` `_t` types or `<stdbool.h>` `bool`
99 to first-party C when the Dowa equivalent exists.
100 - Keep binary bodies binary-safe: use explicit lengths and `Dowa_Arena_Copy`/`memcpy`, not `strlen`, when forwarding arbitrary bytes.
101 - Destroy `Seobeo_Client_Request`, `Seobeo_Client_Response`, `Seobeo_Handle`, and WebSocket messages on owned paths.
102 - Do not swallow network errors. Return explicit HTTP 4xx/5xx responses or propagate error codes.
103 - Preserve keep-alive, content-length, and response header behavior when touching routing or streaming.
104 - 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`.
105 - For WebSockets, respect RFC 6455 requirements: client frames masked, fragmentation handled, control frames handled, and close paths cleaned up.