Documentation
¶
Overview ¶
Package sources provides interfaces and implementations for retrieving MCP registry data from various external sources.
The package defines the SourceHandler interface which abstracts the process of validating source configurations and fetching registry data from external sources such as HTTP endpoints, Git repositories, local files, or external registries.
Architecture:
- SourceHandler: Interface for fetching and validating registry data
- StorageManager: Interface for persisting registry data to local storage
- SourceDataValidator: Validates and parses registry data in different formats
- FetchResult: Strongly-typed result containing Registry instances with metadata
Current implementations:
- GitSourceHandler: Retrieves registry data from Git repositories Supports public repos via HTTPS with branch/tag/commit checkout
- APISourceHandler: Retrieves registry data from HTTP/HTTPS endpoints Delegates to format-specific handlers (ToolHiveAPIHandler, UpstreamAPIHandler)
- FileSourceHandler: Retrieves registry data from local filesystem Supports both absolute and relative file paths for development and production
- FileStorageManager: Persists Registry data to local file storage for serving
The package provides a factory pattern for creating appropriate source handlers based on the source type configuration, and uses strongly-typed Registry instances throughout for type safety.
Index ¶
- Constants
- func EmptyJSON(format string) []byte
- func InvalidJSON() []byte
- type APISourceHandler
- type DefaultSourceDataValidator
- type DefaultSourceHandlerFactory
- type EnvVarDetail
- type FetchResult
- type FileSourceHandler
- type FileStorageManager
- func (f *FileStorageManager) Delete(_ context.Context, _ *config.Config) error
- func (f *FileStorageManager) Get(_ context.Context, _ *config.Config) (*toolhivetypes.UpstreamRegistry, error)
- func (f *FileStorageManager) Store(_ context.Context, _ *config.Config, reg *toolhivetypes.UpstreamRegistry) error
- type GitSourceHandler
- type ListServersResponse
- type RegistryInfoResponse
- type ServerDetailResponse
- type ServerSummaryResponse
- type SourceDataValidator
- type SourceHandler
- type SourceHandlerFactory
- type StorageManager
- type TestRegistryBuilder
- func (b *TestRegistryBuilder) BuildJSON() []byte
- func (b *TestRegistryBuilder) BuildPrettyJSON() []byte
- func (b *TestRegistryBuilder) ContainerServerCount() int
- func (b *TestRegistryBuilder) Empty() *TestRegistryBuilder
- func (b *TestRegistryBuilder) GetRegistry() *toolhivetypes.Registry
- func (b *TestRegistryBuilder) GetUpstreamData() []upstreamv0.ServerResponse
- func (b *TestRegistryBuilder) RemoteServerCount() int
- func (b *TestRegistryBuilder) ServerCount() int
- func (b *TestRegistryBuilder) WithLastUpdated(timestamp string) *TestRegistryBuilder
- func (b *TestRegistryBuilder) WithRemoteServer(url string) *TestRegistryBuilder
- func (b *TestRegistryBuilder) WithRemoteServerName(name, url string) *TestRegistryBuilder
- func (b *TestRegistryBuilder) WithServer(name string) *TestRegistryBuilder
- func (b *TestRegistryBuilder) WithServerName(name string) *TestRegistryBuilder
- func (b *TestRegistryBuilder) WithVersion(version string) *TestRegistryBuilder
- type ToolHiveAPIHandler
- type UpstreamAPIHandler
Constants ¶
const (
// DefaultRegistryDataFile is the default file name for the registry data in Git sources
DefaultRegistryDataFile = "registry.json"
)
const (
// RegistryFileName is the name of the registry data file
RegistryFileName = "registry.json"
)
Variables ¶
This section is empty.
Functions ¶
func InvalidJSON ¶
func InvalidJSON() []byte
InvalidJSON returns intentionally malformed JSON for testing error cases
Types ¶
type APISourceHandler ¶
type APISourceHandler struct {
// contains filtered or unexported fields
}
APISourceHandler handles registry data from API endpoints It detects the format (ToolHive vs Upstream) and delegates to the appropriate handler
func NewAPISourceHandler ¶
func NewAPISourceHandler() *APISourceHandler
NewAPISourceHandler creates a new API source handler
func (*APISourceHandler) CurrentHash ¶
CurrentHash returns the current hash of the API response
func (*APISourceHandler) FetchRegistry ¶
func (h *APISourceHandler) FetchRegistry(ctx context.Context, cfg *config.Config) (*FetchResult, error)
FetchRegistry retrieves registry data from the API endpoint It auto-detects the format and delegates to the appropriate handler
func (*APISourceHandler) Validate ¶
func (*APISourceHandler) Validate(source *config.SourceConfig) error
Validate validates the API source configuration
type DefaultSourceDataValidator ¶
type DefaultSourceDataValidator struct{}
DefaultSourceDataValidator is the default implementation of SourceValidator
func (*DefaultSourceDataValidator) ValidateData ¶
func (*DefaultSourceDataValidator) ValidateData(data []byte, format string) (*toolhivetypes.UpstreamRegistry, error)
ValidateData validates raw data and returns a parsed UpstreamRegistry
type DefaultSourceHandlerFactory ¶
type DefaultSourceHandlerFactory struct{}
DefaultSourceHandlerFactory is the default implementation of SourceHandlerFactory
func (*DefaultSourceHandlerFactory) CreateHandler ¶
func (*DefaultSourceHandlerFactory) CreateHandler(sourceType string) (SourceHandler, error)
CreateHandler creates a source handler for the given source type
type EnvVarDetail ¶
type EnvVarDetail struct {
Name string `json:"name"`
Description string `json:"description"`
Required bool `json:"required"`
Default string `json:"default,omitempty"`
Secret bool `json:"secret,omitempty"`
}
EnvVarDetail represents detailed environment variable information
type FetchResult ¶
type FetchResult struct {
// Registry is the parsed registry data in unified UpstreamRegistry format
Registry *toolhivetypes.UpstreamRegistry
// Hash is the SHA256 hash of the serialized data for change detection
Hash string
// ServerCount is the number of servers found in the registry data
ServerCount int
// Format indicates the original format of the source data
Format string
}
FetchResult contains the result of a fetch operation
func NewFetchResult ¶
func NewFetchResult(reg *toolhivetypes.UpstreamRegistry, hash string, format string) *FetchResult
NewFetchResult creates a new FetchResult from a UpstreamRegistry instance and pre-calculated hash The hash should be calculated by the source handler to ensure consistency with CurrentHash
type FileSourceHandler ¶
type FileSourceHandler struct {
// contains filtered or unexported fields
}
FileSourceHandler handles registry data from local files
func NewFileSourceHandler ¶
func NewFileSourceHandler() *FileSourceHandler
NewFileSourceHandler creates a new file source handler
func (*FileSourceHandler) CurrentHash ¶
func (h *FileSourceHandler) CurrentHash(ctx context.Context, registryConfig *config.Config) (string, error)
CurrentHash returns the current hash of the file without performing a full parse
func (*FileSourceHandler) FetchRegistry ¶
func (h *FileSourceHandler) FetchRegistry(ctx context.Context, registryConfig *config.Config) (*FetchResult, error)
FetchRegistry retrieves registry data from the local file
func (*FileSourceHandler) Validate ¶
func (*FileSourceHandler) Validate(source *config.SourceConfig) error
Validate validates the file source configuration
type FileStorageManager ¶
type FileStorageManager struct {
// contains filtered or unexported fields
}
FileStorageManager implements StorageManager using local filesystem
func (*FileStorageManager) Get ¶
func (f *FileStorageManager) Get(_ context.Context, _ *config.Config) (*toolhivetypes.UpstreamRegistry, error)
Get retrieves and parses registry data from the JSON file
func (*FileStorageManager) Store ¶
func (f *FileStorageManager) Store(_ context.Context, _ *config.Config, reg *toolhivetypes.UpstreamRegistry) error
Store saves the registry data to a JSON file
type GitSourceHandler ¶
type GitSourceHandler struct {
// contains filtered or unexported fields
}
GitSourceHandler handles registry data from Git repositories
func NewGitSourceHandler ¶
func NewGitSourceHandler() *GitSourceHandler
NewGitSourceHandler creates a new Git source handler
func (*GitSourceHandler) CurrentHash ¶
CurrentHash returns the current hash of the source data after fetching the registry data
func (*GitSourceHandler) FetchRegistry ¶
func (h *GitSourceHandler) FetchRegistry(ctx context.Context, cfg *config.Config) (*FetchResult, error)
FetchRegistry retrieves registry data from the Git repository
func (*GitSourceHandler) Validate ¶
func (*GitSourceHandler) Validate(source *config.SourceConfig) error
Validate validates the Git source configuration
type ListServersResponse ¶
type ListServersResponse struct {
Servers []ServerSummaryResponse `json:"servers"`
Total int `json:"total"`
}
ListServersResponse represents the servers list response from /v0/servers
type RegistryInfoResponse ¶
type RegistryInfoResponse struct {
Version string `json:"version"`
LastUpdated string `json:"last_updated"`
Source string `json:"source"`
TotalServers int `json:"total_servers"`
}
RegistryInfoResponse represents the registry information response from /v0/info
type ServerDetailResponse ¶
type ServerDetailResponse struct {
Name string `json:"name"`
Description string `json:"description"`
Tier string `json:"tier"`
Status string `json:"status"`
Transport string `json:"transport"`
Tools []string `json:"tools"`
EnvVars []EnvVarDetail `json:"env_vars,omitempty"`
Permissions map[string]interface{} `json:"permissions,omitempty"`
Metadata map[string]interface{} `json:"metadata,omitempty"`
RepositoryURL string `json:"repository_url,omitempty"`
Tags []string `json:"tags,omitempty"`
Args []string `json:"args,omitempty"`
Volumes map[string]interface{} `json:"volumes,omitempty"`
Image string `json:"image,omitempty"`
}
ServerDetailResponse represents a server in detail API responses (full view)
type ServerSummaryResponse ¶
type ServerSummaryResponse struct {
Name string `json:"name"`
Description string `json:"description"`
Tier string `json:"tier"`
Status string `json:"status"`
Transport string `json:"transport"`
ToolsCount int `json:"tools_count"`
}
ServerSummaryResponse represents a server in list API responses (summary view)
type SourceDataValidator ¶
type SourceDataValidator interface {
// ValidateData validates raw data and returns a parsed UpstreamRegistry
ValidateData(data []byte, format string) (*toolhivetypes.UpstreamRegistry, error)
}
SourceDataValidator is an interface for validating registry source configurations
func NewSourceDataValidator ¶
func NewSourceDataValidator() SourceDataValidator
NewSourceDataValidator creates a new default source validator
type SourceHandler ¶
type SourceHandler interface {
// FetchRegistry retrieves data from the source and returns the result
FetchRegistry(ctx context.Context, cfg *config.Config) (*FetchResult, error)
// Validate validates the source configuration
Validate(source *config.SourceConfig) error
// CurrentHash returns the current hash of the source data without performing a full fetch
CurrentHash(ctx context.Context, cfg *config.Config) (string, error)
}
SourceHandler is an interface with methods to fetch data from external data sources
type SourceHandlerFactory ¶
type SourceHandlerFactory interface {
// CreateHandler creates a source handler for the given source type
CreateHandler(sourceType string) (SourceHandler, error)
}
SourceHandlerFactory creates source handlers based on source type
func NewSourceHandlerFactory ¶
func NewSourceHandlerFactory() SourceHandlerFactory
NewSourceHandlerFactory creates a new source handler factory
type StorageManager ¶
type StorageManager interface {
// Store saves a UpstreamRegistry instance to persistent storage
Store(ctx context.Context, cfg *config.Config, reg *toolhivetypes.UpstreamRegistry) error
// Get retrieves and parses registry data from persistent storage
Get(ctx context.Context, cfg *config.Config) (*toolhivetypes.UpstreamRegistry, error)
// Delete removes registry data from persistent storage
Delete(ctx context.Context, cfg *config.Config) error
}
StorageManager defines the interface for registry data persistence
func NewFileStorageManager ¶
func NewFileStorageManager(basePath string) StorageManager
NewFileStorageManager creates a new file-based storage manager
type TestRegistryBuilder ¶
type TestRegistryBuilder struct {
// contains filtered or unexported fields
}
TestRegistryBuilder provides a fluent interface for building test registry data
func NewTestRegistryBuilder ¶
func NewTestRegistryBuilder(format string) *TestRegistryBuilder
NewTestRegistryBuilder creates a new test registry builder for the specified format
func (*TestRegistryBuilder) BuildJSON ¶
func (b *TestRegistryBuilder) BuildJSON() []byte
BuildJSON returns the JSON representation of the built registry
func (*TestRegistryBuilder) BuildPrettyJSON ¶
func (b *TestRegistryBuilder) BuildPrettyJSON() []byte
BuildPrettyJSON returns the JSON representation with indentation for readability
func (*TestRegistryBuilder) ContainerServerCount ¶
func (b *TestRegistryBuilder) ContainerServerCount() int
ContainerServerCount returns the number of container servers only
func (*TestRegistryBuilder) Empty ¶
func (b *TestRegistryBuilder) Empty() *TestRegistryBuilder
Empty creates an empty registry with minimal required fields
func (*TestRegistryBuilder) GetRegistry ¶
func (b *TestRegistryBuilder) GetRegistry() *toolhivetypes.Registry
GetRegistry returns the built registry (for ToolHive format only)
func (*TestRegistryBuilder) GetUpstreamData ¶
func (b *TestRegistryBuilder) GetUpstreamData() []upstreamv0.ServerResponse
GetUpstreamData returns the built upstream data (for Upstream format only)
func (*TestRegistryBuilder) RemoteServerCount ¶
func (b *TestRegistryBuilder) RemoteServerCount() int
RemoteServerCount returns the number of remote servers only (ToolHive format only)
func (*TestRegistryBuilder) ServerCount ¶
func (b *TestRegistryBuilder) ServerCount() int
ServerCount returns the number of servers (both container and remote for ToolHive format)
func (*TestRegistryBuilder) WithLastUpdated ¶
func (b *TestRegistryBuilder) WithLastUpdated(timestamp string) *TestRegistryBuilder
WithLastUpdated sets a custom last updated timestamp (ToolHive format only)
func (*TestRegistryBuilder) WithRemoteServer ¶
func (b *TestRegistryBuilder) WithRemoteServer(url string) *TestRegistryBuilder
WithRemoteServer adds a remote server with the given URL (only for ToolHive format)
func (*TestRegistryBuilder) WithRemoteServerName ¶
func (b *TestRegistryBuilder) WithRemoteServerName(name, url string) *TestRegistryBuilder
WithRemoteServerName adds a remote server with a specific name and URL
func (*TestRegistryBuilder) WithServer ¶
func (b *TestRegistryBuilder) WithServer(name string) *TestRegistryBuilder
WithServer adds a container server with the given name and default valid values
func (*TestRegistryBuilder) WithServerName ¶
func (b *TestRegistryBuilder) WithServerName(name string) *TestRegistryBuilder
WithServerName adds a server with a specific name
func (*TestRegistryBuilder) WithVersion ¶
func (b *TestRegistryBuilder) WithVersion(version string) *TestRegistryBuilder
WithVersion sets a custom version (ToolHive format only)
type ToolHiveAPIHandler ¶
type ToolHiveAPIHandler struct {
// contains filtered or unexported fields
}
ToolHiveAPIHandler handles registry data from ToolHive Registry API endpoints API Format: /v0/servers (list), /v0/servers/{name} (detail), /v0/info (metadata)
func NewToolHiveAPIHandler ¶
func NewToolHiveAPIHandler(httpClient httpclient.Client) *ToolHiveAPIHandler
NewToolHiveAPIHandler creates a new ToolHive API handler
func (*ToolHiveAPIHandler) CurrentHash ¶
CurrentHash returns the current hash of the API response
func (*ToolHiveAPIHandler) FetchRegistry ¶
func (h *ToolHiveAPIHandler) FetchRegistry(ctx context.Context, registryConfig *config.Config) (*FetchResult, error)
FetchRegistry retrieves registry data from the ToolHive API endpoint
type UpstreamAPIHandler ¶
type UpstreamAPIHandler struct {
// contains filtered or unexported fields
}
UpstreamAPIHandler handles registry data from upstream MCP Registry API endpoints API Format: /v0/servers (paginated list), /v0/servers/{name}/versions, /openapi.yaml Phase 2 implementation - currently validates format but does not fetch data
func NewUpstreamAPIHandler ¶
func NewUpstreamAPIHandler(httpClient httpclient.Client) *UpstreamAPIHandler
NewUpstreamAPIHandler creates a new upstream MCP Registry API handler
func (*UpstreamAPIHandler) CurrentHash ¶
CurrentHash returns the current hash of the API response Phase 2: Not yet implemented
func (*UpstreamAPIHandler) FetchRegistry ¶
func (*UpstreamAPIHandler) FetchRegistry(_ context.Context, _ *config.Config) (*FetchResult, error)
FetchRegistry retrieves registry data from the upstream MCP Registry API endpoint Phase 2: Not yet implemented - will support pagination and format conversion