v5.0.0 - Overall project restructuring & refactoring

This one comes with quite a few updates and improvements to the codebase.
(implementing more of my learnings from time away)

decoupling of logic & data into separate (functional) api layers

One of the main issues facing the codebase is it's tight coupling of logic & data.

Let's take the Beatmap class as an example - it;

• defines the representation of an osu! beatmap
• provides methods to interact with specific instances
• contains the logical functionality for managing osu! beatmaps

If you look through bancho.py's codebase, you'll see this recurring theme implemented in many inconsistent ways.
(see if you can find the similarities & differences in the Player class for example)

This PR aims to decouple structural representation, data providers, and business logic into 3 separate api levels.

data structures will be represented as "models"

Models represent the format of a resource.
They allow you to think only about the structure of a resource - the attributes within it and its properties.

An example of a model may be the representation of a beamtap - for example;

from dataclasses import dataclass

@dataclass
class Beatmap:
    id: int
    set_id: int
    md5: str
    ranked_status: int

    circle_size: float
    health_drain: float
    approach_rate: float
    overall_difficulty: float

(you may also define simple properties, but nothing involving complex logic or external data points)

data providers will be represented as "repositories"

Repositories are an abstraction around the interaction with a resource.
They allow you to think of the interactions with the data providing service, as opposed to the actual implementation details of the underlying services - proving a standardized API for your business-logic layers.

Continuing with the theme of beatmaps, a simple repository may look something like

from typing import Mapping
from typing import Optional

import models
import services

## in-memory cache

id_cache: Mapping[int, models.Beatmap] = {}
md5_cache: Mapping[str, models.Beatmap] = {}

## reads

async def fetch_by_id(id: int) -> Optional[models.Beatmap]:
    if beatmap := id_cache.get(id):
        return beatmap

    beatmap_row = await services.database.fetch_one(
        "SELECT * FROM beatmaps WHERE id = :id",
        {"id": id},
    )
    if beatmap_row is None:
        return None

    beatmap = models.Beatmap(**beatmap_row)

    id_cache[beatmap.id] = beatmap

    return beatmap

## writes

## updates

async def update_status(id: int, new_status: int) -> None:
    await services.database.execute(
        "UPDATE beatmaps SET status = :status WHERE id = :id",
        {"status": new_status, "id": id},
    )

    id_cache[id].status = new_status


async def update_playcount(id: int, playcount: int) -> None:
    await services.database.execute(
        "UPDATE beatmaps SET playcount = :playcount WHERE id = :id",
        {"playcount": playcount, "id": id},
    )

    id_cache[id].playcount = playcount

## deletes

async def delete_by_id(id: int) -> None:
    await services.database.execute(
        "DELETE FROM beatmaps WHERE id = :id",
        {"id": id},
    )

    if id in id_cache:
        del id_cache[id]

(you may also have functions to fetch by other means, update, or create beatmaps)

business logic will be represented by specific "usecases"

Usecases define the logical interface exposed by a resource.
They allow you to interact with & make complex calculations & modifications possibly depending on multiple resources simultaneously.

Building on our previous examples further, some use cases of a beatmap may look something like

import models
import repositories

async def update_status(beatmap: models.Beatmap, new_status: int) -> None:
    await repositories.beatmaps.update_status(beatmap.id, new_status)


async def update_playcount(beatmap: models.Beatmap) -> None:
    await repositories.beatmaps.update_playcount(beatmap.id, beatmap.plays)

Splitting the objects into layers like this allows us to implement a standardized API across the codebase's multiple resources.

With this sort of orthogonal design, we can increase code reuse significantly, increase the level of abstraction the programmer works at, and use this api as a framework for writing unit & smoke tests for the regular user flow in the application trivially.

restful api restructuring

This PR also resolves the paths provided by the v1 API to be restful -- we've updated the paths to fit a resource-driven design.

# GET /players/{player_id}
# GET /players/{player_id}/stats
# GET /players/{player_id}/status
# GET /players/{player_id}/scores/best
# GET /players/{player_id}/scores/recent
# GET /players/{player_id}/most-played-beatmaps
# GET /players/leaderboard

# GET /beatmaps/{beatmap_id}
# GET /beatmaps/{beatmap_id}/scores

# GET /scores/{score_id}
# GET /scores/{score_id}/replay

# GET /matches/{match_id}

assume developers will use cloudflare (flex) for ssl

This simplifies the server setup itself quite significantly - no need for an ssl certificate, complex nginx setup or anything - just listen on port 80 and have cloudflare do the rest - implemented here.

disclaimer

Note that the examples provided in this are simplifications, and the exact implementation details of the PR are still being actively worked on - nothing is final!