keg

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Feb 24, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MarkdownContentFilename = "README.md"
	YAMLMetaFilename        = "meta.yaml"
	JSONStatsFilename       = "stats.json"
	KegCurrentEnvKey        = "KEG_CURRENT"
	KegLockFile             = ".keg-lock"
	NodeImagesDir           = "images"
	NodeAttachmentsDir      = "attachments"
)

Variables

View Source 
var (
	// ConfigV1VersionString is the initial KEG configuration version identifier.
	ConfigV1VersionString = "2023-01"

	// ConfigV2VersionString is the current KEG configuration version identifier.
	ConfigV2VersionString = "2025-07"

	// FormatMarkdown is the short format identifier for Markdown content.
	FormatMarkdown = "markdown"

	// FormatRST is the short format identifier for reStructuredText content.
	FormatRST = "rst"
)
View Source 
var (
	ErrInvalid       = os.ErrInvalid    // invalid argument
	ErrExist         = os.ErrExist      // file already exists
	ErrNotExist      = os.ErrNotExist   // file does not exist
	ErrPermission    = os.ErrPermission // permission denied
	ErrParse         = errors.New("unable to parse")
	ErrConflict      = errors.New("conflict")
	ErrQuotaExceeded = errors.New("quota exceeded")
	ErrRateLimited   = errors.New("rate limited")

	// ErrDestinationExists is returned when a move/rename cannot proceed because
	// the destination node id already exists. Prefer returning a typed
	// DestinationExistsError that unwraps to this sentinel when callers may need
	// structured information.
	ErrDestinationExists = errors.New("destination already exists")

	// ErrLockTimeout indicates acquiring a repository or node lock timed out or
	// was canceled. Lock-acquiring helpers should wrap context/cancellation
	// information while preserving this sentinel for callers that need to detect
	// timeout semantics via errors.Is.
	ErrLockTimeout = errors.New("lock acquire timeout")

	// ErrLock indicates a generic failure to acquire a repository or node
	// lock. Use errors.Is(err, ErrLock) to detect non-timeout lock acquisition
	// failures.
	ErrLock = errors.New("cannot acquire lock")
)

Sentinel errors used for simple equality-style checks.

View Source 
var RawZeroNodeContent = `` /* 229-byte string literal not displayed */

RawZeroNodeContent is the fallback content used when a node has no content. It serves as a friendly placeholder indicating the content is planned but not yet available. Callers may display this as the node README. If you want the content created sooner, open an issue describing the request.

Functions

func IsBackendError 

func IsBackendError(err error) bool

IsBackendError reports whether err is (or wraps) a BackendError.

func IsConflict 

func IsConflict(err error) bool

IsConflict returns true if err is a conflict error.

func IsDestinationExists 

func IsDestinationExists(err error) bool

IsDestinationExists returns true if err represents a destination-exists condition.

func IsInvalidConfig 

func IsInvalidConfig(err error) bool

IsInvalidConfig reports whether err is (or wraps) an invalid-config condition.

func IsPermissionDenied 

func IsPermissionDenied(err error) bool

IsPermissionDenied returns true if err indicates a permission problem.

func IsRetryable 

func IsRetryable(err error) bool

IsRetryable inspects the error chain for a Retryable() bool implementation and returns its result (false if none found).

func IsTemporary 

func IsTemporary(err error) bool

IsTemporary inspects the error chain for a Temporary() bool implementation and returns its result (false if none found).

func NewAliasNotFoundError 

func NewAliasNotFoundError(alias string) error

NewAliasNotFoundError constructs a typed AliasNotFoundError.

func NewBackendError 

func NewBackendError(backend, op string, status int, cause error, transient bool) error

NewBackendError constructs a *BackendError describing an operation against a backend.

func NewInvalidConfigError 

func NewInvalidConfigError(msg string) error

NewInvalidConfigError creates an InvalidConfigError with a human message.

func NewRateLimitError 

func NewRateLimitError(retryAfter time.Duration, msg string, cause error) error

NewRateLimitError constructs a *RateLimitError with a suggested retry duration.

func NewTransientError 

func NewTransientError(cause error) error

NewTransientError constructs a *TransientError wrapping the provided cause.

func NormalizeTag 

func NormalizeTag(s string) string

NormalizeTag normalizeTag lowercases, trims, and tokenizes a tag string into a hyphen-separated token.

func NormalizeTags 

func NormalizeTags(tags []string) []string

func ParseTags 

func ParseTags(raw string) []string

ParseTags accepts a comma/semicolon/newline separated list of tags (or a whitespace-separated string when no explicit separators are present) and returns a normalized, deduplicated, sorted slice of tags.

Behavior: - Trims whitespace around tokens. - Lowercases tokens and converts internal whitespace to hyphens via NormalizeTag. - Splits on commas, semicolons, CR/LF, or newlines when present; otherwise splits on whitespace. - Deduplicates tokens and returns them in lexicographic order.

func RandomCode 

func RandomCode(context.Context) string

func RepoContainsKeg 

func RepoContainsKeg(ctx context.Context, repo Repository) (bool, error)

RepoContainsKeg checks if a keg has been properly initialized within a repository. It verifies both that a keg config exists and that a zero node (node ID 0) is present. Returns true only if both conditions are met, indicating a fully initialized keg.

Types

type AliasNotFoundError 

type AliasNotFoundError struct {
	Alias string
}

AliasNotFoundError is a typed error that carries the missing alias for callers that need richer diagnostic information.

func (*AliasNotFoundError) Error 

func (e *AliasNotFoundError) Error() string

type AssetKind 

type AssetKind string

AssetKind identifies an asset namespace for a node. 

const (
	AssetKindImage AssetKind = "image"
	AssetKindItem  AssetKind = "item"
)

type BackendError 

type BackendError struct {
	Backend    string // e.g. "s3", "http", "postgres", "fs"
	Op         string // operation, e.g. "WriteContent", "GetMeta"
	StatusCode int    // optional HTTP / backend status
	Cause      error
	Transient  bool // whether this is a transient error (retryable)
}

BackendError wraps errors coming from an external backend (API, DB, object store). It exposes Retryable() to indicate transient failures.

func ParseBackendError 

func ParseBackendError(err error) *BackendError

func (*BackendError) Error 

func (e *BackendError) Error() string

func (*BackendError) Retryable 

func (e *BackendError) Retryable() bool

Retryable reports whether the backend error is transient.

func (*BackendError) Unwrap 

func (e *BackendError) Unwrap() error

Unwrap returns the wrapped cause.

type BacklinkIndex 

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

BacklinkIndex maps a destination node path to the list of source nodes that link to that destination. The underlying map keys are node.Path() values (string). The index is used to construct the "backlinks" index artifact.

The type is intended for in-memory, single-process use. Concurrency control is the caller's responsibility.

func ParseBacklinksIndex 

func ParseBacklinksIndex(ctx context.Context, data []byte) (*BacklinkIndex, error)

ParseBacklinksIndex parses the raw bytes of a backlinks index into a BacklinkIndex.

Expected on-disk format is one line per destination: 

"<dst>\t<src1> <src2> ...\n"

Behavior:

  • Empty or nil input yields an empty BacklinkIndex with no error.
  • Lines are split on tab to separate destination from space-separated sources.
  • Duplicate sources for a destination are tolerated and may be deduped by callers of Data.
  • This function does not modify any external state.

func (*BacklinkIndex) Add 

func (idx *BacklinkIndex) Add(ctx context.Context, data *NodeData) error

Add incorporates backlink information derived from the provided NodeData. For each outgoing link listed in data.Links the function will add the source node (data.ID) to the corresponding destination entry in the index.

Behavior expectations:

  • If idx is nil the call is a no-op and returns nil.
  • If idx.data is nil it will be initialized.
  • The method should avoid introducing duplicate source entries for a given destination when possible.

This method only mutates in-memory state and does not perform I/O.

func (*BacklinkIndex) Data 

func (idx *BacklinkIndex) Data(ctx context.Context) ([]byte, error)

Data serializes the index into the canonical on-disk format.

Serialization rules:

  • Each non-empty destination produces a line: "<dst>\t<src1> <src2> ...\n"
  • Source lists are deduplicated and sorted in a deterministic order.
  • Destination keys are emitted in a deterministic, parse-aware order (numeric node ids sorted numerically when possible, otherwise lexicographic).
  • An empty index returns an empty byte slice.

The returned bytes are owned by the caller and may be written atomically by the repository layer.

func (*BacklinkIndex) Rm 

func (idx *BacklinkIndex) Rm(ctx context.Context, node NodeId) error

Rm removes any backlink references introduced by the given node. It removes the node as a source from any destination lists and may remove the entry for a destination if it ends up with no sources.

