Documentation
¶
Overview ¶
Package entitlement writes the ping-issued token consumed by plugin runtimes. Purpose: publish only the verified cached licence JWT as a private file. Inputs: context, project directory, and the existing licence cache. Outputs: .nself/state/entitlement.jwt, or E125 with an empty fail-closed file. Constraints: v1.4 never writes; no JWT is exposed in compose or diagnostics. SPORT: runtime entitlement publication for build, start and license set.
Index ¶
- Constants
- Variables
- func AutorefreshDisabled() bool
- func DevKeyMode() bool
- func HasLicensedInstalled() (bool, error)
- func IsLicensedPlugin(dir string) (bool, error)
- func Path(projectDir string) string
- func PublishFromCache(projectDir string) error
- func Refresh(ctx context.Context, projectDir string) error
- func RefreshForPlugins(ctx context.Context, projectDir, pluginDir string) error
- func RefreshForStart(ctx context.Context, projectDir string, warnings io.Writer)
- func RefreshInstalled(ctx context.Context, projectDir string) error
- func RefreshInstalledForKey(ctx context.Context, projectDir, key string) error
- func StartMayContinue(err error, warnings io.Writer) bool
- func TimerWanted() bool
- func ValidateKeyOutsideProject(ctx context.Context, key string) error
- type Outcome
- type RefreshError
- type TimerInstall
- type TimerRemoval
- type Timers
Constants ¶
const ( ClassRejected = "licence-rejected" ClassTokenVerify = "token-verify" ClassNoLicence = "no-licence" ClassNotCovered = "not-covered" ClassWriteFailed = "write-failed" ClassInspect = "plugin-inspect" ClassTimerRemove = "timer-remove-failed" ClassCacheWrite = "cache-write-failed" )
Failure classes printed by the scheduled refresh (`entitlement refresh failed: <class>`).
Variables ¶
var ( ErrTimerUnsafePath = errors.New("unsafe-path") ErrTimerNoBackend = errors.New("no-backend") )
Errors a Timers.Ensure may wrap so the build notice can name the reason.
ErrValidationUnavailable means a saved key could not be checked online. Callers may warn and retry at the next build without failing the key save.
Functions ¶
func AutorefreshDisabled ¶
func AutorefreshDisabled() bool
AutorefreshDisabled reports NSELF_ENTITLEMENT_AUTOREFRESH=false (also 0, no, off); the same rule as maintenance.AutorefreshDisabled, which TestAutorefreshDisabledParity keeps equal.
func DevKeyMode ¶
func DevKeyMode() bool
DevKeyMode identifies the local ping exception, unavailable in release builds. Purpose: preserve release enforcement. Inputs: none. Outputs: false. Constraints: default builds ignore all key override variables. SPORT: devkeys gate.
func HasLicensedInstalled ¶
HasLicensedInstalled reports whether an enabled installed plugin is licensed. Purpose: share the installation gate for refresh and diagnostics. Inputs: NSELF_PLUGIN_DIR or user's default installation. Outputs: status/error. Constraints: disabled plugins are ignored; malformed manifests fail closed. SPORT: contract:plugin.entitlement-token.
func IsLicensedPlugin ¶
IsLicensedPlugin classifies the native manifest's licence axis. Purpose: share build, start and doctor policy without importing L2 plugin code. Inputs: installed plugin directory. Outputs: licensed status or named E125. Constraints: missing manifests are free; malformed manifests fail closed. SPORT: ADR 0005; contract:plugin.entitlement-token.
func Path ¶
Path resolves the private runtime token file. Purpose: share the runtime state location. Inputs: project root. Outputs: path. Constraints: project-local state only. SPORT: entitlement file location.
func PublishFromCache ¶
PublishFromCache rewrites the entitlement file from the verified licence cache without network access (air-gapped `license import`). It does nothing in v1.4 mode or when no licensed plugin is installed.
func Refresh ¶
Refresh publishes a verified cached licence JWT while preserving mounted inodes. Purpose: prepare the runtime token. Inputs: context and project root. Outputs: a private JWT file, or an empty file and E125 if no verified token exists. Constraints: trust server signatures, not cache copies; v1.4 is unchanged. SPORT: runtime entitlement refresh.
func RefreshForPlugins ¶
RefreshForPlugins publishes entitlement for an explicit installation directory. Purpose: bind discovery and coverage to the same plugins. Inputs: context/paths. Outputs: private token/error. Constraints: v1.5 only. SPORT: entitlement refresh.
func RefreshForStart ¶
RefreshForStart reports entitlement failures while allowing free services up. Purpose: isolate licensed availability. Inputs: context/project/warnings. Outputs: warning line. Constraints: runtime Guard fails closed. SPORT: start.
func RefreshInstalled ¶
RefreshInstalled refreshes a project only when a licensed plugin is installed. Purpose: keep free-only stacks independent of licences. Inputs: context/project. Outputs: the refresh result. Constraints: native manifests, no runtime Docker calls. SPORT: start/license-set entitlement publication.
func RefreshInstalledForKey ¶
RefreshInstalledForKey validates a newly set key before publishing its token. Purpose: prevent old-key reuse after license set. Inputs: context/project/new key. Outputs: private runtime file or E125. Constraints: only licensed installations need online validation; a rejected key never retains the old token. SPORT: license-set token capture.
func StartMayContinue ¶
StartMayContinue reports E125 without preventing free services from starting. Purpose: report direct refresh failure. Inputs: error/warnings. Outputs: continuation decision. Constraints: other errors remain fatal. SPORT: licensed-plugin isolation during start.
func TimerWanted ¶
func TimerWanted() bool
TimerWanted reports whether this host should run the refresh timer: v1.5, a licensed plugin in the default plugin directory and autorefresh not disabled. Used by doctor (E132).
func ValidateKeyOutsideProject ¶
ValidateKeyOutsideProject captures the token now for the next project build. Purpose: avoid a stale-cache dead end. Inputs: context/key. Outputs: validation error. Constraints: V15 only; offline saves the key for a later build retry; no file. SPORT: global license set.
Types ¶
type Outcome ¶
type Outcome struct {
Exp time.Time // new token expiry (zero when nothing was refreshed)
Removed bool // the timer's reason is gone and it was removed
RootRequired bool // systemd units remain; the caller exits 78 (maintenance.ExitGone)
Skipped bool // v1.4 mode or development keys: nothing to do
Reason string // why the timer was removed
}
Outcome is the result of one scheduled refresh.
func RunScheduled ¶
RunScheduled is one unattended refresh: it removes the timer when no licensed plugin remains or autorefresh is disabled, otherwise it revalidates online and rewrites the entitlement file in place only after the new JWT verifies and covers every installed licensed plugin.
type RefreshError ¶
RefreshError is a scheduled refresh failure; Error never carries more than the class.
func (*RefreshError) Error ¶
func (e *RefreshError) Error() string
func (*RefreshError) Unwrap ¶
func (e *RefreshError) Unwrap() error
type TimerInstall ¶
TimerInstall is the result of Timers.Ensure.
type TimerRemoval ¶
type TimerRemoval struct{ Removed, RootRequired bool }
TimerRemoval is the result of Timers.Remove; RootRequired means root-owned systemd units remain.
type Timers ¶
type Timers struct {
Ensure func(projectDir, bin string) (TimerInstall, error)
Remove func(projectDir string) (TimerRemoval, error)
}
Timers is the host timer API (internal/maintenance), supplied by the command layer so this package adds no same-layer import edge (repoqa D3). With no functions set no timer is managed.
var (
HostTimers Timers
)
Seams: the host timers (wired by cmd/commands), the clock, the running binary and the notice sink.
Source Files