checkerdef

type ActivationResolver struct {
	// contains filtered or unexported fields
}

type CheckSpec struct {
	// Name is the human-readable name for the sample check.
	Name string

	// Slug is the URL-friendly identifier for the sample check.
	Slug string

	// Period is the check frequency interval.
	Period time.Duration

	// Config is the actual checker configuration.
	Config map[string]any
}

type CheckType string

type CheckTypeMeta struct {
	Type          CheckType     `json:"type"`
	Labels        []string      `json:"labels"`
	Description   string        `json:"description"`
	MinPeriod     time.Duration `json:"-"` // Minimum allowed check period (0 = use global default)
	MaxPeriod     time.Duration `json:"-"` // Maximum allowed check period (0 = no limit)
	DefaultPeriod time.Duration `json:"-"` // Default check period (0 = use global default)

	// SupportsTunnel reports whether the type honors a tunnel dialer
	// (TunnelDialerFrom) and can therefore carry a `tunnelCheckUid` in its
	// config. Declarative metadata rather than a hand-maintained list
	// elsewhere: the API serves it and the dashboard gates its selector on it.
	// Enabled for every TCP-dialing type that routes its probe through the
	// context dialer: http, tcp, the mail protocols (smtp/imap/pop3), ssl, the
	// database drivers (postgres/mysql/mssql/oracle), and the client-library
	// types (redis/mongodb/rabbitmq/kafka/grpc/websocket/ftp/mqtt). UDP/ICMP
	// types cannot — SSH direct-tcpip forwards TCP only.
	SupportsTunnel bool `json:"supportsTunnel"`

	// SupportsIPVersion reports whether the type honors the shared `ipVersion`
	// config key (auto/ipv4/ipv6). Declarative metadata for the same reason as
	// SupportsTunnel: the API serves it and the dashboard gates its selector on
	// it, instead of a hand-maintained type list that would drift.
	//
	// Enabled for the types that resolve a hostname and pick one address
	// themselves (tcp, udp, icmp, ssl, ssh, smtp, imap, pop3, dnsbl) plus http,
	// which pins the family on its transport instead. Deliberately NOT enabled
	// for `dns`: for a DNS check "ipVersion" could mean either which record
	// types to assert on or which transport to reach the nameserver over —
	// different features, neither implemented here, so the option is rejected
	// rather than silently ignored. Everything else either has no network
	// target (heartbeat, email, sleep) or dials by name through a client
	// library that exposes no address-family seam.
	SupportsIPVersion bool `json:"supportsIpVersion"`
}

type CheckTypeStatus struct {
	CheckTypeMeta
	Enabled        bool   `json:"enabled"`
	DisabledReason string `json:"disabledReason,omitempty"`
}

type Checker interface {
	// Type returns the check type identifier this checker handles (e.g., "http", "tcp").
	Type() CheckType

	// Validate checks if the configuration is valid.
	// It shall not perform any network operations.
	// Returns nil if valid, or an error describing what's wrong.
	Validate(spec *CheckSpec) error

	// Execute performs the check and returns the result.
	// The context should be used for cancellation and timeout control.
	// The config is already validated before being passed to Execute.
	// Returns a pointer to Result and an error. If error is not nil, Result will be nil.
	Execute(ctx context.Context, config Config) (*Result, error)
}

type CheckerSamplesProvider interface {
	// GetSampleConfigs returns a slice of sample configurations with metadata.
	GetSampleConfigs(opts *ListSampleOptions) []CheckSpec
}

type Config interface {
	// FromMap populates the configuration from a map.
	// Returns an error if the map contains invalid values.
	// TODO: Remove it
	FromMap(configMap map[string]any) error

	// GetConfig returns the configuration as a map.
	// TODO: Support it through the `models.Result` so that we can pass it directly to the plugins
	GetConfig() map[string]any
}

type ConfigError struct {
	// Parameter is the name of the configuration parameter that failed validation.
	// This should match the field name in the configuration map/struct.
	Parameter string

	// Message is the human-readable error message describing what's wrong.
	Message string
}

type ConfigNormalizer interface {
	NormalizeConfig(configMap map[string]any) (map[string]any, error)
}

type ContextDialer interface {
	DialContext(ctx context.Context, network, addr string) (net.Conn, error)
}

type Diagnostics struct {
	// FailureResponse is the captured response of a FAILED probe. Nil unless
	// the check opted in (HTTP: `capture_failure_response`) AND a response
	// actually existed — a timeout, DNS failure or TLS error produces no
	// response, so the capture degrades to absent and the existing error
	// output remains the only evidence.
	FailureResponse *FailureResponse `json:"failureResponse,omitempty"`

	// Screenshot is the capture of what a FAILING browser check's page looked
	// like. Nil unless the check opted in (browser: `screenshot`) and the
	// capture succeeded.
	//
	// See Screenshot's own doc comment for why its bytes never cross the agent
	// WS control channel.
	Screenshot *Screenshot `json:"screenshot,omitempty"`

	// NetworkFailure states that this probe failed to REACH its target, and
	// names the endpoint it was dialing (spec 2026-08-21-10). It is set at
	// transport-error sites only, which is what makes "an application-level
	// failure never triggers a path trace" a property of where the field is
	// written rather than of a string match on an error message.
	//
	// It is the only member of Diagnostics that is not opt-in per check: it
	// costs a few dozen bytes and only ever exists on a failing probe. The
	// opt-in is on the ACTION it enables (`tracerouteOnFailure`), decided
	// server-side at the incident transition — see NetworkFailure's doc.
	NetworkFailure *NetworkFailure `json:"networkFailure,omitempty"`
}

