Help us shape the future of Go! Take the 2026 Go Developer Survey

docs

package
v0.49.0 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package docs implements the `volcano docs` subsystem: fetching Volcano documentation from a configurable GitHub source into a local cache and searching it with a small, dependency-free BM25 index. It is designed primarily for AI agents that need to look up or validate facts against the official docs, with machine-readable (JSON) output as a first-class concern.

Index

Constants

View Source 
const (
	EnvRepo = "VOLCANO_DOCS_REPO"
	EnvRef  = "VOLCANO_DOCS_REF"
	EnvPath = "VOLCANO_DOCS_PATH"
)

Environment overrides for the documentation source.

View Source 
const ManifestSchemaVersion = 1

ManifestSchemaVersion versions the on-disk manifest format.

View Source 
const Provider = "github"

Provider identifies the backing documentation host. Only GitHub is supported today; the field keeps the cache key and JSON envelope forward compatible if another provider is ever added.

View Source 
const StaleAfter = 7 * 24 * time.Hour

StaleAfter is how long a cache is served before it is reported stale. Reads never refresh automatically; staleness is informational only.

Variables

View Source 
var (
	// ErrCacheMissing indicates no cache snapshot exists yet (and, for reads,
	// --offline prevented a bootstrap sync).
	ErrCacheMissing = errors.New("docs cache is empty; run `volcano docs sync`")
	// ErrSourceUnavailable indicates the GitHub source could not be reached or
	// returned an error while syncing.
	ErrSourceUnavailable = errors.New("docs source unavailable")
	// ErrInvalidSource indicates a malformed repo/ref/path.
	ErrInvalidSource = errors.New("invalid docs source")
	// ErrDocNotFound indicates a requested document/section does not exist.
	ErrDocNotFound = errors.New("doc not found")
	// ErrInvalidID indicates a malformed document id/path.
	ErrInvalidID = errors.New("invalid doc id")
	// ErrSyncIncomplete indicates a sync failed partway and left the previous
	// cache untouched.
	ErrSyncIncomplete = errors.New("docs sync incomplete")
	// ErrOfflineConflict indicates a network-requiring operation (e.g. `sync`)
	// was invoked with --offline, which is an invalid flag combination rather
	// than a source failure.
	ErrOfflineConflict = errors.New("operation requires network access but --offline was set")
)

Sentinel errors carry stable machine codes for the JSON envelope. Each maps to a DOCS_* code in the command layer.

Functions

func CacheDir 

func CacheDir(override string, src SourceRef) (string, error)

CacheDir returns the per-source cache directory: <base>/docs/<version>/<source-key>.

func Code 

func Code(err error) string

Code returns the DOCS_* machine code for a docs error, or empty string.

Types

type Cache 

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

Cache manages snapshot directories and the current pointer for one source.

func NewCache 

func NewCache(dir string) *Cache

NewCache returns a Cache rooted at the per-source directory.

func (*Cache) Exists 

func (c *Cache) Exists() bool

Exists reports whether a published snapshot is available.

func (*Cache) Load 

func (c *Cache) Load() (*Manifest, error)

Load reads the live manifest. Returns ErrCacheMissing when no snapshot exists.

func (*Cache) ReadFile 

func (c *Cache) ReadFile(relPath string) ([]byte, error)

ReadFile returns the raw bytes of a cached document by its relative path.

type CacheState 

type CacheState struct {
	Key       string     `json:"key"`
	SyncedAt  *time.Time `json:"synced_at"`
	CheckedAt *time.Time `json:"checked_at"`
	Stale     bool       `json:"stale"`
	Offline   bool       `json:"offline"`
}

CacheState reports the current cache metadata for the JSON envelope.

type FileEntry 

type FileEntry struct {
	Path string `json:"path"`
	SHA  string `json:"sha"`
	Size int64  `json:"size"`
}

FileEntry records one cached document and its GitHub blob SHA so a later sync can reuse unchanged files without re-downloading them.

type GetResult 

type GetResult struct {
	ID          string   `json:"id"`
	Path        string   `json:"path"`
	Topic       string   `json:"topic"`
	Title       string   `json:"title"`
	Anchor      string   `json:"anchor,omitempty"`
	HeadingPath []string `json:"heading_path,omitempty"`
	LineStart   int      `json:"line_start,omitempty"`
	LineEnd     int      `json:"line_end,omitempty"`
	Content     string   `json:"content"`
}

GetResult is the payload for `docs get`.

type HTTPDoer 

type HTTPDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPDoer is the minimal HTTP contract used by sync, satisfied by *http.Client and the runtime's injected client.

type Index 

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

Index is an in-memory BM25 index built per invocation. No index is persisted; the corpus is small enough to rebuild on each search.

func NewIndex 

func NewIndex(sections []Section) *Index

NewIndex builds a BM25 index over the given sections.

func (*Index) Search 

func (idx *Index) Search(query, topic string, limit int) []Result

Search returns up to limit ranked results, filtered to topic when non-empty.

type ListItem 

type ListItem struct {
	Path  string `json:"path"`
	Topic string `json:"topic"`
	Title string `json:"title"`
}

ListItem is one document entry for `docs list`.

type Manifest 

type Manifest struct {
	SchemaVersion  int         `json:"schema_version"`
	Provider       string      `json:"provider"`
	Source         SourceRef   `json:"source"`
	ResolvedCommit string      `json:"resolved_commit"`
	Files          []FileEntry `json:"files"`
	SyncedAt       time.Time   `json:"synced_at"`
	CheckedAt      time.Time   `json:"checked_at"`
}

Manifest describes a published cache snapshot.

func (*Manifest) Stale 

func (m *Manifest) Stale(now time.Time) bool