Behavior expectations:

  • If idx is nil the call is a no-op and returns nil.
  • If idx.data is nil it will be initialized to an empty map.
  • After removal, entries with no sources may either remain as empty slices or be deleted; callers should tolerate either representation.

This method only mutates in-memory state and does not perform I/O.

type Config 

type Config = ConfigV2

KegConfig is an alias for the latest configuration version. Update this alias when introducing a newer configuration version.

func NewConfig 

func NewConfig(options ...ConfigOption) *Config

func ParseKegConfig 

func ParseKegConfig(data []byte) (*Config, error)

ParseKegConfig parses raw YAML config data into the latest Config version. It detects the "kegv" version field and performs migration from earlier versions when necessary.

func (*Config) AddEntity 

func (kc *Config) AddEntity(name string, id int, summary string) error

AddEntity adds or updates an entity entry by entity name.

func (*Config) AddTag 

func (kc *Config) AddTag(name, summary string) error

AddTag adds or updates a tag summary by tag name.

func (*Config) ResolveAlias 

func (kc *Config) ResolveAlias(alias string) (*kegurl.Target, error)

func (*Config) String 

func (kc *Config) String() string

func (*Config) ToJSON 

func (kc *Config) ToJSON() ([]byte, error)

ToJSON serializes the Config to JSON.

func (*Config) ToYAML 

func (kc *Config) ToYAML() ([]byte, error)

ToYAML serializes the Config to YAML.

func (*Config) Touch 

func (kc *Config) Touch(t time.Time)

type ConfigOption 

type ConfigOption = func(cfg *Config)

type ConfigV1 

type ConfigV1 struct {
	// Kegv is the version of the specification.
	Kegv string `yaml:"kegv"`

	// Updated indicates when the keg was last indexed.
	Updated string `yaml:"updated,omitempty"`

	// Title is the title of the KEG worklog or project.
	Title string `yaml:"title,omitempty"`

	// URL is the main URL where the KEG can be found.
	URL string `yaml:"url,omitempty"`

	// Creator is the URL or identifier of the creator of the KEG.
	Creator string `yaml:"creator,omitempty"`

	// State indicates the current state of the KEG (e.g., living, archived).
	State string `yaml:"state,omitempty"`

	// Summary provides a brief description or summary of the KEG content.
	Summary string `yaml:"summary,omitempty"`

	// Indexes is a list of index entries that link to related files or nodes.
	Indexes []IndexEntry `yaml:"indexes,omitempty"`
	// contains filtered or unexported fields
}

ConfigV1 KegConfigV1 represents the initial version of the KEG configuration specification.

type ConfigV2 

type ConfigV2 struct {
	// Kegv is the version of the specification.
	Kegv string `yaml:"kegv"`

	// Updated indicates when the keg was last indexed.
	Updated string `yaml:"updated,omitempty"`

	// Title is the title of the KEG worklog or project.
	Title string `yaml:"title,omitempty"`

	// URL is the main URL where the KEG can be found.
	URL string `yaml:"url,omitempty"`

	// Creator is the URL or identifier of the creator of the KEG.
	Creator string `yaml:"creator,omitempty"`

	// State indicates the current state of the KEG (e.g., living, archived).
	State string `yaml:"state,omitempty"`

	// Summary provides a brief description or summary of the KEG content.
	Summary string `yaml:"summary,omitempty"`

	// Links holds a list of LinkEntry objects representing related links or
	// references in the configuration.
	Links []LinkEntry `yaml:"links,omitempty"`

	// Indexes is a list of index entries that link to related files or nodes.
	Indexes []IndexEntry `yaml:"indexes,omitempty"`

	Entities map[string]EntityEntry `yaml:"entities,omitempty"`

	Tags map[string]string `yaml:"tags,omitempty"`
	// contains filtered or unexported fields
}

KegConfigV2 represents the second (current) version of the KEG configuration specification. It extends V1 with additional fields such as Links and Zekia.

type CreateOptions 

type CreateOptions struct {
	// Title is the human-readable title for the node
	Title string
	// Lead is a one-line summary
	Lead string
	// Tags are searchable labels for the node
	Tags []string
	// Body is the raw markdown content; if empty, default content is generated from Title/Lead
	Body []byte
	// Attrs are arbitrary key-value attributes attached to the node
	Attrs map[string]any
}

CreateOptions specifies parameters for creating a new node

type Dex 

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

Dex provides a high-level, in-memory view of the repository's generated dex indices: nodes, tags, links, and backlinks. It is a convenience wrapper used by index builders and other tooling to read or inspect index data without dealing directly with repository I/O. Dex does not perform any I/O itself; callers are responsible for providing a Repository when writing indices.

func NewDexFromRepo 

func NewDexFromRepo(ctx context.Context, repo Repository) (*Dex, error)

NewDexFromRepo loads available index artifacts ("nodes.tsv", "tags", "links", "backlinks") from the provided repository and returns a Dex populated with parsed indexes. Missing or empty index files are treated as empty datasets and do not cause an error.

func (*Dex) Add 

func (dex *Dex) Add(ctx context.Context, data *NodeData) error

Add adds the provided node to all managed indexes. This implements the IndexBuilder contract for convenience when using Dex as an aggregated builder. 

func (dex *Dex) Backlinks(ctx context.Context, node NodeId) ([]NodeId, bool)

Backlinks returns the parsed backlinks index (map[dst] -> []src). NOTE: not intended to be mutated

func (*Dex) Clear 

func (dex *Dex) Clear(ctx context.Context)

Clear resets all in-memory index data held by the Dex instance.

func (*Dex) GetRef 

func (dex *Dex) GetRef(ctx context.Context, id NodeId) *NodeIndexEntry
func (dex *Dex) Links(ctx context.Context, node NodeId) ([]NodeId, bool)

Links returns the parsed outgoing links index (map[src] -> []dst).

func (*Dex) NextNode 

func (dex *Dex) NextNode(ctx context.Context) NodeId

func (*Dex) Nodes 

func (dex *Dex) Nodes(ctx context.Context) []NodeIndexEntry

Nodes returns a copy of the parsed nodes index (slice of NodeRef).

func (*Dex) Remove 

func (dex *Dex) Remove(ctx context.Context, node NodeId) error

Remove removes the node identified by id from all managed indexes. This implements the IndexBuilder contract for convenience when using Dex. 

func (dex *Dex) TagLinks(ctx context.Context, node NodeId) ([]NodeId, bool)

TagLinks Tags returns the parsed tags index (map[tag] -> []NodeID).

func (*Dex) TagList 

func (dex *Dex) TagList(ctx context.Context) []string

func (*Dex) TagNodes 

func (dex *Dex) TagNodes(ctx context.Context, tag string) ([]NodeId, bool)

TagNodes returns the parsed tags index entry for tag (map[tag] -> []NodeID).

func (*Dex) Write 

func (dex *Dex) Write(ctx context.Context, repo Repository) error

Write serializes the in-memory indexes and writes them atomically to the provided repository using WriteIndex. If any write operation fails the error chain is returned (errors.Join is used to aggregate multiple errors).

type EntityEntry 

type EntityEntry struct {
	ID      int    `yaml:"id"`
	Summary string `yaml:"summary"`
}

type FsRepo 

type FsRepo struct {
	// Root is the base directory path containing all KEG node directories
	Root string
	// ContentFilename specifies the filename for node content (typically README.md)
	ContentFilename string
	// MetaFilename specifies the filename for node metadata (typically meta.yaml)
	MetaFilename  string
	StatsFilename string
	// contains filtered or unexported fields
}

FsRepo implements Repository using the local filesystem as storage. It manages KEG nodes as directories under [Root], with each node containing content files, metadata, and optional attachments. Thread-safe operations are coordinated through the embedded mutex.

func NewFsRepo 

func NewFsRepo(root string, rt *toolkit.Runtime) *FsRepo

NewFsRepo constructs a filesystem repository with the provided root/runtime.

func NewFsRepoFromEnvOrSearch 

func NewFsRepoFromEnvOrSearch(ctx context.Context, rt *toolkit.Runtime) (*FsRepo, error)

NewFsRepoFromEnvOrSearch tries to locate a keg file using the order: 1) KEG_CURRENT env var (file or directory) 2) current working directory 3) if inside a git project, search the project tree for a keg file 4) recursive search from current working directory 5) fallback to default config location (~/.config/keg or XDG equivalent)

Returns a pointer to an initialized FsRepo and the path of the discovered keg file (or "" if using fallback path).

func (*FsRepo) ClearIndexes 

func (f *FsRepo) ClearIndexes(ctx context.Context) error

func (*FsRepo) DeleteAsset 

