FlashSale Service

This repository contains a Go-based flash sale service. Every hour, a new sale of 10,000 items begins. Users can “checkout” (reserve) items and then “purchase” (buy) them using a unique code. The service uses Redis for fast in-memory operations and PostgreSQL for persistent storage.

⸻

Table of Contents

1. Features
2. Prerequisites
3. Setup & Build • Using Docker Compose
4. Configuration
5. Run Service
6. API Endpoints
7. Testing & Load Tests
8. Cleanup
9. Notes & Tips

⸻

Features • Hourly flash sale with 10,000 unique items. • Each user limited to 10 items per sale. • Unique reservation code generation. • Redis-backed atomic operations (Lua script) to prevent overselling. • PostgreSQL for persistent sale, item, and checkout records. • Automatic recovery/resume on service restart.

⸻

Prerequisites • Docker (>= 20.10) & Docker Compose (>= 1.27)

⸻

Setup & Build

Using Docker Compose

1. Clone this repository:

git clone <repository_url> cd <repo_folder>

2.	Ensure files docker-compose.yml, Dockerfile, and init.sql are present.
3.	Build and start all services:

docker-compose up --build

This will create three services: db (PostgreSQL), redis, and app.

4.	Verify the service is running:

curl http://localhost:8080/health

Should return:

{"status":"ok"}

⸻

Configuration

All configuration is via environment variables (with defaults shown):

Variable Default Description POSTGRES_HOST “postgres” PostgreSQL host (DNS name or IP) POSTGRES_PORT “5432” PostgreSQL port POSTGRES_USER “postgres” PostgreSQL user POSTGRES_PASSWORD “postgres” PostgreSQL password POSTGRES_DB “flashsale_db” PostgreSQL database name REDIS_ADDR “redis:6379” Redis address (host:port) REDIS_DB “0” Redis database index HTTP_PORT “8080” Port for the HTTP server MAX_PER_USER “10” Maximum items per user per sale SALE_GRACE_SEC “60” Extra seconds past the hour for code expiration

⸻

Run Service

After starting with Docker Compose, the service listens on http://localhost:8080.

⸻

API Endpoints

1. Health Check • Endpoint: /health • Method: GET • Response: 200 OK, JSON { "status": "ok" }

2. Checkout (Reserve an Item) • Endpoint: /checkout • Method: POST • Request Body (JSON):

{"user_id":"alice","item_id":123}

•	Responses:
•	200 OK – returns { "code": "<32-char-hex>" }.
•	403 Forbidden – user limit exceeded.
•	409 Conflict – item unavailable.
•	400 Bad Request – invalid JSON or missing fields.
•	500 Internal Server Error – unexpected error.

3. Purchase (Finalize Sale) • Endpoint: /purchase • Method: POST • Request Body (JSON):

{"code":"39fcc244e0f44fa20fd6289b171acdc3"}

•	Responses:
•	200 OK – returns

{"status":"ok","user_id":"alice","item_id":123,"sale_id":"2025060614"}

•	403 Forbidden – code from past sale.
•	404 Not Found – invalid or already purchased code.
•	400 Bad Request – invalid JSON or missing code.
•	500 Internal Server Error – unexpected error.

⸻

We include a Go-based load test harness loadtests.go with three predefined modes: full, ddos, and sim. Only the -mode flag is required.

1. Build the load test tool:

   go mod download
   go build -o loadtests loadtests.go

2. Run full mode (checkout + purchase flow):

   ./loadtests -mode=full

   • Performs a sequence of checkout requests, collects all reservation codes, then runs purchase requests for those codes.

3. Run ddos mode (purchase-only flood):

   ./loadtests -mode=ddos

   • Repeatedly sends purchase requests using codes from the built-in store (expects codes.txt present).

4. Run sim mode (mixed simulation):

   ./loadtests -mode=sim

   • Alternates checkout and purchase calls across a range of users and items to simulate real-world traffic.

Results will display total requests, success rate, latencies, and error breakdown.