Release v6.0.0 - Python
This documents UX and functional changes for the v6.0.0 aurweb release.
Following this release, we'll be working on a few very nice features
noted at the end of this article in Upcoming Work.
Preface
-------
This v6.0.0 release makes the long-awaited Python port official.
Along with the development of the python port, we have modified a
number of features. There have been some integral changes to how
package requests are dealt with, so _Trusted Users_ should read
the entirety of this document.
Legend
------
There are a few terms which I'd like to define to increase
understanding of these changes as they are listed:
- _self_
- Refers to a user viewing or doing something regarding their own account
- _/pkgbase/{name}/{action}_
- Refers to a POST action which can be triggered via the relevent package
page at `/{pkgbase,packages}/{name}`.
Grouped changes explained in multiple items will always be prefixed with
the same letter surrounded by braces. Example:
- [A] Some feature that does something
- [A] The same feature where another thing has changed
Infrastructure
--------------
- Python packaging is now done with poetry.
- SQLite support has been removed. This was done because even though
SQLAlchemy is an ORM, SQLite has quite a few SQL-server-like features
missing both out of the box and integrally which force us to account
for the different database types. We now only support mysql, and should
be able to support postgresql without much effort in the future.
Note: Users wishing to easily spin up a database quickly can use
`docker-compose up -d mariadb` for a Docker-hosted mariadb service.
- An example systemd service has been included at `examples/aurweb.service`.
- Example wrappers to `aurweb-git-(auth|serve|update)` have been included
at `examples/aurweb-git-(auth|serve|update).sh` and should be used to
call these scripts when aurweb is installed into a poetry virtualenv.
HTML
----
- Pagers have all been modified. They still serve the same purpose, but
they have slightly different display.
- Some markup and methods around the website has been changed for
post requests, and some forms have been completely reworked.
Package Requests
----------------
- Normal users can now view and close their own requests
- [A] Requests can no longer be accepted through manual closures
- [A] Requests are now closed via their relevent actions
- Deletion
- Through `/packages` bulk delete action
- Through `/pkgbase/{name}/delete`
- Merge
- Through `/pkgbase/{name}/merge`
- Orphan
- Through `/packages` bulk disown action
- Through `/pkgbase/{name}/disown`
- Deletion and merge requests (and their closures) are now autogenerated
if no pre-existing request exists. This was done to increase tracking of
package modifications performed by those with access to do so (TUs).
- Deletion, merge and orphan request actions now close all (1 or more)
requests pertaining to the action performed. This comes with the downside
of multiple notifications sent out about a closure if more than one
request (or no request) exists for them
- Merge actions now automatically reject other pre-existing merge requests
with a mismatched `MergeBaseName` column when a merge action is performed
- The last `/requests` page no longer goes nowhere
Package Bulk Actions: /packages
-------------------------------
- The `Merge into` field has been removed. Merges now require being
performed via the `/pkgbase/{name}/merge` action.
Package View
------------
- Some cached metadata is no longer cached (pkginfo). Previously,
this was defaulted to a one day cache for some package information.
If we need to bring this back, we can.
TU Proposals
------------
- A valid username is now required for any addition or removal of a TU.
RPC
---
- `type=get-comment-form` has been removed and is now located at
`/pkgbase/{name}/comments/{id}/form`.
- Support for versions 1-4 have been removed.
- JSON key ordering is different than PHP's JSON.
- `type=search` performance is overall slightly worse than PHP's. This
should not heavily affect users, as a 3,000 record query is returned
in roughly 0.20ms from a local standpoint. We will be working on this
in aim to push it over PHP.
Archives
--------
- Added metadata archive `packages-meta-v1.json.gz`.
- Added metadata archive `packages-meta-ext-v1.json.gz`.
- Enable this by passing `--extended` to `aurweb-mkpkglists`.
Performance Changes
-------------------
As is expected from a complete rewrite of the website, performance
has changed across the board. In most places, Python's implementation
now performs better than the pre-existing PHP implementation, with the
exception of a few routes. Notably:
- `/` loads much quicker as it is now persistently cached forcibly
for five minutes at a time.
- `/packages` search is much quicker.
- `/packages/{name}` view is slightly slower; we are no longer caching
various pieces of package info for `cache_pkginfo_ttl`, which is
defaulted to 86400 seconds, or one day.
- Request actions are slower due to the removal of the `via` parameter.
We now query the database for requests related to the action based on
the current state of the DB.
- `/rpc?type=info` queries are slightly quicker.
- `/rpc?type=search` queries of low result counts are quicker.
- `/rpc?type=search` queries of large result counts (> 2500) are slower.
- We are not satisfied with this. We'll be working on pushing this
over the edge along with the rest of the DB-intensive routes.
However, the speed degredation is quite negligible for users'
experience: 0.12ms PHP vs 0.15ms Python on a 3,000 record query
on my local 4-core 8-thread system.
Upcoming Work
-------------
This release is the first major release of the Python implementation.
We have multiple tasks up for work immediately, which will bring us
a few more minor versions forward as they are completed.
- Update request and tu vote pagers
- Archive differentials
- Archive mimetypes
- (a) Git scripts to ORM conversion
- (a) Sharness removal
- Restriction of number of requests users can submit
We heavily attempt to provide easy use of poetry virtualenvs
with aurweb in this revision of the INSTALL file. Added a
section about cron jobs and updated the nginx config example
with a lot more detail and locations for other parts of
the AUR infrastructure.
Signed-off-by: Kevin Morris <kevr@0cost.org>
The SQL logic in this file for package metadata now exactly
reflects RPC's search logic, without searching for specific
packages.
Two command line arguments are available:
--extended | Include License, Keywords, Groups, relations
and dependencies.
When --extended is passed, the script will create a
packages-meta-ext-v1.json.gz, configured via packagesmetaextfile.
Archive JSON is in the following format: line-separated package objects
enclosed in a list:
[
{...},
{...},
{...}
]
Signed-off-by: Kevin Morris <kevr@0cost.org>
Along with this initial requests metric implementation,
we also now serve the `/metrics` route, which grabs request
metrics out of cache and renders them properly for Prometheus.
**NOTE** Metrics are only enabled when the aurweb system admin
has enabled caching by configuring `options.cache` correctly
in `$AUR_CONFIG`. Otherwise, an error is logged about no cache
being configured.
New dependencies have been added which require the use of
`composer`. See `INSTALL` for the dependency section in regards
to composer dependencies and how to install them properly for
aurweb.
Metrics are in the following forms:
aurweb_http_requests_count(method="GET",route="/some_route")
aurweb_api_requests_count(method="GET",route="/rpc",type="search")
This should allow us to search through the requests for specific routes
and queries.
Signed-off-by: Kevin Morris <kevr@0cost.org>
As the new-age Python package manager, Poetry brings a lot
of good additions to the table. It allows us to more easily
deal with virtualenvs for the project and resolve dependencies.
As of this commit, `requirements.txt` is replaced by Poetry,
configured at `pyproject.toml`.
In Docker and GitLab, we currently use Poetry in a root fashion.
We should work toward purely using virtualenvs in Docker, but,
for now we'd like to move forward with other things. The project
can still be installed to a virtualenv and used on a user's system
through Poetry; it is just not yet doing so in Docker.
Modifications:
* docker/scripts/install-deps.sh
* Remove python dependencies.
* conf/config.defaults
* Script paths have been updated to use '/usr/bin'.
* docker/git-entrypoint.sh
* Use '/usr/bin/aurweb-git-auth' instead of
'/usr/local/bin/aurweb-git-auth'.
Additions:
* docker/scripts/install-python-deps.sh
* A script used purely to install Python dependencies with Poetry.
This has to be used within the aurweb project directory and
requires system-wide dependencies are installed beforehand.
* Also upgrades system-wide pip.
Signed-off-by: Kevin Morris <kevr@0cost.org>
python-orjson speeds up a lot of JSON serialization steps,
so we choose to use it over the standard library json module.
Signed-off-by: Kevin Morris <kevr@0cost.org>
This includes the addition of the python-fakeredis package,
used for stubbing python-redis when a user does not have a
configured cache.
Signed-off-by: Kevin Morris <kevr@0cost.org>
+ Mounted static files (at web/html) to /static.
+ Added AURWEB_VERSION to aurweb.config (this is used around HTML
to refer back to aurweb's release on git.archlinux.org), so we
need it easily accessible in the Python codebase.
+ Implemented basic Jinja2 partials to put together whole aurweb
pages. This may be missing some things currently and is a WIP
until this set is ready to be merged.
+ Added config [options] aurwebdir = YOUR_AUR_ROOT; this configuration
option should specify the root directory of the aurweb project.
It is used by various parts of the FastAPI codebase to target
project directories.
Added routes via aurweb.routers.html:
* POST /language: Set your session language.
* GET /favicon.ico: Redirect to /static/images/favicon.ico.
* Some browsers always look for $ROOT/favicon.ico to get an icon
for the page being loaded, regardless of a specified "shortcut
icon" given in a <link> directive.
* GET /: Home page; WIP.
* Updated aurweb.routers.html.language passes query parameters to
its next redirection.
When calling aurweb.templates.render_template, the context passed should
be formed via the aurweb.templates.make_context. See
aurweb.routers.html.index for an example of this.
Signed-off-by: Kevin Morris <kevr@0cost.org>
Additionally, we now ask for two more favors from contributors:
1. All source modified or added within a patchset **must** maintain
equivalent or increased coverage by providing tests that use the
functionality.
2. Please keep your source within an 80 column width.
PS: Sneak a few test Makefile and gitlab fixes.
Signed-off-by: Kevin Morris <kevr@0cost.org>
uvicorn is subjectively nicer to play with for local dev work, but
hypercorn is required in order to do HTTP/2 which is fairly
performance-important.
Signed-off-by: Kevin Morris <kevr@0cost.org>
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
Co-authored-by: Eli Schwartz <eschwartz@archlinux.org>
Signed-off-by: Eli Schwartz <eschwartz@archlinux.org>
The new schema was generated with sqlacodegen and then manually adjusted
to fit schema/aur-schema.sql faithfully, both in the organisation of the
code and in the SQL generated by SQLAlchemy.
Initializing the database now requires the new tool aurweb.initdb.
References to aur-schema.sql have been updated and the old schema
dropped.
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
In the process, rename config.proto to config.defaults (because that is
what it is now).
Also use dict.get('key', default_value) when querying os.environ, rather
than an if block, as it is more pythonic/readable/concise, and reduces
the number of dict lookups.
This change allows aurweb configuration to be done via either:
- copying config.defaults to config and modifying values
- creating a new config only containing modified values, next to a
config.defaults containing unmodified values
The motivation for this change is to enable ansible configuration in our
flagship deployment by storing only changed values, and deferring to
config.defaults otherwise.
A side benefit is, it is easier to see what has changed by inspecting
only the site configuration file.
If a config.defaults file does not exist next to $AUR_CONFIG or in
$AUR_CONFIG_DEFAULTS, it is ignored and *all* values are expected to
live in the modified config file.
Signed-off-by: Eli Schwartz <eschwartz@archlinux.org>
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
Change the defines to config_get and add one cache option and one option
to define memcache_servers. Mention the required dependency to get
memcached working in the INSTALL file.
Signed-off-by: Jelle van der Waa <jelle@vdwaa.nl>
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
To people unfamiliar with the code, it is not obvious that
the pdo_* PHP extensions must be enabled.
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
Add installation instructions for python-bleach and python-markdown
which are required for the rendercomment script.
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
AUR_PRIVILEGED allows people with privileged AUR accounts to evade the
block on non-fast-forward commits. While valid in this case, we should
not do so by default, since in at least one case a TU did this without
realizing there was an existing package.
( https://aur.archlinux.org/packages/rtmidi/ )
Switch to using allow_overwrite to check for destructive actions.
Use .ssh/config "SendEnv" on the TU's side and and sshd_config
"AcceptEnv" in the AUR server to specifically request overwrite access.
TUs should use: `AUR_OVERWRITE=1 git push --force`
Signed-off-by: Eli Schwartz <eschwartz@archlinux.org>
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
Add instructions to test aurweb's web interface via the PHP built-in web
server.
Signed-off-by: Mark Weiman <mark.weiman@markzz.com>
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
Add a note to the Git/SSH interface documentation that we recommend to
disable automatic garbage collection and use a maintenance script to
cleanup and optimize the Git repository instead.
Also, add a reference to the Git/SSH interface documentation to the Git
repository setup instructions in INSTALL.
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
Since d4fe77a (Reorganize Git interface scripts, 2016-10-08), the key
components of the aurweb SSH interface are installed system-wide. Update
the default configuration path to point to a central location.
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
Move the Git interface scripts from git-interface/ to aurweb/git/. Use
setuptools to automatically create wrappers which can be installed using
`python3 setup.py install`. Update the configuration files, the test
suite as well as the INSTALL and README files to reflect these changes.
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
In 002d348 (Describe how to omit "have" lines, 2015-11-14), we added
instructions on how to omit "have" lines originating from other package
repositories. Fix those instructions such that the HEAD ref of the
repository is transferred properly.
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
python-srcinfo is a more transparent and simpler library for parsing
SRCINFO files.
Signed-off-by: Johannes Löthberg <johannes@kyriasis.com>
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
A new feature in Git allows for omitting "have" lines corresponding to
refs outside the current Git namespace. Explain how to enable this
feature in the INSTALL instructions and in the Git interface
documentation.
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
Using uWSGI for the Smart HTTP protocol caused some issues, see e.g.
FS#45428. Suggest using fcgiwrap instead which is more lightweight, has
better documentation and is easier to debug.
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
Specifically check for URIs git-http-backend(1) can handle. This also
allows us to make the ".git" suffix optional.
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
To make sure we never lose any history, non-fast-forwards are forbidden.
Instead of relying on receive.denyNonFastForwards, add a simple check to
the update hook. This has the added benefit of more flexibility.
Signed-off-by: Lukas Fleischer <lfleischer@archlinux.org>
