656 lines
15 KiB
Markdown
656 lines
15 KiB
Markdown
|
||
# 🚀 WebSocket API Service - Real-Time Communication
|
||
|
||
> **Modern WebSocket API service with advanced real-time communication, client management, and broadcasting capabilities**
|
||
|
||
## 📑 Daftar Isi
|
||
|
||
- [✨ Fitur Utama](#-fitur-utama)
|
||
- [🏗️ Arsitektur](#%EF%B8%8F-arsitektur)
|
||
- [⚡ Quick Start](#-quick-start)
|
||
- [🔐 Autentikasi](#-autentikasi)
|
||
- [📊 API Endpoints](#-api-endpoints)
|
||
- [🛠️ Development](#%EF%B8%8F-development)
|
||
- [🚀 Deployment](#-deployment)
|
||
- [📚 Dokumentasi](#-dokumentasi)
|
||
|
||
***
|
||
|
||
## ✨ Fitur Utama
|
||
|
||
### Real-Time Communication
|
||
|
||
- **🔄 WebSocket Server** - High-performance WebSocket server dengan auto-reconnect
|
||
- **🏠 Room Management** - Multi-room support untuk isolated communication
|
||
- **👥 Client Tracking** - Advanced client identification (IP-based, static ID, generated)
|
||
- **📡 Real-time Broadcasting** - Server-initiated broadcasts ke semua atau specific clients
|
||
- **💬 Direct Messaging** - Peer-to-peer messaging antar clients
|
||
- **🔄 Database Notifications** - PostgreSQL LISTEN/NOTIFY integration
|
||
|
||
### Advanced Features
|
||
|
||
- **📊 Connection Monitoring** - Real-time statistics dan health monitoring
|
||
- **🧹 Auto Cleanup** - Automatic cleanup untuk inactive connections
|
||
- **🔒 Secure Authentication** - JWT-based authentication untuk WebSocket connections
|
||
- **📈 Performance Metrics** - Built-in performance tracking dan analytics
|
||
- **🎯 Message Queue** - High-throughput message processing dengan worker pools
|
||
- **🔍 Activity Logging** - Comprehensive activity logging untuk debugging
|
||
|
||
### Developer Experience
|
||
|
||
- **🔥 Hot Reload** - Development dengan auto-restart
|
||
- **🐳 Docker Ready** - Easy deployment dengan Docker
|
||
- **⚡ Code Generator** - Buat handler dan model otomatis
|
||
- **🧪 Testing Suite** - Unit dan integration tests
|
||
- **📊 Health Monitoring** - Monitoring kesehatan aplikasi
|
||
|
||
***
|
||
|
||
## 🏗️ Arsitektur WebSocket
|
||
|
||
### WebSocket Architecture Layers
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ WebSocket Layer │ ← websocket.go, broadcast.go
|
||
├─────────────────────────────────────┤
|
||
│ Application Layer │ ← handlers/, middleware/
|
||
├─────────────────────────────────────┤
|
||
│ Domain Layer │ ← models/, services/
|
||
├─────────────────────────────────────┤
|
||
│ Infrastructure Layer │ ← database/, external APIs
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
### Core Components
|
||
|
||
```
|
||
api-service/
|
||
├── 📁 cmd/api/ # 🚪 WebSocket server entry point
|
||
├── 📁 internal/ # 🏠 Core WebSocket logic
|
||
│ ├── handlers/websocket/ # 🔄 WebSocket handlers & hub
|
||
│ ├── middleware/ # 🛡️ Auth & validation middleware
|
||
│ ├── models/ # 📊 Data structures & validation
|
||
│ ├── routes/ # 🛣️ API routing
|
||
│ ├── services/ # 💼 Business logic services
|
||
│ └── database/ # 💾 Database connections
|
||
├── 📁 docs/ # 📚 Swagger documentation
|
||
└── 📁 configs/ # ⚙️ Configuration files
|
||
```
|
||
|
||
### WebSocket Hub Architecture
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ Hub │ ← Central WebSocket manager
|
||
├─────────────────────────────────────┤
|
||
│ • Client Management │ ← Register/unregister clients
|
||
│ • Message Broadcasting │ ← Broadcast to clients/rooms
|
||
│ • Room Management │ ← Multi-room support
|
||
│ • Connection Monitoring │ ← Track active connections
|
||
│ • Database Notifications │ ← PostgreSQL LISTEN/NOTIFY
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
|
||
***
|
||
|
||
## ⚡ Quick Start
|
||
|
||
### 1️⃣ Setup Environment (2 menit)
|
||
|
||
```bash
|
||
# Clone repository
|
||
git clone <repository-url>
|
||
cd api-service
|
||
|
||
# Setup environment
|
||
cp .env.example .env
|
||
```
|
||
|
||
### 2️⃣ Pilih Method Setup
|
||
|
||
**🐳 Docker (Recommended)**
|
||
|
||
```bash
|
||
make docker-run
|
||
```
|
||
|
||
**🔧 Manual Setup**
|
||
|
||
```bash
|
||
# Install dependencies
|
||
go mod download
|
||
|
||
# Start server
|
||
go run cmd/api/main.go
|
||
```
|
||
|
||
### 3️⃣ Setup WebSocket Client
|
||
|
||
**Start Vue.js Client Example:**
|
||
|
||
```bash
|
||
cd examples/clientsocket
|
||
|
||
# Install dependencies
|
||
npm install
|
||
|
||
# Start development server
|
||
npm run dev
|
||
```
|
||
|
||
### 4️⃣ Verify Installation
|
||
|
||
| Service | URL | Status |
|
||
| :-- | :-- | :-- |
|
||
| **WebSocket API** | ws://localhost:8080/api/v1/ws | ✅ |
|
||
| **WebSocket Client** | http://localhost:3000 | 🌐 |
|
||
| **API Documentation** | http://localhost:8080/swagger/index.html | 📖 |
|
||
| **Health Check** | http://localhost:8080/api/sistem/health | 💚 |
|
||
|
||
|
||
***
|
||
|
||
## 🔐 Autentikasi
|
||
|
||
### Login \& Mendapatkan Token
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/auth/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"username": "admin",
|
||
"password": "password"
|
||
}'
|
||
```
|
||
|
||
**Response:**
|
||
|
||
```json
|
||
{
|
||
"access_token": "eyJhbGciOiJIUzI1NiIs...",
|
||
"expires_in": 3600,
|
||
"user": {
|
||
"id": "123",
|
||
"username": "admin",
|
||
"role": "admin"
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
### Menggunakan Token
|
||
|
||
```bash
|
||
curl -X GET http://localhost:8080/api/v1/products \
|
||
-H "Authorization: Bearer <your-token>"
|
||
```
|
||
|
||
|
||
### Demo Accounts
|
||
|
||
| Username | Password | Role | Akses |
|
||
| :-- | :-- | :-- | :-- |
|
||
| `admin` | `password` | Admin | Semua endpoint |
|
||
| `user` | `password` | User | Read-only |
|
||
|
||
|
||
***
|
||
|
||
## 📊 API Endpoints
|
||
|
||
### 🔄 WebSocket Endpoints
|
||
|
||
#### Main WebSocket Connection
|
||
|
||
| Protocol | Endpoint | Deskripsi |
|
||
| :-- | :-- | :-- |
|
||
| `WS` | `ws://localhost:8080/api/v1/ws` | WebSocket connection utama |
|
||
|
||
**Connection Parameters:**
|
||
|
||
```javascript
|
||
// Basic connection
|
||
const ws = new WebSocket('ws://localhost:8080/api/v1/ws');
|
||
```
|
||
|
||
#### WebSocket Management API
|
||
|
||
| Method | Endpoint | Deskripsi |
|
||
| :-- | :-- | :-- |
|
||
| `GET` | `/api/websocket/stats` | WebSocket connection statistics |
|
||
| `GET` | `/api/websocket/clients` | List all connected clients |
|
||
| `GET` | `/api/websocket/rooms` | List all active rooms |
|
||
| `POST` | `/api/websocket/broadcast` | Server-initiated broadcast |
|
||
| `POST` | `/api/websocket/broadcast/room/:room` | Broadcast to specific room |
|
||
| `POST` | `/api/websocket/send/:clientId` | Send message to specific client |
|
||
| `POST` | `/api/websocket/cleanup/inactive` | Cleanup inactive clients |
|
||
|
||
### 🌍 Public REST Endpoints
|
||
|
||
| Method | Endpoint | Deskripsi |
|
||
| :-- | :-- | :-- |
|
||
| `POST` | `/api/v1/auth/login` | Login pengguna |
|
||
| `POST` | `/api/v1/auth/register` | Registrasi pengguna baru |
|
||
| `GET` | `/api/sistem/health` | Status kesehatan API |
|
||
| `GET` | `/api/sistem/info` | System information |
|
||
|
||
### 🔒 Protected REST Endpoints
|
||
|
||
#### User Management
|
||
|
||
| Method | Endpoint | Deskripsi |
|
||
| :-- | :-- | :-- |
|
||
| `GET` | `/api/v1/auth/me` | Profile pengguna |
|
||
| `PUT` | `/api/v1/auth/me` | Update profile |
|
||
|
||
|
||
***
|
||
|
||
## 🛠️ Development
|
||
|
||
### Code Generation (30 detik)
|
||
|
||
**🎯 Generate CRUD Lengkap**
|
||
|
||
```bash
|
||
# Generate handler untuk entity baru
|
||
go run tools/general/generate-handler.go product get post put delete
|
||
|
||
# Generate dengan fitur advanced
|
||
go run tools/general/generate-handler.go orders get post put delete dynamic search stats
|
||
```
|
||
|
||
### Development Commands
|
||
|
||
```bash
|
||
# 🔥 Development dengan hot reload
|
||
make watch
|
||
|
||
# 🧪 Testing
|
||
make test # Unit tests
|
||
make itest # Integration tests
|
||
make test-all # Semua tests
|
||
|
||
# 📖 Update dokumentasi
|
||
make docs # Generate Swagger docs
|
||
|
||
# 🔍 Code quality
|
||
make lint # Linting
|
||
make format # Format code
|
||
```
|
||
|
||
|
||
### Environment Configuration
|
||
|
||
**📁 .env File:**
|
||
|
||
```bash
|
||
# Database
|
||
BLUEPRINT_DB_HOST=localhost
|
||
BLUEPRINT_DB_PORT=5432
|
||
BLUEPRINT_DB_USERNAME=postgres
|
||
BLUEPRINT_DB_PASSWORD=postgres
|
||
BLUEPRINT_DB_DATABASE=api_service
|
||
|
||
# JWT
|
||
JWT_SECRET=your-super-secret-key-change-in-production
|
||
|
||
# Application
|
||
APP_ENV=development
|
||
APP_PORT=8080
|
||
LOG_LEVEL=debug
|
||
```
|
||
|
||
|
||
***
|
||
|
||
## 🚀 Deployment
|
||
|
||
### 🐳 Docker Deployment
|
||
|
||
**Development:**
|
||
|
||
```bash
|
||
# Start semua services
|
||
make docker-run
|
||
|
||
# Stop services
|
||
make docker-down
|
||
|
||
# Rebuild dan restart
|
||
make docker-rebuild
|
||
```
|
||
|
||
**Production:**
|
||
|
||
```bash
|
||
# Build production image
|
||
docker build -t api-service:prod .
|
||
|
||
# Run production container
|
||
docker run -d \
|
||
--name api-service \
|
||
-p 8080:8080 \
|
||
--env-file .env.prod \
|
||
api-service:prod
|
||
```
|
||
|
||
|
||
### 🔧 Manual Deployment
|
||
|
||
```bash
|
||
# Build aplikasi
|
||
make build
|
||
|
||
# Run migrations
|
||
./scripts/migrate.sh up
|
||
|
||
# Start server
|
||
./bin/api-service
|
||
```
|
||
|
||
|
||
***
|
||
|
||
## 📚 Dokumentasi
|
||
|
||
### 📖 Interactive API Documentation
|
||
|
||
Kunjungi **Swagger UI** di: http://localhost:8080/swagger/index.html
|
||
|
||
**Cara menggunakan:**
|
||
|
||
1. 🔑 Login melalui `/auth/login` endpoint
|
||
2. 📋 Copy token dari response
|
||
3. 🔓 Klik tombol "Authorize" di Swagger
|
||
4. 📝 Masukkan: `Bearer <your-token>`
|
||
5. ✅ Test semua endpoint yang tersedia
|
||
|
||
### 🔄 WebSocket Client Examples
|
||
|
||
#### JavaScript WebSocket Client
|
||
|
||
**Basic Connection:**
|
||
|
||
```javascript
|
||
// Create WebSocket connection
|
||
const ws = new WebSocket('ws://localhost:8080/api/v1/ws');
|
||
|
||
// Connection opened
|
||
ws.onopen = function(event) {
|
||
console.log('Connected to WebSocket server');
|
||
};
|
||
|
||
// Listen for messages
|
||
ws.onmessage = function(event) {
|
||
const data = JSON.parse(event.data);
|
||
console.log('Message received:', data);
|
||
};
|
||
|
||
// Send a message
|
||
function sendMessage(message) {
|
||
ws.send(JSON.stringify({
|
||
type: 'broadcast',
|
||
message: message
|
||
}));
|
||
}
|
||
|
||
// Handle connection close
|
||
ws.onclose = function(event) {
|
||
console.log('Disconnected from WebSocket server');
|
||
};
|
||
```
|
||
|
||
#### Vue.js Component Example
|
||
|
||
```vue
|
||
<template>
|
||
<div class="websocket-chat">
|
||
<div class="messages" ref="messages">
|
||
<div v-for="message in messages" :key="message.id" class="message">
|
||
<strong>{{ message.client_id }}:</strong> {{ message.content }}
|
||
</div>
|
||
</div>
|
||
|
||
<div class="input-area">
|
||
<input
|
||
v-model="newMessage"
|
||
@keyup.enter="sendMessage"
|
||
placeholder="Type a message..."
|
||
>
|
||
<button @click="sendMessage">Send</button>
|
||
</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
name: 'WebSocketChat',
|
||
data() {
|
||
return {
|
||
ws: null,
|
||
messages: [],
|
||
newMessage: ''
|
||
};
|
||
},
|
||
mounted() {
|
||
this.connectWebSocket();
|
||
},
|
||
beforeUnmount() {
|
||
if (this.ws) {
|
||
this.ws.close();
|
||
}
|
||
},
|
||
methods: {
|
||
connectWebSocket() {
|
||
this.ws = new WebSocket('ws://localhost:8080/api/v1/ws');
|
||
|
||
this.ws.onopen = () => {
|
||
console.log('WebSocket connected');
|
||
};
|
||
|
||
this.ws.onmessage = (event) => {
|
||
const data = JSON.parse(event.data);
|
||
this.handleMessage(data);
|
||
};
|
||
|
||
this.ws.onclose = () => {
|
||
console.log('WebSocket disconnected');
|
||
// Auto-reconnect after 5 seconds
|
||
setTimeout(() => this.connectWebSocket(), 5000);
|
||
};
|
||
},
|
||
|
||
sendMessage() {
|
||
if (this.newMessage.trim() && this.ws) {
|
||
this.ws.send(JSON.stringify({
|
||
type: 'broadcast',
|
||
message: this.newMessage
|
||
}));
|
||
|
||
this.newMessage = '';
|
||
}
|
||
},
|
||
|
||
handleMessage(data) {
|
||
this.messages.push({
|
||
id: Date.now(),
|
||
client_id: data.client_id || 'server',
|
||
content: data.message
|
||
});
|
||
|
||
// Auto-scroll to bottom
|
||
this.$nextTick(() => {
|
||
this.$refs.messages.scrollTop = this.$refs.messages.scrollHeight;
|
||
});
|
||
}
|
||
}
|
||
};
|
||
</script>
|
||
```
|
||
|
||
### 🧪 Testing Examples
|
||
|
||
**WebSocket Testing with wscat:**
|
||
|
||
```bash
|
||
# Install wscat globally
|
||
npm install -g wscat
|
||
|
||
# Connect to WebSocket server
|
||
wscat -c ws://localhost:8080/api/v1/ws
|
||
|
||
# Send a message
|
||
{"type": "broadcast", "message": "Hello from wscat!"}
|
||
```
|
||
|
||
**cURL for REST endpoints:**
|
||
|
||
```bash
|
||
# Login
|
||
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"username":"admin","password":"password"}' | jq -r '.access_token')
|
||
|
||
# Get WebSocket statistics
|
||
curl http://localhost:8080/api/websocket/stats
|
||
|
||
# Broadcast message to all clients
|
||
curl -X POST http://localhost:8080/api/websocket/broadcast \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"type": "broadcast", "message": "Server broadcast message"}'
|
||
|
||
# Get system information
|
||
curl http://localhost:8080/api/sistem/info
|
||
|
||
# Health check
|
||
curl http://localhost:8080/api/sistem/health
|
||
```
|
||
|
||
**Response Examples:**
|
||
|
||
```json
|
||
{
|
||
"connected_clients": 5,
|
||
"databases": ["default"],
|
||
"database_health": "connected",
|
||
"timestamp": 1694325600
|
||
}
|
||
```
|
||
|
||
|
||
***
|
||
|
||
## 🚨 Troubleshooting
|
||
|
||
### Masalah Umum
|
||
|
||
**❌ Database Connection Error**
|
||
|
||
```bash
|
||
# Cek status PostgreSQL
|
||
make db-status
|
||
|
||
# Reset database
|
||
make db-reset
|
||
|
||
# Check logs
|
||
make logs-db
|
||
```
|
||
|
||
**❌ Generate Handler Gagal**
|
||
|
||
- ✅ Pastikan berada di root project
|
||
- ✅ Cek permission write di folder `internal/`
|
||
- ✅ Verifikasi file `internal/routes/v1/routes.go` exists
|
||
|
||
**❌ Token Invalid/Expired**
|
||
|
||
- 🔄 Login ulang untuk mendapatkan token baru
|
||
- ⏰ Token expire dalam 1 jam (configurable)
|
||
- 📝 Format harus: `Bearer <token>`
|
||
|
||
**❌ Import Error saat Generate**
|
||
|
||
- 🧹 Jalankan: `go mod tidy`
|
||
- 🔄 Restart development server
|
||
- 📝 Cek format import di generated files
|
||
|
||
|
||
### Debug Mode
|
||
|
||
```bash
|
||
# Enable debug logging
|
||
export LOG_LEVEL=debug
|
||
|
||
# Run dengan verbose output
|
||
make run-debug
|
||
|
||
# Monitor performance
|
||
make monitor
|
||
```
|
||
|
||
|
||
***
|
||
|
||
## 🎯 Next Steps
|
||
|
||
### 📋 WebSocket Development Roadmap
|
||
|
||
- [x] ✅ **Setup environment selesai**
|
||
- [x] ✅ **Implementasi WebSocket server**
|
||
- [x] ✅ **Setup Vue.js client example**
|
||
- [x] ✅ **Test WebSocket functionality**
|
||
- [ ] 🔄 **Implementasi room management**
|
||
- [ ] 🔄 **Tambahkan authentication ke WebSocket**
|
||
- [ ] 🔄 **Implementasi database notifications**
|
||
- [ ] 🔄 **Tambahkan unit tests untuk WebSocket**
|
||
- [ ] 🔄 **Setup monitoring dan observability**
|
||
- [ ] 🔄 **Deploy ke production**
|
||
|
||
### 🚀 Advanced WebSocket Features
|
||
|
||
- **🔄 Database Integration** - PostgreSQL LISTEN/NOTIFY
|
||
- **📊 Real-time Analytics** - Connection metrics dan monitoring
|
||
- **🔒 Enhanced Security** - Rate limiting, CORS, authentication
|
||
- **📈 Performance Optimization** - Connection pooling, message queuing
|
||
- **🏠 Multi-room Support** - Advanced room management
|
||
- **📱 Mobile SDK Integration** - React Native, Flutter support
|
||
- **🌐 Multi-protocol Support** - MQTT, Server-Sent Events
|
||
- **📡 Load Balancing** - Horizontal scaling untuk WebSocket
|
||
|
||
### 🛠️ Immediate Next Steps
|
||
|
||
1. **Test WebSocket Connection**
|
||
```bash
|
||
# Start the server
|
||
go run cmd/api/main.go
|
||
|
||
# Test with wscat
|
||
wscat -c ws://localhost:8080/api/v1/ws
|
||
```
|
||
|
||
2. **Try Vue.js Client Example**
|
||
```bash
|
||
cd examples/clientsocket
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
3. **Explore WebSocket Features**
|
||
- Join/leave rooms
|
||
- Send broadcast messages
|
||
- Direct messaging between clients
|
||
- Monitor connection statistics
|
||
|
||
***
|
||
|
||
**⚡ Total setup time: 5 menit | 🔄 WebSocket ready: Langsung test | 🌐 Client example: Vue.js included**
|
||
|
||
> **💡 Pro Tip:** Gunakan `make help` untuk melihat semua command yang tersedia
|
||
|
||
***
|
||
|