Add examples for new MHD 1.0 features and document them in README

New example files:
- empty_response_example: 204 No Content and HEAD-only responses
- iovec_response_example: scatter-gather response from multiple buffers
- pipe_response_example: streaming response from a pipe fd
- websocket_echo: WebSocket echo server with on_open/on_message/on_close
- daemon_info: daemon introspection (bound port, listen fd, http_utils)
- external_event_loop: driving the server with run_wait() and quiesce()
- turbo_mode: high-performance config with turbo, suppressed date header,
  TCP Fast Open, and listen backlog

All examples are added to the Other Examples section of the README with
inline code, test commands, and links to the source files.

Author: etr

README.md

@@ -1494,6 +1494,297 @@ To test the above example, you can run the following command from a terminal:
 
 You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/deferred_with_accumulator.cpp).
 
+#### Example of an empty response (204 No Content)
+```cpp
+    #include <httpserver.hpp>
+
+    using namespace httpserver;
+
+    class no_content_resource : public http_resource {
+    public:
+        std::shared_ptr<http_response> render_DELETE(const http_request&) {
+            // Return a 204 No Content response with no body
+            return std::make_shared<empty_response>(
+                    http::http_utils::http_no_content);
+        }
+
+        std::shared_ptr<http_response> render_HEAD(const http_request&) {
+            // Return a HEAD-only response with headers but no body
+            auto response = std::make_shared<empty_response>(
+                    http::http_utils::http_ok,
+                    empty_response::HEAD_ONLY);
+            response->with_header("X-Total-Count", "42");
+            return response;
+        }
+    };
+
+    int main() {
+        webserver ws = create_webserver(8080);
+
+        no_content_resource ncr;
+        ws.register_resource("/items", &ncr);
+        ws.start(true);
+
+        return 0;
+    }
+```
+To test the above example, you can run the following commands from a terminal:
+
+    curl -XDELETE -v localhost:8080/items
+    curl -I -v localhost:8080/items
+
+You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/empty_response_example.cpp).
+
+#### Example of a scatter-gather (iovec) response
+```cpp
+    #include <httpserver.hpp>
+
+    using namespace httpserver;
+
+    class iovec_resource : public http_resource {
+    public:
+        std::shared_ptr<http_response> render_GET(const http_request&) {
+            // Build a response from multiple separate buffers without copying
+            std::vector<std::string> parts;
+            parts.push_back("{\"header\": \"value\", ");
+            parts.push_back("\"items\": [1, 2, 3], ");
+            parts.push_back("\"footer\": \"end\"}");
+
+            return std::make_shared<iovec_response>(
+                    std::move(parts), 200, "application/json");
+        }
+    };
+
+    int main() {
+        webserver ws = create_webserver(8080);
+
+        iovec_resource ir;
+        ws.register_resource("/data", &ir);
+        ws.start(true);
+
+        return 0;
+    }
+```
+To test the above example, you can run the following command from a terminal:
+
+    curl -XGET -v localhost:8080/data
+
+You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/iovec_response_example.cpp).
+
+#### Example of a pipe-based streaming response
+```cpp
+    #include <cstring>
+    #include <thread>
+    #include <unistd.h>
+    #include <httpserver.hpp>
+
+    using namespace httpserver;
+
+    class pipe_resource : public http_resource {
+    public:
+        std::shared_ptr<http_response> render_GET(const http_request&) {
+            int pipefd[2];
+            if (pipe(pipefd) == -1) {
+                return std::make_shared<string_response>("pipe failed", 500);
+            }
+
+            // Spawn a thread to write data into the pipe
+            std::thread writer([fd = pipefd[1]]() {
+                const char* messages[] = {"Hello ", "from ", "a pipe!\n"};
+                for (const char* msg : messages) {
+                    ssize_t ret = write(fd, msg, strlen(msg));
+                    (void)ret;
+                }
+                close(fd);
+            });
+            writer.detach();
+
+            // Return the read end of the pipe as the response
+            return std::make_shared<pipe_response>(pipefd[0], 200, "text/plain");
+        }
+    };
+
+    int main() {
+        webserver ws = create_webserver(8080);
+
+        pipe_resource pr;
+        ws.register_resource("/stream", &pr);
+        ws.start(true);
+
+        return 0;
+    }
+```
+To test the above example, you can run the following command from a terminal:
+
+    curl -XGET -v localhost:8080/stream
+
+You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/pipe_response_example.cpp).
+
+#### Example of a WebSocket echo server
+```cpp
+    #include <iostream>
+    #include <httpserver.hpp>
+
+    using namespace httpserver;
+
+    class echo_handler : public websocket_handler {
+    public:
+        void on_open(websocket_session& session) override {
+            std::cout << "WebSocket connection opened" << std::endl;
+            session.send_text("Welcome to the echo server!");
+        }
+
+        void on_message(websocket_session& session, const std::string& msg) override {
+            std::cout << "Received: " << msg << std::endl;
+            session.send_text("Echo: " + msg);
+        }
+
+        void on_close(websocket_session& session, uint16_t code, const std::string& reason) override {
+            std::cout << "WebSocket closed (code=" << code << ", reason=" << reason << ")" << std::endl;
+        }
+    };
+
+    int main() {
+        webserver ws = create_webserver(8080);
+
+        echo_handler handler;
+        ws.register_ws_resource("/ws", &handler);
+        ws.start(true);
+
+        return 0;
+    }
+```
+Note: WebSocket support requires libmicrohttpd 1.0.0 built with WebSocket support. You can test this with any WebSocket client library or browser JavaScript: `new WebSocket("ws://localhost:8080/ws")`.
+
+You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/websocket_echo.cpp).
+
+#### Example of daemon introspection
+```cpp
+    #include <iostream>
+    #include <httpserver.hpp>
+
+    using namespace httpserver;
+
+    class hello_resource : public http_resource {
+    public:
+        std::shared_ptr<http_response> render_GET(const http_request&) {
+            return std::make_shared<string_response>("Hello, World!");
+        }
+    };
+
+    int main() {
+        // Use port 0 to let the OS assign an ephemeral port
+        webserver ws = create_webserver(0);
+
+        hello_resource hr;
+        ws.register_resource("/hello", &hr);
+        ws.start(false);
+
+        // Query daemon information
+        std::cout << "libmicrohttpd version: "
+                  << http::http_utils::get_mhd_version() << std::endl;
+        std::cout << "Bound port: " << ws.get_bound_port() << std::endl;
+        std::cout << "Listen FD: " << ws.get_listen_fd() << std::endl;
+        std::cout << "Active connections: " << ws.get_active_connections() << std::endl;
+        std::cout << "HTTP 200 reason: "
+                  << http::http_utils::reason_phrase(200) << std::endl;
+        std::cout << "HTTP 404 reason: "
+                  << http::http_utils::reason_phrase(404) << std::endl;
+
+        ws.sweet_kill();
+        return 0;
+    }
+```
+You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/daemon_info.cpp).
+
+#### Example of an external event loop
+```cpp
+    #include <csignal>
+    #include <iostream>
+    #include <httpserver.hpp>
+
+    using namespace httpserver;
+
+    static volatile bool running = true;
+
+    void signal_handler(int) { running = false; }
+
+    class hello_resource : public http_resource {
+    public:
+        std::shared_ptr<http_response> render_GET(const http_request&) {
+            return std::make_shared<string_response>("Hello from external event loop!");
+        }
+    };
+
+    int main() {
+        signal(SIGINT, signal_handler);
+
+        webserver ws = create_webserver(8080);
+
+        hello_resource hr;
+        ws.register_resource("/hello", &hr);
+        ws.start(false);
+
+        std::cout << "Server running on port " << ws.get_bound_port() << std::endl;
+
+        // Drive the event loop externally using run_wait
+        while (running) {
+            // Block for up to 1000ms waiting for HTTP activity
+            ws.run_wait(1000);
+
+            // You can do other work here between iterations
+        }
+
+        // Graceful shutdown: stop accepting new connections first
+        ws.quiesce();
+        ws.stop();
+
+        return 0;
+    }
+```
+To test the above example, you can run the following command from a terminal:
+
+    curl -XGET -v localhost:8080/hello
+
+You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/external_event_loop.cpp).
+
+#### Example of turbo mode with performance options
+```cpp
+    #include <httpserver.hpp>
+
+    using namespace httpserver;
+
+    class hello_resource : public http_resource {
+    public:
+        std::shared_ptr<http_response> render_GET(const http_request&) {
+            return std::make_shared<string_response>("Hello, turbo world!");
+        }
+    };
+
+    int main() {
+        // Create a high-performance server with turbo mode,
+        // suppressed date headers, and a thread pool.
+        webserver ws = create_webserver(8080)
+            .start_method(http::http_utils::INTERNAL_SELECT)
+            .max_threads(4)
+            .turbo()
+            .suppress_date_header()
+            .tcp_fastopen_queue_size(16)
+            .listen_backlog(128);
+
+        hello_resource hr;
+        ws.register_resource("/hello", &hr);
+        ws.start(true);
+
+        return 0;
+    }
+```
+To test the above example, you can run the following command from a terminal:
+
+    curl -XGET -v localhost:8080/hello
+
+You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/turbo_mode.cpp).
+
 [Back to TOC](#table-of-contents)
 
 ## Copying

examples/Makefile.am

@@ -19,7 +19,7 @@
 LDADD = $(top_builddir)/src/libhttpserver.la
 AM_CPPFLAGS = -I$(top_srcdir)/src -I$(top_srcdir)/src/httpserver/
 METASOURCES = AUTO
-noinst_PROGRAMS = hello_world service minimal_hello_world custom_error allowing_disallowing_methods handlers hello_with_get_arg args_processing setting_headers custom_access_log minimal_https minimal_file_response minimal_deferred url_registration minimal_ip_ban benchmark_select benchmark_threads benchmark_nodelay deferred_with_accumulator file_upload file_upload_with_callback
+noinst_PROGRAMS = hello_world service minimal_hello_world custom_error allowing_disallowing_methods handlers hello_with_get_arg args_processing setting_headers custom_access_log minimal_https minimal_file_response minimal_deferred url_registration minimal_ip_ban benchmark_select benchmark_threads benchmark_nodelay deferred_with_accumulator file_upload file_upload_with_callback empty_response_example iovec_response_example pipe_response_example daemon_info external_event_loop turbo_mode
 
 hello_world_SOURCES = hello_world.cpp
 service_SOURCES = service.cpp
@@ -42,6 +42,12 @@ benchmark_threads_SOURCES = benchmark_threads.cpp
 benchmark_nodelay_SOURCES = benchmark_nodelay.cpp
 file_upload_SOURCES = file_upload.cpp
 file_upload_with_callback_SOURCES = file_upload_with_callback.cpp
+empty_response_example_SOURCES = empty_response_example.cpp
+iovec_response_example_SOURCES = iovec_response_example.cpp
+pipe_response_example_SOURCES = pipe_response_example.cpp
+daemon_info_SOURCES = daemon_info.cpp
+external_event_loop_SOURCES = external_event_loop.cpp
+turbo_mode_SOURCES = turbo_mode.cpp
 
 if HAVE_BAUTH
 noinst_PROGRAMS += basic_authentication centralized_authentication
@@ -59,3 +65,9 @@ if HAVE_DAUTH
 noinst_PROGRAMS += digest_authentication
 digest_authentication_SOURCES = digest_authentication.cpp
 endif
+
+if HAVE_WEBSOCKET
+noinst_PROGRAMS += websocket_echo
+websocket_echo_SOURCES = websocket_echo.cpp
+websocket_echo_LDADD = $(LDADD) -lmicrohttpd_ws
+endif

examples/daemon_info.cpp

@@ -0,0 +1,59 @@
+/*
+     This file is part of libhttpserver
+     Copyright (C) 2011-2019 Sebastiano Merlino
+
+     This library is free software; you can redistribute it and/or
+     modify it under the terms of the GNU Lesser General Public
+     License as published by the Free Software Foundation; either
+     version 2.1 of the License, or (at your option) any later version.
+
+     This library is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     Lesser General Public License for more details.
+
+     You should have received a copy of the GNU Lesser General Public
+     License along with this library; if not, write to the Free Software
+     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+     USA
+*/
+
+#include <iostream>
+#include <memory>
+
+#include <httpserver.hpp>
+
+class hello_resource : public httpserver::http_resource {
+ public:
+     std::shared_ptr<httpserver::http_response> render_GET(const httpserver::http_request&) {
+         return std::make_shared<httpserver::string_response>("Hello, World!");
+     }
+};
+
+int main() {
+    // Use port 0 to let the OS assign an ephemeral port
+    httpserver::webserver ws = httpserver::create_webserver(0);
+
+    hello_resource hr;
+    ws.register_resource("/hello", &hr);
+    ws.start(false);
+
+    // Query daemon information
+    std::cout << "libmicrohttpd version: "
+              << httpserver::http::http_utils::get_mhd_version() << std::endl;
+    std::cout << "Bound port: " << ws.get_bound_port() << std::endl;
+    std::cout << "Listen FD: " << ws.get_listen_fd() << std::endl;
+    std::cout << "Active connections: " << ws.get_active_connections() << std::endl;
+    std::cout << "HTTP 200 reason: "
+              << httpserver::http::http_utils::reason_phrase(200) << std::endl;
+    std::cout << "HTTP 404 reason: "
+              << httpserver::http::http_utils::reason_phrase(404) << std::endl;
+
+    std::cout << "\nServer running on port " << ws.get_bound_port()
+              << ". Press Ctrl+C to stop." << std::endl;
+
+    // Block until interrupted
+    ws.sweet_kill();
+
+    return 0;
+}