diff --git a/src/nominatim_api/server/asgi_adaptor.py b/src/nominatim_api/server/asgi_adaptor.py new file mode 100644 index 00000000..9558fbd3 --- /dev/null +++ b/src/nominatim_api/server/asgi_adaptor.py @@ -0,0 +1,168 @@ +# SPDX-License-Identifier: GPL-3.0-or-later +# +# This file is part of Nominatim. (https://nominatim.org) +# +# Copyright (C) 2024 by the Nominatim developer community. +# For a full list of authors see the git log. +""" +Base abstraction for implementing based on different ASGI frameworks. +""" +from typing import Optional, Any, NoReturn, Callable +import abc +import math + +from ..config import Configuration +from .. import logging as loglib +from ..core import NominatimAPIAsync + +CONTENT_TEXT = 'text/plain; charset=utf-8' +CONTENT_XML = 'text/xml; charset=utf-8' +CONTENT_HTML = 'text/html; charset=utf-8' +CONTENT_JSON = 'application/json; charset=utf-8' + +CONTENT_TYPE = {'text': CONTENT_TEXT, 'xml': CONTENT_XML, 'debug': CONTENT_HTML} + +class ASGIAdaptor(abc.ABC): + """ Adapter class for the different ASGI frameworks. + Wraps functionality over concrete requests and responses. + """ + content_type: str = CONTENT_TEXT + + @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, status: int = 400) -> Exception: + """ Construct an appropriate exception from the given error message. + The exception must result in a HTTP error with the given status. + """ + + + @abc.abstractmethod + def create_response(self, status: int, output: str, num_results: int) -> 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'. + """ + + @abc.abstractmethod + def base_uri(self) -> str: + """ Return the URI of the original request. + """ + + + @abc.abstractmethod + def config(self) -> Configuration: + """ Return the current configuration object. + """ + + + 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 + + self.raise_error(f"Parameter '{name}' missing.") + + try: + intval = int(value) + except ValueError: + self.raise_error(f"Parameter '{name}' must be a number.") + + return intval + + + def get_float(self, name: str, default: Optional[float] = None) -> float: + """ Return an input parameter as a flaoting-point number. Raises an + exception if the parameter is given but not in an float 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 + + self.raise_error(f"Parameter '{name}' missing.") + + try: + fval = float(value) + except ValueError: + self.raise_error(f"Parameter '{name}' must be a number.") + + if math.isnan(fval) or math.isinf(fval): + self.raise_error(f"Parameter '{name}' must be a number.") + + return fval + + + 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 + + self.raise_error(f"Parameter '{name}' missing.") + + return value != '0' + + + def raise_error(self, msg: str, status: int = 400) -> NoReturn: + """ Raise an exception resulting in the given HTTP status and + message. The message will be formatted according to the + output format chosen by the request. + """ + if self.content_type == CONTENT_XML: + msg = f""" + + {status} + {msg} + + """ + elif self.content_type == CONTENT_JSON: + msg = f"""{{"error":{{"code":{status},"message":"{msg}"}}}}""" + elif self.content_type == CONTENT_HTML: + loglib.log().section('Execution error') + loglib.log().var_dump('Status', status) + loglib.log().var_dump('Message', msg) + msg = loglib.get_and_disable() + + raise self.error(msg, status) + + +EndpointFunc = Callable[[NominatimAPIAsync, ASGIAdaptor], Any] diff --git a/src/nominatim_api/server/falcon/server.py b/src/nominatim_api/server/falcon/server.py index bc9850b2..a81b9b07 100644 --- a/src/nominatim_api/server/falcon/server.py +++ b/src/nominatim_api/server/falcon/server.py @@ -18,6 +18,7 @@ from ...config import Configuration from ...core import NominatimAPIAsync from ... import v1 as api_impl from ... import logging as loglib +from ..asgi_adaptor import ASGIAdaptor, EndpointFunc class HTTPNominatimError(Exception): """ A special exception class for errors raised during processing. @@ -57,7 +58,7 @@ async def timeout_error_handler(req: Request, resp: Response, #pylint: disable=u resp.content_type = 'text/plain; charset=utf-8' -class ParamWrapper(api_impl.ASGIAdaptor): +class ParamWrapper(ASGIAdaptor): """ Adaptor class for server glue to Falcon framework. """ @@ -98,7 +99,7 @@ class EndpointWrapper: """ Converter for server glue endpoint functions to Falcon request handlers. """ - def __init__(self, name: str, func: api_impl.EndpointFunc, api: NominatimAPIAsync) -> None: + def __init__(self, name: str, func: EndpointFunc, api: NominatimAPIAsync) -> None: self.name = name self.func = func self.api = api diff --git a/src/nominatim_api/server/starlette/server.py b/src/nominatim_api/server/starlette/server.py index 5f5cf055..60a81321 100644 --- a/src/nominatim_api/server/starlette/server.py +++ b/src/nominatim_api/server/starlette/server.py @@ -24,9 +24,10 @@ from starlette.middleware.cors import CORSMiddleware from ...config import Configuration from ...core import NominatimAPIAsync from ... import v1 as api_impl +from ..asgi_adaptor import ASGIAdaptor, EndpointFunc from ... import logging as loglib -class ParamWrapper(api_impl.ASGIAdaptor): +class ParamWrapper(ASGIAdaptor): """ Adaptor class for server glue to Starlette framework. """ @@ -69,7 +70,7 @@ class ParamWrapper(api_impl.ASGIAdaptor): return cast(Configuration, self.request.app.state.API.config) -def _wrap_endpoint(func: api_impl.EndpointFunc)\ +def _wrap_endpoint(func: EndpointFunc)\ -> Callable[[Request], Coroutine[Any, Any, Response]]: async def _callback(request: Request) -> Response: return cast(Response, await func(request.app.state.API, ParamWrapper(request))) diff --git a/src/nominatim_api/v1/__init__.py b/src/nominatim_api/v1/__init__.py index 87e8e1c5..c7f150f0 100644 --- a/src/nominatim_api/v1/__init__.py +++ b/src/nominatim_api/v1/__init__.py @@ -10,9 +10,7 @@ Implementation of API version v1 (aka the legacy version). #pylint: disable=useless-import-alias -from .server_glue import (ASGIAdaptor as ASGIAdaptor, - EndpointFunc as EndpointFunc, - ROUTES as ROUTES) +from .server_glue import ROUTES as ROUTES from . import format as _format diff --git a/src/nominatim_api/v1/server_glue.py b/src/nominatim_api/v1/server_glue.py index 0e954901..5f9212e1 100644 --- a/src/nominatim_api/v1/server_glue.py +++ b/src/nominatim_api/v1/server_glue.py @@ -8,17 +8,14 @@ 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, NoReturn, Dict, cast +from typing import Optional, Any, Type, Dict, cast from functools import reduce -import abc import dataclasses -import math from urllib.parse import urlencode import sqlalchemy as sa from ..errors import UsageError -from ..config import Configuration from .. import logging as loglib from ..core import NominatimAPIAsync from .format import dispatch as formatting @@ -28,156 +25,7 @@ from ..status import StatusResult from ..results import DetailedResult, ReverseResults, SearchResult, SearchResults from ..localization import Locales from . import helpers - -CONTENT_TEXT = 'text/plain; charset=utf-8' -CONTENT_XML = 'text/xml; charset=utf-8' -CONTENT_HTML = 'text/html; charset=utf-8' -CONTENT_JSON = 'application/json; charset=utf-8' - -CONTENT_TYPE = {'text': CONTENT_TEXT, 'xml': CONTENT_XML, 'debug': CONTENT_HTML} - -class ASGIAdaptor(abc.ABC): - """ Adapter class for the different ASGI frameworks. - Wraps functionality over concrete requests and responses. - """ - content_type: str = CONTENT_TEXT - - @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, status: int = 400) -> Exception: - """ Construct an appropriate exception from the given error message. - The exception must result in a HTTP error with the given status. - """ - - - @abc.abstractmethod - def create_response(self, status: int, output: str, num_results: int) -> 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'. - """ - - @abc.abstractmethod - def base_uri(self) -> str: - """ Return the URI of the original request. - """ - - - @abc.abstractmethod - def config(self) -> Configuration: - """ Return the current configuration object. - """ - - - 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 - - self.raise_error(f"Parameter '{name}' missing.") - - try: - intval = int(value) - except ValueError: - self.raise_error(f"Parameter '{name}' must be a number.") - - return intval - - - def get_float(self, name: str, default: Optional[float] = None) -> float: - """ Return an input parameter as a flaoting-point number. Raises an - exception if the parameter is given but not in an float 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 - - self.raise_error(f"Parameter '{name}' missing.") - - try: - fval = float(value) - except ValueError: - self.raise_error(f"Parameter '{name}' must be a number.") - - if math.isnan(fval) or math.isinf(fval): - self.raise_error(f"Parameter '{name}' must be a number.") - - return fval - - - 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 - - self.raise_error(f"Parameter '{name}' missing.") - - return value != '0' - - - def raise_error(self, msg: str, status: int = 400) -> NoReturn: - """ Raise an exception resulting in the given HTTP status and - message. The message will be formatted according to the - output format chosen by the request. - """ - if self.content_type == CONTENT_XML: - msg = f""" - - {status} - {msg} - - """ - elif self.content_type == CONTENT_JSON: - msg = f"""{{"error":{{"code":{status},"message":"{msg}"}}}}""" - elif self.content_type == CONTENT_HTML: - loglib.log().section('Execution error') - loglib.log().var_dump('Status', status) - loglib.log().var_dump('Message', msg) - msg = loglib.get_and_disable() - - raise self.error(msg, status) - +from ..server.asgi_adaptor import CONTENT_HTML, CONTENT_JSON, CONTENT_TYPE, ASGIAdaptor def build_response(adaptor: ASGIAdaptor, output: str, status: int = 200, num_results: int = 0) -> Any: @@ -565,8 +413,6 @@ async def polygons_endpoint(api: NominatimAPIAsync, params: ASGIAdaptor) -> Any: return build_response(params, formatting.format_result(results, fmt, {})) -EndpointFunc = Callable[[NominatimAPIAsync, ASGIAdaptor], Any] - ROUTES = [ ('status', status_endpoint), ('details', details_endpoint),