report

package
v0.3.8 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package report builds the datasets of the Reports page and GET /reports (docs/PHASE3.md section 14): the expiry forecast, the issuances per week by source, the certificates per CA and status, the alert history and the agent fleet.

Everything is computed from data the server already holds, through the existing services with a system principal, after the caller passed the tenant-wide authz.ReadPKI check (Service.Get). Nothing is stored and nothing leaves the server: the package imports no network package.

Untrusted text. CA names, agent host names and similar strings come from operators and, one step removed, from CSRs, ACME clients and agents. The datasets carry them as raw strings and never as markup; escaping is the job of the template and of the JSON encoder that render them.

Index

Constants

View Source
const (
	// ExpiryWeeks: the current ISO week and 12 more.
	ExpiryWeeks = 13
	// IssuanceWeeks: 12 weeks ending with the current one.
	IssuanceWeeks = 12
	// AlertWeeks: the current week and 4 before it, which covers what the
	// store keeps.
	AlertWeeks = 5
	// AlertRetentionDays is how long the monitor keeps resolved alerts
	// (internal/server/monitor.go, monitorKeep). The report does not change it.
	AlertRetentionDays = 30
	// CacheTTL is how long a built report is reused: the monitor's period.
	CacheTTL = time.Minute
)

Shape of the datasets (docs/PHASE3.md D7).

View Source
const FailTTL = 5 * time.Second

FailTTL is how long a failed build is remembered: for this long every caller gets the same error at once, instead of each one repeating the full build against a database that is failing.

Variables

This section is empty.

Functions

func WeekLabel

func WeekLabel(t time.Time) string

WeekLabel is the ISO week of t as "2026-W47".

func WeekStart

func WeekStart(t time.Time) time.Time

WeekStart is the Monday 00:00 UTC of the ISO week that contains t.

Types

type Agents

type Agents interface {
	ListAgents(ctx context.Context, who keys.Who) ([]agents.Agent, error)
	GetAgent(ctx context.Context, who keys.Who, id string) (*agents.Agent, error)
}

Agents is what the report reads about agents (*agents.Service).

type AlertStore

type AlertStore interface {
	Since(ctx context.Context, since time.Time) ([]monitor.Alert, error)
}

AlertStore is the alert store (*monitor.Store).

type AlertWeek

type AlertWeek struct {
	Start             time.Time
	Warning, Critical int
}

AlertWeek counts the alerts that were first seen in one week.

type Alerts

type Alerts struct {
	RetentionDays int
	// Weeks counts the alerts opened per ISO week by severity (the severity
	// they have now), the oldest week first.
	Weeks []AlertWeek
	// Open is how many alerts hold right now.
	Open int
}

Alerts is the alert history the store keeps.

type Authority

type Authority struct {
	ID, Name string
	// External: the certificates without a CA; ID and Name are empty and the
	// page gives it a label.
	External bool
	// Valid includes Expiring (it ends within ca.ExpiringWindow), the same
	// as the Certificates page with status "valid"; a chart that stacks the
	// four draws Valid-Expiring, Expiring, Expired and Revoked.
	Valid, Expiring, Expired, Revoked int64
}

Authority is a CA with its certificate counts.

type DeploymentCounts

type DeploymentCounts struct{ Deployed, Pending, Failed, RolledBack int }

DeploymentCounts are the deployments (removed ones not) by state.

type Deps

type Deps struct {
	Tenant string // for the permission check of Service.Get
	Engine Engine
	Agents Agents // nil = the agent listener is off, no fleet
	Alerts AlertStore
	Rules  monitor.Rules
	// ServerVersion is the running version, compared with the agents'.
	ServerVersion string
	Clock         clock.Clock
	// Who reads the data: a system principal that may read the whole tenant.
	// The zero value means authz.System("report").
	Who keys.Who
	// Log gets the debug line with the duration of a build; nil = no logging.
	Log *slog.Logger
}

Deps are the inputs of one tenant's report.

type Engine

