mtglib

type AddressReport struct {
	Name string `json:"name"`

	// IPLimit is the configured limit, or absent for none.
	IPLimit int `json:"ip_limit,omitempty"`

	// ActiveIPs is the number of distinct addresses counted right now: those
	// holding a live connection here plus those reported from elsewhere. It
	// is a count, so it is never gated.
	ActiveIPs int `json:"active_ips,omitempty"`

	// ConnectedIPs and ExternalIPs are the addresses themselves, present
	// only with track-client-ips, for the reason ProxyOpts.TrackClientIPs
	// gives. ExternalExpiresAt is when the reported set stops counting
	// unless it is refreshed first.
	ConnectedIPs      []string   `json:"connected_ips,omitempty"`
	ExternalIPs       []string   `json:"external_ips,omitempty"`
	ExternalExpiresAt *time.Time `json:"external_expires_at,omitempty"`

	// ConnectedIPsLastSeen is when each connected address last moved a byte,
	// gated as ConnectedIPs is.
	ConnectedIPsLastSeen map[string]time.Time `json:"connected_ips_last_seen,omitempty"`
}

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 BanJSON struct {
	Address   string    `json:"address"`
	ExpiresAt time.Time `json:"expires_at"`
}

type BanResult struct {
	Banned    int      `json:"banned"`
	Closed    int      `json:"closed"`
	Addresses []string `json:"addresses,omitempty"`
}

type BansReport struct {
	Total    int       `json:"total"`
	Tracking bool      `json:"tracking"`
	Bans     []BanJSON `json:"bans,omitzero"`
}

type ClientJSON struct {
	Address string `json:"address"`

	ClientUsageJSON
}

type ClientUsageJSON struct {
	Connections     int        `json:"connections"`
	BytesIn         int64      `json:"bytes_in"`
	BytesOut        int64      `json:"bytes_out"`
	ThrottledMillis int64      `json:"throttled_ms,omitempty"`
	FirstSeen       time.Time  `json:"first_seen"`
	LastSeen        time.Time  `json:"last_seen"`
	SpeedLimit      int64      `json:"speed_limit,omitempty"`
	SpeedLimitUp    int64      `json:"speed_limit_up,omitempty"`
	SpeedLimitDown  int64      `json:"speed_limit_down,omitempty"`
	BannedUntil     *time.Time `json:"banned_until,omitempty"`
}

type ClientsReport struct {
	Total    int              `json:"total"`
	Overflow int64            `json:"overflow"`
	Tracking bool             `json:"tracking"`
	Rest     *ClientUsageJSON `json:"rest,omitempty"`
	Clients  []ClientJSON     `json:"clients,omitzero"`
}

type DenyReason int

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 EventIPLimited struct {
	SecretName string
	// 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 FakeTLSJSON struct {
	Hinted            int64   `json:"hinted"`
	Scanned           int64   `json:"scanned"`
	Unmatched         int64   `json:"unmatched"`
	DeniedIP          int64   `json:"denied_ip"`
	DeniedGlobal      int64   `json:"denied_global"`
	Oversized         int64   `json:"oversized"`
	OverBudgetMatched int64   `json:"over_budget_matched"`
	Enforced          bool    `json:"enforced"`
	NsPerBlock        float64 `json:"ns_per_block"`
}

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 KickResult struct {
	Closed int `json:"closed"`
}

type ListenerJSON struct {
	Bind   string   `json:"bind"`
	Accept []string `json:"accept"`
	Public bool     `json:"public"`
}