func (f *FsRepo) DeleteAsset(ctx context.Context, id NodeId, kind AssetKind, name string) error

DeleteAsset implements Repository.

func (*FsRepo) DeleteFile 

func (f *FsRepo) DeleteFile(ctx context.Context, id NodeId, name string) error

func (*FsRepo) DeleteImage 

func (f *FsRepo) DeleteImage(ctx context.Context, id NodeId, name string) error

func (*FsRepo) DeleteNode 

func (f *FsRepo) DeleteNode(ctx context.Context, id NodeId) error

DeleteNode implements Repository.

func (*FsRepo) GetIndex 

func (f *FsRepo) GetIndex(ctx context.Context, name string) ([]byte, error)

GetIndex implements Repository.

func (*FsRepo) HasNode 

func (f *FsRepo) HasNode(ctx context.Context, id NodeId) (bool, error)

func (*FsRepo) ListAssets 

func (f *FsRepo) ListAssets(ctx context.Context, id NodeId, kind AssetKind) ([]string, error)

ListAssets implements Repository.

func (*FsRepo) ListFiles 

func (f *FsRepo) ListFiles(ctx context.Context, id NodeId) ([]string, error)

func (*FsRepo) ListImages 

func (f *FsRepo) ListImages(ctx context.Context, id NodeId) ([]string, error)

func (*FsRepo) ListIndexes 

func (f *FsRepo) ListIndexes(ctx context.Context) ([]string, error)

ListIndexes implements Repository.

func (*FsRepo) ListNodes 

func (f *FsRepo) ListNodes(ctx context.Context) ([]NodeId, error)

func (*FsRepo) MoveNode 

func (f *FsRepo) MoveNode(ctx context.Context, id NodeId, dst NodeId) error

MoveNode implements Repository.

func (*FsRepo) Name 

func (f *FsRepo) Name() string

func (*FsRepo) Next 

func (f *FsRepo) Next(ctx context.Context) (NodeId, error)

func (*FsRepo) NodeFilesExist 

func (f *FsRepo) NodeFilesExist(ctx context.Context, id NodeId) (bool, bool, error)

func (*FsRepo) ReadConfig 

func (f *FsRepo) ReadConfig(ctx context.Context) (*Config, error)

ReadConfig implements Repository.

func (*FsRepo) ReadContent 

func (f *FsRepo) ReadContent(ctx context.Context, id NodeId) ([]byte, error)

ReadContent implements Repository.

func (*FsRepo) ReadMeta 

func (f *FsRepo) ReadMeta(ctx context.Context, id NodeId) ([]byte, error)

ReadMeta implements Repository.

func (*FsRepo) ReadStats 

func (f *FsRepo) ReadStats(ctx context.Context, id NodeId) (*NodeStats, error)

ReadStats implements Repository.

func (*FsRepo) Runtime 

func (f *FsRepo) Runtime() *toolkit.Runtime

func (*FsRepo) WithNodeLock 

func (f *FsRepo) WithNodeLock(ctx context.Context, id NodeId, fn func(context.Context) error) error

WithNodeLock executes fn while holding an exclusive lock for node id.

func (*FsRepo) WriteAsset 

func (f *FsRepo) WriteAsset(ctx context.Context, id NodeId, kind AssetKind, name string, data []byte) error

WriteAsset implements Repository.

func (*FsRepo) WriteConfig 

func (f *FsRepo) WriteConfig(ctx context.Context, config *Config) error

WriteConfig implements Repository.

func (*FsRepo) WriteContent 

func (f *FsRepo) WriteContent(ctx context.Context, id NodeId, data []byte) error

WriteContent implements Repository.

func (*FsRepo) WriteFile 

func (f *FsRepo) WriteFile(ctx context.Context, id NodeId, name string, data []byte) error

func (*FsRepo) WriteImage 

func (f *FsRepo) WriteImage(ctx context.Context, id NodeId, name string, data []byte) error

func (*FsRepo) WriteIndex 

func (f *FsRepo) WriteIndex(ctx context.Context, name string, data []byte) error

WriteIndex implements Repository.

func (*FsRepo) WriteMeta 

func (f *FsRepo) WriteMeta(ctx context.Context, id NodeId, data []byte) error

WriteMeta implements Repository.

func (*FsRepo) WriteStats 

func (f *FsRepo) WriteStats(ctx context.Context, id NodeId, stats *NodeStats) error

WriteStats implements Repository.

type IndexBuilder 

type IndexBuilder interface {
	// Name returns the canonical index filename (for example "dex/tags").
	Name() string

	// Add incorporates information from a node into the index's in-memory state.
	Add(ctx context.Context, node *NodeData) error

	// Remove deletes node-related state from the index.
	Remove(ctx context.Context, node NodeId) error

	// Clear resets the index to an empty state.
	Clear(ctx context.Context) error

	// Data returns the serialized index bytes to be written to storage.
	Data(ctx context.Context) ([]byte, error)
}

IndexBuilder is an interface for constructing a single index artifact (for example: nodes.tsv, tags, links, backlinks). Implementations maintain in-memory state via Add / Remove / Clear and produce the serialized bytes to write via Data.

type IndexEntry 

type IndexEntry struct {
	File    string `yaml:"file"`
	Summary string `yaml:"summary"`
}

IndexEntry represents an entry in the indexes list in the KEG configuration.

type IndexOptions 

type IndexOptions struct {
	Rebuild  bool
	NoUpdate bool
}

type InvalidConfigError 

type InvalidConfigError struct {
	Msg string
}

InvalidConfigError represents a validation or parse failure for tapper config.

func (*InvalidConfigError) Error 

func (e *InvalidConfigError) Error() string

func (*InvalidConfigError) Is 

func (e *InvalidConfigError) Is(target error) bool

func (*InvalidConfigError) Unwrap 

func (e *InvalidConfigError) Unwrap() error

type Keg 

type Keg struct {
	// Target is the keg URL/location (nil for memory-backed kegs)
	Target *kegurl.Target
	// Repo is the storage backend implementation
	Repo Repository
	// Runtime provides clock/hash/fs helpers used by high-level keg operations.
	Runtime *toolkit.Runtime
	// contains filtered or unexported fields
}

Keg is a concrete high-level service providing KEG node operations backed by a Repository. It abstracts storage implementation details, allowing operations over nodes to work uniformly across memory, filesystem, and remote backends. Keg delegates low-level storage operations to its underlying repository and maintains an in-memory dex for indexing.

func NewKeg 

func NewKeg(repo Repository, rt *toolkit.Runtime, opts ...Option) *Keg

NewKeg returns a Keg service backed by the provided repository. Functional options can be provided to customize Keg behavior.

func NewKegFromTarget 

func NewKegFromTarget(ctx context.Context, target kegurl.Target, rt *toolkit.Runtime) (*Keg, error)

NewKegFromTarget constructs a Keg from a kegurl.Target. It automatically selects the appropriate repository implementation based on the target's scheme: - memory:// targets use an in-memory repository - file:// targets use a filesystem repository Returns an error if the target scheme is not supported.

func (*Keg) Commit 

func (k *Keg) Commit(ctx context.Context, id NodeId) error

Commit finalizes a temporary node by allocating a permanent ID and moving it from its temporary location (with Code suffix) to the canonical numeric ID. For nodes without a Code (already permanent), Commit is a no-op.

func (*Keg) Config 

func (k *Keg) Config(ctx context.Context) (*Config, error)

Config returns the keg's configuration.

func (*Keg) Create 

func (k *Keg) Create(ctx context.Context, opts *CreateOptions) (NodeId, error)

Create creates a new node: allocates an ID, parses content, generates metadata, and indexes the node in the dex. The node is immediately persisted to the repository. If Body is empty, default markdown content is generated from Title and Lead.

func (*Keg) Dex 

func (k *Keg) Dex(ctx context.Context) (*Dex, error)

Dex returns the keg's index, loading it from the repository on first access. The dex is lazily loaded and cached in memory for efficient access.

func (*Keg) GetContent 

func (k *Keg) GetContent(ctx context.Context, id NodeId) ([]byte, error)

GetContent retrieves the raw markdown content for a node.

func (*Keg) GetMeta 

func (k *Keg) GetMeta(ctx context.Context, id NodeId) (*NodeMeta, error)

GetMeta retrieves the parsed metadata for a node.

func (*Keg) GetStats 

func (k *Keg) GetStats(ctx context.Context, id NodeId) (*NodeStats, error)

GetStats retrieves programmatic node stats for a node.

func (*Keg) Index 

func (k *Keg) Index(ctx context.Context, opts IndexOptions) error

Index updates the keg indices. With Rebuild=true, all index artifacts are rebuilt from scratch. With Rebuild=false, only nodes updated since config.updated (plus missing metadata/stats files) are indexed.

func (*Keg) IndexNode 

func (k *Keg) IndexNode(ctx context.Context, id NodeId) error

IndexNode updates a node's metadata by re-parsing its content and extracting properties like title, lead, and content hash. The dex is also updated to reflect any changes. If content hasn't changed, this is a no-op.

func (*Keg) Init 

func (k *Keg) Init(ctx context.Context) error

Init initializes a new keg by creating the config file, zero node with default content, and updating the dex. It returns an error if the keg already exists. Init is idempotent in the sense that it checks for existing kegs first.

func (*Keg) Move 

func (k *Keg) Move(ctx context.Context, src NodeId, dst NodeId) error

Move renames a node from src to dst and rewrites in-content links that target src (../N) across the keg.

func (*Keg) Next 

func (k *Keg) Next(ctx context.Context) (NodeId, error)

Next reserves and returns the next available node ID from the repository.

func (*Keg) Node 

func (k *Keg) Node(id NodeId) *Node

Node retrieves complete node data including content, metadata, items, and images for a given node ID. Returns an error if any component fails to load.

func (*Keg) Remove 

func (k *Keg) Remove(ctx context.Context, id NodeId) error

Remove deletes a node from the repository and updates dex/config artifacts.

func (*Keg) SetConfig 

func (k *Keg) SetConfig(ctx context.Context, data []byte) error

SetConfig parses and writes keg configuration from raw bytes. Prefer UpdateConfig for most use cases as it handles read-modify-write atomically.

func (*Keg) SetContent 

func (k *Keg) SetContent(ctx context.Context, id NodeId, data []byte) error

SetContent writes content for a node and updates its metadata by re-indexing. This ensures the node's title, lead, and other metadata are kept in sync with content changes.

func (*Keg) SetMeta 

func (k *Keg) SetMeta(ctx context.Context, id NodeId, meta *NodeMeta) error

SetMeta writes metadata for a node and updates the dex.

func (*Keg) Touch 

func (k *Keg) Touch(ctx context.Context, id NodeId) error

Touch updates the access time of a node to the current time.

func (*Keg) UpdateConfig 

func (k *Keg) UpdateConfig(ctx context.Context, f func(*Config)) error

UpdateConfig reads the keg config, applies the provided mutation function, and writes the result back to the repository. This is the preferred way to modify keg configuration to ensure updates are atomically persisted.

func (*Keg) UpdateMeta 

func (k *Keg) UpdateMeta(ctx context.Context, id NodeId, f func(*NodeMeta)) error

UpdateMeta reads the node's metadata, applies the provided mutation function, and writes the result back to the repository with dex updates.

type LinkEntry 

type LinkEntry struct {
	Alias string `json:"alias"` // Alias for the link
	URL   string `json:"url"`   // URL of the link
}

LinkEntry represents a named link in the KEG configuration.

type LinkIndex 

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

LinkIndex maps a source node path to the list of destination nodes that the source links to. It is used to construct the "links" index artifact.

The underlying map keys are node.Path() values (string). The index is expected to be small enough to be kept in memory for index-building tooling.

The type has unexported fields and is safe for in-memory, single-process use. Concurrency control is the caller's responsibility.

func ParseLinkIndex 

func ParseLinkIndex(ctx context.Context, data []byte) (LinkIndex, error)

ParseLinkIndex parses the raw bytes of a links index into a LinkIndex. The expected on-disk format is one line per source: 

"<src>\t<dst1> <dst2> ...\n"

Behavior:

  • Empty or nil input yields an empty LinkIndex with no error.
  • Lines are split on tab to separate source from space-separated destinations.
  • Duplicate destinations for a source are tolerated and may be deduped by callers of Data.

This function does not modify any external state.

func (*LinkIndex) Add 

func (idx *LinkIndex) Add(ctx context.Context, data *NodeData) error

Add incorporates link information from the provided NodeData into the index. The NodeData.ID value is used as the source key (via NodeId.Path semantics) and NodeData.Links is treated as the list of destination nodes.

Behavior expectations (not enforced here but callers may rely on them):

  • If idx is nil the call is a no-op and returns nil.
  • If idx.data is nil it will be initialized.
  • The method should avoid introducing duplicate destination entries for a given source when possible.

This method only mutates in-memory state and does not perform I/O.

func (*LinkIndex) Data 

func (idx *LinkIndex) Data(ctx context.Context) ([]byte, error)

Data serializes the index into the canonical on-disk format.

Serialization rules:

  • Each non-empty source produces a line: "<src>\t<dst1> <dst2> ...\n"
  • Destination lists are deduplicated and sorted in a deterministic order.
  • Source keys are emitted in a deterministic, parse-aware order (numeric node ids sorted numerically when possible, otherwise lexicographic).
  • An empty index returns an empty byte slice.

The returned bytes are owned by the caller and may be written atomically by the repository layer.

func (*LinkIndex) Rm 

func (idx *LinkIndex) Rm(ctx context.Context, node NodeId) error

Rm removes any references introduced by the given node as a source and removes the node from any destination lists where it appears.

Behavior expectations:

  • If idx is nil the call is a no-op and returns nil.
  • If idx.data is nil it will be initialized to an empty map.
  • After removal, entries with no destinations may either remain as empty slices or be deleted; callers should tolerate either representation.

This method only mutates in-memory state and does not perform I/O.

type MemoryRepo 

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

MemoryRepo is an in-memory implementation of Repository intended for tests and lightweight tooling that doesn't require persistent storage.

Concurrency / locking:

  • MemoryRepo uses an internal sync.RWMutex (mu) to guard all internal maps and per-node structures. Readers should use RLock/RUnlock; mutating operations use Lock/Unlock.
  • The implementation is safe for concurrent use by multiple goroutines.

Semantics / behavior:

  • NodeId entries are created on demand when writing content, meta, items, or images.
  • Index files are kept in-memory by name (for example "nodes.tsv") and are accessible via WriteIndex/GetIndex.
  • Methods return sentinel or typed errors defined in the package to match the Repository contract (for example NewNodeNotFoundError, ErrNotFound).

func NewMemoryRepo 

func NewMemoryRepo(rt *toolkit.Runtime) *MemoryRepo

NewMemoryRepo constructs a ready-to-use in-memory repository.

func (*MemoryRepo) ClearDex 

func (r *MemoryRepo) ClearDex() error

ClearDex removes all stored index artifacts.

func (*MemoryRepo) ClearIndexes 

func (r *MemoryRepo) ClearIndexes(ctx context.Context) error

ClearIndexes removes all stored index artifacts.

func (*MemoryRepo) ClearNodeLock 

func (r *MemoryRepo) ClearNodeLock(ctx context.Context, id NodeId) error

ClearNodeLock removes an active per-node lock marker.

func (*MemoryRepo) DeleteAsset 

func (r *MemoryRepo) DeleteAsset(ctx context.Context, id NodeId, kind AssetKind, name string) error

DeleteAsset removes an asset by name for a node.

func (*MemoryRepo) DeleteFile 

func (r *MemoryRepo) DeleteFile(ctx context.Context, id NodeId, name string) error

func (*MemoryRepo) DeleteImage 

func (r *MemoryRepo) DeleteImage(ctx context.Context, id NodeId, name string) error

func (*MemoryRepo) DeleteNode 

func (r *MemoryRepo) DeleteNode(ctx context.Context, id NodeId) error

DeleteNode removes the node and all associated content/metadata/items. If the node does not exist, NewNodeNotFoundError is returned.

func (*MemoryRepo) GetIndex 

func (r *MemoryRepo) GetIndex(ctx context.Context, name string) ([]byte, error)

GetIndex reads a stored index by name. If not present, ErrNotFound is returned. The returned bytes are a copy.

func (*MemoryRepo) HasNode 

func (r *MemoryRepo) HasNode(ctx context.Context, id NodeId) (bool, error)

func (*MemoryRepo) ListAssets 

func (r *MemoryRepo) ListAssets(ctx context.Context, id NodeId, kind AssetKind) ([]string, error)

ListAssets lists asset names for a node and asset kind, sorted lexicographically.

func (*MemoryRepo) ListFiles 

func (r *MemoryRepo) ListFiles(ctx context.Context, id NodeId) ([]string, error)

func (*MemoryRepo) ListImages 

func (r *MemoryRepo) ListImages(ctx context.Context, id NodeId) ([]string, error)

func (*MemoryRepo) ListIndexes 

func (r *MemoryRepo) ListIndexes(ctx context.Context) ([]string, error)

ListIndexes returns the names of stored index files sorted lexicographically.

func (*MemoryRepo) ListNodes 

