@gjsify/http-soup-bridge 0.3.21 → 0.4.3

package/package.json

@@ -1,60 +1,60 @@
 {
-  "name": "@gjsify/http-soup-bridge",
-  "version": "0.3.21",
-  "description": "Vala-based main-thread bridge for libsoup HTTP server. Marshals SoupServer + SoupServerMessage signals onto the GLib main context and keeps every libsoup boxed type (MessageBody, MessageHeaders, the message's GMainContext ref, the HTTP1 IO GSource) on the C side, so SpiderMonkey GC has no chance to race a libsoup-side cleanup. Used by @gjsify/http to keep MCP/SSE/long-poll workloads stable on GJS.",
-  "type": "module",
-  "main": "lib/esm/index.js",
-  "module": "lib/esm/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/esm/index.js"
+    "name": "@gjsify/http-soup-bridge",
+    "version": "0.4.3",
+    "description": "Vala-based main-thread bridge for libsoup HTTP server. Marshals SoupServer + SoupServerMessage signals onto the GLib main context and keeps every libsoup boxed type (MessageBody, MessageHeaders, the message's GMainContext ref, the HTTP1 IO GSource) on the C side, so SpiderMonkey GC has no chance to race a libsoup-side cleanup. Used by @gjsify/http to keep MCP/SSE/long-poll workloads stable on GJS.",
+    "type": "module",
+    "main": "lib/esm/index.js",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        }
+    },
+    "files": [
+        "lib",
+        "prebuilds",
+        "meson.build",
+        "src/vala"
+    ],
+    "gjsify": {
+        "prebuilds": "prebuilds"
+    },
+    "scripts": {
+        "clear": "rm -rf lib build tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo || exit 0",
+        "check": "tsc --noEmit",
+        "init:meson": "meson setup build .",
+        "init:meson:wipe": "gjsify run init:meson --wipe",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/ts/**/*.{ts,js}'",
+        "build:meson": "gjsify run init:meson && meson compile -C build",
+        "build:types": "tsc",
+        "build:gir-types": "ts-for-gir generate --externalDeps --allowMissingDeps --girDirectories=./prebuilds/linux-x86_64 --girDirectories=/usr/share/gir-1.0 --modules=GjsifyHttpSoupBridge-1.0 --outdir=src/ts --npmScope=@girs --package=false --ignoreVersionConflicts=true",
+        "build:prebuilds": "gjsify run build:meson && mkdir -p prebuilds/linux-x86_64 && cp build/libgjsifyhttpsoupbridge.so build/GjsifyHttpSoupBridge-1.0.gir build/GjsifyHttpSoupBridge-1.0.typelib prebuilds/linux-x86_64/"
+    },
+    "keywords": [
+        "gjs",
+        "http",
+        "server",
+        "libsoup",
+        "soup",
+        "vala",
+        "native",
+        "sse",
+        "long-poll"
+    ],
+    "dependencies": {
+        "@girs/gio-2.0": "2.88.0-4.0.0-rc.15",
+        "@girs/gjs": "4.0.0-rc.15",
+        "@girs/glib-2.0": "2.88.0-4.0.0-rc.15",
+        "@girs/gobject-2.0": "2.88.0-4.0.0-rc.15",
+        "@girs/soup-3.0": "3.6.6-4.0.0-rc.15"
+    },
+    "devDependencies": {
+        "@gjsify/cli": "workspace:^",
+        "@ts-for-gir/cli": "^4.0.0-rc.15",
+        "@types/node": "^25.6.2",
+        "typescript": "^6.0.3"
     }
