datapath

type DNSGuard interface {
	// Enable пускает DNS только к резолверам dns (и запросы самого tt).
	Enable(dns []netip.Addr) error
	// Disable снимает запрет.
	Disable() error
}

type Datapath interface {
	// Start поднимает datapath по конфигу WireGuard, который сервер вернул
	// в GETCONF. Возвращается, когда трафик можно подавать, и не ждёт
	// завершения: остановка — это Close или отмена ctx.
	//
	// ctx живёт не дольше туннеля: его отмена равносильна Close. Исключение —
	// Persistent: там ctx ограничивает только сам запуск.
	Start(ctx context.Context, conf *WGConfig) error

	// Endpoint — адрес из поля Endpoint конфига: порт loopback выбирает ядро,
	// а сервер возвращает его в конфиге обратно. Слушает на нём ядро только
	// без канала в памяти (external); у Piped он номинальный.
	//
	// Осмысленно только после успешного Start; до него — нулевое значение.
	Endpoint() netip.AddrPort

	// Requires — что нужно для запуска: права, файлы рядом с бинарём, внешние
	// программы. Спрашивается до Start, чтобы объяснить нехватку одной строкой,
	// а не падением на середине подключения (architecture.md §09).
	Requires() Requirements

	// Close останавливает datapath и убирает за собой всё, что он создал:
	// адаптер, службу, временный файл конфига с приватным ключом.
	//
	// Close обязан быть безопасным до Start и при повторном вызове: супервизор
	// зовёт его из defer, а Э1 требует снятия datapath даже при панике в ядре
	// (задача F3). Одновременные вызовы — норма (сторож отмены ctx внутри
	// реализации и defer супервизора): каждый вызов возвращается только
	// после того, как уборка закончена, иначе процесс выйдет посреди неё.
	Close() error
}

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

type ExternalOptions struct {
	// Program — путь к wireguard.exe. Пусто — искать самим: реестр, каталог
	// Program Files, затем PATH (см. locateWireGuard).
	Program string
	// Name — имя туннеля. Пусто — DefaultTunnelName.
	Name string
	// Dir — каталог для файла конфига. Пусто — каталог настроек пользователя
	// (qwdtt-cli в os.UserConfigDir). Рядом с бинарём файл не кладётся ни
	// при каких настройках: в нём приватный ключ.
	Dir string
	// Timeout — сколько ждать wireguard.exe. Ноль — DefaultProgramTimeout.
	Timeout time.Duration

	// Logf — куда писать; nil означает молчать. Datapath сам в stdout не
	// пишет — вывод принадлежит CLI.
	Logf func(format string, args ...any)

	// DNSGuard — защита от утечки DNS: включается, когда служба туннеля
	// работает, выключается в Close. Нужна и здесь: с половинами /1 вместо
	// /0 (splitDefaultRoutes) WireGuard свой запрет DNS не включает
	// (plan-e2.md, решение 5). nil — без неё.
	DNSGuard DNSGuard
}

type IPv6Blocker interface {
	// BlockIPv6 задаёт, закрывать ли IPv6 при следующем Enable.
	BlockIPv6(block bool)
}

type Persistent interface {
	// Suspend снимает то, из-за чего трафик системы идёт в туннель, —
	// маршруты и запрет утечки DNS, — и оставляет остальное. Вернёт их
	// следующий успешный Start.
	//
	// Супервизор зовёт его сразу после неудачной попытки, до задержки: пока
	// маршруты ведут в мёртвый туннель, страница капчи VK не загрузится, а
	// капчу ядро просит как раз при переподключении. Безвреден до Start
	// и повторно.
	Suspend() error
}

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

type Piped interface {
	CoreConn() net.PacketConn
}

