Add serve_static middleware and support algorithms

Author: vinniefalco

.cursor/rules/doc.mdc

@@ -0,0 +1,7 @@
+---
+description: Documentation style conventions for code snippets, javadocs, and API documentation examples
+globs: 
+alwaysApply: false
+---
+
+- `route_params` are named `rp`

include/boost/http/detail/any_bufref.hpp

@@ -0,0 +1,92 @@
+//
+// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/http
+//
+
+#ifndef BOOST_HTTP_DETAIL_ANY_BUFREF_HPP
+#define BOOST_HTTP_DETAIL_ANY_BUFREF_HPP
+
+#include <boost/http/detail/config.hpp>
+#include <boost/capy/buffers.hpp>
+#include <cstddef>
+
+namespace boost {
+namespace http {
+namespace detail {
+
+/** A type-erased const buffer sequence reference.
+
+    This class provides a type-erased interface for iterating
+    over buffer sequences without knowing the concrete type.
+*/
+class any_bufref
+{
+public:
+    /** Construct from a const buffer sequence.
+
+        @param bs The buffer sequence to adapt.
+    */
+    template<capy::ConstBufferSequence BS>
+    explicit
+    any_bufref(BS const& bs) noexcept
+        : bs_(&bs)
+        , fn_(&copy_impl<BS>)
+    {
+    }
+
+    /** Fill an array with buffers from the sequence.
+
+        @param dest Pointer to array of mutable buffer descriptors.
+
+        @param n Maximum number of buffers to copy.
+
+        @return The number of buffers actually copied.
+    */
+    std::size_t
+    copy_to(
+        capy::mutable_buffer* dest,
+        std::size_t n) const noexcept
+    {
+        return fn_(bs_, dest, n);
+    }
+
+private:
+    template<capy::ConstBufferSequence BS>
+    static std::size_t
+    copy_impl(
+        void const* p,
+        capy::mutable_buffer* dest,
+        std::size_t n)
+    {
+        auto const& bs = *static_cast<BS const*>(p);
+        auto it = capy::begin(bs);
+        auto const end_it = capy::end(bs);
+
+        std::size_t i = 0;
+        for(; it != end_it && i < n; ++it, ++i)
+        {
+            auto const& buf = *it;
+            dest[i] = capy::mutable_buffer(
+                const_cast<char*>(
+                    static_cast<char const*>(buf.data())),
+                buf.size());
+        }
+        return i;
+    }
+
+    using fn_t = std::size_t(*)(void const*,
+        capy::mutable_buffer*, std::size_t);
+
+    void const* bs_;
+    fn_t fn_;
+};
+
+} // detail
+} // http
+} // boost
+
+#endif

include/boost/http/server/cors.hpp

