Documentation
¶
Overview ¶
Package application provides the application interface for Starmap commands.
The Application interface defines the contract between the application layer and command implementations, enabling dependency injection and testability.
Design Principles:
- Accept interfaces, return structs (Go proverb)
- Define interfaces where they're used, not where they're implemented
- Keep interfaces small and focused
Usage in Commands:
import (
"context"
"github.com/agentstation/starmap/internal/application"
)
func NewCommand(app application.Application) *cobra.Command {
return &cobra.Command{
RunE: func(cmd *cobra.Command, args []string) error {
ctx := cmd.Context() // context.Context from cobra
catalog, err := app.Catalog()
if err != nil {
return err
}
// ... use catalog
return nil
},
}
}
Testing with Mocks:
mock := &application.Mock{
CatalogFunc: func() (*catalogs.Catalog, error) {
return testCatalog, nil
},
LoggerFunc: func() *zerolog.Logger {
logger := zerolog.Nop()
return &logger
},
}
cmd := NewCommand(mock)
// ... test command behavior
Index ¶
- type Application
- type Mock
- func (m *Mock) BuiltBy() string
- func (m *Mock) Catalog() (*catalogs.Catalog, error)
- func (m *Mock) CatalogState() (starmap.CatalogState, error)
- func (m *Mock) Commit() string
- func (m *Mock) Date() string
- func (m *Mock) Logger() *zerolog.Logger
- func (m *Mock) OperationalState(ctx context.Context) (catalogscheduler.OperationalState, error)
- func (m *Mock) OutputFormat() string
- func (m *Mock) Readiness() (starmap.CatalogReadiness, error)
- func (m *Mock) Starmap(opts ...starmap.Option) (*starmap.Client, error)
- func (m *Mock) Version() string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Application ¶
type Application interface {
// Catalog returns the immutable default catalog.
// This is a convenience method for commands that just need catalog access.
Catalog() (*catalogs.Catalog, error)
// CatalogState atomically returns the catalog and its generation identity.
CatalogState() (starmap.CatalogState, error)
// Readiness reports catalog availability and active embedded-bootstrap budgets.
Readiness() (starmap.CatalogReadiness, error)
// OperationalState composes generation, freshness, last-sync, and scheduler state.
OperationalState(context.Context) (catalogscheduler.OperationalState, error)
// Starmap returns the starmap instance with optional configuration.
// When called without options, returns the default cached instance (lazy-initialized, thread-safe).
// When called with options, creates a new instance with custom configuration (no caching).
//
// Examples:
// sm, err := app.Starmap() // default instance (cached)
// sm, err := app.Starmap(opt1, opt2) // custom instance (new)
Starmap(opts ...starmap.Option) (*starmap.Client, error)
// Logger returns the configured logger instance.
// Commands should use this for all logging operations.
Logger() *zerolog.Logger
// OutputFormat returns the configured output format (json, yaml, table, etc).
// Commands that support different output formats should use this.
OutputFormat() string
// Version returns the application version string.
Version() string
// Commit returns the git commit hash.
Commit() string
// Date returns the build date.
Date() string
// BuiltBy returns the build system identifier.
BuiltBy() string
}
Application provides the application interface that commands need. The App struct from cmd/starmap/app automatically implements this interface, providing dependency injection for commands while maintaining testability.
Commands should accept this interface rather than the concrete App type, allowing for easier testing with mock implementations.
Thread Safety: All methods must be safe for concurrent access.
type Mock ¶
type Mock struct {
CatalogFunc func() (*catalogs.Catalog, error)
CatalogStateFunc func() (starmap.CatalogState, error)
ReadinessFunc func() (starmap.CatalogReadiness, error)
OperationalStateFunc func(context.Context) (catalogscheduler.OperationalState, error)
StarmapFunc func(opts ...starmap.Option) (*starmap.Client, error)
LoggerFunc func() *zerolog.Logger
OutputFormatFunc func() string
VersionFunc func() string
CommitFunc func() string
DateFunc func() string
BuiltByFunc func() string
}
Mock provides a mock implementation of Application for testing. Each method can be customized by setting the corresponding function field. If a function field is nil, the method returns a default/zero value.
Example Usage:
mock := &application.Mock{
CatalogFunc: func() (*catalogs.Catalog, error) {
return testCatalog, nil
},
LoggerFunc: func() *zerolog.Logger {
logger := zerolog.Nop()
return &logger
},
}
cmd := list.NewCommand(mock)
// ... test command
func (*Mock) CatalogState ¶
func (m *Mock) CatalogState() (starmap.CatalogState, error)
CatalogState returns a configured atomic state or derives one from Catalog.
func (*Mock) OperationalState ¶
func (m *Mock) OperationalState(ctx context.Context) (catalogscheduler.OperationalState, error)
OperationalState returns configured operator state or an unconfigured default.
func (*Mock) OutputFormat ¶
OutputFormat returns output format using the mock function or "table".
func (*Mock) Readiness ¶
func (m *Mock) Readiness() (starmap.CatalogReadiness, error)
Readiness returns configured catalog readiness or a ready default.
Source Files