Documentation
¶
Overview ¶
Package git implements the bounded remote Git source adapter.
Index ¶
- Constants
- Variables
- func ClassOfError(err error) string
- func CompileMatchers(includes []string) ([]glob.Glob, error)
- func DocumentMediaType(relative string) string
- func DocumentTitle(relative string, content []byte) string
- func DocumentURI(sourceID knowl.SourceID, uriBase, snapshot, relPath string) string
- func EncodePageTokenForTest(version int, snapshot, after string) (string, error)
- func RedactString(text string) string
- func RedactURL(raw string) string
- func RepositoryIdentity(config knowl.GitSourceConfig) string
- func ResolveAuth(config knowl.GitSourceConfig) (transport.AuthMethod, error)
- func WrapClassified(class string, cause error, detail string) error
- type Adapter
- func (a *Adapter) Fetch(ctx context.Context, source knowl.Source, ref knowl.DocumentRef) (knowl.Document, error)
- func (a *Adapter) List(ctx context.Context, source knowl.Source, pageToken string) (knowl.DocumentPage, error)
- func (a *Adapter) PrepareSnapshot(ctx context.Context, source knowl.Source, previousCheckpoint string) (app.SnapshotPreparation, error)
- type CacheManager
- type ClassifiedError
- type Limits
- type RefResolver
- func (r *RefResolver) CheckLineage(config knowl.GitSourceConfig, prevRemote, prevRepoID string) error
- func (r *RefResolver) ResolveRemoteRef(ctx context.Context, config knowl.GitSourceConfig) (*ResolvedRef, error)
- func (r *RefResolver) ValidateHistory(storer storage.Storer, config knowl.GitSourceConfig, prevCheckpoint string, ...) error
- type RemoteClient
- type RemoteRefLister
- type RepositoryOpener
- type ResolvedRef
- type TreeWalker
Constants ¶
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.
const DefaultNetworkTimeout = 30 * time.Second
DefaultNetworkTimeout bounds network operations against the remote repository.
Variables ¶
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 ¶
ClassOfError extracts the failure class from an error if available.
func CompileMatchers ¶
CompileMatchers compiles include patterns into slash-aware glob matchers.
func DocumentMediaType ¶
DocumentMediaType reports the deterministic media type of a Git document path.
func DocumentTitle ¶
DocumentTitle derives the title from Markdown frontmatter/heading or file basename.
func DocumentURI ¶
DocumentURI returns the document URI for a Git source: If uriBase is configured: uriBase joined with relPath Otherwise: knowl://sources/{sourceID}/{relPath}
func EncodePageTokenForTest ¶
EncodePageTokenForTest exposes token encoding for tests.
func RedactString ¶
RedactString sanitizes credentials, tokens, sensitive URLs, and private key blocks from text.
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.
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 ¶
ClassifiedError pairs an error with a stable failure classification.
type Limits ¶
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.