fix: restructuring safe websocket client

README.md

@@ -1,2 +1,22 @@
 # safe-web-socket
 
+> A secure, production-ready WebSocket wrapper for Go with built-in validation, rate limiting, authentication, and connection management.
+
+## Overview
+
+`SafeWebSocket` is a Go library designed to simplify the creation of **secure, scalable, and resilient WebSocket servers**. Built on top of `gorilla/websocket`, it adds essential safety layers — including authentication, input validation, connection limits, rate limiting, and graceful shutdown — so you can focus on your application logic, not security pitfalls.
+
+Whether you’re building real-time dashboards, chat apps, or live data feeds, `SafeWebSocket` ensures your WebSocket endpoints are protected against common attacks (e.g., DoS, injection, unauthorized access).
+
+## Features
+- ✅ **Graceful Shutdown & Cleanup**
+- ✅ **Automatic Reconnection Handling (Client-side helpers)**
+- ✅ **WebSocket Ping/Pong Health Checks**
+
+## Installation
+
+```bash
+go get git.neurocipta.com/rogerferdinan/safe-web-socket
+```
+
+> Requires Go 1.24+

go.mod

@@ -3,3 +3,5 @@ module git.neurocipta.com/rogerferdinan/safe-web-socket
 go 1.24.5
 
 require github.com/gorilla/websocket v1.5.3
+
+require git.neurocipta.com/rogerferdinan/custom-rwmutex v1.0.0 // indirect

go.sum

@@ -1,2 +1,4 @@
+git.neurocipta.com/rogerferdinan/custom-rwmutex v1.0.0 h1:KnNc40SrYsg0cksIIcQy/ca6bunkGADQOs1u7O/E+iY=
+git.neurocipta.com/rogerferdinan/custom-rwmutex v1.0.0/go.mod h1:9DvvHc2UZhBwEs63NgO4IhiuHnBNtTuBkTJgiMnnCss=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=

internal/hub.go

