Artifact [6880f6507c]

Artifact 6880f6507cd931ebd2317ff60311a725d52270b557c182b0a4a05b835e574d9a:

• File internal/checkout/observer.go — part of check-in [f5744359d3] at 2026-04-19 16:30:54 on branch trunk — Initial open source release

  libfossil is a pure-Go implementation of the Fossil SCM, reading and writing the same .fossil SQLite repository format as upstream Fossil.

  This is the first public release of code that previously lived in a private repository. The module path is github.com/danmestas/libfossil and the binary is named libfossil to avoid $PATH collisions with upstream fossil.

  Included: - Repo lifecycle (create, clone), checkout/checkin, timeline, merge, diff, annotate, shun, tag, branch, bisect, stash, undo/redo - Sync-over-HTTP protocol (client and handler) - Two SQLite drivers: modernc (pure Go, default) and ncruces (wasm-capable) - Observer interfaces (SyncObserver, CheckoutObserver) with an optional OpenTelemetry implementation in observer/otel (separate submodule) - Deterministic simulation testing harness with BUGGIFY fault injection - Kong-based embeddable CLI under cli/ and a standalone binary under cmd/libfossil/ (user: [email protected], size: 2902) [annotate] [blame] [check-ins using]

package checkout

import (
	"context"

	libfossil "github.com/danmestas/libfossil/internal/fsltype"
)

// ExtractStart describes the beginning of an extract or update operation.
type ExtractStart struct {
	Operation string          // "extract" or "update"
	TargetRID libfossil.FslID
}

// ExtractEnd describes the result of an extract or update operation.
type ExtractEnd struct {
	Operation    string
	TargetRID    libfossil.FslID
	FilesWritten int
	FilesRemoved int
	Conflicts    int
	Err          error
}

// ScanEnd describes the result of a ScanChanges operation.
type ScanEnd struct {
	FilesScanned int
	FilesChanged int
	FilesMissing int
	FilesExtra   int
}

// CommitStart describes the beginning of a commit operation.
type CommitStart struct {
	FilesEnqueued int
	Branch        string
	User          string
}

// CommitEnd describes the result of a commit operation.
type CommitEnd struct {
	RID         libfossil.FslID
	UUID        string
	FilesCommit int
	Err         error
}

// Observer receives lifecycle callbacks during checkout operations.
// A single Observer instance may be shared across multiple concurrent operations.
// Pass nil for no-op default.
//
// Performance: nopObserver implements all methods as empty functions.
// The only cost on the hot path is one indirect call per invocation (~2ns).
type Observer interface {
	// Extract/update lifecycle.
	ExtractStarted(ctx context.Context, e ExtractStart) context.Context
	ExtractFileCompleted(ctx context.Context, name string, change UpdateChange)
	ExtractCompleted(ctx context.Context, e ExtractEnd)

	// Scan lifecycle.
	ScanStarted(ctx context.Context) context.Context
	ScanCompleted(ctx context.Context, e ScanEnd)

	// Commit lifecycle.
	CommitStarted(ctx context.Context, e CommitStart) context.Context
	CommitCompleted(ctx context.Context, e CommitEnd)

	// Per-error recording — called on individual errors.
	Error(ctx context.Context, err error)
}

// nopObserver is the default observer that does nothing.
type nopObserver struct{}

func (nopObserver) ExtractStarted(ctx context.Context, _ ExtractStart) context.Context {
	return ctx
}
func (nopObserver) ExtractFileCompleted(_ context.Context, _ string, _ UpdateChange) {}
func (nopObserver) ExtractCompleted(_ context.Context, _ ExtractEnd)                 {}
func (nopObserver) ScanStarted(ctx context.Context) context.Context                  { return ctx }
func (nopObserver) ScanCompleted(_ context.Context, _ ScanEnd)                       {}
func (nopObserver) CommitStarted(ctx context.Context, _ CommitStart) context.Context {
	return ctx
}
func (nopObserver) CommitCompleted(_ context.Context, _ CommitEnd) {}
func (nopObserver) Error(_ context.Context, _ error)              {}

// resolveObserver returns obs if non-nil, otherwise nopObserver{}.
func resolveObserver(obs Observer) Observer {
	if obs == nil {
		return nopObserver{}
	}
	return obs
}