git

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 9, 2026 License: MIT Imports: 38 Imported by: 0

Documentation

Overview

Package git implements the bounded remote Git source adapter.

Index

Constants

View Source
const (
	ClassReachability               = "reachability"
	ClassAuthentication             = "authentication"
	ClassHostVerification           = "host_verification"
	ClassUnsupportedTransport       = "unsupported_transport"
	ClassMissingRef                 = "missing_ref"
	ClassMovedTag                   = "moved_tag"
	ClassRejectedHistoryRewrite     = "rejected_history_rewrite"
	ClassRepositoryIdentityMismatch = "repository_identity_mismatch"
	ClassResourceLimit              = "resource_limit"
	ClassScanInvalid                = "scan_invalid"
	ClassFetch                      = "fetch"
)

Standard stable failure classes matching the Knowl domain vocabulary.

View Source
const DefaultNetworkTimeout = 30 * time.Second

DefaultNetworkTimeout bounds network operations against the remote repository.

Variables

View Source
var (
	// ErrReachability reports failure to connect to the remote host.
	ErrReachability = errors.New("git repository unreachable")
	// ErrAuthentication reports invalid or rejected credentials.
	ErrAuthentication = errors.New("git authentication failed")
	// ErrHostVerification reports an unknown or mismatched SSH host key.
	ErrHostVerification = errors.New("git host verification failed")
	// ErrUnsupportedTransport reports a rejected or disallowed transport scheme.
	ErrUnsupportedTransport = errors.New("unsupported git transport")
	// ErrMissingRef reports that the tracked branch or tag does not exist on the remote.
	ErrMissingRef = errors.New("tracked git ref not found on remote")
	// ErrMovedTag reports that a tracked tag resolved to a different target without authorization.
	ErrMovedTag = errors.New("tracked git tag target moved without authorization")
	// ErrRejectedHistoryRewrite reports a non-fast-forward branch advance without authorization.
	ErrRejectedHistoryRewrite = errors.New("git branch history rewritten without authorization")
	// ErrRepositoryIdentityMismatch reports a remote repository change without rebind authorization.
	ErrRepositoryIdentityMismatch = errors.New("git remote repository identity changed without authorization")
	// ErrLimit reports that a Git source exceeded a configured limit.
	ErrLimit = errors.New("git source exceeds a limit")
	// ErrDocumentNotFound reports that a listed document blob is missing in the snapshot.
	ErrDocumentNotFound = errors.New("git source document not found")
	// ErrRevisionChanged reports that a document revision does not match the listed descriptor.
	ErrRevisionChanged = errors.New("git source document revision changed")
	// ErrPageToken reports an invalid or corrupted pagination token.
	ErrPageToken = errors.New("git source page token invalid")
	// ErrScanInvalid reports an invalid snapshot or repository state during scan.
	ErrScanInvalid = errors.New("git source scan invalid")
)

Functions

func ClassOfError

func ClassOfError(err error) string

ClassOfError extracts the failure class from an error if available.

func CompileMatchers

func CompileMatchers(includes []string) ([]glob.Glob, error)

CompileMatchers compiles include patterns into slash-aware glob matchers.

func DocumentMediaType

func DocumentMediaType(relative string) string

DocumentMediaType reports the deterministic media type of a Git document path.

func DocumentTitle

func DocumentTitle(relative string, content []byte) string

DocumentTitle derives the title from Markdown frontmatter/heading or file basename.

func DocumentURI

func DocumentURI(sourceID knowl.SourceID, uriBase, snapshot, relPath string) string

DocumentURI returns the document URI for a Git source: If uriBase is configured: uriBase joined with relPath Otherwise: knowl://sources/{sourceID}/{relPath}

func EncodePageTokenForTest

func EncodePageTokenForTest(version int, snapshot, after string) (string, error)

EncodePageTokenForTest exposes token encoding for tests.

func RedactString

func RedactString(text string) string

RedactString sanitizes credentials, tokens, sensitive URLs, and private key blocks from text.

func RedactURL

func RedactURL(raw string) string

RedactURL returns a credential-free representation of a URL string.

func RepositoryIdentity

func RepositoryIdentity(config knowl.GitSourceConfig) string

RepositoryIdentity returns the credential-free durable lineage digest for a normalized config, and safely derives it for explicitly composed adapters.

func ResolveAuth

func ResolveAuth(config knowl.GitSourceConfig) (transport.AuthMethod, error)

ResolveAuth returns go-git transport.AuthMethod configured for the Git source, or nil if unauthenticated.

func WrapClassified

func WrapClassified(class string, cause error, detail string) error

WrapClassified wraps an error with a stable failure class and sanitized detail.

Types

type Adapter

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

Adapter implements app.SourceAdapter for remote Git sources.

func NewAdapter

func NewAdapter(limits Limits, resolver *RefResolver, repoStore RepositoryOpener) (*Adapter, error)

NewAdapter constructs a Git source adapter with explicit operational bounds.

func NewDefaultAdapter

func NewDefaultAdapter(repoStore RepositoryOpener) *Adapter

NewDefaultAdapter constructs an Adapter with default bounds.

func (*Adapter) Fetch

