Home

Awesome

Hare Sockets ๐Ÿ‡

<img align="right" width="159px" src="./resources/images/small-icon.png">

Go codecov Mentioned in Awesome Go Go Report Card Codacy Badge Maintainability GoDoc Join the chat at https://gitter.im/hare-sockets/community Release License: MIT

Hare is an user-friendly package for sockets in Golang and a CLI tool for sockets interaction. You can send and listen to TCP connections with a few lines of code or commands.

Contents

๐Ÿ–ฅ๏ธ Installation

Installation guide for the CLI Tool and Golang Library.

๐Ÿ’ป CLI Tool

To install the CLI tool, you can install it through Homebrew:

$ brew tap leozz37/hare

$ brew install hare

Or you can install manually with the Makefile script:

$ make install

๐Ÿ‡ Golang Lib

First, you need Go (version 1.12+ is required), then you can install Hare:

$ go get -u "github.com/leozz37/hare"

Import it in your code:

import "github.com/leozz37/hare"

๐Ÿ• Quickstart

Quick start for the CLI Tool and the Golang Library.

๐Ÿ’ป CLI Tool

To use the CLI tool, these are the flags:

  -d string
        Data to be sended
  -h string
        Host address to bo operated (default "localhost")
  -l    Listen to a given address
  -p string
        Port address to bo operated         [REQUIRED]
  -s    Send message to a given address

You can run the --help flag:

$ hare --help

To Listen to port 3000 for example, run:

$ hare -l -p 3000

To Send a payload with the message Hello World to port 3000 for example, run:

$ hare -s -p 3000 -d 'Hello World'

cli-example

๐Ÿ‡ Golang Lib

Sample code for sending payloads:

package main

import (
    "github.com/leozz37/hare"
)

func main() {
    hare.Send(3000, "Hello, World")
}

Sample code for listening a port:

package main

import (
    "fmt"

    "github.com/leozz37/hare"
)

func main() {
    r, _ := hare.Listen("3000")

    for {
        if r.HasNewMessages() {
            fmt.Println(r.GetMessage())
        }
    }
}

๐Ÿ“– Documentation

The library consists of two features: listen and send to a given port. You can check the full documentation on Godoc.

Send

Receives a port and a message, both as string and returns an error (if something goes wrong).

func Send(port, message string) error;

Usage example:

func main() {
    err := hare.Send(3000, "Hello, World")
    if err != nil {
        panic(err)
    }
}

Listen

Receives a port as string and returns a Listener struct and an error (if something goes wrong).

func Listen(port string) (*Listener, error);

Usage example:

func main() {
    r, _ := hare.Listen("3000")
    l, _ := hare.listen("3001")

    for {
        if r.HasNewMessages() {
            fmt.Println(r.GetMessage())
        } else if l.HasNewMessages() {
            fmt.Println(l.GetMessage())
        }
    }

Listener

The Listener struct returned by Listen() function has the following fields:

type Listener struct {
    SocketListener net.Listener
    HasNewMessages func() bool
    GetMessage     func() string
    Stop           func()
}

SocketListener is the socket connection.

listener.SocketListener, _ = net.Listen("tcp", "localhost:" + port)

HasNewMessages() function returns a bool being true with there's a new message:

func main() {
    r, _ := hare.Listen("3000")

    if r.HasNewMessages() {
        fmt.Println("There's a new message!")
    }
}

GetMessage() function returns a string with the last message received on the socket:

func main() {
    r, _ := hare.Listen("3000")

    if r.HasNewMessages() {
        fmt.Println(r.GetMessage())
    }
}

Stop() function closes the listener connection:

func main() {
    r, _ := hare.Listen("3000")
    hare.Send("3000", "Hey beauty")

    r.Stop()

    err := Send("3000", "This should fails")
    if err != nil {
        panic(err)
    }
}

๐Ÿ“™ Examples

You can check the example for code usages, like send and listen samples.

Since Hare only listens and send messages, here's a complete example:

package main

import (
    "fmt"
    "time"

    "github.com/leozz37/hare"
)

func listenSockets(port string) {
    r, _ := hare.Listen(port)

    for {
        if r.HasNewMessages() {
            fmt.Println(r.GetMessage())
        }
    }
}

func main() {
    go listenSockets("3000")
    go listenSockets("3001")

    for {
        hare.Send("3000", "Hello port 3000")
        hare.Send("3001", "Hello port 3001")
        time.Sleep(time.Second)
    }
}

๐Ÿงช Testing

To run the test suite, you can run with:

$ go test

If you want a more detailed report with coverage and an coverage.out file, do the following:

$ go test -v -covermode=count -coverprofile=coverage.out

๐Ÿค Contributing

A full guideline about contributing to Hare can be found in the CONTRIBUTING.md file.

โš–๏ธ License

Hare is released under the MIT License.