-  },
-  "files": [
-    "lib",
-    "prebuilds",
-    "meson.build",
-    "src/vala"
-  ],
-  "gjsify": {
-    "prebuilds": "prebuilds"
-  },
-  "scripts": {
-    "clear": "rm -rf lib build tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo || exit 0",
-    "check": "tsc --noEmit",
-    "init:meson": "meson setup build .",
-    "init:meson:wipe": "yarn init:meson --wipe",
-    "build": "yarn build:gjsify && yarn build:types",
-    "build:gjsify": "gjsify build --library 'src/ts/**/*.{ts,js}'",
-    "build:meson": "yarn init:meson && meson compile -C build",
-    "build:types": "tsc",
-    "build:gir-types": "ts-for-gir generate --externalDeps --allowMissingDeps --girDirectories=./prebuilds/linux-x86_64 --girDirectories=/usr/share/gir-1.0 --modules=GjsifyHttpSoupBridge-1.0 --outdir=src/ts --npmScope=@girs --package=false --ignoreVersionConflicts=true",
-    "build:prebuilds": "yarn build:meson && mkdir -p prebuilds/linux-x86_64 && cp build/libgjsifyhttpsoupbridge.so build/GjsifyHttpSoupBridge-1.0.gir build/GjsifyHttpSoupBridge-1.0.typelib prebuilds/linux-x86_64/"
-  },
-  "keywords": [
-    "gjs",
-    "http",
-    "server",
-    "libsoup",
-    "soup",
-    "vala",
-    "native",
-    "sse",
-    "long-poll"
-  ],
-  "dependencies": {
-    "@girs/gio-2.0": "2.88.0-4.0.0-rc.14",
-    "@girs/gjs": "4.0.0-rc.14",
-    "@girs/glib-2.0": "2.88.0-4.0.0-rc.14",
-    "@girs/gobject-2.0": "2.88.0-4.0.0-rc.14",
-    "@girs/soup-3.0": "3.6.6-4.0.0-rc.14"
-  },
-  "devDependencies": {
-    "@gjsify/cli": "^0.3.21",
-    "@ts-for-gir/cli": "^4.0.0-rc.14",
-    "@types/node": "^25.6.2",
-    "typescript": "^6.0.3"
-  }
-}
+}

package/src/vala/peer-close-watch.vala

