releases

package module
v0.0.0-...-d2e5bb1 Latest Latest
Warning

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

 Go to latest Published: Aug 6, 2022 License: MPL-2.0 Imports: 10 Imported by: 0

README

Proto-Releases

Proto-releases provides protobuf extensions and tools to manage stability levels and releases of protobuf-based APIs.

This is experimental, work in progress, and by no means a complete set of tools for the above purpose. Discussion & contributions welcome.

See the LICENSE file for licensing terms.

For example, this "internal" proto acmecorp/hello.proto:

package acmecorp;
message Hello {
    int32 repeat = 1 [
        (releases.field).preview_in = 9;
    ];
    string name = 2 [
        (releases.field).release_in = 5;
    ];
}
service GreetingService {
    rpc SayHello(Hello) returns google.protobuf.Empty {
        option (releases.method).release_in = 5;
        option (google.api.http) = {
            get: "/v1unstable/hello"
        };
    };
}

Can be converted to the following "stable" proto acmecorp/v1/hello.proto:

package acmecorp.v1;
message Hello {
    string name = 2;
}
service GreetingService {
    rpc SayHello(Hello) returns google.protobuf.Empty {
        option (google.api.http) = {
            get: "/v1/hello"
        };
    };
}

Further, a single implementation of the original service can be used in Go to implement all released service versions:

srv := grpc.NewServer()
greetingsSvc := NewGreetingsService()
RegisterGreetingsServiceServer(srv, greetingsSvc)
beta.RegisterGreetingsServiceBaseServer(srv, greetingsSvc)
stable.RegisterGreetingsServiceBaseServer(srv, greetingsSvc)

Working Example

See the examples directory for a very small demo:

A more complete suite of examples can be found in the fixtures directory.

Further Documentation

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// TODO: replace with real id from global extension registry.
	//
	// optional releases.Range enum = 65535;
	E_Enum = &file_options_proto_extTypes[3]
)

Extension fields to descriptorpb.EnumValueOptions.

View Source 
var (
	// TODO: replace with real id from global extension registry.
	//
	// optional releases.Range field = 65535;
	E_Field = &file_options_proto_extTypes[1]
)

Extension fields to descriptorpb.FieldOptions.

View Source 
var (
	// TODO: replace with real id from global extension registry.
	//
	// optional releases.Range message = 65535;
	E_Message = &file_options_proto_extTypes[0]
)

Extension fields to descriptorpb.MessageOptions.

View Source 
var (
	// TODO: replace with real id from global extension registry.
	//
	// optional releases.Range method = 65535;
	E_Method = &file_options_proto_extTypes[4]
)

Extension fields to descriptorpb.MethodOptions.

View Source 
var (
	// TODO: replace with real id from global extension registry.
	//
	// optional releases.Range oneof = 65535;
	E_Oneof = &file_options_proto_extTypes[2]
)

Extension fields to descriptorpb.OneofOptions.

View Source 
var ErrConfig = errors.New("release config error")
View Source 
var File_config_proto protoreflect.FileDescriptor
View Source 
var File_options_proto protoreflect.FileDescriptor

Functions

func Include 

func Include(range_ *Range, config *Config) bool

func ParseGoPackageShorthand 

func ParseGoPackageShorthand(v string, into *Config_GoPackageMapping) error

func ParsePackageShorthand 

func ParsePackageShorthand(v string, into *Config_PackageMapping) error

Types

type Config 

type Config struct {

	// The number of the release.
	//
	// If non-zero, this determines the release number to use when applying the
	// options that specify which fields to include in a release. See the Range
	// message for further details.
	Release uint64 `protobuf:"varint,1,opt,name=release,proto3" json:"release,omitempty"`
	// Whether the release is a preview release. See the Range message for
	// further details.
	Preview   bool                     `protobuf:"varint,2,opt,name=preview,proto3" json:"preview,omitempty"`
	Package   *Config_PackageMapping   `protobuf:"bytes,4,opt,name=package,proto3" json:"package,omitempty"`
	GoPackage *Config_GoPackageMapping `protobuf:"bytes,3,opt,name=go_package,json=goPackage,proto3" json:"go_package,omitempty"`
	HttpRule  *Config_HttpRuleMapping  `protobuf:"bytes,5,opt,name=http_rule,json=httpRule,proto3" json:"http_rule,omitempty"`
	// contains filtered or unexported fields
}

func (*Config) Descriptor deprecated 

func (*Config) Descriptor() ([]byte, []int)

Deprecated: Use Config.ProtoReflect.Descriptor instead.

func (*Config) GetGoPackage 

func (x *Config) GetGoPackage() *Config_GoPackageMapping

func (*Config) GetHttpRule 

func (x *Config) GetHttpRule() *Config_HttpRuleMapping

func (*Config) GetPackage 

func (x *Config) GetPackage() *Config_PackageMapping

func (*Config) GetPreview 

func (x *Config) GetPreview() bool

func (*Config) GetRelease 

func (x *Config) GetRelease() uint64

func (*Config) ProtoMessage 

func (*Config) ProtoMessage()

func (*Config) ProtoReflect 

func (x *Config) ProtoReflect() protoreflect.Message

func (*Config) Reset 

func (x *Config) Reset()

func (*Config) String 

func (x *Config) String() string

type Config_GoPackageMapping 

type Config_GoPackageMapping struct {
	SourceRoot    string `protobuf:"bytes,1,opt,name=source_root,json=sourceRoot,proto3" json:"source_root,omitempty"`
	ReleaseRoot   string `protobuf:"bytes,2,opt,name=release_root,json=releaseRoot,proto3" json:"release_root,omitempty"`
	ReleaseSuffix string `protobuf:"bytes,3,opt,name=release_suffix,json=releaseSuffix,proto3" json:"release_suffix,omitempty"`
	// contains filtered or unexported fields
}

GoPackageMapping specifies how package paths should be transformed.

The output package is concatenated from three parts: <release_root>/<source_suffix>/<release_suffix>

<release_root> and <release_suffix> are specified by the fields of GoPackageMapping. <source_suffix> is taken from the input by stripping the prefix specified by the <source_root> field of GoPackageMapping.

func (*Config_GoPackageMapping) Descriptor deprecated 

func (*Config_GoPackageMapping) Descriptor() ([]byte, []int)

Deprecated: Use Config_GoPackageMapping.ProtoReflect.Descriptor instead.

func (*Config_GoPackageMapping) GetReleaseRoot 

func (x *Config_GoPackageMapping) GetReleaseRoot() string

func (*Config_GoPackageMapping) GetReleaseSuffix 

func (x *Config_GoPackageMapping) GetReleaseSuffix() string

func (*Config_GoPackageMapping) GetSourceRoot 

func (x *Config_GoPackageMapping) GetSourceRoot() string

func (*Config_GoPackageMapping) ProtoMessage 

func (*Config_GoPackageMapping) ProtoMessage()

func (*Config_GoPackageMapping) ProtoReflect 

func (x *Config_GoPackageMapping) ProtoReflect() protoreflect.Message

func (*Config_GoPackageMapping) Reset 

func (x *Config_GoPackageMapping) Reset()

func (*Config_GoPackageMapping) String 

func (x *Config_GoPackageMapping) String() string

type Config_HttpRuleMapping 

type Config_HttpRuleMapping struct {
	SourceRoot  string `protobuf:"bytes,1,opt,name=source_root,json=sourceRoot,proto3" json:"source_root,omitempty"`
	ReleaseRoot string `protobuf:"bytes,2,opt,name=release_root,json=releaseRoot,proto3" json:"release_root,omitempty"`
	// contains filtered or unexported fields
}

func (*Config_HttpRuleMapping) Descriptor deprecated 

func (*Config_HttpRuleMapping) Descriptor() ([]byte, []int)

Deprecated: Use Config_HttpRuleMapping.ProtoReflect.Descriptor instead.

func (*Config_HttpRuleMapping) GetReleaseRoot 

func (x *Config_HttpRuleMapping) GetReleaseRoot() string

func (*Config_HttpRuleMapping) GetSourceRoot 

func (x *Config_HttpRuleMapping) GetSourceRoot() string

func (*Config_HttpRuleMapping) ProtoMessage 

func (*Config_HttpRuleMapping) ProtoMessage()

func (*Config_HttpRuleMapping) ProtoReflect 

func (x *Config_HttpRuleMapping) ProtoReflect() protoreflect.Message

func (*Config_HttpRuleMapping) Reset 

func (x *Config_HttpRuleMapping) Reset()

func (*Config_HttpRuleMapping) String 

func (x *Config_HttpRuleMapping) String() string

type Config_PackageMapping 

type Config_PackageMapping struct {
	SourceRoot    string `protobuf:"bytes,1,opt,name=source_root,json=sourceRoot,proto3" json:"source_root,omitempty"`
	ReleaseRoot   string `protobuf:"bytes,2,opt,name=release_root,json=releaseRoot,proto3" json:"release_root,omitempty"`
	ReleaseSuffix string `protobuf:"bytes,3,opt,name=release_suffix,json=releaseSuffix,proto3" json:"release_suffix,omitempty"`
	// contains filtered or unexported fields
}

PackageMapping specifies how package paths should be transformed.

