melody

README

melody

🎶 Minimalist websocket framework for Go.

Melody is websocket framework based on github.com/gorilla/websocket that abstracts away the tedious parts of handling websockets. It gets out of your way so you can write real-time apps. Features include:

• Clear and easy interface similar to net/http or Gin.
• A simple way to broadcast to all or selected connected sessions.
• Message buffers making concurrent writing safe.
• Automatic handling of sending ping/pong heartbeats that timeout broken sessions.
• Store data on sessions.

Install

go get github.com/olahol/melody

Example: chat

package main

import (
	"net/http"

	"github.com/olahol/melody"
)

func main() {
	m := melody.New()

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		http.ServeFile(w, r, "index.html")
	})

	http.HandleFunc("/ws", func(w http.ResponseWriter, r *http.Request) {
		m.HandleRequest(w, r)
	})

	m.HandleMessage(func(s *melody.Session, msg []byte) {
		m.Broadcast(msg)
	})

	http.ListenAndServe(":5000", nil)
}

Example: gophers

package main

import (
	"net/http"
	"strings"

	"github.com/google/uuid"
	"github.com/olahol/melody"
)

type GopherInfo struct {
	ID, X, Y string
}

func main() {
	m := melody.New()

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		http.ServeFile(w, r, "index.html")
	})

	http.HandleFunc("/ws", func(w http.ResponseWriter, r *http.Request) {
		m.HandleRequest(w, r)
	})

	m.HandleConnect(func(s *melody.Session) {
		ss, _ := m.Sessions()

		for _, o := range ss {
			value, exists := o.Get("info")

			if !exists {
				continue
			}

			info := value.(*GopherInfo)

			s.Write([]byte("set " + info.ID + " " + info.X + " " + info.Y))
		}

		id := uuid.NewString()
		s.Set("info", &GopherInfo{id, "0", "0"})

		s.Write([]byte("iam " + id))
	})

	m.HandleDisconnect(func(s *melody.Session) {
		value, exists := s.Get("info")

		if !exists {
			return
		}

		info := value.(*GopherInfo)

		m.BroadcastOthers([]byte("dis "+info.ID), s)
	})

	m.HandleMessage(func(s *melody.Session, msg []byte) {
		p := strings.Split(string(msg), " ")
		value, exists := s.Get("info")

		if len(p) != 2 || !exists {
			return
		}

		info := value.(*GopherInfo)
		info.X = p[0]
		info.Y = p[1]

		m.BroadcastOthers([]byte("set "+info.ID+" "+info.X+" "+info.Y), s)
	})

	http.ListenAndServe(":5000", nil)
}

More examples

Documentation

Contributors

FAQ

If you are getting a 403 when trying to connect to your websocket you can change allow all origin hosts:

m := melody.New()
m.Upgrader.CheckOrigin = func(r *http.Request) bool { return true }

Documentation

Index

• Constants
• Variables
• func FormatCloseMessage(closeCode int, text string) []byte
• type Config
• type Melody
  • func New() *Melody
  • func (m *Melody) Broadcast(msg []byte) error
  • func (m *Melody) BroadcastBinary(msg []byte) error
  • func (m *Melody) BroadcastBinaryFilter(msg []byte, fn func(*Session) bool) error
  • func (m *Melody) BroadcastBinaryOthers(msg []byte, s *Session) error
  • func (m *Melody) BroadcastFilter(msg []byte, fn func(*Session) bool) error
  • func (m *Melody) BroadcastMultiple(msg []byte, sessions []*Session) error
  • func (m *Melody) BroadcastOthers(msg []byte, s *Session) error
  • func (m *Melody) Close() error
  • func (m *Melody) CloseWithMsg(msg []byte) error
  • func (m *Melody) HandleClose(fn func(*Session, int, string) error)
  • func (m *Melody) HandleConnect(fn func(*Session))
  • func (m *Melody) HandleDisconnect(fn func(*Session))
  • func (m *Melody) HandleError(fn func(*Session, error))
  • func (m *Melody) HandleMessage(fn func(*Session, []byte))
  • func (m *Melody) HandleMessageBinary(fn func(*Session, []byte))
  • func (m *Melody) HandlePong(fn func(*Session))
  • func (m *Melody) HandleRequest(w http.ResponseWriter, r *http.Request) error
  • func (m *Melody) HandleRequestWithKeys(w http.ResponseWriter, r *http.Request, keys map[string]any) error
  • func (m *Melody) HandleSentMessage(fn func(*Session, []byte))
  • func (m *Melody) HandleSentMessageBinary(fn func(*Session, []byte))
  • func (m *Melody) IsClosed() bool
  • func (m *Melody) Len() int
  • func (m *Melody) Sessions() ([]*Session, error)
