Skip to content

modules

import "github.com/alehatsman/mooncake/internal/modules"

Package modules implements the Git-native module system from spec-67. A module is a Git repository (or subpath of one) that exports one or more components via index.yml. References are pinned to explicit Git tags.

Index

func DefaultCacheRoot

func DefaultCacheRoot() (string, error)

DefaultCacheRoot is \~/.cache/mooncake/modules.

Resolved lazily because $HOME may be unset (tests) or differ from the user who started the process (sudo-driven applies).

type Fetcher

Fetcher manages the on-disk module cache. The zero value uses the default cache root and the system `git` binary.

Concurrent fetches of the same reference race for the lock-free "rename-into-place" cache: the loser sees a populated cache directory and short-circuits.

type Fetcher struct {
    // Root is the cache root directory. If empty, DefaultCacheRoot() is used.
    Root string

    // Git is the git binary name or path. If empty, "git" is used.
    Git string

    // CloneURL overrides the URL used for `git clone`. If nil,
    // Reference.CloneURL() is used. Set in tests to point at a file:// repo.
    CloneURL func(Reference) string
}

func (*Fetcher) CacheDir

func (f *Fetcher) CacheDir(ref Reference) (string, error)

CacheDir returns the absolute cache directory for a module reference. The directory may or may not exist.

func (*Fetcher) Fetch

func (f *Fetcher) Fetch(ctx context.Context, ref Reference) (string, error)

Fetch ensures the module identified by ref is present in the cache and returns the absolute directory. A cache hit skips the clone entirely.

type Index

Index represents a module's index.yml manifest. It declares the module's identity and maps export names to component file paths relative to the module root.

name: postgres
exports:
  default: components/install.yml
  backup:  components/backup.yml

type Index struct {
    Name        string            `yaml:"name"`
    Description string            `yaml:"description"`
    Exports     map[string]string `yaml:"exports"`
}

func LoadIndex

func LoadIndex(moduleRoot string) (*Index, error)

LoadIndex reads and parses moduleRoot/index.yml. moduleRoot is the directory holding the manifest (typically a cache directory like \~/.cache/mooncake/modules/\<host>/\<owner>/\<repo>@\<version>/).

func (*Index) ResolveExport

func (idx *Index) ResolveExport(moduleRoot, export string) (string, error)

ResolveExport looks up an export name and returns the absolute path to the component file. moduleRoot is the directory the index was loaded from.

export == "" or "default" → uses the "default" export entry
otherwise                 → uses the entry named exactly `export`

The returned path is verified to exist on disk before returning.

type Reference

Reference is a parsed module reference of the form \<host>/\<owner>/\<repo>[/\<subpath>]@\<version>.

Example: github.com/mooncake-modules/[email protected] parses to {Host:"github.com", Owner:"mooncake-modules", Repo:"postgres", Version:"v1.3.0"}.

type Reference struct {
    Host    string
    Owner   string
    Repo    string
    Subpath string
    Version string
}

func ParseReference

func ParseReference(s string) (Reference, error)

ParseReference parses a module reference string. The version is required — references without "@\<version>" are rejected.

func (Reference) CloneURL

func (r Reference) CloneURL() string

CloneURL returns the https URL of the underlying Git repository (subpath is not part of the clone URL).

func (Reference) ModulePath

func (r Reference) ModulePath() string

ModulePath returns the path portion (no version), e.g. "github.com/owner/repo" or "github.com/owner/repo/subpath".

func (Reference) String

func (r Reference) String() string

String returns the canonical "\<path>@\<version>" form.

type Resolved

Resolved is what the resolver returns: the file path to load as a component plus the module root (needed so further imports inside the component resolve relative to the module, not the playbook).

type Resolved struct {
    ComponentPath string
    ModuleRoot    string
}

type Resolver

Resolver turns a use: reference into a concrete component file path. It combines reference parsing, module fetching, and index.yml export lookup.

Aliases are looked up in Modules (typically the playbook's modules: block). Inline remote references (`github.com/owner/[email protected]`) skip the alias map.

type Resolver struct {
    Fetcher *Fetcher
    Modules map[string]string
}

func NewResolver

func NewResolver(modules map[string]string) *Resolver

NewResolver constructs a resolver with the default fetcher and the supplied alias map. Passing nil for the map disables alias resolution.

func (*Resolver) Resolve

func (r *Resolver) Resolve(ctx context.Context, refStr string) (Resolved, error)

Resolve takes a use: reference string and returns the component file to load. The refStr should be in one of these forms:

"github.com/owner/[email protected]"     - inline remote, default export
"alias"                             - alias from Modules, default export
"alias/export"                      - alias + named export

Local paths (./foo.yml) are NOT handled here — the executor dispatches those directly without going through the resolver.

Generated by gomarkdoc