preflight

package
v0.4.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 12, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package preflight builds a cost-preview Plan for an xray run without performing the run. It is consumed by `xray check` to surface the expected wall-clock, disk, and API budget before the customer commits to an extraction.

All probing is read-only: GraphQL count aggregates and metadata fields (diskUsage, pullRequests.totalCount) that mutate nothing.

Index

Constants

View Source
const (
	// APICallsPerRepoBase is the cheap-overhead per repo: branch list,
	// branch_protection, languages, releases, codeowners, harness probe,
	// file_metrics summary. Roughly one paged call per endpoint.
	APICallsPerRepoBase = 40

	// APICallsPerPR is the average GraphQL+enrich load per PR: list page
	// share, reviews + comments + review_threads pagination, defects
	// enrich, merge-method fetch. Empirical median across the seed
	// engagements ~ 2.
	APICallsPerPR = 2

	// APICallsPerCommit is the per-commit enrich cost (batched, so this
	// is fractional in practice).
	APICallsPerCommit = 1

	// CloneBytesPerKBDiskUsage converts GitHub's diskUsage (KB) to a
	// clone-size estimate in bytes. diskUsage is the on-disk size of the
	// bare repository on GitHub's storage, which is typically a tight
	// upper bound for the bare clone xray performs (`git clone --bare`).
	CloneBytesPerKBDiskUsage = 1024

	// SecondsPerAPICall is the connector-side wall-clock budget per API
	// call, averaged across the GraphQL primary-rate ceiling, retry
	// jitter, and parallelism. Calibrated against the v0.1 baseline
	// (~3.5k calls / 7 min wall-clock on 5 workers).
	SecondsPerAPICall = 0.04

	// SecondsPerGBClone covers the clone phase: network bandwidth +
	// local disk write. Assumes a 200 Mbit/s effective downstream.
	SecondsPerGBClone = 40

	// MinimumWallClockSeconds is the floor — a "trivial" plan (one tiny
	// repo, one connector) still has fixed overhead.
	MinimumWallClockSeconds = 30
)

Calibration constants for the cost preview. These are deliberate over-estimates so the preview never under-promises wall-clock to a nervous customer. Refined empirically as the connectors stabilise.

Variables

This section is empty.

Functions

func FormatBytes

func FormatBytes(n int64) string

FormatBytes renders a byte count using 1024-based units with the matching binary unit labels (KiB / MiB / GiB) so the cost-preview's number and the post-run summary's artifact-size both compute and label the same way. Customers see one consistent format across both commands instead of "500 MB" in check and "476.8 MiB" in summary.

Types

type InaccessibleEndpoint

type InaccessibleEndpoint struct {
	Repo     string
	Endpoint string
	Reason   string
}

InaccessibleEndpoint records a permission-gated endpoint discovered to be inaccessible during preflight. Surfaced upfront so the customer can fix scope before starting the full run.

type Plan

type Plan struct {
	Repos         int
	Teams         int
	WindowStart   time.Time
	WindowEnd     time.Time
	WindowDays    int
	Connectors    []string
	CloneBytes    int64
	APICalls      int
	WallClockSecs int
}

Plan is the cost-preview output for a configured run.

func BuildPlan

func BuildPlan(cfg *config.Config, stats []RepoStat) Plan

BuildPlan composes a Plan from the config and the supplied per-repo stats. The function is pure: it does not consult the network. Callers fetch stats via a Prober (or pass nil stats for a config-only preview).

type RepoStat

type RepoStat struct {
	Slug         string
	DiskUsageKB  int64 // GraphQL repository.diskUsage; 0 if unavailable.
	PullRequests int   // estimated PRs updated in window (all-time count scaled by window/repo-age ratio; unscaled if window not set).
	Commits      int   // estimated commits in window; 0 if unknown.
}

RepoStat is a per-repo cheap-aggregate snapshot used to feed the cost estimate. The connector-specific probe implementation populates these fields via read-only GraphQL aggregates.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL