bootstrap

Documentation

Overview

Package bootstrap — BootstrapSync orchestrator and public option surface.

Review-driven additions (05-REVIEWS.md):

• L2: PURE_SIMDJSON_CACHE_DIR env var → resolveConfig + defaultCacheDir.
• L3: version-stamped User-Agent on every outbound HTTP request (see download.go).
• M2: 30-second failure memoization so a blocked network does not stall every NewParser() call for minutes.
• M3: test seams re-exported via export_test.go for bootstrap_test.

Package bootstrap implements artifact download, checksum verification, and cache management for the pure-simdjson shared library. Error sentinels defined here are canonical — the root purejson package re-exports them via pointer alias. Never call errors.New for these sentinels anywhere else.

Index

• Constants
• Variables
• func BootstrapSync(ctx context.Context, opts ...BootstrapOption) error
• func CachePath(goos, goarch string) string
• func ChecksumKey(version, goos, goarch string) string
• func LooksLikeSHA256Hex(raw string) bool
• func PlatformLibraryName(goos string) string
• func ResolveChecksum(ctx context.Context, opts ...BootstrapOption) (string, error)
• type BootstrapOption
  • func WithDest(path string) BootstrapOption
  • func WithMirror(rawURL string) BootstrapOption
  • func WithTarget(goos, goarch string) BootstrapOption
  • func WithVersion(v string) BootstrapOption

Constants

const Version = "0.1.7"

Version is the library version pinned at compile time. The release tag and this constant must match. ldflags -X is explicitly rejected (D-06): consumer go build does not run our build flags.

Variables

var (
	// ErrChecksumMismatch reports that a downloaded artifact's SHA-256 digest did
	// not match the authoritative expected value. Permanent: no retry on mismatch
	// (D-17, D-31).
	ErrChecksumMismatch = errors.New("checksum mismatch")

	// ErrAllSourcesFailed reports that all download sources (R2 + GitHub fallback)
	// were exhausted. The outer wrap at the library_loading.go boundary adds a
	// hint referencing PURE_SIMDJSON_LIB_PATH (D-21).
	ErrAllSourcesFailed = errors.New("all sources failed")

	// ErrNoChecksum reports that no authoritative digest could be resolved for the
	// requested platform/version from checksum overrides or published SHA256SUMS.
	ErrNoChecksum = errors.New("no checksum for platform")
)

var Checksums = map[string]string{}

Checksums optionally overrides published SHA-256 digests for "v<Version>/<os>-<arch>/<libname>" path fragments.

Production bootstrap resolves digests from published SHA256SUMS metadata under the release tag. Tests and controlled local flows may inject overrides here to avoid network metadata lookups.

var SupportedPlatforms = [][2]string{
	{"linux", "amd64"},
	{"linux", "arm64"},
	{"darwin", "amd64"},
	{"darwin", "arm64"},
	{"windows", "amd64"},
}

SupportedPlatforms lists the five release targets (DIST-01).

Functions

func BootstrapSync

func BootstrapSync(ctx context.Context, opts ...BootstrapOption) error

BootstrapSync downloads, verifies, and installs the shared library for the resolved target platform into the cache directory. Safe for concurrent callers: an exclusive flock guards the install step, so repeated invocations collapse into a single download.

Signature is locked by D-03.

func CachePath

func CachePath(goos, goarch string) string

CachePath returns the absolute path where the artifact for goos/goarch is stored. Layout: <cacheDir>/v<Version>/<goos>-<goarch>/<libname> (D-07). Called from library_loading.go::resolveLibraryPath to check cache presence (D-04).

func ChecksumKey

func ChecksumKey(version, goos, goarch string) string

ChecksumKey returns the map key used in Checksums for a given platform (D-08). Format: "v<version>/<goos>-<goarch>/<PlatformLibraryName>" EXPORTED (uppercase) because the CLI in cmd/pure-simdjson-bootstrap (a separate package) needs it for the `verify` subcommand.

func LooksLikeSHA256Hex

func LooksLikeSHA256Hex(raw string) bool

func PlatformLibraryName

func PlatformLibraryName(goos string) string

PlatformLibraryName returns the on-disk library filename for the given GOOS (D-10). This is the name the file has in the CACHE, not on the GitHub release. Exported so the CLI (cmd/pure-simdjson-bootstrap) can construct cache paths without redeclaring the name set.

func ResolveChecksum

func ResolveChecksum(ctx context.Context, opts ...BootstrapOption) (string, error)

ResolveChecksum returns the expected SHA-256 digest for the resolved target. Test and controlled local flows may inject values through the Checksums map. Production resolution falls back to published SHA256SUMS metadata.

Types

type BootstrapOption

type BootstrapOption func(*bootstrapConfig) error

BootstrapOption configures BootstrapSync.

func WithDest

func WithDest(path string) BootstrapOption

WithDest writes the artifact into path instead of the default cache dir. Used by the CLI fetch subcommand to populate a vendor directory.

func WithMirror

func WithMirror(rawURL string) BootstrapOption

WithMirror overrides the R2 base URL. Validated at resolve time: HTTP is rejected for non-loopback hosts (T-05-05).

func WithTarget

func WithTarget(goos, goarch string) BootstrapOption

WithTarget overrides the goos/goarch target. Defaults to runtime.GOOS / runtime.GOARCH; CLI uses this for --target cross-platform prefetch.

func WithVersion

func WithVersion(v string) BootstrapOption

WithVersion overrides the library version. Defaults to the compile-time Version constant; CLI uses this for cross-version fetches.