compat

package

v0.0.0-...-13d1711 Latest Latest Go to latest Published: Oct 9, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/bmeddeb/phebs

Links

Open Source Insights

Documentation ¶

Rendered for

Overview ¶

Package compat runs protobuf wire-compatibility checks through the pinned Buf CLI. Repository content is never executed: callers supply bounded .proto text, which is copied into a fresh sanitized tree before the one fixed `buf breaking` command is launched by the OS sandbox.

Constants ¶

View Source

const (
	// Version is intentionally coupled to the go.mod tool pin. A different
	// binary is rejected before it can produce a verdict.
	Version = "1.72.0"

	Policy = "WIRE"
)

Variables ¶

View Source

var (
	ErrInvalidInput = errors.New("invalid compatibility input")
	ErrUnavailable  = errors.New("compatibility checker unavailable")
	ErrLimit        = errors.New("compatibility checker limit exceeded")
	ErrCheckFailed  = errors.New("compatibility checker failed")
)

Functions ¶

func FindBinary ¶

func FindBinary() (string, error)

FindBinary locates Buf using the same deployment pattern as the zoekt child: an explicit override, beside phebs, under its bin directory, then PATH.

func WirePolicyDigest ¶

func WirePolicyDigest() string

WirePolicyDigest binds the exact pinned engine, policy configuration, and visible limits used by proof-bundle callers.

Types ¶

type Checker ¶

type Checker struct {
	// contains filtered or unexported fields
}

Checker invokes one pinned Buf binary through the platform sandbox.

func New ¶

func New(bin string) (*Checker, error)

New constructs a checker only when the host can provide the required network/write sandbox and process resource boundary.

func (*Checker) Check ¶

func (c *Checker) Check(ctx context.Context, request Request) (*CompatibilityResult, error)

Check validates and commits both input sets before launching Buf. Every error is classified so transports can distinguish bad input, bounded refusal, unavailable host isolation, and an engine failure.

func (*Checker) Validate ¶

func (c *Checker) Validate(ctx context.Context) error

Validate performs the same sandboxed version probe used by Check. Servers call it before registering HTTP/MCP capability, so discovery never exposes a tool backed by a missing, mismatched, or non-enforceable child.

type CompatibilityResult ¶

type CompatibilityResult struct {
	Compatible     bool            `json:"compatible"`
	Before         InputSnapshot   `json:"before"`
	After          InputSnapshot   `json:"after"`
	Violations     []Violation     `json:"violations"`
	AffectedFields []FieldIdentity `json:"affected_fields"`
	Run            Run             `json:"extraction_run"`
}

CompatibilityResult is the specification verdict plus stable consumer join keys.

type FieldIdentity ¶

type FieldIdentity struct {
	Lineage string `json:"lineage"`
	Message string `json:"message"`
	Number  int    `json:"field_number"`
}

FieldIdentity is the stable consumer-join key. A source field name and type can change between versions; message full name and wire number do not.

type File ¶

type File struct {
	Path    string `json:"path" minLength:"1" maxLength:"4096" jsonschema:"canonical slash-separated relative .proto path"`
	Content string `json:"content" maxLength:"4194304" jsonschema:"UTF-8 protobuf source text; maximum 4 MiB"`
}

File is one caller-supplied protobuf source file. Path is a canonical repository-relative slash path; Content is never retained in the result.

type InputFile ¶

type InputFile struct {
	Path   string `json:"path"`
	Digest string `json:"digest"`
}

InputFile records only the canonical path and content digest of an input.

type InputSnapshot ¶

type InputSnapshot struct {
	Digest string      `json:"digest"`
	Files  []InputFile `json:"files"`
}

InputSnapshot is the content commitment for one side of the comparison.

type Limits ¶

type Limits struct {
	Engine                string `json:"engine"`
	Version               string `json:"version"`
	Policy                string `json:"policy"`
	MaxFilesPerSnapshot   int    `json:"max_files_per_snapshot"`
	MaxFileBytes          int    `json:"max_file_bytes"`
	MaxInputBytes         int    `json:"max_input_bytes"`
	MaxTokensPerFile      int    `json:"max_tokens_per_file"`
	MaxStructuralDepth    int    `json:"max_structural_depth"`
	MaxViolations         int    `json:"max_violations"`
	MaxAffectedFieldCount int    `json:"max_affected_field_count"`
}

Limits is the public, deterministic compatibility/preflight contract shown beside other evidence projections.

func WireLimits ¶

func WireLimits() Limits

WireLimits returns the frozen Buf WIRE and parser ceilings without probing or executing the child binary.

type PreparedRequest ¶

type PreparedRequest struct {
	Before InputSnapshot `json:"before"`
	After  InputSnapshot `json:"after"`
	// contains filtered or unexported fields
}

PreparedRequest is a pure, source-free commitment produced before Buf is invoked. The canonical request and parser metadata remain private so callers cannot bypass Check's execution boundary.

func Prepare ¶

func Prepare(ctx context.Context, request Request) (*PreparedRequest, error)

Prepare applies the exact canonicalization, aggregate bounds, lexical preflight, and in-process parser work used by Check without executing Buf.

type Request ¶

type Request struct {
	Lineage string `` /* 127-byte string literal not displayed */
	Before  []File `json:"before" maxItems:"256" jsonschema:"baseline protobuf source files"`
	After   []File `json:"after" maxItems:"256" jsonschema:"candidate protobuf source files"`
}

Request compares After against Before. Lineage binds affected field numbers to the same version-independent identity used by SCIP consumer evidence.

type Run ¶

type Run struct {
	Engine    string   `json:"engine"`
	Version   string   `json:"version"`
	Policy    string   `json:"policy"`
	Arguments []string `json:"arguments"`
	ExitCode  int      `json:"exit_code"`
	Result    string   `json:"result"`
}

Run is deterministic invocation provenance embedded in the immutable proof bundle. Arguments are the exact relative arguments supplied to Buf, so they disclose no host temp path and remain byte-stable for identical inputs.

type Service ¶

type Service interface {
	Check(ctx context.Context, request Request) (*CompatibilityResult, error)
}

Service is the narrow boundary used by the shared HTTP/MCP proof service.

type Violation ¶

type Violation struct {
	Snapshot    string         `json:"snapshot"`
	Path        string         `json:"path"`
	StartLine   int            `json:"start_line"`
	StartColumn int            `json:"start_column"`
	EndLine     int            `json:"end_line"`
	EndColumn   int            `json:"end_column"`
	Rule        string         `json:"rule"`
	Message     string         `json:"message"`
	Field       *FieldIdentity `json:"affected_field,omitempty"`
}

Violation is one structured Buf breaking finding. Spans are one-based and refer to a file in the named input snapshot.

Source Files ¶

View all Source files

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