• type Session
  • func (s *Session) Close() error
  • func (s *Session) CloseWithMsg(msg []byte) error
  • func (s *Session) Get(key string) (value any, exists bool)
  • func (s *Session) IsClosed() bool
  • func (s *Session) LocalAddr() net.Addr
  • func (s *Session) MustGet(key string) any
  • func (s *Session) RemoteAddr() net.Addr
  • func (s *Session) Set(key string, value any)
  • func (s *Session) UnSet(key string)
  • func (s *Session) WebsocketConnection() *websocket.Conn
  • func (s *Session) Write(msg []byte) error
  • func (s *Session) WriteBinary(msg []byte) error

Constants

const (
	CloseNormalClosure           = 1000
	CloseGoingAway               = 1001
	CloseProtocolError           = 1002
	CloseUnsupportedData         = 1003
	CloseNoStatusReceived        = 1005
	CloseAbnormalClosure         = 1006
	CloseInvalidFramePayloadData = 1007
	ClosePolicyViolation         = 1008
	CloseMessageTooBig           = 1009
	CloseMandatoryExtension      = 1010
	CloseInternalServerErr       = 1011
	CloseServiceRestart          = 1012
	CloseTryAgainLater           = 1013
	CloseTLSHandshake            = 1015
)

Close codes defined in RFC 6455, section 11.7. Duplicate of codes from gorilla/websocket for convenience.

Variables

var (
	ErrClosed            = errors.New("melody instance is closed")
	ErrSessionClosed     = errors.New("session is closed")
	ErrWriteClosed       = errors.New("tried to write to closed a session")
	ErrMessageBufferFull = errors.New("session message buffer is full")
)

Functions

func FormatCloseMessage

func FormatCloseMessage(closeCode int, text string) []byte

FormatCloseMessage formats closeCode and text as a WebSocket close message.

Types

type Config

type Config struct {
	WriteWait                 time.Duration // Duration until write times out.
	PongWait                  time.Duration // Timeout for waiting on pong.
	PingPeriod                time.Duration // Duration between pings.
	MaxMessageSize            int64         // Maximum size in bytes of a message.
	MessageBufferSize         int           // The max amount of messages that can be in a sessions buffer before it starts dropping them.
	ConcurrentMessageHandling bool          // Handle messages from sessions concurrently.
}

Config melody configuration struct.

type Melody

type Melody struct {
	Config   *Config
	Upgrader *websocket.Upgrader
	// contains filtered or unexported fields
}

Melody implements a websocket manager.

func New

func New() *Melody

New creates a new melody instance with default Upgrader and Config.

func (*Melody) Broadcast

func (m *Melody) Broadcast(msg []byte) error

Broadcast broadcasts a text message to all sessions.

func (*Melody) BroadcastBinary

func (m *Melody) BroadcastBinary(msg []byte) error

BroadcastBinary broadcasts a binary message to all sessions.

func (*Melody) BroadcastBinaryFilter

func (m *Melody) BroadcastBinaryFilter(msg []byte, fn func(*Session) bool) error

BroadcastBinaryFilter broadcasts a binary message to all sessions that fn returns true for.

func (*Melody) BroadcastBinaryOthers

func (m *Melody) BroadcastBinaryOthers(msg []byte, s *Session) error

BroadcastBinaryOthers broadcasts a binary message to all sessions except session s.

func (*Melody) BroadcastFilter

func (m *Melody) BroadcastFilter(msg []byte, fn func(*Session) bool) error

BroadcastFilter broadcasts a text message to all sessions that fn returns true for.

func (*Melody) BroadcastMultiple

func (m *Melody) BroadcastMultiple(msg []byte, sessions []*Session) error

BroadcastMultiple broadcasts a text message to multiple sessions given in the sessions slice.

func (*Melody) BroadcastOthers

func (m *Melody) BroadcastOthers(msg []byte, s *Session) error

BroadcastOthers broadcasts a text message to all sessions except session s.

func (*Melody) Close

func (m *Melody) Close() error

Close closes the melody instance and all connected sessions.

func (*Melody) CloseWithMsg

func (m *Melody) CloseWithMsg(msg []byte) error

CloseWithMsg closes the melody instance with the given close payload and all connected sessions. Use the FormatCloseMessage function to format a proper close message payload.

func (*Melody) HandleClose

func (m *Melody) HandleClose(fn func(*Session, int, string) error)

