ngrok

README

ngrok-go

Note: This is alpha-quality software. Interfaces are subject to change without warning

This is the ngrok agent in library form, suitable for integrating directly into an application. See example/http.go for example usage, or the tests in online_test.go.

License

ngrok-go is licensed under the terms of the MIT license.

See LICENSE for details.

Documentation

Index

• Constants
• type ConnectOption
  • func WithAuthtoken(token string) ConnectOption
  • func WithAuthtokenFromEnv() ConnectOption
  • func WithCA(pool *x509.CertPool) ConnectOption
  • func WithConnectHandler(handler SessionConnectHandler) ConnectOption
  • func WithDialer(dialer Dialer) ConnectOption
  • func WithDisconnectHandler(handler SessionDisconnectHandler) ConnectOption
  • func WithHeartbeatHandler(handler SessionHeartbeatHandler) ConnectOption
  • func WithHeartbeatInterval(interval time.Duration) ConnectOption
  • func WithHeartbeatTolerance(tolerance time.Duration) ConnectOption
  • func WithLogger(logger log.Logger) ConnectOption
  • func WithMetadata(meta string) ConnectOption
  • func WithProxyURL(url *url.URL) ConnectOption
  • func WithRegion(region string) ConnectOption
  • func WithServer(addr string) ConnectOption
  • func WithStopHandler(handler ServerCommandHandler) ConnectOption
• type Dialer
• type ServerCommandHandler
• type Session
  • func Connect(ctx context.Context, opts ...ConnectOption) (Session, error)
• type SessionConnectHandler
• type SessionDisconnectHandler
• type SessionHeartbeatHandler
• type Tunnel
  • func StartTunnel(ctx context.Context, tunnelConfig config.Tunnel, connectOpts ...ConnectOption) (Tunnel, error)

Constants

const (
	// The US ngrok region.
	RegionUS = "us"
	// The Europe ngrok region.
	RegionEU = "eu"
	// The South America ngrok region.
	RegionSA = "sa"
	// The Asia-Pacific ngrok region.
	RegionAP = "ap"
	// The Australia ngrok region.
	RegionAU = "au"
	// The Japan ngrok region.
	RegionJP = "jp"
	// The India ngrok region.
	RegionIN = "in"
)

Types

type ConnectOption

type ConnectOption func(*connectConfig)

func WithAuthtoken

func WithAuthtoken(token string) ConnectOption

Use the provided Authtoken to authenticate this session. Sets the [ConnectConfig].Authtoken field.

func WithAuthtokenFromEnv

func WithAuthtokenFromEnv() ConnectOption

WithAuthtokenFromEnv populates the authtoken with one defined in the standard NGROK_AUTHTOKEN environment variable. Sets the [ConnectConfig].Authtoken field.

func WithCA

func WithCA(pool *x509.CertPool) ConnectOption

Use the provided x509.CertPool to authenticate the ngrok server certificate. Sets the [ConnectConfig].CAPool field.

func WithConnectHandler

func WithConnectHandler(handler SessionConnectHandler) ConnectOption

func WithDialer

func WithDialer(dialer Dialer) ConnectOption

Use the provided dialer for establishing a TCP connection to the ngrok server. Sets the [ConnectConfig].Dialer field. Takes precedence over ProxyURL if both are specified.

func WithDisconnectHandler

func WithDisconnectHandler(handler SessionDisconnectHandler) ConnectOption

func WithHeartbeatHandler

func WithHeartbeatHandler(handler SessionHeartbeatHandler) ConnectOption

func WithHeartbeatInterval

func WithHeartbeatInterval(interval time.Duration) ConnectOption

Set the heartbeat interval for the session. This value determines how often we send application level heartbeats to the server go check connection liveness.

func WithHeartbeatTolerance

func WithHeartbeatTolerance(tolerance time.Duration) ConnectOption

Set the heartbeat tolerance for the session. If the session's heartbeats are outside of their interval by this duration, the server will assume the session is dead and close it.

