From 654b652530bb7274ec5dc033375e175f81cb42b1 Mon Sep 17 00:00:00 2001 From: Sarah Hoffmann Date: Tue, 24 Jan 2023 21:04:32 +0100 Subject: [PATCH] factor out common server implementation code Most of the server implementation of V1 API now resides in api.v1.server_glue. The webframeworks only supply some glue code which is independent to changes in the API code. --- nominatim/api/v1/__init__.py | 6 ++ nominatim/api/v1/server_glue.py | 153 +++++++++++++++++++++++++++ nominatim/server/falcon/server.py | 80 +++++++------- nominatim/server/sanic/server.py | 77 ++++++-------- nominatim/server/starlette/server.py | 62 +++++------ 5 files changed, 254 insertions(+), 124 deletions(-) create mode 100644 nominatim/api/v1/server_glue.py diff --git a/nominatim/api/v1/__init__.py b/nominatim/api/v1/__init__.py index c83562d1..8c00af2d 100644 --- a/nominatim/api/v1/__init__.py +++ b/nominatim/api/v1/__init__.py @@ -8,6 +8,12 @@ Implementation of API version v1 (aka the legacy version). """ +#pylint: disable=useless-import-alias + +from nominatim.api.v1.server_glue import (ASGIAdaptor as ASGIAdaptor, + EndpointFunc as EndpointFunc, + ROUTES as ROUTES) + import nominatim.api.v1.format as _format list_formats = _format.dispatch.list_formats diff --git a/nominatim/api/v1/server_glue.py b/nominatim/api/v1/server_glue.py new file mode 100644 index 00000000..7444b7aa --- /dev/null +++ b/nominatim/api/v1/server_glue.py @@ -0,0 +1,153 @@ +# SPDX-License-Identifier: GPL-2.0-only +# +# This file is part of Nominatim. (https://nominatim.org) +# +# Copyright (C) 2023 by the Nominatim developer community. +# For a full list of authors see the git log. +""" +Generic part of the server implementation of the v1 API. +Combine with the scaffolding provided for the various Python ASGI frameworks. +""" +from typing import Optional, Any, Type, Callable +import abc + +import nominatim.api as napi +from nominatim.api.v1.format import dispatch as formatting + +CONTENT_TYPE = { + 'text': 'text/plain; charset=utf-8', + 'xml': 'text/xml; charset=utf-8', + 'jsonp': 'application/javascript' +} + + +class ASGIAdaptor(abc.ABC): + """ Adapter class for the different ASGI frameworks. + Wraps functionality over concrete requests and responses. + """ + + @abc.abstractmethod + def get(self, name: str, default: Optional[str] = None) -> Optional[str]: + """ Return an input parameter as a string. If the parameter was + not provided, return the 'default' value. + """ + + @abc.abstractmethod + def get_header(self, name: str, default: Optional[str] = None) -> Optional[str]: + """ Return a HTTP header parameter as a string. If the parameter was + not provided, return the 'default' value. + """ + + + @abc.abstractmethod + def error(self, msg: str) -> Exception: + """ Construct an appropriate exception from the given error message. + The exception must result in a HTTP 400 error. + """ + + + @abc.abstractmethod + def create_response(self, status: int, output: str, content_type: str) -> Any: + """ Create a response from the given parameters. The result will + be returned by the endpoint functions. The adaptor may also + return None when the response is created internally with some + different means. + + The response must return the HTTP given status code 'status', set + the HTTP content-type headers to the string provided and the + body of the response to 'output'. + """ + + + def build_response(self, output: str, media_type: str, status: int = 200) -> Any: + """ Create a response from the given output. Wraps a JSONP function + around the response, if necessary. + """ + if media_type == 'json' and status == 200: + jsonp = self.get('json_callback') + if jsonp is not None: + if any(not part.isidentifier() for part in jsonp.split('.')): + raise self.error('Invalid json_callback value') + output = f"{jsonp}({output})" + media_type = 'jsonp' + + return self.create_response(status, output, + CONTENT_TYPE.get(media_type, 'application/json')) + + + def get_int(self, name: str, default: Optional[int] = None) -> int: + """ Return an input parameter as an int. Raises an exception if + the parameter is given but not in an integer format. + + If 'default' is given, then it will be returned when the parameter + is missing completely. When 'default' is None, an error will be + raised on a missing parameter. + """ + value = self.get(name) + + if value is None: + if default is not None: + return default + + raise self.error(f"Parameter '{name}' missing.") + + try: + return int(value) + except ValueError as exc: + raise self.error(f"Parameter '{name}' must be a number.") from exc + + + def get_bool(self, name: str, default: Optional[bool] = None) -> bool: + """ Return an input parameter as bool. Only '0' is accepted as + an input for 'false' all other inputs will be interpreted as 'true'. + + If 'default' is given, then it will be returned when the parameter + is missing completely. When 'default' is None, an error will be + raised on a missing parameter. + """ + value = self.get(name) + + if value is None: + if default is not None: + return default + + raise self.error(f"Parameter '{name}' missing.") + + return value != '0' + + +def parse_format(params: ASGIAdaptor, result_type: Type[Any], default: str) -> str: + """ Get and check the 'format' parameter and prepare the formatter. + `fmtter` is a formatter and `default` the + format value to assume when no parameter is present. + """ + fmt = params.get('format', default=default) + assert fmt is not None + + if not formatting.supports_format(result_type, fmt): + raise params.error("Parameter 'format' must be one of: " + + ', '.join(formatting.list_formats(result_type))) + + return fmt + + +async def status_endpoint(api: napi.NominatimAPIAsync, params: ASGIAdaptor) -> Any: + """ Server glue for /status endpoint. See API docs for details. + """ + result = await api.status() + + fmt = parse_format(params, napi.StatusResult, 'text') + + if fmt == 'text' and result.status: + status_code = 500 + else: + status_code = 200 + + return params.build_response(formatting.format_result(result, fmt), fmt, + status=status_code) + +EndpointFunc = Callable[[napi.NominatimAPIAsync, ASGIAdaptor], Any] + +ROUTES = [ + ('status', status_endpoint) +] diff --git a/nominatim/server/falcon/server.py b/nominatim/server/falcon/server.py index 62b56770..ddbd2ca6 100644 --- a/nominatim/server/falcon/server.py +++ b/nominatim/server/falcon/server.py @@ -7,70 +7,66 @@ """ Server implementation using the falcon webserver framework. """ -from typing import Type, Any, Optional, Mapping +from typing import Optional, Mapping, cast from pathlib import Path import falcon -import falcon.asgi +from falcon.asgi import App, Request, Response -from nominatim.api import NominatimAPIAsync, StatusResult +from nominatim.api import NominatimAPIAsync import nominatim.api.v1 as api_impl -CONTENT_TYPE = { - 'text': falcon.MEDIA_TEXT, - 'xml': falcon.MEDIA_XML -} -class NominatimV1: - """ Implementation of V1 version of the Nominatim API. +class ParamWrapper(api_impl.ASGIAdaptor): + """ Adaptor class for server glue to Falcon framework. """ - def __init__(self, project_dir: Path, environ: Optional[Mapping[str, str]]) -> None: - self.api = NominatimAPIAsync(project_dir, environ) + def __init__(self, req: Request, resp: Response) -> None: + self.request = req + self.response = resp - def parse_format(self, req: falcon.asgi.Request, rtype: Type[Any], default: str) -> None: - """ Get and check the 'format' parameter and prepare the formatter. - `rtype` describes the expected return type and `default` the - format value to assume when no parameter is present. - """ - req.context.format = req.get_param('format', default=default) + def get(self, name: str, default: Optional[str] = None) -> Optional[str]: + return cast(Optional[str], self.request.get_param(name, default=default)) - if not api_impl.supports_format(rtype, req.context.format): - raise falcon.HTTPBadRequest( - description="Parameter 'format' must be one of: " + - ', '.join(api_impl.list_formats(rtype))) + def get_header(self, name: str, default: Optional[str] = None) -> Optional[str]: + return cast(Optional[str], self.request.get_header(name, default=default)) - def format_response(self, req: falcon.asgi.Request, resp: falcon.asgi.Response, - result: Any) -> None: - """ Render response into a string according to the formatter - set in `parse_format()`. - """ - resp.text = api_impl.format_result(result, req.context.format) - resp.content_type = CONTENT_TYPE.get(req.context.format, falcon.MEDIA_JSON) + def error(self, msg: str) -> falcon.HTTPBadRequest: + return falcon.HTTPBadRequest(description=msg) + + + def create_response(self, status: int, output: str, content_type: str) -> None: + self.response.status = status + self.response.text = output + self.response.content_type = content_type - async def on_get_status(self, req: falcon.asgi.Request, resp: falcon.asgi.Response) -> None: - """ Implementation of status endpoint. - """ - self.parse_format(req, StatusResult, 'text') - result = await self.api.status() +class EndpointWrapper: + """ Converter for server glue endpoint functions to Falcon request handlers. + """ + + def __init__(self, func: api_impl.EndpointFunc, api: NominatimAPIAsync) -> None: + self.func = func + self.api = api - self.format_response(req, resp, result) - if result.status and req.context.format == 'text': - resp.status = 500 + + async def on_get(self, req: Request, resp: Response) -> None: + """ Implementation of the endpoint. + """ + await self.func(self.api, ParamWrapper(req, resp)) def get_application(project_dir: Path, - environ: Optional[Mapping[str, str]] = None) -> falcon.asgi.App: - """ Create a Nominatim falcon ASGI application. + environ: Optional[Mapping[str, str]] = None) -> App: + """ Create a Nominatim Falcon ASGI application. """ - app = falcon.asgi.App() - - api = NominatimV1(project_dir, environ) + api = NominatimAPIAsync(project_dir, environ) - app.add_route('/status', api, suffix='status') + app = App() + for name, func in api_impl.ROUTES: + app.add_route('/' + name, EndpointWrapper(func, api)) return app diff --git a/nominatim/server/sanic/server.py b/nominatim/server/sanic/server.py index 8dd29b54..57b374d0 100644 --- a/nominatim/server/sanic/server.py +++ b/nominatim/server/sanic/server.py @@ -7,75 +7,58 @@ """ Server implementation using the sanic webserver framework. """ -from typing import Any, Optional, Mapping +from typing import Any, Optional, Mapping, Callable, cast, Coroutine from pathlib import Path -import sanic +from sanic import Request, HTTPResponse, Sanic +from sanic.exceptions import SanicException +from sanic.response import text as TextResponse -from nominatim.api import NominatimAPIAsync, StatusResult +from nominatim.api import NominatimAPIAsync import nominatim.api.v1 as api_impl -api = sanic.Blueprint('NominatimAPI') +class ParamWrapper(api_impl.ASGIAdaptor): + """ Adaptor class for server glue to Sanic framework. + """ -CONTENT_TYPE = { - 'text': 'text/plain; charset=utf-8', - 'xml': 'text/xml; charset=utf-8' -} + def __init__(self, request: Request) -> None: + self.request = request -def usage_error(msg: str) -> sanic.HTTPResponse: - """ Format the response for an error with the query parameters. - """ - return sanic.response.text(msg, status=400) + def get(self, name: str, default: Optional[str] = None) -> Optional[str]: + return cast(Optional[str], self.request.args.get(name, default)) -def api_response(request: sanic.Request, result: Any) -> sanic.HTTPResponse: - """ Render a response from the query results using the configured - formatter. - """ - body = api_impl.format_result(result, request.ctx.format) - return sanic.response.text(body, - content_type=CONTENT_TYPE.get(request.ctx.format, - 'application/json')) - - -@api.on_request # type: ignore[misc] -async def extract_format(request: sanic.Request) -> Optional[sanic.HTTPResponse]: - """ Get and check the 'format' parameter and prepare the formatter. - `ctx.result_type` describes the expected return type and - `ctx.default_format` the format value to assume when no parameter - is present. - """ - assert request.route is not None - request.ctx.format = request.args.get('format', request.route.ctx.default_format) - if not api_impl.supports_format(request.route.ctx.result_type, request.ctx.format): - return usage_error("Parameter 'format' must be one of: " + - ', '.join(api_impl.list_formats(request.route.ctx.result_type))) + def get_header(self, name: str, default: Optional[str] = None) -> Optional[str]: + return cast(Optional[str], self.request.headers.get(name, default)) - return None + def error(self, msg: str) -> SanicException: + return SanicException(msg, status_code=400) + + + def create_response(self, status: int, output: str, + content_type: str) -> HTTPResponse: + return TextResponse(output, status=status, content_type=content_type) -@api.get('/status', ctx_result_type=StatusResult, ctx_default_format='text') -async def status(request: sanic.Request) -> sanic.HTTPResponse: - """ Implementation of status endpoint. - """ - result = await request.app.ctx.api.status() - response = api_response(request, result) - if request.ctx.format == 'text' and result.status: - response.status = 500 +def _wrap_endpoint(func: api_impl.EndpointFunc)\ + -> Callable[[Request], Coroutine[Any, Any, HTTPResponse]]: + async def _callback(request: Request) -> HTTPResponse: + return cast(HTTPResponse, await func(request.app.ctx.api, ParamWrapper(request))) - return response + return _callback def get_application(project_dir: Path, - environ: Optional[Mapping[str, str]] = None) -> sanic.Sanic: + environ: Optional[Mapping[str, str]] = None) -> Sanic: """ Create a Nominatim sanic ASGI application. """ - app = sanic.Sanic("NominatimInstance") + app = Sanic("NominatimInstance") app.ctx.api = NominatimAPIAsync(project_dir, environ) - app.blueprint(api) + for name, func in api_impl.ROUTES: + app.add_route(_wrap_endpoint(func), f"/{name}", name=f"v1_{name}_simple") return app diff --git a/nominatim/server/starlette/server.py b/nominatim/server/starlette/server.py index 60a78a47..2bf569ed 100644 --- a/nominatim/server/starlette/server.py +++ b/nominatim/server/starlette/server.py @@ -7,7 +7,7 @@ """ Server implementation using the starlette webserver framework. """ -from typing import Any, Type, Optional, Mapping +from typing import Any, Optional, Mapping, Callable, cast, Coroutine from pathlib import Path from starlette.applications import Starlette @@ -16,58 +16,50 @@ from starlette.exceptions import HTTPException from starlette.responses import Response from starlette.requests import Request -from nominatim.api import NominatimAPIAsync, StatusResult +from nominatim.api import NominatimAPIAsync import nominatim.api.v1 as api_impl -CONTENT_TYPE = { - 'text': 'text/plain; charset=utf-8', - 'xml': 'text/xml; charset=utf-8' -} - -def parse_format(request: Request, rtype: Type[Any], default: str) -> None: - """ Get and check the 'format' parameter and prepare the formatter. - `rtype` describes the expected return type and `default` the - format value to assume when no parameter is present. +class ParamWrapper(api_impl.ASGIAdaptor): + """ Adaptor class for server glue to Starlette framework. """ - fmt = request.query_params.get('format', default=default) - if not api_impl.supports_format(rtype, fmt): - raise HTTPException(400, detail="Parameter 'format' must be one of: " + - ', '.join(api_impl.list_formats(rtype))) + def __init__(self, request: Request) -> None: + self.request = request - request.state.format = fmt + def get(self, name: str, default: Optional[str] = None) -> Optional[str]: + return self.request.query_params.get(name, default=default) -def format_response(request: Request, result: Any) -> Response: - """ Render response into a string according. - """ - fmt = request.state.format - return Response(api_impl.format_result(result, fmt), - media_type=CONTENT_TYPE.get(fmt, 'application/json')) + def get_header(self, name: str, default: Optional[str] = None) -> Optional[str]: + return self.request.headers.get(name, default) -async def on_status(request: Request) -> Response: - """ Implementation of status endpoint. - """ - parse_format(request, StatusResult, 'text') - result = await request.app.state.API.status() - response = format_response(request, result) - if request.state.format == 'text' and result.status: - response.status_code = 500 + def error(self, msg: str) -> HTTPException: + return HTTPException(400, detail=msg) + - return response + def create_response(self, status: int, output: str, content_type: str) -> Response: + return Response(output, status_code=status, media_type=content_type) -V1_ROUTES = [ - Route('/status', endpoint=on_status) -] +def _wrap_endpoint(func: api_impl.EndpointFunc)\ + -> Callable[[Request], Coroutine[Any, Any, Response]]: + async def _callback(request: Request) -> Response: + return cast(Response, await func(request.app.state.API, ParamWrapper(request))) + + return _callback + def get_application(project_dir: Path, environ: Optional[Mapping[str, str]] = None) -> Starlette: """ Create a Nominatim falcon ASGI application. """ - app = Starlette(debug=True, routes=V1_ROUTES) + routes = [] + for name, func in api_impl.ROUTES: + routes.append(Route(f"/{name}", endpoint=_wrap_endpoint(func))) + + app = Starlette(debug=True, routes=routes) app.state.API = NominatimAPIAsync(project_dir, environ) -- 2.39.5