adminapi

Documentation

Overview

Package adminapi описывает протокол управления списком доступа.

Один и тот же набор команд обслуживают два канала: локальный unix-сокет и управляющий поток внутри туннеля, доступный пирам с ролью администратора. Формат общий намеренно - иначе два способа управления неизбежно разъехались бы по возможностям.

Index

• Constants
• func Decode(data []byte, v any) error
• func Encode(v any) ([]byte, error)
• type PeerSpec
• type PeerView
• type RemoteConfig
• type Request
• type Response
  • func Errorf(format string, args ...any) Response
  • func Local(socketPath string, req Request) (Response, error)
  • func Remote(ctx context.Context, cfg RemoteConfig, req Request) (Response, error)
• type StatusView
• type UpdateSpec

Constants

const (
	// CmdPeerAdd добавляет пира в хранилище.
	CmdPeerAdd = "peer.add"
	// CmdPeerRemove убирает пира из хранилища.
	CmdPeerRemove = "peer.remove"
	// CmdPeerUpdate продлевает подписку и меняет лимиты.
	CmdPeerUpdate = "peer.update"
	// CmdPeerList перечисляет всех известных пиров.
	CmdPeerList = "peer.list"
	// CmdStatus отдаёт сводку по серверу.
	CmdStatus = "status"
)

Команды протокола.

const (
	SourceConfig = "config"
	SourceStore  = "store"
)

Источники пира.

Functions

func Decode

func Decode(data []byte, v any) error

Decode разбирает значение протокола.

func Encode

func Encode(v any) ([]byte, error)

Encode сериализует значение протокола.

Types

type PeerSpec

type PeerSpec struct {
	Name      string `json:"name,omitempty"`
	PublicKey string `json:"public_key"`
	// Address закрепляет виртуальный адрес. Пусто - выдать из пула.
	Address string `json:"address,omitempty"`
	// ExpiresAt в формате RFC 3339. Пусто - бессрочно.
	ExpiresAt string `json:"expires_at,omitempty"`
	// QuotaBytes - лимит трафика в байтах. Ноль - безлимит.
	QuotaBytes uint64 `json:"quota_bytes,omitempty"`
}

PeerSpec - описание добавляемого пира. Поля строковые: протокол должен оставаться читаемым и стабильным независимо от внутренних типов сервера.

type PeerView

type PeerView struct {
	Name      string `json:"name,omitempty"`
	PublicKey string `json:"public_key"`
	Address   string `json:"address,omitempty"`
	Role      string `json:"role"`
	ExpiresAt string `json:"expires_at,omitempty"`
	// QuotaBytes и UsedBytes - лимит трафика и расход. Ноль в квоте
	// означает безлимит.
	QuotaBytes uint64 `json:"quota_bytes,omitempty"`
	UsedBytes  uint64 `json:"used_bytes,omitempty"`
	// Source показывает, откуда пир взялся: "config" или "store".
	// Удалить командой можно только пиров из хранилища.
	Source string `json:"source"`

	Connected bool   `json:"connected"`
	RxBytes   uint64 `json:"rx_bytes,omitempty"`
	TxBytes   uint64 `json:"tx_bytes,omitempty"`
}

PeerView - пир глазами управления.

type RemoteConfig

type RemoteConfig struct {
	Server     string
	ServerKey  noise.PublicKey
	PrivateKey noise.PrivateKey
	SNI        string
}

RemoteConfig - параметры подключения к серверу по туннелю.

type Request

type Request struct {
	Command string `json:"command"`
	// Peer заполняется для peer.add.
	Peer *PeerSpec `json:"peer,omitempty"`
	// PublicKey заполняется для peer.remove и peer.update.
	PublicKey string `json:"public_key,omitempty"`
	// Update заполняется для peer.update.
	Update *UpdateSpec `json:"update,omitempty"`
}

Request - команда управления.

type Response

type Response struct {
	OK    bool   `json:"ok"`
	Error string `json:"error,omitempty"`
	// Peers заполняется для peer.list и peer.add.
	Peers []PeerView `json:"peers,omitempty"`
	// Status заполняется для status.
	Status *StatusView `json:"status,omitempty"`
}

Response - ответ на команду.

func Errorf

func Errorf(format string, args ...any) Response

Errorf собирает ответ с ошибкой.

func Local

func Local(socketPath string, req Request) (Response, error)

Local отправляет команду через локальный unix-сокет сервера.

func Remote

func Remote(ctx context.Context, cfg RemoteConfig, req Request) (Response, error)

Remote отправляет команду по управляющему каналу внутри туннеля.

Полноценный клиент здесь не нужен: администратору не требуются ни TUN, ни маршруты - только рукопожатие и один управляющий обмен. Сервер выдаст виртуальный адрес как обычному пиру, но пользоваться им никто не станет.

type StatusView

type StatusView struct {
	Subnet    string `json:"subnet"`
	Address   string `json:"address"`
	PublicKey string `json:"public_key"`
	Peers     int    `json:"peers"`
	Connected int    `json:"connected"`
	Uptime    string `json:"uptime"`
	// Listen - то, что стоит в конфигурации сервера, например ":443".
	// Публичный адрес сервер не знает: снаружи он может быть за NAT
	// или за несколькими адресами сразу.
	Listen string `json:"listen"`
	// TLSServerName - имя в сертификате. Клиенту оно нужно как значение
	// sni, чтобы обе стороны выглядели согласованно.
	TLSServerName string `json:"tls_server_name,omitempty"`
}

StatusView - сводка по серверу.

type UpdateSpec

type UpdateSpec struct {
	// ExpiresAt в формате RFC 3339.
	ExpiresAt string `json:"expires_at,omitempty"`
	// ClearExpiry делает доступ бессрочным.
	ClearExpiry bool `json:"clear_expiry,omitempty"`
	// QuotaBytes - новый лимит трафика; ноль вместе с SetQuota снимает лимит.
	QuotaBytes *uint64 `json:"quota_bytes,omitempty"`
	// ResetUsage обнуляет израсходованный трафик - обычное действие
	// при продлении подписки на новый период.
	ResetUsage bool `json:"reset_usage,omitempty"`
}

UpdateSpec - изменение подписки. Указатели отличают «не трогать» от «выставить значение», отдельные флаги - от «снять ограничение».