parameters

package
v2.0.10+incompatible Latest Latest
Warning

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

 Go to latest Published: Jan 29, 2020 License: GPL-3.0 Imports: 11 Imported by: 0

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

View Source 
const (
	NetworkLatencyMultiplier                         = "NetworkLatencyMultiplier"
	NetworkLatencyMultiplierMin                      = "NetworkLatencyMultiplierMin"
	NetworkLatencyMultiplierMax                      = "NetworkLatencyMultiplierMax"
	NetworkLatencyMultiplierLambda                   = "NetworkLatencyMultiplierLambda"
	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"
	UseOnlyCustomTLSProfiles                         = "UseOnlyCustomTLSProfiles"
	CustomTLSProfiles                                = "CustomTLSProfiles"
	SelectRandomizedTLSProfileProbability            = "SelectRandomizedTLSProfileProbability"
	NoDefaultTLSSessionIDProbability                 = "NoDefaultTLSSessionIDProbability"
	LimitQUICVersionsProbability                     = "LimitQUICVersionsProbability"
	LimitQUICVersions                                = "LimitQUICVersions"
	FragmentorProbability                            = "FragmentorProbability"
	FragmentorLimitProtocols                         = "FragmentorLimitProtocols"
	FragmentorMinTotalBytes                          = "FragmentorMinTotalBytes"
	FragmentorMaxTotalBytes                          = "FragmentorMaxTotalBytes"
	FragmentorMinWriteBytes                          = "FragmentorMinWriteBytes"
	FragmentorMaxWriteBytes                          = "FragmentorMaxWriteBytes"
	FragmentorMinDelay                               = "FragmentorMinDelay"
	FragmentorMaxDelay                               = "FragmentorMaxDelay"
	FragmentorDownstreamProbability                  = "FragmentorDownstreamProbability"
	FragmentorDownstreamLimitProtocols               = "FragmentorDownstreamLimitProtocols"
	FragmentorDownstreamMinTotalBytes                = "FragmentorDownstreamMinTotalBytes"
	FragmentorDownstreamMaxTotalBytes                = "FragmentorDownstreamMaxTotalBytes"
	FragmentorDownstreamMinWriteBytes                = "FragmentorDownstreamMinWriteBytes"
	FragmentorDownstreamMaxWriteBytes                = "FragmentorDownstreamMaxWriteBytes"
	FragmentorDownstreamMinDelay                     = "FragmentorDownstreamMinDelay"
	FragmentorDownstreamMaxDelay                     = "FragmentorDownstreamMaxDelay"
	ObfuscatedSSHMinPadding                          = "ObfuscatedSSHMinPadding"
	ObfuscatedSSHMaxPadding                          = "ObfuscatedSSHMaxPadding"
	TunnelOperateShutdownTimeout                     = "TunnelOperateShutdownTimeout"
	TunnelPortForwardDialTimeout                     = "TunnelPortForwardDialTimeout"
	PacketTunnelReadTimeout                          = "PacketTunnelReadTimeout"
	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"
	MeekTrafficShapingProbability                    = "MeekTrafficShapingProbability"
	MeekTrafficShapingLimitProtocols                 = "MeekTrafficShapingLimitProtocols"
	MeekMinTLSPadding                                = "MeekMinTLSPadding"
	MeekMaxTLSPadding                                = "MeekMaxTLSPadding"
	MeekMinLimitRequestPayloadLength                 = "MeekMinLimitRequestPayloadLength"
	MeekMaxLimitRequestPayloadLength                 = "MeekMaxLimitRequestPayloadLength"
	MeekRedialTLSProbability                         = "MeekRedialTLSProbability"
	TransformHostNameProbability                     = "TransformHostNameProbability"
	PickUserAgentProbability                         = "PickUserAgentProbability"
	LivenessTestMinUpstreamBytes                     = "LivenessTestMinUpstreamBytes"
	LivenessTestMaxUpstreamBytes                     = "LivenessTestMaxUpstreamBytes"
	LivenessTestMinDownstreamBytes                   = "LivenessTestMinDownstreamBytes"
	LivenessTestMaxDownstreamBytes                   = "LivenessTestMaxDownstreamBytes"
	ReplayCandidateCount                             = "ReplayCandidateCount"
	ReplayDialParametersTTL                          = "ReplayDialParametersTTL"
	ReplayTargetUpstreamBytes                        = "ReplayTargetUpstreamBytes"
	ReplayTargetDownstreamBytes                      = "ReplayTargetDownstreamBytes"
	ReplayTargetTunnelDuration                       = "ReplayTargetTunnelDuration"
	ReplaySSH                                        = "ReplaySSH"
	ReplayObfuscatorPadding                          = "ReplayObfuscatorPadding"
	ReplayFragmentor                                 = "ReplayFragmentor"
	ReplayTLSProfile                                 = "ReplayTLSProfile"
	ReplayRandomizedTLSProfile                       = "ReplayRandomizedTLSProfile"
	ReplayFronting                                   = "ReplayFronting"
	ReplayHostname                                   = "ReplayHostname"
	ReplayQUICVersion                                = "ReplayQUICVersion"
	ReplayObfuscatedQUIC                             = "ReplayObfuscatedQUIC"
	ReplayLivenessTest                               = "ReplayLivenessTest"
	ReplayUserAgent                                  = "ReplayUserAgent"
	ReplayAPIRequestPadding                          = "ReplayAPIRequestPadding"
	ReplayLaterRoundMoveToFrontProbability           = "ReplayLaterRoundMoveToFrontProbability"
	ReplayRetainFailedProbability                    = "ReplayRetainFailedProbability"
	APIRequestUpstreamPaddingMinBytes                = "APIRequestUpstreamPaddingMinBytes"
	APIRequestUpstreamPaddingMaxBytes                = "APIRequestUpstreamPaddingMaxBytes"
	APIRequestDownstreamPaddingMinBytes              = "APIRequestDownstreamPaddingMinBytes"
	APIRequestDownstreamPaddingMaxBytes              = "APIRequestDownstreamPaddingMaxBytes"
	PersistentStatsMaxStoreRecords                   = "PersistentStatsMaxStoreRecords"
	PersistentStatsMaxSendBytes                      = "PersistentStatsMaxSendBytes"
	RecordRemoteServerListPersistentStatsProbability = "RecordRemoteServerListPersistentStatsProbability"
	RecordFailedTunnelPersistentStatsProbability     = "RecordFailedTunnelPersistentStatsProbability"
	ServerEntryMinimumAgeForPruning                  = "ServerEntryMinimumAgeForPruning"
	ApplicationParametersProbability                 = "ApplicationParametersProbability"
	ApplicationParameters                            = "ApplicationParameters"
)

Variables

This section is empty.

Functions

func IsServerSideOnly added in v1.0.9 

func IsServerSideOnly(name string) bool

IsServerSideOnly indicates if the parameter specified by name is used server-side only.

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() ClientParametersAccessor

Get returns the current parameters.

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

The returned ClientParametersAccessor may be used to read multiple related values atomically and consistently while the current set of values in ClientParameters may change concurrently.

Get does not perform any heap allocations and is intended for repeated, direct, low-overhead invocations.

func (*ClientParameters) GetCustom 

func (p *ClientParameters) GetCustom(
	customNetworkLatencyMultiplier float64) ClientParametersAccessor

GetCustom returns the current parameters while also setting customizations for this instance.

The properties of Get also apply to GetCustom: must be read-only; atomic and consisent view; no heap allocations.

Customizations include:

  • customNetworkLatencyMultiplier, which overrides NetworkLatencyMultiplier for this instance 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 ClientParametersAccessor 

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

ClientParametersAccessor provides consistent, atomic access to client parameter values. Any customizations are applied transparently.

func (ClientParametersAccessor) Bool 

func (p ClientParametersAccessor) Bool(name string) bool

Bool returns a bool parameter value.

func (ClientParametersAccessor) Close 

func (p ClientParametersAccessor) Close()

Close clears internal references to large memory objects, allowing them to be garbage collected. Call Close when done using a ClientParametersAccessor, where memory footprint is a concern, and where the ClientParametersAccessor is not immediately going out of scope. After Close is called, all other ClientParametersAccessor functions will panic if called.

func (ClientParametersAccessor) CustomTLSProfile 

func (p ClientParametersAccessor) CustomTLSProfile(name string) *protocol.CustomTLSProfile

CustomTLSProfile returns the CustomTLSProfile fields with the specified Name field if it exists in the CustomTLSProfiles parameter value. Returns nil if not found.

func (ClientParametersAccessor) CustomTLSProfileNames 

func (p ClientParametersAccessor) CustomTLSProfileNames() []string

CustomTLSProfileNames returns the CustomTLSProfile.Name fields for each profile in the CustomTLSProfiles parameter value.

func (ClientParametersAccessor) DownloadURLs 

func (p ClientParametersAccessor) DownloadURLs(name string) DownloadURLs

DownloadURLs returns a DownloadURLs parameter value.

func (ClientParametersAccessor) Duration 

func (p ClientParametersAccessor) 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 (ClientParametersAccessor) Float 

func (p ClientParametersAccessor) Float(name string) float64

Float returns a float64 parameter value.

func (ClientParametersAccessor) HTTPHeaders 

func (p ClientParametersAccessor) HTTPHeaders(name string) http.Header

HTTPHeaders returns an http.Header parameter value.

func (ClientParametersAccessor) Int 

func (p ClientParametersAccessor) Int(name string) int

Int returns an int parameter value.

func (ClientParametersAccessor) KeyValues 

func (p ClientParametersAccessor) KeyValues(name string) KeyValues

KeyValues returns a KeyValues parameter value.

func (ClientParametersAccessor) QUICVersions 

func (p ClientParametersAccessor) QUICVersions(name string) protocol.QUICVersions

QUICVersions returns a protocol.QUICVersions 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 (ClientParametersAccessor) RateLimits 

func (p ClientParametersAccessor) RateLimits(name string) common.RateLimits

RateLimits returns a common.RateLimits parameter value.

func (ClientParametersAccessor) String 

func (p ClientParametersAccessor) String(name string) string

String returns a string parameter value.

func (ClientParametersAccessor) Strings 

func (p ClientParametersAccessor) Strings(name string) []string

func (ClientParametersAccessor) TLSProfiles 

func (p ClientParametersAccessor) 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 (ClientParametersAccessor) Tag 

func (p ClientParametersAccessor) Tag() string

Tag returns the tag associated with these parameters.

func (ClientParametersAccessor) TunnelProtocols 

func (p ClientParametersAccessor) 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 (ClientParametersAccessor) WeightedCoinFlip 

func (p ClientParametersAccessor) WeightedCoinFlip(name string) bool

WeightedCoinFlip returns the result of prng.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.

type KeyValues 

type KeyValues map[string]json.RawMessage

KeyValues represents a set of name/JSON pairs.

func (KeyValues) Validate 

func (keyValues KeyValues) Validate() error

Validate checks that the JSON values are well-formed.

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.