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 ¶
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 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 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 StagingRoot ¶
StagingRoot returns the staging directory for an imported skill tier.
Types ¶
type Document ¶
type Document struct {
Version int `json:"version"`
// 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 Targets ¶
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