Release 2.8.0

manually

.bandit-test.yml

@@ -1 +1 @@
-skips: ['B101', 'B105', 'B106', 'B404']
+skips: ['B101', 'B104', 'B105', 'B106', 'B404']

.github/workflows/setup.sh

@@ -18,7 +18,7 @@ if [[ -z $MINIMAL_INSTALL ]]; then
     # VCS support
     pacman --noconfirm -Sy breezy darcs mercurial subversion
     # web server
-    pacman --noconfirm -Sy python-aioauth-client python-aiohttp python-aiohttp-debugtoolbar python-aiohttp-jinja2 python-aiohttp-security python-aiohttp-session python-cryptography python-jinja
+    pacman --noconfirm -Sy python-aioauth-client python-aiohttp python-aiohttp-apispec-git python-aiohttp-cors python-aiohttp-debugtoolbar python-aiohttp-jinja2 python-aiohttp-security python-aiohttp-session python-cryptography python-jinja
     # additional features
     pacman --noconfirm -Sy gnupg python-boto3 rsync
 fi

.pylintrc

@@ -533,5 +533,5 @@ valid-metaclass-classmethod-first-arg=cls
 
 # Exceptions that will emit a warning when being caught. Defaults to
 # "BaseException, Exception".
-overgeneral-exceptions=BaseException,
-                       Exception
+overgeneral-exceptions=builtins.BaseException,
+                       builtins.Exception

CONTRIBUTING.md

@@ -156,6 +156,52 @@ Again, the most checks can be performed by `make check` command, though some add
 * No global variable is allowed outside of `ahriman.version` module. `ahriman.core.context` is also special case.
 * Single quotes are not allowed. The reason behind this restriction is the fact that docstrings must be written by using double quotes only, and we would like to make style consistent.
 * If your class writes anything to log, the `ahriman.core.log.LazyLogging` trait must be used.
+* Web API methods must be documented by using `aiohttp_apispec` library. Schema testing mostly should be implemented in related view class tests. Recommended example for documentation (excluding comments):
+
+    ```python
+    import aiohttp_apispec
+
+    from marshmallow import Schema, fields  
+
+    from ahriman.web.schemas.auth_schema import AuthSchema
+    from ahriman.web.schemas.error_schema import ErrorSchema
+    from ahriman.web.schemas.package_name_schema import PackageNameSchema
+    from ahriman.web.views.base import BaseView
+
+
+    class RequestSchema(Schema):
+
+        field = fields.String(metadata={"description": "Field description", "example": "foo"})
+
+
+    class ResponseSchema(Schema):
+
+        field = fields.String(required=True, metadata={"description": "Field description"})
+
+
+    class Foo(BaseView):
+
+        POST_PERMISSION = ...
+
+        @aiohttp_apispec.docs(
+            tags=["Tag"],
+            summary="Do foo",
+            description="Extended description of the method which does foo",
+            responses={
+                200: {"description": "Success response", "schema": ResponseSchema},
+                204: {"description": "Success response"},  # example without json schema response
+                400: {"description": "Bad data is supplied", "schema": ErrorSchema},  # exception raised by this method
+                401: {"description": "Authorization required", "schema": ErrorSchema},  # should be always presented
+                403: {"description": "Access is forbidden", "schema": ErrorSchema},  # should be always presented
+                500: {"description": "Internal server error", "schema": ErrorSchema},  # should be always presented
+            },
+            security=[{"token": [POST_PERMISSION]}],
+        )
+        @aiohttp_apispec.cookies_schema(AuthSchema)  # should be always presented
+        @aiohttp_apispec.match_info_schema(PackageNameSchema)
+        @aiohttp_apispec.json_schema(RequestSchema(many=True))
+        async def post(self) -> None: ...
+    ```
 
 ### Other checks
 

Dockerfile

@@ -30,9 +30,9 @@ COPY "docker/install-aur-package.sh" "/usr/local/bin/install-aur-package"
 ## darcs is not installed by reasons, because it requires a lot haskell packages which dramatically increase image size
 RUN pacman --noconfirm -Sy devtools git pyalpm python-cerberus python-inflection python-passlib python-requests python-setuptools python-srcinfo && \
     pacman --noconfirm -Sy python-build python-installer python-wheel && \
-    pacman --noconfirm -Sy breezy mercurial python-aiohttp python-boto3 python-cryptography python-jinja python-requests-unixsocket rsync subversion && \
-    runuser -u build -- install-aur-package python-aioauth-client python-aiohttp-jinja2 python-aiohttp-debugtoolbar \
-                                            python-aiohttp-session python-aiohttp-security
+    pacman --noconfirm -Sy breezy mercurial python-aiohttp python-aiohttp-cors python-boto3 python-cryptography python-jinja python-requests-unixsocket rsync subversion && \
+    runuser -u build -- install-aur-package python-aioauth-client python-aiohttp-apispec-git python-aiohttp-jinja2  \
+                                            python-aiohttp-debugtoolbar python-aiohttp-session python-aiohttp-security
 
 # cleanup unused
 RUN find "/var/cache/pacman/pkg" -type f -delete

README.md

@@ -36,6 +36,6 @@ The application provides reasonable defaults which allow to use it out-of-box; h
 
 ## Live demos
 
-* [Build status page](https://ahriman-demo.arcanis.me). You can log in as `demo` user by using `demo` password. However, you will not be able to run tasks.
+* [Build status page](https://ahriman-demo.arcanis.me). You can log in as `demo` user by using `demo` password. However, you will not be able to run tasks. [HTTP API documentation](https://ahriman-demo.arcanis.me/api-docs) is also available.
 * [Repository index](http://repo.arcanis.me/x86_64/index.html).
 * [Telegram feed](https://t.me/arcanisrepo).

docs/ahriman.1

@@ -1,4 +1,4 @@
-.TH AHRIMAN "1" "2023\-01\-27" "ahriman" "Generated Python Manual"
+.TH AHRIMAN "1" "2023\-04\-09" "ahriman" "Generated Python Manual"
 .SH NAME
 ahriman
 .SH SYNOPSIS
@@ -215,8 +215,8 @@ usage: ahriman help\-version [\-h]
 print application and its dependencies versions
 
 .SH COMMAND \fI\,'ahriman package\-add'\/\fR
-usage: ahriman package\-add [\-h] [\-e] [\-n] [\-y] [\-s {auto,archive,aur,directory,local,remote,repository}]
-                           [\-\-without\-dependencies]
+usage: ahriman package\-add [\-h] [\-\-dependencies | \-\-no\-dependencies] [\-e] [\-n] [\-y]
+                           [\-s {auto,archive,aur,directory,local,remote,repository}]
                            package [package ...]
 
 add existing or new package to the build queue
@@ -226,6 +226,10 @@ add existing or new package to the build queue
 package source (base name, path to local files, remote URL)
 
 .SH OPTIONS \fI\,'ahriman package\-add'\/\fR
+.TP
+\fB\-\-dependencies\fR, \fB\-\-no\-dependencies\fR
+process missing package dependencies (default: True)
+
 .TP
 \fB\-e\fR, \fB\-\-exit\-code\fR
 return non\-zero exit status if result is empty
@@ -242,10 +246,6 @@ download fresh package databases from the mirror before actions, \-yy to force r
 \fB\-s\fR \fI\,{auto,archive,aur,directory,local,remote,repository}\/\fR, \fB\-\-source\fR \fI\,{auto,archive,aur,directory,local,remote,repository}\/\fR
 explicitly specify the package source for this command
 
-.TP
-\fB\-\-without\-dependencies\fR
-do not add dependencies
-
 .SH COMMAND \fI\,'ahriman package\-remove'\/\fR
 usage: ahriman package\-remove [\-h] package [package ...]
 
@@ -401,8 +401,8 @@ fetch actual version of VCS packages (default: True)
 download fresh package databases from the mirror before actions, \-yy to force refresh even if up to date
 
 .SH COMMAND \fI\,'ahriman repo\-daemon'\/\fR
-usage: ahriman repo\-daemon [\-h] [\-i INTERVAL] [\-\-aur | \-\-no\-aur] [\-\-local | \-\-no\-local] [\-\-manual | \-\-no\-manual]
-                           [\-\-vcs | \-\-no\-vcs] [\-y]
+usage: ahriman repo\-daemon [\-h] [\-i INTERVAL] [\-\-aur | \-\-no\-aur] [\-\-dependencies | \-\-no\-dependencies]
+                           [\-\-local | \-\-no\-local] [\-\-manual | \-\-no\-manual] [\-\-vcs | \-\-no\-vcs] [\-y]
 
 start process which periodically will run update process
 
@@ -415,6 +415,10 @@ interval between runs in seconds
 \fB\-\-aur\fR, \fB\-\-no\-aur\fR
 enable or disable checking for AUR updates (default: True)
 
+.TP
+\fB\-\-dependencies\fR, \fB\-\-no\-dependencies\fR
+process missing package dependencies (default: True)
+
 .TP
 \fB\-\-local\fR, \fB\-\-no\-local\fR
 enable or disable checking of local packages for updates (default: True)
@@ -523,8 +527,8 @@ run triggers on empty build result as configured by settings
 instead of running all triggers as set by configuration, just process specified ones in order of mention
 
 .SH COMMAND \fI\,'ahriman repo\-update'\/\fR
-usage: ahriman repo\-update [\-h] [\-\-dry\-run] [\-e] [\-\-aur | \-\-no\-aur] [\-\-local | \-\-no\-local] [\-\-manual | \-\-no\-manual]
-                           [\-\-vcs | \-\-no\-vcs] [\-y]
+usage: ahriman repo\-update [\-h] [\-\-aur | \-\-no\-aur] [\-\-dependencies | \-\-no\-dependencies] [\-\-dry\-run] [\-e]
+                           [\-\-local | \-\-no\-local] [\-\-manual | \-\-no\-manual] [\-\-vcs | \-\-no\-vcs] [\-y]
                            [package ...]
 
 check for packages updates and run build process if requested
@@ -534,6 +538,14 @@ check for packages updates and run build process if requested
 filter check by package base
 
 .SH OPTIONS \fI\,'ahriman repo\-update'\/\fR
+.TP
+\fB\-\-aur\fR, \fB\-\-no\-aur\fR
+enable or disable checking for AUR updates (default: True)
+
+.TP
+\fB\-\-dependencies\fR, \fB\-\-no\-dependencies\fR
+process missing package dependencies (default: True)
+
 .TP
 \fB\-\-dry\-run\fR
 just perform check for updates, same as check command
@@ -542,10 +554,6 @@ just perform check for updates, same as check command
 \fB\-e\fR, \fB\-\-exit\-code\fR
 return non\-zero exit status if result is empty
 
-.TP
-\fB\-\-aur\fR, \fB\-\-no\-aur\fR
-enable or disable checking for AUR updates (default: True)
-
 .TP
 \fB\-\-local\fR, \fB\-\-no\-local\fR
 enable or disable checking of local packages for updates (default: True)
@@ -590,10 +598,15 @@ clear directory with built packages (default: False)
 clear directory with pacman local database cache (default: False)
 
 .SH COMMAND \fI\,'ahriman service\-config'\/\fR
-usage: ahriman service\-config [\-h]
+usage: ahriman service\-config [\-h] [\-\-secure | \-\-no\-secure]
 
 dump configuration for the specified architecture
 
+.SH OPTIONS \fI\,'ahriman service\-config'\/\fR
+.TP
+\fB\-\-secure\fR, \fB\-\-no\-secure\fR
+hide passwords and secrets from output (default: True)
+
 .SH COMMAND \fI\,'ahriman service\-config\-validate'\/\fR
 usage: ahriman service\-config\-validate [\-h] [\-e]
 

docs/ahriman.core.database.migrations.rst

@@ -52,6 +52,14 @@ ahriman.core.database.migrations.m005\_make\_opt\_depends module
    :no-undoc-members:
    :show-inheritance:
 
+ahriman.core.database.migrations.m006\_packages\_architecture\_required module
+------------------------------------------------------------------------------
+
+.. automodule:: ahriman.core.database.migrations.m006_packages_architecture_required
+   :members:
+   :no-undoc-members:
+   :show-inheritance:
+
 Module contents
 ---------------
 

docs/ahriman.models.rst

@@ -196,14 +196,6 @@ ahriman.models.user\_access module
    :no-undoc-members:
    :show-inheritance:
 
-ahriman.models.user\_identity module
-------------------------------------
-
-.. automodule:: ahriman.models.user_identity
-   :members:
-   :no-undoc-members:
-   :show-inheritance:
-
 Module contents
 ---------------
 

docs/architecture.rst

@@ -269,6 +269,7 @@ Web application
 Web application requires the following python packages to be installed:
 
 * Core part requires ``aiohttp`` (application itself), ``aiohttp_jinja2`` and ``Jinja2`` (HTML generation from templates).
+* Additional web features also require ``aiohttp-apispec`` (autogenerated documentation), ``aiohttp_cors`` (CORS support, required by documentation)
 * In addition, ``aiohttp_debugtoolbar`` is required for debug panel. Please note that this option does not work together with authorization and basically must not be used in production.
 * In addition, authorization feature requires ``aiohttp_security``, ``aiohttp_session`` and ``cryptography``.
 * In addition to base authorization dependencies, OAuth2 also requires ``aioauth-client`` library.
@@ -279,6 +280,13 @@ Middlewares
 
 Service provides some custom middlewares, e.g. logging every exception (except for user ones) and user authorization.
 
+HEAD and OPTIONS requests
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``HEAD`` request is automatically generated by ``ahriman.web.views.base.BaseView`` class. It just calls ``GET`` method, removes any data from body and returns the result. In case if no ``GET`` method available for this view, the ``aiohttp.web.HTTPMethodNotAllowed`` exception will be raised.
+
+On the other side, ``OPTIONS`` method is implemented in the ``ahriman.web.middlewares.exception_handler.exception_handler`` middleware. In case if ``aiohttp.web.HTTPMethodNotAllowed`` exception is raised and original method was ``OPTIONS``, the middleware handles it, converts to valid request and returns response to user.
+
 Web views
 ^^^^^^^^^
 
@@ -288,6 +296,7 @@ REST API supports both form and JSON data, but the last one is recommended.
 
 Different APIs are separated into different packages:
 
+* ``ahriman.web.views.api`` not a real API, but some views which provide OpenAPI support.
 * ``ahriman.web.views.service`` provides views for application controls.
 * ``ahriman.web.views.status`` package provides REST API for application reporting.
 * ``ahriman.web.views.user`` package provides login and logout methods which can be called without authorization.

docs/completions/bash/_ahriman

@@ -10,9 +10,9 @@ _shtab_ahriman_help_commands_unsafe_option_strings=('-h' '--help' '--command')
 _shtab_ahriman_help_updates_option_strings=('-h' '--help' '-e' '--exit-code')
 _shtab_ahriman_help_version_option_strings=('-h' '--help')
 _shtab_ahriman_version_option_strings=('-h' '--help')
-_shtab_ahriman_package_add_option_strings=('-h' '--help' '-e' '--exit-code' '-n' '--now' '-y' '--refresh' '-s' '--source' '--without-dependencies')
-_shtab_ahriman_add_option_strings=('-h' '--help' '-e' '--exit-code' '-n' '--now' '-y' '--refresh' '-s' '--source' '--without-dependencies')
-_shtab_ahriman_package_update_option_strings=('-h' '--help' '-e' '--exit-code' '-n' '--now' '-y' '--refresh' '-s' '--source' '--without-dependencies')
+_shtab_ahriman_package_add_option_strings=('-h' '--help' '--dependencies' '--no-dependencies' '-e' '--exit-code' '-n' '--now' '-y' '--refresh' '-s' '--source')
+_shtab_ahriman_add_option_strings=('-h' '--help' '--dependencies' '--no-dependencies' '-e' '--exit-code' '-n' '--now' '-y' '--refresh' '-s' '--source')
+_shtab_ahriman_package_update_option_strings=('-h' '--help' '--dependencies' '--no-dependencies' '-e' '--exit-code' '-n' '--now' '-y' '--refresh' '-s' '--source')
 _shtab_ahriman_package_remove_option_strings=('-h' '--help')
 _shtab_ahriman_remove_option_strings=('-h' '--help')
 _shtab_ahriman_package_status_option_strings=('-h' '--help' '--ahriman' '-e' '--exit-code' '--info' '--no-info' '-s' '--status')
@@ -27,8 +27,8 @@ _shtab_ahriman_patch_set_add_option_strings=('-h' '--help' '-t' '--track')
 _shtab_ahriman_repo_backup_option_strings=('-h' '--help')
 _shtab_ahriman_repo_check_option_strings=('-h' '--help' '-e' '--exit-code' '--vcs' '--no-vcs' '-y' '--refresh')
 _shtab_ahriman_check_option_strings=('-h' '--help' '-e' '--exit-code' '--vcs' '--no-vcs' '-y' '--refresh')
-_shtab_ahriman_repo_daemon_option_strings=('-h' '--help' '-i' '--interval' '--aur' '--no-aur' '--local' '--no-local' '--manual' '--no-manual' '--vcs' '--no-vcs' '-y' '--refresh')
-_shtab_ahriman_daemon_option_strings=('-h' '--help' '-i' '--interval' '--aur' '--no-aur' '--local' '--no-local' '--manual' '--no-manual' '--vcs' '--no-vcs' '-y' '--refresh')
+_shtab_ahriman_repo_daemon_option_strings=('-h' '--help' '-i' '--interval' '--aur' '--no-aur' '--dependencies' '--no-dependencies' '--local' '--no-local' '--manual' '--no-manual' '--vcs' '--no-vcs' '-y' '--refresh')
+_shtab_ahriman_daemon_option_strings=('-h' '--help' '-i' '--interval' '--aur' '--no-aur' '--dependencies' '--no-dependencies' '--local' '--no-local' '--manual' '--no-manual' '--vcs' '--no-vcs' '-y' '--refresh')
 _shtab_ahriman_repo_rebuild_option_strings=('-h' '--help' '--depends-on' '--dry-run' '--from-database' '-e' '--exit-code')
 _shtab_ahriman_rebuild_option_strings=('-h' '--help' '--depends-on' '--dry-run' '--from-database' '-e' '--exit-code')
 _shtab_ahriman_repo_remove_unknown_option_strings=('-h' '--help' '--dry-run')
@@ -43,14 +43,14 @@ _shtab_ahriman_repo_sync_option_strings=('-h' '--help')
 _shtab_ahriman_sync_option_strings=('-h' '--help')
 _shtab_ahriman_repo_tree_option_strings=('-h' '--help')
 _shtab_ahriman_repo_triggers_option_strings=('-h' '--help')
-_shtab_ahriman_repo_update_option_strings=('-h' '--help' '--dry-run' '-e' '--exit-code' '--aur' '--no-aur' '--local' '--no-local' '--manual' '--no-manual' '--vcs' '--no-vcs' '-y' '--refresh')
-_shtab_ahriman_update_option_strings=('-h' '--help' '--dry-run' '-e' '--exit-code' '--aur' '--no-aur' '--local' '--no-local' '--manual' '--no-manual' '--vcs' '--no-vcs' '-y' '--refresh')
+_shtab_ahriman_repo_update_option_strings=('-h' '--help' '--aur' '--no-aur' '--dependencies' '--no-dependencies' '--dry-run' '-e' '--exit-code' '--local' '--no-local' '--manual' '--no-manual' '--vcs' '--no-vcs' '-y' '--refresh')
+_shtab_ahriman_update_option_strings=('-h' '--help' '--aur' '--no-aur' '--dependencies' '--no-dependencies' '--dry-run' '-e' '--exit-code' '--local' '--no-local' '--manual' '--no-manual' '--vcs' '--no-vcs' '-y' '--refresh')
 _shtab_ahriman_service_clean_option_strings=('-h' '--help' '--cache' '--no-cache' '--chroot' '--no-chroot' '--manual' '--no-manual' '--packages' '--no-packages' '--pacman' '--no-pacman')
 _shtab_ahriman_clean_option_strings=('-h' '--help' '--cache' '--no-cache' '--chroot' '--no-chroot' '--manual' '--no-manual' '--packages' '--no-packages' '--pacman' '--no-pacman')
 _shtab_ahriman_repo_clean_option_strings=('-h' '--help' '--cache' '--no-cache' '--chroot' '--no-chroot' '--manual' '--no-manual' '--packages' '--no-packages' '--pacman' '--no-pacman')
-_shtab_ahriman_service_config_option_strings=('-h' '--help')
-_shtab_ahriman_config_option_strings=('-h' '--help')
-_shtab_ahriman_repo_config_option_strings=('-h' '--help')
+_shtab_ahriman_service_config_option_strings=('-h' '--help' '--secure' '--no-secure')
+_shtab_ahriman_config_option_strings=('-h' '--help' '--secure' '--no-secure')
+_shtab_ahriman_repo_config_option_strings=('-h' '--help' '--secure' '--no-secure')
 _shtab_ahriman_service_config_validate_option_strings=('-h' '--help' '-e' '--exit-code')
 _shtab_ahriman_config_validate_option_strings=('-h' '--help' '-e' '--exit-code')
 _shtab_ahriman_repo_config_validate_option_strings=('-h' '--help' '-e' '--exit-code')
@@ -139,33 +139,36 @@ _shtab_ahriman_version___help_nargs=0
 _shtab_ahriman_package_add_pos_0_nargs=+
 _shtab_ahriman_package_add__h_nargs=0
 _shtab_ahriman_package_add___help_nargs=0
+_shtab_ahriman_package_add___dependencies_nargs=0
+_shtab_ahriman_package_add___no_dependencies_nargs=0
 _shtab_ahriman_package_add__e_nargs=0
 _shtab_ahriman_package_add___exit_code_nargs=0
 _shtab_ahriman_package_add__n_nargs=0
 _shtab_ahriman_package_add___now_nargs=0
 _shtab_ahriman_package_add__y_nargs=0
 _shtab_ahriman_package_add___refresh_nargs=0
-_shtab_ahriman_package_add___without_dependencies_nargs=0
 _shtab_ahriman_add_pos_0_nargs=+
 _shtab_ahriman_add__h_nargs=0
 _shtab_ahriman_add___help_nargs=0
+_shtab_ahriman_add___dependencies_nargs=0
+_shtab_ahriman_add___no_dependencies_nargs=0
 _shtab_ahriman_add__e_nargs=0
 _shtab_ahriman_add___exit_code_nargs=0
 _shtab_ahriman_add__n_nargs=0
 _shtab_ahriman_add___now_nargs=0
 _shtab_ahriman_add__y_nargs=0
 _shtab_ahriman_add___refresh_nargs=0
-_shtab_ahriman_add___without_dependencies_nargs=0
 _shtab_ahriman_package_update_pos_0_nargs=+
 _shtab_ahriman_package_update__h_nargs=0
 _shtab_ahriman_package_update___help_nargs=0
+_shtab_ahriman_package_update___dependencies_nargs=0
+_shtab_ahriman_package_update___no_dependencies_nargs=0
 _shtab_ahriman_package_update__e_nargs=0
 _shtab_ahriman_package_update___exit_code_nargs=0
 _shtab_ahriman_package_update__n_nargs=0
 _shtab_ahriman_package_update___now_nargs=0
 _shtab_ahriman_package_update__y_nargs=0
 _shtab_ahriman_package_update___refresh_nargs=0
-_shtab_ahriman_package_update___without_dependencies_nargs=0
 _shtab_ahriman_package_remove_pos_0_nargs=+
 _shtab_ahriman_package_remove__h_nargs=0
 _shtab_ahriman_package_remove___help_nargs=0
@@ -231,6 +234,8 @@ _shtab_ahriman_repo_daemon__h_nargs=0
 _shtab_ahriman_repo_daemon___help_nargs=0
 _shtab_ahriman_repo_daemon___aur_nargs=0
 _shtab_ahriman_repo_daemon___no_aur_nargs=0
+_shtab_ahriman_repo_daemon___dependencies_nargs=0
+_shtab_ahriman_repo_daemon___no_dependencies_nargs=0
 _shtab_ahriman_repo_daemon___local_nargs=0
 _shtab_ahriman_repo_daemon___no_local_nargs=0
 _shtab_ahriman_repo_daemon___manual_nargs=0
@@ -243,6 +248,8 @@ _shtab_ahriman_daemon__h_nargs=0
 _shtab_ahriman_daemon___help_nargs=0
 _shtab_ahriman_daemon___aur_nargs=0
 _shtab_ahriman_daemon___no_aur_nargs=0
+_shtab_ahriman_daemon___dependencies_nargs=0
+_shtab_ahriman_daemon___no_dependencies_nargs=0
 _shtab_ahriman_daemon___local_nargs=0
 _shtab_ahriman_daemon___no_local_nargs=0
 _shtab_ahriman_daemon___manual_nargs=0
@@ -295,11 +302,13 @@ _shtab_ahriman_repo_triggers___help_nargs=0
 _shtab_ahriman_repo_update_pos_0_nargs=*
 _shtab_ahriman_repo_update__h_nargs=0
 _shtab_ahriman_repo_update___help_nargs=0
+_shtab_ahriman_repo_update___aur_nargs=0
+_shtab_ahriman_repo_update___no_aur_nargs=0
+_shtab_ahriman_repo_update___dependencies_nargs=0
+_shtab_ahriman_repo_update___no_dependencies_nargs=0
 _shtab_ahriman_repo_update___dry_run_nargs=0
 _shtab_ahriman_repo_update__e_nargs=0
 _shtab_ahriman_repo_update___exit_code_nargs=0
-_shtab_ahriman_repo_update___aur_nargs=0
-_shtab_ahriman_repo_update___no_aur_nargs=0
 _shtab_ahriman_repo_update___local_nargs=0
 _shtab_ahriman_repo_update___no_local_nargs=0
 _shtab_ahriman_repo_update___manual_nargs=0
@@ -311,11 +320,13 @@ _shtab_ahriman_repo_update___refresh_nargs=0
 _shtab_ahriman_update_pos_0_nargs=*
 _shtab_ahriman_update__h_nargs=0
 _shtab_ahriman_update___help_nargs=0
+_shtab_ahriman_update___aur_nargs=0
+_shtab_ahriman_update___no_aur_nargs=0
+_shtab_ahriman_update___dependencies_nargs=0
+_shtab_ahriman_update___no_dependencies_nargs=0
 _shtab_ahriman_update___dry_run_nargs=0
 _shtab_ahriman_update__e_nargs=0
 _shtab_ahriman_update___exit_code_nargs=0
-_shtab_ahriman_update___aur_nargs=0
-_shtab_ahriman_update___no_aur_nargs=0
 _shtab_ahriman_update___local_nargs=0
 _shtab_ahriman_update___no_local_nargs=0
 _shtab_ahriman_update___manual_nargs=0
@@ -362,10 +373,16 @@ _shtab_ahriman_repo_clean___pacman_nargs=0
 _shtab_ahriman_repo_clean___no_pacman_nargs=0
 _shtab_ahriman_service_config__h_nargs=0
 _shtab_ahriman_service_config___help_nargs=0
+_shtab_ahriman_service_config___secure_nargs=0
+_shtab_ahriman_service_config___no_secure_nargs=0
 _shtab_ahriman_config__h_nargs=0
 _shtab_ahriman_config___help_nargs=0
+_shtab_ahriman_config___secure_nargs=0
+_shtab_ahriman_config___no_secure_nargs=0
 _shtab_ahriman_repo_config__h_nargs=0
 _shtab_ahriman_repo_config___help_nargs=0
+_shtab_ahriman_repo_config___secure_nargs=0
+_shtab_ahriman_repo_config___no_secure_nargs=0
 _shtab_ahriman_service_config_validate__h_nargs=0
 _shtab_ahriman_service_config_validate___help_nargs=0
 _shtab_ahriman_service_config_validate__e_nargs=0

docs/completions/zsh/_ahriman

@@ -87,11 +87,11 @@ _shtab_ahriman_options=(
 
 _shtab_ahriman_add_options=(
   "(- : *)"{-h,--help}"[show this help message and exit]"
+  {--dependencies,--no-dependencies}"[process missing package dependencies (default\: \%(default)s)]:dependencies:"
   {-e,--exit-code}"[return non-zero exit status if result is empty]"
   {-n,--now}"[run update function after]"
   "*"{-y,--refresh}"[download fresh package databases from the mirror before actions, -yy to force refresh even if up to date]"
   {-s,--source}"[explicitly specify the package source for this command]:source:(auto archive aur directory local remote repository)"
-  "--without-dependencies[do not add dependencies]"
   "(*):package source (base name, path to local files, remote URL):"
 )
 
@@ -122,6 +122,7 @@ _shtab_ahriman_clean_options=(
 
 _shtab_ahriman_config_options=(
   "(- : *)"{-h,--help}"[show this help message and exit]"
+  {--secure,--no-secure}"[hide passwords and secrets from output (default\: \%(default)s)]:secure:"
 )
 
 _shtab_ahriman_config_validate_options=(
@@ -133,6 +134,7 @@ _shtab_ahriman_daemon_options=(
   "(- : *)"{-h,--help}"[show this help message and exit]"
   {-i,--interval}"[interval between runs in seconds]:interval:"
   {--aur,--no-aur}"[enable or disable checking for AUR updates (default\: \%(default)s)]:aur:"
+  {--dependencies,--no-dependencies}"[process missing package dependencies (default\: \%(default)s)]:dependencies:"
   {--local,--no-local}"[enable or disable checking of local packages for updates (default\: \%(default)s)]:local:"
   {--manual,--no-manual}"[include or exclude manual updates (default\: \%(default)s)]:manual:"
   {--vcs,--no-vcs}"[fetch actual version of VCS packages (default\: \%(default)s)]:vcs:"
@@ -182,11 +184,11 @@ _shtab_ahriman_key_import_options=(
 
 _shtab_ahriman_package_add_options=(
   "(- : *)"{-h,--help}"[show this help message and exit]"
+  {--dependencies,--no-dependencies}"[process missing package dependencies (default\: \%(default)s)]:dependencies:"
   {-e,--exit-code}"[return non-zero exit status if result is empty]"
   {-n,--now}"[run update function after]"
   "*"{-y,--refresh}"[download fresh package databases from the mirror before actions, -yy to force refresh even if up to date]"
   {-s,--source}"[explicitly specify the package source for this command]:source:(auto archive aur directory local remote repository)"
-  "--without-dependencies[do not add dependencies]"
   "(*):package source (base name, path to local files, remote URL):"
 )
 
@@ -217,11 +219,11 @@ _shtab_ahriman_package_status_update_options=(
 
 _shtab_ahriman_package_update_options=(
   "(- : *)"{-h,--help}"[show this help message and exit]"
+  {--dependencies,--no-dependencies}"[process missing package dependencies (default\: \%(default)s)]:dependencies:"
   {-e,--exit-code}"[return non-zero exit status if result is empty]"
   {-n,--now}"[run update function after]"
   "*"{-y,--refresh}"[download fresh package databases from the mirror before actions, -yy to force refresh even if up to date]"
   {-s,--source}"[explicitly specify the package source for this command]:source:(auto archive aur directory local remote repository)"
-  "--without-dependencies[do not add dependencies]"
   "(*):package source (base name, path to local files, remote URL):"
 )
 
@@ -293,6 +295,7 @@ _shtab_ahriman_repo_clean_options=(
 
 _shtab_ahriman_repo_config_options=(
   "(- : *)"{-h,--help}"[show this help message and exit]"
+  {--secure,--no-secure}"[hide passwords and secrets from output (default\: \%(default)s)]:secure:"
 )
 
 _shtab_ahriman_repo_config_validate_options=(
@@ -304,6 +307,7 @@ _shtab_ahriman_repo_daemon_options=(
   "(- : *)"{-h,--help}"[show this help message and exit]"
   {-i,--interval}"[interval between runs in seconds]:interval:"
   {--aur,--no-aur}"[enable or disable checking for AUR updates (default\: \%(default)s)]:aur:"
+  {--dependencies,--no-dependencies}"[process missing package dependencies (default\: \%(default)s)]:dependencies:"
   {--local,--no-local}"[enable or disable checking of local packages for updates (default\: \%(default)s)]:local:"
   {--manual,--no-manual}"[include or exclude manual updates (default\: \%(default)s)]:manual:"
   {--vcs,--no-vcs}"[fetch actual version of VCS packages (default\: \%(default)s)]:vcs:"
@@ -390,9 +394,10 @@ _shtab_ahriman_repo_triggers_options=(
 
 _shtab_ahriman_repo_update_options=(
   "(- : *)"{-h,--help}"[show this help message and exit]"
+  {--aur,--no-aur}"[enable or disable checking for AUR updates (default\: \%(default)s)]:aur:"
+  {--dependencies,--no-dependencies}"[process missing package dependencies (default\: \%(default)s)]:dependencies:"
   "--dry-run[just perform check for updates, same as check command]"
   {-e,--exit-code}"[return non-zero exit status if result is empty]"
-  {--aur,--no-aur}"[enable or disable checking for AUR updates (default\: \%(default)s)]:aur:"
   {--local,--no-local}"[enable or disable checking of local packages for updates (default\: \%(default)s)]:local:"
   {--manual,--no-manual}"[include or exclude manual updates (default\: \%(default)s)]:manual:"
   {--vcs,--no-vcs}"[fetch actual version of VCS packages (default\: \%(default)s)]:vcs:"
@@ -423,6 +428,7 @@ _shtab_ahriman_service_clean_options=(
 
 _shtab_ahriman_service_config_options=(
   "(- : *)"{-h,--help}"[show this help message and exit]"
+  {--secure,--no-secure}"[hide passwords and secrets from output (default\: \%(default)s)]:secure:"
 )
 
 _shtab_ahriman_service_config_validate_options=(
@@ -504,9 +510,10 @@ _shtab_ahriman_sync_options=(
 
 _shtab_ahriman_update_options=(
   "(- : *)"{-h,--help}"[show this help message and exit]"
+  {--aur,--no-aur}"[enable or disable checking for AUR updates (default\: \%(default)s)]:aur:"
+  {--dependencies,--no-dependencies}"[process missing package dependencies (default\: \%(default)s)]:dependencies:"
   "--dry-run[just perform check for updates, same as check command]"
   {-e,--exit-code}"[return non-zero exit status if result is empty]"
-  {--aur,--no-aur}"[enable or disable checking for AUR updates (default\: \%(default)s)]:aur:"
   {--local,--no-local}"[enable or disable checking of local packages for updates (default\: \%(default)s)]:local:"
   {--manual,--no-manual}"[include or exclude manual updates (default\: \%(default)s)]:manual:"
   {--vcs,--no-vcs}"[fetch actual version of VCS packages (default\: \%(default)s)]:vcs:"

docs/configuration.rst

@@ -50,6 +50,7 @@ Base authorization settings. ``OAuth`` provider requires ``aioauth-client`` libr
 * ``allow_read_only`` - allow requesting status APIs without authorization, boolean, required.
 * ``client_id`` - OAuth2 application client ID, string, required in case if ``oauth`` is used.
 * ``client_secret`` - OAuth2 application client secret key, string, required in case if ``oauth`` is used.
+* ``cookie_secret_key`` - secret key which will be used for cookies encryption, string, optional. It must be 32 url-safe base64-encoded bytes and can be generated as following ``base64.urlsafe_b64encode(os.urandom(32)).decode("utf8")``. If not set, it will be generated automatically; note, however, that in this case, all sessions will be automatically expired during restart.
 * ``max_age`` - parameter which controls both cookie expiration and token expiration inside the service, integer, optional, default is 7 days.
 * ``oauth_provider`` - OAuth2 provider class name as is in ``aioauth-client`` (e.g. ``GoogleClient``, ``GithubClient`` etc), string, required in case if ``oauth`` is used.
 * ``oauth_scopes`` - scopes list for OAuth2 provider, which will allow retrieving user email (which is used for checking user permissions), e.g. ``https://www.googleapis.com/auth/userinfo.email`` for ``GoogleClient`` or ``user:email`` for ``GithubClient``, space separated list of strings, required in case if ``oauth`` is used.
@@ -68,7 +69,7 @@ Build related configuration. Group name can refer to architecture, e.g. ``build:
 * ``makepkg_flags`` - additional flags passed to ``makepkg`` command, space separated list of strings, optional.
 * ``makechrootpkg_flags`` - additional flags passed to ``makechrootpkg`` command, space separated list of strings, optional.
 * ``triggers`` - list of ``ahriman.core.triggers.Trigger`` class implementation (e.g. ``ahriman.core.report.ReportTrigger ahriman.core.upload.UploadTrigger``) which will be loaded and run at the end of processing, space separated list of strings, optional. You can also specify triggers by their paths, e.g. ``/usr/lib/python3.10/site-packages/ahriman/core/report/report.py.ReportTrigger``. Triggers are run in the order of mention.
-* ``vcs_allowed_age`` - maximal age in seconds of the VCS packages before their version will be updated with its remote source, int, optional, default ``0``.
+* ``vcs_allowed_age`` - maximal age in seconds of the VCS packages before their version will be updated with its remote source, int, optional, default ``604800``.
 
 ``repository`` group
 --------------------

docs/faq.rst

@@ -878,6 +878,11 @@ How to enable OAuth authorization
 #.
    Restart web service ``systemctl restart ahriman-web@x86_64``.
 
+How to implement own interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can write your own interface by using API which is provided by the web service. Full autogenerated API documentation is available at ``http://localhost:8080/api-docs``.
+
 Backup and restore
 ------------------
 

package/archlinux/PKGBUILD

@@ -1,7 +1,7 @@
 # Maintainer: Evgeniy Alekseev
 
 pkgname='ahriman'
-pkgver=2.6.1
+pkgver=2.8.0
 pkgrel=1
 pkgdesc="ArcH linux ReposItory MANager"
 arch=('any')
@@ -14,6 +14,8 @@ optdepends=('breezy: -bzr packages support'
             'mercurial: -hg packages support'
             'python-aioauth-client: web server with OAuth2 authorization'
             'python-aiohttp: web server'
+            'python-aiohttp-apispec>=3.0.0: web server'
+            'python-aiohttp-cors: web server'
             'python-aiohttp-debugtoolbar: web server with enabled debug panel'
             'python-aiohttp-jinja2: web server'
             'python-aiohttp-security: web server with authorization'

package/share/ahriman/templates/api.jinja2

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>ahriman API</title>
+
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    <!-- Embed elements Elements via Web Component -->
+    <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
+    <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css" type="text/css">
+
+    <link rel="shortcut icon" href="/static/favicon.ico">
+</head>
+<body>
+
+    <elements-api
+            apiDescriptionUrl="/api-docs/swagger.json"
+            router="hash"
+            layout="sidebar"
+    />
+
+</body>
+</html>

setup.py

@@ -68,6 +68,7 @@ setup(
         ]),
         # templates
         ("share/ahriman/templates", [
+            "package/share/ahriman/templates/api.jinja2",
             "package/share/ahriman/templates/build-status.jinja2",
             "package/share/ahriman/templates/email-index.jinja2",
             "package/share/ahriman/templates/error.jinja2",
@@ -140,9 +141,11 @@ setup(
         ],
         "web": [
             "Jinja2",
-            "aiohttp",
-            "aiohttp_jinja2",
             "aioauth-client",
+            "aiohttp",
+            "aiohttp-apispec",
+            "aiohttp_cors",
+            "aiohttp_jinja2",
             "aiohttp_debugtoolbar",
             "aiohttp_session",
             "aiohttp_security",

src/ahriman/application/ahriman.py

@@ -245,6 +245,8 @@ def _set_package_add_parser(root: SubParserAction) -> argparse.ArgumentParser:
                                     "5) and finally you can add package from AUR.",
                              formatter_class=_formatter)
     parser.add_argument("package", help="package source (base name, path to local files, remote URL)", nargs="+")
+    parser.add_argument("--dependencies", help="process missing package dependencies",
+                        action=argparse.BooleanOptionalAction, default=True)
     parser.add_argument("-e", "--exit-code", help="return non-zero exit status if result is empty", action="store_true")
     parser.add_argument("-n", "--now", help="run update function after", action="store_true")
     parser.add_argument("-y", "--refresh", help="download fresh package databases from the mirror before actions, "
@@ -252,7 +254,6 @@ def _set_package_add_parser(root: SubParserAction) -> argparse.ArgumentParser:
                         action="count", default=False)
     parser.add_argument("-s", "--source", help="explicitly specify the package source for this command",
                         type=PackageSource, choices=enum_values(PackageSource), default=PackageSource.Auto)
-    parser.add_argument("--without-dependencies", help="do not add dependencies", action="store_true")
     parser.set_defaults(handler=handlers.Add)
     return parser
 
@@ -472,7 +473,7 @@ def _set_repo_check_parser(root: SubParserAction) -> argparse.ArgumentParser:
     parser.add_argument("-y", "--refresh", help="download fresh package databases from the mirror before actions, "
                                                 "-yy to force refresh even if up to date",
                         action="count", default=False)
-    parser.set_defaults(handler=handlers.Update, dry_run=True, aur=True, local=True, manual=False)
+    parser.set_defaults(handler=handlers.Update, dependencies=False, dry_run=True, aur=True, local=True, manual=False)
     return parser
 
 
@@ -492,6 +493,8 @@ def _set_repo_daemon_parser(root: SubParserAction) -> argparse.ArgumentParser:
     parser.add_argument("-i", "--interval", help="interval between runs in seconds", type=int, default=60 * 60 * 12)
     parser.add_argument("--aur", help="enable or disable checking for AUR updates",
                         action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--dependencies", help="process missing package dependencies",
+                        action=argparse.BooleanOptionalAction, default=True)
     parser.add_argument("--local", help="enable or disable checking of local packages for updates",
                         action=argparse.BooleanOptionalAction, default=True)
     parser.add_argument("--manual", help="include or exclude manual updates",
@@ -691,10 +694,12 @@ def _set_repo_update_parser(root: SubParserAction) -> argparse.ArgumentParser:
                              description="check for packages updates and run build process if requested",
                              formatter_class=_formatter)
     parser.add_argument("package", help="filter check by package base", nargs="*")
-    parser.add_argument("--dry-run", help="just perform check for updates, same as check command", action="store_true")
-    parser.add_argument("-e", "--exit-code", help="return non-zero exit status if result is empty", action="store_true")
     parser.add_argument("--aur", help="enable or disable checking for AUR updates",
                         action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--dependencies", help="process missing package dependencies",
+                        action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--dry-run", help="just perform check for updates, same as check command", action="store_true")
+    parser.add_argument("-e", "--exit-code", help="return non-zero exit status if result is empty", action="store_true")
     parser.add_argument("--local", help="enable or disable checking of local packages for updates",
                         action=argparse.BooleanOptionalAction, default=True)
     parser.add_argument("--manual", help="include or exclude manual updates",
@@ -750,6 +755,8 @@ def _set_service_config_parser(root: SubParserAction) -> argparse.ArgumentParser
     parser = root.add_parser("service-config", aliases=["config", "repo-config"], help="dump configuration",
                              description="dump configuration for the specified architecture",
                              formatter_class=_formatter)
+    parser.add_argument("--secure", help="hide passwords and secrets from output",
+                        action=argparse.BooleanOptionalAction, default=True)
     parser.set_defaults(handler=handlers.Dump, lock=None, report=False, quiet=True, unsafe=True)
     return parser
 

src/ahriman/application/application/application.py

@@ -17,10 +17,11 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
-from typing import Set
+from typing import Iterable, List, Set
 
 from ahriman.application.application.application_packages import ApplicationPackages
 from ahriman.application.application.application_repository import ApplicationRepository
+from ahriman.models.package import Package
 from ahriman.models.result import Result
 
 
@@ -87,3 +88,39 @@ class Application(ApplicationPackages, ApplicationRepository):
         directly as it will be called after on_start action
         """
         self.repository.triggers.on_stop()
+
+    def with_dependencies(self, packages: List[Package], *, process_dependencies: bool) -> List[Package]:
+        """
+        add missing dependencies to list of packages
+
+        Args:
+            packages(List[Package]): list of source packages of which dependencies have to be processed
+            process_dependencies(bool): if no set, dependencies will not be processed
+        """
+        def missing_dependencies(source: Iterable[Package]) -> Set[str]:
+            # build initial list of dependencies
+            result = set()
+            for package in source:
+                result.update(package.depends_build)
+
+            # remove ones which are already well-known
+            result = result.difference(known_packages)
+
+            # remove ones which are in this list already
+            for package in source:
+                result = result.difference(package.packages_full)
+
+            return result
+
+        if not process_dependencies or not packages:
+            return packages
+
+        known_packages = self._known_packages()
+        with_dependencies = {package.base: package for package in packages}
+
+        while missing := missing_dependencies(with_dependencies.values()):
+            for package_name in missing:
+                package = Package.from_aur(package_name, self.repository.pacman)
+                with_dependencies[package.base] = package
+
+        return list(with_dependencies.values())

src/ahriman/application/application/application_packages.py

@@ -21,7 +21,7 @@ import requests
 import shutil
 
 from pathlib import Path
-from typing import Any, Iterable, Set
+from typing import Any, Iterable
 
 from ahriman.application.application.application_properties import ApplicationProperties
 from ahriman.core.build_tools.sources import Sources
@@ -47,22 +47,18 @@ class ApplicationPackages(ApplicationProperties):
         dst = self.repository.paths.packages / local_path.name
         shutil.copy(local_path, dst)
 
-    def _add_aur(self, source: str, known_packages: Set[str], without_dependencies: bool) -> None:
+    def _add_aur(self, source: str) -> None:
         """
         add package from AUR
 
         Args:
             source(str): package base name
-            known_packages(Set[str]): list of packages which are known by the service
-            without_dependencies(bool): if set, dependency check will be disabled
         """
         package = Package.from_aur(source, self.repository.pacman)
 
         self.database.build_queue_insert(package)
         self.database.remote_update(package)
 
-        self._process_dependencies(package, known_packages, without_dependencies)
-
     def _add_directory(self, source: str, *_: Any) -> None:
         """
         add packages from directory
@@ -74,14 +70,12 @@ class ApplicationPackages(ApplicationProperties):
         for full_path in filter(package_like, local_dir.iterdir()):
             self._add_archive(str(full_path))
 
-    def _add_local(self, source: str, known_packages: Set[str], without_dependencies: bool) -> None:
+    def _add_local(self, source: str) -> None:
         """
         add package from local PKGBUILDs
 
         Args:
             source(str): path to directory with local source files
-            known_packages(Set[str]): list of packages which are known by the service
-            without_dependencies(bool): if set, dependency check will be disabled
         """
         source_dir = Path(source)
         package = Package.from_build(source_dir, self.architecture)
@@ -91,8 +85,6 @@ class ApplicationPackages(ApplicationProperties):
 
         self.database.build_queue_insert(package)
 
-        self._process_dependencies(package, known_packages, without_dependencies)
-
     def _add_remote(self, source: str, *_: Any) -> None:
         """
         add package from remote sources (e.g. HTTP)
@@ -101,7 +93,8 @@ class ApplicationPackages(ApplicationProperties):
             source(str): remote URL of the package archive
         """
         dst = self.repository.paths.packages / Path(source).name  # URL is path, is not it?
-        response = requests.get(source, stream=True, timeout=None)  # timeout=None to suppress pylint warns
+        # timeout=None to suppress pylint warns. Also suppress bandit warnings
+        response = requests.get(source, stream=True, timeout=None)  # nosec
         response.raise_for_status()
 
         with dst.open("wb") as local_file:
@@ -118,50 +111,19 @@ class ApplicationPackages(ApplicationProperties):
         package = Package.from_official(source, self.repository.pacman)
         self.database.build_queue_insert(package)
         self.database.remote_update(package)
-        # repository packages must not depend on unknown packages, thus we are not going to process dependencies
 
-    def _known_packages(self) -> Set[str]:
-        """
-        load packages from repository and pacman repositories
-
-        Returns:
-            Set[str]: list of known packages
-
-        Raises:
-            NotImplementedError: not implemented method
-        """
-        raise NotImplementedError
-
-    def _process_dependencies(self, package: Package, known_packages: Set[str], without_dependencies: bool) -> None:
-        """
-        process package dependencies
-
-        Args:
-            package(Package): source package of which dependencies have to be processed
-            known_packages(Set[str]): list of packages which are known by the service
-            without_dependencies(bool): if set, dependency check will be disabled
-        """
-        if without_dependencies:
-            return
-
-        dependencies = package.depends_build
-        self.add(dependencies.difference(known_packages), PackageSource.AUR, without_dependencies)
-
-    def add(self, names: Iterable[str], source: PackageSource, without_dependencies: bool) -> None:
+    def add(self, names: Iterable[str], source: PackageSource) -> None:
         """
         add packages for the next build
 
         Args:
             names(Iterable[str]): list of package bases to add
             source(PackageSource): package source to add
-            without_dependencies(bool): if set, dependency check will be disabled
         """
-        known_packages = self._known_packages()  # speedup dependencies processing
-
         for name in names:
             resolved_source = source.resolve(name)
             fn = getattr(self, f"_add_{resolved_source.value}")
-            fn(name, known_packages, without_dependencies)
+            fn(name)
 
     def on_result(self, result: Result) -> None:
         """

src/ahriman/application/handlers/add.py

@@ -47,11 +47,12 @@ class Add(Handler):
         application = Application(architecture, configuration,
                                   report=report, unsafe=unsafe, refresh_pacman_database=args.refresh)
         application.on_start()
-        application.add(args.package, args.source, args.without_dependencies)
+        application.add(args.package, args.source)
         if not args.now:
             return
 
         packages = application.updates(args.package, aur=False, local=False, manual=True, vcs=False,
                                        log_fn=application.logger.info)
+        packages = application.with_dependencies(packages, process_dependencies=args.dependencies)
         result = application.update(packages)
         Add.check_if_empty(args.exit_code, result.is_empty)

src/ahriman/application/handlers/dump.py

@@ -48,4 +48,4 @@ class Dump(Handler):
         """
         dump = configuration.dump()
         for section, values in sorted(dump.items()):
-            ConfigurationPrinter(section, values).print(verbose=False, separator=" = ")
+            ConfigurationPrinter(section, values).print(verbose=not args.secure, separator=" = ")

src/ahriman/application/handlers/search.py

@@ -40,7 +40,7 @@ class Search(Handler):
     """
 
     ALLOW_AUTO_ARCHITECTURE_RUN = False  # it should be called only as "no-architecture"
-    SORT_FIELDS = {field.name for field in fields(AURPackage) if field.default_factory is not list}
+    SORT_FIELDS = {field.name for field in fields(AURPackage) if field.default_factory is not list}  # type: ignore
 
     @classmethod
     def run(cls: Type[Handler], args: argparse.Namespace, architecture: str, configuration: Configuration, *,

src/ahriman/application/handlers/update.py

@@ -53,6 +53,7 @@ class Update(Handler):
         if args.dry_run:
             return
 
+        packages = application.with_dependencies(packages, process_dependencies=args.dependencies)
         result = application.update(packages)
         Update.check_if_empty(args.exit_code, result.is_empty)
 

src/ahriman/application/handlers/validate.py

@@ -52,7 +52,7 @@ class Validate(Handler):
             unsafe(bool): if set no user check will be performed before path creation
         """
         schema = Validate.schema(architecture, configuration)
-        validator = Validator(instance=configuration, schema=schema)
+        validator = Validator(configuration=configuration, schema=schema)
 
         if validator.validate(configuration.dump()):
             return  # no errors found

src/ahriman/application/handlers/web.py

@@ -55,3 +55,7 @@ class Web(Handler):
 
         application = setup_service(architecture, configuration, spawner)
         run_server(application)
+
+        # terminate spawn process at the last
+        spawner.stop()
+        spawner.join()

src/ahriman/core/configuration/configuration.py

@@ -56,7 +56,7 @@ class Configuration(configparser.RawConfigParser):
         architecture according to the merge rules. Moreover, the architecture names will be removed from section names.
 
         In order to get current settings, the ``check_loaded`` method can be used. This method will raise an
-        ``InitializeException`` in case if configuration was not yet loaded::
+        ``InitializeError`` in case if configuration was not yet loaded::
 
             >>> path, architecture = configuration.check_loaded()
     """
@@ -165,7 +165,7 @@ class Configuration(configparser.RawConfigParser):
             Tuple[Path, str]: configuration root path and architecture if loaded
 
         Raises:
-            InitializeException: in case if architecture and/or path are not set
+            InitializeError: in case if architecture and/or path are not set
         """
         if self.path is None or self.architecture is None:
             raise InitializeError("Configuration path and/or architecture are not set")
@@ -213,9 +213,9 @@ class Configuration(configparser.RawConfigParser):
         if self.has_section(full_section):
             return full_section, section
         # okay lets just use section as type
-        if not self.has_section(section):
-            raise configparser.NoSectionError(section)
-        return section, section
+        if self.has_section(section):
+            return section, section
+        raise configparser.NoSectionError(section)
 
     def load(self, path: Path) -> None:
         """

src/ahriman/core/configuration/schema.py

@@ -64,6 +64,7 @@ CONFIGURATION_SCHEMA: ConfigurationSchema = {
             "mirror": {
                 "type": "string",
                 "required": True,
+                "is_url": [],
             },
             "repositories": {
                 "type": "list",
@@ -109,9 +110,15 @@ CONFIGURATION_SCHEMA: ConfigurationSchema = {
             "client_secret": {
                 "type": "string",
             },
+            "cookie_secret_key": {
+                "type": "string",
+                "minlength": 32,
+                "maxlength": 64,  # we cannot verify maxlength, because base64 representation might be longer than bytes
+            },
             "max_age": {
                 "type": "integer",
                 "coerce": "integer",
+                "min": 0,
             },
             "oauth_provider": {
                 "type": "string",
@@ -159,6 +166,7 @@ CONFIGURATION_SCHEMA: ConfigurationSchema = {
             "vcs_allowed_age": {
                 "type": "integer",
                 "coerce": "integer",
+                "min": 0,
             },
         },
     },
@@ -201,6 +209,7 @@ CONFIGURATION_SCHEMA: ConfigurationSchema = {
         "schema": {
             "address": {
                 "type": "string",
+                "is_url": ["http", "https"],
             },
             "debug": {
                 "type": "boolean",
@@ -217,9 +226,11 @@ CONFIGURATION_SCHEMA: ConfigurationSchema = {
             },
             "host": {
                 "type": "string",
+                "is_ip_address": ["localhost"],
             },
             "index_url": {
                 "type": "string",
+                "is_url": ["http", "https"],
             },
             "password": {
                 "type": "string",
@@ -255,44 +266,4 @@ CONFIGURATION_SCHEMA: ConfigurationSchema = {
             },
         },
     },
-    "remote-pull": {
-        "type": "dict",
-        "schema": {
-            "target": {
-                "type": "list",
-                "coerce": "list",
-                "schema": {"type": "string"},
-            },
-        },
-    },
-    "remote-push": {
-        "type": "dict",
-        "schema": {
-            "target": {
-                "type": "list",
-                "coerce": "list",
-                "schema": {"type": "string"},
-            },
-        },
-    },
-    "report": {
-        "type": "dict",
-        "schema": {
-            "target": {
-                "type": "list",
-                "coerce": "list",
-                "schema": {"type": "string"},
-            },
-        },
-    },
-    "upload": {
-        "type": "dict",
-        "schema": {
-            "target": {
-                "type": "list",
-                "coerce": "list",
-                "schema": {"type": "string"},
-            },
-        },
-    },
 }

src/ahriman/core/configuration/validator.py

@@ -17,19 +17,22 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import ipaddress
+
 from cerberus import TypeDefinition, Validator as RootValidator  # type: ignore
 from pathlib import Path
 from typing import Any, List
+from urllib.parse import urlparse
 
 from ahriman.core.configuration import Configuration
 
 
-class Validator(RootValidator):  # type: ignore
+class Validator(RootValidator):
     """
     class which defines custom validation methods for the service configuration
 
     Attributes:
-        instance(Configuration): configuration instance
+        configuration(Configuration): configuration instance
     """
 
     types_mapping = RootValidator.types_mapping.copy()
@@ -40,12 +43,12 @@ class Validator(RootValidator):  # type: ignore
         default constructor
 
         Args:
-            instance(Configuration): configuration instance used for extraction
+            configuration(Configuration): configuration instance used for extraction
             *args(Any): positional arguments to be passed to base validator
             **kwargs(): keyword arguments to be passed to base validator
         """
         RootValidator.__init__(self, *args, **kwargs)
-        self.instance: Configuration = kwargs["instance"]
+        self.configuration: Configuration = kwargs["configuration"]
 
     def _normalize_coerce_absolute_path(self, value: str) -> Path:
         """
@@ -57,7 +60,7 @@ class Validator(RootValidator):  # type: ignore
         Returns:
             Path: value converted to path instance according to configuration rules
         """
-        converted: Path = self.instance.converters["path"](value)
+        converted: Path = self.configuration.converters["path"](value)
         return converted
 
     def _normalize_coerce_boolean(self, value: str) -> bool:
@@ -71,7 +74,7 @@ class Validator(RootValidator):  # type: ignore
             bool: value converted to boolean according to configuration rules
         """
         # pylint: disable=protected-access
-        converted: bool = self.instance._convert_to_boolean(value)  # type: ignore
+        converted: bool = self.configuration._convert_to_boolean(value)  # type: ignore
         return converted
 
     def _normalize_coerce_integer(self, value: str) -> int:
@@ -97,9 +100,50 @@ class Validator(RootValidator):  # type: ignore
         Returns:
             List[str]: value converted to string list instance according to configuration rules
         """
-        converted: List[str] = self.instance.converters["list"](value)
+        converted: List[str] = self.configuration.converters["list"](value)
         return converted
 
+    def _validate_is_ip_address(self, constraint: List[str], field: str, value: str) -> None:
+        """
+        check if the specified value is valid ip address
+
+        Args:
+            constraint(List[str]): optional list of allowed special words (e.g. ``localhost``)
+            field(str): field name to be checked
+            value(Path): value to be checked
+
+        Examples:
+            The rule's arguments are validated against this schema:
+            {"type": "list", "schema": {"type": "string"}}
+        """
+        if value in constraint:
+            return
+        try:
+            ipaddress.ip_address(value)
+        except ValueError:
+            self._error(field, f"Value {value} must be valid IP address")
+
+    def _validate_is_url(self, constraint: List[str], field: str, value: str) -> None:
+        """
+        check if the specified value is a valid url
+
+        Args:
+            constraint(List[str]): optional list of supported schemas. If empty, no schema validation will be performed
+            field(str): field name to be checked
+            value(str): value to be checked
+
+        Examples:
+            The rule's arguments are validated against this schema:
+            {"type": "list", "schema": {"type": "string"}}
+        """
+        url = urlparse(value)  # it probably will never rise exceptions on parse
+        if not url.scheme:
+            self._error(field, f"Url scheme is not set for {value}")
+        if not url.netloc and url.scheme not in ("file",):
+            self._error(field, f"Location must be set for url {value} of scheme {url.scheme}")
+        if constraint and url.scheme not in constraint:
+            self._error(field, f"Url {value} scheme must be one of {constraint}")
+
     def _validate_path_exists(self, constraint: bool, field: str, value: Path) -> None:
         """
         check if paths exists

src/ahriman/core/database/migrations/m000_initial.py

@@ -114,19 +114,19 @@ def migrate_package_statuses(connection: Connection, paths: RepositoryPaths) ->
             values
             (:package_base, :version, :aur_url)
             """,
-            dict(package_base=metadata.base, version=metadata.version, aur_url=""))
+            {"package_base": metadata.base, "version": metadata.version, "aur_url": ""})
         connection.execute(
             """
             insert into package_statuses
             (package_base, status, last_updated)
             values
             (:package_base, :status, :last_updated)""",
-            dict(package_base=metadata.base, status=last_status.status.value, last_updated=last_status.timestamp))
+            {"package_base": metadata.base, "status": last_status.status.value, "last_updated": last_status.timestamp})
 
     def insert_packages(metadata: Package) -> None:
         package_list = []
         for name, description in metadata.packages.items():
-            package_list.append(dict(package=name, package_base=metadata.base, **description.view()))
+            package_list.append({"package": name, "package_base": metadata.base, **description.view()})
         connection.executemany(
             """
             insert into packages

src/ahriman/core/database/migrations/m001_package_source.py

@@ -80,11 +80,11 @@ def migrate_package_remotes(connection: Connection, paths: RepositoryPaths) -> N
             web_url = :web_url, source = :source
             where package_base = :package_base
             """,
-            dict(
-                package_base=base,
-                branch=remote.branch, git_url=remote.git_url, path=remote.path,
-                web_url=remote.web_url, source=remote.source
-            )
+            {
+                "package_base": base,
+                "branch": remote.branch, "git_url": remote.git_url, "path": remote.path,
+                "web_url": remote.web_url, "source": remote.source
+            }
         )
 
     packages = PackageOperations._packages_get_select_package_bases(connection)

src/ahriman/core/database/operations/logs_operations.py

@@ -71,12 +71,12 @@ class LogsOperations(Operations):
                 values
                 (:package_base, :process_id, :created, :record)
                 """,
-                dict(
-                    package_base=log_record_id.package_base,
-                    process_id=log_record_id.process_id,
-                    created=created,
-                    record=record
-                )
+                {
+                    "package_base": log_record_id.package_base,
+                    "process_id": log_record_id.process_id,
+                    "created": created,
+                    "record": record,
+                }
             )
 
         return self.with_connection(run, commit=True)

src/ahriman/core/database/operations/operations.py

@@ -20,7 +20,7 @@
 import sqlite3
 
 from pathlib import Path
-from typing import Any, Dict, Tuple, TypeVar, Callable
+from typing import Any, Callable, Dict, Tuple, TypeVar
 
 from ahriman.core.log import LazyLogging
 

src/ahriman/core/database/operations/package_operations.py

@@ -82,15 +82,15 @@ class PackageOperations(Operations):
             on conflict (package_base) do update set
             version = :version, branch = :branch, git_url = :git_url, path = :path, web_url = :web_url, source = :source
             """,
-            dict(
-                package_base=package.base,
-                version=package.version,
-                branch=package.remote.branch if package.remote is not None else None,
-                git_url=package.remote.git_url if package.remote is not None else None,
-                path=package.remote.path if package.remote is not None else None,
-                web_url=package.remote.web_url if package.remote is not None else None,
-                source=package.remote.source.value if package.remote is not None else None,
-            )
+            {
+                "package_base": package.base,
+                "version": package.version,
+                "branch": package.remote.branch if package.remote is not None else None,
+                "git_url": package.remote.git_url if package.remote is not None else None,
+                "path": package.remote.path if package.remote is not None else None,
+                "web_url": package.remote.web_url if package.remote is not None else None,
+                "source": package.remote.source.value if package.remote is not None else None,
+            }
         )
 
     @staticmethod
@@ -106,7 +106,7 @@ class PackageOperations(Operations):
         for name, description in package.packages.items():
             if description.architecture is None:
                 continue  # architecture is required
-            package_list.append(dict(package=name, package_base=package.base, **description.view()))
+            package_list.append({"package": name, "package_base": package.base, **description.view()})
         connection.executemany(
             """
             insert into packages
@@ -145,7 +145,7 @@ class PackageOperations(Operations):
             on conflict (package_base) do update set
             status = :status, last_updated = :last_updated
             """,
-            dict(package_base=package_base, status=status.status.value, last_updated=status.timestamp))
+            {"package_base": package_base, "status": status.status.value, "last_updated": status.timestamp})
 
     @staticmethod
     def _packages_get_select_package_bases(connection: Connection) -> Dict[str, Package]:

src/ahriman/core/formatters/__init__.py

@@ -27,7 +27,7 @@ from ahriman.core.formatters.package_printer import PackagePrinter
 from ahriman.core.formatters.patch_printer import PatchPrinter
 from ahriman.core.formatters.status_printer import StatusPrinter
 from ahriman.core.formatters.tree_printer import TreePrinter
-from ahriman.core.formatters.validation_printer import ValidationPrinter
 from ahriman.core.formatters.update_printer import UpdatePrinter
 from ahriman.core.formatters.user_printer import UserPrinter
+from ahriman.core.formatters.validation_printer import ValidationPrinter
 from ahriman.core.formatters.version_printer import VersionPrinter

src/ahriman/core/formatters/configuration_printer.py

@@ -28,9 +28,20 @@ class ConfigurationPrinter(StringPrinter):
     print content of the configuration section
 
     Attributes:
+        HIDE_KEYS(List[str]): (class attribute) hide values for mentioned keys. This list must be used in order to hide
+            passwords from outputs
         values(Dict[str, str]): configuration values dictionary
     """
 
+    HIDE_KEYS = [
+        "api_key",  # telegram key
+        "client_secret",  # oauth secret
+        "cookie_secret_key",  # cookie secret key
+        "password",  # generic password (github, email, web server, etc)
+        "salt",  # password default salt
+        "secret_key",  # aws secret key
+    ]
+
     def __init__(self, section: str, values: Dict[str, str]) -> None:
         """
         default constructor
@@ -50,6 +61,6 @@ class ConfigurationPrinter(StringPrinter):
             List[Property]: list of content properties
         """
         return [
-            Property(key, value, is_required=True)
+            Property(key, value, is_required=key not in self.HIDE_KEYS)
             for key, value in sorted(self.values.items())
         ]

src/ahriman/core/formatters/printer.py

@@ -33,7 +33,7 @@ class Printer:
 
         Args:
             verbose(bool): print all fields
-            log_fn(Callable[[str], None]): logger function to log data (Default value = print)
+            log_fn(Callable[[str], None], optional): logger function to log data (Default value = print)
             separator(str, optional): separator for property name and property value (Default value = ": ")
         """
         if (title := self.title()) is not None:

src/ahriman/core/gitremote/remote_pull_trigger.py

@@ -33,6 +33,16 @@ class RemotePullTrigger(Trigger):
     """
 
     CONFIGURATION_SCHEMA = {
+        "remote-pull": {
+            "type": "dict",
+            "schema": {
+                "target": {
+                    "type": "list",
+                    "coerce": "list",
+                    "schema": {"type": "string"},
+                },
+            },
+        },
         "gitremote": {
             "type": "dict",
             "schema": {

src/ahriman/core/gitremote/remote_push.py

@@ -82,7 +82,10 @@ class RemotePush(LazyLogging):
         Sources.fetch(package_target_dir, package.remote)
         # ...and last, but not least, we remove the dot-git directory...
         for git_file in package_target_dir.glob(".git*"):
-            shutil.rmtree(package_target_dir / git_file)
+            if git_file.is_file():
+                git_file.unlink()
+            else:
+                shutil.rmtree(git_file)
         # ...copy all patches...
         for patch in self.database.patches_get(package.base):
             filename = f"ahriman-{package.base}.patch" if patch.key is None else f"ahriman-{patch.key}.patch"

src/ahriman/core/gitremote/remote_push_trigger.py

@@ -38,6 +38,16 @@ class RemotePushTrigger(Trigger):
     """
 
     CONFIGURATION_SCHEMA = {
+        "remote-push": {
+            "type": "dict",
+            "schema": {
+                "target": {
+                    "type": "list",
+                    "coerce": "list",
+                    "schema": {"type": "string"},
+                },
+            },
+        },
         "gitremote": {
             "type": "dict",
             "schema": {

src/ahriman/core/report/report_trigger.py

@@ -35,6 +35,16 @@ class ReportTrigger(Trigger):
     """
 
     CONFIGURATION_SCHEMA = {
+        "report": {
+            "type": "dict",
+            "schema": {
+                "target": {
+                    "type": "list",
+                    "coerce": "list",
+                    "schema": {"type": "string"},
+                },
+            },
+        },
         "console": {
             "type": "dict",
             "schema": {
@@ -62,6 +72,7 @@ class ReportTrigger(Trigger):
                 },
                 "homepage": {
                     "type": "string",
+                    "is_url": ["http", "https"],
                 },
                 "host": {
                     "type": "string",
@@ -70,6 +81,7 @@ class ReportTrigger(Trigger):
                 "link_path": {
                     "type": "string",
                     "required": True,
+                    "is_url": [],
                 },
                 "no_empty_report": {
                     "type": "boolean",
@@ -82,6 +94,8 @@ class ReportTrigger(Trigger):
                     "type": "integer",
                     "coerce": "integer",
                     "required": True,
+                    "min": 0,
+                    "max": 65535,
                 },
                 "receivers": {
                     "type": "list",
@@ -118,10 +132,12 @@ class ReportTrigger(Trigger):
                 },
                 "homepage": {
                     "type": "string",
+                    "is_url": ["http", "https"],
                 },
                 "link_path": {
                     "type": "string",
                     "required": True,
+                    "is_url": [],
                 },
                 "path": {
                     "type": "path",
@@ -153,10 +169,12 @@ class ReportTrigger(Trigger):
                 },
                 "homepage": {
                     "type": "string",
+                    "is_url": ["http", "https"],
                 },
                 "link_path": {
                     "type": "string",
                     "required": True,
+                    "is_url": [],
                 },
                 "template_path": {
                     "type": "path",
@@ -171,6 +189,7 @@ class ReportTrigger(Trigger):
                 "timeout": {
                     "type": "integer",
                     "coerce": "integer",
+                    "min": 0,
                 },
             },
         },

src/ahriman/core/repository/executor.py

@@ -21,7 +21,7 @@ import shutil
 
 from pathlib import Path
 from tempfile import TemporaryDirectory
-from typing import Iterable, List, Optional
+from typing import Dict, Iterable, List, Optional
 
 from ahriman.core.build_tools.task import Task
 from ahriman.core.repository.cleaner import Cleaner
@@ -122,26 +122,40 @@ class Executor(Cleaner):
             except Exception:
                 self.logger.exception("could not remove %s", package)
 
+        packages_to_remove: Dict[str, Path] = {}
+        bases_to_remove: List[str] = []
+
+        # build package list based on user input
         requested = set(packages)
         for local in self.packages():
             if local.base in packages or all(package in requested for package in local.packages):
-                to_remove = {
+                packages_to_remove.update({
                     package: properties.filepath
                     for package, properties in local.packages.items()
                     if properties.filepath is not None
-                }
-                remove_base(local.base)
+                })
+                bases_to_remove.append(local.base)
             elif requested.intersection(local.packages.keys()):
-                to_remove = {
+                packages_to_remove.update({
                     package: properties.filepath
                     for package, properties in local.packages.items()
                     if package in requested and properties.filepath is not None
-                }
-            else:
-                to_remove = {}
+                })
 
-            for package, filename in to_remove.items():
-                remove_package(package, filename)
+        # check for packages which were requested to remove, but weren't found locally
+        # it might happen for example, if there were no success build before
+        for unknown in requested:
+            if unknown in packages_to_remove or unknown in bases_to_remove:
+                continue
+            bases_to_remove.append(unknown)
+
+        # remove packages from repository files
+        for package, filename in packages_to_remove.items():
+            remove_package(package, filename)
+
+        # remove bases from registered
+        for package in bases_to_remove:
+            remove_base(package)
 
         return self.repo.repo_path
 

src/ahriman/core/spawn.py

@@ -60,7 +60,7 @@ class Spawn(Thread, LazyLogging):
         self.lock = Lock()
         self.active: Dict[str, Process] = {}
         # stupid pylint does not know that it is possible
-        self.queue: Queue[Tuple[str, bool]] = Queue()  # pylint: disable=unsubscriptable-object
+        self.queue: Queue[Tuple[str, bool] | None] = Queue()  # pylint: disable=unsubscriptable-object
 
     @staticmethod
     def process(callback: Callable[[argparse.Namespace, str], bool], args: argparse.Namespace, architecture: str,
@@ -78,55 +78,7 @@ class Spawn(Thread, LazyLogging):
         result = callback(args, architecture)
         queue.put((process_id, result))
 
-    def key_import(self, key: str, server: Optional[str]) -> None:
-        """
-        import key to service cache
-
-        Args:
-            key(str): key to import
-            server(str): PGP key server
-        """
-        kwargs = {} if server is None else {"key-server": server}
-        self.spawn_process("service-key-import", key, **kwargs)
-
-    def packages_add(self, packages: Iterable[str], *, now: bool) -> None:
-        """
-        add packages
-
-        Args:
-            packages(Iterable[str]): packages list to add
-            now(bool): build packages now
-        """
-        kwargs = {"source": PackageSource.AUR.value}  # avoid abusing by building non-aur packages
-        if now:
-            kwargs["now"] = ""
-        self.spawn_process("package-add", *packages, **kwargs)
-
-    def packages_rebuild(self, depends_on: str) -> None:
-        """
-        rebuild packages which depend on the specified package
-
-        Args:
-            depends_on(str): packages dependency
-        """
-        self.spawn_process("repo-rebuild", **{"depends-on": depends_on})
-
-    def packages_remove(self, packages: Iterable[str]) -> None:
-        """
-        remove packages
-
-        Args:
-            packages(Iterable[str]): packages list to remove
-        """
-        self.spawn_process("package-remove", *packages)
-
-    def packages_update(self, ) -> None:
-        """
-        run full repository update
-        """
-        self.spawn_process("repo-update")
-
-    def spawn_process(self, command: str, *args: str, **kwargs: str) -> None:
+    def _spawn_process(self, command: str, *args: str, **kwargs: str) -> None:
         """
         spawn external ahriman process with supplied arguments
 
@@ -161,6 +113,54 @@ class Spawn(Thread, LazyLogging):
         with self.lock:
             self.active[process_id] = process
 
+    def key_import(self, key: str, server: Optional[str]) -> None:
+        """
+        import key to service cache
+
+        Args:
+            key(str): key to import
+            server(str): PGP key server
+        """
+        kwargs = {} if server is None else {"key-server": server}
+        self._spawn_process("service-key-import", key, **kwargs)
+
+    def packages_add(self, packages: Iterable[str], *, now: bool) -> None:
+        """
+        add packages
+
+        Args:
+            packages(Iterable[str]): packages list to add
+            now(bool): build packages now
+        """
+        kwargs = {"source": PackageSource.AUR.value}  # avoid abusing by building non-aur packages
+        if now:
+            kwargs["now"] = ""
+        self._spawn_process("package-add", *packages, **kwargs)
+
+    def packages_rebuild(self, depends_on: str) -> None:
+        """
+        rebuild packages which depend on the specified package
+
+        Args:
+            depends_on(str): packages dependency
+        """
+        self._spawn_process("repo-rebuild", **{"depends-on": depends_on})
+
+    def packages_remove(self, packages: Iterable[str]) -> None:
+        """
+        remove packages
+
+        Args:
+            packages(Iterable[str]): packages list to remove
+        """
+        self._spawn_process("package-remove", *packages)
+
+    def packages_update(self, ) -> None:
+        """
+        run full repository update
+        """
+        self._spawn_process("repo-update")
+
     def run(self) -> None:
         """
         thread run method
@@ -174,3 +174,9 @@ class Spawn(Thread, LazyLogging):
             if process is not None:
                 process.terminate()  # make sure lol
                 process.join()
+
+    def stop(self) -> None:
+        """
+        gracefully terminate thread
+        """
+        self.queue.put(None)

src/ahriman/core/status/web_client.py

@@ -17,17 +17,18 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import contextlib
 import logging
 import requests
 
-from typing import List, Optional, Tuple
+from typing import Generator, List, Optional, Tuple
 from urllib.parse import quote_plus as urlencode
 
 from ahriman.core.configuration import Configuration
 from ahriman.core.log import LazyLogging
 from ahriman.core.status.client import Client
 from ahriman.core.util import exception_response_text
-from ahriman.models.build_status import BuildStatusEnum, BuildStatus
+from ahriman.models.build_status import BuildStatus, BuildStatusEnum
 from ahriman.models.internal_status import InternalStatus
 from ahriman.models.package import Package
 from ahriman.models.user import User
@@ -98,6 +99,18 @@ class WebClient(Client, LazyLogging):
             address = f"http://{host}:{port}"
         return address, False
 
+    @contextlib.contextmanager
+    def __execute_request(self) -> Generator[None, None, None]:
+        """
+        execute request and handle exceptions
+        """
+        try:
+            yield
+        except requests.HTTPError as e:
+            self.logger.exception("could not perform http request: %s", exception_response_text(e))
+        except Exception:
+            self.logger.exception("could not perform http request")
+
     def _create_session(self, *, use_unix_socket: bool) -> requests.Session:
         """
         generate new request session
@@ -130,13 +143,9 @@ class WebClient(Client, LazyLogging):
             "password": self.user.password
         }
 
-        try:
+        with self.__execute_request():
             response = self.__session.post(self._login_url, json=payload)
             response.raise_for_status()
-        except requests.HTTPError as e:
-            self.logger.exception("could not login as %s: %s", self.user, exception_response_text(e))
-        except Exception:
-            self.logger.exception("could not login as %s", self.user)
 
     def _logs_url(self, package_base: str) -> str:
         """
@@ -177,13 +186,9 @@ class WebClient(Client, LazyLogging):
             "package": package.view()
         }
 
-        try:
+        with self.__execute_request():
             response = self.__session.post(self._package_url(package.base), json=payload)
             response.raise_for_status()
-        except requests.HTTPError as e:
-            self.logger.exception("could not add %s: %s", package.base, exception_response_text(e))
-        except Exception:
-            self.logger.exception("could not add %s", package.base)
 
     def get(self, package_base: Optional[str]) -> List[Tuple[Package, BuildStatus]]:
         """
@@ -195,7 +200,7 @@ class WebClient(Client, LazyLogging):
         Returns:
             List[Tuple[Package, BuildStatus]]: list of current package description and status if it has been found
         """
-        try:
+        with self.__execute_request():
             response = self.__session.get(self._package_url(package_base or ""))
             response.raise_for_status()
 
@@ -204,10 +209,8 @@ class WebClient(Client, LazyLogging):
                 (Package.from_json(package["package"]), BuildStatus.from_json(package["status"]))
                 for package in status_json
             ]
-        except requests.HTTPError as e:
-            self.logger.exception("could not get %s: %s", package_base, exception_response_text(e))
-        except Exception:
-            self.logger.exception("could not get %s", package_base)
+
+        # noinspection PyUnreachableCode
         return []
 
     def get_internal(self) -> InternalStatus:
@@ -217,16 +220,14 @@ class WebClient(Client, LazyLogging):
         Returns:
             InternalStatus: current internal (web) service status
         """
-        try:
+        with self.__execute_request():
             response = self.__session.get(self._status_url)
             response.raise_for_status()
 
             status_json = response.json()
             return InternalStatus.from_json(status_json)
-        except requests.HTTPError as e:
-            self.logger.exception("could not get web service status: %s", exception_response_text(e))
-        except Exception:
-            self.logger.exception("could not get web service status")
+
+        # noinspection PyUnreachableCode
         return InternalStatus(status=BuildStatus())
 
     def logs(self, package_base: str, record: logging.LogRecord) -> None:
@@ -254,13 +255,9 @@ class WebClient(Client, LazyLogging):
         Args:
             package_base(str): basename to remove
         """
-        try:
+        with self.__execute_request():
             response = self.__session.delete(self._package_url(package_base))
             response.raise_for_status()
-        except requests.HTTPError as e:
-            self.logger.exception("could not delete %s: %s", package_base, exception_response_text(e))
-        except Exception:
-            self.logger.exception("could not delete %s", package_base)
 
     def update(self, package_base: str, status: BuildStatusEnum) -> None:
         """
@@ -272,13 +269,9 @@ class WebClient(Client, LazyLogging):
         """
         payload = {"status": status.value}
 
-        try:
+        with self.__execute_request():
             response = self.__session.post(self._package_url(package_base), json=payload)
             response.raise_for_status()
-        except requests.HTTPError as e:
-            self.logger.exception("could not update %s: %s", package_base, exception_response_text(e))
-        except Exception:
-            self.logger.exception("could not update %s", package_base)
 
     def update_self(self, status: BuildStatusEnum) -> None:
         """
@@ -289,10 +282,6 @@ class WebClient(Client, LazyLogging):
         """
         payload = {"status": status.value}
 
-        try:
+        with self.__execute_request():
             response = self.__session.post(self._status_url, json=payload)
             response.raise_for_status()
-        except requests.HTTPError as e:
-            self.logger.exception("could not update service status: %s", exception_response_text(e))
-        except Exception:
-            self.logger.exception("could not update service status")

src/ahriman/core/tree.py

@@ -19,10 +19,11 @@
 #
 from __future__ import annotations
 
-import itertools
+import functools
 
-from typing import Callable, Iterable, List, Tuple
+from typing import Callable, Iterable, List
 
+from ahriman.core.util import partition
 from ahriman.models.package import Package
 
 
@@ -149,13 +150,6 @@ class Tree:
         Returns:
             List[List[Package]]: sorted list of packages lists based on their dependencies
         """
-        # https://docs.python.org/dev/library/itertools.html#itertools-recipes
-        def partition(source: List[Leaf]) -> Tuple[List[Leaf], Iterable[Leaf]]:
-            first_iter, second_iter = itertools.tee(source)
-            filter_fn: Callable[[Leaf], bool] = lambda leaf: leaf.is_dependency(next_level)
-            # materialize first list and leave second as iterator
-            return list(filter(filter_fn, first_iter)), itertools.filterfalse(filter_fn, second_iter)
-
         unsorted: List[List[Leaf]] = []
 
         # build initial tree
@@ -170,7 +164,9 @@ class Tree:
             next_level = unsorted[next_num]
 
             # change lists inside the collection
-            unsorted[current_num], to_be_moved = partition(current_level)
+            # additional workaround with partial in order to hide cell-var-from-loop pylint warning
+            predicate = functools.partial(Leaf.is_dependency, packages=next_level)
+            unsorted[current_num], to_be_moved = partition(current_level, predicate)
             unsorted[next_num].extend(to_be_moved)
 
         comparator: Callable[[Package], str] = lambda package: package.base

src/ahriman/core/upload/upload_trigger.py

@@ -35,6 +35,16 @@ class UploadTrigger(Trigger):
     """
 
     CONFIGURATION_SCHEMA = {
+        "upload": {
+            "type": "dict",
+            "schema": {
+                "target": {
+                    "type": "list",
+                    "coerce": "list",
+                    "schema": {"type": "string"},
+                },
+            },
+        },
         "github": {
             "type": "dict",
             "schema": {
@@ -57,6 +67,7 @@ class UploadTrigger(Trigger):
                 "timeout": {
                     "type": "integer",
                     "coerce": "integer",
+                    "min": 0,
                 },
                 "username": {
                     "type": "string",
@@ -101,6 +112,7 @@ class UploadTrigger(Trigger):
                 "chunk_size": {
                     "type": "integer",
                     "coerce": "integer",
+                    "min": 0,
                 },
                 "region": {
                     "type": "string",

src/ahriman/core/util.py

@@ -19,6 +19,7 @@
 #
 import datetime
 import io
+import itertools
 import logging
 import os
 import re
@@ -28,14 +29,31 @@ import subprocess
 from enum import Enum
 from pathlib import Path
 from pwd import getpwuid
-from typing import Any, Dict, Generator, IO, Iterable, List, Optional, Type, Union
+from typing import Any, Callable, Dict, Generator, IO, Iterable, List, Optional, Tuple, Type, TypeVar, Union
 
 from ahriman.core.exceptions import OptionError, UnsafeRunError
 from ahriman.models.repository_paths import RepositoryPaths
 
 
-__all__ = ["check_output", "check_user", "enum_values", "exception_response_text", "filter_json", "full_version",
-           "package_like", "pretty_datetime", "pretty_size", "safe_filename", "trim_package", "utcnow", "walk"]
+__all__ = [
+    "check_output",
+    "check_user",
+    "enum_values",
+    "exception_response_text",
+    "filter_json",
+    "full_version",
+    "package_like",
+    "partition",
+    "pretty_datetime",
+    "pretty_size",
+    "safe_filename",
+    "trim_package",
+    "utcnow",
+    "walk",
+]
+
+
+T = TypeVar("T")
 
 
 def check_output(*args: str, exception: Optional[Exception] = None, cwd: Optional[Path] = None,
@@ -225,6 +243,21 @@ def package_like(filename: Path) -> bool:
     return ".pkg." in name and not name.endswith(".sig")
 
 
+def partition(source: List[T], predicate: Callable[[T], bool]) -> Tuple[List[T], List[T]]:
+    """
+    partition list into two based on predicate, based on # https://docs.python.org/dev/library/itertools.html#itertools-recipes
+
+    Args:
+        source(List[T]): source list to be partitioned
+        predicate(Callable[[T], bool]): filter function
+
+    Returns:
+        Tuple[List[T], List[T]]: two lists, first is which ``predicate`` is ``True``, second is ``False``
+    """
+    first_iter, second_iter = itertools.tee(source)
+    return list(filter(predicate, first_iter)), list(itertools.filterfalse(predicate, second_iter))
+
+
 def pretty_datetime(timestamp: Optional[Union[datetime.datetime, float, int]]) -> str:
     """
     convert datetime object to string

src/ahriman/models/package.py

@@ -17,7 +17,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
-# pylint: disable=too-many-lines
+# pylint: disable=too-many-lines,too-many-public-methods
 from __future__ import annotations
 
 import copy
@@ -96,7 +96,7 @@ class Package(LazyLogging):
         Returns:
             Set[str]: full dependencies list used by devtools
         """
-        return (set(self.depends) | set(self.depends_make)) - self.packages.keys()
+        return (set(self.depends) | set(self.depends_make)).difference(self.packages_full)
 
     @property
     def depends_make(self) -> List[str]:
@@ -163,6 +163,20 @@ class Package(LazyLogging):
         """
         return sorted(set(sum((package.licenses for package in self.packages.values()), start=[])))
 
+    @property
+    def packages_full(self) -> List[str]:
+        """
+        get full packages list including provides
+
+        Returns:
+            List[str]: full list of packages which this base contains
+        """
+        packages = set()
+        for package, properties in self.packages.items():
+            packages.add(package)
+            packages.update(properties.provides)
+        return sorted(packages)
+
     @classmethod
     def from_archive(cls: Type[Package], path: Path, pacman: Pacman, remote: Optional[RemoteSource]) -> Package:
         """

src/ahriman/models/result.py

@@ -19,7 +19,7 @@
 #
 from __future__ import annotations
 
-from typing import Any, List, Optional, Iterable
+from typing import Any, Iterable, List, Optional
 
 from ahriman.core.exceptions import UnprocessedPackageStatusError
 from ahriman.models.package import Package

src/ahriman/models/user_identity.py

@@ -1,102 +0,0 @@
-#
-# Copyright (c) 2021-2023 ahriman team.
-#
-# This file is part of ahriman
-# (see https://github.com/arcan1s/ahriman).
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program. If not, see <http://www.gnu.org/licenses/>.
-#
-from __future__ import annotations
-
-import time
-
-from dataclasses import dataclass
-from typing import Optional, Type
-
-
-@dataclass(frozen=True)
-class UserIdentity:
-    """
-    user identity used inside web service
-
-    Attributes:
-        username(str): username
-        expire_at(int): identity expiration timestamp
-    """
-
-    username: str
-    expire_at: int
-
-    @classmethod
-    def from_identity(cls: Type[UserIdentity], identity: str) -> Optional[UserIdentity]:
-        """
-        parse identity into object
-
-        Args:
-            identity(str): identity from session data
-
-        Returns:
-            Optional[UserIdentity]: user identity object if it can be parsed and not expired and None otherwise
-        """
-        try:
-            username, expire_at = identity.split()
-            user = cls(username, int(expire_at))
-            return None if user.is_expired() else user
-        except ValueError:
-            return None
-
-    @classmethod
-    def from_username(cls: Type[UserIdentity], username: Optional[str], max_age: int) -> Optional[UserIdentity]:
-        """
-        generate identity from username
-
-        Args:
-            username(Optional[str]): username
-            max_age(int): time to expire, seconds
-
-        Returns:
-            Optional[UserIdentity]: constructed identity object
-        """
-        return cls(username, cls.expire_when(max_age)) if username is not None else None
-
-    @staticmethod
-    def expire_when(max_age: int) -> int:
-        """
-        generate expiration time using delta
-
-        Args:
-            max_age(int): time delta to generate. Must be usually TTE
-
-        Returns:
-            int: expiration timestamp
-        """
-        return int(time.time()) + max_age
-
-    def is_expired(self) -> bool:
-        """
-        compare timestamp with current timestamp and return True in case if identity is expired
-
-        Returns:
-            bool: True in case if identity is expired and False otherwise
-        """
-        return self.expire_when(0) > self.expire_at
-
-    def to_identity(self) -> str:
-        """
-        convert object to identity representation
-
-        Returns:
-            str: web service identity
-        """
-        return f"{self.username} {self.expire_at}"

src/ahriman/version.py

@@ -17,4 +17,4 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
-__version__ = "2.6.1"
+__version__ = "2.8.0"

src/ahriman/web/apispec.py

@@ -0,0 +1,120 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+import aiohttp_apispec  # type: ignore
+
+from aiohttp.web import Application
+from typing import Any, Dict, List
+
+from ahriman import version
+from ahriman.core.configuration import Configuration
+
+
+__all__ = ["setup_apispec"]
+
+
+def _info() -> Dict[str, Any]:
+    """
+    create info object for swagger docs
+
+    Returns:
+        Dict[str, Any]: info object as per openapi specification
+    """
+    return {
+        "title": "ahriman",
+        "description": """Wrapper for managing custom repository inspired by [repo-scripts](https://github.com/arcan1s/repo-scripts).
+
+## Features
+
+* Install-configure-forget manager for the very own repository.
+* Multi-architecture support.
+* Dependency manager.
+* VCS packages support.
+* Official repository support.
+* Ability to patch AUR packages and even create package from local PKGBUILDs.
+* Sign support with gpg (repository, package, per package settings).
+* Triggers for repository updates, e.g. synchronization to remote services (rsync, s3 and github) and report generation (email, html, telegram).
+* Repository status interface with optional authorization and control options
+
+<security-definitions />
+""",
+        "license": {
+            "name": "GPL3",
+            "url": "https://raw.githubusercontent.com/arcan1s/ahriman/master/COPYING",
+        },
+        "version": version.__version__,
+    }
+
+
+def _security() -> List[Dict[str, Any]]:
+    """
+    get security definitions
+
+    Returns:
+        List[Dict[str, Any]]: generated security definition
+    """
+    return [{
+        "token": {
+            "type": "apiKey",  # as per specification we are using api key
+            "name": "API_SESSION",
+            "in": "cookie",
+        }
+    }]
+
+
+def _servers(application: Application) -> List[Dict[str, Any]]:
+    """
+    get list of defined addresses for server
+
+    Args:
+        application(Application): web application instance
+
+    Returns:
+        List[Dict[str, Any]]: list (actually only one) of defined web urls
+    """
+    configuration: Configuration = application["configuration"]
+    address = configuration.get("web", "address", fallback=None)
+    if not address:
+        host = configuration.get("web", "host")
+        port = configuration.getint("web", "port")
+        address = f"http://{host}:{port}"
+
+    return [{
+        "url": address,
+    }]
+
+
+def setup_apispec(application: Application) -> aiohttp_apispec.AiohttpApiSpec:
+    """
+    setup swagger api specification
+
+    Args:
+        application(Application): web application instance
+
+    Returns:
+        aiohttp_apispec.AiohttpApiSpec: created specification instance
+    """
+    return aiohttp_apispec.setup_aiohttp_apispec(
+        application,
+        url="/api-docs/swagger.json",
+        openapi_version="3.0.2",
+        info=_info(),
+        servers=_servers(application),
+        security=_security(),
+    )

src/ahriman/web/cors.py

@@ -0,0 +1,48 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+import aiohttp_cors  # type: ignore
+
+from aiohttp.web import Application
+
+
+__all__ = ["setup_cors"]
+
+
+def setup_cors(application: Application) -> aiohttp_cors.CorsConfig:
+    """
+    setup CORS for the web application
+
+    Args:
+        application(Application): web application instance
+
+    Returns:
+        aiohttp_cors.CorsConfig: generated CORS configuration
+    """
+    cors = aiohttp_cors.setup(application, defaults={
+        "*": aiohttp_cors.ResourceOptions(
+            expose_headers="*",
+            allow_headers="*",
+            allow_methods="*",
+        )
+    })
+    for route in application.router.routes():
+        cors.add(route)
+
+    return cors

src/ahriman/web/middlewares/__init__.py

@@ -17,8 +17,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
-from aiohttp.web import Request
-from aiohttp.web_response import StreamResponse
+from aiohttp.web import Request, StreamResponse
 from typing import Awaitable, Callable
 
 

src/ahriman/web/middlewares/auth_handler.py

@@ -18,29 +18,25 @@
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
 import aiohttp_security  # type: ignore
-import base64
 import socket
 import types
 
-from aiohttp import web
-from aiohttp.web import middleware, Request
-from aiohttp.web_response import StreamResponse
-from aiohttp.web_urldispatcher import StaticResource
+from aiohttp.web import Application, Request, StaticResource, StreamResponse, middleware
 from aiohttp_session import setup as setup_session
 from aiohttp_session.cookie_storage import EncryptedCookieStorage
 from cryptography import fernet
 from typing import Optional
 
 from ahriman.core.auth import Auth
+from ahriman.core.configuration import Configuration
 from ahriman.models.user_access import UserAccess
-from ahriman.models.user_identity import UserIdentity
 from ahriman.web.middlewares import HandlerType, MiddlewareType
 
 
-__all__ = ["AuthorizationPolicy", "auth_handler", "setup_auth"]
+__all__ = ["setup_auth"]
 
 
-class AuthorizationPolicy(aiohttp_security.AbstractAuthorizationPolicy):  # type: ignore
+class _AuthorizationPolicy(aiohttp_security.AbstractAuthorizationPolicy):
     """
     authorization policy implementation
 
@@ -67,10 +63,7 @@ class AuthorizationPolicy(aiohttp_security.AbstractAuthorizationPolicy):  # type
         Returns:
             Optional[str]: user identity (username) in case if user exists and None otherwise
         """
-        user = UserIdentity.from_identity(identity)
-        if user is None:
-            return None
-        return user.username if await self.validator.known_username(user.username) else None
+        return identity if await self.validator.known_username(identity) else None
 
     async def permits(self, identity: str, permission: UserAccess, context: Optional[str] = None) -> bool:
         """
@@ -84,13 +77,10 @@ class AuthorizationPolicy(aiohttp_security.AbstractAuthorizationPolicy):  # type
         Returns:
             bool: True in case if user is allowed to perform this request and False otherwise
         """
-        user = UserIdentity.from_identity(identity)
-        if user is None:
-            return False
-        return await self.validator.verify_access(user.username, permission, context)
+        return await self.validator.verify_access(identity, permission, context)
 
 
-def auth_handler(allow_read_only: bool) -> MiddlewareType:
+def _auth_handler(allow_read_only: bool) -> MiddlewareType:
     """
     authorization and authentication middleware
 
@@ -125,26 +115,43 @@ def auth_handler(allow_read_only: bool) -> MiddlewareType:
     return handle
 
 
-def setup_auth(application: web.Application, validator: Auth) -> web.Application:
+def _cookie_secret_key(configuration: Configuration) -> fernet.Fernet:
+    """
+    extract cookie secret key from configuration if set or generate new one
+
+    Args:
+        configuration(Configuration): configuration instance
+
+    Returns:
+        fernet.Fernet: fernet key instance
+    """
+    if (secret_key := configuration.get("auth", "cookie_secret_key", fallback=None)) is not None:
+        return fernet.Fernet(secret_key)
+
+    secret_key = fernet.Fernet.generate_key()
+    return fernet.Fernet(secret_key)
+
+
+def setup_auth(application: Application, configuration: Configuration, validator: Auth) -> Application:
     """
     setup authorization policies for the application
 
     Args:
-        application(web.Application): web application instance
+        application(Application): web application instance
+        configuration(Configuration): configuration instance
         validator(Auth): authorization module instance
 
     Returns:
-        web.Application: configured web application
+        Application: configured web application
     """
-    fernet_key = fernet.Fernet.generate_key()
-    secret_key = base64.urlsafe_b64decode(fernet_key)
+    secret_key = _cookie_secret_key(configuration)
     storage = EncryptedCookieStorage(secret_key, cookie_name="API_SESSION", max_age=validator.max_age)
     setup_session(application, storage)
 
-    authorization_policy = AuthorizationPolicy(validator)
+    authorization_policy = _AuthorizationPolicy(validator)
     identity_policy = aiohttp_security.SessionIdentityPolicy()
 
     aiohttp_security.setup(application, identity_policy, authorization_policy)
-    application.middlewares.append(auth_handler(validator.allow_read_only))
+    application.middlewares.append(_auth_handler(validator.allow_read_only))
 
     return application

src/ahriman/web/middlewares/exception_handler.py

@@ -20,8 +20,8 @@
 import aiohttp_jinja2
 import logging
 
-from aiohttp.web import HTTPClientError, HTTPException, HTTPServerError, HTTPUnauthorized, Request, StreamResponse, \
-    json_response, middleware
+from aiohttp.web import HTTPClientError, HTTPException, HTTPMethodNotAllowed, HTTPNoContent, HTTPServerError, \
+    HTTPUnauthorized, Request, StreamResponse, json_response, middleware
 
 from ahriman.web.middlewares import HandlerType, MiddlewareType
 
@@ -29,6 +29,20 @@ from ahriman.web.middlewares import HandlerType, MiddlewareType
 __all__ = ["exception_handler"]
 
 
+def _is_templated_unauthorized(request: Request) -> bool:
+    """
+    check if the request is eligible for rendering html template
+
+    Args:
+        request(Request): source request to check
+
+    Returns:
+        bool: True in case if response should be rendered as html and False otherwise
+    """
+    return request.path in ("/api/v1/login", "/api/v1/logout") \
+        and "application/json" not in request.headers.getall("accept", [])
+
+
 def exception_handler(logger: logging.Logger) -> MiddlewareType:
     """
     exception handler middleware. Just log any exception (except for client ones)
@@ -44,10 +58,21 @@ def exception_handler(logger: logging.Logger) -> MiddlewareType:
         try:
             return await handler(request)
         except HTTPUnauthorized as e:
-            if is_templated_unauthorized(request):
+            if _is_templated_unauthorized(request):
                 context = {"code": e.status_code, "reason": e.reason}
                 return aiohttp_jinja2.render_template("error.jinja2", request, context, status=e.status_code)
             return json_response(data={"error": e.reason}, status=e.status_code)
+        except HTTPMethodNotAllowed as e:
+            if e.method == "OPTIONS":
+                # automatically handle OPTIONS method, idea comes from
+                # https://github.com/arcan1s/ffxivbis/blob/master/src/main/scala/me/arcanis/ffxivbis/http/api/v1/HttpHandler.scala#L32
+                raise HTTPNoContent(headers={"Allow": ",".join(sorted(e.allowed_methods))})
+            if e.method == "HEAD":
+                # since we have special autogenerated HEAD method, we need to remove it from list of available
+                e.allowed_methods = {method for method in e.allowed_methods if method != "HEAD"}
+                e.headers["Allow"] = ",".join(sorted(e.allowed_methods))
+                raise e
+            raise
         except HTTPClientError as e:
             return json_response(data={"error": e.reason}, status=e.status_code)
         except HTTPServerError as e:
@@ -60,17 +85,3 @@ def exception_handler(logger: logging.Logger) -> MiddlewareType:
             return json_response(data={"error": str(e)}, status=500)
 
     return handle
-
-
-def is_templated_unauthorized(request: Request) -> bool:
-    """
-    check if the request is eligible for rendering html template
-
-    Args:
-        request(Request): source request to check
-
-    Returns:
-        bool: True in case if response should be rendered as html and False otherwise
-    """
-    return request.path in ("/api/v1/login", "/api/v1/logout") \
-        and "application/json" not in request.headers.getall("accept", [])

src/ahriman/web/routes.py

@@ -20,6 +20,8 @@
 from aiohttp.web import Application
 from pathlib import Path
 
+from ahriman.web.views.api.docs import DocsView
+from ahriman.web.views.api.swagger import SwaggerView
 from ahriman.web.views.index import IndexView
 from ahriman.web.views.service.add import AddView
 from ahriman.web.views.service.pgp import PGPView
@@ -43,82 +45,31 @@ def setup_routes(application: Application, static_path: Path) -> None:
     """
     setup all defined routes
 
-    Available routes are:
-
-        * ``GET /`` get build status page
-        * ``GET /index.html`` same as above
-
-        * ``POST /api/v1/service/add`` add new packages to repository
-
-        * ``GET /api/v1/service/pgp`` fetch PGP key from the keyserver
-        * ``POST /api/v1/service/pgp`` import PGP key from the keyserver
-
-        * ``POST /api/v1/service/rebuild`` rebuild packages based on their dependency list
-
-        * ``POST /api/v1/service/remove`` remove existing package from repository
-
-        * ``POST /api/v1/service/request`` request to add new packages to repository
-
-        * ``GET /api/v1/service/search`` search for substring in AUR
-
-        * ``POST /api/v1/service/update`` update all packages in repository
-
-        * ``GET /api/v1/packages`` get all known packages
-        * ``POST /api/v1/packages`` force update every package from repository
-
-        * ``DELETE /api/v1/package/:base`` delete package base from status page
-        * ``GET /api/v1/package/:base`` get package base status
-        * ``POST /api/v1/package/:base`` update package base status
-
-        * ``DELETE /api/v1/packages/{package}/logs`` delete package related logs
-        * ``GET /api/v1/packages/{package}/logs`` create log record for the package
-        * ``POST /api/v1/packages/{package}/logs`` get last package logs
-
-        * ``GET /api/v1/status`` get service status itself
-        * ``POST /api/v1/status`` update service status itself
-
-        * ``GET /api/v1/login`` OAuth2 handler for login
-        * ``POST /api/v1/login`` login to service
-        * ``POST /api/v1/logout`` logout from service
-
     Args:
         application(Application): web application instance
         static_path(Path): path to static files directory
     """
-    application.router.add_get("/", IndexView, allow_head=True)
-    application.router.add_get("/index.html", IndexView, allow_head=True)
+    application.router.add_view("/", IndexView)
+    application.router.add_view("/index.html", IndexView)
+
+    application.router.add_view("/api-docs", DocsView)
+    application.router.add_view("/api-docs/swagger.json", SwaggerView)
 
     application.router.add_static("/static", static_path, follow_symlinks=True)
 
-    application.router.add_post("/api/v1/service/add", AddView)
+    application.router.add_view("/api/v1/service/add", AddView)
+    application.router.add_view("/api/v1/service/pgp", PGPView)
+    application.router.add_view("/api/v1/service/rebuild", RebuildView)
+    application.router.add_view("/api/v1/service/remove", RemoveView)
+    application.router.add_view("/api/v1/service/request", RequestView)
+    application.router.add_view("/api/v1/service/search", SearchView)
+    application.router.add_view("/api/v1/service/update", UpdateView)
 
-    application.router.add_get("/api/v1/service/pgp", PGPView, allow_head=True)
-    application.router.add_post("/api/v1/service/pgp", PGPView)
+    application.router.add_view("/api/v1/packages", PackagesView)
+    application.router.add_view("/api/v1/packages/{package}", PackageView)
+    application.router.add_view("/api/v1/packages/{package}/logs", LogsView)
 
-    application.router.add_post("/api/v1/service/rebuild", RebuildView)
+    application.router.add_view("/api/v1/status", StatusView)
 
-    application.router.add_post("/api/v1/service/remove", RemoveView)
-
-    application.router.add_post("/api/v1/service/request", RequestView)
-
-    application.router.add_get("/api/v1/service/search", SearchView, allow_head=False)
-
-    application.router.add_post("/api/v1/service/update", UpdateView)
-
-    application.router.add_get("/api/v1/packages", PackagesView, allow_head=True)
-    application.router.add_post("/api/v1/packages", PackagesView)
-
-    application.router.add_delete("/api/v1/packages/{package}", PackageView)
-    application.router.add_get("/api/v1/packages/{package}", PackageView, allow_head=True)
-    application.router.add_post("/api/v1/packages/{package}", PackageView)
-
-    application.router.add_delete("/api/v1/packages/{package}/logs", LogsView)
-    application.router.add_get("/api/v1/packages/{package}/logs", LogsView, allow_head=True)
-    application.router.add_post("/api/v1/packages/{package}/logs", LogsView)
-
-    application.router.add_get("/api/v1/status", StatusView, allow_head=True)
-    application.router.add_post("/api/v1/status", StatusView)
-
-    application.router.add_get("/api/v1/login", LoginView)
-    application.router.add_post("/api/v1/login", LoginView)
-    application.router.add_post("/api/v1/logout", LogoutView)
+    application.router.add_view("/api/v1/login", LoginView)
+    application.router.add_view("/api/v1/logout", LogoutView)

src/ahriman/web/schemas/__init__.py

@@ -0,0 +1,19 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#

src/ahriman/web/schemas/aur_package_schema.py

@@ -0,0 +1,35 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+
+class AURPackageSchema(Schema):
+    """
+    response AUR package schema
+    """
+
+    package = fields.String(required=True, metadata={
+        "description": "Package base",
+        "example": "ahriman",
+    })
+    description = fields.String(required=True, metadata={
+        "description": "Package description",
+        "example": "ArcH linux ReposItory MANager",
+    })

src/ahriman/web/schemas/auth_schema.py

@@ -0,0 +1,30 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+
+class AuthSchema(Schema):
+    """
+    request cookie authorization schema
+    """
+
+    API_SESSION = fields.String(required=True, metadata={
+        "description": "API session key as returned from authorization",
+    })

src/ahriman/web/schemas/counters_schema.py

@@ -0,0 +1,51 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+
+class CountersSchema(Schema):
+    """
+    response package counters schema
+    """
+
+    total = fields.Integer(required=True, metadata={
+        "description": "Total amount of packages",
+        "example": 6,
+    })
+    _unknown = fields.Integer(data_key="unknown", required=True, metadata={
+        "description": "Amount of packages in unknown state",
+        "example": 0,
+    })
+    pending = fields.Integer(required=True, metadata={
+        "description": "Amount of packages in pending state",
+        "example": 2,
+    })
+    building = fields.Integer(required=True, metadata={
+        "description": "Amount of packages in building state",
+        "example": 1,
+    })
+    failed = fields.Integer(required=True, metadata={
+        "description": "Amount of packages in failed state",
+        "example": 1,
+    })
+    success = fields.Integer(required=True, metadata={
+        "description": "Amount of packages in success state",
+        "example": 3,
+    })

src/ahriman/web/schemas/error_schema.py

@@ -0,0 +1,30 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+
+class ErrorSchema(Schema):
+    """
+    response error schema
+    """
+
+    error = fields.String(required=True, metadata={
+        "description": "Error description",
+    })

src/ahriman/web/schemas/internal_status_schema.py

@@ -0,0 +1,49 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+from ahriman import version
+from ahriman.web.schemas.counters_schema import CountersSchema
+from ahriman.web.schemas.status_schema import StatusSchema
+
+
+class InternalStatusSchema(Schema):
+    """
+    response service status schema
+    """
+
+    architecture = fields.String(required=True, metadata={
+        "description": "Repository architecture",
+        "example": "x86_64",
+    })
+    packages = fields.Nested(CountersSchema, required=True, metadata={
+        "description": "Repository package counters",
+    })
+    repository = fields.String(required=True, metadata={
+        "description": "Repository name",
+        "example": "repo-clone",
+    })
+    status = fields.Nested(StatusSchema, required=True, metadata={
+        "description": "Repository status as stored by web service",
+    })
+    version = fields.String(required=True, metadata={
+        "description": "Repository version",
+        "example": version.__version__,
+    })

src/ahriman/web/schemas/log_schema.py

@@ -0,0 +1,38 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+
+class LogSchema(Schema):
+    """
+    request package log schema
+    """
+
+    created = fields.Float(required=True, metadata={
+        "description": "Log record timestamp",
+        "example": 1680537091.233495,
+    })
+    process_id = fields.Integer(required=True, metadata={
+        "description": "Current process id",
+        "example": 42,
+    })
+    message = fields.String(required=True, metadata={
+        "description": "Log message",
+    })

src/ahriman/web/schemas/login_schema.py

@@ -0,0 +1,35 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+
+class LoginSchema(Schema):
+    """
+    request login schema
+    """
+
+    username = fields.String(required=True, metadata={
+        "description": "Login username",
+        "example": "user",
+    })
+    password = fields.String(required=True, metadata={
+        "description": "Login password",
+        "example": "pa55w0rd",
+    })

src/ahriman/web/schemas/logs_schema.py

@@ -0,0 +1,39 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+from ahriman.web.schemas.status_schema import StatusSchema
+
+
+class LogsSchema(Schema):
+    """
+    response package logs schema
+    """
+
+    package_base = fields.String(required=True, metadata={
+        "description": "Package base name",
+        "example": "ahriman",
+    })
+    status = fields.Nested(StatusSchema, required=True, metadata={
+        "description": "Last package status",
+    })
+    logs = fields.String(required=True, metadata={
+        "description": "Full package log from the last build",
+    })

src/ahriman/web/schemas/oauth2_schema.py

@@ -0,0 +1,30 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+
+class OAuth2Schema(Schema):
+    """
+    request OAuth2 authorization schema
+    """
+
+    code = fields.String(metadata={
+        "description": "OAuth2 authorization code. In case if not set, the redirect to provider will be initiated",
+    })

src/ahriman/web/schemas/package_name_schema.py

@@ -0,0 +1,31 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+
+class PackageNameSchema(Schema):
+    """
+    request package name schema
+    """
+
+    package = fields.String(required=True, metadata={
+        "description": "Package name",
+        "example": "ahriman",
+    })

src/ahriman/web/schemas/package_names_schema.py

@@ -0,0 +1,31 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+
+class PackageNamesSchema(Schema):
+    """
+    request package names schema
+    """
+
+    packages = fields.List(fields.String(), required=True, metadata={
+        "description": "Package names",
+        "example": ["ahriman"],
+    })

src/ahriman/web/schemas/package_properties_schema.py

@@ -0,0 +1,79 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+
+class PackagePropertiesSchema(Schema):
+    """
+    request and response package properties schema
+    """
+
+    architecture = fields.String(metadata={
+        "description": "Package architecture",
+        "example": "x86_64",
+    })
+    archive_size = fields.Integer(metadata={
+        "description": "Archive size in bytes",
+        "example": 287989,
+    })
+    build_date = fields.Integer(metadata={
+        "description": "Package build timestamp",
+        "example": 1680537091,
+    })
+    depends = fields.List(fields.String(), metadata={
+        "description": "Package dependencies list",
+        "example": ["devtools"],
+    })
+    make_depends = fields.List(fields.String(), metadata={
+        "description": "Package make dependencies list",
+        "example": ["python-build"],
+    })
+    opt_depends = fields.List(fields.String(), metadata={
+        "description": "Package optional dependencies list",
+        "example": ["python-aiohttp"],
+    })
+    description = fields.String(metadata={
+        "description": "Package description",
+        "example": "ArcH linux ReposItory MANager",
+    })
+    filename = fields.String(metadata={
+        "description": "Package file name",
+        "example": "ahriman-2.7.1-1-any.pkg.tar.zst",
+    })
+    groups = fields.List(fields.String(), metadata={
+        "description": "Package groups",
+        "example": ["base-devel"],
+    })
+    installed_size = fields.Integer(metadata={
+        "description": "Installed package size in bytes",
+        "example": 2047658,
+    })
+    licenses = fields.List(fields.String(), metadata={
+        "description": "Package licenses",
+        "example": ["GPL3"],
+    })
+    provides = fields.List(fields.String(), metadata={
+        "description": "Package provides list",
+        "example": ["ahriman-git"],
+    })
+    url = fields.String(metadata={
+        "description": "Upstream url",
+        "example": "https://github.com/arcan1s/ahriman",
+    })

src/ahriman/web/schemas/package_schema.py

@@ -0,0 +1,46 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+from ahriman import version
+from ahriman.web.schemas.package_properties_schema import PackagePropertiesSchema
+from ahriman.web.schemas.remote_schema import RemoteSchema
+
+
+class PackageSchema(Schema):
+    """
+    request and response package schema
+    """
+
+    base = fields.String(required=True, metadata={
+        "description": "Package base",
+        "example": "ahriman",
+    })
+    version = fields.String(required=True, metadata={
+        "description": "Package version",
+        "example": version.__version__,
+    })
+    remote = fields.Nested(RemoteSchema, required=True, metadata={
+        "description": "Package remote properties",
+    })
+    packages = fields.Dict(
+        keys=fields.String(), values=fields.Nested(PackagePropertiesSchema), required=True, metadata={
+            "description": "Packages which belong to this base",
+        })

src/ahriman/web/schemas/package_status_schema.py

@@ -0,0 +1,50 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+from ahriman.models.build_status import BuildStatusEnum
+from ahriman.web.schemas.package_schema import PackageSchema
+from ahriman.web.schemas.status_schema import StatusSchema
+
+
+class PackageStatusSimplifiedSchema(Schema):
+    """
+    special request package status schema
+    """
+
+    package = fields.Nested(PackageSchema, metadata={
+        "description": "Package description",
+    })
+    status = fields.Enum(BuildStatusEnum, by_value=True, required=True, metadata={
+        "description": "Current status",
+    })
+
+
+class PackageStatusSchema(Schema):
+    """
+    response package status schema
+    """
+
+    package = fields.Nested(PackageSchema, required=True, metadata={
+        "description": "Package description",
+    })
+    status = fields.Nested(StatusSchema, required=True, metadata={
+        "description": "Last package status",
+    })

src/ahriman/web/schemas/pgp_key_id_schema.py

@@ -0,0 +1,35 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+
+class PGPKeyIdSchema(Schema):
+    """
+    request PGP key ID schema
+    """
+
+    key = fields.String(required=True, metadata={
+        "description": "PGP key ID",
+        "example": "0xE989490C",
+    })
+    server = fields.String(required=True, metadata={
+        "description": "PGP key server",
+        "example": "keyserver.ubuntu.com",
+    })

src/ahriman/web/schemas/pgp_key_schema.py

@@ -0,0 +1,30 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+
+class PGPKeySchema(Schema):
+    """
+    response PGP key schema
+    """
+
+    key = fields.String(required=True, metadata={
+        "description": "PGP key body",
+    })

src/ahriman/web/schemas/remote_schema.py

@@ -0,0 +1,48 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+from ahriman.models.package_source import PackageSource
+
+
+class RemoteSchema(Schema):
+    """
+    request and response package remote schema
+    """
+
+    branch = fields.String(required=True, metadata={
+        "description": "Repository branch",
+        "example": "master",
+    })
+    git_url = fields.String(required=True, metadata={
+        "description": "Package git url",
+        "example": "https://aur.archlinux.org/ahriman.git",
+    })
+    path = fields.String(required=True, metadata={
+        "description": "Path to package sources in git repository",
+        "example": ".",
+    })
+    source = fields.Enum(PackageSource, by_value=True, required=True, metadata={
+        "description": "Pacakge source",
+    })
+    web_url = fields.String(required=True, metadata={
+        "description": "Package repository page",
+        "example": "https://aur.archlinux.org/packages/ahriman",
+    })

src/ahriman/web/schemas/search_schema.py

@@ -0,0 +1,31 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+
+class SearchSchema(Schema):
+    """
+    request package search schema
+    """
+
+    _for = fields.List(fields.String(), data_key="for", required=True, metadata={
+        "description": "Keyword for search",
+        "example": ["ahriman"],
+    })

src/ahriman/web/schemas/status_schema.py

@@ -0,0 +1,36 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from marshmallow import Schema, fields
+
+from ahriman.models.build_status import BuildStatusEnum
+
+
+class StatusSchema(Schema):
+    """
+    request and response status schema
+    """
+
+    status = fields.Enum(BuildStatusEnum, by_value=True, required=True, metadata={
+        "description": "Current status",
+    })
+    timestamp = fields.Integer(metadata={
+        "description": "Last update timestamp",
+        "example": 1680537091,
+    })

src/ahriman/web/views/api/__init__.py

@@ -0,0 +1,19 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#

src/ahriman/web/views/api/docs.py

@@ -0,0 +1,46 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+import aiohttp_jinja2
+
+from typing import Any, Dict
+
+from ahriman.models.user_access import UserAccess
+from ahriman.web.views.base import BaseView
+
+
+class DocsView(BaseView):
+    """
+    api docs view
+
+    Attributes:
+        GET_PERMISSION(UserAccess): (class attribute) get permissions of self
+    """
+
+    GET_PERMISSION = UserAccess.Unauthorized
+
+    @aiohttp_jinja2.template("api.jinja2")
+    async def get(self) -> Dict[str, Any]:
+        """
+        return static docs html
+
+        Returns:
+            Dict[str, Any]: parameters for jinja template
+        """
+        return {}

src/ahriman/web/views/api/swagger.py

@@ -0,0 +1,76 @@
+#
+# Copyright (c) 2021-2023 ahriman team.
+#
+# This file is part of ahriman
+# (see https://github.com/arcan1s/ahriman).
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+from aiohttp.web import Response, json_response
+from typing import Callable, Dict
+
+from ahriman.core.util import partition
+from ahriman.models.user_access import UserAccess
+from ahriman.web.views.base import BaseView
+
+
+class SwaggerView(BaseView):
+    """
+    api docs specification view
+
+    Attributes:
+        GET_PERMISSION(UserAccess): (class attribute) get permissions of self
+    """
+
+    GET_PERMISSION = UserAccess.Unauthorized
+
+    async def get(self) -> Response:
+        """
+        get api specification
+
+        Returns:
+            Response: 200 with json api specification
+        """
+        spec = self.request.app["swagger_dict"]
+        is_body_parameter: Callable[[Dict[str, str]], bool] = lambda p: p["in"] == "body"
+
+        # special workaround because it writes request body to parameters section
+        paths = spec["paths"]
+        for methods in paths.values():
+            for method in methods.values():
+                if "parameters" not in method:
+                    continue
+
+                body, other = partition(method["parameters"], is_body_parameter)
+                if not body:
+                    continue  # there were no ``body`` parameters found
+
+                # there should be only one body parameters
+                method["requestBody"] = {
+                    "content": {
+                        "application/json": {
+                            "schema": next(iter(body))["schema"]
+                        }
+                    }
+                }
+                method["parameters"] = other
+
+        # inject security schema
+        spec["components"]["securitySchemes"] = {
+            key: value
+            for schema in spec["security"]
+            for key, value in schema.items()
+        }
+
+        return json_response(spec)

src/ahriman/web/views/base.py

@@ -19,8 +19,9 @@
 #
 from __future__ import annotations
 
-from aiohttp.web import Request, View
-from typing import Any, Callable, Dict, List, Optional, Type, TypeVar
+from aiohttp_cors import CorsViewMixin  # type: ignore
+from aiohttp.web import Request, StreamResponse, View
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Type, TypeVar
 
 from ahriman.core.auth import Auth
 from ahriman.core.configuration import Configuration
@@ -28,15 +29,19 @@ from ahriman.core.spawn import Spawn
 from ahriman.core.status.watcher import Watcher
 from ahriman.models.user_access import UserAccess
 
-
 T = TypeVar("T", str, List[str])
 
 
-class BaseView(View):
+class BaseView(View, CorsViewMixin):
     """
     base web view to make things typed
+
+    Attributes:
+        OPTIONS_PERMISSION(UserAccess): (class attribute) options permissions of self
     """
 
+    OPTIONS_PERMISSION = UserAccess.Unauthorized
+
     @property
     def configuration(self) -> Configuration:
         """
@@ -92,7 +97,8 @@ class BaseView(View):
         Returns:
             UserAccess: extracted permission
         """
-        permission: UserAccess = getattr(cls, f"{request.method.upper()}_PERMISSION", UserAccess.Full)
+        method = "GET" if (other := request.method.upper()) == "HEAD" else other
+        permission: UserAccess = getattr(cls, f"{method}_PERMISSION", UserAccess.Full)
         return permission
 
     @staticmethod
@@ -118,23 +124,6 @@ class BaseView(View):
             raise KeyError(f"Key {key} is missing or empty")
         return value
 
-    async def extract_data(self, list_keys: Optional[List[str]] = None) -> Dict[str, Any]:
-        """
-        extract json data from either json or form data
-
-        Args:
-            list_keys(Optional[List[str]], optional): optional list of keys which must be forced to list from form data
-                (Default value = None)
-
-        Returns:
-            Dict[str, Any]: raw json object or form data converted to json
-        """
-        try:
-            json: Dict[str, Any] = await self.request.json()
-            return json
-        except ValueError:
-            return await self.data_as_json(list_keys or [])
-
     async def data_as_json(self, list_keys: List[str]) -> Dict[str, Any]:
         """
         extract form data and convert it to json object
@@ -158,3 +147,39 @@ class BaseView(View):
             else:
                 json[key] = value
         return json
+
+    async def extract_data(self, list_keys: Optional[List[str]] = None) -> Dict[str, Any]:
+        """
+        extract json data from either json or form data
+
+        Args:
+            list_keys(Optional[List[str]], optional): optional list of keys which must be forced to list from form data
+                (Default value = None)
+
+        Returns:
+            Dict[str, Any]: raw json object or form data converted to json
+        """
+        try:
+            json: Dict[str, Any] = await self.request.json()
+            return json
+        except ValueError:
+            return await self.data_as_json(list_keys or [])
+
+    # pylint: disable=not-callable,protected-access
+    async def head(self) -> StreamResponse:  # type: ignore
+        """
+        HEAD method implementation based on the result of GET method
+
+        Raises:
+            HTTPMethodNotAllowed: in case if there is no GET method implemented
+        """
+        get_method: Optional[Callable[..., Awaitable[StreamResponse]]] = getattr(self, "get", None)
+        # using if/else in order to suppress mypy warning which doesn't know that
+        # ``_raise_allowed_methods`` raises exception
+        if get_method is not None:
+            # there is a bug in pylint, see https://github.com/pylint-dev/pylint/issues/6005
+            response = await get_method()
+            response._body = b""  # type: ignore
+            return response
+
+        self._raise_allowed_methods()

src/ahriman/web/views/index.py

@@ -41,10 +41,9 @@ class IndexView(BaseView):
 
     Attributes:
         GET_PERMISSION(UserAccess): (class attribute) get permissions of self
-        HEAD_PERMISSION(UserAccess): (class attribute) head permissions of self
     """
 
-    GET_PERMISSION = HEAD_PERMISSION = UserAccess.Unauthorized
+    GET_PERMISSION = UserAccess.Unauthorized
 
     @aiohttp_jinja2.template("build-status.jinja2")
     async def get(self) -> Dict[str, Any]:

src/ahriman/web/views/service/add.py

@@ -17,9 +17,14 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import aiohttp_apispec  # type: ignore
+
 from aiohttp.web import HTTPBadRequest, HTTPNoContent
 
 from ahriman.models.user_access import UserAccess
+from ahriman.web.schemas.auth_schema import AuthSchema
+from ahriman.web.schemas.error_schema import ErrorSchema
+from ahriman.web.schemas.package_names_schema import PackageNamesSchema
 from ahriman.web.views.base import BaseView
 
 
@@ -33,34 +38,28 @@ class AddView(BaseView):
 
     POST_PERMISSION = UserAccess.Full
 
+    @aiohttp_apispec.docs(
+        tags=["Actions"],
+        summary="Add new package",
+        description="Add new package(s) from AUR",
+        responses={
+            204: {"description": "Success response"},
+            400: {"description": "Bad data is supplied", "schema": ErrorSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [POST_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.json_schema(PackageNamesSchema)
     async def post(self) -> None:
         """
         add new package
 
-        JSON body must be supplied, the following model is used::
-
-            {
-                "packages": ["ahriman"]  # either list of packages or package name as in AUR
-            }
-
         Raises:
+            HTTPBadRequest: if bad data is supplied
             HTTPNoContent: in case of success response
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Content-Type: application/json' 'http://example.com/api/v1/service/add' -d '{"packages": ["ahriman"]}'
-                > POST /api/v1/service/add HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                > Content-Type: application/json
-                > Content-Length: 25
-                >
-                < HTTP/1.1 204 No Content
-                < Date: Wed, 23 Nov 2022 18:44:21 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
         """
         try:
             data = await self.extract_data(["packages"])

src/ahriman/web/views/service/pgp.py

@@ -17,9 +17,15 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import aiohttp_apispec  # type: ignore
+
 from aiohttp.web import HTTPBadRequest, HTTPNoContent, HTTPNotFound, Response, json_response
 
 from ahriman.models.user_access import UserAccess
+from ahriman.web.schemas.auth_schema import AuthSchema
+from ahriman.web.schemas.error_schema import ErrorSchema
+from ahriman.web.schemas.pgp_key_id_schema import PGPKeyIdSchema
+from ahriman.web.schemas.pgp_key_schema import PGPKeySchema
 from ahriman.web.views.base import BaseView
 
 
@@ -29,17 +35,31 @@ class PGPView(BaseView):
 
     Attributes:
         GET_PERMISSION(UserAccess): (class attribute) get permissions of self
-        HEAD_PERMISSION(UserAccess): (class attribute) head permissions of self
         POST_PERMISSION(UserAccess): (class attribute) post permissions of self
     """
 
     POST_PERMISSION = UserAccess.Full
-    GET_PERMISSION = HEAD_PERMISSION = UserAccess.Reporter
+    GET_PERMISSION = UserAccess.Reporter
 
+    @aiohttp_apispec.docs(
+        tags=["Actions"],
+        summary="Search for PGP key",
+        description="Search for PGP key and retrieve its body",
+        responses={
+            200: {"description": "Success response", "schema": PGPKeySchema},
+            400: {"description": "Bad data is supplied", "schema": ErrorSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            404: {"description": "Package base is unknown", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [GET_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.querystring_schema(PGPKeyIdSchema)
     async def get(self) -> Response:
         """
-        retrieve key from the key server. It supports two query parameters: ``key`` - pgp key fingerprint and
-        ``server`` which points to valid PGP key server
+        retrieve key from the key server
 
         Returns:
             Response: 200 with key body on success
@@ -47,24 +67,7 @@ class PGPView(BaseView):
         Raises:
             HTTPBadRequest: if bad data is supplied
             HTTPNotFound: if key wasn't found or service was unable to fetch it
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Accept: application/json' 'http://example.com/api/v1/service/pgp?key=0xE989490C&server=keyserver.ubuntu.com'
-                > GET /api/v1/service/pgp?key=0xE989490C&server=keyserver.ubuntu.com HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: application/json
-                >
-                < HTTP/1.1 200 OK
-                < Content-Type: application/json; charset=utf-8
-                < Content-Length: 3275
-                < Date: Fri, 25 Nov 2022 22:54:02 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
-                {"key": "key"}
-                        """
+        """
         try:
             key = self.get_non_empty(self.request.query.getone, "key")
             server = self.get_non_empty(self.request.query.getone, "server")
@@ -78,36 +81,28 @@ class PGPView(BaseView):
 
         return json_response({"key": key})
 
+    @aiohttp_apispec.docs(
+        tags=["Actions"],
+        summary="Fetch PGP key",
+        description="Fetch PGP key from the key server",
+        responses={
+            204: {"description": "Success response"},
+            400: {"description": "Bad data is supplied", "schema": ErrorSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [POST_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.json_schema(PGPKeyIdSchema)
     async def post(self) -> None:
         """
         store key to the local service environment
 
-        JSON body must be supplied, the following model is used::
-
-            {
-                "key": "0x8BE91E5A773FB48AC05CC1EDBED105AED6246B39",  # key fingerprint to import
-                "server": "keyserver.ubuntu.com"                      # optional pgp server address
-            }
-
         Raises:
             HTTPBadRequest: if bad data is supplied
             HTTPNoContent: in case of success response
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Content-Type: application/json' 'http://example.com/api/v1/service/pgp' -d '{"key": "0xE989490C"}'
-                > POST /api/v1/service/pgp HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                > Content-Type: application/json
-                > Content-Length: 21
-                >
-                < HTTP/1.1 204 No Content
-                < Date: Fri, 25 Nov 2022 22:55:56 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
         """
         data = await self.extract_data()
 

src/ahriman/web/views/service/rebuild.py

@@ -17,9 +17,14 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import aiohttp_apispec  # type: ignore
+
 from aiohttp.web import HTTPBadRequest, HTTPNoContent
 
 from ahriman.models.user_access import UserAccess
+from ahriman.web.schemas.auth_schema import AuthSchema
+from ahriman.web.schemas.error_schema import ErrorSchema
+from ahriman.web.schemas.package_names_schema import PackageNamesSchema
 from ahriman.web.views.base import BaseView
 
 
@@ -33,40 +38,33 @@ class RebuildView(BaseView):
 
     POST_PERMISSION = UserAccess.Full
 
+    @aiohttp_apispec.docs(
+        tags=["Actions"],
+        summary="Rebuild packages",
+        description="Rebuild packages which depend on specified one",
+        responses={
+            204: {"description": "Success response"},
+            400: {"description": "Bad data is supplied", "schema": ErrorSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [POST_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.json_schema(PackageNamesSchema)
     async def post(self) -> None:
         """
         rebuild packages based on their dependency
 
-        JSON body must be supplied, the following model is used::
-
-            {
-                "packages": ["ahriman"]  # either list of packages or package name of dependency
-            }
-
         Raises:
             HTTPBadRequest: if bad data is supplied
             HTTPNoContent: in case of success response
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Content-Type: application/json' 'http://example.com/api/v1/service/rebuild' -d '{"packages": ["python"]}'
-                > POST /api/v1/service/rebuild HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                > Content-Type: application/json
-                > Content-Length: 24
-                >
-                < HTTP/1.1 204 No Content
-                < Date: Sun, 27 Nov 2022 00:22:26 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
         """
         try:
             data = await self.extract_data(["packages"])
             packages = self.get_non_empty(lambda key: [package for package in data[key] if package], "packages")
-            depends_on = next(package for package in packages)
+            depends_on = next(iter(packages))
         except Exception as e:
             raise HTTPBadRequest(reason=str(e))
 

src/ahriman/web/views/service/remove.py

@@ -17,9 +17,14 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import aiohttp_apispec  # type: ignore
+
 from aiohttp.web import HTTPBadRequest, HTTPNoContent
 
 from ahriman.models.user_access import UserAccess
+from ahriman.web.schemas.auth_schema import AuthSchema
+from ahriman.web.schemas.error_schema import ErrorSchema
+from ahriman.web.schemas.package_names_schema import PackageNamesSchema
 from ahriman.web.views.base import BaseView
 
 
@@ -33,35 +38,28 @@ class RemoveView(BaseView):
 
     POST_PERMISSION = UserAccess.Full
 
+    @aiohttp_apispec.docs(
+        tags=["Actions"],
+        summary="Remove packages",
+        description="Remove specified packages from the repository",
+        responses={
+            204: {"description": "Success response"},
+            400: {"description": "Bad data is supplied", "schema": ErrorSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [POST_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.json_schema(PackageNamesSchema)
     async def post(self) -> None:
         """
         remove existing packages
 
-        JSON body must be supplied, the following model is used::
-
-            {
-                "packages": ["ahriman"]  # either list of packages or package name
-            }
-
         Raises:
             HTTPBadRequest: if bad data is supplied
             HTTPNoContent: in case of success response
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Content-Type: application/json' 'http://example.com/api/v1/service/remove' -d '{"packages": ["ahriman"]}'
-                > POST /api/v1/service/remove HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                > Content-Type: application/json
-                > Content-Length: 25
-                >
-                < HTTP/1.1 204 No Content
-                < Date: Wed, 23 Nov 2022 18:57:56 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
         """
         try:
             data = await self.extract_data(["packages"])

src/ahriman/web/views/service/request.py

@@ -17,9 +17,14 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import aiohttp_apispec  # type: ignore
+
 from aiohttp.web import HTTPBadRequest, HTTPNoContent
 
 from ahriman.models.user_access import UserAccess
+from ahriman.web.schemas.auth_schema import AuthSchema
+from ahriman.web.schemas.error_schema import ErrorSchema
+from ahriman.web.schemas.package_names_schema import PackageNamesSchema
 from ahriman.web.views.base import BaseView
 
 
@@ -33,35 +38,28 @@ class RequestView(BaseView):
 
     POST_PERMISSION = UserAccess.Reporter
 
+    @aiohttp_apispec.docs(
+        tags=["Actions"],
+        summary="Request new package",
+        description="Request new package(s) to be added from AUR",
+        responses={
+            204: {"description": "Success response"},
+            400: {"description": "Bad data is supplied", "schema": ErrorSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [POST_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.json_schema(PackageNamesSchema)
     async def post(self) -> None:
         """
         request to add new package
 
-        JSON body must be supplied, the following model is used::
-
-            {
-                "packages": ["ahriman"]  # either list of packages or package name as in AUR
-            }
-
         Raises:
             HTTPBadRequest: if bad data is supplied
             HTTPNoContent: in case of success response
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Content-Type: application/json' 'http://example.com/api/v1/service/request' -d '{"packages": ["ahriman"]}'
-                > POST /api/v1/service/request HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                > Content-Type: application/json
-                > Content-Length: 25
-                >
-                < HTTP/1.1 204 No Content
-                < Date: Wed, 23 Nov 2022 18:59:32 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
         """
         try:
             data = await self.extract_data(["packages"])

src/ahriman/web/views/service/search.py

@@ -17,12 +17,18 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import aiohttp_apispec  # type: ignore
+
 from aiohttp.web import HTTPBadRequest, HTTPNotFound, Response, json_response
 from typing import Callable, List
 
 from ahriman.core.alpm.remote import AUR
 from ahriman.models.aur_package import AURPackage
 from ahriman.models.user_access import UserAccess
+from ahriman.web.schemas.aur_package_schema import AURPackageSchema
+from ahriman.web.schemas.auth_schema import AuthSchema
+from ahriman.web.schemas.error_schema import ErrorSchema
+from ahriman.web.schemas.search_schema import SearchSchema
 from ahriman.web.views.base import BaseView
 
 
@@ -32,14 +38,29 @@ class SearchView(BaseView):
 
     Attributes:
         GET_PERMISSION(UserAccess): (class attribute) get permissions of self
-        HEAD_PERMISSION(UserAccess): (class attribute) head permissions of self
     """
 
-    GET_PERMISSION = HEAD_PERMISSION = UserAccess.Reporter
+    GET_PERMISSION = UserAccess.Reporter
 
+    @aiohttp_apispec.docs(
+        tags=["Actions"],
+        summary="Search for package",
+        description="Search for package in AUR",
+        responses={
+            200: {"description": "Success response", "schema": AURPackageSchema(many=True)},
+            400: {"description": "Bad data is supplied", "schema": ErrorSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            404: {"description": "Package base is unknown", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [GET_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.querystring_schema(SearchSchema)
     async def get(self) -> Response:
         """
-        search packages in AUR. Search string (non-empty) must be supplied as ``for`` parameter
+        search packages in AUR
 
         Returns:
             Response: 200 with found package bases and descriptions sorted by base
@@ -47,23 +68,6 @@ class SearchView(BaseView):
         Raises:
             HTTPBadRequest: in case if bad data is supplied
             HTTPNotFound: if no packages found
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Accept: application/json' 'http://example.com/api/v1/service/search?for=ahriman'
-                > GET /api/v1/service/search?for=ahriman HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: application/json
-                >
-                < HTTP/1.1 200 OK
-                < Content-Type: application/json; charset=utf-8
-                < Content-Length: 148
-                < Date: Wed, 23 Nov 2022 19:07:13 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
-                [{"package": "ahriman", "description": "ArcH linux ReposItory MANager"}, {"package": "ahriman-git", "description": "ArcH Linux ReposItory MANager"}]
         """
         try:
             search: List[str] = self.get_non_empty(lambda key: self.request.query.getall(key, default=[]), "for")

src/ahriman/web/views/service/update.py

@@ -17,9 +17,13 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import aiohttp_apispec  # type: ignore
+
 from aiohttp.web import HTTPNoContent
 
 from ahriman.models.user_access import UserAccess
+from ahriman.web.schemas.auth_schema import AuthSchema
+from ahriman.web.schemas.error_schema import ErrorSchema
 from ahriman.web.views.base import BaseView
 
 
@@ -33,26 +37,25 @@ class UpdateView(BaseView):
 
     POST_PERMISSION = UserAccess.Full
 
+    @aiohttp_apispec.docs(
+        tags=["Actions"],
+        summary="Update packages",
+        description="Run repository update process",
+        responses={
+            204: {"description": "Success response"},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [POST_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
     async def post(self) -> None:
         """
         run repository update. No parameters supported here
 
         Raises:
             HTTPNoContent: in case of success response
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -XPOST 'http://example.com/api/v1/service/update'
-                > POST /api/v1/service/update HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                >
-                < HTTP/1.1 204 No Content
-                < Date: Fri, 25 Nov 2022 22:57:56 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
         """
         self.spawner.packages_update()
 

src/ahriman/web/views/status/logs.py

@@ -17,11 +17,18 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import aiohttp_apispec  # type: ignore
+
 from aiohttp.web import HTTPBadRequest, HTTPNoContent, HTTPNotFound, Response, json_response
 
 from ahriman.core.exceptions import UnknownPackageError
 from ahriman.models.log_record_id import LogRecordId
 from ahriman.models.user_access import UserAccess
+from ahriman.web.schemas.auth_schema import AuthSchema
+from ahriman.web.schemas.error_schema import ErrorSchema
+from ahriman.web.schemas.log_schema import LogSchema
+from ahriman.web.schemas.logs_schema import LogsSchema
+from ahriman.web.schemas.package_name_schema import PackageNameSchema
 from ahriman.web.views.base import BaseView
 
 
@@ -32,39 +39,53 @@ class LogsView(BaseView):
     Attributes:
         DELETE_PERMISSION(UserAccess): (class attribute) delete permissions of self
         GET_PERMISSION(UserAccess): (class attribute) get permissions of self
-        HEAD_PERMISSION(UserAccess): (class attribute) head permissions of self
         POST_PERMISSION(UserAccess): (class attribute) post permissions of self
     """
 
     DELETE_PERMISSION = POST_PERMISSION = UserAccess.Full
-    GET_PERMISSION = HEAD_PERMISSION = UserAccess.Reporter
+    GET_PERMISSION = UserAccess.Reporter
 
+    @aiohttp_apispec.docs(
+        tags=["Packages"],
+        summary="Delete package logs",
+        description="Delete all logs which belong to the specified package",
+        responses={
+            204: {"description": "Success response"},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [DELETE_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.match_info_schema(PackageNameSchema)
     async def delete(self) -> None:
         """
         delete package logs
 
         Raises:
             HTTPNoContent: on success response
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -XDELETE 'http://example.com/api/v1/packages/ahriman/logs'
-                > DELETE /api/v1/packages/ahriman/logs HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                >
-                < HTTP/1.1 204 No Content
-                < Date: Wed, 23 Nov 2022 19:26:40 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
         """
         package_base = self.request.match_info["package"]
         self.service.remove_logs(package_base, None)
 
         raise HTTPNoContent()
 
+    @aiohttp_apispec.docs(
+        tags=["Packages"],
+        summary="Get package logs",
+        description="Retrieve all package logs and the last package status",
+        responses={
+            200: {"description": "Success response", "schema": LogsSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            404: {"description": "Package base is unknown", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [GET_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.match_info_schema(PackageNameSchema)
     async def get(self) -> Response:
         """
         get last package logs
@@ -72,22 +93,8 @@ class LogsView(BaseView):
         Returns:
             Response: 200 with package logs on success
 
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Accept: application/json' 'http://example.com/api/v1/packages/ahriman/logs'
-                > GET /api/v1/packages/ahriman/logs HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: application/json
-                >
-                < HTTP/1.1 200 OK
-                < Content-Type: application/json; charset=utf-8
-                < Content-Length: 100112
-                < Date: Wed, 23 Nov 2022 19:24:14 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
-                {"package_base": "ahriman", "status": {"status": "success", "timestamp": 1669231136}, "logs": "[2022-11-23 19:17:32] clone remote https://aur.archlinux.org/ahriman.git to /tmp/tmpy9j6fq9p using branch master"}
+        Raises:
+            HTTPNotFound: if package base is unknown
         """
         package_base = self.request.match_info["package"]
 
@@ -104,37 +111,29 @@ class LogsView(BaseView):
         }
         return json_response(response)
 
+    @aiohttp_apispec.docs(
+        tags=["Packages"],
+        summary="Add package logs",
+        description="Insert new package log record",
+        responses={
+            204: {"description": "Success response"},
+            400: {"description": "Bad data is supplied", "schema": ErrorSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [POST_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.match_info_schema(PackageNameSchema)
+    @aiohttp_apispec.json_schema(LogSchema)
     async def post(self) -> None:
         """
         create new package log record
 
-        JSON body must be supplied, the following model is used::
-
-            {
-                "created": 42.001,           # log record created timestamp
-                "message": "log message",    # log record
-                "process_id": 42             # process id from which log record was emitted
-            }
-
         Raises:
             HTTPBadRequest: if bad data is supplied
             HTTPNoContent: in case of success response
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Content-Type: application/json' 'http://example.com/api/v1/packages/ahriman/logs' -d '{"created": 1669231764.042444, "message": "my log message", "process_id": 1}'
-                > POST /api/v1/packages/ahriman/logs HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                > Content-Type: application/json
-                > Content-Length: 76
-                >
-                < HTTP/1.1 204 No Content
-                < Date: Wed, 23 Nov 2022 19:30:45 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
         """
         package_base = self.request.match_info["package"]
         data = await self.extract_data()

src/ahriman/web/views/status/package.py

@@ -17,12 +17,18 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import aiohttp_apispec  # type: ignore
+
 from aiohttp.web import HTTPBadRequest, HTTPNoContent, HTTPNotFound, Response, json_response
 
 from ahriman.core.exceptions import UnknownPackageError
 from ahriman.models.build_status import BuildStatusEnum
 from ahriman.models.package import Package
 from ahriman.models.user_access import UserAccess
+from ahriman.web.schemas.auth_schema import AuthSchema
+from ahriman.web.schemas.error_schema import ErrorSchema
+from ahriman.web.schemas.package_name_schema import PackageNameSchema
+from ahriman.web.schemas.package_status_schema import PackageStatusSchema, PackageStatusSimplifiedSchema
 from ahriman.web.views.base import BaseView
 
 
@@ -33,39 +39,53 @@ class PackageView(BaseView):
     Attributes:
         DELETE_PERMISSION(UserAccess): (class attribute) delete permissions of self
         GET_PERMISSION(UserAccess): (class attribute) get permissions of self
-        HEAD_PERMISSION(UserAccess): (class attribute) head permissions of self
         POST_PERMISSION(UserAccess): (class attribute) post permissions of self
     """
 
     DELETE_PERMISSION = POST_PERMISSION = UserAccess.Full
-    GET_PERMISSION = HEAD_PERMISSION = UserAccess.Read
+    GET_PERMISSION = UserAccess.Read
 
+    @aiohttp_apispec.docs(
+        tags=["Packages"],
+        summary="Delete package",
+        description="Delete package and its status from service",
+        responses={
+            204: {"description": "Success response"},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [DELETE_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.match_info_schema(PackageNameSchema)
     async def delete(self) -> None:
         """
         delete package base from status page
 
         Raises:
             HTTPNoContent: on success response
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -XDELETE 'http://example.com/api/v1/packages/ahriman'
-                > DELETE /api/v1/packages/ahriman HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                >
-                < HTTP/1.1 204 No Content
-                < Date: Wed, 23 Nov 2022 19:43:40 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
         """
         package_base = self.request.match_info["package"]
         self.service.remove(package_base)
 
         raise HTTPNoContent()
 
+    @aiohttp_apispec.docs(
+        tags=["Packages"],
+        summary="Get package",
+        description="Retrieve packages and its descriptor",
+        responses={
+            200: {"description": "Success response", "schema": PackageStatusSchema(many=True)},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            404: {"description": "Package base is unknown", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [GET_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.match_info_schema(PackageNameSchema)
     async def get(self) -> Response:
         """
         get current package base status
@@ -75,23 +95,6 @@ class PackageView(BaseView):
 
         Raises:
             HTTPNotFound: if no package was found
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Accept: application/json' 'http://example.com/api/v1/packages/ahriman'
-                > GET /api/v1/packages/ahriman HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: application/json
-                >
-                < HTTP/1.1 200 OK
-                < Content-Type: application/json; charset=utf-8
-                < Content-Length: 743
-                < Date: Wed, 23 Nov 2022 19:41:01 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
-                [{"package": {"base": "ahriman", "version": "2.3.0-1", "remote": {"git_url": "https://aur.archlinux.org/ahriman.git", "web_url": "https://aur.archlinux.org/packages/ahriman", "path": ".", "branch": "master", "source": "aur"}, "packages": {"ahriman": {"architecture": "any", "archive_size": 247573, "build_date": 1669231069, "depends": ["devtools", "git", "pyalpm", "python-inflection", "python-passlib", "python-requests", "python-setuptools", "python-srcinfo"], "description": "ArcH linux ReposItory MANager", "filename": "ahriman-2.3.0-1-any.pkg.tar.zst", "groups": [], "installed_size": 1676153, "licenses": ["GPL3"], "provides": [], "url": "https://github.com/arcan1s/ahriman"}}}, "status": {"status": "success", "timestamp": 1669231136}}]
         """
         package_base = self.request.match_info["package"]
 
@@ -108,37 +111,29 @@ class PackageView(BaseView):
         ]
         return json_response(response)
 
+    @aiohttp_apispec.docs(
+        tags=["Packages"],
+        summary="Update package",
+        description="Update package status and set its descriptior optionally",
+        responses={
+            204: {"description": "Success response"},
+            400: {"description": "Bad data is supplied", "schema": ErrorSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [POST_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.match_info_schema(PackageNameSchema)
+    @aiohttp_apispec.json_schema(PackageStatusSimplifiedSchema)
     async def post(self) -> None:
         """
         update package build status
 
-        JSON body must be supplied, the following model is used::
-
-            {
-                "status": "unknown",   # package build status string, must be valid ``BuildStatusEnum``
-                "package": {}          # package body (use ``dataclasses.asdict`` to generate one), optional.
-                                       # Must be supplied in case if package base is unknown
-            }
-
         Raises:
             HTTPBadRequest: if bad data is supplied
             HTTPNoContent: in case of success response
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Content-Type: application/json' 'http://example.com/api/v1/packages/ahriman' -d '{"status": "success"}'
-                > POST /api/v1/packages/ahriman HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                > Content-Type: application/json
-                > Content-Length: 21
-                >
-                < HTTP/1.1 204 No Content
-                < Date: Wed, 23 Nov 2022 19:42:49 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
         """
         package_base = self.request.match_info["package"]
         data = await self.extract_data()

src/ahriman/web/views/status/packages.py

@@ -17,9 +17,14 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import aiohttp_apispec  # type: ignore
+
 from aiohttp.web import HTTPNoContent, Response, json_response
 
 from ahriman.models.user_access import UserAccess
+from ahriman.web.schemas.auth_schema import AuthSchema
+from ahriman.web.schemas.error_schema import ErrorSchema
+from ahriman.web.schemas.package_status_schema import PackageStatusSchema
 from ahriman.web.views.base import BaseView
 
 
@@ -29,36 +34,31 @@ class PackagesView(BaseView):
 
     Attributes:
         GET_PERMISSION(UserAccess): (class attribute) get permissions of self
-        HEAD_PERMISSION(UserAccess): (class attribute) head permissions of self
         POST_PERMISSION(UserAccess): (class attribute) post permissions of self
     """
 
-    GET_PERMISSION = HEAD_PERMISSION = UserAccess.Read
+    GET_PERMISSION = UserAccess.Read
     POST_PERMISSION = UserAccess.Full
 
+    @aiohttp_apispec.docs(
+        tags=["Packages"],
+        summary="Get packages list",
+        description="Retrieve all packages and their descriptors",
+        responses={
+            200: {"description": "Success response", "schema": PackageStatusSchema(many=True)},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [GET_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
     async def get(self) -> Response:
         """
         get current packages status
 
         Returns:
             Response: 200 with package description on success
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Accept: application/json' 'http://example.com/api/v1/packages'
-                > GET /api/v1/packages HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: application/json
-                >
-                < HTTP/1.1 200 OK
-                < Content-Type: application/json; charset=utf-8
-                < Content-Length: 2687
-                < Date: Wed, 23 Nov 2022 19:35:24 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
-                [{"package": {"base": "ahriman", "version": "2.3.0-1", "remote": {"git_url": "https://aur.archlinux.org/ahriman.git", "web_url": "https://aur.archlinux.org/packages/ahriman", "path": ".", "branch": "master", "source": "aur"}, "packages": {"ahriman": {"architecture": "any", "archive_size": 247573, "build_date": 1669231069, "depends": ["devtools", "git", "pyalpm", "python-inflection", "python-passlib", "python-requests", "python-setuptools", "python-srcinfo"], "description": "ArcH linux ReposItory MANager", "filename": "ahriman-2.3.0-1-any.pkg.tar.zst", "groups": [], "installed_size": 1676153, "licenses": ["GPL3"], "provides": [], "url": "https://github.com/arcan1s/ahriman"}}}, "status": {"status": "success", "timestamp": 1669231136}}]
         """
         response = [
             {
@@ -68,26 +68,25 @@ class PackagesView(BaseView):
         ]
         return json_response(response)
 
+    @aiohttp_apispec.docs(
+        tags=["Packages"],
+        summary="Load packages",
+        description="Load packages from cache",
+        responses={
+            204: {"description": "Success response"},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [POST_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
     async def post(self) -> None:
         """
-        reload all packages from repository. No parameters supported here
+        reload all packages from repository
 
         Raises:
             HTTPNoContent: on success response
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -XPOST 'http://example.com/api/v1/packages'
-                > POST /api/v1/packages HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                >
-                < HTTP/1.1 204 No Content
-                < Date: Wed, 23 Nov 2022 19:38:06 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
         """
         self.service.load()
 

src/ahriman/web/views/status/status.py

@@ -17,6 +17,8 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import aiohttp_apispec  # type: ignore
+
 from aiohttp.web import HTTPBadRequest, HTTPNoContent, Response, json_response
 
 from ahriman import version
@@ -24,6 +26,10 @@ from ahriman.models.build_status import BuildStatusEnum
 from ahriman.models.counters import Counters
 from ahriman.models.internal_status import InternalStatus
 from ahriman.models.user_access import UserAccess
+from ahriman.web.schemas.auth_schema import AuthSchema
+from ahriman.web.schemas.error_schema import ErrorSchema
+from ahriman.web.schemas.internal_status_schema import InternalStatusSchema
+from ahriman.web.schemas.status_schema import StatusSchema
 from ahriman.web.views.base import BaseView
 
 
@@ -33,36 +39,31 @@ class StatusView(BaseView):
 
     Attributes:
         GET_PERMISSION(UserAccess): (class attribute) get permissions of self
-        HEAD_PERMISSION(UserAccess): (class attribute) head permissions of self
         POST_PERMISSION(UserAccess): (class attribute) post permissions of self
     """
 
-    GET_PERMISSION = HEAD_PERMISSION = UserAccess.Read
+    GET_PERMISSION = UserAccess.Read
     POST_PERMISSION = UserAccess.Full
 
+    @aiohttp_apispec.docs(
+        tags=["Status"],
+        summary="Web service status",
+        description="Get web service status counters",
+        responses={
+            200: {"description": "Success response", "schema": InternalStatusSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [GET_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
     async def get(self) -> Response:
         """
         get current service status
 
         Returns:
             Response: 200 with service status object
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Accept: application/json' 'http://example.com/api/v1/status'
-                > GET /api/v1/status HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: application/json
-                >
-                < HTTP/1.1 200 OK
-                < Content-Type: application/json; charset=utf-8
-                < Content-Length: 222
-                < Date: Wed, 23 Nov 2022 19:32:31 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
-                {"status": {"status": "success", "timestamp": 1669231237}, "architecture": "x86_64", "packages": {"total": 4, "unknown": 0, "pending": 0, "building": 0, "failed": 0, "success": 4}, "repository": "repo", "version": "2.3.0"}
         """
         counters = Counters.from_packages(self.service.packages)
         status = InternalStatus(
@@ -74,35 +75,28 @@ class StatusView(BaseView):
 
         return json_response(status.view())
 
+    @aiohttp_apispec.docs(
+        tags=["Status"],
+        summary="Set web service status",
+        description="Update web service status. Counters will remain unchanged",
+        responses={
+            204: {"description": "Success response"},
+            400: {"description": "Bad data is supplied", "schema": ErrorSchema},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            403: {"description": "Access is forbidden", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [POST_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
+    @aiohttp_apispec.json_schema(StatusSchema)
     async def post(self) -> None:
         """
         update service status
 
-        JSON body must be supplied, the following model is used::
-
-            {
-                "status": "unknown",   # service status string, must be valid ``BuildStatusEnum``
-            }
-
         Raises:
             HTTPBadRequest: if bad data is supplied
             HTTPNoContent: in case of success response
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Content-Type: application/json' 'http://example.com/api/v1/status' -d '{"status": "success"}'
-                > POST /api/v1/status HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                > Content-Type: application/json
-                > Content-Length: 21
-                >
-                < HTTP/1.1 204 No Content
-                < Date: Wed, 23 Nov 2022 19:33:57 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
         """
         try:
             data = await self.extract_data()

src/ahriman/web/views/user/login.py

@@ -17,11 +17,15 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import aiohttp_apispec  # type: ignore
+
 from aiohttp.web import HTTPFound, HTTPMethodNotAllowed, HTTPUnauthorized
 
 from ahriman.core.auth.helpers import remember
 from ahriman.models.user_access import UserAccess
-from ahriman.models.user_identity import UserIdentity
+from ahriman.web.schemas.error_schema import ErrorSchema
+from ahriman.web.schemas.login_schema import LoginSchema
+from ahriman.web.schemas.oauth2_schema import OAuth2Schema
 from ahriman.web.views.base import BaseView
 
 
@@ -36,6 +40,18 @@ class LoginView(BaseView):
 
     GET_PERMISSION = POST_PERMISSION = UserAccess.Unauthorized
 
+    @aiohttp_apispec.docs(
+        tags=["Login"],
+        summary="Login via OAuth2",
+        description="Login by using OAuth2 authorization code. Only available if OAuth2 is enabled",
+        responses={
+            302: {"description": "Success response"},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [GET_PERMISSION]}],
+    )
+    @aiohttp_apispec.querystring_schema(OAuth2Schema)
     async def get(self) -> None:
         """
         OAuth2 response handler
@@ -49,9 +65,6 @@ class LoginView(BaseView):
             HTTPFound: on success response
             HTTPMethodNotAllowed: in case if method is used, but OAuth is disabled
             HTTPUnauthorized: if case of authorization error
-
-        Examples:
-            This request must not be used directly.
         """
         from ahriman.core.auth.oauth import OAuth
 
@@ -64,59 +77,39 @@ class LoginView(BaseView):
             raise HTTPFound(oauth_provider.get_oauth_url())
 
         response = HTTPFound("/")
-        username = await oauth_provider.get_oauth_username(code)
-        identity = UserIdentity.from_username(username, self.validator.max_age)
-        if identity is not None and await self.validator.known_username(username):
-            await remember(self.request, response, identity.to_identity())
+        identity = await oauth_provider.get_oauth_username(code)
+        if identity is not None and await self.validator.known_username(identity):
+            await remember(self.request, response, identity)
             raise response
 
         raise HTTPUnauthorized()
 
+    @aiohttp_apispec.docs(
+        tags=["Login"],
+        summary="Login via basic authorization",
+        description="Login by using username and password",
+        responses={
+            302: {"description": "Success response"},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [POST_PERMISSION]}],
+    )
+    @aiohttp_apispec.json_schema(LoginSchema)
     async def post(self) -> None:
         """
-        login user to service
-
-        either JSON body or form data must be supplied the following fields are required::
-
-            {
-                "username": "username",  # username to use for login
-                "password": "pa55w0rd"   # password to use for login
-            }
-
-        The authentication session will be passed in ``Set-Cookie`` header.
+        login user to service. The authentication session will be passed in ``Set-Cookie`` header.
 
         Raises:
             HTTPFound: on success response
             HTTPUnauthorized: if case of authorization error
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -H 'Content-Type: application/json' 'http://example.com/api/v1/login' -d '{"username": "test", "password": "test"}'
-                > POST /api/v1/login HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                > Content-Type: application/json
-                > Content-Length: 40
-                >
-                < HTTP/1.1 302 Found
-                < Content-Type: text/plain; charset=utf-8
-                < Location: /
-                < Content-Length: 10
-                < Set-Cookie: ...
-                < Date: Wed, 23 Nov 2022 17:51:27 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
-                302: Found
         """
         data = await self.extract_data()
-        username = data.get("username")
+        identity = data.get("username")
 
         response = HTTPFound("/")
-        identity = UserIdentity.from_username(username, self.validator.max_age)
-        if identity is not None and await self.validator.check_credentials(username, data.get("password")):
-            await remember(self.request, response, identity.to_identity())
+        if identity is not None and await self.validator.check_credentials(identity, data.get("password")):
+            await remember(self.request, response, identity)
             raise response
 
         raise HTTPUnauthorized()

src/ahriman/web/views/user/logout.py

@@ -17,10 +17,14 @@
 # You should have received a copy of the GNU General Public License
 # along with this program. If not, see <http://www.gnu.org/licenses/>.
 #
+import aiohttp_apispec  # type: ignore
+
 from aiohttp.web import HTTPFound, HTTPUnauthorized
 
 from ahriman.core.auth.helpers import check_authorized, forget
 from ahriman.models.user_access import UserAccess
+from ahriman.web.schemas.auth_schema import AuthSchema
+from ahriman.web.schemas.error_schema import ErrorSchema
 from ahriman.web.views.base import BaseView
 
 
@@ -34,33 +38,26 @@ class LogoutView(BaseView):
 
     POST_PERMISSION = UserAccess.Unauthorized
 
+    @aiohttp_apispec.docs(
+        tags=["Login"],
+        summary="Logout",
+        description="Logout user and remove authorization cookies",
+        responses={
+            302: {"description": "Success response"},
+            401: {"description": "Authorization required", "schema": ErrorSchema},
+            500: {"description": "Internal server error", "schema": ErrorSchema},
+        },
+        security=[{"token": [POST_PERMISSION]}],
+    )
+    @aiohttp_apispec.cookies_schema(AuthSchema)
     async def post(self) -> None:
         """
-        logout user from the service. No parameters supported here.
+        logout user from the service
 
         The server will respond with ``Set-Cookie`` header, in which API session cookie will be nullified.
 
         Raises:
             HTTPFound: on success response
-
-        Examples:
-            Example of command by using curl::
-
-                $ curl -v -XPOST 'http://example.com/api/v1/logout'
-                > POST /api/v1/logout HTTP/1.1
-                > Host: example.com
-                > User-Agent: curl/7.86.0
-                > Accept: */*
-                >
-                < HTTP/1.1 302 Found
-                < Content-Type: text/plain; charset=utf-8
-                < Location: /
-                < Content-Length: 10
-                < Set-Cookie: ...
-                < Date: Wed, 23 Nov 2022 19:10:51 GMT
-                < Server: Python/3.10 aiohttp/3.8.3
-                <
-                302: Found
         """
         try:
             await check_authorized(self.request)

src/ahriman/web/web.py

@@ -22,7 +22,7 @@ import jinja2
 import logging
 import socket
 
-from aiohttp import web
+from aiohttp.web import Application, normalize_path_middleware, run_app
 from typing import Optional
 
 from ahriman.core.auth import Auth
@@ -32,20 +32,22 @@ from ahriman.core.exceptions import InitializeError
 from ahriman.core.log.filtered_access_logger import FilteredAccessLogger
 from ahriman.core.spawn import Spawn
 from ahriman.core.status.watcher import Watcher
+from ahriman.web.apispec import setup_apispec
+from ahriman.web.cors import setup_cors
 from ahriman.web.middlewares.exception_handler import exception_handler
 from ahriman.web.routes import setup_routes
 
 
-__all__ = ["create_socket", "on_shutdown", "on_startup", "run_server", "setup_service"]
+__all__ = ["run_server", "setup_service"]
 
 
-def create_socket(configuration: Configuration, application: web.Application) -> Optional[socket.socket]:
+def _create_socket(configuration: Configuration, application: Application) -> Optional[socket.socket]:
     """
     create unix socket based on configuration option
 
     Args:
         configuration(Configuration): configuration instance
-        application(web.Application): web application instance
+        application(Application): web application instance
 
     Returns:
         Optional[socket.socket]: unix socket object if set by option
@@ -64,7 +66,7 @@ def create_socket(configuration: Configuration, application: web.Application) ->
         unix_socket.chmod(0o666)  # for the glory of satan of course
 
     # register socket removal
-    async def remove_socket(_: web.Application) -> None:
+    async def remove_socket(_: Application) -> None:
         unix_socket.unlink(missing_ok=True)
 
     application.on_shutdown.append(remove_socket)
@@ -72,25 +74,25 @@ def create_socket(configuration: Configuration, application: web.Application) ->
     return sock
 
 
-async def on_shutdown(application: web.Application) -> None:
+async def _on_shutdown(application: Application) -> None:
     """
     web application shutdown handler
 
     Args:
-        application(web.Application): web application instance
+        application(Application): web application instance
     """
     application.logger.warning("server terminated")
 
 
-async def on_startup(application: web.Application) -> None:
+async def _on_startup(application: Application) -> None:
     """
     web application start handler
 
     Args:
-        application(web.Application): web application instance
+        application(Application): web application instance
 
     Raises:
-        InitializeException: in case if matched could not be loaded
+        InitializeError: in case if matched could not be loaded
     """
     application.logger.info("server started")
     try:
@@ -101,25 +103,25 @@ async def on_startup(application: web.Application) -> None:
         raise InitializeError(message)
 
 
-def run_server(application: web.Application) -> None:
+def run_server(application: Application) -> None:
     """
     run web application
 
     Args:
-        application(web.Application): web application instance
+        application(Application): web application instance
     """
     application.logger.info("start server")
 
     configuration: Configuration = application["configuration"]
     host = configuration.get("web", "host")
     port = configuration.getint("web", "port")
-    unix_socket = create_socket(configuration, application)
+    unix_socket = _create_socket(configuration, application)
 
-    web.run_app(application, host=host, port=port, sock=unix_socket, handle_signals=False,
-                access_log=logging.getLogger("http"), access_log_class=FilteredAccessLogger)
+    run_app(application, host=host, port=port, sock=unix_socket, handle_signals=True,
+            access_log=logging.getLogger("http"), access_log_class=FilteredAccessLogger)
 
 
-def setup_service(architecture: str, configuration: Configuration, spawner: Spawn) -> web.Application:
+def setup_service(architecture: str, configuration: Configuration, spawner: Spawn) -> Application:
     """
     create web application
 
@@ -129,18 +131,21 @@ def setup_service(architecture: str, configuration: Configuration, spawner: Spaw
         spawner(Spawn): spawner thread
 
     Returns:
-        web.Application: web application instance
+        Application: web application instance
     """
-    application = web.Application(logger=logging.getLogger(__name__))
-    application.on_shutdown.append(on_shutdown)
-    application.on_startup.append(on_startup)
+    application = Application(logger=logging.getLogger(__name__))
+    application.on_shutdown.append(_on_shutdown)
+    application.on_startup.append(_on_startup)
 
-    application.middlewares.append(web.normalize_path_middleware(append_slash=False, remove_slash=True))
+    application.middlewares.append(normalize_path_middleware(append_slash=False, remove_slash=True))
     application.middlewares.append(exception_handler(application.logger))
 
     application.logger.info("setup routes")
     setup_routes(application, configuration.getpath("web", "static_path"))
 
+    application.logger.info("setup CORS")
+    setup_cors(application)
+
     application.logger.info("setup templates")
     aiohttp_jinja2.setup(application, loader=jinja2.FileSystemLoader(configuration.getpath("web", "templates")))
 
@@ -168,6 +173,9 @@ def setup_service(architecture: str, configuration: Configuration, spawner: Spaw
     validator = application["validator"] = Auth.load(configuration, database)
     if validator.enabled:
         from ahriman.web.middlewares.auth_handler import setup_auth
-        setup_auth(application, validator)
+        setup_auth(application, configuration, validator)
+
+    application.logger.info("setup api docs")
+    setup_apispec(application)
 
     return application

tests/ahriman/application/application/test_application.py

@@ -1,4 +1,5 @@
 from pytest_mock import MockerFixture
+from unittest.mock import MagicMock, call as MockCall
 
 from ahriman.application.application import Application
 from ahriman.models.package import Package
@@ -44,3 +45,55 @@ def test_on_stop(application: Application, mocker: MockerFixture) -> None:
 
     application.on_stop()
     triggers_mock.assert_called_once_with()
+
+
+def test_with_dependencies(application: Application, package_ahriman: Package, package_python_schedule: Package,
+                           mocker: MockerFixture) -> None:
+    """
+    must append list of missing dependencies
+    """
+    def create_package_mock(package_base) -> MagicMock:
+        mock = MagicMock()
+        mock.base = package_base
+        mock.depends_build = []
+        mock.packages_full = [package_base]
+        return mock
+
+    package_python_schedule.packages = {
+        package_python_schedule.base: package_python_schedule.packages[package_python_schedule.base]
+    }
+    package_ahriman.packages[package_ahriman.base].depends = ["devtools", "python", package_python_schedule.base]
+    package_ahriman.packages[package_ahriman.base].make_depends = ["python-build", "python-installer"]
+
+    packages = {
+        package_ahriman.base: package_ahriman,
+        package_python_schedule.base: package_python_schedule,
+        "python": create_package_mock("python"),
+        "python-installer": create_package_mock("python-installer"),
+    }
+
+    package_mock = mocker.patch("ahriman.models.package.Package.from_aur", side_effect=lambda p, _: packages[p])
+    packages_mock = mocker.patch("ahriman.application.application.Application._known_packages",
+                                 return_value=["devtools", "python-build"])
+
+    result = application.with_dependencies([package_ahriman], process_dependencies=True)
+    assert {package.base: package for package in result} == packages
+    package_mock.assert_has_calls([
+        MockCall(package_python_schedule.base, application.repository.pacman),
+        MockCall("python", application.repository.pacman),
+        MockCall("python-installer", application.repository.pacman),
+    ], any_order=True)
+    packages_mock.assert_called_once_with()
+
+
+def test_with_dependencies_skip(application: Application, package_ahriman: Package, mocker: MockerFixture) -> None:
+    """
+    must skip processing of dependencies
+    """
+    packages_mock = mocker.patch("ahriman.application.application.Application._known_packages")
+
+    assert application.with_dependencies([package_ahriman], process_dependencies=False) == [package_ahriman]
+    packages_mock.assert_not_called()
+
+    assert application.with_dependencies([], process_dependencies=True) == []
+    packages_mock.assert_not_called()

tests/ahriman/application/application/test_application_packages.py

@@ -2,7 +2,7 @@ import pytest
 
 from pathlib import Path
 from pytest_mock import MockerFixture
-from unittest.mock import MagicMock, call as MockCall
+from unittest.mock import MagicMock
 
 from ahriman.application.application.application_packages import ApplicationPackages
 from ahriman.models.package import Package
@@ -29,13 +29,10 @@ def test_add_aur(application_packages: ApplicationPackages, package_ahriman: Pac
     must add package from AUR
     """
     mocker.patch("ahriman.models.package.Package.from_aur", return_value=package_ahriman)
-    dependencies_mock = mocker.patch(
-        "ahriman.application.application.application_packages.ApplicationPackages._process_dependencies")
     build_queue_mock = mocker.patch("ahriman.core.database.SQLite.build_queue_insert")
     update_remote_mock = mocker.patch("ahriman.core.database.SQLite.remote_update")
 
-    application_packages._add_aur(package_ahriman.base, set(), False)
-    dependencies_mock.assert_called_once_with(pytest.helpers.anyvar(int), set(), False)
+    application_packages._add_aur(package_ahriman.base)
     build_queue_mock.assert_called_once_with(package_ahriman)
     update_remote_mock.assert_called_once_with(package_ahriman)
 
@@ -64,15 +61,12 @@ def test_add_local(application_packages: ApplicationPackages, package_ahriman: P
     mocker.patch("ahriman.models.package.Package.from_build", return_value=package_ahriman)
     init_mock = mocker.patch("ahriman.core.build_tools.sources.Sources.init")
     copytree_mock = mocker.patch("shutil.copytree")
-    dependencies_mock = mocker.patch(
-        "ahriman.application.application.application_packages.ApplicationPackages._process_dependencies")
     build_queue_mock = mocker.patch("ahriman.core.database.SQLite.build_queue_insert")
 
-    application_packages._add_local(package_ahriman.base, set(), False)
+    application_packages._add_local(package_ahriman.base)
     copytree_mock.assert_called_once_with(
         Path(package_ahriman.base), application_packages.repository.paths.cache_for(package_ahriman.base))
     init_mock.assert_called_once_with(application_packages.repository.paths.cache_for(package_ahriman.base))
-    dependencies_mock.assert_called_once_with(pytest.helpers.anyvar(int), set(), False)
     build_queue_mock.assert_called_once_with(package_ahriman)
 
 
@@ -107,59 +101,15 @@ def test_add_repository(application_packages: ApplicationPackages, package_ahrim
     update_remote_mock.assert_called_once_with(package_ahriman)
 
 
-def test_known_packages(application_packages: ApplicationPackages) -> None:
-    """
-    must raise NotImplemented for missing known_packages method
-    """
-    with pytest.raises(NotImplementedError):
-        application_packages._known_packages()
-
-
-def test_process_dependencies(application_packages: ApplicationPackages, package_ahriman: Package,
-                              mocker: MockerFixture) -> None:
-    """
-    must process dependencies addition
-    """
-    add_mock = mocker.patch("ahriman.application.application.application_packages.ApplicationPackages.add")
-
-    application_packages._process_dependencies(package_ahriman, set(), False)
-    add_mock.assert_called_once_with(package_ahriman.depends_build, PackageSource.AUR, False)
-
-
-def test_process_dependencies_missing(application_packages: ApplicationPackages, package_ahriman: Package,
-                                      mocker: MockerFixture) -> None:
-    """
-    must process dependencies addition only for missing packages
-    """
-    missing = {"devtools"}
-    add_mock = mocker.patch("ahriman.application.application.application_packages.ApplicationPackages.add")
-
-    application_packages._process_dependencies(
-        package_ahriman, package_ahriman.depends_build.difference(missing), False)
-    add_mock.assert_called_once_with(missing, PackageSource.AUR, False)
-
-
-def test_process_dependencies_skip(application_packages: ApplicationPackages, package_ahriman: Package,
-                                   mocker: MockerFixture) -> None:
-    """
-    must skip dependencies processing
-    """
-    add_mock = mocker.patch("ahriman.application.application.application_packages.ApplicationPackages.add")
-    application_packages._process_dependencies(package_ahriman, set(), True)
-    add_mock.assert_not_called()
-
-
 def test_add_add_archive(application_packages: ApplicationPackages, package_ahriman: Package,
                          mocker: MockerFixture) -> None:
     """
     must add package from archive via add function
     """
-    mocker.patch("ahriman.application.application.application_packages.ApplicationPackages._known_packages",
-                 return_value=set())
     add_mock = mocker.patch("ahriman.application.application.application_packages.ApplicationPackages._add_archive")
 
-    application_packages.add([package_ahriman.base], PackageSource.Archive, False)
-    add_mock.assert_called_once_with(package_ahriman.base, set(), False)
+    application_packages.add([package_ahriman.base], PackageSource.Archive)
+    add_mock.assert_called_once_with(package_ahriman.base)
 
 
 def test_add_add_aur(
@@ -169,12 +119,10 @@ def test_add_add_aur(
     """
     must add package from AUR via add function
     """
-    mocker.patch("ahriman.application.application.application_packages.ApplicationPackages._known_packages",
-                 return_value=set())
     add_mock = mocker.patch("ahriman.application.application.application_packages.ApplicationPackages._add_aur")
 
-    application_packages.add([package_ahriman.base], PackageSource.AUR, True)
-    add_mock.assert_called_once_with(package_ahriman.base, set(), True)
+    application_packages.add([package_ahriman.base], PackageSource.AUR)
+    add_mock.assert_called_once_with(package_ahriman.base)
 
 
 def test_add_add_directory(application_packages: ApplicationPackages, package_ahriman: Package,
@@ -182,12 +130,10 @@ def test_add_add_directory(application_packages: ApplicationPackages, package_ah
     """
     must add packages from directory via add function
     """
-    mocker.patch("ahriman.application.application.application_packages.ApplicationPackages._known_packages",
-                 return_value=set())
     add_mock = mocker.patch("ahriman.application.application.application_packages.ApplicationPackages._add_directory")
 
-    application_packages.add([package_ahriman.base], PackageSource.Directory, False)
-    add_mock.assert_called_once_with(package_ahriman.base, set(), False)
+    application_packages.add([package_ahriman.base], PackageSource.Directory)
+    add_mock.assert_called_once_with(package_ahriman.base)
 
 
 def test_add_add_local(application_packages: ApplicationPackages, package_ahriman: Package,
@@ -195,12 +141,10 @@ def test_add_add_local(application_packages: ApplicationPackages, package_ahrima
     """
     must add package from local sources via add function
     """
-    mocker.patch("ahriman.application.application.application_packages.ApplicationPackages._known_packages",
-                 return_value=set())
     add_mock = mocker.patch("ahriman.application.application.application_packages.ApplicationPackages._add_local")
 
-    application_packages.add([package_ahriman.base], PackageSource.Local, False)
-    add_mock.assert_called_once_with(package_ahriman.base, set(), False)
+    application_packages.add([package_ahriman.base], PackageSource.Local)
+    add_mock.assert_called_once_with(package_ahriman.base)
 
 
 def test_add_add_remote(application_packages: ApplicationPackages, package_description_ahriman: PackageDescription,
@@ -208,13 +152,11 @@ def test_add_add_remote(application_packages: ApplicationPackages, package_descr
     """
     must add package from remote source via add function
     """
-    mocker.patch("ahriman.application.application.application_packages.ApplicationPackages._known_packages",
-                 return_value=set())
     add_mock = mocker.patch("ahriman.application.application.application_packages.ApplicationPackages._add_remote")
     url = f"https://host/{package_description_ahriman.filename}"
 
-    application_packages.add([url], PackageSource.Remote, False)
-    add_mock.assert_called_once_with(url, set(), False)
+    application_packages.add([url], PackageSource.Remote)
+    add_mock.assert_called_once_with(url)
 
 
 def test_on_result(application_packages: ApplicationPackages) -> None:

tests/ahriman/application/handlers/test_handler_add.py

@@ -26,7 +26,7 @@ def _default_args(args: argparse.Namespace) -> argparse.Namespace:
     args.now = False
     args.refresh = 0
     args.source = PackageSource.Auto
-    args.without_dependencies = False
+    args.dependencies = True
     return args
 
 
@@ -38,10 +38,12 @@ def test_run(args: argparse.Namespace, configuration: Configuration, repository:
     args = _default_args(args)
     mocker.patch("ahriman.core.repository.Repository.load", return_value=repository)
     application_mock = mocker.patch("ahriman.application.application.Application.add")
+    dependencies_mock = mocker.patch("ahriman.application.application.Application.with_dependencies")
     on_start_mock = mocker.patch("ahriman.application.application.Application.on_start")
 
     Add.run(args, "x86_64", configuration, report=False, unsafe=False)
-    application_mock.assert_called_once_with(args.package, args.source, args.without_dependencies)
+    application_mock.assert_called_once_with(args.package, args.source)
+    dependencies_mock.assert_not_called()
     on_start_mock.assert_called_once_with()
 
 
@@ -59,11 +61,14 @@ def test_run_with_updates(args: argparse.Namespace, configuration: Configuration
     application_mock = mocker.patch("ahriman.application.application.Application.update", return_value=result)
     check_mock = mocker.patch("ahriman.application.handlers.Handler.check_if_empty")
     updates_mock = mocker.patch("ahriman.application.application.Application.updates", return_value=[package_ahriman])
+    dependencies_mock = mocker.patch("ahriman.application.application.Application.with_dependencies",
+                                     return_value=[package_ahriman])
 
     Add.run(args, "x86_64", configuration, report=False, unsafe=False)
     updates_mock.assert_called_once_with(args.package, aur=False, local=False, manual=True, vcs=False,
                                          log_fn=pytest.helpers.anyvar(int))
     application_mock.assert_called_once_with([package_ahriman])
+    dependencies_mock.assert_called_once_with([package_ahriman], process_dependencies=args.dependencies)
     check_mock.assert_called_once_with(False, False)
 
 
@@ -78,6 +83,7 @@ def test_run_empty_exception(args: argparse.Namespace, configuration: Configurat
     mocker.patch("ahriman.application.application.Application.add")
     mocker.patch("ahriman.core.repository.Repository.load", return_value=repository)
     mocker.patch("ahriman.application.application.Application.update", return_value=Result())
+    mocker.patch("ahriman.application.application.Application.with_dependencies")
     mocker.patch("ahriman.application.application.Application.updates")
     check_mock = mocker.patch("ahriman.application.handlers.Handler.check_if_empty")