type ListenerPolicy struct {
	// Modes is the set of secret forms this socket serves.
	Modes ModeSet

	// Public is the operator's acknowledgement that a non-loopback obfuscated2
	// port is fingerprintable as an MTProto proxy. It also arms HandshakesPerIP.
	Public bool

	// ProxyProtocol says a PROXY header is expected on this listener. It is
	// consumed by the CLI when it builds the socket, not by the proxy.
	ProxyProtocol bool

	// OnUnknownSecret is the disposal of a refused connection.
	OnUnknownSecret UnknownSecretAction

	// HandshakesPerIP is the per-IP failed-handshake budget per second (burst
	// 2x). 0 disables it, and it is armed only when Public is set.
	HandshakesPerIP uint
}

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 ModeSet uint8

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 ObfuscatedJSON struct {
	Trials      int64 `json:"trials"`
	Misses      int64 `json:"misses"`
	Denied      int64 `json:"denied"`
	Draining    int64 `json:"draining"`
	RateLimited int64 `json:"rate_limited"`
}

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

	// DomainFrontingHost is the address to use when connecting to the
	// fronting domain instead of resolving the hostname from the secret via
	// DNS. It can be a literal IP or a hostname; hostnames are resolved at
	// dial time via the native dialer (which honours dual-stack and Happy
	// Eyeballs).
	//
	// This is useful when DNS resolution of the secret's hostname is blocked
	// or loops back to this server. The hostname from the secret is still
	// used for SNI in the TLS handshake.
	//
	// This is an optional setting.
	DomainFrontingHost string

	// DomainFrontingIP previously held the dial target for the fronting
	// domain. The setting is no longer honoured: setting it logs a warning
	// at proxy startup and the value is dropped.
	//
	// Deprecated: use DomainFrontingHost. Setting this field has no effect.
	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

	// TrackClientIPs makes GET /stats report per-user client addresses:
	// connected_ips, the distinct addresses holding a live connection right
	// now, and last_ip, the address of the most recent admitted connection.
	//
	// It defaults to FALSE, and that default is deliberate. This is a
	// circumvention proxy: the people using it are frequently the reason it
	// exists, and an operator's answer to "who connected from where" is also
	// the answer anyone who takes the server gets. connected_ips costs no new
	// retention -- those addresses are already held for the duration of the
	// connection, and vanish with it -- but last_ip outlives the connection it
	// came from, so a deployment that never asks for it never accumulates it.
	//
	// Nothing here is written to disk. The usage state file holds quota
	// counters only, so an address survives a restart in no form at all.
	//
	// This is an optional setting.
	TrackClientIPs bool

	// HandshakeHints makes the FakeTLS door remember, per client address (an
	// IPv4 address or an IPv6 /64), the names of up to 16 secrets that recently
	// completed a handshake from it, and verify a hello from that address
	// against those first. A returning client then costs one HMAC instead of a
	// scan over every hosted secret. A hint is only an order to try things in:
	// every hinted secret passes the same verification, so it never makes a
	// wrong secret match, and a hello that matches nothing can neither read nor
	// plant one. Loopback, private, link-local, unspecified and multicast
	// addresses get none -- behind a carrier that does not forward the client
	// address they would be one shared key, and a multicast address is no
	// client at all.
	//
	// nil follows TrackClientIPs, and that default is the point: the cache holds
	// address -> secret name in memory for 30 to 60 minutes after the last
	// successful handshake, so it is on exactly when the operator has already
	// chosen to keep client addresses past a connection. A non-nil value
	// overrides it either way. Nothing here is logged, exported or written to
	// disk.
	//
	// This is an optional setting.
	HandshakeHints *bool

	// HandshakeBudgetMode is what the FakeTLS door does with a hello it would
	// have to scan every hosted secret for (one no hint matched) when that scan
	// is over its CPU budget, or when the hello is above the scan cap of 128
	// SHA-256 blocks (about 8 KiB; a real client sends 0.5 to 2 KiB):
	//
	//   - "enforce" (or empty, the default) lets a scan the budget can pay for
	//     within 150 ms wait for it and run, and fronts any other hello at once to
	//     the cover site exactly as a hello that matched nothing is fronted --
	//     never closes it;
	//   - "observe" keeps the same accounting but never waits and never refuses:
	//     it counts what enforce would have refused, and the refused hellos that
	//     then matched a secret, and scans anyway;
	//   - "off" has no budget and no scan cap.
	//
	// The budget is in real CPU: the cost of a SHA-256 block on this machine is
	// measured once per process. Under enforce a legitimate client with no hint
	// can be fronted while a flood keeps the budget spent; it retries. With
	// hints on (HandshakeHints), a client whose address matched a secret
	// recently has its hinted candidates tried before, and outside, the budget;
	// a hint miss falls through to a scan that is charged like any other.
	//
	// The zero values of this and the next two settings are the defaults:
	// enforce, 50 ms per address, 25% of the cores.
	//
	// This is an optional setting.
	HandshakeBudgetMode string

	// HandshakeBudgetPerIPMillis is the scan CPU one client address (an IPv4
	// address or an IPv6 /64) may spend per second, in milliseconds, with a
	// burst of four seconds' worth. Loopback, private, link-local and other
	// addresses that do not stand for one place have no bucket of their own;
	// they share the process-wide one.
	//
	// nil is 50. 0 disables the per-address bucket, leaving only the
	// process-wide one -- which is what peers behind a carrier that does not
	// forward client addresses get anyway, since they all arrive from a loopback
	// or private address. A front proxy on a public address that sends no PROXY
	// header is the opposite case: every client arrives from that one address
	// and shares one bucket, so 0 is what it wants. Above 1000 is invalid.
	//
	// This is an optional setting.
	HandshakeBudgetPerIPMillis *uint

	// HandshakeBudgetCPUPercent is the share of the cores (GOMAXPROCS, read
	// once at start) the whole process may spend scanning, with a burst of one
	// second's worth. This is the bound that holds against many addresses and
	// against forged ones.
	//
	// 0 is 25. Above 100 is invalid.
	//
	// This is an optional setting.
	HandshakeBudgetCPUPercent uint

	// 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

	// DoppelGangerShaping is how the doppelganger spaces its records in time:
	// "record" (or empty, the default) waits a drawn delay before every
	// record; "burst" waits once when a connection wakes from idle and then
	// sends records back to back.
	DoppelGangerShaping string

	// DoppelGangerScoutCovers measures the cover sites the ee secrets name --
	// their certificate flight's size, for the fake handshake's noise record
	// -- when DoppelGangerURLs is empty. Their record timing is not taken:
	// pacing keeps the built-in model. It makes outbound HTTPS requests to
	// those sites, so a library caller has to ask; the mtg-proxy binary does
	// unless [defense.doppelganger] scout-covers = false.
	DoppelGangerScoutCovers 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

	// APIListener is a socket already bound for the management API. When it
	// is set, APIBindTo is ignored and the proxy serves the API on this socket
	// instead, taking ownership of it: it is closed when the proxy shuts down.
	//
	// It exists for an embedder or a test that needs the port to be its own
	// before the proxy starts, rather than one the proxy picks and reports.
	//
	// This is an optional setting.
	APIListener net.Listener

	// 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

	// SecretsReloader re-reads the desired secret configuration from its source
	// (for the CLI, the config file passed to `mtg run`). When set, a POST to
	// /reload on the stats API triggers Proxy.ReloadSecrets, which calls this
	// and swaps the secret set (and advertising tags) in without a restart.
	// When nil, /reload reports the capability is unavailable and the proxy
	// behaves exactly as before.
	//
	// This is an optional setting.
	SecretsReloader func() (SecretConfig, error)

	// GlobalAdTag is the advertising tag (ad_tag from @MTProxybot) applied to
	// every secret without a per-secret override. When set, matching clients
	// are routed through Telegram middle proxies so a sponsored channel is
	// shown. nil disables advertising globally.
	//
	// This is an optional setting.
	GlobalAdTag *[AdTagLength]byte

	// SecretAdTags carries per-secret advertising tag overrides keyed by secret
	// name. A secret listed here uses its own tag instead of GlobalAdTag.
	//
	// This is an optional setting.
	SecretAdTags map[string][AdTagLength]byte

	// SecretLimits carries per-secret governance limits (data quota, expiry,
	// disabled flag) keyed by secret name. A secret absent here is unlimited,
	// never expires and is enabled.
	//
	// This is an optional setting.
	SecretLimits map[string]SecretLimits

	// RetiringSecrets is the complete list of retiring keys the initial set
	// holds: old keys of a secret name, each accepted until its own Until after
	// the name was given a new primary key, with the name's quota, limits,
	// bans and stats. nil means none. It has the meaning SecretConfig.Retiring
	// has, and an entry the set cannot hold is dropped and logged, never an
	// error.
	//
	// This is an optional setting.
	RetiringSecrets []RetiringSecret

	// RotationClock is the clock retiring keys expire by. One per process,
	// shared by whatever reads the configuration and the proxy, so that both
	// judge an overlap by the same instant and neither is ever handed a time
	// earlier than one the other has seen. nil makes NewProxy build one of its
	// own on the wall clock.
	//
	// This is an optional setting.
	RotationClock *RotationClock

	// UsageStateFile is the path of a JSON file where per-secret quota usage is
	// persisted so it survives restarts. When empty, quota accounting is
	// in-memory only and resets when the process restarts.
	//
	// This is an optional setting.
	UsageStateFile string

	// EmitTraffic controls whether per-read/write EventTraffic events are
	// produced for relayed connections. These events are consumed only by the
	// statsd/prometheus observers, so leave it false when no metrics sink is
	// configured: doing so skips a heap allocation (plus time.Now, a streamID
	// hash and a channel send) on every relay read and write. The CLI sets it
	// automatically when statsd or prometheus is enabled.
	//
	// This is an optional setting.
	EmitTraffic bool

	// PublicIPv4 and PublicIPv6 advertise this proxy's externally reachable
	// addresses. They are used as the proxy's own address in the middle-proxy
	// RPC handshake and RPC_PROXY_REQ; required to be correct behind NAT.
	//
	// These are optional settings.
	PublicIPv4 net.IP
	PublicIPv6 net.IP

	// AdvertisedPort is the port reported as the proxy's own port in
	// RPC_PROXY_REQ. Usually the first bind port.
	//
	// This is an optional setting.
	AdvertisedPort int

	// Listeners describes every socket this proxy was configured to serve, for
	// the capability report on GET /stats. It is display only: the policy that
	// actually governs a connection travels on the connection itself.
	//
	// This is an optional setting.
	Listeners []ListenerJSON

	// ListenerModes is the union of every configured listener's accept set. It
	// is what tells NewProxy that a dd or plain secret has no door, so the
	// operator gets a warning instead of a client that silently cannot connect.
	//
	// This is an optional setting.
	ListenerModes ModeSet

	// APIToken, when non-empty, requires every management-API request to carry
	// an "Authorization: Bearer <token>" header. Empty keeps the API
	// unauthenticated (relying on the localhost-bind convention).
	//
	// This is an optional setting.
	APIToken string
}

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

