parameters

Documentation

Overview

Package parameters implements dynamic, concurrency-safe parameters that determine Psiphon client behavior.

Parameters include network timeouts, probabilities for actions, lists of protocols, etc. Parameters are initialized with reasonable defaults. New values may be applied, allowing the client to customized its parameters from both a config file and tactics data. Sane minimum values are enforced.

Parameters may be read and updated concurrently. The read mechanism offers a snapshot so that related parameters, such as two Ints representing a range; or a more complex series of related parameters; may be read in an atomic and consistent way. For example:

p := clientParameters.Get()
min := p.Int("Min")
max := p.Int("Max")
p = nil

For long-running operations, it is recommended to set any pointer to the snapshot to nil to allow garbage collection of old snaphots in cases where the parameters change.

In general, client parameters should be read as close to the point of use as possible to ensure that dynamic changes to the parameter values take effect.

For duration parameters, time.ParseDuration-compatible string values are supported when applying new values. This allows specifying durations as, for example, "100ms" or "24h".

Values read from the parameters are not deep copies and must be treated as read-only.

Index

• Constants
• type ClientParameters
  • func NewClientParameters(getValueLogger func(error)) (*ClientParameters, error)
  • func (p *ClientParameters) Get() *ClientParametersSnapshot
  • func (p *ClientParameters) Set(tag string, skipOnError bool, applyParameters ...map[string]interface{}) ([]int, error)
• type ClientParametersSnapshot
  • func (p *ClientParametersSnapshot) Bool(name string) bool
  • func (p *ClientParametersSnapshot) DownloadURLs(name string) DownloadURLs
  • func (p *ClientParametersSnapshot) Duration(name string) time.Duration
  • func (p *ClientParametersSnapshot) Float(name string) float64
  • func (p *ClientParametersSnapshot) HTTPHeaders(name string) http.Header
  • func (p *ClientParametersSnapshot) Int(name string) int
  • func (p *ClientParametersSnapshot) RateLimits(name string) common.RateLimits
  • func (p *ClientParametersSnapshot) String(name string) string
  • func (p *ClientParametersSnapshot) Strings(name string) []string
  • func (p *ClientParametersSnapshot) TLSProfiles(name string) protocol.TLSProfiles
  • func (p *ClientParametersSnapshot) Tag() string
  • func (p *ClientParametersSnapshot) TunnelProtocols(name string) protocol.TunnelProtocols
  • func (p *ClientParametersSnapshot) WeightedCoinFlip(name string) bool
• type DownloadURL
• type DownloadURLs
  • func (d DownloadURLs) DecodeAndValidate() error
  • func (d DownloadURLs) Select(attempt int) (string, string, bool)

Constants

