mtglib

type AntiReplayCache interface {
	// Seen before checks if this set of bytes was observed before or not. If it
	// is required to store this information somewhere else, then it has to do
	// that.
	SeenBefore(data []byte) bool
}

type Event interface {
	// StreamID returns an identifier of the stream, connection, request, you name
	// it. All events within the same stream returns the same stream id.
	StreamID() string

	// Timestamp returns a timestamp when this event was generated.
	Timestamp() time.Time
}

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

type EventConnectedToDC struct {

	// RemoteIP is an IP address of the Telegram server proxy has been connected
	// to.
	RemoteIP net.IP

	// DC is an index of the datacenter proxy has been connected to.
	DC int
	// contains filtered or unexported fields
}

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

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

type EventIPBlocklisted struct {
	RemoteIP    net.IP
	IsBlockList bool
	// contains filtered or unexported fields
}

type EventIPListSize struct {
	Size        int
	IsBlockList bool
	// contains filtered or unexported fields
}

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

type EventStart struct {

	// RemoteIP is an IP address of the client.
	RemoteIP net.IP
	// contains filtered or unexported fields
}

type EventStream interface {
	// Send delivers an event to observers. Given context has to be respected. If
	// the context is closed, all blocking operations should be released ASAP.
	//
	// It is possible that context is closed but the message is delivered.
	// EventStream implementations should solve this issue somehow.
	Send(context.Context, Event)
}

type EventThrottled struct {
	SecretName string
	// contains filtered or unexported fields
}

type EventTraffic struct {

	// Traffic is a count of bytes which were transmitted.
	Traffic uint

	// IsRead defines if we _read_ or _write_ to connection. A rule of thumb is
	// simple: EventTraffic is bound to a remote connection. Not to a client one,
	// but either to Telegram or front domain one.
	//
	// In the case of Telegram, isRead means that we've fetched some bytes from
	// Telegram to send it to a client.
	//
	// In the case of the front domain, it means that we've fetched some bytes
	// from this domain to send it to a client.
	IsRead bool
	// contains filtered or unexported fields
}

type IPBlocklist interface {
	// Contains checks if given IP address belongs to this blocklist If. it is, a
	// connection is terminated .
	Contains(net.IP) bool

	// Run starts a background update procedure for a blocklist
	Run(time.Duration)

	// Shutdown stops a blocklist. It is assumed that none will access it after.
	Shutdown()
}

type Logger interface {
	// Named returns a new logger with a bound name. Name chaining is allowed and
	// appreciated.
	Named(name string) Logger

	// BindInt binds new integer parameter to a new logger instance.
	BindInt(name string, value int) Logger

	// BindStr binds new string parameter to a new logger instance.
	BindStr(name, value string) Logger

	// BindJSON binds a new JSON-encoded string to a new logger instance.
	BindJSON(name, value string) Logger

	// Printf is to support log.Logger behavior.
	Printf(format string, args ...any)

	// Info puts a message about some normal situation.
	Info(msg string)

	// InfoError puts a message about some normal situation but this situation is
	// related to a given error.
	InfoError(msg string, err error)

	// Warning puts a message about some extraordinary situation worth to look at.
	Warning(msg string)

	// WarningError puts a message about some extraordinary situation worth to
	// look at. This situation is related to a given error.
	WarningError(msg string, err error)

	// Debug puts a message useful for debugging only.
	Debug(msg string)

	// Debug puts a message useful for debugging only. This message is related to
	// a given error.
	DebugError(msg string, err error)
}

type Network interface {
	// Dial establishes context-free TCP connections.
	Dial(network, address string) (essentials.Conn, error)

	// DialContext dials using a context. This is a preferable way of
	// establishing TCP connections.
	DialContext(ctx context.Context, network, address string) (essentials.Conn, error)

	// MakeHTTPClient build an HTTP client with given dial function. If nothing is
	// provided, then DialContext of this interface is going to be used.
	MakeHTTPClient(func(ctx context.Context, network, address string) (essentials.Conn, error)) *http.Client

	// NativeDialer returns a configured instance of native dialer that
	// skips proxy connections or any other irrelevant settings.
	NativeDialer() *net.Dialer
}

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

type ProxyOpts struct {
	// Secret defines a secret which should be used by a proxy.
	//
	// Deprecated: Use Secrets instead for multi-secret support.
	// Kept for backward compatibility.
	Secret Secret

	// Secrets defines a map of named secrets which should be used by a proxy.
	// If set, Secret is ignored. During FakeTLS handshake, each secret is
	// tried until one validates.
	Secrets map[string]Secret

	// Network defines a network instance which should be used for all network
	// communications made by proxies.
	//
	// This is a mandatory setting.
	Network Network

	// AntiReplayCache defines an instance of antireplay cache.
	//
	// This is a mandatory setting.
	AntiReplayCache AntiReplayCache

	// IPBlocklist defines an instance of IP blocklist.
	//
	// This is a mandatory setting.
	IPBlocklist IPBlocklist

	// IPAllowlist defines a whitelist of IPs to allow to use proxy.
	//
	// This is an optional setting, ignored by default (no restrictions).
	IPAllowlist IPBlocklist

	// EventStream defines an instance of event stream.
	//
	// This ia a mandatory setting.
	EventStream EventStream

	// Logger defines an instance of the logger.
	//
	// This is a mandatory setting.
	Logger Logger

	// BufferSize is a size of the copy buffer in bytes.
	//
	// Please remember that we multiply this number in 2, because when we relay
	// between proxies, we have to create 2 intermediate buffers: to and from.
	//
	// This is an optional setting.
	//
	// Deprecated: this setting is no longer makes any effect.
	BufferSize uint

	// Concurrency is a size of the worker pool for connection management.
	//
	// If we have more connections than this number, they are going to be
	// rejected.
	//
	// This is an optional setting.
	Concurrency uint

	// IdleTimeout is a timeout for relay when we have to break a stream.
	//
	// This is a timeout for any activity. So, if we have any message which will
	// pass to either direction, a timer is reset. If we have no any reads or
	// writes for this timeout, a connection will be aborted.
	//
	// This is an optional setting.
	IdleTimeout time.Duration

	// HandshakeTimeout is a timeout during which all handshake ceremonies must
	// be completed, otherwise this process will be aborted
	//
	// This is an optional setting.
	HandshakeTimeout time.Duration

	// TolerateTimeSkewness is a time boundary that defines a time range where
	// faketls timestamp is acceptable.
	//
	// This means that if if you got a timestamp X, now is Y, then if |X-Y| <
	// TolerateTimeSkewness, then you accept a packet.
	//
	// This is an optional setting.
	TolerateTimeSkewness time.Duration

	// PreferIP defines an IP connectivity preference. Valid values are:
	// 'prefer-ipv4', 'prefer-ipv6', 'only-ipv4', 'only-ipv6'.
	//
	// This is an optional setting.
	PreferIP string

	// AutoUpdate defines if it is required to auto update proxy list from
	// Telegram instead of relying on a hardcoded list.
	//
	// This is an optional setting.
	AutoUpdate bool

	// DomainFrontingPort is a port we use to connect to a fronting domain.
	//
	// This is required because secret does not specify a port. It specifies a
	// hostname only.
	//
	// This is an optional setting.
	DomainFrontingPort uint

	// DomainFrontingIP is an IP address to use when connecting to the fronting
	// domain instead of resolving the hostname from the secret via DNS.
	//
	// This is useful when DNS resolution of the fronting host is blocked.
	// The hostname from the secret is still used for SNI in the TLS handshake.
	//
	// This is an optional setting.
	DomainFrontingIP string

	// DomainFrontingProxyProtocol is used if communication between upstream
	// endpoint and mtg supports proxy protocol. This is useful in case
	// if mtg is also placed behind load balancer, and this will make
	// fronting webserver to know about real IP addresses
	//
	// This is an optional setting.
	DomainFrontingProxyProtocol bool

	// AllowFallbackOnUnknownDC defines how proxy behaves if unknown DC was
	// requested. If this setting is set to false, then such connection will be
	// rejected. Otherwise, proxy will chose any DC.
	//
	// Telegram is designed in a way that any DC can serve any request, the
	// problem is a latency.
	//
	// This is an optional setting.
	AllowFallbackOnUnknownDC bool

	// UseTestDCs defines if we have to connect to production or to staging DCs of
	// Telegram.
	//
	// This is required if you use mtglib as an integration library for your
	// Telegram-related projects.
	//
	// This is an optional setting.
	//
	// OBSOLETE and DEPRECATED. Ignored.
	UseTestDCs bool

	// DCOverrides defines a set of IP addresses that should be used
	// with a higher priority to those that are calculated somehow by mtg.
	//
	// OBSOLETE and DEPRECATED. Ignored.
	DCOverrides map[int][]string

	// DoppelGangerURLs is a list of URLs that should be crawled by
	// mtg to calculate parameters for statistical distribution of a
	// traffic for fronting domains. If nothing is given, then predefined
	// statistics is going to be used.
	DoppelGangerURLs []string

	// DoppelGangerPerRaid defines how many time each URL from
	// DoppelGangerURLs list should be crawled per raid. We recommend to
	// have this number ~10.
	DoppelGangerPerRaid uint

	// DoppelGangerEach defines a time period between each raid. We recommend
	// to use hours here.
	DoppelGangerEach time.Duration

	// DoppelGangerDRS defines if TLS Dynamic Record Sizing is active.
	DoppelGangerDRS bool

	// APIBindTo is the address to bind the stats HTTP API server to.
	// If empty, the stats API server is not started.
	//
	// This is an optional setting.
	APIBindTo string

	// ThrottleMaxConnections is the total connection limit. When total
	// connections exceed this value, per-user caps are computed using
	// a fair-share algorithm and new connections from over-cap users
	// are rejected. 0 disables throttling.
	//
	// This is an optional setting.
	ThrottleMaxConnections uint

	// ThrottleCheckInterval is how often the throttle recomputes per-user
	// caps. Defaults to 5 seconds.
	//
	// This is an optional setting.
	ThrottleCheckInterval time.Duration
}

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

type Secret struct {
	// Key is a set of bytes used for traffic authentication.
	Key [SecretKeyLength]byte

	// Host is a domain fronting hostname.
	Host string
}

type StatsResponse struct {
	StartedAt        time.Time                `json:"started_at"`
	UptimeSeconds    int64                    `json:"uptime_seconds"`
	TotalConnections int64                    `json:"total_connections"`
	Throttle         *ThrottleJSON            `json:"throttle,omitempty"`
	Users            map[string]UserStatsJSON `json:"users"`
}

type ThrottleJSON struct {
	Active bool             `json:"active"`
	Limit  int64            `json:"limit"`
	Caps   map[string]int64 `json:"caps,omitempty"`
}

type UserStatsJSON struct {
	Connections int64      `json:"connections"`
	BytesIn     int64      `json:"bytes_in"`
	BytesOut    int64      `json:"bytes_out"`
	LastSeen    *time.Time `json:"last_seen"`
}