type QuotaReset int32

type RetiringSecret struct {
	Name   string
	Secret Secret
	Until  time.Time
}

type RotationClock 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. Required by, and meaningful only to,
	// SecretModeFakeTLS: dd and plain never send SNI and never front.
	Host string

	// Mode is the wire form. The ZERO VALUE is SecretModeFakeTLS, so every
	// existing Secret{Key: k, Host: h} literal in the tree and its tests keeps
	// its exact current meaning with no edit.
	Mode SecretMode
}

type SecretConfig struct {
	// Secrets is the name->secret map. It must be non-empty and every secret
	// must be valid.
	Secrets map[string]Secret

	// SecretAdTags carries optional per-secret advertising tag overrides keyed
	// by secret name. A name absent here falls back to GlobalAdTag.
	SecretAdTags map[string][AdTagLength]byte

	// GlobalAdTag is the advertising tag applied to any secret without an
	// override. nil means no advertising (the direct-DC path).
	GlobalAdTag *[AdTagLength]byte

	// Limits carries optional per-secret governance limits (data quota, expiry,
	// disabled flag) keyed by secret name. A name absent here has no limits. It
	// is swapped in atomically together with the secrets, so a reload or API
	// mutation can change limits without a restart.
	Limits map[string]SecretLimits

	// Retiring is the COMPLETE list of retiring keys the swapped-in set is to
	// hold: old keys of a name, each accepted until its own Until after the
	// name was given a new primary key. nil means none, wherever a
	// SecretConfig is consumed -- ReloadSecrets, ReplaceSecrets and every
	// other swap -- never "keep what is there". An entry the set cannot hold
	// (a value Secret.Valid() refuses, expired, for a name not in Secrets, on
	// another name's key or its own primary's, a duplicate, past a cap) is
	// dropped and logged, never an error.
	//
	// For embedders: a ReplaceSecrets with a nil Retiring ends every overlap
	// in force. The next reload of a config file that still grants an
	// overlap grants it again, until its Until.
	Retiring []RetiringSecret
}

