proxy

README

Brickchain Tunneling Proxy

The purpose of the proxy is to allow a server to publish a service through HTTP or Websockets without the hassle of opening up an external port in a firewall. The client, as described below, is the service connected to the proxy, and the proxy is a centrally hosted service.

The proxy converts HTTP and Websocket requests into messages that are passed to the proxy client via the websocket connection that the client already has established with the proxy.

The proxy client processes the request and creates a response message that has the same ID as the request and sends it back to the proxy over the websocket connection. If the client fails to respond to the request,there is a timeout of 30 seconds before the HTTP request is answered with an error code of 504 Gateway timeout.

Tunneling setup

When the client first connects to the proxy it sends a signed RegistrationRequest message. The proxy responds with a hostname that is the base32 encoded hash of the signing keys thumbprint plus a domain name that the proxy should have a valid certificate (probably a wildcard certificate), and DNS pointer for.

Messages

The messages are defined in the messages.go file, and is used by both the client and the server.

RegistrationRequest is created, signed, and sent by the client to the proxy.

RegistrationResponse is sent back from the proxy to the client and contains the hostname that the client now can use.

HTTPRequest is created when a HTTP request is handled by the proxy on behalf of a client (a third party). The Host header of the request decides which client should handle the message, and them the message is sent to the client.

HTTPResponse is what the client needs to respond back with to the proxy. The ID of the response needs to be the same as the ID of the request.

WSRequest is a message created when there is a request towards the proxy with the Websocket upgrade headers set.

WSResponse is what the client should send back to the proxy when it has handled the WSRequest and is ready to process messages coming over the websocket.

WSMessage encapsulates the messages passed back and forth over the websocket established by the WSRequest/WSResponse messages. The ID of the WSMessage needs to be the ID of the WSRequest (can be thought of as the connection ID).

WSTeardown is sent by either the proxy or the client when they want to stop the websocket connection. The ID needs to be the connection ID (the ID from the WSRequest).

A Ping is sent every 10 seconds if there is no other traffic going over the connection. If the client has not received a ping or other traffic in 20 seconds it should reconnect and register again.

Limitations

There is a limiter in the proxy to limit the amount of messages for each connection. Each request body and response body can not exceed 500kb.

In the current implementation a message bus (in memory or redis) is used to pass the messages between the HTTP request handler and the client connection handler.

The code

The server and client are contained in this repository, and both are located the cmd directory.

Documentation

Index

• Constants
• type Disconnect
  • func NewDisconnect() *Disconnect
• type HttpRequest
  • func NewHttpRequest(url string) *HttpRequest
• type HttpResponse
  • func NewHttpResponse(id string, status int) *HttpResponse
• type Ping
  • func NewPing() *Ping
• type RegistrationRequest
  • func NewRegistrationRequest(mandateToken string) *RegistrationRequest
• type RegistrationResponse
  • func NewRegistrationResponse(id string, keyID string) *RegistrationResponse
• type WSMessage
  • func NewWSMessage(id string) *WSMessage
• type WSRequest
  • func NewWSRequest(url string) *WSRequest
• type WSResponse
  • func NewWSResponse(id string, ok bool) *WSResponse
• type WSTeardown
  • func NewWSTeardown(id string) *WSTeardown

Constants

const SchemaBase = "https://proxy.brickchain.com/v1"

Types

type Disconnect

type Disconnect struct {
	document.Base
}

func NewDisconnect

func NewDisconnect() *Disconnect

type HttpRequest

type HttpRequest struct {
	document.Base
	URL     string            `json:"url"`
	Query   string            `json:"query,omitempty"`
	Headers map[string]string `json:"headers"`
	Method  string            `json:"method"`
	Body    string            `json:"body"`
}

func NewHttpRequest

func NewHttpRequest(url string) *HttpRequest

type HttpResponse

type HttpResponse struct {
	document.Base
	Headers     map[string]string `json:"headers"`
	ContentType string            `json:"contentType"`
	Status      int               `json:"status"`
	Body        string            `json:"body"`
}

func NewHttpResponse

func NewHttpResponse(id string, status int) *HttpResponse

type Ping

type Ping struct {
	document.Base
}

func NewPing

func NewPing() *Ping

type RegistrationRequest

type RegistrationRequest struct {
	document.Base
	MandateToken string `json:"mandateToken"`
	Session      string `json:"session,omitempty"`
}

func NewRegistrationRequest

func NewRegistrationRequest(mandateToken string) *RegistrationRequest

type RegistrationResponse

type RegistrationResponse struct {
	document.Base
	KeyID    string `json:"keyID"`
	Hostname string `json:"hostname,omitempty"`
}

func NewRegistrationResponse

func NewRegistrationResponse(id string, keyID string) *RegistrationResponse

type WSMessage

type WSMessage struct {
	document.Base
	MessageType int    `json:"messageType"`
	Body        string `json:"body"`
}

func NewWSMessage

func NewWSMessage(id string) *WSMessage

type WSRequest

type WSRequest struct {
	document.Base
	URL     string            `json:"url"`
	Query   string            `json:"query,omitempty"`
	Headers map[string]string `json:"headers"`
}

func NewWSRequest

func NewWSRequest(url string) *WSRequest

type WSResponse

type WSResponse struct {
	document.Base
	OK    bool   `json:"ok"`
	Error string `json:"error,omitempty"`
}

func NewWSResponse

func NewWSResponse(id string, ok bool) *WSResponse

type WSTeardown

type WSTeardown struct {
	document.Base
}

func NewWSTeardown

func NewWSTeardown(id string) *WSTeardown