rsl

Documentation

Index

• Constants
• Variables
• func GetFirstEntry(repo *git.Repository) (*ReferenceEntry, []*AnnotationEntry, error)
• func GetFirstReferenceEntryForCommit(repo *git.Repository, commit *object.Commit) (*ReferenceEntry, []*AnnotationEntry, error)
• func GetLatestNonGittufReferenceEntry(repo *git.Repository) (*ReferenceEntry, []*AnnotationEntry, error)
• func GetLatestReferenceEntryForRef(repo *git.Repository, refName string) (*ReferenceEntry, []*AnnotationEntry, error)
• func GetLatestReferenceEntryForRefBefore(repo *git.Repository, refName string, anchor plumbing.Hash) (*ReferenceEntry, []*AnnotationEntry, error)
• func GetNonGittufParentReferenceEntryForEntry(repo *git.Repository, entry Entry) (*ReferenceEntry, []*AnnotationEntry, error)
• func InitializeNamespace(repo *git.Repository) error
• func RemoteTrackerRef(remote string) string
• type AnnotationEntry
  • func NewAnnotationEntry(rslEntryIDs []plumbing.Hash, skip bool, message string) *AnnotationEntry
  • func (a *AnnotationEntry) Commit(repo *git.Repository, sign bool) error
  • func (a *AnnotationEntry) GetID() plumbing.Hash
  • func (a *AnnotationEntry) RefersTo(entryID plumbing.Hash) bool
• type Entry
  • func GetEntry(repo *git.Repository, entryID plumbing.Hash) (Entry, error)
  • func GetLatestEntry(repo *git.Repository) (Entry, error)
  • func GetParentForEntry(repo *git.Repository, entry Entry) (Entry, error)
• type ReferenceEntry
  • func GetReferenceEntriesInRange(repo *git.Repository, firstID, lastID plumbing.Hash) ([]*ReferenceEntry, map[plumbing.Hash][]*AnnotationEntry, error)
  • func GetReferenceEntriesInRangeForRef(repo *git.Repository, firstID, lastID plumbing.Hash, refName string) ([]*ReferenceEntry, map[plumbing.Hash][]*AnnotationEntry, error)
  • func NewReferenceEntry(refName string, targetID plumbing.Hash) *ReferenceEntry
  • func (e *ReferenceEntry) Commit(repo *git.Repository, sign bool) error
  • func (e *ReferenceEntry) GetID() plumbing.Hash

Constants

const (
	GittufNamespacePrefix      = "refs/gittuf/"
	Ref                        = "refs/gittuf/reference-state-log"
	ReferenceEntryHeader       = "RSL Reference Entry"
	RefKey                     = "ref"
	TargetIDKey                = "targetID"
	AnnotationEntryHeader      = "RSL Annotation Entry"
	AnnotationMessageBlockType = "MESSAGE"
	BeginMessage               = "-----BEGIN MESSAGE-----"
	EndMessage                 = "-----END MESSAGE-----"
	EntryIDKey                 = "entryID"
	SkipKey                    = "skip"
)

Variables

var (
	ErrRSLExists               = errors.New("cannot initialize RSL namespace as it exists already")
	ErrRSLEntryNotFound        = errors.New("unable to find RSL entry")
	ErrRSLBranchDetected       = errors.New("potential RSL branch detected, entry has more than one parent")
	ErrInvalidRSLEntry         = errors.New("RSL entry has invalid format or is of unexpected type")
	ErrRSLEntryDoesNotMatchRef = errors.New("RSL entry does not match requested ref")
	ErrNoRecordOfCommit        = errors.New("commit has not been encountered before")
)

Functions

func GetFirstEntry

func GetFirstEntry(repo *git.Repository) (*ReferenceEntry, []*AnnotationEntry, error)

GetFirstEntry returns the very first entry in the RSL. It is expected to be a reference entry as the first entry in the RSL cannot be an annotation.

func GetFirstReferenceEntryForCommit

func GetFirstReferenceEntryForCommit(repo *git.Repository, commit *object.Commit) (*ReferenceEntry, []*AnnotationEntry, error)

GetFirstReferenceEntryForCommit returns the first reference entry in the RSL that either records the commit itself or a descendent of the commit. This establishes the first time a commit was seen in the repository, irrespective of the ref it was associated with, and we can infer things like the active developers who could have signed the commit.

func GetLatestNonGittufReferenceEntry

func GetLatestNonGittufReferenceEntry(repo *git.Repository) (*ReferenceEntry, []*AnnotationEntry, error)

GetLatestNonGittufReferenceEntry returns the first reference entry that is not for the gittuf namespace.

func GetLatestReferenceEntryForRef

func GetLatestReferenceEntryForRef(repo *git.Repository, refName string) (*ReferenceEntry, []*AnnotationEntry, error)

GetLatestReferenceEntryForRef returns the latest reference entry available locally in the RSL for the specified refName.

func GetLatestReferenceEntryForRefBefore

