apphttp

package
v2.8.2 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

Package apphttp registers the Canary app's authenticated HTTP routes and maps internal state and daemon RPC values onto explicit browser DTOs. It owns request validation, redaction, and paired-device attribution, while runtime policy and broker-write authority remain daemon-owned.

Index

Constants

View Source 
const (
	// AppStatusPath is the local-Mac-only app-host health endpoint used by
	// `canary app status`. The relay explicitly refuses to forward it.
	AppStatusPath           = "/api/app-status"
	AppStatusSchemaVersion  = "app-status-v1"
	AppStatusStateReady     = "ready"
	AppStatusStateAttention = "attention"
)

App status route and schema constants define the local operator contract.

View Source 
const (
	// AlertSchemaVersion identifies the browser-facing active alert contract.
	// The separate version field identifies the durable ledger projection.
	AlertSchemaVersion = "alerts-v1"
)

Variables

This section is empty.

Functions

func AppStatusReady added in v2.8.2 

func AppStatusReady(dto AppStatusDTO) bool

AppStatusReady reports whether both halves of alerting are currently able to do their jobs. An active alert episode is not a health failure; only producer initialization/coverage/freshness and dispatcher health matter.

func Register 

func Register(deps Dependencies)

Register installs the embedded SPA, pairing, authenticated read, settings, preview, and paired-device action routes on deps.Server.

Types

type AlertAttentionDTO 

type AlertAttentionDTO struct {
	UnreadCount    int                    `json:"unread_count"`
	HighWaterSeq   uint64                 `json:"high_water_seq"`
	ReadThroughSeq uint64                 `json:"read_through_seq"`
	UnreadRefs     []AlertAttentionRefDTO `json:"unread_refs"`
}

AlertAttentionDTO is a durable render cursor, not proof of human attention.

type AlertAttentionRefDTO 

type AlertAttentionRefDTO struct {
	DisplayID string          `json:"display_id"`
	Source    rpc.AlertSource `json:"source"`
	Kind      rpc.AlertKind   `json:"kind"`
}

AlertAttentionRefDTO identifies one redacted unread occurrence.

type AlertCoverageDTO 

type AlertCoverageDTO struct {
	State           rpc.AlertCoverageState     `json:"state"`
	Freshness       rpc.AlertCoverageFreshness `json:"freshness"`
	AsOf            time.Time                  `json:"as_of"`
	ExpectedSources []rpc.AlertSource          `json:"expected_sources"`
	CoveredSources  []rpc.AlertSource          `json:"covered_sources"`
}

AlertCoverageDTO exposes only aggregate source coverage and freshness.

type AlertDTO 

type AlertDTO struct {
	SchemaVersion  string                  `json:"schema_version"`
	Version        string                  `json:"version"`
	Initialized    bool                    `json:"initialized"`
	Generation     uint64                  `json:"generation"`
	AsOf           *time.Time              `json:"as_of"`
	CurrentState   *rpc.AlertSnapshotState `json:"current_state"`
	Coverage       *AlertCoverageDTO       `json:"coverage"`
	Sources        []AlertSourceDTO        `json:"sources"`
	Occurrences    []AlertOccurrenceDTO    `json:"occurrences"`
	Attention      AlertAttentionDTO       `json:"attention"`
	DeliveryHealth AlertDeliveryHealthDTO  `json:"delivery_health"`
}

AlertDTO is the sole public projection of the app-owned alert ledger. Keep this mapping explicit: adding an internal state field must never publish it accidentally.

type AlertDeliveryController 

type AlertDeliveryController interface {
	SetAlertMode(string) error
	PruneDevices(time.Time) (int, error)
	AddPushSubscription(state.PushSubscription) error
	RemovePushSubscription(string) error
	SendSafeDiagnostic(context.Context, string) (state.GovernanceDiagnosticStatus, bool, error)
}

AlertDeliveryController serializes every production mode or target-topology mutation with final alert confirmation and transport.

type AlertDeliveryHealthDTO 

type AlertDeliveryHealthDTO struct {
	State                       string     `json:"state"`
	Class                       string     `json:"class"`
	UpdatedAt                   *time.Time `json:"updated_at"`
	LastPushServiceAcceptanceAt *time.Time `json:"last_push_service_acceptance_at"`
}

AlertDeliveryHealthDTO exposes only classified app delivery health. It deliberately omits targets, attempts, receipts, and raw transport errors.

type AlertOccurrenceDTO 