func (a *Adapter) Fetch(ctx context.Context, source knowl.Source, ref knowl.DocumentRef) (knowl.Document, error)

Fetch returns one immutable source document blob from the snapshot.

func (*Adapter) List

func (a *Adapter) List(ctx context.Context, source knowl.Source, pageToken string) (knowl.DocumentPage, error)

List returns one deterministic, bounded page of descriptors pinned to an immutable snapshot.

func (*Adapter) PrepareSnapshot

func (a *Adapter) PrepareSnapshot(ctx context.Context, source knowl.Source, previousCheckpoint string) (app.SnapshotPreparation, error)

PrepareSnapshot resolves the tracked ref once, refreshes the disposable cache, validates history against the durable checkpoint, and returns the opaque first-page token that pins the whole scan.

type CacheManager

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

CacheManager manages on-disk bare repository mirror caches.

func NewCacheManager

func NewCacheManager(baseDir string, client *RemoteClient) *CacheManager

NewCacheManager constructs a CacheManager rooted at baseDir.

func (*CacheManager) OpenCached added in v0.5.0

func (m *CacheManager) OpenCached(ctx context.Context, source knowl.Source) (*gogit.Repository, error)

OpenCached opens the source-scoped bare mirror without refreshing or repairing it. Callers use this after PrepareSnapshot has made the immutable objects available locally.

func (*CacheManager) OpenOrClone

func (m *CacheManager) OpenOrClone(ctx context.Context, source knowl.Source) (*gogit.Repository, error)

OpenOrClone opens an existing bare mirror cache or transparently clones a new one.

type ClassifiedError

type ClassifiedError interface {
	error
	FailureClass() string
	SafeDetail() string
}

ClassifiedError pairs an error with a stable failure classification.

type Limits

type Limits struct {
	PageSize     int
	MaxVisited   int
	MaxDocuments int
	MaxFileBytes int64
}

Limits bounds tree traversal, document counts, and pagination for Git sources.

func DefaultLimits

func DefaultLimits() Limits

DefaultLimits returns the default operational bounds for Git sources.

type RefResolver

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

RefResolver resolves remote tracked refs to immutable commit snapshots and verifies history integrity.

func NewRefResolver

func NewRefResolver(client RemoteRefLister) *RefResolver

NewRefResolver constructs a new RefResolver.

func (*RefResolver) CheckLineage

func (r *RefResolver) CheckLineage(config knowl.GitSourceConfig, prevRemote, prevRepoID string) error

CheckLineage enforces remote URL and repository identity consistency.

func (*RefResolver) ResolveRemoteRef

func (r *RefResolver) ResolveRemoteRef(ctx context.Context, config knowl.GitSourceConfig) (*ResolvedRef, error)

ResolveRemoteRef probes the remote repository references and binds the tracked ref to an immutable commit SHA.

func (*RefResolver) ValidateHistory

func (r *RefResolver) ValidateHistory(storer storage.Storer, config knowl.GitSourceConfig, prevCheckpoint string, targetHash plumbing.Hash) error

ValidateHistory verifies that advancing to targetHash complies with history integrity rules.

type RemoteClient

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

RemoteClient queries and interacts with remote Git repositories without executing local processes.

func NewRemoteClient

func NewRemoteClient() *RemoteClient

NewRemoteClient constructs a RemoteClient with bounded network timeouts and SSRF controls.

func (*RemoteClient) ListRemoteRefs

func (c *RemoteClient) ListRemoteRefs(ctx context.Context, config knowl.GitSourceConfig) ([]*plumbing.Reference, error)

ListRemoteRefs queries remote repository references over HTTPS or SSH.

type RemoteRefLister

type RemoteRefLister interface {
	ListRemoteRefs(ctx context.Context, config knowl.GitSourceConfig) ([]*plumbing.Reference, error)
}

RemoteRefLister defines the interface for querying remote repository references.

type RepositoryOpener

type RepositoryOpener interface {
	OpenOrClone(ctx context.Context, source knowl.Source) (*gogit.Repository, error)
	OpenCached(ctx context.Context, source knowl.Source) (*gogit.Repository, error)
}

RepositoryOpener provides access to a local Git repository for a configured source.

type ResolvedRef

type ResolvedRef struct {
	Name plumbing.ReferenceName
	Hash plumbing.Hash
}

ResolvedRef is the resolved remote reference name and immutable commit hash.

func FindTargetRef

func FindTargetRef(refs []*plumbing.Reference, config knowl.GitSourceConfig) (*ResolvedRef, error)

FindTargetRef selects the matching ref from a list of remote references, resolving peeled tags when applicable.

type TreeWalker

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

TreeWalker walks Git object trees at a specified commit snapshot and filters descriptors.

func NewTreeWalker

func NewTreeWalker(limits Limits) *TreeWalker

NewTreeWalker constructs a TreeWalker with bounded limits.

func (*TreeWalker) Walk

func (w *TreeWalker) Walk(ctx context.Context, storer storage.Storer, snapshotHash plumbing.Hash, matchers []glob.Glob) ([]knowl.DocumentRef, error)

Walk traverses the Git tree at snapshotHash, filtering entries and returning sorted DocumentRef descriptors.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL