sources

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2025 License: Apache-2.0 Imports: 22 Imported by: 0

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

View Source
const (
	// DefaultRegistryDataFile is the default file name for the registry data in Git sources
	DefaultRegistryDataFile = "registry.json"
)
View Source
const (
	// RegistryFileName is the name of the registry data file
	RegistryFileName = "registry.json"
)

Variables

This section is empty.

Functions

func EmptyJSON

func EmptyJSON(format string) []byte

EmptyJSON returns empty JSON object/array based on format

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

func (h *APISourceHandler) CurrentHash(ctx context.Context, cfg *config.Config) (string, error)

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) Delete

Delete removes the registry data file

func (*FileStorageManager) Get

Get retrieves and parses registry data from the JSON file

func (*FileStorageManager) Store

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

func (h *GitSourceHandler) CurrentHash(ctx context.Context, cfg *config.Config) (string, error)

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

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

func (h *ToolHiveAPIHandler) CurrentHash(ctx context.Context, cfg *config.Config) (string, error)

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

func (*ToolHiveAPIHandler) Validate

func (h *ToolHiveAPIHandler) Validate(ctx context.Context, endpoint string) error

Validate validates that the endpoint is a ToolHive registry

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

func (*UpstreamAPIHandler) CurrentHash(_ context.Context, _ *config.Config) (string, error)

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

func (*UpstreamAPIHandler) Validate

func (h *UpstreamAPIHandler) Validate(ctx context.Context, endpoint string) error

Validate validates that the endpoint is an upstream MCP Registry by checking /openapi.yaml for expected version and description

Directories

Path Synopsis
Package mocks is a generated GoMock package.
Package mocks is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL