v3.2.4 - large structural & featureset improvements overall (more details in desc) (osuAkatsuki#69)

* /api/get_replay

* binoppai

* probably broken tourney client support & api cleanup

* mods in /api/get_scores (strong & weak equality)

* more api handlers & cleanup

* add api/get_map_scores & api/get_score_info

* add /api/get_match

* add api keys & PUT /api/set_avatar

* api (tokens -> keys) & fixes

* de-cringe

* add Player.send_bot to match Channel api

* use chimu.moe as default mirror, extra support

* switch to -devserver, fix custom (& ctb) achievements

* better handling for sql update failure & less deps

* add `after_serving` for `cmyui`.Server

* optional server switcher support in nginx (temporary)

* allow for `!recent <player>` syntax

* switcher support [2/2]

* missed /np ppy.sh

* add assets.ppy.sh for switcher support as well

* beatmap ratings (osu-osz2-getscores.php)

* basic mania pp support

* add ssl certificate generation to readme (fixes osuAkatsuki#63)

* add map info to /api/get_player_(scores/status)

* allow for /api/get_player_info?scope=all

* clean up main & collections

* add Context object to commands (contains trigger, likely more to come), add !server

* testing without clans be like

* shutdown properly on sql updater failure & include psutil in reqs

* for now.. lol

Author: cmyui

README.md

@@ -1,199 +1,111 @@
 [![Discord](https://discordapp.com/api/guilds/748687781605408908/widget.png?style=shield)](https://discord.gg/ShEQgUx)
 
-Table of Contents
-==================
-- [Table of Contents](#table-of-contents)
-  - [What is gulag?](#what-is-gulag)
-  - [Currently supported player commands](#currently-supported-player-commands)
-  - [Requirements](#requirements)
-  - [Setup](#setup)
-  - [Directory Structure](#directory-structure)
-
-What is gulag?
-------
-
-gulag is my take on the abstraction of an osu! server; I use native async/await
-syntax, and have written the server from the ground up from sockets using my
-[python package](https://github.com/cmyui/cmyui_pkg)'s web server implementation.
-This relatively low-level design allows for flexibility, cleanliness, and efficiency
-not seen in other codebases - all while maintaining the simplicity of Python.
-
-A primary goal of gulag is to keep our codebase a developer-friendly API, so
-that programming remains about the logic and ideas, rather than the code itself.
-
-I'm mainly writing this as it's by-far the subject I'm currently the most
-educated in.. I started [Akatsuki](https://akatsuki.pw/) (and programming
-alltogether) back in October of 2017, and I've been managing it since.
-
-The server has come [a long way](https://cdn.discordapp.com/attachments/616400094408736779/799434379176574986/unknown.png),
-and is in quite a usable state. We most likely handle every packet/handler
-supported by any competing server implementation, and feature a very large
-api and [commandset](#currently-supported-player-commands) for both developers
-and players alike, with many unique features only available with gulag.
-
-gulag's database structure is built from the ground up using no specific
-references; this makes it incompatible with common stacks like Ripple's.
-[gulag-web](https://github.com/Yo-ru/gulag-web) is a project being developed
-primarily by the community members of our [Discord](https://discord.gg/ShEQgUx)
-who are interested in the project; they aim to atleast create a fully
-functional frontend, while the location of the API remains undecided.
-Over the past few weeks the development effort has been growing and some
-great progress is starting to be made; I'd recommend checking it out!
-
-Currently supported player commands
-------
-gulag's commandset has been growing quite nicely.
-
-```
-Generic
-------
-
-!help: Show information of all documented commands the player can access.
-!roll: Roll an n-sided die where n is the number you write (100 default).
-!maplink: Return a download link to the user's current map (situation dependant).
-!recent: Show information about your most recent score.
-!with: Specify custom accuracy & mod combinations with `/np`.
-!request: Request a beatmap for nomination.
-!requests: Check the nomination request queue.
-!map: Changes the ranked status of the most recently /np'ed map.
-!notes: Retrieve the logs of a specified player by name.
-!addnote: Add a note to a specified player by name.
-!silence: Silence a specified player with a specified duration & reason.
-!unsilence: Unsilence a specified player.
-!ban: Ban a specified player's account, with a reason.
-!unban: Unban a specified player's account, with a reason.
-!alert: Send a notification to all players.
-!alertuser: Send a notification to a specified player by name.
-!recalc: Performs a full PP recalc on a specified map, or all maps.
-!switchserv: Switch your client's internal endpoints to a specified IP address.
-!debug: Toggle the console's debug setting.
-!setpriv: Set privileges for a specified player (by name).
-!reload: Reload a python module.
-!py: Allow for (async) access to the python interpreter.
-
-
-Multiplayer Management
-------
-
-!mp help: Show information of all documented mp commands the player can access.
-!mp start: Start the current multiplayer match, with any players ready.
-!mp abort: Abort the current in-progress multiplayer match.
-!mp map: Set the current match's current map by id.
-!mp mods: Set the current match or player's mods (depending on freemods).
-!mp freemods: Toggle freemods status for the match.
-!mp host: Set the current match's current host by id.
-!mp randpw: Randomize the current match's password.
-!mp invite: Invite a player to the current match by name.
-!mp addref: Add a referee to the current match by name.
-!mp rmref: Remove a referee from the current match by name.
-!mp listref: List all referees from the current match.
-!mp lock: Lock all unused slots in the current match.
-!mp unlock: Unlock locked slots in the current match.
-!mp teams: Change the team type for the current match.
-!mp condition: Change the win condition for the match.
-!mp scrim: Start a scrim in the current match.
-!mp endscrim: End the current matches ongoing scrim.
-!mp rematch: Restart a scrim with the previous match points, or roll back the most recent match point.
-!mp force: Force a player into the current match by name.
-!mp loadpool: Load a mappool into the current match.
-!mp unloadpool: Unload the current matches mappool.
-!mp ban: Ban a pick in the currently loaded mappool.
-!mp unban: Unban a pick in the currently loaded mappool.
-!mp pick: Pick a map from the currently loaded mappool.
-
-
-Mappool Management
-------
-
-!pool help: Show information of all documented pool commands the player can access.
-!pool create: Add a new mappool to the database.
-!pool delete: Remove a mappool from the database.
-!pool add: Add a new map to a mappool in the database.
-!pool remove: Remove a map from a mappool in the database.
-!pool list: List all existing mappools information.
-!pool info: Get all information for a specific mappool.
-
-
-Clan Management
-------
-
-!clan help: Show information of all documented clan commands the player can access.
-!clan create: Create a clan with a given tag & name.
-!clan disband: Disband a clan (admins may disband others clans).
-!clan info: Lookup information of a clan by tag.
-!clan list: List all existing clans information.
-```
-
-Requirements
-------
-
-- Some know-how with Linux (tested on Ubuntu 18.04), python, and general-programming knowledge.
-- An osu! account (or more specifically, an osu! api key). This is technically optional, but is required for full usage.
-- An SSL Certificate for c(e4-6).ppy.sh (such as [this](https://github.com/osuthailand/ainu-certificate)).
-
-Setup
-------
-
-Setup should be pretty simple - the commands below should set you right up.
-
-Notes:
-
-- Ubuntu 20.04 is known to have issues with nginx and osu for unknown reasons?
-- I will not be able to help you out with creating a custom certificate of your own.
-- If you have any difficulties setting up gulag, feel free to join the Discord server at the top of the README, we now have a bit of a community!
+DISCLAIMER: gulag is still in a beta stage - the server is certainly getting quite
+stable & useable now, but don't let it fool you too much.. there are still large
+portions of the underlying systems that have yet to be implemented completely correctly.
+
+gulag is my implementation of an osu! server's backend (bancho protocol, /web endpoints,
+avatars/assets, and a devevloper rest api). it's designed for relatively experienced devs
+looking for an osu! server with more bells and whistles than many other implementations.
+
+note that in it's current stage, gulag is not nescessarily user-friendly..
+dev-friendly is much better wording; please remember that this is not one of my
+current goals with the project. perhaps eventually the focus will shift, but not
+in the foreseeable future. making small prs to try to fix this is also not a great
+idea, i'm not in the business of trying to make people think it's made to be
+user-friendly when it's not really lol. the time may come eventually.
+
+please don't feel like you need to contribute. this is mostly a one man project and
+this is the way i like it; gulag is my baby and i can probably tell you about any
+portion of code off the top of my head. bugfixes and small improvements are welcome,
+but i think with the average osu developer age being quite low, there will be lots
+more newer devs than older devs :P (i myself am still quite new in the grand scheme).
+if you're making large scale changes, do it for learning rather than clout, and
+i promise the long-term game will this kind of behaviour nicely :)
+
+there is currently no official frontend project for gulag, but members of the community
+have made significant headway with [gulag-web](https://github.com/Yo-ru/gulag-web).
+please note that this project is not maintained by me, and that my focus remains on the
+osu! server itself.
+
+Installation Guide
+-------------
+important notes:
+- ubuntu 20.04 & nginx have unknown issues? i recommend using 18.04
+- i will not help with the creation of a fake *.ppy.sh cert for switcher support.
 
 ```sh
-# Install python3.9 (requires ppa).
+# add ppa for py3.9 (required since it's new)
 sudo add-apt-repository ppa:deadsnakes/ppa
-sudo apt install python3.9 python3.9-dev python3.9-distutils
 
-# Install pip for 3.9.
+# install requirements (py3.9, mysql, nginx, build tools, certbot)
+sudo apt install python3.9 python3.9-dev python3.9-distutils \
+                 mysql-server nginx build-essential certbot
+
+# install pip for py3.9
 wget https://bootstrap.pypa.io/get-pip.py
 python3.9 get-pip.py && rm get-pip.py
 
-# Install our database, reverse-proxy, and build tools.
-sudo apt install mysql-server nginx build-essential
-
-# Clone gulag from github.
+# clone the repo & init submodules
 git clone https://github.com/cmyui/gulag.git && cd gulag
-
-# Init & update submodules.
 git submodule init && git submodule update
 
-# Build oppai-ng's binary.
+# install gulag requirements w/ pip
+python3.9 -m pip install -r ext/requirements.txt
+
+# build oppai-ng's binary
 cd oppai-ng && ./build && cd ..
 
-# Install gulag's requirements.
-python3.9 -m pip install -r ext/requirements.txt
+######################################
+# NOTE: before continuing, create an #
+# empty database in mysql for gulag  #
+######################################
 
-# Import gulag's database structure.
-# NOTE: create an empty database before doing this.
-# This will also insert basic osu! channels & the bot.
+# import gulag's mysql structure
 mysql -u your_sql_username -p your_db_name < ext/db.sql
 
-# Add gulag's nginx config to your nginx/sites-enabled.
-# NOTE: default unix socket location is `/tmp/gulag.sock`,
-# and you will have to change the certificate paths in
-# the nginx config file to your own certificate paths.
-sudo ln ext/nginx.conf /etc/nginx/sites-enabled/gulag.conf
+# generate an ssl certificate for your domain (change email & domain)
+sudo certbot certonly \
+    --manual \
+    --preferred-challenges=dns \
+    --email [email protected] \
+    --server https://acme-v02.api.letsencrypt.org/directory \
+    --agree-tos \
+    -d *.your.domain
+
+# copy our nginx config to `sites-enabled` & open for editing
+sudo cp ext/nginx.conf /etc/nginx/sites-enabled/gulag.conf
+sudo nano /etc/nginx/sites-enabled/gulag.conf
+
+##########################################
+# NOTE: before continuing, make sure you #
+# have completely configured the file.   #
+##########################################
+
+# reload the reverse proxy's config
 sudo nginx -s reload
 
-# Configure gulag.
+# copy our gulag config to cwd & open for editing
 cp ext/config.sample.py config.py
 nano config.py
 
-# Start the server.
+##########################################
+# NOTE: before continuing, make sure you #
+# have completely configured the file.   #
+##########################################
+
+# start the server
 ./main.py
 ```
 
 Directory Structure
 ------
     .
-    ├── constants  # Code for representing gamemodes, mods, privileges, and other constants.
-    ├── ext        # External files from gulag's primary operation.
-    ├── objects    # Code for representing players, scores, maps, and more.
-    ├── utils      # Utility functions used throughout the codebase for general purposes.
-    └── domains    # The route-continaing domains accessible to the public web.
-        ├── cho    # (ce|c4|c5|c6).ppy.sh/* routes
-        ├── osu    # osu.ppy.sh/* routes
-        └── ava    # a.ppy.sh/* routes
+    ├── constants  # code representing gamemodes, mods, privileges, and other constants.
+    ├── ext        # external files from gulag's primary operation.
+    ├── objects    # code for representing players, scores, maps, and more.
+    ├── utils      # utility functions used throughout the codebase for general purposes.
+    └── domains    # the route-continaing domains accessible to the public web.
+        ├── cho    # (ce|c4|c5|c6).ppy.sh/* routes (bancho connections)
+        ├── osu    # osu.ppy.sh/* routes (mainly /web/ & /api/)
+        └── ava    # a.ppy.sh/* routes (avatars)