Hare Sockets 🐇

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
• Quickstart
• Documentation
• Examples
• Testing
• Contributing
• License

🖥️ 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'

🐇 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.