iodine 0.8.1 → 0.8.2

data/ext/iodine/fio-stl.md

@@ -17878,39 +17878,17 @@ int main(void) {
 #include FIO_INCLUDE_FILE
 ```
 
-IPC is the messaging backbone of the facil.io worker/master model. Workers
-fork from a master process. The master keeps listeners, manages state, and
-handles anything that needs a single authoritative view of the world. Workers
-handle client connections. IPC bridges the two: a worker sends a message to
-the master (or to every process in the cluster), the master executes it and
-optionally streams replies back.
+IPC is the messaging backbone of the facil.io worker/master model. Workers fork from a master process. The master keeps listeners, manages state, and handles anything that needs a single authoritative view of the world. Workers handle client connections. IPC bridges the two: a worker sends a message to the master (or to every process in the cluster), the master executes it and optionally streams replies back.
 
-All messages are encrypted in transit with ChaCha20-Poly1305 AEAD, keyed from
-the process secret. Local IPC runs over a Unix socket (or auto-generated TCP
-socket). Multi-machine RPC extends the same protocol over TCP with optional
-UDP peer discovery.
+IPC supports local messages and, when configured with a shared secret, messages between cluster peers. Register op-codes for messages sent between machines; do not send function pointers across machines.
 
-See [./400 io-overview.md](./400 io-overview.md) for where IPC sits in the
-full IO stack.
+See [./400 io-overview.md](./400 io-overview.md) for where IPC sits in the full IO stack.
 
 ---
 
 ## Worker/Master Model
 
-```
-master process
- ├── owns IPC listener socket
- ├── executes messages sent by workers
- ├── forwards cluster/broadcast messages to other machines
- └── worker process × N
-      ├── each has its own IO reactor loop
-      ├── connects back to master via IPC socket on startup
-      └── sends fio_ipc_* messages to reach master or peers
-```
-
-The master is always the hub. Workers can only talk *through* the master —
-there is no direct worker-to-worker channel. On shutdown the master sends a
-local broadcast instructing all workers to stop.
+Workers send local messages through the master. Use `fio_ipc_call` to reach the master, or `fio_ipc_local` to reach the master and local workers. For cluster peers, use `fio_ipc_cluster` or `fio_ipc_broadcast`.
 
 ---
 
@@ -17931,28 +17909,24 @@ Define before including the header to override defaults.
 
 ```c
 typedef struct fio_ipc_s {
-  fio_io_s *from;               /* originating IO (set by receiver; not transmitted) */
-  /* -- wire format starts here -- */
-  uint32_t len;                 /* data[] byte count            (AAD - authenticated) */
-  uint16_t flags;               /* user-settable flags           (AAD - authenticated) */
-  uint16_t routing_flags;       /* internal routing              (AAD - authenticated) */
-  uint64_t timestamp;           /* millisecond tick — part of nonce (unencrypted)    */
-  uint64_t id;                  /* random 64-bit value — part of nonce (unencrypted) */
+  fio_io_s *from; /* originating IO on receipt */
+  uint32_t len;   /* payload length */
+  uint16_t flags; /* application flags */
+  uint16_t routing_flags; /* routing state; do not edit directly */
+  uint64_t timestamp; /* message timestamp */
+  uint64_t id;        /* message ID */
   union {
-    void (*call)(struct fio_ipc_s *); /* function to call (local IPC; encrypted)  */
-    uint32_t opcode;                  /* registered op-code (cluster RPC; encrypted)*/
+    void (*call)(struct fio_ipc_s *); /* local handler */
+    uint32_t opcode;                  /* registered handler ID */
   };
-  void (*on_reply)(struct fio_ipc_s *); /* run on caller when reply arrives (encrypted) */
-  void (*on_done)(struct fio_ipc_s *);  /* run on caller when last reply arrives (encrypted) */
-  void *udata;                          /* caller-side opaque pointer (encrypted) */
-  char data[];                          /* payload + 16-byte Poly1305 MAC at tail (encrypted) */
+  void (*on_reply)(struct fio_ipc_s *); /* reply handler */
+  void (*on_done)(struct fio_ipc_s *);  /* final reply handler */
+  void *udata; /* caller context */
+  char data[]; /* payload; read only len bytes */
 } fio_ipc_s;
 ```
 
-Messages are reference-counted. Everything from `call` onward (including the
-payload) is encrypted on the wire. `from`, `timestamp`, and `id` are unencrypted
-and unauthenticated (they form the nonce). `len`, `flags`, and `routing_flags`
-are unencrypted but authenticated via AEAD.
+Messages are reference-counted. In callbacks, `data` contains `len` payload bytes; do not assume it is null-terminated. Treat routing state as read-only.
 
 ### `fio_ipc_args_s` — construction arguments
 
@@ -18008,8 +17982,7 @@ typedef struct {
   (fio_buf_info_s[]){ __VA_ARGS__, { .len = ((size_t)-1) } }
 ```
 
-Composes multiple buffers into a single message without intermediate
-allocation. Iteration stops at the first entry with `len == (size_t)-1`.
+Composes multiple buffers into a single message without intermediate allocation. Iteration stops at the first entry with `len == (size_t)-1`.
 
 ```c
 uint32_t seq = 42;
@@ -18026,8 +17999,7 @@ fio_ipc_call(.call = my_handler,
 
 ## Delivery Macros
 
-All four macros call `fio_ipc_new(...)` then `fio_ipc_send(...)`. They accept
-named fields from `fio_ipc_args_s`.
+All four macros call `fio_ipc_new(...)` then `fio_ipc_send(...)`. They accept named fields from `fio_ipc_args_s`.
 
 | Macro | Delivered to |
 |-------|-------------|
@@ -18047,11 +18019,9 @@ named fields from `fio_ipc_args_s`.
 #define fio_ipc_broadcast(...) fio_ipc_send(fio_ipc_new(.workers = 1, .cluster = 1, __VA_ARGS__))
 ```
 
-`fio_ipc_cluster` and `fio_ipc_broadcast` require an `opcode` (not a function
-pointer) because function pointers are meaningless across machine boundaries.
+`fio_ipc_cluster` and `fio_ipc_broadcast` require an `opcode` (not a function pointer) because function pointers are meaningless across machine boundaries.
 
-Use `.exclude = FIO_IPC_EXCLUDE_SELF` to skip the calling process when
-broadcasting locally.
+Use `.exclude = FIO_IPC_EXCLUDE_SELF` to skip the calling process when broadcasting locally.
 
 **`FIO_IPC_EXCLUDE_SELF`**
 
@@ -18059,8 +18029,7 @@ broadcasting locally.
 #define FIO_IPC_EXCLUDE_SELF ((fio_io_s *)((char *)-1LL))
 ```
 
-Pass as `.exclude` in `fio_ipc_args_s`, or set `ipc->from = FIO_IPC_EXCLUDE_SELF`
-before calling `fio_ipc_send`.
+Pass as `.exclude` in `fio_ipc_args_s`, or set `ipc->from = FIO_IPC_EXCLUDE_SELF` before calling `fio_ipc_send`.
 
 ---
 
@@ -18130,9 +18099,7 @@ SFUNC void fio_ipc_reply(fio_ipc_reply_args_s args);
   fio_ipc_reply((fio_ipc_reply_args_s){ .ipc = (r), __VA_ARGS__ })
 ```
 
-Send one or more replies from the master back to the caller. Set `.done = 1`
-on the final reply to trigger the caller's `on_done` callback. Replies inherit
-`call`, `on_reply`, `on_done`, and `udata` from the original request.
+Send one or more replies from the master back to the caller. Set `.done = 1` on the final reply to trigger the caller's `on_done` callback. Replies inherit `call`, `on_reply`, `on_done`, and `udata` from the original request.
 
 Streaming replies:
 
@@ -18152,8 +18119,7 @@ void stream_handler(fio_ipc_s *msg) {
 
 ## Op-Code Registration
 
-Op-codes let you perform cluster-wide RPC without transmitting function
-pointers (which differ per binary). Register before `fio_io_start`.
+Op-codes select handlers for cluster messages. Register them before `fio_io_start` on every participating process.
 
 ```c
 SFUNC int fio_ipc_opcode_register(fio_ipc_opcode_s opcode);
@@ -18166,7 +18132,7 @@ SFUNC const fio_ipc_opcode_s *fio_ipc_opcode(uint32_t opcode);
 ```
 
 - Op-codes must be non-zero `uint32_t` values.
-- Values `>= 0xFF000000` are reserved for internal use.
+- Values `>= 0xFF000000` are reserved; choose a lower value.
 - Pass `call = NULL` to unregister.
 - Must be called before `fio_io_start()` (not thread-safe after that).
 - Returns 0 on success, -1 on error.
@@ -18185,8 +18151,7 @@ fio_ipc_opcode_register(.opcode = OP_SYNC, .call = NULL);
 
 ## IPC URL
 
-The IPC socket URL is auto-generated at startup (`unix://fio_tmp_<rand>.sock`
-in `$TMPDIR`). Override before `fio_io_start` on the master:
+The IPC URL is generated at startup. The master can override it before `fio_io_start`:
 
 ```c
 /** Returns current IPC socket URL. */
@@ -18225,14 +18190,59 @@ SFUNC void fio_ipc_cluster_connect(const char *url);
 SFUNC uint16_t fio_ipc_cluster_port(void);
 ```
 
-- Call `fio_ipc_cluster_listen` from the master before or after
-  `fio_io_start`. It opens a TCP listener and a UDP broadcast socket on the
-  same port for automatic peer discovery.
-- Uses the environment's shared secret for encryption (ChaCha20-Poly1305,
-  no forward secrecy). Set `SECRET=<shared-key>` across all instances.
+### Cluster Peer Connection Callbacks
+
+#### `FIO_IPC_CLUSTER_PEER_MAX_SUBSCRIBERS`
+
+```c
+#define FIO_IPC_CLUSTER_PEER_MAX_SUBSCRIBERS 32
+```
+
+At most 32 peer lifecycle callbacks can be registered per process. Further registrations return `-1`.
+
+#### `fio_ipc_cluster_on_peer_s` and `fio_ipc_cluster_on_peer`
+
+```c
+typedef struct fio_ipc_cluster_on_peer_s {
+  void (*on_attached)(fio_ipc_s *event); /* optional */
+  void (*on_detached)(fio_ipc_s *event); /* optional */
+  void *udata; /* callback context; borrowed */
+} fio_ipc_cluster_on_peer_s;
+
+SFUNC int fio_ipc_cluster_on_peer(fio_ipc_cluster_on_peer_s args);
+#define fio_ipc_cluster_on_peer(...)                                           \
+  fio_ipc_cluster_on_peer((fio_ipc_cluster_on_peer_s){__VA_ARGS__})
+```
+
+Call on the master before `fio_io_start`. Each call adds a subscriber; at least one callback is required. `udata` may be NULL and remains caller-owned. Keep it valid while callbacks can run. Returns `0` on success, or `-1` for invalid callbacks, a worker, running IO, or full capacity. Registration is not thread-safe. There is no unsubscribe API.
+
+Callbacks borrow a `fio_ipc_s` event whose `data` contains the peer UUID (`event->len == 16`). During `on_attached`, `event->from` identifies the connected peer. During `on_detached`, it is `NULL`. To retain an event beyond the callback, use `fio_ipc_dup` and later `fio_ipc_free`.
+
+**Note:** To send to an attached peer, create a new opcode message and pass it with `event->from` to `fio_ipc_send_to` during the callback. The send takes ownership of the new message. Do not send or reply to the event itself. Keeping an attached event beyond the callback may delay its detach notification.
+
+```c
+#define PEER_HELLO_OP 42
+static void peer_hello(fio_ipc_s *message) { (void)message; }
+static void peer_attached(fio_ipc_s *event) {
+  fio_ipc_s *message = fio_ipc_new(
+      .cluster = 1, .opcode = PEER_HELLO_OP,
+      .data = FIO_IPC_DATA(FIO_BUF_INFO1((char *)"hello")));
+  if (message)
+    fio_ipc_send_to(event->from, message);
+}
+static void peer_detached(fio_ipc_s *event) { (void)event; }
+/* On each peer before fio_io_start (illustrative setup statements): */
+if (fio_ipc_opcode_register(.opcode = PEER_HELLO_OP, .call = peer_hello) ||
+    fio_ipc_cluster_on_peer(.on_attached = peer_attached,
+                            .on_detached = peer_detached)) {
+  /* handle registration failure before starting IO */
+}
+```
+
+- Call `fio_ipc_cluster_listen` from the master before or after `fio_io_start` to accept and discover peers.
+- Set the same `SECRET` environment variable on all instances. Cluster encryption does not provide forward secrecy; rotate the secret by restarting instances.
 - All instances receive all `cluster` / `broadcast` messages.
-- `fio_ipc_cluster_connect` lets you manually reach peers on other subnets
-  where UDP broadcast doesn't reach.
+- `fio_ipc_cluster_connect` lets you manually reach peers on other subnets where UDP broadcast doesn't reach.
 
 ```c
 /* Typical setup */
@@ -18245,19 +18255,17 @@ fio_io_start(4);
 
 ## Core Lifetime API
 
-These are used internally by the delivery macros and are available for
-advanced use (e.g., constructing messages for local execution, or async
-message handling).
+Use these functions to construct, send, and retain messages when the delivery macros do not fit your use case.
 
 ```c
 /** Create a message without sending it. */
 SFUNC fio_ipc_s *fio_ipc_new(fio_ipc_args_s args);
 #define fio_ipc_new(...) fio_ipc_new((fio_ipc_args_s){ __VA_ARGS__ })
 
-/** Encrypt, route, and free the message. Takes ownership. */
+/** Send the message according to its delivery options. Takes ownership. */
 SFUNC void fio_ipc_send(fio_ipc_s *ipc);
 
-/** Encrypt and send directly to a specific IO. Takes ownership. */
+/** Send directly to a specific IO. Takes ownership. */
 SFUNC void fio_ipc_send_to(fio_io_s *to, fio_ipc_s *ipc);
 
 /** Increment reference count. */
@@ -18293,29 +18301,20 @@ void async_done(fio_ipc_s *msg) {
 
 ---
 
-## Encryption
+## Message encryption (advanced)
 
 ```c
-/** Encrypt a message in-place (idempotent). Called automatically by fio_ipc_send. */
 SFUNC void fio_ipc_encrypt(fio_ipc_s *m);
-
-/** Decrypt a message in-place. Returns 0 on success, non-zero on MAC failure. */
 FIO_IFUNC int fio_ipc_decrypt(fio_ipc_s *m);
 ```
 
-ChaCha20-Poly1305 AEAD. Key derived from the shared process secret plus the
-message's `id` and `timestamp` fields (which form the nonce). `len`, `flags`,
-and `routing_flags` are authenticated but unencrypted. Everything else
-(`call`/`opcode`, `on_reply`, `on_done`, `udata`, `data`) is encrypted.
-
-Decryption failure logs a security warning and the connection is closed.
-Only processes sharing the same secret can communicate.
+Sending encrypts messages automatically. `fio_ipc_encrypt` encrypts a message in place; `fio_ipc_decrypt` returns `0` on success or nonzero if authentication fails. Most applications should use the delivery functions instead.
 
 ---
 
 ## Routing Flags
 
-`routing_flags` is internal — do not edit manually. Available for inspection:
+The routing flags are defined in the header for advanced use. Prefer the delivery macros and `.flags` for application data. Do not modify `routing_flags` on a received message:
 
 ```c
 #define FIO_IPC_FLAG_ENCRYPTED  ((uint16_t)1 << 0) /* message is encrypted */
@@ -18332,21 +18331,6 @@ Only processes sharing the same secret can communicate.
 
 ---
 
-## Keepalive
-
-IPC and cluster connections use an automatic ping/pong protocol. On the first
-timeout the system sends a ping; if no pong arrives before the next timeout
-the connection is closed. Ping frames are never delivered to user callbacks.
-
-Default timeouts (set in the protocol initializer):
-
-| Connection type | Timeout |
-|-----------------|---------|
-| Local IPC (master ↔ worker) | ~6 minutes |
-| Cluster RPC (machine ↔ machine) | ~55 seconds |
-
----
-
 ## Memory Management
 
 - Messages are reference-counted (`fio_ipc_dup` / `fio_ipc_free`).
@@ -18366,6 +18350,8 @@ Default timeouts (set in the protocol initializer):
 - `fio_ipc_dup` / `fio_ipc_free` are thread-safe.
 - `fio_ipc_opcode_register` is **not** thread-safe after `fio_io_start`.
 - `fio_ipc_url_set` must be called on the master before `fio_io_start`.
+
+---
 # OpenSSL TLS Backend
 
 ```c
@@ -20292,32 +20278,11 @@ support in [DEFLATE / Gzip](./162 deflate.md).
 - upgrade helpers for WebSocket and SSE connections.
 - pub/sub helpers for upgraded connections.
 - handle access helpers: `fio_http_io` and `fio_http_settings`.
-- the HTTP handle API (handle and core implementation in
-  `432 http types.h`), including request / response fields, headers,
+- the HTTP handle API, including request / response fields, headers,
   cookies, body storage, writing, static-file responses, logging, MIME
   lookup, and controller hooks.
 
-Implementation helpers named `fio___...` are private implementation details.
-
----
-
-## Module Files
-
-All HTTP module files share the `FIO_HTTP` flag.
-
-- `430 http api.h` — public declarations: settings, listener / route /
-  client APIs, and the full handle API.
-- `432 http types.h` — internal types plus the handle and core
-  implementation (header cache, body storage, static-file responses).
-- `434 http accept.h` — accept path, request dispatchers, upgrade
-  authorization.
-- `434 http1.h` — HTTP/1.1 request / response glue, protocol and
-  controller.
-- `434 sse.h` — EventSource (SSE) upgrade, helpers, protocol, controller.
-- `434 websocket.h` — WebSocket upgrade, events, protocol, write,
-  controller.
-- `438 http.h` — listen / connect glue, protocol wiring, shared helpers.
-- `439 http.h` — cleanup tail (the module's only `#undef FIO_HTTP` site).
+Names prefixed with `fio___` are private and not part of the API.
 
 The parsers are separate modules: [`004 http1 parser.h`](./004 http1 parser.md)
 and [`004 websocket parser.h`](./004 websocket parser.md).
@@ -20417,7 +20382,7 @@ Other settings:
 | `sse_timeout` | SSE timeout; timeout pings are sent. |
 | `connect_timeout` | Client connection timeout. |
 | `log` | Enables HTTP request logging. |
-| `compress_static` | Opt-in static-file compression (on-demand `.br`/`.gz` creation). Per-route; routes inherit the listener's root value at route-creation. The value is a failure-memoization shift register (see *Static File Service*). Detached handles gate on the `FIO_HTTP_CFLAG_COMPRESS_STATIC` cflag instead. See the compression security note below. |
+| `compress_static` | Opt-in static-file compression (on-demand `.br`/`.gz` creation). Per-route; routes inherit the listener's root value at route-creation. May drop to 0 when creation is disabled after failures (see *Static File Service*). See the compression security note below. |
 | `compress_dynamic` | Opt-in dynamic response compression. Connection-global; per-route values are ignored. See the compression security note below. |
 | `compress_ws` | Opt-in WebSocket `permessage-deflate`. Connection-global; per-route values are ignored. See the compression security note below. |
 
@@ -20425,21 +20390,18 @@ Other settings:
 secrets together with attacker-reflected data enables length-oracle attacks
 (BREACH/CRIME). Do not enable compression for responses that mix secrets
 (CSRF tokens, session data) with attacker-controlled reflections, or emit
-such messages uncompressed per call (per-message opt-out: keep the cflag off
-at the route level for sensitive routes, or pre-set `content-encoding`
-— which the dynamic path always respects — to pass a body through
-uncompressed).
+such messages uncompressed: leave `compress_dynamic` / `compress_ws` off
+for listeners serving them, or pre-set a response `content-encoding` header
+(it is always respected) to pass a body through uncompressed.
 
 **WebSocket `permessage-deflate` negotiation:** the server ALWAYS responds
 with `permessage-deflate; server_no_context_takeover;
 client_no_context_takeover` (RFC 7692 allows either endpoint to request the
 flags unilaterally), honoring `server_max_window_bits` when offered (the
 compressor clamps its distances accordingly) and never emitting window-bits
-parameters. Cross-message history is never used, so persistent compression
-state per connection is ~0 (two ~32-byte contexts plus a bounded input
-buffer, shrunk on every message reset); compressor scratch comes from a
-static process-wide slot pool checked out per call — under extreme
-contention a message simply goes out uncompressed.
+parameters. Cross-message history is never used, keeping per-connection
+compression memory minimal. Under heavy load, a message may be sent
+uncompressed.
 
 **Accept-Encoding handling:** `q=0` (in any zero-padded form) forbids an
 encoding (RFC 9110). `Vary: accept-encoding` is set whenever compressed
@@ -20613,33 +20575,29 @@ least as fresh as the original (modification time) is served, with
 selected (RFC 9110 §12.5.3).
 
 With `compress_static` enabled, missing or stale `.br` / `.gz` variants are
-created on demand and written into the root folder. Attached handles read the
-flag from the matching route's settings (routes inherit the listener's root
-value at route-creation); detached handles (created manually, with no
-settings) gate on the `FIO_HTTP_CFLAG_COMPRESS_STATIC` handle cflag instead.
+created on demand and written into the root folder. The value is read from the
+matching route's settings (routes inherit the listener's root value at
+route-creation); handles without settings (created with `fio_http_new`) never
+create variants.
 
 - creation is limited to compressible (text-like) MIME types and originals
   between 1024 bytes and `FIO_HTTP_STATIC_FILE_COMPRESS_LIMIT` (2 MiB);
 - creation is skipped when compression would not shrink the file;
-- `.br` variants are compressed at brotli quality 4 (the benchmark-reviewed
-  fast-path ceiling; q5+ engages the slow hash-chain path) and `.gz`
-  variants at gzip level 6;
+- `.br` variants are compressed at brotli quality 4 and `.gz` variants at
+  gzip level 6;
 - `zstd` / `deflate` variants are only ever served pre-generated — they are
   never created on demand;
 - on-demand creation writes into the served folder and is triggered by
   client requests; the folder must be writable for creation to succeed
-  (a write failure disables creation, see memoization below). Variants
+  (repeated failures disable creation, see below). Variants
   may also be pre-generated at deploy time with any external tool — the
   server only stats the files.
 
-`compress_static` is a failure-memoization shift register, updated atomically
-(the IO threads share the listener / route settings): any non-zero value
-enables on-demand creation. A compression success re-seeds bit 0
-(`value |= 1`); any other failure shifts the value left (`value <<= 1`), so
-8 consecutive failures shift out of the `uint8_t` and disable creation, as
-does a single filesystem-full / permission error (`ENOSPC`, `EACCES`,
-`EROFS`, `EDQUOT` — `value = 0`). Once 0, creation stays disabled until the
-settings are re-applied. Detached handles carry no memoization state.
+Any non-zero `compress_static` value enables on-demand creation. The server
+disables creation (setting the value to 0) after repeated consecutive
+failures, or after a single filesystem-full / permission error (`ENOSPC`,
+`EACCES`, `EROFS`, `EDQUOT`). Once disabled, creation stays off until the
+settings are re-applied.
 
 `Vary: accept-encoding` is set whenever a variant is served, and on
 identity responses whenever variants may be created, so caches key on the
@@ -20856,12 +20814,35 @@ fio_http_controller_s *fio_http_controller_set(fio_http_s *h,
 `udata` and `udata2` are for application state. `cdata` and the controller are
 used by the HTTP layer and custom controllers.
 
+`fio_http_controller` gets the handle's controller; `fio_http_controller_set`
+sets it and returns the controller in use. Passing `NULL` installs a no-op
+controller. Missing callbacks in a custom controller are filled in with no-op
+defaults, so the controller object must be writable and outlive the handle.
+
 ### Request / response properties
 
 ```c
 size_t         fio_http_status(fio_http_s *h);
 size_t         fio_http_status_set(fio_http_s *h, size_t status);
 fio_str_info_s fio_http_method(fio_http_s *h);
+int fio_http_method_is_get(fio_http_s *h);
+int fio_http_method_is_head(fio_http_s *h);
+int fio_http_method_is_post(fio_http_s *h);
+int fio_http_method_is_put(fio_http_s *h);
+int fio_http_method_is_delete(fio_http_s *h);
+int fio_http_method_is_connect(fio_http_s *h);
+int fio_http_method_is_options(fio_http_s *h);
+int fio_http_method_is_trace(fio_http_s *h);
+int fio_http_method_is_patch(fio_http_s *h);
+int fio_http_method_is_query(fio_http_s *h);
+int fio_http_method_is_propfind(fio_http_s *h);
+int fio_http_method_is_proppatch(fio_http_s *h);
+int fio_http_method_is_mkcol(fio_http_s *h);
+int fio_http_method_is_copy(fio_http_s *h);
+int fio_http_method_is_move(fio_http_s *h);
+int fio_http_method_is_lock(fio_http_s *h);
+int fio_http_method_is_unlock(fio_http_s *h);
+int fio_http_method_is_search(fio_http_s *h);
 fio_str_info_s fio_http_method_set(fio_http_s *h, fio_str_info_s value);
 fio_str_info_s fio_http_opath(fio_http_s *h);
 fio_str_info_s fio_http_opath_set(fio_http_s *h, fio_str_info_s value);
@@ -20878,10 +20859,18 @@ int64_t        fio_http_received_at_set(fio_http_s *h, int64_t value);
 `opath` is the original path before route prefix trimming. `path` is the routed
 path visible to the current callback.
 
-`fio_http_status_set(h, 0)` normalizes to `200`; values above the internal range
-normalize to `500`.
+The `fio_http_method_is_*` helpers test whether the request method matches the
+named method, ignoring ASCII case. They return `1` for a match and `0` otherwise;
+pass a non-`NULL` HTTP handle (`h`). Unlike `fio_http_resource_action`, these
+helpers do not classify paths or combine PUT, POST, and PATCH into a single
+action. The helpers cover the core HTTP methods, PATCH, QUERY, and commonly
+used WebDAV methods (PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK, and
+SEARCH).
 
-### State checks and flags
+`fio_http_status_set(h, 0)` normalizes to `200`; values above `1023` normalize
+to `500`.
+
+### State checks
 
 ```c
 int fio_http_is_clean(fio_http_s *h);
@@ -20893,25 +20882,6 @@ int fio_http_is_sse(fio_http_s *h);
 int fio_http_is_freeing(fio_http_s *h);
 ```
 
-The handle also exposes inline flag helpers generated for `cflags` and
-`uflags`:
-
-```c
-uint16_t fio_http_cflags(fio_http_s *h);
-uint16_t fio_http_cflags_set(fio_http_s *h, uint16_t flags);
-uint16_t fio_http_cflags_unset(fio_http_s *h, uint16_t flags);
-uint16_t fio_http_cflags_flip(fio_http_s *h, uint16_t flags);
-uint16_t fio_http_cflags_is_set(fio_http_s *h, uint16_t flags);
-
-uint16_t fio_http_uflags(fio_http_s *h);
-uint16_t fio_http_uflags_set(fio_http_s *h, uint16_t flags);
-uint16_t fio_http_uflags_unset(fio_http_s *h, uint16_t flags);
-uint16_t fio_http_uflags_flip(fio_http_s *h, uint16_t flags);
-uint16_t fio_http_uflags_is_set(fio_http_s *h, uint16_t flags);
-```
-
-Prefer the state helpers unless implementing protocol or controller glue.
-
 ### Headers
 
 ```c
@@ -21132,13 +21102,10 @@ void           fio_http_write_log(fio_http_s *h);
 int            fio_http_from(fio_str_info_s *dest, const fio_http_s *h);
 fio_str_info_s fio_http_date(uint64_t now_in_seconds);
 fio_str_info_s fio_http_log_time(uint64_t now_in_seconds);
-int64_t        fio_http_get_timestump(void);
 ```
 
-`fio_http_get_timestump` is the inline timestamp helper used by the handle for
-`received_at` and log timing. User code usually reads timestamps with
-`fio_http_received_at` or formats them with `fio_http_date` /
-`fio_http_log_time`.
+Read request timestamps with `fio_http_received_at`; format dates with
+`fio_http_date` / `fio_http_log_time`.
 
 `fio_http_from` writes a best-effort peer address starting with the `Forwarded`
 header, then socket peer address, then `"[unknown]"`.
@@ -21179,7 +21146,8 @@ struct fio_http_controller_s {
 ```
 
 Controllers allow the handle to write through different protocols. Initialize
-custom controllers to zero before use. If controller callbacks are not
+custom controllers to zero before use; `private_flags` is reserved and must
+remain zero. If controller callbacks are not
 thread-safe, call `fio_http_write` only from the controller's expected thread.
 
 ---
@@ -21217,24 +21185,11 @@ FIO_HTTP_LOG_X_REQUEST_START          /* 1 */
 FIO_HTTP_ENFORCE_LOWERCASE_HEADERS    /* 0 */
 ```
 
-State and controller flag macros are exposed for protocol glue:
-
-```c
-FIO_HTTP_STATE_STREAMING
-FIO_HTTP_STATE_FINISHED
-FIO_HTTP_STATE_UPGRADED
-FIO_HTTP_STATE_WEBSOCKET
-FIO_HTTP_STATE_SSE
-FIO_HTTP_STATE_COOKIES_PARSED
-FIO_HTTP_STATE_FREEING
-
-FIO_HTTP_CFLAG_COMPRESS_DYNAMIC
-FIO_HTTP_CFLAG_COMPRESS_WS
-FIO_HTTP_CFLAG_COMPRESS_STATIC
-```
-
-Prefer public helper functions over reading state bits directly in application
-code.
+With `FIO_HTTP_LOG_X_REQUEST_START`, request logs (`.log = 1`) include the
+request's wait time when the client or proxy sends an `X-Request-Start`
+header holding a millisecond timestamp (optionally prefixed with `t=`). The
+wait time is omitted when the header is missing or the wait is 512 seconds or
+more.
 
 ---
 

data/ext/iodine/iodine_utils.h

@@ -247,7 +247,7 @@ FIO_SFUNC VALUE iodine_utils_is_eq(VALUE mod, VALUE a, VALUE b) { // clang-forma
 Randomness and Friends
 ***************************************************************************** */
 
-FIO_DEFINE_RANDOM128_FN(static, iodine_random, 10, 0)
+FIO_DEFINE_RANDOM128_FN(static, iodine_random, 11, 0)
 
 FIO_SFUNC VALUE iodine_utils_hmac512(VALUE self, VALUE secret, VALUE massage) {
   rb_check_type(secret, RUBY_T_STRING);

data/lib/iodine/version.rb

@@ -2,7 +2,7 @@
 
 module Iodine
   # The Iodine gem version number
-  VERSION = "0.8.1"
+  VERSION = "0.8.2"
   # NeoRack supported extensions.
   def self.extensions
     return (@extensions ||= { iodine:   (VERSION.split(?.).map() {|i| i.to_i.to_s == i ? i.to_i : i }),

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: iodine
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.2
 platform: ruby
 authors:
 - Boaz Segev
@@ -133,7 +133,7 @@ metadata:
   homepage_uri: https://github.com/boazsegev/iodine
   source_code_uri: https://github.com/boazsegev/iodine
   changelog_uri: https://github.com/boazsegev/iodine/blob/master/CHANGELOG.md
-post_install_message: Thank you for installing Iodine 0.8.1.
+post_install_message: Thank you for installing Iodine 0.8.2.
 rdoc_options: []
 require_paths:
 - lib