@@ -0,0 +1,123 @@
+/*
+ * PeerCloseWatch — detect peer-side TCP half-close while a SoupServerMessage
+ * is paused.
+ *
+ * libsoup destroys its input-polling source on `soup_server_message_pause()`
+ * (see refs/libsoup/libsoup/server/http1/soup-server-message-io-http1.c:32,
+ * 80–84, 1005–1010), so the `'disconnected'` signal never fires for clients
+ * that hang up while we're holding a long-poll/SSE response open. From JS
+ * we couldn't fix this: `Gio.Socket.condition_check(HUP|ERR)` only fires on
+ * bilateral close, and `Gio.Socket.receive_message(MSG_PEEK)` is not
+ * introspectable. From C/Vala both APIs are first-class.
+ *
+ * What this watcher does on each tick:
+ *   1. Wait for `G_IO_IN | G_IO_HUP | G_IO_ERR` on the underlying GSocket.
+ *   2. If HUP/ERR fires → peer fully closed, emit `peer_gone()` and exit.
+ *   3. If IN fires → peer either sent data (legitimate next request on a
+ *      keep-alive connection) or closed their write side. We disambiguate
+ *      with a non-blocking 0-byte `g_socket_receive_message(MSG_PEEK)` —
+ *      a return of 0 is EOF, > 0 is buffered data we leave for libsoup.
+ *
+ * The watcher is owned by a Request bridge instance (see request.vala).
+ * Source attachment / removal is bookkept here so the JS side never sees
+ * a GLib.Source — the typelib only exposes the watcher class itself.
+ */
+namespace GjsifyHttpSoupBridge {
+
+    internal class PeerCloseWatch : GLib.Object {
+
+        /** Fires once on the main context when peer-side EOF / HUP is detected. */
+        public signal void peer_gone();
+
+        private GLib.Socket _socket;
+        private GLib.Source? _source;
+        private bool _emitted = false;
+
+        public PeerCloseWatch(GLib.Socket socket) {
+            _socket = socket;
+        }
+
+        /** Begin watching. Idempotent. No-op once peer_gone has fired. */
+        public void start() {
+            if (_source != null || _emitted)
+                return;
+
+            // GLib.IOCondition.IN catches the half-close case (POLLIN with 0
+            // bytes available = EOF). HUP/ERR catch the bilateral-close /
+            // socket-error case.
+            _source = _socket.create_source(
+                GLib.IOCondition.IN | GLib.IOCondition.HUP | GLib.IOCondition.ERR,
+                null
+            );
+            _source.set_callback(() => on_condition());
+            _source.attach(GLib.MainContext.@default());
+        }
+
+        /** Stop watching. Safe to call multiple times. */
+        public void stop() {
+            if (_source != null) {
+                _source.destroy();
+                _source = null;
+            }
+        }
+
+        private bool on_condition() {
+            if (_emitted)
+                return GLib.Source.REMOVE;
+
+            // HUP / ERR → unambiguous peer-close.
+            var cond = _socket.condition_check(
+                GLib.IOCondition.HUP | GLib.IOCondition.ERR
+            );
+            if ((cond & (GLib.IOCondition.HUP | GLib.IOCondition.ERR)) != 0) {
+                fire_peer_gone();
+                return GLib.Source.REMOVE;
+            }
+
+            // IN bit set. Probe with a 1-byte MSG_PEEK to disambiguate
+            // "peer-half-closed" (recv returns 0) from "data buffered"
+            // (recv returns > 0). MSG_PEEK does not consume bytes, so any
+            // legitimate buffered data is still available to libsoup.
+            uint8 buf[1] = {};
+            var vec = GLib.InputVector();
+            vec.buffer = buf;
+            vec.size = 1;
+            GLib.InputVector[] vecs = { vec };
+            int flags = (int)GLib.SocketMsgFlags.PEEK;
+            try {
+                GLib.SocketAddress? src_addr;
+                GLib.SocketControlMessage[]? msgs;
+                ssize_t n = _socket.receive_message(
+                    out src_addr, vecs, out msgs, ref flags, null
+                );
+                if (n == 0) {
+                    fire_peer_gone();
+                    return GLib.Source.REMOVE;
+                }
+                // n > 0 → real data, peer alive. Stay armed.
+                return GLib.Source.CONTINUE;
+            } catch (GLib.IOError.WOULD_BLOCK e) {
+                // Spurious wake-up — keep watching.
+                return GLib.Source.CONTINUE;
+            } catch (GLib.Error e) {
+                // Any other error: treat as peer-gone defensively.
+                fire_peer_gone();
+                return GLib.Source.REMOVE;
+            }
+        }
+
+        private void fire_peer_gone() {
+            if (_emitted)
+                return;
+            _emitted = true;
+            // Hop through Idle.add so that the signal is emitted *after*
+            // any libsoup callback that may already be running on this
+            // mainloop iteration finishes — never re-enter Soup IO from
+            // a half-completed callback.
+            GLib.Idle.add(() => {
+                this.peer_gone();
+                return GLib.Source.REMOVE;
+            });
+        }
+    }
+}

package/src/vala/request.vala

