Merge branch 'form-data-parsing' into server-headers

michalpokusa · michalpokusa · commit 089569d55c9f · 2023-06-10T13:17:34.000Z
diff --git a/adafruit_httpserver/__init__.py b/adafruit_httpserver/__init__.py
@@ -51,7 +51,7 @@
     CONNECT,
 )
 from .mime_types import MIMETypes
-from .request import Request
+from .request import QueryParams, FormData, Request
 from .response import (
     Response,
     FileResponse,
diff --git a/adafruit_httpserver/request.py b/adafruit_httpserver/request.py
@@ -8,7 +8,7 @@
 """
 
 try:
-    from typing import Dict, Tuple, Union, TYPE_CHECKING
+    from typing import List, Dict, Tuple, Union, Any, TYPE_CHECKING
     from socket import socket
     from socketpool import SocketPool
 
@@ -22,6 +22,141 @@
 from .headers import Headers
 
 
+class _IFieldStorage:
+    """Interface with shared methods for QueryParams and FormData."""
+
+    _storage: Dict[str, List[Union[str, bytes]]]
+
+    def _add_field_value(self, field_name: str, value: Union[str, bytes]) -> None:
+        if field_name not in self._storage:
+            self._storage[field_name] = [value]
+        else:
+            self._storage[field_name].append(value)
+
+    def get(self, field_name: str, default: Any = None) -> Union[str, bytes, None]:
+        """Get the value of a field."""
+        return self._storage.get(field_name, [default])[0]
+
+    def get_list(self, field_name: str) -> List[Union[str, bytes]]:
+        """Get the list of values of a field."""
+        return self._storage.get(field_name, [])
+
+    @property
+    def fields(self):
+        """Returns a list of field names."""
+        return list(self._storage.keys())
+
+    def __getitem__(self, field_name: str):
+        return self.get(field_name)
+
+    def __iter__(self):
+        return iter(self._storage)
+
+    def __len__(self):
+        return len(self._storage)
+
+    def __contains__(self, key: str):
+        return key in self._storage
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({repr(self._storage)})"
+
+
+class QueryParams(_IFieldStorage):
+    """
+    Class for parsing and storing GET quer parameters requests.
+
+    Examples::
+
+        query_params = QueryParams(b"foo=bar&baz=qux&baz=quux")
+        # QueryParams({"foo": "bar", "baz": ["qux", "quux"]})
+
+        query_params.get("foo") # "bar"
+        query_params["foo"] # "bar"
+        query_params.get("non-existent-key") # None
+        query_params.get_list("baz") # ["qux", "quux"]
+        "unknown-key" in query_params # False
+        query_params.fields # ["foo", "baz"]
+    """
+
+    _storage: Dict[str, List[Union[str, bytes]]]
+
+    def __init__(self, query_string: str) -> None:
+        self._storage = {}
+
+        for query_param in query_string.split("&"):
+            if "=" in query_param:
+                key, value = query_param.split("=", 1)
+                self._add_field_value(key, value)
+            elif query_param:
+                self._add_field_value(query_param, "")
+
+
+class FormData(_IFieldStorage):
+    """
+    Class for parsing and storing form data from POST requests.
+
+    Supports ``application/x-www-form-urlencoded``, ``multipart/form-data`` and ``text/plain``
+    content types.
+
+    Examples::
+
+        form_data = FormData(b"foo=bar&baz=qux&baz=quuz", "application/x-www-form-urlencoded")
+        # or
+        form_data = FormData(b"foo=bar\\r\\nbaz=qux\\r\\nbaz=quux", "text/plain")
+        # FormData({"foo": "bar", "baz": "qux"})
+
+        form_data.get("foo") # "bar"
+        form_data["foo"] # "bar"
+        form_data.get("non-existent-key") # None
+        form_data.get_list("baz") # ["qux", "quux"]
+        "unknown-key" in form_data # False
+        form_data.fields # ["foo", "baz"]
+    """
+
+    _storage: Dict[str, List[Union[str, bytes]]]
+
+    def __init__(self, data: bytes, content_type: str) -> None:
+        self.content_type = content_type
+        self._storage = {}
+
+        if content_type.startswith("application/x-www-form-urlencoded"):
+            self._parse_x_www_form_urlencoded(data)
+
+        elif content_type.startswith("multipart/form-data"):
+            boundary = content_type.split("boundary=")[1]
+            self._parse_multipart_form_data(data, boundary)
+
+        elif content_type.startswith("text/plain"):
+            self._parse_text_plain(data)
+
+    def _parse_x_www_form_urlencoded(self, data: bytes) -> None:
+        decoded_data = data.decode()
+
+        for field_name, value in [
+            key_value.split("=", 1) for key_value in decoded_data.split("&")
+        ]:
+            self._add_field_value(field_name, value)
+
+    def _parse_multipart_form_data(self, data: bytes, boundary: str) -> None:
+        blocks = data.split(b"--" + boundary.encode())[1:-1]
+
+        for block in blocks:
+            disposition, content = block.split(b"\r\n\r\n", 1)
+            field_name = disposition.split(b'"', 2)[1].decode()
+            value = content[:-2]
+
+            self._add_field_value(field_name, value)
+
+    def _parse_text_plain(self, data: bytes) -> None:
+        lines = data.split(b"\r\n")[:-1]
+
+        for line in lines:
+            field_name, value = line.split(b"=", 1)
+
+            self._add_field_value(field_name.decode(), value.decode())
+
+
 class Request:
     """
     Incoming request, constructed from raw incoming bytes.
@@ -54,15 +189,15 @@ class Request:
     path: str
     """Path of the request, e.g. ``"/foo/bar"``."""
 
-    query_params: Dict[str, str]
+    query_params: QueryParams
     """
     Query/GET parameters in the request.
 
     Example::
 
             request  = Request(raw_request=b"GET /?foo=bar HTTP/1.1...")
             request.query_params
-            # {"foo": "bar"}
+            # QueryParams({"foo": "bar"})
     """
 
     http_version: str
@@ -91,6 +226,7 @@ def __init__(
         self.connection = connection
         self.client_address = client_address
         self.raw_request = raw_request
+        self._form_data = None
 
         if raw_request is None:
             raise ValueError("raw_request cannot be None")
@@ -117,6 +253,13 @@ def body(self) -> bytes:
     def body(self, body: bytes) -> None:
         self.raw_request = self._raw_header_bytes + b"\r\n\r\n" + body
 
+    @property
+    def form_data(self) -> Union[FormData, None]:
+        """POST data of the request"""
+        if self._form_data is None and self.method == "POST":
+            self._form_data = FormData(self.body, self.headers["Content-Type"])
+        return self._form_data
+
     def json(self) -> Union[dict, None]:
         """Body of the request, as a JSON-decoded dictionary."""
         return json.loads(self.body) if self.body else None
@@ -148,13 +291,7 @@ def _parse_start_line(header_bytes: bytes) -> Tuple[str, str, Dict[str, str], st
 
         path, query_string = path.split("?", 1)
 
-        query_params = {}
-        for query_param in query_string.split("&"):
-            if "=" in query_param:
-                key, value = query_param.split("=", 1)
-                query_params[key] = value
-            elif query_param:
-                query_params[query_param] = ""
+        query_params = QueryParams(query_string)
 
         return method, path, query_params, http_version
 
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -102,7 +102,7 @@ More info: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
 
 .. literalinclude:: ../examples/httpserver_cpu_information.py
     :caption: examples/httpserver_cpu_information.py
-    :emphasize-lines: 9,14-17,32
+    :emphasize-lines: 9,15-18,33
     :linenos:
 
 Handling different methods
@@ -146,6 +146,34 @@ Tested on ESP32-S2 Feather.
     :emphasize-lines: 25-27,39,51,60,66
     :linenos:
 
+Form data parsing
+---------------------
+
+Another way to pass data to the handler function is to use form data.
+Remember that it is only possible to use it with ``POST`` method.
+`More about POST method. <https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST>`_
+
+It is important to use correct ``enctype``, depending on the type of data you want to send.
+
+- ``application/x-www-form-urlencoded`` - For sending simple text data without any special characters including spaces.
+    If you use it, values will be automatically parsed as strings, but special characters will be URL encoded
+    e.g. ``"Hello World! ^-$%"`` will be saved as ``"Hello+World%21+%5E-%24%25"``
+- ``multipart/form-data`` - For sending text and binary files and/or text data with special characters
+    When used, values will **not** be automatically parsed as strings, they will stay as bytes instead.
+    e.g. ``"Hello World! ^-$%"`` will be saved as ``b'Hello World! ^-$%'``, which can be decoded using ``.decode()`` method.
+- ``text/plain`` - For sending text data with special characters.
+    If used, values will be automatically parsed as strings, including special characters, emojis etc.
+    e.g. ``"Hello World! ^-$%"`` will be saved as ``"Hello World! ^-$%"``, this is the **recommended** option.
+
+If you pass multiple values with the same name, they will be saved as a list, that can be accessed using ``request.data.get_list()``.
+Even if there is only one value, it will still get a list, and if there multiple values, but you use ``request.data.get()`` it will
+return only the first one.
+
+.. literalinclude:: ../examples/httpserver_form_data.py
+    :caption: examples/httpserver_form_data.py
+    :emphasize-lines: 32,47,50
+    :linenos:
+
 Chunked response
 ----------------
 
diff --git a/examples/httpserver_cpu_information.py b/examples/httpserver_cpu_information.py
@@ -8,6 +8,7 @@
 
 from adafruit_httpserver import Server, Request, JSONResponse
 
+
 pool = socketpool.SocketPool(wifi.radio)
 server = Server(pool, debug=True)
 
diff --git a/examples/httpserver_form_data.py b/examples/httpserver_form_data.py
@@ -0,0 +1,66 @@
+# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+import socketpool
+import wifi
+
+from adafruit_httpserver import Server, Request, Response, GET, POST
+
+
+pool = socketpool.SocketPool(wifi.radio)
+server = Server(pool, debug=True)
+
+
+FORM_HTML_TEMPLATE = """
+<html lang="en">
+    <head>
+        <title>Form with {enctype} enctype</title>
+    </head>
+    <body>
+        <a href="/form?enctype=application/x-www-form-urlencoded">
+            <button>Load <strong>application/x-www-form-urlencoded</strong> form</button>
+        </a><br />
+        <a href="/form?enctype=multipart/form-data">
+            <button>Load <strong>multipart/form-data</strong> form</button>
+        </a><br />
+        <a href="/form?enctype=text/plain">
+            <button>Load <strong>text/plain</strong> form</button>
+        </a><br />
+
+        <h2>Form with {enctype} enctype</h2>
+        <form action="/form" method="post" enctype="{enctype}">
+            <input type="text" name="something" placeholder="Type something...">
+            <input type="submit" value="Submit">
+        </form>
+        {submitted_value}
+    </body>
+</html>
+"""
+
+
+@server.route("/form", [GET, POST])
+def form(request: Request):
+    """
+    Serve a form with the given enctype, and display back the submitted value.
+    """
+    enctype = request.query_params.get("enctype", "text/plain")
+
+    if request.method == POST:
+        posted_value = request.data.get("something")
+
+    return Response(
+        request,
+        FORM_HTML_TEMPLATE.format(
+            enctype=enctype,
+            submitted_value=(
+                f"<h3>Submitted form value: {posted_value}</h3>"
+                if request.method == POST
+                else ""
+            ),
+        ),
+        content_type="text/html",
+    )
+
+
+server.serve_forever(str(wifi.radio.ipv4_address))
diff --git a/examples/httpserver_neopixel.py b/examples/httpserver_neopixel.py
@@ -37,6 +37,9 @@ def change_neopixel_color_handler_post_body(request: Request):
 
     data = request.body  # e.g b"255,0,0"
     r, g, b = data.decode().split(",")  # ["255", "0", "0"]
+    # or
+    data = request.data  # e.g. r=255&g=0&b=0 or r=255\r\nb=0\r\ng=0
+    r, g, b = data.get("r", 0), data.get("g", 0), data.get("b", 0)
 
     pixel.fill((int(r), int(g), int(b)))
 

Original file line number	Diff line number	Diff line change
`@@ -51,7 +51,7 @@`
`51`	`51`	`CONNECT,`
`52`	`52`	`)`
`53`	`53`	`from .mime_types import MIMETypes`
`54`		`-from .request import Request`
	`54`	`+from .request import QueryParams, FormData, Request`
`55`	`55`	`from .response import (`
`56`	`56`	`Response,`
`57`	`57`	`FileResponse,`