plugins

Documentation

Overview

Package plugins provides clients for plugin repository APIs.

Index

• Constants
• func DownloadJAR(ctx context.Context, jarURL string, httpClient *http.Client) ([]byte, error)
• func SafeHTTPClient() *http.Client
• func ValidateDownloadURL(rawURL string) error
• type CachedPluginClient
  • func NewCachedPluginClient(client PluginClient, ttl time.Duration) *CachedPluginClient
  • func (c *CachedPluginClient) ClearCache()
  • func (c *CachedPluginClient) ClearProject(project string)
  • func (c *CachedPluginClient) GetCompatibility(ctx context.Context, project, version string) (CompatibilityInfo, error)
  • func (c *CachedPluginClient) GetVersions(ctx context.Context, project string) ([]PluginVersion, error)
• type CompatibilityInfo
• type HangarClient
  • func NewHangarClient() *HangarClient
  • func (c *HangarClient) GetCompatibility(ctx context.Context, project, version string) (CompatibilityInfo, error)
  • func (c *HangarClient) GetVersions(ctx context.Context, project string) ([]PluginVersion, error)
• type JARMetadata
  • func ParseJARMetadata(jarBytes []byte) (*JARMetadata, error)
• type PluginClient
• type PluginVersion

Constants

const (
	// MaxJARSize is the maximum JAR file size we will download for metadata extraction (100 MB).
	// Also used by the update controller to set curl --max-filesize.
	MaxJARSize = 100 * 1024 * 1024

	// MaxRedirects is the maximum number of HTTP redirects to follow.
	// Also used by the update controller to set curl --max-redirs.
	MaxRedirects = 10
)

Functions

func DownloadJAR

func DownloadJAR(ctx context.Context, jarURL string, httpClient *http.Client) ([]byte, error)

DownloadJAR downloads a JAR from the given URL and returns the raw bytes. Uses SafeHTTPClient if httpClient is nil. Note: the entire JAR (up to MaxJARSize) is held in memory. With concurrent URL plugin reconciliations, memory usage scales with num_plugins * jar_size.

func SafeHTTPClient

func SafeHTTPClient() *http.Client

SafeHTTPClient creates an HTTP client with timeout and SSRF protection. It blocks redirects to private/internal hosts to prevent SSRF via open redirect, while allowing cross-host redirects to public hosts (e.g., GitHub → CDN).

Known limitation: DNS rebinding attacks are not prevented. ValidateDownloadURL checks the hostname at URL parse time, but a malicious DNS record could resolve to a private IP at connection time. This is mitigated by the fact that modifying Plugin CRDs requires Kubernetes RBAC access.

func ValidateDownloadURL

func ValidateDownloadURL(rawURL string) error

ValidateDownloadURL checks that a URL is valid and safe for plugin downloads. Blocks non-HTTPS URLs, missing hosts, and private/internal network addresses. Note: This validates the hostname at parse time. DNS rebinding (where a hostname resolves to a private IP at connection time) is a known limitation.

Types

type CachedPluginClient

type CachedPluginClient struct {
	// contains filtered or unexported fields
}

CachedPluginClient wraps a PluginClient with in-memory caching.

func NewCachedPluginClient

func NewCachedPluginClient(client PluginClient, ttl time.Duration) *CachedPluginClient

NewCachedPluginClient creates a new caching wrapper around a PluginClient.

func (*CachedPluginClient) ClearCache

func (c *CachedPluginClient) ClearCache()

ClearCache removes all entries from the cache.

func (*CachedPluginClient) ClearProject

func (c *CachedPluginClient) ClearProject(project string)

ClearProject removes cache entries for a specific project.

func (*CachedPluginClient) GetCompatibility

func (c *CachedPluginClient) GetCompatibility(
	ctx context.Context,
	project,
	version string,
) (CompatibilityInfo, error)

GetCompatibility retrieves compatibility info from cache or fetches from the underlying client.

func (*CachedPluginClient) GetVersions

func (c *CachedPluginClient) GetVersions(ctx context.Context, project string) ([]PluginVersion, error)

GetVersions retrieves versions from cache or fetches from the underlying client.

type CompatibilityInfo

type CompatibilityInfo struct {
	// MinecraftVersions lists supported Minecraft versions.
	MinecraftVersions []string
	// PaperVersions lists supported Paper versions.
	PaperVersions []string
}

CompatibilityInfo contains compatibility information for a plugin version.

type HangarClient

type HangarClient struct {
	// contains filtered or unexported fields
}

HangarClient implements PluginClient using the go-hangar library.

func NewHangarClient

func NewHangarClient() *HangarClient

NewHangarClient creates a new Hangar API client.

func (*HangarClient) GetCompatibility

func (c *HangarClient) GetCompatibility(
	ctx context.Context,
	project,
	version string,
) (CompatibilityInfo, error)

GetCompatibility retrieves compatibility information for a specific version.

func (*HangarClient) GetVersions

func (c *HangarClient) GetVersions(ctx context.Context, project string) ([]PluginVersion, error)

GetVersions retrieves all available versions for a plugin from Hangar.

type JARMetadata

type JARMetadata struct {
	// Name is the plugin name from plugin.yml.
	Name string
	// Version is the plugin version string.
	Version string
	// APIVersion is the Minecraft API version (e.g. "1.21").
	APIVersion string
}

JARMetadata contains plugin metadata extracted from plugin.yml or paper-plugin.yml inside a JAR.

func ParseJARMetadata

func ParseJARMetadata(jarBytes []byte) (*JARMetadata, error)

ParseJARMetadata parses a JAR file (ZIP archive) and extracts plugin metadata from plugin.yml or paper-plugin.yml. The SHA256 field is NOT set by this function; callers should compute it separately if needed.

type PluginClient

type PluginClient interface {
	// GetVersions retrieves all available versions for a plugin.
	GetVersions(ctx context.Context, project string) ([]PluginVersion, error)

	// GetCompatibility retrieves compatibility information for a specific version.
	GetCompatibility(ctx context.Context, project, version string) (CompatibilityInfo, error)
}

PluginClient defines the interface for plugin repository clients.

type PluginVersion

type PluginVersion struct {
	// Version is the plugin version string.
	Version string
	// ReleaseDate is when this version was released.
	ReleaseDate time.Time
	// PaperVersions lists compatible Paper versions.
	PaperVersions []string
	// MinecraftVersions lists compatible Minecraft versions.
	MinecraftVersions []string
	// DownloadURL is the URL to download this version's JAR.
	DownloadURL string
	// Hash is the SHA256 hash of the JAR file.
	Hash string
}

PluginVersion contains metadata about a plugin version.