api

Documentation

Overview

Package api defines the wire contract between the edge and the central.

Index

• Constants
• Variables
• type Assignments
• type Check
  • func (c Check) Validate() error
  • func (c Check) ValidateShape() error
• type Result
  • func (r Result) Validate() error
• type ResultsRequest
  • func (r ResultsRequest) Validate() error

Constants

const (
	PathHealth      = "/healthz"
	PathAssignments = "/v1/assignments"
	PathResults     = "/v1/results"
)

Paths of the edge API, served by the central.

const (
	KindTCP      = "tcp"        // a connection opens
	KindHTTP     = "http"       // an HTTP request answers as expected
	KindDNS      = "dns"        // a name resolves
	KindTLS      = "tls"        // a certificate is valid, and for long enough
	KindICMP     = "icmp"       // ICMP echo (ping), and how many are lost
	KindNTP      = "ntp"        // a time server answers, and the clock is right
	KindBanner   = "banner"     // a service greets as expected: SSH, SMTP, FTP, ...
	KindClosed   = "closed"     // a port that must not be reachable is not
	KindDownload = "download"   // a file comes down fast enough
	KindRoute    = "traceroute" // the path to a host, and where it ends
	KindDomain   = "domain"     // a domain name that is not about to expire
)

Kinds of check.

const (
	MaxResultsPerBatch = 1000
	MaxErrorLength     = 512
	MaxTargetLength    = 512
	MaxExpectLength    = 256
)

Limits shared by both sides.

Variables

var Kinds = []string{KindTCP, KindHTTP, KindDNS, KindTLS, KindICMP, KindNTP, KindBanner, KindClosed, KindDownload, KindRoute, KindDomain}

Kinds lists every kind of check.

Types

type Assignments

type Assignments struct {
	Checks []Check `json:"checks"`
}

Assignments is what the central answers to an edge poll.

type Check

type Check struct {
	ID     string `json:"id"`
	Kind   string `json:"kind"`
	Target string `json:"target"`
	// Expect refines what a good answer is; each kind says how.
	Expect          string `json:"expect,omitempty"`
	IntervalSeconds int    `json:"interval_seconds"`
}

Check is one measurement an edge runs on a schedule.

func (Check) Validate

func (c Check) Validate() error

Validate reports why a check cannot be run.

func (Check) ValidateShape

func (c Check) ValidateShape() error

ValidateShape is Validate for a check of a kind that may be newer than the reader: an edge keeps such a check, and reports it as unsupported, rather than refusing the whole list.

type Result

type Result struct {
	CheckID   string    `json:"check_id"`
	At        time.Time `json:"at"`
	OK        bool      `json:"ok"`
	RTTMillis float64   `json:"rtt_millis"`
	Error     string    `json:"error,omitempty"`
}

Result is the outcome of one run of a check.

func (Result) Validate

func (r Result) Validate() error

Validate reports why a result must be refused.

type ResultsRequest

type ResultsRequest struct {
	Results []Result `json:"results"`
}

ResultsRequest is a batch of results posted by an edge.

func (ResultsRequest) Validate

func (r ResultsRequest) Validate() error

Validate reports why a batch must be refused.