func (r *MemoryRepo) ListNodes(ctx context.Context) ([]NodeId, error)

ListNodes returns all known NodeIDs sorted in ascending numeric order.

func (*MemoryRepo) LockNode 

func (r *MemoryRepo) LockNode(ctx context.Context, id NodeId, retryInterval time.Duration) (func() error, error)

LockNode attempts to acquire a per-node lock. It will retry at the provided retryInterval until the context is cancelled. On success it returns an unlock function which the caller MUST call to release the lock.

Behavior notes:

- If retryInterval <= 0, a sensible default is used. - If ctx is cancelled while waiting, ErrLockTimeout is returned.

func (*MemoryRepo) MoveNode 

func (r *MemoryRepo) MoveNode(ctx context.Context, id NodeId, dst NodeId) error

MoveNode renames or moves a node from id to dst.

- If the source node does not exist, ErrNodeNotFound is returned. - If the destination already exists, a DestinationExistsError is returned. The move is performed by transferring the in-memory node pointer.

func (*MemoryRepo) Name 

func (r *MemoryRepo) Name() string

func (*MemoryRepo) Next 

func (r *MemoryRepo) Next(ctx context.Context) (NodeId, error)

Next returns a new NodeID. The context is accepted to satisfy the repository interface but is not used by this in-memory implementation.

This implementation finds the highest existing node id and returns that value + 1. If no nodes exist, it returns 0.

func (*MemoryRepo) NodeFilesExist 

func (r *MemoryRepo) NodeFilesExist(ctx context.Context, id NodeId) (bool, bool, error)

func (*MemoryRepo) ReadConfig 

func (r *MemoryRepo) ReadConfig(ctx context.Context) (*Config, error)

ReadConfig returns the repository-level config previously written with WriteConfig. If no config has been written, ErrNotFound is returned. A copy of the stored Config is returned to avoid external mutation.

func (*MemoryRepo) ReadContent 

func (r *MemoryRepo) ReadContent(ctx context.Context, id NodeId) ([]byte, error)

ReadContent returns the primary content for the given node id.

- If the node does not exist, ErrNodeNotFound is returned. - If the node exists but has no content, (nil, nil) is returned. - The returned slice is a copy to prevent caller-visible mutation.

func (*MemoryRepo) ReadMeta 

func (r *MemoryRepo) ReadMeta(ctx context.Context, id NodeId) ([]byte, error)

ReadMeta returns the serialized node metadata (usually meta.yaml).

- If the node does not exist, ErrNodeNotFound is returned. - If meta is absent, ErrNotFound is returned. - The returned bytes are a copy.

func (*MemoryRepo) ReadStats 

func (r *MemoryRepo) ReadStats(ctx context.Context, id NodeId) (*NodeStats, error)

ReadStats returns parsed programmatic stats for a node.

func (*MemoryRepo) Runtime 

func (r *MemoryRepo) Runtime() *toolkit.Runtime

func (*MemoryRepo) WithNodeLock 

func (r *MemoryRepo) WithNodeLock(ctx context.Context, id NodeId, fn func(context.Context) error) error

WithNodeLock executes fn while holding an exclusive lock for node id.

func (*MemoryRepo) WriteAsset 

func (r *MemoryRepo) WriteAsset(ctx context.Context, id NodeId, kind AssetKind, name string, data []byte) error

WriteAsset stores a named asset blob for a node.

func (*MemoryRepo) WriteConfig 

func (r *MemoryRepo) WriteConfig(ctx context.Context, config *Config) error

WriteConfig stores the provided Config in-memory. A copy of the value is kept.

func (*MemoryRepo) WriteContent 

func (r *MemoryRepo) WriteContent(ctx context.Context, id NodeId, data []byte) error

WriteContent writes the primary content for the given node id, creating the node if necessary.

Note: this implementation stores the provided slice reference in-memory. Callers should avoid mutating the provided slice after calling this method.

func (*MemoryRepo) WriteFile 

func (r *MemoryRepo) WriteFile(ctx context.Context, id NodeId, name string, data []byte) error

func (*MemoryRepo) WriteImage 

func (r *MemoryRepo) WriteImage(ctx context.Context, id NodeId, name string, data []byte) error

func (*MemoryRepo) WriteIndex 

func (r *MemoryRepo) WriteIndex(ctx context.Context, name string, data []byte) error

WriteIndex writes or replaces an in-memory index file.

func (*MemoryRepo) WriteMeta 

func (r *MemoryRepo) WriteMeta(ctx context.Context, id NodeId, data []byte) error

WriteMeta sets the node metadata (meta.yaml bytes), creating the node if needed.

Note: the provided slice is stored as-is in-memory; do not modify it after writing.

func (*MemoryRepo) WriteStats 

func (r *MemoryRepo) WriteStats(ctx context.Context, id NodeId, stats *NodeStats) error

WriteStats writes programmatic stats while preserving manually edited meta fields.

type Node 

type Node struct {
	ID      NodeId
	Repo    Repository
	Runtime *toolkit.Runtime
	// contains filtered or unexported fields
}

Node provides operations and lifecycle management for a single KEG node. It holds the node identifier, repository reference, and lazily-loaded node data.

func (*Node) Accessed 

func (n *Node) Accessed(ctx context.Context) (time.Time, error)

func (*Node) Changed 

func (n *Node) Changed(ctx context.Context) (bool, error)

func (*Node) ClearCache 

func (n *Node) ClearCache()

func (*Node) Created 

func (n *Node) Created(ctx context.Context) (time.Time, error)

func (*Node) Init 

func (n *Node) Init(ctx context.Context) error

Init loads and initializes the node data from the repository including content, metadata, items, and images. Returns an error if the repository is not set or if any repository operation fails.

func (*Node) Lead 

func (n *Node) Lead(ctx context.Context) (string, error)
func (n *Node) Links(ctx context.Context) ([]NodeId, error)

func (*Node) ListImages 

func (n *Node) ListImages(ctx context.Context) ([]string, error)

func (*Node) ListItems 

func (n *Node) ListItems(ctx context.Context) ([]string, error)

func (*Node) Ref 

func (n *Node) Ref(ctx context.Context) (NodeIndexEntry, error)

func (*Node) Save 

func (n *Node) Save(ctx context.Context) error

func (*Node) Stats 

func (n *Node) Stats(ctx context.Context) (*NodeStats, error)

func (*Node) String 

func (n *Node) String() string

func (*Node) Tags 

func (n *Node) Tags(ctx context.Context) ([]string, error)

func (*Node) Touch 

func (n *Node) Touch(ctx context.Context) error

func (*Node) Update 

func (n *Node) Update(ctx context.Context) error

func (*Node) Updated 

func (n *Node) Updated(ctx context.Context) (time.Time, error)

type NodeContent 

type NodeContent struct {
	// Hash is the stable content hash computed by the repository hasher.
	Hash string

	// Title is the canonical title for the content. For Markdown this is the
	// first H1; for RST it is the detected title.
	Title string

	// Lead is the first paragraph immediately following the title. It is used
	// as a short summary or preview of the content.
	Lead string

	// Links is the list of numeric outgoing node links discovered in the
	// content (for example "../42"). Entries are normalized NodeId values.
	Links []NodeId

	// Format is a short hint of the detected format. Typical values are
	// "markdown", "rst", or "empty".
	Format string

	// Body is the content body with Markdown frontmatter removed when present.
	// For non-Markdown formats this is the original file content.
	Body string

	// Frontmatter is the parsed YAML frontmatter when present. It is non-nil
	// only for Markdown documents that include a leading YAML block.
	Frontmatter map[string]any
}

NodeContent holds the extracted pieces of a node's primary content file (README.md or README.rst).

Fields:

  • Hash: stable content hash computed by the repository hasher.
  • Title: canonical title (first H1 for Markdown, or RST title detected).
  • Lead: first paragraph immediately following the title (used as a short summary).
  • Links: numeric outgoing node links discovered in the content (../N).
  • Format: short hint of the detected format ("markdown", "rst", or "empty").
  • Frontmatter: parsed YAML frontmatter when present (Markdown only).
  • Body: the raw body bytes of the content file with frontmatter removed for Markdown (or the original bytes for other formats), represented as a string.

func ParseContent 

func ParseContent(rt *toolkit.Runtime, data []byte, format string) (*NodeContent, error)

ParseContent extracts a NodeContent value from raw file bytes.

The format parameter is a filename hint (e.g., "README.md", "README.rst"). When format is ambiguous the function applies simple heuristics to choose between Markdown and reStructuredText. The returned NodeContent contains a deterministic, deduplicated, sorted list of discovered numeric links.

ParseContent uses the provided runtime hasher to compute content Hash. If the input is empty or only whitespace, a NodeContent with Format == "empty" is returned.

type NodeData 

type NodeData struct {
	// ID is the node identifier as a string (for example "42" or "42-0001").
	// Keep this lightweight while other fields are exposed via accessors.
	ID      NodeId
	Content *NodeContent
	Meta    *NodeMeta
	Stats   *NodeStats

	// Ancillary names (attachments and images). Implementations may populate these
	// from the repository.
	Items  []string
	Images []string
}

NodeData is a high-level representation of a KEG node. Implementations may compose this from repository pieces such as meta, content, and ancillary items.

func (*NodeData) Accessed 

func (n *NodeData) Accessed() time.Time

Accessed returns the accessed timestamp from stats when available.

func (*NodeData) ContentChanged 

func (n *NodeData) ContentChanged() bool

NodeContent has previously changed

func (*NodeData) ContentHash 

func (n *NodeData) ContentHash() string

ContentHash returns the content hash if content is present, otherwise the empty string.

func (*NodeData) Created 

func (n *NodeData) Created() time.Time

Created returns the created timestamp from stats when available.

func (*NodeData) Format 

func (n *NodeData) Format() string

Format returns the content format hint (for example "markdown" or "rst").

func (*NodeData) Lead 

func (n *NodeData) Lead() string

Lead returns the short lead/summary for the node. Prefer stats then content. 

func (n *NodeData) Links() []NodeId

Links returns the outgoing links discovered for the node. Prefer stats and fall back to parsed content links when stats are unavailable.

func (*NodeData) MetaHash 

func (n *NodeData) MetaHash() string

MetaHash returns the stored programmatic hash when available.

func (*NodeData) Ref 

func (n *NodeData) Ref() NodeIndexEntry

Ref builds a NodeIndexEntry from the NodeData. If the NodeData.ID is malformed ParseNode may fail and the function will fall back to a zero NodeId.

func (*NodeData) Tags 

func (n *NodeData) Tags() []string

Tags returns a copy of the normalized tag list from metadata or nil if not set.

func (*NodeData) Title 

func (n *NodeData) Title() string

Title returns the canonical title for the node. Prefer stats title and fall back to parsed content title when available.

func (*NodeData) Touch 

func (n *NodeData) Touch(ctx context.Context, now *time.Time)

func (*NodeData) UpdateMeta 

func (n *NodeData) UpdateMeta(ctx context.Context, now *time.Time) error

func (*NodeData) Updated 

func (n *NodeData) Updated() time.Time

Updated returns the updated timestamp from stats when available.

type NodeId 

type NodeId struct {
	ID    int
	Alias string
	// Code is an additional random identifier used to signify an uncommitted node.
	Code string
}

NodeId is the stable numeric identifier for a KEG node. The ID field is the canonical non-negative integer identifier. The optional Code field is a zero-padded 4-digit numeric suffix used to represent an uncommitted or temporary variant of the node.

func NewTempNode 

func NewTempNode(ctx context.Context, id string) *NodeId

NewTempNode creates a new NodeId using the provided base id string and a 4-digit numeric code. The function attempts to parse the base id via ParseNode; if that fails it will try to parse the string as a non-negative integer. If the id is empty or cannot be parsed as a non-negative integer the returned NodeId will have ID set to 0.

The Code is generated with crypto/rand when available and falls back to the current nanotime if random bytes cannot be obtained. The code is returned as a zero-padded 4-digit string.

The context parameter is accepted to allow future callers to pass context without changing the signature. It is not used by the current implementation.

func ParseNode 

func ParseNode(s string) (*NodeId, error)

ParseNode converts a string into a *NodeId.

Accepted forms:

  • "0" or a non-negative integer without leading zeros (for example "1", "23")

  • "<id>-<code>" where <id> follows the rules above and <code> is exactly 4 digits

  • "keg:<alias>/<id>" or "keg:<alias>/<id>-<code>" to include an alias.

Examples: 

"42"               -> &NodeId{ID:42, Code:""}, nil
"42-0001"          -> &NodeId{ID:42, Code:"0001"}, nil
"keg:work/23"      -> &NodeId{ID:23, Keg:"work"}, nil
"keg:work/23-0001" -> &NodeId{ID:23, Keg:"work", Code:"0001"}, nil
"0023"             -> nil, error (leading zeros not allowed)
""                 -> nil, error

func (NodeId) Compare 

func (n NodeId) Compare(other NodeId) int

Compare returns -1 if n < other, 1 if n > other, and 0 if they are equal.

func (NodeId) Equals 

func (n NodeId) Equals(other NodeId) bool

Equals reports whether two Nodes are identical in ID and Code.

func (NodeId) Gt 

func (n NodeId) Gt(other NodeId) bool

Gt reports whether n is strictly greater than other using ID then Code.

func (NodeId) Gte 

func (n NodeId) Gte(other NodeId) bool

Gte reports whether n is greater than or equal to other.

func (NodeId) Increment 

func (n NodeId) Increment() NodeId

Increment returns a new NodeId with the ID value increased by one while preserving the Code.

func (NodeId) Lt 

func (n NodeId) Lt(other NodeId) bool

Lt reports whether n is strictly less than other using ID then Code.

func (NodeId) Lte 

func (n NodeId) Lte(other NodeId) bool

Lte reports whether n is less than or equal to other.

func (NodeId) Path 

func (id NodeId) Path() string

Path returns the path component for this NodeId suitable for use in file names or URLs.

Examples: 

NodeId{ID:42, Code:""}      -> "42"
NodeId{ID:42, Code:"0001"}  -> "42-0001"
NodeId{ID:42, Keg:"work"} -> "keg:work/42"

func (NodeId) String 

func (id NodeId) String() string

func (NodeId) Valid 

func (id NodeId) Valid() bool

Valid reports whether the NodeId ID is a non-negative integer.

type NodeIndex 

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

NodeIndex is an in-memory index of node descriptors used to construct the `nodes.tsv` index artifact.

The index stores a slice of `NodeIndexEntry` values in a deterministic order (ascending by numeric node id, with codes used to break ties). It provides helpers to parse a serialized index, mutate the in-memory list, and produce the canonical serialized bytes.

Concurrency note: NodeIndex itself does not perform internal synchronization. Callers that require concurrent access should guard an instance with a mutex.

func ParseNodeIndex 

func ParseNodeIndex(ctx context.Context, data []byte) (NodeIndex, error)

ParseNodeIndex parses the serialized nodes index bytes into a NodeIndex.

Expected input is zero or more lines separated by newline. Each non-empty line represents a node entry in the canonical TSV format used by the repo. Parsers should tolerate empty input and skip malformed lines while continuing to parse the remainder. An empty input yields an empty NodeIndex and no error.

Parsing rules and leniency:

  • Each valid line is expected to contain at least the ID field. Additional columns (for example updated timestamp and title) are accepted when present.
  • Lines that cannot be parsed into a valid NodeIndexEntry are skipped and do not cause the entire parse to fail. This allows forward compatibility when new columns are added to the on-disk format.
  • The returned NodeIndex contains entries in the order they were parsed; it is the caller's responsibility to sort or normalize ordering if desired.

Returns:

  • a NodeIndex containing parsed NodeIndexEntry values.
  • a non nil error only for unexpected conditions preventing parsing of the entire input (for example severe encoding issues). Minor line-level parse problems are tolerated and do not cause an error.

Example input: 

"42\t2025-01-02T15:04:05Z\tMy Title\n0\t2024-12-01T12:00:00Z\tZero NodeId\n"

Note: the expected column order is: id<TAB>updated<TAB>title

func (*NodeIndex) Add 

func (idx *NodeIndex) Add(ctx context.Context, data *NodeData) error

Add inserts the provided node into the index. The index should remain sorted by ascending node id after the operation.

Behavior expectations:

  • If idx is nil the call is a no-op and returns nil.
  • The method should ensure idx.data is initialized when first used.
  • Adding an existing node id should be idempotent: the existing entry should be updated or replaced rather than producing duplicates.
  • The operation is in-memory only and does not perform I/O.

Typical callers: - Index builders that aggregate node metadata into the nodes index. - Tests that need to construct an in-memory nodes list.

Note: This method does not acquire any synchronization; callers should hold a lock if concurrent mutations are possible.

Implementation note: 

The function should insert or update the NodeIndexEntry derived from the
supplied NodeData. After modification, idx.data must be ordered so that
Next and serialized output are stable and deterministic.

func (*NodeIndex) Data 

func (idx *NodeIndex) Data(ctx context.Context) ([]byte, error)

Data serializes the NodeIndex into the canonical on-disk TSV representation.

