Extensive updates and expansion of docs and examples

Author: michalpokusa

README.rst

@@ -30,6 +30,7 @@ HTTP Server for CircuitPython.
 - Gives access to request headers, query parameters, body and client's address, the one from which the request came.
 - Supports chunked transfer encoding.
 - Supports URL parameters and wildcard URLs.
+- Supports HTTP Basic and Bearer Authentication on both server and route per level.
 
 
 Dependencies

adafruit_httpserver/__init__.py

@@ -5,7 +5,7 @@
 `adafruit_httpserver`
 ================================================================================
 
-Simple HTTP Server for CircuitPython
+Socket based HTTP Server for CircuitPython
 
 
 * Author(s): Dan Halbert

adafruit_httpserver/methods.py

@@ -9,28 +9,19 @@
 
 
 GET = "GET"
-"""GET method."""
 
 POST = "POST"
-"""POST method."""
 
 PUT = "PUT"
-"""PUT method"""
 
 DELETE = "DELETE"
-"""DELETE method"""
 
 PATCH = "PATCH"
-"""PATCH method"""
 
 HEAD = "HEAD"
-"""HEAD method"""
 
 OPTIONS = "OPTIONS"
-"""OPTIONS method"""
 
 TRACE = "TRACE"
-"""TRACE method"""
 
 CONNECT = "CONNECT"
-"""CONNECT method"""

adafruit_httpserver/server.py

@@ -262,7 +262,7 @@ def require_authentication(self, auths: List[Union[Basic, Bearer]]) -> None:
         Example::
 
             server = Server(pool, "/static")
