harald

README

harald

(like a herald, but better)

Harald has one goal and one goal only: forward traffic if you want it.

Config

Each config looks like this:

{
  "version": 1,
  "log_level": "debug",
  "dial_timeout": "10ms",
  "enable_listeners": false,
  "tls": {},
  "rules": []
}

Fields:

• version: version of the config file, must either be unset or 1.
• log_level: which log messages to emit, see log/slog.Level.UnmarshalJSON for the format details.
• enable_listeners: whether to start the listeners right away.
• dial_timeout: sets the dial timeout for connections to the target. See time.ParseDuration for the format details.
• tls: TLS configuration for the listeners, see TLS for more details.
• rules: contains all forwarding rules, see Rules for more details.

TLS

The TLS config looks like this:

{
  "certificate": "PEM",
  "key": "PEM",
  "client_cas": "PEM",
  "key_log_file": "/some/path",
  "application_protocols": ["http/1.1", "h2"]
}

Rules

A rule looks like this:

{
  "listen": {
    "network": "tcp",
    "address": ":60001"
  },
  "connect": {
    "network": "tcp",
    "address": "localhost:8080"
  }
}

The listen key specifies how and where to listen and the connect settings will be used to connect to the target address. For more details about the listen options see the net.Listen documentation, for the connect details see net.Dial.

Documentation

Overview

Package harald contains the core logic of harald.

Harald is a great guy. He takes care of forwarding connections and listens to your needs. Get him started with SIGUSR1, stop him with SIGUSR2 and shut him down for good with SIGTERM. Currently only unix-like systems (as determined by the go build constraint `unix`) are supported due to the dependency to the process signals.

Any logging is done through the default logger of log/slog. Consult the documentation for how to configure it.

Index

• Constants
• func Harald(c Config, signals <-chan os.Signal) error
• type Config
• type ConfigVersion
  • func (v ConfigVersion) Get() int
• type Duration
  • func (d *Duration) Duration() time.Duration
  • func (d *Duration) UnmarshalText(text []byte) error
• type ForwardRule
  • func (r ForwardRule) Forwarder(tlsConf *tls.Config, dialTimeout time.Duration) *Forwarder
• type Forwarder
  • func (f *Forwarder) Start() (err error)
  • func (f *Forwarder) Stop()
  • func (f *Forwarder) String() string
• type Forwarders
  • func (forwarders Forwarders) Start()
  • func (forwarders Forwarders) Stop()
• type NetConf
• type TLS
  • func (t *TLS) Config() (conf *tls.Config, err error)

Constants

const (
	KeyForwarder    = "forwarder"
	KeyError        = "error"
	KeySignal       = "signal"
	KeyPid          = "pid"
	KeyBytesWritten = "bytes-written"
	KeyConnId       = "conn-id"
)

Functions

func Harald

func Harald(c Config, signals <-chan os.Signal) error

Harald is the main entrypoint. The config controls the behaviour and the signals channel is used to bring up / shut down the listeners and stop the execution. The channel should be subscribed to SIGTERM, SIGUSR1 and SIGUSR2.

Types

type Config

type Config struct {
	ConfigVersion
	LogLevel        slog.Level    `json:"log_level" yaml:"log_level"`
	DialTimeout     Duration      `json:"dial_timeout" yaml:"dial_timeout"`
	EnableListeners bool          `json:"enable_listeners" yaml:"enable_listeners"`
	TLS             *TLS          `json:"tls" yaml:"tls"`
	Rules           []ForwardRule `json:"rules" yaml:"rules"`
}

type ConfigVersion

type ConfigVersion struct {
	Version *int `json:"version" yaml:"version"`
}

func (ConfigVersion) Get

func (v ConfigVersion) Get() int

type Duration

type Duration time.Duration

func (*Duration) Duration

func (d *Duration) Duration() time.Duration

func (*Duration) UnmarshalText

func (d *Duration) UnmarshalText(text []byte) error

type ForwardRule

type ForwardRule struct {
	// Listen parameters to listen for new connections.
	Listen NetConf `json:"listen" yaml:"listen"`
	// Connect parameters
	Connect NetConf `json:"connect" yaml:"connect"`
}

func (ForwardRule) Forwarder

func (r ForwardRule) Forwarder(tlsConf *tls.Config, dialTimeout time.Duration) *Forwarder

Forwarder creates the matching Forwarder to the rule and the given additional parameters. If tlsConf is nil no TLS will be used to listen for new connections.

type Forwarder

type Forwarder struct {
	ForwardRule
	// contains filtered or unexported fields
}

func (*Forwarder) Start

func (f *Forwarder) Start() (err error)

Start opens a new listener.

func (*Forwarder) Stop

func (f *Forwarder) Stop()

Stop will close the listener if it is open. The reference to the listener is also set to nil to prevent further usage. TODO: does this need explicit synchronization?

func (*Forwarder) String

func (f *Forwarder) String() string

String representation of the Forwarder. The format of the addresses is inspired by the '-i' argument of lsof.

type Forwarders

type Forwarders []*Forwarder

Forwarders maintains a list of pointers to Forwarder. It holds pointers because each struct may maintain data that can not be copied.

func (Forwarders) Start

func (forwarders Forwarders) Start()

Start all forwarders in the list. Logs errors encountered while starting a forwarder but continues starting the forwarders.

func (Forwarders) Stop

func (forwarders Forwarders) Stop()

Stop all forwarders in the list.

type NetConf

type NetConf struct {
	Network string `json:"network" yaml:"network"`
	Address string `json:"address" yaml:"address"`
}

type TLS

type TLS struct {
	Certificate string `json:"certificate" yaml:"certificate"`
	Key         string `json:"key" yaml:"key"`
	ClientCAs   string `json:"client_cas" yaml:"client_cas"`
	KeyLogFile  string `json:"key_log_file" yaml:"key_log_file"`
	// ApplicationProtocols offered via ALPN in order of preference. See the
	// IANA registry for a list of options:
	// https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids
	ApplicationProtocols []string `json:"application_protocols" yaml:"application_protocols"`
}

TLS configuration for the server side.

func (*TLS) Config

func (t *TLS) Config() (conf *tls.Config, err error)