prototransform

type Cache interface {
	Load(ctx context.Context, key string) ([]byte, error)
	Save(ctx context.Context, key string, data []byte) error
}

type Converter struct {
	// A custom [Resolver] can be supplied with the InputFormat [Unmarshaler] and
	// OutputFormat [Marshaler] for looking up types when expanding
	// google.protobuf.Any messages. As such, this is likely only needed in cases
	// where extensions may be present. For [proto], [protojson], and [prototext]
	// marshalers and unmarshalers are already handled so there is no need to
	// provide a WithResolver method. If nil, this defaults to using
	// protoregistry.GlobalTypes.
	Resolver Resolver
	// InputFormat handles unmarshaling bytes from the expected input format.
	// You can use a [proto.Unmarshaler], [protojson.Unmarshaler], or
	// [prototext.Unmarshaler] as a value for this field. You can also supply
	// your own custom format that implements the [Unmarshaler] interface. If
	// your custom format needs a [Resolver] (e.g. to resolve types in a
	// google.protobuf.Any message or to resolve extensions), then your custom
	// type should provide a method with the following signature:
	//     WithResolver(Resolver) Unmarshaler
	// This method should return a new unmarshaler that will make use of the
	// given resolver.
	InputFormat InputFormat
	// OutputFormat handles marshaling to bytes in the desired output format.
	// You can use a [proto.Marshaler], [protojson.Marshaler], or
	// [prototext.Marshaler] as a value for this field. You can also supply
	// your own custom format that implements the [Marshaler] interface. If
	// your custom format needs a [Resolver] (e.g. to format types in a
	// google.protobuf.Any message), then your custom type should provide
	// a method with the following signature:
	//     WithResolver(Resolver) Marshaler
	// This method should return a new marshaler that will make use of the
	// given resolver.
	OutputFormat OutputFormat
	// Filters are a set of user-supplied actions which will be performed on a
	// [ConvertMessage] call before the conversion takes place, meaning the
	// output value can be modified according to some set of rules.
	Filters Filters
}

type Filter func(protoreflect.Message) protoreflect.Message

type Filters []Filter

type InputFormat interface {
	WithResolver(Resolver) Unmarshaler
}

type Lease interface {
	// IsHeld returns whether the current process holds the
	// lease. If it returns an error, then it is not known who
	// holds the lease, and the error indicates why not. Polling
	// for a schema will be suspended unless/until this method
	// returns (true, nil).
	IsHeld() (bool, error)
	// SetCallbacks configures the given functions to be called
	// when the lease is acquired or released. The initial state
	// of a lease is "not held". So if the lease is not held at
	// the time this method is invoked, neither callback is
	// invoked. But if the lease IS held at the time this method
	// is invoked, the onAcquire callback will be immediately
	// invoked. A lease must synchronize invocations of the
	// callbacks so that there will never be multiple concurrent
	// calls.
	SetCallbacks(onAcquire, onRelease func())
	// Cancel cancels this lease and frees any associated
	// resources (which may include background goroutines). If
	// the lease is currently held, it will be immediately
	// released, and any onRelease callback will be invoked.
	// IsHeld will return false from that moment. If the
	// same lease needs to be re-acquired later, use the
	// Leaser to create a new lease with the same name.
	Cancel()
}

type Leaser interface {
	// NewLease tries to acquire the given lease name. This
	// returns a lease object, which represents the state of
	// the new lease, and whether the current process holds
	// it or not.
	//
	// Implementations should monitor the lease store so that
	// if the lease is not held but suddenly becomes available
	// (e.g. current leaseholder releases it or crashes),
	// another process can immediately pick it up. The given
	// leaseHolder bytes represent the current process and may
	// be persisted in the lease store if necessary. This is
	// particularly useful if the lease store has no other way
	// to identify connected clients or entry "owners", in which
	// case a lease implementation can compare the persisted
	// lease state to this value to determine if the current
	// client holds the lease.
	//
	// This may start background goroutines. In order to release
	// any such resources associated with the lease, callers must
	// call Lease.Cancel() or cancel the given context.
	NewLease(ctx context.Context, leaseName string, leaseHolder []byte) Lease
}