Serialization rules:

  • Each entry produces a single line in the form used by the repository's nodes index. Common column order is: id<TAB>title<TAB>updated<LF>.
  • Entries must be emitted in ascending node id order.
  • An empty index returns an empty byte slice.

The returned bytes are owned by the caller and may be written atomically by the repository layer. The function should not modify idx.data.

Implementation note: 

The function should not rely on external state. It must produce stable,
deterministic output suitable for writing to an index file.

func (*NodeIndex) Get 

func (idx *NodeIndex) Get(ctx context.Context, node NodeId) *NodeIndexEntry

Get returns the NodeIndexEntry pointer for the provided node if present. The lookup uses node.Path() to match the ID field of entries.

Returns:

  • *NodeIndexEntry when the entry is present.
  • nil when the entry is not present or idx is nil.

The returned pointer points into the internal slice. Callers that need to modify the entry should copy it first to avoid data races.

func (*NodeIndex) List 

func (idx *NodeIndex) List(ctx context.Context) []NodeIndexEntry

List returns the in-memory slice of NodeIndexEntry. The returned slice is the underlying data and callers should not mutate it to avoid data races.

func (*NodeIndex) Next 

func (idx *NodeIndex) Next(ctx context.Context) NodeId

Next returns the next available NodeId id based on the current index contents.

Semantics:

  • If the index is empty, Next returns NodeId{ID:0, Code:""} (the zeroth id).
  • Otherwise Next returns a NodeId whose ID is one greater than the highest numeric ID present in the index. If entries contain code suffixes the numeric portion is used for ordering.
  • The function does not modify the index.

Implementation note: 

The function should examine idx.data to determine the maximal numeric id and
return the subsequent id. It should not allocate or write any external state.

func (*NodeIndex) Rm 

func (idx *NodeIndex) Rm(ctx context.Context, node NodeId) error

Rm removes the node identified by id from the index.

Behavior expectations: - If idx is nil the call is a no-op and returns nil. - If the node is not present the call should not error. - After removal the index slice should remain in a stable, sorted state. - This method only mutates in-memory state and does not perform I/O.

Typical callers: - Index maintenance routines that remove entries for deleted nodes. - Tests cleaning up expected state.

Implementation note: 

The function should locate the entry whose ID equals node.Path() and remove
it from the slice. The remaining slice should preserve deterministic order.

type NodeIndexEntry 

type NodeIndexEntry struct {
	ID      string    `json:"id" yaml:"id"`
	Title   string    `json:"title" yaml:"title"`
	Updated time.Time `json:"updated" yaml:"updated"`
}

NodeIndexEntry is a small descriptor for a node used by repository listings and indices. It contains the node id as a string, a human-friendly title, and the last updated timestamp.

type NodeMeta 

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

NodeMeta holds manually edited node metadata and helpers to read/update it.

Programmatic fields (title/hash/timestamps/lead/links) are represented by NodeStats. NodeMeta focuses on human-editable yaml data and comment-preserving writes.

func NewMeta 

func NewMeta(ctx context.Context, now time.Time) *NodeMeta

NewMeta constructs an empty NodeMeta.

func ParseMeta 

func ParseMeta(ctx context.Context, raw []byte) (*NodeMeta, error)

ParseMeta parses raw yaml bytes into NodeMeta. Empty input returns an empty NodeMeta.

func (*NodeMeta) AddTag 

func (m *NodeMeta) AddTag(tag string)

func (*NodeMeta) Get 

func (m *NodeMeta) Get(key string) (string, bool)

Get retrieves scalar metadata fields by key.

func (*NodeMeta) RmTag 

func (m *NodeMeta) RmTag(tag string)

func (*NodeMeta) Set 

func (m *NodeMeta) Set(ctx context.Context, key string, val any) error

Set updates known NodeMeta keys (tags) and preserves unknown keys in the yaml node when available.

func (*NodeMeta) SetAttrs 

func (m *NodeMeta) SetAttrs(ctx context.Context, attrs map[string]any) error

func (*NodeMeta) SetTags 

func (m *NodeMeta) SetTags(tags []string)

func (*NodeMeta) Tags 

func (m *NodeMeta) Tags() []string

func (*NodeMeta) ToYAML 

func (m *NodeMeta) ToYAML() string

ToYAML serializes only manually edited metadata fields.

func (*NodeMeta) ToYAMLWithStats 

func (m *NodeMeta) ToYAMLWithStats(stats *NodeStats) string

ToYAMLWithStats serializes metadata while optionally merging programmatic NodeStats fields into the emitted yaml.

type NodeStats 

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

NodeStats contains programmatic node data derived by tooling.

func NewStats 

func NewStats(now time.Time) *NodeStats

func ParseStats 

func ParseStats(ctx context.Context, raw []byte) (*NodeStats, error)

ParseStats extracts programmatic node stats from raw bytes. The canonical encoding is JSON; YAML is accepted as a compatibility fallback.

func (*NodeStats) AccessCount 

func (s *NodeStats) AccessCount() int

func (*NodeStats) Accessed 

func (s *NodeStats) Accessed() time.Time

func (*NodeStats) Created 

func (s *NodeStats) Created() time.Time

func (*NodeStats) EnsureTimes 

func (s *NodeStats) EnsureTimes(now time.Time)

func (*NodeStats) Hash 

func (s *NodeStats) Hash() string

func (*NodeStats) IncrementAccessCount 

func (s *NodeStats) IncrementAccessCount()

func (*NodeStats) Lead 

func (s *NodeStats) Lead() string
func (s *NodeStats) Links() []NodeId

func (*NodeStats) SetAccessCount 

func (s *NodeStats) SetAccessCount(count int)

func (*NodeStats) SetAccessed 

func (s *NodeStats) SetAccessed(t time.Time)

func (*NodeStats) SetCreated 

func (s *NodeStats) SetCreated(t time.Time)

func (*NodeStats) SetHash 

func (s *NodeStats) SetHash(hash string, now *time.Time)

func (*NodeStats) SetLead 

func (s *NodeStats) SetLead(lead string)
func (s *NodeStats) SetLinks(links []NodeId)

func (*NodeStats) SetTitle 

func (s *NodeStats) SetTitle(title string)

func (*NodeStats) SetUpdated 

func (s *NodeStats) SetUpdated(t time.Time)

func (*NodeStats) Title 

func (s *NodeStats) Title() string

func (*NodeStats) ToJSON 

func (s *NodeStats) ToJSON() ([]byte, error)

func (*NodeStats) UpdateFromContent 

func (s *NodeStats) UpdateFromContent(content *NodeContent, now *time.Time)

func (*NodeStats) Updated 

func (s *NodeStats) Updated() time.Time

type Option 

type Option func(*Keg)

Option is a functional option for configuring Keg behavior

type RateLimitError 

type RateLimitError struct {
	RetryAfter time.Duration // suggested wait time
	Message    string
	Cause      error
}

RateLimitError represents a throttling response that includes a suggested RetryAfter duration and an optional message. It is always considered retryable.

func (*RateLimitError) Error 

func (e *RateLimitError) Error() string

func (*RateLimitError) Retryable 

func (e *RateLimitError) Retryable() bool

func (*RateLimitError) Unwrap 

func (e *RateLimitError) Unwrap() error

type Repository 

