socket

README

socket

Simple Socket.io alternative with #golang server

Usage

Server:

package main

import (
  "fmt"
  "net/http"

  "github.com/djherbis/socket"
)

type MyObject struct{
  Text string `json:"text"`
}

func main() {
  server := socket.NewServer()

  server.On(socket.Connection, func(so socket.Socket) {
    so.Emit("hello", "world")

    so.On("hey", func(msg string) {
      fmt.Println(msg)
    })

    so.On("new obj", func(myobj MyObject){
      fmt.Println(myobj)
    })

    so.Emit("server obj", MyObject{Text: "obj from server to client"})
  })

  router := http.NewServeMux()
  router.Handle("/socket", server)
  router.Handle("/", http.FileServer(http.Dir("."))) // serve up socket.js
  http.ListenAndServe("localhost:8080", router)
}

Client:

<script src="socket.js"></script>
<script>
  var socket = io("localhost:8080/");
  
  socket.emit("hey", "hey there!");
  
  socket.on("hello", function(msg){
    console.log(msg);
  });
  
  socket.emit("new obj", {text: "objects are automatically marshalled/unmarshalled"});

  socket.on("server obj", function(myobj){
    console.log(myobj);
  });
</script>

Installation

# Server Side
go get github.com/djherbis/socket

# Client Side
<script src="socket.js"></script>

Documentation

Index

• Constants
• Variables
• type ClientSocket
  • func New(url string) (ClientSocket, error)
• type Emitter
• type EventHandler
• type Handler
• type Namespace
• type Packet
• type PacketHandler
• type Room
• type Server
  • func NewServer() *Server
  • func (ns Server) Emit(event string, args ...interface{}) error
  • func (ns Server) Name() string
  • func (s *Server) Of(name string) Namespace
  • func (ns Server) On(event string, fn interface{}) error
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (ns Server) To(room string) Emitter
• type Socket
• type Transport

Constants

const Connection = "connection"

const Disconnect = "disconnect"

const Disconnection = "disconnection"

Variables

var ErrNotSocketFunc = errors.New("connection/disconnection must take fn of type func(Socket)")

Types

type ClientSocket

type ClientSocket interface {

	// ID() is this sockets unique identifier
	ID() string

	// Namespace() is the namespace this socket is a part of
	Namespace() string

	// On will register an function to handle events sent
	// from the other end of the socket
	EventHandler

	// Emit will send an event to the other end of the socket
	Emitter

	// Close the underlying Transport
	Close() error
}

ClientSocket creates a client-side Socket

func New

func New(url string) (ClientSocket, error)

type Emitter

type Emitter interface {
	Emit(event string, args ...interface{}) error
}

Emitter handles sending messages. Emit sends an event and args which will be handled by the func registered via socket.on.

type EventHandler

type EventHandler interface {
	On(event string, fn interface{}) error
}

EventHandler registers a function to be run when an event is received. The arguments to the function will be unmarshalled from the javascript objects emitted by the client-side socket.

type Handler

type Handler interface {
	EventHandler
	PacketHandler
}

Handler is both a PacketHandler and a EventHandler

type Namespace

type Namespace interface {

	// Name returns this namespace's name
	Name() string

	// To emits to a room
	To(room string) Emitter

	// On will register a function on an event
	EventHandler

	// Emit will broadcast to the namespace
	Emitter
}

Namespace is used to multiplex a single Transport and allow independent sockets within a single connection.

type Packet

type Packet interface {
	Namespace() string
	Socket() string
	Event() string
	DecodeArgs(args ...interface{})
}

Packet is used to receive a sent event and decode the javascript objects into a functions arguments

type PacketHandler

type PacketHandler interface {
	OnPacket(Packet)
}

PacketHandler responds to a Packet

type Room

type Room interface {

	// Name returns the room name
	Name() string

	// Size returns the # of sockets in the room
	Size() int

	// Join adds a socket to the Room
	Join(so Socket)

	// Leave removes a socket from the Room
	Leave(so Socket)

	// Emit sends to all members of the room
	Emitter
}

Room is a collection of Sockets

type Server

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

Server handles creating Sockets from http connections

func NewServer

func NewServer() *Server

NewServer creates a new Server

func (Server) Emit

func (ns Server) Emit(event string, args ...interface{}) error

func (Server) Name

func (ns Server) Name() string

func (*Server) Of

func (s *Server) Of(name string) Namespace

Of creates a new Namespace with "name", or returns the existing Namespace with name "name"

func (Server) On

func (ns Server) On(event string, fn interface{}) error

func (*Server) ServeHTTP

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

ServeHttp handles http requests and converting them into Sockets

func (Server) To

func (ns Server) To(room string) Emitter

type Socket

type Socket interface {
	ClientSocket

	// Join adds a Socket to the passed Room
	Join(room string)

	// Leave removes a Socket from the passed Room
	Leave(room string)

	// Rooms returns the rooms this Socket is in
	Rooms() []string

	// To returns an Emitter to the passed room.
	To(string) Emitter

	// Request returns the request which this Socket was created from.
	Request() *http.Request
}

Socket is a Server-side socket

type Transport

type Transport interface {
	Request() *http.Request
	NextPacket() (Packet, error)
	Send(namespace, socketid, event string, args ...interface{}) error
	Close() error
}

Transport manages send and receiving Packets