type Engine interface {
	CAs(ctx context.Context, who keys.Who) ([]ca.CAInfo, error)
	CertificateCounts(ctx context.Context, who keys.Who, filters ...ca.CertificateFilter) (ca.Counts, map[string]ca.Counts, error)
	ExpiryTimes(ctx context.Context, who keys.Who, after, until time.Time) ([]time.Time, error)
	IssuanceSources(ctx context.Context, who keys.Who, since, until time.Time) ([]ca.Issuance, error)
}

Engine is what the report reads from the CA engine (*ca.Engine).

type Expiry

type Expiry struct {
	Weeks []ExpiryWeek // ExpiryWeeks entries, the current week first
}

Expiry is the expiry timeline: when the valid certificates end.

type ExpiryWeek

type ExpiryWeek struct {
	Start  time.Time // Monday 00:00 UTC
	Count  int
	Window Window
}

ExpiryWeek counts the certificates (imported and external ones included, agent identity certificates and revoked ones not) that end in one ISO week. The current week counts only those that end after now.

type Fleet

type Fleet struct {
	// Active agents reported within AgentSilentWarn (or have not reported
	// yet, as the monitor treats them); then the silent ones.
	Active, SilentWarning, SilentCritical int
	Disabled, Revoked                     int
	Version                               VersionCounts
	Deployments                           DeploymentCounts
}

Fleet is the agent fleet. The counts of states cover every agent; the version and deployment counts cover the agents that are not disabled or revoked, like the rules of the monitor.

type IssuanceWeek

type IssuanceWeek struct {
	Start       time.Time
	ACME, Agent int
	UI          int
}

IssuanceWeek counts the certificates of source "issued" created in one ISO week: ACME clients, agents and the UI or API (docs/PHASE3.md D6). The current week is partial.

func (IssuanceWeek) Total

func (w IssuanceWeek) Total() int

Total is every issuance of the week.

type Issuances

type Issuances struct {
	Weeks []IssuanceWeek // IssuanceWeeks entries, the oldest first
}

Issuances is the number of certificates issued per week and source.

type Report

type Report struct {
	GeneratedAt time.Time
	Expiry      Expiry
	Issuances   Issuances
	// Authorities: one entry per CA with certificates and per active CA,
	// sorted by name; the external certificates (no CA) come last.
	Authorities []Authority
	Alerts      Alerts
	// Agents is nil when the agent listener is off.
	Agents *Fleet
}

Report is the five datasets, all times UTC. A cached Report is shared by every caller: treat it as read-only.

func Build

func Build(ctx context.Context, d Deps, now time.Time) (*Report, error)

Build reads the data and computes the five datasets at now. It does no permission check: Service.Get does, and is the way in.

type Service

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

Service builds the report of one tenant and keeps the result for CacheTTL. It is the way in for the API and the pages.

func NewService

func NewService(d Deps) *Service

NewService returns the report service of one tenant.

func (*Service) Get

func (s *Service) Get(ctx context.Context, who keys.Who) (*Report, error)

Get returns the report to who. The tenant-wide authz.ReadPKI check comes first and no data is read for a caller who fails it (a role limited to one CA does: the report names every CA, agent and alert of the tenant). The cache belongs to the tenant, not to the caller, and has no key that comes from a request. The Report is shared: do not change it.

One build at a time: a caller that finds a build in progress waits for it, but gives up when its own context ends. A failed build is remembered for FailTTL (except when the caller of that build gave up: that says nothing about the data).

type VersionCounts

type VersionCounts struct{ Current, Older, Unknown int }

VersionCounts compare the agent versions with the server's. Current includes an agent that is newer. Unknown: the server runs a development build or a version is not strict semver.

type Window

type Window string

Window tells whether an expiry week lies inside a monitor window.

const (
	WindowCritical Window = "critical"
	WindowWarning  Window = "warning"
	WindowNone     Window = "none"
)

Windows of an expiry week: it starts inside the critical window, inside the warning window, or later.

Jump to

Keyboard shortcuts

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