type Marshaler interface {
	Marshal(proto.Message) ([]byte, error)
}

type OutputFormat interface {
	WithResolver(Resolver) Marshaler
}

type Resolver interface {
	protoregistry.ExtensionTypeResolver
	protoregistry.MessageTypeResolver

	// FindEnumByName looks up an enum by its full name.
	// E.g., "google.protobuf.Field.Kind".
	//
	// This returns (nil, NotFound) if not found.
	FindEnumByName(enum protoreflect.FullName) (protoreflect.EnumType, error)
}

type SchemaPoller interface {
	// GetSchema polls for a schema. The given symbols may be used to filter
	// the schema to return a smaller result. The given currentVersion, if not
	// empty, indicates the version that the caller already has fetched and
	// cached. So if that is still the current version of the schema (nothing
	// newer to download), the implementation may return an ErrSchemaNotModified
	// error.
	GetSchema(ctx context.Context, symbols []string, currentVersion string) (descriptors *descriptorpb.FileDescriptorSet, version string, err error)
	// GetSchemaID returns a string that identifies the schema that it fetches.
	// For a BSR module, for example, this might be "buf.build/owner/module:version".
	GetSchemaID() string
}

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

type SchemaWatcherConfig struct {
	// The downloader of descriptors. See [NewSchemaPoller].
	SchemaPoller SchemaPoller
	// The symbols that should be included in the downloaded schema. These must be
	// the fully-qualified names of elements in the schema, which can include
	// packages, messages, enums, extensions, services, and methods. If specified,
	// the downloaded schema will only include descriptors to describe these symbols.
	// If left empty, the entire schema will be downloaded.
	IncludeSymbols []string
	// The period of the polling the BSR for new versions is specified by the
	// PollingPeriod argument. The PollingPeriod will adjust the time interval.
	// The duration must be greater than zero; if not, [NewSchemaWatcher] will
	// return an error. If unset and left zero, a default period of 5 minutes
	// is used.
	PollingPeriod time.Duration
	// A number between 0 and 1 that represents the amount of jitter to add to
	// the polling period. A value of zero means no jitter. A value of one means
	// up to 100% jitter, so the actual period would be between 0 and 2*PollingPeriod.
	// To prevent self-synchronization (and thus thundering herds) when there are
	// multiple pollers, a value of 0.1 to 0.3 is typical.
	Jitter float64
	// If Cache is non-nil, it is used for increased robustness, even in the
	// face of the remote schema registry being unavailable. If non-nil and the
	// API call to initially retrieve a schema fails, the schema will instead
	// be loaded from this cache. Whenever a new schema is downloaded from the
	// remote registry, it will be saved to the cache. So if the process is
	// restarted and the remote registry is unavailable, the latest cached schema
	// can still be used.
	Cache Cache
	// If Leaser is non-nil, it is used to decide whether the current process
	// can poll for the schema. Cache must be non-nil. This is useful when the
	// schema source is a remote process, and the current process is replicated
	// (e.g. many instances running the same workload, for redundancy and/or
	// capacity). This prevents all the replicas from polling. Instead, a single
	// replica will "own" the lease and poll for the schema. It will then store
	// the downloaded schema in the shared cache. A replica that does not have
	// the lease will look only in the cache instead of polling the remote
	// source.
	Leaser Leaser
	// CurrentProcess is an optional identifier for the current process. This
	// is only used if Leaser is non-nil. If present, this value is used to
	// identify the current process as the leaseholder. If not present, a
	// default value will be computed using the current process's PID and the
	// host name and network addresses of the current host. If present, this
	// value must be unique for all other processes that might try to acquire
	// the same lease.
	CurrentProcess []byte
	// OnUpdate is an optional callback that will be invoked when a new schema
	// is fetched. This can be used by an application to take action when a new
	// schema becomes available.
	OnUpdate func(*SchemaWatcher)
	// OnError is an optional callback that will be invoked when a schema cannot
	// be fetched. This could be due to the SchemaPoller returning an error or
	// failure to convert the fetched descriptors into a resolver.
	OnError func(*SchemaWatcher, error)
}

type Unmarshaler interface {
	Unmarshal([]byte, proto.Message) error
}