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
- func WeekLabel(t time.Time) string
- func WeekStart(t time.Time) time.Time
- type Agents
- type AlertStore
- type AlertWeek
- type Alerts
- type Authority
- type DeploymentCounts
- type Deps
- type Engine
- type Expiry
- type ExpiryWeek
- type Fleet
- type IssuanceWeek
- type Issuances
- type Report
- type Service
- type VersionCounts
- type Window
Constants ¶
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).
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 ¶
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 ¶
AlertStore is the alert store (*monitor.Store).
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 ¶
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 ¶
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.
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.
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 ¶
NewService returns the report service of one tenant.
func (*Service) Get ¶
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.