legacy

Documentation

Index

• func SlogToLog15(slogger *slog.Logger) log15.Logger
• type Conn
• type ConnectOption
  • func WithAuthtoken(token string) ConnectOption
  • func WithCA(pool *x509.CertPool) ConnectOption
  • func WithClientInfo(clientType, version string, comments ...string) 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 log15.Logger) ConnectOption
  • func WithMetadata(meta string) ConnectOption
  • func WithMultiLeg(enable bool) ConnectOption
  • func WithRestartHandler(handler ServerCommandHandler) ConnectOption
  • func WithServer(addr string) ConnectOption
  • func WithStopHandler(handler ServerCommandHandler) ConnectOption
  • func WithTLSConfig(tlsCustomizer func(*tls.Config)) ConnectOption
  • func WithUpdateHandler(handler ServerCommandHandler) ConnectOption
• type Dialer
• type Error
• type ServerCommandHandler
• type Session
  • func Connect(ctx context.Context, opts ...ConnectOption) (Session, error)
• type SessionConnectHandler
• type SessionDisconnectHandler
• type SessionHeartbeatHandler
• type Tunnel
• type TunnelInfo

Functions

func SlogToLog15

func SlogToLog15(slogger *slog.Logger) log15.Logger

SlogToLog15 converts a slog.Logger to a log15.Logger for use with the legacy package

Types

type Conn

type Conn interface {
	net.Conn
	// Proto returns the tunnel protocol (http, https, tls, or tcp) for this connection.
	Proto() string

	// PassthroughTLS returns whether this connection contains an end-to-end tls
	// connection.
	PassthroughTLS() bool
}

Conn is a connection from an ngrok Tunnel.

It implements the standard net.Conn interface and has additional methods to query ngrok-specific connection metadata.

Because the net.Listener interface requires `Accept` to return a net.Conn, you will have to type-assert it to an ngrok Conn: ``` conn, _ := tun.Accept() ngrokConn := conn.(ngrok.Conn) ```

type ConnectOption

type ConnectOption func(*connectConfig)

ConnectOption is passed to Connect to customize session connection and establishment.

func WithAuthtoken

func WithAuthtoken(token string) ConnectOption

WithAuthtoken configures the session to authenticate with the provided authtoken. You can find your existing authtoken or create a new one in the ngrok dashboard.

See the authtoken parameter in the ngrok docs for additional details.

func WithCA

func WithCA(pool *x509.CertPool) ConnectOption

WithCA configures the CAs used to validate the TLS certificate returned by the ngrok service while establishing the session. Use this option only if you are connecting through a man-in-the-middle or deep packet inspection proxy.

See the root_cas parameter in the ngrok docs for additional details.

func WithClientInfo

func WithClientInfo(clientType, version string, comments ...string) ConnectOption

WithClientInfo configures client type and version information for applications built on this library. This is a way for consumers of this library to identify themselves to the ngrok service.

This will add a new entry to the `User-Agent` field in the "most significant" (first) position.

func WithConnectHandler

func WithConnectHandler(handler SessionConnectHandler) ConnectOption

WithConnectHandler configures a function which is called each time the ngrok Session successfully connects to the ngrok service. Use this option to receive events when the Session successfully connects or reconnects after a disconnection due to network failure.

func WithDialer

func WithDialer(dialer Dialer) ConnectOption

WithDialer configures the session to use the provided Dialer when establishing a connection to the ngrok service. This option will cause [WithProxyURL] to be ignored.

func WithDisconnectHandler

func WithDisconnectHandler(handler SessionDisconnectHandler) ConnectOption

WithDisconnectHandler configures a function which is called each time the ngrok Session disconnects from the ngrok service. Use this option to detect when the ngrok session has gone temporarily offline.

This handler will be called every time the Session encounters an error during or after connection. It may be called multiple times in a row; it may be called before any Connect handler is called and before Connect returns.

If this function is called with a nil error, the Session has stopped and will not reconnect, usually due to [Session.Close] being called.

func WithHeartbeatHandler

func WithHeartbeatHandler(handler SessionHeartbeatHandler) ConnectOption

WithHeartbeatHandler configures a function which is called each time the Session successfully heartbeats the ngrok service. The callback receives the latency of the round trip time from initiating the heartbeat to receiving an acknowledgement back from the ngrok service.

func WithHeartbeatInterval

func WithHeartbeatInterval(interval time.Duration) ConnectOption

WithHeartbeatInterval configures how often the session will send heartbeat messages to the ngrok service to check session liveness.

See the heartbeat_interval parameter in the ngrok docs for additional details.

func WithHeartbeatTolerance

func WithHeartbeatTolerance(tolerance time.Duration) ConnectOption

WithHeartbeatTolerance configures the duration to wait for a response to a heartbeat before assuming the session connection is dead and attempting to reconnect.

See the heartbeat_tolerance parameter in the ngrok docs for additional details.

func WithLogger

func WithLogger(logger log15.Logger) ConnectOption

WithLogger configures a logger to receive log messages from the Session. Accepts a log15.Logger directly.

func WithMetadata

func WithMetadata(meta string) ConnectOption

WithMetadata configures the opaque, machine-readable metadata string for this session. Metadata is made available to you in the ngrok dashboard and the Agents API resource. It is a useful way to allow you to uniquely identify sessions. We suggest encoding the value in a structured format like JSON.

See the metadata parameter in the ngrok docs for additional details.

func WithMultiLeg

func WithMultiLeg(enable bool) ConnectOption

WithMultiLeg as true allows connecting to the ngrok service on secondary legs.

func WithRestartHandler

