Documentation
¶
Overview ¶
Package instance owns the Instance's own state (ADR 0032): the one row that no Workspace owns (its random Instance id, the Telemetry report setting, the acknowledged notice) and the rule of who decides about it. It reads across Workspaces, so it holds the raw ent client.
Index ¶
- Variables
- func BuildReport(ctx context.Context, client *ent.Client, host Host, now time.Time) (telemetryapi.TelemetryReport, error)
- func DeployShapeOf(container string) telemetryapi.TelemetryDeployShape
- func ReportOffset(instanceID string) time.Duration
- type Environment
- type Host
- type Lock
- type Module
- func (m *Module) AcknowledgeNotice(ctx context.Context) (State, error)
- func (m *Module) AnnounceRelease(ctx context.Context) error
- func (m *Module) CheckRelease(ctx context.Context) error
- func (m *Module) Ensure(ctx context.Context) (*ent.InstanceState, error)
- func (m *Module) IsOwner(ctx context.Context, userID int64) (bool, error)
- func (m *Module) Jobs() jobs.Extension
- func (m *Module) LatestRelease(ctx context.Context) (string, error)
- func (m *Module) MarkReportSent(ctx context.Context, at time.Time) error
- func (m *Module) Report(ctx context.Context) (telemetryapi.TelemetryReport, error)
- func (m *Module) SetTelemetry(ctx context.Context, enabled bool) (State, error)
- func (m *Module) Setting(ctx context.Context) (Setting, error)
- func (m *Module) State(ctx context.Context) (State, error)
- type Option
- type ReleaseCheckArgs
- type ReleaseSource
- type SendReportArgs
- type Sender
- type SenderOption
- type Setting
- type State
Constants ¶
This section is empty.
Variables ¶
var ErrTelemetryLocked = errors.New("the telemetry setting is decided by the environment")
ErrTelemetryLocked is returned when the Owner tries to change a setting the environment decides.
Functions ¶
func BuildReport ¶
func BuildReport(ctx context.Context, client *ent.Client, host Host, now time.Time) (telemetryapi.TelemetryReport, error)
BuildReport assembles the Telemetry report (ADR 0032) from core tables only: never from an Enterprise Usage snapshot, which a plain install does not have. It is the one builder, the preview and the daily sender both call it. Counts leave it only as orders of magnitude, so an exact number never does, and it reads nothing that names a Workspace or a person.
func DeployShapeOf ¶
func DeployShapeOf(container string) telemetryapi.TelemetryDeployShape
DeployShapeOf maps what upgrade.DetectContainer found ("helm" on Kubernetes, "docker" in a container, "" otherwise) to the schema's deploy shape.
func ReportOffset ¶
ReportOffset is how far into the day (UTC) the Instance reports: a fixed 0 to 6 hours derived from its Instance id, so it is the same every day and after every restart.
Types ¶
type Environment ¶
type Environment struct {
Telemetry *bool
DoNotTrack bool
// ReleaseCheck is SPHERICON_RELEASE_CHECK; it never depends on the two above.
ReleaseCheck bool
// Dev is a development or test environment: neither the Telemetry report nor the
// Release check ever runs there.
Dev bool
// SchemaURL is the page that documents the Telemetry report's schema.
SchemaURL string
}
Environment is what the deployment says about the Instance: SPHERICON_TELEMETRY when set to true or false, DO_NOT_TRACK=1, SPHERICON_RELEASE_CHECK and the version that runs.
func EnvironmentOf ¶
func EnvironmentOf(cfg *config.Config) Environment
EnvironmentOf reads the Instance switches from the configuration.
type Host ¶
type Host struct {
AppVersion string
Edition telemetryapi.TelemetryEdition
DeployShape telemetryapi.TelemetryDeployShape
OS string
Arch string
Locale telemetryapi.TelemetryLocale
// LicenseExpiredAt is when the license key expired; zero unless it has lapsed (ADR 0035).
LicenseExpiredAt time.Time
}
Host is what the report says about the running binary and its surroundings. The builder never reads the process (build info, environment, files): the caller hands these in, so a test builds the same report every time.
type Module ¶
type Module struct {
// contains filtered or unexported fields
}
Module is the Instance state and the rules around it.
func New ¶
func New(client *ent.Client, env Environment, host Host, now func() time.Time, opts ...Option) *Module
New builds the module; a nil clock means time.Now. The host is what the Telemetry report says about the running binary; its AppVersion is the version the Release check compares to.
func (*Module) AcknowledgeNotice ¶
AcknowledgeNotice records that the one-time notice was seen; the first time stands.
func (*Module) AnnounceRelease ¶
AnnounceRelease logs the cached newer release, if any: called at start, so a Self-hoster's logs show it before the next daily check.
func (*Module) CheckRelease ¶
CheckRelease asks the source for the newest release and stores it with the check time only when it is strictly newer than the running version and not a prerelease. A source that cannot be reached leaves the previous result and fails nothing. A build that is not a release, or SPHERICON_RELEASE_CHECK=false, asks nobody.
func (*Module) Ensure ¶
Ensure returns the Instance state row, creating it (with a fresh random Instance id) when this is the first start. Safe to call concurrently and repeatedly.
func (*Module) IsOwner ¶
IsOwner reports whether the User is an Owner of the oldest existing Workspace: the next oldest when that one is deleted, every Owner when there are several, and a transfer follows the role. These Owners alone decide about the Instance.
func (*Module) Jobs ¶
Jobs is the daily Release check, handed to the job client as an extension. A restart checks again at once, which is harmless: the check sends nothing.
func (*Module) LatestRelease ¶
LatestRelease is the cached result of the Release check: a stable release newer than the running version, or empty. It asks nobody.
func (*Module) MarkReportSent ¶
MarkReportSent stores when the last Telemetry report went out.
func (*Module) Report ¶
func (m *Module) Report(ctx context.Context) (telemetryapi.TelemetryReport, error)
Report is the Telemetry report as the Instance would send it now, whether or not sending is on: the same builder the daily sender uses.
func (*Module) SetTelemetry ¶
SetTelemetry stores the Owner's choice; ErrTelemetryLocked when the environment decides.
type Option ¶
type Option func(*Module)
Option configures the module.
func WithLogger ¶
WithLogger sets the logger of the Release check's lines; the default is slog's.
func WithReleaseSource ¶
func WithReleaseSource(s ReleaseSource) Option
WithReleaseSource sets where the Release check asks for the newest release. Without one the check does nothing.
type ReleaseCheckArgs ¶
type ReleaseCheckArgs struct{}
ReleaseCheckArgs is the daily tick of the Release check.
func (ReleaseCheckArgs) Kind ¶
func (ReleaseCheckArgs) Kind() string
type ReleaseSource ¶
ReleaseSource answers "what is the newest stable release", as a bare version: the one lookup `sphericon upgrade` builds, so there is no second way to ask (ADR 0032).
type SendReportArgs ¶
type SendReportArgs struct{}
SendReportArgs is the tick that sends the Telemetry report when one is due.
func (SendReportArgs) Kind ¶
func (SendReportArgs) Kind() string
type Sender ¶
type Sender struct {
// contains filtered or unexported fields
}
Sender sends the daily Telemetry report (ADR 0032). It sends nothing in a development environment or from a build that is not a release, and otherwise only while the effective setting is on, the Owner's notice is acknowledged and a report is due.
func NewSender ¶
NewSender builds the sender over the receiver address in cfg. A development environment (the module's Environment.Dev) never sends, so a test opts in by building its config as production.
type Setting ¶
Setting is the Telemetry report setting as it applies: whether reports are sent and whether the environment (not the Owner) decides.
func Effective ¶
func Effective(env Environment, stored bool) Setting
Effective applies ADR 0032 to the environment and the stored in-app setting (on until an Owner switches it off): off if SPHERICON_TELEMETRY is false or DO_NOT_TRACK=1; on and locked if SPHERICON_TELEMETRY is true; otherwise the stored setting decides. DO_NOT_TRACK only ever switches off. The sender of the report reuses it.
type State ¶
type State struct {
Telemetry Setting
NoticeAcknowledged bool
// LatestRelease is the bare version of a newer stable release, empty when there is none.
LatestRelease string
// LicenseExpiredAt is when the license key expired; zero unless it has lapsed (ADR 0035).
LicenseExpiredAt time.Time
// SchemaURL is the page that documents the Telemetry report's schema.
SchemaURL string
}
State is what an Owner sees about the Instance.
Source Files