type SecretInfo struct {
	Name           string `json:"name"`
	Secret         string `json:"secret"`
	Host           string `json:"host"`
	AdTag          string `json:"ad_tag,omitempty"`
	EffectiveAdTag string `json:"effective_ad_tag,omitempty"`

	Quota          int64      `json:"quota,omitempty"`
	QuotaUsed      int64      `json:"quota_used,omitempty"`
	QuotaRemaining *int64     `json:"quota_remaining,omitempty"`
	QuotaReset     string     `json:"quota_reset,omitempty"`
	ExpiresAt      *time.Time `json:"expires_at,omitempty"`
	Disabled       bool       `json:"disabled,omitempty"`

	// SpeedLimit is the user's cap in bytes per second, upload and download
	// combined across every connection, or absent for unlimited. It is set
	// with a human spelling ("5mbit", "1MB/s") and read back as a number, the
	// same way quota is.
	SpeedLimit int64 `json:"speed_limit,omitempty"`

	// SpeedLimitUp and SpeedLimitDown are the per-direction caps, from the
	// client's side, in the same unit; absent for unlimited.
	SpeedLimitUp   int64 `json:"speed_limit_up,omitempty"`
	SpeedLimitDown int64 `json:"speed_limit_down,omitempty"`

	// IPLimit is how many distinct addresses the user may be at once, or
	// absent for unlimited; ActiveIPs is how many they count as being at
	// right now. Neither is an address, so neither is gated.
	IPLimit   int `json:"ip_limit,omitempty"`
	ActiveIPs int `json:"active_ips,omitempty"`

	// ClientConns is how many live connections one address may hold to this
	// secret at once, or absent for unlimited. A limit, not an address.
	ClientConns int `json:"client_conns,omitempty"`

	// ClientSpeedLimit is the per-address ceiling in bytes per second, set as
	// client_speed with a human spelling and read back as a number, the way
	// speed is read back as speed_limit; absent for unlimited.
	ClientSpeedLimit int64 `json:"client_speed_limit,omitempty"`

	// ClientFair is whether the secret's speed limits are divided among its
	// addresses, client_fair; absent when they are not. A switch, not an
	// address.
	ClientFair bool `json:"client_fair,omitempty"`

	// Mode is the wire form this secret serialises to: "ee", "dd" or "plain".
	Mode string `json:"mode"`

	// Unserved is true when no configured listener can serve this secret's form:
	// a dd or plain secret on a proxy with no [[listener]]. The secret is stored
	// and valid, it just has no door. It is NOT an error -- one odd client must
	// never take an inbound offline -- but it is the thing an operator needs to
	// see.
	Unserved bool `json:"unserved,omitempty"`

	// Connections and LastSeen are the runtime view of this secret, carried
	// here so a caller rendering one user does not have to fetch and filter the
	// whole of GET /stats to learn whether anybody is on it. They are the same
	// numbers /stats reports, read from the same counters.
	Connections int64      `json:"connections"`
	LastSeen    *time.Time `json:"last_seen"`

	// ConnectedIPs and LastIP mirror the same fields on GET /stats, and are
	// filled in on exactly the same condition: only when the proxy is
	// configured with track-client-ips. See ProxyOpts.TrackClientIPs for why
	// that is off by default.
	//
	// Connections and LastSeen above are NOT gated, because they are not
	// addresses -- knowing that a user has two connections says nothing about
	// where they are.
	ConnectedIPs []string `json:"connected_ips,omitempty"`
	LastIP       string   `json:"last_ip,omitempty"`

	// ConnectedIPsLastSeen is when each connected address last moved a byte,
	// gated as ConnectedIPs is.
	ConnectedIPsLastSeen map[string]time.Time `json:"connected_ips_last_seen,omitempty"`

	// ExternalIPs and ExternalExpiresAt are the addresses a panel reported
	// this user present at elsewhere and when that report lapses, gated
	// exactly as ConnectedIPs is.
	ExternalIPs       []string   `json:"external_ips,omitempty"`
	ExternalExpiresAt *time.Time `json:"external_expires_at,omitempty"`

	// RetiringKeys, RetiringUntil, RetiringConnections and RetiringLastSeen mirror
	// the same four fields on GET /stats, read from the same set and the same
	// counters, and absent for a secret with no unexpired previous key. A count,
	// two times and a count: none is an address, so none is gated, and none is
	// ever a key.
	RetiringKeys        int        `json:"retiring_keys,omitempty"`
	RetiringUntil       *time.Time `json:"retiring_until,omitempty"`
	RetiringConnections int        `json:"retiring_connections,omitempty"`
	RetiringLastSeen    *time.Time `json:"retiring_last_seen,omitempty"`
}

