Added Server.debug for verbose messages during development

Author: michalpokusa

adafruit_httpserver/server.py

@@ -15,6 +15,7 @@
     pass
 
 from errno import EAGAIN, ECONNRESET, ETIMEDOUT
+from traceback import print_exception
 
 from .authentication import Basic, Bearer, require_authentication
 from .exceptions import (
@@ -37,12 +38,15 @@ class Server:
     host: str = None
     port: int = None
 
-    def __init__(self, socket_source: Protocol, root_path: str = None) -> None:
+    def __init__(
+        self, socket_source: Protocol, root_path: str = None, *, debug: bool = False
+    ) -> None:
         """Create a server, and get it ready to run.
 
         :param socket: An object that is a source of sockets. This could be a `socketpool`
           in CircuitPython or the `socket` module in CPython.
         :param str root_path: Root directory to serve files from
+        :param bool debug: Enables debug messages useful during development
         """
         self._auths = []
         self._buffer = bytearray(1024)
@@ -53,6 +57,8 @@ def __init__(self, socket_source: Protocol, root_path: str = None) -> None:
         self.root_path = root_path
         self.stopped = False
 
+        self.debug = debug
+
     def route(self, path: str, methods: Union[str, List[str]] = GET) -> Callable:
         """
         Decorator used to add a route.
@@ -119,8 +125,9 @@ def serve_forever(self, host: str, port: int = 80) -> None:
                 self.poll()
             except KeyboardInterrupt:  # Exit on Ctrl-C e.g. during development
                 return
-            except:  # pylint: disable=bare-except
-                continue
+            except Exception as error:  # pylint: disable=broad-except
+                if self.debug:
+                    _debug_exception_in_handler(error)
 
     def start(self, host: str, port: int = 80) -> None:
         """
@@ -142,6 +149,9 @@ def start(self, host: str, port: int = 80) -> None:
         self._sock.listen(10)
         self._sock.setblocking(False)  # Non-blocking socket
 
+        if self.debug:
+            _debug_started_server(self)
+
     def stop(self) -> None:
         """
         Stops the server from listening for new connections and closes the socket.
@@ -245,7 +255,7 @@ def _handle_request(self, request: Request, handler: Union[Callable, None]):
             # ...request.method is GET or HEAD, try to serve a file from the filesystem.
             elif request.method in [GET, HEAD]:
                 self._serve_file_from_filesystem(request)
-            # ...
+
             else:
                 Response(request, status=BAD_REQUEST_400).send()
 
@@ -276,6 +286,9 @@ def poll(self):
                 if (request := self._receive_request(conn, client_address)) is None:
                     return
 
+                if self.debug:
+                    _debug_incoming_request(request)
+
                 # Find a handler for the route
                 handler = self.routes.find_handler(_Route(request.path, request.method))
 
@@ -349,3 +362,24 @@ def socket_timeout(self, value: int) -> None:
             self._timeout = value
         else:
             raise ValueError("Server.socket_timeout must be a positive numeric value.")
+
+
+def _debug_started_server(server: "Server"):
+    """Prints a message when the server starts."""
+    host, port = server.host, server.port
+
+    print(f"Started development server on http://{host}:{port}")
+
+
+def _debug_incoming_request(request: "Request"):
+    """Prints a message when a request is received."""
+    client_ip = request.client_address[0]
+    method = request.method
+    size = len(request.raw_request)
+
+    print(f"{client_ip} -- {method} {request.path} {size}")
+
+
+def _debug_exception_in_handler(error: Exception):
+    """Prints a message when an exception is raised in a handler."""
+    print_exception(error)

docs/examples.rst

@@ -1,6 +1,9 @@
 Simple Test
 -----------
 
+**All examples in this document are using** ``Server`` **in** ``debug`` **mode.**
+**This mode is useful for development, but it is not recommended to use it in production.**
+
 This is the minimal example of using the library.
 This example is serving a simple static text message.
 

examples/httpserver_authentication_handlers.py

@@ -16,7 +16,7 @@
 
 
 pool = socketpool.SocketPool(wifi.radio)
-server = Server(pool)
+server = Server(pool, debug=True)
 
 # Create a list of available authentication methods.
 auths = [
@@ -64,5 +64,4 @@ def require_authentication_or_manually_handle(request: Request):
             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

@@ -15,7 +15,7 @@
 ]
 
 pool = socketpool.SocketPool(wifi.radio)
-server = Server(pool, "/static")
+server = Server(pool, "/static", debug=True)
 server.require_authentication(auths)
 
 
@@ -29,5 +29,4 @@ def implicit_require_authentication(request: Request):
         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

@@ -9,7 +9,7 @@
 
 
 pool = socketpool.SocketPool(wifi.radio)
-server = Server(pool)
+server = Server(pool, debug=True)
 
 
 @server.route("/chunked")
@@ -26,5 +26,4 @@ def chunked(request: Request):
         response.send_chunk("ies")
 
 
-print(f"Listening on http://{wifi.radio.ipv4_address}:80")
 server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_cpu_information.py

@@ -10,7 +10,7 @@
 from adafruit_httpserver import Server, Request, Response
 
 pool = socketpool.SocketPool(wifi.radio)
-server = Server(pool)
+server = Server(pool, debug=True)
 
 
 @server.route("/cpu-information")
@@ -29,5 +29,4 @@ def cpu_information_handler(request: Request):
         response.send(json.dumps(data))
 
 
-print(f"Listening on http://{wifi.radio.ipv4_address}:80")
 server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_handler_serves_file.py

@@ -10,7 +10,7 @@
 
 
 pool = socketpool.SocketPool(wifi.radio)
-server = Server(pool, "/static")
+server = Server(pool, "/static", debug=True)
 
 
 @server.route("/home")
@@ -23,5 +23,4 @@ def home(request: Request):
         response.send_file("home.html", root_path="/www")
 
 
-print(f"Listening on http://{wifi.radio.ipv4_address}:80")
 server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_mdns.py

@@ -14,7 +14,7 @@
 mdns_server.advertise_service(service_type="_http", protocol="_tcp", port=80)
 
 pool = socketpool.SocketPool(wifi.radio)
-server = Server(pool, "/static")
+server = Server(pool, "/static", debug=True)
 
 
 @server.route("/")
@@ -26,5 +26,4 @@ def base(request: Request):
         response.send_file("index.html")
 
 
-print(f"Listening on http://{wifi.radio.ipv4_address}:80")
 server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_methods.py

@@ -9,7 +9,7 @@
 
 
 pool = socketpool.SocketPool(wifi.radio)
-server = Server(pool)
+server = Server(pool, debug=True)
 
 
 @server.route("/api", [GET, POST, PUT, DELETE])
@@ -34,5 +34,4 @@ def api(request: Request):
             response.send("Object deleted")
 
 
-print(f"Listening on http://{wifi.radio.ipv4_address}:80")
 server.serve_forever(str(wifi.radio.ipv4_address))

examples/httpserver_multiple_servers.py

@@ -10,8 +10,8 @@
 
 pool = socketpool.SocketPool(wifi.radio)
 
-bedroom_server = Server(pool, "/bedroom")
-office_server = Server(pool, "/office")
+bedroom_server = Server(pool, "/bedroom", debug=True)
+office_server = Server(pool, "/office", debug=True)
 
 
 @bedroom_server.route("/bedroom")
@@ -45,9 +45,6 @@ def home(request: Request):
 id_address = str(wifi.radio.ipv4_address)
 
 # Start the servers.
-
-print(f"[bedroom_server] Listening on http://{id_address}:5000")
-print(f"[office_server] Listening on http://{id_address}:8000")
 bedroom_server.start(id_address, 5000)
 office_server.start(id_address, 8000)