@@ -11,7 +11,7 @@ import (
 const (
 	writeWait  = 10 * time.Second
 	pongWait   = 60 * time.Second
-	pingPeriod = 55 * time.Second
+	pingPeriod = 25 * time.Second
 )
 
 type Client struct {
@@ -19,7 +19,6 @@ type Client struct {
 	Send           chan []byte
 	SubscribedPath string
 	done           chan struct{}
-	mu             *CustomRwMutex
 }
 
 func NewClient(conn *websocket.Conn, subscribedPath string) *Client {
@@ -28,7 +27,6 @@ func NewClient(conn *websocket.Conn, subscribedPath string) *Client {
 		Send:           make(chan []byte, 64),
 		SubscribedPath: subscribedPath,
 		done:           make(chan struct{}),
-		mu:             NewCustomRwMutex(),
 	}
 }
 
@@ -37,8 +35,6 @@ type Hub struct {
 	Broadcast  chan []byte
 	Register   chan *Client
 	Unregister chan *Client
-	writeMu    *CustomRwMutex
-	readMu     *CustomRwMutex
 }
 
 func NewHub() *Hub {
@@ -47,7 +43,6 @@ func NewHub() *Hub {
 		Register:   make(chan *Client),
 		Unregister: make(chan *Client),
 		Clients:    make(map[*Client]bool),
-		writeMu:    NewCustomRwMutex(),
 	}
 }
 
@@ -63,6 +58,7 @@ func (h *Hub) Run() {
 					delete(h.Clients, c)
 					close(c.Send)
 				}
+				log.Println("Client Unregistered")
 			case message := <-h.Broadcast:
 				for client := range h.Clients {
 					select {
@@ -99,7 +95,7 @@ func WritePump(c *Client, h *Hub) {
 			}
 		case <-pingTicker.C:
 			c.Conn.SetWriteDeadline(time.Now().Add(writeWait))
-			if err := c.Conn.WriteMessage(websocket.PingMessage, nil); err != nil {
+			if err := c.Conn.WriteMessage(websocket.PingMessage, []byte{}); err != nil {
 				return
 			}
 		}
@@ -122,7 +118,7 @@ func ReadPump(c *Client, h *Hub) {
 	for {
 		messageType, message, err := c.Conn.ReadMessage()
 		if err != nil {
-			if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseAbnormalClosure) {
+			if !websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseAbnormalClosure) {
 				log.Printf("WebSocket error: %v", err)
 			}
 			break

internal/mutex.go

@@ -1,33 +0,0 @@
-package internal
-
-import (
-	"sync"
-)
-
-type CustomRwMutex struct {
-	mu *sync.RWMutex
-}
-
-func NewCustomRwMutex() *CustomRwMutex {
-	return &CustomRwMutex{
-		mu: &sync.RWMutex{},
-	}
-}
-
-func (rwMu *CustomRwMutex) WriteHandler(fn func() error) error {
-	rwMu.mu.Lock()
-	defer rwMu.mu.Unlock()
-	if err := fn(); err != nil {
-		return err
-	}
-	return nil
-}
-
-func (rwMu *CustomRwMutex) ReadHandler(fn func() error) error {
-	rwMu.mu.RLock()
-	defer rwMu.mu.RUnlock()
-	if err := fn(); err != nil {
-		return err
-	}
-	return nil
-}

v1/client/client.go

@@ -1,82 +1,316 @@
 package client
 
-// import (
-// 	"context"
-// 	"fmt"
-// 	"time"
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/url"
+	"strings"
+	"sync"
+	"time"
 
-// 	"git.neurocipta.com/rogerferdinan/safe-web-socket/internal"
-// 	"github.com/gorilla/websocket"
-// )
+	custom_rwmutex "git.neurocipta.com/rogerferdinan/custom-rwmutex"
+	"git.neurocipta.com/rogerferdinan/safe-web-socket/internal"
+	"github.com/gorilla/websocket"
+)
 
-// const (
-// 	pingPeriod = 30 * time.Second
-// )
+const (
+	pingPeriod = 10 * time.Second
+)
 
-// type SafeWebsocketClientBuilder struct {
-// 	baseHost *string `nil_checker:"required"`
-// 	basePort *uint16 `nil_checker:"required"`
-// }
+type SafeMap[K comparable, V any] struct {
+	m sync.Map
+}
 
-// func NewSafeWebsocketClientBuilder() *SafeWebsocketClientBuilder {
-// 	return &SafeWebsocketClientBuilder{}
-// }
+func NewSafeMap[K comparable, V any]() *SafeMap[K, V] {
+	return &SafeMap[K, V]{
+		m: sync.Map{},
+	}
+}
 
-// func (b *SafeWebsocketClientBuilder) BaseHost(host string) *SafeWebsocketClientBuilder {
-// 	b.baseHost = &host
-// 	return b
-// }
+func (sm *SafeMap[K, V]) Store(key K, value V) {
+	sm.m.Store(key, value)
+}
 
-// func (b *SafeWebsocketClientBuilder) BasePort(port uint16) *SafeWebsocketClientBuilder {
-// 	b.basePort = &port
-// 	return b
-// }
+func (sm *SafeMap[K, V]) Load(key K) (value V, ok bool) {
+	val, loaded := sm.m.Load(key)
+	if !loaded {
+		return *new(V), false
+	}
+	return val.(V), true
+}
 
-// func (b *SafeWebsocketClientBuilder) Build() (*SafeWebsocketClient, error) {
-// 	if err := internal.NilChecker(b); err != nil {
-// 		return nil, err
-// 	}
+func (sm *SafeMap[K, V]) Delete(key K) {
+	sm.m.Delete(key)
+}
 
-// 	ctx, cancel := context.WithCancel(context.Background())
+func (sm *SafeMap[K, V]) Range(f func(K, V) bool) {
+	sm.m.Range(func(key, value any) bool {
+		k, ok1 := key.(K)
+		v, ok2 := value.(V)
+		if !ok1 || !ok2 {
+			return true
+		}
+		return f(k, v)
+	})
+}
 
-// 	wsClient := SafeWebsocketClient{
-// 		baseHost:    b.baseHost,
-// 		basePort:    b.basePort,
-// 		ctx:         ctx,
-// 		cancel:      cancel,
-// 		reconnectCh: make(chan struct{}, 1),
-// 		isConnected: false,
-// 	}
+func (sm *SafeMap[K, V]) Len() int {
+	count := 0
+	sm.Range(func(_ K, _ V) bool {
+		count++
+		return true
+	})
+	return count
+}
 
-// 	if err := wsClient.connect(); err != nil {
-// 		cancel()
-// 		return nil, fmt.Errorf("failed to establish initial connection: %v", err)
-// 	}
+type SafeWebsocketClientBuilder struct {
+	baseHost *string `nil_checker:"required"`
+	basePort *uint16 `nil_checker:"required"`
+	path     *string
+	rawQuery *string
+	useTLS   *bool
+}
 
-// 	wsClient.startPingTicker()
-// 	wsClient.startReceiveHandler()
+func NewSafeWebsocketClientBuilder() *SafeWebsocketClientBuilder {
+	return &SafeWebsocketClientBuilder{}
+}
 
-// 	return &wsClient, nil
-// }
+func (b *SafeWebsocketClientBuilder) BaseHost(host string) *SafeWebsocketClientBuilder {
+	b.baseHost = &host
+	return b
+}
 
-// type SafeWebsocketClient struct {
-// 	baseHost    *string
-// 	basePort    *uint16
-// 	mu          *internal.CustomRwMutex
-// 	ctx         context.Context
-// 	cancel      context.CancelFunc
-// 	reconnectCh chan struct{}
-// 	isConnected bool
-// }
+func (b *SafeWebsocketClientBuilder) BasePort(port uint16) *SafeWebsocketClientBuilder {
+	b.basePort = &port
+	return b
+}
 
-// func (wsClient *SafeWebsocketClient) connect() error {
-// 	url := fmt.Sprintf("%s:%d", *wsClient.baseHost, *wsClient.basePort)
-// 	conn, _, err := websocket.DefaultDialer.Dial(url, nil)
-// 	if err != nil {
-// 		return fmt.Errorf("failed to connect to %s: %w", *wsClient.baseHost, err)
-// 	}
+func (b *SafeWebsocketClientBuilder) UseTLS(useTLS bool) *SafeWebsocketClientBuilder {
+	b.useTLS = &useTLS
+	return b
+}
 
-// 	conn.SetPingHandler(func(pingData string) error {
-// 		conn.WriteMessage(websocket.PongMessage, []byte(pingData))
-// 	})
-// }
+func (b *SafeWebsocketClientBuilder) Path(path string) *SafeWebsocketClientBuilder {
+	b.path = &path
+	return b
+}
+
+func (b *SafeWebsocketClientBuilder) RawQuery(rawQuery string) *SafeWebsocketClientBuilder {
+	b.rawQuery = &rawQuery
+	return b
+}
+
+func (b *SafeWebsocketClientBuilder) Build() (*SafeWebsocketClient, error) {
+	if err := internal.NilChecker(b); err != nil {
+		return nil, err
+	}
+
+	var useTLS bool
+	if b.useTLS != nil {
+		useTLS = *b.useTLS
+	}
+
+	wsClient := SafeWebsocketClient{
+		baseHost:    *b.baseHost,
+		basePort:    *b.basePort,
+		useTLS:      useTLS,
+		path:        b.path,
+		rawQuery:    b.rawQuery,
+		dataChannel: make(chan []byte, 1),
+		mu:          custom_rwmutex.NewCustomRwMutex(),
+		reconnectCh: make(chan struct{}, 1),
+		isConnected: false,
+		doneMap:     NewSafeMap[string, chan struct{}](),
+	}
+
+	go wsClient.reconnectHandler()
+
+	if err := wsClient.connect(); err != nil {
+		return nil, fmt.Errorf("failed to establish initial connection: %v", err)
+	}
+
+	return &wsClient, nil
+}
+
+type SafeWebsocketClient struct {
+	baseHost    string
+	basePort    uint16
+	useTLS      bool
+	path        *string
+	rawQuery    *string
+	dataChannel chan []byte
+	mu          *custom_rwmutex.CustomRwMutex
+	conn        *websocket.Conn
+	ctx         context.Context
+	cancel      context.CancelFunc
+	reconnectCh chan struct{}
+	isConnected bool
+
+	doneMap *SafeMap[string, chan struct{}]
+}
+
+func (wsClient *SafeWebsocketClient) connect() error {
+	var scheme string
+	if wsClient.useTLS {
+		scheme = "wss"
+	} else {
+		scheme = "ws"
+	}
+	newURL := url.URL{
+		Scheme: scheme,
+		Host:   fmt.Sprintf("%s:%d", wsClient.baseHost, wsClient.basePort),
+	}
+
+	if wsClient.path != nil && strings.TrimSpace(*wsClient.path) != "" {
+		newURL.Path = *wsClient.path
+	}
+
+	if wsClient.rawQuery != nil && strings.TrimSpace(*wsClient.rawQuery) != "" {
+		newURL.RawQuery = *wsClient.rawQuery
+	}
+
+	conn, _, err := websocket.DefaultDialer.Dial(newURL.String(), nil)
+	if err != nil {
+		return fmt.Errorf("failed to connect to %s: %w", wsClient.baseHost, err)
+	}
+
+	conn.SetPingHandler(func(pingData string) error {
+		return wsClient.mu.WriteHandler(func() error {
+			if err := conn.WriteMessage(websocket.PongMessage, []byte(pingData)); err != nil {
+				if err == websocket.ErrCloseSent {
+					return nil
+				}
+				if netErr, ok := err.(interface{ Timeout() bool }); ok && netErr.Timeout() {
+					return nil
+				}
+				return err
+			}
+			return nil
+		})
+	})
+
+	wsClient.mu.WriteHandler(func() error {
+		if wsClient.conn != nil {
+			wsClient.conn.Close()
+		}
+
+		ctx, cancel := context.WithCancel(context.Background())
+		wsClient.ctx = ctx
+		wsClient.cancel = cancel
+		wsClient.conn = conn
+		wsClient.isConnected = true
+
+		go wsClient.startPingTicker(ctx)
+		go wsClient.startReceiveHandler(ctx)
+
+		return nil
+	})
+	return nil
+}
+
+func (wsClient *SafeWebsocketClient) startPingTicker(ctx context.Context) {
+	ticker := time.NewTicker(pingPeriod)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ticker.C:
+			wsClient.mu.WriteHandler(func() error {
+				if wsClient.conn == nil {
+					return fmt.Errorf("connecrtion closed")
+				}
+				if err := wsClient.conn.WriteMessage(websocket.PingMessage, []byte{}); err != nil {
+					log.Printf("Ping failed: %v. Will attempt reconnect.", err)
+					wsClient.triggerReconnect()
+				}
+				return nil
+			})
+		case <-ctx.Done():
+			log.Println("Ping ticker stopped due to context cancellation")
+			return
+		}
+	}
+}
+
+func (wsClient *SafeWebsocketClient) startReceiveHandler(ctx context.Context) {
+	for {
+		select {
+		case <-ctx.Done():
+			log.Println("Reconnect handler stopped")
+			return
+		default:
+			wsClient.mu.ReadHandler(func() error {
+				conn := wsClient.conn
+
+				if conn == nil {
+					wsClient.triggerReconnect()
+					return fmt.Errorf("connection closed")
+				}
+				_, message, err := conn.ReadMessage()
+				if err != nil {
+					wsClient.triggerReconnect()
+					return fmt.Errorf("failed to read message: %v", err)
+				}
+				select {
+				case wsClient.dataChannel <- message:
+				default:
+					log.Println("Data channel full, dropping message")
+				}
+				return nil
+			})
+
+		}
+	}
+}
+
+func (wsClient *SafeWebsocketClient) triggerReconnect() {
+	select {
+	case wsClient.reconnectCh <- struct{}{}:
+	default:
+	}
+}
+
+func (wsClient *SafeWebsocketClient) reconnectHandler() {
+	backoff := 1 * time.Second
+	maxBackoff := 30 * time.Second
+	for {
+		select {
+		case <-wsClient.reconnectCh:
+			log.Println("Reconnect triggered")
+			wsClient.mu.WriteHandler(func() error {
+				if wsClient.cancel != nil {
+					wsClient.cancel()
+				}
+				wsClient.isConnected = false
+				return nil
+			})
+
+			time.Sleep(100 * time.Millisecond)
+
+			for {
+				log.Println("Attempting reconnect in %v...", backoff)
+				select {
+				case <-time.After(backoff):
+					if err := wsClient.connect(); err != nil {
+						log.Println("Reconnect failed: %v", err)
+						if backoff < maxBackoff {
+							backoff *= 2
+						}
+						continue
+					}
+					log.Println("Reconnected successfully")
+					backoff = 1 * time.Second
+					break
+				}
+			}
+		case <-wsClient.ctx.Done():
+			log.Println("Reconnect handler stopped due to client shutdown")
+			return
+		}
+	}
+}
+
+func (wsClient *SafeWebsocketClient) DataChannel() <-chan []byte {
+	return wsClient.dataChannel
+}

v1/examples/client/main.go

@@ -0,0 +1,25 @@
+package main
+
+import (
+	"fmt"
+	"log"
+
+	"git.neurocipta.com/rogerferdinan/safe-web-socket/v1/client"
+)
+
+func main() {
+	wsClient, err := client.NewSafeWebsocketClientBuilder().
+		BaseHost("localhost").
+		BasePort(8080).
+		Path("/ws/test/data_1").
+		UseTLS(false).
+		Build()
+	if err != nil {
+		log.Fatal(err)
+	}
+	dataChannel := wsClient.DataChannel()
+
+	for data := range dataChannel {
+		fmt.Println(string(data))
+	}
+}

v1/examples/server/main.go

@@ -1,12 +1,18 @@
 package main
 
 import (
+	"encoding/json"
 	"log"
 	"time"
 
 	"git.neurocipta.com/rogerferdinan/safe-web-socket/v1/server"
 )
 
+type ExampleData struct {
+	Time time.Time `json:"time"`
+	Data string    `json:"data"`
+}
+
 func main() {
 	s, err := server.NewSafeWebsocketServerBuilder().
 		BaseHost("localhost").
@@ -14,13 +20,27 @@ func main() {
 		HandleFuncWebsocket("/ws/test/", "data_1", func(c chan []byte) {
 			ticker := time.NewTicker(10 * time.Millisecond)
 			for range ticker.C {
-				c <- []byte(time.Now().Format("2006-01-02 15:04:05") + "_data_1")
+				jsonBytes, err := json.Marshal(ExampleData{
+					Time: time.Now(),
+					Data: "data_1",
+				})
+				if err != nil {
+					continue
+				}
+				c <- jsonBytes
 			}
 		}).
 		HandleFuncWebsocket("/ws/test/", "data_2", func(c chan []byte) {
 			ticker := time.NewTicker(10 * time.Millisecond)
 			for range ticker.C {
-				c <- []byte(time.Now().Format("2006-01-02 15:04:05") + "_data_2")
+				jsonBytes, err := json.Marshal(ExampleData{
+					Time: time.Now(),
+					Data: "data_2",
+				})
+				if err != nil {
+					continue
+				}
+				c <- jsonBytes
 			}
 		}).
 		Build()

v1/server/server.go

@@ -18,9 +18,6 @@ type SafeWebsocketServerBuilder struct {
 }
 
 func NewSafeWebsocketServerBuilder() *SafeWebsocketServerBuilder {
-	h := internal.NewHub()
-	h.Run()
-
 	return &SafeWebsocketServerBuilder{
 		upgrader: &websocket.Upgrader{
 			ReadBufferSize:  1024,