type SecretLimits struct {
	// QuotaBytes is the maximum number of relayed bytes (client read + write)
	// allowed in the current quota period. 0 means unlimited.
	QuotaBytes int64

	// QuotaReset selects how QuotaBytes is replenished.
	QuotaReset QuotaReset

	// ExpiresAt is the instant after which the secret stops working. The zero
	// time means the secret never expires.
	ExpiresAt time.Time

	// Disabled, when true, rejects every new connection for the secret without
	// removing it from the set.
	Disabled bool

	// SpeedBytesPerSecond is the sustained throughput this user is allowed,
	// in bytes per second, upload and download combined, across every
	// connection and every door they use at once. 0 means unlimited.
	//
	// It is a per-user allowance, not a per-connection one: two devices on
	// the same secret share it. It is enforced by holding reads and writes
	// to the rate rather than by buffering, so backpressure reaches the
	// client's own TCP window and nothing is queued in memory.
	SpeedBytesPerSecond int64

	// SpeedUpBytesPerSecond and SpeedDownBytesPerSecond cap one direction each,
	// from the client's side: up is what the client sends, down is what it
	// receives. Each is its own bucket, so a user may be given a slow upload
	// and a fast download, and both apply on top of the combined cap when that
	// is set too. 0 means unlimited.
	SpeedUpBytesPerSecond   int64
	SpeedDownBytesPerSecond int64

	// IPLimit is how many distinct addresses this user may hold connections
	// from at once, counting the addresses of their live connections here
	// together with any a panel has reported them present at elsewhere. 0
	// means unlimited.
	//
	// A connection from an address already counted is always admitted -- a
	// second socket from the same phone is the same device -- and one from a
	// new address is refused while the count is at the limit. An IPv6
	// address counts as its /64. Refusal happens at admission, after the
	// secret matched, so only a holder of the valid secret can observe it.
	IPLimit int

	// ClientConns is how many live connections one address may hold to this
	// secret at once, client-conns: the per-address connection cap. 0 means
	// unlimited.
	//
	// It is counted from the address ledger -- the same unit and the same live
	// count IPLimit reads, so a v4-mapped address is its IPv4 address and an
	// IPv6 address is its /64 -- and not from the per-address table, so it
	// holds when the table is full and counts the connections that were open
	// before it was set. A connection from an address already holding that
	// many is refused after the handshake, as an IPLimit refusal is. An
	// address that does not stand for one place (loopback, private and the
	// like: behind a carrier that forwards no client address, every client) is
	// never capped. Distinct from IPLimit, which counts places: a Telegram
	// client opens several connections, so this is set to a few times that.
	ClientConns int

	// ClientSpeedBytesPerSecond is how fast one address may move bytes on this
	// secret, upload and download combined across all of its connections,
	// client-speed: the per-address ceiling. 0 means unlimited.
	//
	// It is the address's own bucket, beside the user's SpeedBytesPerSecond,
	// which still holds the secret as a whole: an address is held to whichever
	// is reached first, and two addresses are each held to it, not to it
	// between them. An address is the unit IPLimit counts (an IPv4 address, an
	// IPv6 /64). Every peer that does not stand for one place, and every
	// address the per-address table has no room for, shares the secret's one
	// rest entry, which has no ceiling: it stands for many clients at once, and
	// one address's ceiling would hold all of them together.
	ClientSpeedBytesPerSecond int64

	// ClientFair, client-fair, divides the secret's own speed limits among the
	// addresses using it: a work-conserving share, worked out again every
	// second, in which an address that wants less than an even split keeps
	// what it wants and the others share the rest equally, however many
	// connections each holds. Each of SpeedBytesPerSecond,
	// SpeedUpBytesPerSecond and SpeedDownBytesPerSecond that is set is divided
	// on its own, so it needs at least one of them. Without one of speed /
	// speed-up / speed-down the engine treats it as off -- nothing is divided,
	// though as a per-address control it still keeps the secret's addresses'
	// entries; only the config and the HTTP API refuse it. The rest entry --
	// every address that does not stand for one place -- holds one share
	// between them.
	ClientFair bool
}

type SecretMode uint8

type StatsResponse struct {
	StartedAt        time.Time     `json:"started_at"`
	UptimeSeconds    int64         `json:"uptime_seconds"`
	TotalConnections int64         `json:"total_connections"`
	Features         []string      `json:"features"`
	Throttle         *ThrottleJSON `json:"throttle,omitempty"`

	// Listeners and Obfuscated describe the extra obfuscated2 entry. Both are
	// omitted when no [[listener]] is configured, so a deployment that never
	// declared one keeps a byte-identical response.
	Listeners  []ListenerJSON  `json:"listeners,omitempty"`
	Obfuscated *ObfuscatedJSON `json:"obfuscated,omitempty"`

	// FakeTLSHandshake is what the FakeTLS door decided about the hellos that
	// reached its secret scan. It is omitted until the door has counted
	// something, and it is a top-level object on purpose: nothing about the door
	// is a user, and the panel bills every key under Users as one.
	FakeTLSHandshake *FakeTLSJSON `json:"faketls_handshake,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 UnbanResult struct {
	Removed int `json:"removed"`
}

type UnknownSecretAction uint8

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

	QuotaUsed      int64      `json:"quota_used"`
	Quota          int64      `json:"quota,omitempty"`
	QuotaRemaining *int64     `json:"quota_remaining,omitempty"`
	QuotaReset     string     `json:"quota_reset,omitempty"`
	ExpiresAt      *time.Time `json:"expires_at,omitempty"`
	Disabled       bool       `json:"disabled,omitempty"`

	// QuotaCutoffs counts streams ended by reaching the quota, since the
	// process started. A quota nobody reaches shows none.
	QuotaCutoffs int64 `json:"quota_cutoffs,omitempty"`

	// AdTagSkipped counts streams that carried an ad tag but took the direct
	// path anyway because their transport has no middle-proxy reframer. An
	// operator who monetises through @MTProxybot has to be able to see this: a
	// silent skip is a revenue bug nobody can diagnose.
	AdTagSkipped int64 `json:"ad_tag_skipped,omitempty"`

	// AdTagFailed counts streams that carried an ad tag, on a transport the
	// middle proxy handles, and took the direct path because the middle proxy
	// could not be reached or refused them. Unlike a skip this is not by
	// design: a proxy on a network that cannot reach core.telegram.org, or
	// whose ad tag was revoked, shows up here and nowhere else.
	AdTagFailed int64 `json:"ad_tag_failed,omitempty"`

	// SpeedLimit is the user's configured cap in bytes per second, and
	// ThrottledMillis the time their connections have spent held to it. A
	// user with a limit and no throttled time is not reaching it; one whose
	// throttled time grows by a second a second is living at it.
	SpeedLimit      int64 `json:"speed_limit,omitempty"`
	ThrottledMillis int64 `json:"throttled_ms,omitempty"`

	// SpeedLimitUp and SpeedLimitDown are the per-direction caps in bytes per
	// second, from the client's side, or absent for unlimited. ThrottledMillis
	// above counts the time held to any of the three buckets, and to the
	// per-address limiters of the addresses the user connects from.
	SpeedLimitUp   int64 `json:"speed_limit_up,omitempty"`
	SpeedLimitDown int64 `json:"speed_limit_down,omitempty"`

	// IPLimit is the user's address limit; ActiveIPs is how many distinct
	// addresses they count as being at right now, the addresses of their
	// live connections here plus any reported from elsewhere; and
	// IPLimitRefused is how many connections were turned away for arriving
	// from one address too many. The first two are absent when zero, the
	// count is never gated: how many places a user is in says nothing about
	// where.
	IPLimit        int   `json:"ip_limit,omitempty"`
	ActiveIPs      int   `json:"active_ips,omitempty"`
	IPLimitRefused int64 `json:"ip_limit_refused,omitempty"`

	// ClientConns is the per-address connection cap, read back, and
	// ClientConnsRefused is how many connections were turned away for arriving
	// from an address that already held that many. Scalars inside the user
	// object, never a key under users and never an address: both are absent
	// when zero, and neither is gated.
	ClientConns        int   `json:"client_conns,omitempty"`
	ClientConnsRefused int64 `json:"client_conns_refused,omitempty"`

	// ClientSpeedLimit is the per-address ceiling in bytes per second, read
	// back as SpeedLimit is, and absent for unlimited. Time an address spent
	// held to it is in ThrottledMillis.
	ClientSpeedLimit int64 `json:"client_speed_limit,omitempty"`

	// ClientFair is whether the user's speed limits are divided among the
	// addresses they connect from, read back, and absent when they are not.
	// Time an address spent held to its share is in ThrottledMillis.
	ClientFair bool `json:"client_fair,omitempty"`

	// Clients is how many source addresses the per-address table holds an
	// entry for, the shared rest entry not counted, and ClientsOverflow how
	// many connections were sent to the rest entry because the table had no
	// room for their address, since the secret was added. Counts, never
	// addresses: both are absent when zero and neither is gated. The addresses
	// themselves are on GET /secrets/{name}/clients, never here.
	Clients         int   `json:"clients,omitempty"`
	ClientsOverflow int64 `json:"clients_overflow,omitempty"`

	// ConnectedIPs lists the distinct client addresses holding a live
	// connection right now, sorted. LastIP is the address of the most recent
	// admitted connection, which outlives that connection. ExternalIPs are
	// the addresses a panel reported the user present at elsewhere, and
	// ExternalExpiresAt is when that report lapses unless refreshed.
	//
	// All are filled in only when the proxy is configured with
	// track-client-ips, and all are omitted when empty, so /stats on a
	// deployment that never enabled it is byte-identical to before they
	// existed. See ProxyOpts.TrackClientIPs for why that is the default.
	ConnectedIPs      []string   `json:"connected_ips,omitempty"`
	LastIP            string     `json:"last_ip,omitempty"`
	ExternalIPs       []string   `json:"external_ips,omitempty"`
	ExternalExpiresAt *time.Time `json:"external_expires_at,omitempty"`

	// ConnectedIPsLastSeen is, for each address in ConnectedIPs, the second a
	// stream from it last moved a byte: the latest across the streams sharing
	// the address. Gated and omitted exactly as ConnectedIPs is, so a panel
	// can tell a device that fell silent from one still talking.
	ConnectedIPsLastSeen map[string]time.Time `json:"connected_ips_last_seen,omitempty"`

	// RetiringKeys, RetiringUntil, RetiringConnections and RetiringLastSeen are
	// the read-back of a rotation's overlap: how many previous keys of the secret
	// are still accepted, when the last of them stops being (UTC), how many live
	// streams hold a key that is not the secret's current one, and when a stream
	// last came in on a previous key. Four scalars inside the user object, never
	// a key under users and never a key's value: all are absent for a secret
	// with no unexpired previous key, so /stats on a deployment that never
	// rotates is byte-identical to before they existed, and none is gated.
	// handleStats fills them from the set in force, onto users that are already
	// there; ProxyStats itself knows nothing of keys.
	RetiringKeys        int        `json:"retiring_keys,omitempty"`
	RetiringUntil       *time.Time `json:"retiring_until,omitempty"`
	RetiringConnections int        `json:"retiring_connections,omitempty"`
	RetiringLastSeen    *time.Time `json:"retiring_last_seen,omitempty"`
}