---
name: zenbu-seobeo-networking
description: Use this skill when changing or extending seobeo, the C networking layer for HTTP clients, HTTP/static servers, routing, streaming, TLS, or WebSockets.
---

# Seobeo Networking

Use this skill for the `seobeo/` networking library and any server code built on top of it.

## Mental model

`seobeo` is the shared C networking layer. It provides:

- TCP server/client handles in `s_network.c`.
- TLS helpers in `s_ssl.c`.
- Static file and HTTP routing in `s_web.c`.
- Curl-like HTTP client APIs in `s_http_client.c`.
- WebSocket client/server support in `s_websocket*.c`.
- Snapshot/test utilities in `snapshot_creator.c`.
- Public API declarations in `seobeo/seobeo.h`.
- Internal types in `seobeo/seobeo_internal.h`.

Prefer using public APIs from `seobeo.h` in applications. Only reach into internals when modifying seobeo itself.

## Common APIs

HTTP client:

```c
Seobeo_Client_Request *p_req = Seobeo_Client_Request_Create("https://example.com/path");
Seobeo_Client_Request_Set_Method(p_req, "GET");
Seobeo_Client_Request_Add_Header_Array(p_req, "Accept: application/json");
Seobeo_Client_Response *p_resp = Seobeo_Client_Request_Execute(p_req);
Seobeo_Client_Request_Destroy(p_req);
Seobeo_Client_Response_Destroy(p_resp);
```

HTTP routes:

```c
Seobeo_Router_Init();
Seobeo_Router_Register("GET", "/api/example/:id", Handler);
Seobeo_Web_Server_Start("site/src", "8080", SEOBEO_MODE_EDGE, 1);
Seobeo_Router_Destroy();
```

Route handler shape:

```c
Seobeo_Request_Entry *Handler(Seobeo_Request_Entry *req, Dowa_Arena *arena)
{
  Seobeo_Request_Entry *resp = NULL;
  Dowa_HashMap_Push_Arena(resp, "status", "200", arena);
  Dowa_HashMap_Push_Arena(resp, "content-type", "application/json", arena);
  Dowa_HashMap_Push_Arena(resp, "body", "{\"ok\":true}", arena);
  return resp;
}
```

WebSocket server:

```c
Seobeo_WebSocket_Server_Init();
Seobeo_WebSocket_Server_Register("/chat", Chat_Handler, NULL);
```

Server-Sent Events:

```c
void Events(
    Seobeo_SSE_Stream *p_stream,
    Seobeo_Request_Entry *p_request,
    Dowa_Arena *p_arena)
{
  Seobeo_SSE_Send_Data(p_stream, "ready");
}

Seobeo_Router_Register_SSE("/events", Events);
```

SSE handlers run once during connection setup and must return promptly. The
stream may be retained for later thread-safe sends only through balanced
`Seobeo_SSE_Retain` / `Seobeo_SSE_Release` calls; request/response arenas and
request-map pointers expire when the handler returns. Check
`Seobeo_SSE_Is_Open`, handle bounded backpressure, and use comments for
heartbeats.

Background work:

```c
Seobeo_Worker_Pool *pool = Seobeo_Worker_Pool_Create(2, 16);
Seobeo_Worker_Pool_Submit(pool, Process_File, context, free);
Seobeo_Worker_Pool_Shutdown(pool, TRUE);
Seobeo_Worker_Pool_Destroy(pool);
```

Use `Seobeo_Thread_Start` + `Seobeo_Thread_Join` for one joinable task, or
`Seobeo_Thread_Start_Detached` for fire-and-forget work. Prefer a bounded pool
for request-triggered FFmpeg, upload, or other expensive jobs.

## Build targets

Choose the smallest library variant that matches the feature:

- `//seobeo:seobeo_min`: TCP/SSL basics.
- `//seobeo:seobeo_tcp_server`: HTTP server, no WebSocket, no SSL.
- `//seobeo:seobeo_tcp_server_ws`: HTTP server with WebSocket.
- `//seobeo:seobeo_tcp_client`: HTTP client.
- `//seobeo:seobeo_tcp_client_ws`: HTTP client with WebSocket.
- `//seobeo:seobeo`: full combined library.
- `//seobeo:seobeo_debug`: full library with debug logging.
- `//seobeo:seobeo_worker`: standalone thread/worker-pool API.

## Tests

Run the narrowest relevant tests first:

```bash
bazel test //seobeo:seobeo_client_test
bazel test //seobeo:seobeo_websocket_test
bazel test //seobeo:seobeo_websocket_server_test
bazel test //seobeo/tests:seobeo_sse_test
```

For API changes, also build downstream users:

```bash
bazel build //mrjunejune:mrjunejune_server //hg-web:hg_web_server
```

## Safety checklist

- Use Dowa aliases such as `uint8`, `uint32`, and `boolean` with
  `TRUE`/`FALSE`; avoid adding `<stdint.h>` `_t` types or `<stdbool.h>` `bool`
  to first-party C when the Dowa equivalent exists.
- Keep binary bodies binary-safe: use explicit lengths and `Dowa_Arena_Copy`/`memcpy`, not `strlen`, when forwarding arbitrary bytes.
- Destroy `Seobeo_Client_Request`, `Seobeo_Client_Response`, `Seobeo_Handle`, and WebSocket messages on owned paths.
- Do not swallow network errors. Return explicit HTTP 4xx/5xx responses or propagate error codes.
- Preserve keep-alive, content-length, and response header behavior when touching routing or streaming.
- 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`.
- For WebSockets, respect RFC 6455 requirements: client frames masked, fragmentation handled, control frames handled, and close paths cleaned up.