proto

package
v1.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 22, 2025 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ProxyProtoNone = 0
	ProxyProtoV1   = 1
	ProxyProtoV2   = 2
)

in sync with rpx.Tunnel_ProxyProto

View Source 
const (
	EdgeTypeUndefined EdgeType = 0
	EdgeTypeTCP                = 1
	EdgeTypeTLS                = 2
	EdgeTypeHTTPS              = 3
)

in sync with rpx.EdgesTypes_Edge

Variables

View Source 
var Version = []string{"3", "2"} // integers in priority order

Functions

func StringError added in v1.4.0 

func StringError(msg string) error

func Unpack 

func Unpack(packed, unpacked any) error

Unpack allows the caller to unpack anything that is specified in the protocol as an interface{} This includes the all Extra fields and the Options for a Bind. This is one of the most awful hacks in the whole library. The trouble is that anything that is passed as an empty interface in the protocol will be deserialized into a map[string]interface{}. So in order to get them in the form we want, we write them out as JSON again and then read them back in with the now-known proper type for deserialization

func UnpackProtoOpts 

func UnpackProtoOpts(protocol string, opts any, bindMsg any) error

Unpacks protocol options for Bind and BindResp messages. This is an internal function shared between client and server.

func WrapError added in v1.4.0 

func WrapError(err error) error

Types

type AgentVersionDeprecated added in v1.2.0 

type AgentVersionDeprecated struct {
	NextMin  string
	NextDate time.Time
	Msg      string
}

func (*AgentVersionDeprecated) Error added in v1.2.0 

func (avd *AgentVersionDeprecated) Error() string

type Auth 

type Auth struct {
	Version  []string  // protocol versions supported, ordered by preference
	ClientID string    `json:"ClientId"` // empty for new sessions
	Extra    AuthExtra // clients may add whatever data the like to auth messages
}

When a client opens a new control channel to the server it must start by sending an Auth message.

type AuthExtra 

type AuthExtra struct {
	OS                 string
	Arch               string
	Authtoken          ObfuscatedString
	Version            string
	Hostname           string
	UserAgent          string
	Metadata           string
	Cookie             string
	HeartbeatInterval  int64
	HeartbeatTolerance int64
	Fingerprint        *Fingerprint

	// for each remote operation, these variables define whether the ngrok
	// client is capable of executing that operation. each capability
	// is transmitted as a pointer to string, with the following meanings:
	//
	// null ->               operation disallow because the ngrok agent version is too old.
	//                       this is true because older clients will never set this value
	//
	// "" (empty string)  -> the operation is supported
	//
	// non-empty string   -> the operation is not supported and this value is the  user-facing
	//                       error message describing why it is not supported
	UpdateUnsupportedError  *string
	StopUnsupportedError    *string
	RestartUnsupportedError *string

	ProxyType       string
	MutualTLS       bool
	ServiceRun      bool
	ConfigVersion   string
	CustomInterface bool
	CustomCAs       bool

	ClientType ClientType // The type of client this is. Currently agent and library clients are supported

	// The leg number of the client connection associated with this session.
	// Defaults to zero, will be 1 or more for the additional connected
	// leg(s) when multi-leg is engaged.
	LegNumber uint32
}

type AuthResp 

type AuthResp struct {
	Version  string // protocol version chosen
	ClientID string `json:"ClientId"`
	Error    string
	Extra    AuthRespExtra
}

A server responds to an Auth message with an AuthResp message over the control channel.Mutual

If Error is not the empty string the server has indicated it will not accept the new session and will close the connection.

The server response includes a unique ClientId that is used to associate and authenticate future proxy connections via the same field in RegProxy messages.

type AuthRespExtra 

type AuthRespExtra struct {
	Version string // server version
	Region  string // server region
	// Encrypted server.PersistentSession object.
	Cookie      string
	AccountName string
	// Duration in seconds
	SessionDuration    int64
	PlanName           string
	Banner             string
	DeprecationWarning *AgentVersionDeprecated
	ConnectAddresses   []ConnectAddress
}

type Bind 

