/home/mrjunejune/zenbu: mrjunejune/src/blog/websocket-demystified/index.md comparison

comparison mrjunejune/src/blog/websocket-demystified/index.md @ 131:b230a743a01e

Added blog.

author	June Park <parkjune1995@gmail.com>
date	Fri, 09 Jan 2026 07:42:04 -0800
parents	3a564ffb2092
children	7a63e41a21fb

comparison

equal deleted inserted replaced

-:f7860f491a8c
+:b230a743a01e
-# Websocket Demystified
+# WebSocket Demystified
-Websocket has been around for more than 10 years now. (Its [RFC](https://www.rfc-editor.org/rfc/rfc6455) was created in 2011.). This was inevitable as apps got more complexed people wanted to create an application that can create bidirectional communicate with server, and not create hacky solutions that will create raw TCP connection between client and server with some keys or do some short/long polling. Now, this is the most widely used protocol for LLM chat usages or any chat usages as expected since LLM sends messages in a stream of bytes as it is predicting next words at a time. Many developers create websocket connection through
+WebSockets have been around for more than 10 years now—the [RFC 6455](https://www.rfc-editor.org/rfc/rfc6455) was dropped way back in 2011. This was inevitable. As apps got more complex, people wanted real bidirectional communication without resorting to hacky solutions like raw TCP connections with custom keys or the constant overhead of short/long polling.
+Today, it’s the standard for everything from chat apps to LLM interfaces, where the model streams bytes back to you one token at a time as it predicts the next word.
+Most developers just grab a library like [ws](https://github.com/websockets/ws) for Node.js or [websockets](https://websockets.readthedocs.io/) for Python and call it a day. But many don’t realize the underlying mechanism is actually pretty simple to implement yourself in a day or so. Let's look at how to build it from scratch.
+---
+## Requirements
+* Ability to type
+* Half a brain
+* A computer
+---
+## The Lifecycle
+To get a WebSocket up and running, you have to follow a specific dance. It’s not just "connecting to a port"; it's an evolution of an existing relationship.
+1. **The Handshake:** A client sends a "pretty please" HTTP request asking to upgrade the connection.
+2. **The Response:** The server agrees (101 Switching Protocols) and sends back a specific hash.
+3. **The Switch:** Both sides stop talking "HTTP" and start talking "Frames."
+4. **The Interaction:** Bidirectional, binary-framed messaging until someone closes the door.
+---
+## Opening Handshakes
+To start the upgrade from HTTP to WebSocket, the client sends a standard GET request but with some very specific headers.
+<div class="center"> <img src="/public/white-noise-grass.png" /> </div>
+I’m assuming you know how HTTP works. If not, you can open a developer tool by right clicking on your browser and seeing into network tab and refershign the page. The only interesting values here is the `Sec-WebSocket-Key`. This key is usually a 16-byte random value encoded in **Base64**.
+**Note:** It’s not for security—it’s to prevent intermediate caches from accidentally serving a cached WebSocket response to a different client.
+But before we jump into that, we need to construct that Base64 key.
+### What is Base64?
+Let's ask Gemini:
+> "Base64 is a binary-to-text encoding scheme that represents data in an ASCII string format by translating it into a radix-64 representation, using a specific set of 64 printable characters." — Gemini
+Nice, it didn't halluciante. Let's constracut these. Here they are 64 characters that are safe to print in ASCII.:
+```c
+static const char base64_chars[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+```
+In Python, this is a one-liner:
+```python
+import base64
+import os
+print(base64.b64encode(os.urandom(16)))
+```
+But we are rewriting this from scratch in **C**, so we need to suffer a little. The logic is: take 3 bytes (24 bits) and split them into 4 chunks of 6 bits each. Each 6-bit chunk becomes an index into our `base64_chars` array.
+#### Step 1: Generate Random Bytes
+First, we grab 16 random bytes.
+```c
+srand((unsigned int)time(NULL));
+uint8 random_value[16];
+for (int i = 0; i < 16; i++)
+random_value[i] = (uint8)(rand() % 256);
+```
+#### Step 2: The Bit-Shifting Magic
+We loop through our 16 bytes in groups of 3. We pack them into a 32-bit integer, then carve that integer into 6-bit slices.
+> **Note:** The length isn't strictly defined as 32, but many implementations land there.
+```c
+char result[32] = {0};
+int32 result_index = 0;
+for (int i = 0; i < 16; i += 3) {
+uint32 first_value = 0, second_value = 0, third_value = 0;
+if (i < 15) {
+first_value  = (uint32)random_value[i] << 16;
+second_value = (uint32)random_value[i+1] << 8; // Fixed logic from original draft
+third_value  = (uint32)random_value[i+2];
+} else {
+// Handle the trailing bytes (padding logic usually goes here)
+first_value  = (uint32)random_value[i] << 16;
+}
+uint32 group_value = first_value | second_value | third_value;
+// Map bits to characters: 0x3F is 0011 1111 (keeps only 6 bits)
+result[result_index++] = base64_chars[(group_value >> 18) & 0x3F];
+result[result_index++] = base64_chars[(group_value >> 12) & 0x3F];
+result[result_index++] = base64_chars[(group_value >> 6) & 0x3F];
+result[result_index++] = base64_chars[group_value & 0x3F];
+}
+```
+Now you have a `Sec-WebSocket-Key`. When the server gets it, it appends a "Magic String" (`258EAFA5-E914-47DA-95CA-C5AB0DC85B11`), SHA1 hashes it, and Base64 encodes it back to you as `Sec-WebSocket-Accept`.
+---
+## Upgrading the Protocol
+If you are the client, you just wait for that `101 Switching Protocols` response. Once you see it, you stop sending HTTP text and start sending frames.
+If you are the **server**, you need to keep that connection alive. In my project, `Seobeo`, I create a separate connection object, throw away the HTTP request info to save memory, and start a fresh buffer for WebSocket frames.
+```c
+// Transitioning the state from HTTP to WebSocket
+Seobeo_WebSocket_Server_Connection *p_conn = malloc(sizeof(Seobeo_WebSocket_Server_Connection));
+memset(p_conn, 0, sizeof(Seobeo_WebSocket_Server_Connection));
+p_conn->p_handle = p_handle;
+p_conn->is_active = TRUE;
+p_conn->fragment_capacity = 4096;
+p_conn->fragment_buffer = malloc(p_conn->fragment_capacity);
+```
+---
+## Frame-Based Protocols
+This is where the logic gets "cancerous." WebSockets don't just send raw strings; they wrap everything in a **Frame**.
+### The Opcode Table
+The first byte contains the `FIN` bit (is this the end of the message?) and the `Opcode` (what kind of data is this?).
+| Opcode (Hex) | Meaning | Description |
+| --- | --- | --- |
+| `0x0` | Continuation | Part of a multi-frame message |
+| `0x1` | Text | UTF-8 payload |
+| `0x2` | Binary | Raw binary data |
+| `0x8` | Close | Terminate the connection |
+| `0x9` | Ping | Heartbeat check |
+| `0xA` | Pong | Heartbeat response |
+### The Masking Rule
+* **Client to Server:** MUST be masked.
+* **Server to Client:** MUST NOT be masked.
+If a client sends unmasked data, the server must close the connection. It’s the law.
+### Why the Bitwise Mess? (Endianness)
+In the code below, you’ll see things like `payload_length >> 56`. This is because network protocol headers use **Big-Endian** (most significant byte first). If your computer is Little-Endian (most are), you have to manually shift bits into the right order so the wire sees them correctly.
+---
+## Sending a Frame (Client Side)
+Here is how we construct a frame to send data to the server.
+```c
+uint8 frame[14];
+size_t frame_len = 0;
+// Byte 0: FIN bit (0x80) and Opcode
+frame[0] = (fin ? 0x80 : 0x00) | (opcode & 0x0F);
+frame_len++;
+// Generate a 4-byte mask key
+uint8 mask_key[4];
+for (int i = 0; i < 4; i++)
+mask_key[i] = (uint8)(rand() % 256);
+// Byte 1+: Payload Length logic
+if (payload_length < 126) {
+frame[1] = 0x80 | (uint8)payload_length; // 0x80 sets the MASK bit
+frame_len++;
+} else if (payload_length <= 65535) {
+frame[1] = 0x80 | 126;
+frame[2] = (uint8)((payload_length >> 8) & 0xFF);
+frame[3] = (uint8)(payload_length & 0xFF);
+frame_len += 3;
+} else {
+frame[1] = 0x80 | 127;
+for (int i = 0; i < 8; i++)
+frame[2 + i] = (uint8)((payload_length >> (56 - i * 8)) & 0xFF);
+frame_len += 9;
+}
+// Attach the mask key
+memcpy(frame + frame_len, mask_key, 4);
+frame_len += 4;
+```
+To actually send the data, you XOR every byte with the mask:
+```c
+for (size_t i = 0; i < length; i++)
+data[i] ^= mask_key[i % 4];
+```
+---
+## Receiving a Frame (Server Side)
+On the server side, we have to do the reverse. We peel the onion layer by layer.
+#### 1. Parse the Header
+We check the first two bytes to see how big the payload is and if it's masked.
+```c
+uint8 *buf = p_conn->p_handle->read_buffer;
+uint8 byte1 = buf[0];
+uint8 byte2 = buf[1];
+boolean fin = (byte1 & 0x80) != 0;
+Seobeo_WebSocket_Opcode opcode = (Seobeo_WebSocket_Opcode)(byte1 & 0x0F);
+boolean masked = (byte2 & 0x80) != 0;
+uint64 payload_len = byte2 & 0x7F;
+size_t header_len = 2;
+```
+#### 2. Handle Extended Lengths
+If the length is 126 or 127, it means the actual size is hidden in the next 2 or 8 bytes.
+```c
+if (payload_len == 126) {
+payload_len = (buf[2] << 8) | buf[3];
+header_len += 2;
+} else if (payload_len == 127) {
+payload_len = 0;
+for (int i = 0; i < 8; i++)
+payload_len = (payload_len << 8) | buf[2 + i];
+header_len += 8;
+}
+```
+#### 3. Unmask the Payload
+If the data is masked (and it should be if it's from a client), we use that 4-byte key to flip the bits back to normal.
+```c
+uint8 mask_key[4] = {0};
+if (masked) {
+memcpy(mask_key, buf + header_len, 4);
+header_len += 4;
+}
+uint8 *payload = malloc(payload_len);
+memcpy(payload, buf + header_len, payload_len);
+if (masked)
+Seobeo_WebSocket_Unmask_Data(payload, payload_len, mask_key);
+```
+---
+## Conclusion
+That’s it. That is WebSockets in a nutshell. Once you handle the bit-shifting for the length and the XOR masking, you’re just reading and writing to a socket like any other protocol.
+You can test my implementation at `mrjunejune.com/talk`. Open two tabs and talk to yourself—it’s a great way to verify your frames are flying correctly.

Mercurial

comparison mrjunejune/src/blog/websocket-demystified/index.md @ 131:b230a743a01e