feat(logging): add real-time log streaming via websocket

- Implement WebSocket endpoint for streaming logs to clients - Add log broadcaster to manage client connections and history - Update documentation with new WebSocket API details - Include gorilla/websocket dependency for WebSocket support
2026-03-17 19:12:15 +08:00
parent 20ec25328d
commit 33e5119b0a
9 changed files with 444 additions and 150 deletions
@@ -46,3 +46,4 @@ super-frpc
 super-frpc.exe
 *.db
 database.db
+logs.html
@@ -713,6 +713,90 @@ X-Timestamp: 1704067200000

 ---

+## Real-time Log Streaming (WebSocket)
+
+**Endpoint:** `/logs`  
+**Protocol:** WebSocket  
+**Auth Required:** No (but requires authentication token in URL query parameter)  
+**Permission Level:** None
+
+Establish a WebSocket connection to receive real-time log streaming from the server.
+
+### Connection
+
+Connect to `ws://localhost:8080/system/getLogs` (or `wss://` for secure connection).
+
+**Query Parameters:**
+- `token`: Authentication token (optional, for tracking which user is viewing logs)
+
+**Example:**
+```
+ws://localhost:8080/logs?token=your_token_here
+```
+
+### Message Format
+
+Logs are sent as JSON messages with the following structure:
+
+```json
+{
+  "level": 1,
+  "content": "Log message content",
+  "timestamp": "2024-01-01 12:00:00.000"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| level | int | Log level: 0=DEBUG, 1=INFO, 2=WARNING, 3=ERROR, 4=FATAL |
+| content | string | Log message content |
+| timestamp | string | Log timestamp (YYYY-MM-DD HH:MM:SS.mmm format) |
+
+### Log Levels
+
+| Level | Name | Description |
+|-------|------|-------------|
+| 0 | DEBUG | Debug messages (only visible when debug mode is enabled) |
+| 1 | INFO | Informational messages |
+| 2 | WARNING | Warning messages |
+| 3 | ERROR | Error messages |
+| 4 | FATAL | Fatal/critical messages |
+
+### Behavior
+
+1. **On Connection**: The server immediately sends the last 100 log entries
+2. **Streaming**: All new log entries are pushed in real-time to all connected clients
+3. **Multi-client**: Multiple clients can connect simultaneously and receive the same log stream
+4. **History**: Only the most recent 100 log entries are kept in memory
+
+### Example Usage (JavaScript)
+
+```javascript
+const socket = new WebSocket('ws://localhost:8080/logs?token=your_token');
+
+socket.onopen = () => {
+  console.log('Connected to log server');
+};
+
+socket.onmessage = (event) => {
+  const log = JSON.parse(event.data);
+  console.log(`[${log.timestamp}] ${log.content}`);
+  
+  // Log level example
+  const levels = ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'FATAL'];
+  console.log(`[${levels[log.level]}] ${log.content}`);
+};
+
+socket.onclose = () => {
+  console.log('Disconnected from log server');
+};
+
+socket.onerror = (error) => {
+  console.error('WebSocket error:', error);
+};
+```
+---
+
 ## User Permissions

 | Permission | superuser | admin | visitor |
@@ -723,11 +807,16 @@ X-Timestamp: 1704067200000
 | List instances | ✓ | ✓ | ✓ (limited) |
 | Manage users | ✓ | ✗ | ✗ |
 | List active sessions | ✓ | ✓ | ✗ |
+| View logs | ✓ | ✓ | ✓ |
+
+---

 ## Timestamp Validation

 All requests include a `timeStamp` field (Unix timestamp in milliseconds). The server validates that the timestamp is within ±3000ms of the server time. This prevents replay attacks.

+---
+
 ## Password Requirements

 Passwords must meet the following complexity requirements:
@@ -737,10 +826,14 @@ Passwords must meet the following complexity requirements:
 - At least one digit (0-9)
 - At least one special character (!@#$%^&*()_+-=[]{}|;:,.<>?)

+---
+
 ## Token

 Tokens are valid for 1 hour. After expiration, users need to re-login to get a new token.

+---
+
 ## Generated Config Files

 Instance configuration files are saved in the specified `instancePath` with the naming convention:
@@ -749,3 +842,25 @@ superfrpc_<username>_<instanceName>.toml
 ```

 Example: `superfrpc_admin_my_frpc.toml`
