Documentation
¶
Overview ¶
Package httpapi implements the Scorecard-webapp GET contract over the orchestrator (design D1/D11): GET /projects/{host}/{org}/{repo} (+ ?commit=), /badge, /capabilities, /health, and /readyz. It uses the standard library's net/http with Go 1.22 method+wildcard routing — the same choice `scorecard serve` landed on — so the durable pieces can graft upstream.
Result bodies are canonical Scorecard JSON2, served verbatim. Provenance (source, resolved commit, date, version, completeness) is carried in response headers so the JSON2 body stays webapp-compatible for clients like scorecard-mcp (design D4/D12).
Status: not the deployment path ¶
This package is not what ships. The results API imported from ossf/scorecard-webapp (api/) implements the same contract and is the code already serving api.scorecard.dev, so re-hosting it is a lift-and-shift and it is the implementation that deploys (design W10).
This package is retained deliberately, not abandoned: it builds, its tests run, and internal/store's configurable-backend seam is the most likely shape of the eventual provider exit. But do not add new API surface here expecting it to ship. The decision is revisitable — see docs/upstream-graft.md — and the honest options at the next decision point are to converge this with api/ or to remove it, not to maintain it indefinitely as a study.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Capabilities ¶
type Capabilities struct {
// Mode is the sourcing model, "cached+live".
Mode string `json:"mode"`
// Checks describes the check coverage, "all".
Checks string `json:"checks"`
// Caveats are human-readable provenance notes clients should surface.
Caveats []string `json:"caveats"`
// LatestTTLSeconds is how long a latest result stays fresh.
LatestTTLSeconds int `json:"latest_ttl_seconds"`
// RequiresOptIn reports whether coverage needs publish_results (false here).
RequiresOptIn bool `json:"requires_opt_in"`
}
Capabilities advertises this server's mode, coverage, and caveats so clients (e.g. scorecard-mcp) report provenance from the server instead of assuming public-cache behavior (design D7). Field order favors pointer packing; JSON tags fix the wire shape.
func DefaultCapabilities ¶
func DefaultCapabilities(latestTTL time.Duration) Capabilities
DefaultCapabilities returns the capabilities of this hybrid server: it scans on demand, runs all checks against any accessible repository, requires no opt-in, and caches latest results with the given TTL.
func (Capabilities) WithFallback ¶
func (c Capabilities) WithFallback() Capabilities
WithFallback returns a copy of c advertising the upstream result fallback: it updates the mode and appends caveats describing the upstream's limits, so a client reports provenance accurately when a result is served from upstream (design F2/D7).
type Producer ¶
type Producer interface {
GetOrProduce(ctx context.Context, ref model.RepoRef, commit string) (*orchestrator.Outcome, error)
}
Producer is the orchestrator behavior the HTTP layer depends on.
type ServeConfig ¶
type ServeConfig struct {
Addr string
ReadHeaderTimeout time.Duration
ReadTimeout time.Duration
WriteTimeout time.Duration
IdleTimeout time.Duration
ShutdownTimeout time.Duration
}
ServeConfig configures the HTTP listener and its timeouts.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server serves the Scorecard API contract. Field order favors pointer packing (govet fieldalignment); the by-value caps sits last so its non-pointer tail does not split the pointer fields.
func New ¶
func New(producer Producer, caps Capabilities, opts ...Option) *Server
New builds a Server over the given producer and advertised capabilities.
func (*Server) ListenAndServe ¶
func (s *Server) ListenAndServe(ctx context.Context, cfg ServeConfig) error
ListenAndServe runs the HTTP server until ctx is cancelled (e.g. by a SIGINT/SIGTERM-derived context supplied by main), then shuts down gracefully within ShutdownTimeout. It returns nil on a clean shutdown.
Source Files