The output package is concatenated from three parts: <release_root>.<source_suffix>.<release_suffix>

<release_root> and <release_suffix> are specified by the fields of PackageMapping. <source_suffix> is taken from the input by stripping the prefix specified by the <source_root> field of PackageMapping.

func (*Config_PackageMapping) Descriptor deprecated 

func (*Config_PackageMapping) Descriptor() ([]byte, []int)

Deprecated: Use Config_PackageMapping.ProtoReflect.Descriptor instead.

func (*Config_PackageMapping) GetReleaseRoot 

func (x *Config_PackageMapping) GetReleaseRoot() string

func (*Config_PackageMapping) GetReleaseSuffix 

func (x *Config_PackageMapping) GetReleaseSuffix() string

func (*Config_PackageMapping) GetSourceRoot 

func (x *Config_PackageMapping) GetSourceRoot() string

func (*Config_PackageMapping) ProtoMessage 

func (*Config_PackageMapping) ProtoMessage()

func (*Config_PackageMapping) ProtoReflect 

func (x *Config_PackageMapping) ProtoReflect() protoreflect.Message

func (*Config_PackageMapping) Reset 

func (x *Config_PackageMapping) Reset()

func (*Config_PackageMapping) String 

func (x *Config_PackageMapping) String() string

type GoPackageFlagValue 

type GoPackageFlagValue struct {
	Config    *Config_GoPackageMapping
	ConfigPtr **Config_GoPackageMapping
	// contains filtered or unexported fields
}

func (*GoPackageFlagValue) Set 

func (s *GoPackageFlagValue) Set(v string) error

func (*GoPackageFlagValue) String 

func (s *GoPackageFlagValue) String() string

type GoPackageShorthandError 

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

func (GoPackageShorthandError) Error 

func (err GoPackageShorthandError) Error() string

func (GoPackageShorthandError) Unwrap 

func (err GoPackageShorthandError) Unwrap() error

type PackageShorthand 

type PackageShorthand struct {
	Config    *Config_PackageMapping
	ConfigPtr **Config_PackageMapping
	// contains filtered or unexported fields
}

func (*PackageShorthand) Set 

func (s *PackageShorthand) Set(v string) error

func (*PackageShorthand) String 

func (s *PackageShorthand) String() string

type PackageShorthandError 

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

func (PackageShorthandError) Error 

func (err PackageShorthandError) Error() string

func (PackageShorthandError) Unwrap 

func (err PackageShorthandError) Unwrap() error

type Range 

type Range struct {

	// Specify from which release onwards to include this item.
	// Any non-zero (including negative) value will cause the item to be
	// included in all preview releases, unless preview_in is specified.
	ReleaseIn uint64 `protobuf:"varint,1,opt,name=release_in,json=releaseIn,proto3" json:"release_in,omitempty"`
	// Specify from which preview release onwards to include this item.
	PreviewIn uint64 `protobuf:"varint,2,opt,name=preview_in,json=previewIn,proto3" json:"preview_in,omitempty"`
	// Specify from which release onwards to drop this item.
	RemoveIn uint64 `protobuf:"varint,3,opt,name=remove_in,json=removeIn,proto3" json:"remove_in,omitempty"`
	// contains filtered or unexported fields
}

func (*Range) Descriptor deprecated 

func (*Range) Descriptor() ([]byte, []int)

Deprecated: Use Range.ProtoReflect.Descriptor instead.

func (*Range) GetPreviewIn 

func (x *Range) GetPreviewIn() uint64

func (*Range) GetReleaseIn 

func (x *Range) GetReleaseIn() uint64

func (*Range) GetRemoveIn 

func (x *Range) GetRemoveIn() uint64

func (*Range) ProtoMessage 

func (*Range) ProtoMessage()

func (*Range) ProtoReflect 

func (x *Range) ProtoReflect() protoreflect.Message

func (*Range) Reset 

func (x *Range) Reset()

func (*Range) String 

func (x *Range) String() string

Source Files

View all Source files

Directories

Path Synopsis
server
server/alpha
server/beta
server/stable
releases/alpha/fixtures
releases/alpha/fixtures/subpackage
releases/beta1/fixtures
releases/beta1/fixtures/subpackage
releases/beta2/fixtures
releases/beta2/fixtures/subpackage
releases/beta3/fixtures
releases/beta3/fixtures/subpackage
releases/stable1/fixtures
releases/stable1/fixtures/subpackage
releases/stable2/fixtures
releases/stable2/fixtures/subpackage
releases/stable3/fixtures
releases/stable3/fixtures/subpackage
subpackage
internal
protos/google.golang.org/genproto/googleapis/api/annotations

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.