Documentation
¶
Overview ¶
Package source provides data source implementations for lvt-source blocks.
Package source provides data source implementations for lvt-source blocks.
Package source provides data source implementations for lvt-source blocks. Sources fetch data from external systems (exec, databases, APIs) and make it available to templates.
Index ¶
- func AddIDsToItems(content string) (string, bool)
- func EnsureUniqueIDs(content string) (string, bool)
- func ScanMarkdownForIDs(content string) []string
- func UserFriendlyMessage(err error) string
- func WithRetry(ctx context.Context, source string, cfg RetryConfig, fn RetryableFunc) ([]map[string]interface{}, error)
- type CSVFileSource
- type CacheInfoProvider
- type CachedSource
- type CachedWritableSource
- type CircuitBreaker
- type CircuitBreakerConfig
- type CircuitOpenError
- type CircuitState
- type ConflictError
- type ConnectionError
- type ExecSource
- type GraphQLError
- type GraphQLSource
- type HTTPError
- type JSONFileSource
- type MarkdownSource
- func (s *MarkdownSource) Close() error
- func (s *MarkdownSource) Fetch(ctx context.Context) ([]map[string]interface{}, error)
- func (s *MarkdownSource) GetAnchor() string
- func (s *MarkdownSource) GetFilePath() string
- func (s *MarkdownSource) IsReadonly() bool
- func (s *MarkdownSource) Name() string
- func (s *MarkdownSource) WriteItem(ctx context.Context, action string, data map[string]interface{}) error
- type MarkdownSourceParser
- type PostgresSource
- type Registry
- type RestSource
- type RetryConfig
- type RetryableFunc
- type SQLExecutor
- type SQLiteSource
- func (s *SQLiteSource) Close() error
- func (s *SQLiteSource) Exec(ctx context.Context, query string, args ...interface{}) (int64, error)
- func (s *SQLiteSource) Fetch(ctx context.Context) ([]map[string]interface{}, error)
- func (s *SQLiteSource) IsReadonly() bool
- func (s *SQLiteSource) Name() string
- func (s *SQLiteSource) WriteItem(ctx context.Context, action string, data map[string]interface{}) error
- type Source
- type SourceError
- type TimeoutError
- type UnsupportedSourceError
- type ValidationError
- type WritableSource
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddIDsToItems ¶
AddIDsToItems adds ID comments to items that don't have them
func EnsureUniqueIDs ¶
EnsureUniqueIDs checks for duplicate IDs and generates new ones if needed
func ScanMarkdownForIDs ¶
ScanMarkdownForIDs scans a markdown file and returns all item IDs found
func UserFriendlyMessage ¶
UserFriendlyMessage returns a user-friendly error message for templates
func WithRetry ¶
func WithRetry(ctx context.Context, source string, cfg RetryConfig, fn RetryableFunc) ([]map[string]interface{}, error)
WithRetry wraps a function with retry logic
Types ¶
type CSVFileSource ¶
type CSVFileSource struct {
// contains filtered or unexported fields
}
CSVFileSource reads data from a CSV file
func NewCSVFileSource ¶
func NewCSVFileSource(name, file, siteDir string, options map[string]string) (*CSVFileSource, error)
NewCSVFileSource creates a new CSV file source
func (*CSVFileSource) Close ¶
func (s *CSVFileSource) Close() error
Close is a no-op for file sources
func (*CSVFileSource) Fetch ¶
func (s *CSVFileSource) Fetch(ctx context.Context) ([]map[string]interface{}, error)
Fetch reads and parses the CSV file
func (*CSVFileSource) Name ¶
func (s *CSVFileSource) Name() string
Name returns the source identifier
type CacheInfoProvider ¶
CacheInfoProvider is implemented by sources that expose cache metadata
type CachedSource ¶
type CachedSource struct {
// contains filtered or unexported fields
}
CachedSource wraps a Source with caching behavior
func NewCachedSource ¶
func NewCachedSource(inner Source, c cache.Cache, cfg config.SourceConfig) *CachedSource
NewCachedSource creates a new cached source wrapper
func (*CachedSource) Close ¶
func (s *CachedSource) Close() error
Close closes the underlying source and cancels any background operations
func (*CachedSource) Fetch ¶
func (s *CachedSource) Fetch(ctx context.Context) ([]map[string]interface{}, error)
Fetch retrieves data, using cache if available
func (*CachedSource) GetCacheInfo ¶
func (s *CachedSource) GetCacheInfo() *cache.CacheInfo
GetCacheInfo returns cache metadata for UI display Implements CacheInfoProvider interface
func (*CachedSource) GetInner ¶
func (s *CachedSource) GetInner() Source
GetInner returns the underlying source This is useful for accessing WritableSource methods
func (*CachedSource) Invalidate ¶
func (s *CachedSource) Invalidate()
Invalidate removes this source's data from cache
type CachedWritableSource ¶
type CachedWritableSource struct {
*CachedSource
// contains filtered or unexported fields
}
CachedWritableSource wraps a WritableSource with caching behavior It invalidates the cache on write operations
func NewCachedWritableSource ¶
func NewCachedWritableSource(inner WritableSource, c cache.Cache, cfg config.SourceConfig) *CachedWritableSource
NewCachedWritableSource creates a new cached writable source wrapper
func (*CachedWritableSource) IsReadonly ¶
func (s *CachedWritableSource) IsReadonly() bool
IsReadonly returns whether the source is in read-only mode
type CircuitBreaker ¶
type CircuitBreaker struct {
// contains filtered or unexported fields
}
CircuitBreaker implements the circuit breaker pattern
func NewCircuitBreaker ¶
func NewCircuitBreaker(name string, config CircuitBreakerConfig) *CircuitBreaker
NewCircuitBreaker creates a new circuit breaker
func (*CircuitBreaker) Execute ¶
func (cb *CircuitBreaker) Execute(ctx context.Context, fn RetryableFunc) ([]map[string]interface{}, error)
Execute runs a function through the circuit breaker
func (*CircuitBreaker) Reset ¶
func (cb *CircuitBreaker) Reset()
Reset forces the circuit breaker to closed state
func (*CircuitBreaker) State ¶
func (cb *CircuitBreaker) State() CircuitState
State returns the current circuit state
type CircuitBreakerConfig ¶
type CircuitBreakerConfig struct {
FailureThreshold int // Number of failures to open circuit (default: 5)
SuccessThreshold int // Number of successes in half-open to close (default: 2)
Timeout time.Duration // Time to wait before half-open (default: 30s)
FailureWindow time.Duration // Window to count failures (default: 1 minute)
EnableLog bool // Whether to log state changes
}
CircuitBreakerConfig configures the circuit breaker
func DefaultCircuitBreakerConfig ¶
func DefaultCircuitBreakerConfig() CircuitBreakerConfig
DefaultCircuitBreakerConfig returns the default circuit breaker configuration
type CircuitOpenError ¶
type CircuitOpenError struct {
Source string
}
CircuitOpenError indicates the circuit breaker is open
func (*CircuitOpenError) Error ¶
func (e *CircuitOpenError) Error() string
type CircuitState ¶
type CircuitState int
CircuitState represents the state of a circuit breaker
const ( CircuitClosed CircuitState = iota // Normal operation, requests allowed CircuitOpen // Failures exceeded threshold, requests blocked CircuitHalfOpen // Testing if service recovered )
func (CircuitState) String ¶
func (s CircuitState) String() string
type ConflictError ¶
ConflictError is returned when a write operation detects concurrent modification
func (*ConflictError) Error ¶
func (e *ConflictError) Error() string
type ConnectionError ¶
ConnectionError represents a connection failure
func (*ConnectionError) Error ¶
func (e *ConnectionError) Error() string
func (*ConnectionError) Unwrap ¶
func (e *ConnectionError) Unwrap() error
type ExecSource ¶
type ExecSource struct {
// contains filtered or unexported fields
}
ExecSource runs a command and parses output as data
func NewExecSource ¶
func NewExecSource(name, cmd, siteDir string) (*ExecSource, error)
NewExecSource creates a new exec source (legacy constructor for backwards compatibility)
func NewExecSourceWithConfig ¶
func NewExecSourceWithConfig(name string, cfg config.SourceConfig, siteDir string) (*ExecSource, error)
NewExecSourceWithConfig creates a new exec source from config
func (*ExecSource) Fetch ¶
func (s *ExecSource) Fetch(ctx context.Context) ([]map[string]interface{}, error)
Fetch executes the command and parses output according to format
func (*ExecSource) FetchWithArgs ¶
func (s *ExecSource) FetchWithArgs(ctx context.Context, args map[string]string) ([]map[string]interface{}, error)
FetchWithArgs executes the command with custom argument values The args map contains argument name -> value pairs that override the defaults
type GraphQLError ¶
GraphQLError represents an error returned by a GraphQL API
func (*GraphQLError) Error ¶
func (e *GraphQLError) Error() string
type GraphQLSource ¶
type GraphQLSource struct {
// contains filtered or unexported fields
}
GraphQLSource fetches data from a GraphQL API endpoint
func NewGraphQLSource ¶
func NewGraphQLSource(name string, cfg config.SourceConfig, siteDir string) (*GraphQLSource, error)
NewGraphQLSource creates a new GraphQL API source
func (*GraphQLSource) Close ¶
func (s *GraphQLSource) Close() error
Close is a no-op for GraphQL sources
func (*GraphQLSource) Fetch ¶
func (s *GraphQLSource) Fetch(ctx context.Context) ([]map[string]interface{}, error)
Fetch makes a GraphQL request and parses the response
func (*GraphQLSource) Name ¶
func (s *GraphQLSource) Name() string
Name returns the source identifier
type HTTPError ¶
HTTPError represents an HTTP error response
func (*HTTPError) IsRetryable ¶
IsRetryable returns true for 5xx errors and 429 (rate limit)
type JSONFileSource ¶
type JSONFileSource struct {
// contains filtered or unexported fields
}
JSONFileSource reads data from a JSON file
func NewJSONFileSource ¶
func NewJSONFileSource(name, file, siteDir string) (*JSONFileSource, error)
NewJSONFileSource creates a new JSON file source
func (*JSONFileSource) Close ¶
func (s *JSONFileSource) Close() error
Close is a no-op for file sources
func (*JSONFileSource) Fetch ¶
func (s *JSONFileSource) Fetch(ctx context.Context) ([]map[string]interface{}, error)
Fetch reads and parses the JSON file
func (*JSONFileSource) Name ¶
func (s *JSONFileSource) Name() string
Name returns the source identifier
type MarkdownSource ¶
type MarkdownSource struct {
// contains filtered or unexported fields
}
MarkdownSource reads data from markdown sections (task lists, bullet lists, tables)
func NewMarkdownSource ¶
func NewMarkdownSource(name, file, anchor, siteDir, currentFile string, readonly bool) (*MarkdownSource, error)
NewMarkdownSource creates a new markdown source
func (*MarkdownSource) Close ¶
func (s *MarkdownSource) Close() error
Close is a no-op for file sources
func (*MarkdownSource) Fetch ¶
func (s *MarkdownSource) Fetch(ctx context.Context) ([]map[string]interface{}, error)
Fetch reads and parses the markdown section
func (*MarkdownSource) GetAnchor ¶
func (s *MarkdownSource) GetAnchor() string
GetAnchor returns the section anchor
func (*MarkdownSource) GetFilePath ¶
func (s *MarkdownSource) GetFilePath() string
GetFilePath returns the resolved file path for file watching
func (*MarkdownSource) IsReadonly ¶
func (s *MarkdownSource) IsReadonly() bool
IsReadonly returns whether the source is read-only
func (*MarkdownSource) Name ¶
func (s *MarkdownSource) Name() string
Name returns the source identifier
func (*MarkdownSource) WriteItem ¶
func (s *MarkdownSource) WriteItem(ctx context.Context, action string, data map[string]interface{}) error
WriteItem adds, updates, or deletes an item in the markdown source Supported actions: add, toggle, delete, update Returns ConflictError if the file was modified externally since last read
type MarkdownSourceParser ¶
type MarkdownSourceParser struct{}
MarkdownSourceParser provides utilities for parsing markdown data sections Used by the code generator to inline parsing logic
func (*MarkdownSourceParser) ParseContent ¶
func (p *MarkdownSourceParser) ParseContent(content, anchor string) ([]map[string]interface{}, error)
ParseContent parses markdown content and returns structured data
type PostgresSource ¶
type PostgresSource struct {
// contains filtered or unexported fields
}
PostgresSource executes queries against a PostgreSQL database
func NewPostgresSource ¶
func NewPostgresSource(name, query string, options map[string]string) (*PostgresSource, error)
NewPostgresSource creates a new PostgreSQL source
func NewPostgresSourceWithConfig ¶
func NewPostgresSourceWithConfig(name, query string, options map[string]string, cfg config.SourceConfig) (*PostgresSource, error)
NewPostgresSourceWithConfig creates a new PostgreSQL source with full configuration
func (*PostgresSource) Close ¶
func (s *PostgresSource) Close() error
Close releases the database connection
func (*PostgresSource) Fetch ¶
func (s *PostgresSource) Fetch(ctx context.Context) ([]map[string]interface{}, error)
Fetch executes the query and returns results with retry and circuit breaker
func (*PostgresSource) Name ¶
func (s *PostgresSource) Name() string
Name returns the source identifier
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds configured sources for a site
func NewRegistry ¶
NewRegistry creates a source registry from config
func NewRegistryWithFile ¶
NewRegistryWithFile creates a source registry with knowledge of the current markdown file This is needed for markdown sources that reference anchors in the current file
func (*Registry) InvalidateAllCaches ¶
func (r *Registry) InvalidateAllCaches()
InvalidateAllCaches invalidates all cached data
func (*Registry) InvalidateCache ¶
InvalidateCache invalidates the cache for a specific source
type RestSource ¶
type RestSource struct {
// contains filtered or unexported fields
}
RestSource fetches data from a REST API endpoint
func NewRestSource ¶
func NewRestSource(name, apiURL string, options map[string]string) (*RestSource, error)
NewRestSource creates a new REST API source (legacy, uses URL directly)
func NewRestSourceWithConfig ¶
func NewRestSourceWithConfig(name string, cfg config.SourceConfig) (*RestSource, error)
NewRestSourceWithConfig creates a new REST API source with full configuration
func (*RestSource) Fetch ¶
func (s *RestSource) Fetch(ctx context.Context) ([]map[string]interface{}, error)
Fetch makes an HTTP request and parses JSON response with retry and circuit breaker
func (*RestSource) String ¶
func (s *RestSource) String() string
String returns a debug representation with masked sensitive headers
type RetryConfig ¶
type RetryConfig struct {
MaxRetries int // Maximum number of retry attempts (default: 3)
BaseDelay time.Duration // Initial delay between retries (default: 100ms)
MaxDelay time.Duration // Maximum delay between retries (default: 5s)
Multiplier float64 // Delay multiplier for exponential backoff (default: 2.0)
EnableLog bool // Whether to log retry attempts
}
RetryConfig configures retry behavior
func DefaultRetryConfig ¶
func DefaultRetryConfig() RetryConfig
DefaultRetryConfig returns the default retry configuration
type RetryableFunc ¶
RetryableFunc is a function that can be retried
type SQLExecutor ¶
type SQLExecutor interface {
Source
// Exec executes a SQL statement with the given arguments.
// Returns the number of rows affected.
Exec(ctx context.Context, query string, args ...interface{}) (int64, error)
}
SQLExecutor extends Source with ability to execute arbitrary SQL statements. This is used by custom actions defined in frontmatter (action kind: "sql").
type SQLiteSource ¶
type SQLiteSource struct {
// contains filtered or unexported fields
}
SQLiteSource provides read/write access to SQLite tables. It implements WritableSource for Add, Update, Delete operations.
func NewSQLiteSource ¶
func NewSQLiteSource(name, dbPath, table, siteDir string, readonly bool) (*SQLiteSource, error)
NewSQLiteSource creates a new SQLite source
func (*SQLiteSource) Close ¶
func (s *SQLiteSource) Close() error
Close releases the database connection
func (*SQLiteSource) Exec ¶
Exec executes a SQL statement with the given arguments. This implements the SQLExecutor interface for custom action support. Returns the number of rows affected.
func (*SQLiteSource) Fetch ¶
func (s *SQLiteSource) Fetch(ctx context.Context) ([]map[string]interface{}, error)
Fetch retrieves all records from the table
func (*SQLiteSource) IsReadonly ¶
func (s *SQLiteSource) IsReadonly() bool
IsReadonly returns whether the source is read-only
type Source ¶
type Source interface {
// Name returns the source identifier
Name() string
// Fetch retrieves data from the source.
// Returns a slice of maps suitable for template iteration.
Fetch(ctx context.Context) ([]map[string]interface{}, error)
// Close releases any resources held by the source
Close() error
}
Source is the interface for data providers. Implementations fetch data from various backends (exec, pg, rest, etc.)
type SourceError ¶
type SourceError struct {
Source string // Source name (e.g., "users")
Operation string // Operation that failed (e.g., "fetch", "connect")
Err error // Underlying error
Retryable bool // Whether this error is retryable
}
SourceError wraps errors with source context
func NewSourceError ¶
func NewSourceError(source, operation string, err error) *SourceError
NewSourceError creates a SourceError with retryable detection
func (*SourceError) Error ¶
func (e *SourceError) Error() string
func (*SourceError) IsRetryable ¶
func (e *SourceError) IsRetryable() bool
IsRetryable returns true if the error is retryable
func (*SourceError) Unwrap ¶
func (e *SourceError) Unwrap() error
type TimeoutError ¶
TimeoutError represents a timeout
func (*TimeoutError) Error ¶
func (e *TimeoutError) Error() string
type UnsupportedSourceError ¶
type UnsupportedSourceError struct {
Type string
}
UnsupportedSourceError is returned for unknown source types
func (*UnsupportedSourceError) Error ¶
func (e *UnsupportedSourceError) Error() string
type ValidationError ¶
ValidationError represents invalid data or configuration
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
type WritableSource ¶
type WritableSource interface {
Source
// WriteItem performs a write operation on the source.
// action is one of: "add", "toggle", "delete", "update"
// data contains the item data (e.g., form fields, id for delete)
WriteItem(ctx context.Context, action string, data map[string]interface{}) error
// IsReadonly returns whether the source is in read-only mode
IsReadonly() bool
}
WritableSource extends Source with write capability. Sources like markdown and sqlite implement this to support Add, Update, Delete actions.
Source Files