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 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) 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") // 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") )
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 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
}
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.
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 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.
Source Files