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 ErrorCode
• type HTTPAPIDNSSettings
• type HTTPAPIErrorResp
• type HTTPAPIHTTPSettings
• type JSONDuration
  • func (d JSONDuration) MarshalJSON() (b []byte, err error)
  • func (d *JSONDuration) UnmarshalJSON(b []byte) (err error)
• type JSONTime
  • func (t JSONTime) MarshalJSON() (b []byte, err error)
  • func (t *JSONTime) UnmarshalJSON(b []byte) (err error)
• 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() (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 (
	// ErrorCodeTMP000 is the temporary error code used for all errors.
	ErrorCodeTMP000 = ""
)

ErrorCode constants.

TODO(a.garipov): Expand and document codes.

Types

type Config

type Config struct {
	// 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 ErrorCode

type ErrorCode string

ErrorCode is the error code as used by the HTTP API. See the ErrorCode definition in the OpenAPI specification.

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     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 HTTPAPIErrorResp

type HTTPAPIErrorResp struct {
	Code ErrorCode `json:"code"`
	Msg  string    `json:"msg"`
}

HTTPAPIErrorResp is the error response as used by the HTTP API. See the BadRequestResp, InternalServerErrorResp, and similar objects in the OpenAPI specification.

type HTTPAPIHTTPSettings

type HTTPAPIHTTPSettings struct {
	Addresses       []netip.AddrPort `json:"addresses"`
	SecureAddresses []netip.AddrPort `json:"secure_addresses"`
	Timeout         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 JSONDuration

type JSONDuration time.Duration

JSONDuration is a time.Duration that can be decoded from JSON and encoded into JSON according to our API conventions.

func (JSONDuration) MarshalJSON

func (d JSONDuration) MarshalJSON() (b []byte, err error)

MarshalJSON implements the json.Marshaler interface for JSONDuration. err is always nil.

func (*JSONDuration) UnmarshalJSON

func (d *JSONDuration) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON implements the json.Marshaler interface for *JSONDuration.

type JSONTime

type JSONTime time.Time

JSONTime is a time.Time that can be decoded from JSON and encoded into JSON according to our API conventions.

func (JSONTime) MarshalJSON

func (t JSONTime) MarshalJSON() (b []byte, err error)

MarshalJSON implements the json.Marshaler interface for JSONTime. err is always nil.

func (*JSONTime) UnmarshalJSON

func (t *JSONTime) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON implements the json.Marshaler interface for *JSONTime.

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     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         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      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() (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.