health

package
v1.0.4 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: GPL-3.0 Imports: 8 Imported by: 0

Documentation

Overview

Package health answers a question the container runtime cannot: is this service actually EARNING, as distinct from merely running?

Desktop's status column is built from the container's own state, which is computed from starts, stops and crashes. A service that has produced nothing for a month still shows a green "running" pill, because from the runtime's point of view nothing is wrong. "It runs but earns nothing" is the most common complaint in this whole product category, and container state is structurally incapable of seeing it.

So this is a SEPARATE verdict, deliberately. A service can be a perfectly healthy container and a dead producer, and collapsing the two hides exactly the case the user cares about. It ports the idea from the web sibling's app/producer_state.py.

Two signals feed it, and they are the two Desktop can actually observe:

  • Log signals — the per-service regexes declared in the service catalog (docker.health_signals). Service-specific knowledge lives in the catalog, never here, and for the catalogued services with no earnings collector this is the only signal there is.
  • Restart loops — a container the runtime itself reports as "restarting" spends most of its life starting up rather than working. This is the runtime's own observation, not a tally kept here: Desktop records an event for a user action that failed, never for a container that exited on its own, so counting those events would accuse a healthy service of looping because the user clicked Deploy three times while the container runtime was off.

What is NOT here matters just as much. There is no "producing" verdict: nothing Desktop can see from a container proves money moved, and a green "earning" badge that means "we found no problem" is the false confidence this package exists to remove. The worst answer is a confident one we cannot support, so anything we could not check says so.

Index

Constants

View Source
const NativeRuntime = "native"

NativeRuntime is the runtime kind for a service supervised as a process on the user's own machine (internal/runtime.NativeRuntimeKind). It is repeated here rather than imported so this package stays a leaf with no runtime dependency.

Variables

This section is empty.

Functions

func Collect

func Collect(ctx context.Context, logs LogReader, services ServiceLookup, deployed []Deployed) map[string]Report

Collect returns the producer verdict for every deployed service, keyed by slug.

Logs are read ONLY for a service whose catalog entry declares signals to match them against, and only while its container is up, except the last run's log of a container whose entry declares an account_disabled signal, read through a RunLogReader — reading a log tail nobody has a pattern for would be a container-runtime round trip per service per refresh, spent to learn nothing. A natively supervised process is skipped for a second reason: the catalog's signals sit under its docker: stanza and explain themselves in terms of a container, so matching them there produces advice the user cannot act on.

The log reads run at the same time, each under its own logTimeout, so the whole collection costs one timeout at most rather than one per service: ten deployed services on a wedged runtime used to hold a dashboard refresh for thirty seconds.

func IsWindowed added in v0.25.3

func IsWindowed(s catalog.HealthSignal) bool

IsWindowed reports whether a signal is judged over hours of logs, not the tail.

func MatchRefusal added in v0.28.1

func MatchRefusal(logs string, signals []catalog.HealthSignal) string

MatchRefusal returns the explanation of the first account_disabled signal found at the end of a finished run's log, or "". The text is searched as a whole, never line by line: pawns-cli prints "user is disabled" with no newline on every start.

func WindowedHit added in v0.25.3

func WindowedHit(lines string, s catalog.HealthSignal) bool

WindowedHit is true when the pattern matches at least MinMatches lines of the window and the unless pattern none. No line at all is no hit: a node nobody has used has nothing to judge.

Types

type Deployed

type Deployed struct {
	Slug string
	// ContainerState is the runtime's word for it; empty means it could not be asked.
	ContainerState string
	// Runtime is which backend is running it: "docker", "podman" or NativeRuntime.
	Runtime string
}

Deployed is one deployed service as the caller sees it, before any judgement.

type Hit

type Hit struct {
	Pattern string
	Means   string
	State   State
}

Hit is one declared signal that was found in the logs.

func MatchSignals

func MatchSignals(logs string, signals []catalog.HealthSignal) []Hit

MatchSignals returns the declared signals whose pattern appears in the logs. An invalid regex is skipped rather than fatal: a typo in one service's catalog entry must not break the verdict for every other service.

