README
¶
Neptulon
Neptulon is a bidirectional RPC framework with middleware support. Communication protocol is JSON-RPC over WebSockets which is full-duplex bidirectional.
Neptulon framework is only about 400 lines of code, which makes it easy to fork, specialize, and maintain for specific purposes, if you need to.
Getting Started
Following is a server for echoing all incoming messages as is:
s := neptulon.NewServer("127.0.0.1:3000")
s.MiddlewareFunc(middleware.Echo)
s.ListenAndServe()
Following is a client connection to the above server. You can also use WebSocket Test Page from your browser to connect to the server.
c, _ := neptulon.NewConn()
c.Connect("ws://127.0.0.1:3000")
c.SendRequest("echo", map[string]string{"message": "Hello!"}, func(ctx *neptulon.ResCtx) error {
var msg interface{}
err := ctx.Result(&msg)
fmt.Println("Server sent:", msg)
return err
})
For a more comprehensive example, see example_test.go file.
Middleware
Both the Server and client Conn types have the same middleware handler signature: Middleware(func(ctx *ReqCtx) error). Since both the server and the client can send request messages to each other, you can use the same set of middleware to for both, to handle the incoming requests.
See middleware package to get a list of all bundled middleware.
Client Libraries
You can connect to your Neptulon server using any programming language that has WebSocket + JSON libraries. For convenience and for reference, following client modules are provided nonetheless:
- Go: Bundled conn.go file.
- Java: Package client-java. Uses OkHttp for WebSockets and GSON for JSON serialization.
Users
Titan mobile messaging app server is written entirely using the Neptulon framework. You can visit its repo to see a complete use case of Neptulon framework.
Testing
All the tests can be executed with GORACE="halt_on_error=1" go test -race -cover ./... command. Optionally you can add -v flag to observe all connection logs.
License
Documentation
¶
Overview ¶
Package neptulon is a RPC framework with middleware support.
Example ¶
Example demonstrating the Neptulon server.
package main
import (
"fmt"
"log"
"time"
"github.com/neptulon/neptulon"
)
const debug = false
// Example demonstrating the Neptulon server.
func main() {
type SampleMsg struct {
Message string `json:"message"`
}
// start the server and echo incoming messages back to the sender
s := neptulon.NewServer("127.0.0.1:3000")
s.MiddlewareFunc(func(ctx *neptulon.ReqCtx) error {
var msg SampleMsg
if err := ctx.Params(&msg); err != nil {
return err
}
ctx.Res = msg
return ctx.Next()
})
go s.ListenAndServe()
defer s.Close()
time.Sleep(time.Millisecond * 50) // let server goroutine to warm up
// connect to the server and send a message
c, err := neptulon.NewConn()
if err != nil {
log.Fatal(err)
}
if err := c.Connect("ws://127.0.0.1:3000"); err != nil {
log.Fatal(err)
}
defer c.Close()
_, err = c.SendRequest("echo", SampleMsg{Message: "Hello!"}, func(ctx *neptulon.ResCtx) error {
var msg SampleMsg
if err := ctx.Result(&msg); err != nil {
return err
}
fmt.Println("Server says:", msg.Message)
return nil
})
if err != nil {
log.Fatal(err)
}
time.Sleep(time.Millisecond * 50) // wait to get an answer
}
Output: Server says: Hello!
Index ¶
- type Conn
- func (c *Conn) Close() error
- func (c *Conn) Connect(addr string) error
- func (c *Conn) DisconnHandler(handler func(c *Conn))
- func (c *Conn) Middleware(middleware ...Middleware)
- func (c *Conn) MiddlewareFunc(middleware ...func(ctx *ReqCtx) error)
- func (c *Conn) RemoteAddr() net.Addr
- func (c *Conn) SendRequest(method string, params interface{}, resHandler func(res *ResCtx) error) (reqID string, err error)
- func (c *Conn) SendRequestArr(method string, resHandler func(res *ResCtx) error, params ...interface{}) (reqID string, err error)
- func (c *Conn) SetDeadline(seconds int)
- func (c *Conn) Wait(timeout int) error
- type Middleware
- type ReqCtx
- type ResCtx
- type ResError
- type Server
- func (s *Server) Close() error
- func (s *Server) DisconnHandler(handler func(c *Conn))
- func (s *Server) ListenAndServe() error
- func (s *Server) Middleware(middleware ...Middleware)
- func (s *Server) MiddlewareFunc(middleware ...func(ctx *ReqCtx) error)
- func (s *Server) SendRequest(connID string, method string, params interface{}, ...) (reqID string, err error)
- func (s *Server) SendRequestArr(connID string, method string, resHandler func(ctx *ResCtx) error, ...) (reqID string, err error)
- func (s *Server) UseTLS(cert, privKey, clientCACert []byte) error
- func (s *Server) Wait()
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Conn ¶
type Conn struct {
ID string // Randomly generated unique client connection ID.
Session *cmap.CMap // Thread-safe data store for storing arbitrary data for this connection session.
// contains filtered or unexported fields
}
Conn is a client connection.
func (*Conn) Connect ¶
Connect connects to the given WebSocket server. addr should be formatted as ws://host:port -or- wss://host:port (i.e. ws://127.0.0.1:3000 -or- wss://localhost:3000)
func (*Conn) DisconnHandler ¶
DisconnHandler registers a function to handle disconnection event.
func (*Conn) Middleware ¶
func (c *Conn) Middleware(middleware ...Middleware)
Middleware registers middleware to handle incoming request messages.
func (*Conn) MiddlewareFunc ¶
MiddlewareFunc registers middleware function to handle incoming request messages.
func (*Conn) RemoteAddr ¶
RemoteAddr returns the remote network address.
func (*Conn) SendRequest ¶
func (c *Conn) SendRequest(method string, params interface{}, resHandler func(res *ResCtx) error) (reqID string, err error)
SendRequest sends a JSON-RPC request through the connection with an auto generated request ID. resHandler is called when a response is returned.
func (*Conn) SendRequestArr ¶
func (c *Conn) SendRequestArr(method string, resHandler func(res *ResCtx) error, params ...interface{}) (reqID string, err error)
SendRequestArr sends a JSON-RPC request through the connection, with array params and auto generated request ID. resHandler is called when a response is returned.
func (*Conn) SetDeadline ¶
SetDeadline set the read/write deadlines for the connection, in seconds. Default value for read/write deadline is 300 seconds.
type Middleware ¶
Middleware is the type definition for Neptulon middleware.
type ReqCtx ¶
type ReqCtx struct {
Conn *Conn // Client connection.
Session *cmap.CMap // Session is a data store for storing arbitrary data within this context to communicate with other middleware handling this message.
ID string // Request ID.
Method string // Called method.
Res interface{} // Response to be returned.
Err *ResError // Error to be returned.
// contains filtered or unexported fields
}
ReqCtx is the request context.
type ResCtx ¶
type ResCtx struct {
Conn *Conn // Client connection.
ID string // Message ID.
Success bool // If response is a success or error response.
ErrorCode int // Error code (if any).
ErrorMessage string // Error message (if any).
// contains filtered or unexported fields
}
ResCtx is the response context.
type ResError ¶
type ResError struct {
Code int `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
}
ResError is a JSON-RPC response error object representation for outgoing responses.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a Neptulon server.
func NewServer ¶
NewServer creates a new Neptulon server. addr should be formatted as host:port (i.e. 127.0.0.1:3000)
func (*Server) DisconnHandler ¶
DisconnHandler registers a function to handle client disconnection events.
func (*Server) ListenAndServe ¶
ListenAndServe starts the Neptulon server. This function blocks until server is closed.
func (*Server) Middleware ¶
func (s *Server) Middleware(middleware ...Middleware)
Middleware registers middleware to handle incoming request messages.
func (*Server) MiddlewareFunc ¶
MiddlewareFunc registers middleware function to handle incoming request messages.
func (*Server) SendRequest ¶
func (s *Server) SendRequest(connID string, method string, params interface{}, resHandler func(ctx *ResCtx) error) (reqID string, err error)
SendRequest sends a JSON-RPC request through the connection denoted by the connection ID with an auto generated request ID. resHandler is called when a response is returned.
func (*Server) SendRequestArr ¶
func (s *Server) SendRequestArr(connID string, method string, resHandler func(ctx *ResCtx) error, params ...interface{}) (reqID string, err error)
SendRequestArr sends a JSON-RPC request through the connection denoted by the connection ID, with array params and auto generated request ID. resHandler is called when a response is returned.
Source Files
Directories