replace

package
v1.18.0 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package replace moves the stored data of a replaced job/tool key onto the module that declared `Replaces` — typically a plugin extracted from a built-in, whose key differs (notion-ticket-sync → notion_ticket_sync).

What moves, once per (old, new) pair:

  • config rows whose key the new module declares, copied as STORED (a secret's ciphertext is copied byte for byte, never decrypted). A value already set on the new key is kept; only an empty field, or a non-secret still equal to the plugin's declared default, is filled.
  • jobs: schedule, enabled, max_runs and max_timeout_min, while the new job row is still pristine (never configured). Run history stays on the old job row; the report says how many runs it holds.
  • tags, the visibility override and bookmarks of /jobs/<old> or /tools/<old>, merged into the new path.

After that the old key is hidden: the caller unregisters it (Prepare), the jobs service filters it out of every listing (IsReplaced) and its job row is disabled on every boot, so the old job can never run next to the new one. The old rows are not deleted, so removing the plugin brings the old item back intact.

Index

Constants

View Source
const (
	KindJob  = "job"
	KindTool = "tool"
)

Item kinds a pair can carry.

View Source
const (
	ActionCopy = "copy"
	ActionKeep = "keep"
	ActionSkip = "skip"
)

Field actions in a Report.

Variables

This section is empty.

Functions

func IsReplaced

func IsReplaced(jobKey string) bool

IsReplaced reports whether a job key was replaced by another module.

func Path

func Path(kind, key string) string

Path is the item path tags, visibility and bookmarks hang off.

Types

type AccessReport

type AccessReport struct {
	TagsAdded      int    `json:"tags_added"`
	Visibility     string `json:"visibility"` // copy / keep / skip
	BookmarksAdded int    `json:"bookmarks_added"`
}

AccessReport is what happens to tags, visibility and bookmarks.

type FieldReport

type FieldReport struct {
	Key    string `json:"key"`
	Secret bool   `json:"secret"`
	Old    string `json:"old"`
	New    string `json:"new"`
	Action string `json:"action"`
	Reason string `json:"reason"`
}

FieldReport is what happens to one config key. Values of secret fields are shown as "set"/"empty" only.

type JobReport

type JobReport struct {
	Schedule      string `json:"schedule"`
	Enabled       bool   `json:"enabled"`
	MaxRuns       int    `json:"max_runs"`
	MaxTimeoutMin int    `json:"max_timeout_min"`
	Action        string `json:"action"`
	Reason        string `json:"reason"`
	// OldDisabled is true when the old row was enabled and gets switched off.
	OldDisabled bool `json:"old_disabled"`
	// HistoryRuns is how many runs stay recorded under the old key.
	HistoryRuns int64 `json:"history_runs"`
}

JobReport is what happens to the job row.

type Migrator

type Migrator struct {
	// contains filtered or unexported fields
}

Migrator runs replacements against the database.

func New

func New(db *gorm.DB) *Migrator

New returns a Migrator over db.

func (*Migrator) Apply

func (m *Migrator) Apply(ctx context.Context, p Pair, actor string, force bool) (Report, error)

Apply migrates p. A pair already migrated is skipped unless force; either way the old job row is kept disabled. actor is recorded in the audit row.

func (*Migrator) ApplyAll

func (m *Migrator) ApplyAll(ctx context.Context, pairs []Pair)

ApplyAll applies every pair at boot, logging (never failing) per pair.

func (*Migrator) Plan

func (m *Migrator) Plan(ctx context.Context, p Pair) (Report, error)

Plan reports what Apply would move, without writing anything.

type Pair

type Pair struct {
	Kind string `json:"kind"`
	Old  string `json:"old"`
	New  string `json:"new"`
	// Configs are the rows the new module declares (Owner unset).
	Configs []pkgentity.Config `json:"-"`
	// DefaultCron is the new job's declared schedule, used to tell a
	// pristine job row from one an admin already configured.
	DefaultCron string `json:"-"`
}

Pair is one declared replacement: the module New took over Old.

func Collect

func Collect(jobMods []job.Module, toolMods []tool.Module) []Pair

Collect reads Replaces off every registered job and tool module. Self references, blanks and an old key claimed twice (first wins) are dropped with a warning.

func Forget added in v1.16.0

func Forget(newKey string) []Pair

Forget drops the active pairs whose new key is newKey — the replacing module was unloaded while wick runs — and returns them, so the caller can bring the old modules back.

func Lookup

func Lookup(newKey string) []Pair

Lookup returns the active pairs whose new key is newKey.

func Prepare

func Prepare(jobMods []job.Module, toolMods []tool.Module, unregJob, unregTool func(string) bool) []Pair

Prepare collects the declared pairs, unregisters every replaced key so the old module is neither bootstrapped nor routed, and remembers the pairs for IsReplaced / Lookup. Call it after every job/tool (built-in and plugin) is registered and before validation and the configs/jobs bootstrap.

type Report

type Report struct {
	Kind   string `json:"kind"`
	Old    string `json:"old"`
	New    string `json:"new"`
	DryRun bool   `json:"dry_run"`
	// AlreadyDone: the pair was migrated before and no force was asked, so
	// nothing moved this time (the old job is still kept disabled).
	AlreadyDone bool          `json:"already_done"`
	MigratedAt  *time.Time    `json:"migrated_at,omitempty"`
	Configs     []FieldReport `json:"configs"`
	Job         *JobReport    `json:"job,omitempty"`
	Access      AccessReport  `json:"access"`
}

Report describes one pair's migration (planned when DryRun).

func (Report) Summary

func (r Report) Summary() string

Summary is a one-line, value-free description for logs and audit.

Jump to

Keyboard shortcuts

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