wau 0.1.0__py3-none-any.whl

wau-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: wau
+Version: 0.1.0
+Summary: Web API Utils
+Author: Marco Schmalz
+License-Expression: LGPL-3.0-or-later
+Keywords: api,json,werkzeug,education
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dataset>=2.0.0
+Requires-Dist: pyjwt>=2.13.0
+Requires-Dist: werkzeug>=3.1.8
+Dynamic: license-file
+
+# `wau` — Web API Utils
+
+Web API Utils, or short `wau`, is a thin layer on top of Werkzeug to provide a simple and consistent interface for writing APIs in Python. `wau` is built for educational purposes and is not intended for production use. It is opinionated, as it only supports JSON as data format. It uses simple type annotations to define the expected input and output of the API endpoints. Common tasks as authentication, CORS and server-sent events are supported by default.
+
+## Installation
+
+Install from PyPI:
+
+```powershell
+pip install wau
+```
+
+or with uv:
+
+```powershell
+uv add wau
+```
+
+## Testing
+
+Test dependencies are separated from runtime dependencies in `pyproject.toml`
+using the `test` dependency group.
+
+Run the test suite:
+
+```powershell
+uv run --group test python -m pytest -q
+```
+
+Run doctests:
+
+```powershell
+uv run --group test python -m doctest .\wau.py
+```
+
+## Publishing
+
+Build package artifacts:
+
+```powershell
+uv build
+```
+
+Validate metadata and README rendering:
+
+```powershell
+uvx twine check dist/*
+```
+
+Upload to TestPyPI first:
+
+```powershell
+uv publish --publish-url https://test.pypi.org/legacy/
+```
+
+Then publish to PyPI:
+
+```powershell
+uv publish
+```
+
+## License
+
+This project is licensed under GNU LGPL v3 or later (`LGPL-3.0-or-later`).
+
+If you distribute modified versions of this library, those library
+modifications must be published under the same license terms.

wau-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+wau.py,sha256=wQsoNvzvH6HFRBj8ZKIpKjT87_9aB-WfOi0kEt8pdCU,37026
+wau-0.1.0.dist-info/licenses/LICENSE,sha256=5lfLO8VaZisSCb3xtnOUdjX26TYX52CYXYRVUJsSzUk,500
+wau-0.1.0.dist-info/METADATA,sha256=bm0_c9LKeic0-u1efpcsK2YvduO8yVgHtNKXq3Ak_dY,2172
+wau-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+wau-0.1.0.dist-info/top_level.txt,sha256=xH8uF0IWDusYlJBXD4LSHfJLMSsa-Yyj0_2I26TAJQQ,4
+wau-0.1.0.dist-info/RECORD,,

wau-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wau-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,14 @@
+GNU LESSER GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+This project is licensed under the GNU Lesser General Public License,
+version 3 or (at your option) any later version.
+
+For the full license text, see:
+https://www.gnu.org/licenses/lgpl-3.0.txt
+
+SPDX-License-Identifier: LGPL-3.0-or-later

wau-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+wau

wau.py

