Skip to content
@VAST-GAME

V.A.S.T.

Welcome to the V.A.S.T. Coding Hackathon hosted by the Academic Association of Mathematics & Computer Science of University of Isfahan (A.M.C.S.U.I.)! 🎓
README.md

🚀 V.A.S.T. Event Coding Hackathon 👨🏻‍💻

V.A.S.T. Hackathon

📑 Table of Contents

🌟 Overview

Welcome to the V.A.S.T. Coding Hackathon hosted by the Academic Association of Mathematics & Computer Science of University of Isfahan (A.M.C.S.U.I.) ! 🎓

In this exciting challenge, teams of up to 4 participants will design, develop, and deploy a robust API using any programming language or framework of their choice. 💻

🎯 Project Goals

  • Create a secure 🔒 and efficient ⚡ API
  • Implement proper authentication
  • Handle rate limiting and security measures
  • Dockerize the application 🐳
  • Pass all provided test cases 🧪

🏆 Evaluation Criteria

Your API's logic and performance will be evaluated based on:

  • Test case pass rate
  • Code quality and organization
  • Security implementation
  • Error handling
  • Documentation quality

📁 Project Structure

vast-game/
├── src/           # Source code
├── test/          # Test cases
├── runner.sh      # Test runner script
└── setup.sh       # Setup script

🌐 API Endpoints

Endpoint Method Description Auth Required Rate Limit
/login POST User authentication ❌ 4/min
/register POST New user registration ❌ 4/min
/logout POST User logout ✅ 4/min
/protected GET Protected resource ✅ 4/min
/forget-password POST Password recovery ❌ 4/min
/profile GET User profile ✅ 4/min

📚 API Documentation

Authentication Flow

  1. Register a new user
  2. Login to get JWT token
  3. Use token for protected routes
  4. Logout to invalidate token

Login User 🧩

POST /login

Headers

Content-Type: application/json

Body

{
  "email": "user@example.com",
  "password": "StrongPass123!"
}

Parameters

Name Type In Description
email string body User's email address
password string body User's password

Responses