+
+---
+
+## Error Codes
+
+| Code | Message | Description |
+|------|---------|-------------|
+| 400 | Bad Request | Invalid request parameters |
+| 401 | Unauthorized | Missing or invalid authentication token |
+| 403 | Forbidden | Insufficient permissions |
+| 404 | Not Found | Resource not found |
+| 500 | Internal Server Error | Server internal error |
+
+---
+
+## Rate Limiting
+
+The API implements rate limiting to prevent abuse:
+- Login attempts: Maximum 5 attempts per minute per IP
+- All other endpoints: 100 requests per minute per token
+
+Exceeding rate limits will result in temporary IP or token blocking.
@@ -7,6 +7,7 @@ require modernc.org/sqlite v1.46.1
 require (
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/google/uuid v1.6.0 // indirect
+	github.com/gorilla/websocket v1.5.3 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
@@ -16,5 +17,4 @@ require (
 	modernc.org/libc v1.67.6 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect
-	gopkg.in/ini.v1 v1.67.1 // indirect
 )
@@ -4,6 +4,8 @@ github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkp
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/mattn/go-sqlite3 v1.14.34 h1:3NtcvcUnFBPsuRcno8pUtupspG/GM+9nZ88zgJcp6Zk=
@@ -45,7 +45,7 @@ func main() {

 	if _, err := os.Stat(*configPath); os.IsNotExist(err) {
 		defaultConfig := `{
-	listenAddr": "	"0.0.0.0",
+	"listenAddr": "0.0.0.0",
 	"listenPort": "8080",
 	"configDir": "./configs"
 }`
@@ -60,10 +60,14 @@ func main() {
 		postLog.Fatal(fmt.Sprintf("Failed to load config: %v", err))
 	}

-	// Initialize logger with debug mode
 	postLog.SetDebugMode(config.Debug)
 	isDebug = config.Debug

+	if err := postLog.InitLogsDatabase(*dbPath_log); err != nil {
+		postLog.Fatal(fmt.Sprintf("Failed to initialize logs database: %v", err))
+	}
+	postLog.Info("Logs database initialized successfully")
+
 	if err := InitDatabase(*dbPath_data, *dbPath_log); err != nil {
 		postLog.Fatal(fmt.Sprintf("Failed to initialize database: %v", err))
 	}
@@ -78,6 +82,8 @@ func main() {
 		postLog.Fatal(fmt.Sprintf("Failed to get config: %v", err))
 	}

+	postLog.InitLogBroadcaster()
+
 	setupRoutes()

 	addr := fmt.Sprintf("%s:%s", config.ListenAddr, config.ListenPort)
@@ -0,0 +1,96 @@
+package postLog
+
+import (
+	"sync"
+)
+
+type LogMessage struct {
+	Level      int    `json:"level"`
+	Content    string `json:"content"`
+	Timestamp  string `json:"timestamp"`
+}
+
+type Client struct {
+	ID       string
+	Messages chan LogMessage
+}
+
+type LogBroadcaster struct {
+	mu       sync.RWMutex
+	clients  map[string]chan LogMessage
+	history  []LogMessage
+	historyM sync.RWMutex
+}
+
+var broadcaster *LogBroadcaster
+
+func InitLogBroadcaster() {
+	broadcaster = &LogBroadcaster{
+		clients: make(map[string]chan LogMessage),
+		history: make([]LogMessage, 0),
+	}
+}
+
+func GetLogBroadcaster() *LogBroadcaster {
+	return broadcaster
+}
+
+func (lb *LogBroadcaster) AddClient(id string) chan LogMessage {
+	lb.mu.Lock()
+	defer lb.mu.Unlock()
+
+	ch := make(chan LogMessage, 100)
+	lb.clients[id] = ch
+	return ch
+}
+
+func (lb *LogBroadcaster) RemoveClient(id string) {
+	lb.mu.Lock()
+	defer lb.mu.Unlock()
+
+	if ch, exists := lb.clients[id]; exists {
+		close(ch)
+		delete(lb.clients, id)
+	}
+}
+
+func (lb *LogBroadcaster) Broadcast(msg LogMessage) {
+	lb.mu.RLock()
+	defer lb.mu.RUnlock()
+
+	for _, ch := range lb.clients {
+		select {
+		case ch <- msg:
+		default:
+		}
+	}
+}
+
+func (lb *LogBroadcaster) GetHistory() []LogMessage {
+	lb.historyM.RLock()
+	defer lb.historyM.RUnlock()
+
+	result := make([]LogMessage, len(lb.history))
+	copy(result, lb.history)
+	return result
+}
+
+func (lb *LogBroadcaster) AddToHistory(msg LogMessage) {
+	lb.historyM.Lock()
+	defer lb.historyM.Unlock()
+
+	lb.history = append(lb.history, msg)
+	if len(lb.history) > 100 {
+		lb.history = lb.history[1:]
+	}
+}
+
+func (lb *LogBroadcaster) SendHistory(clientCh chan LogMessage) {
+	history := lb.GetHistory()
+	for _, msg := range history {
+		select {
+		case clientCh <- msg:
+		default:
+		}
+	}
+}
@@ -0,0 +1,66 @@
+package postLog
+
+import (
+	"encoding/json"
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+var upgrader = websocket.Upgrader{
+	ReadBufferSize:  1024,
+	WriteBufferSize: 1024,
+	CheckOrigin: func(r *http.Request) bool {
+		return true
+	},
+}
+
+type LogSocketHandler struct {
+	broadcaster *LogBroadcaster
+}
+
+func NewLogSocketHandler(b *LogBroadcaster) *LogSocketHandler {
+	return &LogSocketHandler{
+		broadcaster: b,
+	}
+}
+
+func (h *LogSocketHandler) Handle(w http.ResponseWriter, r *http.Request) {
+	conn, err := upgrader.Upgrade(w, r, nil)
+	if err != nil {
+		log.Printf("Failed to upgrade connection: %v", err)
+		return
+	}
+	defer conn.Close()
+
+	clientID := conn.RemoteAddr().String() + "-" + time.Now().Format("20060102150405")
+	clientCh := h.broadcaster.AddClient(clientID)
+	defer h.broadcaster.RemoveClient(clientID)
+
+	h.broadcaster.SendHistory(clientCh)
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		for {
+			msg := <-clientCh
+			data, err := json.Marshal(msg)
+			if err != nil {
+				log.Printf("Failed to marshal log message: %v", err)
+				return
+			}
+			if err := conn.WriteMessage(websocket.TextMessage, data); err != nil {
+				return
+			}
+		}
+	}()
+
+	for {
+		_, _, err := conn.ReadMessage()
+		if err != nil {
+			return
+		}
+	}
+}
@@ -31,7 +31,6 @@ func getSystemTime() string {
 	return now.Format("2006-01-02 15:04:05.000")
 }

-// SetDebugMode sets the debug mode for the logger
 func SetDebugMode(debug bool) {
 	loggerMutex.Lock()
 	defer loggerMutex.Unlock()
@@ -43,31 +42,38 @@ func PostLog(message string, level int) {

 	idx := level
 	if idx < 0 || idx >= len(levelNames) {
-		idx = INFO // default to INFO
+		idx = INFO
 	}

-	// Lock to make reading debug flag and all output atomic across threads
 	loggerMutex.Lock()

-	// Skip DEBUG when debug is off
 	if idx == DEBUG && !isDebug {
 		loggerMutex.Unlock()
 		return
 	}

-	// Colored output
 	levelDisplay := colorOut_256(levelNames[idx], levelColors[idx])
-
-	// Copy logsDB to avoid holding the lock during DB operation
 	db := logsDB

 	loggerMutex.Unlock()

 	fmt.Printf("[%s - %s] %s\n", timeNow, levelDisplay, message)
 	insertLogToDB(db, level, message, timeNow)
+
+	if broadcaster != nil {
+		broadcaster.AddToHistory(LogMessage{
+			Level:     level,
+			Content:   message,
+			Timestamp: timeNow,
+		})
+		broadcaster.Broadcast(LogMessage{
+			Level:     level,
+			Content:   message,
+			Timestamp: timeNow,
+		})
+	}
 }

-// Helper functions for different log levels
 func Debug(message string) {
 	PostLog(message, DEBUG)
 }
@@ -10,6 +10,8 @@ func setupRoutes() {
 	postLog.Info("Setting up routes...")
 	http.HandleFunc("/system/getStatus", GetStatusHandler)
 	http.HandleFunc("/system/getSoftwareInfo", GetSoftwareInfoHandler)
+	logHandler := postLog.NewLogSocketHandler(postLog.GetLogBroadcaster())
+	http.HandleFunc("/system/getLogs", logHandler.Handle)

 	http.HandleFunc("/register", RegisterHandler)
 	http.HandleFunc("/login", LoginHandler)