# Assignment Specification: TCP Concurrent Multi-Player Tic-Tac-Toe Game Server (Java)

**Course:** Distributed Computing & Computer Systems  
**Evaluation Standard:** Concurrent Socket Systems Programming & RFC Framing  
**Module:** SiPro SocketArena™ & SecureProctor™  
**Language:** Java (SE 11+)  
**Author:** SiPro Technologies Systems Engineering  

---

## 1. Executive Summary & Objective

In modern distributed architectures, servers must concurrently handle hundreds or thousands of client connections without head-of-line blocking or resource starvation. 

In this laboratory assignment, students implement a **Concurrent Multi-Client TCP Game Server** and a **Networked Client** for a real-time, two-player **Tic-Tac-Toe** game over raw TCP/IP sockets in **Java**. 

Unlike single-threaded iterative servers that process requests sequentially, this server utilizes a **multi-threaded concurrent architecture**:
1. The **Master Listener Thread** accepts incoming connections on port `9099` using `ServerSocket`.
2. The **Matchmaker Module** uses Java thread synchronization (`synchronized` blocks) to pair waiting players into isolated matches.
3. For each paired match, a dedicated **Match Worker Thread** (`Thread` implementing `Runnable`) is spawned to handle board state progression, turn switching, and move validation independently without blocking other concurrent matches.

---

## 2. System Architecture & Concurrency Sequence

```mermaid
sequenceDiagram
    autonumber
    actor P1 as Player 1 (X)
    actor P2 as Player 2 (O)
    participant Master as Master Server (ServerSocket)
    participant Matchmaker as Matchmaker Queue (synchronized)
    participant Worker as Match Worker Thread (Thread N)

    P1->>Master: TCP SYN (Port 9099)
    Master-->>P1: TCP SYN-ACK
    P1->>Master: JOIN Alice
    Master->>Matchmaker: Enqueue Player 1 (Alice)
    Master-->>P1: WAIT Waiting for opponent...

    P2->>Master: TCP SYN (Port 9099)
    Master-->>P2: TCP SYN-ACK
    P2->>Master: JOIN Bob
    Master->>Matchmaker: Dequeue Player 1 + Pair with Bob
    Master->>Worker: Spawn new Thread(new MatchWorker(Alice, Bob))
    
    activate Worker
    Worker-->>P1: START X Bob
    Worker-->>P2: START O Alice
    Worker-->>P1: BOARD .........
    Worker-->>P2: BOARD .........
    Worker-->>P1: YOUR_TURN
    Worker-->>P2: OPPONENT_TURN

    P1->>Worker: MOVE 1 1 (Alice marks center)
    Worker-->>P1: BOARD ....X....
    Worker-->>P2: BOARD ....X....
    Worker-->>P1: OPPONENT_TURN
    Worker-->>P2: YOUR_TURN

    P2->>Worker: MOVE 0 0 (Bob marks top-left)
    Worker-->>P1: BOARD O...X....
    Worker-->>P2: BOARD O...X....
    Note over Worker: Moves continue until victory or draw
    Worker-->>P1: MATCH_OVER VICTORY Congratulations!
    Worker-->>P2: MATCH_OVER DEFEAT Player X won!
    deactivate Worker
```

---

## 3. Protocol Specification: RFC-SIPRO-TTT

Communication occurs via newline-delimited (`\n`) ASCII stream frames.

### Client to Server Messages:
| Command | Syntax | Description | Example |
| :--- | :--- | :--- | :--- |
| `JOIN` | `JOIN <player_name>` | Initial registration packet sent upon connection | `JOIN Alice` |
| `MOVE` | `MOVE <row> <col>` | Move submission (`row` 0..2, `col` 0..2) | `MOVE 1 1` |
| `QUIT` | `QUIT` | Gracefully forfeit and terminate session | `QUIT` |

