expose

Documentation

Overview

Expose serves as an abstract mechanism for exposing local services to the world.

It supports both HTTP services (to which it can proxy directly) and plain-old TCP ports, which it exposes via websockets.

Exposing starts by creating an Exposer, which can be one of several types depending on available resorces. That Exposer is then used to create Exposures for specific backend services. Each Exposure then provides a GetURL method that returns a public URL which will reach the exposed service.

Index

• type Exposer
  • func NewLocal(publicIP net.IP) (Exposer, error)
  • func NewStatelessDNS(publicIP net.IP, publicPort uint16, hostDomain, statelessDNSSecret string, ...) (Exposer, error)
  • func NewWST(serverURL, wstAudience, workerGroup, workerId string, authClient authClient) (Exposer, error)
• type Exposure

Types

type Exposer

type Exposer interface {
	// Expose an HTTP service.  The resulting URL will proxy directly to this
	// service, including streaming bidirectional communication
	ExposeHTTP(targetPort uint16) (Exposure, error)

	// Expose a TCP port.  The resulting URL will proxy websocket connections
	// to the given port.  For each new websocket connection, a new TCP
	// connection is initiated to the backend service.  The payload of each
	// incoming websocket message is written to the TCP connection, and all
	// data read from the TCP connection is written to the websocket.
	//
	// Note that TCP is not a message-framed protocol, so callers should not
	// rely on message boundaries to delimit data transmitted across this
	// connection.
	ExposeTCPPort(targetPort uint16) (Exposure, error)
}

Exposer provides an interface for exposing services, including configuration and any necessary shared state. It is intended to exist for the lifetime of the process.

func NewLocal

func NewLocal(publicIP net.IP) (Exposer, error)

Create a local exposer implementation. Local exposers are useful for local testing, and simply exposes the URL as given, or (for ExposeTCPPort) proxies a websocket on localhost to the port.

func NewStatelessDNS

func NewStatelessDNS(publicIP net.IP, publicPort uint16, hostDomain, statelessDNSSecret string, duration time.Duration, tlsCert, tlsKey string) (Exposer, error)

Create a stateless DNS exposer implementation. This is similar to a local exposer, except that it generates hostnames compatible with https://github.com/taskcluster/stateless-dns-go and can thus use TLS certificates to serve over https. The hostname is formed by prepending a string indicating the IP and expiration to the hostDomain. That string is signed with the statelessDNSSecret in such a way that the DNS server can validate it. The tlsCert and tlsKey are used to serve HTTPS, and should be valid for `*.<hostDomain>`.

If incoming connections must be on a specific port (because it is open in a firewall somewhere), pass that as publicPort. If all ports are available. publicPort can be 0.

func NewWST

func NewWST(serverURL, wstAudience, workerGroup, workerId string, authClient authClient) (Exposer, error)

Create a websocktunnel-based exposer implementation.

type Exposure

type Exposure interface {
	// Stop this exposure.  Note that any existing connections may continue
	// to operate.
	Close() error

	// Get the public URL for this exposure
	GetURL() *url.URL
}

Exposure is a more ephemeral exposure of a single backend service, derived from Exposer.ExposeHTTP or Exposer.ExposeTCPPort. It can return a URL for the exposed service, and can be Closed when the service should no longer be exposed.