Stale reports whether the snapshot is older than StaleAfter relative to now.

type Options 

type Options struct {
	Overrides    Overrides
	Config       *config.Config
	HTTPClient   HTTPDoer
	CacheDir     string
	GitHubAPIURL string
	RawBaseURL   string
	Token        string
	Now          func() time.Time
	Env          func(string) (string, bool)
}

Options configures a Service. The command layer builds this from cliruntime.Deps, the loaded config, and --repo/--ref/--path flags.

type Overrides 

type Overrides struct {
	Repo string
	Ref  string
	Path string
}

Overrides carries explicit per-invocation source overrides, typically from --repo/--ref/--path flags. Empty fields are treated as "not set".

type Result 

type Result struct {
	ID           string   `json:"id"`
	Rank         int      `json:"rank"`
	Score        float64  `json:"score"`
	Path         string   `json:"path"`
	Topic        string   `json:"topic"`
	Title        string   `json:"title"`
	HeadingPath  []string `json:"heading_path"`
	Anchor       string   `json:"anchor"`
	LineStart    int      `json:"line_start"`
	LineEnd      int      `json:"line_end"`
	Snippet      string   `json:"snippet"`
	MatchedTerms []string `json:"matched_terms"`
}

Result is one ranked search hit, deduplicated to the section level.

type Section 

type Section struct {
	DocPath     string   `json:"path"`
	Topic       string   `json:"topic"`
	Title       string   `json:"title"`
	Heading     string   `json:"heading"`
	HeadingPath []string `json:"heading_path"`
	Anchor      string   `json:"anchor"`
	Level       int      `json:"-"`
	LineStart   int      `json:"line_start"`
	LineEnd     int      `json:"line_end"`
	Body        string   `json:"-"`
}

Section is a heading-delimited slice of a document. Sections are the unit of search and retrieval: each has a stable id (docPath#anchor), a heading breadcrumb for context, and source line bounds.

func ParseDoc 

func ParseDoc(docPath string, content []byte) []Section

ParseDoc splits raw markdown into sections. It is fence-aware so ATX-style "#" lines inside code blocks are never treated as headings. The document title is the first level-1 heading, falling back to a prettified file name.

func (Section) ID 

func (s Section) ID() string

ID returns the stable section identifier docPath#anchor. A section with no anchor (document preamble) is identified by its bare doc path.

type Service 

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

Service is the entry point for docs operations, bundling a resolved source, its cache, and a syncer.

func NewService 

func NewService(opts Options) (*Service, error)

NewService resolves the documentation source and prepares the cache/syncer.

func (*Service) CacheState 

func (s *Service) CacheState(offline bool) CacheState

CacheState builds cache metadata; manifest may be nil when no cache exists.

func (*Service) Get 

func (s *Service) Get(ctx context.Context, id string, offline bool) (*GetResult, error)

Get retrieves a document by path, or a single section when the id carries a #anchor. A bare path returns the complete raw markdown document.

func (*Service) List 

func (s *Service) List(ctx context.Context, topic string, offline bool) ([]ListItem, error)

List returns the cached documents, optionally filtered by topic.

func (*Service) ResolvedCommit 

func (s *Service) ResolvedCommit() string

ResolvedCommit returns the live cache's pinned commit, or "".

func (*Service) Search 

func (s *Service) Search(ctx context.Context, query, topic string, limit int, offline bool) ([]Result, error)

Search bootstraps if needed then runs a BM25 query.

func (*Service) Source 

func (s *Service) Source() SourceRef

Source returns the resolved documentation source.

func (*Service) Sync 

func (s *Service) Sync(ctx context.Context, force bool) (*SyncResult, error)

Sync fetches/refreshes the cache from the source.

type SourceRef 

type SourceRef struct {
	Repo string `json:"repository"`
	Ref  string `json:"ref"`
	Path string `json:"path"`
}

SourceRef locates a documentation corpus: a GitHub owner/name repository, a ref (branch, tag, or commit), and the subdirectory the docs live under.

func DefaultSource 

func DefaultSource() SourceRef

DefaultSource returns the compiled-in default documentation source.

func ResolveSource 

func ResolveSource(ov Overrides, cfg *config.Config, lookup envLookup) SourceRef

ResolveSource applies the precedence flags > env (VOLCANO_DOCS_*) > config.DocsSource > compiled defaults, field by field. A missing value at one layer falls through to the next, so a user can override only the ref while inheriting the default repo and path.

func (SourceRef) CacheKey 

func (s SourceRef) CacheKey() string

CacheKey derives a stable, filesystem-safe identifier for a source so that distinct repo/ref/path combinations never share a cache namespace.

func (SourceRef) Validate 

func (s SourceRef) Validate() error

Validate enforces the narrow GitHub owner/name + ref + path shape. Rejecting anything else keeps configurable sources from becoming a path-traversal or SSRF vector: we only ever talk to api.github.com / raw.githubusercontent.com for a well-formed repository.

type SyncResult 

type SyncResult struct {
	ResolvedCommit string `json:"resolved_commit"`
	Added          int    `json:"added"`
	Updated        int    `json:"updated"`
	Removed        int    `json:"removed"`
	Unchanged      int    `json:"unchanged"`
	Changed        bool   `json:"changed"`
}

SyncResult summarizes a completed synchronization.

type Syncer 

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

Syncer fetches a documentation corpus from GitHub into a Cache.

func (*Syncer) Sync 

func (s *Syncer) Sync(ctx context.Context, force bool) (*SyncResult, error)

Sync resolves the source ref to a commit, enumerates markdown docs, reuses unchanged blobs from the prior snapshot, downloads changed ones, and atomically publishes a new snapshot. A no-change sync only refreshes checked_at. Any failure leaves the previous cache untouched.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.