sam/internet_use_control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 9: Hub API and Apprise alerts (/capabilities, /ask, /notify)

Browse Source 
Build on Phases 1-8. Adds the project side of the frozen Hub contract
(central_ai_llm_master/docs/ask-contract.md) and the alert engine from
AGENTS.md §4 FR-12/FR-13, §8, §11 Phase 9.

- hub: internal/hub implements AskRequest/AskResponse/NotifyRequest and a
  deterministic, read-only Answerer. It answers screen time today/yesterday,
  what is blocked now, and device presence, scoped to one child or all kids.
  Screen time is the foreground-app total per device-day; the domain total is
  used only when a device reports no apps, so a report carrying both is never
  double-counted.
- apprise: internal/apprise is a small Apprise API client (stored key or
  stateless URL mode, optional bearer token, typed notifications).
- alert: internal/alert evaluates device state on an interval and raises one
  Apprise alert per transition: a limit hit (a device becomes blocked) or a
  device offline longer than the threshold. A never-seen device is never
  alerted, and the first observation seeds state without replaying an old
  limit. The alert is recorded before delivery, with its delivery outcome.
- store: migration 005 adds `alerts` (delivery outcome, audited) and
  `alert_state` (per-device dedup). New usage reads from the telemetry detail
  table so the daily answer can be checked independently.
- web: GET /capabilities, POST /ask (read-only) and POST /notify behind the
  shared CONTROL_HUB_TOKEN, separate from the session and admin API tokens.
  /notify accepts the contract's {from,level,message,person} and delivers it
  through Apprise (the future tamper-report path, FR-17).
- cmd/control: start the alert engine (CONTROL_ALERTS_ENABLED,
  CONTROL_ALERT_OFFLINE_AFTER, CONTROL_ALERT_INTERVAL) and add `alerts` and
  `usage` subcommands for read-only inspection.
- deploy/verify-phase9.sh + `make verify-phase9` prove the definition of done;
  version 0.7.0-phase9.

Measured on .13 (2026-10-13):
- GET /capabilities -> internet_use_control topics.
- POST /ask "how long have the kids been on screens today?" -> "The kids have
  had 1h 22m of screen time today." (total_seconds=4925); the independent
  count from the telemetry detail table is also 4925 (app=4925, domain=4800).
- A manual lock raised a delivered limit alert (id 4); an MQTT offline status
  raised a delivered offline alert (id 5); POST /notify delivered (id 6). All
  three report delivered=1 in `alerts`.

Tests: gofmt, go vet ./... and go test ./... pass in golang:1.25-alpine.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Sam Rolfe
2026-10-13 16:41:07 +11:00
parent 4f233a8012
commit 3cf353d933
23 changed files with 2881 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
internal/config/config.go
View File