type Input

type Input struct {
	Slug string
	// ContainerState is the runtime's own word for the container: "running",
	// "restarting", "exited", "created". An EMPTY string means we could not ask,
	// which is not the same claim as "it is stopped" — telling a user their service
	// is down when we simply could not look sends them to restart something that is
	// probably up.
	ContainerState string
	// Native says this service runs as a supervised process on the user's own
	// machine rather than in a container. The catalog's signals live under its
	// docker: stanza and their explanations are written about a container -- the
	// mysterium one tells the user to redeploy a container that, here, does not
	// exist -- so they are not matched against a native process's logs.
	Native bool
	// Signals are the log patterns this service's catalog entry declares. None is the
	// normal case: most services declare none, and that makes them not-checked rather
	// than fine.
	Signals []catalog.HealthSignal
	// Logs is the recent log tail. LogsRead says whether reading them actually worked,
	// because an empty string is both "the read failed" and "the service is quiet",
	// and only one of those is worth telling the user about.
	Logs     string
	LogsRead bool
	// WindowHits are the windowed signals that held at their last check.
	WindowHits []Hit
	// Refusal is the explanation of the account_disabled signal the last finished
	// run printed, or "" when none did (see MatchRefusal).
	Refusal string
}

Input is everything Assess is allowed to reason from, gathered by the caller.

type LogReader

type LogReader interface {
	Logs(ctx context.Context, slug string, lines int) (string, error)
}

LogReader reads a deployed service's recent log tail. It is the one-method slice of the services manager this package needs, so the collection can be tested without a container runtime.

type Report

type Report struct {
	Slug    string   `json:"slug"`
	State   State    `json:"state"`
	Reasons []string `json:"reasons"`
}

Report is the producer verdict for one service, ready to hand to the UI. Reasons is what the user is shown; it is populated for every state, including not-checked, because "why don't you know?" is the first question a bare "not checked" provokes.

func Assess

func Assess(in Input) Report

Assess combines the available signals into one verdict for one service.

type RunLogReader added in v0.28.1

type RunLogReader interface {
	LastRunLogs(ctx context.Context, slug string, lines int) (string, error)
}

RunLogReader reads the log of a service's last finished run only, or "" when it has none worth judging (see runtime.DockerProvider.LastRunLogs). A refusal is judged only through it: a plain tail can hold an earlier run's refusal after the account came back, and calling that run disabled hides Start until the service is removed.

type ServiceLookup

type ServiceLookup interface {
	Get(slug string) (catalog.Service, bool)
}

ServiceLookup finds a catalog entry by slug: *catalog.Catalog, narrowed.

type State

type State string

State is a producer verdict. "Earning" is not among them, and that is the point: no signal here can prove it.

const (
	// StateNotChecked means we have no basis for a claim either way: the container is
	// not running, its service declares no log signals, its logs could not be read, or
	// they were read and showed nothing known. Not a clean bill of health.
	StateNotChecked State = "not-checked"
	// StateIdle means a declared signal says the service is up but doing no paid work.
	StateIdle State = "idle"
	// StateFailing means a declared signal says it is broken, or it is restart-looping.
	StateFailing State = "failing"
	// StateAccountDisabled means the provider refuses to run the client: its last
	// finished run printed an account_disabled signal. Restarting cannot help, and
	// only the provider can turn the account back on.
	StateAccountDisabled State = catalog.SignalAccountDisabled
)

func (State) NotEarning

func (s State) NotEarning() bool

NotEarning reports whether this verdict is a positive finding that the service is running without earning. StateNotChecked is deliberately false: we did not find it healthy, we found nothing.

type WindowReader added in v0.25.3

type WindowReader interface {
	LogsMatching(ctx context.Context, slug string, since time.Duration, match *regexp.Regexp, lines int) (string, error)
	SignalVars(slug string) map[string]string
}

WindowReader reads hours of a service's logs, filtered, and the values its signal texts are filled from. *services.Manager, narrowed.

Jump to

Keyboard shortcuts

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