const (
	NetworkLatencyMultiplier                   = "NetworkLatencyMultiplier"
	TacticsWaitPeriod                          = "TacticsWaitPeriod"
	TacticsRetryPeriod                         = "TacticsRetryPeriod"
	TacticsRetryPeriodJitter                   = "TacticsRetryPeriodJitter"
	TacticsTimeout                             = "TacticsTimeout"
	ConnectionWorkerPoolSize                   = "ConnectionWorkerPoolSize"
	TunnelConnectTimeout                       = "TunnelConnectTimeout"
	EstablishTunnelTimeout                     = "EstablishTunnelTimeout"
	EstablishTunnelWorkTime                    = "EstablishTunnelWorkTime"
	EstablishTunnelPausePeriod                 = "EstablishTunnelPausePeriod"
	EstablishTunnelPausePeriodJitter           = "EstablishTunnelPausePeriodJitter"
	EstablishTunnelServerAffinityGracePeriod   = "EstablishTunnelServerAffinityGracePeriod"
	StaggerConnectionWorkersPeriod             = "StaggerConnectionWorkersPeriod"
	StaggerConnectionWorkersJitter             = "StaggerConnectionWorkersJitter"
	LimitIntensiveConnectionWorkers            = "LimitIntensiveConnectionWorkers"
	IgnoreHandshakeStatsRegexps                = "IgnoreHandshakeStatsRegexps"
	PrioritizeTunnelProtocolsProbability       = "PrioritizeTunnelProtocolsProbability"
	PrioritizeTunnelProtocols                  = "PrioritizeTunnelProtocols"
	PrioritizeTunnelProtocolsCandidateCount    = "PrioritizeTunnelProtocolsCandidateCount"
	InitialLimitTunnelProtocolsProbability     = "InitialLimitTunnelProtocolsProbability"
	InitialLimitTunnelProtocols                = "InitialLimitTunnelProtocols"
	InitialLimitTunnelProtocolsCandidateCount  = "InitialLimitTunnelProtocolsCandidateCount"
	LimitTunnelProtocolsProbability            = "LimitTunnelProtocolsProbability"
	LimitTunnelProtocols                       = "LimitTunnelProtocols"
	LimitTLSProfilesProbability                = "LimitTLSProfilesProbability"
	LimitTLSProfiles                           = "LimitTLSProfiles"
	FragmentorProbability                      = "FragmentorProbability"
	FragmentorLimitProtocols                   = "FragmentorLimitProtocols"
	FragmentorMinTotalBytes                    = "FragmentorMinTotalBytes"
	FragmentorMaxTotalBytes                    = "FragmentorMaxTotalBytes"
	FragmentorMinWriteBytes                    = "FragmentorMinWriteBytes"
	FragmentorMaxWriteBytes                    = "FragmentorMaxWriteBytes"
	FragmentorMinDelay                         = "FragmentorMinDelay"
	FragmentorMaxDelay                         = "FragmentorMaxDelay"
	ObfuscatedSSHMinPadding                    = "ObfuscatedSSHMinPadding"
	ObfuscatedSSHMaxPadding                    = "ObfuscatedSSHMaxPadding"
	TunnelOperateShutdownTimeout               = "TunnelOperateShutdownTimeout"
	TunnelPortForwardDialTimeout               = "TunnelPortForwardDialTimeout"
	TunnelRateLimits                           = "TunnelRateLimits"
	AdditionalCustomHeaders                    = "AdditionalCustomHeaders"
	SpeedTestPaddingMinBytes                   = "SpeedTestPaddingMinBytes"
	SpeedTestPaddingMaxBytes                   = "SpeedTestPaddingMaxBytes"
	SpeedTestMaxSampleCount                    = "SpeedTestMaxSampleCount"
	SSHKeepAliveSpeedTestSampleProbability     = "SSHKeepAliveSpeedTestSampleProbability"
	SSHKeepAlivePaddingMinBytes                = "SSHKeepAlivePaddingMinBytes"
	SSHKeepAlivePaddingMaxBytes                = "SSHKeepAlivePaddingMaxBytes"
	SSHKeepAlivePeriodMin                      = "SSHKeepAlivePeriodMin"
	SSHKeepAlivePeriodMax                      = "SSHKeepAlivePeriodMax"
	SSHKeepAlivePeriodicTimeout                = "SSHKeepAlivePeriodicTimeout"
	SSHKeepAlivePeriodicInactivePeriod         = "SSHKeepAlivePeriodicInactivePeriod"
	SSHKeepAliveProbeTimeout                   = "SSHKeepAliveProbeTimeout"
	SSHKeepAliveProbeInactivePeriod            = "SSHKeepAliveProbeInactivePeriod"
	HTTPProxyOriginServerTimeout               = "HTTPProxyOriginServerTimeout"
	HTTPProxyMaxIdleConnectionsPerHost         = "HTTPProxyMaxIdleConnectionsPerHost"
	FetchRemoteServerListTimeout               = "FetchRemoteServerListTimeout"
	FetchRemoteServerListRetryPeriod           = "FetchRemoteServerListRetryPeriod"
	FetchRemoteServerListStalePeriod           = "FetchRemoteServerListStalePeriod"
	RemoteServerListSignaturePublicKey         = "RemoteServerListSignaturePublicKey"
	RemoteServerListURLs                       = "RemoteServerListURLs"
	ObfuscatedServerListRootURLs               = "ObfuscatedServerListRootURLs"
	PsiphonAPIRequestTimeout                   = "PsiphonAPIRequestTimeout"
	PsiphonAPIStatusRequestPeriodMin           = "PsiphonAPIStatusRequestPeriodMin"
	PsiphonAPIStatusRequestPeriodMax           = "PsiphonAPIStatusRequestPeriodMax"
	PsiphonAPIStatusRequestShortPeriodMin      = "PsiphonAPIStatusRequestShortPeriodMin"
	PsiphonAPIStatusRequestShortPeriodMax      = "PsiphonAPIStatusRequestShortPeriodMax"
	PsiphonAPIStatusRequestPaddingMinBytes     = "PsiphonAPIStatusRequestPaddingMinBytes"
	PsiphonAPIStatusRequestPaddingMaxBytes     = "PsiphonAPIStatusRequestPaddingMaxBytes"
	PsiphonAPIPersistentStatsMaxCount          = "PsiphonAPIPersistentStatsMaxCount"
	PsiphonAPIConnectedRequestPeriod           = "PsiphonAPIConnectedRequestPeriod"
	PsiphonAPIConnectedRequestRetryPeriod      = "PsiphonAPIConnectedRequestRetryPeriod"
	FetchSplitTunnelRoutesTimeout              = "FetchSplitTunnelRoutesTimeout"
	SplitTunnelRoutesURLFormat                 = "SplitTunnelRoutesURLFormat"
	SplitTunnelRoutesSignaturePublicKey        = "SplitTunnelRoutesSignaturePublicKey"
	SplitTunnelDNSServer                       = "SplitTunnelDNSServer"
	FetchUpgradeTimeout                        = "FetchUpgradeTimeout"
	FetchUpgradeRetryPeriod                    = "FetchUpgradeRetryPeriod"
	FetchUpgradeStalePeriod                    = "FetchUpgradeStalePeriod"
	UpgradeDownloadURLs                        = "UpgradeDownloadURLs"
	UpgradeDownloadClientVersionHeader         = "UpgradeDownloadClientVersionHeader"
	TotalBytesTransferredNoticePeriod          = "TotalBytesTransferredNoticePeriod"
	MeekDialDomainsOnly                        = "MeekDialDomainsOnly"
	MeekLimitBufferSizes                       = "MeekLimitBufferSizes"
	MeekCookieMaxPadding                       = "MeekCookieMaxPadding"
	MeekFullReceiveBufferLength                = "MeekFullReceiveBufferLength"
	MeekReadPayloadChunkLength                 = "MeekReadPayloadChunkLength"
	MeekLimitedFullReceiveBufferLength         = "MeekLimitedFullReceiveBufferLength"
	MeekLimitedReadPayloadChunkLength          = "MeekLimitedReadPayloadChunkLength"
	MeekMinPollInterval                        = "MeekMinPollInterval"
	MeekMinPollIntervalJitter                  = "MeekMinPollIntervalJitter"
	MeekMaxPollInterval                        = "MeekMaxPollInterval"
	MeekMaxPollIntervalJitter                  = "MeekMaxPollIntervalJitter"
	MeekPollIntervalMultiplier                 = "MeekPollIntervalMultiplier"
	MeekPollIntervalJitter                     = "MeekPollIntervalJitter"
	MeekApplyPollIntervalMultiplierProbability = "MeekApplyPollIntervalMultiplierProbability"
	MeekRoundTripRetryDeadline                 = "MeekRoundTripRetryDeadline"
	MeekRoundTripRetryMinDelay                 = "MeekRoundTripRetryMinDelay"
	MeekRoundTripRetryMaxDelay                 = "MeekRoundTripRetryMaxDelay"
	MeekRoundTripRetryMultiplier               = "MeekRoundTripRetryMultiplier"
	MeekRoundTripTimeout                       = "MeekRoundTripTimeout"
	TransformHostNameProbability               = "TransformHostNameProbability"
	PickUserAgentProbability                   = "PickUserAgentProbability"
)

