Categories
BLOG

glue go

Glue go

Glue – Robust Go and Javascript Socket Library

Glue is a real-time bidirectional socket library. It is a clean, robust and efficient alternative to socket.io. This library is designed to connect webbrowsers with a go-backend in a simple way. It automatically detects supported socket layers and chooses the most suitable one. This library handles automatic reconnections on disconnections and handles caching to bridge those disconnections. The server implementation is thread-safe and stable. The API is fixed and there won’t be any breaking API changes.

Currently two socket layers are supported:

  • WebSockets – This is the primary option. They are used if the webbrowser supports WebSockets defined by RFC 6455.
  • AjaxSockets – This socket layer is used as a fallback mode.

Feel free to contribute to this project. Please check the TODO file for more information.

The client javascript Glue library is located in client/dist/glue.js.

You can use bower to install the client library:

bower install –save glue-socket

Get the source and start hacking.

go get github.com/desertbit/glue

Client – Javascript Library

A simple call to glue() without any options will establish a socket connection to the same host. A glue socket object is returned.

Optional Javascript options which can be passed to Glue:

The glue socket object has following public methods:

A channel object has following public methods:

Server – Go Library

Check the Documentation at GoDoc.org.

Use a custom HTTP multiplexer

If you choose to use a custom HTTP multiplexer, then it is possible to deactivate the automatic HTTP handler registration of glue.

The glue server implements the ServeHTTP method of the HTTP Handler interface of the http package. Use this to register the glue HTTP handler with a custom multiplexer. Be aware, that the URL of the custom HTTP handler has to match with the glue HTTPHandleURL options string.

Data has to be read from the socket and each channel. If you don’t require to read data from the socket or a channel, then discard received data with the DiscardRead() method. If received data is not discarded, then the read buffer will block as soon as it is full, which will also block the keep-alive mechanism of the socket. The result would be a closed socket.

Bind custom values to a socket

The socket.Value interface is a placeholder for custom data.

Channels are separate communication channels from the client to the server of a single socket connections. Multiple separate communication channels can be created:

With Glue it is easy to broadcast messages to multiple clients. The Glue Server keeps track of all active connected client sessions. You can make use of the server Sockets, GetSocket or OnNewSocket methods to implement broadcasting.

This socket library is very straightforward to use. Check the sample directory for more examples.

Read data from the socket with a read event function. Check the sample directory for other ways of reading data from the socket.

Glue – Robust Go and Javascript Socket Library (Alternative to Socket.io) – desertbit/glue

Glue go

Package glue – Robust Go and Javascript Socket Library. This library is thread-safe.

Index ¶

  • Constants
  • Variables
  • type Channel
    • func (c *Channel) DiscardRead()
    • func (c *Channel) OnRead(f OnReadFunc)
    • func (c *Channel) Read(timeout . time.Duration) (string, error)
    • func (c *Channel) Socket() *Socket
    • func (c *Channel) Write(data string)
  • type ClosedChan
  • type HTTPSocketType
  • type OnCloseFunc
  • type OnNewSocketFunc
  • type OnReadFunc
  • type Options
    • func (o *Options) SetDefaults()
  • type Server
    • func NewServer(o . Options) *Server
    • func (s *Server) Block(b bool)
    • func (s *Server) GetSocket(id string) *Socket
    • func (s *Server) IsBlocked() bool
    • func (s *Server) OnNewSocket(f OnNewSocketFunc)
    • func (s *Server) Release()
    • func (s *Server) Run() error
    • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
    • func (s *Server) Sockets() []*Socket
  • type Socket
    • func (s *Socket) Channel(name string) *Channel
    • func (s *Socket) Close()
    • func (s *Socket) ClosedChan() ClosedChan
    • func (s *Socket) DiscardRead()
    • func (s *Socket) ID() string
    • func (s *Socket) IsClosed() bool
    • func (s *Socket) IsInitialized() bool
    • func (s *Socket) OnClose(f OnCloseFunc)
    • func (s *Socket) OnRead(f OnReadFunc)
    • func (s *Socket) Read(timeout . time.Duration) (string, error)
    • func (s *Socket) RemoteAddr() string
    • func (s *Socket) UserAgent() string
    • func (s *Socket) Write(data string)
Package Files ¶

Constants ¶

Variables ¶

type Channel ¶ Uses

A Channel is a separate communication channel.

func (*Channel) DiscardRead ¶ Uses

DiscardRead ignores and discars the data received from this channel. Call this method during initialization, if you don’t read any data from this channel. If received data is not discarded, then the read buffer will block as soon as it is full, which will also block the keep-alive mechanism of the socket. The result would be a closed socket.

func (*Channel) OnRead ¶ Uses

OnRead sets the function which is triggered if new data is received on the channel. If this event function based method of reading data from the socket is used, then don’t use the socket Read method. Either use the OnRead or the Read approach.

func (*Channel) Read ¶ Uses