@@ -18,31 +18,73 @@
 namespace boost {
 namespace http {
 
+/** Options for CORS middleware configuration.
+*/
 struct cors_options
 {
+    /// Allowed origin, or "*" for any. Empty defaults to "*".
     std::string origin;
+
+    /// Allowed HTTP methods. Empty defaults to common methods.
     std::string methods;
+
+    /// Allowed request headers.
     std::string allowedHeaders;
+
+    /// Response headers exposed to client.
     std::string exposedHeaders;
+
+    /// Max age for preflight cache.
     std::chrono::seconds max_age{ 0 };
+
+    /// Status code for preflight response.
     status result = status::no_content;
+
+    /// If true, pass preflight to next handler.
     bool preFlightContinue = false;
+
+    /// If true, allow credentials.
     bool credentials = false;
 };
 
-class cors
+/** CORS middleware for handling cross-origin requests.
+
+    This middleware handles Cross-Origin Resource Sharing
+    (CORS) by setting appropriate response headers and
+    handling preflight OPTIONS requests.
+
+    @par Example
+    @code
+    cors_options opts;
+    opts.origin = "*";
+    opts.methods = "GET,POST,PUT,DELETE";
+    opts.credentials = true;
+
+    router.use( cors( opts ) );
+    @endcode
+
+    @see cors_options
+*/
+class BOOST_HTTP_DECL cors
 {
+    cors_options options_;
+
 public:
-    BOOST_HTTP_DECL
-    explicit cors(
-        cors_options options = {}) noexcept;
+    /** Construct a CORS middleware.
 
-    BOOST_HTTP_DECL
-    route_result
-    operator()(route_params& p) const;
+        @param options Configuration options.
+    */
+    explicit cors(cors_options options = {}) noexcept;
 
-private:
-    cors_options options_;
+    /** Handle a request.
+
+        Sets CORS headers and handles preflight requests.
+
+        @param rp The route parameters.
+
+        @return A task that completes with the routing result.
+    */
+    route_task operator()(route_params& rp) const;
 };
 
 } // http

include/boost/http/server/encode_url.hpp

@@ -0,0 +1,48 @@
+//
+// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/http
+//
+
+#ifndef BOOST_HTTP_SERVER_ENCODE_URL_HPP
+#define BOOST_HTTP_SERVER_ENCODE_URL_HPP
+
+#include <boost/http/detail/config.hpp>
+#include <boost/core/detail/string_view.hpp>
+#include <string>
+
+namespace boost {
+namespace http {
+
+/** Percent-encode a URL for safe use in HTTP responses.
+
+    Encodes characters that are not safe in URLs using
+    percent-encoding (e.g. space becomes %20). This is
+    useful for encoding URLs that will be included in
+    Location headers or HTML links.
+
+    The following characters are NOT encoded:
+    - Unreserved: A-Z a-z 0-9 - _ . ~
+    - Reserved (allowed in URLs): ! # $ & ' ( ) * + , / : ; = ? @
+
+    @par Example
+    @code
+    std::string url = encode_url( "/path/to/file with spaces.txt" );
+    // url == "/path/to/file%20with%20spaces.txt"
+    @endcode
+
+    @param url The URL or URL component to encode.
+
+    @return A new string with unsafe characters percent-encoded.
+*/
+BOOST_HTTP_DECL
+std::string
+encode_url(core::string_view url);
+
+} // http
+} // boost
+
+#endif

include/boost/http/server/escape_html.hpp

@@ -0,0 +1,51 @@
+//
+// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/http
+//
+
+#ifndef BOOST_HTTP_SERVER_ESCAPE_HTML_HPP
+#define BOOST_HTTP_SERVER_ESCAPE_HTML_HPP
+
+#include <boost/http/detail/config.hpp>
+#include <boost/core/detail/string_view.hpp>
+#include <string>
+
+namespace boost {
+namespace http {
+
+/** Escape a string for safe inclusion in HTML.
+
+    Replaces characters that have special meaning in HTML
+    with their corresponding character entity references:
+
+    @li `&` becomes `&amp;`
+    @li `<` becomes `&lt;`
+    @li `>` becomes `&gt;`
+    @li `"` becomes `&quot;`
+    @li `'` becomes `&#39;`
+
+    This function is used to prevent XSS (Cross-Site Scripting)
+    attacks when embedding user input in HTML responses.
+
+    @par Example
+    @code
+    std::string safe = escape_html( "<script>alert('xss')</script>" );
+    // safe == "&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;"
+    @endcode
+
+    @param s The string to escape.
+
+    @return A new string with HTML special characters escaped.
+*/
+BOOST_HTTP_DECL
+std::string
+escape_html(core::string_view s);
+
+} // http
+} // boost
+
+#endif

include/boost/http/server/etag.hpp

@@ -0,0 +1,84 @@
+//
+// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/http
+//
+
+#ifndef BOOST_HTTP_SERVER_ETAG_HPP
+#define BOOST_HTTP_SERVER_ETAG_HPP
+
+#include <boost/http/detail/config.hpp>
+#include <boost/core/detail/string_view.hpp>
+#include <cstdint>
+#include <string>
+
+namespace boost {
+namespace http {
+
+/** Options for ETag generation.
+*/
+struct etag_options
+{
+    /// Generate a weak ETag (prefixed with W/).
+    bool weak = false;
+};
+
+/** Generate an ETag from content.
+
+    Creates an ETag by computing a hash of the provided
+    content. The resulting ETag can be used in HTTP
+    responses to enable caching.
+
+    @par Example
+    @code
+    std::string content = "Hello, World!";
+    std::string tag = etag( content );
+    // tag == "\"d-3/1gIbsr1bCvZ2KQgJ7DpTGR3YH\""
+    @endcode
+
+    @param body The content to hash.
+
+    @param opts Options controlling ETag generation.
+
+    @return An ETag string suitable for use in the ETag header.
+*/
+BOOST_HTTP_DECL
+std::string
+etag(core::string_view body, etag_options opts = {});
+
+/** Generate an ETag from file metadata.
+
+    Creates an ETag based on a file's size and modification
+    time. This is more efficient than hashing file content
+    and is suitable for static file serving.
+
+    @par Example
+    @code
+    std::uint64_t size = 1234;
+    std::uint64_t mtime = 1704067200; // Unix timestamp
+    std::string tag = etag( size, mtime );
+    // tag == "\"4d2-65956a00\""
+    @endcode
+
+    @param size The file size in bytes.
+
+    @param mtime The file modification time (typically Unix timestamp).
+
+    @param opts Options controlling ETag generation.
+
+    @return An ETag string suitable for use in the ETag header.
+*/
+BOOST_HTTP_DECL
+std::string
+etag(
+    std::uint64_t size,
+    std::uint64_t mtime,
+    etag_options opts = {});
+
+} // http
+} // boost
+
+#endif