func GetLatestReferenceEntryForRefBefore(repo *git.Repository, refName string, anchor plumbing.Hash) (*ReferenceEntry, []*AnnotationEntry, error)

GetLatestReferenceEntryForRefBefore returns the latest reference entry available locally in the RSL for the specified refName before the specified anchor.

func GetNonGittufParentReferenceEntryForEntry

func GetNonGittufParentReferenceEntryForEntry(repo *git.Repository, entry Entry) (*ReferenceEntry, []*AnnotationEntry, error)

GetNonGittufParentReferenceEntryForEntry returns the first RSL reference entry starting from the specified entry's parent that is not for the gittuf namespace.

func InitializeNamespace

func InitializeNamespace(repo *git.Repository) error

InitializeNamespace creates a git ref for the reference state log. Initially, the entry has a zero hash.

func RemoteTrackerRef

func RemoteTrackerRef(remote string) string

RemoteTrackerRef returns the remote tracking ref for the specified remote name. For example, for 'origin', the remote tracker ref is 'refs/remotes/origin/gittuf/reference-state-log'.

Types

type AnnotationEntry

type AnnotationEntry struct {
	// ID contains the Git hash for the commit corresponding to the annotation.
	ID plumbing.Hash

	// RSLEntryIDs contains one or more Git hashes for the RSL entries the annotation applies to.
	RSLEntryIDs []plumbing.Hash

	// Skip indicates if the RSLEntryIDs must be skipped during gittuf workflows.
	Skip bool

	// Message contains any messages or notes added by a user for the annotation.
	Message string
}

AnnotationEntry is a type of RSL record that references prior items in the RSL. It can be used to add extra information for the referenced items. Annotations can also be used to "skip", i.e. revoke, the referenced items. It implements the Entry interface.

func NewAnnotationEntry

func NewAnnotationEntry(rslEntryIDs []plumbing.Hash, skip bool, message string) *AnnotationEntry

NewAnnotationEntry returns an Annotation object that applies to one or more prior RSL entries.

func (*AnnotationEntry) Commit

func (a *AnnotationEntry) Commit(repo *git.Repository, sign bool) error

Commit creates a commit object in the RSL for the Annotation.

func (*AnnotationEntry) GetID

func (a *AnnotationEntry) GetID() plumbing.Hash

func (*AnnotationEntry) RefersTo

func (a *AnnotationEntry) RefersTo(entryID plumbing.Hash) bool

RefersTo returns true if the specified entryID is referred to by the annotation.

type Entry

type Entry interface {
	GetID() plumbing.Hash
	Commit(*git.Repository, bool) error
	// contains filtered or unexported methods
}

Entry is the abstract representation of an object in the RSL.

func GetEntry

func GetEntry(repo *git.Repository, entryID plumbing.Hash) (Entry, error)

GetEntry returns the entry corresponding to entryID.

func GetLatestEntry

func GetLatestEntry(repo *git.Repository) (Entry, error)

GetLatestEntry returns the latest entry available locally in the RSL.

func GetParentForEntry

func GetParentForEntry(repo *git.Repository, entry Entry) (Entry, error)

GetParentForEntry returns the entry's parent RSL entry.

type ReferenceEntry

type ReferenceEntry struct {
	// ID contains the Git hash for the commit corresponding to the entry.
	ID plumbing.Hash

	// RefName contains the Git reference the entry is for.
	RefName string

	// TargetID contains the Git hash for the object expected at RefName.
	TargetID plumbing.Hash
}

ReferenceEntry represents a record of a reference state in the RSL. It implements the Entry interface.

func GetReferenceEntriesInRange

func GetReferenceEntriesInRange(repo *git.Repository, firstID, lastID plumbing.Hash) ([]*ReferenceEntry, map[plumbing.Hash][]*AnnotationEntry, error)

GetReferenceEntriesInRange returns a list of reference entries between the specified range and a map of annotations that refer to each reference entry in the range. The annotations map is keyed by the ID of the reference entry, with the value being a list of annotations that apply to that reference entry.

func GetReferenceEntriesInRangeForRef

func GetReferenceEntriesInRangeForRef(repo *git.Repository, firstID, lastID plumbing.Hash, refName string) ([]*ReferenceEntry, map[plumbing.Hash][]*AnnotationEntry, error)

GetReferenceEntriesInRangeForRef returns a list of reference entries for the ref between the specified range and a map of annotations that refer to each reference entry in the range. The annotations map is keyed by the ID of the reference entry, with the value being a list of annotations that apply to that reference entry.

func NewReferenceEntry

func NewReferenceEntry(refName string, targetID plumbing.Hash) *ReferenceEntry

NewReferenceEntry returns a ReferenceEntry object for a normal RSL entry.

func (*ReferenceEntry) Commit

func (e *ReferenceEntry) Commit(repo *git.Repository, sign bool) error

Commit creates a commit object in the RSL for the ReferenceEntry.

func (*ReferenceEntry) GetID

func (e *ReferenceEntry) GetID() plumbing.Hash