Types

type ClientParameters

type ClientParameters struct {
	// contains filtered or unexported fields
}

ClientParameters is a set of client parameters. To use the parameters, call Get. To apply new values to the parameters, call Set.

func NewClientParameters

func NewClientParameters(
	getValueLogger func(error)) (*ClientParameters, error)

NewClientParameters initializes a new ClientParameters with the default parameter values.

getValueLogger is optional, and is used to report runtime errors with getValue; see comment in getValue.

func (*ClientParameters) Get

func (p *ClientParameters) Get() *ClientParametersSnapshot

Get returns the current parameters. Values read from the current parameters are not deep copies and must be treated read-only.

func (*ClientParameters) Set

func (p *ClientParameters) Set(
	tag string, skipOnError bool, applyParameters ...map[string]interface{}) ([]int, error)

Set replaces the current parameters. First, a set of parameters are initialized using the default values. Then, each applyParameters is applied in turn, with the later instances having precedence.

When skipOnError is true, unknown or invalid parameters in any applyParameters are skipped instead of aborting with an error.

For protocol.TunnelProtocols and protocol.TLSProfiles type values, when skipOnError is true the values are filtered instead of validated, so only known tunnel protocols and TLS profiles are retained.

When an error is returned, the previous parameters remain completely unmodified.

For use in logging, Set returns a count of the number of parameters applied from each applyParameters.

