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 ¶
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
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// 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 ¶
PprofConfig is the configuration for the pprof debug API.
type ReqPatchSettingsDNS ¶
type ReqPatchSettingsDNS 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"`
}
ReqPatchSettingsDNS describes the request to the PATCH /api/v1/settings/dns HTTP API.
type ReqPatchSettingsHTTP ¶
type ReqPatchSettingsHTTP struct {
Addresses []netip.AddrPort `json:"addresses"`
SecureAddresses []netip.AddrPort `json:"secure_addresses"`
Timeout aghhttp.JSONDuration `json:"timeout"`
}
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 ¶
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 ¶
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 ¶
Shutdown implements the agh.Service interface for *Service. svc may be nil.
func (*Service) Start ¶
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.
Source Files