func WithRestartHandler(handler ServerCommandHandler) ConnectOption

WithRestartHandler configures a function which is called when the ngrok service requests that this Session restarts. Your application may choose to interpret this callback as a request to reconnect the Session or restart the entire process.

Errors returned by this function will be visible to the ngrok dashboard or API as the response to the Restart operation.

Do not block inside this callback. It will cause the Dashboard or API Restart operation to hang. Do not call Session.Close or os.Exit inside this callback, it will also cause the operation to hang.

Instead, either spawn a goroutine to asynchronously restart, or return an error.

func WithServer

func WithServer(addr string) ConnectOption

WithServer configures the network address to dial to connect to the ngrok service. Use this option only if you are connecting to a custom agent ingress.

See the server_addr parameter in the ngrok docs for additional details.

func WithStopHandler

func WithStopHandler(handler ServerCommandHandler) ConnectOption

WithStopHandler configures a function which is called when the ngrok service requests that this Session stops. Your application may choose to interpret this callback as a request to terminate the Session or the entire process.

Errors returned by this function will be visible to the ngrok dashboard or API as the response to the Stop operation.

Do not block inside this callback. It will cause the Dashboard or API Stop operation to hang. Do not call Session.Close or os.Exit inside this callback, it will also cause the operation to hang.

Instead, either return an error or if you intend to Stop, spawn a goroutine to asynchronously call Session.Close or os.Exit.

func WithTLSConfig

func WithTLSConfig(tlsCustomizer func(*tls.Config)) ConnectOption

WithTLSConfig allows customization of the TLS connection made from the agent to the ngrok service. Customization is applied after the WithServer and WithCA options are applied.

func WithUpdateHandler

func WithUpdateHandler(handler ServerCommandHandler) ConnectOption

WithUpdateHandler configures a function which is called when the ngrok service requests that the application running this Session updates. Your application may use this callback to trigger a check for a newer version followed by an update and restart if one exists.

Errors returned by this function will be visible to the ngrok dashboard or API as the response to the Update operation.

Do not block inside this callback. It will cause the Dashboard or API Update operation to hang. Do not call Session.Close or os.Exit inside this callback, it will also cause the operation to hang.

Instead, spawn a goroutine to asynchronously handle the update process or return an error if there is no newer version to update to.

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.
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

Dialer is the interface a custom connection dialer must implement for use with the WithDialer option.

type Error

type Error interface {
	error
	// Msg returns the error string without the error code.
	Msg() string
	// ErrorCode returns the ngrok error code, if one exists.
	ErrorCode() string
}

Error is an error enriched with a specific ErrorCode. All ngrok error codes are documented at https://ngrok.com/docs/errors.

An Error can be extracted from a generic error using errors.As.

Example:

var nerr ngrok.Error
if errors.As(err, &nerr) {
  fmt.Printf("%s: %s\n", nerr.ErrorCode(), nerr.Msg())
}

type ServerCommandHandler

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

ServerCommandHandler is the callback type for WithStopHandler

type Session

type Session interface {
	// Listen creates a new Tunnel which will listen for new inbound
	// connections. The returned Tunnel object is a net.Listener.
	Listen(ctx context.Context, cfg config.Tunnel) (Tunnel, error)

	// Warnings returns a list of warnings generated for the session on connect/auth
	Warnings() []error

	// Close ends the ngrok session. All Tunnel objects created by Listen
	// on this session will be closed.
	Close() error
}

Session encapsulates an established session with the ngrok service. Sessions recover from network failures by automatically reconnecting.

func Connect

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

Connect begins a new ngrok Session by connecting to the ngrok service, retrying transient failures if they occur.

Connect blocks until the session is successfully established or fails with an error that will not be retried. Customize session connection behavior with ConnectOption arguments.

type SessionConnectHandler

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

SessionConnectHandler is the callback type for WithConnectHandler

type SessionDisconnectHandler

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

SessionDisconnectHandler is the callback type for WithDisconnectHandler

type SessionHeartbeatHandler

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

SessionHeartbeatHandler is the callback type for [WithHearbeatHandler]

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

	// Information associated with the tunnel
	TunnelInfo

	// Close is a convenience method for calling Tunnel.CloseWithContext
	// with a context that has a timeout of 5 seconds. This also allows the
	// Tunnel to satisfy the io.Closer interface.
	Close() error

	// CloseWithContext closes the Tunnel. Closing a tunnel is an operation
	// that involves sending a "close" message over the parent session.
	// Since this is a network operation, it is most correct to provide a
	// context with a timeout.
	CloseWithContext(context.Context) error

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

Tunnel is a net.Listener created by a call to [Listen] or Session.Listen. A Tunnel allows your application to receive net.Conn connections from endpoints created on the ngrok service.

type TunnelInfo

type TunnelInfo interface {
	// ForwardsTo returns a human-readable string presented in the ngrok
	// dashboard and the Tunnels API. Use config.WithForwardsTo when
	// calling Session.Listen to set this value explicitly.
	ForwardsTo() string
	// ID returns a tunnel's unique ID.
	ID() string
	// Labels returns the labels set by config.WithLabel if this is a
	// labeled tunnel. Non-labeled tunnels will return an empty map.
	Labels() map[string]string
	// Metadata returns the arbitrary metadata string for this tunnel.
	Metadata() string
	// Proto returns the protocol of the tunnel's endpoint.
	// Labeled tunnels will return the empty string.
	Proto() string
	// URL returns the tunnel endpoint's URL.
	// Labeled tunnels will return the empty string.
	URL() string
}

TunnelInfo implementations contain metadata about a Tunnel.