Skip to content

README.md

Latest commit

 

History

History
166 lines (112 loc) · 5.6 KB

README.md

File metadata and controls

166 lines (112 loc) · 5.6 KB
Raw

API Service

Main backend API service for the CORE game website.

Overview

This NestJS service serves as the primary backend, handling:

  • User authentication and management
  • Team and event/tournament management
  • Match results and statistics
  • Database operations (PostgreSQL)
  • RabbitMQ microservice communication

Getting Started

Prerequisites

Use Node.js 26 or newer. TypeScript stays on the 6.0 release line because the Nest CLI, ts-jest, and typescript-eslint require its JavaScript compiler API.

Install pnpm:

corepack enable && corepack prepare pnpm@latest --activate

or

brew install pnpm

Installation & Setup

  1. Install dependencies:

    pnpm install

  2. Set up environment variables:

    cp .env.example .env

    Edit .env.local with your configuration (see Environment Variables below).

  3. Run database migrations:

    pnpm migration:run-local

  4. Run development server:

    pnpm start:dev

Production

  • Build: pnpm build
  • Start: pnpm start:prod

Session concurrency tests

pnpm test runs the unit and HTTP tests. To also run the PostgreSQL session race regression tests, provide SESSION_TEST_DATABASE_URL pointing at a test PostgreSQL database. The suite creates and drops its own randomly named schema; it needs permission to create schemas. CI runs these tests against PostgreSQL 17.

SESSION_TEST_DATABASE_URL=postgresql://postgres:session-tests@localhost:55439/postgres pnpm test --runInBand

The tests overlap rotation with logout, logout-all and reuse detection, and verify that concurrent refreshes share one successor and failed rotations roll back. They also overlap an old GitHub grant check with a new login to ensure the new session survives. They are skipped when the test database URL is absent.

Environment Variables

Database (Required)

  • DB_HOST - PostgreSQL host
  • DB_PORT - PostgreSQL port
  • DB_USER - Database username
  • DB_PASSWORD - Database password
  • DB_NAME - Database name
  • DB_SCHEMA - Database schema
  • DB_URL - Alternative database connection URL overwrites the other database connection variables
  • DB_SSL_REQUIRED - Enable SSL connection (true/false)

External Services (Required)

  • RABBITMQ_URL - RabbitMQ connection URL
  • API_SECRET_ENCRYPTION_KEY - Key for encrypting sensitive data

Optional

  • PORT - Server port (default: 4000)
  • NODE_ENV - Environment (development/production)

Database Management

Migrations

  • Generate: pnpm migration:generate migration_name Compares your current TypeScript entities with the database and automatically generates the necessary SQL (e.g., adding or removing columns). Use this for most schema changes.
  • Create: pnpm migration:create migration_name Creates an empty migration template. Use this only for manual SQL changes (e.g., seeding data, creating complex views, or custom indexes) that TypeORM cannot detect automatically.
  • Run: pnpm migration:run-local (local) / pnpm migration:run (production)
  • Revert: pnpm migration:revert-local (local) / pnpm migration:revert (production)

Seeding

  • Seed Users and Teams: pnpm seed:users <eventId> Generates 90 users and 30 teams (3 members each) and assigns them to the specified event. This is useful for testing group phases and bracket logic. Each seeded team gets a simulated repository named sim-<teamId> in READY state, so no repository is ever created for it. When NODE_ENV is development, github-service reports permission, lock, unlock and delete operations on these repositories as successful without calling GitHub, so closing submissions locks the seeded teams and the tournament can start. RANDOM_GAME_RESULTS=true is required, because real matches cannot clone sim-* repositories. Tilt sets both.

Backfilling 42 campuses

  • Backfill campus names: pnpm backfill:campus [--apply] [--all] Looks up every linked 42 account without a campus on the 42 intra API (/v2/users/:id) and stores its primary campus. Without --apply it only prints what would change; --all also re-checks accounts that already have a campus. Set the DB_* variables of the target database and read the token without echoing it:

    read -rs FORTYTWO_ACCESS_TOKEN && export FORTYTWO_ACCESS_TOKEN
pnpm backfill:campus          # dry run
pnpm backfill:campus --apply

    An application token works: curl -X POST https://api.intra.42.fr/oauth/token -d grant_type=client_credentials -d client_id=<uid> -d client_secret=<secret>. Requests are spaced to stay within the default limit of 2 per second, and the run stops at once if the token is rejected.

API Documentation

When running in development mode, Swagger documentation is available at: http://localhost:4000/api

Architecture

This service runs as both:

  • REST API - HTTP endpoints for frontend communication
  • Microservice - RabbitMQ message consumer for:
    • game_results - Match result processing
    • github-service-results - GitHub operation results

Environment Variables

GitHub OAuth (Required)

  1. Go to GitHub → Settings → Developer settings → OAuth Apps
  2. Register a new OAuth app
  3. Set Authorization callback URL: http://localhost:4000/auth/github/callback
  4. Add Client ID and Secret to .env.local

42 School OAuth (Optional)

For testing account linking functionality:

  1. Go to 42 School → Settings → API → Applications
  2. Create a new application
  3. Set Redirect URI: http://localhost:4000/auth/42/callback
  4. Add Client ID and Client Secret to .env.local