Documentation
¶
Overview ¶
Package skilljournal makes a skill import transaction restart-safe.
A transaction publishes several imported trees, the configuration file, and the lockfile with independent renames. No filesystem makes that sequence one atomic step, so the transaction instead records its intent — and a durable copy of everything it is about to replace — in a journal inside its staging directory before it touches anything live.
If the process dies part way through, the journal survives. The next operation to enter the project lock calls Recover, which rolls the whole transaction back to the exact state it started from: no skill is left missing or half-published, and configuration, imported trees, and lock state can never be stranded at different generations.
Index ¶
- Constants
- Variables
- func LegacyInstruction(name string) string
- func MarkCommitted(stagingRoot string) error
- func Recover(targets Targets) error
- func RecoverBoth(root string) error
- func Rollback(targets Targets, applied Progress, ...) error
- func StagingRoot(importedSkillsDir string) string
- func Write(stagingRoot string, doc Document) error
- type Document
- type Progress
- type Targets
- type WriteIntent
Constants ¶
const ( // StagingDirName is the transaction staging directory inside the imported // skill tier. Keeping it on the same filesystem guarantees rename-based // publication rather than a cross-device copy. It is hidden so skill // enumeration never mistakes it for an imported skill. StagingDirName = ".staging" // FileName is the journal document inside the staging directory. FileName = "journal.json" // StagedTreePrefix names a fully materialized replacement tree. StagedTreePrefix = "new-" // WriteBackupPrefix names the previous tree of a replaced skill. WriteBackupPrefix = "old-" // DeleteBackupPrefix names the previous tree of a deleted skill. DeleteBackupPrefix = "removed-" // ConfigBackupName is the pre-transaction configuration file copy. ConfigBackupName = "config.backup" // LockBackupName is the pre-transaction lockfile copy. LockBackupName = "lock.backup" )
const AdoptionVersion = 2
AdoptionVersion extends recovery with explicitly retired local skill slots.
const LocalBackupPrefix = "local-"
LocalBackupPrefix distinguishes local retirements from imported writes.
const Version = 1
Version is the journal schema version. A journal recording a different version is rejected rather than guessed at, because recovering from a misread journal could destroy local work.
Variables ¶
var ErrMalformed = errors.New("skill import journal is malformed")
ErrMalformed reports a journal that exists but cannot be trusted to drive recovery. Recovery fails loudly rather than deleting or restoring content on a guess.
Functions ¶
func LegacyInstruction ¶ added in v1.0.0
LegacyInstruction is the fixed trusted adoption rename map, never journal data.
func MarkCommitted ¶
MarkCommitted records that every live write already succeeded, so recovery keeps the new state instead of rolling it back.
func Recover ¶
Recover completes any interrupted transaction for a project.
It is a no-op when no transaction is in flight. An uncommitted transaction is rolled back to its pre-transaction state; a committed one only has its staging directory cleared. Callers must already hold the project lock.
func RecoverBoth ¶ added in v1.0.0
RecoverBoth uses trusted coordinates for both kinds before any source consumer.
func Rollback ¶ added in v1.0.0
func Rollback(targets Targets, applied Progress, writeFile func(string, []byte, os.FileMode) error) error
Rollback shares restart recovery's restore engine, but restores only touched paths and requires every backup the writer knows it moved. Failed validation leaves all live paths and recovery evidence intact.
func StagingRoot ¶
StagingRoot returns the staging directory for an imported skill tier.
Types ¶
type Document ¶
type Document struct {
Version int `json:"version"`
LocalRetirements []string `json:"local_retirements,omitempty"`
// Committed marks a transaction whose final durable write already
// succeeded. Recovery then only removes the staging directory.
Committed bool `json:"committed"`
// Writes are the skills the transaction replaces or creates.
Writes []WriteIntent `json:"writes"`
// Deletes are the skill names the transaction removes.
Deletes []string `json:"deletes"`
// Config records that the transaction replaces the configuration file, so
// recovery knows a configuration backup must be restored.
Config bool `json:"config"`
// LockExisted records whether a lockfile was present before the
// transaction. Recovery restores the backup when it was, and removes the
// published lockfile when it was not.
LockExisted bool `json:"lock_existed"`
}
Document is the recorded intent of one in-flight transaction.
type Progress ¶ added in v1.0.0
type Progress struct {
Writes []WriteIntent
Deletes []string
LocalRetirements []string
Config bool
Lock bool
}
Progress records live paths touched by an in-process transaction. Writes retain whether an original moved, so missing backups cannot be mistaken for originals that were never changed.
type Targets ¶
type Targets struct {
ImportedSkillsDir string
LocalSkillsDir string
ConfigPath string
SkillsLockPath string
ExactFiles bool
}
Targets are the resolved live paths a transaction publishes to. They are supplied by the caller rather than read from the journal so a tampered journal can never direct recovery at a path outside the project.
type WriteIntent ¶
type WriteIntent struct {
Name string `json:"name"`
// Existed records whether the imported directory was present before the
// transaction started. Recovery needs it because a write that was never
// reached and a newly created skill both leave no backup behind: the first
// must be left alone, the second must be removed.
Existed bool `json:"existed"`
}
WriteIntent is one skill the transaction replaces or creates.
Source Files