type Requirements struct {
	// Unsupported — почему реализация не работает на этой системе; nil —
	// работает. Если задано, остальные поля вызывающий не проверяет: права
	// и файлы для того, что здесь всё равно не запустится, советовать незачем
	// (найдено первым прогоном на Linux).
	Unsupported error

	// Admin — нужны права администратора (root). Проверяет их вызывающий:
	// сам datapath о токене процесса ничего не знает.
	Admin bool

	// Files — файлы, которые должны лежать рядом с бинарём, например
	// wintun.dll. Имена, а не пути: искать их — дело вызывающего.
	Files []string

	// Programs — внешние программы, которые должны быть установлены,
	// например wireguard.exe.
	Programs []string

	// Netguard — datapath забирает весь трафик системы, и собственные сокеты
	// ядра нужно увести мимо туннеля, иначе туннель зависит от самого себя
	// (architecture.md §05). Включает netguard вызывающий: он даёт ядру
	// core.Config.DialControl.
	Netguard bool

	// DNSGuard — datapath ставит правила защиты от утечки DNS и ждёт их
	// сессию в своих опциях (поле DNSGuard). Открывает её вызывающий, до
	// подключения: отказ WFP — понятная ошибка сразу, а не цикл
	// переподключений (plan-e2.md, W4).
	DNSGuard bool

	// Warning — ограничение, о котором нужно предупредить пользователя при
	// запуске, даже когда всё остальное на месте. Пустая строка — сказать
	// нечего. CLI печатает его строкой «Предупреждение: …» до подключения.
	//
	// Заведено ради external в Э1 (до netguard он работал только со
	// сплит-конфигом); в Э2 это ограничение снято, и сейчас поле никто
	// не заполняет.
	Warning string
}

type Reserver interface {
	Reserve() (release func(), err error)
}

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

type SocksOptions struct {
	// Listen — адрес SOCKS5-сервера. Пусто — DefaultSocksListen.
	Listen string
	// Auth включает проверку логина и пароля (метод 0x02).
	Auth     bool
	Username string
	Password string

	// Logf — куда писать; nil означает молчать. Через него же проходит вывод
	// wireguard-go и библиотеки SOCKS5: datapath, как и ядро, сам в stdout
	// ничего не пишет — вывод принадлежит CLI.
	Logf func(format string, args ...any)
}

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

type TunOptions struct {
	// Name — имя адаптера, как его покажет Get-NetAdapter. Пусто —
	// DefaultTunnelName.
	Name string

	// Logf — куда писать; nil означает молчать. Сюда же уходит вывод
	// wireguard-go и самого wintun.dll: datapath сам в stdout не пишет.
	Logf func(format string, args ...any)

	// DNSGuard — защита от утечки DNS: включается, когда маршруты стоят,
	// выключается в Suspend и Close. nil — без неё (CLI с -allow-leak, тесты).
	DNSGuard DNSGuard
}

type WGConfig struct {
	// Raw — текст конфига, как он пришёл. Нужен external: штатный WireGuard
	// читает файл сам, и пересобирать конфиг из полей значило бы рисковать
	// потерей того, что разбор не понял.
	Raw string

	// PrivateKeyHex и PeerPublicHex — ключи в том виде, в каком их принимает
	// протокол IPC wireguard-go: hex, а не base64 из файла конфига.
	PrivateKeyHex string
	PeerPublicHex string

	// Addresses — адреса интерфейса, уже без длины префикса: netstack.CreateNetTUN
	// принимает именно адреса.
	Addresses []netip.Addr
	// DNS — резолверы туннеля. Если сервер их не прислал, остаётся 1.1.1.1.
	DNS []netip.Addr
	// MTU — по умолчанию 1280: минимум, гарантированный IPv6, и запас под все
	// заголовки туннеля.
	MTU int

	// AllowedIPs — префиксы строками, как в конфиге: дальше они уходят в IPC
	// без разбора. Пустой список читается как 0.0.0.0/0.
	AllowedIPs []string
	// Endpoint — куда слать UDP. Строка, а не netip.AddrPort: wireguard-go
	// принимает и имя хоста и резолвит его сам. Разбор адреса — EndpointAddrPort.
	Endpoint string
	// Keepalive — PersistentKeepalive в секундах, по умолчанию 25.
	Keepalive uint16
}