Improve content negociation middlewares

docs/middlewares/content-negotiation.rst

@@ -0,0 +1,97 @@
+Content Negotiation
+===================
+
+Negotiating the resource representation is an essential part of the HTTP
+protocol.
+
+The negotiation process is simple: expectations are provided for a specific
+header, if they are met, the processing is forwarded with the highest quality
+value, otherwise a ``406 Not Acceptable`` status is raised.
+
+.. code:: vala
+
+    using Valum.ContentNegotiation;
+
+    app.get ("", negotiate ("Accept",
+                            {"text/html", "text/html+xml"},
+                            (req, res, next, stack, content_type) => {
+        // produce a response based on 'content_type'
+    }));
+
+Pass the ``NegotiateFlags.NEXT`` flag to forward with ``next`` instead of
+raising a ``406 Not Acceptable``.
+
+.. code:: vala
+
+    app.get ("", negotiate ("Accept", {"text/html"}, (req, res) => {
+        // produce 'text/html'
+    }, NegotiateFlags.NEXT)).then ((req, res) => {
+        // the user agent does not accept 'text/html'
+    });
+
+The default value for the continuation is ``forward``. It will simply call
+``next`` to continue to the next middleware following the negotiation. This is
+typically what would be found on the top of an application.
+
+.. code:: vala
+
+    app.use (negotiate ("Accept", {"text/xhtml"}));
+
+    // all the following route assume that 'text/xhtml' is being produced.
+
+    app.status (Soup.Status.NOT_ACCEPTABLE, (req, res) => {
+        // handle '406 Not Acceptable' here
+    });
+
+A custom comparison function can be provided to ``negotiate`` in order to
+handle wildcards and other edge cases. The user agent pattern is the first
+argument and the expectation is the second.
+
+.. warning::
+
+    Most of the HTTP/1.1 specification about headers is case-insensitive, use
+    `Soup.str_case_equal`_ to perform comparisons.
+
+.. _Soup.str_case_equal: http://valadoc.org/#!api=libsoup-2.4/Soup.str_case_equal
+
+.. code:: vala
+
+    app.use (negotiate ("Accept",
+                        {"text/xhtml"},
+                        forward,
+                        NegotiateFlags.NONE,
+                        (a, b) => {
+        return a == "*" || Soup.str_case_equal (a, b);
+    });
+
+Middlewares
+-----------
+
+For convenience, middlewares that support edge cases are provided to handle
+common headers:
+
++---------------------+----------------------+------------------------+
+| Middleware          | Header               | Edge cases             |
++=====================+======================+========================+
+| ``accept``          | ``Content-Type``     | ``*/*`` and ``type/*`` |
++---------------------+----------------------+------------------------+
+| ``accept_charset``  | ``Content-Type``     | ``*``                  |
++---------------------+----------------------+------------------------+
+| ``accept_encoding`` | ``Content-Encoding`` | ``*``                  |
++---------------------+----------------------+------------------------+
+| ``accept_language`` | ``Content-Language`` | missing language type  |
++---------------------+----------------------+------------------------+
+| ``accept_ranges``   | ``Content-Ranges``   | none                   |
++---------------------+----------------------+------------------------+
+
+The ``accept`` middleware will assign the media type and preserve all other
+parameters.
+
+The ``accept_encoding`` middleware will convert the :doc:`../vsgi/response` if
+it's either ``gzip`` or ``deflate``.
+
+.. warning::
+
+    The ``accept_encoding`` middleware must always be applied before
+    ``accept_charset`` to avoid corruption; converting the charset of
+    a compressed binary format is not an excellent idea.

docs/middlewares/index.rst

@@ -2,5 +2,6 @@ Middlewares
 ===========
 
 .. toctree::
+    content-negotiation
     server-sent-events
     subdomain

examples/app/app.vala

@@ -16,6 +16,7 @@
  */
 
 using Valum;
+using Valum.ContentNegotiation;
 using Valum.ServerSentEvents;
 using VSGI.Soup;
 
@@ -281,16 +282,21 @@ app.get ("server-sent-events", stream_events ((req, send) => {
 	});
 }));
 
-app.get ("negociate", accept ("application/json", (req, res) => {
+app.get ("negotiate", accept ({"application/json"}, (req, res) => {
 	res.headers.set_content_type ("application/json", null);
 	res.body.write_all ("{\"a\":\"b\"}".data, null);
-})).then (accept ("text/xml", (req, res) => {
+}, NegotiateFlags.NEXT)).then (accept ({"text/xml"}, (req, res) => {
 	res.headers.set_content_type ("text/xml", null);
 	res.body.write_all ("<a>b</a>".data, null);
-})).then ((req, res) => {
-	res.status = global::Soup.Status.NOT_ACCEPTABLE;
-	res.body.write_all ("Supply the 'Accept' header with either 'application/json' or 'text/xml'.".data, null);
-});
+}));
+
+app.get ("negotiate-charset", accept_charset ({"iso-8859-1"}, (req, res) => {
+	res.body.write_all ("Héllo world!".data, null);
+}));
+
+app.get ("negotiate-encoding", accept_encoding ({"gzip", "deflate"}, (req, res, next, stack, encoding) => {
+	res.body.write_all ("Hello world! (compressed with %s)".printf (encoding).data, null);
+}));
 
 app.status (Soup.Status.NOT_FOUND, (req, res, next, stack) => {
 	var template = new View.from_stream (resources_open_stream ("/templates/404.html", ResourceLookupFlags.NONE));

examples/app/templates/home.html

@@ -106,7 +106,15 @@ <h4>Extras</h4>
               <ul class="list-inline">
                 <li><a href="/ctpl/foo/bar">CTPL templating</a></li>
                 <li><a href="/server-sent-events">Server-Sent Events</a></li>
-                <li><a href="/negociate">negociate</a></li>
+                <li>
+                  <a href="/negotiate">negotiate</a>
+                </li>
+                <li>
+                  <a href="/negotiate-encoding"> negotiate encoding (gzip or deflate)</a>
+                </li>
+                <li>
+                  <a href="/negotiate-charset">negotiate charset (iso-8859-1)</a>
+                </li>
               </ul>
               <footer>
                 <p class="text-center">