@@ -0,0 +1,169 @@
+/*
+ * Request — read-side snapshot of one in-flight Soup.ServerMessage.
+ *
+ * Properties (method, url, headers, body, remote_address, remote_port) are
+ * captured at construction time from the SoupServerMessage. Body bytes are
+ * pulled from `Soup.ServerMessage.get_request_body()` and copied so JS
+ * never holds a reference to the live SoupMessageBody (a refcounted boxed
+ * type implicated in the GJS GC race we're working around).
+ *
+ * `aborted` flips to true and `aborted_signal` fires when:
+ *   * Soup emits 'disconnected' on the underlying message, OR
+ *   * the PeerCloseWatch helper detects a peer half-close on a paused
+ *     long-poll message (the only way we get reliable peer-close
+ *     detection on libsoup-paused messages, see peer-close-watch.vala).
+ *
+ * JS API (visible via the typelib):
+ *   property method   : string
+ *   property url      : string
+ *   property remote_address : string
+ *   property remote_port    : uint
+ *   property header_pairs   : string[]   // [name, value, name, value, …]
+ *   property body           : uint8[]
+ *   property aborted        : bool
+ *   signal   aborted_signal()
+ *   signal   close()
+ */
+namespace GjsifyHttpSoupBridge {
+
+    public class Request : GLib.Object {
+
+        public string  method          { get; private set; default = ""; }
+        public string  url             { get; private set; default = ""; }
+        public string  remote_address  { get; private set; default = ""; }
+        public uint    remote_port     { get; private set; default = 0; }
+        public string[] header_pairs   { get; private set; default = new string[0]; }
+        public bool     aborted        { get; private set; default = false; }
+
+        // Body bytes are exposed as a method (not a property) because
+        // GIR-marshalled `uint8[]` properties round-trip through `weak`
+        // references that get cleared by the time JS reads them. A method
+        // returning `(transfer full)` is the only shape we've found that
+        // reliably hands the bytes to JS.
+        private uint8[] _body = new uint8[0];
+        public uint8[] get_body() {
+            var copy = new uint8[_body.length];
+            GLib.Memory.copy(copy, _body, _body.length);
+            return (owned)copy;
+        }
+
+        public signal void aborted_signal();
+        public signal void close();
+
+        // ---- Internal state ---------------------------------------------
+
+        private Soup.ServerMessage _msg;
+        private PeerCloseWatch? _watch;
+        private ulong _disconnected_handler = 0;
+        private ulong _finished_handler = 0;
+
+        internal Request(Soup.ServerMessage msg) {
+            _msg = msg;
+
+            method = msg.get_method();
+
+            unowned GLib.Uri? uri = msg.get_uri();
+            if (uri != null) {
+                url = uri.get_path();
+                var query = uri.get_query();
+                if (query != null && query.length > 0) {
+                    url = url + "?" + query;
+                }
+            }
+
+            var remote_host = msg.get_remote_host();
+            if (remote_host != null) remote_address = remote_host;
+
+            var remote = msg.get_remote_address() as GLib.InetSocketAddress;
+            if (remote != null) remote_port = remote.get_port();
+
+            // Flatten request headers into [name, value, name, value, …].
+            // This is the JS-friendliest shape for headers — avoids exposing
+            // SoupMessageHeaders boxed handles.
+            var pairs = new GLib.GenericArray<string>();
+            unowned Soup.MessageHeaders req_hdrs = msg.get_request_headers();
+            req_hdrs.foreach((name, value) => {
+                pairs.add(name);
+                pairs.add(value);
+            });
+            var arr = new string[pairs.length];
+            for (uint i = 0; i < pairs.length; i++) arr[i] = pairs[i];
+            header_pairs = arr;
+
+            // Snapshot the request body. Soup buffers it for us before
+            // dispatching the handler (`add_handler` fires after `got-body`).
+            // We deep-copy the bytes so JS never holds a SoupMessageBody
+            // handle and so the buffer survives Soup's per-message tear-down.
+            unowned Soup.MessageBody req_body = msg.get_request_body();
+            unowned uint8[] raw = req_body.data;
+            if (raw.length > 0) {
+                var copy = new uint8[raw.length];
+                GLib.Memory.copy(copy, raw, raw.length);
+                _body = (owned)copy;
+            }
+
+            // Wire the unambiguous peer-close path: Soup's 'disconnected'
+            // signal. This fires reliably while Soup is actively reading
+            // (i.e. before the handler pauses the message).
+            _disconnected_handler = _msg.disconnected.connect(() => {
+                fire_aborted();
+            });
+
+            _finished_handler = _msg.finished.connect(() => {
+                fire_close();
+            });
+
+            // Also arm the peer-close watch so we get half-close detection
+            // while the response is paused (long-poll / SSE). The watcher
+            // does the MSG_PEEK probing C-side so we never expose a
+            // GLib.Source to JS.
+            var sock = _msg.get_socket();
+            if (sock != null) {
+                _watch = new PeerCloseWatch(sock);
+                _watch.peer_gone.connect(() => {
+                    fire_aborted();
+                });
+                _watch.start();
+            }
+        }
+
+        // ---- Internal helpers -------------------------------------------
+
+        private bool _aborted_fired = false;
+        private void fire_aborted() {
+            if (_aborted_fired) return;
+            _aborted_fired = true;
+            aborted = true;
+            stop_watch();
+            GLib.Idle.add(() => {
+                this.aborted_signal();
+                this.close();
+                return GLib.Source.REMOVE;
+            });
+        }
+
+        private bool _close_fired = false;
+        private void fire_close() {
+            if (_close_fired) return;
+            _close_fired = true;
+            stop_watch();
+            disconnect_handlers();
+            GLib.Idle.add(() => {
+                this.close();
+                return GLib.Source.REMOVE;
+            });
+        }
+
+        private void stop_watch() {
+            if (_watch != null) {
+                _watch.stop();
+                _watch = null;
+            }
+        }
+
+        private void disconnect_handlers() {
+            if (_disconnected_handler != 0) { _msg.disconnect(_disconnected_handler); _disconnected_handler = 0; }
+            if (_finished_handler != 0)    { _msg.disconnect(_finished_handler);    _finished_handler = 0;    }
+        }
+    }
+}

