feat(151,proto): add long-running operation support

Add support for operation support for protobuf generation.

This required a minor refactor where we use a Message interface
rather than concrete MessageBuilder and MessageDescriptor types 
directly. This allows for the abilitiy to use messages imported
as resources (as is the case with aep.api.Operation).

Author: toumorokoshi

pkg/api/testutils.go

@@ -69,6 +69,54 @@ func ExampleAPI() *API {
 	}
 	publisher.Children = append(publisher.Children, book)
 
+	// Resource to test operation logic
+	tome := &Resource{
+		Singular: "tome",
+		Plural:   "tomes",
+		Parents:  []*Resource{publisher},
+		Schema: &openapi.Schema{
+			Type: "object",
+			Properties: map[string]openapi.Schema{
+				"name": {Type: "string", XAEPFieldNumber: 1},
+				"id":   {Type: "string", XAEPFieldNumber: 2},
+			},
+		},
+		Methods: Methods{
+			List: &ListMethod{},
+			Get:  &GetMethod{},
+			Apply: &ApplyMethod{
+				IsLongRunning: true,
+			},
+			Create: &CreateMethod{
+				IsLongRunning: true,
+			},
+			Update: &UpdateMethod{
+				IsLongRunning: true,
+			},
+			Delete: &DeleteMethod{
+				IsLongRunning: true,
+			},
+		},
+		CustomMethods: []*CustomMethod{
+			{
+				Name:   "archive",
+				Method: "POST",
+				Request: &openapi.Schema{
+					Type:       "object",
+					Properties: map[string]openapi.Schema{},
+				},
+				Response: &openapi.Schema{
+					Type: "object",
+					Properties: map[string]openapi.Schema{
+						"archived": {Type: "boolean", XAEPFieldNumber: 1},
+					},
+				},
+				IsLongRunning: true,
+			},
+		},
+	}
+	publisher.Children = append(publisher.Children, tome)
+
 	// Create book-edition resource
 	bookEdition := &Resource{
 		Singular: "book-edition",
@@ -109,6 +157,7 @@ func ExampleAPI() *API {
 			"book-edition": bookEdition,
 			"publisher":    publisher,
 			"operation":    OperationResourceWithDefaults(),
+			"tome":         tome,
 		},
 	}
 }

pkg/proto/message.go

@@ -0,0 +1,69 @@
+package proto
+
+import (
+	"github.com/jhump/protoreflect/desc"
+	"github.com/jhump/protoreflect/desc/builder"
+	"google.golang.org/protobuf/types/descriptorpb"
+)
+
+// type Message wraps a MessageBuilder or a
+// message descriptor. It abstracts those concrete
+// implementations to provide a common interface.
+type Message interface {
+	FieldType() *builder.FieldType
+	RpcType() *builder.RpcType
+	Options() *descriptorpb.MessageOptions
+	AddMessage(fb *builder.FileBuilder)
+}
+
+// A variant that wraps MessageBuilder, for messages
+// created during generation.
+type WrappedMessageBuilder struct {
+	mb *builder.MessageBuilder
+}
+
+func NewWrappedMessageBuilder(mb *builder.MessageBuilder) WrappedMessageBuilder {
+	return WrappedMessageBuilder{mb: mb}
+}
+
+func (wrapped WrappedMessageBuilder) FieldType() *builder.FieldType {
+	return builder.FieldTypeMessage(wrapped.mb)
+}
+
+func (wrapped WrappedMessageBuilder) Options() *descriptorpb.MessageOptions {
+	return wrapped.mb.Options
+}
+
+func (wrapped WrappedMessageBuilder) RpcType() *builder.RpcType {
+	return builder.RpcTypeMessage(wrapped.mb, false)
+}
+
+func (wrapped WrappedMessageBuilder) AddMessage(fb *builder.FileBuilder) {
+	fb.AddMessage(wrapped.mb)
+}
+
+// A variant that wraps MessageDescriptor, for messages
+// referenced
+type WrappedMessageDescriptor struct {
+	md *desc.MessageDescriptor
+}
+
+func NewWrappedMessageDescriptor(md *desc.MessageDescriptor) WrappedMessageDescriptor {
+	return WrappedMessageDescriptor{md: md}
+}
+
+func (wrapped WrappedMessageDescriptor) FieldType() *builder.FieldType {
+	return builder.FieldTypeImportedMessage(wrapped.md)
+}
+
+func (wrapped WrappedMessageDescriptor) Options() *descriptorpb.MessageOptions {
+	return nil
+}
+
+func (wrapped WrappedMessageDescriptor) RpcType() *builder.RpcType {
+	return builder.RpcTypeImportedMessage(wrapped.md, false)
+}
+
+func (wrapped WrappedMessageDescriptor) AddMessage(fb *builder.FileBuilder) {
+	// noop
+}

