Fix server destroy lifecycle race

[ViktorJannicke]

Summary

Fix crashes, use-after-free races, and shutdown deadlocks when a WebUI window is destroyed while its server, callbacks, WebSocket work, WebView work, or show operations are still active.

This introduces coordinated two-phase destruction: new work is rejected immediately, while final memory reclamation waits until every owner of the window and its CivetWeb connections has retired.

Motivation

We recently started using WebUI in a project and, while integrating it more deeply, began exercising window and server lifecycle paths beyond the basic examples. This exposed reproducible crashes when destroying a window from a callback and during repeated server teardown.

Investigating those crashes required following ownership across WebUI’s window state, server threads, callbacks, and the embedded CivetWeb connection storage. The resulting diff is larger than the visible fix might suggest because the affected lifetime rules were spread across several teardown paths. This change consolidates those rules so destruction consistently stops new work, waits for active work to retire, and only then releases the underlying state.

Problem

webui_destroy() could free window state while it was still referenced by:

• The server thread during startup or shutdown
• User callbacks, including file-handler callbacks
• Detached WebSocket and asynchronous-response work
• WebView worker threads
• Concurrent webui_show*() or webui_start_server() calls
• Folder-monitor threads

Destroying a window from one of its own callbacks was especially unsafe. Waiting synchronously would deadlock because CivetWeb was waiting for that callback to return, while freeing immediately caused use-after-free crashes.

CivetWeb also needed a way to stop accepting new work and interrupt blocked connection I/O without immediately joining workers and freeing connection storage still referenced by WebUI tasks.

Changes

Window lifecycle

• Split destruction into request and finalization phases.
• Track the complete server-thread lifetime, including startup and cleanup.
• Track active callbacks, detached tasks, WebView work, and public show calls.
• Stop admitting new work as soon as destruction begins.
• Defer callback-triggered destruction until the callback and server retire.
• Make concurrent webui_destroy() calls wait on the global window registry instead of touching potentially reclaimed per-window synchronization objects.
• Prevent reusing a window ID until the previous generation has been fully finalized.
• Correct the window ID upper-bound check to reject WEBUI_MAX_IDS.

Show and global cleanup coordination

• Retain windows for the full duration of webui_show*() and webui_start_server().
• Prevent new show calls once global cleanup begins.
• Make webui_clean() wait for both server threads and show operations.
• When webui_clean() is called from a WebUI callback, request application exit and defer process-wide reclamation until the callback has returned.
• Cancel asynchronous waits when their window begins stopping.

webui_start_server() result lifetime

• Store returned server URLs per window.
• Starting another window no longer overwrites an earlier returned URL.
• Returned URLs remain valid across the originating thread exiting and across window destruction, until the same window result is replaced or WebUI is cleaned.

Worker and monitor shutdown

• Account for detached WebSocket and WebView work before reclaiming window state.
• Replace forced folder-monitor cancellation with cooperative, bounded polling on Windows, Linux, and macOS.
• Interrupt blocked CivetWeb connection I/O so retained tasks can finish during shutdown.
• Use CivetWeb’s per-connection write serialization instead of a global WebUI send lock.

Vendored CivetWeb carry patch

Add a WebUI-private quiesce operation that:

• Rejects newly accepted sockets without freeing the server context.
• Prevents dynamic workers from being published after quiescing begins.
• Closes queued sockets and interrupts active worker connections.
• Keeps worker connection storage alive until WebUI tasks have retired.
• Synchronizes socket scanning with worker close and descriptor invalidation.
• Initializes idle worker sockets to INVALID_SOCKET.
• Transfers alternative-queue socket ownership without leaving stale descriptor copies.

The extension is private to WebUI and is not added to CivetWeb’s public API.

Compatibility

• No WebUI public function signatures changed.
• No new public CivetWeb APIs were introduced.
• Existing C and C++ consuming code remains source-compatible.
• webui_start_server() now provides safer returned-string storage.
• Destruction from callbacks and concurrent lifecycle operations are now handled safely.

Verification

Verified on Linux with:

• Full CMake release build, including examples
• GCC release and debug builds
• Clang GNU99 syntax checks
• Default and ALTERNATIVE_QUEUE CivetWeb configurations
• AddressSanitizer and UndefinedBehaviorSanitizer
• Repeated create/show/destroy lifecycle stress
• Destruction from normal, file-handler, and asynchronous callbacks
• Concurrent show/destroy, show/clean, and repeated destroy calls
• Folder-monitor shutdown
• Same-ID rejection while an older generation retires
• webui_start_server() URL lifetime across destruction and thread exit
• Repeated stop and file-descriptor-zero safety checks

[AlbertShown]

Thank you @ViktorJannicke for this important PR. I can reproduce the issue you reported on Linux using the code below:

void backend(webui_event_t* e) {
	webui_destroy(e->window);
}

int main() {
	size_t win = webui_new_window();
	webui_bind(win, "backend", backend);
	webui_show(win, "<html><head><script src=\"webui.js\"></script></head> <button onclick=\"backend()\">Call Backend</button> </html>");
	webui_wait();
	return 0;
}

The recent days I was working on a new test design where the window server thread stays alive until the window is explicitly destroyed or when the app exits, instead of the current design where the server thread stops by a simple window close event. I believe the new design will make things simpler and safer. Please let me finish the new design first and fix the crash you reported.

If the new design internal tests did not go well, I will switch to your PR, but we should avoid changing CivetWeb vendor code to allow a flawless future upgrade.

[AlbertShown]

A core re-design is done in 77cbaae and many other PRs are committed to pass the new Stress Test tool.

Please update your WebUI library and let me know if your project is now more stable.

[ViktorJannicke]

Thanks! I retested current main at 85043e9 on my NixOS Machine. The original webui_destroy()-from-callback crash is gone, my 32-cycle server destroy regression passes, and all 25 CS-WebUI native/managed tests pass ontop of latest main. The lifecycle-related Stress Test stages—concurrent create/destroy, destroy from callback, and rapid open/close—also pass.
The full Stress Test currently stops at stage 9 with Re-show on the new port failed; I can open a separate issue with details if that is not already known.
For the lifecycle issue behind #712, the new server-threading design appears to supersede the PR.

[ViktorJannicke]

Since this PR is redundant I will close it now.

[AlbertShown]

crash is gone

Happy to hear that.

I can open a separate issue with details if that is not already known

Yes, it is a known issue. It passes on Windows but fails on Linux. I will fix it soon.