backend

type Controller interface {
	// Bind4 binds fd to any internet-capable IPv4 interface.
	Bind4(who, addrport string, fd int)
	// Bind6 binds fd to any internet-capable IPv6 interface.
	// also: github.com/lwip-tcpip/lwip/blob/239918c/src/core/ipv6/ip6.c#L68
	Bind6(who, addrport string, fd int)
	// Protect marks fd as protected.
	Protect(who string, fd int)
}

type DNSListener interface {
	ResolverListener
	// OnQuery is called when a DNS query is received. The listener
	// can return a DNSOpts to modify
	OnQuery(domain string, qtyp int) *DNSOpts
	// OnResponse is called when a DNS response is received.
	OnResponse(*DNSSummary)
}

type DNSOpts struct {
	// pid is the proxy to use for this query.
	PID string
	// csv of ips to answer for this query; incl unspecified.
	IPCSV string
	// csv of transports ids to use for this query.
	TIDCSV string
	// bypass on-device blocklists.
	NOBLOCK bool
}

type DNSResolver interface {
	DNSTransportMult
	RDNSResolver
}

type DNSSummary struct {
	Type           string  // dnscrypt, dns53, doh, odoh, dot
	ID             string  // transport id
	Latency        float64 // Response (or failure) latency in seconds
	QName          string  // query domain
	QType          int     // A, AAAA, SVCB, HTTPS, etc.
	RData          string  // response data, usually a csv of ips
	RCode          int     // response code
	RTtl           int     // response ttl
	Server         string
	RelayServer    string // hop, if any; proxy or a relay server
	Status         int
	Blocklists     string // csv separated list of blocklists names, if any.
	UpstreamBlocks bool   // true if any among upstream transports returned blocked ans.
	Msg            string // final status message, if any
}

type DNSTransport interface {
	// uniquely identifies this transport
	ID() string
	// one of DNS53, DOH, DNSCrypt, System
	Type() string
	// Median round-trip time for this transport, in millis.
	P50() int64
	// Return the server host address used to initialize this transport.
	GetAddr() string
	// State of the transport after previous query (see: queryerror.go)
	Status() int
}

type DNSTransportMult interface {
	// Add adds a transport to this multi-transport.
	Add(t DNSTransport) bool
	// Remove removes a transport from this multi-transport.
	Remove(id string) bool
	// Get returns a transport from this multi-transport.
	Get(id string) (DNSTransport, error)
	// Stop stops this multi-transport.
	Stop() error
	// Refresh re-registers transports and returns a csv of active ones.
	Refresh() (string, error)
	// LiveTransports returns a csv of active transports.
	LiveTransports() string
}

type IpTree interface {
	// Adds value v to the cidr route.
	Add(cidr, v string) error
	// Sets cidr route to v, overwriting any previous value.
	Set(cidr, v string) error
	// Removes value v, if found.
	Esc(cidr, v string) bool
	// Deletes cidr route. Returns true if cidr was found.
	Del(cidr string) bool
	// Gets the value of cidr or "" if cidr is not found.
	Get(cidr string) (string, error)
	// Returns true if the cidr route is found.
	Has(cidr string) (bool, error)
	// Returns csv of all routes matching cidr or "".
	Routes(cidr string) string
	// Returns csv of values of all routes matching cidr or "".
	Values(cidr string) string
	// Returns the route@csv(value) of any route matching cidr or "".
	GetAny(cidr string) (string, error)
	// Returns true if any route matches cidr.
	HasAny(cidr string) (bool, error)
	// Removes values like v for cidr.
	EscLike(cidr, likev string) int32
	// Returns csv of all routes with any value like v matching cidr.
	RoutesLike(cidr, likev string) string
	// Returns csv of all routes with values like v for cidr.
	ValuesLike(cidr, likev string) string
	// Returns csv of all values like v for cidr.
	GetLike(cidr, likev string) string
	// Returns the longest route for cidr as "r1@csv(v)|r2@csv(v2)" or "".
	GetAll(cidr string) (string, error)
	// Deletes all routes matching cidr. Returns the number of routes deleted.
	DelAll(cidr string) int32
	// Clears the trie.
	Clear()
	// Returns the number of routes.
	Len() int
}

type PipKey interface {
	// Token gnerates a 32 byte randomized token (auths dataplane ops; see: tokensize)
	Token() string
	// Blind generates id:blindMsg:blindingFactor:salt:msg
	// id is a 64 byte hmac tying blindMsg to the public key
	// blindMsg is a 256 byte blinded message
	// blindingFactor is upto 256 byte random blinding factor
	// salt is 48 bytes random salt (see: hashfn)
	// msg is a 32 byte random message (see: msgsize)
	Blind() (string, error)
	// Finalize returns msg:sig for a finalized blind-signature
	Finalize(blindSig string) (string, error)
}

type Protector interface {
	// Returns ip to bind given a network, n
	UIP(n string) []byte
}