type Bind struct {
	ID            string    `json:"-"`
	ClientID      string    `json:"Id"` // a session-unique bind ID generated by the client, if empty, one is generated
	Proto         string    // the protocol to bind (one of 'http', 'https', 'tcp', 'tls', 'ssh')
	ForwardsTo    string    // the address of the upstream service the ngrok agent will forward to
	ForwardsProto string    // the L7 protocol the upstream service is expecting (one of ”, 'http1', 'http2')
	Opts          any       // options for the bind - protocol dependent
	Extra         BindExtra // anything extra the application wants to send
}

A client sends this message to the server over a new stream to request the server bind a remote port/hostname on the client's behalf.

type BindExtra 

type BindExtra struct {
	Name           string
	Token          string
	IPPolicyRef    string
	Metadata       string
	Description    string
	Binding        string
	PoolingEnabled bool
}

type BindResp 

type BindResp struct {
	ClientID string        `json:"Id"` // a session-unique bind ID generated by the client, if empty, one is generated
	URL      string        // public URL of the bind (a human friendly combination of Hostname/Port/Proto/Opts)
	Proto    string        // protocol bound on
	Opts     any           // protocol-specific options that were chosen
	Error    string        // error message is the server failed to bind
	Extra    BindRespExtra // application-defined extra values
}

The server responds with a BindResp message to notify the client of the success or failure of a bind.

type BindRespExtra 

type BindRespExtra struct {
	Token string
}

type ClientType 

type ClientType string
const (
	LibraryOfficialGo ClientType = "ngrok-go"
)

type ConnectAddress added in v1.9.0 

type ConnectAddress struct {
	Region     string
	ServerAddr string
}

type EdgeType 

type EdgeType int32

func ParseEdgeType 

func ParseEdgeType(et string) (EdgeType, bool)

type Fingerprint 

type Fingerprint struct {
	M []string
	D []string
}

Note: entirely unused

type HTTPEndpoint 

type HTTPEndpoint struct {
	URL               string
	Domain            string
	Hostname          string // public hostname of the bind
	Subdomain         string
	Auth              string
	HostHeaderRewrite bool   // true if the request's host header is being rewritten
	LocalURLScheme    string // scheme of the local forward
	ProxyProto

	// middleware
	Compression           *pb.MiddlewareConfiguration_Compression
	CircuitBreaker        *pb.MiddlewareConfiguration_CircuitBreaker
	IPRestriction         *pb.MiddlewareConfiguration_IPRestriction
	BasicAuth             *pb.MiddlewareConfiguration_BasicAuth
	OAuth                 *pb.MiddlewareConfiguration_OAuth
	OIDC                  *pb.MiddlewareConfiguration_OIDC
	WebhookVerification   *pb.MiddlewareConfiguration_WebhookVerification
	MutualTLSCA           *pb.MiddlewareConfiguration_MutualTLS
	RequestHeaders        *pb.MiddlewareConfiguration_Headers
	ResponseHeaders       *pb.MiddlewareConfiguration_Headers
	WebsocketTCPConverter *pb.MiddlewareConfiguration_WebsocketTCPConverter
	UserAgentFilter       *pb.MiddlewareConfiguration_UserAgentFilter
	Policy                *pb.MiddlewareConfiguration_Policy
	TrafficPolicy         string
}

type LabelOptions 

type LabelOptions struct {
	Labels map[string]string
}

type ObfuscatedString 

type ObfuscatedString string

func (ObfuscatedString) PlainText 

func (t ObfuscatedString) PlainText() string

func (ObfuscatedString) String 

func (t ObfuscatedString) String() string

type ProxyHeader 

type ProxyHeader struct {
	ID             string `json:"Id"` // Bind ID this connection is being proxied for
	ClientAddr     string // Network address of the client initiating the connection to the tunnel
	Proto          string // Protocol of the stream
	EdgeType       string // Type of edge
	PassthroughTLS bool   // true if the session is passing tls encrypted traffic to the agent
}

This message is sent first over a new stream from the server to the client to provide it with metadata about the connection it will tunnel over the stream.

type ProxyProto 

type ProxyProto int32

func ParseProxyProto 

func ParseProxyProto(proxyProto string) (ProxyProto, bool)

type ReqType 