Code Description Response Body Example
200 Success {"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "message": "Login successful"}
400 Bad Request {"error": "Invalid email format"}
401 Unauthorized {"error": "Invalid credentials"}
429 Too Many Requests {"error": "Rate limit exceeded"}

Test Requirements:

  • Email validation (must be valid email format)
  • Password validation (min 8 characters, special chars, numbers, uppercase)
  • Email existence check
  • Password correctness verification
  • Rate limit: 4 requests per minute

Register User 🧩

POST /register

Headers

Content-Type: application/json

Body

{
  "email": "user@example.com",
  "password": "StrongPass123!"
}

Parameters

Name Type In Description
email string body User's email address
password string body User's password

Responses

Code Description Response Body Example
201 Created {"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "message": "Registration successful"}
400 Bad Request {"error": "Invalid email format"}
409 Conflict {"error": "Email already exists"}

Test Requirements:

  • Email validation (must be valid email format)
  • Password validation (min 8 characters, special chars, numbers, uppercase)
  • Email uniqueness check
  • Rate limit: 4 requests per minute

Protected Routes 🔑

Logout User 🧩

POST /logout

Headers

Authorization: Bearer <token>

Responses

Code Description Response Body Example
200 Success {"message": "Logged out successfully"}
401 Unauthorized {"error": "Invalid token"}

Test Requirements:

  • Token validation
  • Token invalidation after logout
  • Rate limit: 4 requests per minute

Get Protected Resource 🧩

GET /protected

Headers

Authorization: Bearer <token>

Responses

Code Description Response Body Example
200 Success {"message": "This is a protected route", "data": {}}
401 Unauthorized {"error": "Invalid token"}

Test Requirements:

  • Token validation
  • Token expiration handling
  • Rate limit: 4 requests per minute

Get User Profile 🧩

GET /profile

Headers

Authorization: Bearer <token>

Responses

Code Description Response Body Example
200 Success {"email": "user@example.com", "profile": {}}
401 Unauthorized {"error": "Invalid token"}

Test Requirements:

  • Token validation
  • User data retrieval
  • Rate limit: 4 requests per minute

Forget Password Reset 🧩

POST /forget-password

Headers

Content-Type: application/json

Body

{
  "email": "user@example.com"
}

Parameters

Name Type In Description
email string body User's email address

Responses

Code Description Response Body Example
200 Success {"message": "Password reset email sent"}
400 Bad Request {"error": "Invalid email format"}
429 Too Many Requests {"error": "Rate limit exceeded"}

Test Requirements:

  • Email validation (must be valid email format)
  • Email existence check
  • Rate limit: 4 requests per minute
  • Should not reveal if email exists in the system
  • Should send password reset email if email exists

🧪 Testing

Getting Started with Tests

  1. Download NodeJs
  2. Clone the repository 
    cd test
  3. Install dependencies: 
    npm install
  4. Run the tests: 
    npm test

Test Categories

  1. Authentication Tests (100 points)

    • Registration Tests (25 points)
    • Login Tests (25 points)
    • Protected Route Tests (15 points)
    • Logout Tests (15 points)
    • Password Reset Tests (20 points)

  2. Security Tests

    • Rate limiting
    • Token validation
    • Password strength
    • Input validation

Mock Data

{
  "test_user": {
    "email": "test@example.com",
    "password": "Test123!@#"
  },
  "test_tokens": {
    "valid": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expired": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "invalid": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

📋 Grading Criteria

Points Distribution

  • Authentication (100 points)
    • Registration: 25 points
    • Login: 25 points
    • Protected Routes: 15 points
    • Logout: 15 points
    • Password Reset: 20 points

Evaluation Factors

  • Test case pass rate
  • Code quality and organization
  • Security implementation
  • Error handling
  • Documentation quality
  • API design and structure

🚀 Getting Started

1. Setup Environment 🛠️

First, ensure you have the necessary tools installed:

  • Node.js (v14 or higher)
  • Docker (for containerization)
  • Git (for version control)
  • A code editor (we recommend VS Code)

Then run the setup script:

./setup.sh

2. Run Tests 🧪

To verify your environment is working correctly:

./runner.sh

3. Development Guide 💻

Choose Your Stack

Select your preferred programming language and framework. Here are some recommended options:

  1. API Implementation

    • Implement all required endpoints as specified in the API Documentation
    • Follow RESTful API best practices
    • Use proper HTTP status codes
    • Implement comprehensive error handling

  2. Security Measures 🔒

    • Implement JWT authentication
    • Add rate limiting (4 requests/minute)
    • Use secure password hashing (e.g., bcrypt)
    • Implement input validation
    • Add CORS protection
    • Use environment variables for sensitive data

  3. Testing Your Implementation

    • Write unit tests for your endpoints
    • Test edge cases and error scenarios
    • Verify rate limiting functionality
    • Test authentication flow
    • Run the provided test suite

4. Deployment Guide 🐳

Docker Setup

  1. Create Dockerfile Create a Dockerfile in your src directory:

    # Example for Node.js application
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .

EXPOSE 8000

CMD ["npm", "start"]

  2. Docker Requirements

    • Your service must be self-contained (no external dependencies)
    • No database or external service dependencies
    • Must run on port 8000 inside the container
    • Environment variables should be handled within the container
    • Use multi-stage builds for smaller image size

  3. Building and Running

    # Build the Docker image
docker build -t vast-api src/

# Run the container
docker run -p 8000:8000 vast-api

  4. Best Practices

    • Use .dockerignore to exclude unnecessary files
    • Implement health checks
    • Use non-root user in container
    • Optimize layer caching
    • Keep images small and secure

Deployment Checklist ✅

  • All endpoints implemented and tested
  • Rate limiting configured (4 requests/minute)
  • Authentication working correctly
  • Error handling implemented
  • Dockerfile created and tested
  • Container runs without external dependencies
  • Service accessible on port 8000
  • All tests passing

Resources 📚

🎗️ Contact & Support

Technical Support

👥 Contributors

Mohammad Mohagheghian Amin Masoudi

Pinned Loading

  1. .github .github Public

    1

Repositories

Showing 2 of 2 repositories

Top languages

Loading…

Most used topics

Loading…