From 579426df591f2d984a4fd53c2c55c40eb0198a53 Mon Sep 17 00:00:00 2001 From: Lacy Date: Tue, 14 Jul 2026 13:14:44 +0200 Subject: [PATCH] docs(headers): Added file header with copyright & file description --- .cargo/config.toml | 9 +++++++++ Cargo.toml | 9 +++++++++ Dockerfile | 9 +++++++++ assets/input.css | 11 +++++++++++ audit.toml | 9 +++++++++ docker-compose.yml | 10 ++++++++++ import.sql | 9 +++++++++ rust-toolchain.toml | 8 ++++++++ src/doc.rs | 12 ++++++++++++ src/logging/flusher.rs | 13 +++++++++++++ src/logging/mod.rs | 11 +++++++++++ src/main.rs | 12 ++++++++++++ src/middleware/auth.rs | 12 ++++++++++++ src/middleware/logging.rs | 12 ++++++++++++ src/middleware/mod.rs | 11 +++++++++++ src/models/auth.rs | 11 +++++++++++ src/models/entity.rs | 12 ++++++++++++ src/models/game.rs | 11 +++++++++++ src/models/matchs.rs | 11 +++++++++++ src/models/mod.rs | 11 +++++++++++ src/models/tournament.rs | 10 ++++++++++ src/routes/dashboard.rs | 13 +++++++++++++ src/routes/health.rs | 10 ++++++++++ src/routes/map.rs | 11 +++++++++++ src/routes/matches.rs | 11 +++++++++++ src/routes/mod.rs | 11 +++++++++++ src/routes/players.rs | 11 +++++++++++ src/routes/teams.rs | 11 +++++++++++ src/routes/tournaments.rs | 11 +++++++++++ src/util.rs | 11 +++++++++++ swagger-ui-overrides/index.html | 11 +++++++++++ templates/_style.html | 11 +++++++++++ templates/dashboard.html | 12 ++++++++++++ templates/dashboard_history.html | 11 +++++++++++ templates/dashboard_login.html | 11 +++++++++++ 35 files changed, 379 insertions(+) diff --git a/.cargo/config.toml b/.cargo/config.toml index 7ce8c70..849ba0d 100644 --- a/.cargo/config.toml +++ b/.cargo/config.toml @@ -1,2 +1,11 @@ +# GC-Stats — API +# +# Cargo configuration: points cargo run/build at the local Swagger UI +# overrides folder used to theme the embedded docs. +# +# Copyright (c) 2026 Alice Alleman — GC-Stats-API +# License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) +# Repository: https://github.com/GC-Stats/API + [env] SWAGGER_UI_OVERWRITE_FOLDER = { value = "swagger-ui-overrides", relative = true } \ No newline at end of file diff --git a/Cargo.toml b/Cargo.toml index 6be392d..418c217 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,3 +1,12 @@ +# GC-Stats — API +# +# Cargo package manifest: crate metadata and dependencies for the GC-Stats +# API service. +# +# Copyright (c) 2026 Alice Alleman — GC-Stats-API +# License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) +# Repository: https://github.com/GC-Stats/API + [package] name = "GC-Stats-API" version = "1.0.0" diff --git a/Dockerfile b/Dockerfile index 71866b4..7332e85 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,3 +1,12 @@ +# GC-Stats — API +# +# Multi-stage Docker build: compiles the Rust binary and Tailwind CSS +# assets, then copies them into a slim runtime image. +# +# Copyright (c) 2026 Alice Alleman — GC-Stats-API +# License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) +# Repository: https://github.com/GC-Stats/API + FROM rust:1.95-slim-bookworm AS builder RUN apt-get update && apt-get install -y \ diff --git a/assets/input.css b/assets/input.css index 4db10e5..c03e7bf 100644 --- a/assets/input.css +++ b/assets/input.css @@ -1,3 +1,14 @@ +/* + GC-Stats — API + + Tailwind entry stylesheet: theme tokens (colors, fonts) and base styles + for the dashboard pages. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + @import "tailwindcss"; @source "../templates"; diff --git a/audit.toml b/audit.toml index 7c096e0..a6bad59 100644 --- a/audit.toml +++ b/audit.toml @@ -1,2 +1,11 @@ +# GC-Stats — API +# +# cargo-audit configuration: advisories intentionally ignored, with +# justification. +# +# Copyright (c) 2026 Alice Alleman — GC-Stats-API +# License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) +# Repository: https://github.com/GC-Stats/API + [ignore] RUSTSEC-2023-0071 = { reason = "Used only for MySQL auth in sqlx, not for sensitive crypto operations. No fix available upstream." } \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml index 3053d42..cab69c5 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,3 +1,13 @@ +# GC-Stats — API +# +# Docker Compose services for the production and pre-production API +# containers, including their networks and Loki logging driver +# configuration. +# +# Copyright (c) 2026 Alice Alleman — GC-Stats-API +# License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) +# Repository: https://github.com/GC-Stats/API + services: gc_prod_api: build: diff --git a/import.sql b/import.sql index 7d4b452..27d89f4 100644 --- a/import.sql +++ b/import.sql @@ -1,3 +1,12 @@ +-- GC-Stats — API +-- +-- Database schema/data dump used to (re)create the gc_prod database +-- structure. +-- +-- Copyright (c) 2026 Alice Alleman — GC-Stats-API +-- License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) +-- Repository: https://github.com/GC-Stats/API + -- phpMyAdmin SQL Dump -- version 5.2.3 -- https://www.phpmyadmin.net/ diff --git a/rust-toolchain.toml b/rust-toolchain.toml index 4933b3b..3ab2929 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -1,2 +1,10 @@ +# GC-Stats — API +# +# Pins the Rust toolchain version used to build this project. +# +# Copyright (c) 2026 Alice Alleman — GC-Stats-API +# License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) +# Repository: https://github.com/GC-Stats/API + [toolchain] channel = "1.95" diff --git a/src/doc.rs b/src/doc.rs index c3fbe69..8930752 100644 --- a/src/doc.rs +++ b/src/doc.rs @@ -1,3 +1,15 @@ +/* + GC-Stats — API + + OpenAPI documentation for the public API. Declares the documented paths, + response schemas and tags, and registers the `x-api-key` header security + scheme shown in Swagger UI. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use utoipa::openapi::security::{ApiKey, ApiKeyValue, SecurityScheme}; use utoipa::{Modify, OpenApi}; use crate::routes::{matches, players, tournaments, map}; diff --git a/src/logging/flusher.rs b/src/logging/flusher.rs index 24a1cbf..89405b6 100644 --- a/src/logging/flusher.rs +++ b/src/logging/flusher.rs @@ -1,3 +1,16 @@ +/* + GC-Stats — API + + Background task that periodically drains buffered request-log entries + from local Redis into the `api_request_log` MariaDB table. Uses an + inflight key so a crash mid-flush is recovered and retried on the next + cycle without losing entries. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use std::sync::Arc; use std::time::Duration; use redis::{AsyncCommands, Script}; diff --git a/src/logging/mod.rs b/src/logging/mod.rs index a51281f..375006e 100644 --- a/src/logging/mod.rs +++ b/src/logging/mod.rs @@ -1 +1,12 @@ +/* + GC-Stats — API + + Declares the logging module and re-exports the request-log flusher + submodule. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + pub mod flusher; diff --git a/src/main.rs b/src/main.rs index 36e0ba0..fcafac1 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,3 +1,15 @@ +/* + GC-Stats — API + + Application entrypoint. Loads configuration, connects to MariaDB and + Redis, builds the Axum router (health check, dashboard, versioned `/v1` + API, Swagger UI) and starts the HTTP server. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + mod models; mod routes; mod middleware; diff --git a/src/middleware/auth.rs b/src/middleware/auth.rs index ffa732d..35e6f4d 100644 --- a/src/middleware/auth.rs +++ b/src/middleware/auth.rs @@ -1,3 +1,15 @@ +/* + GC-Stats — API + + Authentication and rate-limiting middleware for the `/v1` API. Validates + the `x-api-key` header against MariaDB (cached in Redis) and enforces a + sliding-window rate limit per key. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use axum::{ extract::{State, Request}, http::StatusCode, diff --git a/src/middleware/logging.rs b/src/middleware/logging.rs index b9ea210..a22f8ff 100644 --- a/src/middleware/logging.rs +++ b/src/middleware/logging.rs @@ -1,3 +1,15 @@ +/* + GC-Stats — API + + Middleware that records method, matched route, status code, duration and + user agent for each request, then pushes the entry onto the local Redis + buffer for later flushing to MariaDB. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use axum::{ extract::{State, Request}, middleware::Next, diff --git a/src/middleware/mod.rs b/src/middleware/mod.rs index 7eaa040..844d729 100644 --- a/src/middleware/mod.rs +++ b/src/middleware/mod.rs @@ -1,2 +1,13 @@ +/* + GC-Stats — API + + Declares the middleware module and re-exports the auth and logging + submodules. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + pub mod auth; pub mod logging; diff --git a/src/models/auth.rs b/src/models/auth.rs index 9665fb7..87092da 100644 --- a/src/models/auth.rs +++ b/src/models/auth.rs @@ -1,3 +1,14 @@ +/* + GC-Stats — API + + API key model and the SHA-256 hashing helper used to store and look up + keys without persisting them in plaintext. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use serde::{Serialize, Deserialize}; use sha2::{Digest, Sha256}; use sqlx::FromRow; diff --git a/src/models/entity.rs b/src/models/entity.rs index fa9cf88..8b30b34 100644 --- a/src/models/entity.rs +++ b/src/models/entity.rs @@ -1,3 +1,15 @@ +/* + GC-Stats — API + + Shared response models and helpers for players and teams: logo/photo URL + building, logo history partitioning, batched current-logo lookups, and + the `Player`/`Team` DB row types. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use std::collections::HashMap; use serde::{Serialize, Deserialize}; use sqlx::FromRow; diff --git a/src/models/game.rs b/src/models/game.rs index 1f0373d..ddc7fb5 100644 --- a/src/models/game.rs +++ b/src/models/game.rs @@ -1,3 +1,14 @@ +/* + GC-Stats — API + + Response models for maps and rounds: per-map player stats, map metadata, + and per-round player stats. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use serde::{Serialize, Deserialize}; use sqlx::FromRow; use utoipa::ToSchema; diff --git a/src/models/matchs.rs b/src/models/matchs.rs index 99dcdd4..b5af857 100644 --- a/src/models/matchs.rs +++ b/src/models/matchs.rs @@ -1,3 +1,14 @@ +/* + GC-Stats — API + + Response models for matches: the match record itself and its map + vetoes. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use serde::{Serialize, Deserialize}; use sqlx::FromRow; use chrono::{ NaiveDateTime }; diff --git a/src/models/mod.rs b/src/models/mod.rs index 16b1d9f..4a12904 100644 --- a/src/models/mod.rs +++ b/src/models/mod.rs @@ -1,3 +1,14 @@ +/* + GC-Stats — API + + Declares the models module and re-exports the game, match, tournament, + entity and auth submodules. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + pub mod game; pub mod matchs; pub mod tournament; diff --git a/src/models/tournament.rs b/src/models/tournament.rs index 6c067aa..33adde0 100644 --- a/src/models/tournament.rs +++ b/src/models/tournament.rs @@ -1,3 +1,13 @@ +/* + GC-Stats — API + + Response models for tournaments: the tournament record and its phases. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use serde::{Serialize, Deserialize}; use sqlx::FromRow; use chrono::NaiveDate; diff --git a/src/routes/dashboard.rs b/src/routes/dashboard.rs index 8e177c4..dae3a1f 100644 --- a/src/routes/dashboard.rs +++ b/src/routes/dashboard.rs @@ -1,3 +1,16 @@ +/* + GC-Stats — API + + Routes for the client-facing usage dashboard: login/logout via API key, + request statistics (summary, status breakdown, top endpoints, + time-bucketed chart), recent logs, and the paginated request history + page. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use std::net::SocketAddr; use std::sync::Arc; use askama::Template; diff --git a/src/routes/health.rs b/src/routes/health.rs index a1b573c..b4058d7 100644 --- a/src/routes/health.rs +++ b/src/routes/health.rs @@ -1,3 +1,13 @@ +/* + GC-Stats — API + + Health check endpoint used for uptime monitoring. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use axum::{Json}; use serde_json::{json, Value}; diff --git a/src/routes/map.rs b/src/routes/map.rs index bee18f0..5119cdf 100644 --- a/src/routes/map.rs +++ b/src/routes/map.rs @@ -1,3 +1,14 @@ +/* + GC-Stats — API + + `/v1/map` endpoints: fetch a map's full details (teams, player stats) + and its per-round breakdown. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use std::collections::{BTreeMap, HashSet}; use axum::{extract::{Path, State}, Json, http::StatusCode, Router}; use std::sync::Arc; diff --git a/src/routes/matches.rs b/src/routes/matches.rs index 27b7af0..672d7af 100644 --- a/src/routes/matches.rs +++ b/src/routes/matches.rs @@ -1,3 +1,14 @@ +/* + GC-Stats — API + + `/v1/matches` endpoint: fetch a match's full details (teams, maps, + vetoes). + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use axum::{extract::{Path, State}, Json, http::StatusCode, Router}; use std::sync::Arc; use axum::routing::get; diff --git a/src/routes/mod.rs b/src/routes/mod.rs index 91bba69..7631ee1 100644 --- a/src/routes/mod.rs +++ b/src/routes/mod.rs @@ -1,3 +1,14 @@ +/* + GC-Stats — API + + Declares the routes module and assembles the versioned `/v1` API router + from the teams, players, tournaments, matches and map routers. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use std::sync::Arc; use axum::Router; use crate::AppState; diff --git a/src/routes/players.rs b/src/routes/players.rs index 61004b0..cb5fc21 100644 --- a/src/routes/players.rs +++ b/src/routes/players.rs @@ -1,3 +1,14 @@ +/* + GC-Stats — API + + `/v1/players` endpoints: search players by name, fetch a player's full + profile, their team history, and their photo history. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use axum::{extract::{Path, State}, Json, http::StatusCode, Router}; use std::sync::Arc; use axum::routing::get; diff --git a/src/routes/teams.rs b/src/routes/teams.rs index 42f828c..0baa468 100644 --- a/src/routes/teams.rs +++ b/src/routes/teams.rs @@ -1,3 +1,14 @@ +/* + GC-Stats — API + + `/v1/teams` endpoints: search teams by name, fetch a team's full + profile, its current/past roster, and its logo history. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use axum::{extract::{Path, State}, Json, http::StatusCode, Router}; use std::sync::Arc; use axum::routing::get; diff --git a/src/routes/tournaments.rs b/src/routes/tournaments.rs index aff6fca..440e8d3 100644 --- a/src/routes/tournaments.rs +++ b/src/routes/tournaments.rs @@ -1,3 +1,14 @@ +/* + GC-Stats — API + + `/v1/tournaments` endpoints: search tournaments by name, fetch a + tournament's full details with its phases, and its logo history. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + use axum::{extract::{Path, State}, Json, http::StatusCode, Router}; use std::sync::Arc; use axum::routing::get; diff --git a/src/util.rs b/src/util.rs index 1c83a71..9311502 100644 --- a/src/util.rs +++ b/src/util.rs @@ -1,3 +1,14 @@ +/* + GC-Stats — API + + Shared utility functions, currently a helper to escape SQL `LIKE` + wildcards in user-supplied search input. + + Copyright (c) 2026 Alice Alleman — GC-Stats-API + License: https://github.com/GC-Stats/API/blob/main/LICENSE.md (GC-Stats License v1.0) + Repository: https://github.com/GC-Stats/API +*/ + /// Escapes MySQL `LIKE` wildcards (`%`, `_`) and the escape character itself /// so user input is matched literally instead of being interpreted as a pattern. pub fn escape_like(input: &str) -> String { diff --git a/swagger-ui-overrides/index.html b/swagger-ui-overrides/index.html index 9584c35..624ce06 100644 --- a/swagger-ui-overrides/index.html +++ b/swagger-ui-overrides/index.html @@ -1,3 +1,14 @@ + + diff --git a/templates/_style.html b/templates/_style.html index db08892..afb493c 100644 --- a/templates/_style.html +++ b/templates/_style.html @@ -1,3 +1,14 @@ + + diff --git a/templates/dashboard.html b/templates/dashboard.html index a495eda..2b4fe23 100644 --- a/templates/dashboard.html +++ b/templates/dashboard.html @@ -1,3 +1,15 @@ + + diff --git a/templates/dashboard_history.html b/templates/dashboard_history.html index 89c1499..c5b5527 100644 --- a/templates/dashboard_history.html +++ b/templates/dashboard_history.html @@ -1,3 +1,14 @@ + + diff --git a/templates/dashboard_login.html b/templates/dashboard_login.html index 6e24561..350cda8 100644 --- a/templates/dashboard_login.html +++ b/templates/dashboard_login.html @@ -1,3 +1,14 @@ + +