package/src/vala/response.vala

@@ -0,0 +1,276 @@
+/*
+ * Response — write side of one in-flight Soup.ServerMessage.
+ *
+ * Owns the SoupServerMessage privately. Keeps every libsoup boxed type
+ * (MessageBody, MessageHeaders, Encoding, the message's HTTP1-IO GMain
+ * Context ref) on the C side so SpiderMonkey GC has nothing to race
+ * against.
+ *
+ * Replaces the JS-side `SoupMessageLifecycle.ts` machinery from
+ * @gjsify/http: `'wrote-chunk'`-tracked re-unpause, `'finished'` /
+ * `'disconnected'` signal handling, GC guard, peer-close-driven cleanup —
+ * everything moves into this class.
+ *
+ * JS API (visible via the typelib):
+ *   set_header / append_header / remove_header / get_header / header_names
+ *   write_head(code, reason)             — flush headers
+ *   write_chunk(bytes) -> bool           — false if already aborted
+ *   end()                                — finish chunked or batch mode
+ *   end_with(bytes)                      — convenience: write + end
+ *   abort()                              — server-side cancel
+ *   signal close()                       — fired once on terminal state
+ *   signal drain()                       — fired when Soup auto-pause clears
+ *
+ * Internal state-machine:
+ *   IDLE → STREAMING (after first write_chunk or write_head with body)
+ *   IDLE → BATCH     (after end() with no prior chunk → set_response)
+ *   *    → FINISHED  (Soup 'finished' signal)
+ *   *    → ABORTED   (peer-close or abort() call)
+ */
+namespace GjsifyHttpSoupBridge {
+
+    public class Response : GLib.Object {
+
+        public uint   status_code    { get; set; default = 200; }
+        public string status_message { get; set; default = ""; }
+        public bool   headers_sent   { get; private set; default = false; }
+        public bool   finished       { get; private set; default = false; }
+        public bool   aborted        { get; private set; default = false; }
+
+        /** Fires once on the main context when the response reaches a terminal state. */
+        public signal void close();
+
+        /** Fires when libsoup auto-pause clears (backpressure relieved). */
+        public signal void drain();
+
+        // ---- Internal state ----------------------------------------------
+
+        private Soup.ServerMessage _msg;
+        private GLib.HashTable<string, GLib.GenericArray<string>> _headers;
+        private bool _streaming = false;
+        private bool _needs_unpause = false;
+
+        private ulong _wrote_chunk_handler = 0;
+        private ulong _disconnected_handler = 0;
+        private ulong _finished_handler = 0;
+
+        // ---- Construction / wiring ---------------------------------------
+
+        internal Response(Soup.ServerMessage msg) {
+            _msg = msg;
+            _headers = new GLib.HashTable<string, GLib.GenericArray<string>>(
+                GLib.str_hash, GLib.str_equal
+            );
+
+            // 'wrote-chunk' fires synchronously inside Soup's HTTP1 IO loop
+            // right before the auto-pause. By the time we resume in
+            // write_chunk()/end(), pause_count is back at 1 and a single
+            // unpause() is both safe and necessary.
+            _wrote_chunk_handler = _msg.wrote_chunk.connect(() => {
+                _needs_unpause = true;
+                // Re-emit on the main context so JS subscribers always see
+                // 'drain' from the GLib default context (never from Soup's
+                // streaming-callback context).
+                GLib.Idle.add(() => {
+                    this.drain();
+                    return GLib.Source.REMOVE;
+                });
+            });
+
+            // 'disconnected' is reliable while Soup is actively reading; for
+            // paused long-polls the Request side runs a PeerCloseWatch and
+            // calls our `abort()` on its own.
+            _disconnected_handler = _msg.disconnected.connect(() => {
+                fire_terminal(true);
+            });
+
+            _finished_handler = _msg.finished.connect(() => {
+                fire_terminal(false);
+            });
+        }
+
+        // ---- Header API --------------------------------------------------
+
+        public void set_header(string name, string value) {
+            var lower = name.down();
+            var arr = new GLib.GenericArray<string>();
+            arr.add(value);
+            _headers.replace(lower, arr);
+        }
+
+        public void append_header(string name, string value) {
+            var lower = name.down();
+            var arr = _headers.lookup(lower);
+            if (arr == null) {
+                arr = new GLib.GenericArray<string>();
+                _headers.replace(lower, arr);
+            }
+            arr.add(value);
+        }
+
+        public void remove_header(string name) {
+            _headers.remove(name.down());
+        }
+
+        public string? get_header(string name) {
+            var arr = _headers.lookup(name.down());
+            if (arr == null || arr.length == 0) return null;
+            return arr[0];
+        }
+
+        public string[] header_names() {
+            var keys = _headers.get_keys_as_array();
+            var result = new string[keys.length];
+            for (int i = 0; i < keys.length; i++) result[i] = keys[i];
+            return result;
+        }
+
+        // ---- Write side --------------------------------------------------
+
+        /**
+         * Flush status + headers and switch into chunked-streaming mode.
+         * Idempotent — only fires once.
+         */
+        public void write_head(uint code, string? reason) {
+            if (headers_sent || aborted) return;
+            status_code = code;
+            if (reason != null) status_message = reason;
+            start_streaming();
+        }
+
+        /**
+         * Append a body chunk. Returns false if the response is already
+         * terminal (so JS callers can stop pumping).
+         */
+        public bool write_chunk(uint8[] chunk) {
+            if (aborted || finished) return false;
+            if (!_streaming) start_streaming();
+
+            _msg.get_response_body().append_bytes(new GLib.Bytes(chunk));
+
+            // After Soup's HTTP1 IO writes a chunk it auto-pauses
+            // (refs/libsoup/libsoup/server/http1/soup-server-message-io-http1.c
+            // :32, 80–84, 1005–1010). The 'wrote-chunk' signal sets the
+            // ticket; if it's set we owe libsoup an unpause so the *next*
+            // chunk we appended just now actually gets written.
+            if (_needs_unpause) {
+                _needs_unpause = false;
+                _msg.unpause();
+            }
+            return true;
+        }
+
+        /**
+         * Finish the response. In streaming mode this calls
+         * `Soup.MessageBody.complete()` so libsoup writes the chunked
+         * terminator. In batch mode (no prior write_chunk) it calls
+         * `Soup.ServerMessage.set_response()` to produce a fixed-length
+         * empty body.
+         */
+        public void end() {
+            if (finished || aborted) return;
+
+            if (_streaming) {
+                _msg.get_response_body().complete();
+                if (_needs_unpause) {
+                    _needs_unpause = false;
+                    _msg.unpause();
+                }
+            } else {
+                send_batch();
+            }
+            finished = true;
+        }
+
+        public void end_with(uint8[] chunk) {
+            if (write_chunk(chunk)) end();
+        }
+
+        public void abort() {
+            if (aborted) return;
+            aborted = true;
+            fire_terminal(true);
+        }
+
+        // ---- Internal helpers --------------------------------------------
+
+        private void start_streaming() {
+            if (_streaming) return;
+            _streaming = true;
+            headers_sent = true;
+
+            _msg.set_status(status_code, status_message != "" ? status_message : null);
+
+            var hdrs = _msg.get_response_headers();
+
+            // Transfer-encoding selection mirrors @gjsify/http's previous
+            // behaviour: CONTENT_LENGTH wins if the caller set one
+            // explicitly, CHUNKED otherwise.
+            if (_headers.contains("content-length")) {
+                hdrs.set_encoding(Soup.Encoding.CONTENT_LENGTH);
+            } else {
+                hdrs.set_encoding(Soup.Encoding.CHUNKED);
+            }
+
+            if (!_headers.contains("connection")) {
+                hdrs.replace("Connection", "close");
+            }
+
+            _headers.foreach((k, vs) => {
+                for (uint i = 0; i < vs.length; i++) {
+                    if (i == 0) hdrs.replace(k, vs[i]);
+                    else hdrs.append(k, vs[i]);
+                }
+            });
+
+            _msg.unpause();
+        }
+
+        private void send_batch() {
+            if (headers_sent) return;
+            headers_sent = true;
+
+            _msg.set_status(status_code, status_message != "" ? status_message : null);
+
+            var hdrs = _msg.get_response_headers();
+
+            if (!_headers.contains("connection")) {
+                hdrs.replace("Connection", "close");
+            }
+
+            _headers.foreach((k, vs) => {
+                for (uint i = 0; i < vs.length; i++) {
+                    if (i == 0) hdrs.replace(k, vs[i]);
+                    else hdrs.append(k, vs[i]);
+                }
+            });
+
+            string content_type = "text/plain";
+            var ct_arr = _headers.lookup("content-type");
+            if (ct_arr != null && ct_arr.length > 0) content_type = ct_arr[0];
+
+            uint8[] empty = new uint8[0];
+            _msg.set_response(content_type, Soup.MemoryUse.COPY, empty);
+            _msg.unpause();
+        }
+
+        private bool _terminal_fired = false;
+        private void fire_terminal(bool became_aborted) {
+            if (_terminal_fired) return;
+            _terminal_fired = true;
+            if (became_aborted) aborted = true;
+            finished = true;
+
+            // Disconnect signal handlers so libsoup's own message tear-down
+            // doesn't re-enter our class on a recycled signal ID.
+            if (_wrote_chunk_handler != 0) { _msg.disconnect(_wrote_chunk_handler); _wrote_chunk_handler = 0; }
+            if (_disconnected_handler != 0) { _msg.disconnect(_disconnected_handler); _disconnected_handler = 0; }
+            if (_finished_handler != 0)    { _msg.disconnect(_finished_handler);    _finished_handler = 0;    }
+
+            GLib.Idle.add(() => {
+                this.close();
+                return GLib.Source.REMOVE;
+            });
+        }
+    }
+}

