winhttp 0.1.0

data/ext/winhttp/winhttp.c

@@ -0,0 +1,1247 @@
+/*
+ * winhttp — HTTP for Ruby on the asynchronous WinHTTP client API.
+ *
+ * Engine/strategy: WINHTTP_FLAG_ASYNC. WinHTTP's status callback runs on a
+ * worker thread (or synchronously inside our own call) — a foreign native
+ * thread that may NOT call Ruby or take the GVL — so the callback only touches
+ * plain C state: a CRITICAL_SECTION-guarded event list + an auto-reset event
+ * (Bridge P from the seam research). One Ruby "pump" thread waits on that event
+ * (GVL released), drains the list (GVL held), and routes each event to its
+ * request's Thread::Queue mailbox. The per-request state machine (Ruby) pops
+ * those mailboxes — natively blocking standalone, parking the fiber under a
+ * Fiber::Scheduler (winloop). One code path for both modes.
+ *
+ * PURE C (no C++), so rb_raise/longjmp is the normal, safe error mechanism —
+ * the same discipline as winipc/winloop, and the opposite of the lithos /EHsc
+ * hazard. Include <ruby.h> before the Windows headers; never name a variable
+ * IN/OUT.
+ *
+ * Control-block lifetime (the load-bearing contract): WinHTTP can hold
+ * callbacks/buffers alive after the Ruby wrapper is GC'd, so control blocks are
+ * separate heap allocations (NOT embedded in the TypedData wrapper). A request
+ * block is freed exactly when BOTH wrapper_gone (Ruby wrapper closed/GC'd) AND
+ * os_done (terminal HANDLE_CLOSING reaped, or provably never coming) are set.
+ * Every flag transition and every table mutation happens with the GVL held
+ * (request creation, pump drain, close, GC free hooks) — so the GVL is the lock
+ * for all tables and control blocks; the CRITICAL_SECTION guards ONLY the raw
+ * callback event list. Lock ordering (normative): GVL -> g_cs is allowed;
+ * g_cs -> GVL is forbidden (the callback takes g_cs without the GVL and acquires
+ * nothing else), so there is no deadlock even when WinHTTP invokes the callback
+ * synchronously on a Ruby thread holding the GVL.
+ *
+ * LLP64 reminder: `long` is 32-bit on x64/arm64-mswin — sizes/timeouts from
+ * Ruby use NUM2LL / long long, never NUM2LONG. Handle/context values are
+ * uint64 ids, never pointers. Arch-neutral: gate on _WIN64, use ULONG_PTR.
+ *
+ * Links winhttp.lib; kernel32 (events, critical sections, FormatMessage) is
+ * linked by default.
+ */
+
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <ruby/encoding.h>
+#include <limits.h>
+#include <stdint.h>
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+#include <winhttp.h>
+
+/* ------------------------------------------------------------------ globals */
+
+static VALUE mWinhttp;
+static VALUE cSession, cRequest;
+static VALUE eError, eOSError, eTimeout, eResolve, eConnect, eTls, eRedirect,
+             eProtocol, eCanceled, eClosed;
+
+/* Event kinds carried from the callback to the pump to the request mailbox. */
+enum {
+    EV_SEND    = 1,  /* SENDREQUEST_COMPLETE                                  */
+    EV_HEADERS = 2,  /* HEADERS_AVAILABLE                                     */
+    EV_READ    = 3,  /* READ_COMPLETE   (a = byte count)                      */
+    EV_ERROR   = 4,  /* REQUEST_ERROR   (a = dwResult/which API, b = dwError) */
+    EV_SECURE  = 5,  /* SECURE_FAILURE  (a = failure flag bits)              */
+    EV_CLOSING = 6,  /* HANDLE_CLOSING  (consumed in C; never routed)         */
+    EV_LOST    = 7   /* synthesized by the pump on callback-side OOM          */
+};
+
+/* Receive buffer: >= 8 KiB per the research (avoids a WinHTTP recursion /
+ * stack-exhaustion problem); 64 KiB is the streaming chunk ceiling too. */
+#define RBUF_CAP (64 * 1024)
+
+/* Callback event node: plain malloc, allocated/freed with NO Ruby involvement. */
+typedef struct evnode {
+    struct evnode *next;
+    uint64_t id;   /* dwContext (0 = pre-context callback: dropped by the pump) */
+    int      kind;
+    DWORD    a;
+    DWORD    b;
+} evnode;
+
+/* Per-session control block (heap; freed when wrapper_gone && live == 0). */
+typedef struct whses {
+    HINTERNET hsession;
+    long      live;          /* requests whose ctx is armed and not yet os_done */
+    int       closed;        /* Session#close ran (hsession closed or leaked)    */
+    int       wrapper_gone;
+} whses;
+
+/* Per-request control block (heap; freed when wrapper_gone && os_done). */
+typedef struct whreq {
+    uint64_t       id;       /* dwContext value — NEVER a pointer, NEVER reused */
+    HINTERNET      hconn;    /* fresh per request (never cache connects)        */
+    HINTERNET      hreq;
+    whses         *ses;      /* owning session's control block                  */
+    unsigned char *body;     /* malloc'd COPY of the request body (or NULL)     */
+    size_t         body_len;
+    unsigned char *rbuf;     /* malloc'd receive buffer, RBUF_CAP                */
+    int            handles_closed; /* WinHttpCloseHandle(hreq) already issued    */
+    int            ctx_armed;      /* WINHTTP_OPTION_CONTEXT_VALUE set OK         */
+    int            wrapper_gone;
+    int            os_done;
+} whreq;
+
+/* Process-lifetime globals, created in Init_winhttp and NEVER destroyed (the
+ * phylax immortal-handle precedent — this is what makes late callbacks after
+ * any teardown harmless: they write into structures that always exist). */
+static CRITICAL_SECTION g_cs;
+static HANDLE   g_event;      /* auto-reset; signaled on every queued event */
+static evnode  *g_head, *g_tail;
+static volatile LONG g_dropped;   /* callback-side malloc failures (see §5.20) */
+static uint64_t g_next_id = 1;    /* monotonic; mutated only under the GVL     */
+static st_table *g_reqs;          /* id -> whreq*; mutated only under the GVL  */
+
+/* ------------------------------------------------------------ small helpers */
+
+/* UTF-8 Ruby String -> freshly xmalloc'd NUL-terminated UTF-16. Caller xfrees.
+ * The String is normalized to UTF-8 up front (suite boundary rule). */
+static WCHAR *
+to_wide(VALUE str)
+{
+    int len, n;
+    WCHAR *w;
+    str = rb_str_export_to_enc(StringValue(str), rb_utf8_encoding());
+    len = (int)RSTRING_LEN(str);
+    if (len == 0) {
+        w = (WCHAR *)xmalloc(sizeof(WCHAR));
+        w[0] = 0;
+        return w;
+    }
+    n = MultiByteToWideChar(CP_UTF8, 0, RSTRING_PTR(str), len, NULL, 0);
+    if (n <= 0) rb_raise(rb_eArgError, "winhttp: invalid UTF-8 in string");
+    w = (WCHAR *)xmalloc(sizeof(WCHAR) * (n + 1));
+    MultiByteToWideChar(CP_UTF8, 0, RSTRING_PTR(str), len, w, n);
+    w[n] = 0;
+    return w;
+}
+
+/* UTF-16 (len chars, or -1 NUL-terminated) -> a fresh UTF-8 Ruby String. */
+static VALUE
+wide_to_str(const WCHAR *w, int len)
+{
+    int n;
+    VALUE out;
+    if (!w) return rb_utf8_str_new("", 0);
+    n = WideCharToMultiByte(CP_UTF8, 0, w, len, NULL, 0, NULL, NULL);
+    if (n <= 0) return rb_utf8_str_new("", 0);
+    out = rb_utf8_str_new(NULL, len < 0 ? n - 1 : n);
+    WideCharToMultiByte(CP_UTF8, 0, w, len, RSTRING_PTR(out), n, NULL, NULL);
+    return out;
+}
+
+/* Build + raise a winhttp error carrying @code (the Win32/WinHTTP error). The
+ * code must be captured by the caller immediately after the failing call.
+ * ERROR_WINHTTP_* (12000-range) message text lives in winhttp.dll, so we ask
+ * FormatMessageW to look there as well as in the system table. */
+static void
+raise_code(VALUE klass, const char *api, DWORD code)
+{
+    VALUE exc, msg;
+    WCHAR *buf = NULL;
+    char detail[512];
+    DWORD n;
+    HMODULE hwh = GetModuleHandleW(L"winhttp.dll");
+
+    detail[0] = 0;
+    n = FormatMessageW(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM |
+                       FORMAT_MESSAGE_FROM_HMODULE | FORMAT_MESSAGE_IGNORE_INSERTS,
+                       hwh, code, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
+                       (LPWSTR)&buf, 0, NULL);
+    if (n && buf) {
+        while (n && (buf[n-1] == L'\r' || buf[n-1] == L'\n' || buf[n-1] == L'.')) buf[--n] = 0;
+        WideCharToMultiByte(CP_UTF8, 0, buf, -1, detail, (int)sizeof(detail), NULL, NULL);
+        detail[sizeof(detail) - 1] = 0;
+    }
+    /* Release the OS buffer BEFORE any Ruby allocation, so an OOM longjmp from
+     * rb_sprintf / rb_exc_new_str cannot leak it (winipc raise_code discipline). */
+    if (buf) LocalFree(buf);
+
+    if (detail[0])
+        msg = rb_sprintf("%s: %s (error %lu)", api, detail, (unsigned long)code);
+    else
+        msg = rb_sprintf("%s failed (error %lu)", api, (unsigned long)code);
+    exc = rb_exc_new_str(klass, msg);
+    rb_iv_set(exc, "@code", ULONG2NUM(code));
+    rb_exc_raise(exc);
+}
+
+/* Map a WinHTTP/Win32 error code to the right exception subclass. */
+static VALUE
+class_for_code(DWORD code)
+{
+    switch (code) {
+        case ERROR_WINHTTP_TIMEOUT:                 /* 12002 */
+            return eTimeout;
+        case ERROR_WINHTTP_NAME_NOT_RESOLVED:       /* 12007 */
+            return eResolve;
+        case ERROR_WINHTTP_CANNOT_CONNECT:          /* 12029 */
+        case ERROR_WINHTTP_CONNECTION_ERROR:        /* 12030 */
+            return eConnect;
+        case ERROR_WINHTTP_SECURE_FAILURE:          /* 12175 */
+        case ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED: /* 12044 */
+        case ERROR_WINHTTP_CLIENT_CERT_NO_PRIVATE_KEY:    /* 12185 */
+        case ERROR_WINHTTP_CLIENT_CERT_NO_ACCESS_PRIVATE_KEY: /* 12186 */
+        case ERROR_WINHTTP_SECURE_CERT_DATE_INVALID:      /* 12037 */
+        case ERROR_WINHTTP_SECURE_CERT_CN_INVALID:        /* 12038 */
+        case ERROR_WINHTTP_SECURE_INVALID_CA:             /* 12045 */
+        case ERROR_WINHTTP_SECURE_CERT_REV_FAILED:        /* 12057 */
+        case ERROR_WINHTTP_SECURE_CHANNEL_ERROR:          /* 12157 */
+        case ERROR_WINHTTP_SECURE_INVALID_CERT:           /* 12169 */
+        case ERROR_WINHTTP_SECURE_CERT_REVOKED:           /* 12170 */
+        case ERROR_WINHTTP_SECURE_CERT_WRONG_USAGE:       /* 12179 */
+            return eTls;
+        case ERROR_WINHTTP_REDIRECT_FAILED:         /* 12156 */
+            return eRedirect;
+        case ERROR_WINHTTP_INVALID_SERVER_RESPONSE: /* 12152 */
+        case ERROR_WINHTTP_HEADER_NOT_FOUND:        /* 12150 */
+        case ERROR_WINHTTP_INVALID_HEADER:          /* 12153 */
+            return eProtocol;
+        case ERROR_WINHTTP_OPERATION_CANCELLED:     /* 12017 */
+        case ERROR_OPERATION_ABORTED:               /* 995   */
+            return eCanceled;
+        default:
+            return eOSError;
+    }
+}
+
+/* ============================================================================
+ * The status callback (Bridge P) — runs on a WinHTTP worker thread or
+ * synchronously inside our own WinHttp* call. Touches ONLY: malloc, an evnode's
+ * fields, g_cs, g_dropped, SetEvent. Never Ruby, never the GVL, never blocks,
+ * no WinHttp* re-entry. Statuses not in the kind table are filtered out here.
+ * ==========================================================================*/
+
+static void
+push_event(uint64_t id, int kind, DWORD a, DWORD b)
+{
+    evnode *n = (evnode *)malloc(sizeof(evnode));
+    if (!n) {
+        /* No Ruby available to raise: record the loss + still wake the pump,
+         * which synthesizes EV_LOST for every mailbox (§5.20). */
+        InterlockedIncrement(&g_dropped);
+        SetEvent(g_event);
+        return;
+    }
+    n->next = NULL;
+    n->id = id;
+    n->kind = kind;
+    n->a = a;
+    n->b = b;
+    EnterCriticalSection(&g_cs);
+    if (g_tail) g_tail->next = n; else g_head = n;
+    g_tail = n;
+    LeaveCriticalSection(&g_cs);
+    SetEvent(g_event);
+}
+
+static void CALLBACK
+status_callback(HINTERNET h, DWORD_PTR ctx, DWORD status,
+                LPVOID info, DWORD len)
+{
+    uint64_t id = (uint64_t)ctx;
+    (void)h;
+    switch (status) {
+        case WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE:
+            push_event(id, EV_SEND, 0, 0);
+            break;
+        case WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE:
+            push_event(id, EV_HEADERS, 0, 0);
+            break;
+        case WINHTTP_CALLBACK_STATUS_READ_COMPLETE:
+            /* In async mode WinHttpReadData's READ_COMPLETE reports the byte
+             * count in `len` (info points at our own buffer). */
+            push_event(id, EV_READ, len, 0);
+            break;
+        case WINHTTP_CALLBACK_STATUS_REQUEST_ERROR: {
+            WINHTTP_ASYNC_RESULT *r = (WINHTTP_ASYNC_RESULT *)info;
+            DWORD which = r ? (DWORD)r->dwResult : 0;
+            DWORD err   = r ? r->dwError : 0;
+            push_event(id, EV_ERROR, which, err);
+            break;
+        }
+        case WINHTTP_CALLBACK_STATUS_SECURE_FAILURE: {
+            DWORD flags = (info && len >= sizeof(DWORD)) ? *(DWORD *)info : 0;
+            push_event(id, EV_SECURE, flags, 0);
+            break;
+        }
+        case WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING:
+            push_event(id, EV_CLOSING, 0, 0);
+            break;
+        default:
+            /* WRITE_COMPLETE, DATA_AVAILABLE, REDIRECT, resolve/connect chatter:
+             * no node, no wakeup. */
+            break;
+    }
+}
+
+/* =====================================================================
+ * Session — Winhttp::Session
+ * ===================================================================== */
+
+static void
+whses_free(void *p)
+{
+    whses *s = (whses *)p;
+    /* GC free hook (GVL held during sweep; table/flag ops are plain C). Safety
+     * net, never the API. */
+    if (!s) return;
+    s->wrapper_gone = 1;
+    if (s->live == 0) {
+        if (s->hsession && !s->closed) WinHttpCloseHandle(s->hsession);
+        free(s);
+    }
+    /* else: leave it for the pump's EV_CLOSING handler (an orphaned session
+     * with in-flight requests) — it frees when live hits 0. */
+}
+
+/* The TypedData payload is a POINTER to the heap control block (so WinHTTP may
+ * outlive the wrapper). dfree runs the free-hook above on that pointer. */
+static void
+ses_wrapper_free(void *p)
+{
+    whses **slot = (whses **)p;
+    if (slot && *slot) whses_free(*slot);
+    xfree(slot);
+}
+
+static size_t
+ses_wrapper_size(const void *p)
+{
+    (void)p;
+    return sizeof(whses *) + sizeof(whses);
+}
+
+static const rb_data_type_t ses_type = {
+    "Winhttp::Session",
+    { 0, ses_wrapper_free, ses_wrapper_size, },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+ses_alloc(VALUE klass)
+{
+    whses **slot;
+    VALUE obj = TypedData_Make_Struct(klass, whses *, &ses_type, slot);
+    *slot = NULL; /* sentinel: a never-initialized Session is inert */
+    return obj;
+}
+
+static whses *
+ses_ptr(VALUE self)
+{
+    whses **slot;
+    TypedData_Get_Struct(self, whses *, &ses_type, slot);
+    return *slot;
+}
+
+/* Set a DWORD option; return TRUE/FALSE (caller decides whether to raise). */
+static BOOL
+set_dword_opt(HINTERNET h, DWORD opt, DWORD val)
+{
+    return WinHttpSetOption(h, opt, &val, sizeof(val));
+}
+
+/* Winhttp::Session._open(ua, access_type, proxy, bypass,
+ *                        connect_ms, send_ms, receive_ms,   (-1 == unset)
+ *                        http2, decompress, redirect_policy, max_redirects,
+ *                        revocation)   revocation: 0 none / 1 best_effort / 2 strict
+ * Returns [session, effective_revocation_int].
+ */
+static VALUE
+ses_open(int argc, VALUE *argv, VALUE klass)
+{
+    VALUE vua, vaccess, vproxy, vbypass, vct, vst, vrt, vh2, vdec, vrp, vmaxr, vrev;
+    VALUE obj;
+    whses **slot;
+    whses *s;
+    HINTERNET hs;
+    WCHAR *ua = NULL, *proxy = NULL, *bypass = NULL;
+    DWORD access, gle;
+    long long ct, st, rt;
+    int want_h2, want_dec, redirect_policy, rev;
+    long long maxr;
+    DWORD secure_protocols;
+    int effective_rev;
+
+    /* We pass exactly 12 positional args from Ruby; read them directly. */
+    if (argc != 12) rb_raise(rb_eArgError, "winhttp: _open arity");
+    vua = argv[0]; vaccess = argv[1]; vproxy = argv[2]; vbypass = argv[3];
+    vct = argv[4]; vst = argv[5]; vrt = argv[6];
+    vh2 = argv[7]; vdec = argv[8]; vrp = argv[9]; vmaxr = argv[10]; vrev = argv[11];
+
+    access = (DWORD)NUM2ULONG(vaccess);
+    ct = NUM2LL(vct); st = NUM2LL(vst); rt = NUM2LL(vrt);
+    want_h2 = RTEST(vh2); want_dec = RTEST(vdec);
+    redirect_policy = NUM2INT(vrp);
+    maxr = NUM2LL(vmaxr);
+    rev = NUM2INT(vrev);
+
+    /* Convert all strings up front (TypeError here is clean: no handle yet). */
+    ua = to_wide(vua);
+    if (!NIL_P(vproxy)) proxy = to_wide(vproxy);
+    if (!NIL_P(vbypass)) bypass = to_wide(vbypass);
+
+    obj = ses_alloc(klass);
+    TypedData_Get_Struct(obj, whses *, &ses_type, slot);
+
+    hs = WinHttpOpen(ua, access,
+                     proxy ? proxy : WINHTTP_NO_PROXY_NAME,
+                     bypass ? bypass : WINHTTP_NO_PROXY_BYPASS,
+                     WINHTTP_FLAG_ASYNC);
+    gle = GetLastError();
+    xfree(ua);
+    if (proxy) xfree(proxy);
+    if (bypass) xfree(bypass);
+    if (!hs) raise_code(eOSError, "WinHttpOpen", gle);
+
+    /* Register the status callback ONCE on the session before any child handle
+     * (inherited by derived handles). */
+    if (WinHttpSetStatusCallback(hs, status_callback,
+                                 WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS, 0)
+        == WINHTTP_INVALID_STATUS_CALLBACK) {
+        gle = GetLastError();
+        WinHttpCloseHandle(hs);
+        raise_code(eOSError, "WinHttpSetStatusCallback", gle);
+    }
+
+    /* Timeouts (resolve fixed at 0 == default-infinite resolve; others only
+     * when the caller supplied them; -1 means "leave the WinHTTP default"). */
+    if (ct >= 0 || st >= 0 || rt >= 0) {
+        int cms = (int)(ct >= 0 ? ct : 0);
+        int sms = (int)(st >= 0 ? st : 30000);
+        int rms = (int)(rt >= 0 ? rt : 30000);
+        if (!WinHttpSetTimeouts(hs, 0, cms, sms, rms)) {
+            gle = GetLastError();
+            WinHttpCloseHandle(hs);
+            raise_code(eOSError, "WinHttpSetTimeouts", gle);
+        }
+    }
+
+    /* TLS floor: always TLS1.2|TLS1.3, fall back to TLS1.2 alone, else raise. */
+    secure_protocols = WINHTTP_FLAG_SECURE_PROTOCOL_TLS1_2 |
+                       WINHTTP_FLAG_SECURE_PROTOCOL_TLS1_3;
+    if (!set_dword_opt(hs, WINHTTP_OPTION_SECURE_PROTOCOLS, secure_protocols)) {
+        secure_protocols = WINHTTP_FLAG_SECURE_PROTOCOL_TLS1_2;
+        if (!set_dword_opt(hs, WINHTTP_OPTION_SECURE_PROTOCOLS, secure_protocols)) {
+            gle = GetLastError();
+            WinHttpCloseHandle(hs);
+            raise_code(eOSError, "WinHttpSetOption(SECURE_PROTOCOLS)", gle);
+        }
+    }
+
+    /* HTTP/2 + decompression: best-effort, a rejecting OS degrades silently. */
+    if (want_h2)
+        set_dword_opt(hs, WINHTTP_OPTION_ENABLE_HTTP_PROTOCOL,
+                      WINHTTP_PROTOCOL_FLAG_HTTP2);
+    if (want_dec)
+        set_dword_opt(hs, WINHTTP_OPTION_DECOMPRESSION,
+                      WINHTTP_DECOMPRESSION_FLAG_ALL);
+
+    /* Redirect policy + max count. */
+    set_dword_opt(hs, WINHTTP_OPTION_REDIRECT_POLICY, (DWORD)redirect_policy);
+    if (maxr >= 0)
+        set_dword_opt(hs, WINHTTP_OPTION_MAX_HTTP_AUTOMATIC_REDIRECTS, (DWORD)maxr);
+
+    /* Revocation policy is settled here by probing throwaway handles (neither
+     * call touches the network; both probe handles are context-less, so their
+     * HANDLE_CLOSING arrives as id 0 and the pump drops it). */
+    effective_rev = 0; /* :none default */
+    if (rev != 0) {
+        HINTERNET hc = WinHttpConnect(hs, L"localhost", 80, 0);
+        if (hc) {
+            HINTERNET hrq = WinHttpOpenRequest(hc, L"GET", L"/", NULL,
+                                               WINHTTP_NO_REFERER,
+                                               WINHTTP_DEFAULT_ACCEPT_TYPES, 0);
+            if (hrq) {
+                BOOL ok_rev = set_dword_opt(hrq, WINHTTP_OPTION_ENABLE_FEATURE,
+                                            WINHTTP_ENABLE_SSL_REVOCATION);
+                if (rev == 2) {
+                    /* :strict — revocation must be available, else raise. */
+                    if (ok_rev) {
+                        effective_rev = 2;
+                    } else {
+                        gle = GetLastError();
+                        WinHttpCloseHandle(hrq);
+                        WinHttpCloseHandle(hc);
+                        WinHttpCloseHandle(hs);
+                        raise_code(eOSError,
+                                   "WinHttpSetOption(ENABLE_SSL_REVOCATION)", gle);
+                    }
+                } else {
+                    /* :best_effort — both options must succeed, else degrade. */
+                    BOOL ok_off = ok_rev &&
+                        set_dword_opt(hrq, WINHTTP_OPTION_IGNORE_CERT_REVOCATION_OFFLINE,
+                                      TRUE);
+                    effective_rev = (ok_rev && ok_off) ? 1 : 0;
+                }
+                WinHttpCloseHandle(hrq);
+            } else if (rev == 2) {
+                gle = GetLastError();
+                WinHttpCloseHandle(hc);
+                WinHttpCloseHandle(hs);
+                raise_code(eOSError, "WinHttpOpenRequest(probe)", gle);
+            }
+            WinHttpCloseHandle(hc);
+        } else if (rev == 2) {
+            gle = GetLastError();
+            WinHttpCloseHandle(hs);
+            raise_code(eOSError, "WinHttpConnect(probe)", gle);
+        }
+    }
+
+    s = (whses *)calloc(1, sizeof(whses));
+    if (!s) { WinHttpCloseHandle(hs); rb_raise(rb_eNoMemError, "winhttp: out of memory"); }
+    s->hsession = hs;
+    s->live = 0;
+    s->closed = 0;
+    s->wrapper_gone = 0;
+    *slot = s;
+
+    return rb_ary_new3(2, obj, INT2NUM(effective_rev));
+}
+
+static VALUE ses_closed_p(VALUE self) {
+    whses *s = ses_ptr(self);
+    return (!s || s->closed) ? Qtrue : Qfalse;
+}
+
+/* Mark the session closed FIRST (GVL-held, strictly before any handle is
+ * closed): new requests / _start's re-check raise Winhttp::Closed. Returns the
+ * raw HINTERNET so Ruby can sequence the abort sweep before _close_handle. */
+static VALUE ses_mark_closed(VALUE self) {
+    whses *s = ses_ptr(self);
+    if (!s) return Qnil;
+    s->closed = 1;
+    return Qnil;
+}
+
+/* Close the session handle iff live == 0. Returns true when closed (or already
+ * gone / no live requests), false when deferred because requests are still
+ * tearing down. */
+static VALUE ses_try_close_handle(VALUE self) {
+    whses *s = ses_ptr(self);
+    if (!s) return Qtrue;
+    if (s->live > 0) return Qfalse;
+    if (s->hsession) { WinHttpCloseHandle(s->hsession); s->hsession = NULL; }
+    return Qtrue;
+}
+
+static VALUE ses_live_count(VALUE self) {
+    whses *s = ses_ptr(self);
+    return s ? LONG2NUM(s->live) : INT2NUM(0);
+}
+
+/* =====================================================================
+ * Request — Winhttp::Request (internal plumbing; no public contract)
+ * ===================================================================== */
+
+static void
+whreq_maybe_free(whreq *r)
+{
+    /* Free iff BOTH flags set. Caller holds the GVL. */
+    if (!(r->wrapper_gone && r->os_done)) return;
+    st_delete(g_reqs, (st_data_t *)&r->id, NULL);
+    if (r->body) free(r->body);
+    if (r->rbuf) free(r->rbuf);
+    free(r);
+}
+
+static void
+whreq_free(void *p)
+{
+    /* GC free hook for the Request wrapper (GVL held during sweep). Safety net.
+     * Set wrapper_gone; if no callback can ever come (!ctx_armed) or the OS is
+     * already done, free now; else leave it for the pump's EV_CLOSING. */
+    whreq **slot = (whreq **)p;
+    whreq *r = slot ? *slot : NULL;
+    if (r) {
+        r->wrapper_gone = 1;
+        if (!r->handles_closed && r->hreq) {
+            WinHttpCloseHandle(r->hreq);
+            r->handles_closed = 1;
+        }
+        if (!r->ctx_armed) {
+            /* No context armed => no HANDLE_CLOSING for our id will ever come.
+             * The connect handle (if any) is closed here; nothing is registered
+             * in g_reqs yet for the pre-arm path, so just free our memory. We
+             * must still drop the live count / connect if it was registered. */
+            if (r->hconn) WinHttpCloseHandle(r->hconn);
+            /* If this block was registered (it is only ever registered after
+             * the handles exist, just before arming), st_delete is harmless if
+             * absent. ses->live was only incremented at arm time. */
+            st_delete(g_reqs, (st_data_t *)&r->id, NULL);
+            if (r->body) free(r->body);
+            if (r->rbuf) free(r->rbuf);
+            free(r);
+        } else {
+            whreq_maybe_free(r);
+        }
+    }
+    xfree(slot);
+}
+
+static size_t
+req_wrapper_size(const void *p)
+{
+    whreq * const *slot = (whreq * const *)p;
+    whreq *r = slot ? *slot : NULL;
+    size_t n = sizeof(whreq *) + sizeof(whreq);
+    if (r) n += r->body_len + (r->rbuf ? RBUF_CAP : 0);
+    return n;
+}
+
+static const rb_data_type_t req_type = {
+    "Winhttp::Request",
+    { 0, whreq_free, req_wrapper_size, },
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+req_alloc(VALUE klass)
+{
+    whreq **slot;
+    VALUE obj = TypedData_Make_Struct(klass, whreq *, &req_type, slot);
+    *slot = NULL;
+    return obj;
+}
+
+static whreq *
+req_ptr(VALUE self)
+{
+    whreq **slot;
+    TypedData_Get_Struct(self, whreq *, &req_type, slot);
+    return *slot;
+}
+
+/* Raises Winhttp::Canceled if the request handle is already closed (the
+ * cancelled-op-may-complete-successfully backstop, §3.6.6). */
+static whreq *
+req_live(VALUE self)
+{
+    whreq *r = req_ptr(self);
+    if (!r) rb_raise(eError, "winhttp: request is not initialized");
+    if (r->handles_closed)
+        raise_code(eCanceled, "WinHttp(after close)", ERROR_WINHTTP_OPERATION_CANCELLED);
+    return r;
+}
+
+/* Session#_start(req_obj, verb, host, port, secure, path, header_blob, body,
+ *                effective_revocation) -> id (Integer)
+ *
+ * One raise-hygienic C frame. The Request wrapper (req_obj) is allocated in
+ * Ruby and passed in so its free hook owns the handles from the instant they
+ * exist. Holds the GVL throughout (§3.5), so the ses->closed re-check is
+ * race-free against Session#close.
+ */
+static VALUE
+req_start(VALUE self, VALUE req_obj, VALUE vverb, VALUE vhost, VALUE vport,
+          VALUE vsecure, VALUE vpath, VALUE vblob, VALUE vbody, VALUE vrev)
+{
+    whses *ses = ses_ptr(self);
+    whreq **slot;
+    whreq *r;
+    WCHAR *verb = NULL, *host = NULL, *path = NULL, *blob = NULL;
+    INTERNET_PORT port = (INTERNET_PORT)NUM2UINT(vport);
+    int secure = RTEST(vsecure);
+    int rev = NUM2INT(vrev);
+    DWORD open_flags = secure ? WINHTTP_FLAG_SECURE : 0;
+    DWORD gle;
+    uint64_t id;
+
+    if (!ses || ses->closed)
+        rb_raise(eClosed, "winhttp: session is closed");
+
+    TypedData_Get_Struct(req_obj, whreq *, &req_type, slot);
+
+    /* Coerce/convert all strings up front (raise-clean: no control block yet). */
+    verb = to_wide(vverb);
+    host = to_wide(vhost);
+    path = to_wide(vpath);
+    if (!NIL_P(vblob)) blob = to_wide(vblob);
+
+    /* Allocate the control block + buffers (plain malloc; free on failure and
+     * raise manually so an OOM longjmp can't leak the wide strings). */
+    r = (whreq *)calloc(1, sizeof(whreq));
+    if (r) r->rbuf = (unsigned char *)malloc(RBUF_CAP);
+    if (!r || !r->rbuf) {
+        if (r) free(r);
+        xfree(verb); xfree(host); xfree(path); if (blob) xfree(blob);
+        rb_raise(rb_eNoMemError, "winhttp: out of memory");
+    }
+    r->ses = ses;
+    *slot = r; /* the wrapper free hook owns r from here on */
+
+    /* Copy the body into a private buffer (WinHTTP does not copy buffers). */
+    if (!NIL_P(vbody)) {
+        long blen;
+        StringValue(vbody);
+        blen = RSTRING_LEN(vbody);
+        if (blen > 0) {
+            r->body = (unsigned char *)malloc((size_t)blen);
+            if (!r->body) {
+                xfree(verb); xfree(host); xfree(path); if (blob) xfree(blob);
+                rb_raise(rb_eNoMemError, "winhttp: out of memory");
+            }
+            memcpy(r->body, RSTRING_PTR(vbody), (size_t)blen);
+            r->body_len = (size_t)blen;
+        }
+    }
+
+    /* Re-check ses->closed (TOCTOU close — §3.4/§5.25): GVL-held, race-free. */
+    if (ses->closed) {
+        xfree(verb); xfree(host); xfree(path); if (blob) xfree(blob);
+        rb_raise(eClosed, "winhttp: session is closed");
+    }
+
+    r->hconn = WinHttpConnect(ses->hsession, host, port, 0);
+    if (!r->hconn) {
+        gle = GetLastError();
+        xfree(verb); xfree(host); xfree(path); if (blob) xfree(blob);
+        /* pre-arm cleanup: no context, immediate free is safe (free hook). */
+        raise_code(class_for_code(gle), "WinHttpConnect", gle);
+    }
+    r->hreq = WinHttpOpenRequest(r->hconn, verb, path, NULL,
+                                 WINHTTP_NO_REFERER, WINHTTP_DEFAULT_ACCEPT_TYPES,
+                                 open_flags);
+    if (!r->hreq) {
+        gle = GetLastError();
+        xfree(verb); xfree(host); xfree(path); if (blob) xfree(blob);
+        raise_code(class_for_code(gle), "WinHttpOpenRequest", gle);
+    }
+    xfree(verb); xfree(host); xfree(path); /* done with these */
+
+    /* Registration strictly before arming, so an armed context always has a
+     * table entry. */
+    id = g_next_id++;
+    r->id = id;
+    st_insert(g_reqs, (st_data_t)id, (st_data_t)r);
+    ses->live++;
+
+    /* Arm the context value before anything can complete (§5.10): this is what
+     * makes HANDLE_CLOSING with our id guaranteed. */
+    {
+        DWORD_PTR ctxv = (DWORD_PTR)id;
+        if (!WinHttpSetOption(r->hreq, WINHTTP_OPTION_CONTEXT_VALUE,
+                              &ctxv, sizeof(ctxv))) {
+            gle = GetLastError();
+            /* roll back registration; still pre-arm (ctx not set) => free now. */
+            st_delete(g_reqs, (st_data_t *)&id, NULL);
+            ses->live--;
+            if (blob) xfree(blob);
+            raise_code(class_for_code(gle), "WinHttpSetOption(CONTEXT_VALUE)", gle);
+        }
+        r->ctx_armed = 1;
+    }
+
+    /* --- post-arm regime: any failure leaves the block registered + live
+     * counted; EV_CLOSING settles it (§3.4). Never free inline here. --- */
+
+    /* Per-request revocation options matching the construction-settled policy. */
+    if (rev != 0) {
+        if (!set_dword_opt(r->hreq, WINHTTP_OPTION_ENABLE_FEATURE,
+                           WINHTTP_ENABLE_SSL_REVOCATION)) {
+            gle = GetLastError();
+            if (blob) xfree(blob);
+            WinHttpCloseHandle(r->hreq);
+            r->handles_closed = 1;
+            raise_code(class_for_code(gle),
+                       "WinHttpSetOption(ENABLE_SSL_REVOCATION)", gle);
+        }
+        if (rev == 1) {
+            if (!set_dword_opt(r->hreq, WINHTTP_OPTION_IGNORE_CERT_REVOCATION_OFFLINE,
+                               TRUE)) {
+                gle = GetLastError();
+                if (blob) xfree(blob);
+                WinHttpCloseHandle(r->hreq);
+                r->handles_closed = 1;
+                raise_code(class_for_code(gle),
+                           "WinHttpSetOption(IGNORE_CERT_REVOCATION_OFFLINE)", gle);
+            }
+        }
+    }
+
+    if (blob) {
+        if (!WinHttpAddRequestHeaders(r->hreq, blob, (DWORD)-1,
+                                      WINHTTP_ADDREQ_FLAG_ADD)) {
+            gle = GetLastError();
+            xfree(blob);
+            WinHttpCloseHandle(r->hreq);
+            r->handles_closed = 1;
+            raise_code(class_for_code(gle), "WinHttpAddRequestHeaders", gle);
+        }
+        xfree(blob);
+    }
+
+    return ULL2NUM(id);
+}
+
+/* Request#_send — WinHttpSendRequest (async). Immediate FALSE => no callback,
+ * raise now. */
+static VALUE
+req_send(VALUE self)
+{
+    whreq *r = req_live(self);
+    DWORD_PTR ctxv = (DWORD_PTR)r->id;
+    LPVOID body = r->body ? (LPVOID)r->body : WINHTTP_NO_REQUEST_DATA;
+    DWORD blen = (DWORD)r->body_len;
+    if (!WinHttpSendRequest(r->hreq, WINHTTP_NO_ADDITIONAL_HEADERS, 0,
+                            body, blen, blen, ctxv)) {
+        DWORD gle = GetLastError();
+        raise_code(class_for_code(gle), "WinHttpSendRequest", gle);
+    }
+    return Qnil;
+}
+
+static VALUE
+req_receive(VALUE self)
+{
+    whreq *r = req_live(self);
+    if (!WinHttpReceiveResponse(r->hreq, NULL)) {
+        DWORD gle = GetLastError();
+        raise_code(class_for_code(gle), "WinHttpReceiveResponse", gle);
+    }
+    return Qnil;
+}
+
+static VALUE
+req_read_start(VALUE self)
+{
+    whreq *r = req_live(self);
+    if (!WinHttpReadData(r->hreq, r->rbuf, RBUF_CAP, NULL)) {
+        DWORD gle = GetLastError();
+        raise_code(class_for_code(gle), "WinHttpReadData", gle);
+    }
+    return Qnil;
+}
+
+/* Request#_read_take(n) -> fresh ASCII-8BIT String of the first n bytes. */
+static VALUE
+req_read_take(VALUE self, VALUE vn)
+{
+    whreq *r = req_live(self);
+    long n = (long)NUM2LL(vn);
+    VALUE out;
+    if (n < 0) n = 0;
+    if (n > RBUF_CAP) n = RBUF_CAP;
+    out = rb_str_new((const char *)r->rbuf, n);
+    rb_enc_associate(out, rb_ascii8bit_encoding());
+    return out;
+}
+
+/* Query a raw-headers / status / url / protocol bundle, GVL held.
+ * Returns [status(Integer), raw_headers(String UTF-8), final_url(String),
+ *          http2(bool)]. */
+static VALUE
+req_headers(VALUE self)
+{
+    whreq *r = req_live(self);
+    DWORD status = 0, size = 0, gle;
+    DWORD idx = 0; /* WINHTTP_NO_HEADER_INDEX is NULL; we pass &idx, reset per call */
+    VALUE raw, url, ret;
+    WCHAR *buf;
+    DWORD proto = 0, psz = sizeof(proto);
+
+    /* status code (numeric) */
+    size = sizeof(status);
+    if (!WinHttpQueryHeaders(r->hreq,
+                             WINHTTP_QUERY_STATUS_CODE | WINHTTP_QUERY_FLAG_NUMBER,
+                             WINHTTP_HEADER_NAME_BY_INDEX, &status, &size, &idx)) {
+        gle = GetLastError();
+        raise_code(class_for_code(gle), "WinHttpQueryHeaders(STATUS_CODE)", gle);
+    }
+
+    /* raw headers (CRLF) — two-call size pattern */
+    size = 0; idx = 0;
+    WinHttpQueryHeaders(r->hreq, WINHTTP_QUERY_RAW_HEADERS_CRLF,
+                        WINHTTP_HEADER_NAME_BY_INDEX, NULL, &size, &idx);
+    gle = GetLastError();
+    if (gle != ERROR_INSUFFICIENT_BUFFER && size == 0) {
+        raise_code(class_for_code(gle), "WinHttpQueryHeaders(RAW_HEADERS)", gle);
+    }
+    buf = (WCHAR *)xmalloc(size + sizeof(WCHAR));
+    idx = 0;
+    if (!WinHttpQueryHeaders(r->hreq, WINHTTP_QUERY_RAW_HEADERS_CRLF,
+                             WINHTTP_HEADER_NAME_BY_INDEX, buf, &size, &idx)) {
+        gle = GetLastError();
+        xfree(buf);
+        raise_code(class_for_code(gle), "WinHttpQueryHeaders(RAW_HEADERS)", gle);
+    }
+    raw = wide_to_str(buf, (int)(size / sizeof(WCHAR)));
+    xfree(buf);
+
+    /* final URL (after redirects) — two-call size pattern */
+    size = 0;
+    WinHttpQueryOption(r->hreq, WINHTTP_OPTION_URL, NULL, &size);
+    if (size == 0) {
+        url = rb_utf8_str_new("", 0);
+    } else {
+        buf = (WCHAR *)xmalloc(size + sizeof(WCHAR));
+        if (!WinHttpQueryOption(r->hreq, WINHTTP_OPTION_URL, buf, &size)) {
+            xfree(buf);
+            url = rb_utf8_str_new("", 0);
+        } else {
+            url = wide_to_str(buf, -1);
+            xfree(buf);
+        }
+    }
+
+    /* protocol used (best-effort; 0 on failure) */
+    if (!WinHttpQueryOption(r->hreq, WINHTTP_OPTION_HTTP_PROTOCOL_USED,
+                            &proto, &psz)) {
+        proto = 0;
+    }
+
+    ret = rb_ary_new3(4, UINT2NUM(status), raw, url,
+                      (proto & WINHTTP_PROTOCOL_FLAG_HTTP2) ? Qtrue : Qfalse);
+    return ret;
+}
+
+/* Request#_abort / #_finish — WinHttpCloseHandle(hreq), idempotent. Teardown is
+ * async; the pump's EV_CLOSING settles os_done + the connect handle. */
+static VALUE
+req_abort(VALUE self)
+{
+    whreq *r = req_ptr(self);
+    if (r && !r->handles_closed && r->hreq) {
+        WinHttpCloseHandle(r->hreq);
+        r->handles_closed = 1;
+    }
+    return Qnil;
+}
+
+/* =====================================================================
+ * Pump primitives (Bridge P)
+ * ===================================================================== */
+
+static void *
+pump_wait_fn(void *p)
+{
+    (void)p;
+    WaitForSingleObject(g_event, INFINITE);
+    return NULL;
+}
+
+static void
+pump_wait_ubf(void *p)
+{
+    (void)p;
+    SetEvent(g_event); /* break the no-GVL wait promptly (Thread#kill / exit) */
+}
+
+/* Winhttp._pump_wait — block (GVL released) until the callback signals. */
+static VALUE
+pump_wait(VALUE mod)
+{
+    (void)mod;
+    rb_thread_call_without_gvl(pump_wait_fn, NULL, pump_wait_ubf, NULL);
+    return Qnil;
+}
+
+/* Winhttp._pump_drain — detach the event list (g_cs held only for the pointer
+ * swap), then per node (GVL held): EV_CLOSING bookkeeping in C (never routed),
+ * else build a [id, kind, a, b] tuple. Returns the tuple array. Also emits one
+ * EV_LOST tuple with id 0 when g_dropped > 0 (the Ruby pump fans it out to all
+ * mailboxes). */
+static VALUE
+pump_drain(VALUE mod)
+{
+    evnode *head, *n;
+    VALUE out = rb_ary_new();
+    LONG dropped;
+    (void)mod;
+
+    EnterCriticalSection(&g_cs);
+    head = g_head;
+    g_head = g_tail = NULL;
+    LeaveCriticalSection(&g_cs);
+
+    n = head;
+    while (n) {
+        evnode *next = n->next;
+        if (n->kind == EV_CLOSING) {
+            /* Drain-side lifetime bookkeeping for id n->id (GVL held). */
+            st_data_t v;
+            if (st_lookup(g_reqs, (st_data_t)n->id, &v)) {
+                whreq *r = (whreq *)v;
+                whses *ses = r->ses;
+                r->os_done = 1;
+                if (r->hconn) { WinHttpCloseHandle(r->hconn); r->hconn = NULL; }
+                if (ses && ses->live > 0) ses->live--;
+                if (ses && ses->wrapper_gone && ses->live == 0 && !ses->closed) {
+                    if (ses->hsession) WinHttpCloseHandle(ses->hsession);
+                    free(ses);
+                    r->ses = NULL;
+                }
+                whreq_maybe_free(r);
+            }
+            /* EV_CLOSING is consumed in C and not routed to any mailbox. */
+        } else {
+            rb_ary_push(out, rb_ary_new3(4,
+                ULL2NUM(n->id), INT2NUM(n->kind),
+                ULONG2NUM(n->a), ULONG2NUM(n->b)));
+        }
+        free(n);
+        n = next;
+    }
+
+    dropped = InterlockedExchange(&g_dropped, 0);
+    if (dropped > 0) {
+        /* id 0 sentinel — the Ruby pump fans EV_LOST out to every mailbox. */
+        rb_ary_push(out, rb_ary_new3(4, ULL2NUM(0), INT2NUM(EV_LOST),
+                                     INT2NUM(0), INT2NUM(0)));
+    }
+    return out;
+}
+
+/* Winhttp._live_count — test-only introspection (§3.2): number of g_reqs
+ * entries whose os_done is unset. Underscore-named, no public contract; exists
+ * solely so the §5.10 leak probe (test 51) can assert against real counters per
+ * the suite's no-mock rule. */
+static int
+live_count_i(st_data_t key, st_data_t val, st_data_t arg)
+{
+    whreq *r = (whreq *)val;
+    long *acc = (long *)arg;
+    (void)key;
+    if (!r->os_done) (*acc)++;
+    return ST_CONTINUE;
+}
+
+static VALUE
+live_count(VALUE mod)
+{
+    long acc = 0;
+    (void)mod;
+    st_foreach(g_reqs, live_count_i, (st_data_t)&acc);
+    return LONG2NUM(acc);
+}
+
+/* =====================================================================
+ * URL cracking — Winhttp._crack(url) -> [secure, host, port, path]
+ * ===================================================================== */
+
+static VALUE
+url_crack(VALUE mod, VALUE vurl)
+{
+    URL_COMPONENTS uc;
+    WCHAR user[2], pass[2];
+    WCHAR *url, *host = NULL, *path = NULL, *extra = NULL;
+    size_t urllen, cap;
+    int secure, err = 0;
+    VALUE host_s, path_s;
+    (void)mod;
+
+    url = to_wide(vurl);
+
+    /* A cracked component can never be longer than the URL itself, so sizing
+     * host/path/extra at (urllen + 1) WCHARs each is always sufficient — this
+     * is what makes legitimate long URLs (big OAuth/JWT/base64 query strings,
+     * signed URLs) crack instead of failing ERROR_INSUFFICIENT_BUFFER against
+     * the old fixed 256/4096-WCHAR stack buffers. */
+    urllen = wcslen(url);
+    cap = urllen + 1;
+    host  = (WCHAR *)xmalloc(sizeof(WCHAR) * cap);
+    path  = (WCHAR *)xmalloc(sizeof(WCHAR) * cap);
+    extra = (WCHAR *)xmalloc(sizeof(WCHAR) * cap);
+
+    memset(&uc, 0, sizeof(uc));
+    uc.dwStructSize = sizeof(uc);
+    uc.lpszHostName = host;       uc.dwHostNameLength = (DWORD)cap;
+    uc.lpszUrlPath = path;        uc.dwUrlPathLength = (DWORD)cap;
+    uc.lpszExtraInfo = extra;     uc.dwExtraInfoLength = (DWORD)cap;
+    /* Non-zero length pointers so userinfo presence is detectable. */
+    uc.lpszUserName = user;       uc.dwUserNameLength = (DWORD)(sizeof(user) / sizeof(WCHAR));
+    uc.lpszPassword = pass;       uc.dwPasswordLength = (DWORD)(sizeof(pass) / sizeof(WCHAR));
+
+    if (!WinHttpCrackUrl(url, 0, 0, &uc)) err = 1;
+    xfree(url);
+
+    /* Free the component buffers before any rb_raise (longjmp): copy out what
+     * we still need into Ruby Strings first, then xfree, then raise/return. */
+    if (err) {
+        xfree(host); xfree(path); xfree(extra);
+        rb_raise(rb_eArgError, "winhttp: could not parse URL");
+    }
+
+    if (uc.nScheme != INTERNET_SCHEME_HTTP && uc.nScheme != INTERNET_SCHEME_HTTPS) {
+        xfree(host); xfree(path); xfree(extra);
+        rb_raise(rb_eArgError, "winhttp: URL scheme must be http or https");
+    }
+
+    /* Reject embedded credentials (user:pass@host — never supported). */
+    if (uc.dwUserNameLength > 0 || uc.dwPasswordLength > 0) {
+        xfree(host); xfree(path); xfree(extra);
+        rb_raise(rb_eArgError, "winhttp: credentials in URL are not supported");
+    }
+
+    secure = (uc.nScheme == INTERNET_SCHEME_HTTPS);
+    host_s = wide_to_str(uc.lpszHostName, (int)uc.dwHostNameLength);
+
+    /* path + query reassembled (OpenRequest takes path+extra together). */
+    {
+        VALUE p = wide_to_str(uc.lpszUrlPath, (int)uc.dwUrlPathLength);
+        VALUE e = (uc.dwExtraInfoLength > 0)
+                  ? wide_to_str(uc.lpszExtraInfo, (int)uc.dwExtraInfoLength)
+                  : rb_utf8_str_new("", 0);
+        if (RSTRING_LEN(p) == 0) p = rb_utf8_str_new("/", 1);
+        path_s = rb_str_plus(p, e);
+    }
+
+    xfree(host); xfree(path); xfree(extra);
+
+    return rb_ary_new3(4, secure ? Qtrue : Qfalse, host_s,
+                       UINT2NUM(uc.nPort), path_s);
+}
+
+/* Winhttp._raise_os(api, code, secure_flags) — raise the mapped subclass from
+ * Ruby (the state machine routes EV_ERROR here). For TlsError, decode the
+ * captured SECURE_FAILURE flag bits into the @details symbol array. */
+static VALUE
+raise_os(VALUE mod, VALUE vapi, VALUE vcode, VALUE vsecure)
+{
+    DWORD code = (DWORD)NUM2ULONG(vcode);
+    VALUE klass = class_for_code(code);
+    const char *api = NIL_P(vapi) ? "WinHttp" : StringValueCStr(vapi);
+    (void)mod;
+
+    if (klass == eTls && !NIL_P(vsecure)) {
+        DWORD flags = (DWORD)NUM2ULONG(vsecure);
+        VALUE details = rb_ary_new();
+        VALUE exc, msg;
+        WCHAR *buf = NULL;
+        char detail[512];
+        DWORD n;
+        HMODULE hwh = GetModuleHandleW(L"winhttp.dll");
+
+        if (flags & WINHTTP_CALLBACK_STATUS_FLAG_CERT_REV_FAILED)
+            rb_ary_push(details, ID2SYM(rb_intern("cert_rev_failed")));
+        if (flags & WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CERT)
+            rb_ary_push(details, ID2SYM(rb_intern("invalid_cert")));
+        if (flags & WINHTTP_CALLBACK_STATUS_FLAG_CERT_REVOKED)
+            rb_ary_push(details, ID2SYM(rb_intern("cert_revoked")));
+        if (flags & WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CA)
+            rb_ary_push(details, ID2SYM(rb_intern("invalid_ca")));
+        if (flags & WINHTTP_CALLBACK_STATUS_FLAG_CERT_CN_INVALID)
+            rb_ary_push(details, ID2SYM(rb_intern("cert_cn_invalid")));
+        if (flags & WINHTTP_CALLBACK_STATUS_FLAG_CERT_DATE_INVALID)
+            rb_ary_push(details, ID2SYM(rb_intern("cert_date_invalid")));
+        if (flags & WINHTTP_CALLBACK_STATUS_FLAG_SECURITY_CHANNEL_ERROR)
+            rb_ary_push(details, ID2SYM(rb_intern("security_channel_error")));
+
+        detail[0] = 0;
+        n = FormatMessageW(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM |
+                           FORMAT_MESSAGE_FROM_HMODULE | FORMAT_MESSAGE_IGNORE_INSERTS,
+                           hwh, code, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
+                           (LPWSTR)&buf, 0, NULL);
+        if (n && buf) {
+            while (n && (buf[n-1] == L'\r' || buf[n-1] == L'\n' || buf[n-1] == L'.')) buf[--n] = 0;
+            WideCharToMultiByte(CP_UTF8, 0, buf, -1, detail, (int)sizeof(detail), NULL, NULL);
+            detail[sizeof(detail) - 1] = 0;
+        }
+        if (buf) LocalFree(buf);
+        if (detail[0])
+            msg = rb_sprintf("%s: %s (error %lu)", api, detail, (unsigned long)code);
+        else
+            msg = rb_sprintf("%s failed (error %lu)", api, (unsigned long)code);
+        exc = rb_exc_new_str(eTls, msg);
+        rb_iv_set(exc, "@code", ULONG2NUM(code));
+        rb_iv_set(exc, "@details", details);
+        rb_exc_raise(exc);
+    }
+
+    raise_code(klass, api, code);
+    return Qnil; /* unreachable */
+}
+
+/* ----------------------------------------------------------------- Init --- */
+
+void
+Init_winhttp(void)
+{
+    mWinhttp = rb_define_module("Winhttp");
+
+    eError    = rb_define_class_under(mWinhttp, "Error", rb_eStandardError);
+    eOSError  = rb_define_class_under(mWinhttp, "OSError", eError);
+    eTimeout  = rb_define_class_under(mWinhttp, "TimeoutError", eOSError);
+    eResolve  = rb_define_class_under(mWinhttp, "ResolveError", eOSError);
+    eConnect  = rb_define_class_under(mWinhttp, "ConnectError", eOSError);
+    eTls      = rb_define_class_under(mWinhttp, "TlsError", eOSError);
+    eRedirect = rb_define_class_under(mWinhttp, "RedirectError", eOSError);
+    eProtocol = rb_define_class_under(mWinhttp, "ProtocolError", eOSError);
+    eCanceled = rb_define_class_under(mWinhttp, "Canceled", eOSError);
+    eClosed   = rb_define_class_under(mWinhttp, "Closed", eError);
+
+    /* Event-kind constants (consumed by the Ruby state machine). */
+    rb_define_const(mWinhttp, "EV_SEND",    INT2FIX(EV_SEND));
+    rb_define_const(mWinhttp, "EV_HEADERS", INT2FIX(EV_HEADERS));
+    rb_define_const(mWinhttp, "EV_READ",    INT2FIX(EV_READ));
+    rb_define_const(mWinhttp, "EV_ERROR",   INT2FIX(EV_ERROR));
+    rb_define_const(mWinhttp, "EV_SECURE",  INT2FIX(EV_SECURE));
+    rb_define_const(mWinhttp, "EV_LOST",    INT2FIX(EV_LOST));
+
+    /* Access-type constants for Session._open. */
+    rb_define_const(mWinhttp, "ACCESS_AUTOMATIC", UINT2NUM(WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY));
+    rb_define_const(mWinhttp, "ACCESS_NO_PROXY",  UINT2NUM(WINHTTP_ACCESS_TYPE_NO_PROXY));
+    rb_define_const(mWinhttp, "ACCESS_NAMED",     UINT2NUM(WINHTTP_ACCESS_TYPE_NAMED_PROXY));
+
+    /* Redirect-policy constants. */
+    rb_define_const(mWinhttp, "REDIRECT_DISALLOW_HTTPS_TO_HTTP",
+                    UINT2NUM(WINHTTP_OPTION_REDIRECT_POLICY_DISALLOW_HTTPS_TO_HTTP));
+    rb_define_const(mWinhttp, "REDIRECT_NEVER",
+                    UINT2NUM(WINHTTP_OPTION_REDIRECT_POLICY_NEVER));
+
+    /* Module pump + introspection primitives. */
+    rb_define_module_function(mWinhttp, "_pump_wait", pump_wait, 0);
+    rb_define_module_function(mWinhttp, "_pump_drain", pump_drain, 0);
+    rb_define_module_function(mWinhttp, "_live_count", live_count, 0);
+    rb_define_module_function(mWinhttp, "_crack", url_crack, 1);
+    rb_define_module_function(mWinhttp, "_raise_os", raise_os, 3);
+
+    /* Session */
+    cSession = rb_define_class_under(mWinhttp, "Session", rb_cObject);
+    rb_define_alloc_func(cSession, ses_alloc);
+    rb_define_singleton_method(cSession, "_open", ses_open, -1);
+    rb_define_method(cSession, "closed?", ses_closed_p, 0);
+    rb_define_method(cSession, "_mark_closed", ses_mark_closed, 0);
+    rb_define_method(cSession, "_try_close_handle", ses_try_close_handle, 0);
+    rb_define_method(cSession, "_live", ses_live_count, 0);
+    rb_define_method(cSession, "_start", req_start, 9);
+
+    /* Request — internal plumbing; all methods underscore-named. */
+    cRequest = rb_define_class_under(mWinhttp, "Request", rb_cObject);
+    rb_define_alloc_func(cRequest, req_alloc);
+    rb_define_method(cRequest, "_send", req_send, 0);
+    rb_define_method(cRequest, "_receive", req_receive, 0);
+    rb_define_method(cRequest, "_read_start", req_read_start, 0);
+    rb_define_method(cRequest, "_read_take", req_read_take, 1);
+    rb_define_method(cRequest, "_headers", req_headers, 0);
+    rb_define_method(cRequest, "_abort", req_abort, 0);
+    rb_define_method(cRequest, "_finish", req_abort, 0); /* same idempotent close */
+
+    /* Process-lifetime globals (NEVER destroyed; immortal-handle precedent). */
+    InitializeCriticalSection(&g_cs);
+    g_event = CreateEventW(NULL, FALSE, FALSE, NULL); /* auto-reset, unnamed */
+    g_head = g_tail = NULL;
+    g_dropped = 0;
+    g_reqs = st_init_numtable();
+}