type DialerFunc func(ctx context.Context, network, addr string) (net.Conn, error)

type EgressCache struct {
	// contains filtered or unexported fields
}

type EgressProbe func(version IPVersion, ip net.IP) error

type FailureResponse struct {
	// URL is the URL the probe requested.
	URL string `json:"url,omitempty"`
	// StatusLine is the response status line, e.g. "HTTP/2.0 503 Service Unavailable".
	StatusLine string `json:"statusLine,omitempty"`
	// StatusCode is the numeric response status.
	StatusCode int `json:"statusCode,omitempty"`
	// Headers are the RESPONSE headers with sensitive values replaced by the
	// redaction marker. Multi-valued headers are joined with ", ".
	Headers map[string]string `json:"headers,omitempty"`
	// Body is the captured response body, truncated to the capture cap. Empty
	// when Binary is true — a non-text or non-UTF-8 body is never stored raw.
	Body string `json:"body,omitempty"`
	// Truncated reports that Body holds only the leading bytes of a larger body.
	Truncated bool `json:"truncated,omitempty"`
	// ContentLength is the response's declared Content-Length, or -1 when the
	// response did not declare one (chunked). It is what tells a reader how
	// much a truncated Body is missing.
	ContentLength int64 `json:"contentLength,omitempty"`
	// ContentType is the raw Content-Type response header.
	ContentType string `json:"contentType,omitempty"`
	// BodyBytes is the size in bytes of the body the probe actually read.
	BodyBytes int `json:"bodyBytes,omitempty"`
	// BodySHA256 is the hex SHA-256 of the bytes the probe read. It is the
	// only identity a binary body gets, and it lets two captures be compared
	// without storing either.
	BodySHA256 string `json:"bodySha256,omitempty"`
	// Binary reports that the body was not text-like or not valid UTF-8, so
	// only metadata (ContentType, BodyBytes, BodySHA256) was kept.
	Binary bool `json:"binary,omitempty"`
	// CapturedAt is when the probe captured this response.
	CapturedAt time.Time `json:"capturedAt,omitzero"`
	// RemoteAddr is the address the probe actually connected to, when the
	// transport reported one.
	RemoteAddr string `json:"remoteAddr,omitempty"`
	// Region is the probing region. Filled SERVER-SIDE from the persisted
	// result row rather than by the checker, so it cannot be influenced by a
	// deported agent's own idea of where it runs.
	Region string `json:"region,omitempty"`
}

type IPVersion string

type ListSampleOptionType uint8

type ListSampleOptions struct {
	Type    ListSampleOptionType
	BaseURL string // Base URL for self-referencing checks (e.g., fake API)
}

type NetworkFailure struct {
	// Class is one of the NetFailure* constants.
	Class string `json:"class"`
	// Host is the configured hostname, for display. May be empty, and may be
	// the same as Address when the check was configured with a literal IP.
	Host string `json:"host,omitempty"`
	// Address is the resolved IP the probe dialed.
	Address string `json:"address,omitempty"`
	// Port is the TCP/UDP port the probe dialed. Zero for ICMP checks, which
	// is exactly what makes the TCP fallback prober unusable for them.
	Port int `json:"port,omitempty"`
}

type Result struct {
	Status   Status         // The check status
	Duration time.Duration  // Time taken to execute the check
	Metrics  map[string]any // Numerical metrics that can be aggregated (e.g., ttfb, dns_time)
	Output   map[string]any // Diagnostic output (error messages, status text, etc.)

	// Diagnostics carries opt-in, incident-only evidence (today: the captured
	// failing HTTP response). It is deliberately NOT part of Output: Output is
	// persisted per raw result row as JSONB, and this payload is kilobytes.
	// See the Diagnostics doc comment for the full rationale. Nil on every
	// path that did not opt in — which is all of them by default.
	Diagnostics *Diagnostics
}

type SMTPJobIdentity struct {
	CheckUID string
}

type Screenshot struct {
	// PNG is the raw image. NEVER SERIALIZED — see the type doc.
	PNG []byte `json:"-"`
	// CapturedAt is when the screenshot was taken.
	CapturedAt time.Time `json:"capturedAt,omitzero"`
	// Available is the agent-side MARKER: "I hold a capture for this result".
	// It is what crosses the wire in place of the bytes, so the server can ask
	// for the upload if (and only if) this result opens an incident.
	Available bool `json:"available,omitempty"`
	// CaptureID names the capture in the agent's local LRU, so the server's
	// upload request can identify which one it wants.
	CaptureID string `json:"captureId,omitempty"`
	// Region is the probing region. Filled SERVER-SIDE from the persisted
	// result row, never by the checker — a deported agent must not be the
	// authority on where it ran.
	Region string `json:"region,omitempty"`
}

type Status int