clientlib

Documentation

Index

• Variables
• type NoticeEvent
• type Parameters
• type ParametersDelta
• type PsiphonTunnel
  • func StartTunnel(ctx context.Context, configJSON []byte, embeddedServerEntryList string, ...) (tunnel *PsiphonTunnel, retErr error)
  • func (tunnel *PsiphonTunnel) Stop()

Variables

var ErrTimeout = std_errors.New("clientlib: tunnel establishment timeout")

ErrTimeout is returned when the tunnel establishment attempt fails due to timeout

Types

type NoticeEvent

type NoticeEvent struct {
	Data      map[string]interface{} `json:"data"`
	Type      string                 `json:"noticeType"`
	Timestamp string                 `json:"timestamp"`
}

NoticeEvent represents the notices emitted by tunnel core. It will be passed to noticeReceiver, if supplied. NOTE: Ordinary users of this library should never need this.

type Parameters

type Parameters struct {
	// Used as the directory for the datastore, remote server list, and obfuscasted
	// server list.
	// Empty string means the default will be used (current working directory).
	// nil means the values in the config file will be used.
	// Optional, but strongly recommended.
	DataRootDirectory *string

	// Overrides config.ClientPlatform. See config.go for details.
	// nil means the value in the config file will be used.
	// Optional, but strongly recommended.
	ClientPlatform *string

	// Overrides config.NetworkID. For details see:
	// https://godoc.org/github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon#NetworkIDGetter
	// nil means the value in the config file will be used. (If not set in the config,
	// an error will result.)
	// Empty string will produce an error.
	// Optional, but strongly recommended.
	NetworkID *string

	// Overrides config.EstablishTunnelTimeoutSeconds. See config.go for details.
	// nil means the EstablishTunnelTimeoutSeconds value in the config file will be used.
	// If there's no such value in the config file, the default will be used.
	// Zero means there will be no timeout.
	// Optional.
	EstablishTunnelTimeoutSeconds *int

	// EmitDiagnosticNoticesToFile indicates whether to use the rotating log file
	// facility to record diagnostic notices instead of sending diagnostic
	// notices to noticeReceiver. Has no effect unless the tunnel
	// config.EmitDiagnosticNotices flag is set.
	EmitDiagnosticNoticesToFiles bool
}

Parameters provide an easier way to modify the tunnel config at runtime.

type ParametersDelta

type ParametersDelta map[string]interface{}

ParametersDelta allows for fine-grained modification of parameters.Parameters. NOTE: Ordinary users of this library should never need this.

type PsiphonTunnel

type PsiphonTunnel struct {

	// The port on which the HTTP proxy is running
	HTTPProxyPort int
	// The port on which the SOCKS proxy is running
	SOCKSProxyPort int
	// contains filtered or unexported fields
}

PsiphonTunnel is the tunnel object. It can be used for stopping the tunnel and retrieving proxy ports.

func StartTunnel

func StartTunnel(ctx context.Context,
	configJSON []byte, embeddedServerEntryList string,
	params Parameters, paramsDelta ParametersDelta,
	noticeReceiver func(NoticeEvent)) (tunnel *PsiphonTunnel, retErr error)

StartTunnel establishes a Psiphon tunnel. It returns an error if the establishment was not successful. If the returned error is nil, the returned tunnel can be used to find out the proxy ports and subsequently stop the tunnel.

ctx may be cancelable, if the caller wants to be able to interrupt the establishment attempt, or context.Background().

configJSON will be passed to psiphon.LoadConfig to configure the tunnel. Required.

embeddedServerEntryList is the encoded embedded server entry list. It is optional.

params are config values that typically need to be overridden at runtime.

paramsDelta contains changes that will be applied to the Parameters. NOTE: Ordinary users of this library should never need this and should pass nil.

noticeReceiver, if non-nil, will be called for each notice emitted by tunnel core. NOTE: Ordinary users of this library should never need this and should pass nil.

func (*PsiphonTunnel) Stop

func (tunnel *PsiphonTunnel) Stop()

Stop stops/disconnects/shuts down the tunnel. It is safe to call when not connected. Not safe to call concurrently with Start.