cooldown

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
}

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

• func ParseDuration(s string) (time.Duration, error)
• type Config
  • func (c *Config) Enabled() bool
  • func (c *Config) For(ecosystem, packagePURL string) time.Duration
  • func (c *Config) IsAllowed(ecosystem, packagePURL string, publishedAt time.Time) bool

Functions

func ParseDuration

func ParseDuration(s string) (time.Duration, error)

ParseDuration parses a duration string supporting days (e.g., "3d"), in addition to Go's standard time.ParseDuration formats ("48h", "30m"). "0" means disabled (returns 0).

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

func (c *Config) Enabled() bool

Enabled returns true if any cooldown is configured.

func (*Config) For

func (c *Config) For(ecosystem, packagePURL string) time.Duration

For returns the effective cooldown duration for a given ecosystem and package PURL. Resolution order: package override > ecosystem override > global default.

func (*Config) IsAllowed

func (c *Config) IsAllowed(ecosystem, packagePURL string, publishedAt time.Time) bool

IsAllowed returns true if a version with the given publish time has passed the cooldown period for this ecosystem/package.