Introduce buf (#382)

This commit introduces buf in order to write proto files while following
best practices.

The linter requires that the zero value for all enums should be suffixed
with _UNSPECIFIED. However, it is difficult to migrate the operations
already stored in the DB, so we ignore the rule for now.

We are also considering introducing an IDL repository or Buf Schema
Registry to manage proto files in a single location. Even now, this
repository is SSOT for proto files, but we are using it by manually
copying it from another repository(e.g. yorkie-js-sdk, yorkie-house).

Co-authored-by: Miller <[email protected]>

.github/workflows/ci.yml

@@ -7,7 +7,6 @@ on:
     branches: [ main ]
 
 jobs:
-
   build:
     name: build
     runs-on: ubuntu-latest
@@ -18,15 +17,21 @@ jobs:
       with:
         go-version: ^1.18
 
+    - name: Setup buf action
+      uses: bufbuild/buf-setup-action@v1
+
     - name: Check out code
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
 
     - name: Get tools dependencies
       run: make tools
 
     - name: Lint
       run: make lint
 
+    - name: Lint proto files
+      uses: bufbuild/buf-lint-action@v1
+
     - name: Build
       run: make build
 

Makefile

@@ -33,15 +33,15 @@ proto: ## generate proto files
 --gofast_out=plugins=grpc,\
 Mgoogle/protobuf/timestamp.proto=github.com/gogo/protobuf/types,\
 Mgoogle/protobuf/wrappers.proto=github.com/gogo/protobuf/types,\
-Mgoogle/protobuf/any.proto=github.com/gogo/protobuf/types,:./api \
-api/*.proto
+Mgoogle/protobuf/any.proto=github.com/gogo/protobuf/types,:./api/yorkie/v1 \
+api/yorkie/v1/*.proto
 
 protoset: ## generate protoset file
 	protoc \
 -I=./api \
 --descriptor_set_out=yorkie.protoset \
 --include_imports \
-api/*.proto
+api/yorkie/v1/*.proto
 
 build: ## builds an executable that runs in the current environment
 	go build -o $(EXECUTABLE) -ldflags "${GO_LDFLAGS}" ./cmd/yorkie

admin/client.go

@@ -23,9 +23,9 @@ import (
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/credentials/insecure"
 
-	"github.com/yorkie-team/yorkie/api"
 	"github.com/yorkie-team/yorkie/api/converter"
 	"github.com/yorkie-team/yorkie/api/types"
+	api "github.com/yorkie-team/yorkie/api/yorkie/v1"
 	"github.com/yorkie-team/yorkie/pkg/document"
 	"github.com/yorkie-team/yorkie/pkg/document/key"
 )
@@ -55,7 +55,7 @@ type Options struct {
 // Client is a client for admin service.
 type Client struct {
 	conn            *grpc.ClientConn
-	client          api.AdminClient
+	client          api.AdminServiceClient
 	dialOptions     []grpc.DialOption
 	authInterceptor *AuthInterceptor
 
@@ -114,7 +114,7 @@ func (c *Client) Dial(adminAddr string) error {
 	}
 
 	c.conn = conn
-	c.client = api.NewAdminClient(conn)
+	c.client = api.NewAdminServiceClient(conn)
 
 	return nil
 }

api/buf.yaml

@@ -0,0 +1,13 @@
+version: v1
+breaking:
+  use:
+    - FILE
+lint:
+  use:
+    - DEFAULT
+  ignore_only:
+    # The linter requires that the zero value for all enums should be suffixed
+    # with _UNSPECIFIED. However, it is difficult to migrate the operations
+    # already stored in the DB, so we ignore the rule for now.
+    ENUM_ZERO_VALUE_SUFFIX:
+      - yorkie/v1/resources.proto

api/converter/converter_test.go

@@ -23,9 +23,9 @@ import (
 
 	"github.com/stretchr/testify/assert"
 
-	"github.com/yorkie-team/yorkie/api"
 	"github.com/yorkie-team/yorkie/api/converter"
 	"github.com/yorkie-team/yorkie/api/types"
+	api "github.com/yorkie-team/yorkie/api/yorkie/v1"
 	"github.com/yorkie-team/yorkie/pkg/document"
 	"github.com/yorkie-team/yorkie/pkg/document/proxy"
 	"github.com/yorkie-team/yorkie/pkg/document/time"

api/converter/from_bytes.go

@@ -21,7 +21,7 @@ import (
 
 	"github.com/gogo/protobuf/proto"
 
-	"github.com/yorkie-team/yorkie/api"
+	api "github.com/yorkie-team/yorkie/api/yorkie/v1"
 	"github.com/yorkie-team/yorkie/pkg/document/json"
 	"github.com/yorkie-team/yorkie/pkg/document/time"
 )

api/converter/from_pb.go

@@ -21,8 +21,8 @@ import (
 
 	protoTypes "github.com/gogo/protobuf/types"
 
-	"github.com/yorkie-team/yorkie/api"
 	"github.com/yorkie-team/yorkie/api/types"
+	api "github.com/yorkie-team/yorkie/api/yorkie/v1"
 	"github.com/yorkie-team/yorkie/pkg/document/change"
 	"github.com/yorkie-team/yorkie/pkg/document/json"
 	"github.com/yorkie-team/yorkie/pkg/document/key"
@@ -220,13 +220,13 @@ func FromDocumentKeys(pbKeys []string) []key.Key {
 // FromEventType converts the given Protobuf formats to model format.
 func FromEventType(pbDocEventType api.DocEventType) (types.DocEventType, error) {
 	switch pbDocEventType {
-	case api.DocEventType_DOCUMENTS_CHANGED:
+	case api.DocEventType_DOC_EVENT_TYPE_DOCUMENTS_CHANGED:
 		return types.DocumentsChangedEvent, nil
-	case api.DocEventType_DOCUMENTS_WATCHED:
+	case api.DocEventType_DOC_EVENT_TYPE_DOCUMENTS_WATCHED:
 		return types.DocumentsWatchedEvent, nil
-	case api.DocEventType_DOCUMENTS_UNWATCHED:
+	case api.DocEventType_DOC_EVENT_TYPE_DOCUMENTS_UNWATCHED:
 		return types.DocumentsUnwatchedEvent, nil
-	case api.DocEventType_PRESENCE_CHANGED:
+	case api.DocEventType_DOC_EVENT_TYPE_PRESENCE_CHANGED:
 		return types.PresenceChangedEvent, nil
 	}
 	return "", fmt.Errorf("%v: %w", pbDocEventType, ErrUnsupportedEventType)
@@ -577,7 +577,7 @@ func fromTimeTicket(pbTicket *api.TimeTicket) (*time.Ticket, error) {
 
 func fromElement(pbElement *api.JSONElementSimple) (json.Element, error) {
 	switch pbType := pbElement.Type; pbType {
-	case api.ValueType_JSON_OBJECT:
+	case api.ValueType_VALUE_TYPE_JSON_OBJECT:
 		createdAt, err := fromTimeTicket(pbElement.CreatedAt)
 		if err != nil {
 			return nil, err
@@ -586,7 +586,7 @@ func fromElement(pbElement *api.JSONElementSimple) (json.Element, error) {
 			json.NewRHTPriorityQueueMap(),
 			createdAt,
 		), nil
-	case api.ValueType_JSON_ARRAY:
+	case api.ValueType_VALUE_TYPE_JSON_ARRAY:
 		createdAt, err := fromTimeTicket(pbElement.CreatedAt)
 		if err != nil {
 			return nil, err
@@ -595,21 +595,21 @@ func fromElement(pbElement *api.JSONElementSimple) (json.Element, error) {
 			json.NewRGATreeList(),
 			createdAt,
 		), nil
-	case api.ValueType_NULL:
+	case api.ValueType_VALUE_TYPE_NULL:
 		fallthrough
-	case api.ValueType_BOOLEAN:
+	case api.ValueType_VALUE_TYPE_BOOLEAN:
 		fallthrough
-	case api.ValueType_INTEGER:
+	case api.ValueType_VALUE_TYPE_INTEGER:
 		fallthrough
-	case api.ValueType_LONG:
+	case api.ValueType_VALUE_TYPE_LONG:
 		fallthrough
-	case api.ValueType_DOUBLE:
+	case api.ValueType_VALUE_TYPE_DOUBLE:
 		fallthrough
-	case api.ValueType_STRING:
+	case api.ValueType_VALUE_TYPE_STRING:
 		fallthrough
-	case api.ValueType_BYTES:
+	case api.ValueType_VALUE_TYPE_BYTES:
 		fallthrough
-	case api.ValueType_DATE:
+	case api.ValueType_VALUE_TYPE_DATE:
 		valueType, err := fromPrimitiveValueType(pbElement.Type)
 		if err != nil {
 			return nil, err
@@ -622,7 +622,7 @@ func fromElement(pbElement *api.JSONElementSimple) (json.Element, error) {
 			json.ValueFromBytes(valueType, pbElement.Value),
 			createdAt,
 		), nil
-	case api.ValueType_TEXT:
+	case api.ValueType_VALUE_TYPE_TEXT:
 		createdAt, err := fromTimeTicket(pbElement.CreatedAt)
 		if err != nil {
 			return nil, err
@@ -631,7 +631,7 @@ func fromElement(pbElement *api.JSONElementSimple) (json.Element, error) {
 			json.NewRGATreeSplit(json.InitialTextNode()),
 			createdAt,
 		), nil
-	case api.ValueType_RICH_TEXT:
+	case api.ValueType_VALUE_TYPE_RICH_TEXT:
 		createdAt, err := fromTimeTicket(pbElement.CreatedAt)
 		if err != nil {
 			return nil, err
@@ -640,11 +640,11 @@ func fromElement(pbElement *api.JSONElementSimple) (json.Element, error) {
 			json.NewRGATreeSplit(json.InitialRichTextNode()),
 			createdAt,
 		), nil
-	case api.ValueType_INTEGER_CNT:
+	case api.ValueType_VALUE_TYPE_INTEGER_CNT:
 		fallthrough
-	case api.ValueType_LONG_CNT:
+	case api.ValueType_VALUE_TYPE_LONG_CNT:
 		fallthrough
-	case api.ValueType_DOUBLE_CNT:
+	case api.ValueType_VALUE_TYPE_DOUBLE_CNT:
 		counterType, err := fromCounterType(pbType)
 		if err != nil {
 			return nil, err
@@ -664,21 +664,21 @@ func fromElement(pbElement *api.JSONElementSimple) (json.Element, error) {
 
 func fromPrimitiveValueType(valueType api.ValueType) (json.ValueType, error) {
 	switch valueType {
-	case api.ValueType_NULL:
+	case api.ValueType_VALUE_TYPE_NULL:
 		return json.Null, nil
-	case api.ValueType_BOOLEAN:
+	case api.ValueType_VALUE_TYPE_BOOLEAN:
 		return json.Boolean, nil
-	case api.ValueType_INTEGER:
+	case api.ValueType_VALUE_TYPE_INTEGER:
 		return json.Integer, nil
-	case api.ValueType_LONG:
+	case api.ValueType_VALUE_TYPE_LONG:
 		return json.Long, nil
-	case api.ValueType_DOUBLE:
+	case api.ValueType_VALUE_TYPE_DOUBLE:
 		return json.Double, nil
-	case api.ValueType_STRING:
+	case api.ValueType_VALUE_TYPE_STRING:
 		return json.String, nil
-	case api.ValueType_BYTES:
+	case api.ValueType_VALUE_TYPE_BYTES:
 		return json.Bytes, nil
-	case api.ValueType_DATE:
+	case api.ValueType_VALUE_TYPE_DATE:
 		return json.Date, nil
 	}
 
@@ -687,11 +687,11 @@ func fromPrimitiveValueType(valueType api.ValueType) (json.ValueType, error) {
 
 func fromCounterType(valueType api.ValueType) (json.CounterType, error) {
 	switch valueType {
-	case api.ValueType_INTEGER_CNT:
+	case api.ValueType_VALUE_TYPE_INTEGER_CNT:
 		return json.IntegerCnt, nil
-	case api.ValueType_LONG_CNT:
+	case api.ValueType_VALUE_TYPE_LONG_CNT:
 		return json.LongCnt, nil
-	case api.ValueType_DOUBLE_CNT:
+	case api.ValueType_VALUE_TYPE_DOUBLE_CNT:
 		return json.DoubleCnt, nil
 	}
 

api/converter/to_bytes.go

@@ -22,7 +22,7 @@ import (
 
 	"github.com/gogo/protobuf/proto"
 
-	"github.com/yorkie-team/yorkie/api"
+	api "github.com/yorkie-team/yorkie/api/yorkie/v1"
 	"github.com/yorkie-team/yorkie/pkg/document/json"
 )
 

api/converter/to_pb.go

@@ -22,8 +22,8 @@ import (
 
 	protoTypes "github.com/gogo/protobuf/types"
 
-	"github.com/yorkie-team/yorkie/api"
 	"github.com/yorkie-team/yorkie/api/types"
+	api "github.com/yorkie-team/yorkie/api/yorkie/v1"
 	"github.com/yorkie-team/yorkie/pkg/document/change"
 	"github.com/yorkie-team/yorkie/pkg/document/json"
 	"github.com/yorkie-team/yorkie/pkg/document/key"
@@ -202,13 +202,13 @@ func ToClientsMap(clientsMap map[string][]types.Client) map[string]*api.Clients
 func ToDocEventType(eventType types.DocEventType) (api.DocEventType, error) {
 	switch eventType {
 	case types.DocumentsChangedEvent:
-		return api.DocEventType_DOCUMENTS_CHANGED, nil
+		return api.DocEventType_DOC_EVENT_TYPE_DOCUMENTS_CHANGED, nil
 	case types.DocumentsWatchedEvent:
-		return api.DocEventType_DOCUMENTS_WATCHED, nil
+		return api.DocEventType_DOC_EVENT_TYPE_DOCUMENTS_WATCHED, nil
 	case types.DocumentsUnwatchedEvent:
-		return api.DocEventType_DOCUMENTS_UNWATCHED, nil
+		return api.DocEventType_DOC_EVENT_TYPE_DOCUMENTS_UNWATCHED, nil
 	case types.PresenceChangedEvent:
-		return api.DocEventType_PRESENCE_CHANGED, nil
+		return api.DocEventType_DOC_EVENT_TYPE_PRESENCE_CHANGED, nil
 	default:
 		return 0, fmt.Errorf("%s: %w", eventType, ErrUnsupportedEventType)
 	}
@@ -421,12 +421,12 @@ func toJSONElementSimple(elem json.Element) (*api.JSONElementSimple, error) {
 	switch elem := elem.(type) {
 	case *json.Object:
 		return &api.JSONElementSimple{
-			Type:      api.ValueType_JSON_OBJECT,
+			Type:      api.ValueType_VALUE_TYPE_JSON_OBJECT,
 			CreatedAt: ToTimeTicket(elem.CreatedAt()),
 		}, nil
 	case *json.Array:
 		return &api.JSONElementSimple{
-			Type:      api.ValueType_JSON_ARRAY,
+			Type:      api.ValueType_VALUE_TYPE_JSON_ARRAY,
 			CreatedAt: ToTimeTicket(elem.CreatedAt()),
 		}, nil
 	case *json.Primitive:
@@ -442,12 +442,12 @@ func toJSONElementSimple(elem json.Element) (*api.JSONElementSimple, error) {
 		}, nil
 	case *json.Text:
 		return &api.JSONElementSimple{
-			Type:      api.ValueType_TEXT,
+			Type:      api.ValueType_VALUE_TYPE_TEXT,
 			CreatedAt: ToTimeTicket(elem.CreatedAt()),
 		}, nil
 	case *json.RichText:
 		return &api.JSONElementSimple{
-			Type:      api.ValueType_RICH_TEXT,
+			Type:      api.ValueType_VALUE_TYPE_RICH_TEXT,
 			CreatedAt: ToTimeTicket(elem.CreatedAt()),
 		}, nil
 	case *json.Counter:
@@ -487,21 +487,21 @@ func toCreatedAtMapByActor(
 func toValueType(valueType json.ValueType) (api.ValueType, error) {
 	switch valueType {
 	case json.Null:
-		return api.ValueType_NULL, nil
+		return api.ValueType_VALUE_TYPE_NULL, nil
 	case json.Boolean:
-		return api.ValueType_BOOLEAN, nil
+		return api.ValueType_VALUE_TYPE_BOOLEAN, nil
 	case json.Integer:
-		return api.ValueType_INTEGER, nil
+		return api.ValueType_VALUE_TYPE_INTEGER, nil
 	case json.Long:
-		return api.ValueType_LONG, nil
+		return api.ValueType_VALUE_TYPE_LONG, nil
 	case json.Double:
-		return api.ValueType_DOUBLE, nil
+		return api.ValueType_VALUE_TYPE_DOUBLE, nil
 	case json.String:
-		return api.ValueType_STRING, nil
+		return api.ValueType_VALUE_TYPE_STRING, nil
 	case json.Bytes:
-		return api.ValueType_BYTES, nil
+		return api.ValueType_VALUE_TYPE_BYTES, nil
 	case json.Date:
-		return api.ValueType_DATE, nil
+		return api.ValueType_VALUE_TYPE_DATE, nil
 	}
 
 	return 0, fmt.Errorf("%d, %w", valueType, ErrUnsupportedValueType)
@@ -510,11 +510,11 @@ func toValueType(valueType json.ValueType) (api.ValueType, error) {
 func toCounterType(valueType json.CounterType) (api.ValueType, error) {
 	switch valueType {
 	case json.IntegerCnt:
-		return api.ValueType_INTEGER_CNT, nil
+		return api.ValueType_VALUE_TYPE_INTEGER_CNT, nil
 	case json.LongCnt:
-		return api.ValueType_LONG_CNT, nil
+		return api.ValueType_VALUE_TYPE_LONG_CNT, nil
 	case json.DoubleCnt:
-		return api.ValueType_DOUBLE_CNT, nil
+		return api.ValueType_VALUE_TYPE_DOUBLE_CNT, nil
 	}
 
 	return 0, fmt.Errorf("%d, %w", valueType, ErrUnsupportedCounterType)