tunnel

README

= Tunnel.go

Is a dead simple messaging system written in Go. It aims to facilitate the dialogue and messages exchange between services.

It's based on top of TCP with a custom protocol.

See `https://github.com/codingLayce/tunnel-server` for a Tunnel server command tool.

== Go Client

Client SDK in Golang to communicate with a Tunnel server.

=== Connect to a Tunnel server

[source,Go]
----
    import "github.com/codingLayce/tunnel.go"

    func main() {
        client, err := tunnel.Connect("tunnel.server.addr:19917")
        if err != nil {
            panic(err)
        }
        defer client.Stop() // Don't forget for graceful shutdown
    }
----

=== Create a Brodcast Tunnel

After a successful call to `CreateBTunnel` a broadcast Tunnel is created server-side.

[source,Go]
----
    import "github.com/codingLayce/tunnel.go"

    func main() {
        // ... client setup ...

        err := client.CreateBTunnel("MyTunnel")
        if err != nil {
            panic(err)
        }
    }
----

=== Broadcast a message

After a successful call to `PublishMessage` the given message will be broadcast to all listeners.

[source,Go]
----
    import "github.com/codingLayce/tunnel.go"

    func main() {
        // ... client setup ...

        err := client.PublishMessage("MyTunnel", "Lovely message")
        if err != nil {
            panic(err)
        }
    }
----

=== Listen to Tunnel

After a successful call to `ListenTunnel` when a message arrives to the client, it will invoke the given callback.

[source,Go]
----
    import "github.com/codingLayce/tunnel.go"

    func main() {
        // ... client setup ...

        err := client.ListenTunnel("MyTunnel", func(msg string){
            fmt.Printf("Message received: %s\n", msg)
        })
        if err != nil {
            panic(err)
        }
    }
----

Documentation

Index

• type Client
  • func Connect(addr string) (*Client, error)
  • func (c *Client) CreateBTunnel(name string) error
  • func (c *Client) ListenTunnel(name string, callback func(string)) error
  • func (c *Client) PublishMessage(tunnelName, message string) error
  • func (c *Client) Stop()
• type TCPClient

Types

type Client

type Client struct {
	Logger *slog.Logger
	// contains filtered or unexported fields
}

func Connect

func Connect(addr string) (*Client, error)

Connect creates a new Client and connects to a Tunnel server. You must call Stop method when the client is no longer needed (to gracefully wait for the internal routines to finish).

Internally the Client is going to keep the connection with the server active (by retrying to connect with the Tunnel server if the connection is lost).

func (*Client) CreateBTunnel

func (c *Client) CreateBTunnel(name string) error

CreateBTunnel asks the server to create a new Broadcast Tunnel. Returns an error if the name is invalid or if the server nack the request.

func (*Client) ListenTunnel

func (c *Client) ListenTunnel(name string, callback func(string)) error

ListenTunnel makes the client listening for the given Tunnel's name messages. When a message is received, the callback function is invoked.

func (*Client) PublishMessage

func (c *Client) PublishMessage(tunnelName, message string) error

PublishMessage publishes the given message to the given Tunnel. Returns an error if the server doesn't accept the message.

func (*Client) Stop

func (c *Client) Stop()

Stop stops the internal client. Client is no longer usable after stopping it.

type TCPClient

type TCPClient interface {
	Connect() error
	Stop()
	Done() <-chan struct{}
	Send(payload []byte) error
}