references

Documentation

Index

• func ClearGlobalRefCache()
• type AbsoluteReferenceResult
  • func ResolveAbsoluteReference(ref Reference, targetLocation string) (*AbsoluteReferenceResult, error)
  • func ResolveAbsoluteReferenceCached(ref Reference, targetLocation string) (*AbsoluteReferenceResult, error)
• type RefCache
  • func (c *RefCache) Clear()
  • func (c *RefCache) GetStats() RefCacheStats
  • func (c *RefCache) Resolve(ref Reference, targetLocation string) (*AbsoluteReferenceResult, error)
• type RefCacheKey
• type RefCacheStats
  • func GetRefCacheStats() RefCacheStats
• type Reference
  • func (r Reference) GetJSONPointer() jsonpointer.JSONPointer
  • func (r Reference) GetURI() string
  • func (r Reference) HasJSONPointer() bool
  • func (r Reference) String() string
  • func (r Reference) Validate() error
• type ResolutionTarget
• type Resolvable
• type ResolveOptions
• type ResolveResult
  • func Resolve[T any](ctx context.Context, ref Reference, unmarshaler Unmarshal[T], ...) (*ResolveResult[T], []error, error)
• type Unmarshal

Functions

func ClearGlobalRefCache

func ClearGlobalRefCache()

ClearGlobalRefCache clears the global reference cache

Types

type AbsoluteReferenceResult

type AbsoluteReferenceResult struct {
	// AbsoluteReference is the resolved absolute reference string
	AbsoluteReference string
	// Classification contains the reference type classification
	Classification *utils.ReferenceClassification
}

AbsoluteReferenceResult contains the result of resolving an absolute reference

func ResolveAbsoluteReference

func ResolveAbsoluteReference(ref Reference, targetLocation string) (*AbsoluteReferenceResult, error)

ResolveAbsoluteReference resolves a reference to an absolute reference string based on the target location. It handles empty URIs, absolute URLs, absolute file paths, and relative URIs that need to be joined with the target location. This function now uses caching to avoid repeated computation of the same (reference, target) pairs.

func ResolveAbsoluteReferenceCached

func ResolveAbsoluteReferenceCached(ref Reference, targetLocation string) (*AbsoluteReferenceResult, error)

ResolveAbsoluteReferenceCached resolves a reference to an absolute reference string using a cache to avoid repeated resolution of the same (reference, target) pairs.

type RefCache

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

RefCache provides a thread-safe cache for reference resolution results

func (*RefCache) Clear

func (c *RefCache) Clear()

Clear clears all cached reference resolutions. Useful for testing or memory management.

func (*RefCache) GetStats

func (c *RefCache) GetStats() RefCacheStats

GetStats returns statistics about the cache

func (*RefCache) Resolve

func (c *RefCache) Resolve(ref Reference, targetLocation string) (*AbsoluteReferenceResult, error)

Resolve resolves a reference using the cache. If the (ref, target) pair has been resolved before, it returns a copy of the cached result. Otherwise, it resolves the reference, caches it, and returns the result.

type RefCacheKey

type RefCacheKey struct {
	RefURI         string
	TargetLocation string
}

RefCacheKey represents a unique key for caching reference resolution results

type RefCacheStats

type RefCacheStats struct {
	Size int64
}

Stats returns basic statistics about the cache

func GetRefCacheStats

func GetRefCacheStats() RefCacheStats

GetRefCacheStats returns statistics about the global reference cache

type Reference

type Reference string

func (Reference) GetJSONPointer

func (r Reference) GetJSONPointer() jsonpointer.JSONPointer

func (Reference) GetURI

func (r Reference) GetURI() string

func (Reference) HasJSONPointer

func (r Reference) HasJSONPointer() bool

func (Reference) String

func (r Reference) String() string

func (Reference) Validate

func (r Reference) Validate() error

type ResolutionTarget

type ResolutionTarget interface {
	InitCache()

	GetCachedReferencedObject(key string) (any, bool)
	StoreReferencedObjectInCache(key string, obj any)

	GetCachedReferenceDocument(key string) ([]byte, bool)
	StoreReferenceDocumentInCache(key string, doc []byte)
}

type Resolvable

type Resolvable[T any] interface {
	GetReference() Reference
	Resolve(ctx context.Context, opts ResolveOptions) ([]error, error)
	GetResolvedObject() *T
}

type ResolveOptions

type ResolveOptions struct {
	// RootDocument is the root document of the resolution chain, will be resolved against if TargetDocument is not set. Will hold the cached resolutions results.
	RootDocument ResolutionTarget
	// TargetLocation should represent the absolute location on disk or URL of the target document. All references will be resolved relative to this location.
	TargetLocation string
	// TargetDocument is the document that will be used to resolve references against.
	TargetDocument any
	// DisableExternalRefs will disable resolving external references.
	DisableExternalRefs bool
	// VirtualFS is an optional virtual file system that will be used for any file based references. If not provided normal file system operations will be used.
	VirtualFS system.VirtualFS
	// HTTPClient is an optional HTTP client that will be used for any HTTP based references. If not provided http.DefaultClient will be used.
	HTTPClient system.Client
	// SkipValidation will skip validation of the target document during resolution.
	SkipValidation bool
}

ResolveOptions represent the options available when resolving a reference.

type ResolveResult

type ResolveResult[T any] struct {
	// Object is the resolved object
	Object *T
	// AbsoluteReference is the absolute reference that was resolved
	AbsoluteReference string
	// ResolvedDocument is the document that was resolved against (for chaining resolutions)
	ResolvedDocument any
}

ResolveResult contains the result of a reference resolution operation

func Resolve

func Resolve[T any](ctx context.Context, ref Reference, unmarshaler Unmarshal[T], opts ResolveOptions) (*ResolveResult[T], []error, error)

type Unmarshal

type Unmarshal[T any] func(ctx context.Context, node *yaml.Node, skipValidation bool) (*T, []error, error)