type Proxies interface {
	// Add adds a proxy to this multi-transport.
	AddProxy(id, url string) (Proxy, error)
	// Remove removes a transport from this multi-transport.
	RemoveProxy(id string) bool
	// GetProxy returns a transport from this multi-transport.
	GetProxy(id string) (Proxy, error)
	// Router returns a lowest common denomination router for this multi-transport.
	Router() Router
	// Stop stops all proxies.
	StopProxies() error
	// Refresh re-registers proxies and returns a csv of active ones.
	RefreshProxies() (string, error)
}

type Proxy interface {
	// ID returns the ID of this proxy.
	ID() string
	// Type returns the type of this proxy.
	Type() string
	// Returns routes.
	Router() Router
	// GetAddr returns the address of this proxy.
	GetAddr() string
	// DNS returns the ip:port or doh/dot url or dnscrypt stamp for this proxy.
	DNS() string
	// Status returns the status of this proxy.
	Status() int
	// Stop stops this proxy.
	Stop() error
	// Refresh re-registers this proxy.
	Refresh() error
}

type ProxyListener interface {
	// OnProxyAdded is called when a proxy is added.
	OnProxyAdded(id string)
	// OnProxyRemoved is called when a proxy is removed except when all
	// proxies are stopped, in which case OnProxiesStopped is called.
	OnProxyRemoved(id string)
	// OnProxiesStopped is called when all proxies are stopped.
	// Note: OnProxyRemoved is not called for each proxy.
	OnProxiesStopped()
}

type RDNS interface {
	// SetStamp sets the rethinkdns blockstamp.
	SetStamp(string) error
	// GetStamp returns the current rethinkdns blockstamp.
	GetStamp() (string, error)
	// StampToNames returns csv group:names of blocklists in the given stamp s.
	StampToNames(s string) (string, error)
	// FlagsToStamp returns a blockstamp for given csv blocklist-ids, if valid.
	FlagsToStamp(csv string, enctyp int) (string, error)
	// StampToFlags retruns csv blocklist-ids given a valid blockstamp s.
	StampToFlags(s string) (string, error)
}

type RDNSResolver interface {
	// SetRdnsLocal sets the local rdns resolver.
	SetRdnsLocal(trie, rank, conf, filetag string) error
	// GetRdnsLocal returns the local rdns resolver.
	GetRdnsLocal() (RDNS, error)
	// SetRdnsRemote sets the remote rdns resolver.
	SetRdnsRemote(filetag string) error
	// GetRdnsRemote returns the remote rdns resolver.
	GetRdnsRemote() (RDNS, error)
	// Translate enables or disables ALG responses
	Translate(bool)
}

type RadixTree interface {
	// Adds k to the trie. Returns true if k was not already in the trie.
	Add(k string) bool
	// Sets k to v in the trie, overwriting any previous value.
	Set(k, v string)
	// Deletes k from the trie. Returns true if k was in the trie.
	Del(k string) bool
	// Gets the value of k from the trie or "" if k is not in the trie.
	Get(k string) string
	// Returns true if k is in the trie.
	Has(k string) bool
	// Returns the value of the longest prefix of k in the trie or "".
	GetAny(prefix string) string
	// Returns true if any key in the trie has the prefix.
	HasAny(prefix string) bool
	// Deletes all keys in the trie with the prefix. Returns the number of keys deleted.
	DelAll(prefix string) int32
	// Clears the trie.
	Clear()
	// Returns the number of keys in the trie.
	Len() int
}

type ResolverListener interface {
	// OnDNSAdded is called when a new DNS transport with id is added.
	OnDNSAdded(id string)
	// OnDNSRemoved is called when a DNS transport with id is removed, except
	// when the transport is stopped, then OnDNSStopped is called instead.
	OnDNSRemoved(id string)
	// OnDNSStopped is called when the DNS transport is stopped. Note:
	// OnDNSRemoved is not called for each transport before this.
	OnDNSStopped()
}

type Router interface {
	// IP4 returns true if this router supports IPv4.
	IP4() bool
	// IP6 returns true if this router supports IPv6.
	IP6() bool
	// MTU returns the MTU of this router.
	MTU() (int, error)
	// Stats returns the stats of this router.
	Stat() *Stats
	// Contains returns true if this router can route ipprefix.
	Contains(ipprefix string) bool
}

type Stats struct {
	Addr   string // address of the router
	Rx     int64  // bytes received
	Tx     int64  // bytes transmitted
	ErrRx  int64  // receive errors
	ErrTx  int64  // transmit errors
	LastRx int64  // last receive in millis
	LastTx int64  // last transmit in millis
	LastOK int64  // last handshake or ping or connect millis
	Since  int64  // uptime in millis
}

type WgKey interface {
	// IsZero returns true if the key is all zeros.
	IsZero() bool
	// Base64 returns the key as a base64-encoded string.
	Base64() string
	// Hex returns the key as a hex-encoded string.
	Hex() string
	// Mult returns the key multiplied by the basepoint (curve25519).
	Mult() WgKey
}