@@ -0,0 +1,1095 @@
+import collections
+import datetime
+import functools
+import inspect
+import itertools
+import json
+import queue
+import re
+import sys
+import threading
+import traceback
+import urllib.parse
+
+import werkzeug
+from werkzeug.exceptions import (
+    HTTPException,
+    NotFound,
+    Unauthorized,
+    UnprocessableEntity,
+    UnsupportedMediaType,
+)
+from werkzeug.middleware.dispatcher import DispatcherMiddleware
+from werkzeug.routing import Map, Rule
+from werkzeug.security import check_password_hash
+
+try:
+    import jwt
+except ImportError:
+    # Do not complain now, but only when auth classes get instantiated
+    jwt = None
+
+
+class API:
+    """An API speaking in JSON with the outside world.
+
+    Here is a very simple first API:
+    >>> app = API()
+    >>> @app.GET("/hello")
+    ... def root(request):
+    ...     return "Hello World"
+    ...
+    >>> from werkzeug.test import Client
+    >>> client = Client(app)
+    >>> response = client.get('/hello')
+    >>> response.get_json()
+    'Hello World'
+
+    The `request` parameter must be called `request` and must be the first
+    parameter of the handler function, but it can be omitted if not needed.
+
+    So, here is a even simpler version of the above code:
+    >>> @app.GET("/hello_again")
+    ... def root():
+    ...     return "Hello again!"
+    ...
+    >>> response = client.get('/hello_again')
+    >>> response.get_json()
+    'Hello again!'
+
+    URL paths can be parametrized:
+    >>> @app.register("GET", "/user/{id}")
+    ... def home(id):
+    ...     return f"Welcome home {id}!"
+    ...
+    >>> response = client.get("/user/007")
+    >>> response.status
+    '200 OK'
+    >>> response.get_json()
+    'Welcome home 007!'
+
+    Path parameters can be typed:
+    >>> @app.register("GET", "/agent/{id:int}")
+    ... def home(id):
+    ...     return f"Welcome home {id}! You're more than {id - 1}."
+    ...
+    >>> response = client.get("/agent/Bond")
+    >>> response.status
+    '404 NOT FOUND'
+    >>> response = client.get("/agent/007")
+    >>> response.status
+    '200 OK'
+    >>> response.get_json()
+    "Welcome home 7! You're more than 6."
+
+    Now with generic POST data: add a data parameter and optionally specify
+    it's type (default is dict)
+    >>> @app.POST("/")
+    ... def create(request, data:list):
+    ...     print(data)
+    ...
+    >>> response = client.post("/", json=[1, 2, 3])
+    [1, 2, 3]
+
+    >>> response = client.post("/", json={})
+    >>> response.status
+    '422 UNPROCESSABLE ENTITY'
+
+    And finally requesting a dict in the POST data with specified fields
+    (and types):
+
+    >>> @app.PUT("/")
+    ... def update(request, name, age:int, superhuman:bool=False):
+    ...     print(f"{name} is {age} years old.")
+    ...     print(f"{name} is {'' if superhuman else 'not '}superhuman.")
+    ...
+    >>> data = {"name": "Betsy", "age": 34}
+    >>> response = client.put("/", json=data)
+    Betsy is 34 years old.
+    Betsy is not superhuman.
+    >>> response.status
+    '200 OK'
+
+    >>> data = {"name": "Betsy"}
+    >>> response = client.put("/", json=data)
+    >>> response.status
+    '422 UNPROCESSABLE ENTITY'
+
+    >>> data = {"name": "Betsy", "age": "34"}
+    >>> response = client.put("/", json=data)
+    >>> response.status
+    '422 UNPROCESSABLE ENTITY'
+
+    >>> data = {"name": "Betsy", "age": 34, "superhuman": True}
+    >>> response = client.put("/", json=data)
+    Betsy is 34 years old.
+    Betsy is superhuman.
+    >>> response.status
+    '200 OK'
+
+    >>> data = {"name": "Betsy", "age": 34, "verysmart": True}
+    >>> response = client.put("/", json=data)
+    >>> response.status
+    '422 UNPROCESSABLE ENTITY'
+
+    >>> data = "This is not valid JSON"
+    >>> response = client.put("/", data=data)
+    >>> response.status
+    '415 UNSUPPORTED MEDIA TYPE'
+    """
+
+    def __init__(self):
+        self._url_map = Map()
+
+    def register(self, method, url, func=None):
+        """Register a route with a callback.
+
+        This function can be used either directly:
+
+        >>> api = API()
+        >>> api.register("GET", "/", func=lambda request: "Hello!")  # doctest: +ELLIPSIS
+        <function <lambda> at 0x...>
+
+        or as a decorator
+        >>> @api.register("GET", "/user/{id}")
+        ... def home(request, id):
+        ...     return f"Welcome home {id}!"
+        ...
+
+        To test it use the Client class.
+        >>> from werkzeug.test import Client
+        >>> client = Client(api)
+        >>> response = client.get("/")
+        >>> response.status
+        '200 OK'
+        >>> response.get_json()
+        'Hello!'
+        >>> response = client.get("/user/007")
+        >>> response.status
+        '200 OK'
+        >>> response.get_json()
+        'Welcome home 007!'
+
+        `url` accepts parametrized and optionally typed placeholders
+        (`{id}`, `{id:int}`).
+        """
+        if func is None:
+            return functools.partial(self.register, method, url)
+
+        url = _normalize_url_placeholders(url)
+
+        rule = Rule(url, methods=(method,))
+        Map([rule])  # Bind rule temporarily
+        url_params = rule.arguments
+
+        sig = inspect.signature(func)
+        params = sig.parameters
+        param_keys = list(sig.parameters.keys())
+
+        # The first argument can optionally be request, after that route params.
+        # Parameter order is ignored.
+        if param_keys and param_keys[0] == "request":
+            func_url_params = set(param_keys[1 : len(url_params) + 1])
+            body_params = param_keys[len(url_params) + 1 :]
+        else:
+            func_url_params = set(param_keys[: len(url_params)])
+            body_params = param_keys[len(url_params) :]
+
+        missmatch = url_params ^ func_url_params
+        if missmatch:
+            raise TypeError(
+                f"{func.__name__}() arguments and route parameter missmatch "
+                f"({func_url_params} != {url_params})"
+            )
+
+        body_type = None
+        if len(body_params) == 1 and body_params[0] == "data":
+            body_type = (
+                params["data"].annotation
+                if params["data"].annotation is not inspect.Parameter.empty
+                else dict
+            )
+            content_types = {}
+        elif body_params:
+            body_type = dict
+            content_types = {
+                key: params[key].annotation
+                for key in body_params
+                if params[key].annotation is not inspect.Parameter.empty
+            }
+
+        if body_type:
+            wrapped_func = _parse_json_body(func, body_type, content_types)
+        else:
+            wrapped_func = _simple_wrapper(func)
+
+        self._url_map.add(Rule(url, methods=(method,), endpoint=wrapped_func))
+        return func
+
+    def GET(self, string):
+        """Shorthand for registering GET requests.
+
+        Use as a decorator:
+        >>> api = API()
+        >>> @api.GET("/admin")
+        ... def admin_home(request):
+        ...     return "Nothing here"
+        ...
+        >>> from werkzeug.test import Client
+        >>> client = Client(api)
+        >>> client.get("/admin")
+        <TestResponse streamed [200 OK]>
+        """
+        return self.register("GET", string)
+
+    def POST(self, string):
+        """Shorthand for registering POST requests."""
+        return self.register("POST", string)
+
+    def PUT(self, string):
+        """Shorthand for registering PUT requests."""
+        return self.register("PUT", string)
+
+    def PATCH(self, string):
+        """Shorthand for registering PATCH requests."""
+        return self.register("PATCH", string)
+
+    def DELETE(self, string):
+        """Shorthand for registering DELETE requests."""
+        return self.register("DELETE", string)
+
+    def __call__(self, environ, start_response):
+        try:
+            request = werkzeug.Request(environ)
+            adapter = self._url_map.bind_to_environ(environ)
+            endpoint, values = adapter.match()
+
+            # Dispatch request
+            response = endpoint(request, **values)
+            if not callable(response):
+                response = _json_response(response)
+            return response(environ, start_response)
+        except HTTPException as e:
+            response = _json_response(
+                {"code": e.code, "name": e.name, "description": e.description},
+                status=e.code,
+            )
+        except Exception as e:
+            response = _json_response(
+                {"code": 500, "name": "Internal Server Error"}, status=500
+            )
+            err = environ["wsgi.errors"]
+            print(f"ERROR {e.__class__.__name__}: {str(e)}", file=err)
+            traceback.print_exc(file=err)
+        return response(environ, start_response)
+
+
+def _json_response(data, status=200):
+    if data is None:
+        return werkzeug.Response(status=status)
+    elif isinstance(data, werkzeug.Response):
+        # Already a response object — pass through as-is
+        return data
+    else:
+        data = json.dumps(data, indent=2, default=str) + "\n"
+        return werkzeug.Response(data, status=status, mimetype="application/json")
+
+
+def _simple_wrapper(func):
+    sig = inspect.signature(func)
+
+    @functools.wraps(func)
+    def wrapper(request, *args, **kwargs):
+        if sig.parameters and list(sig.parameters.keys())[0] == "request":
+            args = (request,) + args
+        elif request.data:
+            raise UnsupportedMediaType("No request body allowed")
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def _normalize_url_placeholders(url):
+    """Convert readable URL placeholders to Werkzeug form.
+
+    Examples:
+      `{id}`      -> `<id>`
+      `{id:int}`  -> `<int:id>`
+    """
+    for orig, contents in re.findall(r"(\{([^\}\{]+)\})", url):
+        if ":" in contents:
+            contents = ":".join(reversed(contents.split(":")))
+        url = url.replace(orig, f"<{contents}>")
+    return url
+
+
+def _check_value(key, value, value_type):
+    if value_type is bool and (value is True or value is False):
+        return value
+    elif value_type == float and isinstance(value, int):
+        return float(value)
+    if isinstance(value_type, type) and isinstance(value, value_type):
+        return value
+    elif (
+        isinstance(value, str)
+        and callable(value_type)
+        and value_type not in (bool, int, float, str, list, dict)
+    ):
+        func = value_type
+        try:
+            return func(value)
+        except ValueError:
+            raise UnprocessableEntity(
+                f"Invalid format: '{key}' cannot be converted to {func.__name__}."
+            )
+    else:
+        raise UnprocessableEntity(
+            f"Invalid format: '{key}' must be of type {value_type.__name__}."
+        )
+
+
+def _parse_json_body(func=None, body_type=dict, content_types={}):  # noqa: C901
+    if func is None:
+        return functools.partial(
+            _parse_json_body, body_type=body_type, content_types=content_types
+        )
+
+    sig = inspect.signature(func)
+
+    @functools.wraps(func)
+    def wrapper(request, *args, **kwargs):
+        try:
+            data = str(request.data, "utf-8").strip()
+        except UnicodeDecodeError:
+            raise UnsupportedMediaType("Cannot parse request body: invalid UTF-8 data")
+
+        if not data:
+            raise UnsupportedMediaType("Cannot parse request body: no data supplied")
+
+        try:
+            data = json.loads(data)
+        except json.decoder.JSONDecodeError:
+            raise UnsupportedMediaType("Cannot parse request body: invalid JSON")
+
+        if body_type is not None and not isinstance(data, body_type):
+            raise UnprocessableEntity(
+                f"Invalid data format: {body_type.__name__} expected"
+            )
+
+        if sig.parameters and list(sig.parameters.keys())[0] == "request":
+            args = (request,) + args
+
+        if body_type == dict and content_types:
+            too_many = data.keys() - (sig.parameters.keys() - kwargs.keys())
+            if too_many:
+                raise UnprocessableEntity(f"Key not allowed: {', '.join(too_many)}")
+
+            kwargs.update(data)
+            bound = sig.bind_partial(*args, **kwargs)
+
+            for key, value in bound.arguments.items():
+                if key in content_types:
+                    bound.arguments[key] = _check_value(key, value, content_types[key])
+
+            bound.apply_defaults()
+
+            missing = sig.parameters.keys() - bound.arguments.keys()
+            if missing:
+                raise UnprocessableEntity(f"Key missing: {', '.join(missing)}")
+
+        else:
+            kwargs["data"] = data
+
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def timestamp(string=None):
+    """Parse JS date strings to datetime objects.
+
+    Returns the current datetime (now), if called with no argument.
+
+    `timestamp` returns UTC timestamps.
+
+    Example usage:
+
+    To convert a JS timestamp, create one in the browser or in node:
+    > let now = new Date()
+    > JSON.stringify(now)
+    '"2020-12-09T23:44:53.782Z"'
+
+    Convert the value to a native Python datetime object:
+    >>> timestamp(json.loads('"2020-12-09T23:44:53.782Z"'))
+    datetime.datetime(2020, 12, 9, 23, 44, 53, 782000, tzinfo=datetime.timezone.utc)
+
+    To get the current time:
+    >>> timestamp()                                         # doctest: +ELLIPSIS
+    datetime.datetime(2..., tzinfo=datetime.timezone.utc)
+
+    This function can be used as an annotation in request handlers:
+    >>> api = API()
+    >>> @api.POST("/reminder")
+    ... def reminder(request, date:timestamp, text:str):
+    ...     pass
+    ...
+    """
+    if string is not None:
+        return datetime.datetime.fromisoformat(string.replace("Z", "+00:00"))
+    else:
+        return datetime.datetime.now().astimezone(datetime.timezone.utc)
+
+
+def _cors_same_host_middleware(app, allowed_host):
+    allowed_host = allowed_host.lower().strip()
+
+    def _origin_for_host(origin):
+        try:
+            parsed = urllib.parse.urlparse(origin)
+        except ValueError:
+            return None
+
+        if not parsed.scheme or not parsed.hostname:
+            return None
+
+        if parsed.hostname.lower() == allowed_host:
+            return origin
+        return None
+
+    def _append_vary_origin(headers):
+        for index, (key, value) in enumerate(headers):
+            if key.lower() == "vary":
+                vary_values = {v.strip().lower() for v in value.split(",") if v.strip()}
+                if "origin" not in vary_values:
+                    headers[index] = (key, f"{value}, Origin")
+                return
+        headers.append(("Vary", "Origin"))
+
+    def wrapped(environ, start_response):
+        origin = environ.get("HTTP_ORIGIN", "")
+        allowed_origin = _origin_for_host(origin)
+        is_preflight = (
+            environ.get("REQUEST_METHOD") == "OPTIONS"
+            and "HTTP_ACCESS_CONTROL_REQUEST_METHOD" in environ
+        )
+
+        if is_preflight and allowed_origin:
+            requested_headers = environ.get("HTTP_ACCESS_CONTROL_REQUEST_HEADERS", "")
+            headers = [
+                ("Access-Control-Allow-Origin", allowed_origin),
+                (
+                    "Access-Control-Allow-Methods",
+                    "GET, POST, PUT, PATCH, DELETE, OPTIONS",
+                ),
+                (
+                    "Access-Control-Allow-Headers",
+                    (
+                        requested_headers
+                        if requested_headers
+                        else "Content-Type, Authorization"
+                    ),
+                ),
+                ("Access-Control-Max-Age", "86400"),
+            ]
+            _append_vary_origin(headers)
+            response = werkzeug.Response(status=204, headers=headers)
+            return response(environ, start_response)
+
+        def cors_start_response(status, headers, exc_info=None):
+            if allowed_origin:
+                headers = list(headers)
+                headers.append(("Access-Control-Allow-Origin", allowed_origin))
+                _append_vary_origin(headers)
+            return start_response(status, headers, exc_info)
+
+        return app(environ, cors_start_response)
+
+    return wrapped
+
+
+class BaseJWTAuthMiddleware:
+    """Middleware authorizing access to chained application using JWT.
+
+    Attention: Authentication must be provided.
+
+    This middleware exposes two endpoints:
+     - /auth/login  for generating new tokens.
+     - /auth/renew  for renewing an existing token
+
+    Tokens are short-lived and are valid for only 15 minutes, but expired tokens
+    can be renewed during one week starting from their initial issuing date.
+
+    Upon successful authentication the username is stored in the WSGI environment,
+    and can be retrieved from Werkzeug's Request object: `request.remote_user`
+    """
+
+    def __init__(
+        self,
+        app,
+        secret,
+        *,
+        exempt=[],
+        prefix="/auth",
+        login_methods=("POST",),
+    ):
+        if jwt is None:
+            print("WARNING: No module named 'jwt'", file=sys.stderr)
+            print("Cannot perform authentication without PyJWT", file=sys.stderr)
+            print("Run `pip install PyJWT` to fix this", file=sys.stderr)
+            raise ModuleNotFoundError("No module named 'jwt'")
+
+        auth_api = API()
+        for method in login_methods:
+            auth_api.register(method, "/login", func=functools.partial(self._login))
+        auth_api.register("POST", "/renew", func=functools.partial(self._renew))
+
+        self.app = DispatcherMiddleware(app, {prefix: auth_api})
+
+        prefix = prefix.rstrip("/")
+        exempt_map = Map()
+        for method, path, *_ in exempt:
+            exempt_map.add(
+                Rule(
+                    _normalize_url_placeholders(path),
+                    methods=(method.upper(),),
+                    endpoint=True,
+                )
+            )
+        for method in login_methods:
+            exempt_map.add(
+                Rule(prefix + "/login", methods=(method.upper(),), endpoint=True)
+            )
+        exempt_map.add(Rule(prefix + "/renew", methods=("POST",), endpoint=True))
+        self._exempt_map = exempt_map
+
+        self.secret = secret
+
+    def __call__(self, environ, start_response):
+        try:
+            if not self._is_exempt(environ):
+                # Check authorization (throws an exception if it fails)
+                username = self._check_authorization(environ)
+                assert isinstance(username, str)
+                assert username != ""
+                del environ["HTTP_AUTHORIZATION"]
+                environ["REMOTE_USER"] = username
+            return self.app(environ, start_response)
+        except HTTPException as e:
+            response = _json_response(
+                {"code": e.code, "name": e.name, "description": e.description},
+                status=e.code,
+            )
+        except Exception as e:
+            response = _json_response(
+                {"code": 500, "name": "Internal Server Error"}, status=500
+            )
+            err = environ["wsgi.errors"]
+            print(f"ERROR {e.__class__.__name__}: {str(e)}", file=err)
+            traceback.print_exc(file=err)
+
+        return response(environ, start_response)
+
+    def _is_exempt(self, environ):
+        """Return whether the request matches a registered exempt rule."""
+        adapter = self._exempt_map.bind_to_environ(environ)
+        try:
+            adapter.match()
+            return True
+        except HTTPException:
+            return False
+
+    def _check_authorization(self, environ):
+        """Verify request authorization header.
+
+        Returns username if authorization passed.
+
+        Raises a 401 Unauthorized exception if authorization failed.
+        """
+        if "HTTP_AUTHORIZATION" not in environ:
+            raise Unauthorized("No authorization header supplied")
+
+        auth = environ["HTTP_AUTHORIZATION"]
+
+        if not auth.startswith("Bearer "):
+            raise Unauthorized("Invalid authorization header")
+
+        token = auth[len("Bearer ") :]
+        try:
+            claims = jwt.decode(
+                token,
+                self.secret,
+                algorithms=["HS256"],
+                options={"require_exp": True, "require_iat": True},
+            )
+        except jwt.ExpiredSignatureError:
+            raise Unauthorized("Expired token")
+        except jwt.InvalidTokenError:
+            raise Unauthorized("Invalid token")
+        return claims["username"]
+
+    def _login(self, request):
+        username = self.authenticate(request)
+        if username is None:
+            raise Unauthorized("User authentication failed")
+        now = datetime.datetime.now(datetime.UTC)
+        claims = {
+            "username": username,
+            "iat": now,
+            "exp": now + datetime.timedelta(minutes=15),
+        }
+        token = jwt.encode(claims, self.secret, algorithm="HS256")
+
+        return {"token": token}
+
+    def _renew(self, request, token: str):
+        now = datetime.datetime.now(datetime.UTC)
+        try:
+            # Valid tokens can always be renewed within their short lifetime,
+            # independent of the issuing date
+            claims = jwt.decode(
+                token,
+                self.secret,
+                algorithms=["HS256"],
+                options={"require_exp": True, "require_iat": True},
+            )
+        except jwt.ExpiredSignatureError:
+            # Expired tokens can be renewed for at most one week after the
+            # first issuing date
+            claims = jwt.decode(
+                token,
+                self.secret,
+                algorithms=["HS256"],
+                options={
+                    "require_exp": True,
+                    "require_iat": True,
+                    "verify_exp": False,
+                },
+            )
+            issued_at = datetime.datetime.fromtimestamp(claims["iat"], tz=datetime.UTC)
+            if issued_at + datetime.timedelta(days=7) < now:
+                raise Unauthorized("Unrenewable expired token")
+        except jwt.InvalidTokenError:
+            raise Unauthorized("Invalid token")
+
+        claims["exp"] = now + datetime.timedelta(minutes=15)
+
+        token = jwt.encode(claims, self.secret, algorithm="HS256")
+
+        return {"token": token}
+
+    def authenticate(self, request):
+        """Authenticate user.
+
+        Returns a user identification string (usually the username) if
+        authentication passed, None otherwise.  This method must be
+        overwritten in an implementing subclass.
+        """
+        raise NotImplementedError()
+
+
+class ExternalAuth(BaseJWTAuthMiddleware):
+    """Rely on external authentication.
+
+    The username of an authenticated user must be passed with the
+    `REMOTE_USER` key in the wsgi environment.
+    """
+
+    def __init__(self, *args, login_methods=("GET", "POST"), **kwargs):
+        super().__init__(*args, login_methods=login_methods, **kwargs)
+
+    def authenticate(self, request):
+        return request.remote_user
+
+
+class DummyAuth(BaseJWTAuthMiddleware):
+    """Dummy authenticator for testing and development.
+
+    Login always passes and always returns "dummyuser" as username.
+
+    Here is an example session:
+
+    Create an API:
+    >>> api = API()
+    >>> @api.GET("/")
+    ... def root(request):
+    ...     return "Hello World"
+    ...
+
+    Wrap it with an authentication/authorization layer:
+    >>> app = DummyAuth(api, "not a secret but still quite long")
+
+    >>> from werkzeug.test import Client
+    >>> client = Client(app)
+
+    By default, access is denied:
+    >>> client.get("/")
+    <TestResponse streamed [401 UNAUTHORIZED]>
+
+    Login to get a token:
+    >>> response = client.post("/auth/login")
+    >>> response.status
+    '200 OK'
+    >>> token = response.get_json()["token"]
+    >>> token                                                      # doctest: +ELLIPSIS
+    'eyJ...'
+
+    Use the token to gain access:
+    >>> headers = {"Authorization": f"Bearer {token}"}
+    >>> client.get("/", headers=headers)
+    <TestResponse streamed [200 OK]>
+    """
+
+    def authenticate(self, request):
+        return "dummyuser"
+
+
+class UsernamePasswordAuth(BaseJWTAuthMiddleware):
+    """Authenticate with a username and password combination.
+
+    `dataset` user tables are supported natively. It must contain a unique
+    and identifiable `username` and a `password` column. Alternatively, a
+    custom password hash retrieval function may be specified.
+
+    Passwords are expected to be hashed using the PBKDF2 algorithm. Use
+    werkzeug's `werkzeug.security.generate_password_hash` function to generate
+    compatible password hashes.
+
+    Example usage:
+
+    Let's create a in-memory database with a user table containing one entry:
+    >>> import dataset
+    >>> from werkzeug.security import generate_password_hash
+    >>> db = dataset.connect("sqlite:///:memory:")
+    >>> db['user'].insert(dict(username="paul", password=generate_password_hash("john")))
+    1
+
+    Assemble a dummy application and client:
+    >>> app = UsernamePasswordAuth(API(), "not a secret but still quite long", user_table=db['user'])
+    >>> from werkzeug.test import Client
+    >>> client = Client(app)
+
+    Logging in with correct credentials is now possible:
+    >>> cred = {"username": "paul", "password": "john"}
+    >>> response = client.post("/auth/login", json=cred)
+    >>> response.status
+    '200 OK'
+    >>> response.get_json()["token"]         # doctest: +ELLIPSIS
+    'eyJ...'
+
+    Requests with invalid passwords fail:
+    >>> cred = {"username": "paul", "password": "george"}
+    >>> response = client.post("/auth/login", json=cred)
+    >>> response.status
+    '401 UNAUTHORIZED'
+
+    The same is true for non-existent users:
+    >>> cred = {"username": "yoko", "password": "john"}
+    >>> response = client.post("/auth/login", json=cred)
+    >>> response.status
+    '401 UNAUTHORIZED'
+    """
+
+    def __init__(
+        self,
+        app,
+        secret,
+        user_table=None,
+        find_password=None,
+        *,
+        exempt=[],
+        prefix="/auth",
+        login_methods=("POST",),
+    ):
+        """Initialize the authentication middleware.
+
+        The `user_table` argument is expected to be a dataset table containing
+        at least a unique identifying `username` and a `password` field.
+
+        Alternatively the `find_password` parameter expects a function taking
+        a username as argument, and returning the corresponding password hash.
+        The function must return None if the user or password cannot be found.
+
+        If both present, the `user_table` parameter takes precedence over
+        `find_password`.
+        """
+        super().__init__(
+            app, secret, exempt=exempt, prefix=prefix, login_methods=login_methods
+        )
+        if user_table is not None:
+
+            def user_table_find_password(username):
+                user = user_table.find_one(username=username)
+                if user:
+                    return user["password"]
+
+            self.find_password = user_table_find_password
+        elif find_password is not None:
+            self.find_password = find_password
+        else:
+            raise ValueError("One of 'user_table' and 'find_password' must be supplied")
+
+    def authenticate(self, request):
+        @_parse_json_body(content_types=dict(username=str, password=str))
+        def handler(request, username, password):
+            pw_hash = self.find_password(username)
+            if pw_hash and check_password_hash(pw_hash, password):
+                return username
+
+        return handler(request)
+
+
+def run(
+    app,
+    prefix=None,
+    port=3000,
+    hostname="localhost",
+    allow_cors_from_hostname=False,
+    use_reloader=True,
+):
+    """Run a wsgi application like an API.
+
+    Optionally specify a listening `port` (default: 3000) and a bind
+    `hostname` (default: localhost). Set the hostname to the empty string,
+    to listen on all interfaces.
+
+    CORS is disabled by default. If `allow_cors_from_hostname` is set to
+    `True`, requests from origins sharing the same hostname are allowed,
+    regardless of their port number.
+
+    `use_reloader` is forwarded to Werkzeug's development server.
+    """
+    if prefix is not None:
+        app = DispatcherMiddleware(NotFound, {prefix: app})
+
+    if allow_cors_from_hostname:
+        app = _cors_same_host_middleware(app, hostname)
+
+    werkzeug.run_simple(
+        hostname,
+        port,
+        app,
+        threaded=True,
+        use_reloader=use_reloader,
+    )
+
+
+Event = collections.namedtuple("Event", ["id", "event_type", "data"])
+
+
+class PubSub:
+    """Class implementing a publish/subscribe event passing scheme.
+
+    Basic example usage:
+    >>> chat = PubSub()
+    >>> subscription = chat.subscribe()
+    >>> chat.publish("message", "Hello")
+    >>> next(subscription)
+    Event(id=0, event_type='message', data='Hello')
+
+    Messages can be differentiated by topic:
+    >>> general_room = chat.subscribe(topic="general")
+    >>> nerd_room = chat.subscribe(topic="nerd")
+    >>> chat.publish("new_user", "guido", topic="nerd")
+    >>> chat.publish("message", "Hi geeks!", topic="nerd")
+    >>> chat.publish("message", "It is 12 am", topic="general")
+    >>> next(general_room)
+    Event(id=3, event_type='message', data='It is 12 am')
+    >>> next(nerd_room)
+    Event(id=1, event_type='new_user', data='guido')
+    >>> next(nerd_room)
+    Event(id=2, event_type='message', data='Hi geeks!')
+    """
+
+    def __init__(self):
+        self._main_lock = threading.Lock()
+        self._topic_locks = collections.defaultdict(threading.Lock)
+        self._queues = collections.defaultdict(set)
+        self._replay_log = collections.defaultdict(
+            lambda: collections.deque(maxlen=1_000)
+        )
+        self._current_id = itertools.count()
+
+    def publish(self, event_type, data, topic=None):
+        """Publish an event.
+
+        The event has an `event_type`, usually a string, and a `data` payload.
+        `data` can be free-formed, but should be JSON-serializable.
+
+        Optionally a topic can be specified. The message will be only forwarded
+        to subscribers interested in the specified topic.
+        """
+        with self._main_lock:
+            id = next(self._current_id)
+            queues = self._queues[topic]
+            replay_log = self._replay_log[topic]
+            topic_lock = self._topic_locks[topic]
+
+        to_remove = []
+        event = Event(id, event_type, data)
+
+        with topic_lock:
+            replay_log.append(event)
+
+            for q in queues:
+                try:
+                    q.put_nowait(event)
+                except queue.Full:  # Somebody fell asleep?!?
+                    to_remove.append(q)
+
+            for q in to_remove:
+                try:
+                    queues.remove(q)
+                except KeyError:
+                    pass
+
+    def broadcast(self, event_type, data):
+        """Broadcast event to all subscribers."""
+        with self._main_lock:
+            topics = list(self._queues.keys())
+
+        for topic in topics:
+            self.publish(event_type, data, topic)
+
+    def subscribe(self, topic=None):
+        """Subscribe to published events.
+
+        Events are returned as triples, containing a unique event `id`, the
+        `event_type`, and the payload `data`.
+
+        Optionally a specific `topic` can be specified.
+        """
+        q = queue.Queue(100)
+        with self._main_lock:
+            queues = self._queues[topic]
+            topic_lock = self._topic_locks[topic]
+
+        with topic_lock:
+            queues.add(q)
+
+        def iterator():
+            try:
+                while q in queues:
+                    try:
+                        yield q.get(timeout=60)
+                    except queue.Empty:
+                        pass
+            except GeneratorExit:
+                try:
+                    with topic_lock:
+                        queues.remove(q)
+                except KeyError:
+                    pass
+
+        return iterator()
+
+    def _event_stream(self, replay_events=(), topic=None):
+        subscription = self.subscribe(topic)
+        for event in itertools.chain(replay_events, subscription):
+            yield (
+                f"id: {event.id}\n"
+                f"event: {event.event_type}\n"
+                f"data: {json.dumps(event.data, default=str)}\n\n"
+            ).encode("utf-8")
+
+    def _replay_events(self, last_id, topic=None):
+        if last_id is None:
+            return ()
+
+        last_id = int(last_id)
+
+        with self._main_lock:
+            replay_log = self._replay_log[topic]
+            topic_lock = self._topic_locks[topic]
+
+        with topic_lock:
+            log_iter = iter(replay_log)
+            for event in log_iter:
+                if event.id == last_id:
+                    break
+            else:
+                raise ValueError(f"{last_id} is not in event log")
+            return list(log_iter)
+
+    def streaming_response(self, request, topic=None):
+        """Generate a streaming HTTP response with server-sent events.
+
+        See https://html.spec.whatwg.org/multipage/server-sent-events.html
+        for more information about server-sent events.
+
+        When reconnecting after losing the connection for a while, browsers
+        automatically set the `Last-Event-ID` header field to the value of
+        the id of the last received event. The response will first replay
+        missed events, before sending newly arriving events. When the event
+        specified by `Last-Event-ID` is not found, a 404 Not Found response
+        is sent, signalling to the browser, that a clean recovery is not
+        possible.
+
+        Here is an example session. First, let us create an API:
+        >>> api = API()
+        >>> chat = PubSub()
+        >>> @api.POST("/")
+        ... def post_message(request, message:str):
+        ...     chat.publish("message", message)
+        ...
+        >>> @api.GET("/")
+        ... def stream(request):
+        ...     return chat.streaming_response(request)
+        ...
+
+        We can now post messages and see them appear in our subscription:
+        >>> subscription = chat.subscribe()
+        >>> from werkzeug.test import Client
+        >>> client = Client(api)
+        >>> resp = client.post("/", json={"message": "hello"})
+        >>> resp = client.post("/", json={"message": "everybody"})
+        >>> next(subscription)
+        Event(id=0, event_type='message', data='hello')
+        >>> next(subscription)
+        Event(id=1, event_type='message', data='everybody')
+
+        Now, let's simulate a reconnecting browser that only got the first
+        message:
+        >>> response = client.get("/", headers={"Last-Event-ID": "0"})
+        >>> response.status
+        '200 OK'
+        >>> body = iter(response.response)
+
+        The events are formatted according to the specification for server-sent
+        events:
+        >>> print(str(next(body), encoding="utf-8").strip())
+        id: 1
+        event: message
+        data: "everybody"
+
+        Further incoming messages are sent to the listening client, without
+        closing the connection:
+        >>> resp = client.post("/", json={"message": "howdoyoudo?"})
+        >>> print(str(next(body), encoding="utf-8").strip())
+        id: 2
+        event: message
+        data: "howdoyoudo?"
+        """
+        last_id = request.headers.get("Last-Event-ID", None)
+        try:
+            replay_events = self._replay_events(last_id)
+        except ValueError:
+            raise NotFound()
+
+        return werkzeug.Response(
+            self._event_stream(replay_events, topic), mimetype="text/event-stream"
+        )
+
+
+__all__ = (
+    "API",
+    "NotFound",
+    "Unauthorized",
+    "UnprocessableEntity",
+    "timestamp",
+    "BaseJWTAuthMiddleware",
+    "ExternalAuth",
+    "DummyAuth",
+    "UsernamePasswordAuth",
+    "run",
+    "PubSub",
+)