lightcable

README

lightcable

lightweight websocket channel server

Compile

• golang >= 1.13

Application scenario

• A simple Websocket broadcast room
• WebRTC signaling server
• Replace socket.io (Special case: client only join a room)
• Wx APP sdk and webview communication (WeChat Mini Program and Webview communication)

As a Application

docker run -p 8080:8080 ghcr.io/a-wing/lightcable

install && run

go install github.com/a-wing/lightcable/cmd/lightcable@latest

# Listen port: 8088
lightcable -l localhost:8088

URL

ws://localhost:8080/{room}

broadcast server demo

Server

lightcable

Room: xxx

websocat --linemode-strip-newlines 'ws://localhost:8080/xxx'

Room: xxx

websocat --linemode-strip-newlines 'ws://localhost:8080/xxx'

Room: xxx-2

websocat --linemode-strip-newlines 'ws://localhost:8080/xxx-2'

Documentation

Index

• Variables
• type Client
• type Config
• type Message
• type Server
  • func New(cfg *Config) *Server
  • func (s *Server) Broadcast(room, name string, code int, data []byte)
  • func (s *Server) BroadcastAll(name string, code int, data []byte)
  • func (s *Server) OnConnClose(fn func(*Client))
  • func (s *Server) OnConnReady(fn func(*Client))
  • func (s *Server) OnConnected(fn func(w http.ResponseWriter, r *http.Request) (room, name string, ok bool))
  • func (s *Server) OnMessage(fn func(*Message))
  • func (s *Server) OnRoomClose(fn func(room string))
  • func (s *Server) OnRoomReady(fn func(room string))
  • func (s *Server) OnServClose(fn func())
  • func (s *Server) Run(ctx context.Context)
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) Upgrade(w http.ResponseWriter, r *http.Request, room, name string) error
• type WorkerConfig

Variables

var DefaultConfig = &Config{
	SignBufferCount: 128,
	CastBufferCount: 128,

	Worker: WorkerConfig{
		SignBufferCount: 128,
		CastBufferCount: 128,
		Local:           false,
	},
}

DefaultConfig is a server with all fields set to the default values.

Types

type Client

type Client struct {
	Name string
	Room string

	Err error
	// contains filtered or unexported fields
}

Client is a middleman between the websocket connection and the worker.

type Config

type Config struct {
	// register, unregister room buffer count
	SignBufferCount int
	// broadcast message to room buffer count
	CastBufferCount int

	Worker WorkerConfig
}

Config describes the configuration of the server.

type Message

type Message struct {
	Room string
	Name string
	Code int
	Data []byte
	// contains filtered or unexported fields
}

Message represents a message send and received from the Websocket connection.

Code is websocket Opcode Name is user custom Name

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is lightcable core Server. use callback notification message broadcast message, A Server auto create and manage multiple goroutines every room create worker

func New

func New(cfg *Config) *Server

New creates a new Server.

func (*Server) Broadcast

func (s *Server) Broadcast(room, name string, code int, data []byte)

Broadcast will room all websocket connection send message https://www.rfc-editor.org/rfc/rfc6455.html#section-11.8 code is websocket Opcode name is custom name, this will be callback OnMessage

func (*Server) BroadcastAll

func (s *Server) BroadcastAll(name string, code int, data []byte)

BroadcastAll will all room all websocket connection send message

func (*Server) OnConnClose

func (s *Server) OnConnClose(fn func(*Client))

OnConnClose will Client error or websocket close or server close if context server closed err == nil

func (*Server) OnConnReady

func (s *Server) OnConnReady(fn func(*Client))

OnConnReady websocket connection successfully and join room this will block worker

func (*Server) OnConnected

func (s *Server) OnConnected(fn func(w http.ResponseWriter, r *http.Request) (room, name string, ok bool))

OnConnected auth this websocket connection callback ok: true Allows connection; false Reject connection Maybe Concurrent. unique ID need self use sync.Mutex

func (*Server) OnMessage

func (s *Server) OnMessage(fn func(*Message))

OnMessage will all Websocket Conn Recv Message will callback this function This have Block worker. Block this room

func (*Server) OnRoomClose

func (s *Server) OnRoomClose(fn func(room string))

OnRoomClose worker all websocket connection closed, worker close

func (*Server) OnRoomReady

func (s *Server) OnRoomReady(fn func(room string))

OnRoomReady Create a new room successfully

func (*Server) OnServClose

func (s *Server) OnServClose(fn func())

OnServClose server safely shutdown done callback

func (*Server) Run

func (s *Server) Run(ctx context.Context)

Run need use 'go server.Run(context.Background())' run daemon in order to concurrency. server instance only a run

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP Interface 'http.Handler'. creates new websocket connection Maybe Create new Worker. worker == room

func (*Server) Upgrade

func (s *Server) Upgrade(w http.ResponseWriter, r *http.Request, room, name string) error

Add a New Websocket Client

type WorkerConfig

type WorkerConfig struct {
	// register, unregister client buffer count
	SignBufferCount int
	// broadcast message to client buffer count
	CastBufferCount int

	// If you set this option as `false`
	// The server will not broadcast to you messages you send.
	// Look like MQTTv5 nolocal
	Local bool
}

Worker Config describes the configuration of the server. server should worker, every worker use this configuration