Documentation
¶
Overview ¶
Package server implements the proxy HTTP server.
Package server provides the HTTP server and router for the proxy.
The server mounts protocol handlers at their respective paths:
- /npm/* - npm registry protocol
- /cargo/* - Cargo registry protocol (sparse index)
- /gem/* - RubyGems registry protocol
- /go/* - Go module proxy protocol
- /hex/* - Hex.pm registry protocol
- /pub/* - pub.dev registry protocol
- /pypi/* - PyPI registry protocol
- /maven/* - Maven repository protocol
- /gradle/* - Gradle HttpBuildCache protocol
- /nuget/* - NuGet V3 API protocol
- /composer/* - Composer/Packagist protocol
- /conan/* - Conan C/C++ protocol
- /conda/* - Conda/Anaconda protocol
- /cran/* - CRAN (R) protocol
- /julia/* - Julia Pkg server protocol
- /swift/* - Swift Package Registry protocol
- /v2/* - OCI/Docker container registry protocol
- /apk/* - Alpine APK repository protocol
- /debian/* - Debian/APT repository protocol
- /rpm/* - RPM/Yum repository protocol
Additional endpoints:
- /health - Health check endpoint
- /stats - Cache statistics (JSON)
- /openapi.json - OpenAPI spec (JSON)
- /metrics - Prometheus metrics
Web UI (HTML), mounted under /ui so reverse proxies can gate it separately from the package endpoints:
- /ui/ - Dashboard
- /ui/install - Client configuration guide
- /ui/packages - List all cached packages
- /ui/search - Search packages
- /ui/package/... - Package and version detail pages
- /ui/api/browse/... - Archive browsing (used by the UI)
- /ui/api/compare/... - Archive diffing (used by the UI)
API endpoints for enrichment data:
- GET /api/package/{ecosystem}/{name} - Package metadata
- GET /api/package/{ecosystem}/{name}/{version} - Version metadata with vulns
- GET /api/vulns/{ecosystem}/{name} - Package vulnerabilities
- GET /api/vulns/{ecosystem}/{name}/{version} - Version vulnerabilities
- POST /api/outdated - Check outdated packages
- POST /api/bulk - Bulk package lookup
- GET /api/packages - List cached packages (JSON)
Index ¶
- Constants
- func GetRequestID(ctx context.Context) string
- func RequestIDMiddleware(next http.Handler) http.Handler
- type APIHandler
- func (h *APIHandler) HandleBulkLookup(w http.ResponseWriter, r *http.Request)
- func (h *APIHandler) HandleOutdated(w http.ResponseWriter, r *http.Request)
- func (h *APIHandler) HandlePackagePath(w http.ResponseWriter, r *http.Request)
- func (h *APIHandler) HandlePackagesList(w http.ResponseWriter, r *http.Request)
- func (h *APIHandler) HandleSearch(w http.ResponseWriter, r *http.Request)
- func (h *APIHandler) HandleVulnsPath(w http.ResponseWriter, r *http.Request)
- type BrowseFileInfo
- type BrowseListResponse
- type BrowseSourceData
- type BuildInfo
- type BulkRequest
- type BulkResponse
- type ComparePageData
- type DBSearcher
- type DashboardData
- type DashboardStats
- type EnrichmentResponse
- type EnrichmentStatsView
- type ErrorResponse
- type HealthCheck
- type HealthResponse
- type Layout
- type MirrorAPIHandler
- type OutdatedPackage
- type OutdatedRequest
- type OutdatedResponse
- type OutdatedResult
- type PackageInfo
- type PackageListResult
- type PackageResponse
- type PackageShowData
- type PackagesListPageData
- type PackagesListResponse
- type RegistryConfig
- type SearchPackageResult
- type SearchPageData
- type SearchResponse
- type SearchResultItem
- type Server
- type StatsResponse
- type Templates
- type VersionResponse
- type VersionShowData
- type VulnResponse
- type VulnsResponse
Constants ¶
const ( ErrCodeBadRequest = "BAD_REQUEST" ErrCodeNotFound = "NOT_FOUND" ErrCodeUpstream = "UPSTREAM_ERROR" ErrCodeInternal = "INTERNAL_ERROR" )
Error codes returned in API error responses. These are stable identifiers that clients can match on; the message text is for humans and may change.
Variables ¶
This section is empty.
Functions ¶
func GetRequestID ¶
GetRequestID retrieves the request ID from context.
Types ¶
type APIHandler ¶
type APIHandler struct {
// contains filtered or unexported fields
}
APIHandler provides REST endpoints for package enrichment data.
func NewAPIHandler ¶
func NewAPIHandler(svc *enrichment.Service, db DBSearcher) *APIHandler
NewAPIHandler creates a new API handler with enrichment services.
func (*APIHandler) HandleBulkLookup ¶
func (h *APIHandler) HandleBulkLookup(w http.ResponseWriter, r *http.Request)
HandleBulkLookup handles POST /api/bulk @Summary Bulk package lookup by PURL @Tags api @Accept json @Produce json @Param request body BulkRequest true "PURLs" @Success 200 {object} BulkResponse @Failure 400 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Router /api/bulk [post]
func (*APIHandler) HandleOutdated ¶
func (h *APIHandler) HandleOutdated(w http.ResponseWriter, r *http.Request)
HandleOutdated handles POST /api/outdated @Summary Check outdated packages @Tags api @Accept json @Produce json @Param request body OutdatedRequest true "Packages to check" @Success 200 {object} OutdatedResponse @Failure 400 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Router /api/outdated [post]
func (*APIHandler) HandlePackagePath ¶
func (h *APIHandler) HandlePackagePath(w http.ResponseWriter, r *http.Request)
HandlePackagePath dispatches /api/package/{ecosystem}/* to the appropriate handler. Resolves namespaced package names (Composer vendor/name, npm @scope/name) from the path.
func (*APIHandler) HandlePackagesList ¶
func (h *APIHandler) HandlePackagesList(w http.ResponseWriter, r *http.Request)
HandlePackagesList handles GET /api/packages @Summary List cached packages @Tags api @Produce json @Param ecosystem query string false "Ecosystem" @Param sort query string false "Sort" Enums(hits,name,size,cached_at,ecosystem,vulns) @Success 200 {object} PackagesListResponse @Failure 400 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Router /api/packages [get]
func (*APIHandler) HandleSearch ¶
func (h *APIHandler) HandleSearch(w http.ResponseWriter, r *http.Request)
HandleSearch handles GET /api/search @Summary Search cached packages @Tags api @Produce json @Param q query string true "Query" @Param ecosystem query string false "Ecosystem" @Success 200 {object} SearchResponse @Failure 400 {object} ErrorResponse @Failure 500 {object} ErrorResponse @Router /api/search [get]
func (*APIHandler) HandleVulnsPath ¶
func (h *APIHandler) HandleVulnsPath(w http.ResponseWriter, r *http.Request)
HandleVulnsPath dispatches /api/vulns/{ecosystem}/* to the vulns handler. Supports both {name} and {name}/{version} paths with namespaced package names.
type BrowseFileInfo ¶
type BrowseFileInfo struct {
Path string `json:"path"`
Name string `json:"name"`
Size int64 `json:"size"`
IsDir bool `json:"is_dir"`
ModTime string `json:"mod_time,omitempty"`
}
BrowseFileInfo contains metadata about a file in an archives.
type BrowseListResponse ¶
type BrowseListResponse struct {
Path string `json:"path"`
Files []BrowseFileInfo `json:"files"`
}
BrowseListResponse contains the file listing for a directory in an archives.
type BrowseSourceData ¶
type BrowseSourceData struct {
Layout
Ecosystem string
PackageName string
Version string
EscapedVersion string
}
BrowseSourceData contains data for the browse source page.
Version is the decoded version, for display. EscapedVersion is the same value escaped as a single URL path segment and is what the links and the browse API calls must use; see database.Version.EscapedVersion.
type BulkRequest ¶
type BulkRequest struct {
PURLs []string `json:"purls"`
}
BulkRequest is the request body for bulk package lookups.
type BulkResponse ¶
type BulkResponse struct {
Packages map[string]*PackageResponse `json:"packages"`
}
BulkResponse contains bulk lookup results.
type ComparePageData ¶
type ComparePageData struct {
Layout
Ecosystem string
PackageName string
FromVersion string
ToVersion string
EscapedFromVersion string
EscapedToVersion string
}
ComparePageData contains data for the version comparison page.
FromVersion and ToVersion are decoded, for display; the Escaped variants are the path-segment form used to build the compare API URL.
type DBSearcher ¶
type DBSearcher interface {
SearchPackages(query string, ecosystem string, limit int, offset int) ([]database.SearchResult, error)
CountSearchResults(query string, ecosystem string) (int64, error)
ListCachedPackages(ecosystem string, sortBy string, limit int, offset int) ([]database.PackageListItem, error)
CountCachedPackages(ecosystem string) (int64, error)
}
DBSearcher defines the interface for database search operations.
type DashboardData ¶
type DashboardData struct {
Layout
Stats DashboardStats
EnrichmentStats EnrichmentStatsView
RecentPackages []PackageInfo
PopularPackages []PackageInfo
}
DashboardData contains data for rendering the dashboard.
type DashboardStats ¶
type DashboardStats struct {
CachedArtifacts int64
TotalSize string
TotalPackages int64
TotalVersions int64
}
DashboardStats contains cache statistics for the dashboard.
type EnrichmentResponse ¶
type EnrichmentResponse struct {
Package *PackageResponse `json:"package,omitempty"`
Version *VersionResponse `json:"version,omitempty"`
Vulnerabilities []VulnResponse `json:"vulnerabilities,omitempty"`
IsOutdated bool `json:"is_outdated"`
LicenseCategory string `json:"license_category"`
}
EnrichmentResponse contains full enrichment data.
type EnrichmentStatsView ¶
type EnrichmentStatsView struct {
EnrichedPackages int64
VulnSyncedPackages int64
TotalVulnerabilities int64
CriticalVulns int64
HighVulns int64
MediumVulns int64
LowVulns int64
HasVulns bool
}
EnrichmentStatsView contains enrichment statistics for display.
type ErrorResponse ¶ added in v0.3.2
ErrorResponse is the JSON body returned for API errors.
type HealthCheck ¶ added in v0.4.0
type HealthCheck struct {
Status string `json:"status"`
Error string `json:"error,omitempty"`
Step string `json:"step,omitempty"`
}
HealthCheck reports the status of a single subsystem check.
type HealthResponse ¶ added in v0.4.0
type HealthResponse struct {
Status string `json:"status"`
Checks map[string]HealthCheck `json:"checks"`
// CircuitBreakers reports the state ("open" or "closed") of each upstream
// registry's artifact-fetch circuit breaker, keyed by the host fetched from
// or, where the fetch URL has none to read, by an opaque placeholder
// standing in for it. It is omitted when no breaker has been created yet.
// An open breaker fails every artifact fetch it covers without contacting
// the upstream, but says nothing about this proxy's own health, so it does
// not change Status.
CircuitBreakers map[string]string `json:"circuit_breakers,omitempty"`
}
HealthResponse is the JSON payload returned by /health.
type Layout ¶ added in v0.5.0
Layout carries shared fields consumed by the base template. It is embedded in every page data struct so templates can access canonical URL and build information alongside the page's own fields.
type MirrorAPIHandler ¶
type MirrorAPIHandler struct {
// contains filtered or unexported fields
}
MirrorAPIHandler handles mirror API requests.
func NewMirrorAPIHandler ¶
func NewMirrorAPIHandler(jobs *mirror.JobStore) *MirrorAPIHandler
NewMirrorAPIHandler creates a new mirror API handler.
func (*MirrorAPIHandler) HandleCancel ¶
func (h *MirrorAPIHandler) HandleCancel(w http.ResponseWriter, r *http.Request)
HandleCancel cancels a running mirror job.
func (*MirrorAPIHandler) HandleCreate ¶
func (h *MirrorAPIHandler) HandleCreate(w http.ResponseWriter, r *http.Request)
HandleCreate starts a new mirror job.
func (*MirrorAPIHandler) HandleGet ¶
func (h *MirrorAPIHandler) HandleGet(w http.ResponseWriter, r *http.Request)
HandleGet returns the status of a mirror job.
type OutdatedPackage ¶
type OutdatedPackage struct {
Ecosystem string `json:"ecosystem"`
Name string `json:"name"`
Version string `json:"version"`
}
OutdatedPackage represents a package to check for outdatedness.
type OutdatedRequest ¶
type OutdatedRequest struct {
Packages []OutdatedPackage `json:"packages"`
}
OutdatedRequest is the request body for checking outdated packages.
type OutdatedResponse ¶
type OutdatedResponse struct {
Results []OutdatedResult `json:"results"`
}
OutdatedResponse contains outdated check results.
type OutdatedResult ¶
type OutdatedResult struct {
Ecosystem string `json:"ecosystem"`
Name string `json:"name"`
Version string `json:"version"`
LatestVersion string `json:"latest_version,omitempty"`
IsOutdated bool `json:"is_outdated"`
}
OutdatedResult contains the outdated status for a package.
type PackageInfo ¶
type PackageInfo struct {
Ecosystem string
Name string
Version string
Size string
Hits int64
CachedAt string
License string
LicenseCategory string
VulnCount int64
LatestVersion string
IsOutdated bool
}
PackageInfo contains information about a cached package.
type PackageListResult ¶
type PackageListResult struct {
Ecosystem string `json:"ecosystem"`
Name string `json:"name"`
LatestVersion string `json:"latest_version,omitempty"`
License string `json:"license,omitempty"`
LicenseCategory string `json:"license_category,omitempty"`
Hits int64 `json:"hits"`
Size int64 `json:"size"`
CachedAt string `json:"cached_at,omitempty"`
VulnCount int64 `json:"vuln_count"`
}
PackageListResult represents a single package in the list.
type PackageResponse ¶
type PackageResponse struct {
Ecosystem string `json:"ecosystem"`
Name string `json:"name"`
LatestVersion string `json:"latest_version,omitempty"`
License string `json:"license,omitempty"`
LicenseCategory string `json:"license_category,omitempty"`
Description string `json:"description,omitempty"`
Homepage string `json:"homepage,omitempty"`
Repository string `json:"repository,omitempty"`
RegistryURL string `json:"registry_url,omitempty"`
}
PackageResponse contains enriched package metadata.
type PackageShowData ¶
type PackageShowData struct {
Layout
Package *database.Package
Versions []database.Version
Vulnerabilities []database.Vulnerability
LicenseCategory string
}
PackageShowData contains data for rendering the package show page.
type PackagesListPageData ¶
type PackagesListPageData struct {
Layout
Ecosystem string
SortBy string
Results []SearchResultItem
Count int
Page int
PerPage int
TotalPages int
}
PackagesListPageData contains data for rendering the packages list page.
type PackagesListResponse ¶
type PackagesListResponse struct {
Results []PackageListResult `json:"results"`
Count int `json:"count"`
Total int64 `json:"total"`
Ecosystem string `json:"ecosystem,omitempty"`
SortBy string `json:"sort_by"`
Page int `json:"page"`
PerPage int `json:"per_page"`
}
PackagesListResponse contains a list of cached packages.
type RegistryConfig ¶
type RegistryConfig struct {
ID string
Name string
Language string
Endpoint string
Instructions template.HTML
}
RegistryConfig contains configuration instructions for a package registry.
type SearchPackageResult ¶
type SearchPackageResult struct {
Ecosystem string `json:"ecosystem"`
Name string `json:"name"`
LatestVersion string `json:"latest_version,omitempty"`
License string `json:"license,omitempty"`
Hits int64 `json:"hits"`
Size int64 `json:"size"`
CachedAt string `json:"cached_at,omitempty"`
}
SearchPackageResult represents a single search result.
type SearchPageData ¶
type SearchPageData struct {
Layout
Query string
Ecosystem string
Results []SearchResultItem
Count int
Page int
PerPage int
TotalPages int
}
SearchPageData contains data for rendering the search results page.
type SearchResponse ¶
type SearchResponse struct {
Results []SearchPackageResult `json:"results"`
Query string `json:"query"`
Count int `json:"count"`
}
SearchResponse contains search results.
type SearchResultItem ¶
type SearchResultItem struct {
Ecosystem string
Name string
LatestVersion string
License string
LicenseCategory string
Hits int64
Size int64
SizeFormatted string
CachedAt string
VulnCount int64
}
SearchResultItem represents a single search result for display.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the main proxy server.
func (*Server) LoggerMiddleware ¶
LoggerMiddleware logs HTTP requests with request ID correlation.
type StatsResponse ¶
type StatsResponse struct {
CachedArtifacts int64 `json:"cached_artifacts"`
TotalSize int64 `json:"total_size_bytes"`
TotalSizeHuman string `json:"total_size"`
StorageURL string `json:"storage_url"`
DatabasePath string `json:"database_path"`
}
StatsResponse contains cache statistics.
type Templates ¶
type Templates struct {
// contains filtered or unexported fields
}
Templates holds lazily-parsed templates for each page.
type VersionResponse ¶
type VersionResponse struct {
Ecosystem string `json:"ecosystem"`
Name string `json:"name"`
Version string `json:"version"`
License string `json:"license,omitempty"`
PublishedAt string `json:"published_at,omitempty"`
Integrity string `json:"integrity,omitempty"`
Yanked bool `json:"yanked"`
IsOutdated bool `json:"is_outdated"`
}
VersionResponse contains enriched version metadata.
type VersionShowData ¶
type VersionShowData struct {
Layout
Package *database.Package
Version *database.Version
Artifacts []database.Artifact
Vulnerabilities []database.Vulnerability
IsOutdated bool
LicenseCategory string
HasCachedArtifact bool
}
VersionShowData contains data for rendering the version show page.
type VulnResponse ¶
type VulnResponse struct {
ID string `json:"id"`
Summary string `json:"summary,omitempty"`
Severity string `json:"severity,omitempty"`
CVSSScore float64 `json:"cvss_score,omitempty"`
FixedVersion string `json:"fixed_version,omitempty"`
References []string `json:"references,omitempty"`
}
VulnResponse contains vulnerability information.
type VulnsResponse ¶
type VulnsResponse struct {
Ecosystem string `json:"ecosystem"`
Name string `json:"name"`
Version string `json:"version,omitempty"`
Vulnerabilities []VulnResponse `json:"vulnerabilities"`
Count int `json:"count"`
}
VulnsResponse contains vulnerabilities for a package/version.