docs

codec/types/interface_registry.go

@@ -375,7 +375,18 @@ func (registry *interfaceRegistry) FindDescriptorByName(name protoreflect.FullNa
 }
 
 type ModuleRegistrar interface {
-	RegisterFiles(fs embed.FS, fileDescriptors ...protoreflect.FileDescriptor) error
+	// RegisterFiles registers the protobuf file descriptors for a module. pinnedProtoImageFS should
+	// be an embedded FS which contains a file - image.bin.gz - generated by buf build, that contains
+	// the pinned FileDescriptorSet that this module was built against. This pinned FileDescriptorSet
+	// will be used when performing unknown field rejection for correct API compatibility. The
+	// file descriptors also passed into RegisterFiles are the protobuf files that the module
+	// "owns" and should define relevant Msg and Query servers as well as ORM tables. Instead of
+	// using the file descriptors passed in at runtime, RegisterFiles will used the same versions
+	// of those file descriptors stored in the pinned FileDescriptorSet, in case the binary for
+	// a module was compiled with a newer build of the proto files that the module was developed against.
+	// This feature will eventually allow a single binary to contain multiple versions of the same module
+	// and perform upgrades without a restart.
+	RegisterFiles(pinnedProtoImageFS embed.FS, fileDescriptors ...protoreflect.FileDescriptor) error
 }
 
 type moduleRegistrar struct {