Documentation
¶
Overview ¶
Package workspaceops is the working-copy half of configuration versioning as a service: reading a workspace, writing items of it (several writers racing merge three ways), updating it onto a newer published revision, taking a draft in, resolving conflicts, saving a checkpoint (a draft to share) and committing (publishing it as a new revision), each write logged. The admin API and the configuration MCP endpoint both call it.
It knows items and revisions, not configurations: a Codec turns revisions into items and items back into a payload, and a workspace.Schema holds the merge rules.
Index ¶
- Variables
- type Codec
- type CommitRequest
- type History
- type ItemsCache
- type NotMovedError
- type Reconciler
- type Service
- func (s Service) Checkpoint(ctx context.Context, username, by, comment string) (revision.Revision, error)
- func (s Service) Commit(ctx context.Context, username, by string, req CommitRequest) (revision.Revision, error)
- func (s Service) Load(ctx context.Context, username, by string, to int64, keep bool) (State, error)
- func (s Service) Log(ctx context.Context, username string, limit int) ([]workspace.LogEntry, error)
- func (s Service) MergeDraft(ctx context.Context, username, by string, draft int64) (State, error)
- func (s Service) Read(ctx context.Context, username string) (State, bool, error)
- func (s Service) Reset(ctx context.Context, username, by string, to int64) (State, error)
- func (s Service) Resolve(ctx context.Context, username, by, id string, theirs bool) (State, error)
- func (s Service) Update(ctx context.Context, username, by string, to int64) (State, error)
- func (s Service) WriteItems(ctx context.Context, username, by, op string, writes []Write, ...) (State, error)
- type State
- type Write
Constants ¶
This section is empty.
Variables ¶
var ( // ErrConflicts: open conflicts block saving and committing. ErrConflicts = errors.New("workspace: resolve the conflicts first") // ErrNothingPublished: a workspace builds on the published configuration. ErrNothingPublished = errors.New("workspace: nothing is published") // ErrNeverPublished: a workspace builds on a revision that was published; // a draft is loaded (see Load) or merged (see MergeDraft). ErrNeverPublished = errors.New("workspace: the revision was never published: load it or merge it instead") // ErrBehind: the workspace builds on an older revision than the // published one; it commits only after an update (fast-forward only). ErrBehind = errors.New("workspace: it builds on an older revision than the published one: update it first") // ErrNoConflict: no open conflict has the ID given. ErrNoConflict = errors.New("workspace: no such open conflict") // ErrRenameAlone: a rename written without the removal of the item it // renames, which says what its writer read of it; without that, a // change made to it meanwhile would be lost. ErrRenameAlone = errors.New("workspace: a rename must remove the item it renames in the same write, " + "with the value read") )
Errors returned by the operations.
Functions ¶
This section is empty.
Types ¶
type Codec ¶
type Codec interface {
// Items is rev's configuration as items.
Items(rev revision.Revision) (workspace.Snapshot, error)
// Build is the normalized payload items make on base; an error when it
// does not hold together (a workspace may not, while edited).
Build(base revision.Revision, items workspace.Snapshot) ([]byte, error)
}
Codec turns configurations into workspace items and back.
type CommitRequest ¶
type CommitRequest struct {
// Version is the workspace version reviewed; another one is
// workspace.ErrChanged (check it again).
Version int64
// ExpectedPublished is the revision the reviewer saw published.
ExpectedPublished int64
RestartRequired bool
Comment string
}
CommitRequest commits a workspace as it was read.
type History ¶
type History interface {
Draft(ctx context.Context, req revisionops.DraftRequest) (revision.Revision, bool, error)
Publish(ctx context.Context, req revisionops.PublishRequest) (revision.Revision, error)
Discard(ctx context.Context, id int64, author string) (revision.Revision, error)
}
History stores, publishes and discards revisions (revisionops.Service does, with its checks).
type ItemsCache ¶ added in v0.1.18
type ItemsCache struct {
// contains filtered or unexported fields
}
ItemsCache keeps the items of recently read revisions. Decoding a large revision takes most of a workspace operation, and every operation reads its base's items; a revision never changes, so they are kept by ID. The snapshots kept are shared: operations only read them (workspace.Snapshot and the merge rules build new values). The zero value is ready to use.
type NotMovedError ¶ added in v0.1.21
NotMovedError is a commit published whose workspace could not then be moved onto the revision: the revision serves, and the workspace still builds on the one before, with its notes and drafts, until it is updated.
func (*NotMovedError) Error ¶ added in v0.1.21
func (e *NotMovedError) Error() string
func (*NotMovedError) Unwrap ¶ added in v0.1.21
func (e *NotMovedError) Unwrap() error
type Reconciler ¶
type Reconciler func(before, after workspace.Snapshot, renames map[workspace.Ref]workspace.Ref) ( workspace.Snapshot, error)
Reconciler keeps a configuration's items consistent with each other as a write changes them (before to after): the references to an entity renamed or removed, for one. renames maps an item written to the item it was renamed or moved from. It returns after with what that changes.
type Service ¶
type Service struct {
Store workspace.Store
Codec Codec
Schema workspace.Schema
// Revisions is the history; History writes it.
Revisions revision.Store
History History
// Reconcile, when set, runs on every write, in the same version.
Reconcile Reconciler
// Cache, when set, keeps the items of revisions read.
Cache *ItemsCache
}
Service performs workspace operations. It holds no per-request state.
func (Service) Checkpoint ¶
func (s Service) Checkpoint(ctx context.Context, username, by, comment string) (revision.Revision, error)
Checkpoint saves username's workspace as a draft (to share with other administrators), in place of the one it saved before; it is taken already, so it is not offered back to this workspace. The draft holds the workspace as read: when it was written while saving, the workspace keeps the draft but no longer matches it (CheckpointAt).
func (Service) Commit ¶
func (s Service) Commit(ctx context.Context, username, by string, req CommitRequest) (revision.Revision, error)
Commit publishes username's workspace, at the version reviewed, as a new revision: its content is built and checked, stored, and published only while ExpectedPublished is still the published one (else a *revisionops.ConflictError; the revision stored is discarded). The workspace then builds on the new revision, keeping what was written to it while committing; its notes are dropped and the drafts it saved or took in, published with it, are discarded. A workspace that cannot be moved onto it is a *NotMovedError, with the revision published.
func (Service) Load ¶ added in v0.1.21
Load makes the content of revision to (any revision: an older one, a discarded draft) username's workspace, as changes to the published revision, which it then builds on: published as it is, they restore to. Without keep, what was changed here, the conflicts, the notes and the record of the drafts taken in or saved from it are dropped, as by Reset. With keep, what was changed here is re-applied onto to: a value both changed differently keeps the workspace's, as a conflict holding to's.
func (Service) MergeDraft ¶
MergeDraft takes draft (another administrator's checkpoint) into username's workspace, onto the published revision: what the draft changed since the revision it builds on joins the workspace, and what was changed here stays. A value the draft and a newer publish changed differently keeps the draft's, as a conflict against the published one; a value the draft and this workspace changed differently keeps the workspace's, as a conflict against the draft's. Taking a draft twice does nothing.
func (Service) Read ¶
Read is username's workspace; false when none is kept and nothing is published.
func (Service) Reset ¶
Reset makes username's workspace revision to (a published one) as it is: what was changed here, the conflicts and the notes are dropped, and so is the record of the drafts taken in or saved from it (they are drafts still, offered again).
func (Service) Resolve ¶
Resolve resolves conflict id: theirs takes the other side's value, else the workspace's stays.
func (Service) Update ¶
Update moves username's workspace onto revision to (a newer published one), re-applying what was changed here: a value both changed differently keeps the workspace's, as a conflict against to.
func (Service) WriteItems ¶
func (s Service) WriteItems(ctx context.Context, username, by, op string, writes []Write, note *workspace.Note) ( State, error, )
WriteItems writes items of username's workspace. An item written meanwhile (by another console, an agent) since its writer read it merges three ways (read, written, current): changes to different values both stay, and a value both changed differently keeps the written one, as a conflict against the current one. Nothing is lost. note, if any, says why.
type State ¶
State is a workspace as it stands: as kept (its items the base's when nothing was written), the base revision's items, and the open conflicts.
type Write ¶
Write is an item written: its value (Missing removes it) and the value its writer read (Missing: absent). From, when set, is the item it was renamed or moved from, which it replaces (see Reconciler): the same writes remove that item, with the value its writer read, unless it is gone already (ErrRenameAlone).