Read the next message from the channel. This method is blocking. One variadic argument sets a timeout duration. If no timeout is specified, this method will block forever. ErrSocketClosed is returned, if the socket connection is closed. ErrReadTimeout is returned, if the timeout is reached.

func (*Channel) Socket ¶ Uses

Socket returns the channel’s socket.

func (*Channel) Write ¶ Uses

Write data to the channel.

type ClosedChan ¶ Uses

ClosedChan is a channel which doesn’t block as soon as the socket is closed.

type HTTPSocketType ¶ Uses

A HTTPSocketType defines which socket type to use for the HTTP glue server.

type OnCloseFunc ¶ Uses

OnCloseFunc is an event function.

type OnNewSocketFunc ¶ Uses

OnNewSocketFunc is an event function.

type OnReadFunc ¶ Uses

OnReadFunc is an event function.

type Options ¶ Uses

Options holds the glue server options.

func (*Options) SetDefaults ¶ Uses

SetDefaults sets unset option values to its default value.

type Server ¶ Uses

A Server represents a glue server which handles incoming socket connections.

func NewServer ¶ Uses

NewServer creates a new glue server instance. One variadic arguments specifies the server options.

func (*Server) Block ¶ Uses

Block new incomming connections.

func (*Server) GetSocket ¶ Uses

GetSocket obtains a socket by its ID. Returns nil if not found.

func (*Server) IsBlocked ¶ Uses

IsBlocked returns a boolean whenever new incoming connections should be blocked.

func (*Server) OnNewSocket ¶ Uses

OnNewSocket sets the event function which is triggered if a new socket connection was made. The event function must not block! As soon as the event function returns, the socket is added to the active sockets map.

func (*Server) Release ¶ Uses

Release this package. This will block all new incomming socket connections and close all current connected sockets.

func (*Server) Run ¶ Uses

Run starts the server and listens for incoming socket connections. This is a blocking method.

func (*Server) ServeHTTP ¶ Uses

ServeHTTP implements the HTTP Handler interface of the http package.

func (*Server) Sockets ¶ Uses

Sockets returns a list of all current connected sockets. Hint: Sockets are added to the active sockets list before the OnNewSocket event function is called. Use the IsInitialized flag to determind if a socket is not ready yet.

type Socket ¶ Uses

A Socket represents a single socket connections to a client.

func (*Socket) Channel ¶ Uses

Channel returns the corresponding channel value specified by the name. If no channel value exists for the given name, a new channel is created. Multiple calls to Channel with the same name, will always return the same channel value pointer.

func (*Socket) Close ¶ Uses

Close the socket connection.

func (*Socket) ClosedChan ¶ Uses

ClosedChan returns a channel which is non-blocking (closed) as soon as the socket is closed.

func (*Socket) DiscardRead ¶ Uses

DiscardRead ignores and discars the data received from the client. Call this method during initialization, if you don’t read any data from the socket. If received data is not discarded, then the read buffer will block as soon as it is full, which will also block the keep-alive mechanism of the socket. The result would be a closed socket.

func (*Socket) ID ¶ Uses

ID returns the socket’s unique ID. This is a cryptographically secure pseudorandom number.

func (*Socket) IsClosed ¶ Uses

IsClosed returns a boolean whenever the connection is closed.

func (*Socket) IsInitialized ¶ Uses

IsInitialized returns a boolean indicating if a socket is initialized and ready to be used. This flag is set to true after the OnNewSocket function has returned for this socket.

func (*Socket) OnClose ¶ Uses

OnClose sets the functions which is triggered if the socket connection is closed. This method can be called multiple times to bind multiple functions.

func (*Socket) OnRead ¶ Uses

OnRead sets the function which is triggered if new data is received. If this event function based method of reading data from the socket is used, then don’t use the socket Read method. Either use the OnRead or the Read approach.

func (*Socket) Read ¶ Uses

Read the next message from the socket. This method is blocking. One variadic argument sets a timeout duration. If no timeout is specified, this method will block forever. ErrSocketClosed is returned, if the socket connection is closed. ErrReadTimeout is returned, if the timeout is reached.

func (*Socket) RemoteAddr ¶ Uses

RemoteAddr returns the remote address of the client.

func (*Socket) UserAgent ¶ Uses

UserAgent returns the user agent of the client.

func (*Socket) Write ¶ Uses

Write data to the client.

Directories ¶

Path Synopsis
backend

Package backend provides the server backend with various socket implementations.
backend/closer

Emit a close function only once, also if called multiple times.
backend/global

Package global provides global types and constants for the backend packages.
backend/sockets/ajaxsocket

Package ajaxsocket provides the ajax socket implementation.
backend/sockets/websocket
log

Package log holds the log backend used by the socket library.
sample/Channels
sample/OnlyWrite
sample/ReadEventWrite
sample/ReadWrite
utils

Package utils provides utilities for the glue socket implementation.

Package glue imports 15 packages (graph) and is imported by 9 packages. Updated 2019-06-21 . Refresh now. Tools for package owners.

Package glue – Robust Go and Javascript Socket Library.