protobuf

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package protobuf validates protobuf payloads against a FileDescriptorSet.

It is a separate package so the protobuf runtime lands only in the graph of a service that validates protobuf. The registry itself needs neither this nor the JSON Schema compiler: to a store, a schema is bytes.

Index

Constants

This section is empty.

Variables

View Source
var ErrNoRoot = errors.NewSentinel("schema.protobuf.no_root",
	"schema: a protobuf schema must name its root message in Schema.Root")

ErrNoRoot is returned when a protobuf schema does not name its entry point.

A FileDescriptorSet holds every message the target file depends on, and nothing in it says which one a payload is. Inferring it by convention — the first message of the last file, say — is wrong exactly once, and produces a validator quietly checking a different message than the one anybody meant.

Functions

This section is empty.

Types

type Checker

type Checker struct{}

Checker is the no-op compatibility checker for protobuf.

Protobuf compatibility has well-understood rules — field numbers may not be reused, a required field may not be added, a type may not change — and they are the rules a real checker would encode. It does not encode them yet, and this exists so the seam is live code rather than a comment.

func (Checker) Check

Check accepts everything.

func (Checker) Language

func (Checker) Language() schema.Language

Language reports schema.Protobuf.

type Validator

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

Validator checks protobuf payloads against a serialised FileDescriptorSet.

Descriptors are cached by identifier, on the same reasoning as the JSON Schema validator's cache: parsing is the expensive part, and a published schema cannot change.

func New

func New() *Validator

New returns a validator with an empty cache.

func (*Validator) Cached

func (v *Validator) Cached() int

Cached reports how many descriptors the validator is holding, so the cache can be asserted rather than assumed.

func (*Validator) Language

func (v *Validator) Language() schema.Language

Language reports schema.Protobuf.

func (*Validator) Validate

func (v *Validator) Validate(_ context.Context, s schema.Schema, payload []byte) error

Validate returns schema.ErrInvalidPayload when the payload is not a valid encoding of the schema's root message, and schema.ErrSchemaUnusable when the schema itself cannot be used — it is not a descriptor set, it names no root, or its root is not a message in the set. A schema.Guard fails closed on the first and open on the second, because they have different owners.

Be clear about what this proves, because it is less than it looks. Protobuf's wire format is deliberately permissive:

  • Every proto3 field is optional, so an empty payload conforms to every schema.
  • Unknown fields are preserved rather than rejected.
  • A field whose wire type does not match its descriptor is treated as an unknown field and skipped, not reported.

What is left is a real check — malformed framing, a truncated message, trailing bytes that do not decode — and it is a weaker check than JSON Schema's because the format is weaker. Pretending otherwise would be the misleading part, so the test suite asserts each of those three permissions explicitly rather than leaving them to be discovered.

Jump to

Keyboard shortcuts

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