websvc

Documentation

Overview

Package websvc contains the AdGuard Home HTTP API service.

NOTE: Packages other than cmd must not import this package, as it imports most other packages.

TODO(a.garipov): Add tests.

Index

• Constants
• type Config
• type ConfigManager
• type HTTPAPIDNSSettings
• type HTTPAPIHTTPSettings
• type PprofConfig
• type ReqPatchSettingsDNS
• type ReqPatchSettingsHTTP
• type RespGetV1SettingsAll
• type RespGetV1SystemInfo
• type Service
  • func New(c *Config) (svc *Service, err error)
  • func (svc *Service) Config() (c *Config)
  • func (svc *Service) Shutdown(ctx context.Context) (err error)
  • func (svc *Service) Start(ctx context.Context) (err error)

Constants

const (
	PathRoot     = "/"
	PathFrontend = "/*filepath"

	PathHealthCheck = "/health-check"

	PathV1SettingsAll  = "/api/v1/settings/all"
	PathV1SettingsDNS  = "/api/v1/settings/dns"
	PathV1SettingsHTTP = "/api/v1/settings/http"
	PathV1SystemInfo   = "/api/v1/system/info"
)

Path constants

const (
	PathPatternFrontend       = "/"
	PathPatternHealthCheck    = "/health-check"
	PathPatternV1SettingsAll  = "/api/v1/settings/all"
	PathPatternV1SettingsDNS  = "/api/v1/settings/dns"
	PathPatternV1SettingsHTTP = "/api/v1/settings/http"
	PathPatternV1SystemInfo   = "/api/v1/system/info"
)

Path pattern constants.

Types

type Config

type Config struct {
	// Logger is used for logging the operation of the web API service.  It must
	// not be nil.
	Logger *slog.Logger

	// Pprof is the configuration for the pprof debug API.  It must not be nil.
	Pprof *PprofConfig

	// ConfigManager is used to show information about services as well as
	// dynamically reconfigure them.
	ConfigManager ConfigManager

	// Frontend is the filesystem with the frontend and other statically
	// compiled files.
	Frontend fs.FS

	// TLS is the optional TLS configuration.  If TLS is not nil,
	// SecureAddresses must not be empty.
	TLS *tls.Config

	// Start is the time of start of AdGuard Home.
	Start time.Time

	// OverrideAddress is the initial or override address for the HTTP API.  If
	// set, it is used instead of [Addresses] and [SecureAddresses].
	OverrideAddress netip.AddrPort

	// Addresses are the addresses on which to serve the plain HTTP API.
	Addresses []netip.AddrPort

	// SecureAddresses are the addresses on which to serve the HTTPS API.  If
	// SecureAddresses is not empty, TLS must not be nil.
	SecureAddresses []netip.AddrPort

	// Timeout is the timeout for all server operations.
	Timeout time.Duration

	// ForceHTTPS tells if all requests to Addresses should be redirected to a
	// secure address instead.
	//
	// TODO(a.garipov): Use; define rules, which address to redirect to.
	ForceHTTPS bool
}

Config is the AdGuard Home web service configuration structure.

type ConfigManager

type ConfigManager interface {
	DNS() (svc agh.ServiceWithConfig[*dnssvc.Config])
	Web() (svc agh.ServiceWithConfig[*Config])

	UpdateDNS(ctx context.Context, c *dnssvc.Config) (err error)
	UpdateWeb(ctx context.Context, c *Config) (err error)
}

ConfigManager is the configuration manager interface.

type HTTPAPIDNSSettings

type HTTPAPIDNSSettings struct {
	Addresses           []netip.AddrPort     `json:"addresses"`
	BootstrapServers    []string             `json:"bootstrap_servers"`
	UpstreamServers     []string             `json:"upstream_servers"`
	DNS64Prefixes       []netip.Prefix       `json:"dns64_prefixes"`
	UpstreamTimeout     aghhttp.JSONDuration `json:"upstream_timeout"`
	BootstrapPreferIPv6 bool                 `json:"bootstrap_prefer_ipv6"`
	UseDNS64            bool                 `json:"use_dns64"`
}

HTTPAPIDNSSettings are the DNS settings as used by the HTTP API. See the DnsSettings object in the OpenAPI specification.