HandleClose sets the handler for close messages received from the session. The code argument to h is the received close code or CloseNoStatusReceived if the close message is empty. The default close handler sends a close frame back to the session.

The application must read the connection to process close messages as described in the section on Control Frames above.

The connection read methods return a CloseError when a close frame is received. Most applications should handle close messages as part of their normal error handling. Applications should only set a close handler when the application must perform some action before sending a close frame back to the session.

func (*Melody) HandleConnect

func (m *Melody) HandleConnect(fn func(*Session))

HandleConnect fires fn when a session connects.

func (*Melody) HandleDisconnect

func (m *Melody) HandleDisconnect(fn func(*Session))

HandleDisconnect fires fn when a session disconnects.

func (*Melody) HandleError

func (m *Melody) HandleError(fn func(*Session, error))

HandleError fires fn when a session has an error.

func (*Melody) HandleMessage

func (m *Melody) HandleMessage(fn func(*Session, []byte))

HandleMessage fires fn when a text message comes in. NOTE: by default Melody handles messages sequentially for each session. This has the effect that a message handler exceeding the read deadline (Config.PongWait, by default 1 minute) will time out the session. Concurrent message handling can be turned on by setting Config.ConcurrentMessageHandling to true.

func (*Melody) HandleMessageBinary

func (m *Melody) HandleMessageBinary(fn func(*Session, []byte))

HandleMessageBinary fires fn when a binary message comes in.

func (*Melody) HandlePong

func (m *Melody) HandlePong(fn func(*Session))

HandlePong fires fn when a pong is received from a session.

func (*Melody) HandleRequest

func (m *Melody) HandleRequest(w http.ResponseWriter, r *http.Request) error

HandleRequest upgrades http requests to websocket connections and dispatches them to be handled by the melody instance.

func (*Melody) HandleRequestWithKeys

func (m *Melody) HandleRequestWithKeys(w http.ResponseWriter, r *http.Request, keys map[string]any) error

HandleRequestWithKeys does the same as HandleRequest but populates session.Keys with keys.

func (*Melody) HandleSentMessage

func (m *Melody) HandleSentMessage(fn func(*Session, []byte))

HandleSentMessage fires fn when a text message is successfully sent.

func (*Melody) HandleSentMessageBinary

func (m *Melody) HandleSentMessageBinary(fn func(*Session, []byte))

HandleSentMessageBinary fires fn when a binary message is successfully sent.

func (*Melody) IsClosed

func (m *Melody) IsClosed() bool

IsClosed returns the status of the melody instance.

func (*Melody) Len

func (m *Melody) Len() int

Len return the number of connected sessions.

func (*Melody) Sessions

func (m *Melody) Sessions() ([]*Session, error)

Sessions returns all sessions. An error is returned if the melody session is closed.

type Session

type Session struct {
	Request *http.Request
	Keys    map[string]any
	// contains filtered or unexported fields
}

Session wrapper around websocket connections.

func (*Session) Close

func (s *Session) Close() error

Close closes session.

func (*Session) CloseWithMsg

func (s *Session) CloseWithMsg(msg []byte) error

CloseWithMsg closes the session with the provided payload. Use the FormatCloseMessage function to format a proper close message payload.

func (*Session) Get

func (s *Session) Get(key string) (value any, exists bool)

Get returns the value for the given key, ie: (value, true). If the value does not exists it returns (nil, false)

func (*Session) IsClosed

func (s *Session) IsClosed() bool

IsClosed returns the status of the connection.

func (*Session) LocalAddr

func (s *Session) LocalAddr() net.Addr

LocalAddr returns the local addr of the connection.

func (*Session) MustGet

func (s *Session) MustGet(key string) any

MustGet returns the value for the given key if it exists, otherwise it panics.

func (*Session) RemoteAddr

func (s *Session) RemoteAddr() net.Addr

RemoteAddr returns the remote addr of the connection.

func (*Session) Set

func (s *Session) Set(key string, value any)

Set is used to store a new key/value pair exclusively for this session. It also lazy initializes s.Keys if it was not used previously.

func (*Session) UnSet

func (s *Session) UnSet(key string)

UnSet will delete the key and has no return value

func (*Session) WebsocketConnection

func (s *Session) WebsocketConnection() *websocket.Conn

WebsocketConnection returns the underlying websocket connection. This can be used to e.g. set/read additional websocket options or to write sychronous messages.

func (*Session) Write

func (s *Session) Write(msg []byte) error

Write writes message to session.

func (*Session) WriteBinary

func (s *Session) WriteBinary(msg []byte) error

WriteBinary writes a binary message to session.