### Server to Client Messages:
| Command | Syntax | Description | Example |
| :--- | :--- | :--- | :--- |
| `WAIT` | `WAIT <message>` | Informs player they are queued for matchmaking | `WAIT Waiting for an opponent...` |
| `START` | `START <X\|O> <opp_name>` | Signals game start and assigns player symbol | `START X Bob` |
| `BOARD` | `BOARD <9_char_string>` | Current 3x3 board (`.` or ` ` for empty, `X`, `O`) | `BOARD ....X....` |
| `YOUR_TURN` | `YOUR_TURN` | Directs client to prompt user and submit move | `YOUR_TURN` |
| `OPPONENT_TURN` | `OPPONENT_TURN` | Informs client that opponent is calculating move | `OPPONENT_TURN` |
| `INVALID_MOVE` | `INVALID_MOVE <reason>` | Rejects illegal move (occupied or out of bounds) | `INVALID_MOVE Cell occupied` |
| `MATCH_OVER` | `MATCH_OVER <STATUS> <details>` | Signals game end (`VICTORY`, `DEFEAT`, `DRAW`) | `MATCH_OVER VICTORY You won!` |

---

## 4. Fill-In-The-Blanks Breakdown & Evaluation Rubric (100 Marks)

### Section A: Server Implementation (`TicTacToeServer.java`) [50 Marks]
- **Blank 1 (5 Marks):** Master `ServerSocket` creation on port 9099.
- **Blank 2 (5 Marks):** Address reuse configuration (`setReuseAddress(true)`).
- **Blank 3 (5 Marks):** Socket binding to local host endpoint (`bind(new InetSocketAddress(PORT))`).
- **Blank 4 (5 Marks):** Listen queue depth validation (backlog 10).
- **Blank 5 (5 Marks):** Incoming connection accept loop (`serverSocket.accept()`).
- **Blank 6 (5 Marks):** Matchmaking queue synchronization (`synchronized(matchmakingLock)`).
- **Blank 7 (5 Marks):** Match worker thread instantiation (`new Thread(new MatchWorker(p1, p2))`).
- **Blank 8 (5 Marks):** Match worker thread launch (`matchThread.start()`).
- **Blank 9 (5 Marks):** Board state validation & winner verification (`checkWinner(board)`).
- **Blank 10 (5 Marks):** Graceful socket closure & stream teardown (`socket.close()`).

### Section B: Client Implementation (`TicTacToeClient.java`) [40 Marks]
- **Blank 1 (5 Marks):** TCP client stream `Socket` initialization.
- **Blank 2 (5 Marks):** Server connection handshake (`socket.connect(...)`).
- **Blank 3 (5 Marks):** `JOIN` packet serialization and transmission (`out.println("JOIN " + name)`).
- **Blank 4 (5 Marks):** Stream buffer reception (`in.readLine()`).
- **Blank 5 (5 Marks):** Server command dispatch (`WAIT`, `START`, `BOARD`, `YOUR_TURN`).
- **Blank 6 (5 Marks):** Move input validation & `MOVE` command framing.
- **Blank 7 (5 Marks):** ASCII 3x3 game board visualization (`renderBoard(boardStr)`).
- **Blank 8 (5 Marks):** Match termination handling and socket cleanup (`socket.close()`).

### Section C: Concurrency, Deadlock & Stress Testing [10 Marks]
- **Multi-Match Isolation (5 Marks):** Verified that 4+ concurrent players (2+ simultaneous matches) execute simultaneously without crosstalk or blocking.
- **Abnormal Disconnection Handling (5 Marks):** Verified that if Player 1 terminates abruptly, Player 2 receives `MATCH_OVER OPPONENT_QUIT` and server thread terminates without hanging sockets in `CLOSE_WAIT`.

---

## 5. Execution & Verification Instructions

### Terminal 1: Compile & Run the Concurrent Server
```bash
javac TicTacToeServer.java
java TicTacToeServer
```

### Terminal 2: Run Player 1 (Alice)
```bash
javac TicTacToeClient.java
java TicTacToeClient Alice
```

### Terminal 3: Run Player 2 (Bob)
```bash
java TicTacToeClient Bob
```