package/src/vala/server.vala

@@ -0,0 +1,120 @@
+/*
+ * Server — wraps Soup.Server with a JS-safe signal-based API.
+ *
+ * The class owns the SoupServer privately. JS callers see only:
+ *   listen(port, hostname) -> bool
+ *   close()
+ *   property port           : uint
+ *   property address        : string
+ *   property listening      : bool
+ *   property soup_server    : Soup.Server   // for ws-upgrade callers
+ *   signal   request_received(Request, Response)
+ *   signal   upgrade(Request, GLib.IOStream, GLib.Bytes)
+ *   signal   error_occurred(string)
+ *
+ * The `soup_server` property is exposed read-only because @gjsify/ws's
+ * WebSocketServer needs to call `add_websocket_handler` on the same
+ * underlying Soup.Server (port-sharing). Soup.Server *itself* is a
+ * GObject (not a Boxed), so exposing it doesn't reintroduce the
+ * Boxed-Source GC race the bridge fixes — the race was specifically
+ * about boxed types like SoupMessageBody / SoupMessageHeaders / the
+ * implicit GLib.Source ref, none of which leak through this surface.
+ */
+namespace GjsifyHttpSoupBridge {
+
+    public class Server : GLib.Object {
+
+        public uint    port      { get; private set; default = 0; }
+        public string  address   { get; private set; default = ""; }
+        public bool    listening { get; private set; default = false; }
+
+        /** Underlying Soup.Server, exposed so @gjsify/ws can share the port. */
+        public Soup.Server soup_server { get; private set; }
+
+        public signal void request_received(Request req, Response res);
+        public signal void upgrade(Request req, GLib.IOStream iostream, GLib.Bytes head);
+        public signal void error_occurred(string message);
+
+        construct {
+            // Soup.Server's constructor is the GObject varargs form
+            // `Server(string optname1, ...)`. We use the property-bag form
+            // via GObject.Object.new() with a zero-property list, which
+            // round-trips to `g_object_new(SOUP_TYPE_SERVER, NULL)`.
+            soup_server = (Soup.Server) GLib.Object.new(typeof(Soup.Server));
+            // ServerCallback signature: (Server, ServerMessage, path, query?)
+            soup_server.add_handler(null, (server, msg, path, query) => {
+                handle_message(msg);
+            });
+        }
+
+        public void listen(uint port_arg, string hostname) throws GLib.Error {
+            soup_server.listen_local(port_arg, Soup.ServerListenOptions.IPV4_ONLY);
+            var listeners = soup_server.get_listeners();
+            if (listeners != null && listeners.length() > 0) {
+                var laddr = listeners.nth_data(0).get_local_address() as GLib.InetSocketAddress;
+                if (laddr != null) {
+                    port = laddr.get_port();
+                } else {
+                    port = port_arg;
+                }
+            } else {
+                port = port_arg;
+            }
+            address = hostname;
+            listening = true;
+        }
+
+        public void close() {
+            if (!listening) return;
+            soup_server.disconnect();
+            listening = false;
+        }
+
+        // ---- Per-request dispatch ---------------------------------------
+
+        private void handle_message(Soup.ServerMessage msg) {
+            // Detect WebSocket upgrade BEFORE pausing the message, so
+            // steal_connection() returns a usable IOStream. We mirror
+            // @gjsify/http's existing logic here so consumers can keep
+            // using `Server.on('upgrade', …)` unchanged.
+            unowned Soup.MessageHeaders req_hdrs = msg.get_request_headers();
+            string? conn = req_hdrs.get_one("Connection");
+            string? upg  = req_hdrs.get_one("Upgrade");
+            bool is_upgrade = conn != null && conn.down().contains("upgrade") && upg != null;
+
+            if (is_upgrade) {
+                // Build a Request snapshot for the upgrade event but skip
+                // creating a Response (libsoup will discard any response
+                // we'd write after steal_connection).
+                var req = new Request(msg);
+                GLib.IOStream? io = null;
+                try {
+                    io = msg.steal_connection();
+                } catch (GLib.Error e) {
+                    error_occurred(e.message);
+                    return;
+                }
+                if (io != null) {
+                    var head = new GLib.Bytes(new uint8[0]);
+                    GLib.Idle.add(() => {
+                        this.upgrade(req, io, head);
+                        return GLib.Source.REMOVE;
+                    });
+                }
+                return;
+            }
+
+            // Non-upgrade path: pause Soup so the JS handler can take its
+            // time before unpause()-ing through Response.write_chunk/end.
+            msg.pause();
+
+            var req = new Request(msg);
+            var res = new Response(msg);
+
+            GLib.Idle.add(() => {
+                this.request_received(req, res);
+                return GLib.Source.REMOVE;
+            });
+        }
+    }
+}