remotecache

Documentation

Index

• func CacheKey(remoteURL string) string
• func IsRemoteURL(s string) bool
• func MatchesRemotePattern(rawURL, pattern string) bool
• func ValidateRemoteName(name string) error
• func ValidateRemoteURL(rawURL string) error
• func ValidateRemoteURLWithPatterns(rawURL string, patterns []string) error
• type Cache
  • func DefaultCache() (*Cache, error)
  • func (c *Cache) Ensure(ctx context.Context, remoteURL string) (string, error)
  • func (c *Cache) Evict(remoteURL string) error
  • func (c *Cache) OpenStore(ctx context.Context, remoteURL string, opener StoreOpener) (storage.DoltStorage, error)
  • func (c *Cache) Push(ctx context.Context, remoteURL string) error
• type CacheMeta
• type StoreOpener

Functions

func CacheKey

func CacheKey(remoteURL string) string

CacheKey returns a filesystem-safe identifier for a remote URL. It uses the first 16 hex characters (64 bits) of the SHA-256 hash. Birthday-bound collision risk is negligible for a local cache: 50% at ~4.3 billion entries, well beyond any realistic number of remotes.

func IsRemoteURL

func IsRemoteURL(s string) bool

IsRemoteURL returns true if s looks like a dolt remote URL rather than a local filesystem path. Recognized schemes: dolthub://, https://, http://, s3://, gs://, az://, file://, ssh://, git+ssh://, git+https://, and SCP-style git@host:path.

func MatchesRemotePattern

func MatchesRemotePattern(rawURL, pattern string) bool

MatchesRemotePattern checks whether a URL matches a glob-style pattern. Patterns use path.Match semantics (e.g., "dolthub://myorg/*").

func ValidateRemoteName

func ValidateRemoteName(name string) error

ValidateRemoteName checks that a remote name is safe for use as a Dolt remote identifier. Names must start with a letter and contain only alphanumeric characters, hyphens, and underscores. Max 64 characters.

func ValidateRemoteURL

func ValidateRemoteURL(rawURL string) error

ValidateRemoteURL performs strict security validation on a remote URL. It rejects URLs containing control characters (including null bytes), validates structural correctness per scheme, and rejects leading dashes that could be interpreted as CLI flags.

This is a security boundary — all remote URLs should pass through this before reaching exec.Command arguments or SQL parameters.

func ValidateRemoteURLWithPatterns

func ValidateRemoteURLWithPatterns(rawURL string, patterns []string) error

ValidateRemoteURLWithPatterns validates a URL and optionally checks it against an allowlist of glob patterns. If patterns is empty, only structural validation is performed.

Types

type Cache

type Cache struct {
	Dir      string        // e.g., ~/.cache/beads/remotes
	FreshFor time.Duration // skip pull if last pull was within this duration; 0 means always pull
}

Cache manages local clones of remote Dolt databases. Each remote URL maps to a directory under Dir named by CacheKey(url).

func DefaultCache

func DefaultCache() (*Cache, error)

DefaultCache returns a Cache using the XDG-conventional cache directory.

func (*Cache) Ensure

func (c *Cache) Ensure(ctx context.Context, remoteURL string) (string, error)

Ensure clones the remote if not cached (cold start), or pulls if already cached (warm start). Returns the cache entry directory path.

Auth credentials are inherited from environment variables: DOLT_REMOTE_USER, DOLT_REMOTE_PASSWORD, or DoltHub credentials configured via `dolt creds`.

func (*Cache) Evict

func (c *Cache) Evict(remoteURL string) error

Evict removes a cached remote clone entirely.

func (*Cache) OpenStore

func (c *Cache) OpenStore(ctx context.Context, remoteURL string, opener StoreOpener) (storage.DoltStorage, error)

OpenStore opens a DoltStorage from the cached clone using the provided StoreOpener. The cache entry directory is used as the beads directory. The caller is responsible for calling Close() on the returned store.

Note: OpenStore does not acquire a cache lock. The caller must ensure no concurrent Ensure() or Push() is running against the same remoteURL, as those modify the underlying dolt database. This is safe for single- process CLI use but not for concurrent multi-process access.

func (*Cache) Push

func (c *Cache) Push(ctx context.Context, remoteURL string) error

Push pushes local commits in the cached clone back to the remote.

type CacheMeta

type CacheMeta struct {
	RemoteURL string `json:"remote_url"`
	LastPull  int64  `json:"last_pull_ns"`
	LastPush  int64  `json:"last_push_ns"`
}

CacheMeta stores metadata about a cached remote clone.

type StoreOpener

type StoreOpener func(ctx context.Context, beadsDir string) (storage.DoltStorage, error)

StoreOpener is a function that opens a DoltStorage from a beads directory. This is injected by the cmd layer to abstract over build-tag-specific store construction (embedded vs server).