README
¶
bore-go
A small Go client library for the bore TCP tunnel server. This is client-only and mirrors the Rust protocol implementation (null-delimited JSON frames, optional HMAC auth, and on-demand connection proxying).
Features
- Connect to a
boreserver and request a public port - Proxy inbound connections to a local TCP service
- Optional secret authentication (HMAC-SHA256)
- Runtime status helpers: connection state, last heartbeat, active proxies
Installation
Install via:
go get github.com/FrontMage/bore-go
Usage
package main
import (
"context"
"log"
borego "github.com/FrontMage/bore-go"
)
func main() {
// Forward local port 8000 to the bore server.
client, err := borego.NewClient("localhost", 8000, "0.0.0.0", 0, "")
if err != nil {
log.Fatalf("failed to start client: %v", err)
}
log.Printf("public port assigned: %d", client.RemotePort())
ctx := context.Background()
if err := client.Listen(ctx); err != nil {
log.Fatalf("listen exited: %v", err)
}
}
With authentication
client, err := borego.NewClient("localhost", 8000, "0.0.0.0", 0, "my-secret")
Status helpers
if client.Connected() {
log.Println("control connection is alive")
}
if t, ok := client.LastHeartbeat(); ok {
log.Printf("last heartbeat: %s", t)
}
log.Printf("active proxies: %d", client.ActiveProxies())
Stopping
_ = client.Close()
Related
- Upstream Rust project: https://github.com/ekzhang/bore
Keywords
bore, bore client, tcp tunnel, port forwarding, reverse proxy, nat traversal, localtunnel, ngrok
Notes
- The default control port is
7835(same as the Rust implementation). - When
desiredPortis0, the server picks a random available port. Listenblocks; run it in a goroutine if you need async control.
License
MIT
Documentation
¶
Index ¶
- Constants
- Variables
- type Authenticator
- type Client
- type Delimited
- func (d *Delimited) BufferedData() ([]byte, error)
- func (d *Delimited) Close() error
- func (d *Delimited) RawConn() net.Conn
- func (d *Delimited) RecvFrame(timeout bool) ([]byte, bool, error)
- func (d *Delimited) RecvServer(timeout bool) (ServerMessage, bool, error)
- func (d *Delimited) SendJSON(v interface{}) error
- type ServerMessage
- type ServerMessageKind
Constants ¶
const ( // ControlPort is the TCP port used by the bore control channel. ControlPort = 7835 // MaxFrameLength caps the length of a JSON frame (excluding the trailing null byte). MaxFrameLength = 256 // NetworkTimeout defines the timeout for dialing and initial protocol steps. NetworkTimeout = 3 * time.Second )
Variables ¶
var ( // ErrUnexpectedEOF indicates that the server closed the connection unexpectedly. ErrUnexpectedEOF = errors.New("unexpected EOF from server") // ErrUnexpectedHandshake indicates an unexpected message during authentication. ErrUnexpectedHandshake = errors.New("unexpected handshake message") )
Functions ¶
This section is empty.
Types ¶
type Authenticator ¶
type Authenticator struct {
// contains filtered or unexported fields
}
Authenticator replies to server challenges using a shared secret.
func NewAuthenticator ¶
func NewAuthenticator(secret string) *Authenticator
NewAuthenticator constructs an authenticator from a secret string.
func (*Authenticator) Answer ¶
func (a *Authenticator) Answer(challenge uuid.UUID) string
Answer creates the HMAC tag for a challenge UUID.
func (*Authenticator) ClientHandshake ¶
func (a *Authenticator) ClientHandshake(conn *Delimited) error
ClientHandshake answers the server's challenge when authentication is enabled.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client maintains a control connection to a bore server and proxies incoming connections.
func NewClient ¶
func NewClient(localHost string, localPort uint16, to string, desiredPort uint16, secret string) (*Client, error)
NewClient connects to the remote server and performs the initial handshake.
func (*Client) ActiveProxies ¶
ActiveProxies returns the number of currently active proxy connections.
func (*Client) LastHeartbeat ¶
LastHeartbeat returns the last heartbeat time and whether one has been observed.
func (*Client) Listen ¶
Listen waits for new connection notifications from the server and proxies them.
func (*Client) RemotePort ¶
RemotePort returns the public port assigned by the server.
type Delimited ¶
type Delimited struct {
// contains filtered or unexported fields
}
Delimited wraps a TCP connection with null-delimited JSON framing.
func NewDelimited ¶
NewDelimited constructs a framed connection.
func (*Delimited) BufferedData ¶
BufferedData drains any data currently buffered by the reader.
func (*Delimited) RecvFrame ¶
RecvFrame reads the next null-delimited JSON frame. The returned bool is false on clean EOF.
func (*Delimited) RecvServer ¶
func (d *Delimited) RecvServer(timeout bool) (ServerMessage, bool, error)
RecvServer reads and decodes a server message.
type ServerMessage ¶
type ServerMessage struct {
Kind ServerMessageKind
Port uint16
ID uuid.UUID
ErrorText string
}
ServerMessage is a parsed message sent from the bore server.
type ServerMessageKind ¶
type ServerMessageKind string
ServerMessageKind enumerates message types sent from the server.
const ( ServerHello ServerMessageKind = "hello" ServerChallenge ServerMessageKind = "challenge" ServerHeartbeat ServerMessageKind = "heartbeat" ServerConnection ServerMessageKind = "connection" ServerError ServerMessageKind = "error" )
Source Files
Directories