@@ -73,6 +73,30 @@ type Config struct {
// only until the shared Mosquitto gets the TLS listener; never set it in
// production.
MQTTInsecure bool
// HubToken authenticates the read-only Hub API: GET /capabilities,
// POST /ask and POST /notify (Phase 9, FR-12). Secret; the Hub sends it.
// When it is empty those endpoints answer 503 and nothing else changes.
HubToken string
// AppriseURL is the Apprise API base, for example
// http://192.168.20.35:8210. Alerts are delivered through it (FR-13).
AppriseURL string
// AppriseKey names a stored Apprise configuration. Empty means stateless
// mode, which uses AppriseURLs.
AppriseKey string
// AppriseURLs are the stateless Apprise destinations (APPRISE_URLS).
AppriseURLs []string
// AppriseToken is an optional bearer token when the Apprise API is
// protected. It is empty in this lab.
AppriseToken string
// AlertsEnabled turns the limit/offline alert engine on. When false the
// service still answers /ask and /notify.
AlertsEnabled bool
// AlertOfflineAfter is how long a device may be unreachable before Sam is
// told. Only used when AlertsEnabled is true.
AlertOfflineAfter time.Duration
// AlertInterval is how often the alert engine re-evaluates.
AlertInterval time.Duration
}
// Load reads and validates the configuration.
@@ -94,6 +118,15 @@ func Load() (*Config, error) {
MQTTPassword: os.Getenv("CONTROL_MQTT_PASSWORD"),
MQTTCAFile: env("CONTROL_MQTT_CA_FILE", "/etc/webrestrict/tls/ca.crt"),
MQTTInsecure: envBool("CONTROL_MQTT_INSECURE", false),
HubToken: os.Getenv("CONTROL_HUB_TOKEN"),
AppriseURL: strings.TrimRight(env("CONTROL_APPRISE_URL", DefaultAppriseURL), "/"),
AppriseKey: strings.TrimSpace(os.Getenv("CONTROL_APPRISE_KEY")),
AppriseURLs: splitList(os.Getenv("CONTROL_APPRISE_URLS")),
AppriseToken: os.Getenv("CONTROL_APPRISE_TOKEN"),
AlertsEnabled: envBool("CONTROL_ALERTS_ENABLED", true),
AlertOfflineAfter: durationSetting("CONTROL_ALERT_OFFLINE_AFTER", DefaultAlertOfflineAfter),
AlertInterval: durationSetting("CONTROL_ALERT_INTERVAL", DefaultAlertInterval),
}
secret := os.Getenv("CONTROL_SESSION_SECRET")
@@ -143,6 +176,24 @@ const DefaultMQTTBroker = "tcp://host.docker.internal:1883"
// It matches the lab host's configured zone; set CONTROL_TIMEZONE to override.
const DefaultTimezone = "Australia/Sydney"
// DefaultAppriseURL is the house Apprise API on `.35` (AGENTS.md §2a, §8).
const DefaultAppriseURL = "http://192.168.20.35:8210"
// DefaultAlertOfflineAfter is how long a device may be unreachable before Sam
// is told (FR-13).
const DefaultAlertOfflineAfter = 30 * time.Minute
// DefaultAlertInterval is how often the alert engine re-evaluates device state.
const DefaultAlertInterval = 30 * time.Second
// HubConfigured reports whether the Hub API can serve authenticated requests.
func (c *Config) HubConfigured() bool { return strings.TrimSpace(c.HubToken) != "" }
// AppriseConfigured reports whether alerts can be delivered.
func (c *Config) AppriseConfigured() bool {
return strings.TrimSpace(c.AppriseURL) != "" && (c.AppriseKey != "" || len(c.AppriseURLs) > 0)
}
// MQTTTLS reports whether the broker URL asks for TLS.
func (c *Config) MQTTTLS() bool {
return strings.HasPrefix(c.MQTTBroker, "tls://") || strings.HasPrefix(c.MQTTBroker, "ssl://")
@@ -189,6 +240,35 @@ func envBool(key string, fallback bool) bool {
return b
}
// durationSetting reads a Go duration from the environment, falling back when
// it is empty or unparseable.
func durationSetting(key string, fallback time.Duration) time.Duration {
v := strings.TrimSpace(os.Getenv(key))
if v == "" {
return fallback
}
d, err := time.ParseDuration(v)
if err != nil || d <= 0 {
return fallback
}
return d
}
// splitList parses a comma- or whitespace-separated list. It is used for the
// stateless Apprise destination list (APPRISE_URLS), which contains spaces.
func splitList(s string) []string {
fields := strings.FieldsFunc(s, func(r rune) bool {
return r == ',' || r == ' ' || r == '\t' || r == '\n' || r == '\r'
})
out := make([]string, 0, len(fields))
for _, f := range fields {
if f = strings.TrimSpace(f); f != "" {
out = append(out, f)
}
}
return out
}
func parseLevel(s string) (slog.Level, error) {
switch strings.ToLower(strings.TrimSpace(s)) {
case "debug":

57
internal/config/config_test.go
View File

@@ -129,3 +129,60 @@ func TestMQTTDefaultsAndGuards(t *testing.T) {
t.Error("MQTTEnabled = true, want false when CONTROL_MQTT_ENABLED=false")
}
}
func TestPhase9HubAndAlertDefaults(t *testing.T) {
t.Setenv("CONTROL_SESSION_SECRET", "0123456789abcdef")
t.Setenv("CONTROL_ADMIN_PASSWORD", "hunter2")
t.Setenv("CONTROL_MQTT_INSECURE", "true")
for _, k := range []string{
"CONTROL_HUB_TOKEN", "CONTROL_APPRISE_KEY", "CONTROL_APPRISE_URLS",
"CONTROL_APPRISE_TOKEN", "CONTROL_ALERTS_ENABLED", "CONTROL_ALERT_OFFLINE_AFTER",
"CONTROL_APPRISE_URL",
} {
t.Setenv(k, "")
}
cfg, err := Load()
if err != nil {
t.Fatalf("Load: %v", err)
}
if cfg.HubConfigured() {
t.Error("HubConfigured = true with no CONTROL_HUB_TOKEN")
}
if cfg.AppriseURL != DefaultAppriseURL {
t.Errorf("AppriseURL = %q, want %q", cfg.AppriseURL, DefaultAppriseURL)
}
if cfg.AppriseConfigured() {
t.Error("AppriseConfigured = true with no destination")
}
if !cfg.AlertsEnabled {
t.Error("AlertsEnabled = false, want true by default")
}
if cfg.AlertOfflineAfter != DefaultAlertOfflineAfter {
t.Errorf("AlertOfflineAfter = %v, want %v", cfg.AlertOfflineAfter, DefaultAlertOfflineAfter)
}
t.Setenv("CONTROL_HUB_TOKEN", "hub-secret")
t.Setenv("CONTROL_APPRISE_URLS", "mailto:sam@example.com pushover://x/y")
t.Setenv("CONTROL_ALERT_OFFLINE_AFTER", "10m")
t.Setenv("CONTROL_ALERTS_ENABLED", "false")
cfg, err = Load()
if err != nil {
t.Fatalf("Load: %v", err)
}
if !cfg.HubConfigured() {
t.Error("HubConfigured = false with a token set")
}
if !cfg.AppriseConfigured() {
t.Error("AppriseConfigured = false with CONTROL_APPRISE_URLS set")
}
if len(cfg.AppriseURLs) != 2 {
t.Errorf("AppriseURLs = %#v, want 2 entries", cfg.AppriseURLs)
}
if cfg.AlertOfflineAfter != 10*time.Minute {
t.Errorf("AlertOfflineAfter = %v, want 10m", cfg.AlertOfflineAfter)
}
if cfg.AlertsEnabled {
t.Error("AlertsEnabled = true, want false")
}
}