Documentation
¶
Overview ¶
Package v4api is the forward package's v4 administrator API, /api/v4/forward/* (docs/architecture/forward-sdk.md section 3, F5a). It is a thin HTTP layer over the kernel's ForwardControl (kernel.forward.v1): routes, the node inventory and the forward node registry (the v2 forward node and Ansible machine routes rewritten), the traffic ledger and the observability views. It reads and writes no table: the kernel owns the forwarding state, and no answer carries a node credential.
The kernel serves the API as the package's manifest control route /api/v4/plugins/forward/* and keeps two checks of its own: DELETE needs a super administrator, and the paths config/editions.json reserves for the commercial edition (user self-service, plans, multipliers; v4.3) do not exist in the community edition. Every endpoint here is in both editions (H23: core forwarding, load balancing, failover and onboarding); commercial endpoints join Endpoints with EditionCommercial under one of those prefixes.
Conventions: JSON bodies; contract messages are protojson with the proto field names and enum names ("ENGINE_NFTABLES"). An answer is {"data": ...}; a refusal {"error": {"code", "message", "violations"}}, each violation {field, message, code, route_id} with the stable codes of sdk/forward/validate. Writes take the Idempotency-Key header as their request id (one is generated without it), so a retried write applies once.
Index ¶
Constants ¶
const ( ControlPrefix = "/api/v4/plugins/forward" PublicPrefix = "/api/v4/forward" )
Path prefixes the kernel sends: the control route namespace, and the public prefix for callers that pass it through unchanged.
const ( EditionAll = "all" EditionCommercial = "commercial" )
Editions an endpoint is served in.
const Route = ControlPrefix + "/*"
Route is the package's manifest control route; the kernel serves it at /api/v4/forward/* too, and dispatches both with RouteID.
Variables ¶
var ProviderKinds = []ProviderKind{ {Kind: "DNS_PROVIDER_KIND_CLOUDFLARE", Name: "Cloudflare", Config: []string{"endpoint"}, Required: []string{}, Credentials: []string{"api_token"}}, {Kind: "DNS_PROVIDER_KIND_ALIDNS", Name: "Alibaba Cloud DNS", Config: []string{"endpoint"}, Required: []string{}, Credentials: []string{"access_key_id", "access_key_secret"}}, {Kind: "DNS_PROVIDER_KIND_DNSPOD", Name: "DNSPod (Tencent Cloud)", Config: []string{"endpoint"}, Required: []string{}, Credentials: []string{"secret_id", "secret_key"}}, {Kind: "DNS_PROVIDER_KIND_HUAWEICLOUD", Name: "Huawei Cloud DNS", Config: []string{"endpoint"}, Required: []string{}, Credentials: []string{"access_key", "secret_key"}}, {Kind: "DNS_PROVIDER_KIND_WEBHOOK", Name: "Webhook", Config: []string{"url"}, Required: []string{"url"}, Credentials: []string{"secret"}}, }
ProviderKinds are the DNS provider kinds of H21.
var RouteID = func() string { digest := sha256.Sum256([]byte("forward\x00" + Route)) return "forward.control." + hex.EncodeToString(digest[:]) }()
RouteID is the route id the kernel gives Route: the package id, ".control." and the hex SHA-256 of the package id, a NUL byte and the route (the kernel's service.PluginControlBridgeRouteID).
Functions ¶
This section is empty.
Types ¶
type Endpoint ¶
type Endpoint struct {
Method string
// Pattern is the path under the prefix; {name} matches one segment.
Pattern string
// Edition is EditionAll or EditionCommercial.
Edition string
// Summary says what it does.
Summary string
// Replaces names the v2 route it rewrites, if any.
Replaces string
// contains filtered or unexported fields
}
Endpoint is one method and path pattern of the API.
type ProviderKind ¶
type ProviderKind struct {
Kind string `json:"kind"`
Name string `json:"name"`
Config []string `json:"config"`
Required []string `json:"required_config"`
Credentials []string `json:"credentials"`
}
ProviderKind describes what a DNS provider kind takes, for a form.
type Request ¶
type Request struct {
Method string
// Path is the request path under ControlPrefix or PublicPrefix.
Path string
Query map[string][]string
Body []byte
IdempotencyKey string
// ActorID is the kernel-authenticated caller.
ActorID uint
// SuperAdmin is the kernel's word that the caller may DELETE (a super
// administrator). The kernel sends it on the list routes, whose answers
// carry it as can_delete (F5b D7); it is false elsewhere.
SuperAdmin bool
}
Request is one API call as the package host receives it.
type Service ¶
type Service struct {
Forward forwardv1.ForwardControlClient
// NewRequestID names a write without an Idempotency-Key; a random id by
// default.
NewRequestID func() string
}
Service answers the API on ForwardControl.
type TargetHealth ¶
type TargetHealth struct {
RouteID string `json:"route_id"`
RouteName string `json:"route_name"`
Paused bool `json:"paused"`
// Key is "host:port".
Key string `json:"key"`
Host string `json:"host"`
Port uint32 `json:"port"`
Weight uint32 `json:"weight"`
Priority uint32 `json:"priority"`
// State is the worst state the reporting nodes see (HEALTH_STATE_*);
// HEALTH_STATE_UNSPECIFIED before any report.
State string `json:"state"`
// Healthy and Reports count the nodes that see it healthy and that
// report it at all.
Healthy int `json:"healthy"`
Reports int `json:"reports"`
// RttUs is the best latest connect round trip; 0 when none succeeded.
RttUs uint32 `json:"rtt_us"`
CheckedAtUnixMs int64 `json:"checked_at_unix_ms"`
CircuitOpenUntil int64 `json:"circuit_open_until_unix_ms,omitempty"`
}
TargetHealth is one target of one route with what the last hop's nodes report about it.
type TopologyEdge ¶
type TopologyEdge struct {
From string `json:"from"`
To string `json:"to"`
RouteID string `json:"route_id"`
HopIndex uint32 `json:"hop_index"`
Engine string `json:"engine"`
// Security is the link's transport (LINK_SECURITY_*); empty to a
// target.
Security string `json:"security,omitempty"`
Paused bool `json:"paused"`
}
TopologyEdge is one link of one route: hop HopIndex's node to the next hop's node, or the last hop's node to a target.
type TopologyNode ¶
type TopologyNode struct {
ID string `json:"id"`
// Kind is "forward", "proxy" or "target".
Kind string `json:"kind"`
Name string `json:"name"`
InInventory bool `json:"in_inventory"`
Reported bool `json:"reported"`
Applied bool `json:"applied"`
HopErrors uint32 `json:"hop_errors"`
// Lagging is true when the node runs an older generation than its
// desired one, or never reported one.
Lagging bool `json:"lagging"`
}
TopologyNode is a node of the graph.
type Total ¶
type Total struct {
RouteID string `json:"route_id"`
HopIndex uint32 `json:"hop_index"`
NodeRef string `json:"node_ref"`
UpBytes uint64 `json:"up_bytes"`
DownBytes uint64 `json:"down_bytes"`
UpPackets uint64 `json:"up_packets"`
DownPackets uint64 `json:"down_packets"`
NewConns uint64 `json:"new_conns"`
}
Total is one route hop's metered traffic on one node over a window.