type AlertOccurrenceDTO struct {
	DisplayID        string                    `json:"display_id"`
	Source           rpc.AlertSource           `json:"source"`
	Kind             rpc.AlertKind             `json:"kind"`
	PresentationCode rpc.AlertPresentationCode `json:"presentation_code"`
	Title            string                    `json:"title"`
	Body             string                    `json:"body"`
	State            rpc.AlertEpisodeState     `json:"state"`
	Severity         rpc.AlertSeverity         `json:"severity"`
	EvidenceHealth   rpc.AlertEvidenceHealth   `json:"evidence_health"`
	Destination      rpc.AlertDestination      `json:"destination"`
	EvidenceAsOf     time.Time                 `json:"evidence_as_of"`
	StateChangedAt   time.Time                 `json:"state_changed_at"`
	FirstSeenAt      time.Time                 `json:"first_seen_at"`
	LastSeenAt       time.Time                 `json:"last_seen_at"`
	EndedAt          *time.Time                `json:"ended_at"`
	EndReason        *string                   `json:"end_reason"`
	AttentionSeq     uint64                    `json:"attention_seq"`
	Disposition      string                    `json:"disposition"`
}

AlertOccurrenceDTO exposes one redacted occurrence. DisplayID is the only public identity; producer keys, fingerprints, and delivery attempt identity remain private.

type AlertProducerStatusDTO added in v2.8.2 

type AlertProducerStatusDTO struct {
	Initialized  bool                    `json:"initialized"`
	AsOf         *time.Time              `json:"as_of"`
	CurrentState *rpc.AlertSnapshotState `json:"current_state"`
	Coverage     *AlertCoverageDTO       `json:"coverage"`
	Sources      []AlertSourceDTO        `json:"sources"`
}

AlertProducerStatusDTO reports the app's last daemon-authored alert snapshot. It is producer evidence, separate from the app-owned dispatcher state below, and contains no account, candidate, or transport identity.

type AlertSourceDTO 

type AlertSourceDTO struct {
	Source         rpc.AlertSource         `json:"source"`
	Status         string                  `json:"status"`
	Reason         string                  `json:"reason"`
	EvidenceHealth rpc.AlertEvidenceHealth `json:"evidence_health"`
	InputAsOf      *time.Time              `json:"input_as_of"`
	ObservedAt     *time.Time              `json:"observed_at"`
	EvidenceAsOf   *time.Time              `json:"evidence_as_of"`
	FreshUntil     *time.Time              `json:"fresh_until"`
	Covered        bool                    `json:"covered"`
}

AlertSourceDTO preserves the exact typed source reason, health, and timing evidence. Nil times mean that source has not yet been observed.

type AppStatusDTO added in v2.8.2 

type AppStatusDTO struct {
	SchemaVersion   string                 `json:"schema_version"`
	Version         string                 `json:"version"`
	State           string                 `json:"state"`
	AlertProducer   AlertProducerStatusDTO `json:"alert_producer"`
	AlertDispatcher AlertDeliveryHealthDTO `json:"alert_dispatcher"`
}

AppStatusDTO is the redacted local operator health contract for the app host. A successful response itself proves HTTP liveness; State summarizes whether producer coverage and dispatcher readiness are both current.

type BrokerWriteConfirmation 

type BrokerWriteConfirmation struct {
	ConfirmAccount string `json:"confirm_account,omitempty"`
	ConfirmMode    string `json:"confirm_mode,omitempty"`
}

BrokerWriteConfirmation carries a paired user's account/mode affirmation. Matching it is necessary request validation, not broker-write authority; the daemon's current policy, freeze, preview, and execution gates remain binding.

type Dependencies 

type Dependencies struct {
	Server          *hyperserve.Server
	Store           *state.Store
	Auth            *auth.Manager
	Daemon          daemonclient.Client
	Live            *live.Service
	Relay           relay.Client
	PublicURL       string
	Version         string
	AlertController AlertDeliveryController
}

Dependencies supplies the app host's explicit adapters and authorities to the HTTP layer. Registering a daemon client makes RPC methods reachable but does not transfer daemon policy or broker-write authority to HTTP.

type GovernanceDTO 

type GovernanceDTO struct {
	Candidates            []rpc.NudgeCandidate             `json:"candidates"`
	SourceHealth          GovernanceSourceHealth           `json:"source_health"`
	PollSource            GovernancePollSource             `json:"poll_source"`
	Reconciliation        *ReconciliationDTO               `json:"reconciliation,omitempty"`
	ConfirmedFlowCoverage *rpc.NudgeConfirmedFlowCoverage  `json:"confirmed_flow_coverage,omitempty"`
	Context               *rpc.NudgeSnapshotContext        `json:"context,omitempty"`
	Occurrences           []GovernanceOccurrenceDTO        `json:"occurrences"`
	DeliveryHealth        AlertDeliveryHealthDTO           `json:"delivery_health"`
	Diagnostic            state.GovernanceDiagnosticStatus `json:"diagnostic"`
}

GovernanceDTO is the typed SPA boundary. Current candidates retain the foundation's opaque semantic fingerprint; durable evidence is projected from the source-neutral alert-delivery ledger (the legacy governance ledger is retired), so delivery health is the shared alert transport health, and per-attempt rows are not exposed.

type GovernanceOccurrenceDTO added in v2.5.4 

type GovernanceOccurrenceDTO struct {
	DisplayID   string    `json:"display_id"`
	Kind        string    `json:"kind"`
	State       string    `json:"state"`
	Severity    string    `json:"severity"`
	Title       string    `json:"title"`
	Body        string    `json:"body"`
	Destination string    `json:"destination"`
	OccurredAt  time.Time `json:"occurred_at"`
	FirstSeenAt time.Time `json:"first_seen_at"`
	LastSeenAt  time.Time `json:"last_seen_at"`
	ResolvedAt  time.Time `json:"resolved_at,omitzero"`
}

GovernanceOccurrenceDTO is one governance-sourced row projected from the source-neutral delivery ledger. Producer keys, evidence fingerprints, and transport identities are deliberately absent; title and body are fixed Canary presentation copy, never daemon or broker free text.

type GovernancePollSource 

type GovernancePollSource struct {
	State         string    `json:"state"`
	Reason        string    `json:"reason,omitempty"`
	UpdatedAt     time.Time `json:"updated_at,omitzero"`
	LastSuccessAt time.Time `json:"last_success_at,omitzero"`
}

GovernancePollSource describes freshness of the app-to-daemon poll itself; daemon evaluator/source health remains a separate typed field.

type GovernanceSourceHealth 

type GovernanceSourceHealth struct {
	Aggregate      string               `json:"aggregate"`
	Policy         rpc.NudgeInputHealth `json:"policy"`
	Reconciliation rpc.NudgeInputHealth `json:"reconciliation"`
	Capital        rpc.NudgeInputHealth `json:"capital"`
	Pins           rpc.NudgeInputHealth `json:"pins"`
	Cadence        rpc.NudgeInputHealth `json:"cadence"`
	ConfirmedFlow  rpc.NudgeInputHealth `json:"confirmed_flow"`
}

GovernanceSourceHealth is a wire value rather than rpc.NudgeSourceHealth so its JSON encoding preserves the result-level aggregate that was normalized with candidate context.

type ReconciliationDTO 

type ReconciliationDTO struct {
	Report     ReconciliationReportDTO     `json:"report"`
	Evaluation ReconciliationEvaluationDTO `json:"evaluation"`
}

ReconciliationDTO keeps report production and policy evaluation as separate browser concepts.

type ReconciliationEvaluationDTO 

type ReconciliationEvaluationDTO struct {
	State  string `json:"state"`
	Reason string `json:"reason,omitempty"`
}

ReconciliationEvaluationDTO reports the daemon's distinct policy-evaluation state and reason without conflating it with report generation.

type ReconciliationReportDTO 

type ReconciliationReportDTO struct {
	State              string `json:"state"`
	Reason             string `json:"reason,omitempty"`
	ExpectedCoverageTo string `json:"expected_coverage_to,omitempty"`
	CoverageTo         string `json:"coverage_to,omitempty"`
	LastAttemptAt      string `json:"last_attempt_at,omitempty"`
	LastCompletedAt    string `json:"last_completed_at,omitempty"`
	NextAttemptAt      string `json:"next_attempt_at,omitempty"`
	RetryAutomatic     bool   `json:"retry_automatic"`
	CanCheckNow        bool   `json:"can_check_now"`
}

ReconciliationReportDTO is the allowlisted browser projection of report generation cadence and coverage; empty timestamps mean unavailable evidence.

type SafePushTestResult 

type SafePushTestResult struct {
	State               string `json:"state"`
	PushServiceAccepted bool   `json:"push_service_accepted"`
}

SafePushTestResult reports a redacted diagnostic transport class. A true PushServiceAccepted is not proof of device display or human attention.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.