type ReqType muxado.StreamType
const (
	// sent from the client to the server
	AuthReq                 ReqType = 0
	BindReq                 ReqType = 1
	UnbindReq               ReqType = 2
	StartTunnelWithLabelReq ReqType = 7

	// sent from the server to the client
	ProxyReq      ReqType = 3
	RestartReq    ReqType = 4
	StopReq       ReqType = 5
	UpdateReq     ReqType = 6
	StopTunnelReq ReqType = 9

	// sent from client to the server
	SrvInfoReq ReqType = 8
)

NOTE(alan) never change the number of a message type that has already been assigned, you will break the protocol

type Restart 

type Restart struct{}

This request is sent from the server to the ngrok agent asking it to restart itself

type RestartResp 

type RestartResp struct {
	Error string // an error, if one occurred, while trying to restart. empty on OK
}

The client responds with RestartResponse to the ngrok server to acknowledge it will restart

type SSHOptions 

type SSHOptions struct {
	Hostname string // public hostname of the bind
	Username string
	Password string
	ProxyProto
}

type SrvInfo 

type SrvInfo struct{}

type SrvInfoResp 

type SrvInfoResp struct {
	Region string
}

type StartTunnelWithLabel 

type StartTunnelWithLabel struct {
	// ID       string            `json:"-"` // a session-unique bind ID generated by the client, if empty, one is generated
	Labels        map[string]string // labels for tunnel group membership
	ForwardsTo    string            // the address of the upstream service the ngrok agent will forward to
	ForwardsProto string            // the L7 protocol the upstream service is expecting (one of ”, 'http1', 'http2')
	Metadata      string
}

A client sends this message to the server over a new stream to request the server start a new tunnel with the given labels on the client's behalf.

type StartTunnelWithLabelResp 

type StartTunnelWithLabelResp struct {
	ID    string `json:"Id"`
	Error string // error message is the server failed to bind
}

The server responds with a StartTunnelWithLabelResp message to notify the client of the success or failure of the tunnel and label creation.

type Stop 

type Stop struct{}

This request is sent from the server to the ngrok agent asking it to immediately terminate itself

type StopResp 

type StopResp struct {
	Error string // an error, if one occurred, while requesting a Stop
}

This client responds with StopResponse to the ngrok server to acknowledge it will shutdown

type StopTunnel added in v1.6.0 

type StopTunnel struct {
	ClientID  string `json:"Id"` // a session-unique bind ID generated by the client
	Message   string // an message to display to the user
	ErrorCode string // an error code to display to the user. empty on OK
}

This request is sent from the server to the ngrok agent to request a tunnel to close, with a notice to display to the user

type TCPEndpoint 

type TCPEndpoint struct {
	URL  string
	Addr string
	ProxyProto

	// middleware
	IPRestriction *pb.MiddlewareConfiguration_IPRestriction
	Policy        *pb.MiddlewareConfiguration_Policy
	TrafficPolicy string
}

type TLSEndpoint 

type TLSEndpoint struct {
	URL       string
	Domain    string
	Hostname  string // public hostname of the bind
	Subdomain string
	ProxyProto
	MutualTLSAtAgent bool

	// edge termination options
	MutualTLSAtEdge *pb.MiddlewareConfiguration_MutualTLS
	TLSTermination  *pb.MiddlewareConfiguration_TLSTermination
	IPRestriction   *pb.MiddlewareConfiguration_IPRestriction
	Policy          *pb.MiddlewareConfiguration_Policy
	TrafficPolicy   string
}

type Unbind 

type Unbind struct {
	ID       string `json:"-"`
	ClientID string `json:"Id"` // Id of the bind to close
	Extra    any    // application-defined
}

A client sends this message to the server over a new stream to request the server close a bind

type UnbindResp 

type UnbindResp struct {
	Error string // an error, if the unbind failed
	Extra any    // application-defined
}

The server responds with an UnbindResp message to notify the client of the success or failure of the unbind.

type Update 

type Update struct {
	Version            string // the version to update to. if empty, the ngrok agent will update itself to the latest version
	PermitMajorVersion bool   // whether the caller has permitted a major version update
}

This request is sent from the server to the ngrok agent asking it to update itself to a new version.

type UpdateResp 

type UpdateResp struct {
	Error string // an error, if one
}

The client responds with UpdateResponse to the ngrok server to acknowledge it will update

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.