pkg/proto/proto.go

@@ -30,7 +30,7 @@ import (
 )
 
 type MessageStorage struct {
-	Messages map[string]*builder.MessageBuilder
+	Messages map[string]Message
 }
 
 func APIToProtoString(a *api.API, outputDir string) ([]byte, error) {
@@ -50,7 +50,7 @@ func APIToProtoString(a *api.API, outputDir string) ([]byte, error) {
 }
 
 func APIToProto(a *api.API, outputDir string) (*desc.FileDescriptor, error) {
-	m := &MessageStorage{Messages: map[string]*builder.MessageBuilder{}}
+	m := &MessageStorage{Messages: map[string]Message{}}
 	dir, file := filepath.Split(outputDir)
 	packageParts := []string{file}
 	for dir != "." {
@@ -130,7 +130,7 @@ func GenerateSchemaMessages(a *api.API, m *MessageStorage, fb *builder.FileBuild
 		if err != nil {
 			return err
 		}
-		fb.AddMessage(mb)
+		mb.AddMessage(fb)
 	}
 	return nil
 }

pkg/proto/proto_test.go

@@ -32,6 +32,7 @@ func TestAPIToProto(t *testing.T) {
 		expectError    bool
 		expectMessages []string
 		expectMethods  []string
+		expectStrings  []string
 	}{
 		{
 			name:        "BasicAPItoProtoConversion",
@@ -58,6 +59,7 @@ func TestAPIToProto(t *testing.T) {
 				"GetBookEditionRequest",
 				"ListBookEditionsRequest",
 				"ListBookEditionsResponse",
+				"ArchiveTomeRequest",
 			},
 			expectMethods: []string{
 				"CreatePublisher",
@@ -72,6 +74,10 @@ func TestAPIToProto(t *testing.T) {
 				"GetBookEdition",
 				"ListBookEditions",
 			},
+			expectStrings: []string{
+				// verify that ArchiveTome is a long-running-operation.
+				"rpc ArchiveTome ( ArchiveTomeRequest ) returns ( aep.api.Operation ) {",
+			},
 		},
 	}
 
@@ -108,7 +114,7 @@ func TestAPIToProto(t *testing.T) {
 
 			protoContent := string(protoString)
 			// Print the proto content for debugging
-			// t.Logf("Proto content: \n%s", protoContent)
+			t.Logf("Proto content: \n---\n%s\n---", protoContent)
 
 			// Check for expected messages
 			for _, msgName := range tt.expectMessages {
@@ -129,6 +135,13 @@ func TestAPIToProto(t *testing.T) {
 					"Expected method %s not found in proto content", methodName)
 			}
 
+			// Check for expected strings
+			for _, expectedString := range tt.expectStrings {
+				assert.True(t,
+					strings.Contains(protoContent, expectedString),
+					"Expected string %s not found in proto content", expectedString)
+			}
+
 			// Verify correct parent-child relationships in the API paths
 			assert.True(t, strings.Contains(protoContent, "get: \"/{path=publishers/*/books/*}\""))
 			assert.True(t, strings.Contains(protoContent, "get: \"/{path=publishers/*/books/*/editions/*}\""))