Release v1.29.0 (#539)

# Commits The following comments are included in this release. Some of these cherry-picked and released in v1.28.0, but they appear again in the list above. - protocol: Add streaming interfaces (#485) - Move Stream-based interfaces into their own package - Make Streaming interfaces private to allow for safe experimentation (#488) - idl: Return structured ParseError from idl.Parse() (#492) - Add CHANGELOG entry for #492 (#494) - Support "<" in the templating language (#499) - idl: add a Position struct to wrap reported lines (#497) - Add streamwriter implementation (#490) - Add a "StreamReader" which implements "stream.Reader" - Use the "stream.Reader" in the "binary.Reader" - Add code generation for all wire types for stream encoding (#500) - Generate "Decode" for "enums" that will directly decode (#495) - Provide "decode" code generation for the streaming variants for all other types (#496) - idl: record document positions on constant nodes (#503) - ast: move idl.Position to the ast package (#504) - idl: replace internal.Position with ast.Position (#505) - Expose stream protocol method to close Writer (#506) - idl: add column numbers to parse error positions (#507) - idl: record full positions for constants (#508) - Mark assertParseCases() as a test helper (#509) - protocol/stream: Define enveloping interfaces (#511) - protocol/stream: Declare interface for encoding envelopes (#513) - binary/StreamWriter: Borrow => New; unexport Return (#515) - stream: add Close method, pool binary reader (#514) - binary/reader: Return to pool after ReadValue (#517) - binary/reader: Skip fixed width collections faster (#518) - binary/stream/reader: Fast-path offsetReader skips (#519) - binary: Move Responders and Protocol into package (#516) - benchmark: Refactor into a suite (#520) - Upgrade to Ragel version 6.10 (from 6.9) (#523) - Responder: Deduplicate interface (#524) - gen/quick_test: Add missing types (#525) - enum/json: Support rejecting unknown values (#502) - Back to development - Upgrade to golang.org/x/tools version 0.1.5 (#529) - ast: add column values to the AST nodes (#522) - stream: Implement Request and Response handling with Enveloping (#526) - offsetReader: Implement io.Seeker - binary/ReadRequest: Use io.Seeker if available - StreamReader: Use Seeker instead of offsetReader - protocol/stream: Unembed stream.Protocol from stream.RequestReader (#532) - thrifttest: Add mocks for streaming interfaces (#527) - streaming: Unembed iface.Private in streaming-based interfaces (#533) - Regenerate files for tests after merging `streamdev` - ast: formally declare CppInclude as a Node (#536) - ast: add Annotations(Node) []*Annotations (#537) - Preparing release v1.29.0 # API changes I ran apidiff on all packages in v1.28.0 and compared it with this release. Removing changes to gen/internal/tests, the result is: ``` --- go.uber.org/thriftrw/ast --- Compatible changes: - Annotation.Column: added - Annotations: added - BaseType.Column: added - Constant.Column: added - ConstantList.Column: added - ConstantMap.Column: added - ConstantMapItem.Column: added - ConstantReference.Column: added - CppInclude.Column: added - DefinitionInfo.Column: added - Enum.Column: added - EnumItem.Column: added - Field.Column: added - Function.Column: added - Include.Column: added - ListType.Column: added - MapType.Column: added - Namespace.Column: added - Position.Column: added - Position.String: added - Service.Column: added - ServiceReference.Column: added - SetType.Column: added - Struct.Column: added - TypeReference.Column: added - Typedef.Column: added --- go.uber.org/thriftrw/envelope/stream --- NEW PACKAGE --- go.uber.org/thriftrw/gen --- Compatible changes: - StreamGenerator: added --- go.uber.org/thriftrw/internal/envelope/exception --- Compatible changes: - (*ExceptionType).Decode: added - (*TApplicationException).Decode: added - (*TApplicationException).Encode: added - ExceptionType.Encode: added --- go.uber.org/thriftrw/plugin/api --- Compatible changes: - (*Argument).Decode: added - (*Argument).Encode: added - (*Feature).Decode: added - (*Function).Decode: added - (*Function).Encode: added - (*GenerateServiceRequest).Decode: added - (*GenerateServiceRequest).Encode: added - (*GenerateServiceResponse).Decode: added - (*GenerateServiceResponse).Encode: added - (*HandshakeRequest).Decode: added - (*HandshakeRequest).Encode: added - (*HandshakeResponse).Decode: added - (*HandshakeResponse).Encode: added - (*Module).Decode: added - (*Module).Encode: added - (*ModuleID).Decode: added - (*Plugin_Goodbye_Args).Decode: added - (*Plugin_Goodbye_Args).Encode: added - (*Plugin_Goodbye_Result).Decode: added - (*Plugin_Goodbye_Result).Encode: added - (*Plugin_Handshake_Args).Decode: added - (*Plugin_Handshake_Args).Encode: added - (*Plugin_Handshake_Result).Decode: added - (*Plugin_Handshake_Result).Encode: added - (*Service).Decode: added - (*Service).Encode: added - (*ServiceGenerator_Generate_Args).Decode: added - (*ServiceGenerator_Generate_Args).Encode: added - (*ServiceGenerator_Generate_Result).Decode: added - (*ServiceGenerator_Generate_Result).Encode: added - (*ServiceID).Decode: added - (*SimpleType).Decode: added - (*Type).Decode: added - (*Type).Encode: added - (*TypePair).Decode: added - (*TypePair).Encode: added - (*TypeReference).Decode: added - (*TypeReference).Encode: added - Feature.Encode: added - ModuleID.Encode: added - ServiceID.Encode: added - SimpleType.Encode: added --- go.uber.org/thriftrw/protocol --- Compatible changes: - BinaryStreamer: added --- go.uber.org/thriftrw/protocol/binary --- Compatible changes: - Default: added - EnvelopeV0Responder: added - EnvelopeV1Responder: added - NewStreamReader: added - NewStreamWriter: added - NoEnvelopeResponder: added - Protocol: added - Responder: added - StreamReader: added - StreamWriter: added --- go.uber.org/thriftrw/protocol/envelope --- NEW PACKAGE --- go.uber.org/thriftrw/protocol/stream --- NEW PACKAGE --- go.uber.org/thriftrw/thrifttest/streamtest --- NEW PACKAGE --- go.uber.org/thriftrw/version --- Incompatible changes: - Version: value changed from "1.28.0" to "1.29.0" ```
thriftrw · Aug 30, 2021 · efbbb99 · efbbb99
2 parents 8e55b5a + b18ff31
commit efbbb99
Show file tree

Hide file tree

Showing 86 changed files with 24,038 additions and 4,171 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [1.29.0] - 2021-08-30
+This release includes support for (de)serializing Thrift structs directly
+to/from IO streams without converting them to the intermediate `wire.Value`
+representation. This method of (de)serialization is significantly faster and
+less memory intensive.
+
+### Added
+- `protocol/stream` and `envelope/stream` packages defining the core types
+  needed to implement support for streaming serialization.
+- `protocol`: `BinaryStreamer` that exports the Binary protocol as a
+  `stream.Protocol`.
+- `protocol/binary`: The new `Default` variable is the default value of
+  `*binary.Protocol` that most users should use. This variable retains the
+  struct type so that it can be used for any new interfaces declared in the
+  future without another `protocol.Binary*` export.
+- All generated types now include `Encode` and `Decode` methods that can
+  serialize or deserialize those types using `stream.Writer` and
+  `stream.Reader` objects.
+- `ast`: All nodes now track the column numbers they're defined on in addition
+  to the line numbers.
+- `ast`: Add `Annotations(Node)` function that reports the annotations for AST
+  nodes that record annotations.
+
+### Changed
+- `protocol`:
+    - Deprecate `Binary` and `EnvelopeAgnosticBinary` in favor of
+      `protocol/binary.Default`.
+    - Deprecate `NoEnvelopeResponder`, `EnvelopeV0Responder`, and
+      `EnvelopeV1Responder` in favor of versions declared in the
+      `protocol/binary` package.
+
+Thanks to [@witriew](https://github.com/witriew), [@dianale31](https://github.com/dianale31), [@usmyth](https://github.com/usmyth), and [@jparise](https://github.com/jparise) for their contributions
+to this release.
+
 ## [1.28.0] - 2021-07-26
 ### Added
 - `idl.Parse` now returns structured `ParseError` on parse failures.
@@ -384,6 +418,7 @@ this release.
 ### Added
 - Initial release.
 
+[1.29.0]: https://github.com/thriftrw/thriftrw-go/compare/v1.28.0...v1.29.0
 [1.28.0]: https://github.com/thriftrw/thriftrw-go/compare/v1.27.0...v1.28.0
 [1.27.0]: https://github.com/thriftrw/thriftrw-go/compare/v1.26.0...v1.27.0
 [1.26.0]: https://github.com/thriftrw/thriftrw-go/compare/v1.25.1...v1.26.0

diff --git a/ast/annotation.go b/ast/annotation.go
@@ -33,21 +33,30 @@ import (
 // They may be used to customize the generated code. Annotations are optional
 // anywhere in the code where they're accepted and may be skipped completely.
 type Annotation struct {
-	Name  string
-	Value string
-	Line  int
+	Name   string
+	Value  string
+	Line   int
+	Column int
 }
 
 func (*Annotation) node() {}
 
 func (*Annotation) visitChildren(nodeStack, visitor) {}
 
-func (ann *Annotation) lineNumber() int { return ann.Line }
+func (ann *Annotation) pos() Position { return Position{Line: ann.Line, Column: ann.Column} }
 
 func (ann *Annotation) String() string {
 	return fmt.Sprintf("%s = %q", ann.Name, ann.Value)
 }
 
+// Annotations returns the annotations for the given node.
+func Annotations(n Node) []*Annotation {
+	if na, ok := n.(nodeWithAnnotations); ok {
+		return na.annotations()
+	}
+	return nil
+}
+
 // FormatAnnotations formats a collection of annotations into a string.
 func FormatAnnotations(anns []*Annotation) string {
 	if len(anns) == 0 {
@@ -61,3 +70,24 @@ func FormatAnnotations(anns []*Annotation) string {
 
 	return "(" + strings.Join(as, ", ") + ")"
 }
+
+// Nodes which have annoations can implement this interface.
+type nodeWithAnnotations interface {
+	Node
+
+	annotations() []*Annotation
+}
+
+var (
+	_ nodeWithAnnotations = BaseType{}
+	_ nodeWithAnnotations = (*Enum)(nil)
+	_ nodeWithAnnotations = (*EnumItem)(nil)
+	_ nodeWithAnnotations = (*Field)(nil)
+	_ nodeWithAnnotations = (*Function)(nil)
+	_ nodeWithAnnotations = ListType{}
+	_ nodeWithAnnotations = MapType{}
+	_ nodeWithAnnotations = (*Service)(nil)
+	_ nodeWithAnnotations = SetType{}
+	_ nodeWithAnnotations = (*Struct)(nil)
+	_ nodeWithAnnotations = (*Typedef)(nil)
+)
diff --git a/ast/annotation_test.go b/ast/annotation_test.go
@@ -21,11 +21,57 @@
 package ast
 
 import (
+	"fmt"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 )
 
+func TestAnnotations(t *testing.T) {
+	anns := []*Annotation{
+		{Name: "annotation", Value: "value"},
+	}
+
+	tests := []struct {
+		give Node
+		want []*Annotation
+	}{
+		{give: &Annotation{}, want: nil},
+		{give: BaseType{Annotations: anns}, want: anns},
+		{give: &Constant{}, want: nil},
+		{give: ConstantBoolean(true), want: nil},
+		{give: ConstantDouble(42.0), want: nil},
+		{give: ConstantInteger(42), want: nil},
+		{give: ConstantMap{Line: 2, Column: 1}, want: nil},
+		{give: ConstantMapItem{Line: 3, Column: 1}, want: nil},
+		{give: ConstantList{Line: 4, Column: 1}, want: nil},
+		{give: ConstantReference{Line: 5, Column: 1}, want: nil},
+		{give: ConstantString("foo"), want: nil},
+		{give: &CppInclude{}, want: nil},
+		{give: &Enum{Annotations: anns}, want: anns},
+		{give: &EnumItem{Annotations: anns}, want: anns},
+		{give: &Field{Annotations: anns}, want: anns},
+		{give: &Function{Annotations: anns}, want: anns},
+		{give: &Include{}, want: nil},
+		{give: ListType{Annotations: anns}, want: anns},
+		{give: MapType{Annotations: anns}, want: anns},
+		{give: &Namespace{}, want: nil},
+		{give: &Program{}, want: nil},
+		{give: &Service{Annotations: anns}, want: anns},
+		{give: SetType{Annotations: anns}, want: anns},
+		{give: &Struct{Annotations: anns}, want: anns},
+		{give: &Typedef{Annotations: anns}, want: anns},
+		{give: TypeReference{}, want: nil},
+	}
+
+	for _, tt := range tests {
+		t.Run(fmt.Sprintf("%T", tt.give), func(t *testing.T) {
+			actual := Annotations(tt.give)
+			assert.Equal(t, tt.want, actual)
+		})
+	}
+}
+
 func TestFormatAnnotations(t *testing.T) {
 	var anns []*Annotation
 	assert.Equal(t, "", FormatAnnotations(anns))

diff --git a/ast/constant.go b/ast/constant.go
@@ -67,10 +67,10 @@ func (i ConstantMapItem) visitChildren(ss nodeStack, v visitor) {
 	v.visit(ss, i.Value)
 }
 
-func (m ConstantMap) lineNumber() int       { return m.Line }
-func (i ConstantMapItem) lineNumber() int   { return i.Line }
-func (l ConstantList) lineNumber() int      { return l.Line }
-func (r ConstantReference) lineNumber() int { return r.Line }
+func (m ConstantMap) pos() Position       { return Position{Line: m.Line, Column: m.Column} }
+func (i ConstantMapItem) pos() Position   { return Position{Line: i.Line, Column: i.Column} }
+func (l ConstantList) pos() Position      { return Position{Line: l.Line, Column: l.Column} }
+func (r ConstantReference) pos() Position { return Position{Line: r.Line, Column: r.Column} }
 
 // ConstantBoolean is a boolean value specified in the Thrift file.
 //
@@ -99,14 +99,16 @@ type ConstantDouble float64
 //
 // Note that map literals can also be used to build structs.
 type ConstantMap struct {
-	Items []ConstantMapItem
-	Line  int
+	Items  []ConstantMapItem
+	Line   int
+	Column int
 }
 
 // ConstantMapItem is a single item in a ConstantMap.
 type ConstantMapItem struct {
 	Key, Value ConstantValue
 	Line       int
+	Column     int
 }
 
 func (ConstantMapItem) node() {}
@@ -115,8 +117,9 @@ func (ConstantMapItem) node() {}
 //
 // 	[1, 2, 3]
 type ConstantList struct {
-	Items []ConstantValue
-	Line  int
+	Items  []ConstantValue
+	Line   int
+	Column int
 }
 
 // ConstantReference is a reference to another constant value defined in the
@@ -127,6 +130,6 @@ type ConstantReference struct {
 	// Name of the referenced value.
 	Name string
 
-	// Line number on which this reference was made.
-	Line int
+	Line   int
+	Column int
 }