type HTTPAPIHTTPSettings

type HTTPAPIHTTPSettings struct {
	Addresses       []netip.AddrPort     `json:"addresses"`
	SecureAddresses []netip.AddrPort     `json:"secure_addresses"`
	Timeout         aghhttp.JSONDuration `json:"timeout"`
	ForceHTTPS      bool                 `json:"force_https"`
}

HTTPAPIHTTPSettings are the HTTP settings as used by the HTTP API. See the HttpSettings object in the OpenAPI specification.

type PprofConfig

type PprofConfig struct {
	Port    uint16 `yaml:"port"`
	Enabled bool   `yaml:"enabled"`
}

PprofConfig is the configuration for the pprof debug API.

type ReqPatchSettingsDNS

type ReqPatchSettingsDNS struct {
	Addresses        jsonpatch.NonRemovable[[]netip.AddrPort] `json:"addresses"`
	BootstrapServers jsonpatch.NonRemovable[[]string]         `json:"bootstrap_servers"`
	UpstreamServers  jsonpatch.NonRemovable[[]string]         `json:"upstream_servers"`
	DNS64Prefixes    jsonpatch.NonRemovable[[]netip.Prefix]   `json:"dns64_prefixes"`

	UpstreamTimeout jsonpatch.NonRemovable[aghhttp.JSONDuration] `json:"upstream_timeout"`

	BootstrapPreferIPv6 jsonpatch.NonRemovable[bool] `json:"bootstrap_prefer_ipv6"`
	UseDNS64            jsonpatch.NonRemovable[bool] `json:"use_dns64"`
}

ReqPatchSettingsDNS describes the request to the PATCH /api/v1/settings/dns HTTP API.

type ReqPatchSettingsHTTP

type ReqPatchSettingsHTTP struct {
	Addresses       jsonpatch.NonRemovable[[]netip.AddrPort] `json:"addresses"`
	SecureAddresses jsonpatch.NonRemovable[[]netip.AddrPort] `json:"secure_addresses"`

	Timeout jsonpatch.NonRemovable[aghhttp.JSONDuration] `json:"timeout"`

	ForceHTTPS jsonpatch.NonRemovable[bool] `json:"force_https"`
}

ReqPatchSettingsHTTP describes the request to the PATCH /api/v1/settings/http HTTP API.

type RespGetV1SettingsAll

type RespGetV1SettingsAll struct {
	DNS  *HTTPAPIDNSSettings  `json:"dns"`
	HTTP *HTTPAPIHTTPSettings `json:"http"`
}

RespGetV1SettingsAll describes the response of the GET /api/v1/settings/all HTTP API.

type RespGetV1SystemInfo

type RespGetV1SystemInfo struct {
	Arch       string           `json:"arch"`
	Channel    string           `json:"channel"`
	OS         string           `json:"os"`
	NewVersion string           `json:"new_version,omitempty"`
	Start      aghhttp.JSONTime `json:"start"`
	Version    string           `json:"version"`
}

RespGetV1SystemInfo describes the response of the GET /api/v1/system/info HTTP API.

type Service

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

Service is the AdGuard Home web service. A nil *Service is a valid agh.Service that does nothing.

func New

func New(c *Config) (svc *Service, err error)

New returns a new properly initialized *Service. If c is nil, svc is a nil *Service that does nothing. The fields of c must not be modified after calling New.

TODO(a.garipov): Get rid of this special handling of nil or explain it better.

func (*Service) Config

func (svc *Service) Config() (c *Config)

Config returns the current configuration of the web service. Config must not be called simultaneously with Start. If svc was initialized with ":0" addresses, addrs will not return the actual bound ports until Start is finished.

func (*Service) Shutdown

func (svc *Service) Shutdown(ctx context.Context) (err error)

Shutdown implements the agh.Service interface for *Service. svc may be nil.

func (*Service) Start

func (svc *Service) Start(ctx context.Context) (err error)

Start implements the agh.Service interface for *Service. svc may be nil. After Start exits, all HTTP servers have tried to start, possibly failing and writing error messages to the log.

TODO(a.garipov): Use the context for cancelation as well.