-            server.restrict_access([Basic("user", "pass")])
+            server.require_authentication([Basic("user", "pass")])
         """
         self._auths = auths
 

docs/api.rst

@@ -25,7 +25,7 @@
 .. automodule:: adafruit_httpserver.methods
     :members:
 
-.. automodule:: adafruit_httpserver.mime_type
+.. automodule:: adafruit_httpserver.mime_types
     :members:
 
 .. automodule:: adafruit_httpserver.exceptions

docs/examples.rst

@@ -1,21 +1,65 @@
 Simple Test
--------------------
+-----------
+
+This is the minimal example of using the library.
+This example is serving a simple static text message.
+
+It also manually connects to the WiFi network.
+
+.. literalinclude:: ../examples/httpserver_simpletest_manual.py
+    :caption: examples/httpserver_simpletest_manual.py
+    :linenos:
+
+Although there is nothing wrong with this approach, from the version 8.0.0 of CircuitPython,
+`it is possible to use the environment variables <https://docs.circuitpython.org/en/latest/docs/environment.html#circuitpython-behavior>`_
+defined in ``settings.toml`` file to store secrets and configure the WiFi network.
+
+This is the same example as above, but it uses the ``settings.toml`` file to configure the WiFi network.
+
+**From now on, all the examples will use the** ``settings.toml`` **file to configure the WiFi network.**
+
+.. literalinclude:: ../examples/settings.toml
+    :caption: settings.toml
+    :linenos:
 
-Serving a simple static text message.
+Note that we still need to import ``socketpool`` and ``wifi`` modules.
 
-.. literalinclude:: ../examples/httpserver_simpletest.py
-    :caption: examples/httpserver_simpletest.py
+.. literalinclude:: ../examples/httpserver_simpletest_auto.py
+    :caption: examples/httpserver_simpletest_auto.py
     :linenos:
 
+Serving static files
+--------------------
+
+It is possible to serve static files from the filesystem.
+In this example we are serving files from the ``/static`` directory.
+
+In order to save memory, we are unregistering unused MIME types and registering additional ones.
+`More about MIME types. <https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types>`_
+
+.. literalinclude:: ../examples/httpserver_static_files_serving.py
+    :caption: examples/httpserver_static_files_serving.py
+    :linenos:
+
+You can also serve a specific file from the handler.
+By default ``Response.send_file()`` looks for the file in the server's ``root_path`` directory, but you can change it.
+
+.. literalinclude:: ../examples/httpserver_handler_serves_file.py
+    :caption: examples/httpserver_handler_serves_file.py
+    :linenos:
+
+Tasks in the background
+-----------------------
+
 If you want your code to do more than just serve web pages,
 use the ``.start()``/``.poll()`` methods as shown in this example.
 
 Between calling ``.poll()`` you can do something useful,
 for example read a sensor and capture an average or
 a running total of the last 10 samples.
 
-.. literalinclude:: ../examples/httpserver_simple_poll.py
-    :caption: examples/httpserver_simple_poll.py
+.. literalinclude:: ../examples/httpserver_start_and_poll.py
+    :caption: examples/httpserver_start_and_poll.py
     :linenos:
 
 Server with MDNS
@@ -30,6 +74,22 @@ In this example, the server is accessible via ``http://custom-mdns-hostname/`` a
     :caption: examples/httpserver_mdns.py
     :linenos:
 
+Handling different methods
+---------------------------------------
+
+On every ``server.route()`` call you can specify which HTTP methods are allowed.
+By default, only ``GET`` method is allowed.
+
+You can pass a list of methods or a single method as a string.
+
+It is recommended to use the the values in ``adafruit_httpserver.methods`` module to avoid typos and for future proofness.
+
+In example below, handler for ``/api`` route will be called when any of ``GET``, ``POST``, ``PUT``, ``DELETE`` methods is used.
+
+.. literalinclude:: ../examples/httpserver_methods.py
+    :caption: examples/httpserver_methods.py
+    :linenos:
+
 Change NeoPixel color
 ---------------------
 
@@ -45,7 +105,7 @@ Tested on ESP32-S2 Feather.
     :linenos:
 
 Get CPU information
----------------------
+-------------------
 
 You can return data from sensors or any computed value as JSON.
 That makes it easy to use the data in other applications.
@@ -55,23 +115,23 @@ That makes it easy to use the data in other applications.
     :linenos:
 
 Chunked response
----------------------
+----------------
 
 Library supports chunked responses. This is useful for streaming data.
-To use it, you need to set the ``chunked=True`` when creating a ``HTTPResponse`` object.
+To use it, you need to set the ``chunked=True`` when creating a ``Response`` object.
 
 .. literalinclude:: ../examples/httpserver_chunked.py
     :caption: examples/httpserver_chunked.py
     :linenos:
 
 URL parameters
----------------------
+--------------
 
 Alternatively to using query parameters, you can use URL parameters.
 
-In order to use URL parameters, you need to wrap them inside ``<>`` in ``HTTPServer.route``, e.g. ``<my_parameter>``.
+In order to use URL parameters, you need to wrap them inside ``<>`` in ``Server.route``, e.g. ``<my_parameter>``.
 
-All URL parameters are **passed as positional (not keyword) arguments** to the handler function, in order they are specified in ``HTTPServer.route``.
+All URL parameters values are **passed as keyword arguments** to the handler function.
 
 Notice how the handler function in example below accepts two additional arguments : ``device_id`` and ``action``.
 
@@ -80,11 +140,26 @@ make sure to add default values for all the ones that might not be passed.
 In the example below the second route has only one URL parameter, so the ``action`` parameter has a default value.
 
 Keep in mind that URL parameters are always passed as strings, so you need to convert them to the desired type.
-Also note that the names of the function parameters **do not have to match** with the ones used in route, but they **must** be in the same order.
-Look at the example below to see how the ``route_param_1`` and ``route_param_1`` are named differently in the handler function.
-
-Although it is possible, it makes more sense be consistent with the names of the parameters in the route and in the handler function.
+Also note that the names of the function parameters **have to match** with the ones used in route, but they **do not have to** be in the same order.
 
 .. literalinclude:: ../examples/httpserver_url_parameters.py
     :caption: examples/httpserver_url_parameters.py
     :linenos:
+
+Authentication
+--------------
+
+In order to increase security of your server, you can use ``Basic`` and ``Bearer`` authentication.
+
+If you want to apply authentication to the whole server, you need to call ``.require_authentication`` on ``Server`` instance.
+
+.. literalinclude:: ../examples/httpserver_authentication_server.py
+    :caption: examples/httpserver_authentication_server.py
+    :linenos:
+
+On the other hand, if you want to apply authentication to a set of routes, you need to call ``require_authentication`` function.
+In both cases you can check if ``request`` is authenticated by calling ``check_authentication`` on it.
+
+.. literalinclude:: ../examples/httpserver_authentication_handlers.py
+    :caption: examples/httpserver_authentication_handlers.py
+    :linenos:

examples/httpserver_authentication_handlers.py

@@ -0,0 +1,68 @@
+# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+import socketpool
+import wifi
+
+from adafruit_httpserver import Server, Request, Response, UNATUHORIZED_401
+from adafruit_httpserver.authentication import (
+    AuthenticationError,
+    Basic,
+    Bearer,
+    check_authentication,
+    require_authentication,
+)
+
+
+pool = socketpool.SocketPool(wifi.radio)
+server = Server(pool)
+
+# Create a list of available authentication methods.
+auths = [
+    Basic("user", "password"),
+    Bearer("642ec696-2a79-4d60-be3a-7c9a3164d766"),
+]
+
+
+@server.route("/check")
+def check_if_authenticated(request: Request):
+    """
+    Check if the request is authenticated and return a appropriate response.
+    """
+    is_authenticated = check_authentication(request, auths)
+
+    with Response(request, content_type="text/plain") as response:
+        response.send("Authenticated" if is_authenticated else "Not authenticated")
+
+
+@server.route("/require-or-401")
+def require_authentication_or_401(request: Request):
+    """
+    Require authentication and return a default server 401 response if not authenticated.
+    """
+    require_authentication(request, auths)
+
+    with Response(request, content_type="text/plain") as response:
+        response.send("Authenticated")
+
+
+@server.route("/require-or-handle")
+def require_authentication_or_manually_handle(request: Request):
+    """
+    Require authentication and manually handle request if not authenticated.
+    """
+
+    try:
+        require_authentication(request, auths)
+
+        with Response(request, content_type="text/plain") as response:
+            response.send("Authenticated")
+
+    except AuthenticationError:
+        with Response(request, status=UNATUHORIZED_401) as response:
+            response.send("Not authenticated - Manually handled")
+
+
+print(f"Listening on http://{wifi.radio.ipv4_address}:80")
+server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_authentication_server.py

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+import socketpool
+import wifi
+
+from adafruit_httpserver import Server, Request, Response, Basic, Bearer
+
+
+# Create a list of available authentication methods.
+auths = [
+    Basic("user", "password"),
+    Bearer("642ec696-2a79-4d60-be3a-7c9a3164d766"),
+]
+
+pool = socketpool.SocketPool(wifi.radio)
+server = Server(pool, "/static")
+server.require_authentication(auths)
+
+
+@server.route("/implicit-require")
+def implicit_require_authentication(request: Request):
+    """
+    Implicitly require authentication because of the server.require_authentication() call.
+    """
+
+    with Response(request, content_type="text/plain") as response:
+        response.send("Authenticated")
+
+
+print(f"Listening on http://{wifi.radio.ipv4_address}:80")
+server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_chunked.py

@@ -2,34 +2,23 @@
 #
 # SPDX-License-Identifier: Unlicense
 
-import os
-
 import socketpool
 import wifi
 
-from adafruit_httpserver.request import HTTPRequest
-from adafruit_httpserver.response import HTTPResponse
-from adafruit_httpserver.server import HTTPServer
-
-
-ssid = os.getenv("WIFI_SSID")
-password = os.getenv("WIFI_PASSWORD")
+from adafruit_httpserver import Server, Request, Response
 
-print("Connecting to", ssid)
-wifi.radio.connect(ssid, password)
-print("Connected to", ssid)
 
 pool = socketpool.SocketPool(wifi.radio)
-server = HTTPServer(pool, "/static")
+server = Server(pool)
 
 
 @server.route("/chunked")
-def chunked(request: HTTPRequest):
+def chunked(request: Request):
     """
     Return the response with ``Transfer-Encoding: chunked``.
     """
 
-    with HTTPResponse(request, chunked=True) as response:
+    with Response(request, chunked=True) as response:
         response.send_chunk("Adaf")
         response.send_chunk("ruit")
         response.send_chunk(" Indus")