README
¶
cooldown
A small, ecosystem-agnostic version-age filter for package-manager tools. Hides versions published too recently so the community has time to spot malicious releases before they're pulled into projects.
Cross-ecosystem by construction: the same Config shape covers npm, PyPI, Cargo, RubyGems, Composer, Conda, Hex, NuGet, Pub, and any future ecosystem. Resolution order is package-PURL > ecosystem-name > global default, so a single config can express a strict default with targeted opt-outs.
Install
go get github.com/git-pkgs/cooldown
Usage
cfg := &cooldown.Config{
Default: "48h", // global window
Ecosystems: map[string]string{"npm": "72h"}, // npm gets longer
Packages: map[string]string{ // per-PURL override
"pkg:npm/htmx.org": "0", // 0 = disabled
},
}
if cfg.IsAllowed("npm", "pkg:npm/lodash", publishedAt) {
// version cleared the window; use it
}
decision := cfg.Evaluate("npm", "pkg:npm/lodash", publishedAt, evaluatedAt)
if !decision.Allowed {
fmt.Printf("available at %s (%s)\n", decision.AvailableAt, decision.Reason)
}
Config.Evaluate accepts an explicit evaluation time and returns the selected cooldown, availability time, and a typed reason. Versions without a publication time remain allowed and return ReasonUnknownPublicationTime. Config.IsAllowed is the current-time shorthand. Config.For(ecosystem, purl) returns the effective duration; useful when surfacing the policy to a UI. Config.Enabled() reports whether any cooldown is configured (cheap check before walking a large version set).
Duration strings accept Go's standard formats (48h, 30m, 1h30m) plus a d suffix for days (3d). 0 disables the window.
Why standalone
Originally lived inside an HTTP proxy that filtered registry responses; spotted as a reusable shape and lifted out. The same predicate is useful for package-manager CLIs, dependency-update bots, security scanners, and anything else that walks a version set with an age constraint.
License
MIT
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
// Default is the global default cooldown duration (e.g., "3d", "48h").
Default string `json:"default" yaml:"default"`
// Ecosystems overrides the default for specific ecosystems.
// Keys are ecosystem names (e.g., "npm", "pypi").
Ecosystems map[string]string `json:"ecosystems" yaml:"ecosystems"`
// Packages overrides the cooldown for specific packages.
// Keys are PURLs (e.g., "pkg:npm/lodash", "pkg:npm/@babel/core").
Packages map[string]string `json:"packages" yaml:"packages"`
// contains filtered or unexported fields
}
Config holds cooldown settings for version filtering. Cooldown hides package versions published too recently, giving the community time to spot malicious releases before they're pulled into projects.
func (*Config) Evaluate ¶ added in v0.2.0
func (c *Config) Evaluate(ecosystem, packagePURL string, publishedAt, evaluatedAt time.Time) Decision
Evaluate returns the cooldown decision for a version at evaluatedAt. AvailableAt is zero when the publication time is unknown. Otherwise, it is the publication time plus the selected cooldown, including when the cooldown is disabled.
type Reason ¶ added in v0.2.0
type Reason string
Reason explains why a package version is allowed or blocked.
const ( // ReasonDisabled means the selected cooldown duration is zero. ReasonDisabled Reason = "disabled" // ReasonElapsed means the package version has passed its cooldown period. ReasonElapsed Reason = "elapsed" // ReasonWaiting means the package version is still in its cooldown period. ReasonWaiting Reason = "waiting" // ReasonUnknownPublicationTime means the package version has no publication // time and is allowed by the default permissive policy. ReasonUnknownPublicationTime Reason = "unknown-publication-time" )
Source Files