def setup(app: web.Application):
"""Setup the rest API module in the application in aiohttp fashion.
- users "rest" section of configuration (see schema in rest_config.py)
- loads and validate openapi specs from a remote (e.g. apihub) or local location
- connects openapi specs paths to handlers (see rest_routes.py)
- enables error, validation and envelope middlewares on API routes
IMPORTANT: this is a critical subsystem. Any failure should stop
the system startup. It CANNOT be simply disabled & continue
"""
log.debug("Setting up %s ...", __name__)
spec_path = resources.get_path("api/v0/openapi.yaml")
with spec_path.open() as fh:
spec_dict = yaml.safe_load(fh)
api_specs = openapi_core.create_spec(spec_dict, spec_path.as_uri())
# validated openapi specs
app[APP_OPENAPI_SPECS_KEY] = api_specs
# Connects handlers
routes = rest_routes.create(api_specs)
app.router.add_routes(routes)
log.debug("routes:\n\t%s", "\n\t".join(map(str, routes)))
# Enable error, validation and envelop middleware on API routes
base_path = get_base_path(api_specs)
append_rest_middlewares(app, base_path)
def setup(app: web.Application, *, swagger_doc_enabled: bool = True):
# ----------------------------------------------
# TODO: temporary, just to check compatibility between
# trafaret and pydantic schemas
cfg = assert_valid_config(app)
# ---------------------------------------------
api_version_dir = cfg["version"]
spec_path = get_openapi_specs_path(api_version_dir)
# validated openapi specs
app[APP_OPENAPI_SPECS_KEY] = specs = load_openapi_specs(spec_path)
# version check
base_path = openapi.get_base_path(specs)
major, *_ = specs.info.version
if f"/v{major}" != base_path:
raise ValueError(
f"REST API basepath {base_path} does not fit openapi.yml version {specs.info.version}"
)
if api_version_prefix != f"v{major}":
raise ValueError(
f"__version__.api_version_prefix {api_version_prefix} does not fit openapi.yml version {specs.info.version}"
)
# diagnostics routes
routes = rest_routes.create(specs)
app.router.add_routes(routes)
# middlewares
# NOTE: using safe get here since some tests use incomplete configs
is_diagnostics_enabled = get_diagnostics_config(app).get("enabled", False)
app.middlewares.extend(
[
error_middleware_factory(
api_version_prefix,
log_exceptions=not is_diagnostics_enabled,
),
envelope_middleware_factory(api_version_prefix),
]
)
# Adds swagger doc UI
# - API doc at /dev/doc (optional, e.g. for testing since it can be heavy)
# - NOTE: avoid /api/* since traeffik uses for it's own API
#
log.debug("OAS loaded from %s ", spec_path)
if swagger_doc_enabled:
setup_swagger(
app,
swagger_url="/dev/doc",
swagger_from_file=str(spec_path),
ui_version=3,
)
async def test_envelope_middleware(path, expected_data, client, specs):
base = openapi.get_base_path(specs)
response = await client.get(base + path)
payload = await response.json()
assert is_enveloped(payload)
data, error = unwrap_envelope(payload)
assert not error
assert data == expected_data
async def test_validate_handlers(path, client, specs):
base = openapi.get_base_path(specs)
response = await client.get(base + path)
payload = await response.json()
assert is_enveloped(payload)
data, error = unwrap_envelope(payload)
assert not error
assert data
def test_prepends_basepath(specs):
# not - strict
try:
handlers = Handlers()
routes = create_routes_from_namespace(specs, handlers, strict=False)
except Exception: # pylint: disable=W0703
pytest.fail("Non-strict failed", pytrace=True)
basepath = openapi.get_base_path(specs)
for route in routes:
assert route.path.startswith(basepath)
assert route.handler.__name__[len("get_"):] in route.path
def create_routes(specs):
base_path = openapi.get_base_path(specs)
logger.debug("creating %s ", __name__)
routes = []
path, handle = '/', rest_handlers.check_health
operation_id = specs.paths[path].operations['get'].operation_id
routes.append( web.get(base_path+path, handle, name=operation_id) )
path, handle = '/check/{action}', rest_handlers.check_action
operation_id = specs.paths[path].operations['post'].operation_id
routes.append( web.post(base_path+path, handle, name=operation_id) )
return routes
def create_rest_routes(specs: openapi.Spec) -> List[web.RouteDef]:
# NOTE: these are routes with paths starting with v0/*
routes = []
base_path: str = openapi.get_base_path(specs)
path, handle = "/health", check_health
operation_id = specs.paths[path].operations["get"].operation_id
routes.append(web.get(base_path + path, handle, name=operation_id))
# NOTE: Internal. Not shown in api/docs
path, handle = "/diagnostics", get_diagnostics
operation_id = "get_diagnotics" # specs.paths[path].operations['get'].operation_id
routes.append(web.get(base_path + path, handle, name=operation_id))
return routes
async def test_404_not_found(client, specs):
# see FIXME: in validate_middleware_factory
response = await client.get("/some-invalid-address-outside-api")
payload = await response.text()
assert response.status == 404, payload
api_base = openapi.get_base_path(specs)
response = await client.get(api_base + "/some-invalid-address-in-api")
payload = await response.json()
assert response.status == 404, payload
assert is_enveloped(payload)
data, error = unwrap_envelope(payload)
assert error
assert not data
def client(loop, aiohttp_client, specs):
app = web.Application()
# routes
handlers = Handlers()
routes = create_routes_from_namespace(specs, handlers, strict=False)
app.router.add_routes(routes)
# validators
app[APP_OPENAPI_SPECS_KEY] = specs
# middlewares
base = openapi.get_base_path(specs)
app.middlewares.append(error_middleware_factory(base))
app.middlewares.append(envelope_middleware_factory(base))
return loop.run_until_complete(aiohttp_client(app))
def setup(app: web.Application, *, debug=False):
log.debug("Setting up %s %s...", __name__, "[DEBUG]" if debug else "")
# main_cfg = app[APP_CONFIG_KEY]["main"]
cfg = app[APP_CONFIG_KEY][CONFIG_SECTION_NAME]
try:
#specs = await create_openapi_specs(location=cfg["location"])
loop = asyncio.get_event_loop()
location = cfg["location"]
specs = loop.run_until_complete(get_specs(location))
# TODO: tmp removed but keep in case ...
# sets servers variables to current server's config
# extra_api_urls = cfg.get("extra_urls", list())
# if debug:
# for host in {'127.0.0.1', 'localhost', main_cfg['host'] }:
# for port in {9081, main_cfg['port']}:
# extra_api_urls.append("http://{}:{}".format(host, port))
# server = get_server(specs.servers, "{publicUrl}/{basePath}")
# for url in extra_api_urls:
# new_server = deepcopy(server)
# new_server.variables['publicUrl'].default = url
# specs.servers.append(new_server)
# TODO: What if many specs to expose? v0, v1, v2 ... perhaps a dict instead?
# TODO: should freeze specs here??
app[APP_OPENAPI_SPECS_KEY] = specs # validated openapi specs
# diagnostics routes
routes = rest_routes.create(specs)
app.router.add_routes(routes)
# middlewares
base_path = openapi.get_base_path(specs)
version = cfg["version"]
assert "/" + version == base_path, "Expected %s, got %s" % (version,
base_path)
append_rest_middlewares(app, base_path)
except openapi.OpenAPIError:
# TODO: protocol when some parts are unavailable because of failure
# Define whether it is critical or this server can still
# continue working offering partial services
log.exception("Invalid rest API specs. Rest API is DISABLED")
def setup(app: web.Application, *, devel=False):
""" Subsystem's setup
:param app: aiohttp application
:type app: web.Application
:param devel: enables development mode, defaults to False
:param devel: bool, optional
"""
log.debug("Setting up %s %s...", __name__, "[DEVEL]" if devel else "")
cfg = app[APP_CONFIG_KEY][CONFIG_SECTION_NAME]
try:
loop = asyncio.get_event_loop()
location = cfg["location"]
if not URL(location).host:
if not Path(location).exists():
# add resource location
if resources.exists(location):
location = resources.get_path(location)
specs = loop.run_until_complete(get_specs(location))
# TODO: What if many specs to expose? v0, v1, v2 ... perhaps a dict instead?
app[APP_OPENAPI_SPECS_KEY] = specs # validated openapi specs
except openapi.OpenAPIError:
# TODO: protocol when some parts are unavailable because of failure
# Define whether it is critical or this server can still
# continue working offering partial services
log.exception("Invalid rest API specs. Rest API is DISABLED")
else:
# routes
routes = create_routes(specs)
log.debug("%s API routes:\n%s", CONFIG_SECTION_NAME, pformat(routes))
app.router.add_routes(routes)
# middlewares
base_path = openapi.get_base_path(specs)
version = cfg["version"]
assert "/" + version == base_path, "Expected %s, got %s" % (version,
base_path)
append_rest_middlewares(app, base_path)
def create(specs: openapi.Spec) -> List[web.RouteDef]:
# TODO: consider the case in which server creates routes for both v0 and v1!!!
# TODO: should this be taken from servers instead?
base_path = openapi.get_base_path(specs)
log.debug("creating %s ", __name__)
routes = []
# TODO: routing will be done automatically using operation_id/tags, etc...
# diagnostics --
path, handle = '/', rest_handlers.check_health
operation_id = specs.paths[path].operations['get'].operation_id
routes.append(web.get(base_path + path, handle, name=operation_id))
path, handle = '/check/{action}', rest_handlers.check_action
operation_id = specs.paths[path].operations['post'].operation_id
routes.append(web.post(base_path + path, handle, name=operation_id))
return routes
def create(specs: openapi.Spec) -> List[web.RouteDef]:
""" Creates routes mapping operators_id with handler functions
:param specs: validated oas
:type specs: openapi.Spec
:return: list of web routes for auth
:rtype: List[web.RouteDef]
"""
log.debug("Creating %s ", __name__)
base_path = openapi.get_base_path(specs)
def include_path(tuple_object):
_method, path, _operation_id, _tags = tuple_object
return path.startswith(base_path + "/auth/")
handlers_map = {
"auth_register": login_handlers.register,
"auth_login": login_handlers.login,
"auth_logout": login_handlers.logout,
"auth_reset_password": login_handlers.reset_password,
"auth_reset_password_allowed": login_handlers.reset_password_allowed,
"auth_change_email": login_handlers.change_email,
"auth_change_password": login_handlers.change_password,
"auth_confirmation": login_handlers.email_confirmation,
"create_api_key": api_keys_handlers.create_api_key,
"delete_api_key": api_keys_handlers.delete_api_key,
"list_api_keys": api_keys_handlers.list_api_keys,
}
routes = map_handlers_with_operations(handlers_map,
filter(include_path,
iter_path_operations(specs)),
strict=True)
log.debug("Mapped auth routes: %s",
"\n".join([pformat(r) for r in routes]))
return routes
def create(specs: openapi.Spec) -> List[web.RouteDef]:
# TODO: consider the case in which server creates routes for both v0 and v1!!!
# TODO: should this be taken from servers instead?
base_path = openapi.get_base_path(specs)
log.debug("creating %s ", __name__)
routes = []
# maintenance --
path, handle = "/", rest_handlers.check_running
operation_id = specs.paths[path].operations["get"].operation_id
routes.append(web.get(base_path + path, handle, name=operation_id))
path, handle = "/check/{action}", rest_handlers.check_action
operation_id = specs.paths[path].operations["post"].operation_id
routes.append(web.post(base_path + path, handle, name=operation_id))
path, handle = "/config", rest_handlers.get_config
operation_id = specs.paths[path].operations["get"].operation_id
routes.append(web.get(base_path + path, handle, name=operation_id))
return routes
def setup(app: web.Application):
"""Setup the rest API module in the application in aiohttp fashion.
- users "rest" section of configuration (see schema in rest_config.py)
- loads and validate openapi specs from a remote (e.g. apihub) or local location
- connects openapi specs paths to handlers (see rest_routes.py)
- enables error, validation and envelope middlewares on API routes
IMPORTANT: this is a critical subsystem. Any failure should stop
the system startup. It CANNOT be simply disabled & continue
"""
log.debug("Setting up %s ...", __name__)
cfg = app[APP_CONFIG_KEY][CONFIG_SECTION_NAME]
# app_config = app[APP_CONFIG_KEY]['main'] # TODO: define appconfig key based on config schema
# api_specs = create_apispecs(app_config)
loop = asyncio.get_event_loop()
location = "{}/storage/{}/openapi.yaml".format(cfg["oas_repo"],
API_VERSION_TAG)
if is_url(location):
loop.run_until_complete(assert_enpoint_is_ok(URL(location)))
api_specs = loop.run_until_complete(create_openapi_specs(location))
# validated openapi specs
app[APP_OPENAPI_SPECS_KEY] = api_specs
# Connects handlers
routes = rest_routes.create(api_specs)
app.router.add_routes(routes)
log.debug("routes:\n\t%s", "\n\t".join(map(str, routes)))
# Enable error, validation and envelop middleware on API routes
base_path = get_base_path(api_specs)
append_rest_middlewares(app, base_path)