type Repository interface {

	// Name returns a short, human-friendly backend identifier.
	Name() string

	// HasNode reports whether id exists as a node in the backend.
	// Missing nodes should return (false, nil). Backend/storage failures should
	// be returned as non-nil errors.
	HasNode(ctx context.Context, id NodeId) (bool, error)
	// Next returns the next available node id allocation candidate.
	// Implementations should honor ctx cancellation where applicable.
	Next(ctx context.Context) (NodeId, error)
	// ListNodes returns all node ids present in the backend.
	// Returned ids should be deterministic (stable ordering) when possible.
	ListNodes(ctx context.Context) ([]NodeId, error)
	// MoveNode renames or relocates a node from id to dst.
	// Implementations should return typed/sentinel errors when source is missing
	// or destination already exists.
	MoveNode(ctx context.Context, id NodeId, dst NodeId) error
	// DeleteNode removes the node and all associated persisted data.
	// If id does not exist, implementations should return a typed/sentinel
	// not-exist error.
	DeleteNode(ctx context.Context, id NodeId) error

	// WithNodeLock executes fn while holding an exclusive lock for node id.
	// Implementations should block until the lock is acquired or ctx is
	// canceled, and must release the lock after fn returns.
	WithNodeLock(ctx context.Context, id NodeId, fn func(context.Context) error) error
	// ReadContent reads the primary node content bytes (for example README.md).
	// Missing nodes should return a typed/sentinel not-exist error.
	ReadContent(ctx context.Context, id NodeId) ([]byte, error)
	// WriteContent writes primary node content bytes for id.
	// Implementations should perform atomic writes when possible.
	WriteContent(ctx context.Context, id NodeId, data []byte) error
	// ReadMeta reads raw node metadata bytes (for example meta.yaml).
	// Missing nodes should return a typed/sentinel not-exist error.
	ReadMeta(ctx context.Context, id NodeId) ([]byte, error)
	// WriteMeta writes raw node metadata bytes.
	// Implementations should preserve atomicity when possible.
	WriteMeta(ctx context.Context, id NodeId, data []byte) error
	// ReadStats returns parsed programmatic node stats for id.
	// Backends that persist stats inside meta.yaml should parse and return those
	// fields while preserving any manual metadata concerns at higher layers.
	ReadStats(ctx context.Context, id NodeId) (*NodeStats, error)
	// WriteStats writes programmatic node stats for id.
	// Implementations should preserve manually edited metadata fields when stats
	// and metadata share a storage representation.
	WriteStats(ctx context.Context, id NodeId, stats *NodeStats) error

	// GetIndex reads an index artifact by name (for example "nodes.tsv").
	// Callers should treat returned bytes as immutable.
	GetIndex(ctx context.Context, name string) ([]byte, error)
	// WriteIndex writes an index artifact by name.
	// Implementations should prefer atomic file replacement semantics.
	WriteIndex(ctx context.Context, name string, data []byte) error
	// ListIndexes returns available index artifact names.
	// Results should be deterministic when possible.
	ListIndexes(ctx context.Context) ([]string, error)
	// ClearIndexes removes or resets index artifacts in the backend.
	// This method should be idempotent and context-aware.
	ClearIndexes(ctx context.Context) error

	// ReadConfig reads repository-level keg configuration.
	// Missing config should return typed/sentinel not-exist errors.
	ReadConfig(ctx context.Context) (*Config, error)
	// WriteConfig persists repository-level keg configuration.
	// Implementations should perform atomic writes when possible.
	WriteConfig(ctx context.Context, config *Config) error
}

Repository is the storage backend contract used by KEG. Implementations are responsible for moving node data between storage and the service layer.

type RepositoryFiles 

type RepositoryFiles interface {
	// ListFiles lists file attachment names for a node.
	ListFiles(ctx context.Context, id NodeId) ([]string, error)
	// WriteFile stores a file attachment for a node.
	WriteFile(ctx context.Context, id NodeId, name string, data []byte) error
	// DeleteFile removes a file attachment from a node.
	DeleteFile(ctx context.Context, id NodeId, name string) error
}

RepositoryFiles provides optional per-node file attachment access.

type RepositoryImages 

type RepositoryImages interface {
	// ListImages lists image names for a node.
	ListImages(ctx context.Context, id NodeId) ([]string, error)
	// WriteImage stores an image payload for a node.
	WriteImage(ctx context.Context, id NodeId, name string, data []byte) error
	// DeleteImage removes an image from a node.
	DeleteImage(ctx context.Context, id NodeId, name string) error
}

RepositoryImages provides optional per-node image access.

type RepositorySnapshots 

type RepositorySnapshots interface {
	// AppendSnapshot appends a new revision with optimistic parent check.
	AppendSnapshot(ctx context.Context, id NodeId, in SnapshotWrite) (Snapshot, error)

	// GetSnapshot returns snapshot metadata and optional state payloads.
	// When opts.ResolveContent is true, returned content must be fully materialized.
	GetSnapshot(ctx context.Context, id NodeId, rev RevisionID, opts SnapshotReadOptions) (snap Snapshot, content []byte, meta []byte, stats *NodeStats, err error)

	// ListSnapshots returns revisions for a node in deterministic order.
	ListSnapshots(ctx context.Context, id NodeId) ([]Snapshot, error)

	// ReadContentAt reconstructs content at a specific revision.
	ReadContentAt(ctx context.Context, id NodeId, rev RevisionID) ([]byte, error)

	// RestoreSnapshot restores live node state to rev. Implementations may append
	// a restore snapshot when createRestoreSnapshot is true.
	RestoreSnapshot(ctx context.Context, id NodeId, rev RevisionID, createRestoreSnapshot bool) error
}

RepositorySnapshots provides revision-based history operations.

type RevisionID 

type RevisionID int64

type Snapshot 

type Snapshot struct {
	ID        RevisionID
	Node      NodeId
	Parent    RevisionID // 0 for root
	CreatedAt time.Time
	Message   string

	// Integrity + retrieval hints
	ContentHash  string
	MetaHash     string
	StatsHash    string
	IsCheckpoint bool // full content stored instead of patch
}

type SnapshotContentKind 

type SnapshotContentKind string

SnapshotContentKind describes how snapshot content bytes are stored. 

const (
	// SnapshotContentKindPatch stores content as a diff from a base revision.
	SnapshotContentKindPatch SnapshotContentKind = "patch"
	// SnapshotContentKindFull stores full reconstructed content bytes.
	SnapshotContentKindFull SnapshotContentKind = "full"
)

type SnapshotContentWrite 

type SnapshotContentWrite struct {
	Kind SnapshotContentKind
	Base RevisionID

	// Algorithm identifies the patch format, for example "xdiff-v1".
	Algorithm string
	Data      []byte

	// Hash is the digest of fully materialized content at this revision.
	Hash string
}

SnapshotContentWrite describes content payload for a new snapshot revision.

type SnapshotReadOptions 

type SnapshotReadOptions struct {
	// ResolveContent reconstructs full content bytes for the selected revision.
	ResolveContent bool
}

SnapshotReadOptions configures how snapshots are loaded.

type SnapshotWrite 

type SnapshotWrite struct {
	ExpectedParent RevisionID
	Message        string

	Meta  []byte
	Stats *NodeStats

	Content SnapshotContentWrite
}

SnapshotWrite describes append parameters for a new node snapshot.

type TagIndex 

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

TagIndex is an in-memory index mapping a normalized tag string to the list of nodes that declare that tag.

The index format (used by ParseTagIndex and Data) is line-oriented. Each line represents a tag and its node list in the form: 

<tag>\t<node1> <node2> ...\n

Where <nodeN> is the node.Path() string representation (for example "42" or "42-0001"). Parsers should tolerate empty input and skip empty lines. When serializing, the implementation should produce stable output by sorting tag keys and de-duplicating and sorting node lists.

Note: TagIndex does not perform internal synchronization. Callers that need concurrent access should guard the index with a mutex.

func ParseTagIndex 

func ParseTagIndex(ctx context.Context, data []byte) (TagIndex, error)

ParseTagIndex parses the serialized tag index bytes into a TagIndex.

Expected input is zero or more lines separated by newline. Each non-empty line must contain a tag, a tab, and a space-separated list of node ids. Invalid or malformed lines should be handled gracefully by ignoring the offending line and continuing parsing. An empty input yields an empty TagIndex and no error.

func (*TagIndex) Add 

func (idx *TagIndex) Add(ctx context.Context, data *NodeData) error

Add incorporates the node into the index for each tag present on the node.

Behavior notes: - If idx is nil this is a no-op. - The method should ensure idx.data is initialized when first used. - Duplicate entries for a given tag should be avoided (idempotent add). - The node should be added using node.Path() as the identifier.

func (*TagIndex) Data 

func (idx *TagIndex) Data(ctx context.Context) ([]byte, error)

Data serializes the TagIndex to the canonical byte representation described for ParseTagIndex.

Serialization requirements:

  • Tags (map keys) must be emitted in a stable, deterministic order. When a tag token can be parsed as a NodeId id it may be ordered numerically; otherwise fall back to lexicographic ordering.
  • NodeId lists for each tag must be de-duplicated and sorted by numeric id then by code (the same ordering ParseNode/NodeId.Compare implies).
  • Lines must use a single tab between tag and the node list, and a single space between node ids. Each line must be terminated with a newline.
  • If the index is empty return an empty byte slice and no error.

func (*TagIndex) Rm 

func (idx *TagIndex) Rm(ctx context.Context, node NodeId) error

Rm removes the node from all tag lists in the index.

Behavior notes:

  • If idx is nil this is a no-op.
  • If a tag has no remaining nodes after removal it should be removed from the map to avoid emitting empty tag lines when serialized.

type TransientError 

type TransientError struct {
	Cause error
}

TransientError marks a transient (retryable) failure, e.g. network timeout, DB deadlock. It implements both Temporary() and Retryable().

func (*TransientError) Error 

func (e *TransientError) Error() string

func (*TransientError) Retryable 

func (e *TransientError) Retryable() bool

func (*TransientError) Temporary 

func (e *TransientError) Temporary() bool

func (*TransientError) Unwrap 

func (e *TransientError) Unwrap() error

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.