README
¶
kuromi
Minimalist websocket framework for Go. 世界クロミ化計画
Kuromi is websocket framework based on github.com/coder/websocket and rewrite of github.com/olahol/melody 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/httpor 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/fshiori/kuromi
Example: chat
package main
import (
"net/http"
"github.com/fshiori/kuromi"
)
func main() {
k := kuromi.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) {
k.HandleRequest(w, r)
})
k.HandleMessage(func(s *kuromi.Session, msg []byte) {
k.Broadcast(msg)
})
http.ListenAndServe(":5000", nil)
}
Documentation
¶
Index ¶
- Constants
- Variables
- type Config
- type Kuromi
- func (k *Kuromi) Broadcast(msg []byte) error
- func (k *Kuromi) BroadcastBinary(msg []byte) error
- func (k *Kuromi) BroadcastBinaryFilter(msg []byte, fn func(*Session) bool) error
- func (k *Kuromi) BroadcastBinaryOthers(msg []byte, s *Session) error
- func (k *Kuromi) BroadcastFilter(msg []byte, fn func(*Session) bool) error
- func (k *Kuromi) BroadcastMultiple(msg []byte, sessions []*Session) error
- func (k *Kuromi) BroadcastOthers(msg []byte, s *Session) error
- func (k *Kuromi) Close() error
- func (k *Kuromi) CloseWithMsg(code websocket.StatusCode, reason string) error
- func (k *Kuromi) HandleClose(fn func(*Session, int, string) error)
- func (k *Kuromi) HandleConnect(fn func(*Session))
- func (k *Kuromi) HandleDisconnect(fn func(*Session))
- func (k *Kuromi) HandleError(fn func(*Session, error))
- func (k *Kuromi) HandleMessage(fn func(*Session, []byte))
- func (k *Kuromi) HandleMessageBinary(fn func(*Session, []byte))
- func (k *Kuromi) HandlePong(fn func(*Session))
- func (k *Kuromi) HandleRequest(w http.ResponseWriter, r *http.Request) error
- func (k *Kuromi) HandleRequestWithKeys(w http.ResponseWriter, r *http.Request, keys map[string]any) error
- func (k *Kuromi) HandleSentMessage(fn func(*Session, []byte))
- func (k *Kuromi) HandleSentMessageBinary(fn func(*Session, []byte))
- func (k *Kuromi) IsClosed() bool
- func (k *Kuromi) Len() int
- func (k *Kuromi) Sessions() ([]*Session, error)
- type Session
- func (s *Session) Close() error
- func (s *Session) CloseWithMsg(code websocket.StatusCode, reason string) error
- func (s *Session) Get(key string) (value any, exists bool)
- func (s *Session) IsClosed() bool
- func (s *Session) MustGet(key string) any
- 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 (
CloseMessage websocket.MessageType = websocket.MessageText + 1000
)
Variables ¶
Functions ¶
This section is empty.
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 kuromi configuration struct.
type Kuromi ¶
type Kuromi struct {
Config *Config
AcceptOptions *websocket.AcceptOptions
// contains filtered or unexported fields
}
Kuromi implements a websocket manager.
func (*Kuromi) BroadcastBinary ¶
BroadcastBinary broadcasts a binary message to all sessions.
func (*Kuromi) BroadcastBinaryFilter ¶
BroadcastBinaryFilter broadcasts a binary message to all sessions that fn returns true for.
func (*Kuromi) BroadcastBinaryOthers ¶
BroadcastBinaryOthers broadcasts a binary message to all sessions except session s.
func (*Kuromi) BroadcastFilter ¶
BroadcastFilter broadcasts a text message to all sessions that fn returns true for.
func (*Kuromi) BroadcastMultiple ¶
BroadcastMultiple broadcasts a text message to multiple sessions given in the sessions slice.
func (*Kuromi) BroadcastOthers ¶
BroadcastOthers broadcasts a text message to all sessions except session s.
func (*Kuromi) CloseWithMsg ¶
func (k *Kuromi) CloseWithMsg(code websocket.StatusCode, reason string) error
CloseWithMsg closes the kuromi instance with the given close payload and all connected sessions. Use the FormatCloseMessage function to format a proper close message payload.
func (*Kuromi) HandleClose ¶
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 (*Kuromi) HandleConnect ¶
HandleConnect fires fn when a session connects.
func (*Kuromi) HandleDisconnect ¶
HandleDisconnect fires fn when a session disconnects.
func (*Kuromi) HandleError ¶
HandleError fires fn when a session has an error.
func (*Kuromi) HandleMessage ¶
HandleMessage fires fn when a text message comes in. NOTE: by default Kuromi 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 (*Kuromi) HandleMessageBinary ¶
HandleMessageBinary fires fn when a binary message comes in.
func (*Kuromi) HandlePong ¶
HandlePong fires fn when a pong is received from a session.
func (*Kuromi) HandleRequest ¶
HandleRequest upgrades http requests to websocket connections and dispatches them to be handled by the kuromi instance.
func (*Kuromi) HandleRequestWithKeys ¶
func (k *Kuromi) 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 (*Kuromi) HandleSentMessage ¶
HandleSentMessage fires fn when a text message is successfully sent.
func (*Kuromi) HandleSentMessageBinary ¶
HandleSentMessageBinary fires fn when a binary message is successfully sent.
type Session ¶
type Session struct {
Request *http.Request
Keys map[string]any
// contains filtered or unexported fields
}
Session wrapper around websocket connections.
func (*Session) CloseWithMsg ¶
func (s *Session) CloseWithMsg(code websocket.StatusCode, reason string) error
CloseWithMsg closes the session with the provided payload. Use the FormatCloseMessage function to format a proper close message payload.
func (*Session) Get ¶
Get returns the value for the given key, ie: (value, true). If the value does not exists it returns (nil, false)
func (*Session) MustGet ¶
MustGet returns the value for the given key if it exists, otherwise it panics.
func (*Session) Set ¶
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) WebsocketConnection ¶
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) WriteBinary ¶
WriteBinary writes a binary message to session.
Source Files
Directories