compiler

Documentation

Overview

Package compiler wraps protocompile to provide namespace-scoped compilation of proto source files. It handles normalization, SHA-256 hashing for content-addressable storage, and builds the resolver chain that enforces namespace isolation (chroot model).

Index

• Constants
• func ComputeFingerprint(files []FileResult) string
• func IsWellKnownType(filename string) bool
• func Version() string
• type CompileResult
• type Compiler
  • func New(opts ...CompilerOption) *Compiler
  • func (c *Compiler) Compile(ctx context.Context, version uint64, sources map[string][]byte, ...) (*CompileResult, error)
• type CompilerOption
  • func WithMaxFileSourceBytes(n int64) CompilerOption
  • func WithMaxFiles(n int) CompilerOption
  • func WithTimeout(d time.Duration) CompilerOption
• type Dep
• type DepSource
  • func LoadBuiltIns(dir string) ([]DepSource, error)
• type FileResult
• type NormalizeResult
  • func NormalizeAndHash(filename string, source []byte) (*NormalizeResult, error)

Constants

const (
	// DefaultCompileTimeout caps wall-clock time spent inside protocompile.
	DefaultCompileTimeout = 30 * time.Second

	// DefaultMaxFileSourceBytes caps the size of any individual proto
	// source the compiler will accept. Enforced before any AST work.
	DefaultMaxFileSourceBytes = 8 * 1024 * 1024 // 8 MiB

	// DefaultMaxFiles caps the number of files in a single Compile call.
	DefaultMaxFiles = 1000
)

Default resource caps. Compile is the user-facing entry point and these numbers bound worst-case CPU and memory consumption per call. The server applies tighter validation upstream; these are the library-level safety net so the compiler is also safe to embed in non-server callers.

Functions

func ComputeFingerprint

func ComputeFingerprint(files []FileResult) string

ComputeFingerprint computes a fingerprint over a sorted set of (filename, hash) pairs. Used to detect whether a new submission actually changes anything compared to the current version.

func IsWellKnownType

func IsWellKnownType(filename string) bool

IsWellKnownType reports whether filename matches a standard import provided by protocompile (e.g., google/protobuf/timestamp.proto).

func Version

func Version() string

Version returns a string identifying the compiler and its dependencies, used to detect when cached compiled descriptors may be stale.

Types

type CompileResult

type CompileResult struct {
	// Snapshot is the compiled, immutable descriptor set.
	Snapshot *snapshot.Snapshot
	// Compiled is the serialized FileDescriptorSet for storage.
	Compiled []byte
	// Files is the list of normalized file hashes, for blob storage.
	Files []FileResult
	// Deps records which dependency versions were used during compilation.
	Deps []Dep
}

CompileResult holds the output of a compilation.

type Compiler

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

Compiler wraps protocompile for namespace-scoped compilation.

func New

func New(opts ...CompilerOption) *Compiler

New creates a new Compiler with default caps. Pass options to override.

func (*Compiler) Compile

func (c *Compiler) Compile(
	ctx context.Context,
	version uint64,
	sources map[string][]byte,
	deps []DepSource,
	builtins []DepSource,
) (*CompileResult, error)

Compile compiles the given proto sources within a namespace scope. The sources map is filename → content for the schema being compiled. The deps slice provides files from other schemas in the namespace that may be imported. The builtins slice provides files from the built-ins namespace that are available to all namespaces; they resolve after namespace sources but before Google well-known types.

type CompilerOption

type CompilerOption func(*Compiler)

CompilerOption customises a Compiler.

func WithMaxFileSourceBytes

func WithMaxFileSourceBytes(n int64) CompilerOption

WithMaxFileSourceBytes sets the per-file size cap.

func WithMaxFiles

func WithMaxFiles(n int) CompilerOption

WithMaxFiles sets the cap on the number of files per Compile call.

func WithTimeout

func WithTimeout(d time.Duration) CompilerOption

WithTimeout sets the wall-clock cap on a single Compile call. Pass 0 to disable (not recommended in server contexts).

type Dep

type Dep struct {
	DepSchemaID string
	DepFilename string
	DepVersion  uint64
}

Dep records a dependency on another schema's file used during compilation.

type DepSource

type DepSource struct {
	SchemaID string
	Version  uint64
	Filename string
	Source   []byte
}

DepSource describes a file available from another schema in the namespace. These are provided to the compiler so it can resolve cross-schema imports.

func LoadBuiltIns

func LoadBuiltIns(dir string) ([]DepSource, error)

LoadBuiltIns reads all .proto files from dir recursively and returns them as DepSource entries suitable for passing to Compile as builtins. The filenames are relative to dir, matching proto import paths.

type FileResult

type FileResult struct {
	Filename       string
	BlobSHA256     string
	OriginalSource []byte
}

FileResult associates a filename with its content hash after normalization.

type NormalizeResult

type NormalizeResult struct {
	// SHA256 is the hex-encoded SHA-256 hash of the normalized content.
	SHA256 string
	// OriginalSource is the unmodified source as submitted.
	OriginalSource []byte
}

NormalizeResult holds the output of normalizing a proto source file.

func NormalizeAndHash

func NormalizeAndHash(filename string, source []byte) (*NormalizeResult, error)

NormalizeAndHash parses a proto file, produces a canonical (normalized) representation by printing the AST without comments or extraneous whitespace, and returns the SHA-256 hash of that normalized form.

The original source is returned unchanged for storage. The hash is used only for content-addressable deduplication and change detection.