type ClientParametersSnapshot

type ClientParametersSnapshot struct {
	// contains filtered or unexported fields
}

ClientParametersSnapshot is an atomic snapshot of the client parameter values. ClientParameters.Get will return a snapshot which may be used to read multiple related values atomically and consistently while the current snapshot in ClientParameters may change concurrently.

func (*ClientParametersSnapshot) Bool

func (p *ClientParametersSnapshot) Bool(name string) bool

Bool returns a bool parameter value.

func (*ClientParametersSnapshot) DownloadURLs

func (p *ClientParametersSnapshot) DownloadURLs(name string) DownloadURLs

DownloadURLs returns a DownloadURLs parameter value.

func (*ClientParametersSnapshot) Duration

func (p *ClientParametersSnapshot) Duration(name string) time.Duration

Duration returns a time.Duration parameter value. When the duration parameter has the useNetworkLatencyMultiplier flag, the NetworkLatencyMultiplier is applied to the returned value.

func (*ClientParametersSnapshot) Float

func (p *ClientParametersSnapshot) Float(name string) float64

Float returns a float64 parameter value.

func (*ClientParametersSnapshot) HTTPHeaders

func (p *ClientParametersSnapshot) HTTPHeaders(name string) http.Header

HTTPHeaders returns an http.Header parameter value.

func (*ClientParametersSnapshot) Int

func (p *ClientParametersSnapshot) Int(name string) int

Int returns an int parameter value.

func (*ClientParametersSnapshot) RateLimits

func (p *ClientParametersSnapshot) RateLimits(name string) common.RateLimits

RateLimits returns a common.RateLimits parameter value.

func (*ClientParametersSnapshot) String

func (p *ClientParametersSnapshot) String(name string) string

String returns a string parameter value.

func (*ClientParametersSnapshot) Strings

func (p *ClientParametersSnapshot) Strings(name string) []string

Strings returns a []string parameter value.

func (*ClientParametersSnapshot) TLSProfiles

func (p *ClientParametersSnapshot) TLSProfiles(name string) protocol.TLSProfiles

TLSProfiles returns a protocol.TLSProfiles parameter value. If there is a corresponding Probability value, a weighted coin flip will be performed and, depending on the result, the value or the parameter default will be returned.

func (*ClientParametersSnapshot) Tag

func (p *ClientParametersSnapshot) Tag() string

Tag returns the tag associated with these parameters.

func (*ClientParametersSnapshot) TunnelProtocols

func (p *ClientParametersSnapshot) TunnelProtocols(name string) protocol.TunnelProtocols

TunnelProtocols returns a protocol.TunnelProtocols parameter value. If there is a corresponding Probability value, a weighted coin flip will be performed and, depending on the result, the value or the parameter default will be returned.

func (*ClientParametersSnapshot) WeightedCoinFlip

func (p *ClientParametersSnapshot) WeightedCoinFlip(name string) bool

WeightedCoinFlip returns the result of common.FlipWeightedCoin using the specified float parameter as the probability input.

type DownloadURL

type DownloadURL struct {

	// URL is the location of the resource. This string is slightly obfuscated
	// with base64 encoding to mitigate trivial binary executable string scanning.
	URL string

	// SkipVerify indicates whether to verify HTTPS certificates. It some
	// circumvention scenarios, verification is not possible. This must
	// only be set to true when the resource has its own verification mechanism.
	SkipVerify bool

	// OnlyAfterAttempts specifies how to schedule this URL when downloading
	// the same resource (same entity, same ETag) from multiple different
	// candidate locations. For a value of N, this URL is only a candidate
	// after N rounds of attempting the download from other URLs.
	OnlyAfterAttempts int
}

DownloadURL specifies a URL for downloading resources along with parameters for the download strategy.

type DownloadURLs

type DownloadURLs []*DownloadURL

DownloadURLs is a list of download URLs.

func (DownloadURLs) DecodeAndValidate

func (d DownloadURLs) DecodeAndValidate() error

DecodeAndValidate validates a list of download URLs.

At least one DownloadURL in the list must have OnlyAfterAttempts of 0, or no DownloadURL would be selected on the first attempt.

func (DownloadURLs) Select

func (d DownloadURLs) Select(attempt int) (string, string, bool)

Select chooses a DownloadURL from the list.

The first return value is the canonical URL, to be used as a key when storing information related to the DownloadURLs, such as an ETag.

The second return value is the chosen download URL, which is selected based at random from the candidates allowed in the specified attempt.