v4api

package
v4.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: MIT Imports: 16 Imported by: 0

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

View Source
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.

View Source
const (
	EditionAll        = "all"
	EditionCommercial = "commercial"
)

Editions an endpoint is served in.

View Source
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

View Source
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.

View Source
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.

func Endpoints

func Endpoints() []Endpoint

Endpoints lists the API, in match order.

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 Response

type Response struct {
	StatusCode int
	Body       []byte
}

Response is the HTTP answer.

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.

func (*Service) Serve

func (s *Service) Serve(ctx context.Context, request Request) Response

Serve answers one request.

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.

type TrendPoint

type TrendPoint struct {
	HourStartUnixMs int64  `json:"hour_start_unix_ms"`
	UpBytes         uint64 `json:"up_bytes"`
	DownBytes       uint64 `json:"down_bytes"`
	NewConns        uint64 `json:"new_conns"`
}

TrendPoint is one hour of traffic summed over the filter.

type Violation

type Violation struct {
	Field   string `json:"field"`
	Message string `json:"message"`
	Code    string `json:"code"`
	RouteID string `json:"route_id,omitempty"`
}

Violation is one reason a write was refused.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL