workspace

Documentation

Overview

Package workspace provides framework-free workspace state and coordination.

Index

• Variables
• func Contains(root, path string) bool
• func ContainsCanonical(root, path string) bool
• func NormalizeTouchPath(path string) string
• type Ledger
  • func NewLedger() *Ledger
  • func (l *Ledger) Forget(sessionID, path string)
  • func (l *Ledger) ForgetSession(sessionID string)
  • func (l *Ledger) RecordRead(sessionID, path string, size int64, hash [sha256.Size]byte)
  • func (l *Ledger) RecordWrite(sessionID, path string, size int64, hash [sha256.Size]byte)
  • func (l *Ledger) Verify(sessionID, path string, size int64, hash [sha256.Size]byte) error
  • func (l *Ledger) VerifyWrite(sessionID, path string, size int64, hash [sha256.Size]byte, exists bool) error
• type MutationQueue
  • func NewMutationQueue() *MutationQueue
  • func (q *MutationQueue) Do(ctx context.Context, fn func() error) error
• type Root
  • func NewRoot(dir string) (*Root, error)
  • func (r *Root) Dir() string
  • func (r *Root) Rel(abs string) string
  • func (r *Root) Resolve(path string) (string, error)
  • func (r *Root) ResolveExisting(path string) (string, error)
  • func (r *Root) ResolveForWrite(path string) (string, error)
• type Touch
• type TouchBus
  • func NewTouchBus() *TouchBus
  • func (b *TouchBus) Publish(ctx context.Context, touch Touch)
  • func (b *TouchBus) Subscribe(observer TouchObserver) func()
• type TouchKind
• type TouchObserver

Variables

var (
	ErrNeverRead = errors.New("workspace file was never read")
	ErrStaleRead = errors.New("workspace file changed since it was read")
)

var (
	ErrPathEmpty      = errors.New("workspace path is empty")
	ErrOutsideRoot    = errors.New("workspace path is outside root")
	ErrNotFound       = errors.New("workspace path not found")
	ErrNotDirectory   = errors.New("workspace root is not a directory")
	ErrIsDirectory    = errors.New("workspace path is a directory")
	ErrNotRegularFile = errors.New("workspace path is not a regular file")
	ErrTooLarge       = errors.New("workspace file is too large")
	ErrBinaryFile     = errors.New("workspace file is binary")
)

Functions

func Contains

func Contains(root, path string) bool

Contains reports whether path is lexically contained by root. Callers that require symlink-aware containment must resolve both paths first.

func ContainsCanonical

func ContainsCanonical(root, path string) bool

ContainsCanonical reports whether path remains beneath root after resolving symlinks. Missing paths fall back to their absolute lexical identity so the same owner can validate prospective inputs.

func NormalizeTouchPath

func NormalizeTouchPath(path string) string

NormalizeTouchPath returns the slash-separated workspace-relative form used by every lazy activation observer.

Types

type Ledger

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

Ledger records the last full-content read or write for each session and path.

func NewLedger

func NewLedger() *Ledger

NewLedger creates an empty ledger.

func (*Ledger) Forget

func (l *Ledger) Forget(sessionID, path string)

Forget removes the state for one session and path.

func (*Ledger) ForgetSession

func (l *Ledger) ForgetSession(sessionID string)

ForgetSession removes all states associated with a session.

func (*Ledger) RecordRead

func (l *Ledger) RecordRead(sessionID, path string, size int64, hash [sha256.Size]byte)

RecordRead records the full-content state observed by a successful read.

func (*Ledger) RecordWrite

func (l *Ledger) RecordWrite(sessionID, path string, size int64, hash [sha256.Size]byte)

RecordWrite records the full-content state produced by a successful write.

func (*Ledger) Verify

func (l *Ledger) Verify(sessionID, path string, size int64, hash [sha256.Size]byte) error

Verify requires that the existing file matches the last state read by sessionID.

func (*Ledger) VerifyWrite

func (l *Ledger) VerifyWrite(sessionID, path string, size int64, hash [sha256.Size]byte, exists bool) error

VerifyWrite verifies an existing target. A nonexistent target may be created without a prior read by passing exists as false.

type MutationQueue

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

MutationQueue serializes all workspace mutations.

func NewMutationQueue

func NewMutationQueue() *MutationQueue

NewMutationQueue creates a queue with one global mutation slot.

func (*MutationQueue) Do

func (q *MutationQueue) Do(ctx context.Context, fn func() error) error

Do waits for the mutation slot or context cancellation, then invokes fn.

type Root

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

Root is an immutable, symlink-resolved workspace directory.

func NewRoot

func NewRoot(dir string) (*Root, error)

NewRoot creates a root from an existing directory.

func (*Root) Dir

func (r *Root) Dir() string

Dir returns the fully resolved absolute root directory.

func (*Root) Rel

func (r *Root) Rel(abs string) string

Rel returns a deterministic slash-separated path relative to the root. Callers should pass paths returned by Resolve, ResolveExisting, or ResolveForWrite.

func (*Root) Resolve

func (r *Root) Resolve(path string) (string, error)

Resolve resolves a path inside the root. It works for existing paths and prospective write paths whose final components do not yet exist.

func (*Root) ResolveExisting

func (r *Root) ResolveExisting(path string) (string, error)

ResolveExisting resolves a path and requires it to exist.

func (*Root) ResolveForWrite

func (r *Root) ResolveForWrite(path string) (string, error)

ResolveForWrite resolves a path and verifies its existing parent chain stays in the root. It intentionally does not require the target to exist.

type Touch

type Touch struct {
	SessionID    string
	InvocationID string
	Path         string
	Kind         TouchKind
	Content      []byte
	Version      int64
	At           time.Time
}

Touch describes a workspace operation. Content is non-nil only for writes and edits. InvocationID is empty outside a native tool invocation.

type TouchBus

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

TouchBus fans out touch events in registration order.

func NewTouchBus

func NewTouchBus() *TouchBus

NewTouchBus creates an empty touch bus.

func (*TouchBus) Publish

func (b *TouchBus) Publish(ctx context.Context, touch Touch)

Publish synchronously notifies a snapshot of subscribers in registration order.

func (*TouchBus) Subscribe

func (b *TouchBus) Subscribe(observer TouchObserver) func()

Subscribe adds an observer and returns an idempotent unsubscribe function.

type TouchKind

type TouchKind int

TouchKind identifies the workspace operation that touched a path.

const (
	TouchRead TouchKind = iota
	TouchWrite
	TouchEdit
	TouchList
	TouchSearch
	TouchDelete
)

type TouchObserver

type TouchObserver interface {
	ObserveTouch(context.Context, Touch)
}

TouchObserver receives synchronous workspace touch events.