libchanner

README

libchanner

This package makes it simple to plug into the power of the libchan RPC library. Elegant simplicity is achieved by providing a set of API functions which perform the repetitive server and client setup.

The ability to stop the server at any time is also included out of the box thanks to stoppableListener.

Get it

go get -u https://github.com/jaytaylor/libchanner/...

Important

This package only works with libchan v0.1.x series.

Code layout

Server resources are in chan_server.go

Client resources are in conn.go

Example usage

See example/main.go for the fully working example.

run it:

go run example/main.go

output:

Successfully decoded time struct! value=2015-04-17 11:34:01.046453821 -0700 PDT

Abreviated highlights:

(for demonstration purposes only, error checking omitted for brevity)

type (
    RemoteRequest struct {
        Command    string
        StatusChan libchan.Sender
    }

    RemoteResponse struct {
        StatusCode int
        Message    string
        Data       []byte
    }
)

func main() {
    // Server setup.
    cs := libchanner.NewChanServer("127.0.0.1:8001", receiverHandler)
    cs.Start()

    // Shutdown the server after we're done.
    defer func() {
        cs.Stop()
    }()

    // Client setup.
    ch, _ := libchanner.DialChan("tcp", "127.0.0.1:8001")

    // Send request.
    req := &RemoteRequest{
        Command:    "CurrentTime",
        StatusChan: ch.RemoteSender,
    }
    ch.Sender.Send(req)

    // Get response.
    response := &RemoteResponse{}
    ch.Receiver.Receive(response)

    // Now do anything you want with the response!
}

// receiverHandler conforms to the ReceiverHandler type.
func receiverHandler(receiver libchan.Receiver) {
    for {
        req := &RemoteRequest{}
        if err := receiver.Receive(req); err != nil {
            panic(fmt.Sprintf("unexpected error receiving remote struct: %s", err))
            break
        }

        response := requestHandler(req)

        if err := req.StatusChan.Send(response); err != nil {
            panic(fmt.Sprintf("unexpected error sending result: %s", err))
        }
    }
}

// requestHandler is the core remote request processor.
func requestHandler(rr *RemoteRequest) *RemoteResponse {
    response := &RemoteResponse{}

    switch rr.Command {
    case "CurrentTime":
        data, err := json.Marshal(time.Now())
        if err != nil {
            response.StatusCode = 1
            response.Message = err.Error()
            break
        }
        response.Data = data

    default:
        response.StatusCode = 1
        response.Message = "unknown command"
    }

    return response
}

also see the unit-tests for additional example usage.

Unit-tests

Running the unit-tests is straightforward and standard:

go test

License

Permissive MIT license.

Contact

You are more than welcome to open issues and send pull requests if you find a bug or want a new feature.

If you appreciate this library please feel free to drop me a line and let me know! It's always nice to hear from people who have benefitted from my work.

Email: jay at (my github username).com

Twitter: @jtaylor

Related work

• netchan (deprecated)

• fatchan

Documentation

Index

• Variables
• type Chan
  • func DialChan(network string, addr string) (*Chan, error)
  • func DialChanTimeout(network string, addr string, timeout time.Duration) (*Chan, error)
• type ChanServer
  • func NewChanServer(laddr string, receiverHandler ReceiverHandler) *ChanServer
  • func (cs *ChanServer) Addr() net.Addr
  • func (cs *ChanServer) Start() error
  • func (cs *ChanServer) Stop() error
• type ReceiverHandler

Variables

var (
	AlreadyRunningError = errors.New("already running")
	NotRunningError     = errors.New("not running")
)

Types

type Chan

type Chan struct {
	Sender       libchan.Sender
	Receiver     libchan.Receiver
	RemoteSender libchan.Sender
	Transport    *spdy.Transport
}

func DialChan

func DialChan(network string, addr string) (*Chan, error)

NewChannel opens a new libchan SPDY channel to the specified address (host:port).

Don't forget to close the transport after you're done using the channel.

func DialChanTimeout

func DialChanTimeout(network string, addr string, timeout time.Duration) (*Chan, error)

type ChanServer

type ChanServer struct {
	Quiet bool // When true, logging will be suppressed.
	// contains filtered or unexported fields
}

ChanServer provides a generic stoppable TCP server which is wired to any desired channel receiver handler.

func NewChanServer

func NewChanServer(laddr string, receiverHandler ReceiverHandler) *ChanServer

NewChanServer creates a new instance of TCP ChanServer.

laddr is a string representing the interface and port to listen on. e.g. ":8001", "127.0.0.1:8001", etc.

receiverHandler is a ReceiverHandler function to send inbound channel requests to.

func (*ChanServer) Addr

func (cs *ChanServer) Addr() net.Addr

Addr returns the listener address and port.

func (*ChanServer) Start

func (cs *ChanServer) Start() error

Start launches the ChanServer.

func (*ChanServer) Stop

func (cs *ChanServer) Stop() error

Stop terminates the ChanServer.

type ReceiverHandler

type ReceiverHandler func(receiver libchan.Receiver)

ReceiverHandler is the type of the handler function to pass in when creating a new ChanServer.