func WithLogger

func WithLogger(logger log.Logger) ConnectOption

Log to a simplified logging interface. This is a "lowest common denominator" interface that should be simple to adapt other loggers to. Examples are provided in `log15adapter` and `pgxadapter`. If the provided `Logger` also implements the `log15.Logger` interface, it will be used directly.

func WithMetadata

func WithMetadata(meta string) ConnectOption

Use the provided opaque metadata string for this session. Sets the [ConnectConfig].Metadata field.

func WithProxyURL

func WithProxyURL(url *url.URL) ConnectOption

Proxy requests through the server identified by the provided URL when using the default Dialer. Sets the [ConnectConfig].ProxyURL field. Ignored if a custom Dialer is in use.

func WithRegion

func WithRegion(region string) ConnectOption

Connect to the ngrok server in a specific region. Overwrites the [ConnectConfig].ServerAddr field.

func WithServer

func WithServer(addr string) ConnectOption

Connect to the provided ngrok server. Sets the [ConnectConfig].Server field.

func WithStopHandler

func WithStopHandler(handler ServerCommandHandler) ConnectOption

type Dialer

type Dialer interface {
	// Connect to an address on the named network.
	// See the documentation for [net.Dial].
	Dial(network, address string) (net.Conn, error)
	// Connect to an address on the named network with the provided
	// [context.Context].
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

Interface implemented by supported dialers for establishing a connection to the ngrok server.

type ServerCommandHandler

type ServerCommandHandler func(ctx context.Context, sess Session) error

type Session

type Session interface {
	// Start a new tunnel over the ngrok session.
	StartTunnel(ctx context.Context, cfg config.Tunnel) (Tunnel, error)

	// Close the ngrok session.
	// This also closes all existing tunnels tied to the session.
	Close() error
}

The interface implemented by an ngrok session object.

func Connect

func Connect(ctx context.Context, opts ...ConnectOption) (Session, error)

Connect to the ngrok server and start a new session.

type SessionConnectHandler

type SessionConnectHandler func(ctx context.Context, sess Session)

type SessionDisconnectHandler

type SessionDisconnectHandler func(ctx context.Context, sess Session, err error)

type SessionHeartbeatHandler

type SessionHeartbeatHandler func(ctx context.Context, sess Session, latency time.Duration)

type Tunnel

type Tunnel interface {
	// Every Tunnel is a net.Listener. It can be plugged into any existing
	// code that expects a net.Listener seamlessly without any changes.
	net.Listener

	// Returns the ForwardsTo string for this tunnel.
	ForwardsTo() string
	// Returns the Metadata string for this tunnel.
	Metadata() string
	// Returns this tunnel's ID.
	ID() string

	// Returns this tunnel's protocol.
	// Will be empty for labeled tunnels.
	Proto() string
	// Returns the URL for this tunnel.
	// Will be empty for labeled tunnels.
	URL() string

	// Returns the labels for this tunnel.
	// Will be empty for non-labeled tunnels.
	Labels() map[string]string

	// Session returns the tunnel's parent Session object that it
	// was started on.
	Session() Session

	// Convenience method that calls `CloseWithContext` with a default timeout
	// of 5 seconds.
	Close() error
	// Closing a tunnel is an operation that involves sending a "close" message
	// over the existing session. Since this is subject to network latency,
	// packet loss, etc., it is most correct to provide a context. See also
	// `Close`, which matches the `io.Closer` interface method.
	CloseWithContext(context.Context) error
}

An ngrok tunnel.

func StartTunnel

func StartTunnel(ctx context.Context, tunnelConfig config.Tunnel, connectOpts ...ConnectOption) (Tunnel, error)

Create a new ngrok session and start a tunnel. Shorthand for a Connect followed by a Session.StartTunnel. If an error is encoutered when starting the tunnel, but after a session has been established, both the Session and error return values will be non-nil.