From 1b00c80133b2cf53835824390db6b2f462ca182d Mon Sep 17 00:00:00 2001 From: s3lph Date: Mon, 9 Jul 2018 20:50:02 +0200 Subject: [PATCH] Implemented a more explicit Pagelet return API using class instances to describe the action to take. --- matemat/webserver/__init__.py | 1 + matemat/webserver/httpd.py | 68 ++++++++-------- matemat/webserver/pagelets/login.py | 14 ++-- matemat/webserver/pagelets/logout.py | 8 +- matemat/webserver/pagelets/main.py | 10 +-- matemat/webserver/pagelets/touchkey.py | 12 +-- matemat/webserver/responses.py | 63 +++++++++++++++ matemat/webserver/test/abstract_httpd_test.py | 6 ++ matemat/webserver/test/test_serve.py | 79 +++++++++++++++---- 9 files changed, 186 insertions(+), 75 deletions(-) create mode 100644 matemat/webserver/responses.py diff --git a/matemat/webserver/__init__.py b/matemat/webserver/__init__.py index c52368e..6059687 100644 --- a/matemat/webserver/__init__.py +++ b/matemat/webserver/__init__.py @@ -7,4 +7,5 @@ server will attempt to serve the request with a static resource in a previously """ from .requestargs import RequestArgument, RequestArguments +from .responses import PageletResponse, RedirectResponse, TemplateResponse from .httpd import MatematWebserver, HttpHandler, pagelet diff --git a/matemat/webserver/httpd.py b/matemat/webserver/httpd.py index c82ba10..41866de 100644 --- a/matemat/webserver/httpd.py +++ b/matemat/webserver/httpd.py @@ -16,7 +16,7 @@ import jinja2 from matemat import __version__ as matemat_version from matemat.exceptions import HttpException -from matemat.webserver import RequestArguments +from matemat.webserver import RequestArguments, PageletResponse, RedirectResponse, TemplateResponse from matemat.webserver.util import parse_args # @@ -37,8 +37,7 @@ _PAGELET_PATHS: Dict[str, Callable[[str, # HTTP method (GET, POST, ...) Dict[str, str]], # Response headers Union[ # Return type: either a response body, or a redirect bytes, str, # Response body: will assign HTTP/1.0 200 OK - Tuple[int, str], # Redirect: First element must be 301, second the redirect path - Tuple[str, Dict[str, Any]] # Jinja template name and kwargs + PageletResponse, # A generic response ]]] = dict() # Inactivity timeout for client sessions @@ -67,9 +66,8 @@ def pagelet(path: str): headers: The dictionary of HTTP response headers. Add headers you wish to send with the response. returns: One of the following: - A HTTP Response body as str or bytes - - A HTTP redirect: A tuple of 301 (an int) and the path to redirect to (a str) - - A Jinja template call: A tuple of the template name (a string) and the template rendering - arguments (a kwargs dict) + - A PageletResponse class instance: An instance of (a subclass of) + matemat.webserver.PageletResponse, e.g. encapsulating a redirect or a Jinja2 template. raises: HttpException: If a non-200 HTTP status code should be returned :param path: The path to register the function for. @@ -82,8 +80,7 @@ def pagelet(path: str): Dict[str, str]], Union[ bytes, str, - Tuple[int, str], - Tuple[str, Dict[str, Any]] + PageletResponse ]]): # Add the function to the dict of pagelets _PAGELET_PATHS[path] = fun @@ -221,8 +218,7 @@ class HttpHandler(BaseHTTPRequestHandler): def _parse_pagelet_result(self, pagelet_res: Union[bytes, # Response body as bytes str, # Response body as str - Tuple[int, str], # Redirect - Tuple[str, Dict[str, Any]]], # Jinja template name, kwargs dict + PageletResponse], # Encapsulated or unresolved response body headers: Dict[str, str]) \ -> Tuple[int, bytes]: """ @@ -235,36 +231,34 @@ class HttpHandler(BaseHTTPRequestHandler): """ # The HTTP Response Status Code, defaults to 200 OK hsc: int = 200 - # The HTTP Response body, defaults to None - data: Union[bytes, str] = None - if isinstance(pagelet_res, tuple): - # If the return type is a tuple, it has to be either a redirect, in which case the first element must be - # int(301), or it is a template call, in which casse the first element must be the template name and the - # second element must be the kwargs dict to the template's render function - head, tail = pagelet_res - if head == 301 and isinstance(tail, str): - # Set the HTTP Response Status Code, and the redirect header - hsc = 301 - headers['Location'] = tail - elif isinstance(head, str) and isinstance(tail, dict): - # Load the Jinja2 template and render it with the provided arguments - template = self.server.jinja_env.get_template(head) - tail['matemat_version'] = self.server_version - data = template.render(**tail) - else: - raise TypeError(f'Return value of pagelet not understood: {pagelet_res}') - elif isinstance(pagelet_res, str) or isinstance(pagelet_res, bytes): - # Return value is a response body + # The HTTP Response body, defaults to empty + data: bytes = bytes() + + # If the response is a bytes object, it is used without further modification + if isinstance(pagelet_res, bytes): data = pagelet_res + + # If the response is a str object, it is encoded into a bytes object + elif isinstance(pagelet_res, str): + data = pagelet_res.encode('utf-8') + + # If the response is a PageletResponse object, the status code is extracted. Generation of the body depends + # on the subtype + elif isinstance(pagelet_res, PageletResponse): + hsc = pagelet_res.status + + # If the object is a RedirectResponse instance, no body is needed + if isinstance(pagelet_res, RedirectResponse): + headers['Location'] = pagelet_res.location + # If the object is a TemplateRespinse instance, pass the Jinja2 environment instance for rendering + elif isinstance(pagelet_res, TemplateResponse): + # noinspection PyProtectedMember + data = pagelet_res._render(self.server.jinja_env) + # else: Empty body + else: - # Return value is not a response body or a redirect raise TypeError(f'Return value of pagelet not understood: {pagelet_res}') - # The pagelet may return None as data as a shorthand for an empty response - if data is None: - data = bytes() - # If the pagelet returns a Python str, convert it to an UTF-8 encoded bytes object - if isinstance(data, str): - data = data.encode('utf-8') + # Return the resulting status code and body return hsc, data diff --git a/matemat/webserver/pagelets/login.py b/matemat/webserver/pagelets/login.py index d22fcd7..6ef9a9c 100644 --- a/matemat/webserver/pagelets/login.py +++ b/matemat/webserver/pagelets/login.py @@ -1,8 +1,8 @@ -from typing import Any, Dict, Tuple, Union +from typing import Any, Dict, Union from matemat.exceptions import AuthenticationError, HttpException -from matemat.webserver import pagelet, RequestArguments +from matemat.webserver import pagelet, RequestArguments, PageletResponse, RedirectResponse, TemplateResponse from matemat.primitives import User from matemat.db import MatematDatabase @@ -13,17 +13,17 @@ def login_page(method: str, args: RequestArguments, session_vars: Dict[str, Any], headers: Dict[str, str])\ - -> Union[bytes, str, Tuple[int, str], Tuple[str, Dict[str, Any]]]: + -> Union[bytes, str, PageletResponse]: if 'user' in session_vars: - return 301, '/' + return RedirectResponse('/') if method == 'GET': - return 'login.html', {} + return TemplateResponse('login.html') elif method == 'POST': with MatematDatabase('test.db') as db: try: user: User = db.login(str(args.username), str(args.password)) except AuthenticationError: - return 301, '/login' + return RedirectResponse('/login') session_vars['user'] = user - return 301, '/' + return RedirectResponse('/') raise HttpException(405) diff --git a/matemat/webserver/pagelets/logout.py b/matemat/webserver/pagelets/logout.py index 766558a..cbd7cad 100644 --- a/matemat/webserver/pagelets/logout.py +++ b/matemat/webserver/pagelets/logout.py @@ -1,7 +1,7 @@ -from typing import Any, Dict, List, Optional, Tuple, Union +from typing import Any, Dict, Union -from matemat.webserver import pagelet, RequestArguments +from matemat.webserver import pagelet, RequestArguments, PageletResponse, RedirectResponse @pagelet('/logout') @@ -10,7 +10,7 @@ def logout(method: str, args: RequestArguments, session_vars: Dict[str, Any], headers: Dict[str, str])\ - -> Union[bytes, str, Tuple[int, str], Tuple[str, Dict[str, Any]]]: + -> Union[bytes, str, PageletResponse]: if 'user' in session_vars: del session_vars['user'] - return 301, '/' + return RedirectResponse('/') diff --git a/matemat/webserver/pagelets/main.py b/matemat/webserver/pagelets/main.py index 24e6f0b..be0bd60 100644 --- a/matemat/webserver/pagelets/main.py +++ b/matemat/webserver/pagelets/main.py @@ -1,7 +1,7 @@ -from typing import Any, Dict, Optional, Tuple, Union +from typing import Any, Dict, Union -from matemat.webserver import pagelet, RequestArguments +from matemat.webserver import pagelet, RequestArguments, PageletResponse, TemplateResponse from matemat.primitives import User from matemat.db import MatematDatabase @@ -12,12 +12,12 @@ def main_page(method: str, args: RequestArguments, session_vars: Dict[str, Any], headers: Dict[str, str])\ - -> Union[bytes, str, Tuple[int, str], Tuple[str, Dict[str, Any]]]: + -> Union[bytes, str, PageletResponse]: with MatematDatabase('test.db') as db: if 'user' in session_vars: user: User = session_vars['user'] products = db.list_products() - return 'main.html', {'user': user, 'list': products} + return TemplateResponse('main.html', user=user, list=products) else: users = db.list_users() - return 'main.html', {'list': users} + return TemplateResponse('main.html', list=users) diff --git a/matemat/webserver/pagelets/touchkey.py b/matemat/webserver/pagelets/touchkey.py index 27c943e..2b81c89 100644 --- a/matemat/webserver/pagelets/touchkey.py +++ b/matemat/webserver/pagelets/touchkey.py @@ -4,7 +4,7 @@ from typing import Any, Dict, Tuple, Union import urllib.parse from matemat.exceptions import AuthenticationError, HttpException -from matemat.webserver import pagelet, RequestArguments +from matemat.webserver import pagelet, RequestArguments, PageletResponse, RedirectResponse, TemplateResponse from matemat.primitives import User from matemat.db import MatematDatabase @@ -15,18 +15,18 @@ def touchkey_page(method: str, args: RequestArguments, session_vars: Dict[str, Any], headers: Dict[str, str])\ - -> Union[bytes, str, Tuple[int, str], Tuple[str, Dict[str, Any]]]: + -> Union[bytes, str, PageletResponse]: if 'user' in session_vars: - return 301, '/' + return RedirectResponse('/') if method == 'GET': - return 'touchkey.html', {'username': str(args.username)} if 'username' in args else {} + return TemplateResponse('touchkey.html', username=str(args.username) if 'username' in args else None) elif method == 'POST': with MatematDatabase('test.db') as db: try: user: User = db.login(str(args.username), touchkey=str(args.touchkey)) except AuthenticationError: quoted = urllib.parse.quote_plus(bytes(args.username)) - return 301, f'/touchkey?username={quoted}' + return RedirectResponse(f'/touchkey?username={quoted}') session_vars['user'] = user - return 301, '/' + return RedirectResponse('/') raise HttpException(405) diff --git a/matemat/webserver/responses.py b/matemat/webserver/responses.py new file mode 100644 index 0000000..f1e7f90 --- /dev/null +++ b/matemat/webserver/responses.py @@ -0,0 +1,63 @@ + +from jinja2 import Environment, Template + + +class PageletResponse: + """ + Base class for pagelet return values that require more action than simply sending plain data. + + An instance of this base class will result in an empty 200 OK response. + """ + + def __init__(self, status: int = 200): + """ + Create an empty response. + + :param status: The HTTP status code, defaults to 200 (OK). + """ + self.status: int = status + + +class RedirectResponse(PageletResponse): + """ + A pagelet response that causes the server to redirect to another location, using a 301 Permanently Moved (uncached) + response status, and a Location header. + """ + + def __init__(self, location: str): + """ + Create a redirection response with the given redirection location. + + :param location: The location to redirect to. + """ + super().__init__(status=301) + self.location: str = location + + +class TemplateResponse(PageletResponse): + """ + A pagelet response that causes the server to load a Jinja2 template and render it with the provided arguments, then + sending the result as response body, with a 200 OK response status. + """ + + def __init__(self, name: str, **kwargs): + """ + Create a template response with the given template name and arguments. + + :param name: Name of the template to load. + :param kwargs: Arguments for rendering the template, will be passed to jinja2.Template.render as is. + """ + super().__init__() + self.name: str = name + self.kwargs = kwargs + + def _render(self, jinja_env: Environment) -> bytes: + """ + Load and render the template using the Jinja2 environment managed by the web server instance. This method + should not be called by a pagelet. + + :param jinja_env: The Jinja2 environment. + :return: An UTF-8 encoded bytes object containing the template rendering result. + """ + template: Template = jinja_env.get_template(self.name) + return template.render(**self.kwargs).encode('utf-8') diff --git a/matemat/webserver/test/abstract_httpd_test.py b/matemat/webserver/test/abstract_httpd_test.py index ff4c0c6..b121dfd 100644 --- a/matemat/webserver/test/abstract_httpd_test.py +++ b/matemat/webserver/test/abstract_httpd_test.py @@ -9,6 +9,8 @@ from abc import ABC from datetime import datetime from http.server import HTTPServer +import jinja2 + from matemat.webserver import pagelet, RequestArguments @@ -107,6 +109,10 @@ class MockServer: self.session_vars: Dict[str, Tuple[datetime, Dict[str, Any]]] = dict() # Webroot for statically served content self.webroot: str = webroot + # Jinja environment with a single, static template + self.jinja_env = jinja2.Environment( + loader=jinja2.DictLoader({'test.txt': 'Hello, {{ what }}!'}) + ) class MockSocket(bytes): diff --git a/matemat/webserver/test/test_serve.py b/matemat/webserver/test/test_serve.py index 5bcdd4d..7b0b61d 100644 --- a/matemat/webserver/test/test_serve.py +++ b/matemat/webserver/test/test_serve.py @@ -1,21 +1,31 @@ -from typing import Any, Dict +from typing import Any, Dict, Union import os import os.path from matemat.exceptions import HttpException -from matemat.webserver import HttpHandler, RequestArguments +from matemat.webserver import HttpHandler, RequestArguments, PageletResponse, RedirectResponse, TemplateResponse from matemat.webserver.test.abstract_httpd_test import AbstractHttpdTest, test_pagelet -@test_pagelet('/just/testing/serve_pagelet_ok') -def serve_test_pagelet_ok(method: str, - path: str, - args: RequestArguments, - session_vars: Dict[str, Any], - headers: Dict[str, str]): +@test_pagelet('/just/testing/serve_pagelet_str') +def serve_test_pagelet_str(method: str, + path: str, + args: RequestArguments, + session_vars: Dict[str, Any], + headers: Dict[str, str]) -> Union[bytes, str, PageletResponse]: headers['Content-Type'] = 'text/plain' - return 'serve test pagelet ok' + return 'serve test pagelet str' + + +@test_pagelet('/just/testing/serve_pagelet_bytes') +def serve_test_pagelet_bytes(method: str, + path: str, + args: RequestArguments, + session_vars: Dict[str, Any], + headers: Dict[str, str]) -> Union[bytes, str, PageletResponse]: + headers['Content-Type'] = 'application/octet-stream' + return b'serve\x80test\xffpagelet\xfebytes' @test_pagelet('/just/testing/serve_pagelet_redirect') @@ -23,16 +33,27 @@ def serve_test_pagelet_redirect(method: str, path: str, args: RequestArguments, session_vars: Dict[str, Any], - headers: Dict[str, str]): - return 301, '/foo/bar' + headers: Dict[str, str]) -> Union[bytes, str, PageletResponse]: + return RedirectResponse('/foo/bar') +@test_pagelet('/just/testing/serve_pagelet_template') +def serve_test_pagelet_template(method: str, + path: str, + args: RequestArguments, + session_vars: Dict[str, Any], + headers: Dict[str, str]) -> Union[bytes, str, PageletResponse]: + headers['Content-Type'] = 'text/plain' + return TemplateResponse('test.txt', what='World') + + +# noinspection PyTypeChecker @test_pagelet('/just/testing/serve_pagelet_fail') def serve_test_pagelet_fail(method: str, path: str, args: RequestArguments, session_vars: Dict[str, Any], - headers: Dict[str, str]): + headers: Dict[str, str]) -> Union[bytes, str, PageletResponse]: session_vars['test'] = 'hello, world!' headers['Content-Type'] = 'text/plain' raise HttpException() @@ -54,17 +75,29 @@ class TestServe(AbstractHttpdTest): f.write('This should not be readable') os.chmod(forbidden, 0) - def test_serve_pagelet_ok(self): + def test_serve_pagelet_str(self): # Call the test pagelet that produces a 200 OK result - self.client_sock.set_request(b'GET /just/testing/serve_pagelet_ok HTTP/1.1\r\n\r\n') + self.client_sock.set_request(b'GET /just/testing/serve_pagelet_str HTTP/1.1\r\n\r\n') HttpHandler(self.client_sock, ('::1', 45678), self.server) packet = self.client_sock.get_response() # Make sure the correct pagelet was called - self.assertEqual('serve_test_pagelet_ok', packet.pagelet) + self.assertEqual('serve_test_pagelet_str', packet.pagelet) # Make sure the expected content is served self.assertEqual(200, packet.statuscode) - self.assertEqual(b'serve test pagelet ok', packet.body) + self.assertEqual(b'serve test pagelet str', packet.body) + + def test_serve_pagelet_bytes(self): + # Call the test pagelet that produces a 200 OK result + self.client_sock.set_request(b'GET /just/testing/serve_pagelet_bytes HTTP/1.1\r\n\r\n') + HttpHandler(self.client_sock, ('::1', 45678), self.server) + packet = self.client_sock.get_response() + + # Make sure the correct pagelet was called + self.assertEqual('serve_test_pagelet_bytes', packet.pagelet) + # Make sure the expected content is served + self.assertEqual(200, packet.statuscode) + self.assertEqual(b'serve\x80test\xffpagelet\xfebytes', packet.body) def test_serve_pagelet_fail(self): # Call the test pagelet that produces a 500 Internal Server Error result @@ -81,12 +114,26 @@ class TestServe(AbstractHttpdTest): HttpHandler(self.client_sock, ('::1', 45678), self.server) packet = self.client_sock.get_response() + # Make sure the correct pagelet was called + self.assertEqual('serve_test_pagelet_redirect', packet.pagelet) # Make sure the correct redirect is issued self.assertEqual(301, packet.statuscode) self.assertEqual('/foo/bar', packet.headers['Location']) # Make sure the response body is empty self.assertEqual(0, len(packet.body)) + def test_serve_pagelet_template(self): + # Call the test pagelet that redirects to another path + self.client_sock.set_request(b'GET /just/testing/serve_pagelet_template HTTP/1.1\r\n\r\n') + HttpHandler(self.client_sock, ('::1', 45678), self.server) + packet = self.client_sock.get_response() + + # Make sure the correct pagelet was called + self.assertEqual('serve_test_pagelet_template', packet.pagelet) + self.assertEqual(200, packet.statuscode) + # Make sure the response body was rendered correctly by the templating engine + self.assertEqual(b'Hello, World!', packet.body) + def test_serve_static_ok(self): # Request a static resource self.client_sock.set_request(b'GET /static_resource.txt HTTP/1.1\r\n\r\n')